Add CPU program suite and fix CALL / V-flag handling

cpu_programs.py provides a small assembler and seven programs that
exercise the ISA end-to-end: iterative Fibonacci, sum 1..N (Z-flag
termination), self-modifying JMP (STORE into a JMP's address word),
all eight conditional jumps, CALL stack semantics, bubble sort, and
MUL cross-checked against repeated ADD.

test_cpu.py runs the suite against any variant. All seven programs
pass on every memory profile from 256 B (scratchpad) through 64 KB
(canonical), 32-bit data path included.

eval_all.py: GenericThresholdCPU previously treated CALL (opcode 0xE)
as a NOP because the case fell through the dispatch table. Added the
push-return-PC + SP behavior and SP support in the state dict.

eval_all.py: ADD / SUB / CMP now set the V (overflow) flag correctly
using the standard two's-complement signed-overflow tests; previously
V was always zero, so JV / JNV could never take.

README.md

@@ -72,6 +72,16 @@ python play.py                                            # 1 KB demo, runs in s
 python play.py --model neural_computer.safetensors        # 64 KB, slower
 ```
 
+For end-to-end CPU validation (Fibonacci, sum 1..N, bubble sort, self-modifying JMP, all eight conditional jumps, CALL stack semantics, MUL cross-checked against repeated ADD):
+
+```bash
+python test_cpu.py                                        # default: 1 KB, ~2 s
+python test_cpu.py --model neural_computer.safetensors    # 64 KB canonical, ~100 s
+python test_cpu.py --only fib,sum_n                       # subset of suite
+```
+
+Each program is assembled by a small Python assembler (`cpu_programs.py`) and run through the threshold-gated CPU; the driver verifies expected memory contents at HALT.
+
 ---
 
 ## Execution model
@@ -429,7 +439,9 @@ variants/                           18 prebuilt configurations
 build.py                            generator (one safetensors per invocation)
 build_all.py                        builds and verifies every named profile
 eval.py                             gate-level fitness suite + reference CPU runtime
-eval_all.py                         variant-agnostic harness (recommended)
+eval_all.py                         variant-agnostic gate-level harness
+cpu_programs.py                     assembler + program suite for CPU-level validation
+test_cpu.py                         runs the program suite against a chosen variant
 play.py                             interactive demo
 prune_weights.py                    GPU-batched weight reduction with conflict resolution
 llm_integration/                    SmolLM2 extractor + circuit wrapper + training code

cpu_programs.py

@@ -0,0 +1,518 @@
+"""
+CPU validation programs for the threshold computer.
+
+A small assembler and a suite of programs that exercise the ISA end-to-end:
+arithmetic, control flow, memory access, self-modifying code, all eight
+conditional jumps, the call mechanism, and a sort.
+
+Each program returns (mem, expected, max_cycles, description) where:
+  mem        : list[int] -- complete memory image
+  expected   : dict[int, int] -- {address: expected_value} verified at HALT
+  max_cycles : int -- cycle budget (an infinite loop will hit this)
+  description: str -- short human-readable summary
+
+Programs target the 1 KB profile (addr_bits=10) by default but use only the
+low 256 bytes so they also run on scratchpad and larger profiles.
+
+All programs assume the CPU starts with PC=0, SP defaulting to addr_mask
+(highest address; CALL pre-decrements before writing).
+"""
+
+from __future__ import annotations
+from typing import Dict, List, Tuple
+
+
+# ----------------------------------------------------------------------------
+# 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.
+
+    Usage:
+        a = Asm(size=256)
+        a.org(0)
+        a.label("start")
+        a.load(0, "data")
+        a.halt()
+        a.org(0x80); a.label("data"); a.db(42)
+        mem = a.assemble()
+    """
+
+    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.
+
+    F(11) = 89. F(13) = 233 still fits in 8 bits; F(14) = 377 overflows.
+
+    Algorithm: maintain (a, b) = (F(k), F(k+1)); after N steps a = F(N).
+    Per iteration: temp=b, b=a+b, a=temp; n--.
+    """
+    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.
+
+    No explicit zero register required; SUB sets Z when its result is zero.
+    R0 = accumulator, R1 = counter (n down to 1), R2 = 1.
+    """
+    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.
+
+    Initial JMP target is path_a (writes 0xAA to OUT). The code first
+    overwrites the JMP's address-word LSB so it points to path_b
+    (writes 0xBB). Successful execution lands at path_b, so OUT = 0xBB.
+    """
+    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.
+
+    Test plan (each step sets flags, then a Jcc; the branch takes when
+    expected and the corresponding marker is written):
+
+      JZ:  CMP equal -> Z=1 -> taken  -> M[OUT0] = 0xA0
+      JNZ: CMP unequal -> Z=0 -> taken -> M[OUT1] = 0xA1
+      JC:  ADD overflow (255+1) -> C=1 -> taken -> M[OUT2] = 0xA2
+      JNC: ADD no overflow -> C=0 -> taken -> M[OUT3] = 0xA3
+      JN:  SUB result 0xFF (n=1) -> N=1 -> taken -> M[OUT4] = 0xA4
+      JP:  ADD result 1 -> N=0 -> taken -> M[OUT5] = 0xA5
+      JV:  ADD signed overflow (127+1=128) -> V=1 -> taken -> M[OUT6] = 0xA6
+      JNV: ADD no signed overflow (1+1=2) -> V=0 -> taken -> M[OUT7] = 0xA7
+
+    A failure on any branch causes the wrong (or no) marker to be written.
+    """
+    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.
+
+    SP starts at addr_mask (mem_size - 1). CALL decrements SP and writes the
+    return-address high byte, decrements again and writes the low byte. After
+    HALT we expect:
+      - mem[addr_mask - 2] = low byte of the return address
+      - mem[addr_mask - 1] = high byte of the return address
+      - the no-return code path was NOT taken
+      - the callee was reached
+    """
+    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).
+
+    Algorithm: bubble sort, fully unrolled (no inner loops). Each compare-swap
+    is 8 instructions; 3 outer passes x 3 inner positions = 9 swaps -> ~72 instrs.
+
+    For each position i in (0,1,2):
+        if A[i] > A[i+1]:
+            tmp = A[i]; A[i] = A[i+1]; A[i+1] = tmp
+    Repeat 3 times -> sorted ascending.
+    """
+    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.
+
+    Multiplies A * B two ways:
+      1. R0 = A; ADD R0, B repeatedly B times. Stored at OUT_ADD.
+      Wait that gives A*(B+1) actually... let me rewrite.
+
+    Use:
+      acc = 0; for i in 0..B-1: acc += A;   -> acc = A*B
+      direct: R0 = A; MUL R0, R1 (R1 = B);  -> R0 = A*B
+    Compare both at OUT.
+    """
+    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}"
+
+
+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)),
+]
+

eval_all.py

@@ -322,18 +322,22 @@ class GenericThresholdCPU:
         b = s["regs"][rs]
         result = a
         carry = 0
+        overflow = 0
         write_result = True
         if opcode == 0x0:
             result, carry = self.alu.add8(a, b)
+            overflow = 1 if (((a ^ result) & (b ^ result)) & 0x80) else 0
         elif opcode == 0x1:
             result, carry = self.alu.sub8(a, b)
+            overflow = 1 if (((a ^ b) & (a ^ result)) & 0x80) else 0
         elif opcode == 0x7:
             result = self.alu.mul8(a, b)
         elif opcode == 0x9:
             r2, carry = self.alu.sub8(a, b)
             z = 1 if r2 == 0 else 0
             n = 1 if (r2 & 0x80) else 0
-            s["flags"] = [z, n, carry, 0]
+            v = 1 if (((a ^ b) & (a ^ r2)) & 0x80) else 0
+            s["flags"] = [z, n, carry, v]
             write_result = False
         elif opcode == 0xA:
             result = self.mem_read(s["mem"], addr)
@@ -350,6 +354,16 @@ class GenericThresholdCPU:
                     n == 1, n == 0, v == 1, v == 0][cond]
             s["pc"] = addr if take else next_pc
             return s
+        elif opcode == 0xE:  # CALL: push return address (next_pc), set PC = addr
+            ret_addr = next_pc & 0xFFFF
+            sp = s.get("sp", addr_mask)
+            sp = (sp - 1) & addr_mask
+            s["mem"] = self.mem_write(s["mem"], sp, (ret_addr >> 8) & 0xFF)
+            sp = (sp - 1) & addr_mask
+            s["mem"] = self.mem_write(s["mem"], sp, ret_addr & 0xFF)
+            s["sp"] = sp
+            s["pc"] = addr
+            return s
         elif opcode == 0xF:
             s["halted"] = True
             return s
@@ -359,7 +373,7 @@ class GenericThresholdCPU:
         if opcode in (0x0, 0x1, 0x7):
             z = 1 if (result & 0xFF) == 0 else 0
             n = 1 if (result & 0x80) else 0
-            s["flags"] = [z, n, carry, 0]
+            s["flags"] = [z, n, carry, overflow]
         s["pc"] = next_pc
         return s
 

test_cpu.py

@@ -0,0 +1,138 @@
+"""
+Run the CPU program suite against a threshold-computer variant.
+
+Loads weights, instantiates GenericThresholdCPU, runs each program from
+cpu_programs.SUITE, and verifies expected memory contents at HALT.
+
+Usage:
+    python test_cpu.py                                       # default: 1KB variant, fast
+    python test_cpu.py --model neural_computer.safetensors   # 64KB canonical, slow
+    python test_cpu.py --only fib,sum_n                      # subset of suite
+"""
+
+from __future__ import annotations
+import argparse
+import os
+import sys
+import time
+from pathlib import Path
+
+import torch
+from safetensors import safe_open
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from eval_all import GenericThresholdCPU, get_manifest
+from cpu_programs import SUITE
+
+
+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() -> int:
+    parser = argparse.ArgumentParser(description="Run the CPU program suite")
+    parser.add_argument(
+        "--model", type=str,
+        default=os.path.join(os.path.dirname(__file__),
+                             "variants", "neural_computer8_small.safetensors"),
+        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
+
+
+if __name__ == "__main__":
+    sys.exit(main())