Consolidate the Python sources into twelve files with one-line docstrings, fold the demos into the playground, and delete the scripts that do not belong to the artifact

.gitignore

@@ -21,4 +21,4 @@ rocq/.nia.cache
 rocq/extract/dump
 rocq/extract/*.cm*
 rocq/extract/*.o
-src/independent/.work/
+src/.work/

README.md

@@ -99,14 +99,14 @@ for a, c in [(0, 0), (0, 1), (1, 0), (1, 1)]:
 Run the full circuit verification suite against any variant:
 
 ```bash
-python src/eval_all.py variants/                              # 18 fitness variants (machines skipped)
-python src/eval_all.py neural_computer.safetensors            # the canonical file
-python src/eval_all.py --cpu-program variants/                # also run an assembled
+python src/eval.py variants variants/                              # 18 fitness variants (machines skipped)
+python src/eval.py variants neural_computer.safetensors            # the canonical file
+python src/eval.py variants --cpu-program variants/                # also run an assembled
                                                           # program through the
                                                           # threshold-gated CPU
 ```
 
-`src/eval_all.py` reads each variant's manifest, runs a gate-level fitness suite (13,900–15,900 tests per variant covering Boolean, arithmetic, ALU, control, modular, error-detection, threshold, and float circuits, including end-to-end evaluation of the composed float pipelines from the shipped wiring metadata — see the Verification table), and optionally executes a small assembled program through a manifest-sized threshold CPU plus a chained 16- or 32-bit ALU sequence on wider variants.
+`src/eval.py variants` reads each variant's manifest, runs a gate-level fitness suite (13,900–15,900 tests per variant covering Boolean, arithmetic, ALU, control, modular, error-detection, threshold, and float circuits, including end-to-end evaluation of the composed float pipelines from the shipped wiring metadata — see the Verification table), and optionally executes a small assembled program through a manifest-sized threshold CPU plus a chained 16- or 32-bit ALU sequence on wider variants.
 
 For an interactive walkthrough that exercises Boolean gates, the 8-bit ALU, mod-5 divisibility, and a CPU loop end-to-end:
 
@@ -115,15 +115,34 @@ python tools/play.py                                      # 1 KB demo, runs in s
 python tools/play.py --model neural_computer.safetensors  # 64 KB, slower
 ```
 
+Each machine of the family also has a demonstration on a named task, which loads the shipped weights and checks its result against an independent reference:
+
+| Command | Machine | What it does |
+|---------|---------|--------------|
+| `python tools/play.py sieve` | `neural_computer8` | Sieve of Eratosthenes; with no indexed addressing, the program rewrites the address bytes of its own LOAD/STORE. Finds all 54 primes < 256. |
+| `python tools/play.py gcd` | `neural_computer8` | Euclid's GCD, with `a mod b` built from the DIV/MUL/SUB opcodes and an XOR register swap. |
+| `python tools/play.py collatz` | `neural_computer8` | Collatz step counts; exact for every seed whose trajectory stays inside the 8-bit range. |
+| `python tools/play.py pi` | `neural_rv32` | pi to nine digits by Machin's 1706 arctangent formula, printed to the console. |
+| `python tools/play.py nets` | `neural_rv32` | Ternary neural nets run as NEUR software: one learned by gradient descent, one (XOR) compiled by construction. |
+| `python tools/play.py fleet` | `neural_matrix8` | 65,536 CPUs stepped in lockstep on the GPU as one batched matrix product. |
+| `python tools/play.py factoring` | `neural_attractor` | Factors semiprimes by relaxing an 8x8 multiplier's energy backward; also divides. |
+| `python tools/play.py nqueens` | `neural_attractor` | Solves 6- and 8-queens by relaxing toward zero unsatisfied clauses. |
+| `python tools/play.py constructor` | `neural_subleq8io` | The universal constructor fabricates a sibling machine byte-for-byte, which then boots. |
+| `python tools/play.py stack` | `neural_reflect` | Self-modifying SUBLEQ code, on a stored machine, on the fixed interpreter: three levels in one tensor. |
+| `python tools/play.py counterfactual` | `neural_reversible` | Bijective mixing, exact reverse recovery, and the counterfactual when a digest bit is flipped. |
+| `python tools/play.py loschmidt` | `neural_ca` | A ~2,000-particle gas mixed 500 steps and un-mixed exactly; one flipped cell corrupts half the past. |
+| `python tools/play.py cipher` | `neural_ca` | The reversible automaton as a block cipher: exact decryption with the right key, noise with a wrong one. |
+| `python tools/play.py pascal` | `neural_tile` | Self-assembly grows Pascal's triangle mod 2; every cell verified against Lucas' theorem. |
+
 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 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
+python src/eval.py cpu                                     # default: 1 KB, ~2 s
+python src/eval.py cpu --model neural_computer.safetensors # 64 KB canonical, ~2 min
+python src/eval.py cpu --only fib,sum_n                    # subset of suite
 ```
 
-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.
+Each program is assembled by a small Python assembler (in `src/eval.py`) and run through the threshold-gated CPU; the driver verifies expected memory contents at HALT.
 
 ---
 
@@ -325,7 +344,7 @@ python src/build.py --bits 32 -a 6 --apply all         # neural_computer32_addr6
 To regenerate every named variant in one pass:
 
 ```bash
-python tools/build_all.py
+python src/build.py variants
 ```
 
 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 `src/eval.py` on each as a sanity check.
@@ -333,11 +352,11 @@ This populates `variants/` with all 18 builds, quantizes each one to the smalles
 The quantizer is also available standalone:
 
 ```bash
-python src/quantize.py path/to/file.safetensors           # in-place
-python src/quantize.py variants/                          # whole directory
-python src/quantize.py model.safetensors -o quantized.safetensors
-python src/quantize.py file.safetensors --ternary         # push toward {-1, 0, 1} weights
-python src/quantize.py file.safetensors --ternary --strict  # error if any weight is non-ternary
+python src/build.py quantize path/to/file.safetensors           # in-place
+python src/build.py quantize variants/                          # whole directory
+python src/build.py quantize model.safetensors -o quantized.safetensors
+python src/build.py quantize file.safetensors --ternary         # push toward {-1, 0, 1} weights
+python src/build.py quantize file.safetensors --ternary --strict  # error if any weight is non-ternary
 ```
 
 Every weight and bias tensor in the canonical model fits in `int8`. The eval pipeline promotes weights to `float32` on load, so integer storage is exact and transparent.
@@ -369,7 +388,7 @@ Every weight and bias tensor in the canonical model fits in `int8`. The eval pip
 
 The 8-bit arithmetic and ALU tests sample strategically; the circuits are constructed gate by gate, so the full 65,536-case sweep adds nothing. The 16-bit and 32-bit arithmetic tests sample edge cases only; full exhaustive coverage at those widths is infeasible without specialized hardware.
 
-`src/eval_all.py` runs the unified suite. Exit code is the number of failing variants (0 means all pass). **Testing evaluates the shipped weights; rebuilding is a separate step.** `python src/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 nine 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 `src/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, with no slot-0 approximation anywhere.
+`src/eval.py variants` runs the unified suite. Exit code is the number of failing variants (0 means all pass). **Testing evaluates the shipped weights; rebuilding is a separate step.** `python src/eval.py variants 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 nine standalone machines. Rebuilding the models (`python src/build.py variants`, ~50 min for all 18) is a separate step, needed only when the circuit constructions in `src/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, with no slot-0 approximation anywhere.
 
 ---
 
@@ -405,7 +424,7 @@ Signed comparisons ride the unsigned bit-cascade with sign bits complemented thr
 
 ```bash
 python src/build.py --apply rv32                            # build the file
-python src/quantize.py variants/neural_rv32.safetensors --ternary --strict
+python src/build.py quantize variants/neural_rv32.safetensors --ternary --strict
 python src/machines.py rv32                                 # eight-program lockstep suite
 python src/machines.py rv32-c                               # stock-compiler C, end to end
 ```
@@ -461,9 +480,9 @@ write is gated by NOT halt), so iterating past HALT is harmless.
   conductance mismatch (bit-exact through σ_G = 0.10).
 
 ```bash
-python src/matrix8.py build          # compile + save variants/neural_matrix8.safetensors
-python src/matrix8.py verify         # exhaustive equality vs the gate graph and integer reference
-python src/matrix8.py analog         # margin measurement + read-noise + conductance-mismatch sweeps
+python src/machines.py matrix8 build          # compile + save variants/neural_matrix8.safetensors
+python src/machines.py matrix8 verify         # exhaustive equality vs the gate graph and integer reference
+python src/machines.py matrix8 analog         # margin measurement + read-noise + conductance-mismatch sweeps
 ```
 
 Because the transition is a fixed matrix stack proven equal to the gate-graph
@@ -508,8 +527,8 @@ correct assignment, but reaching it is NP-hard in general and not guaranteed
 within a fixed annealing schedule.
 
 ```bash
-python tools/build_attractor.py      # compile a multiplier to variants/neural_attractor.safetensors
-python tools/test_attractor.py       # forward eval, whole-network relaxation, factoring, SAT
+python src/automata.py build-attractor  # compile a multiplier to variants/neural_attractor.safetensors
+python src/automata.py attractor        # forward eval, whole-network relaxation, factoring, SAT
 ```
 
 ---
@@ -549,9 +568,9 @@ Four checks establish the equality:
   closing the loop across two generations.
 
 ```bash
-python src/constructor8.py build     # emit variants/neural_subleq8io.safetensors
-python src/constructor8.py verify    # host soundness + codec round-trip + constructor on all 3 backends
-python src/constructor8.py self      # full self-reproduction on the threshold matrices, then gen-2 boot
+python src/host.py constructor8 build     # emit variants/neural_subleq8io.safetensors
+python src/host.py constructor8 verify    # host soundness + codec round-trip + constructor on all 3 backends
+python src/host.py constructor8 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
@@ -562,12 +581,12 @@ weights and checked to the byte.
 `paper/` states and proves what this machine does, for a host serialized one
 unit at a time: `variants/neural_subleq8io_netlist.safetensors` stores the bias
 of every unit and every edge of the wiring, 17,598 units and 51,132 edges in
-160,240 bytes, in the order `src/host_family.py` builds them, so the network the
+160,240 bytes, in the order `src/host.py` builds them, so the network the
 file denotes is the network the paper analyses, and parsing the file rebuilds
 it. That host is the member with eight-bit words of a family whose step has
 depth 13 for every word width, with a carry-lookahead subtractor and the
-operands fetched through the decode lines of the counter; `src/host_family.py`
-builds any member and `src/check_host_family.py` checks each against SUBLEQ
+operands fetched through the decode lines of the counter; `src/host.py`
+builds any member and `python src/paper.py host-family` checks each against SUBLEQ
 on the evaluator in C. Separating construction from copying
 as von Neumann did, a 27-instruction program emits the serialization of the
 host, its initial memory and its own description tape; each generation is
@@ -575,9 +594,9 @@ instantiated from the bytes the last one emitted, by parsing that output,
 rebuilding the netlist from its first field, and building the evaluator from
 that netlist. It also shows where the restriction to {-1, 0, 1} is paid for,
 and that a fixed ternary network, the two-head machine of
-`src/twohead_net.py`, holds a stored network in its state and evaluates one
+`src/twohead.py`, holds a stored network in its state and evaluates one
 record per step, which `rocq/` proves for every window of 2^α cells, bank and
-tape. The host itself, compiled by `src/stored_host.py` into 36,074 records of
+tape. The host itself, compiled by `src/twohead.py` into 36,074 records of
 two inputs with records that load its memory, its tape device and a hand-over,
 and stored in the member with 4096 cells, runs the 27-instruction program on a
 recipe for its own records: it writes them into the idle bank, copies the recipe
@@ -587,20 +606,16 @@ by the dynamics alone; `src/stored_host_run.c` runs three generations of
 cells does the same with a description code of its own, every generation of it
 proved in Rocq. Its robustness section gives the margin every orbit has
 against perturbation, a certificate of the leakage an orbit tolerates from the
-inputs active along it, and the amplified host of `src/redundant.py`: every row
+inputs active along it, and the amplified host of `src/noise.py`: every row
 of the levelized host replaced by r rows reading all r copies of its inputs,
 which multiplies every margin by r, reproduces itself exactly, fails only when two
 wrong copies meet, with a probability of second order that the paper bounds, and
 completes the self-reproducing run under read noise at levels where the host
 fails within its first bytes.
 
-The scripts that produce every figure are `src/selfrep.py`, `src/netlist_io.py`, `src/host_family.py`,
-`src/paper_stats.py`, `src/paper_verify.py`, `src/paper_runs.py`,
-`src/twohead.py`, `src/twohead_net.py`, `src/stored_host.py`,
-`src/stored_host_run.c`, `src/check_c.py`, `src/throughput.py`, `src/noise.py`,
-`src/redundant.py`, `src/neuromorphic.py` and the
-`src/check_*.py` set, and their records are in `paper/runs/`; `rocq/` holds the
-Rocq development, which `src/check_rocq.py` builds.
+Every figure of the paper comes from `src/paper.py`, `src/host.py`, `src/twohead.py` and
+`src/noise.py`, with the C programs beside them, and their records are in `paper/runs/`;
+`rocq/` holds the Rocq development, which `python src/paper.py rocq` builds.
 
 ---
 
@@ -707,11 +722,11 @@ the Heaviside AND/XOR weights that realize each gate, so the file holds both the
 reversible program and the threshold substrate it runs on.
 
 ```bash
-python src/reversible.py       # reversible gates, Cuccaro ALU, Bennett construction
-python src/reversible_cpu.py   # bijective transition and backward execution
-python src/reversible_prog.py  # structured reversible programs (multiply, Fibonacci, Janus IF)
-python tools/build_reversible.py   # ship + round-trip variants/neural_reversible.safetensors
-python tools/reversible_matrix.py  # ternary matrix stack: permutation transition + 0.5 margin
+python src/automata.py reversible       # reversible gates, Cuccaro ALU, Bennett construction
+python src/automata.py reversible-cpu   # bijective transition and backward execution
+python src/automata.py reversible-prog  # structured reversible programs (multiply, Fibonacci, Janus IF)
+python src/automata.py build-reversible # ship + round-trip variants/neural_reversible.safetensors
+python src/automata.py reversible-matrix# ternary matrix stack: permutation transition + 0.5 margin
 ```
 
 ---
@@ -747,8 +762,8 @@ circuits. With mirror routing and a constant-particle source the construction is
 functionally complete (Margolus 1984).
 
 ```bash
-python src/ca.py             # rule bijection, lattice reversibility, ballistic motion, interaction gate
-python tools/build_ca.py     # ship the block rule as a ternary matrix tile (permutation + 0.5 margin)
+python src/automata.py ca       # rule bijection, lattice reversibility, ballistic motion, interaction gate
+python src/automata.py build-ca # ship the block rule as a ternary matrix tile (permutation + 0.5 margin)
 ```
 
 ---
@@ -780,8 +795,8 @@ bias (`-tau`); reloading it regrows the counter and reproduces the binding
 decision from the gate.
 
 ```bash
-python src/tile.py           # binding gate, XOR/AND/OR rule tiles, binary counter
-python tools/build_tile.py   # ship + regrow variants/neural_tile.safetensors
+python src/automata.py tile       # binding gate, XOR/AND/OR rule tiles, binary counter
+python src/automata.py build-tile # ship + regrow variants/neural_tile.safetensors
 ```
 
 ---
@@ -947,9 +962,9 @@ Alternative architectures: `PositionExtractor` (~1.5 M, position-specific, no at
 ### Training
 
 ```bash
-python train.py --mode router --epochs 100                          # sanity check
-python train.py --mode llm --epochs 100 --batch_size 256            # frozen LLM
-python train.py --mode llm --unfreeze_layers 4 --batch_size 4096    # fine-tune top layers
+python llm_integration/llm.py train --mode router --epochs 100                        # the router alone
+python llm_integration/llm.py train --mode llm --epochs 100 --batch_size 256          # frozen LLM
+python llm_integration/llm.py train --mode llm --unfreeze_layers 4 --batch_size 4096  # fine-tune top layers
 ```
 
 Loss components: BCE on output bits, BCE on extracted A and B bits (2× weight), and CE on operation classification. Curriculum runs 0–9 → 0–99 → 0–255. Optimizer is AdamW, lr 3e-4, gradient clipping 1.0.
@@ -966,89 +981,42 @@ variants/                           18 fitness variants + 9 standalone machines
                                      neural_subleq8io, neural_reflect,
                                      neural_attractor, neural_reversible, neural_ca,
                                      neural_tile)
-src/                                the library (run scripts as `python src/<name>.py`)
-  ├── build.py                      generator (one safetensors per invocation; also `subleq`, `rv32`)
-  ├── quantize.py                   min integer dtypes + ternary verification/repair
-  ├── eval.py                       gate-level fitness suite, NetlistEvaluator, float oracles, reference CPU
-  ├── eval_all.py                   variant-agnostic harness + manifest-sized threshold CPU
-  ├── machines.py                   neural_subleq8 + neural_rv32 runtimes, references, assemblers,
-  │                                 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
-  ├── reflect.py                    neural_reflect: a universal threshold interpreter whose state
-  │                                 holds its own gate table; universality / quine / matrix suites
-  ├── attractor.py                  neural_attractor: energy-based solver (forward eval, inversion,
-  │                                 SAT) built from a QUBO gate-gadget compiler
-  ├── reversible.py                 neural_reversible: reversible threshold gates, Cuccaro ALU,
-  │                                 Bennett construction
-  ├── reversible_cpu.py             reversible register machine: bijective step, backward execution
-  ├── reversible_prog.py            structured reversible programs (multiply, Fibonacci, Janus IF)
-  ├── ca.py                         neural_ca: reversible Margolus cellular automaton, threshold
-  │                                 block rule, lattice reversibility and billiard-ball dynamics
-  ├── tile.py                       neural_tile: abstract tile assembly, threshold binding rule,
-  │                                 XOR/Sierpinski and binary-counter tile sets
-  ├── selfrep.py                    the tape device, the constructor P and the self-reproducing
-  │                                 program P*, the framing maps, and three evaluators
-  ├── canonical.py                  deterministic safetensors writer (pinned key and tensor order)
-  ├── paper_stats.py                unit counts, levelization sizes, effective fan-in
-  ├── paper_verify.py               codec, framing, serialization, datapath, levelization
-  ├── paper_runs.py                 self-description, three generations, lockstep
-  ├── host_family.py                the host family H_A: a constant-depth SUBLEQ step for
-  │                                 every word width, and its serialization in build order
-  ├── netlist_eval.c                an evaluator of the host family, the amplified host and the
-  │                                 interpreter in C, the levels of a large netlist in parallel
-  ├── check_c.py                    the host on the evaluator in C
-  ├── twohead.py                    the two-head machine, transcribed, the description code
-  │                                 and the translating organism; writes rocq/Organism.v
-  ├── twohead_net.py                the two-head machine as a ternary netlist N_{G,L} for a window
-  │                                 of 2^α cells: its check, its file, the organism on it in C,
-  │                                 and the comparison with the netlist extracted from rocq/
+src/                                the library; `python src/<file>.py <command>`
+  ├── build.py                      the generator (also `subleq`, `rv32`), `quantize`, and
+  │                                 `variants`, which builds, quantizes and scores every variant
+  ├── eval.py                       the gate-level fitness suite, NetlistEvaluator, float oracles;
+  │                                 `variants` scores every variant, `cpu` runs the CPU programs
+  ├── machines.py                   the SUBLEQ, RV32 and matrix machines: runtimes, references,
+  │                                 assemblers and suites (`subleq`, `rv32`, `rv32-c`, `matrix8`)
+  ├── reflect.py                    neural_reflect: a threshold interpreter whose state holds its
+  │                                 own gate table; universality, quine and matrix suites
+  ├── automata.py                   the attractor, reversible, cellular-automaton and tile machines,
+  │                                 their suites and their builders
+  ├── host.py                       the SUBLEQ host: its family, serialization, device, the
+  │                                 constructor and the self-reproducing program, the evaluators,
+  │                                 and `constructor8`, the neural_subleq8io suite
+  ├── twohead.py                    the two-head machine: the organism (`organism`), the netlist
+  │                                 N_{G,L} (`net`), and the host stored in it (`stored`)
+  ├── noise.py                      read noise and weight error on the host (`host`), the amplified
+  │                                 host (`amplified`), and the neuromorphic datapath
+  ├── paper.py                      the paper's checks and runs, one command each
+  ├── independent.py                code written from the paper's text alone
+  ├── netlist_eval.c                an evaluator of the host family and the amplified host in C
   ├── twohead_lockstep.c            the organism on N_{G,L} beside the transcription, in C
-  ├── stored_host.py                the host compiled into 36,074 records of the two-head machine
-  │                                 with 4096 cells: one pass against the host's step and device,
-  │                                 the image and its recipe, and its generations
   ├── stored_host_run.c             the stored host's generations on the two-head machine, in C
   ├── restore_bound.c               the restoration bound of the amplified host along the orbit
-  ├── check_rocq.py                 builds rocq/ and prints the assumptions of its theorems
-  ├── independent/                  separate code written from the paper's definitions: the host
-  │                                 family, the levelization, a noise simulator in C, weight
-  │                                 error, and the neuromorphic datapath
-  ├── redundant.py                  the amplified host N_r: r-fold redundancy with the restoring
-  │                                 organ inside every unit, its self-reproduction, its runs
-  │                                 under read noise
-  ├── noise.py                      read noise on the self-reproducing run, the deviation curve
-  │                                 against the bounds, weight error with zero-entry leakage, the
-  │                                 active-input counts that certify an orbit
-  ├── neuromorphic.py               the datapath on the Loihi and Akida neuron models
-  └── check_*.py                    codec boundaries and optimality, step counts, ternary depth,
-                                    environment cost, device, host, host family, levelization,
-                                    framing, serialization, all 29 machines
+  └── nsim.c                        the noise simulator of independent.py
 paper/                              the manuscript, and the record of every run it reports
 rocq/                               Rocq proofs: the netlist of the two-head machine computes its
                                     step for every window of 2^α cells, the organism builds every
                                     image from any description of it and reproduces in every
                                     generation
-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),
-                                    build_attractor.py / test_attractor.py (neural_attractor),
-                                    build_reversible.py / reversible_matrix.py (neural_reversible),
-                                    build_ca.py (neural_ca matrix tile), build_tile.py (neural_tile)
-llm_integration/                    SmolLM2 extractor + circuit wrapper + training code
-  ├── circuits.py                   FrozenThresholdCircuits (loads safetensors, exposes
-  │                                 add_8bit / sub_8bit / mul_8bit / compare_*)
-  ├── model.py                      Extractor variants, ArithmeticModel
-  ├── train.py                      router / interface / llm training modes
-  ├── fitness.py                    randomized fitness function
-  ├── baseline.py                   vanilla SmolLM2 baseline measurement
+tools/play.py                       the playground, and a demonstration on each machine
+llm_integration/
+  ├── llm.py                        SmolLM2 with the frozen circuits: the circuit wrapper, the
+  │                                 fitness, the extractors, training and the baseline
   ├── trained/                      checkpointed extractor weights
-  └── smollm2/
-      ├── SMOLLM2_ARCHITECTURE.md   architecture analysis
-      ├── analyze_smollm2.py        analysis script
-      └── smollm2_analysis.json     analysis output
+  └── smollm2/                      the architecture of SmolLM2 and its analysis
 ```
 
 ---

demos/README.md

@@ -1,22 +0,0 @@
-# demos
-
-Standalone programs that put each machine in the family to work on a named
-task. Every script is self-contained (`python demos/<name>.py`), loads the
-shipped weights, and cross-checks its result against an independent reference.
-
-| Demo | Machine | What it does |
-|------|---------|--------------|
-| `neural_computer8_self_modifying_sieve.py` | `neural_computer8` | Sieve of Eratosthenes; with no indexed addressing, the program rewrites the address bytes of its own LOAD/STORE. Finds all 54 primes < 256. |
-| `neural_computer8_euclid_gcd.py` | `neural_computer8` | Euclid's GCD, with `a mod b` built from the DIV/MUL/SUB opcodes and an XOR register swap. |
-| `neural_computer8_collatz.py` | `neural_computer8` | Collatz step counts; exact for every seed whose trajectory stays inside the 8-bit range. |
-| `neural_rv32_machin_pi.py` | `neural_rv32` | pi to nine digits by Machin's 1706 arctangent formula, printed to the console. |
-| `neural_rv32_neural_nets_via_neur.py` | `neural_rv32` | Ternary neural nets run as NEUR software: one learned by gradient descent, one (XOR) compiled by construction. |
-| `neural_matrix8_gpu_cpu_fleet.py` | `neural_matrix8` | 65,536 CPUs stepped in lockstep on the GPU as one batched matrix product. |
-| `neural_attractor_factoring.py` | `neural_attractor` | Factors semiprimes by relaxing an 8x8 multiplier's energy backward; also divides. |
-| `neural_attractor_nqueens.py` | `neural_attractor` | Solves 6- and 8-queens by relaxing toward zero unsatisfied clauses. |
-| `neural_subleq8io_universal_constructor.py` | `neural_subleq8io` | The universal constructor fabricates a sibling machine byte-for-byte, which then boots. |
-| `neural_reflect_self_modifying_stack.py` | `neural_reflect` | Self-modifying SUBLEQ code, on a stored machine, on the fixed interpreter: three levels in one tensor. |
-| `neural_reversible_counterfactual.py` | `neural_reversible` | Bijective mixing, exact reverse recovery, and the counterfactual when a digest bit is flipped. |
-| `neural_ca_loschmidt_echo.py` | `neural_ca` | A ~2,000-particle gas mixed 500 steps and un-mixed exactly; one flipped cell corrupts half the past. |
-| `neural_ca_reversible_cipher.py` | `neural_ca` | The reversible automaton as a block cipher: exact decryption with the right key, noise with a wrong one. |
-| `neural_tile_pascal_lucas.py` | `neural_tile` | Self-assembly grows Pascal's triangle mod 2; every cell verified against Lucas' theorem. |

demos/neural_attractor_factoring.py

@@ -1,55 +0,0 @@
-"""neural_attractor  --  factoring semiprimes by running a multiplier backward.
-
-An 8x8 array multiplier compiles to a quadratic energy that is 0 exactly on its
-truth table. Clamp the 16 product bits and relax the 16 input bits and the
-network settles into a factorization: multiplication run in reverse. Clamp one
-input as well and the same circuit performs division.
-
-    python demos/neural_attractor_factoring.py
-"""
-import os, sys, time
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-from attractor import multiplier
-
-
-if __name__ == "__main__":
-    c, io = multiplier(8)
-    print("neural_attractor: factoring by energy relaxation")
-    print("=" * 56)
-    print(f"8x8 array multiplier as an energy landscape: {len(c.gates)} gate "
-          f"gadgets, {c.n} wires, 16 free input bits\n")
-
-    ladder = [(3599, 59, 61), (9797, 97, 101), (32399, 179, 181), (57599, 239, 241)]
-    for N, pa, pb in ladder:
-        target = {io["prod"][k]: (N >> k) & 1 for k in range(16)}
-        t0, got = time.perf_counter(), None
-        for attempt in range(1, 8):
-            s = c.solve(io["xs"] + io["ys"], {io["zero"]: 0}, target,
-                        sweeps=2500, restarts=12, seed=N * 7 + attempt)
-            if s is not None:
-                x = sum(s[io["xs"][k]] << k for k in range(8))
-                y = sum(s[io["ys"][k]] << k for k in range(8))
-                if x * y == N and x > 1 and y > 1:
-                    got = (x, y, attempt); break
-        dt = time.perf_counter() - t0
-        if got:
-            x, y, att = got
-            tag = "the prime pair" if {x, y} == {pa, pb} else "valid factorization"
-            print(f"  {N:5d} = {x:3d} x {y:3d}   ({dt:4.1f}s, attempt {att})  [{tag}]")
-        else:
-            print(f"  {N:5d}: ground state not reached in budget ({dt:.1f}s)")
-
-    # division: clamp one input and the product, relax the other input
-    N, xa = 57599, 241
-    fixed = {io["zero"]: 0}
-    for k in range(8):
-        fixed[io["xs"][k]] = (xa >> k) & 1
-    target = {io["prod"][k]: (N >> k) & 1 for k in range(16)}
-    t0 = time.perf_counter()
-    s = c.solve(io["ys"], fixed, target, sweeps=800, restarts=10, seed=7)
-    if s is not None:
-        y = sum(s[io["ys"][k]] << k for k in range(8))
-        print(f"\n  division mode: clamp x=241 and the product -> y = {y} "
-              f"({time.perf_counter()-t0:.1f}s; {xa} x {y} = {xa * y})")

demos/neural_attractor_nqueens.py

@@ -1,90 +0,0 @@
-"""neural_attractor  --  the N-queens problem solved by energy relaxation.
-
-The attractor computer has no clock and no program counter: a circuit compiles
-to a quadratic energy whose global minimum is its consistent assignment, and
-"running" it is rolling downhill. Here every N-queens constraint (one queen per
-row, no two sharing a column or diagonal) becomes a clause wire that must be 1;
-the annealer relaxes the board variables toward zero unsatisfied clauses. This
-is the min-conflicts / MAX-SAT objective, expressed entirely in the family's
-Heaviside threshold gadgets.
-
-    python demos/neural_attractor_nqueens.py
-"""
-import os, sys, time
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-from attractor import Circuit
-
-
-def queens_circuit(N):
-    """Build the N-queens CNF as a threshold circuit; return every clause wire
-    so the solver can drive them all to 1 (a graded, per-clause objective)."""
-    c = Circuit()
-    v = {(r, col): c.wire() for r in range(N) for col in range(N)}
-    clauses = []
-
-    def OR_lits(lits):
-        acc = lits[0]
-        for w in lits[1:]:
-            acc = c.OR(acc, w)
-        return acc
-
-    for r in range(N):                                   # each row: >= 1 queen
-        clauses.append(OR_lits([v[(r, col)] for col in range(N)]))
-        for c1 in range(N):                              # each row: <= 1 queen
-            for c2 in range(c1 + 1, N):
-                clauses.append(OR_lits([c.NOT(v[(r, c1)]), c.NOT(v[(r, c2)])]))
-    for col in range(N):                                 # each column: <= 1
-        for r1 in range(N):
-            for r2 in range(r1 + 1, N):
-                clauses.append(OR_lits([c.NOT(v[(r1, col)]), c.NOT(v[(r2, col)])]))
-    cells = [(r, col) for r in range(N) for col in range(N)]
-    for i in range(len(cells)):                          # each diagonal: <= 1
-        for j in range(i + 1, len(cells)):
-            (r1, c1), (r2, c2) = cells[i], cells[j]
-            if r1 - c1 == r2 - c2 or r1 + c1 == r2 + c2:
-                clauses.append(OR_lits([c.NOT(v[(r1, c1)]), c.NOT(v[(r2, c2)])]))
-    return c, v, clauses
-
-
-def valid(board, N):
-    qs = [rc for rc, b in board.items() if b]
-    if len(qs) != N:
-        return False
-    for i in range(len(qs)):
-        for j in range(i + 1, len(qs)):
-            (r1, c1), (r2, c2) = qs[i], qs[j]
-            if r1 == r2 or c1 == c2 or abs(r1 - r2) == abs(c1 - c2):
-                return False
-    return True
-
-
-def solve_board(N, seeds=8):
-    c, v, clauses = queens_circuit(N)
-    free = list(v.values())
-    target = {w: 1 for w in clauses}
-    t0 = time.perf_counter()
-    for seed in range(seeds):
-        s = c.solve(free, {}, target, sweeps=6000, restarts=6, seed=seed)
-        if s is not None:
-            board = {rc: s[w] for rc, w in v.items()}
-            if valid(board, N):
-                return board, len(clauses), c.n, time.perf_counter() - t0
-    return None, len(clauses), c.n, time.perf_counter() - t0
-
-
-if __name__ == "__main__":
-    print("neural_attractor: N-queens as energy relaxation")
-    print("=" * 56)
-    for N in (6, 8):
-        board, nclauses, nwires, dt = solve_board(N)
-        status = "SOLVED" if board else "no solution reached in budget"
-        print(f"\n{N}-queens: {nclauses} clause gadgets over {nwires} wires -> "
-              f"{status} ({dt:.1f}s)")
-        if board:
-            for r in range(N):
-                print("   " + " ".join("Q" if board[(r, col)] else "." for col in range(N)))
-            print(f"   verified: {N} queens, no shared row/column/diagonal")
-    print("\nNo search loop was written: the constraints are an energy surface and")
-    print("the solution is its floor. The queens fall into place.")

demos/neural_ca_loschmidt_echo.py

@@ -1,55 +0,0 @@
-"""neural_ca  --  a Loschmidt echo in a reversible cellular automaton.
-
-The Margolus block rule is a bijection, so a gas of ~2,000 particles mixed for
-500 steps can be un-mixed by iterating the same rule backward: the initial
-configuration returns cell-for-cell (particle number conserved throughout). Yet
-flipping a single cell of the mixed state before reversing corrupts roughly half
-the reconstructed past -- exact reversibility and sensitive dependence in the
-same automaton.
-
-    python demos/neural_ca_loschmidt_echo.py
-"""
-import os, sys, time, random, statistics
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-import ca
-
-
-def coarse(g, H, W, k=8):
-    out = []
-    for by in range(0, H, k):
-        for bx in range(0, W, k):
-            out.append(sum(g[y][x] for y in range(by, by + k) for x in range(bx, bx + k)))
-    return out
-
-
-if __name__ == "__main__":
-    H = W = 64
-    rng = random.Random(2026)
-    grid = [[1 if rng.random() < 0.5 else 0 for _ in range(W)] for _ in range(H)]
-    n0 = sum(map(sum, grid))
-    STEPS = 500
-
-    print("neural_ca: Loschmidt echo (mix, then run time backward)")
-    print("=" * 56)
-    t0 = time.perf_counter()
-    fwd = ca.run(grid, STEPS, 0)
-    n1 = sum(map(sum, fwd))
-    back = ca.run_back(fwd, STEPS, 0)
-    echo = back == grid
-    dt = time.perf_counter() - t0
-
-    print(f"particles: {n0} at t=0, {n1} at t={STEPS} "
-          f"({'conserved' if n0 == n1 else 'NOT CONSERVED'})")
-    print(f"coarse 8x8 occupancy stdev: t=0 {statistics.pstdev(coarse(grid, H, W)):.2f} "
-          f"-> t={STEPS} {statistics.pstdev(coarse(fwd, H, W)):.2f} (mixed)")
-    print(f"{STEPS} steps forward + {STEPS} reversed in {dt:.1f}s: "
-          f"t=0 recovered {'EXACTLY' if echo else 'FAILED'}")
-
-    flip = [row[:] for row in fwd]
-    flip[0][0] ^= 1
-    back2 = ca.run_back(flip, STEPS, 0)
-    ham = sum(back2[y][x] != grid[y][x] for y in range(H) for x in range(W))
-    print(f"butterfly: flip ONE cell at t={STEPS}, reverse again -> reconstructed "
-          f"past wrong in {ham}/{H * W} cells")

demos/neural_ca_reversible_cipher.py

@@ -1,84 +0,0 @@
-"""neural_ca  --  a reversible cellular automaton as a perfect cipher.
-
-The Margolus block rule is a bijection of the lattice, so iterating it forward
-diffuses a bitmap into noise and iterating the exact same rule backward restores
-it bit-for-bit. That makes the automaton a block cipher whose key is the pair
-(number of steps, starting partition phase): the right key inverts the diffusion
-perfectly, and a key off by a single step returns noise. No information is ever
-destroyed, so decryption is exact rather than approximate.
-
-    python demos/neural_ca_reversible_cipher.py
-"""
-import os, sys
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-import ca
-
-# a recognizable plaintext bitmap (a heart), padded into a larger lattice
-ART = [
-    "  ###   ###  ",
-    " ##### ##### ",
-    "#############",
-    "#############",
-    "#############",
-    " ########### ",
-    "  #########  ",
-    "   #######   ",
-    "    #####    ",
-    "     ###     ",
-    "      #      ",
-]
-PAD_X, PAD_Y = 6, 4
-
-
-def make_grid():
-    # the Margolus partition tiles 2x2 blocks toroidally, so H and W must be even
-    h = len(ART) + 2 * PAD_Y
-    w = len(ART[0]) + 2 * PAD_X
-    h += h & 1
-    w += w & 1
-    g = [[0] * w for _ in range(h)]
-    for y, row in enumerate(ART):
-        for x, ch in enumerate(row):
-            if ch == "#":
-                g[y + PAD_Y][x + PAD_X] = 1
-    return g
-
-
-def render(g):
-    return "\n".join("".join("#" if c else "." for c in row) for row in g)
-
-
-def hamming(a, b):
-    return sum(a[y][x] != b[y][x] for y in range(len(a)) for x in range(len(a[0])))
-
-
-if __name__ == "__main__":
-    plain = make_grid()
-    KEY_STEPS, KEY_PHASE = 200, 0
-
-    cipher = ca.run(plain, KEY_STEPS, KEY_PHASE)
-    recovered = ca.run_back(cipher, KEY_STEPS, KEY_PHASE)
-    wrong = ca.run_back(cipher, KEY_STEPS - 1, KEY_PHASE)   # key off by one step
-
-    n = sum(map(sum, plain))
-    print("neural_ca: reversible-automaton cipher")
-    print("=" * 46)
-    print(f"key = ({KEY_STEPS} steps, phase {KEY_PHASE}); {n} set bits (conserved "
-          f"throughout: {sum(map(sum, cipher)) == n})\n")
-
-    print("PLAINTEXT:")
-    print(render(plain))
-    print(f"\nCIPHERTEXT after {KEY_STEPS} forward steps (diffused to noise):")
-    print(render(cipher))
-    print(f"\nDECRYPTED with the correct key:")
-    print(render(recovered))
-    print(f"  exact recovery: {recovered == plain}  (Hamming distance 0)")
-    print(f"\nDECRYPTED with a wrong key (off by one step):")
-    print(render(wrong))
-    print(f"  still scrambled: {hamming(wrong, plain)} of {len(plain)*len(plain[0])} "
-          f"cells differ from the plaintext")
-    print("\nEvery step is a bijection, so the ciphertext holds exactly the")
-    print("information of the plaintext -- no more, no less. Only the exact")
-    print("reverse trajectory recovers it.")

demos/neural_computer8_collatz.py

@@ -1,76 +0,0 @@
-"""neural_computer8  --  the Collatz map iterated on the threshold CPU.
-
-n -> n/2 if even, 3n+1 if odd, counting steps to 1. The parity test is a
-bitwise AND with 1 that leaves the flags untouched, so the loop branches on the
-comparison that precedes it. The register file is architecturally 8-bit, so the
-machine computes the Collatz trajectory modulo 256; for seeds whose true
-trajectory never exceeds 255, that is the exact Collatz step count, checked here
-against a native reference.
-
-    python demos/neural_computer8_collatz.py
-"""
-import os, sys, time
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-sys.path.insert(0, os.path.join(REPO, "tools"))
-from safetensors import safe_open
-from cpu_programs import Asm
-from eval_all import GenericThresholdCPU, get_manifest
-
-
-def build(n0):
-    a = Asm(1024)
-    a.load(0, "N"); a.load(1, "ONE"); a.xor(2, 2)   # R0=n, R1=1, R2=steps
-    a.label("loop")
-    a.cmp(0, 1); a.jz("done")            # n == 1 ?
-    a.xor(3, 3); a.add(3, 0); a.and_(3, 1)   # R3 = n & 1  (flags preserved)
-    a.cmp(3, 1); a.jz("odd")
-    a.shr(0); a.jmp("step")              # even: n >>= 1
-    a.label("odd")
-    a.xor(3, 3); a.add(3, 0); a.shl(3)   # R3 = 2n
-    a.add(0, 3); a.add(0, 1)             # n = 3n + 1
-    a.label("step")
-    a.add(2, 1); a.jmp("loop")           # steps++
-    a.label("done")
-    a.store(2, "RES"); a.halt()
-    a.org(0x300); a.label("N"); a.db(n0)
-    a.label("ONE"); a.db(1); a.label("RES"); a.db(0)
-    return a, a.assemble()
-
-
-def true_collatz(n):
-    peak, steps = n, 0
-    while n != 1:
-        n = n // 2 if n % 2 == 0 else 3 * n + 1
-        peak = max(peak, n); steps += 1
-    return steps, peak
-
-
-if __name__ == "__main__":
-    tens = {}
-    with safe_open(os.path.join(REPO, "variants", "neural_computer8_small.safetensors"),
-                   framework="pt") as f:
-        for name in f.keys():
-            tens[name] = f.get_tensor(name).float()
-    cpu = GenericThresholdCPU(tens)
-    addr = get_manifest(tens)["addr_bits"]
-
-    print("neural_computer8: Collatz step counts through the gates")
-    print("=" * 56)
-    print("  seed   CPU steps   true steps   peak   in 8-bit range?")
-    for n0 in (6, 7, 9, 18, 25, 45):
-        a, mem = build(n0)
-        state = {"pc": 0, "regs": [0] * 4, "flags": [0] * 4, "mem": list(mem),
-                 "halted": False, "sp": (1 << addr) - 1}
-        t0 = time.perf_counter()
-        final, cycles = cpu.run(state, max_cycles=3000)
-        steps = final["mem"][a.labels["RES"]]
-        tsteps, peak = true_collatz(n0)
-        inrange = peak <= 255
-        match = "MATCH" if (inrange and steps == tsteps) else \
-                ("mod-256" if not inrange else "MISMATCH")
-        print(f"  {n0:4d}   {steps:9d}   {tsteps:10d}   {peak:4d}   "
-              f"{'yes' if inrange else 'no (wraps)':10s} [{match}]")
-    print("\n  For every seed whose trajectory stays under 256 the threshold CPU")
-    print("  reproduces the exact Collatz step count.")

demos/neural_computer8_euclid_gcd.py

@@ -1,63 +0,0 @@
-"""neural_computer8  --  Euclid's algorithm on the threshold CPU.
-
-The greatest common divisor by repeated remainder, where the remainder itself
-is synthesized from the machine's own opcodes: a mod b = a - (a / b) * b, using
-the DIV, MUL and SUB gates, and the register swap is three XORs (no temporary).
-Every step runs through threshold neurons.
-
-    python demos/neural_computer8_euclid_gcd.py
-"""
-import os, sys, time, math
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-sys.path.insert(0, os.path.join(REPO, "tools"))
-from safetensors import safe_open
-from cpu_programs import Asm
-from eval_all import GenericThresholdCPU, get_manifest
-
-
-def build(a0, b0):
-    g = Asm(1024)
-    g.load(0, "A")            # R0 = a
-    g.load(1, "B")            # R1 = b
-    g.xor(3, 3)               # R3 = 0
-    g.label("loop")
-    g.cmp(1, 3); g.jz("done")  # while b != 0
-    g.xor(2, 2); g.add(2, 0)   # R2 = a
-    g._alu(0x8, 2, 1)          # R2 = a / b     (DIV opcode)
-    g.mul(2, 1)                # R2 = (a/b)*b
-    g.sub(0, 2)                # R0 = a mod b
-    g.xor(0, 1); g.xor(1, 0); g.xor(0, 1)   # swap -> (b, a mod b)
-    g.jmp("loop")
-    g.label("done")
-    g.store(0, "RES"); g.halt()
-    g.org(0x300)
-    g.label("A"); g.db(a0)
-    g.label("B"); g.db(b0)
-    g.label("RES"); g.db(0)
-    return g, g.assemble()
-
-
-if __name__ == "__main__":
-    tens = {}
-    with safe_open(os.path.join(REPO, "variants", "neural_computer8_small.safetensors"),
-                   framework="pt") as f:
-        for name in f.keys():
-            tens[name] = f.get_tensor(name).float()
-    cpu = GenericThresholdCPU(tens)
-    addr = get_manifest(tens)["addr_bits"]
-
-    print("neural_computer8: Euclid's GCD through the gates")
-    print("=" * 56)
-    for a0, b0 in [(84, 36), (120, 90), (221, 34), (255, 128)]:
-        g, mem = build(a0, b0)
-        state = {"pc": 0, "regs": [0] * 4, "flags": [0] * 4, "mem": list(mem),
-                 "halted": False, "sp": (1 << addr) - 1}
-        t0 = time.perf_counter()
-        final, cycles = cpu.run(state, max_cycles=400)
-        res = final["mem"][g.labels["RES"]]
-        ok = res == math.gcd(a0, b0)
-        print(f"  gcd({a0:3d}, {b0:3d}) = {res:3d}   ({cycles:3d} cycles, "
-              f"{time.perf_counter()-t0:.1f}s)   "
-              f"[{'MATCH' if ok else 'MISMATCH vs ' + str(math.gcd(a0, b0))}]")

demos/neural_computer8_self_modifying_sieve.py

@@ -1,76 +0,0 @@
-"""neural_computer8  --  the Sieve of Eratosthenes with self-modifying code.
-
-The threshold CPU's ISA has no indexed addressing, so the program does exactly
-what memory-constrained 1970s code did: it rewrites the address bytes of its own
-LOAD and STORE instructions before each access, walking a pointer across the
-flags array. Every gate that fetches, decodes, marks, and patches is a threshold
-neuron. It halts with all 54 primes below 256 marked.
-
-    python demos/neural_computer8_self_modifying_sieve.py
-"""
-import os, sys, time
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-sys.path.insert(0, os.path.join(REPO, "tools"))
-from safetensors import safe_open
-from cpu_programs import Asm, _enc
-from eval_all import GenericThresholdCPU, get_manifest
-
-FLAGS = 0x300                       # flags[0..255] at 0x300..0x3FF
-
-
-def build():
-    g = Asm(1024)
-    g.load(3, "ONE")                    # R3 = 1 (mark value / increment)
-    g.load(0, "TWO")                    # R0 = p = 2
-    g.label("outer")
-    g.store(0, "Rlo")                   # patch probe address low byte <- p
-    g.dw(_enc(0xA, 2, 0))               # probe: R2 = flags[p]  (self-modified)
-    g.db(FLAGS >> 8); g.label("Rlo"); g.db(0x00)
-    g.cmp(2, 3); g.jz("next_p")         # flags[p] == 1 -> composite, skip
-    g.xor(1, 1); g.add(1, 0); g.add(1, 0)   # m = 2p
-    g.label("inner")
-    g.store(1, "Wlo")                   # patch mark address low byte <- m
-    g.dw(_enc(0xB, 0, 3))               # mark: flags[m] = R3 = 1  (self-modified)
-    g.db(FLAGS >> 8); g.label("Wlo"); g.db(0x00)
-    g.add(1, 0)                         # m += p  (carry iff we passed 255)
-    g.jnc("inner")
-    g.label("next_p")
-    g.add(0, 3)                         # p += 1
-    g.load(2, "SIXTEEN")
-    g.cmp(0, 2)
-    g.jnz("outer")                      # loop until p == 16 (16^2 > 255)
-    g.halt()
-    g.org(0x200)
-    g.label("ONE"); g.db(1)
-    g.label("TWO"); g.db(2)
-    g.label("SIXTEEN"); g.db(16)
-    return g, g.assemble()
-
-
-if __name__ == "__main__":
-    g, mem = build()
-    tens = {}
-    with safe_open(os.path.join(REPO, "variants", "neural_computer8_small.safetensors"),
-                   framework="pt") as f:
-        for name in f.keys():
-            tens[name] = f.get_tensor(name).float()
-    cpu = GenericThresholdCPU(tens)
-    state = {"pc": 0, "regs": [0] * 4, "flags": [0] * 4, "mem": list(mem),
-             "halted": False, "sp": (1 << get_manifest(tens)["addr_bits"]) - 1}
-    t0 = time.perf_counter()
-    final, cycles = cpu.run(state, max_cycles=4000)
-    dt = time.perf_counter() - t0
-
-    got = [n for n in range(2, 256) if final["mem"][FLAGS + n] == 0]
-    ref = [n for n in range(2, 256) if all(n % d for d in range(2, int(n**0.5) + 1))]
-    print("neural_computer8: self-modifying Sieve of Eratosthenes")
-    print("=" * 56)
-    print(f"halted={final['halted']}  {cycles} cycles through the gates ({dt:.0f}s)")
-    print(f"primes < 256 found: {len(got)}   native sieve: {len(ref)}   "
-          f"{'EXACT MATCH' if got == ref else 'MISMATCH'}")
-    print("  " + " ".join(map(str, got)))
-    print(f"self-modified operand bytes at halt: probe={final['mem'][g.labels['Rlo']]}, "
-          f"mark={final['mem'][g.labels['Wlo']]} (the program rewrote its own "
-          f"instruction stream as it ran)")

demos/neural_matrix8_gpu_cpu_fleet.py

@@ -1,73 +0,0 @@
-"""neural_matrix8  --  a fleet of processors as one batched matrix product.
-
-The whole CPU is compiled to 108 ternary weight matrices with a Heaviside step
-between them, so one clock cycle is one matrix-vector product plus a threshold.
-Add a batch dimension and N processors are the same 108 matmuls: here 65,536
-independent CPUs step in lockstep on the GPU. A 256-wide correctness fleet
-confirms every CPU halts exactly at cycle 2n+1 for its own countdown input.
-
-    python demos/neural_matrix8_gpu_cpu_fleet.py
-"""
-import os, sys, time
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-import torch
-from matrix8 import MatrixMachine, state_to_vec, _mk_state, _instr
-
-
-def prog_bytes():
-    return (_instr(0x1, 0, 1)        # SUB R0, R1
-            + _instr(0xD, 0, 0, 1) + [0, 0]   # JNZ 0x0000 (address word)
-            + _instr(0xF)            # HALT
-            + [0] * 8)
-
-
-if __name__ == "__main__":
-    dev = "cuda" if torch.cuda.is_available() else "cpu"
-    mm = MatrixMachine.from_file(device=dev)
-    n_neurons = sum(int(b.numel()) for b in mm.B)
-    name = torch.cuda.get_device_name(0) if dev == "cuda" else "cpu"
-    print("neural_matrix8: 65,536 CPUs as one batched matrix product")
-    print("=" * 56)
-    print(f"loaded {len(mm.W)} ternary matrices, {n_neurons:,} threshold neurons "
-          f"per transition, device={dev} ({name})")
-    mem = prog_bytes()
-
-    # correctness fleet: one CPU per 8-bit input, all 256 at once
-    V = torch.stack([state_to_vec(_mk_state(mem=mem, regs=(x, 1, 0, 0)))
-                     for x in range(256)]).to(dev)
-    first_halt = torch.full((256,), -1, dtype=torch.long)
-    step = 0
-    while step < 600:
-        halted = V[:, MatrixMachine.HALT_IDX] > 0.5
-        first_halt[(first_halt < 0) & halted.cpu()] = step
-        if bool(halted.all()):
-            break
-        V = mm.step(V); step += 1
-    expect = torch.tensor([2 * (x if x else 256) + 1 for x in range(256)])
-    ok_halt = bool((first_halt == expect).all())
-    ok_r0 = bool((V[:, 4:12].cpu().long().sum(1) == 0).all())
-    print(f"\ncorrectness fleet of 256: every CPU halts at cycle 2n+1 for its own "
-          f"input: {'EXACT' if ok_halt else 'MISMATCH'}; all results R0==0: {ok_r0}")
-
-    # throughput fleet: 65,536 CPUs
-    B = 65536
-    V = torch.stack([state_to_vec(_mk_state(mem=mem, regs=(x & 0xFF, 1, 0, 0)))
-                     for x in range(256)]).repeat(256, 1).to(dev)
-    if dev == "cuda":
-        torch.cuda.synchronize()
-    t0, steps = time.perf_counter(), 0
-    while steps < 520:
-        V = mm.step(V); steps += 1
-        if steps % 64 == 0 and bool((V[:, MatrixMachine.HALT_IDX] > 0.5).all()):
-            break
-    if dev == "cuda":
-        torch.cuda.synchronize()
-    dt = time.perf_counter() - t0
-    instr = B * steps
-    print(f"\nthroughput fleet of {B:,}: {steps} transitions in {dt:.1f}s")
-    print(f"  {instr / dt / 1e6:,.1f} million instructions/s aggregate "
-          f"({instr:,} instructions retired)")
-    print(f"  {instr * n_neurons / dt / 1e9:,.1f} billion threshold-neuron "
-          f"evaluations/s")

demos/neural_reflect_self_modifying_stack.py

@@ -1,87 +0,0 @@
-"""neural_reflect  --  three levels of machine in one tensor.
-
-Level 0 is U, a fixed ternary threshold interpreter (~24k gates). Level 1 is a
-complete SUBLEQ computer stored as data inside U's writable state. Level 2 is a
-SUBLEQ program that rewrites its own operand bytes as it runs: a zeroing
-instruction that walks itself across memory, erasing a block. The interpreter,
-the machine it runs, and the program that machine executes are all the same
-tensor; the final memory is checked bit-for-bit against a native SUBLEQ emulator.
-
-    python demos/neural_reflect_self_modifying_stack.py
-"""
-import os, sys, time
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-import torch
-from reflect import (Cfg, build_subleq_machine, build_net, Leveled,
-                     encode_netlist, state_to_vec, subleq32_step, MEM, MEMB)
-
-
-if __name__ == "__main__":
-    dev = "cuda" if torch.cuda.is_available() else "cpu"
-    cfg = Cfg(A=14, G=296, banks=1, self_mod=False)
-    prog, lay = build_subleq_machine(cfg)
-    inet, ii, io = build_net(cfg)
-    print("neural_reflect: self-modifying code on a stored machine on U")
-    print("=" * 60)
-    print(f"level 0: interpreter U = {len(inet.gates):,} threshold gates (fixed)")
-    print(f"level 1: a SUBLEQ machine = {len(prog)} gates, stored as writable data")
-    lev = Leveled(inet, ii, io, device=dev)
-    nl = encode_netlist(cfg, prog)
-    sig0 = [0] * cfg.S
-    sig0[cfg.NET0:cfg.NET0 + len(nl)] = nl
-    base = state_to_vec(cfg, {"sig": sig0, "gp": 0, "halt": 0}).to(dev)
-    PC = lay["PC"]
-
-    # level 2: SUBLEQ (A B C: M[B]-=M[A]; if <=0 goto C). The first instruction
-    # zeroes a target cell, then two instructions increment its own A and B
-    # operand bytes, so the zeroing walks across a data block.
-    pm = [0] * 32
-    pm[0:3]   = [24, 24, 3]      # zero M[<target>]; these operands get rewritten
-    pm[3:6]   = [19, 0, 6]       # M[0] += 1  (patch own A-field: cell 0)
-    pm[6:9]   = [19, 1, 9]       # M[1] += 1  (patch own B-field: cell 1)
-    pm[9:12]  = [20, 21, 15]     # count -= 1; if <= 0 branch to epilogue
-    pm[12:15] = [18, 18, 0]      # 0 -> unconditional jump to loop head
-    pm[15:18] = [18, 18, 31]     # epilogue: branch to 31 = HALT
-    pm[18], pm[19], pm[20], pm[21] = 0, 255, 1, 4
-    pm[24:28] = [7, 99, 123, 200]          # the block the program will erase
-    print(f"level 2: a program whose instruction 0 starts as [24,24,3] and "
-          f"rewrites its own operands")
-
-    ref_mem, ref_pc = list(pm), 0
-    while ref_pc != 31:
-        ref_mem, ref_pc = subleq32_step(ref_mem, ref_pc)
-
-    V = base.unsqueeze(0).clone()
-    for i in range(32):
-        for b in range(8):
-            V[:, MEM + b * MEMB + i] = float((pm[i] >> b) & 1)
-
-    def get_mem(Vc):
-        return sum(Vc[:, MEM + b * MEMB: MEM + b * MEMB + 32].long() << b
-                   for b in range(8))[0].tolist()
-
-    t0, walk, steps, halted = time.perf_counter(), [], 0, False
-    for _ in range(26):
-        m_now = get_mem(V.cpu())
-        walk.append((m_now[0], m_now[1]))
-        for _ in range(cfg.G):
-            V = lev.step(V)
-        steps += 1
-        if int(V[0, cfg.S + cfg.GPW]) == 1:
-            halted = True
-            break
-    dt = time.perf_counter() - t0
-    got = get_mem(V.cpu())
-
-    mut = " -> ".join(f"[{a},{b}]" for a, b in
-                      [walk[0]] + [w for i, w in enumerate(walk[1:], 1) if w != walk[i - 1]])
-    print(f"\nran {steps} hosted instructions in {dt:.0f}s "
-          f"({steps * cfg.G} interpreter recurrences); halted={halted}")
-    print(f"  instruction 0's operand cells as it ran: {mut}")
-    print(f"  target block M[24..27]: {pm[24:28]} -> {got[24:28]}")
-    print(f"  final memory == native SUBLEQ reference: "
-          f"{'EXACT' if got == ref_mem else 'MISMATCH'}")
-    print("\n  The program, the machine it runs on, and the machine that runs")
-    print("  that machine are all the same tensor.")

demos/neural_reversible_counterfactual.py

@@ -1,49 +0,0 @@
-"""neural_reversible  --  computation with no erasure, and the counterfactual.
-
-Every instruction of this register machine is a bijection, so the same weights
-run backward invert the forward computation: a mixing program hashes a seed into
-a digest, and stepping in reverse reconstructs the seed exactly, with no bit ever
-erased (Landauer floor: zero). Because history is only consistent with the truth,
-flipping a single bit of the digest and running backward yields a "past" that is
-wrong in many bits: information is conserved, so a corrupted future refuses to
-invert to the real input.
-
-    python demos/neural_reversible_counterfactual.py
-"""
-import os, sys
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-from reversible_cpu import RCPU, _clone
-
-
-if __name__ == "__main__":
-    # cross-coupled mixing: R0 feeds R3 and R3 feeds R0, so the avalanche spreads
-    prog = []
-    for _ in range(8):
-        prog += [("ADD", 0, 3), ("TOFF", 3, 0, 2), ("ROL", 0, 1), ("XOR", 2, 3)]
-    cpu = RCPU(prog)
-    seed = cpu.new_state(regs=[7, 13, 201, 0])
-
-    print("neural_reversible: no-erasure computing and the counterfactual")
-    print("=" * 60)
-    s = _clone(seed)
-    cpu.run(s, len(prog))
-    print(f"seed registers {seed['R']}  --{len(prog)} bijective steps-->  "
-          f"digest {s['R']}")
-
-    b = _clone(s)
-    cpu.run_back(b, len(prog))
-    print(f"run backward: seed recovered "
-          f"{'EXACTLY' if b['R'] == seed['R'] and b['PC'] == seed['PC'] else 'FAILED'} "
-          f"(no bit was ever erased; Landauer floor 0)")
-
-    c = _clone(s)
-    c["R"][3] ^= 4                                  # corrupt one bit of the digest
-    cpu.run_back(c, len(prog))
-    diff = sum(bin(x ^ y).count("1") for x, y in zip(c["R"], seed["R"]))
-    print(f"counterfactual: flip ONE digest bit, run history backward -> the "
-          f"reconstructed 'seed' is wrong in {diff}/32 register bits")
-    print(f"  corrupted 'seed' = {c['R']}   true seed = {seed['R']}")
-    print("\n  History inverts only when it is the true history. A tampered")
-    print("  future does not lead back to the real past.")

demos/neural_rv32_machin_pi.py

@@ -1,85 +0,0 @@
-"""neural_rv32  --  pi by Machin's formula, computed on the RISC-V threshold CPU.
-
-pi = 16*arctan(1/5) - 4*arctan(1/239)  (John Machin, 1706), evaluated as an
-integer arctangent series at scale 1e8 with rounded divisions. Every add,
-multiply and divide runs through the ternary threshold datapath; 239^2 is
-computed on-machine, and the result is formatted to the memory-mapped console.
-
-    python demos/neural_rv32_machin_pi.py
-"""
-import os, sys, time
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-import torch
-from machines import Asm, Rv32ThresholdCPU, rv_state
-from eval_all import int_to_bits
-
-
-def native():
-    """Integer mirror of the exact recurrence the machine will run."""
-    accA, t, sign, d, dsA = 0, 1600000000 // 5, 1, 1, []
-    while t > 0:
-        accA += sign * ((t + d // 2) // d); dsA.append(d)
-        sign, d, t = -sign, d + 2, (t + 12) // 25
-    accB, t, q, dsB, sign, d = 0, (400000000 + 119) // 239, 239 * 239, [], 1, 1
-    while t > 0:
-        accB += sign * ((t + d // 2) // d); dsB.append(d)
-        sign, d, t = -sign, d + 2, (t + q // 2) // q
-    return accA - accB, dsA, dsB
-
-
-def build(dsA, dsB):
-    a = Asm()
-    a.lui(4, 0x5F5E1)                    # x4 = 1,600,000,000
-    a.addi(5, 0, 25); a.addi(6, 0, 10); a.addi(8, 0, 239); a.addi(14, 0, 5)
-    a.div(11, 4, 14)                     # t = 16e8/5
-    a.addi(10, 0, 0)                     # accA
-    for k, d in enumerate(dsA):
-        a.addi(12, 0, d); a.addi(13, 11, d // 2); a.div(13, 13, 12)
-        (a.add if k % 2 == 0 else a.sub)(10, 10, 13)
-        if k + 1 < len(dsA):
-            a.addi(13, 11, 12); a.div(11, 13, 5)
-    a.lui(7, 0x17D78); a.ori(7, 7, 0x400)    # x7 = 400,000,000
-    a.addi(13, 7, 119); a.div(11, 13, 8)
-    a.mul(9, 8, 8)                       # 239^2 computed on-machine
-    a.srli(14, 9, 1)
-    a.addi(15, 0, 0)                     # accB
-    for k, d in enumerate(dsB):
-        a.addi(12, 0, d); a.addi(13, 11, d // 2); a.div(13, 13, 12)
-        (a.add if k % 2 == 0 else a.sub)(15, 15, 13)
-        if k + 1 < len(dsB):
-            a.add(13, 11, 14); a.div(11, 13, 9)
-    a.sub(10, 10, 15)                    # x10 = pi * 1e8
-    a.addi(20, 0, 0x7F8); a.slli(20, 20, 5)      # console 0xFF00
-    a.lui(21, 0x5F5E); a.ori(21, 21, 0x100)      # P = 1e8
-    a.div(22, 10, 21); a.rem(10, 10, 21)
-    a.addi(22, 22, 48); a.sb(22, 20, 0)          # integer digit
-    a.addi(22, 0, 46); a.sb(22, 20, 0)           # '.'
-    a.div(21, 21, 6); a.addi(23, 0, 8)
-    a.label("digits")
-    a.div(22, 10, 21); a.rem(10, 10, 21)
-    a.addi(22, 22, 48); a.sb(22, 20, 0)
-    a.div(21, 21, 6); a.addi(23, 23, -1); a.bne(23, 0, "digits")
-    a.ecall()
-    return a.assemble()
-
-
-if __name__ == "__main__":
-    pi9, dsA, dsB = native()
-    mem = build(dsA, dsB)
-    print("neural_rv32: Machin's pi on the threshold datapath")
-    print("=" * 56)
-    print("loading neural_rv32 (8.77M ternary parameters)...")
-    cpu = Rv32ThresholdCPU()
-    ts = rv_state(mem)
-    ts["_mem_bits"] = torch.tensor([int_to_bits(b, 8) for b in ts["mem"]], dtype=torch.float32)
-    t0, cyc = time.perf_counter(), 0
-    while not ts["halted"] and cyc < 400:
-        ts = cpu.step(ts); cyc += 1
-    want = f"{pi9 // 10**8}.{pi9 % 10**8:08d}"
-    print(f"console output : {ts['console']!r}   ({cyc} cycles, "
-          f"{time.perf_counter()-t0:.0f}s, dual-issue pairs {cpu.pairs_issued})")
-    print(f"integer mirror : {want!r}   (machine {'EXACT' if ts['console']==want else 'MISMATCH'})")
-    print(f"true pi        : 3.14159265(35...)  -> all printed digits "
-          f"{'correct' if ts['console']=='3.14159265' else 'NOT all correct'}")

demos/neural_rv32_neural_nets_via_neur.py

@@ -1,184 +0,0 @@
-"""neural_rv32  --  neural networks running as software on the neural-net CPU.
-
-neural_rv32's NEUR opcode computes exactly one ternary threshold neuron:
-    rd = H( popcount(rs1 & pos) - popcount(rs1 & neg) + sext5(bias) )
-with weights in {-1,0,+1} and an integer bias. So a program of NEUR
-instructions IS a ternary neural network -- and the CPU executing it is itself
-a threshold network. One net here is LEARNED by gradient descent (a nonlinear
-popcount band) and one is COMPILED by construction (8-bit parity, the function
-that ended the single perceptron); both are then deployed as NEUR code and run
-on the threshold datapath, with the CPU output checked against the reference net.
-
-    python demos/neural_rv32_neural_nets_via_neur.py
-"""
-import os, sys, time
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-os.chdir(REPO)
-import torch
-from machines import Asm, Rv32ThresholdCPU, rv_state
-from eval_all import int_to_bits
-
-torch.manual_seed(0)
-
-
-def ternary(w):                      # {-1,0,+1} forward, identity backward (STE)
-    wq = torch.where(w > 0.5, 1.0, torch.where(w < -0.5, -1.0, 0.0))
-    return w + (wq - w).detach()
-
-def ibias(b, lo=-16, hi=15):
-    bq = b.round().clamp(lo, hi)
-    return b + (bq - b).detach()
-
-# ---- discrete NEUR reference (exactly what the hardware computes) ----------
-def neuron(x, pos, neg, bias):
-    return 1 if (bin(x & pos).count("1") - bin(x & neg).count("1") + bias) >= 0 else 0
-
-def discrete_net(x, hidden, out):
-    h = 0
-    for j, (p, n, b) in enumerate(hidden):
-        h |= neuron(x, p, n, b) << j
-    p, n, b = out
-    return neuron(h, p, n, b)
-
-# ---- train a 2-layer ternary MLP; hidden step trained with an annealed -----
-#      sigmoid so real gradients flow, then hardened to Heaviside at extraction
-def train(target_fn, H, epochs=5000, seed=0, nbits=8):
-    torch.manual_seed(seed)
-    N = 1 << nbits
-    xs = torch.arange(N)
-    X = torch.stack([((xs >> i) & 1).float() for i in range(nbits)], 1)
-    Y = torch.tensor([float(target_fn(int(x))) for x in xs])
-    Wh = torch.nn.Parameter(torch.randn(H, nbits) * 1.5)
-    bh = torch.nn.Parameter(torch.randn(H) * 1.5)
-    Wo = torch.nn.Parameter(torch.randn(H) * 1.5)
-    bo = torch.nn.Parameter(torch.zeros(1))
-    opt = torch.optim.Adam([Wh, bh, Wo, bo], lr=0.03)
-    npos = float(Y.sum())
-    bce = torch.nn.BCEWithLogitsLoss(pos_weight=torch.tensor((N - npos) / max(npos, 1.0)))
-    for ep in range(epochs):
-        opt.zero_grad()
-        Tt = 1.0 + 11.0 * ep / epochs
-        preh = X @ ternary(Wh).T + ibias(bh)
-        h = torch.sigmoid(Tt * preh)
-        preo = h @ ternary(Wo) + ibias(bo)
-        loss = bce(4.0 * preo, Y)
-        loss.backward(); opt.step()
-    Whq = torch.where(Wh > 0.5, 1, torch.where(Wh < -0.5, -1, 0)).tolist()
-    Woq = torch.where(Wo > 0.5, 1, torch.where(Wo < -0.5, -1, 0)).tolist()
-    bhq = bh.round().clamp(-16, 15).long().tolist()
-    boq = int(bo.round().clamp(-16, 15).item())
-    def pack(wrow):
-        return (sum(1 << i for i, w in enumerate(wrow) if w > 0),
-                sum(1 << i for i, w in enumerate(wrow) if w < 0))
-    hidden = [(*pack(Whq[j]), bhq[j]) for j in range(H)]
-    out = (*pack(Woq), boq)
-    acc = sum(discrete_net(int(x), hidden, out) == int(Y[i]) for i, x in enumerate(xs)) / N
-    return hidden, out, acc
-
-# ---- emit the network as NEUR code and run it on neural_rv32 ---------------
-def li(a, reg, v):
-    v &= 0xFFFFFFFF
-    hi = (v + 0x800) >> 12
-    lo = v - (hi << 12)
-    a.lui(reg, hi & 0xFFFFF)
-    if lo: a.addi(reg, reg, lo)
-
-def build_program(xval, hidden, out):
-    a = Asm()
-    li(a, 1, xval)                 # x1 = input byte
-    li(a, 2, 0)                    # x2 = packed hidden
-    for j, (p, n, b) in enumerate(hidden):
-        li(a, 4, p | (n << 8) | ((b & 0x1F) << 16))   # weight word
-        a.neur(3, 1, 4)            # x3 = hidden neuron j
-        if j: a.slli(2, 2, 1)
-        a.or_(2, 2, 3)             # pack MSB-first (neuron 0 -> bit H-1)
-    p, n, b = out
-    H = len(hidden)
-    def remap(mask):               # match the MSB-first hidden packing
-        r = 0
-        for j in range(H):
-            if (mask >> j) & 1: r |= 1 << (H - 1 - j)
-        return r
-    li(a, 4, remap(p) | (remap(n) << 8) | ((b & 0x1F) << 16))
-    a.neur(5, 2, 4)                # x5 = output
-    a.ecall()
-    return a.assemble()
-
-def run_cpu(cpu, xval, hidden, out):
-    mem = build_program(xval, hidden, out)
-    ts = rv_state(mem)
-    ts["_mem_bits"] = torch.tensor([int_to_bits(b, 8) for b in ts["mem"]], dtype=torch.float32)
-    cyc = 0
-    while not ts["halted"] and cyc < 200:
-        ts = cpu.step(ts); cyc += 1
-    return ts["regs"][5], cyc
-
-
-def parity(x, nbits=8): return bin(x & ((1 << nbits) - 1)).count("1") & 1
-def band(x): return int(3 <= bin(x).count("1") <= 5)      # non-monotone in popcount
-
-def learn(fn, H, seeds, epochs):
-    best, t0, used = None, time.perf_counter(), 0
-    for seed in range(seeds):
-        used = seed
-        hidden, out, acc = train(fn, H=H, seed=seed, epochs=epochs)
-        if best is None or acc > best[2]:
-            best = (hidden, out, acc)
-        if acc == 1.0:
-            break
-    hidden, out, acc = best
-    print(f"  trained 8->{H}->1 ternary MLP by annealed-sigmoid SGD: {acc*100:.1f}% "
-          f"exact over all 256 inputs  ({time.perf_counter()-t0:.0f}s, seed {used}); "
-          f"weights all in {{-1,0,+1}}")
-    return hidden, out, acc
-
-def deploy_check(cpu, fn, hidden, out, sample):
-    t0, cpu_vs_net, cpu_vs_true, rows = time.perf_counter(), 0, 0, []
-    for x in sample:
-        y_cpu, _ = run_cpu(cpu, x, hidden, out)
-        cpu_vs_net += (y_cpu == discrete_net(x, hidden, out))
-        cpu_vs_true += (y_cpu == fn(x))
-        rows.append((x, y_cpu, fn(x)))
-    print(f"    NEUR execution on neural_rv32: CPU == reference net on "
-          f"{cpu_vs_net}/{len(sample)} (deployment exact); CPU == truth on "
-          f"{cpu_vs_true}/{len(sample)}  ({time.perf_counter()-t0:.0f}s)")
-    return rows
-
-def compile_parity(nbits=8):        # exact thermometer construction
-    mask = (1 << nbits) - 1
-    hidden = [(mask, 0, -(k + 1)) for k in range(nbits)]     # h_k = [popcount>=k+1]
-    pos = sum(1 << j for j in range(nbits) if j % 2 == 0)    # odd thresholds
-    neg = sum(1 << j for j in range(nbits) if j % 2 == 1)    # even thresholds
-    return hidden, (pos, neg, -1)
-
-
-if __name__ == "__main__":
-    print("=" * 72)
-    print(" Neural networks running as software on the CPU that IS a neural net")
-    print("=" * 72)
-    cpu = Rv32ThresholdCPU()
-
-    print("\n[1] LEARNED by gradient descent -- popcount BAND: fire iff 3<=popcount<=5")
-    print("    (non-monotone, so no single threshold can do it; genuinely nonlinear)")
-    hidden, out, acc = learn(band, H=8, seeds=12, epochs=5000)
-    deploy_check(cpu, band, hidden, out,
-                 [0, 1, 3, 7, 15, 31, 63, 127, 255, 0b10110, 0b1111000, 0b11011011])
-    line = "".join(f"{k}:{discrete_net((1 << k) - 1, hidden, out)} " for k in range(9))
-    print(f"    net output vs popcount k:  {line.strip()}   (true band: k in 3,4,5)")
-
-    print("\n[2] COMPILED by construction -- 8-bit PARITY (XOR), the non-separable")
-    print("    function Minsky & Papert used to end the single perceptron")
-    hidden, out = compile_parity(8)
-    acc = sum(discrete_net(x, hidden, out) == parity(x) for x in range(256)) / 256
-    print(f"    thermometer net (8 hidden 'popcount>=k' + alternating output), all "
-          f"weights in {{-1,0,+1}}: {acc*100:.0f}% exact over all 256 bytes")
-    rows = deploy_check(cpu, parity, hidden, out,
-                        [0, 1, 3, 7, 15, 31, 85, 127, 128, 170, 200, 254, 255])
-    for x, yc, yt in rows:
-        print(f"      parity({x:3d}) = {yc}  (true {yt})  [{'ok' if yc==yt else 'x'}]")
-
-    print("\n  One network learned by SGD, one compiled by hand, both executed")
-    print("  instruction by instruction on a CPU whose every gate is a threshold")
-    print("  neuron. The machine running the models belongs to the models' own class.")

demos/neural_subleq8io_universal_constructor.py

@@ -1,74 +0,0 @@
-"""neural_subleq8io  --  von Neumann's universal constructor, to the byte.
-
-The one-instruction machine (186 datapath units plus 8 packed memory
-tensors) runs a 21-instruction SUBLEQ program
-that reads a description of any machine in the family off its tape and emits
-that machine's safetensors file one byte at a time. Here it fabricates
-neural_tile.safetensors on the shipped gate netlist, byte-for-byte sha-identical
-to the target, and the fabricated file is then booted: tiles reconstructed from
-its own bytes regrow the binary counter. A computer made of threshold gates
-prints a working computer, and the product runs.
-
-    python demos/neural_subleq8io_universal_constructor.py
-"""
-import os, sys, time, json, hashlib
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-os.chdir(REPO)
-from constructor8 import describe, ref_construct, GateHost
-
-
-if __name__ == "__main__":
-    target_path = os.path.join(REPO, "variants", "neural_tile.safetensors")
-    data = open(target_path, "rb").read()
-    tape = describe(data)
-    print("neural_subleq8io: the universal constructor fabricates a sibling")
-    print("=" * 60)
-    print(f"recipe compiled: {len(data)} B machine -> {len(tape)} B tape")
-
-    out_ref, n_ref = ref_construct(tape)
-    assert out_ref == data
-    print(f"reference: constructor needs {n_ref:,} instructions")
-
-    host = GateHost()
-    t0 = time.perf_counter()
-    out, n, _ = host.run(tape, max_steps=n_ref + 100)
-    dt = time.perf_counter() - t0
-    sha_out = hashlib.sha256(out).hexdigest()[:16]
-    sha_tgt = hashlib.sha256(data).hexdigest()[:16]
-    print(f"gate netlist: {n:,} instructions in {dt:.0f}s ({n / dt:.0f} instr/s), "
-          f"{len(out)} bytes emitted")
-    print(f"  sha256 fabricated={sha_out}  shipped={sha_tgt}  "
-          f"{'BYTE-IDENTICAL' if out == data else 'MISMATCH'}; "
-          f"instruction count == reference: {n == n_ref}")
-
-    # boot the fabricated machine: regrow its counter from its own bytes
-    fab = os.path.join(os.environ.get("TEMP", "."), "fabricated_neural_tile.safetensors")
-    open(fab, "wb").write(out)
-    from safetensors.torch import load_file
-    from safetensors import safe_open
-    import tile as T
-
-    t = load_file(fab)
-    with safe_open(fab, framework="pt") as f:
-        m = f.metadata()
-    gl = json.loads(m["glues"])
-    strg = {gl[i]: int(v) for i, v in enumerate(t["glue_strength"].tolist())}
-    tiles = []
-    for row, name in zip(t["tile_glues"].tolist(), json.loads(m["tile_names"])):
-        sides = [gl[i] if i >= 0 else "" for i in row]
-        tiles.append(T.Tile(N=sides[0], E=sides[1], S=sides[2], W=sides[3], name=name))
-    NB = 8
-    rows = (1 << NB) - 1
-    A, det = T.grow(tiles, T.counter_seed(NB), int(m["tau"]), strg, (0, 0, NB, rows))
-    bad = filled = 0
-    for y in range(1, rows + 1):
-        cells = [A.get((x, y)) for x in range(NB)]
-        if any(cc is None for cc in cells):
-            continue
-        filled += 1
-        v = sum((1 if cc.N == "b1" else 0) << (NB - 1 - x) for x, cc in enumerate(cells))
-        bad += (v != y)
-    print(f"boot: the fabricated file grew its counter, {filled} rows, "
-          f"row y encodes y: {'EXACT' if bad == 0 and filled == rows else f'{bad} bad'}")

demos/neural_tile_pascal_lucas.py

@@ -1,42 +0,0 @@
-"""neural_tile  --  self-assembly grows Pascal's triangle mod 2 (Lucas' theorem).
-
-The program is a set of square tiles whose binding rule is a threshold gate: a
-tile attaches at a site when the summed strength of its matching glues meets the
-temperature. With the XOR rule tile set, the crystal that grows is exactly the
-Sierpinski triangle -- cell (x,y) is filled iff the binomial C(x+y, x) is odd,
-which by Lucas' theorem is iff x AND y == 0. Every filled cell is verified
-against that arithmetic. Computation as crystal growth.
-
-    python demos/neural_tile_pascal_lucas.py
-"""
-import os, sys, time
-HERE = os.path.dirname(os.path.abspath(__file__))
-REPO = os.path.dirname(HERE)
-sys.path.insert(0, os.path.join(REPO, "src"))
-import tile as T
-
-
-if __name__ == "__main__":
-    N = 100
-    print("neural_tile: Pascal mod 2 by threshold-gated self-assembly")
-    print("=" * 60)
-    t0 = time.perf_counter()
-    ts = T.rule2_tileset(lambda w, s: w ^ s)
-    seed = T._row_col_seed([1] * (N + 1), [1] * (N + 1))
-    A, det = T.grow(ts, seed, tau=2, strength={}, bounds=(0, 0, N, N), max_tiles=200000)
-    dt = time.perf_counter() - t0
-
-    interior = [(x, y) for x in range(1, N + 1) for y in range(1, N + 1)]
-    grown = sum(1 for p in interior if p in A)
-    bad = 0
-    for (x, y) in interior:
-        v = 1 if A[(x, y)].N == "v1" else 0
-        lucas = 1 if (x & y) == 0 else 0        # C(x+y,x) odd  <=>  no carry in x+y
-        bad += (v != lucas)
-    print(f"grew {grown} rule tiles in {dt:.1f}s (directed={det}, "
-          f"{2 * N} anti-diagonals deep)")
-    print(f"tile(x,y) == [C(x+y,x) is odd] for all {len(interior)} cells: "
-          f"{'EXACT' if bad == 0 else f'{bad} MISMATCHES'}")
-    print("\ncorner of the assembly (30x30, '#' = odd binomial):")
-    for y in range(30, 0, -1):
-        print("  " + "".join("#" if A[(x, y)].N == "v1" else "." for x in range(1, 31)))

llm_integration/baseline.py

@@ -1,221 +0,0 @@
-"""
-Baseline evaluation: Vanilla SmolLM2-360M on arithmetic
-"""
-
-import torch
-import random
-import re
-from transformers import AutoModelForCausalLM, AutoTokenizer
-
-DEVICE = "cuda"
-MODEL_ID = "HuggingFaceTB/SmolLM2-360M-Instruct"
-
-SYSTEM_PROMPT = """You are a calculator. Output only the numeric answer. No words, no explanation, just digits. Examples:
-User: 5 + 3
-Assistant: 8
-User: 12 * 7
-Assistant: 84
-User: 100 > 50
-Assistant: 1
-User: 25 < 10
-Assistant: 0"""
-
-
-def load_model():
-    print(f"Loading {MODEL_ID}...")
-    tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
-    tokenizer.padding_side = "left"
-    if tokenizer.pad_token is None:
-        tokenizer.pad_token = tokenizer.eos_token
-    model = AutoModelForCausalLM.from_pretrained(
-        MODEL_ID,
-        torch_dtype=torch.float16,
-        device_map=DEVICE
-    )
-    model.eval()
-    print(f"  Loaded. Parameters: {sum(p.numel() for p in model.parameters()):,}")
-    return model, tokenizer
-
-
-def format_prompt(tokenizer, op_str):
-    messages = [
-        {"role": "system", "content": SYSTEM_PROMPT},
-        {"role": "user", "content": op_str}
-    ]
-    return tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
-
-
-def generate_batch(model, tokenizer, prompts, max_new_tokens=16):
-    inputs = tokenizer(prompts, return_tensors="pt", padding=True).to(DEVICE)
-    with torch.no_grad():
-        outputs = model.generate(
-            **inputs,
-            max_new_tokens=max_new_tokens,
-            do_sample=False,
-            pad_token_id=tokenizer.eos_token_id
-        )
-    responses = []
-    for i, output in enumerate(outputs):
-        response = tokenizer.decode(output[inputs.input_ids.shape[1]:], skip_special_tokens=True)
-        responses.append(response.strip())
-    return responses
-
-
-def extract_answer(text):
-    """Generous extraction - find any number in output"""
-    text = text.strip().lower()
-    if not text:
-        return None
-
-    # Handle Yes/No for comparisons
-    if text in ['yes', 'true', '1']:
-        return 1
-    if text in ['no', 'false', '0']:
-        return 0
-    if text.startswith('yes'):
-        return 1
-    if text.startswith('no'):
-        return 0
-
-    # Find all numbers, take the LAST one (most likely the answer)
-    numbers = re.findall(r'-?\d+', text)
-    if numbers:
-        return int(numbers[-1])
-    return None
-
-
-def ground_truth(a, b, op):
-    """Compute expected result (8-bit where applicable)"""
-    if op == 'add':
-        return (a + b) & 0xFF
-    elif op == 'sub':
-        return (a - b) & 0xFF
-    elif op == 'mul':
-        return (a * b) & 0xFF
-    elif op == 'div':
-        return a // b if b != 0 else 0
-    elif op == 'and':
-        return a & b
-    elif op == 'or':
-        return a | b
-    elif op == 'xor':
-        return a ^ b
-    elif op == 'gt':
-        return 1 if a > b else 0
-    elif op == 'lt':
-        return 1 if a < b else 0
-    elif op == 'eq':
-        return 1 if a == b else 0
-    elif op == 'ge':
-        return 1 if a >= b else 0
-    elif op == 'le':
-        return 1 if a <= b else 0
-    else:
-        raise ValueError(f"Unknown op: {op}")
-
-
-def op_to_str(a, b, op):
-    """Convert operation to natural string"""
-    symbols = {
-        'add': '+', 'sub': '-', 'mul': '*', 'div': '/',
-        'and': '&', 'or': '|', 'xor': '^',
-        'gt': '>', 'lt': '<', 'eq': '==', 'ge': '>=', 'le': '<='
-    }
-    return f"{a} {symbols[op]} {b}"
-
-
-def evaluate(model, tokenizer, n_samples=1000, batch_size=32, ops=None):
-    if ops is None:
-        ops = ['add', 'sub', 'mul', 'gt', 'lt', 'eq']
-
-    results = {op: {'correct': 0, 'total': 0} for op in ops}
-    all_correct = 0
-    all_total = 0
-
-    samples = []
-    for _ in range(n_samples):
-        a = random.randint(0, 255)
-        b = random.randint(0, 255)
-        if 'div' in ops and random.random() < 0.1:
-            op = 'div'
-            b = random.randint(1, 255)  # avoid div by zero
-        else:
-            op = random.choice([o for o in ops if o != 'div'])
-        samples.append((a, b, op))
-
-    print(f"\nEvaluating {n_samples} samples (batch_size={batch_size})...")
-
-    for batch_start in range(0, n_samples, batch_size):
-        batch = samples[batch_start:batch_start + batch_size]
-        prompts = [format_prompt(tokenizer, op_to_str(a, b, op)) for a, b, op in batch]
-        responses = generate_batch(model, tokenizer, prompts)
-
-        for (a, b, op), response in zip(batch, responses):
-            expected = ground_truth(a, b, op)
-            extracted = extract_answer(response)
-
-            correct = (extracted == expected)
-            results[op]['total'] += 1
-            all_total += 1
-            if correct:
-                results[op]['correct'] += 1
-                all_correct += 1
-
-        if (batch_start + batch_size) % 200 == 0 or batch_start + batch_size >= n_samples:
-            pct = 100 * all_correct / all_total
-            print(f"  Progress: {min(batch_start + batch_size, n_samples)}/{n_samples} | Accuracy: {pct:.2f}%")
-
-    return results, all_correct, all_total
-
-
-def main():
-    random.seed(42)
-    torch.manual_seed(42)
-
-    model, tokenizer = load_model()
-
-    # Quick sanity check
-    print("\nSanity check (5 examples):")
-    test_cases = [
-        ("5 + 3", 8),
-        ("100 - 37", 63),
-        ("12 * 11", 132),
-        ("50 > 30", 1),
-        ("25 < 10", 0),
-    ]
-    prompts = [format_prompt(tokenizer, q) for q, _ in test_cases]
-    responses = generate_batch(model, tokenizer, prompts)
-    for (q, expected), response in zip(test_cases, responses):
-        extracted = extract_answer(response)
-        status = "OK" if extracted == expected else "FAIL"
-        print(f"  {q} = {expected} | Model: '{response}' -> {extracted} [{status}]")
-
-    # Full evaluation
-    print("\n" + "=" * 60)
-    print(" BASELINE EVALUATION")
-    print("=" * 60)
-
-    ops = ['add', 'sub', 'mul', 'gt', 'lt', 'eq']
-    results, correct, total = evaluate(model, tokenizer, n_samples=2000, batch_size=64, ops=ops)
-
-    print("\n" + "=" * 60)
-    print(" RESULTS BY OPERATION")
-    print("=" * 60)
-    for op in ops:
-        r = results[op]
-        pct = 100 * r['correct'] / r['total'] if r['total'] > 0 else 0
-        print(f"  {op:6}: {r['correct']:4}/{r['total']:4} ({pct:6.2f}%)")
-
-    print("\n" + "=" * 60)
-    print(" OVERALL")
-    print("=" * 60)
-    fitness = correct / total
-    print(f"  Correct: {correct}/{total}")
-    print(f"  Fitness: {fitness:.4f} ({100*fitness:.2f}%)")
-    print("=" * 60)
-
-    return fitness
-
-
-if __name__ == "__main__":
-    main()

llm_integration/circuits.py

@@ -1,320 +0,0 @@
-"""
-Frozen threshold circuit wrapper for LLM integration.
-Loads safetensors and provides differentiable-compatible execution.
-"""
-
-import torch
-import torch.nn as nn
-from safetensors import safe_open
-from typing import Dict, Tuple
-
-MODEL_PATH = "D:/8bit-threshold-computer/neural_computer.safetensors"
-
-
-def heaviside(x: torch.Tensor) -> torch.Tensor:
-    """Standard Heaviside step function."""
-    return (x >= 0).float()
-
-
-class HeavisideSTE(torch.autograd.Function):
-    """Heaviside with straight-through estimator for gradients."""
-    @staticmethod
-    def forward(ctx, x):
-        return (x >= 0).float()
-
-    @staticmethod
-    def backward(ctx, grad_output):
-        return grad_output
-
-
-def heaviside_ste(x: torch.Tensor) -> torch.Tensor:
-    """Heaviside with STE gradient."""
-    return HeavisideSTE.apply(x)
-
-
-class FrozenThresholdCircuits(nn.Module):
-    """
-    Wrapper for frozen threshold logic circuits.
-    All weights are frozen - no gradients flow through circuit internals.
-    Gradients flow through inputs/outputs via STE.
-    """
-
-    def __init__(self, model_path: str = MODEL_PATH, device: str = 'cuda'):
-        super().__init__()
-        self.device = device
-        self.weights = {}
-        self._load_weights(model_path)
-
-    def _load_weights(self, path: str):
-        """Load weights from safetensors file."""
-        with safe_open(path, framework='pt') as f:
-            for name in f.keys():
-                tensor = f.get_tensor(name).to(self.device).float()
-                self.weights[name] = tensor
-
-    def _gate(self, inputs: torch.Tensor, weight: torch.Tensor, bias: torch.Tensor) -> torch.Tensor:
-        """Execute single threshold gate with STE."""
-        weight = weight.view(-1)
-        bias = bias.view(-1)
-        pre_activation = (inputs * weight).sum(dim=-1) + bias
-        return heaviside_ste(pre_activation)
-
-    def _xor(self, a: torch.Tensor, b: torch.Tensor, prefix: str) -> torch.Tensor:
-        """XOR via OR-NAND-AND pattern (2 layers)."""
-        inputs = torch.stack([a, b], dim=-1)
-
-        w_or = self.weights[f'{prefix}.layer1.or.weight']
-        b_or = self.weights[f'{prefix}.layer1.or.bias']
-        w_nand = self.weights[f'{prefix}.layer1.nand.weight']
-        b_nand = self.weights[f'{prefix}.layer1.nand.bias']
-
-        h_or = self._gate(inputs, w_or, b_or)
-        h_nand = self._gate(inputs, w_nand, b_nand)
-
-        hidden = torch.stack([h_or, h_nand], dim=-1)
-        w2 = self.weights[f'{prefix}.layer2.weight']
-        b2 = self.weights[f'{prefix}.layer2.bias']
-
-        return self._gate(hidden, w2, b2)
-
-    def _full_adder(self, a: torch.Tensor, b: torch.Tensor, cin: torch.Tensor,
-                    prefix: str) -> Tuple[torch.Tensor, torch.Tensor]:
-        """Full adder: sum and carry out."""
-        ha1_sum = self._xor(a, b, f'{prefix}.ha1.sum')
-
-        inp_carry1 = torch.stack([a, b], dim=-1)
-        w_c1 = self.weights[f'{prefix}.ha1.carry.weight']
-        b_c1 = self.weights[f'{prefix}.ha1.carry.bias']
-        ha1_carry = self._gate(inp_carry1, w_c1, b_c1)
-
-        ha2_sum = self._xor(ha1_sum, cin, f'{prefix}.ha2.sum')
-
-        inp_carry2 = torch.stack([ha1_sum, cin], dim=-1)
-        w_c2 = self.weights[f'{prefix}.ha2.carry.weight']
-        b_c2 = self.weights[f'{prefix}.ha2.carry.bias']
-        ha2_carry = self._gate(inp_carry2, w_c2, b_c2)
-
-        inp_cout = torch.stack([ha1_carry, ha2_carry], dim=-1)
-        w_cout = self.weights[f'{prefix}.carry_or.weight']
-        b_cout = self.weights[f'{prefix}.carry_or.bias']
-        cout = self._gate(inp_cout, w_cout, b_cout)
-
-        return ha2_sum, cout
-
-    def add_8bit(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
-        """
-        8-bit ripple carry addition.
-
-        Args:
-            a_bits: [batch, 8] MSB-first
-            b_bits: [batch, 8] MSB-first
-
-        Returns:
-            result_bits: [batch, 8] MSB-first
-            carry_out: [batch] final carry
-        """
-        batch_size = a_bits.shape[0]
-        carry = torch.zeros(batch_size, device=self.device)
-        result_bits = []
-
-        for bit in range(8):
-            bit_idx = 7 - bit
-            s, carry = self._full_adder(
-                a_bits[:, bit_idx],
-                b_bits[:, bit_idx],
-                carry,
-                f'arithmetic.ripplecarry8bit.fa{bit}'
-            )
-            result_bits.insert(0, s)
-
-        result = torch.stack(result_bits, dim=1)
-        return result, carry
-
-    def sub_8bit(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
-        """
-        8-bit subtraction via two's complement: A - B = A + (~B) + 1
-
-        Args:
-            a_bits: [batch, 8] MSB-first
-            b_bits: [batch, 8] MSB-first
-
-        Returns:
-            result_bits: [batch, 8] MSB-first
-            borrow_out: [batch] (inverted carry)
-        """
-        b_inv = 1.0 - b_bits
-        batch_size = a_bits.shape[0]
-        carry = torch.ones(batch_size, device=self.device)
-        result_bits = []
-
-        for bit in range(8):
-            bit_idx = 7 - bit
-            s, carry = self._full_adder(
-                a_bits[:, bit_idx],
-                b_inv[:, bit_idx],
-                carry,
-                f'arithmetic.ripplecarry8bit.fa{bit}'
-            )
-            result_bits.insert(0, s)
-
-        result = torch.stack(result_bits, dim=1)
-        borrow = 1.0 - carry
-        return result, borrow
-
-    def mul_8bit(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> torch.Tensor:
-        """
-        8-bit multiplication via shift-add (software implementation using adder circuits).
-        Only keeps low 8 bits of result (matches 8-bit wrap behavior).
-
-        Args:
-            a_bits: [batch, 8] MSB-first
-            b_bits: [batch, 8] MSB-first
-
-        Returns:
-            result_bits: [batch, 8] MSB-first (low 8 bits of product)
-        """
-        batch_size = a_bits.shape[0]
-
-        acc = torch.zeros(batch_size, 8, device=self.device)
-
-        for i in range(8):
-            b_bit = b_bits[:, 7 - i]
-            pp = a_bits * b_bit.unsqueeze(1)
-
-            shifted_pp = torch.zeros(batch_size, 8, device=self.device)
-            for j in range(8):
-                dst_idx = j + i
-                if dst_idx < 8:
-                    shifted_pp[:, 7 - dst_idx] = pp[:, 7 - j]
-
-            acc, _ = self.add_8bit(acc, shifted_pp)
-
-        return acc
-
-    def compare_gt(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> torch.Tensor:
-        """A > B comparison."""
-        inputs = torch.cat([a_bits, b_bits], dim=-1)
-        w = self.weights['arithmetic.greaterthan8bit.weight'].view(-1)
-        b = self.weights['arithmetic.greaterthan8bit.bias'].view(-1)
-        return heaviside_ste((inputs * w).sum(dim=-1) + b)
-
-    def compare_lt(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> torch.Tensor:
-        """A < B comparison."""
-        inputs = torch.cat([a_bits, b_bits], dim=-1)
-        w = self.weights['arithmetic.lessthan8bit.weight'].view(-1)
-        b = self.weights['arithmetic.lessthan8bit.bias'].view(-1)
-        return heaviside_ste((inputs * w).sum(dim=-1) + b)
-
-    def compare_eq(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> torch.Tensor:
-        """A == B comparison (two-layer)."""
-        inputs = torch.cat([a_bits, b_bits], dim=-1)
-        prefix = 'arithmetic.equality8bit'
-
-        w_geq = self.weights[f'{prefix}.layer1.geq.weight'].view(-1)
-        b_geq = self.weights[f'{prefix}.layer1.geq.bias'].view(-1)
-        w_leq = self.weights[f'{prefix}.layer1.leq.weight'].view(-1)
-        b_leq = self.weights[f'{prefix}.layer1.leq.bias'].view(-1)
-
-        h_geq = heaviside_ste((inputs * w_geq).sum(dim=-1) + b_geq)
-        h_leq = heaviside_ste((inputs * w_leq).sum(dim=-1) + b_leq)
-
-        hidden = torch.stack([h_geq, h_leq], dim=-1)
-        w2 = self.weights[f'{prefix}.layer2.weight'].view(-1)
-        b2 = self.weights[f'{prefix}.layer2.bias'].view(-1)
-
-        return heaviside_ste((hidden * w2).sum(dim=-1) + b2)
-
-    def forward(self, a_bits: torch.Tensor, b_bits: torch.Tensor,
-                op_onehot: torch.Tensor) -> torch.Tensor:
-        """
-        Execute operation based on one-hot selector.
-        Uses soft routing during training for gradient flow.
-
-        Args:
-            a_bits: [batch, 8] operand A
-            b_bits: [batch, 8] operand B
-            op_onehot: [batch, 6] one-hot operation selector
-                       [add, sub, mul, gt, lt, eq]
-
-        Returns:
-            result_bits: [batch, 8] result (comparisons in bit 7, rest zeros)
-        """
-        batch_size = a_bits.shape[0]
-
-        add_result, _ = self.add_8bit(a_bits, b_bits)
-        sub_result, _ = self.sub_8bit(a_bits, b_bits)
-        mul_result = self.mul_8bit(a_bits, b_bits)
-
-        gt_result = self.compare_gt(a_bits, b_bits)
-        lt_result = self.compare_lt(a_bits, b_bits)
-        eq_result = self.compare_eq(a_bits, b_bits)
-
-        cmp_expanded = torch.zeros(batch_size, 8, device=self.device)
-
-        gt_expanded = cmp_expanded.clone()
-        gt_expanded[:, 7] = gt_result
-
-        lt_expanded = cmp_expanded.clone()
-        lt_expanded[:, 7] = lt_result
-
-        eq_expanded = cmp_expanded.clone()
-        eq_expanded[:, 7] = eq_result
-
-        results = torch.stack([
-            add_result,
-            sub_result,
-            mul_result,
-            gt_expanded,
-            lt_expanded,
-            eq_expanded
-        ], dim=1)
-
-        op_weights = op_onehot.unsqueeze(-1)
-        output = (results * op_weights).sum(dim=1)
-
-        return output
-
-
-if __name__ == "__main__":
-    print("Testing frozen circuits...")
-
-    circuits = FrozenThresholdCircuits(device='cuda')
-    print(f"Loaded {len(circuits.weights)} tensors")
-
-    a = torch.tensor([[0, 0, 0, 0, 0, 1, 0, 1]], device='cuda', dtype=torch.float32)
-    b = torch.tensor([[0, 0, 0, 0, 0, 0, 1, 1]], device='cuda', dtype=torch.float32)
-
-    result, carry = circuits.add_8bit(a, b)
-    val = sum(int(result[0, i].item()) << (7 - i) for i in range(8))
-    print(f"5 + 3 = {val} (expected 8)")
-
-    a = torch.tensor([[0, 1, 1, 0, 0, 1, 0, 0]], device='cuda', dtype=torch.float32)
-    b = torch.tensor([[0, 0, 1, 0, 0, 1, 0, 1]], device='cuda', dtype=torch.float32)
-    result, _ = circuits.sub_8bit(a, b)
-    val = sum(int(result[0, i].item()) << (7 - i) for i in range(8))
-    print(f"100 - 37 = {val} (expected 63)")
-
-    a = torch.tensor([[0, 0, 0, 0, 1, 1, 0, 0]], device='cuda', dtype=torch.float32)
-    b = torch.tensor([[0, 0, 0, 0, 1, 0, 1, 1]], device='cuda', dtype=torch.float32)
-    result = circuits.mul_8bit(a, b)
-    val = sum(int(result[0, i].item()) << (7 - i) for i in range(8))
-    print(f"12 * 11 = {val} (expected 132)")
-
-    a = torch.tensor([[0, 0, 1, 1, 0, 0, 1, 0]], device='cuda', dtype=torch.float32)
-    b = torch.tensor([[0, 0, 0, 1, 1, 1, 1, 0]], device='cuda', dtype=torch.float32)
-    gt = circuits.compare_gt(a, b)
-    lt = circuits.compare_lt(a, b)
-    eq = circuits.compare_eq(a, b)
-    print(f"50 > 30: {int(gt[0].item())} (expected 1)")
-    print(f"50 < 30: {int(lt[0].item())} (expected 0)")
-    print(f"50 == 30: {int(eq[0].item())} (expected 0)")
-
-    print("\nTesting batched forward...")
-    batch_a = torch.randint(0, 2, (16, 8), device='cuda', dtype=torch.float32)
-    batch_b = torch.randint(0, 2, (16, 8), device='cuda', dtype=torch.float32)
-    op = torch.zeros(16, 6, device='cuda')
-    op[:, 0] = 1.0
-
-    result = circuits(batch_a, batch_b, op)
-    print(f"Batch output shape: {result.shape}")
-    print("Done.")

llm_integration/fitness.py

@@ -1,218 +0,0 @@
-"""
-Shared fitness function for threshold circuit LLM integration.
-Randomized tests, no answer supervision - fitness IS the training signal.
-"""
-
-import torch
-import random
-from typing import Callable, Dict, Tuple, List
-
-OPERATIONS = ['add', 'sub', 'mul', 'gt', 'lt', 'eq']
-
-def ground_truth(a: int, b: int, op: str) -> int:
-    """Compute expected result (8-bit arithmetic)."""
-    if op == 'add':
-        return (a + b) & 0xFF
-    elif op == 'sub':
-        return (a - b) & 0xFF
-    elif op == 'mul':
-        return (a * b) & 0xFF
-    elif op == 'gt':
-        return 1 if a > b else 0
-    elif op == 'lt':
-        return 1 if a < b else 0
-    elif op == 'eq':
-        return 1 if a == b else 0
-    else:
-        raise ValueError(f"Unknown op: {op}")
-
-
-def int_to_bits(val: int, n_bits: int = 8) -> torch.Tensor:
-    """Convert integer to bit tensor (MSB first)."""
-    bits = torch.zeros(n_bits)
-    for i in range(n_bits):
-        bits[n_bits - 1 - i] = (val >> i) & 1
-    return bits
-
-
-def bits_to_int(bits: torch.Tensor) -> int:
-    """Convert bit tensor to integer (MSB first)."""
-    val = 0
-    n_bits = bits.shape[-1]
-    for i in range(n_bits):
-        val += int(bits[..., i].item()) << (n_bits - 1 - i)
-    return val
-
-
-def op_to_idx(op: str) -> int:
-    """Convert operation string to index."""
-    return OPERATIONS.index(op)
-
-
-def idx_to_op(idx: int) -> str:
-    """Convert index to operation string."""
-    return OPERATIONS[idx]
-
-
-def generate_batch(batch_size: int, device: str = 'cuda') -> Dict[str, torch.Tensor]:
-    """
-    Generate a batch of random arithmetic problems.
-
-    Returns:
-        Dict with:
-            'a': [batch_size] int tensor of first operands
-            'b': [batch_size] int tensor of second operands
-            'op': [batch_size] int tensor of operation indices
-            'a_bits': [batch_size, 8] bit tensor
-            'b_bits': [batch_size, 8] bit tensor
-            'op_onehot': [batch_size, 6] one-hot operation tensor
-            'expected': [batch_size] int tensor of expected results
-            'expected_bits': [batch_size, 8] bit tensor of expected results
-    """
-    a_vals = torch.randint(0, 256, (batch_size,), device=device)
-    b_vals = torch.randint(0, 256, (batch_size,), device=device)
-    op_indices = torch.randint(0, len(OPERATIONS), (batch_size,), device=device)
-
-    a_bits = torch.zeros(batch_size, 8, device=device)
-    b_bits = torch.zeros(batch_size, 8, device=device)
-    for i in range(8):
-        a_bits[:, 7-i] = (a_vals >> i) & 1
-        b_bits[:, 7-i] = (b_vals >> i) & 1
-
-    op_onehot = torch.zeros(batch_size, len(OPERATIONS), device=device)
-    op_onehot.scatter_(1, op_indices.unsqueeze(1), 1.0)
-
-    expected = torch.zeros(batch_size, dtype=torch.long, device=device)
-    for i in range(batch_size):
-        a, b, op_idx = a_vals[i].item(), b_vals[i].item(), op_indices[i].item()
-        expected[i] = ground_truth(a, b, idx_to_op(op_idx))
-
-    expected_bits = torch.zeros(batch_size, 8, device=device)
-    for i in range(8):
-        expected_bits[:, 7-i] = (expected >> i) & 1
-
-    return {
-        'a': a_vals,
-        'b': b_vals,
-        'op': op_indices,
-        'a_bits': a_bits.float(),
-        'b_bits': b_bits.float(),
-        'op_onehot': op_onehot.float(),
-        'expected': expected,
-        'expected_bits': expected_bits.float(),
-    }
-
-
-def compute_fitness(
-    model_fn: Callable[[torch.Tensor, torch.Tensor, torch.Tensor], torch.Tensor],
-    n_samples: int = 10000,
-    batch_size: int = 256,
-    device: str = 'cuda',
-    return_details: bool = False
-) -> float | Tuple[float, Dict]:
-    """
-    Compute fitness score for a model.
-
-    Args:
-        model_fn: Function that takes (a_bits, b_bits, op_onehot) and returns result_bits
-        n_samples: Number of test cases
-        batch_size: Batch size for evaluation
-        device: Device to run on
-        return_details: If True, return per-operation breakdown
-
-    Returns:
-        Fitness score in [0, 1], optionally with details dict
-    """
-    correct = 0
-    total = 0
-    op_correct = {op: 0 for op in OPERATIONS}
-    op_total = {op: 0 for op in OPERATIONS}
-
-    for _ in range(0, n_samples, batch_size):
-        actual_batch = min(batch_size, n_samples - total)
-        batch = generate_batch(actual_batch, device)
-
-        with torch.no_grad():
-            pred_bits = model_fn(batch['a_bits'], batch['b_bits'], batch['op_onehot'])
-
-        pred_bits_binary = (pred_bits > 0.5).float()
-
-        for i in range(actual_batch):
-            pred_val = 0
-            for j in range(8):
-                pred_val += int(pred_bits_binary[i, j].item()) << (7 - j)
-
-            expected_val = batch['expected'][i].item()
-            op_name = idx_to_op(batch['op'][i].item())
-
-            op_total[op_name] += 1
-            total += 1
-
-            if pred_val == expected_val:
-                correct += 1
-                op_correct[op_name] += 1
-
-    fitness = correct / total if total > 0 else 0.0
-
-    if return_details:
-        details = {
-            'correct': correct,
-            'total': total,
-            'by_op': {
-                op: {
-                    'correct': op_correct[op],
-                    'total': op_total[op],
-                    'accuracy': op_correct[op] / op_total[op] if op_total[op] > 0 else 0.0
-                }
-                for op in OPERATIONS
-            }
-        }
-        return fitness, details
-
-    return fitness
-
-
-def compute_bit_accuracy(pred_bits: torch.Tensor, expected_bits: torch.Tensor) -> float:
-    """Compute per-bit accuracy (for gradient signal analysis)."""
-    pred_binary = (pred_bits > 0.5).float()
-    return (pred_binary == expected_bits).float().mean().item()
-
-
-def compute_loss(pred_bits: torch.Tensor, expected_bits: torch.Tensor) -> torch.Tensor:
-    """Binary cross-entropy loss on output bits."""
-    pred_clamped = pred_bits.clamp(1e-7, 1 - 1e-7)
-    return -((expected_bits * torch.log(pred_clamped) +
-              (1 - expected_bits) * torch.log(1 - pred_clamped))).mean()
-
-
-if __name__ == "__main__":
-    print("Testing fitness module...")
-
-    batch = generate_batch(8, 'cpu')
-    print(f"\nSample batch:")
-    for i in range(4):
-        a, b = batch['a'][i].item(), batch['b'][i].item()
-        op = idx_to_op(batch['op'][i].item())
-        expected = batch['expected'][i].item()
-        print(f"  {a} {op} {b} = {expected}")
-
-    def random_model(a_bits, b_bits, op_onehot):
-        return torch.rand(a_bits.shape[0], 8, device=a_bits.device)
-
-    fitness = compute_fitness(random_model, n_samples=1000, batch_size=100, device='cpu')
-    print(f"\nRandom model fitness: {fitness:.4f} (expected ~0.004 for 8-bit)")
-
-    def perfect_model(a_bits, b_bits, op_onehot):
-        batch_size = a_bits.shape[0]
-        results = torch.zeros(batch_size, 8, device=a_bits.device)
-        for i in range(batch_size):
-            a = sum(int(a_bits[i, j].item()) << (7-j) for j in range(8))
-            b = sum(int(b_bits[i, j].item()) << (7-j) for j in range(8))
-            op_idx = op_onehot[i].argmax().item()
-            result = ground_truth(a, b, idx_to_op(op_idx))
-            for j in range(8):
-                results[i, 7-j] = (result >> j) & 1
-        return results
-
-    fitness = compute_fitness(perfect_model, n_samples=1000, batch_size=100, device='cpu')
-    print(f"Perfect model fitness: {fitness:.4f} (expected 1.0)")

llm_integration/{model.py → llm.py}

@@ -1,24 +1,402 @@
-"""
-Trainable interface layers for frozen threshold circuits.
-BitEncoder, OpRouter, BitDecoder wrap the frozen circuits.
-HiddenStateExtractor and AugmentedArithmeticModel for LLM integration.
-"""
+"""Frozen threshold circuits inside SmolLM2: the circuits, the fitness, the interface, training, baseline."""
+import argparse
+import os
+import random
+import re
+import sys
+import time
+from typing import Dict, Tuple, Callable, List
 
 import torch
 import torch.nn as nn
 import torch.nn.functional as F
-from circuits import FrozenThresholdCircuits, heaviside_ste
+import torch.optim as optim
+from safetensors import safe_open
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+TRAINED = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'trained')
+
+
+MODEL_PATH = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'neural_computer.safetensors')
+
+
+def heaviside(x: torch.Tensor) -> torch.Tensor:
+    """Standard Heaviside step function."""
+    return (x >= 0).float()
+
+
+class HeavisideSTE(torch.autograd.Function):
+    """Heaviside with straight-through estimator for gradients."""
+    @staticmethod
+    def forward(ctx, x):
+        return (x >= 0).float()
+
+    @staticmethod
+    def backward(ctx, grad_output):
+        return grad_output
+
+
+def heaviside_ste(x: torch.Tensor) -> torch.Tensor:
+    """Heaviside with STE gradient."""
+    return HeavisideSTE.apply(x)
+
+
+class FrozenThresholdCircuits(nn.Module):
+    """Wrapper for frozen threshold logic circuits."""
+
+    def __init__(self, model_path: str = MODEL_PATH, device: str = 'cuda'):
+        super().__init__()
+        self.device = device
+        self.weights = {}
+        self._load_weights(model_path)
+
+    def _load_weights(self, path: str):
+        """Load weights from safetensors file."""
+        with safe_open(path, framework='pt') as f:
+            for name in f.keys():
+                tensor = f.get_tensor(name).to(self.device).float()
+                self.weights[name] = tensor
+
+    def _gate(self, inputs: torch.Tensor, weight: torch.Tensor, bias: torch.Tensor) -> torch.Tensor:
+        """Execute single threshold gate with STE."""
+        weight = weight.view(-1)
+        bias = bias.view(-1)
+        pre_activation = (inputs * weight).sum(dim=-1) + bias
+        return heaviside_ste(pre_activation)
+
+    def _xor(self, a: torch.Tensor, b: torch.Tensor, prefix: str) -> torch.Tensor:
+        """XOR via OR-NAND-AND pattern (2 layers)."""
+        inputs = torch.stack([a, b], dim=-1)
+
+        w_or = self.weights[f'{prefix}.layer1.or.weight']
+        b_or = self.weights[f'{prefix}.layer1.or.bias']
+        w_nand = self.weights[f'{prefix}.layer1.nand.weight']
+        b_nand = self.weights[f'{prefix}.layer1.nand.bias']
+
+        h_or = self._gate(inputs, w_or, b_or)
+        h_nand = self._gate(inputs, w_nand, b_nand)
+
+        hidden = torch.stack([h_or, h_nand], dim=-1)
+        w2 = self.weights[f'{prefix}.layer2.weight']
+        b2 = self.weights[f'{prefix}.layer2.bias']
+
+        return self._gate(hidden, w2, b2)
+
+    def _full_adder(self, a: torch.Tensor, b: torch.Tensor, cin: torch.Tensor,
+                    prefix: str) -> Tuple[torch.Tensor, torch.Tensor]:
+        """Full adder: sum and carry out."""
+        ha1_sum = self._xor(a, b, f'{prefix}.ha1.sum')
+
+        inp_carry1 = torch.stack([a, b], dim=-1)
+        w_c1 = self.weights[f'{prefix}.ha1.carry.weight']
+        b_c1 = self.weights[f'{prefix}.ha1.carry.bias']
+        ha1_carry = self._gate(inp_carry1, w_c1, b_c1)
+
+        ha2_sum = self._xor(ha1_sum, cin, f'{prefix}.ha2.sum')
+
+        inp_carry2 = torch.stack([ha1_sum, cin], dim=-1)
+        w_c2 = self.weights[f'{prefix}.ha2.carry.weight']
+        b_c2 = self.weights[f'{prefix}.ha2.carry.bias']
+        ha2_carry = self._gate(inp_carry2, w_c2, b_c2)
+
+        inp_cout = torch.stack([ha1_carry, ha2_carry], dim=-1)
+        w_cout = self.weights[f'{prefix}.carry_or.weight']
+        b_cout = self.weights[f'{prefix}.carry_or.bias']
+        cout = self._gate(inp_cout, w_cout, b_cout)
+
+        return ha2_sum, cout
+
+    def add_8bit(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
+        """8-bit ripple carry addition."""
+        batch_size = a_bits.shape[0]
+        carry = torch.zeros(batch_size, device=self.device)
+        result_bits = []
+
+        for bit in range(8):
+            bit_idx = 7 - bit
+            s, carry = self._full_adder(
+                a_bits[:, bit_idx],
+                b_bits[:, bit_idx],
+                carry,
+                f'arithmetic.ripplecarry8bit.fa{bit}'
+            )
+            result_bits.insert(0, s)
+
+        result = torch.stack(result_bits, dim=1)
+        return result, carry
+
+    def sub_8bit(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
+        """8-bit subtraction by two's complement, A - B = A + ~B + 1."""
+        b_inv = 1.0 - b_bits
+        batch_size = a_bits.shape[0]
+        carry = torch.ones(batch_size, device=self.device)
+        result_bits = []
+
+        for bit in range(8):
+            bit_idx = 7 - bit
+            s, carry = self._full_adder(
+                a_bits[:, bit_idx],
+                b_inv[:, bit_idx],
+                carry,
+                f'arithmetic.ripplecarry8bit.fa{bit}'
+            )
+            result_bits.insert(0, s)
+
+        result = torch.stack(result_bits, dim=1)
+        borrow = 1.0 - carry
+        return result, borrow
+
+    def mul_8bit(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> torch.Tensor:
+        """8-bit multiplication via shift-add (software implementation using adder circuits)."""
+        batch_size = a_bits.shape[0]
+
+        acc = torch.zeros(batch_size, 8, device=self.device)
+
+        for i in range(8):
+            b_bit = b_bits[:, 7 - i]
+            pp = a_bits * b_bit.unsqueeze(1)
+
+            shifted_pp = torch.zeros(batch_size, 8, device=self.device)
+            for j in range(8):
+                dst_idx = j + i
+                if dst_idx < 8:
+                    shifted_pp[:, 7 - dst_idx] = pp[:, 7 - j]
+
+            acc, _ = self.add_8bit(acc, shifted_pp)
+
+        return acc
+
+    def compare_gt(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> torch.Tensor:
+        """A > B comparison."""
+        inputs = torch.cat([a_bits, b_bits], dim=-1)
+        w = self.weights['arithmetic.greaterthan8bit.weight'].view(-1)
+        b = self.weights['arithmetic.greaterthan8bit.bias'].view(-1)
+        return heaviside_ste((inputs * w).sum(dim=-1) + b)
+
+    def compare_lt(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> torch.Tensor:
+        """A < B comparison."""
+        inputs = torch.cat([a_bits, b_bits], dim=-1)
+        w = self.weights['arithmetic.lessthan8bit.weight'].view(-1)
+        b = self.weights['arithmetic.lessthan8bit.bias'].view(-1)
+        return heaviside_ste((inputs * w).sum(dim=-1) + b)
+
+    def compare_eq(self, a_bits: torch.Tensor, b_bits: torch.Tensor) -> torch.Tensor:
+        """A == B comparison (two-layer)."""
+        inputs = torch.cat([a_bits, b_bits], dim=-1)
+        prefix = 'arithmetic.equality8bit'
+
+        w_geq = self.weights[f'{prefix}.layer1.geq.weight'].view(-1)
+        b_geq = self.weights[f'{prefix}.layer1.geq.bias'].view(-1)
+        w_leq = self.weights[f'{prefix}.layer1.leq.weight'].view(-1)
+        b_leq = self.weights[f'{prefix}.layer1.leq.bias'].view(-1)
+
+        h_geq = heaviside_ste((inputs * w_geq).sum(dim=-1) + b_geq)
+        h_leq = heaviside_ste((inputs * w_leq).sum(dim=-1) + b_leq)
+
+        hidden = torch.stack([h_geq, h_leq], dim=-1)
+        w2 = self.weights[f'{prefix}.layer2.weight'].view(-1)
+        b2 = self.weights[f'{prefix}.layer2.bias'].view(-1)
+
+        return heaviside_ste((hidden * w2).sum(dim=-1) + b2)
+
+    def forward(self, a_bits: torch.Tensor, b_bits: torch.Tensor,
+                op_onehot: torch.Tensor) -> torch.Tensor:
+        """Execute operation based on one-hot selector."""
+        batch_size = a_bits.shape[0]
+
+        add_result, _ = self.add_8bit(a_bits, b_bits)
+        sub_result, _ = self.sub_8bit(a_bits, b_bits)
+        mul_result = self.mul_8bit(a_bits, b_bits)
+
+        gt_result = self.compare_gt(a_bits, b_bits)
+        lt_result = self.compare_lt(a_bits, b_bits)
+        eq_result = self.compare_eq(a_bits, b_bits)
+
+        cmp_expanded = torch.zeros(batch_size, 8, device=self.device)
+
+        gt_expanded = cmp_expanded.clone()
+        gt_expanded[:, 7] = gt_result
+
+        lt_expanded = cmp_expanded.clone()
+        lt_expanded[:, 7] = lt_result
+
+        eq_expanded = cmp_expanded.clone()
+        eq_expanded[:, 7] = eq_result
+
+        results = torch.stack([
+            add_result,
+            sub_result,
+            mul_result,
+            gt_expanded,
+            lt_expanded,
+            eq_expanded
+        ], dim=1)
+
+        op_weights = op_onehot.unsqueeze(-1)
+        output = (results * op_weights).sum(dim=1)
+
+        return output
 
-MODEL_ID = 'HuggingFaceTB/SmolLM2-360M-Instruct'
 OPERATIONS = ['add', 'sub', 'mul', 'gt', 'lt', 'eq']
+
+def ground_truth(a: int, b: int, op: str) -> int:
+    """Compute expected result (8-bit arithmetic)."""
+    if op == 'add':
+        return (a + b) & 0xFF
+    elif op == 'sub':
+        return (a - b) & 0xFF
+    elif op == 'mul':
+        return (a * b) & 0xFF
+    elif op == 'gt':
+        return 1 if a > b else 0
+    elif op == 'lt':
+        return 1 if a < b else 0
+    elif op == 'eq':
+        return 1 if a == b else 0
+    else:
+        raise ValueError(f"Unknown op: {op}")
+
+
+def int_to_bits(val: int, n_bits: int = 8) -> torch.Tensor:
+    """Convert integer to bit tensor (MSB first)."""
+    bits = torch.zeros(n_bits)
+    for i in range(n_bits):
+        bits[n_bits - 1 - i] = (val >> i) & 1
+    return bits
+
+
+def bits_to_int(bits: torch.Tensor) -> int:
+    """Convert bit tensor to integer (MSB first)."""
+    val = 0
+    n_bits = bits.shape[-1]
+    for i in range(n_bits):
+        val += int(bits[..., i].item()) << (n_bits - 1 - i)
+    return val
+
+
+def op_to_idx(op: str) -> int:
+    """Convert operation string to index."""
+    return OPERATIONS.index(op)
+
+
+def idx_to_op(idx: int) -> str:
+    """Convert index to operation string."""
+    return OPERATIONS[idx]
+
+
+def generate_batch(batch_size: int, device: str = 'cuda') -> Dict[str, torch.Tensor]:
+    """Generate a batch of random arithmetic problems."""
+    a_vals = torch.randint(0, 256, (batch_size,), device=device)
+    b_vals = torch.randint(0, 256, (batch_size,), device=device)
+    op_indices = torch.randint(0, len(OPERATIONS), (batch_size,), device=device)
+
+    a_bits = torch.zeros(batch_size, 8, device=device)
+    b_bits = torch.zeros(batch_size, 8, device=device)
+    for i in range(8):
+        a_bits[:, 7-i] = (a_vals >> i) & 1
+        b_bits[:, 7-i] = (b_vals >> i) & 1
+
+    op_onehot = torch.zeros(batch_size, len(OPERATIONS), device=device)
+    op_onehot.scatter_(1, op_indices.unsqueeze(1), 1.0)
+
+    expected = torch.zeros(batch_size, dtype=torch.long, device=device)
+    for i in range(batch_size):
+        a, b, op_idx = a_vals[i].item(), b_vals[i].item(), op_indices[i].item()
+        expected[i] = ground_truth(a, b, idx_to_op(op_idx))
+
+    expected_bits = torch.zeros(batch_size, 8, device=device)
+    for i in range(8):
+        expected_bits[:, 7-i] = (expected >> i) & 1
+
+    return {
+        'a': a_vals,
+        'b': b_vals,
+        'op': op_indices,
+        'a_bits': a_bits.float(),
+        'b_bits': b_bits.float(),
+        'op_onehot': op_onehot.float(),
+        'expected': expected,
+        'expected_bits': expected_bits.float(),
+    }
+
+
+def compute_fitness(
+    model_fn: Callable[[torch.Tensor, torch.Tensor, torch.Tensor], torch.Tensor],
+    n_samples: int = 10000,
+    batch_size: int = 256,
+    device: str = 'cuda',
+    return_details: bool = False
+) -> float | Tuple[float, Dict]:
+    """Compute fitness score for a model."""
+    correct = 0
+    total = 0
+    op_correct = {op: 0 for op in OPERATIONS}
+    op_total = {op: 0 for op in OPERATIONS}
+
+    for _ in range(0, n_samples, batch_size):
+        actual_batch = min(batch_size, n_samples - total)
+        batch = generate_batch(actual_batch, device)
+
+        with torch.no_grad():
+            pred_bits = model_fn(batch['a_bits'], batch['b_bits'], batch['op_onehot'])
+
+        pred_bits_binary = (pred_bits > 0.5).float()
+
+        for i in range(actual_batch):
+            pred_val = 0
+            for j in range(8):
+                pred_val += int(pred_bits_binary[i, j].item()) << (7 - j)
+
+            expected_val = batch['expected'][i].item()
+            op_name = idx_to_op(batch['op'][i].item())
+
+            op_total[op_name] += 1
+            total += 1
+
+            if pred_val == expected_val:
+                correct += 1
+                op_correct[op_name] += 1
+
+    fitness = correct / total if total > 0 else 0.0
+
+    if return_details:
+        details = {
+            'correct': correct,
+            'total': total,
+            'by_op': {
+                op: {
+                    'correct': op_correct[op],
+                    'total': op_total[op],
+                    'accuracy': op_correct[op] / op_total[op] if op_total[op] > 0 else 0.0
+                }
+                for op in OPERATIONS
+            }
+        }
+        return fitness, details
+
+    return fitness
+
+
+def compute_bit_accuracy(pred_bits: torch.Tensor, expected_bits: torch.Tensor) -> float:
+    """Compute per-bit accuracy (for gradient signal analysis)."""
+    pred_binary = (pred_bits > 0.5).float()
+    return (pred_binary == expected_bits).float().mean().item()
+
+
+def compute_loss(pred_bits: torch.Tensor, expected_bits: torch.Tensor) -> torch.Tensor:
+    """Binary cross-entropy loss on output bits."""
+    pred_clamped = pred_bits.clamp(1e-7, 1 - 1e-7)
+    return -((expected_bits * torch.log(pred_clamped) +
+              (1 - expected_bits) * torch.log(1 - pred_clamped))).mean()
+
+
+MODEL_ID = 'HuggingFaceTB/SmolLM2-360M-Instruct'
+
 OP_SYMBOLS = {'add': '+', 'sub': '-', 'mul': '*', 'gt': '>', 'lt': '<', 'eq': '=='}
 
 
 class BitEncoder(nn.Module):
-    """
-    Encodes two 8-bit operands from input representation.
-    Uses residual connection to preserve ground truth bits while allowing learned refinement.
-    """
+    """Encodes two 8-bit operands from input representation."""
 
     def __init__(self, input_dim: int = 16 + 6, hidden_dim: int = 32):
         super().__init__()
@@ -30,14 +408,7 @@ class BitEncoder(nn.Module):
         self.scale = nn.Parameter(torch.tensor(0.0))
 
     def forward(self, x: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
-        """
-        Args:
-            x: [batch, input_dim] input with first 16 dims being a_bits, b_bits
-
-        Returns:
-            a_bits: [batch, 8] first operand bits
-            b_bits: [batch, 8] second operand bits
-        """
+        """Split x, whose first 16 features are the bits of a and b, into the two operands."""
         base_bits = x[:, :16]
         refinement = self.refine(x) * torch.sigmoid(self.scale)
         bits = base_bits + refinement
@@ -49,10 +420,7 @@ class BitEncoder(nn.Module):
 
 
 class OpRouter(nn.Module):
-    """
-    Routes computation to the appropriate circuit based on input.
-    Outputs soft weights over operations for gradient flow.
-    """
+    """Routes computation to the appropriate circuit based on input."""
 
     def __init__(self, input_dim: int = 16 + 6, hidden_dim: int = 32, n_ops: int = 6):
         super().__init__()
@@ -63,23 +431,13 @@ class OpRouter(nn.Module):
         )
 
     def forward(self, x: torch.Tensor) -> torch.Tensor:
-        """
-        Args:
-            x: [batch, input_dim] input features
-
-        Returns:
-            op_weights: [batch, n_ops] soft operation weights (softmax)
-        """
+        """Route each input row to the circuit its features select."""
         logits = self.net(x)
         return F.softmax(logits, dim=-1)
 
 
 class BitDecoder(nn.Module):
-    """
-    Decodes circuit output bits to target representation.
-    For standalone training: outputs soft bits for loss computation.
-    For LLM integration: would project to hidden state delta.
-    """
+    """Decodes circuit output bits to target representation."""
 
     def __init__(self, output_dim: int = 8):
         super().__init__()
@@ -90,10 +448,7 @@ class BitDecoder(nn.Module):
 
 
 class ThresholdALU(nn.Module):
-    """
-    Complete trainable interface + frozen circuits.
-    Learns to encode inputs, route to circuits, decode outputs.
-    """
+    """Complete trainable interface + frozen circuits."""
 
     def __init__(self, device: str = 'cuda'):
         super().__init__()
@@ -110,17 +465,7 @@ class ThresholdALU(nn.Module):
 
     def forward(self, a_bits_in: torch.Tensor, b_bits_in: torch.Tensor,
                 op_onehot: torch.Tensor) -> torch.Tensor:
-        """
-        Forward pass through trainable interface + frozen circuits.
-
-        Args:
-            a_bits_in: [batch, 8] input A bits (ground truth for training)
-            b_bits_in: [batch, 8] input B bits (ground truth for training)
-            op_onehot: [batch, 6] one-hot operation selector
-
-        Returns:
-            result_bits: [batch, 8] output bits
-        """
+        """Forward pass through trainable interface + frozen circuits."""
         x = torch.cat([a_bits_in, b_bits_in, op_onehot], dim=-1)
 
         a_bits, b_bits = self.encoder(x)
@@ -142,10 +487,7 @@ class ThresholdALU(nn.Module):
 
 
 class DirectCircuitModel(nn.Module):
-    """
-    Minimal model that directly uses circuits without learned encoding.
-    For validating that circuits themselves achieve 100% fitness.
-    """
+    """Minimal model that directly uses circuits without learned encoding."""
 
     def __init__(self, device: str = 'cuda'):
         super().__init__()
@@ -158,10 +500,7 @@ class DirectCircuitModel(nn.Module):
 
 
 class HiddenStateExtractor(nn.Module):
-    """
-    Extracts operands and operation from LLM hidden states.
-    This is the hard part - must learn to parse numbers from embeddings.
-    """
+    """Extracts operands and operation from LLM hidden states."""
 
     def __init__(self, hidden_dim: int = 960, intermediate_dim: int = 256):
         super().__init__()
@@ -185,15 +524,7 @@ class HiddenStateExtractor(nn.Module):
         )
 
     def forward(self, hidden_states: torch.Tensor):
-        """
-        Args:
-            hidden_states: [batch, hidden_dim] from LLM
-
-        Returns:
-            a_bits: [batch, 8]
-            b_bits: [batch, 8]
-            op_logits: [batch, 6]
-        """
+        """Extract the operand bits and the operation from the hidden states."""
         a_logits = self.a_extractor(hidden_states)
         b_logits = self.b_extractor(hidden_states)
         op_logits = self.op_router(hidden_states)
@@ -211,10 +542,7 @@ class HiddenStateExtractor(nn.Module):
 
 
 class AttentionPooling(nn.Module):
-    """
-    Learnable attention pooling over sequence positions.
-    Replaces mean pooling - learns which tokens matter for extraction.
-    """
+    """Learnable attention pooling over sequence positions."""
 
     def __init__(self, hidden_dim: int = 960, num_heads: int = 4):
         super().__init__()
@@ -229,14 +557,7 @@ class AttentionPooling(nn.Module):
         self.cls_token = nn.Parameter(torch.randn(1, 1, hidden_dim) * 0.02)
 
     def forward(self, embeddings: torch.Tensor, mask: torch.Tensor) -> torch.Tensor:
-        """
-        Args:
-            embeddings: [batch, seq_len, hidden_dim]
-            mask: [batch, seq_len] attention mask (1 = attend, 0 = ignore)
-
-        Returns:
-            pooled: [batch, hidden_dim]
-        """
+        """Pool the embeddings over the positions the mask attends."""
         batch_size, seq_len, hidden_dim = embeddings.shape
 
         cls_expanded = self.cls_token.expand(batch_size, -1, -1)
@@ -271,10 +592,7 @@ class AttentionPooling(nn.Module):
 
 
 class MultiHeadBitExtractor(nn.Module):
-    """
-    8 separate extractors for 8 bits - each bit gets its own specialized network.
-    More expressive than single MLP predicting all 8 bits at once.
-    """
+    """8 separate extractors for 8 bits - each bit gets its own specialized network."""
 
     def __init__(self, hidden_dim: int = 960, intermediate_dim: int = 128):
         super().__init__()
@@ -289,13 +607,7 @@ class MultiHeadBitExtractor(nn.Module):
         ])
 
     def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
-        """
-        Args:
-            hidden_states: [batch, hidden_dim]
-
-        Returns:
-            bits: [batch, 8] - one bit from each extractor
-        """
+        """Predict the eight bits of each operand from the hidden states."""
         hidden_states = torch.nan_to_num(hidden_states, nan=0.0)
 
         bit_logits = [extractor(hidden_states) for extractor in self.bit_extractors]
@@ -310,10 +622,7 @@ class MultiHeadBitExtractor(nn.Module):
 
 
 class Extractor(nn.Module):
-    """
-    Extracts operands and operation from LLM hidden states.
-    Uses attention pooling and per-bit extraction networks.
-    """
+    """Extracts operands and operation from LLM hidden states."""
 
     def __init__(self, hidden_dim: int = 960, intermediate_dim: int = 256, num_heads: int = 4):
         super().__init__()
@@ -330,16 +639,7 @@ class Extractor(nn.Module):
         )
 
     def forward(self, embeddings: torch.Tensor, mask: torch.Tensor):
-        """
-        Args:
-            embeddings: [batch, seq_len, hidden_dim]
-            mask: [batch, seq_len]
-
-        Returns:
-            a_bits: [batch, 8]
-            b_bits: [batch, 8]
-            op_logits: [batch, 6]
-        """
+        """Extract the operands and the operation from the pooled sequence."""
         pooled = self.attention_pool(embeddings, mask)
 
         a_bits, _ = self.a_extractor(pooled)
@@ -350,22 +650,7 @@ class Extractor(nn.Module):
 
 
 class PositionExtractor(nn.Module):
-    """
-    Position-specific extraction with dynamic operator detection.
-
-    Tokenization pattern for "A op B":
-        [A_digits...] [operator] [space] [B_digits...]
-
-    Examples:
-        "5 + 3"     -> ['5', ' +', ' ', '3']           (positions: A=0, op=1, B=3)
-        "47 + 86"   -> ['4', '7', ' +', ' ', '8', '6'] (positions: A=0-1, op=2, B=4-5)
-        "127 + 128" -> ['1','2','7',' +', ' ','1','2','8'] (positions: A=0-2, op=3, B=5-7)
-
-    Token IDs (SmolLM2):
-        Digits '0'-'9': 32-41
-        Operators: ' +'=1232, ' -'=731, ' *'=1672, ' >'=2986, ' <'=2067, ' =='=1758
-        Space: 216
-    """
+    """Position-specific extraction with dynamic operator detection."""
 
     DIGIT_TOKENS = set(range(32, 42))
     OPERATOR_TOKENS = {
@@ -406,33 +691,14 @@ class PositionExtractor(nn.Module):
         )
 
     def _find_operator_position(self, token_ids: torch.Tensor) -> tuple[int, int]:
-        """
-        Find operator token position and its operation index.
-
-        Args:
-            token_ids: [seq_len] tensor of token IDs
-
-        Returns:
-            (position, op_index) or (-1, -1) if not found
-        """
+        """Find operator token position and its operation index."""
         for pos, tid in enumerate(token_ids.tolist()):
             if tid in self.OPERATOR_TOKENS:
                 return pos, self.OPERATOR_TOKENS[tid]
         return -1, -1
 
     def _extract_digit_features(self, hidden: torch.Tensor, start: int, end: int) -> torch.Tensor:
-        """
-        Extract and pad digit hidden states to fixed size.
-
-        Args:
-            hidden: [seq_len, hidden_dim]
-            start: start position (inclusive)
-            end: end position (exclusive)
-
-        Returns:
-            [hidden_dim * MAX_DIGITS] flattened features, zero-padded on the LEFT
-            (so units digit is always at the same position regardless of number length)
-        """
+        """Extract and pad digit hidden states to fixed size."""
         n_digits = end - start
         features = torch.zeros(self.MAX_DIGITS * self.hidden_dim, device=hidden.device)
 
@@ -444,17 +710,7 @@ class PositionExtractor(nn.Module):
         return features
 
     def forward(self, hidden: torch.Tensor, mask: torch.Tensor, token_ids: torch.Tensor = None):
-        """
-        Args:
-            hidden: [batch, seq_len, hidden_dim]
-            mask: [batch, seq_len] attention mask
-            token_ids: [batch, seq_len] token IDs (required for operator detection)
-
-        Returns:
-            a_bits: [batch, 8]
-            b_bits: [batch, 8]
-            op_logits: [batch, 6]
-        """
+        """Extract the operands at the positions around the detected operator token."""
         if token_ids is None:
             raise ValueError("PositionExtractor requires token_ids for operator detection")
 
@@ -515,19 +771,7 @@ class PositionExtractor(nn.Module):
 
 
 class PositionalDigitExtractor(nn.Module):
-    """
-    Position-aware digit extraction: classifies each digit position independently.
-
-    This approach achieves 100% accuracy because:
-    1. Each digit token position is classified independently (100% accuracy on layer 0)
-    2. Numbers are reconstructed using place values (×100, ×10, ×1)
-    3. No information is lost through pooling
-
-    Token IDs (SmolLM2):
-        Digits '0'-'9': 32-41
-        Operators: ' +'=1232, ' -'=731, ' *'=1672, ' >'=2986, ' <'=2067, ' =='=1758
-        Space: 216
-    """
+    """Position-aware digit extraction: classifies each digit position independently."""
 
     DIGIT_TOKENS = set(range(32, 42))
     OPERATOR_TOKENS = {
@@ -605,20 +849,7 @@ class PositionalDigitExtractor(nn.Module):
         return torch.stack(bits)
 
     def forward(self, hidden: torch.Tensor, mask: torch.Tensor, token_ids: torch.Tensor):
-        """
-        Args:
-            hidden: [batch, seq_len, hidden_dim]
-            mask: [batch, seq_len]
-            token_ids: [batch, seq_len]
-
-        Returns:
-            a_bits: [batch, 8]
-            b_bits: [batch, 8]
-            op_logits: [batch, 6]
-            op_indices: [batch] ground truth op from tokens
-            a_digit_logits: list of [batch, 10] per digit position
-            b_digit_logits: list of [batch, 10] per digit position
-        """
+        """Classify each digit position of both operands."""
         batch_size = hidden.shape[0]
         device = hidden.device
 
@@ -672,10 +903,7 @@ class PositionalDigitExtractor(nn.Module):
 
 
 class DigitExtractor(nn.Module):
-    """
-    Digit-level extraction: predicts digits (0-9) then converts to bits.
-    Uses attention pooling (less accurate than PositionalDigitExtractor).
-    """
+    """Digit-level extraction: predicts digits (0-9) then converts to bits."""
 
     def __init__(self, hidden_dim: int = 960, intermediate_dim: int = 256, num_heads: int = 4):
         super().__init__()
@@ -701,11 +929,7 @@ class DigitExtractor(nn.Module):
         )
 
     def digits_to_bits(self, digit_logits: torch.Tensor) -> torch.Tensor:
-        """
-        Convert 3-digit predictions to 8-bit representation.
-        digit_logits: [batch, 30] (3 digits * 10 classes each)
-        Returns: [batch, 8] bits
-        """
+        """Convert the digit logits of three digits, [batch, 30], to 8-bit operands."""
         batch_size = digit_logits.shape[0]
 
         logits = digit_logits.view(batch_size, 3, 10)
@@ -729,10 +953,7 @@ class DigitExtractor(nn.Module):
         return torch.stack(bits, dim=-1)
 
     def forward(self, hidden: torch.Tensor, mask: torch.Tensor):
-        """
-        Returns:
-            a_bits, b_bits, op_logits, a_digit_logits, b_digit_logits
-        """
+        """Return the operand bits, the operation logits and the digit logits."""
         pooled = self.attention_pool(hidden, mask)
 
         a_digit_logits = self.a_digit_pred(pooled)
@@ -746,15 +967,7 @@ class DigitExtractor(nn.Module):
 
 
 class HybridExtractor(nn.Module):
-    """
-    Hybrid extractor that handles both digit tokens and word numbers.
-
-    For digit tokens (32-41): Direct lookup, no training needed
-    For word numbers: Learned MLP extraction from pooled hidden states
-
-    This is the real training target - learning to extract numbers from
-    natural language like "forty seven plus eighty six".
-    """
+    """Hybrid extractor that handles both digit tokens and word numbers."""
 
     DIGIT_TOKENS = set(range(32, 42))
     SYMBOL_OP_TOKENS = {
@@ -820,11 +1033,7 @@ class HybridExtractor(nn.Module):
         return -1
 
     def _extract_from_digits(self, token_ids: torch.Tensor) -> tuple:
-        """
-        Extract values directly from digit tokens (hardcoded lookup).
-        Handles both symbol operators (' +') and word operators ('plus').
-        Returns (a_value, b_value, op_idx) or None if pattern not found.
-        """
+        """Extract values directly from digit tokens (hardcoded lookup)."""
         tokens = token_ids.tolist()
 
         op_pos = -1
@@ -873,11 +1082,7 @@ class HybridExtractor(nn.Module):
         return bits
 
     def _digits_to_value_and_bits(self, digit_logits: torch.Tensor, device) -> tuple:
-        """
-        Convert 3-digit logits to value and bits.
-        digit_logits: [30] (3 digits × 10 classes)
-        Returns: (value tensor, bits tensor [8])
-        """
+        """Convert the 30 logits of three digits to a value and its 8 bits."""
         logits = digit_logits.view(3, 10)
         probs = torch.softmax(logits, dim=-1)
 
@@ -900,16 +1105,7 @@ class HybridExtractor(nn.Module):
         return hundreds * 100 + tens * 10 + ones, torch.stack(bits)
 
     def forward(self, hidden: torch.Tensor, mask: torch.Tensor, token_ids: torch.Tensor = None):
-        """
-        Args:
-            hidden: [batch, seq_len, hidden_dim]
-            mask: [batch, seq_len]
-            token_ids: [batch, seq_len] - optional, enables digit lookup
-
-        Returns:
-            a_bits, b_bits, op_logits, a_values, b_values, used_lookup,
-            a_digit_logits, b_digit_logits
-        """
+        """Extract the operands from digit tokens by lookup, or from the hidden states."""
         batch_size = hidden.shape[0]
         device = hidden.device
 
@@ -1019,10 +1215,7 @@ class HybridExtractor(nn.Module):
 
 
 class ArithmeticModel(nn.Module):
-    """
-    LLM + extractor + frozen threshold circuits.
-    Optionally unfreeze top N transformer layers with --unfreeze_layers.
-    """
+    """LLM + extractor + frozen threshold circuits."""
 
     def __init__(self, device: str = 'cuda', unfreeze_layers: int = 0,
                  extract_layer: int = -1, position_extract: bool = False,
@@ -1117,14 +1310,7 @@ class ArithmeticModel(nn.Module):
         print(f"  Total trainable: {total_trainable:,}", flush=True)
 
     def get_hidden_states(self, texts: list[str]) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
-        """
-        Get hidden states from specified layer.
-
-        Returns:
-            hidden: [batch, seq_len, hidden_dim] hidden states
-            mask: [batch, seq_len] attention mask
-            token_ids: [batch, seq_len] input token IDs
-        """
+        """Get hidden states from specified layer."""
         inputs = self.tokenizer(
             texts,
             return_tensors='pt',
@@ -1146,15 +1332,7 @@ class ArithmeticModel(nn.Module):
         return hidden, mask, token_ids
 
     def forward(self, texts: list[str]):
-        """
-        Full forward pass: text -> hidden states -> extractor -> circuits -> result
-
-        Returns:
-            result_bits, a_bits, b_bits, op_logits
-            If digit_pred: also returns a_digit_logits, b_digit_logits
-            If position_extract or positional_digit: also returns op_indices
-            If positional_digit: also returns a_values, b_values
-        """
+        """Run text through the LLM, the extractor and the circuits to the result."""
         hidden, mask, token_ids = self.get_hidden_states(texts)
 
         if self.hybrid or self.positional_digit or self.position_extract:
@@ -1207,10 +1385,1182 @@ class ArithmeticModel(nn.Module):
         return params
 
 
-if __name__ == "__main__":
+DEVICE = 'cuda'
+
+ONES = ['zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine',
+        'ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen',
+        'seventeen', 'eighteen', 'nineteen']
+
+TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety']
+
+def int_to_words(n: int) -> str:
+    """Convert integer 0-255 to English words."""
+    if n < 0 or n > 255:
+        return str(n)
+    if n < 20:
+        return ONES[n]
+    if n < 100:
+        if n % 10 == 0:
+            return TENS[n // 10]
+        return f"{TENS[n // 10]} {ONES[n % 10]}"
+    if n % 100 == 0:
+        return f"{ONES[n // 100]} hundred"
+    if n % 100 < 20:
+        return f"{ONES[n // 100]} hundred {ONES[n % 100]}"
+    if n % 10 == 0:
+        return f"{ONES[n // 100]} hundred {TENS[(n % 100) // 10]}"
+    return f"{ONES[n // 100]} hundred {TENS[(n % 100) // 10]} {ONES[n % 10]}"
+
+
+def train_int_to_bits(val: int, device: str = 'cuda') -> torch.Tensor:
+    bits = torch.zeros(8, device=device)
+    for i in range(8):
+        bits[7-i] = (val >> i) & 1
+    return bits
+
+
+def train_bits_to_int(bits: torch.Tensor) -> int:
+    val = 0
+    for i in range(8):
+        if bits[i].item() > 0.5:
+            val += 1 << (7-i)
+    return val
+
+
+NL_TEMPLATES = {
+    'add': [
+        "What is {a} plus {b}?",
+        "Calculate {a} + {b}",
+        "Add {a} and {b}",
+        "What's the sum of {a} and {b}?",
+        "If I have {a} and get {b} more, how many total?",
+        "{a} + {b} = ?",
+        "Compute {a} plus {b}",
+    ],
+    'sub': [
+        "What is {a} minus {b}?",
+        "Calculate {a} - {b}",
+        "Subtract {b} from {a}",
+        "What's {a} take away {b}?",
+        "If I have {a} and lose {b}, how many left?",
+        "{a} - {b} = ?",
+        "Compute {a} minus {b}",
+    ],
+    'mul': [
+        "What is {a} times {b}?",
+        "Calculate {a} * {b}",
+        "Multiply {a} by {b}",
+        "What's {a} multiplied by {b}?",
+        "{a} * {b} = ?",
+        "Compute {a} times {b}",
+        "What is the product of {a} and {b}?",
+    ],
+    'gt': [
+        "Is {a} greater than {b}?",
+        "Is {a} > {b}?",
+        "Check if {a} is larger than {b}",
+        "Compare: is {a} more than {b}?",
+        "{a} > {b}?",
+    ],
+    'lt': [
+        "Is {a} less than {b}?",
+        "Is {a} < {b}?",
+        "Check if {a} is smaller than {b}",
+        "Compare: is {a} fewer than {b}?",
+        "{a} < {b}?",
+    ],
+    'eq': [
+        "Is {a} equal to {b}?",
+        "Is {a} == {b}?",
+        "Does {a} equal {b}?",
+        "Check if {a} equals {b}",
+        "Are {a} and {b} the same?",
+    ],
+}
+
+
+def generate_problem(max_val: int = 255):
+    """Generate a random arithmetic problem for LLM training."""
+    a = random.randint(0, max_val)
+    b = random.randint(0, max_val)
+    op = random.choice(OPERATIONS)
+
+    fmt = random.choice(['digits', 'words', 'nl_digits', 'nl_words'])
+
+    if fmt == 'digits':
+        sym = OP_SYMBOLS[op]
+        text = f"{a} {sym} {b}"
+    elif fmt == 'words':
+        a_word = int_to_words(a)
+        b_word = int_to_words(b)
+        op_word = {'add': 'plus', 'sub': 'minus', 'mul': 'times',
+                   'gt': 'greater than', 'lt': 'less than', 'eq': 'equals'}[op]
+        text = f"{a_word} {op_word} {b_word}"
+    elif fmt == 'nl_digits':
+        template = random.choice(NL_TEMPLATES[op])
+        text = template.format(a=a, b=b)
+    else:
+        template = random.choice(NL_TEMPLATES[op])
+        text = template.format(a=int_to_words(a), b=int_to_words(b))
+
+    if op == 'add':
+        result = (a + b) & 0xFF
+    elif op == 'sub':
+        result = (a - b) & 0xFF
+    elif op == 'mul':
+        result = (a * b) & 0xFF
+    elif op == 'gt':
+        result = 1 if a > b else 0
+    elif op == 'lt':
+        result = 1 if a < b else 0
+    elif op == 'eq':
+        result = 1 if a == b else 0
+
+    return text, a, b, op, result
+
+
+def get_curriculum_max(epoch: int, total_epochs: int) -> int:
+    """Curriculum learning: start with small numbers, gradually increase."""
+    progress = epoch / total_epochs
+    if progress < 0.2:
+        return 9
+    elif progress < 0.5:
+        return 99
+    else:
+        return 255
+
+
+def train_router(epochs: int = 100, batch_size: int = 256, lr: float = 1e-2, device: str = 'cuda'):
+    """Train only the router with ground truth bits."""
+    print("=" * 70)
+    print(" ROUTER-ONLY TRAINING (Ground Truth Bits)")
+    print("=" * 70)
+
+    circuits = FrozenThresholdCircuits(device=device)
+    router = OpRouter(input_dim=16 + 6, hidden_dim=64, n_ops=6).to(device)
+
+    print(f"\nRouter parameters: {sum(p.numel() for p in router.parameters()):,}")
+
+    def model_fn(a_bits, b_bits, op_onehot):
+        x = torch.cat([a_bits, b_bits, op_onehot], dim=-1)
+        op_weights = router(x)
+        return circuits(a_bits, b_bits, op_weights)
+
+    initial_fitness = compute_fitness(model_fn, n_samples=1000, device=device)
+    print(f"Initial fitness: {initial_fitness:.4f}")
+
+    optimizer = optim.AdamW(router.parameters(), lr=lr)
+    scheduler = optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs)
+
+    print("\nTraining...")
+    print("-" * 70)
+
+    best_fitness = initial_fitness
+    start_time = time.perf_counter()
+
+    for epoch in range(epochs):
+        router.train()
+        epoch_loss = 0.0
+
+        for _ in range(100):
+            batch = generate_batch(batch_size, device)
+
+            optimizer.zero_grad()
+
+            x = torch.cat([batch['a_bits'], batch['b_bits'], batch['op_onehot']], dim=-1)
+            op_weights = router(x)
+            pred_bits = circuits(batch['a_bits'], batch['b_bits'], op_weights)
+
+            loss = compute_loss(pred_bits, batch['expected_bits'])
+            loss.backward()
+            optimizer.step()
+
+            epoch_loss += loss.item()
+
+        scheduler.step()
+
+        if (epoch + 1) % 10 == 0 or epoch == 0:
+            router.eval()
+            fitness, details = compute_fitness(model_fn, n_samples=2000, device=device, return_details=True)
+            elapsed = time.perf_counter() - start_time
+
+            if fitness > best_fitness:
+                best_fitness = fitness
+                marker = " *"
+            else:
+                marker = ""
+
+            print(f"Epoch {epoch+1:3d} | Loss: {epoch_loss/100:.4f} | "
+                  f"Fitness: {fitness:.4f}{marker} | Time: {elapsed:.1f}s")
+
+            if fitness >= 0.9999:
+                print("\n TARGET: 100% FITNESS ACHIEVED")
+                break
+
+    print("\n" + "=" * 70)
+    print(" RESULTS")
+    print("=" * 70)
+
+    router.eval()
+    final_fitness, details = compute_fitness(model_fn, n_samples=5000, device=device, return_details=True)
+
+    print(f"\nFinal fitness: {final_fitness:.4f}")
+    print(f"\nPer-operation:")
+    for op in OPERATIONS:
+        acc = details['by_op'][op]['accuracy']
+        print(f"  {op}: {acc:.4f}")
+
+    print(f"\nTotal time: {time.perf_counter() - start_time:.1f}s")
+
+    if final_fitness >= 0.99:
+        print("\nCONCLUSION: Router successfully learned operation dispatch.")
+        print("           With correct bit encoding, 100% is achievable.")
+
+    save_path = os.path.join(TRAINED, 'router.pt')
+    torch.save({
+        'router_state_dict': router.state_dict(),
+        'final_fitness': final_fitness,
+        'params': sum(p.numel() for p in router.parameters()),
+    }, save_path)
+    print(f"\nSaved trained router to: {save_path}")
+
+    return router, final_fitness
+
+
+def get_gpu_memory():
+    """Get GPU memory usage in MB."""
+    if torch.cuda.is_available():
+        return torch.cuda.memory_allocated() / 1024 / 1024, torch.cuda.max_memory_allocated() / 1024 / 1024
+    return 0, 0
+
+
+def train_interface(epochs: int = 200, batch_size: int = 512, lr: float = 1e-3,
+                    eval_interval: int = 10, device: str = 'cuda'):
+    """Train BitEncoder + OpRouter with ground truth bits."""
+    print("=" * 70)
+    print(" INTERFACE TRAINING (Encoder + Router)")
+    print("=" * 70)
+    print(f"  Started at: {time.strftime('%H:%M:%S')}")
+
+    print("\n[1/4] Verifying frozen circuits...")
+    print("  Creating DirectCircuitModel...", end=" ", flush=True)
+    direct_model = DirectCircuitModel(device=device)
+    mem, max_mem = get_gpu_memory()
+    print(f"done. VRAM: {mem:.0f}MB")
+
+    def direct_fn(a, b, op):
+        return direct_model(a, b, op)
+
+    print("  Running fitness check (1000 samples)...", end=" ", flush=True)
+    circuit_fitness = compute_fitness(direct_fn, n_samples=1000, device=device)
+    print(f"done. Fitness: {circuit_fitness:.4f}")
+    if circuit_fitness < 0.999:
+        print("  ERROR: Circuits not achieving 100%. Aborting.")
+        return None, 0.0
+    print("  STATUS: PASS")
+
+    print("\n[2/4] Initializing model...")
+    print("  Creating ThresholdALU...", end=" ", flush=True)
+    model = ThresholdALU(device=device)
+    mem, max_mem = get_gpu_memory()
+    print(f"done. VRAM: {mem:.0f}MB")
+
+    trainable_params = sum(p.numel() for p in model.parameters() if p.requires_grad)
+    print(f"  Trainable parameters: {trainable_params:,}")
+
+    def model_fn(a, b, op):
+        return model(a, b, op)
+
+    print("  Running initial fitness check...", end=" ", flush=True)
+    initial_fitness = compute_fitness(model_fn, n_samples=1000, device=device)
+    print(f"done. Fitness: {initial_fitness:.4f}")
+
+    print("\n[3/4] Setting up training...")
+    print("  Creating optimizer...", end=" ", flush=True)
+    optimizer = optim.AdamW(model.parameters(), lr=lr)
+    print("done.")
+    print("  Creating scheduler...", end=" ", flush=True)
+    scheduler = optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs)
+    print("done.")
+
+    print(f"  Config: lr={lr}, batch_size={batch_size}, epochs={epochs}")
+
+    print("\n[4/4] Training...")
+    print("  Generating first batch to warm up...", end=" ", flush=True)
+    warmup_batch = generate_batch(batch_size, device)
+    mem, max_mem = get_gpu_memory()
+    print(f"done. VRAM: {mem:.0f}MB (max: {max_mem:.0f}MB)")
+
+    print("-" * 70)
+
+    best_fitness = initial_fitness
+    start_time = time.perf_counter()
+    n_batches = 100
+
+    for epoch in range(epochs):
+        model.train()
+        epoch_loss = 0.0
+        epoch_start = time.perf_counter()
+
+        for batch_idx in range(n_batches):
+            batch = generate_batch(batch_size, device)
+
+            optimizer.zero_grad()
+
+            pred_bits = model(batch['a_bits'], batch['b_bits'], batch['op_onehot'])
+
+            loss = compute_loss(pred_bits, batch['expected_bits'])
+
+            loss.backward()
+            optimizer.step()
+
+            epoch_loss += loss.item()
+
+            if batch_idx == 0 and epoch == 0:
+                mem, max_mem = get_gpu_memory()
+                print(f"  First forward/backward done. VRAM: {mem:.0f}MB (max: {max_mem:.0f}MB)")
+
+            if (batch_idx + 1) % 25 == 0:
+                avg_so_far = epoch_loss / (batch_idx + 1)
+                print(f"  Epoch {epoch+1} batch {batch_idx+1}/{n_batches} | loss: {avg_so_far:.4f}", flush=True)
+
+        scheduler.step()
+
+        avg_loss = epoch_loss / n_batches
+        epoch_time = time.perf_counter() - epoch_start
+
+        if (epoch + 1) % 5 == 0 or epoch == 0:  # Eval every 5 epochs
+            model.eval()
+            fitness, details = compute_fitness(
+                model_fn, n_samples=2000, device=device, return_details=True
+            )
+
+            elapsed = time.perf_counter() - start_time
+
+            if fitness > best_fitness:
+                best_fitness = fitness
+                marker = " *"
+            else:
+                marker = ""
+
+            mem, _ = get_gpu_memory()
+            print(f"Epoch {epoch+1:4d} | Loss: {avg_loss:.4f} | "
+                  f"Fitness: {fitness:.4f}{marker} | "
+                  f"LR: {scheduler.get_last_lr()[0]:.2e} | "
+                  f"VRAM: {mem:.0f}MB | "
+                  f"Time: {elapsed:.1f}s ({epoch_time:.1f}s/epoch)")
+
+            if fitness >= 0.9999:
+                print("\n" + "=" * 70)
+                print(" TARGET ACHIEVED: 100% FITNESS")
+                print("=" * 70)
+                break
+
+    print("\n" + "=" * 70)
+    print(" TRAINING COMPLETE")
+    print("=" * 70)
+
+    model.eval()
+    final_fitness, details = compute_fitness(
+        model_fn, n_samples=5000, device=device, return_details=True
+    )
+
+    print(f"\nFinal fitness: {final_fitness:.4f}")
+    print(f"Best fitness:  {best_fitness:.4f}")
+    print(f"\nPer-operation breakdown:")
+    for op in OPERATIONS:
+        acc = details['by_op'][op]['accuracy']
+        print(f"  {op:6}: {acc:.4f}")
+
+    print(f"\nTotal time: {time.perf_counter() - start_time:.1f}s")
+
+    save_path = os.path.join(TRAINED, 'interface.pt')
+    torch.save({
+        'encoder_state_dict': model.encoder.state_dict(),
+        'router_state_dict': model.router.state_dict(),
+        'final_fitness': final_fitness,
+        'best_fitness': best_fitness,
+    }, save_path)
+    print(f"\nSaved trained model to: {save_path}")
+
+    return model, final_fitness
+
+
+def compute_llm_loss(pred_bits, a_bits, b_bits, op_logits,
+                     target_result, target_a, target_b, target_op_idx,
+                     bit_weight: float = 2.0):
+    """Multi-component loss for LLM training; bit_weight scales the operand-bit losses."""
+    result_loss = nn.functional.binary_cross_entropy_with_logits(
+        pred_bits, target_result
+    )
+
+    a_bits_safe = torch.clamp(a_bits, 0.0, 1.0)
+    b_bits_safe = torch.clamp(b_bits, 0.0, 1.0)
+    a_bits_safe = torch.nan_to_num(a_bits_safe, nan=0.5, posinf=1.0, neginf=0.0)
+    b_bits_safe = torch.nan_to_num(b_bits_safe, nan=0.5, posinf=1.0, neginf=0.0)
+
+    a_loss = nn.functional.binary_cross_entropy(
+        torch.clamp(a_bits_safe, 1e-6, 1-1e-6), target_a
+    )
+    b_loss = nn.functional.binary_cross_entropy(
+        torch.clamp(b_bits_safe, 1e-6, 1-1e-6), target_b
+    )
+
+    op_loss = nn.functional.cross_entropy(op_logits, target_op_idx)
+
+    total = result_loss + bit_weight * a_loss + bit_weight * b_loss + op_loss
+    total = torch.nan_to_num(total, nan=10.0, posinf=10.0, neginf=0.0)
+
+    return total, {
+        'result': result_loss.item() if not torch.isnan(result_loss) else 10.0,
+        'a': a_loss.item() if not torch.isnan(a_loss) else 10.0,
+        'b': b_loss.item() if not torch.isnan(b_loss) else 10.0,
+        'op': op_loss.item() if not torch.isnan(op_loss) else 10.0
+    }
+
+
+def value_to_digits(value: int) -> list:
+    """Convert integer value to list of digits (hundreds, tens, ones)."""
+    digits = []
+    for place in [100, 10, 1]:
+        digit = (value // place) % 10
+        digits.append(digit)
+    return digits
+
+
+def compute_positional_digit_loss(pred_bits, op_logits, a_digit_logits_list, b_digit_logits_list,
+                                   target_result, target_op_idx, target_a_values, target_b_values,
+                                   device, digit_weight: float = 5.0):
+    """Loss for positional digit extraction with DIRECT digit supervision."""
+    result_loss = nn.functional.binary_cross_entropy_with_logits(
+        pred_bits, target_result
+    )
+
+    op_loss = nn.functional.cross_entropy(op_logits, target_op_idx)
+
+    a_digit_loss = torch.tensor(0.0, device=device)
+    b_digit_loss = torch.tensor(0.0, device=device)
+    n_a_digits = 0
+    n_b_digits = 0
+
+    for i, (a_logits_list, b_logits_list) in enumerate(zip(a_digit_logits_list, b_digit_logits_list)):
+        target_a = target_a_values[i].item()
+        target_b = target_b_values[i].item()
+
+        a_digits = value_to_digits(int(target_a))
+        b_digits = value_to_digits(int(target_b))
+
+        n_a = len(a_logits_list)
+        n_b = len(b_logits_list)
+
+        if n_a > 0:
+            target_a_digits = a_digits[-n_a:]
+            for j, logits in enumerate(a_logits_list):
+                target_digit = torch.tensor([target_a_digits[j]], device=device, dtype=torch.long)
+                a_digit_loss = a_digit_loss + nn.functional.cross_entropy(logits.unsqueeze(0), target_digit)
+                n_a_digits += 1
+
+        if n_b > 0:
+            target_b_digits = b_digits[-n_b:]
+            for j, logits in enumerate(b_logits_list):
+                target_digit = torch.tensor([target_b_digits[j]], device=device, dtype=torch.long)
+                b_digit_loss = b_digit_loss + nn.functional.cross_entropy(logits.unsqueeze(0), target_digit)
+                n_b_digits += 1
+
+    if n_a_digits > 0:
+        a_digit_loss = a_digit_loss / n_a_digits
+    if n_b_digits > 0:
+        b_digit_loss = b_digit_loss / n_b_digits
+
+    total = result_loss + digit_weight * a_digit_loss + digit_weight * b_digit_loss + op_loss
+    total = torch.nan_to_num(total, nan=10.0, posinf=10.0, neginf=0.0)
+
+    return total, {
+        'result': result_loss.item() if not torch.isnan(result_loss) else 10.0,
+        'a_digit': a_digit_loss.item() if not torch.isnan(a_digit_loss) else 10.0,
+        'b_digit': b_digit_loss.item() if not torch.isnan(b_digit_loss) else 10.0,
+        'op': op_loss.item() if not torch.isnan(op_loss) else 10.0
+    }
+
+
+def compute_hybrid_loss(pred_bits, op_logits, used_lookup,
+                        a_digit_logits, b_digit_logits,
+                        target_result, target_a_values, target_b_values, target_op_idx,
+                        device, digit_weight: float = 2.0):
+    """Loss for hybrid extraction with digit-level prediction."""
+    result_loss = nn.functional.binary_cross_entropy_with_logits(
+        pred_bits, target_result
+    )
+
+    op_loss = nn.functional.cross_entropy(op_logits, target_op_idx)
+
+    word_mask = ~used_lookup
+    n_words = word_mask.sum().item()
+
+    if n_words > 0 and a_digit_logits is not None and b_digit_logits is not None:
+        target_a_word = target_a_values[word_mask].long()
+        target_b_word = target_b_values[word_mask].long()
+
+        a_hundreds = target_a_word // 100
+        a_tens = (target_a_word % 100) // 10
+        a_ones = target_a_word % 10
+
+        b_hundreds = target_b_word // 100
+        b_tens = (target_b_word % 100) // 10
+        b_ones = target_b_word % 10
+
+        a_logits = a_digit_logits.view(-1, 3, 10)
+        b_logits = b_digit_logits.view(-1, 3, 10)
+
+        a_digit_loss = (
+            nn.functional.cross_entropy(a_logits[:, 0], a_hundreds) +
+            nn.functional.cross_entropy(a_logits[:, 1], a_tens) +
+            nn.functional.cross_entropy(a_logits[:, 2], a_ones)
+        ) / 3.0
+
+        b_digit_loss = (
+            nn.functional.cross_entropy(b_logits[:, 0], b_hundreds) +
+            nn.functional.cross_entropy(b_logits[:, 1], b_tens) +
+            nn.functional.cross_entropy(b_logits[:, 2], b_ones)
+        ) / 3.0
+    else:
+        a_digit_loss = torch.tensor(0.0, device=device)
+        b_digit_loss = torch.tensor(0.0, device=device)
+
+    total = result_loss + op_loss + digit_weight * (a_digit_loss + b_digit_loss)
+    total = torch.nan_to_num(total, nan=10.0, posinf=10.0, neginf=0.0)
+
+    return total, {
+        'result': result_loss.item() if not torch.isnan(result_loss) else 10.0,
+        'a_digit': a_digit_loss.item() if not torch.isnan(a_digit_loss) else 10.0,
+        'b_digit': b_digit_loss.item() if not torch.isnan(b_digit_loss) else 10.0,
+        'op': op_loss.item() if not torch.isnan(op_loss) else 10.0,
+        'n_words': n_words,
+        'n_lookup': used_lookup.sum().item()
+    }
+
+
+def evaluate_llm(model, n_samples: int = 500):
+    """Evaluate LLM model on random problems (mixed digit/word format)."""
+    model.extractor.eval()
+    correct = 0
+    op_correct = 0
+
+    for _ in range(n_samples):
+        text, a, b, op, expected = generate_problem()
+
+        with torch.no_grad():
+            outputs = model([text])
+            result_bits = outputs[0]
+            op_logits = outputs[3]
+
+        pred_result = train_bits_to_int(result_bits[0])
+        pred_op = OPERATIONS[op_logits[0].argmax().item()]
+
+        if pred_result == expected:
+            correct += 1
+        if pred_op == op:
+            op_correct += 1
+
+    model.extractor.train()
+    return correct / n_samples, op_correct / n_samples
+
+
+def train_llm(epochs: int = 100, batch_size: int = 256, lr: float = 3e-4,
+              unfreeze_layers: int = 0, extract_layer: int = -1,
+              position_extract: bool = False, digit_pred: bool = False,
+              positional_digit: bool = False, device: str = 'cuda'):
+    """Train extractor with LLM hidden states."""
+    hybrid = not (positional_digit or position_extract or digit_pred)
+
+    print("=" * 70)
+    print(" LLM TRAINING")
+    if unfreeze_layers > 0:
+        print(f" {unfreeze_layers} transformer layers unfrozen")
+    else:
+        print(" LLM frozen")
+    if extract_layer != -1:
+        print(f" Extracting from layer {extract_layer}")
+    if hybrid:
+        print(" HYBRID extraction (digit lookup + word learning)")
+    elif positional_digit:
+        print(" POSITIONAL DIGIT extraction (legacy, 100% on digits only)")
+    elif position_extract:
+        print(" Position-specific extraction (legacy)")
+    elif digit_pred:
+        print(" Digit-level prediction (legacy)")
+    print("=" * 70)
+
+    print("\nInitializing model...")
+    model = ArithmeticModel(
+        device=device,
+        unfreeze_layers=unfreeze_layers,
+        extract_layer=extract_layer,
+        position_extract=position_extract,
+        digit_pred=digit_pred,
+        positional_digit=positional_digit,
+        hybrid=hybrid
+    )
+
+    optimizer = optim.AdamW(model.trainable_parameters(), lr=lr)
+    scheduler = optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs)
+
+    print(f"\nTraining config:")
+    print(f"  Epochs: {epochs}")
+    print(f"  Batch size: {batch_size}")
+    print(f"  Learning rate: {lr}")
+    print(f"  Unfreeze layers: {unfreeze_layers}")
+    print(f"  Samples/epoch: {batch_size * 20}")
+
+    print(f"\nInitial evaluation (200 samples)...")
+    acc, op_acc = evaluate_llm(model, 200)
+    print(f"  Accuracy: {acc:.4f}, Op accuracy: {op_acc:.4f}")
+
+    print(f"\nStarting training...")
+    print("-" * 70)
+
+    best_acc = acc
+    start_time = time.perf_counter()
+
+    for epoch in range(epochs):
+        model.extractor.train()
+        if unfreeze_layers > 0:
+            model.llm.train()
+
+        max_val = get_curriculum_max(epoch, epochs)
+
+        epoch_loss = 0
+        if hybrid:
+            epoch_losses = {'result': 0, 'a_digit': 0, 'b_digit': 0, 'op': 0, 'n_words': 0, 'n_lookup': 0}
+        elif positional_digit:
+            epoch_losses = {'result': 0, 'a_digit': 0, 'b_digit': 0, 'op': 0}
+        else:
+            epoch_losses = {'result': 0, 'a': 0, 'b': 0, 'op': 0}
+        n_batches = 20
+        epoch_start = time.perf_counter()
+
+        for batch_idx in range(n_batches):
+            batch_texts = []
+            batch_a = []
+            batch_b = []
+            batch_op = []
+            batch_result = []
+            batch_a_values = []
+            batch_b_values = []
+
+            for _ in range(batch_size):
+                text, a, b, op, result = generate_problem(max_val)
+                batch_texts.append(text)
+                batch_a.append(train_int_to_bits(a, device))
+                batch_b.append(train_int_to_bits(b, device))
+                batch_op.append(OPERATIONS.index(op))
+                batch_result.append(train_int_to_bits(result, device))
+                batch_a_values.append(a)
+                batch_b_values.append(b)
+
+            target_a = torch.stack(batch_a)
+            target_b = torch.stack(batch_b)
+            target_op = torch.tensor(batch_op, device=device)
+            target_result = torch.stack(batch_result)
+            target_a_values = torch.tensor(batch_a_values, device=device, dtype=torch.float32)
+            target_b_values = torch.tensor(batch_b_values, device=device, dtype=torch.float32)
+
+            optimizer.zero_grad()
+
+            outputs = model(batch_texts)
+            pred_bits, a_bits, b_bits, op_logits = outputs[0], outputs[1], outputs[2], outputs[3]
+
+            if hybrid:
+                a_values, b_values, used_lookup = outputs[4], outputs[5], outputs[6]
+                a_digit_logits, b_digit_logits = outputs[7], outputs[8]
+                loss, losses = compute_hybrid_loss(
+                    pred_bits, op_logits, used_lookup,
+                    a_digit_logits, b_digit_logits,
+                    target_result, target_a_values, target_b_values, target_op, device
+                )
+            elif positional_digit:
+                a_digit_logits_list = outputs[7]
+                b_digit_logits_list = outputs[8]
+                loss, losses = compute_positional_digit_loss(
+                    pred_bits, op_logits, a_digit_logits_list, b_digit_logits_list,
+                    target_result, target_op, target_a_values, target_b_values, device
+                )
+            else:
+                loss, losses = compute_llm_loss(
+                    pred_bits, a_bits, b_bits, op_logits,
+                    target_result, target_a, target_b, target_op
+                )
+
+            loss.backward()
+            torch.nn.utils.clip_grad_norm_(model.trainable_parameters(), 1.0)
+            optimizer.step()
+
+            epoch_loss += loss.item()
+            for k in epoch_losses:
+                epoch_losses[k] += losses[k]
+
+            if (batch_idx + 1) % 5 == 0:
+                avg_so_far = epoch_loss / (batch_idx + 1)
+                print(f"  Epoch {epoch+1} batch {batch_idx+1}/{n_batches} | loss: {avg_so_far:.4f}", flush=True)
+
+        epoch_time = time.perf_counter() - epoch_start
+        scheduler.step()
+
+        avg_loss = epoch_loss / n_batches
+        for k in epoch_losses:
+            epoch_losses[k] /= n_batches
+
+        acc, op_acc = evaluate_llm(model, 300)
+        elapsed = time.perf_counter() - start_time
+
+        marker = " *" if acc > best_acc else ""
+        if acc > best_acc:
+            best_acc = acc
+
+        mem, _ = get_gpu_memory()
+        print(f"Epoch {epoch+1:3d} | Loss: {avg_loss:.4f} | "
+              f"Acc: {acc:.4f}{marker} | OpAcc: {op_acc:.4f} | "
+              f"Range: 0-{max_val} | VRAM: {mem:.0f}MB | Time: {elapsed:.0f}s")
+        if hybrid:
+            print(f"          Losses - result:{epoch_losses['result']:.4f} "
+                  f"a_digit:{epoch_losses['a_digit']:.4f} b_digit:{epoch_losses['b_digit']:.4f} "
+                  f"op:{epoch_losses['op']:.4f} | words:{epoch_losses['n_words']:.0f} lookup:{epoch_losses['n_lookup']:.0f}")
+        elif positional_digit:
+            print(f"          Losses - result:{epoch_losses['result']:.4f} "
+                  f"a_digit:{epoch_losses['a_digit']:.4f} b_digit:{epoch_losses['b_digit']:.4f} "
+                  f"op:{epoch_losses['op']:.4f}")
+        else:
+            print(f"          Losses - result:{epoch_losses['result']:.4f} "
+                  f"a:{epoch_losses['a']:.4f} b:{epoch_losses['b']:.4f} "
+                  f"op:{epoch_losses['op']:.4f}")
+
+        if acc >= 0.99:
+            print("\n" + "=" * 70)
+            print(" TARGET ACHIEVED: 99%+ ACCURACY")
+            print("=" * 70)
+            break
+
+    print("\n" + "=" * 70)
+    print(" FINAL EVALUATION")
+    print("=" * 70)
+
+    acc, op_acc = evaluate_llm(model, 1000)
+    print(f"Final accuracy: {acc:.4f}")
+    print(f"Final op accuracy: {op_acc:.4f}")
+    print(f"Best accuracy: {best_acc:.4f}")
+
+    print("\nSample predictions:")
+    for _ in range(10):
+        text, a, b, op, expected = generate_problem()
+        with torch.no_grad():
+            outputs = model([text])
+            result_bits, a_bits, b_bits, op_logits = outputs[0], outputs[1], outputs[2], outputs[3]
+        pred = train_bits_to_int(result_bits[0])
+        pred_a = train_bits_to_int(a_bits[0])
+        pred_b = train_bits_to_int(b_bits[0])
+        pred_op = OPERATIONS[op_logits[0].argmax().item()]
+
+        status = "OK" if pred == expected else "WRONG"
+        print(f"  '{text}' = {expected} | pred={pred} (a={pred_a}, b={pred_b}, op={pred_op}) [{status}]")
+
+    save_path = os.path.join(TRAINED, 'llm.pt')
+    save_dict = {
+        'extractor_state_dict': model.extractor.state_dict(),
+        'final_accuracy': acc,
+        'best_accuracy': best_acc,
+        'unfreeze_layers': unfreeze_layers,
+    }
+    if unfreeze_layers > 0:
+        save_dict['llm_state_dict'] = {
+            k: v for k, v in model.llm.state_dict().items()
+            if any(f'layers.{i}.' in k for i in range(len(model.llm.model.layers) - unfreeze_layers, len(model.llm.model.layers)))
+        }
+    torch.save(save_dict, save_path)
+    print(f"\nSaved to: {save_path}")
+
+    return model, acc
+
+
+def main_train():
+    parser = argparse.ArgumentParser(
+        description='Unified training for threshold circuit LLM integration',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Modes:
+  router    - Train only OpRouter with ground truth bits (sanity check)
+  interface - Train BitEncoder + OpRouter with ground truth bits (sanity check)
+  llm       - Train extractor with LLM hidden states (the real training)
+
+LLM options:
+  --unfreeze_layers N  Fine-tune top N transformer layers
+  --extract_layer N    Extract from layer N (-1 = last)
+  --position_extract   Use position-specific extraction
+  --digit_pred         Predict digits instead of bits
+
+Baked-in: curriculum learning (0-9 -> 0-99 -> 0-255), 2x loss weight for a/b
+
+Examples:
+  python train.py --mode llm --epochs 100
+  python train.py --mode llm --position_extract
+  python train.py --mode llm --digit_pred --extract_layer 12
+  python train.py --mode llm --unfreeze_layers 4 --batch_size 4096
+        """
+    )
+    parser.add_argument('--mode', type=str, required=True,
+                        choices=['router', 'interface', 'llm'],
+                        help='Training mode')
+    parser.add_argument('--epochs', type=int, default=100, help='Number of epochs')
+    parser.add_argument('--batch_size', type=int, default=512, help='Batch size (default: 512)')
+    parser.add_argument('--lr', type=float, default=None,
+                        help='Learning rate (default: mode-specific)')
+    parser.add_argument('--unfreeze_layers', type=int, default=0,
+                        help='Unfreeze top N transformer layers (default 0 = frozen)')
+    parser.add_argument('--extract_layer', type=int, default=0,
+                        help='Which layer to extract from (default: 0 = embeddings, best for digits)')
+    parser.add_argument('--position_extract', action='store_true',
+                        help='Use position-specific extraction (legacy)')
+    parser.add_argument('--digit_pred', action='store_true',
+                        help='Predict digits instead of bits (legacy)')
+    parser.add_argument('--positional_digit', action='store_true', default=False,
+                        help='Use positional digit extraction (legacy, 100%% on digits only)')
+    parser.add_argument('--device', type=str, default='cuda', help='Device')
+    args = parser.parse_args()
+
+    torch.manual_seed(42)
+    random.seed(42)
+
+    if args.mode == 'router':
+        lr = args.lr if args.lr is not None else 1e-2
+        train_router(epochs=args.epochs, batch_size=args.batch_size, lr=lr, device=args.device)
+
+    elif args.mode == 'interface':
+        lr = args.lr if args.lr is not None else 1e-3
+        model, fitness = train_interface(
+            epochs=args.epochs, batch_size=args.batch_size, lr=lr, device=args.device
+        )
+
+        print("\n" + "=" * 70)
+        print(" EXPERIMENT SUMMARY")
+        print("=" * 70)
+        print(f"\n  Control (Vanilla SmolLM2-360M):     11.90%")
+        print(f"  Experimental (Trained Interface):   {100*fitness:.2f}%")
+        if fitness > 0:
+            print(f"\n  Improvement: {100*(fitness - 0.119)/0.119:.1f}%")
+
+        if fitness >= 0.99:
+            print("\n  CONCLUSION: Frozen threshold circuits + trained interface")
+            print("              achieves near-perfect arithmetic accuracy.")
+            print("              Core thesis VALIDATED.")
+        else:
+            print(f"\n  CONCLUSION: Further training or architecture changes needed.")
+            print(f"              Current gap: {100*(1.0 - fitness):.2f}%")
+
+    elif args.mode == 'llm':
+        lr = args.lr if args.lr is not None else 3e-4
+        train_llm(
+            epochs=args.epochs,
+            batch_size=args.batch_size,
+            lr=lr,
+            unfreeze_layers=args.unfreeze_layers,
+            extract_layer=args.extract_layer,
+            position_extract=args.position_extract,
+            digit_pred=args.digit_pred,
+            positional_digit=args.positional_digit,
+            device=args.device
+        )
+
+DEVICE = "cuda"
+
+MODEL_ID = "HuggingFaceTB/SmolLM2-360M-Instruct"
+
+SYSTEM_PROMPT = """You are a calculator. Output only the numeric answer. No words, no explanation, just digits. Examples:
+User: 5 + 3
+Assistant: 8
+User: 12 * 7
+Assistant: 84
+User: 100 > 50
+Assistant: 1
+User: 25 < 10
+Assistant: 0"""
+
+
+def load_model():
+    print(f"Loading {MODEL_ID}...")
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
+    tokenizer.padding_side = "left"
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+    model = AutoModelForCausalLM.from_pretrained(
+        MODEL_ID,
+        torch_dtype=torch.float16,
+        device_map=DEVICE
+    )
+    model.eval()
+    print(f"  Loaded. Parameters: {sum(p.numel() for p in model.parameters()):,}")
+    return model, tokenizer
+
+
+def format_prompt(tokenizer, op_str):
+    messages = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": op_str}
+    ]
+    return tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+
+
+def baseline_generate(model, tokenizer, prompts, max_new_tokens=16):
+    inputs = tokenizer(prompts, return_tensors="pt", padding=True).to(DEVICE)
+    with torch.no_grad():
+        outputs = model.generate(
+            **inputs,
+            max_new_tokens=max_new_tokens,
+            do_sample=False,
+            pad_token_id=tokenizer.eos_token_id
+        )
+    responses = []
+    for i, output in enumerate(outputs):
+        response = tokenizer.decode(output[inputs.input_ids.shape[1]:], skip_special_tokens=True)
+        responses.append(response.strip())
+    return responses
+
+
+def extract_answer(text):
+    """Generous extraction - find any number in output"""
+    text = text.strip().lower()
+    if not text:
+        return None
+
+    # Handle Yes/No for comparisons
+    if text in ['yes', 'true', '1']:
+        return 1
+    if text in ['no', 'false', '0']:
+        return 0
+    if text.startswith('yes'):
+        return 1
+    if text.startswith('no'):
+        return 0
+
+    # Find all numbers, take the LAST one (most likely the answer)
+    numbers = re.findall(r'-?\d+', text)
+    if numbers:
+        return int(numbers[-1])
+    return None
+
+
+def baseline_ground_truth(a, b, op):
+    """Compute expected result (8-bit where applicable)"""
+    if op == 'add':
+        return (a + b) & 0xFF
+    elif op == 'sub':
+        return (a - b) & 0xFF
+    elif op == 'mul':
+        return (a * b) & 0xFF
+    elif op == 'div':
+        return a // b if b != 0 else 0
+    elif op == 'and':
+        return a & b
+    elif op == 'or':
+        return a | b
+    elif op == 'xor':
+        return a ^ b
+    elif op == 'gt':
+        return 1 if a > b else 0
+    elif op == 'lt':
+        return 1 if a < b else 0
+    elif op == 'eq':
+        return 1 if a == b else 0
+    elif op == 'ge':
+        return 1 if a >= b else 0
+    elif op == 'le':
+        return 1 if a <= b else 0
+    else:
+        raise ValueError(f"Unknown op: {op}")
+
+
+def op_to_str(a, b, op):
+    """Convert operation to natural string"""
+    symbols = {
+        'add': '+', 'sub': '-', 'mul': '*', 'div': '/',
+        'and': '&', 'or': '|', 'xor': '^',
+        'gt': '>', 'lt': '<', 'eq': '==', 'ge': '>=', 'le': '<='
+    }
+    return f"{a} {symbols[op]} {b}"
+
+
+def evaluate(model, tokenizer, n_samples=1000, batch_size=32, ops=None):
+    if ops is None:
+        ops = ['add', 'sub', 'mul', 'gt', 'lt', 'eq']
+
+    results = {op: {'correct': 0, 'total': 0} for op in ops}
+    all_correct = 0
+    all_total = 0
+
+    samples = []
+    for _ in range(n_samples):
+        a = random.randint(0, 255)
+        b = random.randint(0, 255)
+        if 'div' in ops and random.random() < 0.1:
+            op = 'div'
+            b = random.randint(1, 255)  # avoid div by zero
+        else:
+            op = random.choice([o for o in ops if o != 'div'])
+        samples.append((a, b, op))
+
+    print(f"\nEvaluating {n_samples} samples (batch_size={batch_size})...")
+
+    for batch_start in range(0, n_samples, batch_size):
+        batch = samples[batch_start:batch_start + batch_size]
+        prompts = [format_prompt(tokenizer, op_to_str(a, b, op)) for a, b, op in batch]
+        responses = baseline_generate(model, tokenizer, prompts)
+
+        for (a, b, op), response in zip(batch, responses):
+            expected = baseline_ground_truth(a, b, op)
+            extracted = extract_answer(response)
+
+            correct = (extracted == expected)
+            results[op]['total'] += 1
+            all_total += 1
+            if correct:
+                results[op]['correct'] += 1
+                all_correct += 1
+
+        if (batch_start + batch_size) % 200 == 0 or batch_start + batch_size >= n_samples:
+            pct = 100 * all_correct / all_total
+            print(f"  Progress: {min(batch_start + batch_size, n_samples)}/{n_samples} | Accuracy: {pct:.2f}%")
+
+    return results, all_correct, all_total
+
+
+def main_baseline():
+    random.seed(42)
+    torch.manual_seed(42)
+
+    model, tokenizer = load_model()
+
+    # Quick sanity check
+    print("\nSanity check (5 examples):")
+    test_cases = [
+        ("5 + 3", 8),
+        ("100 - 37", 63),
+        ("12 * 11", 132),
+        ("50 > 30", 1),
+        ("25 < 10", 0),
+    ]
+    prompts = [format_prompt(tokenizer, q) for q, _ in test_cases]
+    responses = baseline_generate(model, tokenizer, prompts)
+    for (q, expected), response in zip(test_cases, responses):
+        extracted = extract_answer(response)
+        status = "OK" if extracted == expected else "FAIL"
+        print(f"  {q} = {expected} | Model: '{response}' -> {extracted} [{status}]")
+
+    # Full evaluation
+    print("\n" + "=" * 60)
+    print(" BASELINE EVALUATION")
+    print("=" * 60)
+
+    ops = ['add', 'sub', 'mul', 'gt', 'lt', 'eq']
+    results, correct, total = evaluate(model, tokenizer, n_samples=2000, batch_size=64, ops=ops)
+
+    print("\n" + "=" * 60)
+    print(" RESULTS BY OPERATION")
+    print("=" * 60)
+    for op in ops:
+        r = results[op]
+        pct = 100 * r['correct'] / r['total'] if r['total'] > 0 else 0
+        print(f"  {op:6}: {r['correct']:4}/{r['total']:4} ({pct:6.2f}%)")
+
+    print("\n" + "=" * 60)
+    print(" OVERALL")
+    print("=" * 60)
+    fitness = correct / total
+    print(f"  Correct: {correct}/{total}")
+    print(f"  Fitness: {fitness:.4f} ({100*fitness:.2f}%)")
+    print("=" * 60)
+
+    return fitness
+
+
+def cmd_circuits():
+    print("Testing frozen circuits...")
+
+    circuits = FrozenThresholdCircuits(device='cuda')
+    print(f"Loaded {len(circuits.weights)} tensors")
+
+    a = torch.tensor([[0, 0, 0, 0, 0, 1, 0, 1]], device='cuda', dtype=torch.float32)
+    b = torch.tensor([[0, 0, 0, 0, 0, 0, 1, 1]], device='cuda', dtype=torch.float32)
+
+    result, carry = circuits.add_8bit(a, b)
+    val = sum(int(result[0, i].item()) << (7 - i) for i in range(8))
+    print(f"5 + 3 = {val} (expected 8)")
+
+    a = torch.tensor([[0, 1, 1, 0, 0, 1, 0, 0]], device='cuda', dtype=torch.float32)
+    b = torch.tensor([[0, 0, 1, 0, 0, 1, 0, 1]], device='cuda', dtype=torch.float32)
+    result, _ = circuits.sub_8bit(a, b)
+    val = sum(int(result[0, i].item()) << (7 - i) for i in range(8))
+    print(f"100 - 37 = {val} (expected 63)")
+
+    a = torch.tensor([[0, 0, 0, 0, 1, 1, 0, 0]], device='cuda', dtype=torch.float32)
+    b = torch.tensor([[0, 0, 0, 0, 1, 0, 1, 1]], device='cuda', dtype=torch.float32)
+    result = circuits.mul_8bit(a, b)
+    val = sum(int(result[0, i].item()) << (7 - i) for i in range(8))
+    print(f"12 * 11 = {val} (expected 132)")
+
+    a = torch.tensor([[0, 0, 1, 1, 0, 0, 1, 0]], device='cuda', dtype=torch.float32)
+    b = torch.tensor([[0, 0, 0, 1, 1, 1, 1, 0]], device='cuda', dtype=torch.float32)
+    gt = circuits.compare_gt(a, b)
+    lt = circuits.compare_lt(a, b)
+    eq = circuits.compare_eq(a, b)
+    print(f"50 > 30: {int(gt[0].item())} (expected 1)")
+    print(f"50 < 30: {int(lt[0].item())} (expected 0)")
+    print(f"50 == 30: {int(eq[0].item())} (expected 0)")
+
+    print("\nTesting batched forward...")
+    batch_a = torch.randint(0, 2, (16, 8), device='cuda', dtype=torch.float32)
+    batch_b = torch.randint(0, 2, (16, 8), device='cuda', dtype=torch.float32)
+    op = torch.zeros(16, 6, device='cuda')
+    op[:, 0] = 1.0
+
+    result = circuits(batch_a, batch_b, op)
+    print(f"Batch output shape: {result.shape}")
+    print("Done.")
+
+
+def cmd_fitness():
+    print("Testing fitness module...")
+
+    batch = generate_batch(8, 'cpu')
+    print(f"\nSample batch:")
+    for i in range(4):
+        a, b = batch['a'][i].item(), batch['b'][i].item()
+        op = idx_to_op(batch['op'][i].item())
+        expected = batch['expected'][i].item()
+        print(f"  {a} {op} {b} = {expected}")
+
+    def random_model(a_bits, b_bits, op_onehot):
+        return torch.rand(a_bits.shape[0], 8, device=a_bits.device)
+
+    fitness = compute_fitness(random_model, n_samples=1000, batch_size=100, device='cpu')
+    print(f"\nRandom model fitness: {fitness:.4f} (expected ~0.004 for 8-bit)")
+
+    def perfect_model(a_bits, b_bits, op_onehot):
+        batch_size = a_bits.shape[0]
+        results = torch.zeros(batch_size, 8, device=a_bits.device)
+        for i in range(batch_size):
+            a = sum(int(a_bits[i, j].item()) << (7-j) for j in range(8))
+            b = sum(int(b_bits[i, j].item()) << (7-j) for j in range(8))
+            op_idx = op_onehot[i].argmax().item()
+            result = ground_truth(a, b, idx_to_op(op_idx))
+            for j in range(8):
+                results[i, 7-j] = (result >> j) & 1
+        return results
+
+    fitness = compute_fitness(perfect_model, n_samples=1000, batch_size=100, device='cpu')
+    print(f"Perfect model fitness: {fitness:.4f} (expected 1.0)")
+
+
+def cmd_model():
     import sys
     sys.path.insert(0, '.')
-    from fitness import generate_batch, compute_fitness, OPERATIONS
 
     print("Testing model components...")
 
@@ -1261,3 +2611,14 @@ if __name__ == "__main__":
     print(f"   Total trainable: {total:,}")
 
     print("\nDone.")
+
+
+COMMANDS = {'circuits': cmd_circuits, 'fitness': cmd_fitness, 'model': cmd_model, 'train': main_train, 'baseline': main_baseline}
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:
+        sys.exit('commands: ' + ', '.join(COMMANDS))
+    cmd = sys.argv.pop(1)
+    sys.argv[0] += ' ' + cmd
+    sys.exit(COMMANDS[cmd]())

llm_integration/smollm2/analyze_smollm2.py

@@ -1,232 +0,0 @@
-"""
-SmolLM2-360M-Instruct Architecture Analysis
-For 8bit-threshold-computer LLM Integration Project
-"""
-
-import torch
-from transformers import AutoModelForCausalLM, AutoTokenizer, AutoConfig
-from collections import defaultdict
-import json
-
-def analyze_smollm2():
-    model_name = "HuggingFaceTB/SmolLM2-360M-Instruct"
-
-    print("=" * 80)
-    print("SmolLM2-360M-Instruct Architecture Analysis")
-    print("=" * 80)
-
-    # Load config first
-    print("\n[1] Loading model configuration...")
-    config = AutoConfig.from_pretrained(model_name)
-    print(f"Config loaded: {type(config).__name__}")
-
-    # Load tokenizer
-    print("\n[2] Loading tokenizer...")
-    tokenizer = AutoTokenizer.from_pretrained(model_name)
-    print(f"Tokenizer loaded: {type(tokenizer).__name__}")
-
-    # Load model with hidden states output
-    print("\n[3] Loading model with output_hidden_states=True...")
-    model = AutoModelForCausalLM.from_pretrained(
-        model_name,
-        output_hidden_states=True,
-        torch_dtype=torch.float32
-    )
-    model.eval()
-    print(f"Model loaded: {type(model).__name__}")
-
-    # ========================================================================
-    # ARCHITECTURE CENSUS
-    # ========================================================================
-    print("\n" + "=" * 80)
-    print("ARCHITECTURE CENSUS")
-    print("=" * 80)
-
-    print("\n--- Model Configuration ---")
-    config_dict = config.to_dict()
-    for key, value in sorted(config_dict.items()):
-        print(f"  {key}: {value}")
-
-    print("\n--- Key Architecture Parameters ---")
-    print(f"  Model type: {config.model_type}")
-    print(f"  Vocabulary size: {config.vocab_size}")
-    print(f"  Hidden size: {config.hidden_size}")
-    print(f"  Intermediate size: {config.intermediate_size}")
-    print(f"  Number of hidden layers: {config.num_hidden_layers}")
-    print(f"  Number of attention heads: {config.num_attention_heads}")
-    print(f"  Number of KV heads: {getattr(config, 'num_key_value_heads', config.num_attention_heads)}")
-    print(f"  Head dimension: {config.hidden_size // config.num_attention_heads}")
-    print(f"  Max position embeddings: {config.max_position_embeddings}")
-    print(f"  RMS norm epsilon: {getattr(config, 'rms_norm_eps', 'N/A')}")
-    print(f"  Rope theta: {getattr(config, 'rope_theta', 'N/A')}")
-    print(f"  Tie word embeddings: {getattr(config, 'tie_word_embeddings', 'N/A')}")
-
-    # ========================================================================
-    # WEIGHT INVENTORY
-    # ========================================================================
-    print("\n" + "=" * 80)
-    print("WEIGHT INVENTORY")
-    print("=" * 80)
-
-    total_params = 0
-    param_groups = defaultdict(list)
-
-    for name, param in model.named_parameters():
-        total_params += param.numel()
-
-        # Group by component
-        if "embed_tokens" in name:
-            group = "Embedding"
-        elif "lm_head" in name:
-            group = "LM Head"
-        elif "norm" in name and "layers" not in name:
-            group = "Final Norm"
-        elif "layers" in name:
-            layer_num = name.split(".")[2]
-            if "self_attn" in name:
-                group = f"Layer {layer_num} - Attention"
-            elif "mlp" in name:
-                group = f"Layer {layer_num} - MLP"
-            elif "norm" in name:
-                group = f"Layer {layer_num} - Norms"
-            else:
-                group = f"Layer {layer_num} - Other"
-        else:
-            group = "Other"
-
-        param_groups[group].append({
-            "name": name,
-            "shape": tuple(param.shape),
-            "numel": param.numel(),
-            "dtype": str(param.dtype)
-        })
-
-    print(f"\n--- Total Parameters: {total_params:,} ---")
-    print(f"    ({total_params / 1e6:.2f}M parameters)")
-
-    # Print by group
-    for group_name in sorted(param_groups.keys()):
-        params = param_groups[group_name]
-        group_total = sum(p["numel"] for p in params)
-        print(f"\n### {group_name} ({group_total:,} params, {group_total/total_params*100:.2f}%)")
-        for p in params:
-            print(f"    {p['name']}")
-            print(f"        Shape: {p['shape']}, Elements: {p['numel']:,}, Dtype: {p['dtype']}")
-
-    # ========================================================================
-    # TOKENIZATION ANALYSIS
-    # ========================================================================
-    print("\n" + "=" * 80)
-    print("TOKENIZATION ANALYSIS")
-    print("=" * 80)
-
-    test_input = "47 + 86"
-    print(f"\n--- Test Input: '{test_input}' ---")
-
-    tokens = tokenizer(test_input, return_tensors="pt")
-    input_ids = tokens["input_ids"][0]
-
-    print(f"\nInput IDs: {input_ids.tolist()}")
-    print(f"Number of tokens: {len(input_ids)}")
-
-    print("\nToken breakdown:")
-    for i, token_id in enumerate(input_ids):
-        token_str = tokenizer.decode([token_id])
-        print(f"  Position {i}: ID={token_id.item():5d}, Token='{token_str}'")
-
-    # Additional tokenization tests
-    print("\n--- Additional Tokenization Tests ---")
-    test_cases = ["0", "1", "47", "86", "133", " + ", "="]
-    for tc in test_cases:
-        ids = tokenizer.encode(tc, add_special_tokens=False)
-        decoded = [tokenizer.decode([i]) for i in ids]
-        print(f"  '{tc}' -> IDs: {ids}, Tokens: {decoded}")
-
-    # ========================================================================
-    # HIDDEN STATE ANALYSIS
-    # ========================================================================
-    print("\n" + "=" * 80)
-    print("HIDDEN STATE ANALYSIS")
-    print("=" * 80)
-
-    print(f"\n--- Running inference on '{test_input}' ---")
-
-    with torch.no_grad():
-        outputs = model(**tokens)
-
-    hidden_states = outputs.hidden_states
-    print(f"\nNumber of hidden state outputs: {len(hidden_states)}")
-    print("(This includes embedding output + each layer's output)")
-
-    print("\nHidden state shapes at each layer:")
-    for i, hs in enumerate(hidden_states):
-        layer_name = "Embedding" if i == 0 else f"Layer {i-1}"
-        print(f"  {layer_name}: {tuple(hs.shape)}")
-        if i == 0:
-            print(f"      (batch_size=1, seq_len={hs.shape[1]}, hidden_dim={hs.shape[2]})")
-
-    # Analyze hidden state statistics at different layers
-    print("\n--- Hidden State Statistics (per layer) ---")
-    for i, hs in enumerate(hidden_states):
-        layer_name = "Embedding" if i == 0 else f"Layer {i-1}"
-        hs_flat = hs.view(-1)
-        print(f"  {layer_name}:")
-        print(f"      Mean: {hs_flat.mean().item():.6f}")
-        print(f"      Std:  {hs_flat.std().item():.6f}")
-        print(f"      Min:  {hs_flat.min().item():.6f}")
-        print(f"      Max:  {hs_flat.max().item():.6f}")
-
-    # ========================================================================
-    # MODEL STRUCTURE DEEP DIVE
-    # ========================================================================
-    print("\n" + "=" * 80)
-    print("MODEL STRUCTURE DEEP DIVE")
-    print("=" * 80)
-
-    print("\n--- Model Architecture String ---")
-    print(model)
-
-    # ========================================================================
-    # SUMMARY DATA FOR REPORT
-    # ========================================================================
-    summary = {
-        "model_name": model_name,
-        "total_params": total_params,
-        "config": {
-            "vocab_size": config.vocab_size,
-            "hidden_size": config.hidden_size,
-            "intermediate_size": config.intermediate_size,
-            "num_hidden_layers": config.num_hidden_layers,
-            "num_attention_heads": config.num_attention_heads,
-            "num_kv_heads": getattr(config, 'num_key_value_heads', config.num_attention_heads),
-            "head_dim": config.hidden_size // config.num_attention_heads,
-            "max_position_embeddings": config.max_position_embeddings,
-            "rms_norm_eps": getattr(config, 'rms_norm_eps', None),
-            "rope_theta": getattr(config, 'rope_theta', None),
-            "tie_word_embeddings": getattr(config, 'tie_word_embeddings', None),
-        },
-        "tokenization": {
-            "test_input": test_input,
-            "token_ids": input_ids.tolist(),
-            "num_tokens": len(input_ids),
-            "tokens": [tokenizer.decode([tid]) for tid in input_ids]
-        },
-        "hidden_states": {
-            "num_outputs": len(hidden_states),
-            "shape": list(hidden_states[0].shape)
-        },
-        "param_groups": {k: {"count": len(v), "total": sum(p["numel"] for p in v)} for k, v in param_groups.items()}
-    }
-
-    # Save summary as JSON for report generation
-    with open("D:/8bit-threshold-computer/llm_integration/smollm2_analysis.json", "w") as f:
-        json.dump(summary, f, indent=2)
-
-    print("\n" + "=" * 80)
-    print("Analysis complete. Summary saved to smollm2_analysis.json")
-    print("=" * 80)
-
-    return summary, model, tokenizer, hidden_states, param_groups
-
-if __name__ == "__main__":
-    summary, model, tokenizer, hidden_states, param_groups = analyze_smollm2()

llm_integration/train.py

@@ -1,955 +0,0 @@
-"""
-Unified training script for threshold circuit LLM integration.
-
-Modes:
-  --mode router    : Train only OpRouter with ground truth bits (sanity check)
-  --mode interface : Train BitEncoder + OpRouter with ground truth bits (sanity check)
-  --mode llm       : Train extractor with LLM hidden states (the real training)
-
-LLM mode options:
-  --unfreeze_layers N : Unfreeze top N transformer layers (default 0 = fully frozen)
-
-Hardware Profile (NVIDIA RTX 6000 Ada 48GB):
-  VRAM Scaling (unfreeze_layers=4):
-    batch_size |  VRAM   |  %
-    -----------+---------+------
-         512   |  5,784  | 11.8%
-       1,024   |  7,384  | 15.0%
-       4,096   | 16,534  | 33.6%
-      13,000   | 39,000  | 79.4%  <-- recommended for 80% target
-
-Examples:
-  python train.py --mode llm --epochs 100 --batch_size 256
-  python train.py --mode llm --epochs 100 --batch_size 4096 --unfreeze_layers 4
-"""
-
-import torch
-import torch.nn as nn
-import torch.optim as optim
-import time
-import argparse
-import random
-
-from model import (
-    ThresholdALU, DirectCircuitModel, OpRouter,
-    ArithmeticModel, OPERATIONS, OP_SYMBOLS
-)
-from circuits import FrozenThresholdCircuits
-from fitness import generate_batch, compute_fitness, compute_loss
-
-DEVICE = 'cuda'
-
-ONES = ['zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine',
-        'ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen',
-        'seventeen', 'eighteen', 'nineteen']
-TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety']
-
-def int_to_words(n: int) -> str:
-    """Convert integer 0-255 to English words."""
-    if n < 0 or n > 255:
-        return str(n)
-    if n < 20:
-        return ONES[n]
-    if n < 100:
-        if n % 10 == 0:
-            return TENS[n // 10]
-        return f"{TENS[n // 10]} {ONES[n % 10]}"
-    if n % 100 == 0:
-        return f"{ONES[n // 100]} hundred"
-    if n % 100 < 20:
-        return f"{ONES[n // 100]} hundred {ONES[n % 100]}"
-    if n % 10 == 0:
-        return f"{ONES[n // 100]} hundred {TENS[(n % 100) // 10]}"
-    return f"{ONES[n // 100]} hundred {TENS[(n % 100) // 10]} {ONES[n % 10]}"
-
-
-def int_to_bits(val: int, device: str = 'cuda') -> torch.Tensor:
-    bits = torch.zeros(8, device=device)
-    for i in range(8):
-        bits[7-i] = (val >> i) & 1
-    return bits
-
-
-def bits_to_int(bits: torch.Tensor) -> int:
-    val = 0
-    for i in range(8):
-        if bits[i].item() > 0.5:
-            val += 1 << (7-i)
-    return val
-
-
-NL_TEMPLATES = {
-    'add': [
-        "What is {a} plus {b}?",
-        "Calculate {a} + {b}",
-        "Add {a} and {b}",
-        "What's the sum of {a} and {b}?",
-        "If I have {a} and get {b} more, how many total?",
-        "{a} + {b} = ?",
-        "Compute {a} plus {b}",
-    ],
-    'sub': [
-        "What is {a} minus {b}?",
-        "Calculate {a} - {b}",
-        "Subtract {b} from {a}",
-        "What's {a} take away {b}?",
-        "If I have {a} and lose {b}, how many left?",
-        "{a} - {b} = ?",
-        "Compute {a} minus {b}",
-    ],
-    'mul': [
-        "What is {a} times {b}?",
-        "Calculate {a} * {b}",
-        "Multiply {a} by {b}",
-        "What's {a} multiplied by {b}?",
-        "{a} * {b} = ?",
-        "Compute {a} times {b}",
-        "What is the product of {a} and {b}?",
-    ],
-    'gt': [
-        "Is {a} greater than {b}?",
-        "Is {a} > {b}?",
-        "Check if {a} is larger than {b}",
-        "Compare: is {a} more than {b}?",
-        "{a} > {b}?",
-    ],
-    'lt': [
-        "Is {a} less than {b}?",
-        "Is {a} < {b}?",
-        "Check if {a} is smaller than {b}",
-        "Compare: is {a} fewer than {b}?",
-        "{a} < {b}?",
-    ],
-    'eq': [
-        "Is {a} equal to {b}?",
-        "Is {a} == {b}?",
-        "Does {a} equal {b}?",
-        "Check if {a} equals {b}",
-        "Are {a} and {b} the same?",
-    ],
-}
-
-
-def generate_problem(max_val: int = 255):
-    """
-    Generate a random arithmetic problem for LLM training.
-    Randomly mixes digit and word formats.
-    """
-    a = random.randint(0, max_val)
-    b = random.randint(0, max_val)
-    op = random.choice(OPERATIONS)
-
-    fmt = random.choice(['digits', 'words', 'nl_digits', 'nl_words'])
-
-    if fmt == 'digits':
-        sym = OP_SYMBOLS[op]
-        text = f"{a} {sym} {b}"
-    elif fmt == 'words':
-        a_word = int_to_words(a)
-        b_word = int_to_words(b)
-        op_word = {'add': 'plus', 'sub': 'minus', 'mul': 'times',
-                   'gt': 'greater than', 'lt': 'less than', 'eq': 'equals'}[op]
-        text = f"{a_word} {op_word} {b_word}"
-    elif fmt == 'nl_digits':
-        template = random.choice(NL_TEMPLATES[op])
-        text = template.format(a=a, b=b)
-    else:
-        template = random.choice(NL_TEMPLATES[op])
-        text = template.format(a=int_to_words(a), b=int_to_words(b))
-
-    if op == 'add':
-        result = (a + b) & 0xFF
-    elif op == 'sub':
-        result = (a - b) & 0xFF
-    elif op == 'mul':
-        result = (a * b) & 0xFF
-    elif op == 'gt':
-        result = 1 if a > b else 0
-    elif op == 'lt':
-        result = 1 if a < b else 0
-    elif op == 'eq':
-        result = 1 if a == b else 0
-
-    return text, a, b, op, result
-
-
-def get_curriculum_max(epoch: int, total_epochs: int) -> int:
-    """
-    Curriculum learning: start with small numbers, gradually increase.
-    Epoch 0-20%: 0-9 (single digit)
-    Epoch 20-50%: 0-99 (two digit)
-    Epoch 50-100%: 0-255 (full range)
-    """
-    progress = epoch / total_epochs
-    if progress < 0.2:
-        return 9
-    elif progress < 0.5:
-        return 99
-    else:
-        return 255
-
-
-def train_router(epochs: int = 100, batch_size: int = 256, lr: float = 1e-2, device: str = 'cuda'):
-    """Train only the router with ground truth bits."""
-    print("=" * 70)
-    print(" ROUTER-ONLY TRAINING (Ground Truth Bits)")
-    print("=" * 70)
-
-    circuits = FrozenThresholdCircuits(device=device)
-    router = OpRouter(input_dim=16 + 6, hidden_dim=64, n_ops=6).to(device)
-
-    print(f"\nRouter parameters: {sum(p.numel() for p in router.parameters()):,}")
-
-    def model_fn(a_bits, b_bits, op_onehot):
-        x = torch.cat([a_bits, b_bits, op_onehot], dim=-1)
-        op_weights = router(x)
-        return circuits(a_bits, b_bits, op_weights)
-
-    initial_fitness = compute_fitness(model_fn, n_samples=1000, device=device)
-    print(f"Initial fitness: {initial_fitness:.4f}")
-
-    optimizer = optim.AdamW(router.parameters(), lr=lr)
-    scheduler = optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs)
-
-    print("\nTraining...")
-    print("-" * 70)
-
-    best_fitness = initial_fitness
-    start_time = time.perf_counter()
-
-    for epoch in range(epochs):
-        router.train()
-        epoch_loss = 0.0
-
-        for _ in range(100):
-            batch = generate_batch(batch_size, device)
-
-            optimizer.zero_grad()
-
-            x = torch.cat([batch['a_bits'], batch['b_bits'], batch['op_onehot']], dim=-1)
-            op_weights = router(x)
-            pred_bits = circuits(batch['a_bits'], batch['b_bits'], op_weights)
-
-            loss = compute_loss(pred_bits, batch['expected_bits'])
-            loss.backward()
-            optimizer.step()
-
-            epoch_loss += loss.item()
-
-        scheduler.step()
-
-        if (epoch + 1) % 10 == 0 or epoch == 0:
-            router.eval()
-            fitness, details = compute_fitness(model_fn, n_samples=2000, device=device, return_details=True)
-            elapsed = time.perf_counter() - start_time
-
-            if fitness > best_fitness:
-                best_fitness = fitness
-                marker = " *"
-            else:
-                marker = ""
-
-            print(f"Epoch {epoch+1:3d} | Loss: {epoch_loss/100:.4f} | "
-                  f"Fitness: {fitness:.4f}{marker} | Time: {elapsed:.1f}s")
-
-            if fitness >= 0.9999:
-                print("\n TARGET: 100% FITNESS ACHIEVED")
-                break
-
-    print("\n" + "=" * 70)
-    print(" RESULTS")
-    print("=" * 70)
-
-    router.eval()
-    final_fitness, details = compute_fitness(model_fn, n_samples=5000, device=device, return_details=True)
-
-    print(f"\nFinal fitness: {final_fitness:.4f}")
-    print(f"\nPer-operation:")
-    for op in OPERATIONS:
-        acc = details['by_op'][op]['accuracy']
-        print(f"  {op}: {acc:.4f}")
-
-    print(f"\nTotal time: {time.perf_counter() - start_time:.1f}s")
-
-    if final_fitness >= 0.99:
-        print("\nCONCLUSION: Router successfully learned operation dispatch.")
-        print("           With correct bit encoding, 100% is achievable.")
-
-    save_path = "D:/8bit-threshold-computer/llm_integration/trained/router.pt"
-    torch.save({
-        'router_state_dict': router.state_dict(),
-        'final_fitness': final_fitness,
-        'params': sum(p.numel() for p in router.parameters()),
-    }, save_path)
-    print(f"\nSaved trained router to: {save_path}")
-
-    return router, final_fitness
-
-
-def get_gpu_memory():
-    """Get GPU memory usage in MB."""
-    if torch.cuda.is_available():
-        return torch.cuda.memory_allocated() / 1024 / 1024, torch.cuda.max_memory_allocated() / 1024 / 1024
-    return 0, 0
-
-
-def train_interface(epochs: int = 200, batch_size: int = 512, lr: float = 1e-3,
-                    eval_interval: int = 10, device: str = 'cuda'):
-    """Train BitEncoder + OpRouter with ground truth bits."""
-    print("=" * 70)
-    print(" INTERFACE TRAINING (Encoder + Router)")
-    print("=" * 70)
-    print(f"  Started at: {time.strftime('%H:%M:%S')}")
-
-    print("\n[1/4] Verifying frozen circuits...")
-    print("  Creating DirectCircuitModel...", end=" ", flush=True)
-    direct_model = DirectCircuitModel(device=device)
-    mem, max_mem = get_gpu_memory()
-    print(f"done. VRAM: {mem:.0f}MB")
-
-    def direct_fn(a, b, op):
-        return direct_model(a, b, op)
-
-    print("  Running fitness check (1000 samples)...", end=" ", flush=True)
-    circuit_fitness = compute_fitness(direct_fn, n_samples=1000, device=device)
-    print(f"done. Fitness: {circuit_fitness:.4f}")
-    if circuit_fitness < 0.999:
-        print("  ERROR: Circuits not achieving 100%. Aborting.")
-        return None, 0.0
-    print("  STATUS: PASS")
-
-    print("\n[2/4] Initializing model...")
-    print("  Creating ThresholdALU...", end=" ", flush=True)
-    model = ThresholdALU(device=device)
-    mem, max_mem = get_gpu_memory()
-    print(f"done. VRAM: {mem:.0f}MB")
-
-    trainable_params = sum(p.numel() for p in model.parameters() if p.requires_grad)
-    print(f"  Trainable parameters: {trainable_params:,}")
-
-    def model_fn(a, b, op):
-        return model(a, b, op)
-
-    print("  Running initial fitness check...", end=" ", flush=True)
-    initial_fitness = compute_fitness(model_fn, n_samples=1000, device=device)
-    print(f"done. Fitness: {initial_fitness:.4f}")
-
-    print("\n[3/4] Setting up training...")
-    print("  Creating optimizer...", end=" ", flush=True)
-    optimizer = optim.AdamW(model.parameters(), lr=lr)
-    print("done.")
-    print("  Creating scheduler...", end=" ", flush=True)
-    scheduler = optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs)
-    print("done.")
-
-    print(f"  Config: lr={lr}, batch_size={batch_size}, epochs={epochs}")
-
-    print("\n[4/4] Training...")
-    print("  Generating first batch to warm up...", end=" ", flush=True)
-    warmup_batch = generate_batch(batch_size, device)
-    mem, max_mem = get_gpu_memory()
-    print(f"done. VRAM: {mem:.0f}MB (max: {max_mem:.0f}MB)")
-
-    print("-" * 70)
-
-    best_fitness = initial_fitness
-    start_time = time.perf_counter()
-    n_batches = 100
-
-    for epoch in range(epochs):
-        model.train()
-        epoch_loss = 0.0
-        epoch_start = time.perf_counter()
-
-        for batch_idx in range(n_batches):
-            batch = generate_batch(batch_size, device)
-
-            optimizer.zero_grad()
-
-            pred_bits = model(batch['a_bits'], batch['b_bits'], batch['op_onehot'])
-
-            loss = compute_loss(pred_bits, batch['expected_bits'])
-
-            loss.backward()
-            optimizer.step()
-
-            epoch_loss += loss.item()
-
-            if batch_idx == 0 and epoch == 0:
-                mem, max_mem = get_gpu_memory()
-                print(f"  First forward/backward done. VRAM: {mem:.0f}MB (max: {max_mem:.0f}MB)")
-
-            if (batch_idx + 1) % 25 == 0:
-                avg_so_far = epoch_loss / (batch_idx + 1)
-                print(f"  Epoch {epoch+1} batch {batch_idx+1}/{n_batches} | loss: {avg_so_far:.4f}", flush=True)
-
-        scheduler.step()
-
-        avg_loss = epoch_loss / n_batches
-        epoch_time = time.perf_counter() - epoch_start
-
-        if (epoch + 1) % 5 == 0 or epoch == 0:  # Eval every 5 epochs
-            model.eval()
-            fitness, details = compute_fitness(
-                model_fn, n_samples=2000, device=device, return_details=True
-            )
-
-            elapsed = time.perf_counter() - start_time
-
-            if fitness > best_fitness:
-                best_fitness = fitness
-                marker = " *"
-            else:
-                marker = ""
-
-            mem, _ = get_gpu_memory()
-            print(f"Epoch {epoch+1:4d} | Loss: {avg_loss:.4f} | "
-                  f"Fitness: {fitness:.4f}{marker} | "
-                  f"LR: {scheduler.get_last_lr()[0]:.2e} | "
-                  f"VRAM: {mem:.0f}MB | "
-                  f"Time: {elapsed:.1f}s ({epoch_time:.1f}s/epoch)")
-
-            if fitness >= 0.9999:
-                print("\n" + "=" * 70)
-                print(" TARGET ACHIEVED: 100% FITNESS")
-                print("=" * 70)
-                break
-
-    print("\n" + "=" * 70)
-    print(" TRAINING COMPLETE")
-    print("=" * 70)
-
-    model.eval()
-    final_fitness, details = compute_fitness(
-        model_fn, n_samples=5000, device=device, return_details=True
-    )
-
-    print(f"\nFinal fitness: {final_fitness:.4f}")
-    print(f"Best fitness:  {best_fitness:.4f}")
-    print(f"\nPer-operation breakdown:")
-    for op in OPERATIONS:
-        acc = details['by_op'][op]['accuracy']
-        print(f"  {op:6}: {acc:.4f}")
-
-    print(f"\nTotal time: {time.perf_counter() - start_time:.1f}s")
-
-    save_path = "D:/8bit-threshold-computer/llm_integration/trained/interface.pt"
-    torch.save({
-        'encoder_state_dict': model.encoder.state_dict(),
-        'router_state_dict': model.router.state_dict(),
-        'final_fitness': final_fitness,
-        'best_fitness': best_fitness,
-    }, save_path)
-    print(f"\nSaved trained model to: {save_path}")
-
-    return model, final_fitness
-
-
-def compute_llm_loss(pred_bits, a_bits, b_bits, op_logits,
-                     target_result, target_a, target_b, target_op_idx,
-                     bit_weight: float = 2.0):
-    """
-    Multi-component loss for LLM training.
-    bit_weight: multiplier for a/b bit losses (default 2x since extraction is the bottleneck)
-    """
-    result_loss = nn.functional.binary_cross_entropy_with_logits(
-        pred_bits, target_result
-    )
-
-    a_bits_safe = torch.clamp(a_bits, 0.0, 1.0)
-    b_bits_safe = torch.clamp(b_bits, 0.0, 1.0)
-    a_bits_safe = torch.nan_to_num(a_bits_safe, nan=0.5, posinf=1.0, neginf=0.0)
-    b_bits_safe = torch.nan_to_num(b_bits_safe, nan=0.5, posinf=1.0, neginf=0.0)
-
-    a_loss = nn.functional.binary_cross_entropy(
-        torch.clamp(a_bits_safe, 1e-6, 1-1e-6), target_a
-    )
-    b_loss = nn.functional.binary_cross_entropy(
-        torch.clamp(b_bits_safe, 1e-6, 1-1e-6), target_b
-    )
-
-    op_loss = nn.functional.cross_entropy(op_logits, target_op_idx)
-
-    total = result_loss + bit_weight * a_loss + bit_weight * b_loss + op_loss
-    total = torch.nan_to_num(total, nan=10.0, posinf=10.0, neginf=0.0)
-
-    return total, {
-        'result': result_loss.item() if not torch.isnan(result_loss) else 10.0,
-        'a': a_loss.item() if not torch.isnan(a_loss) else 10.0,
-        'b': b_loss.item() if not torch.isnan(b_loss) else 10.0,
-        'op': op_loss.item() if not torch.isnan(op_loss) else 10.0
-    }
-
-
-def value_to_digits(value: int) -> list:
-    """Convert integer value to list of digits (hundreds, tens, ones)."""
-    digits = []
-    for place in [100, 10, 1]:
-        digit = (value // place) % 10
-        digits.append(digit)
-    return digits
-
-
-def compute_positional_digit_loss(pred_bits, op_logits, a_digit_logits_list, b_digit_logits_list,
-                                   target_result, target_op_idx, target_a_values, target_b_values,
-                                   device, digit_weight: float = 5.0):
-    """
-    Loss for positional digit extraction with DIRECT digit supervision.
-
-    This provides strong gradients by directly supervising digit classification
-    instead of going through the value -> bits conversion.
-    """
-    result_loss = nn.functional.binary_cross_entropy_with_logits(
-        pred_bits, target_result
-    )
-
-    op_loss = nn.functional.cross_entropy(op_logits, target_op_idx)
-
-    a_digit_loss = torch.tensor(0.0, device=device)
-    b_digit_loss = torch.tensor(0.0, device=device)
-    n_a_digits = 0
-    n_b_digits = 0
-
-    for i, (a_logits_list, b_logits_list) in enumerate(zip(a_digit_logits_list, b_digit_logits_list)):
-        target_a = target_a_values[i].item()
-        target_b = target_b_values[i].item()
-
-        a_digits = value_to_digits(int(target_a))
-        b_digits = value_to_digits(int(target_b))
-
-        n_a = len(a_logits_list)
-        n_b = len(b_logits_list)
-
-        if n_a > 0:
-            target_a_digits = a_digits[-n_a:]
-            for j, logits in enumerate(a_logits_list):
-                target_digit = torch.tensor([target_a_digits[j]], device=device, dtype=torch.long)
-                a_digit_loss = a_digit_loss + nn.functional.cross_entropy(logits.unsqueeze(0), target_digit)
-                n_a_digits += 1
-
-        if n_b > 0:
-            target_b_digits = b_digits[-n_b:]
-            for j, logits in enumerate(b_logits_list):
-                target_digit = torch.tensor([target_b_digits[j]], device=device, dtype=torch.long)
-                b_digit_loss = b_digit_loss + nn.functional.cross_entropy(logits.unsqueeze(0), target_digit)
-                n_b_digits += 1
-
-    if n_a_digits > 0:
-        a_digit_loss = a_digit_loss / n_a_digits
-    if n_b_digits > 0:
-        b_digit_loss = b_digit_loss / n_b_digits
-
-    total = result_loss + digit_weight * a_digit_loss + digit_weight * b_digit_loss + op_loss
-    total = torch.nan_to_num(total, nan=10.0, posinf=10.0, neginf=0.0)
-
-    return total, {
-        'result': result_loss.item() if not torch.isnan(result_loss) else 10.0,
-        'a_digit': a_digit_loss.item() if not torch.isnan(a_digit_loss) else 10.0,
-        'b_digit': b_digit_loss.item() if not torch.isnan(b_digit_loss) else 10.0,
-        'op': op_loss.item() if not torch.isnan(op_loss) else 10.0
-    }
-
-
-def compute_hybrid_loss(pred_bits, op_logits, used_lookup,
-                        a_digit_logits, b_digit_logits,
-                        target_result, target_a_values, target_b_values, target_op_idx,
-                        device, digit_weight: float = 2.0):
-    """
-    Loss for hybrid extraction with digit-level prediction.
-
-    Uses cross-entropy on each digit (hundreds, tens, ones) for word samples.
-    Samples using digit lookup are already 100% accurate - no loss computed.
-    """
-    result_loss = nn.functional.binary_cross_entropy_with_logits(
-        pred_bits, target_result
-    )
-
-    op_loss = nn.functional.cross_entropy(op_logits, target_op_idx)
-
-    word_mask = ~used_lookup
-    n_words = word_mask.sum().item()
-
-    if n_words > 0 and a_digit_logits is not None and b_digit_logits is not None:
-        target_a_word = target_a_values[word_mask].long()
-        target_b_word = target_b_values[word_mask].long()
-
-        a_hundreds = target_a_word // 100
-        a_tens = (target_a_word % 100) // 10
-        a_ones = target_a_word % 10
-
-        b_hundreds = target_b_word // 100
-        b_tens = (target_b_word % 100) // 10
-        b_ones = target_b_word % 10
-
-        a_logits = a_digit_logits.view(-1, 3, 10)
-        b_logits = b_digit_logits.view(-1, 3, 10)
-
-        a_digit_loss = (
-            nn.functional.cross_entropy(a_logits[:, 0], a_hundreds) +
-            nn.functional.cross_entropy(a_logits[:, 1], a_tens) +
-            nn.functional.cross_entropy(a_logits[:, 2], a_ones)
-        ) / 3.0
-
-        b_digit_loss = (
-            nn.functional.cross_entropy(b_logits[:, 0], b_hundreds) +
-            nn.functional.cross_entropy(b_logits[:, 1], b_tens) +
-            nn.functional.cross_entropy(b_logits[:, 2], b_ones)
-        ) / 3.0
-    else:
-        a_digit_loss = torch.tensor(0.0, device=device)
-        b_digit_loss = torch.tensor(0.0, device=device)
-
-    total = result_loss + op_loss + digit_weight * (a_digit_loss + b_digit_loss)
-    total = torch.nan_to_num(total, nan=10.0, posinf=10.0, neginf=0.0)
-
-    return total, {
-        'result': result_loss.item() if not torch.isnan(result_loss) else 10.0,
-        'a_digit': a_digit_loss.item() if not torch.isnan(a_digit_loss) else 10.0,
-        'b_digit': b_digit_loss.item() if not torch.isnan(b_digit_loss) else 10.0,
-        'op': op_loss.item() if not torch.isnan(op_loss) else 10.0,
-        'n_words': n_words,
-        'n_lookup': used_lookup.sum().item()
-    }
-
-
-def evaluate_llm(model, n_samples: int = 500):
-    """Evaluate LLM model on random problems (mixed digit/word format)."""
-    model.extractor.eval()
-    correct = 0
-    op_correct = 0
-
-    for _ in range(n_samples):
-        text, a, b, op, expected = generate_problem()
-
-        with torch.no_grad():
-            outputs = model([text])
-            result_bits = outputs[0]
-            op_logits = outputs[3]
-
-        pred_result = bits_to_int(result_bits[0])
-        pred_op = OPERATIONS[op_logits[0].argmax().item()]
-
-        if pred_result == expected:
-            correct += 1
-        if pred_op == op:
-            op_correct += 1
-
-    model.extractor.train()
-    return correct / n_samples, op_correct / n_samples
-
-
-def train_llm(epochs: int = 100, batch_size: int = 256, lr: float = 3e-4,
-              unfreeze_layers: int = 0, extract_layer: int = -1,
-              position_extract: bool = False, digit_pred: bool = False,
-              positional_digit: bool = False, device: str = 'cuda'):
-    """
-    Train extractor with LLM hidden states.
-
-    Args:
-        unfreeze_layers: Number of top transformer layers to unfreeze (0 = fully frozen)
-        extract_layer: Which layer to extract from (-1 = last)
-        position_extract: Use position-specific extraction (legacy)
-        digit_pred: Predict digits instead of bits (legacy)
-        positional_digit: Use positional digit extraction (legacy, 100% on digits only)
-    """
-    hybrid = not (positional_digit or position_extract or digit_pred)
-
-    print("=" * 70)
-    print(" LLM TRAINING")
-    if unfreeze_layers > 0:
-        print(f" {unfreeze_layers} transformer layers unfrozen")
-    else:
-        print(" LLM frozen")
-    if extract_layer != -1:
-        print(f" Extracting from layer {extract_layer}")
-    if hybrid:
-        print(" HYBRID extraction (digit lookup + word learning)")
-    elif positional_digit:
-        print(" POSITIONAL DIGIT extraction (legacy, 100% on digits only)")
-    elif position_extract:
-        print(" Position-specific extraction (legacy)")
-    elif digit_pred:
-        print(" Digit-level prediction (legacy)")
-    print("=" * 70)
-
-    print("\nInitializing model...")
-    model = ArithmeticModel(
-        device=device,
-        unfreeze_layers=unfreeze_layers,
-        extract_layer=extract_layer,
-        position_extract=position_extract,
-        digit_pred=digit_pred,
-        positional_digit=positional_digit,
-        hybrid=hybrid
-    )
-
-    optimizer = optim.AdamW(model.trainable_parameters(), lr=lr)
-    scheduler = optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs)
-
-    print(f"\nTraining config:")
-    print(f"  Epochs: {epochs}")
-    print(f"  Batch size: {batch_size}")
-    print(f"  Learning rate: {lr}")
-    print(f"  Unfreeze layers: {unfreeze_layers}")
-    print(f"  Samples/epoch: {batch_size * 20}")
-
-    print(f"\nInitial evaluation (200 samples)...")
-    acc, op_acc = evaluate_llm(model, 200)
-    print(f"  Accuracy: {acc:.4f}, Op accuracy: {op_acc:.4f}")
-
-    print(f"\nStarting training...")
-    print("-" * 70)
-
-    best_acc = acc
-    start_time = time.perf_counter()
-
-    for epoch in range(epochs):
-        model.extractor.train()
-        if unfreeze_layers > 0:
-            model.llm.train()
-
-        max_val = get_curriculum_max(epoch, epochs)
-
-        epoch_loss = 0
-        if hybrid:
-            epoch_losses = {'result': 0, 'a_digit': 0, 'b_digit': 0, 'op': 0, 'n_words': 0, 'n_lookup': 0}
-        elif positional_digit:
-            epoch_losses = {'result': 0, 'a_digit': 0, 'b_digit': 0, 'op': 0}
-        else:
-            epoch_losses = {'result': 0, 'a': 0, 'b': 0, 'op': 0}
-        n_batches = 20
-        epoch_start = time.perf_counter()
-
-        for batch_idx in range(n_batches):
-            batch_texts = []
-            batch_a = []
-            batch_b = []
-            batch_op = []
-            batch_result = []
-            batch_a_values = []
-            batch_b_values = []
-
-            for _ in range(batch_size):
-                text, a, b, op, result = generate_problem(max_val)
-                batch_texts.append(text)
-                batch_a.append(int_to_bits(a, device))
-                batch_b.append(int_to_bits(b, device))
-                batch_op.append(OPERATIONS.index(op))
-                batch_result.append(int_to_bits(result, device))
-                batch_a_values.append(a)
-                batch_b_values.append(b)
-
-            target_a = torch.stack(batch_a)
-            target_b = torch.stack(batch_b)
-            target_op = torch.tensor(batch_op, device=device)
-            target_result = torch.stack(batch_result)
-            target_a_values = torch.tensor(batch_a_values, device=device, dtype=torch.float32)
-            target_b_values = torch.tensor(batch_b_values, device=device, dtype=torch.float32)
-
-            optimizer.zero_grad()
-
-            outputs = model(batch_texts)
-            pred_bits, a_bits, b_bits, op_logits = outputs[0], outputs[1], outputs[2], outputs[3]
-
-            if hybrid:
-                a_values, b_values, used_lookup = outputs[4], outputs[5], outputs[6]
-                a_digit_logits, b_digit_logits = outputs[7], outputs[8]
-                loss, losses = compute_hybrid_loss(
-                    pred_bits, op_logits, used_lookup,
-                    a_digit_logits, b_digit_logits,
-                    target_result, target_a_values, target_b_values, target_op, device
-                )
-            elif positional_digit:
-                a_digit_logits_list = outputs[7]
-                b_digit_logits_list = outputs[8]
-                loss, losses = compute_positional_digit_loss(
-                    pred_bits, op_logits, a_digit_logits_list, b_digit_logits_list,
-                    target_result, target_op, target_a_values, target_b_values, device
-                )
-            else:
-                loss, losses = compute_llm_loss(
-                    pred_bits, a_bits, b_bits, op_logits,
-                    target_result, target_a, target_b, target_op
-                )
-
-            loss.backward()
-            torch.nn.utils.clip_grad_norm_(model.trainable_parameters(), 1.0)
-            optimizer.step()
-
-            epoch_loss += loss.item()
-            for k in epoch_losses:
-                epoch_losses[k] += losses[k]
-
-            if (batch_idx + 1) % 5 == 0:
-                avg_so_far = epoch_loss / (batch_idx + 1)
-                print(f"  Epoch {epoch+1} batch {batch_idx+1}/{n_batches} | loss: {avg_so_far:.4f}", flush=True)
-
-        epoch_time = time.perf_counter() - epoch_start
-        scheduler.step()
-
-        avg_loss = epoch_loss / n_batches
-        for k in epoch_losses:
-            epoch_losses[k] /= n_batches
-
-        acc, op_acc = evaluate_llm(model, 300)
-        elapsed = time.perf_counter() - start_time
-
-        marker = " *" if acc > best_acc else ""
-        if acc > best_acc:
-            best_acc = acc
-
-        mem, _ = get_gpu_memory()
-        print(f"Epoch {epoch+1:3d} | Loss: {avg_loss:.4f} | "
-              f"Acc: {acc:.4f}{marker} | OpAcc: {op_acc:.4f} | "
-              f"Range: 0-{max_val} | VRAM: {mem:.0f}MB | Time: {elapsed:.0f}s")
-        if hybrid:
-            print(f"          Losses - result:{epoch_losses['result']:.4f} "
-                  f"a_digit:{epoch_losses['a_digit']:.4f} b_digit:{epoch_losses['b_digit']:.4f} "
-                  f"op:{epoch_losses['op']:.4f} | words:{epoch_losses['n_words']:.0f} lookup:{epoch_losses['n_lookup']:.0f}")
-        elif positional_digit:
-            print(f"          Losses - result:{epoch_losses['result']:.4f} "
-                  f"a_digit:{epoch_losses['a_digit']:.4f} b_digit:{epoch_losses['b_digit']:.4f} "
-                  f"op:{epoch_losses['op']:.4f}")
-        else:
-            print(f"          Losses - result:{epoch_losses['result']:.4f} "
-                  f"a:{epoch_losses['a']:.4f} b:{epoch_losses['b']:.4f} "
-                  f"op:{epoch_losses['op']:.4f}")
-
-        if acc >= 0.99:
-            print("\n" + "=" * 70)
-            print(" TARGET ACHIEVED: 99%+ ACCURACY")
-            print("=" * 70)
-            break
-
-    print("\n" + "=" * 70)
-    print(" FINAL EVALUATION")
-    print("=" * 70)
-
-    acc, op_acc = evaluate_llm(model, 1000)
-    print(f"Final accuracy: {acc:.4f}")
-    print(f"Final op accuracy: {op_acc:.4f}")
-    print(f"Best accuracy: {best_acc:.4f}")
-
-    print("\nSample predictions:")
-    for _ in range(10):
-        text, a, b, op, expected = generate_problem()
-        with torch.no_grad():
-            outputs = model([text])
-            result_bits, a_bits, b_bits, op_logits = outputs[0], outputs[1], outputs[2], outputs[3]
-        pred = bits_to_int(result_bits[0])
-        pred_a = bits_to_int(a_bits[0])
-        pred_b = bits_to_int(b_bits[0])
-        pred_op = OPERATIONS[op_logits[0].argmax().item()]
-
-        status = "OK" if pred == expected else "WRONG"
-        print(f"  '{text}' = {expected} | pred={pred} (a={pred_a}, b={pred_b}, op={pred_op}) [{status}]")
-
-    save_path = "D:/8bit-threshold-computer/llm_integration/trained/llm.pt"
-    save_dict = {
-        'extractor_state_dict': model.extractor.state_dict(),
-        'final_accuracy': acc,
-        'best_accuracy': best_acc,
-        'unfreeze_layers': unfreeze_layers,
-    }
-    if unfreeze_layers > 0:
-        save_dict['llm_state_dict'] = {
-            k: v for k, v in model.llm.state_dict().items()
-            if any(f'layers.{i}.' in k for i in range(len(model.llm.model.layers) - unfreeze_layers, len(model.llm.model.layers)))
-        }
-    torch.save(save_dict, save_path)
-    print(f"\nSaved to: {save_path}")
-
-    return model, acc
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description='Unified training for threshold circuit LLM integration',
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Modes:
-  router    - Train only OpRouter with ground truth bits (sanity check)
-  interface - Train BitEncoder + OpRouter with ground truth bits (sanity check)
-  llm       - Train extractor with LLM hidden states (the real training)
-
-LLM options:
-  --unfreeze_layers N  Fine-tune top N transformer layers
-  --extract_layer N    Extract from layer N (-1 = last)
-  --position_extract   Use position-specific extraction
-  --digit_pred         Predict digits instead of bits
-
-Baked-in: curriculum learning (0-9 -> 0-99 -> 0-255), 2x loss weight for a/b
-
-Examples:
-  python train.py --mode llm --epochs 100
-  python train.py --mode llm --position_extract
-  python train.py --mode llm --digit_pred --extract_layer 12
-  python train.py --mode llm --unfreeze_layers 4 --batch_size 4096
-        """
-    )
-    parser.add_argument('--mode', type=str, required=True,
-                        choices=['router', 'interface', 'llm'],
-                        help='Training mode')
-    parser.add_argument('--epochs', type=int, default=100, help='Number of epochs')
-    parser.add_argument('--batch_size', type=int, default=512, help='Batch size (default: 512)')
-    parser.add_argument('--lr', type=float, default=None,
-                        help='Learning rate (default: mode-specific)')
-    parser.add_argument('--unfreeze_layers', type=int, default=0,
-                        help='Unfreeze top N transformer layers (default 0 = frozen)')
-    parser.add_argument('--extract_layer', type=int, default=0,
-                        help='Which layer to extract from (default: 0 = embeddings, best for digits)')
-    parser.add_argument('--position_extract', action='store_true',
-                        help='Use position-specific extraction (legacy)')
-    parser.add_argument('--digit_pred', action='store_true',
-                        help='Predict digits instead of bits (legacy)')
-    parser.add_argument('--positional_digit', action='store_true', default=False,
-                        help='Use positional digit extraction (legacy, 100%% on digits only)')
-    parser.add_argument('--device', type=str, default='cuda', help='Device')
-    args = parser.parse_args()
-
-    torch.manual_seed(42)
-    random.seed(42)
-
-    if args.mode == 'router':
-        lr = args.lr if args.lr is not None else 1e-2
-        train_router(epochs=args.epochs, batch_size=args.batch_size, lr=lr, device=args.device)
-
-    elif args.mode == 'interface':
-        lr = args.lr if args.lr is not None else 1e-3
-        model, fitness = train_interface(
-            epochs=args.epochs, batch_size=args.batch_size, lr=lr, device=args.device
-        )
-
-        print("\n" + "=" * 70)
-        print(" EXPERIMENT SUMMARY")
-        print("=" * 70)
-        print(f"\n  Control (Vanilla SmolLM2-360M):     11.90%")
-        print(f"  Experimental (Trained Interface):   {100*fitness:.2f}%")
-        if fitness > 0:
-            print(f"\n  Improvement: {100*(fitness - 0.119)/0.119:.1f}%")
-
-        if fitness >= 0.99:
-            print("\n  CONCLUSION: Frozen threshold circuits + trained interface")
-            print("              achieves near-perfect arithmetic accuracy.")
-            print("              Core thesis VALIDATED.")
-        else:
-            print(f"\n  CONCLUSION: Further training or architecture changes needed.")
-            print(f"              Current gap: {100*(1.0 - fitness):.2f}%")
-
-    elif args.mode == 'llm':
-        lr = args.lr if args.lr is not None else 3e-4
-        train_llm(
-            epochs=args.epochs,
-            batch_size=args.batch_size,
-            lr=lr,
-            unfreeze_layers=args.unfreeze_layers,
-            extract_layer=args.extract_layer,
-            position_extract=args.position_extract,
-            digit_pred=args.digit_pred,
-            positional_digit=args.positional_digit,
-            device=args.device
-        )
-
-
-if __name__ == "__main__":
-    main()

paper/README.md

@@ -6,51 +6,45 @@ Networks.* The manuscript and the records of the runs it reports.
 ```
 universal_construction_ternary.tex    source
 universal_construction_ternary.pdf    typeset
-runs/                                 the record written by each script
+runs/                                 the record written by each command
 ```
 
-## What each script establishes
+## What each command establishes
 
-Each script runs on its own and writes its record to `runs/`; `src/check_rocq.py`
-needs Rocq 9.1 and ocamlfind on the PATH.
+Each command is `python src/<file>.py <command>` and writes its record to `runs/`;
+`paper.py rocq` needs Rocq 9.1 and ocamlfind on the PATH, and `noise.py neuromorphic run`
+needs Lava, which requires Python 3.10.
 
-
-| Script | Record | Establishes |
+| Command | Record | Establishes |
 |---|---|---|
-| `src/host_netlist.py`, `src/host_family.py` | — | the step netlist of the host, a member of the constant-depth family H_A |
-| `src/check_host_family.py` | `paper_host_family.json` | one step of H_A against SUBLEQ_A for A = 3 to 12, on the evaluator in C |
-| `src/netlist_io.py` | — | the serialization sigma and its inverse |
-| `src/noise.py margin` | `paper_noise_margin.json` | the margin along the trajectory |
-| `src/noise.py profile` | `paper_noise_profile.json` | the pre-activation profile and its bound on the failure rate |
-| `src/paper_stats.py` | `paper_stats.json` | unit counts, levelization sizes, fan-in |
-| `src/paper_verify.py` | `paper_verify.json` | codec, framing, serialization, datapath, interpreter |
-| `src/paper_runs.py` | `paper_runs_*.json` | self-description, three generations, lockstep |
-| `src/check_codec.py` | `paper_codec.json` | the recipe codec at every boundary of the token format |
-| `src/check_optimal.py` | `paper_optimal.json` | the length bound is optimal on run-free strings |
-| `src/check_steps.py` | `paper_steps.json` | the closed forms for the step counts |
-| `src/check_device.py` | `paper_device.json` | the device against its definition |
-| `src/check_host.py` | `paper_host.json` | the reference machine against its definition |
-| `src/check_lev.py` | `paper_lev.json` | the levelization against gate-by-gate evaluation |
-| `src/check_framing.py` | `paper_framing.json` | `ser` injective, `inst` partial and inverse |
-| `src/check_ternarity.py` | `paper_ternarity.json` | no ternary unit computes the branch predicate |
-| `src/check_environment.py` | `paper_environment.json` | the cost of the environment against the cost of the network |
-| `src/check_sigma.py` | — | sigma is a function, injective, and inverted by the parser |
-| `src/check_family.py` | `paper_runs_family.json` | the constructor emits all 29 machines |
-| `src/check_family_gate.py` | `paper_runs_family_gate.json` | four of them on the netlist of sigma |
-| `src/check_c.py` | `paper_c_evaluator.json` | the host on the evaluator in C, `src/netlist_eval.c` |
-| `src/check_host_fold.py` | `paper_host_fold.json` | the folded host family, depth 11, against SUBLEQ_A for A = 3 to 12 |
-| `src/twohead.py` | `paper_twohead.json` | the translating organism on the two-head machine, three generations |
-| `src/twohead_net.py` | `paper_twohead_net.json` | the netlist N_{G,L} against the machine for windows of 64 and 4096 cells, its file, the organism on it in C, and the netlist extracted from Rocq |
-| `src/stored_host.py`, `src/stored_host_run.c` | `paper_stored_host.json` | the host compiled into records of the two-head machine: one pass against the host's step and its device, the image and its recipe, three generations in C |
-| `src/check_rocq.py` | `paper_rocq.json` | the Rocq development of `rocq/`: the netlist computes the step for every window, construction and self-reproduction by the organism |
-| `src/throughput.py` | `paper_throughput.json` | the rate of each evaluator |
-| `src/noise.py` | `paper_noise_*.json` | read noise, the deviation curve, weight error with leakage, the active-input counts of the orbit certificate |
-| `src/redundant.py` | `paper_redundant_*.json` | the amplified host N_3: one step against SUBLEQ on replicated states, the margin 3/2, exact self-reproduction in C, the run under noise, the deviation curve and its bound by layer, the failure rate of the state read by majority and the restoration bound, computed by `src/restore_bound.c` |
-| `src/neuromorphic.py` | `paper_neuromorphic.json` | the datapath on the Loihi and Akida neuron models |
-| `src/independent/*.py`, `nsim.c` | `independent_*.json` | separate code written from the paper's definitions: H_A rebuilt from Construction 3.8 for A = 3 to 12, Lev(N_host) from sigma, Tables 3 to 6 with a separate noise simulator, and the datapath on Loihi and Akida |
-
-`src/neuromorphic.py run` needs Lava, which requires Python 3.10; everything
-else runs in the environment of the repository.
+| `host.py` | — | the host family H_A, the serialization sigma and its inverse, the device, the constructor P and the program P*, and the evaluators |
+| `paper.py host-family` | `paper_host_family.json` | one step of H_A against SUBLEQ_A for A = 3 to 12, on the evaluator in C |
+| `paper.py host-fold` | `paper_host_fold.json` | the folded host family, depth 11, against SUBLEQ_A for A = 3 to 12 |
+| `paper.py stats` | `paper_stats.json` | unit counts, levelization sizes, fan-in |
+| `paper.py verify` | `paper_verify.json` | codec, framing, serialization, datapath, levelization |
+| `paper.py runs` | `paper_runs_*.json` | self-description, three generations, lockstep |
+| `paper.py codec` | `paper_codec.json` | the recipe codec at every boundary of the token format |
+| `paper.py optimal` | `paper_optimal.json` | the length bound is optimal on run-free strings |
+| `paper.py steps` | `paper_steps.json` | the closed forms for the step counts |
+| `paper.py device` | `paper_device.json` | the device against its definition |
+| `paper.py host` | `paper_host.json` | the reference machine against its definition |
+| `paper.py lev` | `paper_lev.json` | the levelization against gate-by-gate evaluation |
+| `paper.py framing` | `paper_framing.json` | `ser` injective, `inst` partial and inverse |
+| `paper.py ternarity` | `paper_ternarity.json` | no ternary unit computes the branch predicate |
+| `paper.py environment` | `paper_environment.json` | the cost of the environment against the cost of the network |
+| `paper.py sigma` | — | sigma is a function, injective, and inverted by the parser |
+| `paper.py family` | `paper_runs_family.json` | the constructor emits all 29 machines |
+| `paper.py family-gate` | `paper_runs_family_gate.json` | four of them on the netlist of sigma |
+| `paper.py c` | `paper_c_evaluator.json` | the host on the evaluator in C, `src/netlist_eval.c` |
+| `paper.py throughput` | `paper_throughput.json` | the rate of each evaluator |
+| `paper.py rocq` | `paper_rocq.json` | the Rocq development of `rocq/`, its assumptions and the netlist extracted from it |
+| `twohead.py organism` | `paper_twohead.json` | the translating organism on the two-head machine, three generations |
+| `twohead.py net` | `paper_twohead_net.json` | the netlist N_{G,L} against the machine for windows of 64 and 4096 cells, its file, the organism on it in C, and the netlist extracted from Rocq |
+| `twohead.py stored` | `paper_stored_host.json` | the host compiled into records of the two-head machine: one pass against the host's step and its device, and three generations in C |
+| `noise.py host` | `paper_noise_*.json` | the margin, the profile bound, read noise, the deviation curve, weight error with leakage, the active-input counts of the orbit certificate |
+| `noise.py amplified` | `paper_redundant_*.json` | the amplified host N_3: one step on replicated states, the margin 3/2, exact self-reproduction in C, the run under noise, the deviation curve and its bound by layer, the failure rate of the state read by majority and the restoration bound, computed by `src/restore_bound.c` |
+| `noise.py neuromorphic` | `paper_neuromorphic.json` | the datapath on the Loihi and Akida neuron models |
+| `independent.py` | `independent_*.json` | code written from the paper's definitions alone: H_A rebuilt from Construction 3.8 for A = 3 to 12, Lev(N_host) from sigma, Tables 3 to 6 with the noise simulator `src/nsim.c`, and the datapath on Loihi and Akida |
 
 Rebuild the typeset paper with any TeX installation:
 

paper/universal_construction_ternary.pdf

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:29a8e26ce2577a85810fc815acc5eeaef1925cbaadb629aee163c64bf7cfdcf4
-size 364771
+oid sha256:cf817d63746a8601c860f094ef25e7a746218a355e721248f44559caf8f3f441
+size 364795

paper/universal_construction_ternary.tex

@@ -2514,12 +2514,12 @@ $\sigma(\Nhost)$, and every generation of every run instantiated its evaluator
 afresh from the bytes the previous generation emitted. The two-head machine was
 evaluated by transcriptions of Definition~\ref{def:twohead} in Python and in C, by
 the netlist $N^\alpha_{G,L}$ in Python and in C, and in the Rocq kernel. The
-stored host is built from $\sigma(\Nhost)$ by \texttt{src/stored\_host.py}, which
+stored host is built from $\sigma(\Nhost)$ by \texttt{src/twohead.py}, which
 also compares one pass with the host's step and the device, and its generations
 are run by \texttt{src/stored\_host\_run.c}, a transcription of
 Definition~\ref{def:twohead} that decodes the active bank once per change of
 $\kappa$; the three generations of Remark~\ref{rem:storedcheck} take $9$ minutes.
-Separate code in \texttt{src/independent/}, written from the definitions of this
+Separate code in \texttt{src/independent.py}, written from the definitions of this
 paper, rebuilds $H_A$ from Construction~\ref{con:host} for $A=3$ to $12$,
 levelizes $\sigma(\Nhost)$, repeats Tables~\ref{tab:curve} to~\ref{tab:bound3}
 with a simulator in C and on the accelerator, and maps the datapath onto Loihi
@@ -2540,7 +2540,7 @@ of their length, and Theorem~\ref{thm:organism}. The file that defines the
 organism and its description is written by \texttt{src/twohead.py}, and the
 netlist definition, extracted to OCaml, writes for $N^6_{133,2930}$ and
 $N^{12}_{5,40}$ files byte for byte equal to those that
-\texttt{src/twohead\_net.py} writes.
+\texttt{src/twohead.py} writes.
 
 Besides the runs recorded in the remarks of Sections~\ref{sec:host}
 to~\ref{sec:organism} and in Appendix~\ref{app:measure}, the following were
@@ -2637,7 +2637,7 @@ the Rocq definition. The records of the organism and of $S$ are laid out as in
 Definition~\ref{def:twohead}, with the window cells of
 Constructions~\ref{con:organism} and~\ref{con:stored}; within each block of
 Construction~\ref{con:stored} the order of the records is that of
-\texttt{src/stored\_host.py}, which gives each temporary the least cell free over
+\texttt{src/twohead.py}, which gives each temporary the least cell free over
 its live interval.
 One generation of $\Omega^\ast$ takes $0.3$ seconds on~(a), $45$ seconds on~(d)
 and $9$ minutes on~(b). All figures were

src/attractor.py

@@ -1,261 +0,0 @@
-"""Attractor computer: an energy-based threshold network.
-
-A Boolean circuit is compiled to a quadratic pseudo-Boolean energy
-E(s) = sum_i L[i] s_i + sum_{i<j} Q[i,j] s_i s_j over binary wire variables, with
-per-gate gadgets that are non-negative and zero exactly on the gate truth table:
-
-    AND z=x&y : 3z + xy - 2xz - 2yz
-    OR  z=x|y : x + y + z + xy - 2xz - 2yz
-    NOT z=~x  : 1 - x - z + 2xz
-
-AND/OR/NOT are functionally complete, so any circuit compiles and its consistent
-assignment is the global minimum. There is no program counter or clock: the
-coupling matrix Q (with linear terms L) is the program, and execution is
-relaxation toward the minimum. The relaxation step is a threshold neuron over the
-same integer weights, s_i <- H(-(L[i] + sum_j Q[i,j] s_j)).
-
-The clamped wire subset selects the mode. Clamp inputs to evaluate forward (exact
-via topological propagation to the energy-0 fixed point); clamp outputs to invert
-(a multiplier run backward returns factors); clamp a CNF output to 1 to solve
-SAT. Forward evaluation is exact and linear in gate count; inversion and
-open-constraint solving are annealed ground-state search, NP-hard in general,
-with a zero-energy state certifying a correct assignment.
-"""
-from __future__ import annotations
-import math
-import random
-from collections import defaultdict
-from typing import Dict, List, Optional, Tuple
-
-
-class Circuit:
-    """Wire allocator and energy accumulator. Gates append exact QUBO gadgets
-    and record the relation for topological forward evaluation."""
-
-    def __init__(self) -> None:
-        self.n = 0
-        self.L: Dict[int, int] = defaultdict(int)
-        self.Q: Dict[Tuple[int, int], int] = defaultdict(int)
-        self.const = 0
-        self.gates: List[Tuple[str, int, Tuple[int, ...]]] = []
-
-    def wire(self) -> int:
-        i = self.n
-        self.n += 1
-        return i
-
-    def wires(self, k: int) -> List[int]:
-        return [self.wire() for _ in range(k)]
-
-    def _q(self, i: int, j: int, c: int) -> None:
-        if i == j:
-            self.L[i] += c
-        else:
-            self.Q[(min(i, j), max(i, j))] += c
-
-    def AND(self, x: int, y: int) -> int:
-        z = self.wire()
-        self.L[z] += 3
-        self._q(x, y, 1); self._q(x, z, -2); self._q(y, z, -2)
-        self.gates.append(("AND", z, (x, y)))
-        return z
-
-    def OR(self, x: int, y: int) -> int:
-        z = self.wire()
-        self.L[x] += 1; self.L[y] += 1; self.L[z] += 1
-        self._q(x, y, 1); self._q(x, z, -2); self._q(y, z, -2)
-        self.gates.append(("OR", z, (x, y)))
-        return z
-
-    def NOT(self, x: int) -> int:
-        z = self.wire()
-        self.const += 1
-        self.L[x] += -1; self.L[z] += -1
-        self._q(x, z, 2)
-        self.gates.append(("NOT", z, (x,)))
-        return z
-
-    def XOR(self, x: int, y: int) -> int:
-        return self.OR(self.AND(x, self.NOT(y)), self.AND(self.NOT(x), y))
-
-    def full_adder(self, x: int, y: int, cin: int) -> Tuple[int, int]:
-        axy = self.XOR(x, y)
-        s = self.XOR(axy, cin)
-        cout = self.OR(self.AND(x, y), self.AND(cin, axy))
-        return s, cout
-
-    # ---- energy + couplings ------------------------------------------------
-    def energy(self, s: List[int]) -> int:
-        e = self.const
-        for i, c in self.L.items():
-            e += c * s[i]
-        for (i, j), c in self.Q.items():
-            e += c * s[i] * s[j]
-        return e
-
-    def neighbors(self) -> Dict[int, List[Tuple[int, int]]]:
-        nbr: Dict[int, List[Tuple[int, int]]] = defaultdict(list)
-        for (i, j), c in self.Q.items():
-            nbr[i].append((j, c))
-            nbr[j].append((i, c))
-        return nbr
-
-    # ---- relaxation modes --------------------------------------------------
-    def forward_eval(self, clamp: Dict[int, int]) -> List[int]:
-        """Exact forward relaxation: propagate clamped inputs through the gate
-        relations in topological order onto the energy-0 fixed point."""
-        s = [0] * self.n
-        for w, v in clamp.items():
-            s[w] = v
-        for op, z, ins in self.gates:
-            if op == "AND":
-                s[z] = s[ins[0]] & s[ins[1]]
-            elif op == "OR":
-                s[z] = s[ins[0]] | s[ins[1]]
-            else:
-                s[z] = 1 - s[ins[0]]
-        return s
-
-    def relax_energy(self, clamp: Dict[int, int], sweeps: int = 4000,
-                     t0: float = 4.0, t1: float = 0.02, seed: int = 0
-                     ) -> Tuple[List[int], bool]:
-        """Canonical relaxation: anneal the full threshold network (every free
-        wire), tracking the lowest-energy state. Universal but hard; the exact
-        gadgets keep the target at energy 0."""
-        nbr = self.neighbors()
-        rng = random.Random(seed)
-        s = [rng.randint(0, 1) for _ in range(self.n)]
-        for w, v in clamp.items():
-            s[w] = v
-        free = [i for i in range(self.n) if i not in clamp]
-        best, best_e = list(s), self.energy(s)
-        for step in range(sweeps):
-            T = t0 * (t1 / t0) ** (step / max(1, sweeps - 1))
-            for _ in range(len(free)):
-                i = free[rng.randrange(len(free))]
-                field = self.L[i] + sum(c * s[j] for j, c in nbr[i])
-                dE = (1 - 2 * s[i]) * field
-                if dE <= 0 or rng.random() < math.exp(-dE / T):
-                    s[i] ^= 1
-            e = self.energy(s)
-            if e < best_e:
-                best, best_e = list(s), e
-                if best_e == 0:
-                    return best, True
-        return best, best_e == 0
-
-    def solve(self, free_inputs: List[int], fixed: Dict[int, int],
-              target: Dict[int, int], sweeps: int = 3000, restarts: int = 80,
-              seed: int = 0) -> Optional[List[int]]:
-        """Open-constraint relaxation over a chosen set of driver wires, with
-        the rest slaved through the circuit; anneal the output Hamming mismatch
-        to zero. Clamp outputs and pass the inputs here to run backward."""
-        rng = random.Random(seed)
-
-        def mism(vals: Dict[int, int]) -> int:
-            s = self.forward_eval({**fixed, **vals})
-            return sum(1 for w, v in target.items() if s[w] != v)
-
-        for _ in range(restarts):
-            vals = {w: rng.randint(0, 1) for w in free_inputs}
-            m = mism(vals)
-            if m == 0:
-                return self.forward_eval({**fixed, **vals})
-            for step in range(sweeps):
-                T = 2.0 * (0.02 / 2.0) ** (step / sweeps)
-                w = free_inputs[rng.randrange(len(free_inputs))]
-                vals[w] ^= 1
-                m2 = mism(vals)
-                if m2 <= m or rng.random() < math.exp(-(m2 - m) / T):
-                    m = m2
-                    if m == 0:
-                        return self.forward_eval({**fixed, **vals})
-                else:
-                    vals[w] ^= 1
-        return None
-
-
-# ---------------------------------------------------------------------------
-# Circuit builders
-# ---------------------------------------------------------------------------
-def adder(bits: int) -> Tuple[Circuit, dict]:
-    c = Circuit()
-    xs, ys = c.wires(bits), c.wires(bits)
-    cin = c.wire()
-    outs, carry = [], cin
-    for k in range(bits):
-        s, carry = c.full_adder(xs[k], ys[k], carry)
-        outs.append(s)
-    return c, {"xs": xs, "ys": ys, "cin": cin, "sum": outs + [carry]}
-
-
-def multiplier(bits: int) -> Tuple[Circuit, dict]:
-    c = Circuit()
-    xs, ys = c.wires(bits), c.wires(bits)
-    zero = c.wire()
-    acc = [zero] * (2 * bits)
-    for i in range(bits):
-        carry = zero
-        for j in range(bits):
-            acc[i + j], carry = c.full_adder(acc[i + j], c.AND(xs[i], ys[j]), carry)
-        acc[i + bits] = carry
-    return c, {"xs": xs, "ys": ys, "zero": zero, "prod": acc}
-
-
-_OPCODE = {"AND": 0, "OR": 1, "NOT": 2}
-_OPNAME = {v: k for k, v in _OPCODE.items()}
-
-
-def to_tensors(circ: Circuit, io: dict):
-    """Serialize the coupling matrix (the program) and the gate list to tensors.
-    Q is stored sparsely as index pairs and integer values."""
-    import torch
-    qi = sorted(circ.Q)
-    q_idx = torch.tensor(qi if qi else [], dtype=torch.long).reshape(-1, 2)
-    q_val = torch.tensor([circ.Q[k] for k in qi], dtype=torch.long)
-    li = sorted(circ.L)
-    l_idx = torch.tensor(li, dtype=torch.long)
-    l_val = torch.tensor([circ.L[i] for i in li], dtype=torch.long)
-    g_op = torch.tensor([_OPCODE[op] for op, _, _ in circ.gates], dtype=torch.long)
-    g_out = torch.tensor([o for _, o, _ in circ.gates], dtype=torch.long)
-    g_in = torch.tensor([[ins[0], ins[1] if len(ins) > 1 else -1]
-                         for _, _, ins in circ.gates], dtype=torch.long).reshape(-1, 2)
-    t = {"Q_idx": q_idx, "Q_val": q_val, "L_idx": l_idx, "L_val": l_val,
-         "gate_op": g_op, "gate_out": g_out, "gate_in": g_in}
-    import json
-    meta = {"machine": "attractor", "n": str(circ.n), "const": str(circ.const),
-            "io": json.dumps({k: v for k, v in io.items()})}
-    return t, meta
-
-
-def from_tensors(t: dict, meta: dict) -> Tuple[Circuit, dict]:
-    import json
-    c = Circuit()
-    c.n = int(meta["n"])
-    c.const = int(meta["const"])
-    for (i, j), v in zip(t["Q_idx"].tolist(), t["Q_val"].tolist()):
-        c.Q[(i, j)] = v
-    for i, v in zip(t["L_idx"].tolist(), t["L_val"].tolist()):
-        c.L[i] = v
-    for op, out, ins in zip(t["gate_op"].tolist(), t["gate_out"].tolist(), t["gate_in"].tolist()):
-        c.gates.append((_OPNAME[op], out, tuple(x for x in ins if x >= 0)))
-    return c, json.loads(meta["io"])
-
-
-def cnf(clauses: List[List[int]], n_vars: int) -> Tuple[Circuit, dict]:
-    """Compile a CNF formula. Literals are +v (var v) or -v (negation), v>=1.
-    Returns the circuit, the variable wires, and the wire that is 1 iff the
-    formula is satisfied. Clamp that wire to 1 and relax to find a model."""
-    c = Circuit()
-    var = {v: c.wire() for v in range(1, n_vars + 1)}
-    clause_ws = []
-    for cl in clauses:
-        lits = [var[abs(l)] if l > 0 else c.NOT(var[abs(l)]) for l in cl]
-        acc = lits[0]
-        for w in lits[1:]:
-            acc = c.OR(acc, w)
-        clause_ws.append(acc)
-    sat = clause_ws[0]
-    for w in clause_ws[1:]:
-        sat = c.AND(sat, w)
-    return c, {"vars": var, "sat": sat}

src/automata.py

@@ -0,0 +1,1759 @@
+"""The attractor, reversible, cellular-automaton and tile machines, with their builders."""
+from __future__ import annotations
+
+import json
+import math
+import os
+import random
+import sys
+from collections import defaultdict
+from typing import Dict, List, Optional, Tuple
+
+import torch
+from safetensors import safe_open
+from safetensors.torch import save_file, load_file
+
+from machines import Net, compile_net, MatrixMachine
+
+
+class Circuit:
+    """Wire allocator and energy accumulator."""
+
+    def __init__(self) -> None:
+        self.n = 0
+        self.L: Dict[int, int] = defaultdict(int)
+        self.Q: Dict[Tuple[int, int], int] = defaultdict(int)
+        self.const = 0
+        self.gates: List[Tuple[str, int, Tuple[int, ...]]] = []
+
+    def wire(self) -> int:
+        i = self.n
+        self.n += 1
+        return i
+
+    def wires(self, k: int) -> List[int]:
+        return [self.wire() for _ in range(k)]
+
+    def _q(self, i: int, j: int, c: int) -> None:
+        if i == j:
+            self.L[i] += c
+        else:
+            self.Q[(min(i, j), max(i, j))] += c
+
+    def AND(self, x: int, y: int) -> int:
+        z = self.wire()
+        self.L[z] += 3
+        self._q(x, y, 1); self._q(x, z, -2); self._q(y, z, -2)
+        self.gates.append(("AND", z, (x, y)))
+        return z
+
+    def OR(self, x: int, y: int) -> int:
+        z = self.wire()
+        self.L[x] += 1; self.L[y] += 1; self.L[z] += 1
+        self._q(x, y, 1); self._q(x, z, -2); self._q(y, z, -2)
+        self.gates.append(("OR", z, (x, y)))
+        return z
+
+    def NOT(self, x: int) -> int:
+        z = self.wire()
+        self.const += 1
+        self.L[x] += -1; self.L[z] += -1
+        self._q(x, z, 2)
+        self.gates.append(("NOT", z, (x,)))
+        return z
+
+    def XOR(self, x: int, y: int) -> int:
+        return self.OR(self.AND(x, self.NOT(y)), self.AND(self.NOT(x), y))
+
+    def full_adder(self, x: int, y: int, cin: int) -> Tuple[int, int]:
+        axy = self.XOR(x, y)
+        s = self.XOR(axy, cin)
+        cout = self.OR(self.AND(x, y), self.AND(cin, axy))
+        return s, cout
+
+    # ---- energy + couplings ------------------------------------------------
+    def energy(self, s: List[int]) -> int:
+        e = self.const
+        for i, c in self.L.items():
+            e += c * s[i]
+        for (i, j), c in self.Q.items():
+            e += c * s[i] * s[j]
+        return e
+
+    def neighbors(self) -> Dict[int, List[Tuple[int, int]]]:
+        nbr: Dict[int, List[Tuple[int, int]]] = defaultdict(list)
+        for (i, j), c in self.Q.items():
+            nbr[i].append((j, c))
+            nbr[j].append((i, c))
+        return nbr
+
+    # ---- relaxation modes --------------------------------------------------
+    def forward_eval(self, clamp: Dict[int, int]) -> List[int]:
+        """Exact forward relaxation from the clamped inputs to the energy-0 fixed point."""
+        s = [0] * self.n
+        for w, v in clamp.items():
+            s[w] = v
+        for op, z, ins in self.gates:
+            if op == "AND":
+                s[z] = s[ins[0]] & s[ins[1]]
+            elif op == "OR":
+                s[z] = s[ins[0]] | s[ins[1]]
+            else:
+                s[z] = 1 - s[ins[0]]
+        return s
+
+    def relax_energy(self, clamp: Dict[int, int], sweeps: int = 4000,
+                     t0: float = 4.0, t1: float = 0.02, seed: int = 0
+                     ) -> Tuple[List[int], bool]:
+        """Anneal the full threshold network, tracking the lowest-energy state."""
+        nbr = self.neighbors()
+        rng = random.Random(seed)
+        s = [rng.randint(0, 1) for _ in range(self.n)]
+        for w, v in clamp.items():
+            s[w] = v
+        free = [i for i in range(self.n) if i not in clamp]
+        best, best_e = list(s), self.energy(s)
+        for step in range(sweeps):
+            T = t0 * (t1 / t0) ** (step / max(1, sweeps - 1))
+            for _ in range(len(free)):
+                i = free[rng.randrange(len(free))]
+                field = self.L[i] + sum(c * s[j] for j, c in nbr[i])
+                dE = (1 - 2 * s[i]) * field
+                if dE <= 0 or rng.random() < math.exp(-dE / T):
+                    s[i] ^= 1
+            e = self.energy(s)
+            if e < best_e:
+                best, best_e = list(s), e
+                if best_e == 0:
+                    return best, True
+        return best, best_e == 0
+
+    def solve(self, free_inputs: List[int], fixed: Dict[int, int],
+              target: Dict[int, int], sweeps: int = 3000, restarts: int = 80,
+              seed: int = 0) -> Optional[List[int]]:
+        """Anneal chosen driver wires until the outputs match, the other wires slaved through the circuit."""
+        rng = random.Random(seed)
+
+        def mism(vals: Dict[int, int]) -> int:
+            s = self.forward_eval({**fixed, **vals})
+            return sum(1 for w, v in target.items() if s[w] != v)
+
+        for _ in range(restarts):
+            vals = {w: rng.randint(0, 1) for w in free_inputs}
+            m = mism(vals)
+            if m == 0:
+                return self.forward_eval({**fixed, **vals})
+            for step in range(sweeps):
+                T = 2.0 * (0.02 / 2.0) ** (step / sweeps)
+                w = free_inputs[rng.randrange(len(free_inputs))]
+                vals[w] ^= 1
+                m2 = mism(vals)
+                if m2 <= m or rng.random() < math.exp(-(m2 - m) / T):
+                    m = m2
+                    if m == 0:
+                        return self.forward_eval({**fixed, **vals})
+                else:
+                    vals[w] ^= 1
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Circuit builders
+# ---------------------------------------------------------------------------
+def adder(bits: int) -> Tuple[Circuit, dict]:
+    c = Circuit()
+    xs, ys = c.wires(bits), c.wires(bits)
+    cin = c.wire()
+    outs, carry = [], cin
+    for k in range(bits):
+        s, carry = c.full_adder(xs[k], ys[k], carry)
+        outs.append(s)
+    return c, {"xs": xs, "ys": ys, "cin": cin, "sum": outs + [carry]}
+
+
+def multiplier(bits: int) -> Tuple[Circuit, dict]:
+    c = Circuit()
+    xs, ys = c.wires(bits), c.wires(bits)
+    zero = c.wire()
+    acc = [zero] * (2 * bits)
+    for i in range(bits):
+        carry = zero
+        for j in range(bits):
+            acc[i + j], carry = c.full_adder(acc[i + j], c.AND(xs[i], ys[j]), carry)
+        acc[i + bits] = carry
+    return c, {"xs": xs, "ys": ys, "zero": zero, "prod": acc}
+
+
+_OPCODE = {"AND": 0, "OR": 1, "NOT": 2}
+
+_OPNAME = {v: k for k, v in _OPCODE.items()}
+
+
+def to_tensors(circ: Circuit, io: dict):
+    """Serialize the coupling matrix (the program) and the gate list to tensors."""
+    import torch
+    qi = sorted(circ.Q)
+    q_idx = torch.tensor(qi if qi else [], dtype=torch.long).reshape(-1, 2)
+    q_val = torch.tensor([circ.Q[k] for k in qi], dtype=torch.long)
+    li = sorted(circ.L)
+    l_idx = torch.tensor(li, dtype=torch.long)
+    l_val = torch.tensor([circ.L[i] for i in li], dtype=torch.long)
+    g_op = torch.tensor([_OPCODE[op] for op, _, _ in circ.gates], dtype=torch.long)
+    g_out = torch.tensor([o for _, o, _ in circ.gates], dtype=torch.long)
+    g_in = torch.tensor([[ins[0], ins[1] if len(ins) > 1 else -1]
+                         for _, _, ins in circ.gates], dtype=torch.long).reshape(-1, 2)
+    t = {"Q_idx": q_idx, "Q_val": q_val, "L_idx": l_idx, "L_val": l_val,
+         "gate_op": g_op, "gate_out": g_out, "gate_in": g_in}
+    import json
+    meta = {"machine": "attractor", "n": str(circ.n), "const": str(circ.const),
+            "io": json.dumps({k: v for k, v in io.items()})}
+    return t, meta
+
+
+def from_tensors(t: dict, meta: dict) -> Tuple[Circuit, dict]:
+    import json
+    c = Circuit()
+    c.n = int(meta["n"])
+    c.const = int(meta["const"])
+    for (i, j), v in zip(t["Q_idx"].tolist(), t["Q_val"].tolist()):
+        c.Q[(i, j)] = v
+    for i, v in zip(t["L_idx"].tolist(), t["L_val"].tolist()):
+        c.L[i] = v
+    for op, out, ins in zip(t["gate_op"].tolist(), t["gate_out"].tolist(), t["gate_in"].tolist()):
+        c.gates.append((_OPNAME[op], out, tuple(x for x in ins if x >= 0)))
+    return c, json.loads(meta["io"])
+
+
+def cnf(clauses: List[List[int]], n_vars: int) -> Tuple[Circuit, dict]:
+    """Compile a CNF formula."""
+    c = Circuit()
+    var = {v: c.wire() for v in range(1, n_vars + 1)}
+    clause_ws = []
+    for cl in clauses:
+        lits = [var[abs(l)] if l > 0 else c.NOT(var[abs(l)]) for l in cl]
+        acc = lits[0]
+        for w in lits[1:]:
+            acc = c.OR(acc, w)
+        clause_ws.append(acc)
+    sat = clause_ws[0]
+    for w in clause_ws[1:]:
+        sat = c.AND(sat, w)
+    return c, {"vars": var, "sat": sat}
+
+
+def test_forward():
+    ok = True
+    for bits in (4, 8):
+        c, io = adder(bits)
+        rng = random.Random(bits)
+        bad = 0
+        for _ in range(300):
+            a, b = rng.randint(0, (1 << bits) - 1), rng.randint(0, (1 << bits) - 1)
+            clamp = {io["cin"]: 0}
+            for k in range(bits):
+                clamp[io["xs"][k]] = (a >> k) & 1
+                clamp[io["ys"][k]] = (b >> k) & 1
+            s = c.forward_eval(clamp)
+            got = sum(s[w] << k for k, w in enumerate(io["sum"]))
+            if got != a + b or c.energy(s) != 0:
+                bad += 1
+        print(f"  forward adder {bits}-bit: {'OK' if bad == 0 else f'FAIL({bad})'}")
+        ok &= bad == 0
+    for bits in (3, 5):
+        c, io = multiplier(bits)
+        rng = random.Random(100 + bits)
+        bad = 0
+        for _ in range(300):
+            a, b = rng.randint(0, (1 << bits) - 1), rng.randint(0, (1 << bits) - 1)
+            clamp = {io["zero"]: 0}
+            for k in range(bits):
+                clamp[io["xs"][k]] = (a >> k) & 1
+                clamp[io["ys"][k]] = (b >> k) & 1
+            s = c.forward_eval(clamp)
+            got = sum(s[w] << k for k, w in enumerate(io["prod"]))
+            if got != a * b or c.energy(s) != 0:
+                bad += 1
+        print(f"  forward multiplier {bits}-bit: {'OK' if bad == 0 else f'FAIL({bad})'}")
+        ok &= bad == 0
+    return ok
+
+
+def test_energy_relax():
+    """The canonical form: anneal the whole network (no propagation shortcut)."""
+    c, io = adder(4)
+    rng = random.Random(3)
+    bad = 0
+    for _ in range(20):
+        a, b = rng.randint(0, 15), rng.randint(0, 15)
+        clamp = {io["cin"]: 0}
+        for k in range(4):
+            clamp[io["xs"][k]] = (a >> k) & 1
+            clamp[io["ys"][k]] = (b >> k) & 1
+        conv = False
+        for attempt in range(4):                 # annealers restart
+            s, conv = c.relax_energy(clamp, sweeps=6000, seed=rng.randint(0, 1 << 30))
+            got = sum(s[w] << k for k, w in enumerate(io["sum"]))
+            if conv and got == a + b:
+                break
+        if not conv:
+            bad += 1
+    print(f"  whole-network energy relaxation (4-bit adder, 20 cases): "
+          f"{'OK' if bad == 0 else f'reached ground state in {20 - bad}/20'}")
+    return bad == 0
+
+
+def test_factor():
+    ok = True
+    for bits, targets in ((4, [15, 35, 143]), (5, [21, 55, 91])):
+        c, io = multiplier(bits)
+        for N in targets:
+            target = {io["prod"][k]: (N >> k) & 1 for k in range(2 * bits)}
+            s = c.solve(io["xs"] + io["ys"], {io["zero"]: 0}, target, seed=N)
+            if s is None:
+                print(f"  factor {N}: not found")
+                ok = False
+                continue
+            a = sum(s[io["xs"][k]] << k for k in range(bits))
+            b = sum(s[io["ys"][k]] << k for k in range(bits))
+            good = a * b == N and 1 < a < N and 1 < b < N
+            print(f"  factor {N} ({bits}x{bits}): {a} x {b} {'OK' if a * b == N else 'WRONG'}")
+            ok &= a * b == N
+    return ok
+
+
+def test_sat():
+    # (x1 | x2 | ~x3) & (~x1 | x3) & (x2 | x3) & (~x2 | ~x3), a satisfiable 3-SAT.
+    clauses = [[1, 2, -3], [-1, 3], [2, 3], [-2, -3]]
+    c, io = cnf(clauses, 3)
+    s = c.solve(list(io["vars"].values()), {}, {io["sat"]: 1}, seed=1)
+    if s is None:
+        print("  SAT solve: no model found")
+        return False
+    assign = {v: s[w] for v, w in io["vars"].items()}
+    sat = all(any((assign[abs(l)] == 1) if l > 0 else (assign[abs(l)] == 0) for l in cl)
+              for cl in clauses)
+    print(f"  SAT solve: model {assign} {'satisfies' if sat else 'FAILS'} the formula")
+    return sat
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+ATTRACTOR_OUT = os.path.join(ROOT, "variants", "neural_attractor.safetensors")
+
+BITS = 8
+
+
+def main_build_attractor() -> int:
+    c, io = multiplier(BITS)
+    tensors, meta = to_tensors(c, io)
+    save_file(tensors, ATTRACTOR_OUT, metadata=meta)
+    size = os.path.getsize(ATTRACTOR_OUT)
+    print(f"Built {os.path.relpath(ATTRACTOR_OUT, ROOT)}: {BITS}x{BITS} multiplier as couplings")
+    print(f"  wires={c.n}  Q entries={len(c.Q)}  L entries={len(c.L)}  size={size/1024:.1f} KB")
+
+    # round-trip
+    t = load_file(ATTRACTOR_OUT)
+    with safe_open(ATTRACTOR_OUT, framework="pt") as f:
+        m = f.metadata()
+    c2, io2 = from_tensors(t, m)
+    xs, ys, zero, prod = io2["xs"], io2["ys"], io2["zero"], io2["prod"]
+
+    rng = random.Random(0)
+    bad = 0
+    for _ in range(200):
+        a, b = rng.randint(0, 255), rng.randint(0, 255)
+        clamp = {zero: 0}
+        for k in range(BITS):
+            clamp[xs[k]] = (a >> k) & 1
+            clamp[ys[k]] = (b >> k) & 1
+        s = c2.forward_eval(clamp)
+        got = sum(s[w] << k for k, w in enumerate(prod))
+        if got != a * b or c2.energy(s) != 0:
+            bad += 1
+    print(f"  round-trip forward multiply (200 cases): {'OK' if bad == 0 else f'FAIL({bad})'}")
+
+    # backward: factor a small product through the loaded couplings
+    N = 35
+    target = {prod[k]: (N >> k) & 1 for k in range(2 * BITS)}
+    s = c2.solve(xs + ys, {zero: 0}, target, sweeps=2500, restarts=120, seed=N)
+    if s is not None:
+        fa = sum(s[xs[k]] << k for k in range(BITS))
+        fb = sum(s[ys[k]] << k for k in range(BITS))
+        print(f"  round-trip backward factor {N}: {fa} x {fb} {'OK' if fa * fb == N else 'WRONG'}")
+        ok = fa * fb == N
+    else:
+        print(f"  round-trip backward factor {N}: not found")
+        ok = False
+    return 0 if (bad == 0 and ok) else 1
+
+# --- threshold-gate truth: the target updates are computed by Heaviside gates ---
+def H(x: int) -> int:
+    return 1 if x >= 0 else 0
+
+
+def g_and(a: int, b: int) -> int:
+    return H(a + b - 2)          # fires iff a=b=1
+
+
+def g_xor(a: int, b: int) -> int:
+    # XOR as AND(OR, NAND): OR=H(a+b-1), NAND=H(1-a-b), out=AND(OR,NAND)
+    return g_and(H(a + b - 1), H(1 - a - b))
+
+
+# --- reversible primitives, in place on a bit register (a Python list) ---
+def NOT(reg: List[int], t: int) -> None:
+    reg[t] = 1 - reg[t]
+
+
+def CNOT(reg: List[int], c: int, t: int) -> None:
+    reg[t] = g_xor(reg[t], reg[c])
+
+
+def TOFF(reg: List[int], a: int, b: int, t: int) -> None:
+    reg[t] = g_xor(reg[t], g_and(reg[a], reg[b]))
+
+
+def FRED(reg: List[int], c: int, x: int, y: int) -> None:
+    # controlled swap of x,y on control c
+    if reg[c]:
+        reg[x], reg[y] = reg[y], reg[x]
+
+
+# --- Cuccaro ripple-carry adder: b += a in place, one carry ancilla ---
+# MAJ(c,b,a): b^=a ; c^=a ; a ^= b&c        UMA(c,b,a): a ^= b&c ; c^=a ; b^=c
+def _maj(reg, c, b, a):
+    CNOT(reg, a, b)
+    CNOT(reg, a, c)
+    TOFF(reg, b, c, a)
+
+
+def _uma(reg, c, b, a):
+    TOFF(reg, b, c, a)
+    CNOT(reg, a, c)
+    CNOT(reg, c, b)
+
+
+# Each primitive below is its own inverse, so the inverse of a gate sequence is
+# the reversed sequence. Building the adder as an op list gives subtraction for
+# free (run it backward).
+def _maj_ops(c, b, a):
+    return [(CNOT, a, b), (CNOT, a, c), (TOFF, b, c, a)]
+
+
+def _uma_ops(c, b, a):
+    return [(TOFF, b, c, a), (CNOT, a, c), (CNOT, c, b)]
+
+
+def _adder_ops(a_bits, b_bits, carry, cout=None):
+    n = len(a_bits)
+    ops = _maj_ops(carry, b_bits[0], a_bits[0])
+    for i in range(1, n):
+        ops += _maj_ops(a_bits[i - 1], b_bits[i], a_bits[i])
+    if cout is not None:
+        ops.append((CNOT, a_bits[n - 1], cout))
+    for i in range(n - 1, 0, -1):
+        ops += _uma_ops(a_bits[i - 1], b_bits[i], a_bits[i])
+    ops += _uma_ops(carry, b_bits[0], a_bits[0])
+    return ops
+
+
+def _apply(reg, ops, inverse=False):
+    for gate, *args in (reversed(ops) if inverse else ops):
+        gate(reg, *args)
+
+
+def add_into(reg, a_bits, b_bits, carry, cout=None):
+    """b <- (a + b) mod 2^n (LSB first); a and carry (=0) restored."""
+    _apply(reg, _adder_ops(a_bits, b_bits, carry, cout))
+
+
+def sub_into(reg, a_bits, b_bits, carry, cout=None):
+    """b <- (b - a) mod 2^n: the adder run backward."""
+    _apply(reg, _adder_ops(a_bits, b_bits, carry, cout), inverse=True)
+
+
+def xor_into(reg, a_bits, b_bits):
+    """b <- b XOR a, bitwise (self-inverse)."""
+    for a, b in zip(a_bits, b_bits):
+        CNOT(reg, a, b)
+
+
+def incr(reg, b_bits, one_bits, carry):
+    """b <- b + 1 mod 2^n."""
+    add_into(reg, one_bits, b_bits, carry)
+
+
+def neg_into(reg, b_bits, one_bits, carry):
+    """b <- (-b) mod 2^n via two's complement (~b then +1). Self-inverse."""
+    for t in b_bits:
+        NOT(reg, t)
+    add_into(reg, one_bits, b_bits, carry)
+
+
+def rot_left(reg, b_bits, k=1):
+    """Rotate the word left by k (a permutation of bit positions; reversible)."""
+    n = len(b_bits)
+    k %= n
+    vals = [reg[b_bits[i]] for i in range(n)]
+    for i in range(n):
+        reg[b_bits[(i + k) % n]] = vals[i]
+
+
+def and_into(reg, a_bits, b_bits, t_bits):
+    """t <- t XOR (a AND b), bitwise (word-level Toffoli). Self-inverse."""
+    for a, b, t in zip(a_bits, b_bits, t_bits):
+        TOFF(reg, a, b, t)
+
+
+# --- verification helpers ---
+def is_permutation(fn, nbits: int) -> bool:
+    """Check fn: {0,1}^nbits -> {0,1}^nbits is a bijection (exhaustive)."""
+    seen = set()
+    for x in range(1 << nbits):
+        reg = [(x >> k) & 1 for k in range(nbits)]
+        fn(reg)
+        y = sum(b << k for k, b in enumerate(reg))
+        seen.add(y)
+    return len(seen) == (1 << nbits)
+
+
+def _test_primitives():
+    ok = True
+    ok &= is_permutation(lambda r: NOT(r, 0), 1)
+    ok &= is_permutation(lambda r: CNOT(r, 0, 1), 2)
+    ok &= is_permutation(lambda r: TOFF(r, 0, 1, 2), 3)
+    ok &= is_permutation(lambda r: FRED(r, 0, 1, 2), 3)
+    print(f"  primitives bijective (NOT/CNOT/TOFF/FRED): {'OK' if ok else 'FAIL'}")
+    return ok
+
+
+def _test_adder(width=4):
+    # layout: a[0..w-1], b[0..w-1], carry
+    a_bits = list(range(width))
+    b_bits = list(range(width, 2 * width))
+    carry = 2 * width
+    n = 2 * width + 1
+    ok_perm = is_permutation(lambda r: add_into(r, a_bits, b_bits, carry), n)
+    bad = 0
+    mask = (1 << width) - 1
+    for a in range(1 << width):
+        for b in range(1 << width):
+            reg = [0] * n
+            for k in range(width):
+                reg[a_bits[k]] = (a >> k) & 1
+                reg[b_bits[k]] = (b >> k) & 1
+            add_into(reg, a_bits, b_bits, carry)
+            got_a = sum(reg[a_bits[k]] << k for k in range(width))
+            got_b = sum(reg[b_bits[k]] << k for k in range(width))
+            if got_a != a or got_b != ((a + b) & mask) or reg[carry] != 0:
+                bad += 1
+    print(f"  Cuccaro adder {width}-bit: bijection={'OK' if ok_perm else 'FAIL'}  "
+          f"b<-a+b, a & carry restored={'OK' if bad == 0 else f'FAIL({bad})'}")
+    return ok_perm and bad == 0
+
+
+def bennett(reg, a_b, b_b, c_b, scr_b, out_b, carry):
+    """Bennett compute-copy-uncompute for the irreversible f(a,b,c)=(a+b) XOR c."""
+    ops = []
+    # compute f into scratch (scratch starts 0): scratch += a; scratch += b; scratch ^= c
+    ops += _adder_ops(a_b, scr_b, carry)
+    ops += _adder_ops(b_b, scr_b, carry)
+    ops += [(CNOT, c, s) for c, s in zip(c_b, scr_b)]
+    # copy scratch -> out
+    ops += [(CNOT, s, o) for s, o in zip(scr_b, out_b)]
+    # uncompute scratch (reverse of the compute prefix)
+    n_comp = len(_adder_ops(a_b, scr_b, carry)) * 2 + len(c_b)
+    ops += [(g, *args) for g, *args in reversed(ops[:n_comp])]
+    _apply(reg, ops)
+    return ops
+
+
+def _test_bennett(width=4):
+    a_b = list(range(width))
+    b_b = list(range(width, 2 * width))
+    c_b = list(range(2 * width, 3 * width))
+    scr_b = list(range(3 * width, 4 * width))
+    out_b = list(range(4 * width, 5 * width))
+    carry = 5 * width
+    n = 5 * width + 1
+    mask = (1 << width) - 1
+    bad = 0
+    for a in range(1 << width):
+        for b in range(1 << width):
+            for c in range(1 << width):
+                r = [0] * n
+                for k in range(width):
+                    r[a_b[k]] = (a >> k) & 1
+                    r[b_b[k]] = (b >> k) & 1
+                    r[c_b[k]] = (c >> k) & 1
+                bennett(r, a_b, b_b, c_b, scr_b, out_b, carry)
+                ra = sum(r[a_b[k]] << k for k in range(width))
+                rb = sum(r[b_b[k]] << k for k in range(width))
+                rc = sum(r[c_b[k]] << k for k in range(width))
+                rs = sum(r[scr_b[k]] << k for k in range(width))
+                ro = sum(r[out_b[k]] << k for k in range(width))
+                if (ra, rb, rc, rs, ro, r[carry]) != (a, b, c, 0, ((a + b) & mask) ^ c, 0):
+                    bad += 1
+    print(f"  Bennett (a,b,c,0,0)->(a,b,c,0,(a+b)^c), scratch cleaned "
+          f"[{width}-bit]: {'OK' if bad == 0 else f'FAIL({bad})'}")
+    return bad == 0
+
+
+def _test_alu(width=4):
+    mask = (1 << width) - 1
+    a_b = list(range(width))
+    b_b = list(range(width, 2 * width))
+    one_b = list(range(2 * width, 3 * width))
+    t_b = list(range(3 * width, 4 * width))
+    carry = 4 * width
+    n = 4 * width + 1
+
+    def fresh(a=0, b=0, t=0, one=False):
+        r = [0] * n
+        for k in range(width):
+            r[a_b[k]] = (a >> k) & 1
+            r[b_b[k]] = (b >> k) & 1
+            r[t_b[k]] = (t >> k) & 1
+        if one:
+            r[one_b[0]] = 1
+        return r
+
+    def rd(r, bits):
+        return sum(r[bits[k]] << k for k in range(width))
+
+    results = {}
+    # subtract
+    bad = 0
+    for a in range(1 << width):
+        for b in range(1 << width):
+            r = fresh(a, b)
+            sub_into(r, a_b, b_b, carry)
+            if rd(r, b_b) != ((b - a) & mask) or rd(r, a_b) != a or r[carry] != 0:
+                bad += 1
+    results["sub b-=a"] = bad == 0 and is_permutation(lambda r: sub_into(r, a_b, b_b, carry), n)
+    # xor
+    bad = 0
+    for a in range(1 << width):
+        for b in range(1 << width):
+            r = fresh(a, b)
+            xor_into(r, a_b, b_b)
+            if rd(r, b_b) != (a ^ b) or rd(r, a_b) != a:
+                bad += 1
+    results["xor b^=a"] = bad == 0
+    # negate
+    bad = 0
+    for b in range(1 << width):
+        r = fresh(b=b, one=True)
+        neg_into(r, b_b, one_b, carry)
+        if rd(r, b_b) != ((-b) & mask) or rd(r, one_b) != 1 or r[carry] != 0:
+            bad += 1
+    results["neg b=-b"] = bad == 0
+    # increment
+    bad = 0
+    for b in range(1 << width):
+        r = fresh(b=b, one=True)
+        incr(r, b_b, one_b, carry)
+        if rd(r, b_b) != ((b + 1) & mask):
+            bad += 1
+    results["incr b+=1"] = bad == 0
+    # rotate
+    bad = 0
+    for b in range(1 << width):
+        r = fresh(b=b)
+        rot_left(r, b_b, 1)
+        exp = ((b << 1) | (b >> (width - 1))) & mask
+        if rd(r, b_b) != exp:
+            bad += 1
+    results["rot_left"] = bad == 0
+    # and-into (Toffoli word)
+    bad = 0
+    for a in range(1 << width):
+        for b in range(1 << width):
+            for t in range(1 << width):
+                r = fresh(a, b, t)
+                and_into(r, a_b, b_b, t_b)
+                if rd(r, t_b) != (t ^ (a & b)):
+                    bad += 1
+    results["and t^=a&b"] = bad == 0
+    ok = all(results.values())
+    print("  reversible ALU " + f"{width}-bit: " +
+          "  ".join(f"{k}={'OK' if v else 'FAIL'}" for k, v in results.items()))
+    return ok
+
+
+class RCPU:
+    def __init__(self, program: List[tuple], k_regs=4, width=8, mem_words=16):
+        self.prog = program
+        self.K = k_regs
+        self.W = width
+        self.M = mem_words
+        self.mask = (1 << width) - 1
+        self.L = len(program)
+
+    def new_state(self, regs=None, mem=None) -> dict:
+        return {"R": list(regs) + [0] * (self.K - len(regs)) if regs else [0] * self.K,
+                "PC": 0, "BR": 1, "MEM": list(mem) + [0] * (self.M - len(mem)) if mem else [0] * self.M}
+
+    # ---- reversible instruction effects (forward and inverse) ----
+    def _data(self, s, I, inverse: bool):
+        R, MEM, m = s["R"], s["MEM"], self.mask
+        op = I[0]
+        if op == "ADD":
+            d, r = I[1], I[2]
+            R[d] = (R[d] - R[r]) & m if inverse else (R[d] + R[r]) & m
+        elif op == "SUB":
+            d, r = I[1], I[2]
+            R[d] = (R[d] + R[r]) & m if inverse else (R[d] - R[r]) & m
+        elif op == "ADDI":
+            d, k = I[1], I[2]
+            R[d] = (R[d] - k) & m if inverse else (R[d] + k) & m
+        elif op == "XOR":
+            R[I[1]] ^= R[I[2]]
+        elif op == "XORI":
+            R[I[1]] ^= (I[2] & m)
+        elif op == "NEG":
+            R[I[1]] = (-R[I[1]]) & m
+        elif op == "TOFF":
+            R[I[1]] ^= (R[I[2]] & R[I[3]])
+        elif op == "ROL":
+            k = (-I[2] if inverse else I[2]) % self.W
+            R[I[1]] = ((R[I[1]] << k) | (R[I[1]] >> (self.W - k))) & m if k else R[I[1]]
+        elif op == "EXCH":
+            d, r = I[1], I[2]
+            a = R[r] % self.M
+            R[d], MEM[a] = MEM[a], R[d]
+        # BRA/BEZ/HALT have no data effect
+
+    def _toggle(self, s, I):
+        """Reversible control: toggle BR for a taken branch (self-inverse)."""
+        op = I[0]
+        if op == "BRA":
+            s["BR"] ^= (I[1] ^ 1)
+        elif op == "BEZ":
+            if s["R"][I[1]] == 0:
+                s["BR"] ^= (I[2] ^ 1)
+
+    # ---- single-step transition and its inverse ----
+    def step(self, s):
+        I = self.prog[s["PC"]]
+        self._data(s, I, inverse=False)
+        self._toggle(s, I)
+        s["PC"] = (s["PC"] + s["BR"]) % self.L
+
+    def step_back(self, s):
+        s["PC"] = (s["PC"] - s["BR"]) % self.L
+        I = self.prog[s["PC"]]
+        self._toggle(s, I)               # self-inverse: restores BR
+        self._data(s, I, inverse=True)
+
+    def run(self, s, steps):
+        for _ in range(steps):
+            self.step(s)
+        return s
+
+    def run_back(self, s, steps):
+        for _ in range(steps):
+            self.step_back(s)
+        return s
+
+
+def _clone(s):
+    return {"R": list(s["R"]), "PC": s["PC"], "BR": s["BR"], "MEM": list(s["MEM"])}
+
+
+def _eq(a, b):
+    return a["R"] == b["R"] and a["PC"] == b["PC"] and a["BR"] == b["BR"] and a["MEM"] == b["MEM"]
+
+
+def test_straight_line():
+    prog = [("ADD", 1, 0), ("XOR", 1, 0), ("NEG", 1), ("ADDI", 1, 7),
+            ("TOFF", 2, 0, 1), ("ROL", 0, 1)]
+    m = RCPU(prog, width=8)
+    ok = True
+    for a in (5, 0, 255, 100):
+        for b in (3, 1, 200):
+            s0 = m.new_state([a, b, 0, 0])
+            s = _clone(s0)
+            m.run(s, len(prog))
+            fwd = _clone(s)
+            m.run_back(s, len(prog))
+            ok &= _eq(s, s0)               # round-trip recovers the exact input
+    print(f"  straight-line round-trip (dir -1 recovers input): {'OK' if ok else 'FAIL'}")
+    return ok
+
+
+def test_bijection():
+    """The single-step transition is a bijection: step_back inverts step on every instruction."""
+    import itertools
+    W = 4
+    prog = [
+        ("ADD", 1, 0), ("SUB", 1, 0), ("ADDI", 2, 3), ("XOR", 1, 2),
+        ("XORI", 0, 5), ("NEG", 3), ("TOFF", 3, 0, 1), ("ROL", 0, 1),
+        ("EXCH", 2, 3), ("BRA", 2), ("BEZ", 1, 3), ("BEZ", 0, -2),
+    ]
+    m = RCPU(prog, k_regs=4, width=W, mem_words=4)
+    bad = 0
+    checked = 0
+    rng = __import__("random").Random(0)
+    for pc in range(len(prog)):
+        for br in (1, 2, 3, -2, -1):
+            for _ in range(60):
+                s0 = {"R": [rng.randint(0, (1 << W) - 1) for _ in range(4)],
+                      "PC": pc, "BR": br,
+                      "MEM": [rng.randint(0, (1 << W) - 1) for _ in range(4)]}
+                s = _clone(s0)
+                m.step(s)
+                m.step_back(s)
+                if not _eq(s, s0):
+                    bad += 1
+                # and the other composition order
+                s = _clone(s0)
+                m.step_back(s)
+                m.step(s)
+                if not _eq(s, s0):
+                    bad += 1
+                checked += 2
+    print(f"  step_back o step = id over {checked} (state, instruction) cases: "
+          f"{'OK' if bad == 0 else f'FAIL({bad})'}")
+    return bad == 0
+
+WIDTH = 8
+
+MASK = (1 << WIDTH) - 1
+
+
+def _regs_written(stmts) -> set:
+    w = set()
+    for st in stmts:
+        op = st[0]
+        if op in ("ADD", "SUB", "ADDI", "XOR", "NEG"):
+            w.add(st[1])
+        elif op == "SWAP":
+            w.add(st[1]); w.add(st[2])
+        elif op == "FOR":
+            w |= _regs_written(st[2])
+        elif op == "IF":
+            w |= _regs_written(st[2]) | _regs_written(st[3])
+    return w
+
+
+def invert(stmts: List[tuple]) -> List[tuple]:
+    out = []
+    for st in reversed(stmts):
+        op = st[0]
+        if op == "ADD":
+            out.append(("SUB", st[1], st[2]))
+        elif op == "SUB":
+            out.append(("ADD", st[1], st[2]))
+        elif op == "ADDI":
+            out.append(("ADDI", st[1], -st[2]))
+        elif op in ("XOR", "NEG", "SWAP"):
+            out.append(st)
+        elif op == "FOR":
+            out.append(("FOR", st[1], invert(st[2])))
+        elif op == "IF":
+            # Janus: reverse swaps predicate and exit assertion, inverts branches
+            out.append(("IF", st[4], invert(st[2]), invert(st[3]), st[1]))
+    return out
+
+
+def prog_run(stmts: List[tuple], s: Dict[str, int]) -> Dict[str, int]:
+    for st in stmts:
+        op = st[0]
+        if op == "ADD":
+            s[st[1]] = (s[st[1]] + s[st[2]]) & MASK
+        elif op == "SUB":
+            s[st[1]] = (s[st[1]] - s[st[2]]) & MASK
+        elif op == "ADDI":
+            s[st[1]] = (s[st[1]] + st[2]) & MASK
+        elif op == "XOR":
+            s[st[1]] ^= s[st[2]]
+        elif op == "NEG":
+            s[st[1]] = (-s[st[1]]) & MASK
+        elif op == "SWAP":
+            s[st[1]], s[st[2]] = s[st[2]], s[st[1]]
+        elif op == "FOR":
+            cnt, body = st[1], st[2]
+            if cnt in _regs_written(body):
+                raise ValueError("FOR count register must be read-only (irreversible otherwise)")
+            for _ in range(s[cnt]):
+                prog_run(body, s)
+        elif op == "IF":
+            pred, then, els, exit_assert = st[1], st[2], st[3], st[4]
+            if pred(s):
+                prog_run(then, s)
+                assert exit_assert(s), "exit assertion violated (not reversible)"
+            else:
+                prog_run(els, s)
+                assert not exit_assert(s), "exit assertion violated (not reversible)"
+    return s
+
+
+# --- demonstration programs ---
+MULTIPLY = [("FOR", "b", [("ADD", "acc", "a")])]          # acc += a, b times; a,b preserved
+
+FIB = [("FOR", "n", [("ADD", "a", "b"), ("SWAP", "a", "b")])]   # (a,b)->(b,a+b), n times
+
+
+def _test():
+    ok = True
+
+    # reversible multiply: acc = a*b, inputs preserved; inverse clears acc
+    bad = 0
+    for a in range(16):
+        for b in range(16):
+            s = {"a": a, "b": b, "acc": 0}
+            prog_run(MULTIPLY, s)
+            if s["acc"] != (a * b) & MASK or s["a"] != a or s["b"] != b:
+                bad += 1
+            prog_run(invert(MULTIPLY), s)                       # run backward
+            if s != {"a": a, "b": b, "acc": 0}:
+                bad += 1
+    print(f"  reversible multiply acc=a*b, inputs preserved, inverse clears acc: "
+          f"{'OK' if bad == 0 else f'FAIL({bad})'}")
+    ok &= bad == 0
+
+    # reversible Fibonacci: n steps forward, inverse recovers the seed
+    bad = 0
+    for n in range(12):
+        s = {"a": 0, "b": 1, "n": n}
+        prog_run(FIB, s)
+        # forward value check against a plain reference
+        ra, rb = 0, 1
+        for _ in range(n):
+            ra, rb = rb, (ra + rb) & MASK
+        if (s["a"], s["b"]) != (ra, rb):
+            bad += 1
+        prog_run(invert(FIB), s)
+        if s != {"a": 0, "b": 1, "n": n}:
+            bad += 1
+    print(f"  reversible Fibonacci n steps, inverse recovers seed: "
+          f"{'OK' if bad == 0 else f'FAIL({bad})'}")
+    ok &= bad == 0
+
+    # a reversible conditional (Janus IF): swap when the operands differ. The
+    # exit assertion a != b is true exactly when the then-branch ran (swapping
+    # distinct values keeps them distinct; equal values are skipped), so the
+    # reverse picks the right branch.
+    prog = [("IF", lambda s: s["a"] != s["b"], [("SWAP", "a", "b")], [],
+             lambda s: s["a"] != s["b"])]
+    bad = 0
+    for a in range(16):
+        for b in range(16):
+            s = {"a": a, "b": b}
+            prog_run(prog, s)
+            if sorted([s["a"], s["b"]]) != sorted([a, b]):
+                bad += 1
+            prog_run(invert(prog), s)
+            if s != {"a": a, "b": b}:
+                bad += 1
+    print(f"  reversible conditional (Janus IF with exit assertion): "
+          f"{'OK' if bad == 0 else f'FAIL({bad})'}")
+    ok &= bad == 0
+    return ok
+
+
+REVERSIBLE_OUT = os.path.join(ROOT, "variants", "neural_reversible.safetensors")
+
+# The two reversible primitives, keyed to their gate functions.
+_CODE = {CNOT: 0, TOFF: 1}
+
+_FN = {0: CNOT, 1: TOFF}
+
+# Heaviside threshold gates that implement the target updates: a CNOT target is
+# XOR(t,c); a Toffoli target is XOR(t, AND(a,b)). AND/OR/NAND are single gates.
+_SUBSTRATE = {
+    "and_w": torch.tensor([1, 1]), "and_b": torch.tensor(-2),
+    "or_w": torch.tensor([1, 1]), "or_b": torch.tensor(-1),
+    "nand_w": torch.tensor([-1, -1]), "nand_b": torch.tensor(1),
+}
+
+
+def encode(ops):
+    codes, args = [], []
+    for gate, *a in ops:
+        codes.append(_CODE[gate])
+        args.append((a + [-1, -1, -1])[:3])
+    return torch.tensor(codes, dtype=torch.long), torch.tensor(args, dtype=torch.long)
+
+
+def main_build_reversible() -> int:
+    a_bits = list(range(WIDTH))
+    b_bits = list(range(WIDTH, 2 * WIDTH))
+    carry = 2 * WIDTH
+    n = 2 * WIDTH + 1
+    ops = _adder_ops(a_bits, b_bits, carry)
+    codes, args = encode(ops)
+
+    tensors = {"gate_code": codes, "gate_args": args, **_SUBSTRATE}
+    import json
+    meta = {"machine": "reversible", "width": str(WIDTH), "n_wires": str(n),
+            "a_bits": json.dumps(a_bits), "b_bits": json.dumps(b_bits),
+            "carry": str(carry), "circuit": "in-place reversible adder b<-a+b"}
+    save_file(tensors, REVERSIBLE_OUT, metadata=meta)
+    print(f"Built {os.path.relpath(REVERSIBLE_OUT, ROOT)}: reversible {WIDTH}-bit adder")
+    print(f"  gates={len(ops)}  wires={n}  size={os.path.getsize(REVERSIBLE_OUT)} bytes")
+
+    # round-trip: reconstruct the op list from the file and run it
+    t = load_file(REVERSIBLE_OUT)
+    with safe_open(REVERSIBLE_OUT, framework="pt") as f:
+        m = f.metadata()
+    W = int(m["width"]); ab = json.loads(m["a_bits"]); bb = json.loads(m["b_bits"])
+    cy = int(m["carry"]); nn = int(m["n_wires"])
+    loaded = []
+    for code, a in zip(t["gate_code"].tolist(), t["gate_args"].tolist()):
+        loaded.append((_FN[code], *[x for x in a if x >= 0]))
+
+    def run(reg):
+        for gate, *a in loaded:
+            gate(reg, *a)
+
+    mask = (1 << W) - 1
+    bad = 0
+    rng = random.Random(0)
+    for _ in range(400):
+        a = rng.randint(0, mask); b = rng.randint(0, mask)
+        reg = [0] * nn
+        for k in range(W):
+            reg[ab[k]] = (a >> k) & 1
+            reg[bb[k]] = (b >> k) & 1
+        run(reg)
+        got_b = sum(reg[bb[k]] << k for k in range(W))
+        got_a = sum(reg[ab[k]] << k for k in range(W))
+        if got_b != ((a + b) & mask) or got_a != a or reg[cy] != 0:
+            bad += 1
+    print(f"  round-trip b<-a+b, addend & carry restored (400 cases): "
+          f"{'OK' if bad == 0 else f'FAIL({bad})'}")
+    # bijection is exhaustive-checkable at width 4 on the same construction
+    a4 = list(range(4)); b4 = list(range(4, 8)); c4 = 8
+    ops4 = _adder_ops(a4, b4, c4)
+    perm = is_permutation(lambda r: _apply(r, ops4), 9)
+    print(f"  loaded circuit is a bijection (4-bit): {'OK' if perm else 'FAIL'}")
+    return 0 if (bad == 0 and perm) else 1
+
+
+def adder_net(width: int):
+    """The in-place Cuccaro adder as a feedforward ternary netlist computing its permutation."""
+    a_bits = list(range(width))
+    b_bits = list(range(width, 2 * width))
+    carry = 2 * width
+    n = 2 * width + 1
+    ops = _adder_ops(a_bits, b_bits, carry)
+    net = Net()
+    inputs = [f"in{i}" for i in range(n)]
+    cur = list(inputs)
+    for k, (gate, *args) in enumerate(ops):
+        if gate is CNOT:
+            c, t = args
+            cur[t] = net.XOR(f"c{k}", cur[t], cur[c])          # t ^= c
+        else:                                                   # Toffoli: t ^= a&b
+            a, b, t = args
+            tmp = net.AND(f"t{k}a", [cur[a], cur[b]])
+            cur[t] = net.XOR(f"t{k}x", cur[t], tmp)
+    return net, inputs, list(cur), n, a_bits, b_bits, carry
+
+
+def _refs(n, a_bits, b_bits, carry):
+    out = []
+    for x in range(1 << n):
+        reg = [(x >> i) & 1 for i in range(n)]
+        _apply(reg, _adder_ops(a_bits, b_bits, carry))
+        out.append(sum(reg[i] << i for i in range(n)))
+    return torch.tensor(out)
+
+
+def _outputs(mm, states, n, **step_kw):
+    v = mm.step(states.clone(), **step_kw)
+    bits = (v >= 0.5).to(torch.int64)
+    weights = torch.tensor([1 << i for i in range(n)])
+    return (bits * weights).sum(dim=1)
+
+
+def analog_sweep(mm, states, refs, n):
+    """The permutation must survive analog imperfection."""
+    print("  read-noise sweep (bit-exact = all 512 outputs still match, 4 trials):")
+    for sigma in (0.05, 0.10, 0.15, 0.20):
+        ok = all((_outputs(mm, states, n, analog=True, noise_sigma=sigma,
+                           gen=torch.Generator().manual_seed(s)) == refs).all()
+                 for s in range(4))
+        print(f"    sigma={sigma:.2f}: {'bit-exact' if ok else 'errors appear'}")
+    print("  conductance-mismatch sweep (fixed per-device weight perturbation):")
+    for sg in (0.05, 0.10, 0.15):
+        ok = (_outputs(mm.perturbed(sg, seed=0), states, n, analog=True) == refs).all()
+        print(f"    sigma_G={sg:.2f}: {'bit-exact' if ok else 'errors appear'}")
+
+
+def main_reversible_matrix() -> int:
+    width = 4
+    net, inputs, outputs, n, a_bits, b_bits, carry = adder_net(width)
+    layers, info = compile_net(net, inputs, outputs)
+    mm = MatrixMachine(layers)
+
+    states = torch.stack([torch.tensor([float((x >> i) & 1) for i in range(n)])
+                          for x in range(1 << n)])
+    refs = _refs(n, a_bits, b_bits, carry)
+    got = _outputs(mm, states, n)
+    bad = int((got != refs).sum())
+    perm = len(set(got.tolist())) == (1 << n)
+    margin = mm.min_margin(states[:256])
+
+    print(f"reversible {width}-bit adder as a ternary matrix stack")
+    print(f"  layers={info['layers']}  gates={info['gates']}  "
+          f"max_width={info['max_width']}  total_weights={info['total_weights']}")
+    print(f"  every weight ternary: {'OK' if all(((W == -1) | (W == 0) | (W == 1)).all() for W, _ in layers) else 'FAIL'}")
+    print(f"  matches the gate circuit over all {1 << n} inputs: {'OK' if bad == 0 else f'FAIL({bad})'}")
+    print(f"  composed transition is a permutation of the state space: {'OK' if perm else 'FAIL'}")
+    print(f"  analog noise margin, all layers: {margin:.3f} (guarantee 0.5)")
+    analog_sweep(mm, states, refs, n)
+    ok = bad == 0 and perm and abs(margin - 0.5) < 1e-6
+    print("PASS" if ok else "FAIL")
+    return 0 if ok else 1
+
+Block = Tuple[int, int, int, int]
+
+
+def rule(b: Block) -> Block:
+    tl, tr, bl, br = b
+    if b == (1, 0, 0, 1):
+        return (0, 1, 1, 0)          # diagonal pair -> other diagonal (deflect)
+    if b == (0, 1, 1, 0):
+        return (1, 0, 0, 1)
+    return (br, bl, tr, tl)          # otherwise rotate 180 degrees
+
+
+def is_bijection() -> bool:
+    outs = {rule(tuple((s >> k) & 1 for k in (3, 2, 1, 0))) for s in range(16)}
+    return len(outs) == 16
+
+
+def self_inverse() -> bool:
+    return all(rule(rule(tuple((s >> k) & 1 for k in (3, 2, 1, 0))))
+               == tuple((s >> k) & 1 for k in (3, 2, 1, 0)) for s in range(16))
+
+
+def step(grid: List[List[int]], phase: int) -> List[List[int]]:
+    """One Margolus update; phase 0 aligns blocks at even coordinates, phase 1 offsets them by (1,1)."""
+    H, W = len(grid), len(grid[0])
+    out = [row[:] for row in grid]
+    o = phase
+    for r0 in range(o, o + H, 2):
+        for c0 in range(o, o + W, 2):
+            r, r1 = r0 % H, (r0 + 1) % H
+            c, c1 = c0 % W, (c0 + 1) % W
+            nb = rule((grid[r][c], grid[r][c1], grid[r1][c], grid[r1][c1]))
+            out[r][c], out[r][c1], out[r1][c], out[r1][c1] = nb
+    return out
+
+
+def ca_run(grid: List[List[int]], nsteps: int, start_phase: int = 0) -> List[List[int]]:
+    g = grid
+    for n in range(nsteps):
+        g = step(g, (start_phase + n) & 1)
+    return g
+
+
+def run_back(grid: List[List[int]], nsteps: int, start_phase: int = 0) -> List[List[int]]:
+    """Undo `run`: replay the phase sequence in reverse; the rule is self-inverse."""
+    phases = [(start_phase + n) & 1 for n in range(nsteps)]
+    g = grid
+    for p in reversed(phases):
+        g = step(g, p)
+    return g
+
+
+# --- the block rule as Heaviside threshold gates ---
+# rule(s) = rotate180(s) XOR is_diag(s) on every cell: rotation fixes diagonal
+# pairs, and flipping all four cells of a rotated diagonal pair sends it to the
+# other diagonal. is_diag detects the two diagonal-pair states.
+def _H(x):
+    return 1 if x >= 0 else 0
+
+
+def _and(*xs):
+    return _H(sum(xs) - len(xs))
+
+
+def _or(*xs):
+    return _H(sum(xs) - 1)
+
+
+def _xor(a, b):
+    return _and(_or(a, b), _H(1 - a - b))       # OR AND NAND, the family's XOR
+
+
+def gate_rule(b: Block) -> Block:
+    tl, tr, bl, br = b
+    d = _or(_and(tl, 1 - tr, 1 - bl, br), _and(1 - tl, tr, bl, 1 - br))   # is_diag
+    return (_xor(br, d), _xor(bl, d), _xor(tr, d), _xor(tl, d))
+
+
+def _test_gates():
+    ok = all(gate_rule(tuple((s >> k) & 1 for k in (3, 2, 1, 0)))
+             == rule(tuple((s >> k) & 1 for k in (3, 2, 1, 0))) for s in range(16))
+    print(f"  block rule as Heaviside threshold gates matches over 16 states: "
+          f"{'OK' if ok else 'FAIL'}")
+    return ok
+
+
+# --- tests ---
+def _rand_grid(H, W, seed):
+    import random
+    rng = random.Random(seed)
+    return [[rng.randint(0, 1) for _ in range(W)] for _ in range(H)]
+
+
+def _ball_positions(g):
+    return {(r, c) for r, row in enumerate(g) for c, v in enumerate(row) if v}
+
+
+def _test_rule():
+    print(f"  block rule is a bijection of 16 states: {'OK' if is_bijection() else 'FAIL'}")
+    print(f"  block rule is self-inverse: {'OK' if self_inverse() else 'FAIL'}")
+    return is_bijection() and self_inverse()
+
+
+def _test_reversibility():
+    bad = 0
+    for seed in range(20):
+        g = _rand_grid(8, 8, seed)
+        fwd = ca_run(g, 25, start_phase=0)
+        back = run_back(fwd, 25, start_phase=0)
+        if back != g:
+            bad += 1
+    # particle count is conserved (the rule permutes cells within each block)
+    g = _rand_grid(8, 8, 99)
+    conserved = sum(sum(r) for r in g) == sum(sum(r) for r in ca_run(g, 40))
+    print(f"  lattice reversible (run then reverse recovers grid, 20 grids): "
+          f"{'OK' if bad == 0 else f'FAIL({bad})'}")
+    print(f"  particle number conserved: {'OK' if conserved else 'FAIL'}")
+    return bad == 0 and conserved
+
+
+def _test_ballistic():
+    # a single particle travels in a straight diagonal line
+    H = W = 16
+    g = [[0] * W for _ in range(H)]
+    g[2][2] = 1
+    positions = [next(iter(_ball_positions(g)))]
+    gg = g
+    for n in range(8):
+        gg = step(gg, n & 1)
+        p = _ball_positions(gg)
+        positions.append(next(iter(p)) if len(p) == 1 else None)
+    ok = all(p is not None for p in positions)
+    steady = ok and all(positions[i + 1] == (positions[i][0] + 1, positions[i][1] + 1)
+                        for i in range(len(positions) - 1))
+    print(f"  single particle stays a single particle: {'OK' if ok else 'FAIL'}")
+    print(f"  and moves ballistically on the diagonal, +(1,1) per step: "
+          f"{'OK' if steady else 'FAIL'}  trace={positions[:5]}")
+    return ok and steady
+
+
+def interaction_gate(a: int, b: int) -> dict:
+    """One billiard-ball collision as a reversible interaction gate."""
+    H = W = 12
+    g = [[0] * W for _ in range(H)]
+    if a:
+        g[2][2] = 1
+    if b:
+        g[7][7] = 1
+    g = ca_run(g, 4)
+    return {"A_and_B": g[3][6], "A_and_notB": g[6][6], "notA_and_B": g[3][3]}
+
+
+def and_gate(a: int, b: int) -> int:
+    return interaction_gate(a, b)["A_and_B"]
+
+
+def _test_gate():
+    ok = True
+    for a in (0, 1):
+        for b in (0, 1):
+            o = interaction_gate(a, b)
+            ok &= (o["A_and_B"] == (a & b) and o["A_and_notB"] == (a & (1 - b))
+                   and o["notA_and_B"] == ((1 - a) & b))
+    print(f"  billiard-ball interaction gate (A&B, A&~B, ~A&B) over all 4 inputs: "
+          f"{'OK' if ok else 'FAIL'}")
+    return ok
+
+
+def and3(a: int, b: int, c: int) -> int:
+    """Two composed collisions."""
+    H = W = 16
+    g = [[0] * W for _ in range(H)]
+    if a:
+        g[2][2] = 1
+    if b:
+        g[7][7] = 1
+    if c:
+        g[0][9] = 1
+    return ca_run(g, 4)[3][5]
+
+
+def _test_compose():
+    ok = all(and3(a, b, c) == (a & b & c)
+             for a in (0, 1) for b in (0, 1) for c in (0, 1))
+    print(f"  composed 3-input AND (two chained collisions) over all 8 inputs: "
+          f"{'OK' if ok else 'FAIL'}")
+    return ok
+
+
+def _test_collision():
+    # Two particles interact (the joint evolution differs from independent
+    # motion) and the collision stays reversible: the physics that logic needs.
+    H = W = 12
+    interacted = False
+    revok = True
+    # converging pairs: an SE-mover (even,even) meets an NW-mover (odd,odd) on a
+    # shared diagonal, forming the 1001/0110 diagonal pair the rule deflects.
+    for a, b in [((2, 2), (7, 7)), ((3, 3), (8, 8)), ((2, 8), (7, 3)),
+                 ((4, 4), (9, 9)), ((2, 2), (9, 9))]:
+        g = [[0] * W for _ in range(H)]
+        g[a[0]][a[1]] = 1
+        g[b[0]][b[1]] = 1
+        ga = [[0] * W for _ in range(H)]
+        ga[a[0]][a[1]] = 1
+        gb = [[0] * W for _ in range(H)]
+        gb[b[0]][b[1]] = 1
+        joint = g
+        for n in range(12):
+            joint = step(joint, n & 1)
+            ga = step(ga, n & 1)
+            gb = step(gb, n & 1)
+            free = _ball_positions(ga) | _ball_positions(gb)
+            if _ball_positions(joint) != free:
+                interacted = True
+        if run_back(ca_run(g, 12), 12) != g:
+            revok = False
+    print(f"  two-particle collisions interact (joint != independent motion): "
+          f"{'OK' if interacted else 'FAIL'}")
+    print(f"  collisions remain reversible: {'OK' if revok else 'FAIL'}")
+    return interacted and revok
+
+CA_OUT = os.path.join(ROOT, "variants", "neural_ca.safetensors")
+
+
+def block_net():
+    net = Net()
+    ntl, ntr = net.NOT("ntl", "tl"), net.NOT("ntr", "tr")
+    nbl, nbr = net.NOT("nbl", "bl"), net.NOT("nbr", "br")
+    d1 = net.AND("d1", ["tl", ntr, nbl, "br"])
+    d2 = net.AND("d2", [ntl, "tr", "bl", nbr])
+    dg = net.OR("dg", [d1, d2])                       # is_diag
+    TL = net.XOR("oTL", "br", dg)
+    TR = net.XOR("oTR", "bl", dg)
+    BL = net.XOR("oBL", "tr", dg)
+    BR = net.XOR("oBR", "tl", dg)
+    return net, ["tl", "tr", "bl", "br"], [TL, TR, BL, BR]
+
+
+def matrix_step(mm, grid, phase):
+    """One Margolus update driven entirely by the matrix tile."""
+    H, W = len(grid), len(grid[0])
+    out = [row[:] for row in grid]
+    for r0 in range(phase, phase + H, 2):
+        for c0 in range(phase, phase + W, 2):
+            r, r1, c, c1 = r0 % H, (r0 + 1) % H, c0 % W, (c0 + 1) % W
+            v = torch.tensor([[float(grid[r][c]), float(grid[r][c1]),
+                               float(grid[r1][c]), float(grid[r1][c1])]])
+            o = mm.step(v)[0]
+            out[r][c], out[r][c1], out[r1][c], out[r1][c1] = (int(o[0]), int(o[1]),
+                                                              int(o[2]), int(o[3]))
+    return out
+
+
+def main_build_ca() -> int:
+    net, inp, outp = block_net()
+    layers, info = compile_net(net, inp, outp)
+    mm = MatrixMachine(layers)
+
+    seen, bad, vecs = set(), 0, []
+    for s in range(16):
+        b = tuple((s >> k) & 1 for k in (3, 2, 1, 0))     # tl,tr,bl,br
+        v = torch.tensor([[float(x) for x in b]])
+        got = tuple(int(x) for x in mm.step(v)[0])
+        if got != rule(b):
+            bad += 1
+        seen.add(got)
+        vecs.append(v[0])
+    perm = len(seen) == 16
+    margin = mm.min_margin(torch.stack(vecs))
+
+    tensors = {}
+    for k, (W, B) in enumerate(layers):
+        tensors[f"matrix.layer{k:03d}.weight"] = W.to(torch.int8)
+        tensors[f"matrix.layer{k:03d}.bias"] = B.to(torch.int8)
+    meta = {"machine": "ca",
+            "rule": "Margolus reversible: rotate 180 except diagonal pair swaps (BBM class)",
+            "inputs": "tl,tr,bl,br", "outputs": "TL,TR,BL,BR", "layers": str(info["layers"])}
+    save_file(tensors, CA_OUT, metadata=meta)
+    print(f"Built {os.path.relpath(CA_OUT, ROOT)}: reversible CA block rule as a ternary matrix tile")
+    print(f"  layers={info['layers']}  gates={info['gates']}  size={os.path.getsize(CA_OUT)} bytes")
+    print(f"  every weight ternary: "
+          f"{'OK' if all(((W == -1) | (W == 0) | (W == 1)).all() for W, _ in layers) else 'FAIL'}")
+    print(f"  tile matches the block rule over all 16 states: {'OK' if bad == 0 else f'FAIL({bad})'}")
+    print(f"  tile is a permutation (16 distinct outputs): {'OK' if perm else 'FAIL'}")
+    print(f"  analog noise margin: {margin:.3f} (guarantee 0.5)")
+
+    # analog robustness: the tile must reproduce the rule under read noise and
+    # static conductance mismatch, as neural_matrix8 measures
+    states = torch.stack(vecs)
+    ref = [rule(tuple((s >> k) & 1 for k in (3, 2, 1, 0))) for s in range(16)]
+
+    def outs(machine, **kw):
+        v = machine.step(states, **kw)
+        return [tuple(int(v[i][j]) for j in range(4)) for i in range(v.shape[0])]
+
+    print("  read-noise sweep (exact = tile matches the rule on all 16 states):")
+    for sigma in (0.05, 0.10, 0.15, 0.20):
+        okn = all(outs(mm, analog=True, noise_sigma=sigma,
+                       gen=torch.Generator().manual_seed(s)) == ref for s in range(4))
+        print(f"    sigma={sigma:.2f}: {'exact' if okn else 'errors appear'}")
+    print("  conductance-mismatch sweep:")
+    for sg in (0.05, 0.10, 0.15):
+        okg = outs(mm.perturbed(sg, seed=0), analog=True) == ref
+        print(f"    sigma_G={sg:.2f}: {'exact' if okg else 'errors appear'}")
+
+    # the loaded tile, applied to every block, is one whole-lattice CA step
+    t = load_file(CA_OUT)
+    n = 0
+    lyr = []
+    while f"matrix.layer{n:03d}.weight" in t:
+        lyr.append((t[f"matrix.layer{n:03d}.weight"], t[f"matrix.layer{n:03d}.bias"]))
+        n += 1
+    mm2 = MatrixMachine(lyr)
+    g = _rand_grid(8, 8, 3)
+    gmat = matrix_step(mm2, g, 0)
+    gref = step(g, 0)
+    print(f"  loaded tile drives a full lattice step (matches ca.step): "
+          f"{'OK' if gmat == gref else 'FAIL'}")
+
+    ok = bad == 0 and perm and abs(margin - 0.5) < 1e-6 and gmat == gref
+    print("PASS" if ok else "FAIL")
+    return 0 if ok else 1
+
+# side -> (dx, dy, my_side, neighbor_side)
+_SIDES = [(0, 1, "N", "S"), (1, 0, "E", "W"), (0, -1, "S", "N"), (-1, 0, "W", "E")]
+
+
+class Tile:
+    __slots__ = ("N", "E", "S", "W", "name")
+
+    def __init__(self, N="", E="", S="", W="", name=""):
+        self.N, self.E, self.S, self.W, self.name = N, E, S, W, name
+
+    def glue(self, side):
+        return getattr(self, side)
+
+
+def bind_strength(A: Dict[Tuple[int, int], Tile], x: int, y: int, t: Tile,
+                  strength: Dict[str, int]) -> int:
+    """Summed strength of t's glues that match the abutting neighbor glues."""
+    s = 0
+    for dx, dy, side, opp in _SIDES:
+        nb = A.get((x + dx, y + dy))
+        if nb is None:
+            continue
+        g = t.glue(side)
+        if g and g == nb.glue(opp):
+            s += strength.get(g, 1)
+    return s
+
+
+def binds(A, x, y, t, tau, strength) -> bool:
+    """The threshold-gate binding decision: H(sum strength*match - tau)."""
+    return bind_strength(A, x, y, t, strength) >= tau
+
+
+def grow(tileset: List[Tile], seed: Dict[Tuple[int, int], Tile], tau: int,
+         strength: Dict[str, int], bounds: Tuple[int, int, int, int],
+         max_tiles: int = 100000) -> Tuple[Dict[Tuple[int, int], Tile], bool]:
+    """Directed growth from a seed."""
+    x0, y0, x1, y1 = bounds
+    A = dict(seed)
+    deterministic = True
+    changed = True
+    while changed and len(A) < max_tiles:
+        changed = False
+        frontier = set()
+        for (x, y) in list(A):
+            for dx, dy, _, _ in _SIDES:
+                p = (x + dx, y + dy)
+                if p not in A and x0 <= p[0] <= x1 and y0 <= p[1] <= y1:
+                    frontier.add(p)
+        for (x, y) in frontier:
+            binders = [t for t in tileset if binds(A, x, y, t, tau, strength)]
+            if len(binders) == 1:
+                A[(x, y)] = binders[0]
+                changed = True
+            elif len(binders) > 1:
+                deterministic = False
+    return A, deterministic
+
+
+# ---------------------------------------------------------------------------
+# XOR / Sierpinski tile set: value(x,y) = value(x-1,y) XOR value(x,y-1)
+# ---------------------------------------------------------------------------
+def rule2_tileset(fn) -> List[Tile]:
+    """Rule tiles for value(x,y) = fn(W, S): four cooperatively binding tiles emitting fn north and east."""
+    ts = []
+    for s in (0, 1):
+        for w in (0, 1):
+            v = fn(w, s)
+            ts.append(Tile(N=f"v{v}", E=f"v{v}", S=f"v{s}", W=f"v{w}",
+                           name=f"R w{w} s{s} -> {v}"))
+    return ts
+
+
+def sierpinski_tileset() -> List[Tile]:
+    return rule2_tileset(lambda w, s: w ^ s)
+
+
+def _row_col_seed(bottom: List[int], left: List[int]):
+    """Seed the bottom row and the left column with fixed value tiles."""
+    seed = {}
+    for x, b in enumerate(bottom):
+        seed[(x, 0)] = Tile(N=f"v{b}", E="", S="", W="", name=f"seedB{x}={b}")
+    for y, l in enumerate(left):
+        if y == 0:
+            continue
+        seed[(0, y)] = Tile(N="", E=f"v{l}", S="", W="", name=f"seedL{y}={l}")
+    return seed
+
+
+def _test_binding_gate():
+    """The binding decision is exactly the Heaviside threshold gate."""
+    strength = {"v0": 1, "v1": 1}
+    ts = sierpinski_tileset()
+    A = {(1, 0): Tile(N="v1"), (0, 1): Tile(E="v0")}
+    bad = 0
+    for t in ts:
+        for x, y in [(1, 1)]:
+            w = sum(strength.get(t.glue(side), 1)
+                    for dx, dy, side, opp in _SIDES
+                    if A.get((x + dx, y + dy)) and t.glue(side)
+                    and t.glue(side) == A[(x + dx, y + dy)].glue(opp))
+            gate = 1 if (w - 2) >= 0 else 0                # H(sum*match - tau)
+            if gate != int(binds(A, x, y, t, 2, strength)):
+                bad += 1
+    print(f"  binding decision == Heaviside gate H(sum-tau): {'OK' if bad == 0 else 'FAIL'}")
+    return bad == 0
+
+
+def _test_rule2(fn, name, n=24):
+    strength = {"v0": 1, "v1": 1}
+    bottom = [1 if x == 0 else 0 for x in range(n)]
+    left = [1 if y == 0 else 0 for y in range(n)]
+    seed = _row_col_seed(bottom, left)
+    A, det = grow(rule2_tileset(fn), seed, 2, strength, (0, 0, n - 1, n - 1))
+
+    def val(x, y):
+        t = A.get((x, y))
+        return None if t is None else (1 if t.N == "v1" else 0)
+
+    ref = {(x, 0): bottom[x] for x in range(n)}
+    ref.update({(0, y): left[y] for y in range(n)})
+    for y in range(1, n):
+        for x in range(1, n):
+            ref[(x, y)] = fn(ref[(x - 1, y)], ref[(x, y - 1)])
+
+    filled = bad = 0
+    for y in range(1, n):
+        for x in range(1, n):
+            v = val(x, y)
+            if v is not None:
+                filled += 1
+                bad += v != ref[(x, y)]
+    tag = "OK" if (det and bad == 0 and filled > 0) else "FAIL"
+    print(f"  rule-tile CA fn={name:3s}: directed={det}  placed={filled}  "
+          f"every tile = fn(W,S) {tag}")
+    return det and bad == 0 and filled > 0
+
+
+# ---------------------------------------------------------------------------
+# Binary counter: each row is the row below plus one. LSB is the right column;
+# carry propagates west by cooperative binding (S = bit below, E = carry in).
+# ---------------------------------------------------------------------------
+def counter_tileset() -> List[Tile]:
+    ts = []
+    for b in (0, 1):
+        for c in (0, 1):
+            ts.append(Tile(N=f"b{b ^ c}", E=f"c{c}", S=f"b{b}", W=f"c{b & c}",
+                           name=f"C b{b} c{c} -> b{b ^ c} carry{b & c}"))
+    ts.append(Tile(N="edge", E="", S="edge", W="c1", name="edge(+1 injector)"))
+    return ts
+
+
+def counter_seed(n: int):
+    """Bottom row (y=0) all zero, plus the right-edge +1 injector column base."""
+    seed = {}
+    for x in range(n):
+        seed[(x, 0)] = Tile(N="b0", name=f"seed b0 col{x}")
+    seed[(n, 0)] = Tile(N="edge", W="c1", name="seed edge")
+    return seed
+
+
+def _test_counter(n=6, rows=None):
+    rows = rows or (1 << n) - 1
+    strength = {"edge": 2}                       # value/carry glues default 1
+    A, det = grow(counter_tileset(), counter_seed(n), 2, strength,
+                  (0, 0, n, rows))
+
+    def rowval(y):
+        bits = []
+        for x in range(n):
+            t = A.get((x, y))
+            if t is None:
+                return None
+            bits.append(1 if t.N == "b1" else 0)
+        return sum(bit << (n - 1 - x) for x, bit in enumerate(bits))
+
+    bad = filled = 0
+    for y in range(1, rows + 1):
+        v = rowval(y)
+        if v is not None:
+            filled += 1
+            if v != (y & ((1 << n) - 1)):
+                bad += 1
+    print(f"  binary counter {n}-bit: directed={det}  rows grown={filled}  "
+          f"row y encodes the integer y {'OK' if bad == 0 else f'FAIL({bad})'}")
+    return det and bad == 0 and filled == rows
+
+
+TILE_OUT = os.path.join(ROOT, "variants", "neural_tile.safetensors")
+
+NBITS = 8
+
+TAU = 2
+
+
+def main_build_tile() -> int:
+    ts = counter_tileset()
+    strength = {"edge": 2}
+    glues = sorted({g for t in ts for g in (t.N, t.E, t.S, t.W) if g})
+    gid = {g: i for i, g in enumerate(glues)}
+    tile_glues = torch.tensor([[gid.get(t.N, -1), gid.get(t.E, -1),
+                                gid.get(t.S, -1), gid.get(t.W, -1)] for t in ts],
+                              dtype=torch.long)
+    glue_strength = torch.tensor([strength.get(g, 1) for g in glues], dtype=torch.long)
+    # per-tile binding-gate weights = strengths of the tile's four glues (0 = null)
+    bind_w = torch.tensor([[strength.get(g, 1) if g else 0 for g in (t.N, t.E, t.S, t.W)]
+                           for t in ts], dtype=torch.long)
+    tensors = {"tile_glues": tile_glues, "glue_strength": glue_strength,
+               "binding_weight": bind_w, "binding_bias": torch.tensor(-TAU)}
+    meta = {"machine": "tile", "tau": str(TAU), "glues": json.dumps(glues),
+            "tile_names": json.dumps([t.name for t in ts]), "program": "binary counter"}
+    save_file(tensors, TILE_OUT, metadata=meta)
+    print(f"Built {os.path.relpath(TILE_OUT, ROOT)}: binary-counter tile set")
+    print(f"  tiles={len(ts)}  glues={len(glues)}  tau={TAU}  size={os.path.getsize(TILE_OUT)} bytes")
+
+    # round-trip: reconstruct the tiles from the file and regrow the counter
+    t = load_file(TILE_OUT)
+    with safe_open(TILE_OUT, framework="pt") as f:
+        m = f.metadata()
+    gl = json.loads(m["glues"])
+    strg = {gl[i]: int(s) for i, s in enumerate(t["glue_strength"].tolist())}
+    tiles = []
+    for row, name in zip(t["tile_glues"].tolist(), json.loads(m["tile_names"])):
+        sides = [gl[i] if i >= 0 else "" for i in row]
+        tiles.append(Tile(N=sides[0], E=sides[1], S=sides[2], W=sides[3], name=name))
+
+    rows = (1 << NBITS) - 1
+    A, det = grow(tiles, counter_seed(NBITS), int(m["tau"]), strg,
+                    (0, 0, NBITS, rows))
+    bad = filled = 0
+    for y in range(1, rows + 1):
+        cells = [A.get((x, y)) for x in range(NBITS)]
+        if any(c is None for c in cells):
+            continue
+        filled += 1
+        v = sum((1 if c.N == "b1" else 0) << (NBITS - 1 - x) for x, c in enumerate(cells))
+        if v != (y & ((1 << NBITS) - 1)):
+            bad += 1
+    print(f"  round-trip regrow {NBITS}-bit counter: directed={det}  rows={filled}  "
+          f"row y == y {'OK' if bad == 0 else f'FAIL({bad})'}")
+
+    # the stored binding gate reproduces the model's binding decision
+    gate_ok = True
+    Atest = {(1, 0): Tile(N="b0"), (2, 0): Tile(N="b0")}
+    for ti, tt in enumerate(tiles):
+        for site in [(1, 1), (2, 1)]:
+            w = t["binding_weight"][ti].tolist()
+            match = [1 if tt.glue(side) and Atest.get((site[0] + dx, site[1] + dy))
+                     and tt.glue(side) == Atest[(site[0] + dx, site[1] + dy)].glue(opp) else 0
+                     for dx, dy, side, opp in _SIDES]
+            gate = 1 if sum(wi * mi for wi, mi in zip(w, match)) + int(t["binding_bias"]) >= 0 else 0
+            if gate != int(binds(Atest, site[0], site[1], tt, TAU, strg)):
+                gate_ok = False
+    print(f"  stored binding gate H(weight.match - tau) matches growth rule: "
+          f"{'OK' if gate_ok else 'FAIL'}")
+    return 0 if (bad == 0 and det and gate_ok) else 1
+
+
+def cmd_attractor():
+    print("Attractor computer\n" + "=" * 40)
+    print("Forward evaluation (exact, energy 0):")
+    a = test_forward()
+    print("Canonical relaxation:")
+    b = test_energy_relax()
+    print("Backward inversion (factoring by relaxation):")
+    c_ = test_factor()
+    print("SAT (clamp output to 1, relax to a model):")
+    d = test_sat()
+    print("=" * 40)
+    print("ALL PASS" if (a and b and c_ and d) else "FAILURES")
+    sys.exit(0 if (a and b and c_ and d) else 1)
+
+
+def cmd_reversible():
+    print("Reversible primitives + ALU")
+    a = _test_primitives()
+    b = _test_adder(4) and _test_adder(5)
+    c = _test_alu(4)
+    d = _test_bennett(4)
+    print("PASS" if (a and b and c and d) else "FAIL")
+
+
+def cmd_reversible_cpu():
+    print("Reversible CPU")
+    a = test_straight_line()
+    b = test_bijection()
+    print("PASS" if (a and b) else "FAIL")
+
+
+def cmd_reversible_prog():
+    print("Reversible structured programs")
+    print("PASS" if _test() else "FAIL")
+
+
+def cmd_ca():
+    print("Reversible Margolus cellular automaton")
+    a = _test_rule()
+    g = _test_gates()
+    b = _test_reversibility()
+    c = _test_ballistic()
+    d = _test_collision()
+    e = _test_gate()
+    f = _test_compose()
+    print("PASS" if (a and g and b and c and d and e and f) else "FAIL")
+
+
+def cmd_tile():
+    print("Self-assembling tile computer")
+    a = _test_binding_gate()
+    b = all(_test_rule2(fn, nm) for fn, nm in
+            [(lambda w, s: w ^ s, "XOR"), (lambda w, s: w & s, "AND"),
+             (lambda w, s: w | s, "OR")])
+    c = _test_counter()
+    print("PASS" if (a and b and c) else "FAIL")
+
+
+COMMANDS = {'attractor': cmd_attractor, 'build-attractor': main_build_attractor, 'reversible': cmd_reversible, 'reversible-cpu': cmd_reversible_cpu, 'reversible-prog': cmd_reversible_prog, 'build-reversible': main_build_reversible, 'reversible-matrix': main_reversible_matrix, 'ca': cmd_ca, 'build-ca': main_build_ca, 'tile': cmd_tile, 'build-tile': main_build_tile}
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:
+        sys.exit('commands: ' + ', '.join(COMMANDS))
+    cmd = sys.argv.pop(1)
+    sys.argv[0] += ' ' + cmd
+    sys.exit(COMMANDS[cmd]())

src/build.py

@@ -1,111 +1,16 @@
-"""
-Build tools for 8-bit Threshold Computer safetensors.
-
-Subcommands:
-    python build.py memory   - Generate 64KB memory circuits
-    python build.py inputs   - Add .inputs metadata tensors
-    python build.py all      - Run both (memory first, then inputs)
-
-
-ROUTING SCHEMA (formerly routing.json)
-======================================
-
-Routing info is now embedded in safetensors via .inputs tensors and signal registry metadata.
-
-
-INPUT SOURCE TYPES
-------------------
-
-1. External input: "$input_name" - Named input to the circuit
-   - Example: "$a", "$b", "$cin"
-
-2. Gate output: "path.to.gate" - Output of another gate
-   - Example: "ha1.sum", "layer1.or"
-
-3. Bit extraction: "$input[i]" - Single bit from multi-bit input
-   - Example: "$a[0]" (LSB), "$a[7]" (MSB for 8-bit)
-
-4. Constant: "#0" or "#1" - Fixed value
-   - Example: "#1" for carry-in in two's complement
-
-
-CIRCUIT TYPES
--------------
-
-Single-Layer Gates: .weight and .bias only
-    "boolean.and": ["$a", "$b"]
-
-Two-Layer Gates (XOR, XNOR): layer1 + layer2
-    "boolean.xor.layer1.or": ["$a", "$b"]
-    "boolean.xor.layer1.nand": ["$a", "$b"]
-    "boolean.xor.layer2": ["layer1.or", "layer1.nand"]
-
-Hierarchical Circuits: nested sub-components
-    "arithmetic.fulladder": {
-      "ha1.sum.layer1.or": ["$a", "$b"],
-      "ha1.carry": ["$a", "$b"],
-      "ha2.sum.layer1.or": ["ha1.sum", "$cin"],
-      "carry_or": ["ha1.carry", "ha2.carry"]
-    }
-
-Bit-Indexed Circuits: multi-bit operations
-    "arithmetic.ripplecarry8bit.fa0": ["$a[0]", "$b[0]", "#0"]
-    "arithmetic.ripplecarry8bit.fa1": ["$a[1]", "$b[1]", "fa0.cout"]
-
-
-PACKED MEMORY CIRCUITS
-----------------------
-
-64KB memory uses packed tensors (shapes for 16-bit address, 8-bit data):
-
-    memory.addr_decode.weight: [65536, 16]
-    memory.addr_decode.bias: [65536]
-    memory.read.and.weight: [8, 65536, 2]
-    memory.read.and.bias: [8, 65536]
-    memory.read.or.weight: [8, 65536]
-    memory.read.or.bias: [8]
-    memory.write.sel.weight: [65536, 2]
-    memory.write.sel.bias: [65536]
-    memory.write.nsel.weight: [65536, 1]
-    memory.write.nsel.bias: [65536]
-    memory.write.and_old.weight: [65536, 8, 2]
-    memory.write.and_old.bias: [65536, 8]
-    memory.write.and_new.weight: [65536, 8, 2]
-    memory.write.and_new.bias: [65536, 8]
-    memory.write.or.weight: [65536, 8, 2]
-    memory.write.or.bias: [65536, 8]
-
-Semantics:
-    decode: sel[i] = H(sum(addr_bits * weight[i]) + bias[i])
-    read:   bit[b] = H(sum(H([mem_bit, sel] * and_w) + and_b) * or_w + or_b)
-    write:  new = H(H([old, nsel] * and_old) + H([data, sel] * and_new) - 1)
-
-
-SIGNAL REGISTRY
----------------
-
-Signal IDs are stored in safetensors metadata as JSON:
-
-    {"0": "#0", "1": "#1", "2": "$a", "3": "$b", ...}
-
-Each gate's .inputs tensor contains integer IDs referencing this registry.
-
-
-NAMING CONVENTIONS
-------------------
-
-- External inputs: $name or $name[bit]
-- Constants: #0, #1
-- Internal gates: relative path from circuit root
-"""
-
+"""Builds the threshold computers, quantizes them, and builds every named variant."""
 from __future__ import annotations
 
 import argparse
 import json
+import os
 import re
+import shutil
+import subprocess
+import sys
+import time
 from pathlib import Path
-from typing import Any, Dict, Iterable, List, Optional, Set
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
 
 import torch
 from safetensors import safe_open
@@ -140,9 +45,11 @@ def get_model_path(bits: int = 8, memory_profile: str = None, addr_bits: int = N
 
 
 MODEL_PATH = MODEL_DIR / "neural_computer8.safetensors"
+
 MANIFEST_PATH = Path(__file__).resolve().parent.parent / "tensors.txt"
 
 DEFAULT_ADDR_BITS = 16
+
 DEFAULT_MEM_BYTES = 1 << DEFAULT_ADDR_BITS
 
 MEMORY_PROFILES = {
@@ -166,8 +73,7 @@ def load_tensors(path: Path) -> Dict[str, torch.Tensor]:
 
 
 def load_file_metadata(path: Path) -> Dict[str, str]:
-    """Read the safetensors header metadata so every save can carry it
-    forward (signal_registry, weight_quantization, ...)."""
+    """Read the safetensors header metadata so every save carries it forward."""
     with safe_open(str(path), framework="pt") as f:
         meta = f.metadata()
     return dict(meta) if meta else {}
@@ -264,12 +170,7 @@ def add_memory_write_cells(tensors: Dict[str, torch.Tensor], mem_bytes: int) ->
 
 
 def add_fetch_load_store_buffers(tensors: Dict[str, torch.Tensor], data_bits: int, addr_bits: int) -> None:
-    """Add control buffers for fetch, load, store operations.
-
-    Args:
-        data_bits: Width of data bus (8/16/32)
-        addr_bits: Width of address bus (determines instruction register width)
-    """
+    """Add control buffers for fetch, load, store operations."""
     # Instruction register width = opcode (8) + operands (depends on arch)
     # For simplicity, IR width = max(16, addr_bits) to hold jump targets
     ir_bits = max(16, addr_bits)
@@ -283,13 +184,7 @@ def add_fetch_load_store_buffers(tensors: Dict[str, torch.Tensor], data_bits: in
 
 
 def add_full_adder(tensors: Dict[str, torch.Tensor], prefix: str) -> None:
-    """Add a single full adder at the given prefix.
-
-    Full adder structure:
-    - ha1: first half adder (A XOR B for sum, A AND B for carry)
-    - ha2: second half adder (ha1.sum XOR Cin for sum, ha1.sum AND Cin for carry)
-    - carry_or: OR of ha1.carry and ha2.carry for final carry out
-    """
+    """Add a single full adder at the given prefix."""
     # XOR for ha1.sum (2-layer: OR + NAND -> AND)
     add_gate(tensors, f"{prefix}.ha1.sum.layer1.or", [1.0, 1.0], [-1.0])
     add_gate(tensors, f"{prefix}.ha1.sum.layer1.nand", [-1.0, -1.0], [1.0])
@@ -307,21 +202,7 @@ def add_full_adder(tensors: Dict[str, torch.Tensor], prefix: str) -> None:
 
 
 def add_expr_add_mul(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add expression circuit for A + B × C (order of operations).
-
-    Computes A + (B × C) where multiplication has higher precedence.
-
-    Structure:
-    - Stage 1: Multiply B × C using shift-add algorithm
-      - 8 mask stages: mask[i] = B AND C[i] (8 AND gates each, shifted)
-      - 7 accumulator adders to sum masked values
-    - Stage 2: Add A to multiplication result (8-bit ripple carry)
-
-    Inputs: $a[0-7], $b[0-7], $c[0-7] (MSB-first, 8-bit each)
-    Output: 8-bit result of A + (B × C), wrapping on overflow
-
-    Total: 64 AND gates + 7×8 full adders (mul) + 8 full adders (add) = ~640 gates
-    """
+    """Add expression circuit for A + B × C (order of operations)."""
     prefix = "arithmetic.expr_add_mul"
 
     # Stage 1: Multiply B × C using shift-add
@@ -357,22 +238,7 @@ def add_expr_add_mul(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_expr_paren_add_mul(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add expression circuit for (A + B) × C (parenthetical override).
-
-    Computes (A + B) × C where parentheses override normal precedence.
-    Addition happens first, then multiplication.
-
-    Structure:
-    - Stage 1: Add A + B (8-bit ripple carry adder)
-    - Stage 2: Multiply sum × C using shift-add algorithm
-      - 8 mask stages: mask[i] = sum AND C[i] (8 AND gates each)
-      - 7 accumulator adders to sum shifted masked values
-
-    Inputs: $a[0-7], $b[0-7], $c[0-7] (MSB-first, 8-bit each)
-    Output: 8-bit result of (A + B) × C, wrapping on overflow
-
-    Total: 8 full adders (add) + 64 AND gates + 56 full adders (mul) = ~640 gates
-    """
+    """Add expression circuit for (A + B) × C (parenthetical override)."""
     prefix = "arithmetic.expr_paren_add_mul"
 
     # Stage 1: Add A + B
@@ -392,21 +258,7 @@ def add_expr_paren_add_mul(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_expr_paren(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add expression circuit for (A + B) × C (parenthetical grouping).
-
-    Computes (A + B) × C where addition happens first due to parentheses.
-
-    Structure:
-    - Stage 1: Add A + B (8-bit ripple carry)
-    - Stage 2: Multiply sum × C using shift-add algorithm
-      - 8 mask stages: mask[i] = sum AND C[i] (8 AND gates each)
-      - 7 accumulator adders to sum shifted masked values
-
-    Inputs: $a[0-7], $b[0-7], $c[0-7] (MSB-first, 8-bit each)
-    Output: 8-bit result of (A + B) × C, wrapping on overflow
-
-    Total: 8 full adders (add) + 64 AND gates + 56 full adders (mul) = ~640 gates
-    """
+    """Add expression circuit for (A + B) × C (parenthetical grouping)."""
     prefix = "arithmetic.expr_paren"
 
     # Stage 1: Add A + B
@@ -426,17 +278,7 @@ def add_expr_paren(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_add3(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add 3-operand 8-bit adder circuit.
-
-    Computes A + B + C using two chained ripple-carry stages:
-    - Stage 1: temp = A + B (8 full adders)
-    - Stage 2: result = temp + C (8 full adders)
-
-    Inputs: $a[0-7], $b[0-7], $c[0-7] (MSB-first)
-    Outputs: stage2.fa0-7.ha2.sum.layer2 (result bits), stage2.fa7.carry_or (overflow)
-
-    Total: 16 full adders = 144 gates
-    """
+    """Add 3-operand 8-bit adder circuit."""
     # Stage 1: A + B -> temp
     for bit in range(8):
         add_full_adder(tensors, f"arithmetic.add3_8bit.stage1.fa{bit}")
@@ -447,14 +289,7 @@ def add_add3(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_shl_shr(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add SHL (shift left) and SHR (shift right) circuits.
-
-    Identity gate: w=1, b=-1 -> H(x - 1) = x for x in {0,1}
-    Zero gate: w=0, b=-1 -> H(-1) = 0
-
-    SHL (MSB-first): out[i] = in[i+1] for i<7, out[7] = 0
-    SHR (MSB-first): out[0] = 0, out[i] = in[i-1] for i>0
-    """
+    """Add SHL (shift left) and SHR (shift right) circuits."""
     for bit in range(8):
         if bit < 7:
             add_gate(tensors, f"alu.alu8bit.shl.bit{bit}", [1.0], [-1.0])
@@ -469,18 +304,7 @@ def add_shl_shr(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_mul(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add 8-bit multiplication circuit.
-
-    Produces low 8 bits of the 16-bit result.
-
-    Structure:
-    - 64 AND gates for partial products P[i][j] = A[i] AND B[j]
-    - Uses existing ripple-carry adder components for summation
-
-    The multiply method in ThresholdALU computes:
-    1. Partial products via these AND gates
-    2. Shift-add accumulation via existing 8-bit adder
-    """
+    """Add 8-bit multiplication circuit."""
     # AND gates for partial products: P[i][j] = A[i] AND B[j]
     # These compute whether bit i of A and bit j of B are both 1
     for i in range(8):
@@ -489,19 +313,7 @@ def add_mul(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_div(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add 8-bit division circuit.
-
-    Produces quotient (8 bits) and remainder (8 bits).
-
-    Uses restoring division algorithm:
-    - 8 iterations, each producing one quotient bit
-    - Each iteration: compare, conditionally subtract, shift
-
-    Structure:
-    - 8 comparison gates (one per iteration)
-    - 8 conditional subtraction stages
-    - Uses existing comparator and subtractor components
-    """
+    """Add 8-bit division circuit."""
     # Comparison gates: check if (remainder << 1 | next_bit) >= divisor
     # Bit-cascaded ternary GE comparator per stage.
     for stage in range(8):
@@ -529,14 +341,7 @@ def add_div(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_inc_dec(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add INC and DEC circuits.
-
-    INC: A + 1 using half adders with carry chain
-    DEC: A - 1 using borrow chain (A + 255, two's complement of 1)
-
-    For INC, we add 1 to the LSB and propagate carry.
-    For DEC, we add 0xFF (two's complement of 1) or use borrow logic.
-    """
+    """Add INC and DEC circuits."""
     # INC: half adder chain starting with carry_in = 1
     # bit 7 (LSB): XOR with 1, carry = bit[7]
     # bit 6: XOR with carry, new_carry = bit[6] AND old_carry
@@ -563,12 +368,7 @@ def add_inc_dec(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_neg(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add NEG circuit (two's complement negation).
-
-    NEG(A) = NOT(A) + 1 = ~A + 1
-
-    Structure: NOT gates followed by INC-style adder.
-    """
+    """Add NEG circuit (two's complement negation)."""
     for bit in range(8):
         # NOT gate for each bit
         add_gate(tensors, f"alu.alu8bit.neg.not.bit{bit}", [-1.0], [0.0])
@@ -585,14 +385,7 @@ def add_rol_ror(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_rol_ror_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
-    """Add N-bit ROL and ROR circuits (rotate left/right).
-
-    ROL: out[i] = in[i+1] for i<N-1, out[N-1] = in[0] (MSB wraps to LSB)
-    ROR: out[0] = in[N-1], out[i] = in[i-1] for i>0 (LSB wraps to MSB)
-
-    Args:
-        bits: Data width (8, 16, 32, etc.)
-    """
+    """Add N-bit ROL and ROR circuits (rotate left/right)."""
     # ROL: rotate left (toward MSB)
     for bit in range(bits):
         add_gate(tensors, f"alu.alu{bits}bit.rol.bit{bit}", [1.0], [-1.0])
@@ -603,19 +396,7 @@ def add_rol_ror_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
 
 
 def add_stack_ops(tensors: Dict[str, torch.Tensor], data_bits: int, addr_bits: int) -> None:
-    """Add RET, PUSH, POP circuit components.
-
-    These are higher-level operations that use memory read/write.
-    We create the control logic gates.
-
-    Args:
-        data_bits: Width of data to push/pop (8/16/32)
-        addr_bits: Width of stack pointer and return addresses
-
-    RET: Pop return address from stack, jump to it
-    PUSH: Decrement SP, write value to [SP]
-    POP: Read value from [SP], increment SP
-    """
+    """Add RET, PUSH, POP circuit components."""
     # SP decrement for PUSH (addr_bits wide)
     for bit in range(addr_bits):
         add_gate(tensors, f"control.push.sp_dec.bit{bit}.xor.layer1.or", [1.0, 1.0], [-1.0])
@@ -644,21 +425,7 @@ def add_stack_ops(tensors: Dict[str, torch.Tensor], data_bits: int, addr_bits: i
 
 
 def add_conditional_jumps(tensors: Dict[str, torch.Tensor], addr_bits: int) -> None:
-    """Add conditional jump circuits (JZ, JNZ, JC, JNC, JP, JN, JV, JNV).
-
-    Each conditional jump is a 2:1 MUX per address bit:
-    - If flag is set: output = target_bit
-    - If flag is clear: output = pc_bit
-
-    Structure per bit:
-    - not_sel: NOT(flag)
-    - and_a: pc_bit AND NOT(flag)
-    - and_b: target_bit AND flag
-    - or: and_a OR and_b
-
-    Args:
-        addr_bits: Width of program counter / jump target
-    """
+    """Add conditional jump circuits (JZ, JNZ, JC, JNC, JP, JN, JV, JNV)."""
     jump_types = ['jz', 'jnz', 'jc', 'jnc', 'jp', 'jn', 'jv', 'jnv']
 
     for jmp in jump_types:
@@ -675,19 +442,14 @@ def add_conditional_jumps(tensors: Dict[str, torch.Tensor], addr_bits: int) -> N
 
 
 def add_computer_decode(tensors: Dict[str, torch.Tensor]) -> None:
-    """Instruction decode for the 8-bit computer as threshold gates: a 4-to-16
-    opcode one-hot decoder (exact match on the instruction's opcode nibble). The
-    runtime reads these one-hots to dispatch instead of slicing the word."""
+    """The 4-to-16 opcode one-hot decoder of the 8-bit computer."""
     for opc in range(16):
         w = [1.0 if (opc >> j) & 1 else -1.0 for j in range(4)]
         add_gate(tensors, f"control.decode.op{opc}", w, [-float(bin(opc).count("1"))])
 
 
 def add_computer_pcnext(tensors: Dict[str, torch.Tensor], addr_bits: int) -> None:
-    """PC sequencing for the 8-bit computer as threshold gates: PC+2 / PC+4
-    increment chains and a priority mux selecting the next PC among PC+2 (ALU),
-    PC+4 (load/store), the conditional-jump mux, and the direct target
-    (JMP/CALL). Replaces the runtime's Python PC+2/PC+4 and jump wiring."""
+    """Next-PC selection of the 8-bit computer among PC+2, PC+4, the jump mux and the direct target."""
     for name, start in (("pc2", 1), ("pc4", 2)):
         for bit in range(addr_bits):
             if bit < start:
@@ -707,17 +469,7 @@ def add_computer_pcnext(tensors: Dict[str, torch.Tensor], addr_bits: int) -> Non
 
 
 def add_status_flags(tensors: Dict[str, torch.Tensor], data_bits: int) -> None:
-    """Add status flag computation circuits (Z, N, C, V).
-
-    Args:
-        data_bits: Width of ALU data (8/16/32)
-
-    Flags:
-    - Z (Zero): NOR of all result bits (1 if result == 0)
-    - N (Negative): Copy of MSB (sign bit)
-    - C (Carry): Carry out from adder (external input)
-    - V (Overflow): XOR of carry into and out of MSB (signed overflow)
-    """
+    """Add status flag computation circuits (Z, N, C, V)."""
     # Z flag: NOR of all bits (result == 0)
     # Single threshold gate: fires if sum of all bits < 1
     add_gate(tensors, "flags.zero", [-1.0] * data_bits, [0.0])
@@ -741,14 +493,7 @@ def add_barrel_shifter(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_barrel_shifter_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
-    """Add N-bit barrel shifter circuit.
-
-    Shifts input by 0 to (bits-1) positions based on ceil(log2(bits))-bit shift amount.
-    Uses layers of 2:1 muxes controlled by shift amount bits.
-
-    Args:
-        bits: Data width (8, 16, 32, etc.)
-    """
+    """Add N-bit barrel shifter circuit."""
     import math
     num_layers = max(1, math.ceil(math.log2(bits)))
 
@@ -769,21 +514,7 @@ def add_priority_encoder(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_priority_encoder_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
-    """Add N-bit priority encoder circuit.
-
-    Finds the position of the highest set bit (0 to bits-1).
-    Position 0 = MSB (highest priority), Position bits-1 = LSB (lowest priority).
-    Output is ceil(log2(bits))-bit index + valid flag.
-
-    Circuit structure:
-    1. any_higher{pos}: OR of bits 0 to pos-1 (all higher-priority positions)
-    2. is_highest{pos}: bit[pos] AND NOT(any_higher{pos})
-    3. out{bit}: OR of is_highest{pos} for positions where (pos >> bit) & 1
-    4. valid: OR of all input bits
-
-    Args:
-        bits: Input width (8, 16, 32, etc.)
-    """
+    """Add N-bit priority encoder circuit."""
     import math
     out_bits = max(1, math.ceil(math.log2(bits)))
     prefix = f"combinational.priorityencoder{bits}"
@@ -827,31 +558,7 @@ def add_bit_cascade_compare(
     out_le: str,
     out_eq: str,
 ) -> None:
-    """Generic ternary-only N-bit comparator.
-
-    Inputs are two N-bit values A and B in MSB-first order. The structure
-    produces unsigned-magnitude GT, LT, GE, LE, EQ outputs using only
-    weights in {-1, 0, 1} and integer biases.
-
-    Per-bit primitives (i = 0 is the MSB):
-      {cmp_prefix}.bit{i}.gt              A[i] AND NOT B[i]   weights [1, -1], bias -1
-      {cmp_prefix}.bit{i}.lt              NOT A[i] AND B[i]   weights [-1, 1], bias -1
-      {cmp_prefix}.bit{i}.eq.layer1.and   A[i] AND B[i]
-      {cmp_prefix}.bit{i}.eq.layer1.nor   NOR(A[i], B[i])
-      {cmp_prefix}.bit{i}.eq              XNOR via OR of layer1 outputs
-
-    Cascade (linear chain from MSB to LSB):
-      {cmp_prefix}.cascade.eq_prefix.bit{i}   AND of eq[0..i-1] (i in 1..N-1)
-      {cmp_prefix}.cascade.gt.bit{i}          eq_prefix[i] AND gt[i]
-      {cmp_prefix}.cascade.lt.bit{i}          eq_prefix[i] AND lt[i]
-
-    Final outputs:
-      out_gt = OR of (gt[0], cascade.gt.bit{1..N-1})
-      out_lt = OR of (lt[0], cascade.lt.bit{1..N-1})
-      out_eq = AND of all eq[i]
-      out_ge = NOT(out_lt)
-      out_le = NOT(out_gt)
-    """
+    """Generic ternary-only N-bit comparator."""
     for i in range(bits):
         # per-bit GT: A[i] AND NOT B[i]   ->  H(A - B - 1)
         add_gate(tensors, f"{cmp_prefix}.bit{i}.gt", [1.0, -1.0], [-1.0])
@@ -891,11 +598,7 @@ def add_bit_cascade_compare(
 
 
 def add_comparators(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add 8-bit comparator circuits (GT, LT, GE, LE, EQ) using bit-cascade.
-
-    Inputs are 8 bits of A then 8 bits of B in MSB-first order. The
-    underlying bit-cascade produces only ternary {-1, 0, 1} weights.
-    """
+    """Add 8-bit comparator circuits (GT, LT, GE, LE, EQ) using bit-cascade."""
     add_bit_cascade_compare(
         tensors,
         cmp_prefix="arithmetic.cmp8bit",
@@ -909,30 +612,14 @@ def add_comparators(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_ripple_carry_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
-    """Add N-bit ripple carry adder circuit.
-
-    Creates a chain of full adders for N-bit addition.
-    Works for 8, 16, or 32 bits.
-
-    Inputs: $a[0..N-1], $b[0..N-1] (MSB-first)
-    Outputs: fa0-fa{N-1} sum bits, fa{N-1}.carry_or for overflow
-    """
+    """Add N-bit ripple carry adder circuit."""
     prefix = f"arithmetic.ripplecarry{bits}bit"
     for bit in range(bits):
         add_full_adder(tensors, f"{prefix}.fa{bit}")
 
 
 def add_sub_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
-    """Add N-bit subtractor circuit (A - B).
-
-    Uses two's complement: A - B = A + (~B) + 1
-
-    Structure:
-    - NOT gates for each bit of B
-    - N-bit ripple carry adder with carry_in = 1
-
-    The carry_in=1 is handled by the adder's fa0 having cin=#1 instead of #0.
-    """
+    """Add N-bit subtractor circuit (A - B)."""
     prefix = f"arithmetic.sub{bits}bit"
 
     for bit in range(bits):
@@ -943,10 +630,7 @@ def add_sub_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
 
 
 def add_comparators_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
-    """Add N-bit comparator circuits (GT, LT, GE, LE, EQ) via bit-cascade.
-
-    All weights are in {-1, 0, 1}. Inputs are A bits then B bits, MSB-first.
-    """
+    """Add N-bit comparator circuits (GT, LT, GE, LE, EQ) via bit-cascade."""
     add_bit_cascade_compare(
         tensors,
         cmp_prefix=f"arithmetic.cmp{bits}bit",
@@ -960,27 +644,14 @@ def add_comparators_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
 
 
 def add_mul_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
-    """Add N-bit multiplication circuit.
-
-    Produces low N bits of the 2N-bit result.
-
-    Structure:
-    - N*N AND gates for partial products P[i][j] = A[i] AND B[j]
-    - Shift-add accumulation using existing adder circuits
-
-    For 32-bit: 1024 AND gates for partial products.
-    """
+    """Add N-bit multiplication circuit."""
     for i in range(bits):
         for j in range(bits):
             add_gate(tensors, f"alu.alu{bits}bit.mul.pp.a{i}b{j}", [1.0, 1.0], [-2.0])
 
 
 def add_div_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
-    """Add N-bit division circuit.
-
-    Uses restoring division algorithm with N iterations. Each stage's
-    comparator (rem >= div) is a ternary bit-cascade GE.
-    """
+    """Add N-bit division circuit."""
     for stage in range(bits):
         add_bit_cascade_compare(
             tensors,
@@ -1002,10 +673,7 @@ def add_div_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
 
 
 def add_bitwise_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
-    """Add N-bit bitwise operation circuits (AND, OR, XOR, NOT).
-
-    These are simply N copies of the 1-bit gates.
-    """
+    """Add N-bit bitwise operation circuits (AND, OR, XOR, NOT)."""
     for bit in range(bits):
         add_gate(tensors, f"alu.alu{bits}bit.and.bit{bit}", [1.0, 1.0], [-2.0])
 
@@ -1022,11 +690,7 @@ def add_bitwise_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
 
 
 def add_shift_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
-    """Add N-bit shift circuits (SHL, SHR by 1 position).
-
-    SHL: out[i] = in[i+1] for i<N-1, out[N-1] = 0
-    SHR: out[0] = 0, out[i] = in[i-1] for i>0
-    """
+    """Add N-bit shift circuits (SHL, SHR by 1 position)."""
     for bit in range(bits):
         if bit < bits - 1:
             add_gate(tensors, f"alu.alu{bits}bit.shl.bit{bit}", [1.0], [-1.0])
@@ -1067,19 +731,7 @@ def add_neg_nbits(tensors: Dict[str, torch.Tensor], bits: int) -> None:
 
 
 def add_float16_core(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add float16 core circuits (unpack, pack, classify).
-
-    IEEE 754 half-precision format (16 bits):
-    - Bit 15: Sign (0=positive, 1=negative)
-    - Bits 14-10: Exponent (5 bits, bias=15)
-    - Bits 9-0: Mantissa/fraction (10 bits, implicit leading 1 for normalized)
-
-    Special values:
-    - Zero: exp=0, frac=0
-    - Subnormal: exp=0, frac≠0
-    - Infinity: exp=31, frac=0
-    - NaN: exp=31, frac≠0
-    """
+    """Add float16 core circuits (unpack, pack, classify)."""
     prefix = "float16"
 
     # Identity buffers: H(x - 1) reproduces a binary input (bias 0 would
@@ -1103,28 +755,7 @@ def add_float16_core(tensors: Dict[str, torch.Tensor]) -> None:
 
 def add_float_add(tensors: Dict[str, torch.Tensor], family: str,
                   exp_bits: int, frac_bits: int) -> None:
-    """Add a complete float addition/subtraction pipeline.
-
-    Self-contained circuit; external inputs are the raw operand words
-    $a[0..W-1] / $b[0..W-1] (MSB-first). Contract: exact IEEE specials
-    (NaN, infinities, signed zeros, opposite-sign infinities -> NaN, exact
-    cancellation -> +0), subnormal operands and gradual-underflow subnormal
-    results, round-to-nearest-even for the mantissa. A zero operand passes the
-    other operand through verbatim.
-
-    Datapath: payload comparison picks the larger-magnitude operand, swap
-    muxes route it to L; the smaller mantissa is aligned right through a
-    capped barrel shifter over an F+3-bit round+guard frame with a sticky
-    collector; add and subtract chains run in parallel (the subtract chain
-    takes the sticky as a borrow-in so its round bit is exact) and the sign
-    agreement selects; a leading-zero counter drives the left renormalize
-    barrel; guard/round/sticky then drive a round-to-nearest-even increment
-    on the fraction with a carry into the exponent; two E+2-bit exponent
-    chains compute exp_L + 1 - nlz plus the rounding carry; and a one-hot
-    specials network selects the output word.
-
-    Rounding: round-to-nearest-even (RNE), matching multiply and divide.
-    """
+    """Add a complete float addition/subtraction pipeline."""
     E, F = exp_bits, frac_bits
     P = E + F              # payload width
     FRAME = F + 3          # mantissa + guard + round
@@ -1341,21 +972,7 @@ def add_float16_add(tensors: Dict[str, torch.Tensor]) -> None:
 
 def add_float_mul(tensors: Dict[str, torch.Tensor], family: str,
                   exp_bits: int, frac_bits: int) -> None:
-    """Add a complete float multiplication pipeline.
-
-    Self-contained circuit; external inputs are the raw operand words
-    $a[0..W-1] / $b[0..W-1] (MSB-first). Contract: exact IEEE specials
-    (NaN, infinities, signed zeros), subnormal operands and gradual-underflow
-    subnormal results, round-to-nearest-even for the mantissa.
-
-    Datapath: (F+1)x(F+1) partial products accumulated shift-add into the
-    2F+2-bit product; a leading-zero count and an E+2-bit exponent chain give
-    exp_base = exp_a + exp_b - bias and a signed clamp min(nlz, exp_base); the
-    product is right-shifted by (F+1) - that clamp (one shifter that normalizes
-    normal results, denormalizes subnormal ones, and drives deeply underflowing
-    products to zero), then round-to-nearest-even and a one-hot specials network
-    produce the output word.
-    """
+    """Add a complete float multiplication pipeline."""
     E, F = exp_bits, frac_bits
     prefix = f"{family}.mul"
 
@@ -1498,22 +1115,7 @@ def add_float16_mul(tensors: Dict[str, torch.Tensor]) -> None:
 
 def add_float_div(tensors: Dict[str, torch.Tensor], family: str,
                   exp_bits: int, frac_bits: int) -> None:
-    """Add a complete float division pipeline.
-
-    Self-contained circuit; external inputs are the raw operand words
-    $a[0..W-1] / $b[0..W-1] (MSB-first). Contract: exact IEEE specials
-    (NaN, infinities, signed zeros, x/0 -> inf, 0/0 and inf/inf -> NaN),
-    subnormal operands and gradual-underflow subnormal results,
-    round-to-nearest-even for the mantissa.
-
-    Datapath: each operand mantissa is pre-normalized (a leading-zero count
-    drives a left-barrel so the leading 1 sits at bit F, and na = eexp - lz);
-    F+3 restoring-division stages produce the quotient; a one-bit normalize mux
-    aligns it on the integer quotient bit; two E+2-bit exponent chains give
-    er = na - nb + bias - 1 + q0; the aligned mantissa frame is right-shifted by
-    max(0, 1 - er) to denormalize subnormal quotients; then round-to-nearest-even
-    and a one-hot specials network produce the output word.
-    """
+    """Add a complete float division pipeline."""
     E, F = exp_bits, frac_bits
     prefix = f"{family}.div"
     NSTAGE = F + 3
@@ -1686,21 +1288,7 @@ def add_float16_div(tensors: Dict[str, torch.Tensor]) -> None:
 
 def add_float_fma(tensors: Dict[str, torch.Tensor], family: str,
                   exp_bits: int, frac_bits: int) -> None:
-    """Fused multiply-add: round(a*b + c) with a SINGLE rounding (F-extension).
-
-    Self-contained; external inputs are the raw operand words $a/$b/$c
-    (MSB-first). Contract: exact IEEE specials (NaN, infinities, inf*0 and
-    inf-inf -> NaN, signed zeros), subnormal operands and gradual-underflow
-    subnormal results, round-to-nearest-even, single rounding of a*b+c.
-
-    Datapath: each mantissa is pre-normalized (leading 1 at bit F, na=eexp-lz);
-    the (F+1)x(F+1) product Mp (2F+2 bits) and the addend Mc are right-shifted by
-    sticky barrel shifters into a common 3(F+1)+4-bit field anchored at
-    max(product,c) exponent; a signed magnitude add (with a borrow when the
-    shifted-out subtrahend leaves a tail) forms the sum; a leading-zero count and
-    normalize give the significand, one round-to-nearest-even rounds it, and a
-    one-hot specials network packs the result.
-    """
+    """Fused multiply-add: round(a*b + c) with a SINGLE rounding (F-extension)."""
     E, F = exp_bits, frac_bits
     W = 1 + E + F
     p = F + 1
@@ -1981,18 +1569,7 @@ def add_float_fma(tensors: Dict[str, torch.Tensor], family: str,
 
 def add_float_cmp(tensors: Dict[str, torch.Tensor], family: str,
                   exp_bits: int, frac_bits: int) -> None:
-    """Add a complete IEEE 754 comparison network (EQ, LT, LE, GT, GE).
-
-    Self-contained circuit: external inputs are the raw operand words
-    $a[0..W-1], $b[0..W-1] (MSB-first; bit 0 is the sign, bits 1..E the
-    exponent, the rest the fraction). Composition:
-
-    1. NaN detection gates every result (any comparison with NaN is false).
-    2. both_zero makes +0 == -0 (and suppresses the mixed-sign LT/GT).
-    3. Same signs: IEEE encodings order like sign-magnitude integers, so the
-       payload magnitude comparator decides, inverted for negatives.
-    4. Different signs: the negative operand is smaller (unless both zero).
-    """
+    """Add a complete IEEE 754 comparison network (EQ, LT, LE, GT, GE)."""
     prefix = f"{family}.cmp"
     payload = exp_bits + frac_bits
 
@@ -2080,13 +1657,7 @@ def add_float16_cmp(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_float32_core(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add float32 core circuits (unpack, pack, classify).
-
-    IEEE 754 single-precision format (32 bits):
-    - Bit 31: Sign
-    - Bits 30-23: Exponent (8 bits, bias=127)
-    - Bits 22-0: Mantissa (23 bits, implicit leading 1)
-    """
+    """Add float32 core circuits (unpack, pack, classify)."""
     prefix = "float32"
 
     # Identity buffers: H(x - 1) reproduces a binary input (bias 0 would
@@ -2125,13 +1696,7 @@ def add_float32_div(tensors: Dict[str, torch.Tensor]) -> None:
     add_float_div(tensors, "float32", 8, 23)
 
 def update_manifest(tensors: Dict[str, torch.Tensor], data_bits: int, addr_bits: int, mem_bytes: int) -> None:
-    """Update manifest metadata tensors.
-
-    Args:
-        data_bits: ALU/register width (8/16/32)
-        addr_bits: Address bus width (determines memory size)
-        mem_bytes: Memory size in bytes (2^addr_bits)
-    """
+    """Update manifest metadata tensors."""
     tensors["manifest.data_bits"] = torch.tensor([float(data_bits)], dtype=torch.float32)
     tensors["manifest.addr_bits"] = torch.tensor([float(addr_bits)], dtype=torch.float32)
     tensors["manifest.memory_bytes"] = torch.tensor([float(mem_bytes)], dtype=torch.float32)
@@ -2228,16 +1793,7 @@ def infer_ripplecarry_inputs(gate: str, prefix: str, bits: int, reg: SignalRegis
 
 
 def infer_expr_add_mul_inputs(gate: str, reg: SignalRegistry) -> List[int]:
-    """Infer inputs for A + B × C expression circuit (order of operations).
-
-    Circuit structure:
-    - Mask stage: mask.s[stage].b[bit] = B[bit] AND C[stage]
-    - Accumulator stages 1-7: acc.s[stage] = acc.s[stage-1] + (mask.s[stage] << stage)
-    - Final add: result = A + acc.s7
-
-    Bit ordering: MSB-first externally, LSB-first internally (fa0 = LSB, fa7 = MSB)
-    - $x[7] = bit 0 (LSB), $x[0] = bit 7 (MSB)
-    """
+    """Infer inputs for A + B × C expression circuit (order of operations)."""
     prefix = "arithmetic.expr_add_mul"
 
     # Register all inputs
@@ -2348,15 +1904,7 @@ def infer_expr_add_mul_inputs(gate: str, reg: SignalRegistry) -> List[int]:
 
 
 def infer_expr_paren_add_mul_inputs(gate: str, reg: SignalRegistry) -> List[int]:
-    """Infer inputs for (A + B) × C expression circuit (parenthetical override).
-
-    Circuit structure:
-    - Add stage: sum = A + B
-    - Mask stage: mask.s[stage].b[bit] = sum[bit] AND C[stage]
-    - Accumulator stages 1-7: acc.s[stage] = acc.s[stage-1] + (mask.s[stage] << stage)
-
-    Bit ordering: MSB-first externally, LSB-first internally (fa0 = LSB, fa7 = MSB)
-    """
+    """Infer inputs for (A + B) × C expression circuit (parenthetical override)."""
     prefix = "arithmetic.expr_paren_add_mul"
 
     # Register all inputs
@@ -2463,15 +2011,7 @@ def infer_expr_paren_add_mul_inputs(gate: str, reg: SignalRegistry) -> List[int]
 
 
 def infer_expr_paren_inputs(gate: str, reg: SignalRegistry) -> List[int]:
-    """Infer inputs for (A + B) × C expression circuit (parenthetical grouping).
-
-    Circuit structure:
-    - Add stage: sum = A + B
-    - Mask stage: mask.s[stage].b[bit] = sum[bit] AND C[stage]
-    - Accumulator stages 1-7: acc.s[stage] = acc.s[stage-1] + (mask.s[stage] << stage)
-
-    Bit ordering: MSB-first externally, LSB-first internally (fa0 = LSB, fa7 = MSB)
-    """
+    """Infer inputs for (A + B) × C expression circuit (parenthetical grouping)."""
     prefix = "arithmetic.expr_paren"
 
     # Register all inputs
@@ -3117,11 +2657,7 @@ def infer_combinational_inputs(gate: str, reg: SignalRegistry, tensors: Dict[str
 
 def _infer_bit_cascade(gate: str, reg: SignalRegistry, cmp_prefix: str,
                        a_template: str, b_template: str) -> List[int] | None:
-    """If `gate` is part of the bit-cascade comparator at `cmp_prefix`, return
-    its inputs. `a_template` / `b_template` are format strings like
-    "$a[{}]" / "$b[{}]" that produce the per-bit input signal names. Returns
-    None if `gate` isn't a member of this cascade.
-    """
+    """If `gate` is part of the bit-cascade comparator at `cmp_prefix`, return its inputs."""
     if not gate.startswith(cmp_prefix + "."):
         return None
     suffix = gate[len(cmp_prefix) + 1:]
@@ -3161,10 +2697,7 @@ def _infer_bit_cascade(gate: str, reg: SignalRegistry, cmp_prefix: str,
 def _infer_compare_final(gate: str, reg: SignalRegistry, cmp_prefix: str,
                          out_gt: str, out_lt: str, out_ge: str, out_le: str,
                          out_eq: str, bits: int) -> List[int] | None:
-    """Inputs for the final outputs of an add_bit_cascade_compare emit:
-    out_gt/out_lt are N-input ORs; out_eq is N-input AND; ge/le are
-    NOT-then-buffer chains over lt/gt.
-    """
+    """Inputs of the final outputs of a bit-cascade comparator."""
     if gate == out_gt:
         return ([reg.register(f"{cmp_prefix}.bit0.gt")]
                 + [reg.register(f"{cmp_prefix}.cascade.gt.bit{i}") for i in range(1, bits)])
@@ -3186,12 +2719,7 @@ def _infer_compare_final(gate: str, reg: SignalRegistry, cmp_prefix: str,
 
 def infer_float_cmp_inputs(gate: str, reg: SignalRegistry, family: str,
                            exp_bits: int, frac_bits: int) -> Optional[List[int]]:
-    """Complete wiring for the self-contained float comparison network.
-
-    External inputs are the raw operand words $a[0..W-1] / $b[0..W-1],
-    MSB-first: bit 0 is the sign, bits 1..E the exponent, the rest the
-    fraction. Field extraction is input wiring, not gates.
-    """
+    """Complete wiring for the self-contained float comparison network."""
     prefix = f"{family}.cmp"
     if gate != prefix and not gate.startswith(prefix + "."):
         return None
@@ -3306,8 +2834,7 @@ def infer_float_cmp_inputs(gate: str, reg: SignalRegistry, family: str,
 
 def _fa_member_inputs(sub: str, fa_prefix: str, a_sig: int, b_sig: int,
                       cin_sig: int, reg: SignalRegistry) -> Optional[List[int]]:
-    """Wiring for one gate of an add_full_adder cell, given the cell's
-    operand/carry signal IDs. `sub` is the gate suffix inside the cell."""
+    """Wiring for one gate of an add_full_adder cell, given the cell's operand/carry signal IDs."""
     if sub == "ha1.sum.layer1.or" or sub == "ha1.sum.layer1.nand":
         return [a_sig, b_sig]
     if sub == "ha1.sum.layer2":
@@ -3330,13 +2857,7 @@ def _fa_member_inputs(sub: str, fa_prefix: str, a_sig: int, b_sig: int,
 
 def infer_float_mul_inputs(gate: str, reg: SignalRegistry, family: str,
                            exp_bits: int, frac_bits: int) -> Optional[List[int]]:
-    """Complete wiring for the self-contained float multiplication pipeline.
-
-    Operand words $a/$b are MSB-first. Internally the mantissa and exponent
-    signals are LSB-first: mantissa bit k of `a` is $a[W-1-k] for k < F with
-    the implicit leading one (index F) wired to #1; exponent bit k is
-    $a[E-k]. The accumulated product bit k is acc.s{F-1}.fa{k}'s sum.
-    """
+    """Complete wiring for the self-contained float multiplication pipeline."""
     E, F = exp_bits, frac_bits
     W = 1 + E + F
     prefix = f"{family}.mul"
@@ -3613,14 +3134,7 @@ def infer_float_mul_inputs(gate: str, reg: SignalRegistry, family: str,
 
 def infer_float_div_inputs(gate: str, reg: SignalRegistry, family: str,
                            exp_bits: int, frac_bits: int) -> Optional[List[int]]:
-    """Complete wiring for the self-contained float division pipeline.
-
-    Stage 0 compares the dividend mantissa against the divisor directly;
-    every later stage shifts the previous remainder left by one (the
-    shifted-out top bit forces the quotient bit through the stage OR) and
-    conditionally subtracts. The quotient bit of stage s is
-    mant_div.stage{s}.q; the remainder bits are the stage mux outputs.
-    """
+    """Complete wiring for the self-contained float division pipeline."""
     E, F = exp_bits, frac_bits
     W = 1 + E + F
     prefix = f"{family}.div"
@@ -5009,15 +4523,7 @@ def infer_float_add_inputs(gate: str, reg: SignalRegistry, family: str,
 
 
 def add_subleq_core(tensors: Dict[str, torch.Tensor]) -> None:
-    """Add the SUBLEQ one-instruction datapath.
-
-    The machine: M[B] -= M[A]; branch to C when the result is <= 0 (two's
-    complement). External inputs, LSB-first: $a (subtrahend M[A]), $b
-    (minuend M[B]), $pc (current PC), $c (branch target). Outputs: the new
-    M[B] on sub.fa{k} sums, and the next PC on pc_mux.bit{k}.or. The one
-    architectural decision -- branch or fall through -- is the single
-    threshold neuron subleq.leq over (sign, is-zero).
-    """
+    """Add the SUBLEQ one-instruction datapath."""
     for k in range(8):
         add_gate(tensors, f"subleq.sub.not_a.bit{k}", [-1.0], [0.0])
         add_full_adder(tensors, f"subleq.sub.fa{k}")
@@ -5085,12 +4591,7 @@ def infer_subleq_inputs(gate: str, reg: SignalRegistry) -> Optional[List[int]]:
 
 
 def infer_rv32_inputs(gate: str, reg: SignalRegistry) -> Optional[List[int]]:
-    """Complete wiring for the rv32-specific sub-circuits: the 64-bit MULH
-    accumulator (fed by the shared 32-bit partial products), the SRA select
-    muxes, the NEUR neuron datapath, and the dual-issue hazard comparators.
-    All operand-side ports are external ($rv32_...); internal chains resolve
-    to gate outputs, so each sub-circuit's netlist is recoverable in full.
-    """
+    """Wiring of the RV32 sub-circuits: MULH accumulator, SRA muxes, NEUR and hazard comparators."""
     if not gate.startswith("rv32."):
         return None
 
@@ -5244,10 +4745,7 @@ def infer_rv32_inputs(gate: str, reg: SignalRegistry) -> Optional[List[int]]:
 
 
 def _infer_threshold_computer_bit_cascade(gate: str, reg: SignalRegistry) -> List[int] | None:
-    """Match every bit-cascade location used in this codebase: integer
-    comparators, integer division stage cmps, float magnitude comparators,
-    float exp_cmp, and float division mantissa cmps.
-    """
+    """Match every bit-cascade comparator location in the codebase."""
     # Integer arithmetic.cmp{N}bit.* + the public greaterthan/lessthan/etc.
     m = re.match(r"^arithmetic\.cmp(\d+)bit\..+", gate)
     if m:
@@ -5315,16 +4813,7 @@ _ROUTING_TABLE_CACHE: Dict[str, Any] | None = None
 
 
 def _load_routing_table() -> Dict[str, Any]:
-    """Load `routing/routing.json` once; on missing file, return {}.
-
-    The JSON maps each top-level circuit name (e.g. ``arithmetic.multiplier8x8``)
-    to a dict with at least ``inputs`` (top-level external ports) and
-    ``internal`` (gate-suffix -> list-of-source-signal-name). The source
-    signal names are either external port references (``$a[3]``), constants
-    (``#0`` / ``#1``), or relative gate names within the same circuit
-    (e.g. ``pp.r0.c3``). Anchored cross-circuit references are not
-    expressed here; circuits in the table are assumed self-contained.
-    """
+    """Load `routing/routing.json` once; on missing file, return {}."""
     global _ROUTING_TABLE_CACHE
     if _ROUTING_TABLE_CACHE is not None:
         return _ROUTING_TABLE_CACHE
@@ -5342,16 +4831,7 @@ def _infer_from_routing_table(
     gate: str, reg: SignalRegistry,
     known_gate_suffixes: Optional[Set[str]] = None,
 ) -> Optional[List[int]]:
-    """Resolve a gate's inputs by consulting routing.json.
-
-    ``known_gate_suffixes`` is the set of gate-name suffixes that actually
-    exist in the loaded safetensors (within the same circuit prefix).
-    When the routing JSON names a producer like ``stage0.bit0.ha2.sum``
-    but that suffix isn't a real gate (only ``stage0.bit0.ha2.sum.layer2``
-    is), this set is consulted to redirect the reference to the canonical
-    final-layer signal. Returns None when the gate's circuit isn't
-    covered or its suffix isn't in the routing's ``internal`` map.
-    """
+    """Resolve a gate's inputs by consulting routing.json."""
     table = _load_routing_table()
     if not table:
         return None
@@ -5451,7 +4931,7 @@ def infer_inputs_for_gate(gate: str, reg: SignalRegistry, tensors: Dict[str, tor
             return fc
     # Bit-cascade comparators (integer + float + div) and ternary modular detectors.
     # These are the gates emitted by add_bit_cascade_compare and the ternary
-    # modular rebuild in quantize.py; cover them up front so they don't fall
+    # modular rebuild in the quantize command; cover them up front so they don't fall
     # through to the generic per-family handlers below.
     bc = _infer_threshold_computer_bit_cascade(gate, reg)
     if bc is not None:
@@ -6121,8 +5601,7 @@ def cmd_alu(args) -> None:
 
 
 def cmd_subleq(args) -> None:
-    """Build the standalone SUBLEQ-8 machine file from scratch: 256 B of
-    packed memory circuits plus the one-instruction datapath, fully wired."""
+    """Build the standalone SUBLEQ-8 machine file: 256 bytes of packed memory and the datapath."""
     out = args.model if args.model else MODEL_DIR / "variants" / "neural_subleq8.safetensors"
     print("=" * 60)
     print(" BUILD SUBLEQ-8 (one-instruction threshold machine)")
@@ -6153,10 +5632,7 @@ def cmd_subleq(args) -> None:
 
 
 def add_rv32_extras(tensors: Dict[str, torch.Tensor]) -> None:
-    """RV32-specific circuits beyond the shared families: the full 64-bit
-    product accumulator for MULH*, arithmetic-right-shift select muxes,
-    the NEUR neuron-evaluation datapath, and dual-issue hazard comparators.
-    """
+    """RV32 circuits beyond the shared families: MULH accumulator, SRA muxes, NEUR, hazard comparators."""
     # 64-bit shift-add accumulator over the 32x32 partial products.
     for stage in range(31):
         for bit in range(64):
@@ -6195,9 +5671,11 @@ def add_rv32_extras(tensors: Dict[str, torch.Tensor]) -> None:
 RV32_OPCLASS = {0x33: "op", 0x13: "op_imm", 0x03: "load", 0x23: "store",
                 0x63: "branch", 0x37: "lui", 0x17: "auipc", 0x6F: "jal",
                 0x67: "jalr", 0x73: "system", 0x53: "fp", 0x07: "flw", 0x27: "fsw"}
+
 # Which opcode classes select each immediate format.
 RV32_USE = {"I": ["op_imm", "load", "jalr", "flw"], "S": ["store", "fsw"],
             "B": ["branch"], "U": ["lui", "auipc"], "J": ["jal"]}
+
 RV32_IMM_FMTS = ("I", "S", "B", "U", "J")
 
 
@@ -6235,10 +5713,7 @@ def _rv32_imm_src(fmt: str, k: int):
 
 
 def add_rv32_decode(tensors: Dict[str, torch.Tensor]) -> None:
-    """Instruction decode as threshold gates: opcode-class one-hots (an exact
-    7-bit match on the instruction's opcode field) and the sign-extended
-    immediate for the active format, muxed from the raw instruction word. The
-    runtime reads these gate outputs instead of slicing the word in Python."""
+    """RV32 instruction decode: opcode-class one-hots and the sign-extended immediate."""
     for opc, name in RV32_OPCLASS.items():
         w = [1.0 if (opc >> j) & 1 else -1.0 for j in range(7)]
         add_gate(tensors, f"rv32.decode.is_{name}", w, [-float(bin(opc).count("1"))])
@@ -6254,10 +5729,7 @@ def add_rv32_decode(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def add_rv32_pcnext(tensors: Dict[str, torch.Tensor]) -> None:
-    """PC sequencing as threshold gates: a two-level mux selecting the next PC
-    among PC+4, PC+imm (branch/jal), and (rs1+imm)&~1 (jalr). The three
-    candidates are the gate adder's outputs; this network chooses between them
-    from the decode's control signals rather than a Python if/elif."""
+    """RV32 next-PC selection among PC+4, PC+imm and (rs1+imm)&~1."""
     for k in range(32):
         # m1 = sel_target ? pcimm : pc4
         add_gate(tensors, f"rv32.pcnext.m1.bit{k}.not_sel", [-1.0], [0.0])
@@ -6272,9 +5744,7 @@ def add_rv32_pcnext(tensors: Dict[str, torch.Tensor]) -> None:
 
 
 def cmd_rv32(args) -> None:
-    """Build the standalone RV32 threshold processor file from scratch:
-    64 KB packed memory, the shared 32-bit circuit families, the composed
-    float32 pipelines as the FPU, and the rv32-specific extras."""
+    """Build the standalone RV32 processor file: 64 KB of memory, the shared families and the FPU."""
     out = args.model if args.model else MODEL_DIR / "variants" / "neural_rv32.safetensors"
     print("=" * 60)
     print(" BUILD NEURAL_RV32 (RV32IM + F-subset threshold processor)")
@@ -6458,6 +5928,528 @@ Usage (note: options must come BEFORE subcommand):
     else:
         parser.print_help()
 
+DTYPES = [
+    (torch.int8, -(1 << 7), (1 << 7) - 1),
+    (torch.int16, -(1 << 15), (1 << 15) - 1),
+    (torch.int32, -(1 << 31), (1 << 31) - 1),
+    (torch.int64, None, None),  # always fits
+]
+
+
+def _normalize_to_int(tensor: torch.Tensor) -> torch.Tensor:
+    """Return a tensor with strictly integer values, floored from any half-integer values."""
+    if not tensor.dtype.is_floating_point:
+        return tensor.to(torch.float64)  # promote for range checks
+    tf = tensor.to(torch.float64)
+    rounded = tf.round()
+    if torch.equal(rounded, tf):
+        return tf
+    doubled = tf * 2.0
+    if torch.equal(doubled.round(), doubled):
+        return torch.floor(tf)
+    raise ValueError(
+        f"tensor has non-half-integer values; range "
+        f"[{tf.min().item()}, {tf.max().item()}]"
+    )
+
+
+def _min_signed_int_dtype(tensor: torch.Tensor) -> torch.dtype:
+    if tensor.numel() == 0:
+        return torch.int8
+    lo = int(tensor.min().item())
+    hi = int(tensor.max().item())
+    for dtype, lo_lim, hi_lim in DTYPES:
+        if lo_lim is None or (lo_lim <= lo and hi <= hi_lim):
+            return dtype
+    return torch.int64
+
+
+def _ternarize_modular_and_patterns(
+    tensors: Dict[str, torch.Tensor],
+) -> Tuple[Dict[str, torch.Tensor], Dict]:
+    """Replace the seed file's modular detectors with bit-cascade equivalents."""
+    new_tensors = dict(tensors)
+
+    # --- pattern_recognition: drop leadingones/trailingones ---
+    pr_dropped = 0
+    for k in list(new_tensors.keys()):
+        if (k.startswith("pattern_recognition.leadingones")
+                or k.startswith("pattern_recognition.trailingones")):
+            del new_tensors[k]
+            pr_dropped += 1
+
+    # --- modular: rebuild as ternary bit-cascade equality per multiple ---
+    moduli = [3, 5, 6, 7, 9, 10, 11, 12]
+    mod_gates_added = 0
+    for mod in moduli:
+        prefix = f"modular.mod{mod}"
+        if f"{prefix}.eq.k0.all.weight" in new_tensors:
+            continue  # already bit-cascade; rebuilding would only shed metadata
+        # Drop old structure
+        for k in list(new_tensors.keys()):
+            if k.startswith(prefix + "."):
+                del new_tensors[k]
+
+        multiples = list(range(0, 256, mod))
+        # Per-bit match gates + per-multiple AND
+        for k in multiples:
+            for i in range(8):  # i=0 is MSB (matches inputs MSB-first ordering)
+                k_bit = (k >> (7 - i)) & 1
+                if k_bit == 1:
+                    # bit_match = x[i]: H(x - 0.5) ~~ identity for binary;
+                    # use weight=1, bias=-1 -> H(x-1): x=0 -> 0, x=1 -> 1.
+                    new_tensors[f"{prefix}.eq.k{k}.bit{i}.match.weight"] = torch.tensor([1.0], dtype=torch.float64)
+                    new_tensors[f"{prefix}.eq.k{k}.bit{i}.match.bias"] = torch.tensor([-1.0], dtype=torch.float64)
+                else:
+                    # bit_match = NOT x[i]: weight=-1, bias=0 -> H(-x): x=0 -> 1, x=1 -> 0.
+                    new_tensors[f"{prefix}.eq.k{k}.bit{i}.match.weight"] = torch.tensor([-1.0], dtype=torch.float64)
+                    new_tensors[f"{prefix}.eq.k{k}.bit{i}.match.bias"] = torch.tensor([0.0], dtype=torch.float64)
+                mod_gates_added += 1
+            # AND of all 8 bit-matches: weights [1]*8, bias -8
+            new_tensors[f"{prefix}.eq.k{k}.all.weight"] = torch.tensor([1.0] * 8, dtype=torch.float64)
+            new_tensors[f"{prefix}.eq.k{k}.all.bias"] = torch.tensor([-8.0], dtype=torch.float64)
+            mod_gates_added += 1
+
+        # Final OR over all per-multiple match outputs
+        m = len(multiples)
+        new_tensors[f"{prefix}.weight"] = torch.tensor([1.0] * m, dtype=torch.float64)
+        new_tensors[f"{prefix}.bias"] = torch.tensor([-1.0], dtype=torch.float64)
+        mod_gates_added += 1
+
+    return new_tensors, {
+        "pattern_recognition_dropped": pr_dropped,
+        "modular_gates_added": mod_gates_added,
+        "modular_moduli": len(moduli),
+    }
+
+
+def _ternarize_buffers(
+    tensors: Dict[str, torch.Tensor],
+) -> Tuple[Dict[str, torch.Tensor], Dict]:
+    """Rewrite weight +-2 identity buffers as weight +-1 with the bias adjusted."""
+    new_tensors = dict(tensors)
+    fixed = 0
+    failed_names = []
+
+    weight_keys = [k for k in tensors if k.endswith(".weight")]
+    for wkey in weight_keys:
+        w = tensors[wkey]
+        wf = w.float() if w.dtype.is_floating_point else w.to(torch.float64).float()
+        if (wf.abs() <= 1.0).all():
+            continue  # already ternary
+
+        gate = wkey[: -len(".weight")]
+        bkey = gate + ".bias"
+
+        # Single-input weight=+-2 buffer with single bias
+        if (
+            wf.numel() == 1
+            and abs(wf.item()) == 2.0
+            and bkey in tensors
+            and tensors[bkey].numel() == 1
+        ):
+            w_val = wf.item()
+            b_val = float(tensors[bkey].float().item())
+            sgn = 1.0 if w_val > 0 else -1.0
+            x0_target = 1 if b_val >= 0 else 0
+            x1_target = 1 if (w_val + b_val) >= 0 else 0
+            chosen = None
+            # Prefer keeping the bias unchanged when possible
+            for b_new in [int(b_val), int(b_val) - 1, -1, 0, -2, 1, -3, 2]:
+                x0 = 1 if b_new >= 0 else 0
+                x1 = 1 if (sgn + b_new) >= 0 else 0
+                if x0 == x0_target and x1 == x1_target:
+                    chosen = b_new
+                    break
+            if chosen is not None:
+                new_tensors[wkey] = torch.tensor([sgn], dtype=torch.float64)
+                new_tensors[bkey] = torch.tensor([float(chosen)], dtype=torch.float64)
+                fixed += 1
+                continue
+
+        failed_names.append(wkey)
+
+    return new_tensors, {"fixed": fixed, "failed_names": failed_names}
+
+
+def quantize_tensors(
+    tensors: Dict[str, torch.Tensor],
+    ternary: bool = False,
+) -> Tuple[Dict[str, torch.Tensor], Dict[str, int], Tuple[int, int], Dict]:
+    """Quantize a dict of tensors."""
+    ternary_stats: Dict = {"applied": False, "fixed": 0, "failed_names": []}
+    if ternary:
+        tensors, ternary_stats = _ternarize_buffers(tensors)
+        ternary_stats["applied"] = True
+        # Also rebuild modular detectors and drop pattern_recognition stragglers.
+        tensors, mod_stats = _ternarize_modular_and_patterns(tensors)
+        ternary_stats["modular_gates_added"] = mod_stats["modular_gates_added"]
+        ternary_stats["pattern_recognition_dropped"] = mod_stats["pattern_recognition_dropped"]
+
+    new_tensors: Dict[str, torch.Tensor] = {}
+    counts: Dict[str, int] = {"int8": 0, "int16": 0, "int32": 0, "int64": 0,
+                              "manifest_kept": 0, "skipped": 0}
+    bytes_before = 0
+    bytes_after = 0
+
+    for name, t in tensors.items():
+        bytes_before += t.numel() * t.element_size()
+
+        if name.startswith("manifest."):
+            new_tensors[name] = t
+            counts["manifest_kept"] += 1
+            bytes_after += t.numel() * t.element_size()
+            continue
+
+        try:
+            normalized = _normalize_to_int(t)
+        except ValueError:
+            new_tensors[name] = t
+            counts["skipped"] += 1
+            bytes_after += t.numel() * t.element_size()
+            continue
+
+        target = _min_signed_int_dtype(normalized)
+        cast = normalized.to(target)
+        new_tensors[name] = cast
+        bytes_after += cast.numel() * cast.element_size()
+        counts[str(target).replace("torch.", "")] += 1
+
+    return new_tensors, counts, (bytes_before, bytes_after), ternary_stats
+
+
+def quantize_file(in_path: Path, out_path: Path, verbose: bool = False,
+                  ternary: bool = False, strict_ternary: bool = False) -> Dict:
+    file_before = in_path.stat().st_size
+    tensors: Dict[str, torch.Tensor] = {}
+    metadata: Dict[str, str] = {}
+    with safe_open(str(in_path), framework="pt") as f:
+        meta = f.metadata()
+        if meta:
+            metadata = dict(meta)
+        for name in f.keys():
+            # clone so the source mmap can be released before we write
+            tensors[name] = f.get_tensor(name).clone()
+
+    new_tensors, counts, (before, after), tstats = quantize_tensors(tensors, ternary=ternary)
+
+    # Audit final ternary status (count of weight tensors with |w| > 1)
+    final_nonternary = []
+    for k, v in new_tensors.items():
+        if not k.endswith(".weight"):
+            continue
+        if k.startswith("manifest."):
+            continue
+        vf = v.float() if v.dtype.is_floating_point else v.to(torch.float64).float()
+        if (vf.abs() > 1.0).any():
+            final_nonternary.append(k)
+
+    if ternary and strict_ternary and final_nonternary:
+        raise ValueError(
+            f"--strict failed: {len(final_nonternary)} weight tensors are not "
+            f"ternary after transformation; first: {final_nonternary[:5]}"
+        )
+
+    # Drop the original mmap-backed tensors before writing in-place.
+    del tensors
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    if ternary:
+        # Note ternary mode in metadata so downstream tools can see it
+        if metadata is None:
+            metadata = {}
+        metadata = dict(metadata)
+        metadata["weight_quantization"] = (
+            "ternary_partial" if final_nonternary else "ternary"
+        )
+    save_file(new_tensors, str(out_path), metadata=metadata or None)
+
+    file_after = out_path.stat().st_size
+    return {
+        "in_path": str(in_path),
+        "out_path": str(out_path),
+        "tensor_counts": counts,
+        "tensor_bytes_before": before,
+        "tensor_bytes_after": after,
+        "file_size_before": file_before,
+        "file_size_after": file_after,
+        "ternary": tstats,
+        "final_nonternary": final_nonternary,
+    }
+
+
+def _print_summary(label: str, info: Dict) -> None:
+    cb = info["tensor_bytes_before"]
+    ca = info["tensor_bytes_after"]
+    fb = info["file_size_before"]
+    fa = info["file_size_after"]
+    counts = info["tensor_counts"]
+    bucket_str = "  ".join(f"{k}={v}" for k, v in counts.items() if v)
+    ratio_t = cb / ca if ca else 1.0
+    ratio_f = fb / fa if fa else 1.0
+    print(
+        f"  {label}: file {fb / 1e6:6.1f} MB -> {fa / 1e6:6.1f} MB "
+        f"({ratio_f:.2f}x);  tensor data {cb / 1e6:6.1f} MB -> {ca / 1e6:6.1f} MB "
+        f"({ratio_t:.2f}x)"
+    )
+    print(f"      {bucket_str}")
+    if info.get("ternary", {}).get("applied"):
+        ts = info["ternary"]
+        nt = info["final_nonternary"]
+        print(f"      ternary: {ts['fixed']} buffer gates rewritten; "
+              f"{len(nt)} weight tensors remain non-ternary")
+
+
+def main_quantize() -> int:
+    parser = argparse.ArgumentParser(description="Quantize safetensors to min signed int dtype")
+    parser.add_argument("input", type=Path, help=".safetensors file or directory of files")
+    parser.add_argument("-o", "--output", type=Path, default=None,
+                        help="output file or directory (default: in-place)")
+    parser.add_argument("-v", "--verbose", action="store_true")
+    parser.add_argument("--ternary", action="store_true",
+                        help="Rewrite single-input weight=+/-2 buffers as +/-1 to push toward "
+                             "ternary {-1, 0, 1} weights and report remaining violations")
+    parser.add_argument("--strict", action="store_true",
+                        help="With --ternary, fail if any weight tensor is still non-ternary")
+    parser.add_argument("--report-violations", type=int, default=0, metavar="N",
+                        help="Print first N non-ternary weight tensor names per file")
+    args = parser.parse_args()
+
+    inputs = []
+    if args.input.is_dir():
+        inputs = sorted(p for p in args.input.glob("*.safetensors"))
+    elif args.input.is_file():
+        inputs = [args.input]
+    else:
+        print(f"not found: {args.input}", file=sys.stderr)
+        return 2
+
+    if not inputs:
+        print(f"no .safetensors files under {args.input}", file=sys.stderr)
+        return 2
+
+    if args.output is None:
+        outputs = inputs  # in-place
+    elif args.output.suffix == ".safetensors":
+        if len(inputs) != 1:
+            print("output is a single file but input is a directory; pass a directory output", file=sys.stderr)
+            return 2
+        outputs = [args.output]
+    else:
+        args.output.mkdir(parents=True, exist_ok=True)
+        outputs = [args.output / p.name for p in inputs]
+
+    total_before = 0
+    total_after = 0
+    print(f"Quantizing {len(inputs)} file(s)" + (" (ternary mode)" if args.ternary else "") + "\n")
+    for src, dst in zip(inputs, outputs):
+        info = quantize_file(src, dst, verbose=args.verbose,
+                             ternary=args.ternary, strict_ternary=args.strict)
+        _print_summary(src.name, info)
+        if args.report_violations and info.get("final_nonternary"):
+            for name in info["final_nonternary"][: args.report_violations]:
+                print(f"        non-ternary: {name}")
+            if len(info["final_nonternary"]) > args.report_violations:
+                print(f"        ... and {len(info['final_nonternary']) - args.report_violations} more")
+        total_before += info["file_size_before"]
+        total_after += info["file_size_after"]
+
+    print()
+    print("=" * 76)
+    print(
+        f"Total: {total_before / 1e6:.1f} MB -> {total_after / 1e6:.1f} MB "
+        f"({total_before / max(total_after, 1):.2f}x reduction)"
+    )
+    return 0
+
+ROOT = Path(__file__).resolve().parent.parent
+
+SEED = ROOT / "neural_computer.safetensors"
+
+OUT_DIR = ROOT / "variants"
+
+PROFILES = ["none", "registers", "scratchpad", "small", "reduced", "full"]
+
+BITS = [8, 16, 32]
+
+
+def variant_filename(bits: int, profile: str) -> str:
+    if profile == "none":
+        return f"neural_alu{bits}.safetensors"
+    if profile == "full":
+        return f"neural_computer{bits}.safetensors"
+    return f"neural_computer{bits}_{profile}.safetensors"
+
+
+def run(cmd: list[str], timeout: int = 600) -> tuple[int, str]:
+    p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    return p.returncode, (p.stdout or "") + (p.stderr or "")
+
+
+def build_variant(bits: int, profile: str) -> Path:
+    out = OUT_DIR / variant_filename(bits, profile)
+    shutil.copy2(SEED, out)
+    cmd = [
+        sys.executable, str(ROOT / "src" / "build.py"),
+        "--bits", str(bits),
+        "-m", profile,
+        "--apply",
+        "--model", str(out),
+        "all",
+    ]
+    rc, log = run(cmd, timeout=2400)
+    if rc != 0:
+        raise RuntimeError(f"build failed for bits={bits} profile={profile}:\n{log[-1500:]}")
+    return out
+
+
+def quantize_variant(path: Path) -> tuple[int, int]:
+    """Run the quantize command with --ternary --strict on a built variant."""
+    rc, log = run([sys.executable, str(ROOT / "src" / "build.py"), "quantize", str(path),
+                   "--ternary", "--strict"], timeout=300)
+    if rc != 0:
+        raise RuntimeError(f"quantize failed for {path.name}:\n{log[-800:]}")
+    # parse the "file X.X MB -> Y.Y MB" line
+    for line in log.splitlines():
+        if "file" in line and "->" in line and path.name in line:
+            try:
+                parts = line.split("file")[1].split("->")
+                before = float(parts[0].strip().split()[0]) * 1e6
+                after = float(parts[1].strip().split()[0]) * 1e6
+                return int(before), int(after)
+            except Exception:
+                pass
+    return 0, 0
+
+
+def measure_variant(path: Path) -> dict:
+    """Read tensor count, params, manifest values from the variant."""
+    with safe_open(str(path), framework="pt") as f:
+        keys = list(f.keys())
+        params = sum(f.get_tensor(k).numel() for k in keys)
+        manifest = {
+            k.split(".", 1)[1]: f.get_tensor(k).item()
+            for k in keys if k.startswith("manifest.") and f.get_tensor(k).numel() == 1
+        }
+    return {
+        "tensors": len(keys),
+        "params": params,
+        "size_mb": path.stat().st_size / (1024 * 1024),
+        "manifest": manifest,
+    }
+
+
+def eval_variant(path: Path, device: str = "cpu", timeout: int = 600) -> dict:
+    """Run eval.py against a variant and parse fitness."""
+    cmd = [
+        sys.executable, str(ROOT / "src" / "eval.py"),
+        "--model", str(path),
+        "--device", device,
+        "--quiet",
+    ]
+    t0 = time.time()
+    rc, log = run(cmd, timeout=timeout)
+    dt = time.time() - t0
+
+    fitness = None
+    total_tests = None
+    status = "ERROR"
+    for line in log.splitlines():
+        line = line.strip()
+        if line.startswith("Fitness:"):
+            try:
+                fitness = float(line.split()[1])
+            except Exception:
+                pass
+        elif line.startswith("Total tests:"):
+            try:
+                total_tests = int(line.split()[2])
+            except Exception:
+                pass
+        elif line.startswith("STATUS:"):
+            status = line.split()[1]
+    return {
+        "rc": rc,
+        "fitness": fitness,
+        "total_tests": total_tests,
+        "status": status,
+        "elapsed_s": dt,
+        "log_tail": "\n".join(log.splitlines()[-15:]),
+    }
+
+
+def main_all() -> None:
+    OUT_DIR.mkdir(exist_ok=True)
+    rows = []
+    print(f"Building 18 variants into {OUT_DIR}\n")
+    for bits in BITS:
+        for profile in PROFILES:
+            label = f"bits={bits} profile={profile}"
+            print(f"=== {label} ===", flush=True)
+            t0 = time.time()
+            try:
+                path = build_variant(bits, profile)
+                bt = time.time() - t0
+                pre_q_meta = measure_variant(path)
+                # Quantize in-place as the final step; weights are
+                # integer-valued so this is exact, --strict fails the build
+                # if any weight is non-ternary, and header metadata
+                # (signal_registry) is carried through.
+                qb, qa = quantize_variant(path)
+                meta = measure_variant(path)
+                ev = eval_variant(path, device="cpu", timeout=900)
+                rows.append({
+                    "bits": bits, "profile": profile,
+                    "filename": path.name,
+                    "build_s": bt,
+                    **meta,
+                    **{k: ev[k] for k in ("fitness", "total_tests", "status", "elapsed_s")},
+                    "log_tail": ev["log_tail"] if ev["status"] != "PASS" else "",
+                })
+                q_ratio = qb / qa if qa else 1.0
+                print(f"  built in {bt:.1f}s  size={pre_q_meta['size_mb']:.1f}MB -> "
+                      f"{meta['size_mb']:.1f}MB after quant ({q_ratio:.2f}x)"
+                      f"  params={meta['params']:,}  tensors={meta['tensors']:,}")
+                print(f"  eval: fitness={ev['fitness']}  tests={ev['total_tests']}"
+                      f"  status={ev['status']}  ({ev['elapsed_s']:.1f}s)")
+                if ev["status"] != "PASS":
+                    print("  --- failure tail ---")
+                    print("  " + "\n  ".join(ev["log_tail"].splitlines()))
+                    print("  --------------------")
+            except Exception as e:
+                print(f"  EXCEPTION: {e}")
+                rows.append({"bits": bits, "profile": profile, "error": str(e)})
+            print()
+
+    print("=" * 88)
+    print(" SUMMARY")
+    print("=" * 88)
+    header = f"{'bits':>4} {'profile':<11} {'size_MB':>8} {'tensors':>8} {'params':>11} {'fitness':>9} {'tests':>6} {'status':>7}"
+    print(header)
+    print("-" * len(header))
+    for r in rows:
+        if "error" in r:
+            print(f"{r['bits']:>4} {r['profile']:<11} ERROR: {r['error'][:60]}")
+            continue
+        fit = f"{r['fitness']:.4f}" if r['fitness'] is not None else "n/a"
+        tests = r['total_tests'] if r['total_tests'] is not None else "?"
+        print(f"{r['bits']:>4} {r['profile']:<11} {r['size_mb']:>8.1f} "
+              f"{r['tensors']:>8,} {r['params']:>11,} "
+              f"{fit:>9} {tests:>6} {r['status']:>7}")
+
+    fail = [r for r in rows if r.get("status") != "PASS" or "error" in r]
+    print()
+    if fail:
+        print(f"FAILURES: {len(fail)}/{len(rows)}")
+    else:
+        print(f"ALL {len(rows)} VARIANTS PASS")
+
+
+COMMANDS = {'build': main, 'quantize': main_quantize, 'variants': main_all}
+
 
 if __name__ == "__main__":
-    main()
+    if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:
+        sys.exit(COMMANDS['build']())
+    cmd = sys.argv.pop(1)
+    sys.argv[0] += ' ' + cmd
+    sys.exit(COMMANDS[cmd]())

src/ca.py

@@ -1,261 +0,0 @@
-"""Reversible Margolus (partitioned) cellular automaton.
-
-One fixed rule is applied to every 2x2 block, alternating the block partition
-between even and odd alignment each step (the Margolus neighborhood). The state
-is the lattice; there is no program counter, register file, or control circuit.
-
-Rule (cells ordered TL,TR,BL,BR): rotate the block 180 degrees, except a pair of
-particles on a diagonal (1001, 0110) swaps to the other diagonal. Both cases are
-involutions and neither maps a state across the diagonal-pair boundary, so the
-rule is a self-inverse permutation of the sixteen block states; the lattice
-update is therefore a bijection and replaying the partition sequence in reverse
-inverts the evolution.
-
-Dynamics are the billiard-ball model's: isolated particles move ballistically on
-diagonals and collisions deflect them reversibly. and_gate() computes AND from a
-collision; ballistic transport plus this collision are the primitives of the
-Fredkin-Toffoli universality construction (Margolus 1984).
-"""
-from __future__ import annotations
-from typing import List, Tuple
-
-Block = Tuple[int, int, int, int]
-
-
-def rule(b: Block) -> Block:
-    tl, tr, bl, br = b
-    if b == (1, 0, 0, 1):
-        return (0, 1, 1, 0)          # diagonal pair -> other diagonal (deflect)
-    if b == (0, 1, 1, 0):
-        return (1, 0, 0, 1)
-    return (br, bl, tr, tl)          # otherwise rotate 180 degrees
-
-
-def is_bijection() -> bool:
-    outs = {rule(tuple((s >> k) & 1 for k in (3, 2, 1, 0))) for s in range(16)}
-    return len(outs) == 16
-
-
-def self_inverse() -> bool:
-    return all(rule(rule(tuple((s >> k) & 1 for k in (3, 2, 1, 0))))
-               == tuple((s >> k) & 1 for k in (3, 2, 1, 0)) for s in range(16))
-
-
-def step(grid: List[List[int]], phase: int) -> List[List[int]]:
-    """One Margolus update. phase 0 aligns blocks at even coordinates; phase 1
-    offsets the partition by (1,1). Toroidal, so H and W must be even."""
-    H, W = len(grid), len(grid[0])
-    out = [row[:] for row in grid]
-    o = phase
-    for r0 in range(o, o + H, 2):
-        for c0 in range(o, o + W, 2):
-            r, r1 = r0 % H, (r0 + 1) % H
-            c, c1 = c0 % W, (c0 + 1) % W
-            nb = rule((grid[r][c], grid[r][c1], grid[r1][c], grid[r1][c1]))
-            out[r][c], out[r][c1], out[r1][c], out[r1][c1] = nb
-    return out
-
-
-def run(grid: List[List[int]], nsteps: int, start_phase: int = 0) -> List[List[int]]:
-    g = grid
-    for n in range(nsteps):
-        g = step(g, (start_phase + n) & 1)
-    return g
-
-
-def run_back(grid: List[List[int]], nsteps: int, start_phase: int = 0) -> List[List[int]]:
-    """Undo `run`: replay the phase sequence in reverse; the rule is self-inverse."""
-    phases = [(start_phase + n) & 1 for n in range(nsteps)]
-    g = grid
-    for p in reversed(phases):
-        g = step(g, p)
-    return g
-
-
-# --- the block rule as Heaviside threshold gates ---
-# rule(s) = rotate180(s) XOR is_diag(s) on every cell: rotation fixes diagonal
-# pairs, and flipping all four cells of a rotated diagonal pair sends it to the
-# other diagonal. is_diag detects the two diagonal-pair states.
-def _H(x):
-    return 1 if x >= 0 else 0
-
-
-def _and(*xs):
-    return _H(sum(xs) - len(xs))
-
-
-def _or(*xs):
-    return _H(sum(xs) - 1)
-
-
-def _xor(a, b):
-    return _and(_or(a, b), _H(1 - a - b))       # OR AND NAND, the family's XOR
-
-
-def gate_rule(b: Block) -> Block:
-    tl, tr, bl, br = b
-    d = _or(_and(tl, 1 - tr, 1 - bl, br), _and(1 - tl, tr, bl, 1 - br))   # is_diag
-    return (_xor(br, d), _xor(bl, d), _xor(tr, d), _xor(tl, d))
-
-
-def _test_gates():
-    ok = all(gate_rule(tuple((s >> k) & 1 for k in (3, 2, 1, 0)))
-             == rule(tuple((s >> k) & 1 for k in (3, 2, 1, 0))) for s in range(16))
-    print(f"  block rule as Heaviside threshold gates matches over 16 states: "
-          f"{'OK' if ok else 'FAIL'}")
-    return ok
-
-
-# --- tests ---
-def _rand_grid(H, W, seed):
-    import random
-    rng = random.Random(seed)
-    return [[rng.randint(0, 1) for _ in range(W)] for _ in range(H)]
-
-
-def _ball_positions(g):
-    return {(r, c) for r, row in enumerate(g) for c, v in enumerate(row) if v}
-
-
-def _test_rule():
-    print(f"  block rule is a bijection of 16 states: {'OK' if is_bijection() else 'FAIL'}")
-    print(f"  block rule is self-inverse: {'OK' if self_inverse() else 'FAIL'}")
-    return is_bijection() and self_inverse()
-
-
-def _test_reversibility():
-    bad = 0
-    for seed in range(20):
-        g = _rand_grid(8, 8, seed)
-        fwd = run(g, 25, start_phase=0)
-        back = run_back(fwd, 25, start_phase=0)
-        if back != g:
-            bad += 1
-    # particle count is conserved (the rule permutes cells within each block)
-    g = _rand_grid(8, 8, 99)
-    conserved = sum(sum(r) for r in g) == sum(sum(r) for r in run(g, 40))
-    print(f"  lattice reversible (run then reverse recovers grid, 20 grids): "
-          f"{'OK' if bad == 0 else f'FAIL({bad})'}")
-    print(f"  particle number conserved: {'OK' if conserved else 'FAIL'}")
-    return bad == 0 and conserved
-
-
-def _test_ballistic():
-    # a single particle travels in a straight diagonal line
-    H = W = 16
-    g = [[0] * W for _ in range(H)]
-    g[2][2] = 1
-    positions = [next(iter(_ball_positions(g)))]
-    gg = g
-    for n in range(8):
-        gg = step(gg, n & 1)
-        p = _ball_positions(gg)
-        positions.append(next(iter(p)) if len(p) == 1 else None)
-    ok = all(p is not None for p in positions)
-    steady = ok and all(positions[i + 1] == (positions[i][0] + 1, positions[i][1] + 1)
-                        for i in range(len(positions) - 1))
-    print(f"  single particle stays a single particle: {'OK' if ok else 'FAIL'}")
-    print(f"  and moves ballistically on the diagonal, +(1,1) per step: "
-          f"{'OK' if steady else 'FAIL'}  trace={positions[:5]}")
-    return ok and steady
-
-
-def interaction_gate(a: int, b: int) -> dict:
-    """One billiard-ball collision as a reversible interaction gate. Input
-    particle A enters at (2,2) moving SE and B at (7,7) moving NW; at step 4
-    three output cells carry A&B (the deflected paths), A&~B and ~A&B (the
-    straight-through paths). AND plus routing by mirrors is functionally
-    complete for the billiard-ball construction (Margolus 1984)."""
-    H = W = 12
-    g = [[0] * W for _ in range(H)]
-    if a:
-        g[2][2] = 1
-    if b:
-        g[7][7] = 1
-    g = run(g, 4)
-    return {"A_and_B": g[3][6], "A_and_notB": g[6][6], "notA_and_B": g[3][3]}
-
-
-def and_gate(a: int, b: int) -> int:
-    return interaction_gate(a, b)["A_and_B"]
-
-
-def _test_gate():
-    ok = True
-    for a in (0, 1):
-        for b in (0, 1):
-            o = interaction_gate(a, b)
-            ok &= (o["A_and_B"] == (a & b) and o["A_and_notB"] == (a & (1 - b))
-                   and o["notA_and_B"] == ((1 - a) & b))
-    print(f"  billiard-ball interaction gate (A&B, A&~B, ~A&B) over all 4 inputs: "
-          f"{'OK' if ok else 'FAIL'}")
-    return ok
-
-
-def and3(a: int, b: int, c: int) -> int:
-    """Two composed collisions. A at (2,2) and B at (7,7) collide into an A&B
-    particle, which then collides with C launched at (0,9); the output cell
-    (3,5) at step 4 is occupied iff a, b and c. Composing gates this way builds
-    arbitrary circuits from the interaction gate."""
-    H = W = 16
-    g = [[0] * W for _ in range(H)]
-    if a:
-        g[2][2] = 1
-    if b:
-        g[7][7] = 1
-    if c:
-        g[0][9] = 1
-    return run(g, 4)[3][5]
-
-
-def _test_compose():
-    ok = all(and3(a, b, c) == (a & b & c)
-             for a in (0, 1) for b in (0, 1) for c in (0, 1))
-    print(f"  composed 3-input AND (two chained collisions) over all 8 inputs: "
-          f"{'OK' if ok else 'FAIL'}")
-    return ok
-
-
-def _test_collision():
-    # Two particles interact (the joint evolution differs from independent
-    # motion) and the collision stays reversible: the physics that logic needs.
-    H = W = 12
-    interacted = False
-    revok = True
-    # converging pairs: an SE-mover (even,even) meets an NW-mover (odd,odd) on a
-    # shared diagonal, forming the 1001/0110 diagonal pair the rule deflects.
-    for a, b in [((2, 2), (7, 7)), ((3, 3), (8, 8)), ((2, 8), (7, 3)),
-                 ((4, 4), (9, 9)), ((2, 2), (9, 9))]:
-        g = [[0] * W for _ in range(H)]
-        g[a[0]][a[1]] = 1
-        g[b[0]][b[1]] = 1
-        ga = [[0] * W for _ in range(H)]
-        ga[a[0]][a[1]] = 1
-        gb = [[0] * W for _ in range(H)]
-        gb[b[0]][b[1]] = 1
-        joint = g
-        for n in range(12):
-            joint = step(joint, n & 1)
-            ga = step(ga, n & 1)
-            gb = step(gb, n & 1)
-            free = _ball_positions(ga) | _ball_positions(gb)
-            if _ball_positions(joint) != free:
-                interacted = True
-        if run_back(run(g, 12), 12) != g:
-            revok = False
-    print(f"  two-particle collisions interact (joint != independent motion): "
-          f"{'OK' if interacted else 'FAIL'}")
-    print(f"  collisions remain reversible: {'OK' if revok else 'FAIL'}")
-    return interacted and revok
-
-
-if __name__ == "__main__":
-    print("Reversible Margolus cellular automaton")
-    a = _test_rule()
-    g = _test_gates()
-    b = _test_reversibility()
-    c = _test_ballistic()
-    d = _test_collision()
-    e = _test_gate()
-    f = _test_compose()
-    print("PASS" if (a and g and b and c and d and e and f) else "FAIL")

src/canonical.py

@@ -1,25 +0,0 @@
-"""Deterministic safetensors writer: pins tensor order and metadata key order."""
-import json, struct
-import torch
-
-_DT = {torch.float32:"F32", torch.float64:"F64", torch.int64:"I64",
-       torch.int32:"I32", torch.int16:"I16", torch.int8:"I8",
-       torch.uint8:"U8", torch.bool:"BOOL"}
-
-def canonical_bytes(tensors, metadata_pairs):
-    """tensors: list of (name, tensor) in canonical order.
-       metadata_pairs: list of (key, value) in canonical order."""
-    header = {}
-    if metadata_pairs is not None:
-        header["__metadata__"] = {k: v for k, v in metadata_pairs}
-    blobs, off = [], 0
-    for name, t in tensors:
-        t = t.contiguous()
-        b = t.numpy().tobytes()
-        header[name] = {"dtype": _DT[t.dtype], "shape": list(t.shape),
-                        "data_offsets": [off, off + len(b)]}
-        blobs.append(b); off += len(b)
-    s = json.dumps(header, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
-    pad = (-(8 + len(s))) % 8
-    s = s + b" " * pad
-    return struct.pack("<Q", len(s)) + s + b"".join(blobs)

src/check_c.py

@@ -1,199 +0,0 @@
-"""The host on src/netlist_eval.c, an evaluator in C that shares no code with
-the Python evaluators.
-
-The host netlist is read from its serialization with the standard library,
-written in the flat form the C evaluator reads, levelized by the construction
-of Lemma 2.6 and written again. The C evaluator then checks one step of the
-netlist and one step of Lev(N_host) against its own SUBLEQ on random states,
-runs the self-describing instance and three generations of the
-self-reproducing instance, each instantiated from the bytes the previous one
-emitted.
-
-    python src/check_c.py [--cc gcc]
-"""
-import argparse
-import concurrent.futures as cf
-import hashlib
-import json
-import os
-import struct
-import subprocess
-import sys
-import tempfile
-import time
-from array import array
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-SRC = os.path.join(REPO, "src")
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def parse_sigma(data: bytes):
-    """Biases, predecessor lists and next-state indices from a serialization."""
-    hlen = struct.unpack("<Q", data[:8])[0]
-    head = json.loads(data[8:8 + hlen])
-    T = {}
-    for k, spec in head.items():
-        if k == "__metadata__":
-            continue
-        lo, hi = spec["data_offsets"]
-        a = array({"I8": "b", "I16": "h", "I32": "i"}[spec["dtype"]])
-        a.frombytes(data[8 + hlen + lo:8 + hlen + hi])
-        if sys.byteorder != "little":
-            a.byteswap()
-        T[k] = list(a)
-    bias, fanin, pred, nxt = T["net.bias"], T["net.fanin"], T["net.pred"], T["net.next"]
-    units, p = [], 0
-    for j in range(len(bias)):
-        units.append((bias[j], [(abs(e) - 1, 1 if e > 0 else -1) for e in pred[p:p + fanin[j]]]))
-        p += fanin[j]
-    return len(nxt), units, nxt
-
-
-def write_flat(path, n, units, nxt):
-    B, F, P = array("i"), array("i"), array("i")
-    for b, ins in units:
-        B.append(b)
-        F.append(len(ins))
-        for k, w in ins:
-            P.append(k)
-            P.append(w)
-    with open(path, "wb") as f:
-        f.write(struct.pack("<iii", n, len(units), len(P) // 2))
-        f.write(B.tobytes() + F.tobytes() + P.tobytes() + array("i", nxt).tobytes())
-
-
-def levelize(n, units, nxt):
-    """Lemma 2.6: every row of every layer reads only rows of the layer before."""
-    v = len(units)
-    live = [False] * (n + v)
-    stack = [k for k in nxt if k >= 0]
-    while stack:
-        s = stack.pop()
-        if not live[s]:
-            live[s] = True
-            if s >= n:
-                stack.extend(k for k, _ in units[s - n][1])
-    depth = [0] * (n + v)
-    for j, (_, ins) in enumerate(units):
-        depth[n + j] = 1 + max((depth[k] for k, _ in ins), default=0)
-    d = max(depth[n + j] for j in range(v) if live[n + j])
-    lam = [0] * (n + v)
-    for j, (_, ins) in enumerate(units):
-        if live[n + j]:
-            for k, _ in ins:
-                lam[k] = max(lam[k], depth[n + j])
-    for s in nxt:
-        lam[s] = d + 1
-    layers = [[("copy", i) for i in range(n)]]
-    where = [{i: i for i in range(n)}]
-    for ell in range(1, d):
-        rows, pos = [], {}
-        for s in range(n + v):
-            if s >= n and live[s] and depth[s] == ell:
-                pos[s] = len(rows); rows.append(("unit", s))
-        for s in range(n + v):
-            if (s < n or live[s]) and depth[s] < ell < lam[s]:
-                pos[s] = len(rows); rows.append(("copy", s))
-        layers.append(rows); where.append(pos)
-    layers.append([("unit" if depth[s] == d else "copy", s) for s in nxt])
-    base, out_units = [0], []
-    for ell in range(1, d + 1):
-        base.append(base[-1] + len(layers[ell - 1]))
-        for kind, s in layers[ell]:
-            if kind == "copy":
-                out_units.append((-1, [(base[ell - 1] + where[ell - 1][s], 1)]))
-            else:
-                b, ins = units[s - n]
-                out_units.append((b, [(base[ell - 1] + where[ell - 1][k], w) for k, w in ins]))
-    return (n, out_units, [base[d] + i for i in range(n)],
-            {"depth": d, "rows": sum(len(L) for L in layers[1:]),
-             "identity_rows": sum(1 for L in layers[1:] for kind, _ in L if kind == "copy"),
-             "max_width": max(len(L) for L in layers[1:]),
-             "layer_sizes": [len(L) for L in layers[1:]]})
-
-
-def framed_parts(s: bytes):
-    a = struct.unpack("<Q", s[:8])[0]
-    b = struct.unpack("<Q", s[8 + a:16 + a])[0]
-    return s[8:8 + a], s[16 + a:16 + a + b], s[16 + a + b:]
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser()
-    ap.add_argument("--cc", default="gcc")
-    args = ap.parse_args()
-    t_start = time.perf_counter()
-    from selfrep import M_P, M_STAR, describe, field, ser, read_host
-    work = tempfile.mkdtemp(prefix="netlist_eval_")
-    exe = os.path.join(work, "netlist_eval")
-    subprocess.run([args.cc, "-O3", "-march=native", "-fopenmp", "-o", exe,
-                    os.path.join(SRC, "netlist_eval.c")], check=True)
-    J = lambda *p: os.path.join(work, *p)
-
-    def ev(*a):
-        r = subprocess.run([exe] + [str(x) for x in a], capture_output=True, text=True)
-        return r.returncode, r.stdout.strip()
-
-    sigma = read_host()
-    n, units, nxt = parse_sigma(sigma)
-    write_flat(J("host.bin"), n, units, nxt)
-    ln, lunits, lnxt, lev_info = levelize(n, units, nxt)
-    write_flat(J("lev.bin"), ln, lunits, lnxt)
-    r_H = describe(sigma)
-    tau = describe(field(sigma) + field(bytes(M_STAR)))
-    expect_star = ser(sigma, bytes(M_STAR), tau)
-    for name, b in (("mP", bytes(M_P)), ("mstar", bytes(M_STAR)), ("rH", r_H), ("tau", tau)):
-        open(J(name), "wb").write(b)
-    out = {"lev": lev_info}
-
-    with cf.ThreadPoolExecutor(max_workers=4) as ex:
-        f_rand = ex.submit(ev, "rand", J("host.bin"), 1 << 20, 1)
-        f_lrand = ex.submit(ev, "rand", J("lev.bin"), 1 << 20, 2)
-        f_desc = ex.submit(ev, "run", J("host.bin"), J("mP"), J("rH"), J("desc.out"), "lock")
-        out["netlist_random"] = f_rand.result()[1]
-        out["lev_random"] = f_lrand.result()[1]
-        out["self_describing"] = f_desc.result()[1]
-        # three generations, each rebuilt from the bytes the previous one emitted
-        gens = []
-        net_path, mem_path, tau_path = J("host.bin"), J("mstar"), J("tau")
-        for g in range(1, 4):
-            mode = "lock" if g == 1 else "net"
-            rc, msg = ev("run", net_path, mem_path, tau_path, J(f"gen{g}.out"), mode)
-            emitted = open(J(f"gen{g}.out"), "rb").read()
-            gens.append({"generation": g, "mode": mode, "result": msg,
-                         "sha256": hashlib.sha256(emitted).hexdigest(),
-                         "equals_ser": emitted == expect_star})
-            s_g, m_g, t_g = framed_parts(emitted)
-            n2, u2, x2 = parse_sigma(s_g)
-            net_path = J(f"host_g{g + 1}.bin")
-            write_flat(net_path, n2, u2, x2)
-            mem_path, tau_path = J(f"m_g{g + 1}"), J(f"tau_g{g + 1}")
-            open(mem_path, "wb").write(m_g)
-            open(tau_path, "wb").write(t_g)
-        out["generations"] = gens
-    desc_ok = open(J("desc.out"), "rb").read() == sigma
-    ok = (out["netlist_random"].endswith("0 halted batches not fixed")
-          and " 0 disagree" in out["netlist_random"] and " 0 disagree" in out["lev_random"]
-          and desc_ok and all(g["equals_ser"] for g in gens))
-    out["self_describing_equals_sigma"] = desc_ok
-    out["ok"] = ok
-    out["seconds"] = time.perf_counter() - t_start
-    for k in ("netlist_random", "lev_random", "self_describing"):
-        print(f"  {k}: {out[k]}")
-    for g in gens:
-        print(f"  generation {g['generation']} ({g['mode']}): {g['result']}; equals ser: "
-              f"{'yes' if g['equals_ser'] else 'NO'}; {g['sha256'][:16]}")
-    json.dump(out, open(runs_path("paper_c_evaluator.json"), "w"), indent=1)
-    print("C EVALUATOR:", "PASS" if ok else "FAIL")
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_codec.py

@@ -1,128 +0,0 @@
-"""The recipe codec on every short string and at every boundary of the format.
-
-Checked for both encoders: the round trip, the length bound of the completeness
-lemma, and that the reserved tag 128 is never emitted. The boundaries covered
-are the 127-byte literal cap and the run lengths that map to the extreme repeat
-tags, together with exhaustive coverage at small lengths.
-"""
-import itertools
-import json
-import os
-import random
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from selfrep import describe, describe_literal, decode
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def bound(n: int) -> int:
-    return n + -(-n // 127) + 1
-
-
-def tags(tape: bytes):
-    i, out = 0, []
-    while True:
-        t = tape[i]
-        out.append(t)
-        i += 1
-        if t == 0:
-            return out
-        i += t if t <= 127 else 1
-
-
-class Audit:
-    def __init__(self):
-        self.n = 0
-        self.roundtrip = []
-        self.overlong = []
-        self.not_tight = []
-        self.tag128 = []
-
-    def check(self, b: bytes) -> None:
-        self.n += 1
-        for enc in (describe, describe_literal):
-            r = enc(b)
-            if decode(r) != b:
-                self.roundtrip.append((enc.__name__, len(b)))
-            if len(r) > bound(len(b)):
-                self.overlong.append((enc.__name__, len(b), len(r)))
-        if len(describe_literal(b)) != bound(len(b)):
-            self.not_tight.append(len(b))
-        if 128 in tags(describe(b)):
-            self.tag128.append(len(b))
-
-    @property
-    def ok(self) -> bool:
-        return not (self.roundtrip or self.overlong or self.not_tight or self.tag128)
-
-
-def main() -> int:
-    a = Audit()
-    for n in range(0, 15):
-        for t in itertools.product((0, 1), repeat=n):
-            a.check(bytes(t))
-    binary = a.n
-    for n in range(0, 10):
-        for t in itertools.product((0, 1, 2), repeat=n):
-            a.check(bytes(t))
-    ternary = a.n - binary
-    print(f"  exhaustive: {binary:,} binary strings to length 14, "
-          f"{ternary:,} ternary to length 9")
-
-    edges = (list(range(0, 12))
-             + [126, 127, 128, 129, 130, 251, 252, 253, 254, 255, 256, 257,
-                380, 381, 382, 508, 509, 510])
-    before = a.n
-    for L in edges:
-        a.check(bytes([0x41]) * L)
-        a.check(bytes([0x00]) * L)
-        a.check(bytes([0xFF]) * L)
-        a.check(bytes(range(256))[:L] if L <= 256 else bytes(range(256)) * (L // 256))
-        a.check(bytes([0x41] * L + [0x42]))
-        a.check(bytes([0x42] + [0x41] * L))
-        a.check(bytes([0x41] * L + [0x42] * L))
-        a.check(bytes(([0x41] * 4 + [0x42]) * max(1, L)))
-        a.check(bytes(([0x41] * 3 + [0x42]) * max(1, L)))
-    print(f"  boundaries: {a.n - before:,} strings straddling the literal cap, "
-          f"the extreme repeat tags, and the run/literal transitions")
-
-    rng = random.Random(11)
-    before = a.n
-    for _ in range(4000):
-        n = rng.randrange(0, 900)
-        alpha = rng.choice([2, 3, 7, 256])
-        a.check(bytes(rng.randrange(alpha) for _ in range(n)))
-    for _ in range(1500):
-        n = rng.randrange(0, 900)
-        out = bytearray()
-        while len(out) < n:
-            out += bytes([rng.randrange(256)]) * rng.choice([1, 2, 3, 4, 5, 126, 127, 128, 253])
-        a.check(bytes(out[:n]))
-    print(f"  random and run-structured: {a.n - before:,} strings")
-
-    print(f"  total {a.n:,}: round-trip exact, neither encoder exceeds "
-          f"|f| + ceil(|f|/127) + 1, the literal encoder attains it, "
-          f"tag 128 never emitted: {'yes' if a.ok else 'NO'}")
-    if not a.ok:
-        print("   roundtrip:", a.roundtrip[:5])
-        print("   overlong:", a.overlong[:5])
-        print("   not tight:", a.not_tight[:5])
-        print("   tag128:", a.tag128[:5])
-    json.dump({"strings": a.n, "roundtrip_failures": len(a.roundtrip),
-               "bound_failures": len(a.overlong),
-               "literal_not_tight": len(a.not_tight),
-               "tag128_emitted": len(a.tag128)},
-              open(runs_path("paper_codec.json"), "w"), indent=1)
-    return 0 if a.ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_device.py

@@ -1,118 +0,0 @@
-"""The device against Definition 2.8 of the paper.
-
-Definition 2.8 specifies one device application on the
-post-instruction state (x, tau, h, omega):
-
-  (i)   if y[c_wr] = 1 then omega' = omega . y[R_out] and x'[R_out] = 0,
-        otherwise omega' = omega;
-  (ii)  if y[c_rd] = 1 and h < |tau| then x'[R_in] = tau[h], x'[c_eot] = 0,
-        h' = h + 1; if y[c_rd] = 1 and h = |tau| then x'[c_eot] = 1 and h' = h;
-        if y[c_rd] = 0 then h' = h;
-  (iii) if y[c_rw] = 1 then h' = 0;
-  (iv)  finally x'[c_rd] = x'[c_rw] = x'[c_wr] = 0.
-
-The clauses are transcribed here independently of selfrep.Tape and the two are
-compared over the whole cross product of request values, head positions and
-tapes. The sweep covers non-unit values, so it also decides whether a request
-fires on the value 1 alone.
-"""
-import itertools
-import json
-import os
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from selfrep import Tape, C_WR, C_EOT, C_RW, C_RD, R_IN, R_OUT
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def spec(mem, tau, h, omega):
-    """Definition 2.8, clause by clause, on (mem, h, omega)."""
-    m = list(mem)
-    w = list(omega)
-    if m[C_WR] == 1:                                   # (i)
-        w.append(m[R_OUT])
-        m[R_OUT] = 0
-    hp = h
-    if m[C_RD] == 1:                                   # (ii)
-        if h < len(tau):
-            m[R_IN] = tau[h]
-            m[C_EOT] = 0
-            hp = h + 1
-        else:
-            m[C_EOT] = 1
-    if m[C_RW] == 1:                                   # (iii)
-        hp = 0
-    m[C_WR] = m[C_RD] = m[C_RW] = 0                    # (iv)
-    return m, hp, w
-
-
-def main() -> int:
-    tapes = [b"", b"\x07", b"\x01\x02", bytes(range(5)), bytes(range(64))]
-    vals = (0, 1, 2, 3, 127, 128, 255)
-    bad, n = [], 0
-    for tau in tapes:
-        heads = sorted({0, 1, max(0, len(tau) - 1), len(tau)})
-        for h in heads:
-            for wr, rd, rw in itertools.product(vals, repeat=3):
-                for eot, rin, rout in ((0, 0, 0), (1, 9, 200), (0, 255, 1), (1, 1, 255)):
-                    mem = [0] * 256
-                    mem[C_WR], mem[C_RD], mem[C_RW] = wr, rd, rw
-                    mem[C_EOT], mem[R_IN], mem[R_OUT] = eot, rin, rout
-                    mem[0x10] = 0xAB                    # an ordinary cell, must not move
-                    want_mem, want_h, want_out = spec(mem, tau, h, b"")
-
-                    dev = Tape(tau)
-                    dev.h = h
-                    got_mem = list(mem)
-                    dev.apply(got_mem)
-                    n += 1
-                    if (got_mem != want_mem or dev.h != want_h
-                            or bytes(dev.out) != bytes(want_out)):
-                        bad.append({"tau": len(tau), "h": h, "wr": wr, "rd": rd,
-                                    "rw": rw, "eot": eot,
-                                    "spec": (want_mem[C_EOT], want_mem[R_IN],
-                                             want_mem[R_OUT], want_h, list(want_out)),
-                                    "impl": (got_mem[C_EOT], got_mem[R_IN],
-                                             got_mem[R_OUT], dev.h, list(dev.out))})
-    print(f"  device applications compared: {n:,}")
-    print(f"  implementation agrees with Definition 2.8 on every one: "
-          f"{'yes' if not bad else f'NO ({len(bad)} disagreements)'}")
-    for b in bad[:5]:
-        print("   ", b)
-
-    # A request fires on the value 1 and on no other value. The head starts off
-    # zero so that a rewind is observable; without that a rewind of a head
-    # already at 0 changes nothing and the test would not see it fire.
-    fires = []
-    for cell in (C_WR, C_RD, C_RW):
-        for v in range(256):
-            mem = [0] * 256
-            mem[cell] = v
-            mem[R_OUT] = 0x5A
-            dev = Tape(b"\x11\x22")
-            dev.h = 1
-            before = (dev.h, len(dev.out))
-            dev.apply(mem)
-            acted = (dev.h, len(dev.out)) != before or mem[R_IN] != 0 or mem[C_EOT] != 0
-            if acted != (v == 1):
-                fires.append((cell, v, acted))
-    print(f"  each request fires exactly on the value 1, over all 256 cell values: "
-          f"{'yes' if not fires else f'NO {fires[:5]}'}")
-
-    ok = not bad and not fires
-    json.dump({"applications": n, "disagreements": len(bad),
-               "value_trigger_failures": len(fires)},
-              open(runs_path("paper_device.json"), "w"), indent=1)
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_environment.py

@@ -1,110 +0,0 @@
-"""The cost of instantiation against the cost of the network.
-
-One generation of the host is: inst splits the emitted bytes, sigma^-1 parses
-the first field into the netlist, Lev places the rows and entries of the
-layered map, and the device is applied once per step. This script counts those
-operations, one per byte read by inst and by sigma^-1, one per row and one per
-nonzero entry placed by Lev, and one per device application, times each of
-them, and compares the total with the T * M unit evaluations of the run.
-"""
-import json
-import os
-import sys
-import time
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def main() -> int:
-    from selfrep import (M_STAR, inst, ser, tau_star, run_reference, read_host,
-                         host_netlist, sigma_host)
-    from netlist_io import net_of_sigma
-    from matrix8 import compile_net
-
-    sigma_bytes = read_host()
-    tau = tau_star(sigma_bytes, M_STAR)
-    s = ser(sigma_bytes, bytes(M_STAR), tau)
-
-    # sigma: parameters and predecessor entries stored, and the time to write
-    t0 = time.perf_counter()
-    net, inputs, outputs = host_netlist()
-    t_build = time.perf_counter() - t0
-    t0 = time.perf_counter()
-    encoded = sigma_host()
-    t_sigma = time.perf_counter() - t0
-    assert encoded == sigma_bytes
-    stored, _, _, _ = net_of_sigma(sigma_bytes)
-    entries = (2 * len(stored.gates)                       # bias and fan-in
-               + sum(len(i) for i, _ in stored.gates.values())
-               + len(outputs))
-    print(f"  sigma: {entries:,} stored entries -> {len(encoded):,} bytes "
-          f"in {t_sigma * 1e3:.0f} ms ({t_build * 1e3:.0f} ms to assemble "
-          f"the netlist from source)")
-
-    # inst: one pass over the serialized instance, then sigma^-1 on its first field
-    t0 = time.perf_counter()
-    reps = 50
-    for _ in range(reps):
-        a, b, c = inst(s)
-    t_inst = (time.perf_counter() - t0) / reps
-    assert (a, b, c) == (sigma_bytes, bytes(M_STAR), tau)
-    t0 = time.perf_counter()
-    for _ in range(5):
-        N, I, O, _ = net_of_sigma(a)
-    t_sigma_inv = (time.perf_counter() - t0) / 5
-    assert len(N.gates) == len(stored.gates)
-    print(f"  inst: {len(s):,} bytes parsed in {t_inst * 1e3:.2f} ms, and "
-          f"{len(N.gates):,} units rebuilt from the first field in "
-          f"{t_sigma_inv * 1e3:.0f} ms")
-
-    # Lev: the units placed, and the time to place them
-    t0 = time.perf_counter()
-    layers, info = compile_net(N, I, O)
-    t_lev = time.perf_counter() - t0
-    M = sum(int(W.shape[0]) for W, _ in layers)
-    nnz = sum(int((W != 0).sum()) for W, _ in layers)
-    print(f"  Lev: {len(N.gates):,} units in, {M:,} rows and {nnz:,} nonzero "
-          f"entries placed over {info['layers']} layers in {t_lev:.1f} s")
-
-    # the device: one application per step, at most one byte moved
-    t0 = time.perf_counter()
-    emitted, T = run_reference(M_STAR, tau)
-    t_run = time.perf_counter() - t0
-    assert emitted == s
-    print(f"  device: {T:,} applications, {len(emitted):,} bytes emitted "
-          f"({t_run:.2f} s for the whole reference run)")
-
-    env_ops = len(s) + len(sigma_bytes) + M + nnz + T
-    closed = 2 * len(sigma_bytes) + len(bytes(M_STAR)) + len(tau) + 16 + M + nnz + T
-    assert env_ops == closed, (env_ops, closed)
-    net_ops = T * M
-    print(f"  instantiation: {env_ops:,} elementary operations per generation, "
-          f"which is the closed form 2|sigma|+|m|+|tau|+16+M+nnz+T")
-    print(f"  network:     {net_ops:,} unit evaluations (T = {T:,}, M = {M:,})")
-    print(f"  ratio: {env_ops / net_ops:.3e}")
-
-    out = {"sigma_entries": entries, "sigma_bytes": len(encoded),
-           "sigma_seconds": t_sigma, "build_seconds": t_build,
-           "inst_bytes": len(s), "inst_seconds": t_inst,
-           "sigma_inverse_seconds": t_sigma_inv,
-           "lev_units_in": len(N.gates), "lev_units_out": M, "lev_nonzero": nnz,
-           "lev_layers": info["layers"], "lev_seconds": t_lev,
-           "lev_entries": info["total_weights"],
-           "steps": T, "emitted_bytes": len(emitted),
-           "reference_seconds": t_run,
-           "environment_ops": env_ops, "network_ops": net_ops,
-           "ratio": env_ops / net_ops}
-    json.dump(out, open(runs_path("paper_environment.json"), "w"), indent=1)
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_family.py

@@ -1,64 +0,0 @@
-"""The universal constructor emits every machine of the artifact, byte for byte.
-
-The machines are run on the integer reference, one process per machine.
-
-    python src/check_family.py [--jobs N]
-"""
-import argparse, concurrent.futures as cf, hashlib, json, os, sys, time
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from selfrep import describe, run_reference, M_P
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def files():
-    out = [os.path.join(REPO, "neural_computer.safetensors")]
-    v = os.path.join(REPO, "variants")
-    out += sorted(os.path.join(v, f) for f in os.listdir(v) if f.endswith(".safetensors"))
-    return out
-
-
-def one(p):
-    data = open(p, "rb").read()
-    r = describe(data)
-    out, steps = run_reference(M_P, r, expect=data)
-    return {"file": os.path.basename(p), "bytes": len(out), "recipe": len(r),
-            "steps": steps, "exact": out == data,
-            "sha256": hashlib.sha256(out).hexdigest()}
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser()
-    ap.add_argument("--jobs", type=int, default=os.cpu_count() or 1)
-    args = ap.parse_args()
-    t0 = time.perf_counter()
-    paths = files()
-    # the largest machines first, so the pool is not left waiting on one of them
-    order = sorted(paths, key=os.path.getsize, reverse=True)
-    with cf.ProcessPoolExecutor(max_workers=args.jobs) as ex:
-        got = dict(zip(order, ex.map(one, order)))
-    rec = [got[p] for p in paths]
-    for r in rec:
-        print(f"  {'OK ' if r['exact'] else 'FAIL'} {r['file']:<44} "
-              f"{r['bytes']:>10,} B  {r['steps']:>12,} steps", flush=True)
-    bad = sum(not r["exact"] for r in rec)
-    tot_b = sum(r["bytes"] for r in rec)
-    tot_s = sum(r["steps"] for r in rec)
-    tot_r = sum(r["recipe"] for r in rec)
-    dt = time.perf_counter() - t0
-    print(f"{len(rec)} machines, {tot_b:,} bytes emitted in {tot_s:,} steps "
-          f"from {tot_r:,} bytes of recipe ({dt/60:.1f} min); failures: {bad}")
-    json.dump({"machines": rec, "bytes": tot_b, "steps": tot_s,
-               "recipe_bytes": tot_r, "failures": bad, "seconds": dt},
-              open(runs_path("paper_runs_family.json"), "w"), indent=1)
-    return 0 if bad == 0 else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_family_gate.py

@@ -1,70 +0,0 @@
-"""The constructor emitting other machines of the family on the netlist.
-
-check_family.py runs the constructor on all twenty-eight serialized machines,
-but on the integer reference. The claim that the netlist emits them is stronger
-than the claim that the reference does, so the machines small enough to finish
-are run here on the netlist that sigma(N_host) denotes, unit by unit, with each
-emitted byte compared against the target as it is produced.
-"""
-import hashlib
-import json
-import os
-import sys
-import time
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from selfrep import NetEvaluator, describe, read_host, run_reference, M_P
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-TARGETS = ["neural_tile.safetensors", "neural_ca.safetensors",
-           "neural_reversible.safetensors", "neural_attractor.safetensors"]
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def main() -> int:
-    import torch
-    device = "cuda" if torch.cuda.is_available() else "cpu"
-    F = NetEvaluator(read_host(), device=device,
-                     graph=device.startswith("cuda"))
-    rows = []
-    bad = 0
-    total_b = total_s = 0
-    t_all = time.perf_counter()
-    for name in TARGETS:
-        path = os.path.join(REPO, "variants", name)
-        data = open(path, "rb").read()
-        r = describe(data)
-        ref_out, ref_steps = run_reference(M_P, r, expect=data)
-        assert ref_out == data
-        t0 = time.perf_counter()
-        out, steps = F.run(M_P, r, max_steps=ref_steps + 8, expect=data,
-                           progress=200000)
-        dt = time.perf_counter() - t0
-        ok = out == data and steps == ref_steps
-        bad += not ok
-        total_b += len(out)
-        total_s += steps
-        rows.append({"file": name, "bytes": len(out), "recipe": len(r),
-                     "steps": steps, "reference_steps": ref_steps,
-                     "exact": ok, "seconds": dt,
-                     "steps_per_second": steps / dt if dt else None,
-                     "sha256": hashlib.sha256(out).hexdigest()})
-        print(f"  {'OK ' if ok else 'FAIL'} {name:<34} {len(out):>9,} B  "
-              f"{steps:>10,} steps  ({dt / 60:.1f} min, "
-              f"{steps / dt:,.0f} steps/s)", flush=True)
-    dt = time.perf_counter() - t_all
-    print(f"  {len(rows)} machines on the netlist of sigma: {total_b:,} bytes in "
-          f"{total_s:,} steps ({dt / 60:.1f} min); failures: {bad}")
-    json.dump({"machines": rows, "bytes": total_b, "steps": total_s,
-               "failures": bad, "seconds": dt},
-              open(runs_path("paper_runs_family_gate.json"), "w"), indent=1)
-    return 0 if bad == 0 else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_framing.py

@@ -1,133 +0,0 @@
-"""The framing maps ser and inst: round trip, injectivity, and rejection.
-
-Lemma 2.14 of the paper turns on two properties of Definition 2.12: that the
-length fields make the decomposition of ser(Omega) unique, so that ser is
-injective and inst inverts it, and that inst is partial, rejecting a string that
-is not a framed instance, in place of returning some other triple. Both are
-checked here on shapes chosen to stress the framing: empty serializations and
-tapes, payloads whose leading bytes look like length fields, memory images at
-both extremes, and every truncation of a real instance.
-"""
-import hashlib
-import json
-import os
-import random
-import struct
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from selfrep import ser, inst, lam, HOST_PATH, M_STAR, tau_star
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def shapes():
-    rng = random.Random(5)
-    host = open(HOST_PATH, "rb").read()
-    m0 = bytes(256)
-    m1 = bytes([255]) * 256
-    mr = bytes(rng.randrange(256) for _ in range(256))
-    # A payload whose first eight bytes are a plausible length field, and a tape
-    # that begins the way a framed field begins: if inst read a length from the
-    # wrong offset these would decode to the wrong split.
-    trap = lam(1 << 40) + b"trap"
-    out = [
-        (b"", m0, b""),
-        (b"", m0, b"\x00"),
-        (b"\x00", m0, b""),
-        (b"\x00" * 3, m1, b""),
-        (trap, mr, b""),
-        (b"", mr, trap),
-        (trap, m0, trap),
-        (bytes(range(256)), mr, bytes(range(256))),
-        (host, bytes(M_STAR), tau_star(host, M_STAR)),
-        (host, m0, b""),
-    ]
-    for _ in range(300):
-        a = bytes(rng.randrange(256) for _ in range(rng.randrange(0, 300)))
-        t = bytes(rng.randrange(256) for _ in range(rng.randrange(0, 300)))
-        out.append((a, bytes(rng.randrange(256) for _ in range(256)), t))
-    return out
-
-
-def main() -> int:
-    cases = shapes()
-    rt_bad, digests = [], {}
-    for sg, m, t in cases:
-        b = ser(sg, m, t)
-        if inst(b) != (sg, m, t):
-            rt_bad.append((len(sg), len(t)))
-        digests.setdefault(hashlib.sha256(b).hexdigest(), []).append((len(sg), len(m), len(t)))
-    collisions = {k: v for k, v in digests.items() if len(v) > 1}
-    print(f"  inst(ser(Omega)) = Omega on {len(cases)} instances: "
-          f"{'exact' if not rt_bad else f'{len(rt_bad)} FAILED'}")
-    print(f"  ser injective over them (distinct instances, distinct bytes): "
-          f"{'yes' if not collisions else f'NO {list(collisions.values())[:2]}'}")
-
-    # Truncations. A string shorter than the framed serialization and memory
-    # image is not an instance and must be rejected; one that reaches at least
-    # that far is the instance with a correspondingly shorter tape, and must
-    # parse to exactly that.
-    host = open(HOST_PATH, "rb").read()
-    tau = tau_star(host, M_STAR)
-    full = ser(host, bytes(M_STAR), tau)
-    minimal = 16 + len(host) + 256
-    probes = sorted({p for p in
-                     [0, 1, 7, 8, 9, 15, 16, 17,
-                      8 + len(host) - 1, 8 + len(host), 8 + len(host) + 7,
-                      8 + len(host) + 8, minimal - 256, minimal - 1, minimal,
-                      minimal + 1, len(full) - 1, len(full)]
-                     if 0 <= p <= len(full)})
-    wrongly_accepted, wrongly_rejected = [], []
-    for k in probes:
-        try:
-            got = inst(full[:k])
-        except (ValueError, IndexError, struct.error):
-            if k >= minimal:
-                wrongly_rejected.append(k)
-            continue
-        if k < minimal:
-            wrongly_accepted.append((k, len(got[1])))
-        elif got != (host, bytes(M_STAR), full[minimal:k]):
-            wrongly_accepted.append((k, "wrong triple"))
-    short = sum(1 for k in probes if k < minimal)
-    print(f"  {short} truncations below a complete memory image rejected: "
-          f"{'yes' if not wrongly_accepted else f'NO {wrongly_accepted}'}")
-    print(f"  {len(probes) - short} longer prefixes parse to the instance with "
-          f"that tape: {'yes' if not wrongly_rejected else f'NO {wrongly_rejected}'}")
-    accepted = wrongly_accepted + wrongly_rejected
-
-    # a memory field of the wrong length must be rejected
-    wrong = []
-    for size in (0, 1, 255, 257, 512):
-        b = lam(len(host)) + host + lam(size) + bytes(size) + tau
-        try:
-            inst(b)
-            wrong.append(size)
-        except (ValueError, IndexError, struct.error):
-            pass
-    print(f"  memory field of length != 256 rejected: "
-          f"{'yes' if not wrong else f'NO for {wrong}'}")
-
-    # the full instance is accepted and recovers exactly
-    exact = inst(full) == (host, bytes(M_STAR), tau)
-    print(f"  the distributed instance parses back exactly: {exact}")
-
-    ok = not rt_bad and not collisions and not accepted and not wrong and exact
-    json.dump({"instances": len(cases), "roundtrip_failures": len(rt_bad),
-               "digest_collisions": len(collisions),
-               "truncations_accepted": len(accepted),
-               "bad_memory_lengths_accepted": len(wrong),
-               "distributed_instance_exact": exact},
-              open(runs_path("paper_framing.json"), "w"), indent=1)
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_host.py

@@ -1,113 +0,0 @@
-"""The reference machine against Definition 3.1, and the halt fixed point.
-
-Definition 3.1 specifies one SUBLEQ step: read A = M[p], B = M[p+1], C = M[p+2],
-set M[B] <- M[B] - M[A] mod 256, and set p <- C when the new M[B] is at most 0
-in two's complement and p <- p + 3 otherwise, with indices taken modulo 256 and
-a halt at p = 255. The clauses are transcribed here independently of
-selfrep.run_reference and the two are compared, with the program counter swept
-over every value so the wrapped fetches at the top of memory are covered.
-
-Proposition 3.9 asserts in addition that a halted state is a fixed point of the
-transition, because every architectural write is gated by the negation of the
-halt bit. That is checked on the levelized map itself, not on the reference.
-"""
-import json
-import os
-import random
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from selfrep import Tape, HALT_PC
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def spec_step(mem, p):
-    """Definition 3.1, transcribed."""
-    A = mem[p % 256]
-    B = mem[(p + 1) % 256]
-    C = mem[(p + 2) % 256]
-    m = list(mem)
-    r = (m[B % 256] - m[A % 256]) % 256
-    m[B % 256] = r
-    two_c = r - 256 if r >= 128 else r
-    return m, (C if two_c <= 0 else (p + 3) % 256)
-
-
-def impl_step(mem, p):
-    """The reference of selfrep.run_reference, one step, device detached."""
-    m = list(mem)
-    A = m[p]
-    B = m[(p + 1) & 0xFF]
-    C = m[(p + 2) & 0xFF]
-    r = (m[B] - m[A]) & 0xFF
-    m[B] = r
-    return m, (C if (r == 0 or r >= 0x80) else (p + 3) & 0xFF)
-
-
-def main() -> int:
-    rng = random.Random(31)
-    bad, n = [], 0
-    mems = [[0] * 256, [255] * 256, list(range(256)), list(reversed(range(256)))]
-    mems += [[rng.randrange(256) for _ in range(256)] for _ in range(60)]
-    for mem in mems:
-        for p in range(256):                       # every counter, wraps included
-            if p == HALT_PC:
-                continue
-            sm, sp = spec_step(mem, p)
-            im, ip = impl_step(mem, p)
-            n += 1
-            if sm != im or sp != ip:
-                bad.append((p, sp, ip))
-    print(f"  reference steps compared with Definition 3.1: {n:,}")
-    print(f"  agree on every one: {'yes' if not bad else f'NO {bad[:4]}'}")
-
-    wrapped = sum(1 for p in (254, 255, 253) if p != HALT_PC) * len(mems)
-    print(f"  of which {len(mems) * 3:,} fetch an operand across the top of memory")
-
-    # A halted state is a fixed point of the levelized map. The state is halted
-    # when the halt bit is set, coordinate 8 of the vector; the bit latches one
-    # step after the next counter decodes to 255, so setting the counter alone
-    # does not halt the machine.
-    from selfrep import LevEvaluator, read_host
-    import torch
-    L = LevEvaluator(read_host(), device="cpu", dense=False)
-    gen = torch.Generator().manual_seed(97)
-    V = (torch.rand(48, L.N, generator=gen) < 0.5).float()
-    V[:, 8] = 1.0
-    fixed = bool((L.step(V) == V).all())
-    print(f"  halted states are fixed points of Lev(N_host), 48 random states: "
-          f"{'yes' if fixed else 'NO'}")
-
-    # And the bit latches exactly when the next counter is 255: run one step
-    # from unhalted states and compare the latched bit against the reference.
-    U = (torch.rand(64, L.N, generator=gen) < 0.5).float()
-    U[:, 8] = 0.0
-    W = L.step(U)
-    latch_bad = 0
-    for i in range(U.shape[0]):
-        mem = [int(sum(int(U[i, 9 + j * 8 + k]) << (7 - k) for k in range(8)))
-               for j in range(256)]
-        pc = int(sum(int(U[i, k]) << (7 - k) for k in range(8)))
-        _, npc = impl_step(mem, pc)
-        if int(W[i, 8]) != (1 if npc == HALT_PC else 0):
-            latch_bad += 1
-    print(f"  the halt bit latches exactly when the next counter is 255, "
-          f"64 random states: {'yes' if latch_bad == 0 else f'NO ({latch_bad})'}")
-    fixed = fixed and latch_bad == 0
-
-    ok = not bad and fixed
-    json.dump({"steps_compared": n, "disagreements": len(bad),
-               "halt_fixed_point": fixed},
-              open(runs_path("paper_host.json"), "w"), indent=1)
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_host_family.py

@@ -1,65 +0,0 @@
-"""The host family on the evaluator in C: one step of H_A against SUBLEQ_A.
-
-For each width A the serialization of H_A is written by host_family.sigma,
-parsed with the standard library, written in the flat form of
-src/netlist_eval.c, and one step of the netlist is compared with the C
-evaluator's own SUBLEQ on uniformly random full states, together with the
-halted fixed point.
-
-    python src/check_host_family.py [--widths 3-12] [--states N]
-"""
-import argparse
-import json
-import os
-import subprocess
-import sys
-import tempfile
-import time
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser()
-    ap.add_argument("--widths", default="3-12")
-    ap.add_argument("--states", type=int, default=1 << 16)
-    ap.add_argument("--cc", default="gcc")
-    args = ap.parse_args()
-    lo, hi = (int(x) for x in args.widths.split("-"))
-    from host_family import sigma
-    from check_c import parse_sigma, write_flat
-    work = tempfile.mkdtemp(prefix="host_family_")
-    exe = os.path.join(work, "netlist_eval")
-    subprocess.run([args.cc, "-O3", "-march=native", "-fopenmp", "-o", exe,
-                    os.path.join(REPO, "src", "netlist_eval.c")], check=True)
-    rows, ok = [], True
-    for A in range(lo, hi + 1):
-        t0 = time.perf_counter()
-        s = sigma(A)
-        n, units, nxt = parse_sigma(s)
-        path = os.path.join(work, f"h{A}.bin")
-        write_flat(path, n, units, nxt)
-        N = max(64, args.states >> max(0, A - 10))
-        r = subprocess.run([exe, "rand", path, str(N), str(A)], capture_output=True, text=True)
-        line = r.stdout.strip()
-        good = r.returncode == 0
-        ok &= good
-        rows.append({"A": A, "sigma_bytes": len(s), "units": len(units),
-                     "edges": sum(len(i) for _, i in units), "states": N,
-                     "result": line, "ok": good, "seconds": time.perf_counter() - t0})
-        print(f"  A={A}: {len(units):,} units, {len(s):,} bytes; {line}", flush=True)
-        os.remove(path)
-    json.dump({"widths": rows, "ok": ok}, open(runs_path("paper_host_family.json"), "w"), indent=1)
-    print("HOST FAMILY:", "PASS" if ok else "FAIL")
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_host_fold.py

@@ -1,73 +0,0 @@
-"""The host family with its decoders folded into the read conjunctions: depth 11.
-
-Every fetch and read conjunction and every write enable of H_A reads the bits of
-its address directly, so a read from memory takes two levels from the address
-bits and not three, and the operand fetch and the operand reads each lose one
-level. The step of the folded netlist has depth 11 for every A, against 13. It is
-written with host_family.build(A, fold=True), serialized, and one step is
-compared with the C evaluator's own SUBLEQ on uniformly random full states, as
-src/check_host_family.py does for H_A.
-
-    python src/check_host_fold.py [--widths 3-12] [--states N]
-"""
-import argparse
-import json
-import os
-import subprocess
-import sys
-import tempfile
-import time
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def depth_of(n, units, nxt):
-    d = [0] * (n + len(units))
-    for j, (_, ins) in enumerate(units):
-        d[n + j] = 1 + max((d[k] for k, _ in ins), default=0)
-    return max(d[s] for s in nxt)
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser()
-    ap.add_argument("--widths", default="3-12")
-    ap.add_argument("--states", type=int, default=1 << 16)
-    ap.add_argument("--cc", default="gcc")
-    args = ap.parse_args()
-    lo, hi = (int(x) for x in args.widths.split("-"))
-    from host_family import build, sigma_of_net, sigma
-    from check_c import parse_sigma, write_flat
-    work = tempfile.mkdtemp(prefix="host_fold_")
-    exe = os.path.join(work, "netlist_eval")
-    subprocess.run([args.cc, "-O3", "-march=native", "-fopenmp", "-o", exe,
-                    os.path.join(REPO, "src", "netlist_eval.c")], check=True)
-    rows, ok = [], True
-    for A in range(lo, hi + 1):
-        t0 = time.perf_counter()
-        net, inputs, outputs = build(A, fold=True)
-        s = sigma_of_net(net, inputs, outputs, A)
-        n, units, nxt = parse_sigma(s)
-        n0, units0, nxt0 = parse_sigma(sigma(A))
-        path = os.path.join(work, f"f{A}.bin")
-        write_flat(path, n, units, nxt)
-        N = max(64, args.states >> max(0, A - 10))
-        r = subprocess.run([exe, "rand", path, str(N), str(A)], capture_output=True, text=True)
-        line = r.stdout.strip().splitlines()[-1] if r.stdout.strip() else r.stderr.strip()
-        good = r.returncode == 0
-        ok &= good
-        row = {"A": A, "units": len(units), "edges": sum(len(i) for _, i in units),
-               "depth": depth_of(n, units, nxt), "depth_unfolded": depth_of(n0, units0, nxt0),
-               "units_unfolded": len(units0), "edges_unfolded": sum(len(i) for _, i in units0),
-               "states": N, "result": line, "agrees": good, "seconds": round(time.perf_counter() - t0, 1)}
-        rows.append(row)
-        print(f"  A={A}: {row['units']:,} units, {row['edges']:,} edges, depth {row['depth']} "
-              f"(H_A: {row['units_unfolded']:,}, {row['edges_unfolded']:,}, depth {row['depth_unfolded']}); "
-              f"{line}", flush=True)
-    json.dump({"rows": rows, "all_agree": ok},
-              open(os.path.join(REPO, "paper", "runs", "paper_host_fold.json"), "w"), indent=1)
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_lev.py

@@ -1,121 +0,0 @@
-"""Lemma 2.6 on the host: the levelized map equals the netlist it came from.
-
-Lev(N) is asserted to compute, for every state, the next state that N computes.
-The netlist here is the one the serialization of the host denotes, evaluated
-gate by gate in topological order with no reference to the levelization, and the
-two are compared on uniformly random states, which lie off every trajectory of
-the constructor.
-
-The same states carry the structural facts the lemma asserts: every weight of
-every layer lies in {-1, 0, 1}, and every pre-activation is an integer, so the
-comparator has a margin of one half.
-"""
-import json
-import os
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-import torch
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def gate_by_gate(net, inputs, outputs, V):
-    """Evaluate the netlist directly: topological order, one gate at a time."""
-    gates = net.gates
-    indeg, cons = {}, {}
-    for g, (ins, _) in gates.items():
-        indeg[g] = len([s for s, _ in ins if s in gates])
-        for s, _ in ins:
-            cons.setdefault(s, []).append(g)
-    order = [g for g, d in indeg.items() if d == 0]
-    i = 0
-    while i < len(order):
-        for c in cons.get(order[i], []):
-            indeg[c] -= 1
-            if indeg[c] == 0:
-                order.append(c)
-        i += 1
-    assert len(order) == len(gates)
-
-    B = V.shape[0]
-    val = {"#0": torch.zeros(B), "#1": torch.ones(B)}
-    for k, name in enumerate(inputs):
-        val[name] = V[:, k]
-    for g in order:
-        ins, bias = gates[g]
-        acc = torch.full((B,), float(bias))
-        for s, w in ins:
-            acc = acc + w * val[s]
-        val[g] = (acc >= 0).float()
-    return torch.stack([val[o] for o in outputs], dim=1)
-
-
-def main() -> int:
-    from netlist_io import net_of_sigma
-    from selfrep import LevEvaluator, NetEvaluator, read_host
-
-    sigma = read_host()
-    net, inputs, outputs, _ = net_of_sigma(sigma)
-    L = LevEvaluator(sigma, device="cpu", dense=False)
-
-    gen = torch.Generator().manual_seed(20260910)
-    B = 96
-    V = (torch.rand(B, len(inputs), generator=gen) < 0.5).float()
-
-    direct = gate_by_gate(net, inputs, outputs, V)
-    levelled = L.step(V)
-    agree = bool((direct == levelled).all())
-    print(f"  netlist has {len(net.gates):,} gates on {len(inputs):,} state bits")
-    print(f"  gate-by-gate evaluation equals Lev(N_host) on {B} uniformly random "
-          f"states: {'yes' if agree else 'NO'}")
-    if not agree:
-        d = (direct != levelled).nonzero()
-        print("   first disagreements:", d[:5].tolist())
-
-    grouped = NetEvaluator(sigma, device="cpu").step(V)
-    agree_net = bool((direct == grouped).all())
-    print(f"  the evaluator that carries only the netlist's own predecessor "
-          f"entries agrees on the same states: {'yes' if agree_net else 'NO'}")
-
-    # The dense form: ternary weights, integer pre-activations, margin one half.
-    D = LevEvaluator(sigma, device="cpu", dense=True)
-    nonternary = [i for i, W in enumerate(D.W)
-                  if not set(torch.unique(W).tolist()) <= {-1.0, 0.0, 1.0}]
-    nonint = [i for i, b in enumerate(D.B) if not bool((b == b.round()).all())]
-    print(f"  every weight of all {len(D.W)} layers lies in {{-1,0,1}}: "
-          f"{'yes' if not nonternary else f'NO at {nonternary[:3]}'}")
-    print(f"  every bias is an integer: {'yes' if not nonint else f'NO at {nonint[:3]}'}")
-
-    y, worst, frac = V, float("inf"), 0.0
-    for W, b in zip(D.W, D.B):
-        pre = y @ W.T + b
-        worst = min(worst, float((pre + 0.5).abs().min()))
-        frac = max(frac, float((pre - pre.round()).abs().max()))
-        y = (pre >= 0).float()
-    same_dense = bool((y == levelled).all())
-    print(f"  dense stack agrees with the sparse evaluation on the same states: "
-          f"{'yes' if same_dense else 'NO'}")
-    print(f"  minimum distance of a pre-activation from -1/2 over all "
-          f"{len(D.W)} layers: {worst:.6f}")
-    print(f"  maximum distance of a pre-activation from an integer: {frac:.3e}")
-
-    ok = (agree and agree_net and same_dense and not nonternary
-          and not nonint and abs(worst - 0.5) < 1e-9)
-    json.dump({"states": B, "gates": len(net.gates), "agree": agree,
-               "agree_grouped": agree_net,
-               "dense_agree": same_dense, "nonternary_layers": len(nonternary),
-               "noninteger_bias_layers": len(nonint),
-               "min_margin": worst, "max_noninteger": frac},
-              open(runs_path("paper_lev.json"), "w"), indent=1)
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_optimal.py

@@ -1,153 +0,0 @@
-"""The length bound of the completeness lemma is optimal for the token format.
-
-A literal token covering c bytes occupies c + 1 bytes and a repeat token
-covering a run of c equal bytes occupies 2, so the shortest recipe for a given
-output is a shortest path over the positions of that output. The exact optimum
-is computed here by that recurrence and compared with |f| + ceil(|f|/127) + 1
-on strings with no two equal adjacent bytes, where no repeat token can cover
-more than one byte and the bound is therefore attained by every shortest
-recipe, and with the encoders of the artifact on arbitrary strings.
-"""
-import itertools
-import json
-import os
-import random
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from selfrep import describe, describe_literal, decode
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def bound(n: int) -> int:
-    return n + -(-n // 127) + 1
-
-
-def shortest(f: bytes) -> int:
-    """Length of a shortest r in R with delta(r) = f, by dynamic programming.
-
-    cost[i] is the least number of bytes needed to cover f[i:]; the END byte is
-    added once at the end. A literal token may carry 1..127 bytes at a cost of
-    one more than it carries; a repeat token carries 1..127 copies of one byte
-    at a cost of two.
-    """
-    n = len(f)
-    INF = float("inf")
-    cost = [INF] * (n + 1)
-    cost[n] = 0
-    for i in range(n - 1, -1, -1):
-        best = INF
-        for c in range(1, min(127, n - i) + 1):
-            v = cost[i + c] + c + 1                       # literal token
-            if v < best:
-                best = v
-        run = 0
-        while run < min(127, n - i) and f[i + run] == f[i]:
-            run += 1
-            v = cost[i + run] + 2                         # repeat token
-            if v < best:
-                best = v
-        cost[i] = best
-    return cost[0] + 1
-
-
-def run_free(f: bytes) -> bool:
-    return all(f[i] != f[i + 1] for i in range(len(f) - 1))
-
-
-def main() -> int:
-    out = {}
-    ok = True
-
-    # Exhaustive over ternary strings with no two equal adjacent bytes.
-    tested = 0
-    bad = []
-    for n in range(0, 11):
-        for t in itertools.product((0, 1, 2), repeat=n):
-            f = bytes(t)
-            if not run_free(f):
-                continue
-            tested += 1
-            s = shortest(f)
-            if s != bound(n) or len(describe_literal(f)) != bound(n):
-                bad.append(n)
-    print(f"  every ternary string of length at most 10 with no two equal "
-          f"adjacent bytes ({tested:,} of them): the shortest recipe has "
-          f"exactly |f| + ceil(|f|/127) + 1 bytes: "
-          f"{'yes' if not bad else f'NO at lengths {sorted(set(bad))[:5]}'}")
-    ok &= not bad
-    out["run_free_exhaustive"] = tested
-    out["run_free_failures"] = len(bad)
-
-    # Longer run-free strings over the full alphabet, including the lengths at
-    # which a further literal token becomes necessary.
-    rng = random.Random(4)
-    lens = [0, 1, 126, 127, 128, 253, 254, 255, 380, 381, 508, 509, 700]
-    lens += [rng.randrange(0, 900) for _ in range(120)]
-    lbad = []
-    for n in lens:
-        f = bytearray()
-        prev = -1
-        for _ in range(n):
-            c = rng.randrange(256)
-            while c == prev:
-                c = rng.randrange(256)
-            f.append(c)
-            prev = c
-        f = bytes(f)
-        if shortest(f) != bound(n) or len(describe_literal(f)) != bound(n):
-            lbad.append(n)
-    print(f"  {len(lens)} further run-free strings, lengths to 900 and at every "
-          f"multiple of 127: shortest recipe equals the bound: "
-          f"{'yes' if not lbad else f'NO at {lbad[:5]}'}")
-    ok &= not lbad
-    out["run_free_sampled"] = len(lens)
-    out["run_free_sampled_failures"] = len(lbad)
-
-    # On arbitrary strings the bound is an upper bound only; record how far the
-    # encoder of the artifact is from the optimum.
-    gaps = []
-    abad = 0
-    for _ in range(300):
-        n = rng.randrange(0, 600)
-        alpha = rng.choice([1, 2, 3, 9, 256])
-        f = bytes(rng.randrange(alpha) for _ in range(n))
-        s = shortest(f)
-        d = len(describe(f))
-        if decode(describe(f)) != f or d < s or d > bound(n):
-            abad += 1
-        gaps.append(d - s)
-    print(f"  300 arbitrary strings: describe is never shorter than the optimum "
-          f"and never longer than the bound: {'yes' if abad == 0 else 'NO'}; "
-          f"excess over the optimum: max {max(gaps)}, mean {sum(gaps)/len(gaps):.2f}")
-    ok &= abad == 0
-    out["arbitrary_strings"] = len(gaps)
-    out["arbitrary_failures"] = abad
-    out["describe_excess_max"] = max(gaps)
-    out["describe_excess_mean"] = sum(gaps) / len(gaps)
-
-    # The serialization of the host is not run-free, so its optimum is shorter.
-    from selfrep import HOST_PATH
-    sigma = open(HOST_PATH, "rb").read()
-    s = shortest(sigma)
-    print(f"  sigma(N_host): {len(sigma):,} bytes; bound {bound(len(sigma)):,}, "
-          f"describe {len(describe(sigma)):,}, shortest recipe {s:,}")
-    out["sigma_bytes"] = len(sigma)
-    out["sigma_bound"] = bound(len(sigma))
-    out["sigma_describe"] = len(describe(sigma))
-    out["sigma_shortest"] = s
-    ok &= s <= len(describe(sigma)) <= bound(len(sigma))
-
-    json.dump(out, open(runs_path("paper_optimal.json"), "w"), indent=1)
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_rocq.py

@@ -1,67 +0,0 @@
-"""Build the Rocq development, print the assumptions of its main theorems, and compare
-the extracted netlist with the generator's.
-
-The development in rocq/ proves that the two-head netlist computes the step of the
-machine from every state at every size, that the organism builds every record image
-from any description of it, and that it reproduces in every generation; it also
-evaluates three generations in the kernel. Run under an environment that provides
-rocq and ocamlfind, for instance `eval $(opam env)`:
-
-    python src/check_rocq.py
-"""
-import json
-import os
-import re
-import shutil
-import subprocess
-import sys
-import time
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-ROCQ = os.path.join(REPO, 'rocq')
-RECORD = os.path.join(REPO, 'paper', 'runs', 'paper_rocq.json')
-
-
-def main():
-    for tool in ('rocq', 'make', 'ocamlfind'):
-        if shutil.which(tool) is None:
-            print(f'{tool} not found on PATH')
-            return 1
-    version = subprocess.run(['rocq', '--version'], capture_output=True, text=True).stdout.strip()
-    t0 = time.time()
-    subprocess.run(['rocq', 'makefile', '-f', '_CoqProject', '-o', 'Makefile'], cwd=ROCQ, check=True)
-    subprocess.run(['make', 'clean'], cwd=ROCQ, check=True, capture_output=True)
-    jobs = str(os.cpu_count() or 1)
-    if subprocess.run(['make', '-j', jobs], cwd=ROCQ).returncode != 0:
-        print('the build failed')
-        return 1
-    build = time.time() - t0
-    out = subprocess.run(['rocq', 'compile', '-R', '.', 'TH', 'Assumptions.v'], cwd=ROCQ,
-                         capture_output=True, text=True)
-    for f in os.listdir(ROCQ):
-        if f.startswith('Assumptions.') and f != 'Assumptions.v' or f == '.Assumptions.aux':
-            os.remove(os.path.join(ROCQ, f))
-    if out.returncode != 0:
-        print(out.stdout, out.stderr)
-        return 1
-    names = re.findall(r'^Print Assumptions (\S+)\.$', open(os.path.join(ROCQ, 'Assumptions.v')).read(), re.M)
-    lines = [l.strip() for l in out.stdout.splitlines() if l.strip()]
-    if len(lines) != len(names) or any(l != 'Closed under the global context' for l in lines):
-        print(out.stdout)
-        return 1
-    ext = subprocess.run([sys.executable, os.path.join(REPO, 'src', 'twohead_net.py'), 'extract'],
-                         capture_output=True, text=True)
-    identical = ext.returncode == 0 and '"identical": true' in ext.stdout
-    files = [l for l in open(os.path.join(ROCQ, '_CoqProject')).read().split() if l.endswith('.v')]
-    res = dict(rocq=version.splitlines()[0], files=len(files),
-               build_seconds=round(build, 1), theorems={n: 'closed' for n in names},
-               extraction_identical=identical)
-    rec = json.load(open(RECORD)) if os.path.exists(RECORD) else {}
-    rec.update(res)
-    json.dump(rec, open(RECORD, 'w'), indent=1)
-    print(json.dumps(res, indent=1))
-    return 0 if identical else 1
-
-
-if __name__ == '__main__':
-    sys.exit(main())

src/check_sigma.py

@@ -1,89 +0,0 @@
-"""The serialization sigma of the ordered host netlist, written two ways.
-
-Units are stored in the order the family builds them, every unit after its
-predecessors; tensor entries are ordered by (element type, name); the metadata
-object is written first with its keys in the fixed order (machine,
-weight_quantization, signal_registry, io); the JSON uses compact separators and
-is padded with spaces so the tensor data begins at an eight-byte boundary.
-Rebuilding the host from source reproduces its distributed encoding byte for
-byte, the vectorized writer host_family.sigma produces the same bytes without
-building the netlist, and the netlist the encoding denotes serializes back to
-the same bytes.
-"""
-import json
-import os
-import struct
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-import torch
-
-from netlist_io import net_of_sigma, sigma_of_net
-from selfrep import HOST_PATH, STATE_LAYOUT, IO_CELLS, host_netlist, sigma_host
-
-_DTORD = {"F64": 0, "F32": 1, "F16": 2, "I64": 3, "I32": 4, "I16": 5, "I8": 6,
-          "U8": 7, "BOOL": 8}
-
-
-def resigma(data: bytes) -> bytes:
-    """Serialize the netlist that `data` denotes."""
-    net, inputs, outputs, meta = net_of_sigma(data)
-    return sigma_of_net(net, inputs, outputs, meta["machine"],
-                        json.loads(meta["signal_registry"]),
-                        json.loads(meta["io"]))
-
-
-def main() -> int:
-    rebuilt = sigma_host()
-    dist = open(HOST_PATH, "rb").read()
-    same = rebuilt == dist
-    n = struct.unpack("<Q", dist[:8])[0]
-    h = json.loads(dist[8:8 + n])
-    meta = h.pop("__metadata__")
-    order = list(h)
-    by_dtype_name = order == sorted(order, key=lambda k: (_DTORD[h[k]["dtype"]], k))
-    signed_int = all(h[k]["dtype"] in ("I8", "I16", "I32", "I64") for k in order)
-    print(f"rebuild from source equals the distributed encoding byte for byte: {same}")
-    print(f"  bytes {len(dist):,}   header {n:,}   tensor entries {len(order)}")
-    print(f"  metadata keys in order: {list(meta)}")
-    print(f"  tensor entries ordered by (element type, name): {by_dtype_name}")
-    print(f"  every element type is a signed integer type: {signed_int}")
-    print(f"  data begins at offset {8+n}, which is 8-aligned: {(8+n) % 8 == 0}")
-    print(f"  header padded with {len(dist[8:8+n]) - len(dist[8:8+n].rstrip(b' '))} spaces")
-
-    again = sigma_host()
-    print(f"  two independent builds agree: {again == rebuilt}")
-    from host_family import sigma as family_sigma
-    vec = family_sigma(8) == dist
-    print(f"  the vectorized writer produces the same bytes: {vec}")
-
-    # sigma(sigma^-1(s)) = s on the image: the encoding determines the netlist
-    # and the netlist determines the encoding.
-    round_trip = resigma(dist) == dist
-    print(f"  the netlist the encoding denotes serializes back to it: {round_trip}")
-
-    net, inputs, outputs = host_netlist()
-    built, _, _, _ = net_of_sigma(dist)
-    entries = sum(len(i) for i, _ in built.gates.values())
-    print(f"  {len(built.gates):,} units and {entries:,} predecessor entries "
-          f"recovered from the file alone, on {len(inputs):,} state bits")
-
-    # the netlist recovered from the file computes the transition the source
-    # netlist computes, on states no trajectory visits
-    from check_lev import gate_by_gate
-    gen = torch.Generator().manual_seed(41)
-    V = (torch.rand(64, len(inputs), generator=gen) < 0.5).float()
-    src = gate_by_gate(net, inputs, outputs, V)
-    rec_net, rec_in, rec_out, _ = net_of_sigma(dist)
-    rec = gate_by_gate(rec_net, rec_in, rec_out, V)
-    agree = bool((src == rec).all())
-    print(f"  it computes the transition of the source netlist on 64 uniformly "
-          f"random states: {agree}")
-
-    ok = (same and again == rebuilt and vec and round_trip and agree and by_dtype_name
-          and signed_int)
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_steps.py

@@ -1,169 +0,0 @@
-"""Closed forms for the number of steps of the constructor and of the copier.
-
-Reading a recipe token by token, the decoding loop of P spends a fixed number
-of steps on the token's tag and a fixed number on each byte it contributes to
-the output, so the whole run is a sum over the token census:
-
-    steps(P, r) = 5 f_lit + 4 f_rep + 7 L + 9 R + 8,
-
-where L and R count the literal and repeat tokens, f_lit and f_rep the bytes
-each kind contributes, and the last term is the end token together with the
-halt instruction. The copying phase of P* costs six steps per tape byte and
-two to detect the end of tape. The formulas are compared here against the
-reference run on the recipes of the paper and on random recipes.
-"""
-import json
-import os
-import random
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from selfrep import (HOST_PATH, M_P, M_STAR, describe, describe_literal, decode,
-                     run_reference, tau_star, Tape, HALT_PC)
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def census(r: bytes):
-    """(literal tokens, repeat tokens, bytes from each) of a recipe."""
-    i = 0
-    lit = rep = f_lit = f_rep = 0
-    while True:
-        t = r[i]
-        i += 1
-        if t == 0:
-            return lit, rep, f_lit, f_rep
-        if t <= 127:
-            lit += 1
-            f_lit += t
-            i += t
-        else:
-            rep += 1
-            f_rep += 256 - t
-            i += 1
-
-
-def steps_P(r: bytes) -> int:
-    """Closed form for the run of the constructor P on a recipe."""
-    lit, rep, f_lit, f_rep = census(r)
-    return 5 * f_lit + 4 * f_rep + 7 * lit + 9 * rep + 8
-
-
-def steps_P_star(tau: bytes):
-    """Closed form for the three phases of P* on its own description tape."""
-    lit, rep, f_lit, f_rep = census(tau)
-    a = 5 * f_lit + 4 * f_rep + 7 * lit + 9 * rep + 7
-    return {"A": a, "R": 1, "B": 6 * len(tau) + 2}
-
-
-def upper_bound(r: bytes) -> int:
-    """5|delta(r)| + 9k + 8 with k the number of tokens, k <= (|r|-1)/2."""
-    lit, rep, f_lit, f_rep = census(r)
-    return 5 * (f_lit + f_rep) + 9 * (lit + rep) + 8
-
-
-def coarse_bound(r: bytes) -> int:
-    return 5 * len(decode(r)) + (9 * (len(r) - 1)) // 2 + 8
-
-
-def phase_split(mem0, tau: bytes):
-    mem = list(mem0)
-    dev = Tape(tau)
-    pc = 0
-    counts = {"A": 0, "R": 0, "B": 0}
-    while pc != HALT_PC:
-        counts["A" if pc < 3 * 20 else ("R" if pc == 3 * 20 else "B")] += 1
-        A = mem[pc]
-        B = mem[(pc + 1) & 0xFF]
-        C = mem[(pc + 2) & 0xFF]
-        r = (mem[B] - mem[A]) & 0xFF
-        mem[B] = r
-        pc = C if (r == 0 or r >= 0x80) else (pc + 3) & 0xFF
-        dev.apply(mem)
-    return counts
-
-
-def main() -> int:
-    out = {}
-    ok = True
-    sigma = open(HOST_PATH, "rb").read()
-
-    named = [("r_H = describe(sigma(N_host))", describe(sigma)),
-             ("the all-literal encoding of sigma(N_host)", describe_literal(sigma)),
-             ("tau* (the self-reproducing tape)", tau_star(sigma, M_STAR))]
-    rows = []
-    for label, r in named:
-        _, n = run_reference(M_P, r)
-        pred = steps_P(r)
-        rows.append({"tape": label, "recipe_bytes": len(r), "output_bytes":
-                     len(decode(r)), "steps": n, "closed_form": pred,
-                     "agrees": n == pred, "upper": upper_bound(r),
-                     "coarse": coarse_bound(r)})
-        print(f"  {label}: {n:,} steps, closed form {pred:,}, "
-              f"{'agree' if n == pred else 'DISAGREE'}; "
-              f"bound 5|f|+9k+8 = {upper_bound(r):,}", flush=True)
-        ok &= n == pred and n <= upper_bound(r) <= coarse_bound(r)
-    out["named"] = rows
-
-    # random recipes: both encoders, and strings built to force each token kind
-    rng = random.Random(1009)
-    bad = 0
-    tested = 0
-    for _ in range(400):
-        n = rng.randrange(0, 700)
-        alpha = rng.choice([1, 2, 3, 17, 256])
-        f = bytes(rng.randrange(alpha) for _ in range(n))
-        for enc in (describe, describe_literal):
-            r = enc(f)
-            _, s = run_reference(M_P, r)
-            tested += 1
-            if s != steps_P(r) or s > upper_bound(r) or upper_bound(r) > coarse_bound(r):
-                bad += 1
-    print(f"  {tested:,} random runs of P: closed form exact and within the "
-          f"bound on every one: {'yes' if bad == 0 else f'NO ({bad})'}", flush=True)
-    ok &= bad == 0
-    out["random_runs"] = tested
-    out["random_failures"] = bad
-
-    # the three phases of P*
-    tau = tau_star(sigma, M_STAR)
-    measured = phase_split(M_STAR, tau)
-    pred = steps_P_star(tau)
-    agree = measured == pred
-    print(f"  P* phases measured {measured}, closed form {pred}: "
-          f"{'agree' if agree else 'DISAGREE'}", flush=True)
-    print(f"  total {sum(measured.values()):,} = {sum(pred.values()):,}", flush=True)
-    ok &= agree
-    out["phases_measured"] = measured
-    out["phases_closed_form"] = pred
-    out["total"] = sum(pred.values())
-
-    # phase B is six steps per tape byte and two more, over recipes of every
-    # shape; P* is run only on recipes, on which it halts
-    bbad = 0
-    probes = 0
-    for _ in range(40):
-        for enc in (describe, describe_literal):
-            probe = enc(bytes(rng.randrange(rng.choice([2, 4, 256]))
-                              for _ in range(rng.randrange(0, 200))))
-            got = phase_split(M_STAR, probe)
-            probes += 1
-            if got != steps_P_star(probe):
-                bbad += 1
-    print(f"  phase B = 6|tau| + 2 and phase R = 1 on {probes} further recipes: "
-          f"{'yes' if bbad == 0 else f'NO ({bbad})'}", flush=True)
-    ok &= bbad == 0
-    out["phase_b_failures"] = bbad
-
-    json.dump(out, open(runs_path("paper_steps.json"), "w"), indent=1)
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/check_ternarity.py

@@ -1,142 +0,0 @@
-"""The branch predicate separates ternary weights from integer weights.
-
-The host decides a branch from the two's-complement result r by the depth-two
-cell OR(r_7, z(r)). With integer weights the same predicate is one unit,
-H(128 r_7 - sum_{i<7} 2^i r_i), so the depth-two cell is where the restriction
-to {-1,0,1} is paid for. Both halves are checked here: every ternary unit on
-the eight result bits is enumerated and none computes the predicate, and the
-single large-weight unit is evaluated on all 256 results.
-"""
-import itertools
-import json
-import os
-import sys
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-import torch
-
-REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-
-def runs_path(name: str) -> str:
-    d = os.path.join(REPO, "paper", "runs")
-    os.makedirs(d, exist_ok=True)
-    return os.path.join(d, name)
-
-
-def predicate(n: int):
-    """[r <= 0] for r read in two's complement on `n` bits, as a 2^n vector."""
-    rows = []
-    for v in range(1 << n):
-        two_c = v - (1 << n) if v >> (n - 1) else v
-        rows.append(1 if two_c <= 0 else 0)
-    return torch.tensor(rows, dtype=torch.long)
-
-
-def bitmatrix(n: int):
-    """Row v holds the bits r_0 .. r_{n-1} of v, least significant first."""
-    return torch.tensor([[(v >> i) & 1 for i in range(n)] for v in range(1 << n)],
-                        dtype=torch.long)
-
-
-def ternary_units_computing(n: int, target, bias_range):
-    """Every (w, b) in {-1,0,1}^n x bias_range whose unit computes `target`."""
-    X = bitmatrix(n)
-    found = []
-    total = 0
-    for w in itertools.product((-1, 0, 1), repeat=n):
-        pre = X @ torch.tensor(w, dtype=torch.long)
-        for b in bias_range:
-            total += 1
-            if bool(((pre + b >= 0).long() == target).all()):
-                found.append((w, b))
-    return found, total
-
-
-def main() -> int:
-    out = {}
-    ok = True
-
-    # The predicate is a threshold function of the eight result bits, realized
-    # by one unit whose weights are the positional values of the bits.
-    n = 8
-    target = predicate(n)
-    X = bitmatrix(n)
-    big = torch.tensor([-(1 << i) for i in range(n - 1)] + [1 << (n - 1)],
-                       dtype=torch.long)
-    exact = bool(((X @ big >= 0).long() == target).all())
-    print(f"  one integer-weight unit with weights "
-          f"(-1,-2,-4,-8,-16,-32,-64,+128) and bias 0 computes [r <= 0] on all "
-          f"{1 << n} results: {'yes' if exact else 'NO'}")
-    ok &= exact
-    out["integer_unit_exact"] = exact
-    out["integer_unit_max_weight"] = int(big.abs().max())
-
-    # No ternary unit does, for any integer bias. A bias outside [-n, n] makes
-    # the unit constant, so the sweep below is exhaustive over all biases.
-    bias_range = range(-(n + 2), n + 3)
-    found, total = ternary_units_computing(n, target, bias_range)
-    print(f"  ternary units on the eight result bits enumerated: {total:,} "
-          f"(all {3 ** n:,} weight vectors, biases {bias_range.start} to "
-          f"{bias_range.stop - 1})")
-    print(f"  ternary units computing [r <= 0]: {len(found)}"
-          f"{'  (none, as the proposition asserts)' if not found else f'  {found[:3]}'}")
-    ok &= not found
-    out["ternary_units_enumerated"] = total
-    out["ternary_units_computing_predicate"] = len(found)
-    # A unit with p weights +1 and q weights -1 is constant unless
-    # -p <= b <= q - 1; those biases lie inside the swept range.
-    nonconst = sum(sum(1 for x in w if x) for w in itertools.product((-1, 0, 1), repeat=n))
-    print(f"  of these, {nonconst:,} are not constant, and none of them computes "
-          f"[r <= 0]")
-    out["nonconstant_ternary_units"] = nonconst
-
-    # The separation begins at three bits: on two bits the predicate is ternary.
-    firstfail = None
-    widths = {}
-    for m in range(2, 9):
-        f, _ = ternary_units_computing(m, predicate(m), range(-(m + 2), m + 3))
-        widths[m] = len(f)
-        if not f and firstfail is None:
-            firstfail = m
-    print(f"  ternary realizations by width: {widths}; the predicate stops "
-          f"being a ternary threshold function at {firstfail} bits")
-    out["ternary_realizations_by_width"] = widths
-    out["first_width_without_ternary_unit"] = firstfail
-    ok &= firstfail == 3
-
-    # Depth two suffices, by the cell the host uses.
-    z = (X.sum(dim=1) == 0).long()
-    leq = ((X[:, n - 1] + z) >= 1).long()
-    two = bool((leq == target).all())
-    print(f"  the depth-two cell OR(r_7, z(r)) of the host computes it on all "
-          f"{1 << n} results: {'yes' if two else 'NO'}")
-    ok &= two
-    out["depth_two_cell_exact"] = two
-
-    # The 256-way address decoder is not an instance of the same exchange: it
-    # is one ternary unit already.
-    from matrix8 import Net
-    net = Net()
-    bits = [f"a{i}" for i in range(8)]
-    net.DECODE("sel", bits, 0xA7)
-    ins, bias = net.gates["sel"]
-    dec_ternary = all(w in (-1, 0, 1) for _, w in ins)
-    A = bitmatrix(8)
-    # DECODE reads its bits most significant first
-    w = torch.tensor([wt for _, wt in ins], dtype=torch.long)
-    pre = A.flip(1) @ w + bias
-    hit = (pre >= 0).long()
-    dec_exact = bool((hit == (torch.arange(256) == 0xA7).long()).all())
-    print(f"  the address decoder of the memory is one ternary unit of fan-in "
-          f"eight and fires on exactly one address: "
-          f"{'yes' if dec_ternary and dec_exact else 'NO'}")
-    ok &= dec_ternary and dec_exact
-    out["decoder_is_one_ternary_unit"] = dec_ternary and dec_exact
-
-    json.dump(out, open(runs_path("paper_ternarity.json"), "w"), indent=1)
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

src/constructor8.py

@@ -1,580 +0,0 @@
-"""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, not 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.dirname(os.path.abspath(__file__)))  # repo root; this module lives in src/
-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)
-# =============================================================================
-
-from host_netlist import subleq_state_names, build_subleq_step_net
-
-
-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())

src/eval.py

@@ -1,30 +1,15 @@
-"""
-Unified Evaluation Suite for 8-bit Threshold Computer
-======================================================
-GPU-batched evaluation with per-circuit reporting.
-Includes CPU runtime for threshold-weight execution.
-
-Usage:
-    python eval.py                    # Run circuit evaluation
-    python eval.py --device cpu       # CPU mode
-    python eval.py --pop_size 1000    # Population mode for evolution
-    python eval.py --cpu-test         # Run CPU smoke test
-
-The single gate-routed CPU runtime is GenericThresholdCPU in eval_all.py
-(manifest-sized); the pure-Python reference (CPUState / ref_step) lives here
-for cross-checks.
-
-API (for prune_weights.py):
-    from eval import load_model, create_population, BatchedFitnessEvaluator
-"""
+"""Evaluates the threshold computers: the fitness suite, every variant, and the CPU programs."""
+from __future__ import annotations
 
 import argparse
 import json
 import os
+import sys
 import time
 from collections import defaultdict
 from dataclasses import dataclass, field
-from typing import Callable, Dict, List, Optional, Tuple
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Tuple, Any
 
 import torch
 from safetensors import safe_open
@@ -71,11 +56,7 @@ def load_metadata(path: str = MODEL_PATH) -> Dict:
 
 
 def get_manifest(tensors: Dict[str, torch.Tensor]) -> Dict[str, int]:
-    """Extract manifest values from tensors.
-
-    Returns dict with data_bits, addr_bits, memory_bytes, version.
-    Defaults to 8-bit data, 16-bit addr for legacy models.
-    """
+    """Extract manifest values from tensors."""
     return {
         'data_bits': int(tensors.get('manifest.data_bits', torch.tensor([8.0])).item()),
         'addr_bits': int(tensors.get('manifest.addr_bits',
@@ -102,16 +83,25 @@ def create_population(
 # =============================================================================
 
 FLAG_NAMES = ["Z", "N", "C", "V"]
+
 CTRL_NAMES = ["HALT", "MEM_WE", "MEM_RE", "RESERVED"]
 
 PC_BITS = 16
+
 IR_BITS = 16
+
 REG_BITS = 8
+
 REG_COUNT = 4
+
 FLAG_BITS = 4
+
 SP_BITS = 16
+
 CTRL_BITS = 4
+
 MEM_BYTES = 65536
+
 MEM_BITS = MEM_BYTES * 8
 
 STATE_BITS = PC_BITS + IR_BITS + (REG_BITS * REG_COUNT) + FLAG_BITS + SP_BITS + CTRL_BITS + MEM_BITS
@@ -405,18 +395,9 @@ def _fill_smoke_program(mem: List[int]) -> None:
 
 
 def run_smoke_test() -> int:
-    """Smoke test through the single gate-routed CPU runtime
-    (GenericThresholdCPU), cross-checked against the pure-Python reference:
-
-    1. LOAD 5, LOAD 7, ADD, STORE       -> MEM[0x0102] = 12
-    2. LOAD 2, LOAD 131, MUL, STORE     -> MEM[0x0105] = (2*131) & 0xFF = 6
-    3. Countdown loop 3+2+1 via SUB/JNZ -> MEM[0x0109] = 6
-
-    Runs on the 1 KB variant so the threshold pass finishes in seconds; the
-    reference runs at 64 KB in pure Python.
-    """
+    """Programs through the gate-routed CPU runtime against the Python reference."""
     import os
-    from eval_all import GenericThresholdCPU   # lazy: avoids eval<->eval_all cycle
+    pass   # lazy: avoids eval<->eval_all cycle
 
     expected = {0x0102: 12, 0x0105: 6, 0x0109: 6}
 
@@ -461,18 +442,7 @@ def run_smoke_test() -> int:
 # =============================================================================
 
 class NetlistEvaluator:
-    """Evaluate a self-contained circuit from its shipped wiring metadata.
-
-    The gate graph is built from the .inputs tensors and the header signal
-    registry — the same artifacts safetensors2verilog consumes — so a test
-    driven through this class proves the file itself encodes the circuit,
-    with no wiring knowledge living in Python.
-
-    External signals are names starting with '$' (plus the constants #0/#1);
-    the caller binds them per evaluation. Gate outputs are published under
-    their full gate names. Evaluation is batched over test vectors and,
-    for population dicts, over population slots.
-    """
+    """Evaluate a self-contained circuit from its shipped wiring metadata."""
 
     def __init__(self, tensors: Dict[str, torch.Tensor],
                  signal_registry: Dict[str, str], prefix: str,
@@ -578,8 +548,7 @@ class NetlistEvaluator:
         return sorted(out)
 
     def run(self, external: Dict[str, torch.Tensor]) -> Dict[str, torch.Tensor]:
-        """Evaluate the circuit. Each external is a [num_tests] tensor (or a
-        scalar); every returned gate output is [num_tests, pop_size]."""
+        """Evaluate the circuit."""
         first = next(iter(external.values()))
         if not torch.is_tensor(first):
             num_tests = 1
@@ -635,8 +604,7 @@ class _SlotView:
 
 
 def float_bits_to_value(word: int, exp_bits: int, frac_bits: int) -> float:
-    """Decode an IEEE 754 word to a Python float. float64 represents every
-    float16/float32 value exactly, so the oracle comparisons are exact."""
+    """Decode an IEEE 754 word to a Python float, exactly."""
     sign = (word >> (exp_bits + frac_bits)) & 1
     exp = (word >> frac_bits) & ((1 << exp_bits) - 1)
     frac = word & ((1 << frac_bits) - 1)
@@ -653,8 +621,7 @@ def float_bits_to_value(word: int, exp_bits: int, frac_bits: int) -> float:
 
 
 def float_test_words(exp_bits: int, frac_bits: int) -> Tuple[List[int], List[int]]:
-    """Directed IEEE edge encodings (every category, both signs) plus seeded
-    random words for a family."""
+    """Directed IEEE edge encodings (every category, both signs) plus seeded random words for a family."""
     import random
     E, F = exp_bits, frac_bits
     emax = (1 << E) - 1
@@ -684,10 +651,7 @@ def float_test_words(exp_bits: int, frac_bits: int) -> Tuple[List[int], List[int
 
 
 def float_mul_oracle(aw: int, bw: int, exp_bits: int, frac_bits: int) -> int:
-    """Expected product word under the documented contract: exact IEEE
-    specials (NaN, infinities, signed zeros), subnormal operands and
-    gradual-underflow subnormal results, round-to-nearest-even mantissa.
-    Pure integer arithmetic, so exact."""
+    """The expected IEEE product word: exact specials, subnormals, round to nearest even."""
     E, F = exp_bits, frac_bits
     emax = (1 << E) - 1
     fmask = (1 << F) - 1
@@ -752,10 +716,7 @@ def float_mul_oracle(aw: int, bw: int, exp_bits: int, frac_bits: int) -> int:
 
 
 def float_div_oracle(aw: int, bw: int, exp_bits: int, frac_bits: int) -> int:
-    """Expected quotient word under the documented contract: exact IEEE
-    specials (NaN, infinities, x/0 -> inf, 0/0 and inf/inf -> NaN, signed
-    zeros), subnormal operands and gradual-underflow subnormal results,
-    round-to-nearest-even mantissa."""
+    """The expected IEEE quotient word: exact specials, subnormals, round to nearest even."""
     E, F = exp_bits, frac_bits
     emax = (1 << E) - 1
     fmask = (1 << F) - 1
@@ -817,10 +778,7 @@ def float_div_oracle(aw: int, bw: int, exp_bits: int, frac_bits: int) -> int:
 
 
 def float_fma_oracle(aw: int, bw: int, cw: int, exp_bits: int, frac_bits: int) -> int:
-    """Expected word for round(a*b + c) with a SINGLE rounding: exact IEEE
-    specials (NaN, infinities, inf*0 and inf-inf -> NaN, signed zeros, exact
-    cancellation -> +0), subnormal operands and gradual-underflow results,
-    round-to-nearest-even. Pure integer arithmetic, so exact."""
+    """The expected word of round(a*b + c), rounded once."""
     E, F = exp_bits, frac_bits
     emax = (1 << E) - 1
     fmask = (1 << F) - 1
@@ -910,11 +868,7 @@ def float_fma_oracle(aw: int, bw: int, cw: int, exp_bits: int, frac_bits: int) -
 
 
 def float_add_oracle(aw: int, bw: int, exp_bits: int, frac_bits: int) -> int:
-    """Expected sum word under the documented contract: exact IEEE specials
-    (NaN, infinities, opposite-sign infinities -> NaN, signed zeros, exact
-    cancellation -> +0), subnormal operands and gradual-underflow subnormal
-    results, round-to-nearest-even mantissa. A zero operand passes the other
-    through verbatim. Pure integer arithmetic, so exact."""
+    """The expected IEEE sum word: exact specials, subnormals, round to nearest even."""
     E, F = exp_bits, frac_bits
     emax = (1 << E) - 1
     fmask = (1 << F) - 1
@@ -998,10 +952,7 @@ def float_add_oracle(aw: int, bw: int, exp_bits: int, frac_bits: int) -> int:
 # =============================================================================
 
 class BatchedFitnessEvaluator:
-    """
-    GPU-batched fitness evaluator with per-circuit reporting.
-    Tests all circuits comprehensively.
-    """
+    """GPU-batched fitness evaluator with per-circuit reporting."""
 
     def __init__(self, device: str = 'cuda', model_path: str = MODEL_PATH, tensors: Dict[str, torch.Tensor] = None):
         self.device = device
@@ -1263,14 +1214,7 @@ class BatchedFitnessEvaluator:
     # =========================================================================
 
     def _eval_xor(self, pop: Dict, prefix: str, a: torch.Tensor, b: torch.Tensor) -> torch.Tensor:
-        """Evaluate XOR gate with or/nand decomposition.
-
-        Args:
-            a, b: Tensors of shape [num_tests] or [num_tests, pop_size]
-
-        Returns:
-            Tensor of shape [num_tests, pop_size]
-        """
+        """Evaluate XOR gate with or/nand decomposition."""
         pop_size = next(iter(pop.values())).shape[0]
 
         # Ensure inputs are [num_tests, pop_size]
@@ -1300,14 +1244,7 @@ class BatchedFitnessEvaluator:
 
     def _eval_single_fa(self, pop: Dict, prefix: str,
                         a: torch.Tensor, b: torch.Tensor, cin: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
-        """Evaluate single full adder.
-
-        Args:
-            a, b, cin: Tensors of shape [num_tests] or [num_tests, pop_size]
-
-        Returns:
-            sum_out, cout: Both of shape [num_tests, pop_size]
-        """
+        """Evaluate single full adder."""
         pop_size = next(iter(pop.values())).shape[0]
 
         # Ensure inputs are [num_tests, pop_size]
@@ -1768,11 +1705,7 @@ class BatchedFitnessEvaluator:
         a_bits_2d: torch.Tensor,
         b_bits_2d: torch.Tensor,
     ) -> Dict[str, torch.Tensor]:
-        """Walk the ternary bit-cascade comparator generated by
-        build.add_bit_cascade_compare. Returns a dict with gt/lt/ge/le/eq each of
-        shape [num_tests, pop_size]. a_bits_2d, b_bits_2d are [num_tests, bits]
-        MSB-first.
-        """
+        """Walk the ternary bit-cascade comparator generated by build.add_bit_cascade_compare."""
         pop_size = next(iter(pop.values())).shape[0]
 
         # Per-bit gt, lt, eq
@@ -2469,12 +2402,7 @@ class BatchedFitnessEvaluator:
     # =========================================================================
 
     def _test_modular(self, pop: Dict, mod: int, debug: bool) -> Tuple[torch.Tensor, int]:
-        """Test modular divisibility circuit.
-
-        Two structures: mod 3/5/6/7/9/10/11/12 use bit-cascade equality
-        per multiple of N (`{prefix}.eq.k{k}.*` + final OR at `{prefix}`).
-        mod 2/4/8 use a single-layer ternary detector at `{prefix}` directly.
-        """
+        """Test modular divisibility circuit."""
         pop_size = next(iter(pop.values())).shape[0]
         prefix = f'modular.mod{mod}'
 
@@ -3041,15 +2969,7 @@ class BatchedFitnessEvaluator:
         return scores, total
 
     def _test_priority_encoder_nbits(self, pop: Dict, bits: int, debug: bool) -> Tuple[torch.Tensor, int]:
-        """Test N-bit priority encoder (find highest set bit).
-
-        The priority encoder is a multi-layer circuit:
-        1. any_higher{pos}: OR of bits 0 to pos-1 (all higher-priority positions)
-        2. is_highest{0}: bit[0] directly (MSB is always highest if set)
-        3. is_highest{pos}: bit[pos] AND NOT(any_higher{pos}) for pos > 0
-        4. out{bit}: OR of is_highest{pos} for all pos where (pos >> bit) & 1
-        5. valid: OR of all input bits
-        """
+        """Test N-bit priority encoder (find highest set bit)."""
         import math
         pop_size = next(iter(pop.values())).shape[0]
         scores = torch.zeros(pop_size, device=self.device)
@@ -4013,8 +3933,7 @@ class BatchedFitnessEvaluator:
 
     def _test_float_unpack_pack(self, pop: Dict, family: str, word_bits: int,
                                 debug: bool) -> Tuple[torch.Tensor, int]:
-        """Functionally test the unpack/pack identity buffers: every bit gate
-        must reproduce its binary input (0 -> 0, 1 -> 1)."""
+        """Each unpack/pack identity buffer reproduces its input bit."""
         pop_size = next(iter(pop.values())).shape[0]
         scores = torch.zeros(pop_size, device=self.device)
         total = 0
@@ -4047,9 +3966,7 @@ class BatchedFitnessEvaluator:
 
     def _test_float_classify(self, pop: Dict, family: str, exp_bits: int,
                              frac_bits: int, debug: bool) -> Tuple[torch.Tensor, int]:
-        """Functionally test the classify subcircuit: the exponent/fraction
-        field predicates and the is_zero / is_subnormal / is_inf / is_nan AND
-        gates, against IEEE 754 categories over edge-case encodings."""
+        """The classify subcircuit against the IEEE 754 categories on edge encodings."""
         pop_size = next(iter(pop.values())).shape[0]
         scores = torch.zeros(pop_size, device=self.device)
         total = 0
@@ -4136,10 +4053,7 @@ class BatchedFitnessEvaluator:
 
     def _test_float_cmp_composed(self, pop: Dict, family: str, exp_bits: int,
                                  frac_bits: int, debug: bool) -> Tuple[torch.Tensor, int]:
-        """Composed IEEE comparison test driven entirely by the shipped
-        wiring: the netlist is reconstructed from the .inputs metadata and
-        evaluated end to end, then checked against exact IEEE semantics
-        (NaN unordered, +0 == -0, subnormals ordered, mixed signs)."""
+        """The IEEE comparison rebuilt from the shipped wiring against exact IEEE semantics."""
         pop_size = next(iter(pop.values())).shape[0]
         scores = torch.zeros(pop_size, device=self.device)
         total = 0
@@ -4211,10 +4125,7 @@ class BatchedFitnessEvaluator:
     def _test_float_arith_composed(self, pop: Dict, family: str, op: str,
                                    oracle, exp_bits: int, frac_bits: int,
                                    debug: bool) -> Tuple[torch.Tensor, int]:
-        """Composed arithmetic test for a self-contained float pipeline: the
-        netlist is rebuilt from the .inputs metadata, evaluated end to end
-        over IEEE edge-case and random operand pairs, and the assembled
-        output word is compared to the exact integer oracle."""
+        """A float pipeline rebuilt from the shipped wiring against the exact integer oracle."""
         pop_size = next(iter(pop.values())).shape[0]
         scores = torch.zeros(pop_size, device=self.device)
         total = 0
@@ -4287,9 +4198,7 @@ class BatchedFitnessEvaluator:
 
     def _test_float_fma_composed(self, pop: Dict, family: str, exp_bits: int,
                                  frac_bits: int, debug: bool) -> Tuple[torch.Tensor, int]:
-        """Composed fused-multiply-add test: rebuild the netlist from .inputs,
-        evaluate round(a*b+c) end to end over edge and random triples, compare
-        to the single-rounding oracle."""
+        """The fused multiply-add rebuilt from the shipped wiring against the single-rounding oracle."""
         pop_size = next(iter(pop.values())).shape[0]
         scores = torch.zeros(pop_size, device=self.device)
         prefix = f"{family}.fma"
@@ -4756,12 +4665,7 @@ class BatchedFitnessEvaluator:
 
     def _pop_modN(self, pop: Dict, pop_size: int, val_bits: torch.Tensor,
                   modulus: int) -> torch.Tensor:
-        """Drive the bit-cascade modular.mod{N} divisibility detector.
-
-        Returns a (pop_size,) tensor: 1 iff the 8-bit value (MSB-first bits in
-        val_bits) is divisible by ``modulus``. Walks the per-multiple match
-        gates (modular.modN.eq.k{val}.bit{i}.match -> .all -> top-level OR).
-        """
+        """Drive the bit-cascade modular.mod{N} divisibility detector."""
         ks = [k for k in range(256) if k % modulus == 0]
         alls = []
         for k in ks:
@@ -4782,11 +4686,7 @@ class BatchedFitnessEvaluator:
     def _pop_cmp8bit(self, pop: Dict, pop_size: int,
                      a_bits: torch.Tensor, b_bits: torch.Tensor,
                      kind: str) -> torch.Tensor:
-        """Drive the bit-cascade comparator (cmp8bit) over a population.
-
-        Returns a (pop_size,) tensor of heaviside outputs for the requested
-        comparison kind ('gt' | 'lt' | 'eq'). Bit 0 is MSB.
-        """
+        """Drive the bit-cascade comparator (cmp8bit) over a population."""
         def apply(name: str, inp: torch.Tensor, fan_in: int) -> torch.Tensor:
             w = pop[f'{name}.weight'].view(pop_size, fan_in)
             b = pop[f'{name}.bias'].view(pop_size)
@@ -5049,16 +4949,7 @@ class BatchedFitnessEvaluator:
     # =========================================================================
 
     def evaluate(self, population: Dict[str, torch.Tensor], debug: bool = False) -> torch.Tensor:
-        """
-        Evaluate population fitness with per-circuit reporting.
-
-        Args:
-            population: Dict of tensors, each with shape [pop_size, ...]
-            debug: If True, print per-circuit results
-
-        Returns:
-            Tensor of fitness scores [pop_size], normalized to [0, 1]
-        """
+        """Evaluate population fitness with per-circuit reporting."""
         self.results = []
         self.category_scores = {}
 
@@ -5475,5 +5366,1542 @@ def main():
         return 1
 
 
-if __name__ == '__main__':
-    exit(main())
+# ---------------------------------------------------------------------------
+# Variant-aware threshold ALU + CPU
+# ---------------------------------------------------------------------------
+
+class GenericThresholdALU:
+    """Variant-aware threshold ALU walking the gates of a loaded variant."""
+
+    def __init__(self, tensors: Dict[str, torch.Tensor], data_bits: int):
+        self.T = tensors
+        self.data_bits = data_bits
+
+    def _g(self, name, inputs):
+        w = self.T[name + ".weight"].view(-1)
+        b = self.T[name + ".bias"].view(-1)
+        return int(heaviside((torch.tensor(inputs, dtype=torch.float32) * w).sum() + b).item())
+
+    def _xor_or_nand(self, prefix, inputs):
+        a, b_ = inputs
+        h_or = self._g(f"{prefix}.layer1.or", [a, b_])
+        h_nand = self._g(f"{prefix}.layer1.nand", [a, b_])
+        return self._g(f"{prefix}.layer2", [h_or, h_nand])
+
+    def _fa(self, prefix, a, b, cin):
+        s1 = self._xor_or_nand(f"{prefix}.ha1.sum", [a, b])
+        c1 = self._g(f"{prefix}.ha1.carry", [a, b])
+        s2 = self._xor_or_nand(f"{prefix}.ha2.sum", [s1, cin])
+        c2 = self._g(f"{prefix}.ha2.carry", [s1, cin])
+        cout = self._g(f"{prefix}.carry_or", [c1, c2])
+        return s2, cout
+
+    def add8(self, a, b):
+        a_lsb = list(reversed(int_to_bits(a, 8)))
+        b_lsb = list(reversed(int_to_bits(b, 8)))
+        carry = 0
+        s_lsb = []
+        for i in range(8):
+            s, carry = self._fa(f"arithmetic.ripplecarry8bit.fa{i}", a_lsb[i], b_lsb[i], carry)
+            s_lsb.append(s)
+        return bits_to_int(list(reversed(s_lsb))), carry
+
+    def sub8(self, a, b):
+        a_lsb = list(reversed(int_to_bits(a, 8)))
+        b_lsb = list(reversed(int_to_bits(b, 8)))
+        carry = 1
+        d_lsb = []
+        for i in range(8):
+            notb = self._g(f"arithmetic.sub8bit.notb{i}", [b_lsb[i]])
+            x1 = self._xor_or_nand(f"arithmetic.sub8bit.fa{i}.xor1", [a_lsb[i], notb])
+            x2 = self._xor_or_nand(f"arithmetic.sub8bit.fa{i}.xor2", [x1, carry])
+            and1 = self._g(f"arithmetic.sub8bit.fa{i}.and1", [a_lsb[i], notb])
+            and2 = self._g(f"arithmetic.sub8bit.fa{i}.and2", [x1, carry])
+            carry = self._g(f"arithmetic.sub8bit.fa{i}.or_carry", [and1, and2])
+            d_lsb.append(x2)
+        return bits_to_int(list(reversed(d_lsb))), carry
+
+    _CMP_KIND = {"greaterthan": "gt", "lessthan": "lt", "eq": "eq", "equality": "eq",
+                 "greaterorequal": "ge", "lessorequal": "le"}
+
+    def _cmp_bit_cascade(self, cmp_prefix: str, finals: Dict[str, str],
+                         a_bits_msb: List[int], b_bits_msb: List[int], kind: str) -> int:
+        """Walk an add_bit_cascade_compare structure (bit 0 is the MSB)."""
+        bits = len(a_bits_msb)
+        bit_gt, bit_lt, bit_eq = [], [], []
+        for i in range(bits):
+            ab = [a_bits_msb[i], b_bits_msb[i]]
+            bit_gt.append(self._g(f"{cmp_prefix}.bit{i}.gt", ab))
+            bit_lt.append(self._g(f"{cmp_prefix}.bit{i}.lt", ab))
+            eq_and = self._g(f"{cmp_prefix}.bit{i}.eq.layer1.and", ab)
+            eq_nor = self._g(f"{cmp_prefix}.bit{i}.eq.layer1.nor", ab)
+            bit_eq.append(self._g(f"{cmp_prefix}.bit{i}.eq", [eq_and, eq_nor]))
+        cas_gt, cas_lt = [bit_gt[0]], [bit_lt[0]]
+        for i in range(1, bits):
+            eq_pref = self._g(f"{cmp_prefix}.cascade.eq_prefix.bit{i}", bit_eq[:i])
+            cas_gt.append(self._g(f"{cmp_prefix}.cascade.gt.bit{i}", [eq_pref, bit_gt[i]]))
+            cas_lt.append(self._g(f"{cmp_prefix}.cascade.lt.bit{i}", [eq_pref, bit_lt[i]]))
+        if kind == "gt":
+            return self._g(finals["gt"], cas_gt)
+        if kind == "lt":
+            return self._g(finals["lt"], cas_lt)
+        if kind == "eq":
+            return self._g(finals["eq"], bit_eq)
+        if kind == "ge":
+            lt = self._g(finals["lt"], cas_lt)
+            not_lt = self._g(finals["ge"] + ".not_lt", [lt])
+            return self._g(finals["ge"], [not_lt])
+        if kind == "le":
+            gt = self._g(finals["gt"], cas_gt)
+            not_gt = self._g(finals["le"] + ".not_gt", [gt])
+            return self._g(finals["le"], [not_gt])
+        raise ValueError(kind)
+
+    def cmp8(self, a, b, kind):
+        return self.cmp_n(a, b, kind, 8)
+
+    def mul8(self, a, b):
+        ab = int_to_bits(a, 8)
+        bb = int_to_bits(b, 8)
+        result = 0
+        for j in range(8):
+            if bb[j] == 0:
+                continue
+            row = 0
+            for i in range(8):
+                pp = self._g(f"alu.alu8bit.mul.pp.a{i}b{j}", [ab[i], bb[j]])
+                row |= (pp << (7 - i))
+            shift = 7 - j
+            result, _ = self.add8(result & 0xFF, (row << shift) & 0xFF)
+        return result & 0xFF
+
+    def _packed_pair_op(self, name: str, a: int, b: int) -> int:
+        """8 parallel 2-input gates stored packed: weight [16], bias [8]."""
+        a_bits = int_to_bits(a, 8)
+        b_bits = int_to_bits(b, 8)
+        w = self.T[f"{name}.weight"].view(-1)
+        bias = self.T[f"{name}.bias"].view(-1)
+        out = []
+        for bit in range(8):
+            inp = torch.tensor([float(a_bits[bit]), float(b_bits[bit])])
+            out.append(int(heaviside((inp * w[bit * 2:bit * 2 + 2]).sum() + bias[bit]).item()))
+        return bits_to_int(out)
+
+    def and8(self, a, b):
+        return self._packed_pair_op("alu.alu8bit.and", a, b)
+
+    def or8(self, a, b):
+        return self._packed_pair_op("alu.alu8bit.or", a, b)
+
+    def xor8(self, a, b):
+        a_bits = int_to_bits(a, 8)
+        b_bits = int_to_bits(b, 8)
+        w_or = self.T["alu.alu8bit.xor.layer1.or.weight"].view(-1)
+        b_or = self.T["alu.alu8bit.xor.layer1.or.bias"].view(-1)
+        w_nand = self.T["alu.alu8bit.xor.layer1.nand.weight"].view(-1)
+        b_nand = self.T["alu.alu8bit.xor.layer1.nand.bias"].view(-1)
+        w2 = self.T["alu.alu8bit.xor.layer2.weight"].view(-1)
+        b2 = self.T["alu.alu8bit.xor.layer2.bias"].view(-1)
+        out = []
+        for bit in range(8):
+            inp = torch.tensor([float(a_bits[bit]), float(b_bits[bit])])
+            h_or = heaviside((inp * w_or[bit * 2:bit * 2 + 2]).sum() + b_or[bit])
+            h_nand = heaviside((inp * w_nand[bit * 2:bit * 2 + 2]).sum() + b_nand[bit])
+            hidden = torch.stack([h_or, h_nand])
+            out.append(int(heaviside((hidden * w2[bit * 2:bit * 2 + 2]).sum() + b2[bit]).item()))
+        return bits_to_int(out)
+
+    def shl8(self, a):
+        a_bits = int_to_bits(a, 8)
+        out = []
+        for bit in range(8):
+            src = float(a_bits[bit + 1]) if bit < 7 else 0.0
+            out.append(self._g(f"alu.alu8bit.shl.bit{bit}", [src]))
+        return bits_to_int(out)
+
+    def shr8(self, a):
+        a_bits = int_to_bits(a, 8)
+        out = []
+        for bit in range(8):
+            src = float(a_bits[bit - 1]) if bit > 0 else 0.0
+            out.append(self._g(f"alu.alu8bit.shr.bit{bit}", [src]))
+        return bits_to_int(out)
+
+    def div8(self, a, b):
+        """8-bit restoring division through the per-stage bit-cascade GE comparators and the sub8 subtractor."""
+        if b == 0:
+            return 0xFF, a
+        a_bits = int_to_bits(a, 8)
+        div_bits = int_to_bits(b, 8)
+        quotient = 0
+        remainder = 0
+        for stage in range(8):
+            remainder = ((remainder << 1) | a_bits[stage]) & 0xFF
+            prefix = f"alu.alu8bit.div.stage{stage}"
+            finals = {
+                "gt": f"{prefix}.cmp_bc.gt",
+                "lt": f"{prefix}.cmp_bc.lt",
+                "eq": f"{prefix}.cmp_bc.eq",
+                "ge": f"{prefix}.cmp",
+                "le": f"{prefix}.cmp_bc.le",
+            }
+            ge = self._cmp_bit_cascade(f"{prefix}.cmp_bc", finals,
+                                       int_to_bits(remainder, 8), div_bits, "ge")
+            if ge:
+                remainder, _ = self.sub8(remainder, b)
+                quotient = (quotient << 1) | 1
+            else:
+                quotient = quotient << 1
+        return quotient & 0xFF, remainder & 0xFF
+
+    # ----- N-bit primitives (for 16-bit and 32-bit variants) ----------------
+
+    def add_n(self, a: int, b: int, bits: int):
+        """Width-generic ripple-carry add via arithmetic.ripplecarry{N}bit."""
+        prefix = f"arithmetic.ripplecarry{bits}bit"
+        a_lsb = list(reversed(int_to_bits(a, bits)))
+        b_lsb = list(reversed(int_to_bits(b, bits)))
+        carry = 0
+        s_lsb = []
+        for i in range(bits):
+            s, carry = self._fa(f"{prefix}.fa{i}", a_lsb[i], b_lsb[i], carry)
+            s_lsb.append(s)
+        return bits_to_int(list(reversed(s_lsb))), carry
+
+    def sub_n(self, a: int, b: int, bits: int):
+        """N-bit two's-complement subtract via arithmetic.sub{N}bit (N >= 16)."""
+        prefix = f"arithmetic.sub{bits}bit"
+        a_lsb = list(reversed(int_to_bits(a, bits)))
+        b_lsb = list(reversed(int_to_bits(b, bits)))
+        # NOT each B bit
+        notb = [self._g(f"{prefix}.not_b.bit{i}", [b_lsb[i]]) for i in range(bits)]
+        carry = 1  # carry-in = 1 for two's-complement
+        d_lsb = []
+        for i in range(bits):
+            s, carry = self._fa(f"{prefix}.fa{i}", a_lsb[i], notb[i], carry)
+            d_lsb.append(s)
+        return bits_to_int(list(reversed(d_lsb))), carry
+
+    def cmp_n(self, a: int, b: int, kind: str, bits: int):
+        """N-bit unsigned comparison through the bit-cascade comparator."""
+        short = self._CMP_KIND[kind]
+        finals = {
+            "gt": f"arithmetic.greaterthan{bits}bit",
+            "lt": f"arithmetic.lessthan{bits}bit",
+            "eq": f"arithmetic.equality{bits}bit",
+            "ge": f"arithmetic.greaterorequal{bits}bit",
+            "le": f"arithmetic.lessorequal{bits}bit",
+        }
+        return self._cmp_bit_cascade(f"arithmetic.cmp{bits}bit", finals,
+                                     int_to_bits(a, bits), int_to_bits(b, bits), short)
+
+    def mul_n(self, a: int, b: int, bits: int):
+        """N-bit shift-add multiply (low N bits only)."""
+        ab = int_to_bits(a, bits)
+        bb = int_to_bits(b, bits)
+        mask = (1 << bits) - 1
+        result = 0
+        for j in range(bits):
+            if bb[j] == 0:
+                continue
+            row = 0
+            for i in range(bits):
+                pp = self._g(f"alu.alu{bits}bit.mul.pp.a{i}b{j}", [ab[i], bb[j]])
+                row |= (pp << (bits - 1 - i))
+            shift = (bits - 1) - j
+            result, _ = self.add_n(result & mask, (row << shift) & mask, bits)
+        return result & mask
+
+
+class GenericThresholdCPU:
+    """Variant-aware CPU runtime. Sized from the variant's manifest."""
+
+    def __init__(self, tensors: Dict[str, torch.Tensor]):
+        self.T = tensors
+        m = get_manifest(tensors)
+        self.data_bits = m["data_bits"]
+        self.addr_bits = m["addr_bits"]
+        self.mem_bytes = m["memory_bytes"]
+        # 8-bit CPU primitives (ripplecarry8bit, sub8bit, alu.alu8bit.*, memory.*,
+        # control.*) are present in every variant regardless of manifest data_bits.
+        # Wider data widths simply add additional standalone ALU primitives.
+        if self.mem_bytes == 0:
+            raise NotImplementedError(
+                "Pure-ALU variants have no memory; cannot run CPU programs"
+            )
+        self.alu = GenericThresholdALU(tensors, 8)
+
+    def _addr_decode(self, addr):
+        bits = torch.tensor(int_to_bits(addr, self.addr_bits), dtype=torch.float32)
+        w = self.T["memory.addr_decode.weight"]
+        b = self.T["memory.addr_decode.bias"]
+        return heaviside((w * bits).sum(dim=1) + b)
+
+    def mem_read(self, mem, addr):
+        sel = self._addr_decode(addr)
+        mem_bits = torch.tensor(
+            [int_to_bits(byte, 8) for byte in mem], dtype=torch.float32
+        )
+        and_w = self.T["memory.read.and.weight"]
+        and_b = self.T["memory.read.and.bias"]
+        or_w = self.T["memory.read.or.weight"]
+        or_b = self.T["memory.read.or.bias"]
+        out = []
+        for bit in range(8):
+            inp = torch.stack([mem_bits[:, bit], sel], dim=1)
+            and_out = heaviside((inp * and_w[bit]).sum(dim=1) + and_b[bit])
+            out.append(int(heaviside((and_out * or_w[bit]).sum() + or_b[bit]).item()))
+        return bits_to_int(out)
+
+    def mem_write(self, mem, addr, value):
+        sel = self._addr_decode(addr)
+        data_bits = torch.tensor(int_to_bits(value, 8), dtype=torch.float32)
+        mem_bits = torch.tensor(
+            [int_to_bits(byte, 8) for byte in mem], dtype=torch.float32
+        )
+        sel_w = self.T["memory.write.sel.weight"]
+        sel_b = self.T["memory.write.sel.bias"]
+        nsel_w = self.T["memory.write.nsel.weight"].squeeze(1)
+        nsel_b = self.T["memory.write.nsel.bias"]
+        and_old_w = self.T["memory.write.and_old.weight"]
+        and_old_b = self.T["memory.write.and_old.bias"]
+        and_new_w = self.T["memory.write.and_new.weight"]
+        and_new_b = self.T["memory.write.and_new.bias"]
+        or_w = self.T["memory.write.or.weight"]
+        or_b = self.T["memory.write.or.bias"]
+        we = torch.ones_like(sel)
+        sel_inp = torch.stack([sel, we], dim=1)
+        write_sel = heaviside((sel_inp * sel_w).sum(dim=1) + sel_b)
+        nsel = heaviside(write_sel * nsel_w + nsel_b)
+        for bit in range(8):
+            old = mem_bits[:, bit]
+            data_bit = data_bits[bit].expand(self.mem_bytes)
+            inp_old = torch.stack([old, nsel], dim=1)
+            inp_new = torch.stack([data_bit, write_sel], dim=1)
+            and_old = heaviside((inp_old * and_old_w[:, bit]).sum(dim=1) + and_old_b[:, bit])
+            and_new = heaviside((inp_new * and_new_w[:, bit]).sum(dim=1) + and_new_b[:, bit])
+            or_inp = torch.stack([and_old, and_new], dim=1)
+            new_bit = heaviside((or_inp * or_w[:, bit]).sum(dim=1) + or_b[:, bit])
+            mem_bits[:, bit] = new_bit
+        return [bits_to_int([int(b) for b in mem_bits[i].tolist()]) for i in range(self.mem_bytes)]
+
+    # Conditions 0..7 map to (mux circuit, flag index into [Z, N, C, V]).
+    # Odd conditions are the negated forms; the mux select is the complemented
+    # flag (the circuits are plain per-bit muxes -- see control.* .inputs,
+    # which name the select $not_zero / $not_carry / ... for the odd forms).
+    _JCC = [("control.jz", 0), ("control.jnz", 0), ("control.jc", 2), ("control.jnc", 2),
+            ("control.jn", 1), ("control.jp", 1), ("control.jv", 3), ("control.jnv", 3)]
+
+    def _jcc_pc(self, circuit: str, pc: int, target: int, sel: int) -> int:
+        """Per-bit 2:1 mux over the PC: sel ? target : pc, addr_bits wide."""
+        pc_bits = int_to_bits(pc, self.addr_bits)
+        t_bits = int_to_bits(target, self.addr_bits)
+        out = []
+        for bit in range(self.addr_bits):
+            bp = f"{circuit}.bit{bit}"
+            not_sel = self.alu._g(f"{bp}.not_sel", [float(sel)])
+            and_a = self.alu._g(f"{bp}.and_a", [float(pc_bits[bit]), not_sel])
+            and_b = self.alu._g(f"{bp}.and_b", [float(t_bits[bit]), float(sel)])
+            out.append(self.alu._g(f"{bp}.or", [and_a, and_b]))
+        return bits_to_int(out)
+
+    def _sp_dec(self, sp: int) -> int:
+        """SP - 1 through the control.push.sp_dec borrow chain."""
+        bits = int_to_bits(sp, self.addr_bits)
+        out = [0] * self.addr_bits
+        borrow = 1
+        for bit in range(self.addr_bits - 1, -1, -1):
+            bp = f"control.push.sp_dec.bit{bit}"
+            h_or = self.alu._g(f"{bp}.xor.layer1.or", [float(bits[bit]), float(borrow)])
+            h_nand = self.alu._g(f"{bp}.xor.layer1.nand", [float(bits[bit]), float(borrow)])
+            out[bit] = self.alu._g(f"{bp}.xor.layer2", [h_or, h_nand])
+            borrow = self.alu._g(f"{bp}.borrow", [float(1 - bits[bit]), float(borrow)])
+        return bits_to_int(out)
+
+    def _decode_op(self, opcode):
+        """4-to-16 opcode one-hot through the gate decoder."""
+        ob = [float((opcode >> j) & 1) for j in range(4)]
+        return [self.alu._g(f"control.decode.op{n}", ob) for n in range(16)]
+
+    def _inc(self, pc, name, start):
+        """PC + 2^start through the gate increment chain (LSB-first)."""
+        ab = self.addr_bits
+        pcb = [(pc >> k) & 1 for k in range(ab)]
+        out = [0] * ab
+        carry = 0
+        for k in range(ab):
+            if k < start:
+                out[k] = self.alu._g(f"control.pcnext.{name}.bit{k}", [float(pcb[k])])
+            else:
+                cin = 1 if k == start else carry
+                o = self.alu._g(f"control.pcnext.{name}.bit{k}.xor.layer1.or", [float(pcb[k]), float(cin)])
+                nd = self.alu._g(f"control.pcnext.{name}.bit{k}.xor.layer1.nand", [float(pcb[k]), float(cin)])
+                out[k] = self.alu._g(f"control.pcnext.{name}.bit{k}.xor.layer2", [o, nd])
+                carry = self.alu._g(f"control.pcnext.{name}.bit{k}.carry", [float(pcb[k]), float(cin)])
+        return sum(out[k] << k for k in range(ab))
+
+    def _pcnext(self, pc2, pc4, addr, jcc, use_pc4, use_addr, use_jcc):
+        """Next-PC priority mux through the gates: use_addr ? addr : (use_jcc ? jcc : (use_pc4 ? pc4 : pc2))."""
+        ab = self.addr_bits
+        p2 = [(pc2 >> k) & 1 for k in range(ab)]
+        p4 = [(pc4 >> k) & 1 for k in range(ab)]
+        aB = [(addr >> k) & 1 for k in range(ab)]
+        jB = [(jcc >> k) & 1 for k in range(ab)]
+        out = [0] * ab
+        for k in range(ab):
+            ns = self.alu._g(f"control.pcnext.m_pc4.bit{k}.not_sel", [float(use_pc4)])
+            aa = self.alu._g(f"control.pcnext.m_pc4.bit{k}.and_a", [float(p2[k]), ns])
+            bb = self.alu._g(f"control.pcnext.m_pc4.bit{k}.and_b", [float(p4[k]), float(use_pc4)])
+            m1 = self.alu._g(f"control.pcnext.m_pc4.bit{k}.or", [aa, bb])
+            ns = self.alu._g(f"control.pcnext.m_jcc.bit{k}.not_sel", [float(use_jcc)])
+            aa = self.alu._g(f"control.pcnext.m_jcc.bit{k}.and_a", [float(m1), ns])
+            bb = self.alu._g(f"control.pcnext.m_jcc.bit{k}.and_b", [float(jB[k]), float(use_jcc)])
+            m2 = self.alu._g(f"control.pcnext.m_jcc.bit{k}.or", [aa, bb])
+            ns = self.alu._g(f"control.pcnext.m_addr.bit{k}.not_sel", [float(use_addr)])
+            aa = self.alu._g(f"control.pcnext.m_addr.bit{k}.and_a", [float(m2), ns])
+            bb = self.alu._g(f"control.pcnext.m_addr.bit{k}.and_b", [float(aB[k]), float(use_addr)])
+            out[k] = self.alu._g(f"control.pcnext.m_addr.bit{k}.or", [aa, bb])
+        return sum(out[k] << k for k in range(ab))
+
+    def step(self, state):
+        if state["halted"]:
+            return state
+        s = dict(state)
+        s["mem"] = state["mem"][:]
+        s["regs"] = state["regs"][:]
+        s["flags"] = state["flags"][:]
+        addr_mask = (1 << self.addr_bits) - 1
+        pc = s["pc"]
+        hi = self.mem_read(s["mem"], pc & addr_mask)
+        lo = self.mem_read(s["mem"], (pc + 1) & addr_mask)
+        ir = ((hi & 0xFF) << 8) | (lo & 0xFF)
+        opcode = (ir >> 12) & 0xF
+        oh = self._decode_op(opcode)                 # gate opcode decode (one-hots)
+        rd = (ir >> 10) & 0x3
+        rs = (ir >> 8) & 0x3
+        imm = ir & 0xFF
+        addr = None
+        if oh[0xA] or oh[0xB] or oh[0xC] or oh[0xD] or oh[0xE]:
+            ah = self.mem_read(s["mem"], (pc + 2) & addr_mask)
+            al = self.mem_read(s["mem"], (pc + 3) & addr_mask)
+            addr = (((ah & 0xFF) << 8) | (al & 0xFF)) & addr_mask
+        pc2 = self._inc(pc, "pc2", 1)                # PC+2 through the gate chain
+        pc4 = self._inc(pc, "pc4", 2)                # PC+4 through the gate chain
+        a = s["regs"][rd]
+        b = s["regs"][rs]
+        result = a
+        carry = 0
+        overflow = 0
+        write_result = True
+        jcc_val = 0
+        if oh[0x0]:
+            result, carry = self.alu.add8(a, b)
+            overflow = 1 if (((a ^ result) & (b ^ result)) & 0x80) else 0
+        elif oh[0x1]:
+            result, carry = self.alu.sub8(a, b)
+            overflow = 1 if (((a ^ b) & (a ^ result)) & 0x80) else 0
+        elif oh[0x2]:
+            result = self.alu.and8(a, b)
+        elif oh[0x3]:
+            result = self.alu.or8(a, b)
+        elif oh[0x4]:
+            result = self.alu.xor8(a, b)
+        elif oh[0x5]:
+            result = self.alu.shl8(a)
+        elif oh[0x6]:
+            result = self.alu.shr8(a)
+        elif oh[0x7]:
+            result = self.alu.mul8(a, b)
+        elif oh[0x8]:
+            result, _ = self.alu.div8(a, b)
+        elif oh[0x9]:                                # CMP: set flags only
+            r2, carry = self.alu.sub8(a, b)
+            z = 1 if r2 == 0 else 0
+            n = 1 if (r2 & 0x80) else 0
+            v = 1 if (((a ^ b) & (a ^ r2)) & 0x80) else 0
+            s["flags"] = [z, n, carry, v]
+            write_result = False
+        elif oh[0xA]:                                # LOAD
+            result = self.mem_read(s["mem"], addr)
+        elif oh[0xB]:                                # STORE
+            s["mem"] = self.mem_write(s["mem"], addr, b & 0xFF)
+            write_result = False
+        elif oh[0xC]:                                # JMP (PC = addr via pcnext)
+            write_result = False
+        elif oh[0xD]:                                # JCC (PC via jcc mux + pcnext)
+            cond = imm & 0x7
+            circuit, flag_idx = self._JCC[cond]
+            flag = s["flags"][flag_idx]
+            sel = flag if cond % 2 == 0 else 1 - flag
+            jcc_val = self._jcc_pc(circuit, pc4, addr, sel)
+            write_result = False
+        elif oh[0xE]:                                # CALL: push PC+4, PC = addr
+            ret_addr = pc4 & 0xFFFF
+            sp = s.get("sp", addr_mask)
+            sp = self._sp_dec(sp)
+            s["mem"] = self.mem_write(s["mem"], sp, (ret_addr >> 8) & 0xFF)
+            sp = self._sp_dec(sp)
+            s["mem"] = self.mem_write(s["mem"], sp, ret_addr & 0xFF)
+            s["sp"] = sp
+            write_result = False
+        elif oh[0xF]:                                # HALT
+            s["halted"] = True
+            return s
+
+        if write_result:
+            s["regs"][rd] = result & 0xFF
+        if oh[0x0] or oh[0x1] or oh[0x7]:
+            z = 1 if (result & 0xFF) == 0 else 0
+            n = 1 if (result & 0x80) else 0
+            s["flags"] = [z, n, carry, overflow]
+        # PC sequencing through the gate mux.
+        use_pc4 = 1 if (oh[0xA] or oh[0xB]) else 0
+        use_addr = 1 if (oh[0xC] or oh[0xE]) else 0
+        s["pc"] = self._pcnext(pc2, pc4, addr or 0, jcc_val, use_pc4, use_addr, oh[0xD])
+        return s
+
+    def run(self, state, max_cycles=200):
+        s = state
+        cycles = 0
+        while not s["halted"] and cycles < max_cycles:
+            s = self.step(s)
+            cycles += 1
+        return s, cycles
+
+
+def _encode_instr(opcode, rd, rs, imm):
+    return ((opcode & 0xF) << 12) | ((rd & 0x3) << 10) | ((rs & 0x3) << 8) | (imm & 0xFF)
+
+
+def _w16(mem, addr, value):
+    mem[addr] = (value >> 8) & 0xFF
+    mem[addr + 1] = value & 0xFF
+
+
+PROGRAM_MIN_BYTES = 0x84  # code 0x00..0x1F + data 0x80..0x83
+
+
+def builtin_program(addr_bits: int) -> Tuple[List[int], int]:
+    """Sum 5+4+3+2+1 via a loop."""
+    if (1 << addr_bits) < PROGRAM_MIN_BYTES:
+        raise ValueError(f"addr_bits={addr_bits} too small for builtin program")
+    mem = [0] * (1 << addr_bits)
+    mem[0x80] = 5  # initial counter
+    mem[0x81] = 1  # decrement
+    mem[0x82] = 0  # zero (for compare and accumulator init)
+    # mem[0x83] is the output
+    _w16(mem, 0x0000, _encode_instr(0xA, 1, 0, 0)); _w16(mem, 0x0002, 0x0080)
+    _w16(mem, 0x0004, _encode_instr(0xA, 2, 0, 0)); _w16(mem, 0x0006, 0x0081)
+    _w16(mem, 0x0008, _encode_instr(0xA, 3, 0, 0)); _w16(mem, 0x000A, 0x0082)
+    _w16(mem, 0x000C, _encode_instr(0xA, 0, 0, 0)); _w16(mem, 0x000E, 0x0082)
+    _w16(mem, 0x0010, _encode_instr(0x0, 0, 1, 0))
+    _w16(mem, 0x0012, _encode_instr(0x1, 1, 2, 0))
+    _w16(mem, 0x0014, _encode_instr(0x9, 1, 3, 0))
+    _w16(mem, 0x0016, _encode_instr(0xD, 0, 0, 0x01)); _w16(mem, 0x0018, 0x0010)
+    _w16(mem, 0x001A, _encode_instr(0xB, 0, 0, 0)); _w16(mem, 0x001C, 0x0083)
+    _w16(mem, 0x001E, _encode_instr(0xF, 0, 0, 0))
+    return mem, 15
+
+
+# ---------------------------------------------------------------------------
+# Eval driver
+# ---------------------------------------------------------------------------
+
+def _file_fingerprint(path: Path) -> str:
+    """Stable cache key for a safetensors file: sha256 of its content."""
+    import hashlib
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _cache_key(path: Path, opts: Dict[str, Any]) -> str:
+    """Cache key combining file content with the relevant evaluation options."""
+    fp = _file_fingerprint(path)
+    opt_str = json.dumps(opts, sort_keys=True)
+    import hashlib
+    suffix = hashlib.sha256(opt_str.encode("utf-8")).hexdigest()[:8]
+    return f"{fp}_{suffix}"
+
+
+def _load_cache(cache_dir: Path, key: str) -> Dict[str, Any] | None:
+    p = cache_dir / f"{key}.json"
+    if not p.exists():
+        return None
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _save_cache(cache_dir: Path, key: str, payload: Dict[str, Any]) -> None:
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    p = cache_dir / f"{key}.json"
+    try:
+        p.write_text(json.dumps(payload, indent=2, default=str), encoding="utf-8")
+    except OSError:
+        pass
+
+
+def list_safetensors(path: Path) -> List[Path]:
+    if path.is_file():
+        return [path]
+    if path.is_dir():
+        return sorted(p for p in path.glob("*.safetensors") if p.is_file())
+    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": "src/machines.py",
+    "rv32": "src/machines.py",
+    "matrix8": "src/machines.py matrix8",
+    "subleq8io": "src/host.py constructor8",
+    "reflect": "src/reflect.py",
+    "attractor": "src/automata.py attractor",
+    "reversible": "src/automata.py reversible",
+    "ca": "src/automata.py ca",
+    "tile": "src/automata.py tile",
+}
+
+
+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}
+    # 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"):
+        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))
+    except Exception as e:
+        out.update(error=f"load failed: {e}", status="ERROR")
+        return out
+
+    manifest = get_manifest(tensors)
+    out.update(
+        size_mb=path.stat().st_size / (1024 * 1024),
+        tensors=len(tensors),
+        params=sum(t.numel() for t in tensors.values()),
+        manifest=manifest,
+    )
+
+    # Move to device
+    tensors = {k: v.to(device) for k, v in tensors.items()}
+
+    try:
+        evaluator = BatchedFitnessEvaluator(device=device, model_path=str(path), tensors=tensors)
+        population = create_population(tensors, pop_size=pop_size, device=device)
+        t0 = time.perf_counter()
+        fitness = evaluator.evaluate(population, debug=debug)
+        elapsed = time.perf_counter() - t0
+        f0 = float(fitness[0].item()) if pop_size == 1 else float(fitness.mean().item())
+        out.update(
+            fitness=f0,
+            total_tests=evaluator.total_tests,
+            elapsed_s=elapsed,
+            categories={k: (float(v[0]), int(v[1])) for k, v in evaluator.category_scores.items()},
+            status="PASS" if f0 >= 0.9999 else "FAIL",
+        )
+    except Exception as e:
+        out.update(error=f"eval failed: {type(e).__name__}: {e}", status="ERROR")
+        return out
+
+    # Optional: CPU program test (8-bit CPU primitives are in every variant)
+    if run_cpu_program:
+        if manifest["memory_bytes"] >= PROGRAM_MIN_BYTES:
+            try:
+                cpu_tensors = {k: v.cpu() for k, v in tensors.items()}
+                cpu = GenericThresholdCPU(cpu_tensors)
+                mem, expected = builtin_program(manifest["addr_bits"])
+                state = {"pc": 0, "regs": [0] * 4, "flags": [0] * 4, "mem": mem, "halted": False}
+                t0 = time.perf_counter()
+                final, cycles = cpu.run(state, max_cycles=200)
+                cpu_elapsed = time.perf_counter() - t0
+                got = final["mem"][0x83]
+                out["cpu_program"] = {
+                    "ok": got == expected,
+                    "got": got,
+                    "expected": expected,
+                    "cycles": cycles,
+                    "elapsed_s": cpu_elapsed,
+                }
+                if got != expected:
+                    out["status"] = "FAIL"
+            except Exception as e:
+                out["cpu_program"] = {"error": str(e)}
+        else:
+            out["cpu_program"] = {"skipped": f"mem={manifest['memory_bytes']}B < {PROGRAM_MIN_BYTES}"}
+
+        # Wider-ALU chain test for 16/32-bit variants
+        bits = manifest["data_bits"]
+        if bits in (16, 32):
+            try:
+                alu_tensors = {k: v.cpu() for k, v in tensors.items()}
+                alu = GenericThresholdALU(alu_tensors, bits)
+                t0 = time.perf_counter()
+                if bits == 16:
+                    x, y = 1234, 5678
+                    z, _ = alu.add_n(x, y, 16);          assert z == (x + y) & 0xFFFF
+                    w, _ = alu.sub_n(z, x, 16);          assert w == (z - x) & 0xFFFF, (w, z - x)
+                    gt = alu.cmp_n(z, x, "greaterthan", 16); assert gt == 1
+                    lt = alu.cmp_n(x, z, "lessthan",   16);  assert lt == 1
+                    eq = alu.cmp_n(w, y, "eq",         16);  assert eq == 1
+                    p   = alu.mul_n(123, 5, 16);          assert p == (123 * 5) & 0xFFFF
+                else:  # 32
+                    x, y = 1_000_000, 999_000
+                    z, _ = alu.sub_n(x, y, 32);          assert z == 1_000
+                    s, _ = alu.add_n(z, x, 32);          assert s == 1_001_000
+                    p    = alu.mul_n(z, 100, 32);        assert p == 100_000
+                    gt = alu.cmp_n(x, y, "greaterthan", 32); assert gt == 1
+                    lt = alu.cmp_n(y, x, "lessthan",   32);  assert lt == 1
+                    eq = alu.cmp_n(p, 100_000, "equality", 32); assert eq == 1
+                chain_dt = time.perf_counter() - t0
+                out[f"alu_chain_{bits}"] = {"ok": True, "elapsed_s": chain_dt}
+            except AssertionError as e:
+                out[f"alu_chain_{bits}"] = {"ok": False, "error": f"chain mismatch: {e}"}
+                out["status"] = "FAIL"
+            except Exception as e:
+                out[f"alu_chain_{bits}"] = {"ok": False, "error": f"{type(e).__name__}: {e}"}
+                out["status"] = "FAIL"
+
+    return out
+
+
+def print_row(r: Dict, show_cpu: bool) -> None:
+    if r.get("status") == "SKIP":
+        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]}")
+        return
+    m = r["manifest"]
+    fit = f"{r['fitness']:.4f}" if r.get("fitness") is not None else "n/a"
+    cpu_col = ""
+    if show_cpu and "cpu_program" in r:
+        cp = r["cpu_program"]
+        if cp.get("ok"):
+            cpu_col = f"  CPU OK ({cp['cycles']}cyc/{cp['elapsed_s']:.1f}s)"
+        elif "skipped" in cp:
+            cpu_col = f"  CPU SKIP"
+        elif "error" in cp:
+            cpu_col = f"  CPU ERR"
+        else:
+            cpu_col = f"  CPU FAIL ({cp.get('got')}!={cp.get('expected')})"
+    chain_col = ""
+    if show_cpu:
+        for bits in (16, 32):
+            key = f"alu_chain_{bits}"
+            if key in r:
+                ch = r[key]
+                if ch.get("ok"):
+                    chain_col = f"  ALU{bits} OK ({ch['elapsed_s']:.2f}s)"
+                else:
+                    chain_col = f"  ALU{bits} FAIL"
+    print(
+        f"  {r['filename']:<48}  d={m['data_bits']:>2}b a={m['addr_bits']:>2}b "
+        f"mem={m['memory_bytes']:>6}B  size={r['size_mb']:>6.1f}MB  "
+        f"params={r['params']:>10,}  fit={fit:>6}  tests={r['total_tests']:>5}  "
+        f"{r['status']:>5}{cpu_col}{chain_col}"
+    )
+
+
+def main_all() -> int:
+    parser = argparse.ArgumentParser(description="Variant-agnostic eval harness")
+    parser.add_argument("path", help="Path to .safetensors file or directory of files")
+    parser.add_argument("--device", default="cpu", help="cpu (default) or cuda")
+    parser.add_argument("--pop_size", type=int, default=1)
+    parser.add_argument("--debug", action="store_true", help="Per-circuit detail per file")
+    parser.add_argument("--cpu-program", action="store_true",
+                        help="Also run a small assembled program through the threshold CPU "
+                             "(any variant with >= 132 B memory), plus a chained 16- or "
+                             "32-bit ALU sequence on wider variants")
+    parser.add_argument("--json", action="store_true", help="Emit JSON results to stdout instead of a table")
+    parser.add_argument("--cache-dir", default=".eval_cache",
+                        help="Directory for hash-keyed result cache "
+                             "(default: ./.eval_cache). Set to '' to disable.")
+    parser.add_argument("--no-cache", action="store_true",
+                        help="Disable the result cache for this run.")
+    args = parser.parse_args()
+
+    files = list_safetensors(Path(args.path))
+    if not files:
+        print(f"No .safetensors files found under {args.path}", file=sys.stderr)
+        return 2
+
+    print(f"Evaluating {len(files)} file(s) on {args.device}\n")
+    cache_enabled = bool(args.cache_dir) and not args.no_cache
+    cache_dir = Path(args.cache_dir) if cache_enabled else None
+    cache_opts = {
+        "device": args.device,
+        "pop_size": args.pop_size,
+        "cpu_program": bool(args.cpu_program),
+    }
+    cache_hits = 0
+    results = []
+    fail_count = 0
+    for f in files:
+        print(f"=== {f.name}")
+        cached = None
+        key = None
+        if cache_enabled:
+            try:
+                key = _cache_key(f, cache_opts)
+                cached = _load_cache(cache_dir, key)
+            except OSError:
+                cached = None
+        if cached is not None:
+            r = cached
+            cache_hits += 1
+            print(f"   (cache hit)")
+        else:
+            r = evaluate_one(f, device=args.device, pop_size=args.pop_size,
+                             debug=args.debug, run_cpu_program=args.cpu_program)
+            # Don't cache ERROR results: a transient failure (OOM, interrupt)
+            # would otherwise be replayed on every rerun of the same file.
+            if cache_enabled and key is not None and r.get("status") != "ERROR":
+                _save_cache(cache_dir, key, r)
+        results.append(r)
+        print_row(r, show_cpu=args.cpu_program)
+        if r.get("status") not in ("PASS", "SKIP"):
+            fail_count += 1
+
+    if args.json:
+        # Make it serialisable
+        for r in results:
+            r["manifest"] = {k: (int(v) if isinstance(v, float) and v.is_integer() else v)
+                             for k, v in r.get("manifest", {}).items()}
+        print(json.dumps(results, indent=2, default=str))
+        return fail_count
+
+    # Summary
+    print()
+    print("=" * 100)
+    print(" SUMMARY")
+    print("=" * 100)
+    for r in results:
+        print_row(r, show_cpu=args.cpu_program)
+
+    print()
+    if fail_count == 0:
+        print(f"ALL {len(files)} variants PASS")
+    else:
+        print(f"{fail_count}/{len(files)} variants FAIL")
+    if cache_enabled:
+        print(f"(cache: {cache_hits}/{len(files)} hits, dir={cache_dir})")
+    return fail_count
+
+
+# ----------------------------------------------------------------------------
+# Mini assembler
+# ----------------------------------------------------------------------------
+
+_OPCODE_NAMES = {
+    "add": 0x0, "sub": 0x1, "and": 0x2, "or": 0x3, "xor": 0x4,
+    "shl": 0x5, "shr": 0x6, "mul": 0x7, "div": 0x8, "cmp": 0x9,
+    "load": 0xA, "store": 0xB, "jmp": 0xC, "jcc": 0xD,
+    "call": 0xE, "halt": 0xF,
+}
+
+_COND = {"jz": 0, "jnz": 1, "jc": 2, "jnc": 3,
+         "jn": 4, "jp": 5, "jv": 6, "jnv": 7}
+
+
+def _enc(opcode: int, rd: int = 0, rs: int = 0, imm: int = 0) -> int:
+    return ((opcode & 0xF) << 12) | ((rd & 0x3) << 10) | ((rs & 0x3) << 8) | (imm & 0xFF)
+
+
+class Asm:
+    """Tiny assembler for the threshold-computer ISA."""
+
+    def __init__(self, size: int):
+        self.mem: List[int] = [0] * size
+        self.pc: int = 0
+        self.labels: Dict[str, int] = {}
+        self.fixups: List[Tuple[int, str]] = []
+
+    def org(self, addr: int) -> None:
+        self.pc = addr
+
+    def label(self, name: str) -> None:
+        if name in self.labels:
+            raise ValueError(f"duplicate label: {name}")
+        self.labels[name] = self.pc
+
+    def db(self, *values: int) -> None:
+        for v in values:
+            self.mem[self.pc] = v & 0xFF
+            self.pc += 1
+
+    def dw(self, value: int) -> None:
+        self.mem[self.pc] = (value >> 8) & 0xFF
+        self.mem[self.pc + 1] = value & 0xFF
+        self.pc += 2
+
+    def daddr(self, label: str) -> None:
+        self.fixups.append((self.pc, label))
+        self.dw(0)
+
+    # --- ALU ops (no immediate) ---
+    def _alu(self, op: int, rd: int, rs: int) -> None:
+        self.dw(_enc(op, rd, rs))
+
+    def add(self, rd: int, rs: int) -> None: self._alu(0x0, rd, rs)
+    def sub(self, rd: int, rs: int) -> None: self._alu(0x1, rd, rs)
+    def and_(self, rd: int, rs: int) -> None: self._alu(0x2, rd, rs)
+    def or_(self, rd: int, rs: int) -> None: self._alu(0x3, rd, rs)
+    def xor(self, rd: int, rs: int) -> None: self._alu(0x4, rd, rs)
+    def shl(self, rd: int) -> None: self._alu(0x5, rd, 0)
+    def shr(self, rd: int) -> None: self._alu(0x6, rd, 0)
+    def mul(self, rd: int, rs: int) -> None: self._alu(0x7, rd, rs)
+    def cmp(self, rd: int, rs: int) -> None: self._alu(0x9, rd, rs)
+
+    # --- Memory + control (address-extended) ---
+    def load(self, rd: int, label: str) -> None:
+        self.dw(_enc(0xA, rd, 0)); self.daddr(label)
+
+    def store(self, rs: int, label: str) -> None:
+        self.dw(_enc(0xB, 0, rs)); self.daddr(label)
+
+    def jmp(self, label: str) -> None:
+        self.dw(_enc(0xC)); self.daddr(label)
+
+    def jcc(self, cond: str, label: str) -> None:
+        self.dw(_enc(0xD, 0, 0, _COND[cond])); self.daddr(label)
+
+    def jz(self, label: str) -> None: self.jcc("jz", label)
+    def jnz(self, label: str) -> None: self.jcc("jnz", label)
+    def jc(self, label: str) -> None: self.jcc("jc", label)
+    def jnc(self, label: str) -> None: self.jcc("jnc", label)
+    def jn(self, label: str) -> None: self.jcc("jn", label)
+    def jp(self, label: str) -> None: self.jcc("jp", label)
+    def jv(self, label: str) -> None: self.jcc("jv", label)
+    def jnv(self, label: str) -> None: self.jcc("jnv", label)
+
+    def call(self, label: str) -> None:
+        self.dw(_enc(0xE)); self.daddr(label)
+
+    def halt(self) -> None:
+        self.dw(_enc(0xF))
+
+    def assemble(self) -> List[int]:
+        for offset, label in self.fixups:
+            if label not in self.labels:
+                raise ValueError(f"undefined label: {label}")
+            target = self.labels[label]
+            self.mem[offset] = (target >> 8) & 0xFF
+            self.mem[offset + 1] = target & 0xFF
+        return self.mem
+
+
+# ----------------------------------------------------------------------------
+# Programs
+# ----------------------------------------------------------------------------
+
+ProgramResult = Tuple[List[int], Dict[int, int], int, str]
+
+
+def fib(n: int = 11, mem_size: int = 256) -> ProgramResult:
+    """Iterative Fibonacci F(N), 8-bit wrap."""
+    a = Asm(mem_size)
+
+    a.org(0)
+    a.load(2, "n_addr")           # R2 = n
+    a.load(0, "zero_addr")        # R0 = 0 = F(0)
+    a.load(1, "one_addr")         # R1 = 1 = F(1)
+    a.label("loop")
+    a.load(3, "zero_addr")        # R3 = 0
+    a.cmp(2, 3)                   # n == 0?
+    a.jz("done")
+    a.load(3, "zero_addr")        # R3 = 0
+    a.add(3, 1)                   # R3 = b      (saved old b)
+    a.add(1, 0)                   # R1 = a + b  (new b)
+    a.load(0, "zero_addr")        # R0 = 0
+    a.add(0, 3)                   # R0 = old b  (new a)
+    a.load(3, "one_addr")         # R3 = 1
+    a.sub(2, 3)                   # n--
+    a.jmp("loop")
+    a.label("done")
+    a.store(0, "out")             # OUT = a
+    a.halt()
+
+    a.org(0x80)
+    a.label("zero_addr"); a.db(0)
+    a.label("one_addr");  a.db(1)
+    a.label("n_addr");    a.db(n)
+    a.label("out");       a.db(0)
+
+    mem = a.assemble()
+    expected_a = 0
+    aa, bb = 0, 1
+    for _ in range(n):
+        aa, bb = bb, (aa + bb) & 0xFF
+    expected_a = aa
+    return mem, {a.labels["out"]: expected_a}, 16 * (n + 2), f"Fibonacci F({n}) = {expected_a}"
+
+
+def sum_n(n: int = 10, mem_size: int = 256) -> ProgramResult:
+    """Compute 1 + 2 + ... + N using the Z flag from SUB to terminate."""
+    a = Asm(mem_size)
+
+    a.org(0)
+    a.load(0, "zero_addr")        # acc = 0
+    a.load(1, "n_addr")           # i = n
+    a.load(2, "one_addr")         # 1
+    a.label("loop")
+    a.add(0, 1)                   # acc += i
+    a.sub(1, 2)                   # i-- (Z set when i becomes 0)
+    a.jnz("loop")
+    a.store(0, "out")
+    a.halt()
+
+    a.org(0x80)
+    a.label("zero_addr"); a.db(0)
+    a.label("one_addr");  a.db(1)
+    a.label("n_addr");    a.db(n)
+    a.label("out");       a.db(0)
+
+    mem = a.assemble()
+    expected = (n * (n + 1) // 2) & 0xFF
+    return mem, {a.labels["out"]: expected}, 4 + 4 * n, f"sum 1..{n} = {expected}"
+
+
+def self_mod_jmp(mem_size: int = 256) -> ProgramResult:
+    """Self-modifying code: writes the JMP target's low byte at runtime."""
+    a = Asm(mem_size)
+
+    a.org(0)
+    a.label("start")
+
+    # Forward-declare the_jmp's LSB address. The first two instructions are
+    # each 4 bytes; the_jmp follows them, so the_jmp = pc + 8 from start.
+    # The JMP's address word is at the_jmp + 2; the LSB byte is at the_jmp + 3.
+    a.labels["jmp_target_lsb"] = a.pc + 8 + 3
+
+    a.load(0, "new_lsb")           # R0 = LSB of path_b address (4 bytes)
+    a.store(0, "jmp_target_lsb")   # patch the JMP's LSB (4 bytes)
+    a.label("the_jmp")
+    a.jmp("path_a")                # initially -> path_a; after patch -> path_b
+    a.label("path_a")
+    a.load(1, "val_a"); a.store(1, "out"); a.halt()
+    a.label("path_b")
+    a.load(1, "val_b"); a.store(1, "out"); a.halt()
+
+    a.org(0x80)
+    a.label("val_a");   a.db(0xAA)
+    a.label("val_b");   a.db(0xBB)
+    # new_lsb_word stores path_b's full 16-bit address; new_lsb labels the LSB byte.
+    a.label("new_lsb_word"); a.daddr("path_b")
+    a.labels["new_lsb"] = a.labels["new_lsb_word"] + 1
+    a.label("out");     a.db(0)
+
+    mem = a.assemble()
+    return mem, {a.labels["out"]: 0xBB}, 30, "self-modifying JMP target"
+
+
+def all_branches(mem_size: int = 256) -> ProgramResult:
+    """Drive all eight conditional jumps; each path writes a unique marker."""
+    a = Asm(mem_size)
+
+    a.org(0)
+    # ----- JZ: equal compare -> Z=1 -----
+    a.load(0, "v5"); a.load(1, "v5"); a.cmp(0, 1); a.jz("ok_jz"); a.jmp("fail")
+    a.label("ok_jz"); a.load(2, "m_a0"); a.store(2, "out0")
+
+    # ----- JNZ: unequal compare -> Z=0 -----
+    a.load(0, "v5"); a.load(1, "v3"); a.cmp(0, 1); a.jnz("ok_jnz"); a.jmp("fail")
+    a.label("ok_jnz"); a.load(2, "m_a1"); a.store(2, "out1")
+
+    # ----- JC: 255+1 = 0 with carry -----
+    a.load(0, "v255"); a.load(1, "v1"); a.add(0, 1); a.jc("ok_jc"); a.jmp("fail")
+    a.label("ok_jc"); a.load(2, "m_a2"); a.store(2, "out2")
+
+    # ----- JNC: 1+1 = 2, no carry -----
+    a.load(0, "v1"); a.load(1, "v1"); a.add(0, 1); a.jnc("ok_jnc"); a.jmp("fail")
+    a.label("ok_jnc"); a.load(2, "m_a3"); a.store(2, "out3")
+
+    # ----- JN: 0 - 1 = 0xFF, MSB set -----
+    a.load(0, "v0"); a.load(1, "v1"); a.sub(0, 1); a.jn("ok_jn"); a.jmp("fail")
+    a.label("ok_jn"); a.load(2, "m_a4"); a.store(2, "out4")
+
+    # ----- JP: 0 + 1 = 1, MSB clear -----
+    a.load(0, "v0"); a.load(1, "v1"); a.add(0, 1); a.jp("ok_jp"); a.jmp("fail")
+    a.label("ok_jp"); a.load(2, "m_a5"); a.store(2, "out5")
+
+    # ----- JV: 127 + 1 = 128, signed overflow -----
+    a.load(0, "v127"); a.load(1, "v1"); a.add(0, 1); a.jv("ok_jv"); a.jmp("fail")
+    a.label("ok_jv"); a.load(2, "m_a6"); a.store(2, "out6")
+
+    # ----- JNV: 1 + 1 = 2, no signed overflow -----
+    a.load(0, "v1"); a.load(1, "v1"); a.add(0, 1); a.jnv("ok_jnv"); a.jmp("fail")
+    a.label("ok_jnv"); a.load(2, "m_a7"); a.store(2, "out7")
+
+    a.jmp("end")
+    a.label("fail")
+    a.load(2, "v_fail"); a.store(2, "fail_addr"); a.halt()
+    a.label("end")
+    a.halt()
+
+    # Code runs to ~0xDF; data starts safely after that.
+    a.org(0xE0)
+    a.label("v0");     a.db(0)
+    a.label("v1");     a.db(1)
+    a.label("v3");     a.db(3)
+    a.label("v5");     a.db(5)
+    a.label("v127");   a.db(127)
+    a.label("v255");   a.db(255)
+    a.label("m_a0");   a.db(0xA0)
+    a.label("m_a1");   a.db(0xA1)
+    a.label("m_a2");   a.db(0xA2)
+    a.label("m_a3");   a.db(0xA3)
+    a.label("m_a4");   a.db(0xA4)
+    a.label("m_a5");   a.db(0xA5)
+    a.label("m_a6");   a.db(0xA6)
+    a.label("m_a7");   a.db(0xA7)
+    a.label("v_fail"); a.db(0xEE)
+    a.label("out0");   a.db(0)
+    a.label("out1");   a.db(0)
+    a.label("out2");   a.db(0)
+    a.label("out3");   a.db(0)
+    a.label("out4");   a.db(0)
+    a.label("out5");   a.db(0)
+    a.label("out6");   a.db(0)
+    a.label("out7");   a.db(0)
+    a.label("fail_addr"); a.db(0)
+
+    mem = a.assemble()
+    expected = {
+        a.labels["out0"]: 0xA0,
+        a.labels["out1"]: 0xA1,
+        a.labels["out2"]: 0xA2,
+        a.labels["out3"]: 0xA3,
+        a.labels["out4"]: 0xA4,
+        a.labels["out5"]: 0xA5,
+        a.labels["out6"]: 0xA6,
+        a.labels["out7"]: 0xA7,
+        a.labels["fail_addr"]: 0,    # must remain zero
+    }
+    return mem, expected, 200, "all 8 conditional jumps (JZ/JNZ/JC/JNC/JN/JP/JV/JNV)"
+
+
+def call_pushes_pc(mem_size: int = 256) -> ProgramResult:
+    """Verify CALL pushes the return address (next-instruction PC) onto the stack."""
+    a = Asm(mem_size)
+
+    a.org(0)
+    a.label("caller")
+    a.load(0, "marker_val")
+    a.store(0, "marker_addr")     # write before CALL
+    a.label("call_site")
+    a.call("callee")
+    # If CALL did not transfer control, this fallthrough store would write 0xDD:
+    a.load(0, "noret_val")
+    a.store(0, "noret_addr")
+    a.halt()
+
+    a.label("callee")
+    a.load(0, "callee_val")
+    a.store(0, "callee_addr")
+    a.halt()
+
+    a.org(0x40)
+    a.label("marker_val");  a.db(0x11)
+    a.label("marker_addr"); a.db(0)
+    a.label("noret_val");   a.db(0xDD)
+    a.label("noret_addr");  a.db(0)
+    a.label("callee_val");  a.db(0x22)
+    a.label("callee_addr"); a.db(0)
+
+    mem = a.assemble()
+    addr_mask = mem_size - 1
+    return_addr = a.labels["call_site"] + 4         # 4-byte CALL instruction
+    expected = {
+        a.labels["marker_addr"]: 0x11,              # pre-CALL store ran
+        a.labels["callee_addr"]: 0x22,              # callee reached
+        a.labels["noret_addr"]: 0,                  # fallthrough did not run
+        (addr_mask - 2) & addr_mask: return_addr & 0xFF,         # ret LSB on stack
+        (addr_mask - 1) & addr_mask: (return_addr >> 8) & 0xFF,  # ret MSB
+    }
+    return mem, expected, 30, "CALL pushes return PC onto stack"
+
+
+def bubble_sort_4(mem_size: int = 256) -> ProgramResult:
+    """Sort a 4-byte array using unrolled compare-swap (3 passes of 3 compares)."""
+    a = Asm(mem_size)
+
+    addrs = ["a0", "a1", "a2", "a3"]
+
+    a.org(0)
+    for _outer in range(3):
+        for i in range(3):
+            x, y = addrs[i], addrs[i + 1]
+            # Load pair
+            a.load(0, x)            # R0 = A[i]
+            a.load(1, y)            # R1 = A[i+1]
+            a.cmp(0, 1)             # compare A[i] - A[i+1]
+            # If A[i] <= A[i+1] (Z=1 or C=0 from sub-style cmp), skip swap
+            # SUB sets carry when no borrow (a >= b). So:
+            #   a > b  iff  Z=0 and a >= b -> Z=0 and C=1 (the sub didn't borrow)
+            # We want to swap when a > b. JNC (no carry / borrow) means a < b -> skip swap.
+            # If a == b (Z=1) we also skip. So: jump-skip when JZ OR JNC.
+            # Easier: compute (a > b) by checking C=1 AND Z=0. Use JZ to skip on equal,
+            # then JNC to skip on a < b. Otherwise fall through to swap.
+            skip_lbl = f"skip_{_outer}_{i}"
+            a.jz(skip_lbl)          # equal -> skip
+            a.jnc(skip_lbl)         # a < b (sub borrowed) -> skip
+            # swap: store R0 -> y, R1 -> x
+            a.store(1, x)
+            a.store(0, y)
+            a.label(skip_lbl)
+    a.halt()
+
+    # Initial unsorted array; code runs to ~0xEC, so data starts at 0xF0.
+    initial = [42, 7, 200, 19]
+    a.org(0xF0)
+    for name, val in zip(addrs, initial):
+        a.label(name); a.db(val)
+
+    mem = a.assemble()
+    sorted_vals = sorted(initial)
+    expected = {a.labels[name]: v for name, v in zip(addrs, sorted_vals)}
+    return mem, expected, 800, f"bubble sort {initial} -> {sorted_vals}"
+
+
+def cross_check_mul(mem_size: int = 256) -> ProgramResult:
+    """Cross-check the threshold MUL circuit against repeated ADD."""
+    a = Asm(mem_size)
+    A_VAL = 17
+    B_VAL = 9
+    expected_product = (A_VAL * B_VAL) & 0xFF
+
+    a.org(0)
+    # --- direct multiply ---
+    a.load(0, "A")
+    a.load(1, "B")
+    a.mul(0, 1)
+    a.store(0, "out_mul")
+    # --- repeated-add multiply ---
+    a.load(0, "zero")            # acc = 0
+    a.load(1, "A")               # addend
+    a.load(2, "B")               # counter
+    a.load(3, "one")             # 1
+    a.label("rep_loop")
+    a.add(0, 1)                  # acc += A
+    a.sub(2, 3)                  # B--
+    a.jnz("rep_loop")
+    a.store(0, "out_add")
+    a.halt()
+
+    a.org(0x80)
+    a.label("A");        a.db(A_VAL)
+    a.label("B");        a.db(B_VAL)
+    a.label("zero");     a.db(0)
+    a.label("one");      a.db(1)
+    a.label("out_mul");  a.db(0)
+    a.label("out_add");  a.db(0)
+
+    mem = a.assemble()
+    expected = {
+        a.labels["out_mul"]: expected_product,
+        a.labels["out_add"]: expected_product,
+    }
+    return mem, expected, 80, f"MUL vs repeated ADD: {A_VAL} * {B_VAL} = {expected_product}"
+
+
+def div_via_repeated_sub(mem_size: int = 256) -> ProgramResult:
+    """Compute floor(A/B) and (A mod B) by repeated subtraction."""
+    A_VAL = 100
+    B_VAL = 7
+    expected_q = A_VAL // B_VAL          # 14
+    expected_r = A_VAL % B_VAL           # 2
+
+    a = Asm(mem_size)
+
+    a.org(0)
+    # ---- Repeated-subtraction division ----
+    a.load(0, "A")               # R0 = A (will become remainder)
+    a.load(1, "B")               # R1 = B (divisor)
+    a.load(2, "ZERO")            # R2 = 0 (will become quotient)
+    a.load(3, "ONE")             # R3 = 1 (increment)
+
+    a.label("loop")
+    a.cmp(0, 1)                  # CMP R0, R1; carry=1 (no-borrow) iff R0 >= R1
+    a.jnc("done")                # if R0 < R1 (carry=0), exit loop
+    a.sub(0, 1)                  # R0 -= B
+    a.add(2, 3)                  # quotient += 1
+    a.jmp("loop")
+
+    a.label("done")
+    a.store(2, "OUT_Q_RPT")      # quotient via repeated sub
+    a.store(0, "OUT_R_RPT")      # remainder via repeated sub
+
+    # ---- Direct DIV opcode for cross-check ----
+    a.load(0, "A")
+    a.load(1, "B")
+    a.dw(_enc(0x8, 0, 1, 0))     # DIV R0, R1   -> R0 = R0 / R1 (8-bit DIV)
+    a.store(0, "OUT_Q_DIV")
+    a.halt()
+
+    a.org(0x80)
+    a.label("A");          a.db(A_VAL)
+    a.label("B");          a.db(B_VAL)
+    a.label("ZERO");       a.db(0)
+    a.label("ONE");        a.db(1)
+    a.label("OUT_Q_RPT");  a.db(0)
+    a.label("OUT_R_RPT");  a.db(0)
+    a.label("OUT_Q_DIV");  a.db(0)
+
+    mem = a.assemble()
+    expected = {
+        a.labels["OUT_Q_RPT"]: expected_q,
+        a.labels["OUT_R_RPT"]: expected_r,
+        a.labels["OUT_Q_DIV"]: expected_q,
+    }
+    return mem, expected, 4 * (A_VAL // B_VAL + 4) + 12, (
+        f"{A_VAL} / {B_VAL}: quotient {expected_q} (repeated SUB) "
+        f"matches DIV opcode result; remainder {expected_r}"
+    )
+
+
+def bitwise_chain(mem_size: int = 256) -> ProgramResult:
+    """Run a chain of bitwise ops and verify each intermediate value."""
+    A = 0xCC  # 11001100
+    B = 0xF0  # 11110000
+    C = 0x0F  # 00001111
+    D = 0xAA  # 10101010
+
+    s1 = A & B               # 0xC0
+    s2 = s1 | C              # 0xCF
+    s3 = s2 ^ D              # 0x65
+    s4 = (s3 << 1) & 0xFF    # 0xCA
+    s5 = s4 >> 1             # 0x65
+
+    a = Asm(mem_size)
+    a.org(0)
+    a.load(0, "A"); a.load(1, "B"); a.and_(0, 1); a.store(0, "S1")
+    a.load(1, "C"); a.or_(0, 1);                     a.store(0, "S2")
+    a.load(1, "D"); a.xor(0, 1);                    a.store(0, "S3")
+    a.shl(0);                                        a.store(0, "S4")
+    a.shr(0);                                        a.store(0, "S5")
+    a.halt()
+
+    a.org(0x80)
+    a.label("A"); a.db(A)
+    a.label("B"); a.db(B)
+    a.label("C"); a.db(C)
+    a.label("D"); a.db(D)
+    a.label("S1"); a.db(0)
+    a.label("S2"); a.db(0)
+    a.label("S3"); a.db(0)
+    a.label("S4"); a.db(0)
+    a.label("S5"); a.db(0)
+
+    mem = a.assemble()
+    expected = {
+        a.labels["S1"]: s1,
+        a.labels["S2"]: s2,
+        a.labels["S3"]: s3,
+        a.labels["S4"]: s4,
+        a.labels["S5"]: s5,
+    }
+    return mem, expected, 30, (
+        f"bitwise chain AND/OR/XOR/SHL/SHR -> {s1:#x},{s2:#x},{s3:#x},{s4:#x},{s5:#x}"
+    )
+
+
+def flags_policy(mem_size: int = 256) -> ProgramResult:
+    """Only ADD, SUB, MUL and CMP write FLAGS; every other instruction leaves them."""
+    a = Asm(mem_size)
+
+    a.org(0)
+    # ----- Probe 1: Z=1 survives AND (nonzero result) -----
+    a.load(0, "v5"); a.load(1, "v5"); a.cmp(0, 1)      # Z=1
+    a.load(2, "v3"); a.load(3, "v1"); a.and_(2, 3)     # R2 = 3 & 1 = 1
+    a.jz("p1_ok")
+    a.load(2, "m_fail"); a.store(2, "out1"); a.jmp("p2")
+    a.label("p1_ok")
+    a.load(2, "m_b1"); a.store(2, "out1")
+
+    # ----- Probe 2: Z=0 survives XOR (zero result) -----
+    a.label("p2")
+    a.load(0, "v5"); a.load(1, "v3"); a.cmp(0, 1)      # Z=0
+    a.xor(2, 2)                                        # R2 = 0
+    a.jz("p2_fail")
+    a.load(2, "m_b2"); a.store(2, "out2"); a.jmp("p3")
+    a.label("p2_fail")
+    a.load(2, "m_fail"); a.store(2, "out2")
+
+    # ----- Probe 3: C=1 survives SHR -----
+    a.label("p3")
+    a.load(0, "v255"); a.load(1, "v1"); a.add(0, 1)    # C=1
+    a.load(2, "v3"); a.shr(2)                          # R2 = 1
+    a.jc("p3_ok")
+    a.load(2, "m_fail"); a.store(2, "out3"); a.jmp("done")
+    a.label("p3_ok")
+    a.load(2, "m_b3"); a.store(2, "out3")
+    a.label("done")
+    a.halt()
+
+    a.org(0xA0)
+    a.label("v1");     a.db(1)
+    a.label("v3");     a.db(3)
+    a.label("v5");     a.db(5)
+    a.label("v255");   a.db(255)
+    a.label("m_b1");   a.db(0xB1)
+    a.label("m_b2");   a.db(0xB2)
+    a.label("m_b3");   a.db(0xB3)
+    a.label("m_fail"); a.db(0xEE)
+    a.label("out1");   a.db(0)
+    a.label("out2");   a.db(0)
+    a.label("out3");   a.db(0)
+
+    mem = a.assemble()
+    expected = {
+        a.labels["out1"]: 0xB1,
+        a.labels["out2"]: 0xB2,
+        a.labels["out3"]: 0xB3,
+    }
+    return mem, expected, 60, "flag policy: AND/XOR/SHR leave FLAGS unchanged"
+
+
+SUITE = [
+    ("fib", lambda mem_size: fib(11, mem_size)),
+    ("sum_n", lambda mem_size: sum_n(10, mem_size)),
+    ("self_mod_jmp", lambda mem_size: self_mod_jmp(mem_size)),
+    ("all_branches", lambda mem_size: all_branches(mem_size)),
+    ("call_pushes_pc", lambda mem_size: call_pushes_pc(mem_size)),
+    ("bubble_sort_4", lambda mem_size: bubble_sort_4(mem_size)),
+    ("cross_check_mul", lambda mem_size: cross_check_mul(mem_size)),
+    ("div_via_repeated_sub", lambda mem_size: div_via_repeated_sub(mem_size)),
+    ("bitwise_chain", lambda mem_size: bitwise_chain(mem_size)),
+    ("flags_policy", lambda mem_size: flags_policy(mem_size)),
+]
+
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # this file lives in tools/
+
+
+def load_tensors(path: Path):
+    out = {}
+    with safe_open(str(path), framework="pt") as f:
+        for name in f.keys():
+            out[name] = f.get_tensor(name).float()
+    return out
+
+
+def run_program(cpu: GenericThresholdCPU, mem, max_cycles: int):
+    addr_mask = (1 << cpu.addr_bits) - 1
+    state = {
+        "pc": 0,
+        "regs": [0] * 4,
+        "flags": [0] * 4,
+        "mem": list(mem),
+        "halted": False,
+        "sp": addr_mask,
+    }
+    t0 = time.perf_counter()
+    final, cycles = cpu.run(state, max_cycles=max_cycles)
+    return final, cycles, time.perf_counter() - t0
+
+
+def check_expected(final, expected: dict) -> tuple[bool, list[str]]:
+    failures = []
+    for addr, want in expected.items():
+        got = final["mem"][addr]
+        if got != want:
+            failures.append(f"M[0x{addr:04X}] = {got} (expected {want})")
+    return (len(failures) == 0), failures
+
+
+def main_cpu() -> int:
+    parser = argparse.ArgumentParser(description="Run the CPU program suite")
+    parser.add_argument(
+        "--model", type=str,
+        default=os.path.join(REPO, "variants", "neural_computer8_small.safetensors"),
+        help="Path to .safetensors variant",
+    )
+    parser.add_argument(
+        "--only", type=str, default="",
+        help="Comma-separated subset of program names to run",
+    )
+    args = parser.parse_args()
+
+    print(f"Loading {args.model}")
+    tensors = load_tensors(Path(args.model))
+    manifest = get_manifest(tensors)
+    print(f"Manifest: data={manifest['data_bits']}-bit, addr={manifest['addr_bits']}-bit, "
+          f"mem={manifest['memory_bytes']}B")
+
+    if manifest["memory_bytes"] < 256:
+        print(f"ERROR: variant has {manifest['memory_bytes']}B memory; "
+              f"the suite needs at least 256B (scratchpad).")
+        return 2
+
+    cpu = GenericThresholdCPU(tensors)
+    only = set(s.strip() for s in args.only.split(",") if s.strip())
+
+    print()
+    print("=" * 80)
+    print(f" CPU PROGRAM SUITE  ({manifest['memory_bytes']}B mem, {manifest['data_bits']}-bit ALU)")
+    print("=" * 80)
+
+    pass_count = 0
+    fail_count = 0
+    skip_count = 0
+
+    for name, builder in SUITE:
+        if only and name not in only:
+            skip_count += 1
+            continue
+        try:
+            mem, expected, max_cycles, desc = builder(manifest["memory_bytes"])
+        except Exception as e:
+            print(f"  {name:18}  BUILD ERROR: {e}")
+            fail_count += 1
+            continue
+
+        if len(mem) != manifest["memory_bytes"]:
+            print(f"  {name:18}  SKIP (program built {len(mem)}B, "
+                  f"variant has {manifest['memory_bytes']}B)")
+            skip_count += 1
+            continue
+
+        final, cycles, elapsed = run_program(cpu, mem, max_cycles)
+        ok, failures = check_expected(final, expected)
+        if ok and not final["halted"]:
+            ok = False
+            failures.append(f"did not HALT within {max_cycles} cycles")
+
+        status = "PASS" if ok else "FAIL"
+        if ok:
+            pass_count += 1
+        else:
+            fail_count += 1
+        print(f"  {name:18}  {status}  ({cycles:>3} cyc, {elapsed:>5.2f}s)  {desc}")
+        if not ok:
+            for f in failures[:6]:
+                print(f"    - {f}")
+
+    print()
+    print("=" * 80)
+    total = pass_count + fail_count
+    print(f"  PASS: {pass_count}/{total}   FAIL: {fail_count}/{total}   SKIP: {skip_count}")
+    return 0 if fail_count == 0 else 1
+
+
+COMMANDS = {'eval': main, 'variants': main_all, 'cpu': main_cpu}
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:
+        sys.exit(COMMANDS['eval']())
+    cmd = sys.argv.pop(1)
+    sys.argv[0] += ' ' + cmd
+    sys.exit(COMMANDS[cmd]())

src/eval_all.py

@@ -1,912 +0,0 @@
-"""
-Unified evaluation harness for any threshold-computer variant.
-
-Drops the `--cpu-test` smoke test (which was hardcoded to 16-bit/64KB) and
-adds variant-aware sweep modes. The same harness handles every (data_bits,
-addr_bits) configuration: it reads the manifest from each safetensors file,
-runs the BatchedFitnessEvaluator at the right device, and reports per-file
-plus per-category results.
-
-Usage:
-    python eval_all.py path/to/file.safetensors          # one file
-    python eval_all.py variants/                          # every .safetensors in dir
-    python eval_all.py --device cpu variants/             # CPU only (default)
-    python eval_all.py --pop_size 32 variants/            # batched pop eval
-    python eval_all.py --debug path/to/file.safetensors   # per-circuit detail
-    python eval_all.py --cpu-program PATH                 # also run an assembled program
-                                                          # through the threshold CPU
-                                                          # sized to the file's manifest
-
-Exit code:
-    0 if all files PASS (fitness >= 0.9999)
-    N where N is the number of FAILing files
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import sys
-import time
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
-
-import torch
-from safetensors import safe_open
-
-# Reuse eval.py's evaluator (variant-aware)
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from eval import (
-    BatchedFitnessEvaluator,
-    create_population,
-    load_model,
-    get_manifest,
-    heaviside,
-    int_to_bits,
-    bits_to_int,
-    bits_msb_to_lsb,
-)
-
-
-# ---------------------------------------------------------------------------
-# Variant-aware threshold ALU + CPU
-# ---------------------------------------------------------------------------
-
-class GenericThresholdALU:
-    """Variant-aware threshold ALU walking the gates of a loaded variant.
-
-    8-bit primitives: add8/sub8/mul8/div8, packed bitwise and8/or8/xor8,
-    shl8/shr8, and the bit-cascade comparators via cmp8. Width-generic
-    add_n/sub_n/mul_n/cmp_n cover the 16- and 32-bit circuit families.
-    """
-
-    def __init__(self, tensors: Dict[str, torch.Tensor], data_bits: int):
-        self.T = tensors
-        self.data_bits = data_bits
-
-    def _g(self, name, inputs):
-        w = self.T[name + ".weight"].view(-1)
-        b = self.T[name + ".bias"].view(-1)
-        return int(heaviside((torch.tensor(inputs, dtype=torch.float32) * w).sum() + b).item())
-
-    def _xor_or_nand(self, prefix, inputs):
-        a, b_ = inputs
-        h_or = self._g(f"{prefix}.layer1.or", [a, b_])
-        h_nand = self._g(f"{prefix}.layer1.nand", [a, b_])
-        return self._g(f"{prefix}.layer2", [h_or, h_nand])
-
-    def _fa(self, prefix, a, b, cin):
-        s1 = self._xor_or_nand(f"{prefix}.ha1.sum", [a, b])
-        c1 = self._g(f"{prefix}.ha1.carry", [a, b])
-        s2 = self._xor_or_nand(f"{prefix}.ha2.sum", [s1, cin])
-        c2 = self._g(f"{prefix}.ha2.carry", [s1, cin])
-        cout = self._g(f"{prefix}.carry_or", [c1, c2])
-        return s2, cout
-
-    def add8(self, a, b):
-        a_lsb = list(reversed(int_to_bits(a, 8)))
-        b_lsb = list(reversed(int_to_bits(b, 8)))
-        carry = 0
-        s_lsb = []
-        for i in range(8):
-            s, carry = self._fa(f"arithmetic.ripplecarry8bit.fa{i}", a_lsb[i], b_lsb[i], carry)
-            s_lsb.append(s)
-        return bits_to_int(list(reversed(s_lsb))), carry
-
-    def sub8(self, a, b):
-        a_lsb = list(reversed(int_to_bits(a, 8)))
-        b_lsb = list(reversed(int_to_bits(b, 8)))
-        carry = 1
-        d_lsb = []
-        for i in range(8):
-            notb = self._g(f"arithmetic.sub8bit.notb{i}", [b_lsb[i]])
-            x1 = self._xor_or_nand(f"arithmetic.sub8bit.fa{i}.xor1", [a_lsb[i], notb])
-            x2 = self._xor_or_nand(f"arithmetic.sub8bit.fa{i}.xor2", [x1, carry])
-            and1 = self._g(f"arithmetic.sub8bit.fa{i}.and1", [a_lsb[i], notb])
-            and2 = self._g(f"arithmetic.sub8bit.fa{i}.and2", [x1, carry])
-            carry = self._g(f"arithmetic.sub8bit.fa{i}.or_carry", [and1, and2])
-            d_lsb.append(x2)
-        return bits_to_int(list(reversed(d_lsb))), carry
-
-    _CMP_KIND = {"greaterthan": "gt", "lessthan": "lt", "eq": "eq", "equality": "eq",
-                 "greaterorequal": "ge", "lessorequal": "le"}
-
-    def _cmp_bit_cascade(self, cmp_prefix: str, finals: Dict[str, str],
-                         a_bits_msb: List[int], b_bits_msb: List[int], kind: str) -> int:
-        """Walk an add_bit_cascade_compare structure (bit 0 is the MSB)."""
-        bits = len(a_bits_msb)
-        bit_gt, bit_lt, bit_eq = [], [], []
-        for i in range(bits):
-            ab = [a_bits_msb[i], b_bits_msb[i]]
-            bit_gt.append(self._g(f"{cmp_prefix}.bit{i}.gt", ab))
-            bit_lt.append(self._g(f"{cmp_prefix}.bit{i}.lt", ab))
-            eq_and = self._g(f"{cmp_prefix}.bit{i}.eq.layer1.and", ab)
-            eq_nor = self._g(f"{cmp_prefix}.bit{i}.eq.layer1.nor", ab)
-            bit_eq.append(self._g(f"{cmp_prefix}.bit{i}.eq", [eq_and, eq_nor]))
-        cas_gt, cas_lt = [bit_gt[0]], [bit_lt[0]]
-        for i in range(1, bits):
-            eq_pref = self._g(f"{cmp_prefix}.cascade.eq_prefix.bit{i}", bit_eq[:i])
-            cas_gt.append(self._g(f"{cmp_prefix}.cascade.gt.bit{i}", [eq_pref, bit_gt[i]]))
-            cas_lt.append(self._g(f"{cmp_prefix}.cascade.lt.bit{i}", [eq_pref, bit_lt[i]]))
-        if kind == "gt":
-            return self._g(finals["gt"], cas_gt)
-        if kind == "lt":
-            return self._g(finals["lt"], cas_lt)
-        if kind == "eq":
-            return self._g(finals["eq"], bit_eq)
-        if kind == "ge":
-            lt = self._g(finals["lt"], cas_lt)
-            not_lt = self._g(finals["ge"] + ".not_lt", [lt])
-            return self._g(finals["ge"], [not_lt])
-        if kind == "le":
-            gt = self._g(finals["gt"], cas_gt)
-            not_gt = self._g(finals["le"] + ".not_gt", [gt])
-            return self._g(finals["le"], [not_gt])
-        raise ValueError(kind)
-
-    def cmp8(self, a, b, kind):
-        return self.cmp_n(a, b, kind, 8)
-
-    def mul8(self, a, b):
-        ab = int_to_bits(a, 8)
-        bb = int_to_bits(b, 8)
-        result = 0
-        for j in range(8):
-            if bb[j] == 0:
-                continue
-            row = 0
-            for i in range(8):
-                pp = self._g(f"alu.alu8bit.mul.pp.a{i}b{j}", [ab[i], bb[j]])
-                row |= (pp << (7 - i))
-            shift = 7 - j
-            result, _ = self.add8(result & 0xFF, (row << shift) & 0xFF)
-        return result & 0xFF
-
-    def _packed_pair_op(self, name: str, a: int, b: int) -> int:
-        """8 parallel 2-input gates stored packed: weight [16], bias [8]."""
-        a_bits = int_to_bits(a, 8)
-        b_bits = int_to_bits(b, 8)
-        w = self.T[f"{name}.weight"].view(-1)
-        bias = self.T[f"{name}.bias"].view(-1)
-        out = []
-        for bit in range(8):
-            inp = torch.tensor([float(a_bits[bit]), float(b_bits[bit])])
-            out.append(int(heaviside((inp * w[bit * 2:bit * 2 + 2]).sum() + bias[bit]).item()))
-        return bits_to_int(out)
-
-    def and8(self, a, b):
-        return self._packed_pair_op("alu.alu8bit.and", a, b)
-
-    def or8(self, a, b):
-        return self._packed_pair_op("alu.alu8bit.or", a, b)
-
-    def xor8(self, a, b):
-        a_bits = int_to_bits(a, 8)
-        b_bits = int_to_bits(b, 8)
-        w_or = self.T["alu.alu8bit.xor.layer1.or.weight"].view(-1)
-        b_or = self.T["alu.alu8bit.xor.layer1.or.bias"].view(-1)
-        w_nand = self.T["alu.alu8bit.xor.layer1.nand.weight"].view(-1)
-        b_nand = self.T["alu.alu8bit.xor.layer1.nand.bias"].view(-1)
-        w2 = self.T["alu.alu8bit.xor.layer2.weight"].view(-1)
-        b2 = self.T["alu.alu8bit.xor.layer2.bias"].view(-1)
-        out = []
-        for bit in range(8):
-            inp = torch.tensor([float(a_bits[bit]), float(b_bits[bit])])
-            h_or = heaviside((inp * w_or[bit * 2:bit * 2 + 2]).sum() + b_or[bit])
-            h_nand = heaviside((inp * w_nand[bit * 2:bit * 2 + 2]).sum() + b_nand[bit])
-            hidden = torch.stack([h_or, h_nand])
-            out.append(int(heaviside((hidden * w2[bit * 2:bit * 2 + 2]).sum() + b2[bit]).item()))
-        return bits_to_int(out)
-
-    def shl8(self, a):
-        a_bits = int_to_bits(a, 8)
-        out = []
-        for bit in range(8):
-            src = float(a_bits[bit + 1]) if bit < 7 else 0.0
-            out.append(self._g(f"alu.alu8bit.shl.bit{bit}", [src]))
-        return bits_to_int(out)
-
-    def shr8(self, a):
-        a_bits = int_to_bits(a, 8)
-        out = []
-        for bit in range(8):
-            src = float(a_bits[bit - 1]) if bit > 0 else 0.0
-            out.append(self._g(f"alu.alu8bit.shr.bit{bit}", [src]))
-        return bits_to_int(out)
-
-    def div8(self, a, b):
-        """8-bit restoring division through the per-stage bit-cascade GE
-        comparators and the sub8 subtractor. Returns (quotient, remainder);
-        divide-by-zero yields (0xFF, a)."""
-        if b == 0:
-            return 0xFF, a
-        a_bits = int_to_bits(a, 8)
-        div_bits = int_to_bits(b, 8)
-        quotient = 0
-        remainder = 0
-        for stage in range(8):
-            remainder = ((remainder << 1) | a_bits[stage]) & 0xFF
-            prefix = f"alu.alu8bit.div.stage{stage}"
-            finals = {
-                "gt": f"{prefix}.cmp_bc.gt",
-                "lt": f"{prefix}.cmp_bc.lt",
-                "eq": f"{prefix}.cmp_bc.eq",
-                "ge": f"{prefix}.cmp",
-                "le": f"{prefix}.cmp_bc.le",
-            }
-            ge = self._cmp_bit_cascade(f"{prefix}.cmp_bc", finals,
-                                       int_to_bits(remainder, 8), div_bits, "ge")
-            if ge:
-                remainder, _ = self.sub8(remainder, b)
-                quotient = (quotient << 1) | 1
-            else:
-                quotient = quotient << 1
-        return quotient & 0xFF, remainder & 0xFF
-
-    # ----- N-bit primitives (for 16-bit and 32-bit variants) ----------------
-
-    def add_n(self, a: int, b: int, bits: int):
-        """Width-generic ripple-carry add via arithmetic.ripplecarry{N}bit."""
-        prefix = f"arithmetic.ripplecarry{bits}bit"
-        a_lsb = list(reversed(int_to_bits(a, bits)))
-        b_lsb = list(reversed(int_to_bits(b, bits)))
-        carry = 0
-        s_lsb = []
-        for i in range(bits):
-            s, carry = self._fa(f"{prefix}.fa{i}", a_lsb[i], b_lsb[i], carry)
-            s_lsb.append(s)
-        return bits_to_int(list(reversed(s_lsb))), carry
-
-    def sub_n(self, a: int, b: int, bits: int):
-        """N-bit two's-complement subtract via arithmetic.sub{N}bit (N >= 16).
-
-        Structure (per build.add_sub_nbits): N NOT gates + N standard full adders.
-        """
-        prefix = f"arithmetic.sub{bits}bit"
-        a_lsb = list(reversed(int_to_bits(a, bits)))
-        b_lsb = list(reversed(int_to_bits(b, bits)))
-        # NOT each B bit
-        notb = [self._g(f"{prefix}.not_b.bit{i}", [b_lsb[i]]) for i in range(bits)]
-        carry = 1  # carry-in = 1 for two's-complement
-        d_lsb = []
-        for i in range(bits):
-            s, carry = self._fa(f"{prefix}.fa{i}", a_lsb[i], notb[i], carry)
-            d_lsb.append(s)
-        return bits_to_int(list(reversed(d_lsb))), carry
-
-    def cmp_n(self, a: int, b: int, kind: str, bits: int):
-        """N-bit unsigned comparison via the bit-cascade comparator family
-        (arithmetic.cmp{N}bit.* per build.add_bit_cascade_compare)."""
-        short = self._CMP_KIND[kind]
-        finals = {
-            "gt": f"arithmetic.greaterthan{bits}bit",
-            "lt": f"arithmetic.lessthan{bits}bit",
-            "eq": f"arithmetic.equality{bits}bit",
-            "ge": f"arithmetic.greaterorequal{bits}bit",
-            "le": f"arithmetic.lessorequal{bits}bit",
-        }
-        return self._cmp_bit_cascade(f"arithmetic.cmp{bits}bit", finals,
-                                     int_to_bits(a, bits), int_to_bits(b, bits), short)
-
-    def mul_n(self, a: int, b: int, bits: int):
-        """N-bit shift-add multiply (low N bits only)."""
-        ab = int_to_bits(a, bits)
-        bb = int_to_bits(b, bits)
-        mask = (1 << bits) - 1
-        result = 0
-        for j in range(bits):
-            if bb[j] == 0:
-                continue
-            row = 0
-            for i in range(bits):
-                pp = self._g(f"alu.alu{bits}bit.mul.pp.a{i}b{j}", [ab[i], bb[j]])
-                row |= (pp << (bits - 1 - i))
-            shift = (bits - 1) - j
-            result, _ = self.add_n(result & mask, (row << shift) & mask, bits)
-        return result & mask
-
-
-class GenericThresholdCPU:
-    """Variant-aware CPU runtime. Sized from the variant's manifest."""
-
-    def __init__(self, tensors: Dict[str, torch.Tensor]):
-        self.T = tensors
-        m = get_manifest(tensors)
-        self.data_bits = m["data_bits"]
-        self.addr_bits = m["addr_bits"]
-        self.mem_bytes = m["memory_bytes"]
-        # 8-bit CPU primitives (ripplecarry8bit, sub8bit, alu.alu8bit.*, memory.*,
-        # control.*) are present in every variant regardless of manifest data_bits.
-        # Wider data widths simply add additional standalone ALU primitives.
-        if self.mem_bytes == 0:
-            raise NotImplementedError(
-                "Pure-ALU variants have no memory; cannot run CPU programs"
-            )
-        self.alu = GenericThresholdALU(tensors, 8)
-
-    def _addr_decode(self, addr):
-        bits = torch.tensor(int_to_bits(addr, self.addr_bits), dtype=torch.float32)
-        w = self.T["memory.addr_decode.weight"]
-        b = self.T["memory.addr_decode.bias"]
-        return heaviside((w * bits).sum(dim=1) + b)
-
-    def mem_read(self, mem, addr):
-        sel = self._addr_decode(addr)
-        mem_bits = torch.tensor(
-            [int_to_bits(byte, 8) for byte in mem], dtype=torch.float32
-        )
-        and_w = self.T["memory.read.and.weight"]
-        and_b = self.T["memory.read.and.bias"]
-        or_w = self.T["memory.read.or.weight"]
-        or_b = self.T["memory.read.or.bias"]
-        out = []
-        for bit in range(8):
-            inp = torch.stack([mem_bits[:, bit], sel], dim=1)
-            and_out = heaviside((inp * and_w[bit]).sum(dim=1) + and_b[bit])
-            out.append(int(heaviside((and_out * or_w[bit]).sum() + or_b[bit]).item()))
-        return bits_to_int(out)
-
-    def mem_write(self, mem, addr, value):
-        sel = self._addr_decode(addr)
-        data_bits = torch.tensor(int_to_bits(value, 8), dtype=torch.float32)
-        mem_bits = torch.tensor(
-            [int_to_bits(byte, 8) for byte in mem], dtype=torch.float32
-        )
-        sel_w = self.T["memory.write.sel.weight"]
-        sel_b = self.T["memory.write.sel.bias"]
-        nsel_w = self.T["memory.write.nsel.weight"].squeeze(1)
-        nsel_b = self.T["memory.write.nsel.bias"]
-        and_old_w = self.T["memory.write.and_old.weight"]
-        and_old_b = self.T["memory.write.and_old.bias"]
-        and_new_w = self.T["memory.write.and_new.weight"]
-        and_new_b = self.T["memory.write.and_new.bias"]
-        or_w = self.T["memory.write.or.weight"]
-        or_b = self.T["memory.write.or.bias"]
-        we = torch.ones_like(sel)
-        sel_inp = torch.stack([sel, we], dim=1)
-        write_sel = heaviside((sel_inp * sel_w).sum(dim=1) + sel_b)
-        nsel = heaviside(write_sel * nsel_w + nsel_b)
-        for bit in range(8):
-            old = mem_bits[:, bit]
-            data_bit = data_bits[bit].expand(self.mem_bytes)
-            inp_old = torch.stack([old, nsel], dim=1)
-            inp_new = torch.stack([data_bit, write_sel], dim=1)
-            and_old = heaviside((inp_old * and_old_w[:, bit]).sum(dim=1) + and_old_b[:, bit])
-            and_new = heaviside((inp_new * and_new_w[:, bit]).sum(dim=1) + and_new_b[:, bit])
-            or_inp = torch.stack([and_old, and_new], dim=1)
-            new_bit = heaviside((or_inp * or_w[:, bit]).sum(dim=1) + or_b[:, bit])
-            mem_bits[:, bit] = new_bit
-        return [bits_to_int([int(b) for b in mem_bits[i].tolist()]) for i in range(self.mem_bytes)]
-
-    # Conditions 0..7 map to (mux circuit, flag index into [Z, N, C, V]).
-    # Odd conditions are the negated forms; the mux select is the complemented
-    # flag (the circuits are plain per-bit muxes -- see control.* .inputs,
-    # which name the select $not_zero / $not_carry / ... for the odd forms).
-    _JCC = [("control.jz", 0), ("control.jnz", 0), ("control.jc", 2), ("control.jnc", 2),
-            ("control.jn", 1), ("control.jp", 1), ("control.jv", 3), ("control.jnv", 3)]
-
-    def _jcc_pc(self, circuit: str, pc: int, target: int, sel: int) -> int:
-        """Per-bit 2:1 mux over the PC: sel ? target : pc, addr_bits wide."""
-        pc_bits = int_to_bits(pc, self.addr_bits)
-        t_bits = int_to_bits(target, self.addr_bits)
-        out = []
-        for bit in range(self.addr_bits):
-            bp = f"{circuit}.bit{bit}"
-            not_sel = self.alu._g(f"{bp}.not_sel", [float(sel)])
-            and_a = self.alu._g(f"{bp}.and_a", [float(pc_bits[bit]), not_sel])
-            and_b = self.alu._g(f"{bp}.and_b", [float(t_bits[bit]), float(sel)])
-            out.append(self.alu._g(f"{bp}.or", [and_a, and_b]))
-        return bits_to_int(out)
-
-    def _sp_dec(self, sp: int) -> int:
-        """SP - 1 through the control.push.sp_dec borrow chain. Gate bit index
-        is MSB-first (bit addr_bits-1 is the LSB); the bit complement feeding
-        each borrow AND is fixed wiring, as in the gate fitness suite."""
-        bits = int_to_bits(sp, self.addr_bits)
-        out = [0] * self.addr_bits
-        borrow = 1
-        for bit in range(self.addr_bits - 1, -1, -1):
-            bp = f"control.push.sp_dec.bit{bit}"
-            h_or = self.alu._g(f"{bp}.xor.layer1.or", [float(bits[bit]), float(borrow)])
-            h_nand = self.alu._g(f"{bp}.xor.layer1.nand", [float(bits[bit]), float(borrow)])
-            out[bit] = self.alu._g(f"{bp}.xor.layer2", [h_or, h_nand])
-            borrow = self.alu._g(f"{bp}.borrow", [float(1 - bits[bit]), float(borrow)])
-        return bits_to_int(out)
-
-    def _decode_op(self, opcode):
-        """4-to-16 opcode one-hot through the gate decoder."""
-        ob = [float((opcode >> j) & 1) for j in range(4)]
-        return [self.alu._g(f"control.decode.op{n}", ob) for n in range(16)]
-
-    def _inc(self, pc, name, start):
-        """PC + 2^start through the gate increment chain (LSB-first)."""
-        ab = self.addr_bits
-        pcb = [(pc >> k) & 1 for k in range(ab)]
-        out = [0] * ab
-        carry = 0
-        for k in range(ab):
-            if k < start:
-                out[k] = self.alu._g(f"control.pcnext.{name}.bit{k}", [float(pcb[k])])
-            else:
-                cin = 1 if k == start else carry
-                o = self.alu._g(f"control.pcnext.{name}.bit{k}.xor.layer1.or", [float(pcb[k]), float(cin)])
-                nd = self.alu._g(f"control.pcnext.{name}.bit{k}.xor.layer1.nand", [float(pcb[k]), float(cin)])
-                out[k] = self.alu._g(f"control.pcnext.{name}.bit{k}.xor.layer2", [o, nd])
-                carry = self.alu._g(f"control.pcnext.{name}.bit{k}.carry", [float(pcb[k]), float(cin)])
-        return sum(out[k] << k for k in range(ab))
-
-    def _pcnext(self, pc2, pc4, addr, jcc, use_pc4, use_addr, use_jcc):
-        """Next-PC priority mux through the gates: use_addr ? addr :
-        (use_jcc ? jcc : (use_pc4 ? pc4 : pc2))."""
-        ab = self.addr_bits
-        p2 = [(pc2 >> k) & 1 for k in range(ab)]
-        p4 = [(pc4 >> k) & 1 for k in range(ab)]
-        aB = [(addr >> k) & 1 for k in range(ab)]
-        jB = [(jcc >> k) & 1 for k in range(ab)]
-        out = [0] * ab
-        for k in range(ab):
-            ns = self.alu._g(f"control.pcnext.m_pc4.bit{k}.not_sel", [float(use_pc4)])
-            aa = self.alu._g(f"control.pcnext.m_pc4.bit{k}.and_a", [float(p2[k]), ns])
-            bb = self.alu._g(f"control.pcnext.m_pc4.bit{k}.and_b", [float(p4[k]), float(use_pc4)])
-            m1 = self.alu._g(f"control.pcnext.m_pc4.bit{k}.or", [aa, bb])
-            ns = self.alu._g(f"control.pcnext.m_jcc.bit{k}.not_sel", [float(use_jcc)])
-            aa = self.alu._g(f"control.pcnext.m_jcc.bit{k}.and_a", [float(m1), ns])
-            bb = self.alu._g(f"control.pcnext.m_jcc.bit{k}.and_b", [float(jB[k]), float(use_jcc)])
-            m2 = self.alu._g(f"control.pcnext.m_jcc.bit{k}.or", [aa, bb])
-            ns = self.alu._g(f"control.pcnext.m_addr.bit{k}.not_sel", [float(use_addr)])
-            aa = self.alu._g(f"control.pcnext.m_addr.bit{k}.and_a", [float(m2), ns])
-            bb = self.alu._g(f"control.pcnext.m_addr.bit{k}.and_b", [float(aB[k]), float(use_addr)])
-            out[k] = self.alu._g(f"control.pcnext.m_addr.bit{k}.or", [aa, bb])
-        return sum(out[k] << k for k in range(ab))
-
-    def step(self, state):
-        if state["halted"]:
-            return state
-        s = dict(state)
-        s["mem"] = state["mem"][:]
-        s["regs"] = state["regs"][:]
-        s["flags"] = state["flags"][:]
-        addr_mask = (1 << self.addr_bits) - 1
-        pc = s["pc"]
-        hi = self.mem_read(s["mem"], pc & addr_mask)
-        lo = self.mem_read(s["mem"], (pc + 1) & addr_mask)
-        ir = ((hi & 0xFF) << 8) | (lo & 0xFF)
-        opcode = (ir >> 12) & 0xF
-        oh = self._decode_op(opcode)                 # gate opcode decode (one-hots)
-        rd = (ir >> 10) & 0x3
-        rs = (ir >> 8) & 0x3
-        imm = ir & 0xFF
-        addr = None
-        if oh[0xA] or oh[0xB] or oh[0xC] or oh[0xD] or oh[0xE]:
-            ah = self.mem_read(s["mem"], (pc + 2) & addr_mask)
-            al = self.mem_read(s["mem"], (pc + 3) & addr_mask)
-            addr = (((ah & 0xFF) << 8) | (al & 0xFF)) & addr_mask
-        pc2 = self._inc(pc, "pc2", 1)                # PC+2 through the gate chain
-        pc4 = self._inc(pc, "pc4", 2)                # PC+4 through the gate chain
-        a = s["regs"][rd]
-        b = s["regs"][rs]
-        result = a
-        carry = 0
-        overflow = 0
-        write_result = True
-        jcc_val = 0
-        if oh[0x0]:
-            result, carry = self.alu.add8(a, b)
-            overflow = 1 if (((a ^ result) & (b ^ result)) & 0x80) else 0
-        elif oh[0x1]:
-            result, carry = self.alu.sub8(a, b)
-            overflow = 1 if (((a ^ b) & (a ^ result)) & 0x80) else 0
-        elif oh[0x2]:
-            result = self.alu.and8(a, b)
-        elif oh[0x3]:
-            result = self.alu.or8(a, b)
-        elif oh[0x4]:
-            result = self.alu.xor8(a, b)
-        elif oh[0x5]:
-            result = self.alu.shl8(a)
-        elif oh[0x6]:
-            result = self.alu.shr8(a)
-        elif oh[0x7]:
-            result = self.alu.mul8(a, b)
-        elif oh[0x8]:
-            result, _ = self.alu.div8(a, b)
-        elif oh[0x9]:                                # CMP: set flags only
-            r2, carry = self.alu.sub8(a, b)
-            z = 1 if r2 == 0 else 0
-            n = 1 if (r2 & 0x80) else 0
-            v = 1 if (((a ^ b) & (a ^ r2)) & 0x80) else 0
-            s["flags"] = [z, n, carry, v]
-            write_result = False
-        elif oh[0xA]:                                # LOAD
-            result = self.mem_read(s["mem"], addr)
-        elif oh[0xB]:                                # STORE
-            s["mem"] = self.mem_write(s["mem"], addr, b & 0xFF)
-            write_result = False
-        elif oh[0xC]:                                # JMP (PC = addr via pcnext)
-            write_result = False
-        elif oh[0xD]:                                # JCC (PC via jcc mux + pcnext)
-            cond = imm & 0x7
-            circuit, flag_idx = self._JCC[cond]
-            flag = s["flags"][flag_idx]
-            sel = flag if cond % 2 == 0 else 1 - flag
-            jcc_val = self._jcc_pc(circuit, pc4, addr, sel)
-            write_result = False
-        elif oh[0xE]:                                # CALL: push PC+4, PC = addr
-            ret_addr = pc4 & 0xFFFF
-            sp = s.get("sp", addr_mask)
-            sp = self._sp_dec(sp)
-            s["mem"] = self.mem_write(s["mem"], sp, (ret_addr >> 8) & 0xFF)
-            sp = self._sp_dec(sp)
-            s["mem"] = self.mem_write(s["mem"], sp, ret_addr & 0xFF)
-            s["sp"] = sp
-            write_result = False
-        elif oh[0xF]:                                # HALT
-            s["halted"] = True
-            return s
-
-        if write_result:
-            s["regs"][rd] = result & 0xFF
-        if oh[0x0] or oh[0x1] or oh[0x7]:
-            z = 1 if (result & 0xFF) == 0 else 0
-            n = 1 if (result & 0x80) else 0
-            s["flags"] = [z, n, carry, overflow]
-        # PC sequencing through the gate mux.
-        use_pc4 = 1 if (oh[0xA] or oh[0xB]) else 0
-        use_addr = 1 if (oh[0xC] or oh[0xE]) else 0
-        s["pc"] = self._pcnext(pc2, pc4, addr or 0, jcc_val, use_pc4, use_addr, oh[0xD])
-        return s
-
-    def run(self, state, max_cycles=200):
-        s = state
-        cycles = 0
-        while not s["halted"] and cycles < max_cycles:
-            s = self.step(s)
-            cycles += 1
-        return s, cycles
-
-
-def _encode_instr(opcode, rd, rs, imm):
-    return ((opcode & 0xF) << 12) | ((rd & 0x3) << 10) | ((rs & 0x3) << 8) | (imm & 0xFF)
-
-
-def _w16(mem, addr, value):
-    mem[addr] = (value >> 8) & 0xFF
-    mem[addr + 1] = value & 0xFF
-
-
-PROGRAM_MIN_BYTES = 0x84  # code 0x00..0x1F + data 0x80..0x83
-
-
-def builtin_program(addr_bits: int) -> Tuple[List[int], int]:
-    """Sum 5+4+3+2+1 via a loop. Returns (mem, expected_result_at_0x83).
-
-    Compact layout: code at 0x00..0x1F (32 bytes), data at 0x80..0x83 (4 bytes).
-    Total footprint 132 bytes -- fits within scratchpad (256 B) and larger.
-    Requires addr_bits >= 8.
-    """
-    if (1 << addr_bits) < PROGRAM_MIN_BYTES:
-        raise ValueError(f"addr_bits={addr_bits} too small for builtin program")
-    mem = [0] * (1 << addr_bits)
-    mem[0x80] = 5  # initial counter
-    mem[0x81] = 1  # decrement
-    mem[0x82] = 0  # zero (for compare and accumulator init)
-    # mem[0x83] is the output
-    _w16(mem, 0x0000, _encode_instr(0xA, 1, 0, 0)); _w16(mem, 0x0002, 0x0080)
-    _w16(mem, 0x0004, _encode_instr(0xA, 2, 0, 0)); _w16(mem, 0x0006, 0x0081)
-    _w16(mem, 0x0008, _encode_instr(0xA, 3, 0, 0)); _w16(mem, 0x000A, 0x0082)
-    _w16(mem, 0x000C, _encode_instr(0xA, 0, 0, 0)); _w16(mem, 0x000E, 0x0082)
-    _w16(mem, 0x0010, _encode_instr(0x0, 0, 1, 0))
-    _w16(mem, 0x0012, _encode_instr(0x1, 1, 2, 0))
-    _w16(mem, 0x0014, _encode_instr(0x9, 1, 3, 0))
-    _w16(mem, 0x0016, _encode_instr(0xD, 0, 0, 0x01)); _w16(mem, 0x0018, 0x0010)
-    _w16(mem, 0x001A, _encode_instr(0xB, 0, 0, 0)); _w16(mem, 0x001C, 0x0083)
-    _w16(mem, 0x001E, _encode_instr(0xF, 0, 0, 0))
-    return mem, 15
-
-
-# ---------------------------------------------------------------------------
-# Eval driver
-# ---------------------------------------------------------------------------
-
-def _file_fingerprint(path: Path) -> str:
-    """Stable cache key for a safetensors file: sha256 of its content.
-
-    Hashes are content-addressed so renaming a file doesn't blow the cache,
-    but mtime-only would re-key on every clone of the repo. The sha256 of a
-    30 MB safetensors finishes in tens of milliseconds — small compared to
-    a 5,900-test fitness run.
-    """
-    import hashlib
-    h = hashlib.sha256()
-    with open(path, "rb") as f:
-        for chunk in iter(lambda: f.read(1 << 20), b""):
-            h.update(chunk)
-    return h.hexdigest()
-
-
-def _cache_key(path: Path, opts: Dict[str, Any]) -> str:
-    """Cache key combining file content with the relevant evaluation options."""
-    fp = _file_fingerprint(path)
-    opt_str = json.dumps(opts, sort_keys=True)
-    import hashlib
-    suffix = hashlib.sha256(opt_str.encode("utf-8")).hexdigest()[:8]
-    return f"{fp}_{suffix}"
-
-
-def _load_cache(cache_dir: Path, key: str) -> Dict[str, Any] | None:
-    p = cache_dir / f"{key}.json"
-    if not p.exists():
-        return None
-    try:
-        return json.loads(p.read_text(encoding="utf-8"))
-    except (json.JSONDecodeError, OSError):
-        return None
-
-
-def _save_cache(cache_dir: Path, key: str, payload: Dict[str, Any]) -> None:
-    cache_dir.mkdir(parents=True, exist_ok=True)
-    p = cache_dir / f"{key}.json"
-    try:
-        p.write_text(json.dumps(payload, indent=2, default=str), encoding="utf-8")
-    except OSError:
-        pass
-
-
-def list_safetensors(path: Path) -> List[Path]:
-    if path.is_file():
-        return [path]
-    if path.is_dir():
-        return sorted(p for p in path.glob("*.safetensors") if p.is_file())
-    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",
-    "reflect": "reflect.py",
-    "attractor": "tools/test_attractor.py",
-    "reversible": "src/reversible.py",
-    "ca": "src/ca.py",
-    "tile": "src/tile.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}
-    # 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"):
-        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))
-    except Exception as e:
-        out.update(error=f"load failed: {e}", status="ERROR")
-        return out
-
-    manifest = get_manifest(tensors)
-    out.update(
-        size_mb=path.stat().st_size / (1024 * 1024),
-        tensors=len(tensors),
-        params=sum(t.numel() for t in tensors.values()),
-        manifest=manifest,
-    )
-
-    # Move to device
-    tensors = {k: v.to(device) for k, v in tensors.items()}
-
-    try:
-        evaluator = BatchedFitnessEvaluator(device=device, model_path=str(path), tensors=tensors)
-        population = create_population(tensors, pop_size=pop_size, device=device)
-        t0 = time.perf_counter()
-        fitness = evaluator.evaluate(population, debug=debug)
-        elapsed = time.perf_counter() - t0
-        f0 = float(fitness[0].item()) if pop_size == 1 else float(fitness.mean().item())
-        out.update(
-            fitness=f0,
-            total_tests=evaluator.total_tests,
-            elapsed_s=elapsed,
-            categories={k: (float(v[0]), int(v[1])) for k, v in evaluator.category_scores.items()},
-            status="PASS" if f0 >= 0.9999 else "FAIL",
-        )
-    except Exception as e:
-        out.update(error=f"eval failed: {type(e).__name__}: {e}", status="ERROR")
-        return out
-
-    # Optional: CPU program test (8-bit CPU primitives are in every variant)
-    if run_cpu_program:
-        if manifest["memory_bytes"] >= PROGRAM_MIN_BYTES:
-            try:
-                cpu_tensors = {k: v.cpu() for k, v in tensors.items()}
-                cpu = GenericThresholdCPU(cpu_tensors)
-                mem, expected = builtin_program(manifest["addr_bits"])
-                state = {"pc": 0, "regs": [0] * 4, "flags": [0] * 4, "mem": mem, "halted": False}
-                t0 = time.perf_counter()
-                final, cycles = cpu.run(state, max_cycles=200)
-                cpu_elapsed = time.perf_counter() - t0
-                got = final["mem"][0x83]
-                out["cpu_program"] = {
-                    "ok": got == expected,
-                    "got": got,
-                    "expected": expected,
-                    "cycles": cycles,
-                    "elapsed_s": cpu_elapsed,
-                }
-                if got != expected:
-                    out["status"] = "FAIL"
-            except Exception as e:
-                out["cpu_program"] = {"error": str(e)}
-        else:
-            out["cpu_program"] = {"skipped": f"mem={manifest['memory_bytes']}B < {PROGRAM_MIN_BYTES}"}
-
-        # Wider-ALU chain test for 16/32-bit variants
-        bits = manifest["data_bits"]
-        if bits in (16, 32):
-            try:
-                alu_tensors = {k: v.cpu() for k, v in tensors.items()}
-                alu = GenericThresholdALU(alu_tensors, bits)
-                t0 = time.perf_counter()
-                if bits == 16:
-                    x, y = 1234, 5678
-                    z, _ = alu.add_n(x, y, 16);          assert z == (x + y) & 0xFFFF
-                    w, _ = alu.sub_n(z, x, 16);          assert w == (z - x) & 0xFFFF, (w, z - x)
-                    gt = alu.cmp_n(z, x, "greaterthan", 16); assert gt == 1
-                    lt = alu.cmp_n(x, z, "lessthan",   16);  assert lt == 1
-                    eq = alu.cmp_n(w, y, "eq",         16);  assert eq == 1
-                    p   = alu.mul_n(123, 5, 16);          assert p == (123 * 5) & 0xFFFF
-                else:  # 32
-                    x, y = 1_000_000, 999_000
-                    z, _ = alu.sub_n(x, y, 32);          assert z == 1_000
-                    s, _ = alu.add_n(z, x, 32);          assert s == 1_001_000
-                    p    = alu.mul_n(z, 100, 32);        assert p == 100_000
-                    gt = alu.cmp_n(x, y, "greaterthan", 32); assert gt == 1
-                    lt = alu.cmp_n(y, x, "lessthan",   32);  assert lt == 1
-                    eq = alu.cmp_n(p, 100_000, "equality", 32); assert eq == 1
-                chain_dt = time.perf_counter() - t0
-                out[f"alu_chain_{bits}"] = {"ok": True, "elapsed_s": chain_dt}
-            except AssertionError as e:
-                out[f"alu_chain_{bits}"] = {"ok": False, "error": f"chain mismatch: {e}"}
-                out["status"] = "FAIL"
-            except Exception as e:
-                out[f"alu_chain_{bits}"] = {"ok": False, "error": f"{type(e).__name__}: {e}"}
-                out["status"] = "FAIL"
-
-    return out
-
-
-def print_row(r: Dict, show_cpu: bool) -> None:
-    if r.get("status") == "SKIP":
-        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]}")
-        return
-    m = r["manifest"]
-    fit = f"{r['fitness']:.4f}" if r.get("fitness") is not None else "n/a"
-    cpu_col = ""
-    if show_cpu and "cpu_program" in r:
-        cp = r["cpu_program"]
-        if cp.get("ok"):
-            cpu_col = f"  CPU OK ({cp['cycles']}cyc/{cp['elapsed_s']:.1f}s)"
-        elif "skipped" in cp:
-            cpu_col = f"  CPU SKIP"
-        elif "error" in cp:
-            cpu_col = f"  CPU ERR"
-        else:
-            cpu_col = f"  CPU FAIL ({cp.get('got')}!={cp.get('expected')})"
-    chain_col = ""
-    if show_cpu:
-        for bits in (16, 32):
-            key = f"alu_chain_{bits}"
-            if key in r:
-                ch = r[key]
-                if ch.get("ok"):
-                    chain_col = f"  ALU{bits} OK ({ch['elapsed_s']:.2f}s)"
-                else:
-                    chain_col = f"  ALU{bits} FAIL"
-    print(
-        f"  {r['filename']:<48}  d={m['data_bits']:>2}b a={m['addr_bits']:>2}b "
-        f"mem={m['memory_bytes']:>6}B  size={r['size_mb']:>6.1f}MB  "
-        f"params={r['params']:>10,}  fit={fit:>6}  tests={r['total_tests']:>5}  "
-        f"{r['status']:>5}{cpu_col}{chain_col}"
-    )
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description="Variant-agnostic eval harness")
-    parser.add_argument("path", help="Path to .safetensors file or directory of files")
-    parser.add_argument("--device", default="cpu", help="cpu (default) or cuda")
-    parser.add_argument("--pop_size", type=int, default=1)
-    parser.add_argument("--debug", action="store_true", help="Per-circuit detail per file")
-    parser.add_argument("--cpu-program", action="store_true",
-                        help="Also run a small assembled program through the threshold CPU "
-                             "(any variant with >= 132 B memory), plus a chained 16- or "
-                             "32-bit ALU sequence on wider variants")
-    parser.add_argument("--json", action="store_true", help="Emit JSON results to stdout instead of a table")
-    parser.add_argument("--cache-dir", default=".eval_cache",
-                        help="Directory for hash-keyed result cache "
-                             "(default: ./.eval_cache). Set to '' to disable.")
-    parser.add_argument("--no-cache", action="store_true",
-                        help="Disable the result cache for this run.")
-    args = parser.parse_args()
-
-    files = list_safetensors(Path(args.path))
-    if not files:
-        print(f"No .safetensors files found under {args.path}", file=sys.stderr)
-        return 2
-
-    print(f"Evaluating {len(files)} file(s) on {args.device}\n")
-    cache_enabled = bool(args.cache_dir) and not args.no_cache
-    cache_dir = Path(args.cache_dir) if cache_enabled else None
-    cache_opts = {
-        "device": args.device,
-        "pop_size": args.pop_size,
-        "cpu_program": bool(args.cpu_program),
-    }
-    cache_hits = 0
-    results = []
-    fail_count = 0
-    for f in files:
-        print(f"=== {f.name}")
-        cached = None
-        key = None
-        if cache_enabled:
-            try:
-                key = _cache_key(f, cache_opts)
-                cached = _load_cache(cache_dir, key)
-            except OSError:
-                cached = None
-        if cached is not None:
-            r = cached
-            cache_hits += 1
-            print(f"   (cache hit)")
-        else:
-            r = evaluate_one(f, device=args.device, pop_size=args.pop_size,
-                             debug=args.debug, run_cpu_program=args.cpu_program)
-            # Don't cache ERROR results: a transient failure (OOM, interrupt)
-            # would otherwise be replayed on every rerun of the same file.
-            if cache_enabled and key is not None and r.get("status") != "ERROR":
-                _save_cache(cache_dir, key, r)
-        results.append(r)
-        print_row(r, show_cpu=args.cpu_program)
-        if r.get("status") not in ("PASS", "SKIP"):
-            fail_count += 1
-
-    if args.json:
-        # Make it serialisable
-        for r in results:
-            r["manifest"] = {k: (int(v) if isinstance(v, float) and v.is_integer() else v)
-                             for k, v in r.get("manifest", {}).items()}
-        print(json.dumps(results, indent=2, default=str))
-        return fail_count
-
-    # Summary
-    print()
-    print("=" * 100)
-    print(" SUMMARY")
-    print("=" * 100)
-    for r in results:
-        print_row(r, show_cpu=args.cpu_program)
-
-    print()
-    if fail_count == 0:
-        print(f"ALL {len(files)} variants PASS")
-    else:
-        print(f"{fail_count}/{len(files)} variants FAIL")
-    if cache_enabled:
-        print(f"(cache: {cache_hits}/{len(files)} hits, dir={cache_dir})")
-    return fail_count
-
-
-if __name__ == "__main__":
-    sys.exit(main())