Neural DOOM gradio app (chromatic dark)

README.md

@@ -1,13 +1,20 @@
----
-title: Neural Doom
-emoji: 🔥
-colorFrom: green
+---
+title: Neural DOOM
+emoji: 💀
+colorFrom: red
 colorTo: purple
 sdk: gradio
-sdk_version: 6.17.3
-python_version: '3.13'
+sdk_version: 6.15.2
 app_file: app.py
-pinned: false
+pinned: true
+license: gpl-2.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Neural DOOM
+
+id Software's 1993 DOOM running on an i386 core whose every datapath unit is a
+neural network verified bit-exact over its complete input domain. A full frame
+(5,952,699 instructions) replayed fully neurally was bit-identical to the
+golden run — framebuffer and all 128 MB of machine state. Weights, binary, WAD
+and the title-frame snapshot are pulled from a private repo via the HF_TOKEN
+Space secret. ZeroGPU re-verifies all 13 units exhaustively on demand.

WRITEUP.md

@@ -0,0 +1,122 @@
+# Neural GB — a Game Boy whose logic is neural networks, verified bit-exact
+
+**The claim:** a real, unmodified Game Boy game (*Usurper of the Ghoul Throne*,
+a 512KB MBC5 cartridge from itch.io) boots and renders on an emulator in which
+**every functional unit — instruction decode, the entire ALU, every rotate and
+bit operation, tile decoding, palette mapping, sprite priority — is a trained
+neural network**, and the output is **bit-identical** to a conventional
+reference implementation: every pixel of the framebuffer and every byte of
+machine state.
+
+![the game, rendered fully neurally](images/ghoul_neural.png)
+
+That title screen was not produced by ordinary emulator code. The frame's 4,178
+CPU instructions were each decoded by a neural net and executed through neural
+ALU nets, and each of its 23,040 pixels passed through neural tile-decode,
+palette, and sprite-mux nets. `images/ghoul_golden.png` is the same frame from
+the conventional implementation — they are identical to the bit
+(`proof/4_neural_game_frame.txt`).
+
+## The methodology
+
+Neural networks are approximators; emulation needs exactness — 99.9% correct is
+0% playable, because one wrong flag bit desyncs everything downstream. The
+project's answer is a discipline applied uniformly to every unit:
+
+1. **Decompose** the machine the way hardware engineers do: into small units
+   whose input spaces are completely enumerable (an 8-bit adder has 65,536
+   inputs; the opcode decoder has 256; a palette lookup has 1,024).
+2. **Enumerate** the unit's full input domain and its golden outputs.
+3. **Train** a small bit-level MLP on the *entire* domain.
+4. **Verify exhaustively**: the unit passes only at N/N. 65,535/65,536 is a fail.
+5. **Compose** verified units with plain wiring (routing, scheduling, address
+   arithmetic). Composition of exact units is exact — so programs run forever
+   with zero desync.
+
+The rule that makes this scale: **anything too wide to enumerate is never
+trained as one net — it is composed from verified narrow units**, the way
+hardware ripples a carry. 16-bit arithmetic (2³² cases, untrainable) is two
+passes through the verified 8-bit ADC/SBC nets (each 131,072 cases with the
+carry-in as an explicit input). The 26 units and their verified domains are in
+`proof/1_unit_verification.txt`; trained weights ship in `code/models/`.
+
+## The build, brick by brick
+
+| Brick | What it proved | Artifact |
+|---|---|---|
+| Single tile through neural PPU units | the unit method works for graphics | `images/neural_tile.png` |
+| Shared-clock CPU+PPU machine | a mid-frame register write lands on the right **scanline** (82) | `images/neural_frame.png` |
+| Per-dot orchestrator | a mid-scanline write lands on the right **pixel** (line 82, px 64) — a frame a scanline renderer cannot represent | `images/neural_frame_dot.png` |
+| Complete SM83 CPU core | all 512 opcodes, stack, interrupts, m-cycle bus timing | `code/gb_sm83.py` |
+| Full DMG console | MBC1/MBC5 banking, full PPU (BG+window+sprites, STAT/LYC, DMA), timer, joypad | `code/gb_console.py` |
+| **A real game** | the whole stack holds on commercial-style code | `images/ghoul_neural.png` |
+
+## The proof chain
+
+Self-consistency isn't enough, so the core was held to the standards real
+emulators are judged by:
+
+- **SingleStepTests/sm83**: 512 opcodes × 1,000 randomized cases, each checking
+  full register/flag/RAM state and cycle counts — **all pass**
+  (`proof/2_singlesteptests.txt`).
+- **Blargg's cpu_instrs**: the classic hardware-validated instruction exerciser,
+  reporting over the emulated serial port — **11/11 "Passed all tests"**
+  (`proof/3_blargg_cpu_instrs.txt`).
+- **Golden vs neural bit-identity** on the game frame: framebuffer and complete
+  machine state identical (`proof/4_neural_game_frame.txt`). The comparison is
+  meaningful because both runs share one orchestrator — only the units differ.
+- **Playability**: the turbo raster is pixel-identical to the per-dot reference
+  at the checked frame, runs ~25 fps, and the game responds to a Start press
+  within 2 frames (`proof/5_turbo_and_input.txt`, `images/ghoul_after_start.png`).
+
+A story worth telling: across the entire build, the test suites found **exactly
+one bug — in hand-written glue, not in any neural unit** (SWAP and SRL
+transposed in the CB dispatch table). The verified units were flawless by
+construction; the one unverified lookup table was where the bug hid. That is
+the methodology's thesis in miniature.
+
+## Run it yourself
+
+```
+cd code
+pip install numpy torch pillow            # torch only needed to load/train units
+python gb_units.py                        # verify all 26 units (instant: cached weights)
+python run_sst.py                         # 512-opcode suite (needs sm83/v1 JSONs)
+python run_blargg.py                      # cpu_instrs 11/11 (needs cpu_instrs.gb)
+python run_ghoul.py                       # the bit-exact neural game frame
+python play_gb.py                         # PLAY IT (golden units, ~25 fps)
+python play_gb.py --neural                # every unit neural: slow-motion proof mode
+```
+
+Controls: arrows = d-pad, Z = A, X = B, Enter = Start, Shift = Select, Esc = quit.
+
+## Honest limitations
+
+Gameplay speed uses the golden (conventional) units — the fully neural machine
+runs at ~5 s/frame, so `--neural` is a proof mode, not a way to play. The
+orchestrator simplifies: OAM DMA is an instant copy, no sprite-fetch mode-3
+stalls, no OAM/VRAM access blocking by PPU mode, and no audio. All
+simplifications are identical in golden and neural runs, so every bit-identity
+claim is unaffected by them.
+
+## Epilogue: DOOM on a neural x86
+
+The methodology then scaled to a 1993 PC. The same discipline — enumerate,
+train, verify N/N, compose — produced 13 verified x86 datapath units (8-bit
+ADC/SBB slices carrying all five x86 flags, logic ops, 1-bit shift slices, the
+MASK8 multiplier partial-product slice, and the prefix/ModRM/SIB decode
+tables). Everything wider is composition: 32-bit arithmetic ripples carries
+through the 8-bit slices, multiplication is masked shifted adds, division is
+restoring subtraction — silicon's own recipes.
+
+The i386 core built from these units matches QEMU on 194/194 instruction
+templates (2,560 randomized full-state cases). A minimal Linux shell (ELF
+loader + ~30 syscalls, all clocks deterministic) runs real static binaries:
+id Software's actual DOOM, cross-compiled to i386, boots through its full init
+chain and renders the title screen in 20M instructions.
+
+The proof: the machine was frozen at the title frame, and the next frame
+(5,952,699 instructions) was run twice — once golden, once with every decode,
+ALU, shift, multiply, and divide a neural network. Framebuffer: bit-identical.
+All 128 MB of memory plus registers and flags: identical
+(`proof/6_neural_doom_frame.txt`, `images/doom_neural_frame.png`).

app.py

@@ -0,0 +1,335 @@
+"""
+Neural DOOM -- ZeroGPU Gradio Space, chromatic dark UI.
+
+DOOM runs on an i386 core whose every datapath unit (decode, ALU slices,
+shifts, multiplier slices) is a neural network verified bit-exact over its
+COMPLETE input domain. A full frame (5,952,699 instructions) was replayed
+fully neurally and came out bit-identical to the golden run -- framebuffer
+and all 128 MB of machine state.
+
+Interactives:
+  * ZeroGPU: re-verify ALL 13 units exhaustively on the H200, live
+  * run a live neural execution segment from the title-frame snapshot,
+    bit-checked against the golden reference hash
+  * instruction microscope: single-step real DOOM code and watch every
+    neural unit fire, slice by slice
+
+Assets (unit weights, DOOM binary, WAD, snapshot) come from a private HF
+repo via the HF_TOKEN Space secret.
+"""
+import os, json, time, hashlib
+import numpy as np
+import gradio as gr
+import spaces
+import torch
+from huggingface_hub import snapshot_download
+
+ASSETS_REPO = "Quazim0t0/neural-x86-doom"
+ASSETS = snapshot_download(ASSETS_REPO, token=os.environ.get("HF_TOKEN"))
+
+import x86_units
+x86_units.CACHE = os.path.join(ASSETS, "models")
+from x86_units import build_all, NeuralUnits, GoldenUnits, ALU, BitMLP
+from x86_units import (u_ADC8, u_SBB8, u_logic, u_SHL1, u_SHR1, u_MASK8,
+                       u_NOT8, u_FLAGS8, u_prefix, u_modrm, u_sib)
+from x86_linux import Linux386
+
+SNAP = np.load(os.path.join(ASSETS, "doom_snapshot.npz"))
+GOLDEN_REFS = json.load(open(os.path.join(ASSETS, "doom_golden_refs.json")))
+ELF = open(os.path.join(ASSETS, "doom_i386"), "rb").read()
+WAD = open(os.path.join(ASSETS, "doom1.wad"), "rb").read()
+
+
+def title_frame_image():
+    from PIL import Image
+    fb = SNAP["title_fb"].reshape(400, 640, 4)
+    return Image.fromarray(fb[:, :, [2, 1, 0]])
+
+
+def fresh_machine():
+    m = Linux386(ELF, argv=("doom", "-iwad", "doom1.wad"),
+                 fs={"doom1.wad": WAD, "./doom1.wad": WAD})
+    m.mem[:] = SNAP["mem"].tobytes()
+    r = SNAP["regs"]
+    m.cpu.r = [int(x) for x in r[:8]]
+    (m.cpu.eip, m.cpu.gs_base, m.cpu.instr_count,
+     m.clock_ns, m.brk, m.mmap_ptr, m.next_fd) = (int(x) for x in r[8:15])
+    m.cpu.f = {str(k): int(v) for k, v in zip(SNAP["fkeys"], SNAP["fvals"])}
+    m.frames = []
+    return m
+
+
+def state_hash(m):
+    h = hashlib.sha256()
+    h.update(m.mem)
+    h.update(repr((m.cpu.r, m.cpu.eip, sorted(m.cpu.f.items()), m.clock_ns)).encode())
+    return h.hexdigest()
+
+
+# ================= ZeroGPU: exhaustive unit re-verification =================
+UNIT_SPECS = [
+    ("ADC8", u_ADC8, "8-bit add w/ carry + CF·OF·SF·ZF·AF"),
+    ("SBB8", u_SBB8, "8-bit subtract w/ borrow + flags"),
+    ("AND8", lambda: u_logic(lambda a, b: a & b), "bitwise AND + SF·ZF"),
+    ("OR8",  lambda: u_logic(lambda a, b: a | b), "bitwise OR + SF·ZF"),
+    ("XOR8", lambda: u_logic(lambda a, b: a ^ b), "bitwise XOR + SF·ZF"),
+    ("SHL1", u_SHL1, "shift-left-1 slice w/ carry chain"),
+    ("SHR1", u_SHR1, "shift-right-1 slice w/ carry chain"),
+    ("MASK8", u_MASK8, "multiplier partial-product slice"),
+    ("NOT8", u_NOT8, "bitwise NOT"),
+    ("FLAGS8", u_FLAGS8, "SF·ZF·parity extractor"),
+    ("PREFIX", u_prefix, "instruction prefix classifier"),
+    ("MODRM", u_modrm, "ModRM field decoder"),
+    ("SIB", u_sib, "SIB field decoder"),
+]
+
+@spaces.GPU(duration=60)
+def verify_all_units_gpu():
+    dev = "cuda" if torch.cuda.is_available() else "cpu"
+    gpu = torch.cuda.get_device_name(0) if dev == "cuda" else "CPU fallback"
+    rows = []
+    total_cases = 0
+    t_all = time.time()
+    for name, builder, desc in UNIT_SPECS:
+        X, Y = builder()
+        X = torch.tensor(X, device=dev); Y = torch.tensor(Y, device=dev)
+        net = BitMLP(X.shape[1], Y.shape[1]).to(dev)
+        net.load_state_dict(torch.load(
+            os.path.join(ASSETS, "models", f"{name}.pt"),
+            weights_only=True, map_location=dev))
+        t0 = time.time()
+        with torch.no_grad():
+            ok = int((((net(X) > 0).float() == Y).all(1)).sum())
+        total_cases += X.shape[0]
+        verdict = "✅ EXACT" if ok == X.shape[0] else "❌ FAIL"
+        rows.append(f"| `{name}` | {desc} | {ok:,} / {X.shape[0]:,} | {verdict} | "
+                    f"{(time.time()-t0)*1000:.0f} ms |")
+    dt = time.time() - t_all
+    return (f"### {total_cases:,} cases — every possible input of every unit — "
+            f"re-verified on **{gpu}** in **{dt:.1f}s**\n\n"
+            "| unit | role | cases exact | verdict | GPU time |\n"
+            "|---|---|---|---|---|\n" + "\n".join(rows) +
+            "\n\n*This is the entire mathematical foundation of the machine, "
+            "re-proven from the shipped weights, live, just now.*")
+
+
+# ================= live neural execution segment =================
+_neural = None
+def neural_units():
+    global _neural
+    if _neural is None:
+        _neural = NeuralUnits(build_all())
+    return _neural
+
+def run_neural_segment(seg_choice, progress=gr.Progress()):
+    seg = int(seg_choice.split()[0].replace(",", ""))
+    ref = GOLDEN_REFS.get(str(seg))
+    units = neural_units()
+    m = fresh_machine()
+    m.cpu.u = units
+    m.cpu.alu = ALU(units)
+    t0 = time.time()
+    for i in range(seg):
+        m.cpu.step()
+        if i % 250 == 0:
+            progress(i / seg, desc=f"⚡ {i:,} / {seg:,} instructions through the neural nets")
+    dt = time.time() - t0
+    h = state_hash(m)
+    same = (h == ref)
+    badge = ("<div class='verdict-pass'>BIT-IDENTICAL ✅</div>" if same
+             else "<div class='verdict-fail'>MISMATCH ❌</div>")
+    return (f"{badge}\n\n**{seg:,} instructions of id Software's actual machine code** "
+            f"executed with every decode, ALU op, shift and multiply a neural "
+            f"network — {dt:.0f}s ({seg/dt:,.0f} instr/s).\n\n"
+            f"Resulting machine state (128 MB memory + registers + flags) hashed and "
+            f"compared against the golden reference:\n\n"
+            f"`neural  {h[:40]}…`\n`golden  {(ref or '?')[:40]}…`")
+
+
+# ================= instruction microscope =================
+class TracingUnits:
+    """Proxy around NeuralUnits that records every unit invocation."""
+    def __init__(self, inner):
+        self._inner = inner
+        self.calls = []
+    def __getattr__(self, name):
+        fn = getattr(self._inner, name)
+        def wrap(*a):
+            r = fn(*a)
+            self.calls.append((name, a, r))
+            return r
+        return wrap
+
+MICRO = {"m": None, "tr": None}
+
+def micro_reset():
+    MICRO["m"] = None
+    return micro_step()
+
+def micro_step():
+    if MICRO["m"] is None:
+        m = fresh_machine()
+        tr = TracingUnits(neural_units())
+        m.cpu.u = tr
+        m.cpu.alu = ALU(tr)
+        MICRO["m"], MICRO["tr"] = m, tr
+    m, tr = MICRO["m"], MICRO["tr"]
+    tr.calls = []
+    eip0 = m.cpu.eip
+    code = bytes(m.mem[eip0:eip0 + 12]).hex(" ")
+    m.cpu.step()
+    nbytes = (m.cpu.eip - eip0) if 0 < m.cpu.eip - eip0 <= 12 else 12
+    shown = code[:nbytes * 3 - 1] if nbytes else code
+    rows = []
+    for name, args, res in tr.calls[:40]:
+        a = ", ".join(f"{x:02x}" if isinstance(x, int) else str(x) for x in args)
+        if isinstance(res, tuple):
+            r = " ".join(f"{x:02x}" if isinstance(x, int) else str(x) for x in res)
+        elif isinstance(res, int):
+            r = f"{res:02x}"
+        else:
+            r = str(res)
+        rows.append(f"| `{name}` | `{a}` | `{r}` |")
+    more = f"\n*…plus {len(tr.calls)-40} more unit calls*" if len(tr.calls) > 40 else ""
+    regs = m.cpu.r
+    f = m.cpu.f
+    return (f"### instruction @ `eip {eip0:08x}` — bytes `{shown}`\n"
+            f"**{len(tr.calls)} neural unit calls** computed this instruction:\n\n"
+            "| unit | inputs | outputs |\n|---|---|---|\n" + "\n".join(rows) + more +
+            f"\n\n**after:** `eax {regs[0]:08x}` `ecx {regs[1]:08x}` `edx {regs[2]:08x}` "
+            f"`ebx {regs[3]:08x}` `esp {regs[4]:08x}` `ebp {regs[5]:08x}` "
+            f"`esi {regs[6]:08x}` `edi {regs[7]:08x}` → `eip {m.cpu.eip:08x}`\n\n"
+            f"flags: CF={f['CF']} ZF={f['ZF']} SF={f['SF']} OF={f['OF']} "
+            f"PF={f['PF']} AF={f['AF']}")
+
+
+# ================= UI =================
+WRITEUP = open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "WRITEUP.md"),
+               encoding="utf-8").read()
+
+CSS = """
+:root { color-scheme: dark; }
+body, .gradio-container {
+  background: radial-gradient(ellipse at 20% -10%, #1a0a2e 0%, #0a0a14 45%, #050508 100%) !important;
+}
+#hero h1 {
+  font-size: 2.6em; font-weight: 900; letter-spacing: -0.02em;
+  background: linear-gradient(90deg, #ff3b3b, #ff9d00, #ffe600, #3bff8f, #00e0ff, #b03bff, #ff3b8f);
+  background-size: 300% 100%;
+  -webkit-background-clip: text; background-clip: text; color: transparent;
+  animation: chroma 8s linear infinite;
+}
+@keyframes chroma { 0% {background-position: 0% 50%;} 100% {background-position: 300% 50%;} }
+#hero p, #hero li { color: #c8c8de; }
+.panel {
+  border: 1px solid transparent; border-radius: 14px; padding: 4px;
+  background:
+    linear-gradient(#0e0e1a, #0e0e1a) padding-box,
+    linear-gradient(135deg, #ff3b3b66, #00e0ff66, #b03bff66) border-box;
+  box-shadow: 0 0 24px #00e0ff14, 0 0 48px #b03bff0f;
+}
+#doomframe { position: relative; border-radius: 10px; overflow: hidden;
+  box-shadow: 0 0 30px #ff3b3b33, 0 0 60px #ff3b3b1a; }
+#doomframe::after {
+  content: ""; position: absolute; inset: 0; pointer-events: none;
+  background: repeating-linear-gradient(0deg, transparent 0 2px, #00000022 2px 4px);
+}
+button.primary, .primary {
+  background: linear-gradient(90deg, #ff3b3b, #b03bff) !important;
+  border: none !important; color: white !important; font-weight: 700 !important;
+  box-shadow: 0 0 18px #b03bff55 !important; transition: box-shadow .2s !important;
+}
+button.primary:hover { box-shadow: 0 0 30px #ff3b3b88 !important; }
+.verdict-pass {
+  display: inline-block; padding: 10px 22px; border-radius: 10px; font-size: 1.3em;
+  font-weight: 900; color: #06140a;
+  background: linear-gradient(90deg, #3bff8f, #00e0ff);
+  box-shadow: 0 0 28px #3bff8f66; letter-spacing: .04em;
+}
+.verdict-fail {
+  display: inline-block; padding: 10px 22px; border-radius: 10px; font-size: 1.3em;
+  font-weight: 900; color: #fff; background: linear-gradient(90deg, #ff3b3b, #ff9d00);
+}
+.prooflog {
+  font-family: ui-monospace, monospace; color: #3bff8f; background: #050a07;
+  border: 1px solid #3bff8f44; border-radius: 10px; padding: 14px;
+  box-shadow: inset 0 0 24px #3bff8f11;
+}
+table { border-color: #2a2a44 !important; }
+"""
+
+FORCE_DARK = """
+function refresh() {
+  const url = new URL(window.location);
+  if (url.searchParams.get('__theme') !== 'dark') {
+    url.searchParams.set('__theme', 'dark');
+    window.location.href = url.href;
+  }
+}
+"""
+
+theme = gr.themes.Base(
+    primary_hue="purple", neutral_hue="slate",
+    font=[gr.themes.GoogleFont("Inter"), "system-ui", "sans-serif"],
+    font_mono=[gr.themes.GoogleFont("JetBrains Mono"), "ui-monospace", "monospace"],
+)
+
+with gr.Blocks(title="Neural DOOM") as demo:
+    with gr.Column(elem_id="hero"):
+        gr.Markdown(
+            "# NEURAL DOOM\n"
+            "### id Software's 1993 code, executed by neural networks — bit-exact\n"
+            "Every datapath unit of this i386 — instruction decode, every ALU slice, "
+            "every shift, every multiply — is a neural network verified over its "
+            "**complete input domain**. A full frame (**5,952,699 instructions**) was "
+            "replayed with every unit neural and came out **bit-identical** to the "
+            "conventional run: every pixel, every byte of all 128 MB of machine state.")
+    with gr.Row():
+        with gr.Column(scale=3):
+            gr.Image(value=title_frame_image(), elem_id="doomframe", show_label=False,
+                     interactive=False)
+        with gr.Column(scale=2):
+            gr.HTML("<div class='prooflog'>instructions golden = 5,952,699<br>"
+                    "instructions neural = 5,952,699<br>"
+                    "framebuffer 640×400 ........ BIT-IDENTICAL<br>"
+                    "machine state (128 MB) ..... IDENTICAL<br><br>"
+                    ">>> DOOM FRAME EXACT THROUGH THE FULLY NEURAL x86</div>")
+            gr.Markdown("_102 minutes of compute at ~970 instructions/second — every "
+                        "one decoded and computed by neural nets, one verified 8-bit "
+                        "slice at a time. This page lets you re-run the proofs yourself._")
+    gr.Markdown("---")
+    with gr.Row(equal_height=False):
+        with gr.Column(elem_classes="panel"):
+            gr.Markdown("## 🔬 Re-prove the foundation &nbsp;·&nbsp; ZeroGPU\n"
+                        "One click re-verifies **all 13 units exhaustively** — every "
+                        "possible input of every unit, 525k+ cases — on an H200 slice.")
+            v_btn = gr.Button("⚡ Re-verify all 13 units on GPU", variant="primary")
+            v_out = gr.Markdown()
+        with gr.Column(elem_classes="panel"):
+            gr.Markdown("## ⚙️ Run DOOM neurally, live\n"
+                        "Executes real DOOM machine code from the title-frame snapshot "
+                        "with **every unit neural**, then bit-checks the resulting "
+                        "machine state against the golden reference hash.")
+            seg = gr.Dropdown(["10,000 instructions", "25,000 instructions",
+                               "50,000 instructions"], value="10,000 instructions",
+                              label="segment length", filterable=False)
+            r_btn = gr.Button("⚡ Execute neurally + verify", variant="primary")
+            r_out = gr.Markdown()
+    with gr.Column(elem_classes="panel"):
+        gr.Markdown("## 🧬 Instruction microscope\n"
+                    "Single-step DOOM and watch the neural units fire. Each row is one "
+                    "net computing one verified slice of the instruction — carry chains, "
+                    "flag wiring, decode fields, all of it.")
+        with gr.Row():
+            s_btn = gr.Button("⏭ Step one instruction", variant="primary")
+            x_btn = gr.Button("↺ Reset to title frame")
+        s_out = gr.Markdown()
+    v_btn.click(verify_all_units_gpu, None, v_out)
+    r_btn.click(run_neural_segment, seg, r_out)
+    s_btn.click(micro_step, None, s_out)
+    x_btn.click(micro_reset, None, s_out)
+    gr.Markdown("---")
+    with gr.Accordion("📜 The full write-up — from a Game Boy smiley tile to DOOM", open=False):
+        gr.Markdown(WRITEUP)
+
+demo.launch(theme=theme, css=CSS, js=FORCE_DARK)

requirements.txt

@@ -0,0 +1,5 @@
+numpy
+torch
+pillow
+huggingface_hub
+spaces

x86_core.py

@@ -0,0 +1,579 @@
+"""
+x86_core.py -- i386/i486 user-mode integer core (flat 32-bit protected mode),
+every data transformation routed through the x86_units API (golden or neural).
+
+Scope: the instruction set a -march=i486 -O1 musl/doomgeneric binary uses.
+No FPU (DOOM is fixed-point), no paging (flat), no real mode. Segments are
+flat except %gs, whose base is honored for i386 TLS.
+
+Composition stances (consistent with the GB bricks):
+  - all arithmetic/logic/shift/mul/div through verified slice units (ALU class)
+  - effective-address arithmetic, immediate assembly, and dispatch are wiring
+  - one-operand IMUL/MUL produce edx:eax via the 8x8 partial-product tree;
+    IDIV/DIV are restoring division over verified subtract slices
+"""
+from x86_units import GoldenUnits, ALU
+
+EAX, ECX, EDX, EBX, ESP, EBP, ESI, EDI = range(8)
+CF, PF, AF, ZF, SF, OF, DF = "CF", "PF", "AF", "ZF", "SF", "OF", "DF"
+M32 = 0xFFFFFFFF
+
+
+def sx8(v):  return v - 0x100 if v & 0x80 else v
+def sx16(v): return v - 0x10000 if v & 0x8000 else v
+def sx32(v): return v - 0x100000000 if v & 0x80000000 else v
+
+
+class CPUError(Exception):
+    pass
+
+
+class X86:
+    def __init__(self, mem, units=None):
+        self.mem = mem                       # bytearray, flat
+        self.u = units or GoldenUnits()
+        self.alu = ALU(self.u)
+        self.r = [0] * 8
+        self.eip = 0
+        self.f = {CF: 0, PF: 0, AF: 0, ZF: 0, SF: 0, OF: 0, DF: 0}
+        self.gs_base = 0
+        self.exited = None                   # set to status on exit syscall
+        self.syscall = None                  # callback(cpu) for int 0x80
+        self.instr_count = 0
+
+    # ---------------- memory (wiring) ----------------
+    def rd(self, a, n):
+        a &= M32
+        return int.from_bytes(self.mem[a:a + n], "little")
+    def wr(self, a, v, n):
+        a &= M32
+        self.mem[a:a + n] = int(v & ((1 << (8 * n)) - 1)).to_bytes(n, "little")
+
+    def fetch(self, n=1):
+        v = self.rd(self.eip, n)
+        self.eip = (self.eip + n) & M32
+        return v
+
+    # ---------------- register access (wiring) ----------------
+    def get_r(self, i, size):
+        if size == 32: return self.r[i]
+        if size == 16: return self.r[i] & 0xFFFF
+        if i < 4: return self.r[i] & 0xFF                  # AL CL DL BL
+        return (self.r[i - 4] >> 8) & 0xFF                 # AH CH DH BH
+    def set_r(self, i, v, size):
+        if size == 32: self.r[i] = v & M32
+        elif size == 16: self.r[i] = (self.r[i] & 0xFFFF0000) | (v & 0xFFFF)
+        elif i < 4: self.r[i] = (self.r[i] & ~0xFF) | (v & 0xFF)
+        else: self.r[i - 4] = (self.r[i - 4] & ~0xFF00) | ((v & 0xFF) << 8)
+
+    # ---------------- flags ----------------
+    def setf(self, fl):
+        for k, v in fl.items():
+            self.f[k] = int(v)
+    def eflags(self):
+        f = self.f
+        return (f[CF] | (f[PF] << 2) | (f[AF] << 4) | (f[ZF] << 6) | (f[SF] << 7)
+                | (f[DF] << 10) | (f[OF] << 11) | 0x2)
+    def set_eflags(self, v):
+        self.f[CF] = v & 1; self.f[PF] = (v >> 2) & 1; self.f[AF] = (v >> 4) & 1
+        self.f[ZF] = (v >> 6) & 1; self.f[SF] = (v >> 7) & 1
+        self.f[DF] = (v >> 10) & 1; self.f[OF] = (v >> 11) & 1
+
+    def cond(self, cc):
+        f = self.f
+        v = [f[OF], f[CF], f[ZF], f[CF] | f[ZF], f[SF], f[PF],
+             f[SF] ^ f[OF], (f[SF] ^ f[OF]) | f[ZF]][cc >> 1]
+        return v ^ (cc & 1)
+
+    # ---------------- ModRM / SIB (decode units + EA wiring) ----------------
+    def modrm(self, size, seg_base=0):
+        mod, reg, rm = self.u.modrm(self.fetch())
+        if mod == 3:
+            return reg, ("r", rm)
+        if rm == 4:
+            ss, idx, base = self.u.sib(self.fetch())
+            ea = 0 if (base == 5 and mod == 0) else self.r[base]
+            if base == 5 and mod == 0:
+                ea = self.fetch(4)
+            if idx != 4:
+                ea = (ea + (self.r[idx] << ss)) & M32
+        elif rm == 5 and mod == 0:
+            ea = self.fetch(4)
+        else:
+            ea = self.r[rm]
+        if mod == 1: ea = (ea + sx8(self.fetch())) & M32
+        elif mod == 2: ea = (ea + self.fetch(4)) & M32
+        return reg, ("m", (ea + seg_base) & M32)
+
+    def get_rm(self, loc, size):
+        k, x = loc
+        return self.get_r(x, size) if k == "r" else self.rd(x, size // 8)
+    def set_rm(self, loc, v, size):
+        k, x = loc
+        if k == "r": self.set_r(x, v, size)
+        else: self.wr(x, v, size // 8)
+
+    # ---------------- ALU dispatch through units ----------------
+    def alu_op(self, op, a, b, size):
+        """op: 0 ADD,1 OR,2 ADC,3 SBB,4 AND,5 SUB,6 XOR,7 CMP. Returns result or None."""
+        if op == 0: r, fl = self.alu.addsub(0, a, b, size)
+        elif op == 2: r, fl = self.alu.addsub(0, a, b, size, self.f[CF])
+        elif op in (5, 7): r, fl = self.alu.addsub(1, a, b, size)
+        elif op == 3: r, fl = self.alu.addsub(1, a, b, size, self.f[CF])
+        elif op == 1: r, fl = self.alu.logic("OR", a, b, size)
+        elif op == 4: r, fl = self.alu.logic("AND", a, b, size)
+        else: r, fl = self.alu.logic("XOR", a, b, size)
+        self.setf(fl)
+        return None if op == 7 else r
+
+    def incdec(self, v, size, dec):
+        r, fl = self.alu.addsub(dec, v, 1, size)
+        fl.pop("CF")                                   # INC/DEC preserve CF
+        self.setf(fl)
+        return r
+
+    # ---------------- shifts/rotates: 1-bit verified slices, k times ----------------
+    def shift(self, kind, v, count, size):
+        count &= 31
+        if count == 0:
+            return v
+        msb = 1 << (size - 1)
+        orig_msb = 1 if v & msb else 0
+        for i in range(count):
+            if kind == 4:                                # SHL
+                v, c = self.alu.shl1(v, size)
+            elif kind == 5:                              # SHR
+                v, c = self.alu.shr1(v, size)
+            elif kind == 7:                              # SAR
+                v, c = self.alu.shr1(v, size, top=1 if v & msb else 0)
+            elif kind == 0:                              # ROL
+                v, c = self.alu.shl1(v, size)
+                if c: v |= 1
+            elif kind == 1:                              # ROR
+                v, c = self.alu.shr1(v, size, top=v & 1)
+            elif kind == 2:                              # RCL
+                v, nc = self.alu.shl1(v, size)
+                if self.f[CF]: v |= 1
+                c = nc
+            else:                                        # RCR
+                v, c = self.alu.shr1(v, size, top=self.f[CF])
+            self.f[CF] = c
+        if kind in (4, 5, 7):
+            SF_, ZF_, PF_ = self.alu.flags_of(v, size)
+            self.f[SF], self.f[ZF], self.f[PF] = SF_, ZF_, PF_
+        if count == 1:
+            if kind == 4: self.f[OF] = ((v >> (size - 1)) & 1) ^ self.f[CF]
+            elif kind == 5: self.f[OF] = orig_msb
+            elif kind == 7: self.f[OF] = 0
+            elif kind == 0: self.f[OF] = ((v >> (size - 1)) & 1) ^ self.f[CF]
+            elif kind == 1: self.f[OF] = ((v >> (size - 1)) ^ (v >> (size - 2))) & 1
+        return v
+
+    def shd(self, left, v, fill, count, size):
+        """SHLD/SHRD: double shift through verified 1-bit slices over 2*size bits."""
+        count &= 31
+        if count == 0:
+            return v
+        if left:
+            wide = (v << size) | fill
+            for _ in range(count):
+                wide, c = ALU.shl1(self.alu, wide, 2 * size) if False else self.alu.shl1(wide, 2 * size)
+                self.f[CF] = c
+            v = (wide >> size) & ((1 << size) - 1)
+        else:
+            wide = (fill << size) | v
+            for _ in range(count):
+                wide, c = self.alu.shr1(wide, 2 * size)
+                self.f[CF] = c
+            v = wide & ((1 << size) - 1)
+        SF_, ZF_, PF_ = self.alu.flags_of(v, size)
+        self.f[SF], self.f[ZF], self.f[PF] = SF_, ZF_, PF_
+        return v
+
+    # ---------------- stack (wiring over mem) ----------------
+    def push(self, v):
+        self.r[ESP] = (self.r[ESP] - 4) & M32
+        self.wr(self.r[ESP], v, 4)
+    def pop(self):
+        v = self.rd(self.r[ESP], 4)
+        self.r[ESP] = (self.r[ESP] + 4) & M32
+        return v
+
+    # ---------------- one instruction ----------------
+    def step(self):
+        self.instr_count += 1
+        start = self.eip
+        osize = 32; seg = 0
+        # prefixes (decode unit)
+        rep = None
+        while True:
+            b = self.rd(self.eip, 1)
+            isp, cls = self.u.prefix(b)
+            if not isp:
+                break
+            self.eip = (self.eip + 1) & M32
+            if cls == 1: osize = 16
+            elif cls == 4: rep = "ne"
+            elif cls == 5: rep = "e"
+            elif cls == 6 and b == 0x65: seg = self.gs_base
+        op = self.fetch()
+        try:
+            self.exec_op(op, osize, seg, rep)
+        except CPUError:
+            self.eip = start
+            raise
+
+    def exec_op(self, op, osize, seg, rep):
+        S = osize
+        # ---- ALU group 00-3D ----
+        if op < 0x40 and (op & 7) < 6:
+            kind = op >> 3
+            form = op & 7
+            if form in (0, 1):           # r/m, r
+                size = 8 if form == 0 else S
+                reg, loc = self.modrm(size, seg)
+                r = self.alu_op(kind, self.get_rm(loc, size), self.get_r(reg, size), size)
+                if r is not None: self.set_rm(loc, r, size)
+            elif form in (2, 3):         # r, r/m
+                size = 8 if form == 2 else S
+                reg, loc = self.modrm(size, seg)
+                r = self.alu_op(kind, self.get_r(reg, size), self.get_rm(loc, size), size)
+                if r is not None: self.set_r(reg, r, size)
+            else:                        # AL/eAX, imm
+                size = 8 if form == 4 else S
+                imm = self.fetch(size // 8)
+                r = self.alu_op(kind, self.get_r(EAX, size), imm, size)
+                if r is not None: self.set_r(EAX, r, size)
+            return
+        # ---- INC/DEC r32 40-4F ----
+        if 0x40 <= op <= 0x4F:
+            i = op & 7
+            self.set_r(i, self.incdec(self.get_r(i, S), S, (op >> 3) & 1), S)
+            return
+        # ---- PUSH/POP r32 50-5F ----
+        if 0x50 <= op <= 0x57: self.push(self.get_r(op & 7, 32)); return
+        if 0x58 <= op <= 0x5F: self.set_r(op & 7, self.pop(), 32); return
+        if op == 0x68: self.push(self.fetch(4)); return
+        if op == 0x6A: self.push(sx8(self.fetch()) & M32); return
+        if op == 0x8F:
+            _, loc = self.modrm(S, seg); self.set_rm(loc, self.pop(), 32); return
+        # ---- IMUL r,r/m,imm (69/6B) ----
+        if op in (0x69, 0x6B):
+            reg, loc = self.modrm(S, seg)
+            a = sx32(self.get_rm(loc, S)) if S == 32 else sx16(self.get_rm(loc, S))
+            b = sx8(self.fetch()) if op == 0x6B else (
+                sx32(self.fetch(4)) if S == 32 else sx16(self.fetch(2)))
+            full = self.alu.mul(abs(a), abs(b), S)
+            if (a < 0) != (b < 0): full = (-full) & ((1 << (2 * S)) - 1)
+            res = full & ((1 << S) - 1)
+            sres = sx32(res) if S == 32 else sx16(res)
+            ovf = int(sx32(full if S == 32 else 0) != a * b) if S == 32 else 0
+            ovf = int(((full ^ ((res >> (S-1)) * ((1 << (2*S)) - (1 << S)))) >> S) != 0)
+            self.f[CF] = self.f[OF] = ovf
+            self.set_r(reg, res, S)
+            return
+        # ---- Jcc short 70-7F ----
+        if 0x70 <= op <= 0x7F:
+            d = sx8(self.fetch())
+            if self.cond(op & 0xF): self.eip = (self.eip + d) & M32
+            return
+        # ---- group 80/81/83 ----
+        if op in (0x80, 0x81, 0x83):
+            size = 8 if op == 0x80 else S
+            reg, loc = self.modrm(size, seg)
+            imm = (self.fetch() if op == 0x80 else
+                   sx8(self.fetch()) & ((1 << size) - 1) if op == 0x83 else
+                   self.fetch(size // 8))
+            r = self.alu_op(reg, self.get_rm(loc, size), imm, size)
+            if r is not None: self.set_rm(loc, r, size)
+            return
+        # ---- TEST 84/85 ----
+        if op in (0x84, 0x85):
+            size = 8 if op == 0x84 else S
+            reg, loc = self.modrm(size, seg)
+            self.alu_op(4, self.get_rm(loc, size), self.get_r(reg, size), size)
+            return
+        # ---- XCHG 86/87 ----
+        if op in (0x86, 0x87):
+            size = 8 if op == 0x86 else S
+            reg, loc = self.modrm(size, seg)
+            a, b = self.get_rm(loc, size), self.get_r(reg, size)
+            self.set_rm(loc, b, size); self.set_r(reg, a, size)
+            return
+        # ---- MOV 88-8B ----
+        if 0x88 <= op <= 0x8B:
+            size = 8 if op in (0x88, 0x8A) else S
+            reg, loc = self.modrm(size, seg)
+            if op <= 0x89: self.set_rm(loc, self.get_r(reg, size), size)
+            else: self.set_r(reg, self.get_rm(loc, size), size)
+            return
+        if op in (0x8C, 0x8E):                           # MOV sreg (flat segments: no-op)
+            _, loc = self.modrm(16, seg)
+            if op == 0x8C: self.set_rm(loc, 0, 16)
+            return
+        if op == 0x8D:                                   # LEA
+            reg, loc = self.modrm(S, seg)
+            assert loc[0] == "m"
+            self.set_r(reg, loc[1], S)
+            return
+        if op == 0x90: return                            # NOP
+        if 0x91 <= op <= 0x97:                           # XCHG eAX, r
+            i = op & 7
+            a = self.get_r(EAX, S); self.set_r(EAX, self.get_r(i, S), S); self.set_r(i, a, S)
+            return
+        if op == 0x98:                                   # CWDE
+            self.set_r(EAX, sx16(self.get_r(EAX, 16)) & M32, 32); return
+        if op == 0x99:                                   # CDQ
+            self.set_r(EDX, (M32 if self.r[EAX] & 0x80000000 else 0), 32); return
+        if op == 0x9C: self.push(self.eflags()); return  # PUSHFD
+        if op == 0x9D: self.set_eflags(self.pop()); return
+        # ---- MOV moffs A0-A3 ----
+        if op in (0xA0, 0xA1):
+            a = self.fetch(4) + seg
+            self.set_r(EAX, self.rd(a, 1 if op == 0xA0 else S // 8), 8 if op == 0xA0 else S)
+            return
+        if op in (0xA2, 0xA3):
+            a = self.fetch(4) + seg
+            self.wr(a, self.get_r(EAX, 8 if op == 0xA2 else S), 1 if op == 0xA2 else S // 8)
+            return
+        # ---- string ops ----
+        if op in (0xA4, 0xA5, 0xAA, 0xAB, 0xA6, 0xA7, 0xAE, 0xAF, 0xAC, 0xAD):
+            self.string_op(op, S, rep)
+            return
+        if op in (0xA8, 0xA9):                           # TEST AL/eAX, imm
+            size = 8 if op == 0xA8 else S
+            self.alu_op(4, self.get_r(EAX, size), self.fetch(size // 8), size)
+            return
+        # ---- MOV r, imm B0-BF ----
+        if 0xB0 <= op <= 0xB7: self.set_r(op & 7, self.fetch(), 8); return
+        if 0xB8 <= op <= 0xBF: self.set_r(op & 7, self.fetch(S // 8), S); return
+        # ---- shift groups C0/C1/D0/D1/D3 ----
+        if op in (0xC0, 0xC1, 0xD0, 0xD1, 0xD2, 0xD3):
+            size = 8 if op in (0xC0, 0xD0, 0xD2) else S
+            kind, loc = self.modrm(size, seg)
+            cnt = (self.fetch() if op in (0xC0, 0xC1) else
+                   1 if op in (0xD0, 0xD1) else self.get_r(ECX, 8))
+            self.set_rm(loc, self.shift(kind, self.get_rm(loc, size), cnt, size), size)
+            return
+        if op == 0xC2:
+            n = self.fetch(2); self.eip = self.pop()
+            self.r[ESP] = (self.r[ESP] + n) & M32; return
+        if op == 0xC3: self.eip = self.pop(); return
+        if op in (0xC6, 0xC7):                           # MOV r/m, imm
+            size = 8 if op == 0xC6 else S
+            _, loc = self.modrm(size, seg)
+            self.set_rm(loc, self.fetch(size // 8), size)
+            return
+        if op == 0xC9:                                   # LEAVE
+            self.r[ESP] = self.r[EBP]; self.r[EBP] = self.pop(); return
+        if op == 0xCD:                                   # INT imm
+            n = self.fetch()
+            if n == 0x80 and self.syscall:
+                self.syscall(self)
+                return
+            raise CPUError(f"INT {n:#x}")
+        # ---- group F6/F7: TEST/NOT/NEG/MUL/IMUL/DIV/IDIV ----
+        if op in (0xF6, 0xF7):
+            size = 8 if op == 0xF6 else S
+            kind, loc = self.modrm(size, seg)
+            v = self.get_rm(loc, size)
+            if kind in (0, 1):
+                self.alu_op(4, v, self.fetch(size // 8), size)
+            elif kind == 2:
+                self.set_rm(loc, self.alu.not_(v, size), size)
+            elif kind == 3:                              # NEG
+                r, fl = self.alu.addsub(1, 0, v, size)
+                self.setf(fl); self.set_rm(loc, r, size)
+            else:
+                self.muldiv(kind, v, size)
+            return
+        if op == 0xF8: self.f[CF] = 0; return            # CLC
+        if op == 0xF9: self.f[CF] = 1; return            # STC
+        if op == 0xFC: self.f[DF] = 0; return            # CLD
+        if op == 0xFD: self.f[DF] = 1; return            # STD
+        # ---- group FE/FF ----
+        if op in (0xFE, 0xFF):
+            size = 8 if op == 0xFE else S
+            kind, loc = self.modrm(size, seg)
+            if kind in (0, 1):
+                self.set_rm(loc, self.incdec(self.get_rm(loc, size), size, kind), size)
+            elif kind == 2: self.push(self.eip); self.eip = self.get_rm(loc, 32)
+            elif kind == 4: self.eip = self.get_rm(loc, 32)
+            elif kind == 6: self.push(self.get_rm(loc, 32))
+            else: raise CPUError(f"FF/{kind}")
+            return
+        if op == 0xE8:                                   # CALL rel32
+            d = sx32(self.fetch(4)); self.push(self.eip)
+            self.eip = (self.eip + d) & M32; return
+        if op == 0xE9:
+            d = sx32(self.fetch(4)); self.eip = (self.eip + d) & M32; return
+        if op == 0xEB:
+            d = sx8(self.fetch()); self.eip = (self.eip + d) & M32; return
+        # ---- 0F escape ----
+        if op == 0x0F:
+            self.exec_0f(self.fetch(), S, seg)
+            return
+        raise CPUError(f"opcode {op:#04x}")
+
+    def exec_0f(self, op, S, seg):
+        if 0x80 <= op <= 0x8F:                           # Jcc rel32
+            d = sx32(self.fetch(4))
+            if self.cond(op & 0xF): self.eip = (self.eip + d) & M32
+            return
+        if 0x90 <= op <= 0x9F:                           # SETcc
+            _, loc = self.modrm(8, seg)
+            self.set_rm(loc, 1 if self.cond(op & 0xF) else 0, 8)
+            return
+        if op in (0xB6, 0xB7, 0xBE, 0xBF):               # MOVZX/MOVSX
+            ssize = 8 if op in (0xB6, 0xBE) else 16
+            reg, loc = self.modrm(ssize, seg)
+            v = self.get_rm(loc, ssize)
+            if op >= 0xBE:
+                v = (sx8(v) if ssize == 8 else sx16(v)) & M32
+            self.set_r(reg, v, S)
+            return
+        if op == 0xAF:                                   # IMUL r, r/m
+            reg, loc = self.modrm(S, seg)
+            a = sx32(self.get_r(reg, S)); b = sx32(self.get_rm(loc, S))
+            full = self.alu.mul(abs(a), abs(b), S)
+            if (a < 0) != (b < 0): full = (-full) & ((1 << (2 * S)) - 1)
+            res = full & M32
+            self.f[CF] = self.f[OF] = int(sx32(res) != a * b)
+            self.set_r(reg, res, S)
+            return
+        if op in (0xA4, 0xA5):                           # SHLD
+            reg, loc = self.modrm(S, seg)
+            cnt = self.fetch() if op == 0xA4 else self.get_r(ECX, 8)
+            self.set_rm(loc, self.shd(1, self.get_rm(loc, S), self.get_r(reg, S), cnt, S), S)
+            return
+        if op in (0xAC, 0xAD):                           # SHRD
+            reg, loc = self.modrm(S, seg)
+            cnt = self.fetch() if op == 0xAC else self.get_r(ECX, 8)
+            self.set_rm(loc, self.shd(0, self.get_rm(loc, S), self.get_r(reg, S), cnt, S), S)
+            return
+        if op == 0xBC or op == 0xBD:                     # BSF/BSR
+            reg, loc = self.modrm(S, seg)
+            v = self.get_rm(loc, S)
+            self.f[ZF] = int(v == 0)
+            if v:
+                idx = (v & -v).bit_length() - 1 if op == 0xBC else v.bit_length() - 1
+                self.set_r(reg, idx, S)
+            return
+        if op == 0xA3 or op == 0xAB or op == 0xB3 or op == 0xBA:   # BT/BTS/BTR (+grp8)
+            if op == 0xBA:
+                kind, loc = self.modrm(S, seg)
+                bit = self.fetch() & (S - 1)
+            else:
+                reg, loc = self.modrm(S, seg)
+                bit = self.get_r(reg, S) & (S - 1)
+                kind = {0xA3: 4, 0xAB: 5, 0xB3: 6}[op]
+            v = self.get_rm(loc, S)
+            self.f[CF] = (v >> bit) & 1
+            if kind == 5: self.set_rm(loc, v | (1 << bit), S)
+            elif kind == 6: self.set_rm(loc, v & ~(1 << bit), S)
+            return
+        if op in (0xB0, 0xB1):                           # CMPXCHG
+            size = 8 if op == 0xB0 else S
+            reg, loc = self.modrm(size, seg)
+            dst = self.get_rm(loc, size); acc = self.get_r(EAX, size)
+            self.alu_op(7, acc, dst, size)               # CMP semantics for flags
+            if self.f[ZF]:
+                self.set_rm(loc, self.get_r(reg, size), size)
+            else:
+                self.set_r(EAX, dst, size)
+            return
+        if op in (0xC0, 0xC1):                           # XADD
+            size = 8 if op == 0xC0 else S
+            reg, loc = self.modrm(size, seg)
+            a, b = self.get_rm(loc, size), self.get_r(reg, size)
+            r = self.alu_op(0, a, b, size)
+            self.set_r(reg, a, size); self.set_rm(loc, r, size)
+            return
+        if 0xC8 <= op <= 0xCF:                           # BSWAP
+            i = op & 7; v = self.r[i]
+            self.r[i] = int.from_bytes(v.to_bytes(4, "little"), "big")
+            return
+        if op == 0xA2:                                   # CPUID
+            self.r[EAX] = self.r[EBX] = self.r[ECX] = self.r[EDX] = 0
+            return
+        if 0x40 <= op <= 0x4F:                           # CMOVcc
+            reg, loc = self.modrm(S, seg)
+            v = self.get_rm(loc, S)
+            if self.cond(op & 0xF): self.set_r(reg, v, S)
+            return
+        raise CPUError(f"0F {op:#04x}")
+
+    # ---------------- MUL/IMUL/DIV/IDIV (edx:eax forms) ----------------
+    def muldiv(self, kind, v, size):
+        a = self.get_r(EAX, size)
+        if kind == 4:                                    # MUL
+            full = self.alu.mul(a, v, size)
+            lo = full & ((1 << size) - 1); hi = full >> size
+            self.set_r(EAX, lo, size)
+            if size == 8: self.set_r(EAX, full, 16)
+            else: self.set_r(EDX, hi, size)
+            self.f[CF] = self.f[OF] = int(hi != 0)
+        elif kind == 5:                                  # IMUL
+            sa = sx8(a) if size == 8 else sx16(a) if size == 16 else sx32(a)
+            sv = sx8(v) if size == 8 else sx16(v) if size == 16 else sx32(v)
+            full = self.alu.mul(abs(sa), abs(sv), size)
+            if (sa < 0) != (sv < 0): full = (-full) & ((1 << (2 * size)) - 1)
+            lo = full & ((1 << size) - 1); hi = full >> size
+            if size == 8: self.set_r(EAX, full, 16)
+            else: self.set_r(EAX, lo, size); self.set_r(EDX, hi, size)
+            sign_ext = ((1 << size) - 1) if lo >> (size - 1) else 0
+            self.f[CF] = self.f[OF] = int(hi != sign_ext)
+        else:                                            # DIV/IDIV
+            if size == 8:
+                num = self.get_r(EAX, 16)
+            else:
+                num = (self.get_r(EDX, size) << size) | a
+            if kind == 6:                                # DIV
+                q, r = self.alu.divmod_(num, v, 2 * size)
+                if q >= (1 << size): raise CPUError("#DE overflow")
+            else:                                        # IDIV
+                bits2 = 2 * size
+                snum = num - (1 << bits2) if num >> (bits2 - 1) else num
+                sden = sx8(v) if size == 8 else sx16(v) if size == 16 else sx32(v)
+                q0, r0 = self.alu.divmod_(abs(snum), abs(sden), bits2)
+                q = -q0 if (snum < 0) != (sden < 0) else q0
+                r = -r0 if snum < 0 else r0
+                if not (-(1 << (size - 1)) <= q < (1 << (size - 1))):
+                    raise CPUError("#DE overflow")
+                q &= (1 << size) - 1; r &= (1 << size) - 1
+            if size == 8:
+                self.set_r(EAX, q, 8); self.set_r(4, r, 8)     # AH
+            else:
+                self.set_r(EAX, q, size); self.set_r(EDX, r, size)
+
+    # ---------------- string ops ----------------
+    def string_op(self, op, S, rep):
+        size = 8 if op in (0xA4, 0xAA, 0xA6, 0xAE, 0xAC) else S
+        n = size // 8
+        step = -n if self.f[DF] else n
+        def one():
+            si, di = self.r[ESI], self.r[EDI]
+            if op in (0xA4, 0xA5):                       # MOVS
+                self.wr(di, self.rd(si, n), n)
+                self.r[ESI] = (si + step) & M32; self.r[EDI] = (di + step) & M32
+            elif op in (0xAA, 0xAB):                     # STOS
+                self.wr(di, self.get_r(EAX, size), n)
+                self.r[EDI] = (di + step) & M32
+            elif op in (0xAC, 0xAD):                     # LODS
+                self.set_r(EAX, self.rd(si, n), size)
+                self.r[ESI] = (si + step) & M32
+            elif op in (0xA6, 0xA7):                     # CMPS
+                self.alu_op(7, self.rd(si, n), self.rd(di, n), size)
+                self.r[ESI] = (si + step) & M32; self.r[EDI] = (di + step) & M32
+            else:                                        # SCAS
+                self.alu_op(7, self.get_r(EAX, size), self.rd(di, n), size)
+                self.r[EDI] = (di + step) & M32
+        if rep is None:
+            one(); return
+        cmp_op = op in (0xA6, 0xA7, 0xAE, 0xAF)
+        while self.r[ECX]:
+            one()
+            self.r[ECX] = (self.r[ECX] - 1) & M32
+            if cmp_op:
+                if rep == "e" and not self.f[ZF]: break
+                if rep == "ne" and self.f[ZF]: break

x86_linux.py

@@ -0,0 +1,241 @@
+"""
+x86_linux.py -- minimal Linux userland around the x86 core: static ELF loader,
+stack/auxv setup, and the i386 int-0x80 syscall shim. This is the orchestrator
+shell (all wiring) -- the analogue of the GB console around the SM83.
+
+Just enough POSIX for a static musl binary: write/writev for output, read/open/
+close/lseek over an in-memory FS, brk + anonymous mmap2 for malloc, the i386
+TLS dance (set_thread_area + %gs), clock_gettime, and exit_group.
+
+Special fds let a host front-end talk to the program without a kernel:
+  fd 100: DG_DrawFrame writes the framebuffer here (host captures frames)
+  fd 101: key events are read from here (host-provided queue)
+"""
+import struct, time
+from x86_core import X86, CPUError, EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP, M32
+
+MEM_SIZE = 0x08000000          # 128 MB flat
+STACK_TOP = 0x07FF0000
+MMAP_BASE = 0x04000000
+
+ENOSYS, EBADF, ENOENT, ENOTTY, EINVAL = 38, 9, 2, 25, 22
+
+
+class Linux386:
+    def __init__(self, elf_bytes, argv=("prog",), fs=None, trace_sys=False):
+        self.mem = bytearray(MEM_SIZE)
+        self.cpu = X86(self.mem)
+        self.cpu.syscall = self.do_syscall
+        self.fs = dict(fs or {})              # path -> bytes
+        self.fds = {0: None, 1: None, 2: None}
+        self.next_fd = 3
+        self.stdout = bytearray()
+        self.frames = []                      # fd 100 writes land here
+        self.keys = []                        # fd 101 reads consume this
+        self.brk = 0
+        self.mmap_ptr = MMAP_BASE
+        self.trace = trace_sys
+        self.tls_base = 0
+        self.clock_ns = 0
+        self.load_elf(elf_bytes, argv)
+
+    # ---------------- ELF ----------------
+    def load_elf(self, b, argv):
+        assert b[:4] == b"\x7fELF" and b[4] == 1, "need ELF32"
+        e_entry, e_phoff = struct.unpack_from("<II", b, 24)
+        e_phentsize, e_phnum = struct.unpack_from("<HH", b, 42)
+        phdr_vaddr = 0
+        top = 0
+        for i in range(e_phnum):
+            off = e_phoff + i * e_phentsize
+            p_type, p_offset, p_vaddr, _, p_filesz, p_memsz, p_flags, _ = \
+                struct.unpack_from("<8I", b, off)
+            if p_type == 1:                                   # PT_LOAD
+                self.mem[p_vaddr:p_vaddr + p_filesz] = b[p_offset:p_offset + p_filesz]
+                top = max(top, p_vaddr + p_memsz)
+                if p_offset <= e_phoff < p_offset + p_filesz:
+                    phdr_vaddr = p_vaddr + (e_phoff - p_offset)
+            elif p_type == 6:                                 # PT_PHDR
+                phdr_vaddr = p_vaddr
+        self.brk = (top + 0xFFF) & ~0xFFF
+
+        # ---- stack: argc argv envp auxv ----
+        sp = STACK_TOP
+        def push_bytes(data):
+            nonlocal sp
+            sp -= len(data); self.mem[sp:sp + len(data)] = data
+            return sp
+        arg_ptrs = [push_bytes(a.encode() + b"\0") for a in argv]
+        rnd = push_bytes(bytes(range(16)))
+        sp &= ~0xF
+        aux = [(3, phdr_vaddr), (4, e_phentsize), (5, e_phnum), (6, 4096),
+               (9, e_entry), (11, 1000), (12, 1000), (13, 1000), (14, 1000),
+               (16, 0), (17, 100), (23, 0), (25, rnd), (0, 0)]
+        blob = b""
+        for k, v in aux:
+            blob += struct.pack("<II", k, v)
+        blob = struct.pack("<I", len(argv)) \
+             + b"".join(struct.pack("<I", p) for p in arg_ptrs) + b"\0\0\0\0" \
+             + b"\0\0\0\0" + blob                              # empty envp
+        sp -= len(blob); sp &= ~0xF
+        self.mem[sp:sp + len(blob)] = blob
+        self.cpu.r[ESP] = sp
+        self.cpu.eip = e_entry
+
+    # ---------------- syscalls ----------------
+    def cstr(self, a):
+        e = self.mem.index(b"\0", a)
+        return self.mem[a:e].decode("latin1")
+
+    def do_syscall(self, cpu):
+        n = cpu.r[EAX]
+        a1, a2, a3 = cpu.r[EBX], cpu.r[ECX], cpu.r[EDX]
+        r = self.sys(n, a1, a2, a3, cpu)
+        if self.trace:
+            print(f"  sys{n}({a1:#x},{a2:#x},{a3:#x}) = {r:#x}" if r >= 0
+                  else f"  sys{n} = -{-r}")
+        cpu.r[EAX] = r & M32
+
+    def sys(self, n, a1, a2, a3, cpu):
+        if n in (1, 252):                                     # exit / exit_group
+            cpu.exited = a1
+            return 0
+        if n == 3 or n == 145:                                # read / readv
+            return self.do_read(n, a1, a2, a3)
+        if n == 4 or n == 146:                                # write / writev
+            return self.do_write(n, a1, a2, a3)
+        if n == 5:                                            # open
+            path = self.cstr(a1)
+            if path not in self.fs:
+                if a2 & 0x40:                                 # O_CREAT
+                    self.fs[path] = b""
+                else:
+                    return -ENOENT
+            if a2 & 0x200:                                    # O_TRUNC
+                self.fs[path] = b""
+            self.fds[self.next_fd] = [path, 0]
+            self.next_fd += 1
+            return self.next_fd - 1
+        if n == 6: self.fds.pop(a1, None); return 0           # close
+        if n == 19 or n == 140:                               # lseek / _llseek
+            f = self.fds.get(a1)
+            if not f: return -EBADF
+            if n == 19:
+                off, whence = (a2 if a2 < 0x80000000 else a2 - (1 << 32)), a3
+            else:
+                off = (a2 << 32) | a3
+                whence = self.cpu.r[EDI]
+            size = len(self.fs[f[0]])
+            f[1] = off if whence == 0 else f[1] + off if whence == 1 else size + off
+            if n == 140:
+                self.cpu.wr(self.cpu.r[ESI], f[1], 8)
+                return 0
+            return f[1]
+        if n == 45:                                           # brk
+            if a1: self.brk = a1
+            return self.brk
+        if n == 54: return -ENOTTY                            # ioctl
+        if n == 90 or n == 192:                               # mmap / mmap2
+            length = a2
+            ptr = self.mmap_ptr
+            self.mmap_ptr = (self.mmap_ptr + length + 0xFFF) & ~0xFFF
+            return ptr
+        if n == 91: return 0                                  # munmap
+        if n == 125: return 0                                 # mprotect
+        if n in (174, 175, 126): return 0                     # signals: ignore
+        if n == 197 or n == 195:                              # fstat64/stat64 -> zeros
+            self.mem[a2:a2 + 96] = bytes(96)
+            return 0
+        if n == 243:                                          # set_thread_area
+            entry = self.cpu.rd(a1, 4)
+            base = self.cpu.rd(a1 + 4, 4)
+            self.cpu.gs_base = base
+            if entry == M32:
+                self.cpu.wr(a1, 6, 4)                         # assign entry 6
+            return 0
+        if n == 258: return 1                                 # set_tid_address -> tid
+        if n == 224: return 1                                 # gettid
+        if n == 20: return 1                                  # getpid
+        if n in (199, 200, 201, 202): return 1000             # get*id32
+        if n == 78:                                           # gettimeofday (deterministic)
+            self.clock_ns += 1_000_000
+            self.cpu.wr(a1, self.clock_ns // 10**9, 4)
+            self.cpu.wr(a1 + 4, self.clock_ns % 10**9 // 1000, 4)
+            return 0
+        if n == 265 or n == 407:                              # clock_gettime(64), deterministic
+            self.clock_ns += 1_000_000
+            s, ns = self.clock_ns // 10**9, self.clock_ns % 10**9
+            if n == 265:
+                self.cpu.wr(a2, s, 4); self.cpu.wr(a2 + 4, ns, 4)
+            else:
+                self.cpu.wr(a2, s, 8); self.cpu.wr(a2 + 8, ns, 4)
+            return 0
+        if n == 162 or n == 158:                              # nanosleep / yield
+            return 0
+        if n == 122:                                          # uname
+            self.mem[a1:a1 + 65 * 6] = bytes(65 * 6)
+            for i, s in enumerate([b"Linux", b"neural", b"5.0.0", b"#1", b"i686", b""]):
+                self.mem[a1 + 65 * i:a1 + 65 * i + len(s)] = s
+            return 0
+        if n == 33: return -ENOENT                            # access
+        if n == 221: return 0                                 # fcntl64
+        if n == 240: return 0                                 # futex
+        if n == 270: return 0                                 # tgkill
+        if n == 39: return 0                                  # mkdir
+        if n in (10, 38, 12): return 0                        # unlink/rename/chdir
+        if n == 13:                                           # time (deterministic)
+            self.clock_ns += 10**9
+            t = self.clock_ns // 10**9
+            if a1: self.cpu.wr(a1, t, 4)
+            return t
+        if n == 183:                                          # getcwd
+            self.mem[a1:a1+2] = b"/" + bytes(1)
+            return 2
+        if n == 85: return -EINVAL                            # readlink
+        raise CPUError(f"unimplemented syscall {n}")
+
+    def do_read(self, n, fd, buf, cnt):
+        if fd == 101:                                         # key queue
+            if not self.keys: return 0
+            data = bytes(self.keys[:cnt]); del self.keys[:cnt]
+            self.mem[buf:buf + len(data)] = data
+            return len(data)
+        f = self.fds.get(fd)
+        if not f: return -EBADF
+        if n == 145:                                          # readv
+            total = 0
+            for i in range(cnt):
+                p = self.cpu.rd(buf + 8 * i, 4); l = self.cpu.rd(buf + 8 * i + 4, 4)
+                total += self.do_read(3, fd, p, l)
+            return total
+        data = self.fs[f[0]][f[1]:f[1] + cnt]
+        self.mem[buf:buf + len(data)] = data
+        f[1] += len(data)
+        return len(data)
+
+    def do_write(self, n, fd, buf, cnt):
+        if n == 146:                                          # writev
+            total = 0
+            for i in range(cnt):
+                p = self.cpu.rd(buf + 8 * i, 4); l = self.cpu.rd(buf + 8 * i + 4, 4)
+                total += self.do_write(4, fd, p, l)
+            return total
+        data = bytes(self.mem[buf:buf + cnt])
+        if fd in (1, 2): self.stdout += data
+        elif fd == 100: self.frames.append(data)
+        elif fd in self.fds and self.fds[fd]:
+            path, off = self.fds[fd]
+            cur = self.fs[path]
+            if off > len(cur): cur = cur + bytes(off - len(cur))
+            self.fs[path] = cur[:off] + data + cur[off + len(data):]
+            self.fds[fd][1] = off + len(data)
+        return cnt
+
+    # ---------------- run ----------------
+    def run(self, max_instr=200_000_000):
+        cpu = self.cpu
+        for _ in range(max_instr):
+            cpu.step()
+            if cpu.exited is not None:
+                return cpu.exited
+        raise RuntimeError("instruction budget exhausted")

x86_units.py

@@ -0,0 +1,342 @@
+"""
+x86_units.py -- the i386 integer datapath as verified-exact neural units.
+
+Same discipline as the Game Boy bricks: every unit's golden semantics are
+enumerated over its COMPLETE input domain, a bit-level MLP is trained on the
+whole space, and a pass is N/N. Anything wider than a unit's domain is COMPOSED
+from verified slices the way the silicon does it:
+
+  32-bit add/sub      = four ADC8/SBB8 slices, carry rippled
+                        (CF chains; OF/SF read from the top slice; AF/PF from
+                         the low slice; ZF = AND of slice ZFs)
+  shifts/rotates by k = k applications of 1-bit slice units (domain 512 each)
+                        through the byte lanes
+  32x32 multiply      = 8x8->16 partial products (domain 65536) + ADC trees
+  divide              = restoring division: 32 iterations of verified
+                        shift/subtract/compare slices
+
+x86 flag semantics per slice:
+  CF  carry/borrow out of the slice (chained)
+  OF  signed overflow of the slice (meaningful for the top slice)
+  SF  bit 7 of the slice result   (meaningful for the top slice)
+  ZF  slice result == 0           (composed by AND across slices)
+  AF  carry out of bit 3          (meaningful for the low slice)
+  PF  even parity of the slice    (x86 PF is parity of the LOW byte only)
+"""
+import os, time
+import numpy as np, torch, torch.nn as nn
+
+torch.manual_seed(0); np.random.seed(0); torch.set_num_threads(1)
+CACHE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "models")
+os.makedirs(CACHE, exist_ok=True)
+
+
+def bits(x, n):
+    x = np.asarray(x)
+    return ((x[:, None] >> np.arange(n)[None]) & 1).astype(np.float32)
+
+PARITY = np.array([bin(i).count("1") % 2 == 0 for i in range(256)], np.int64)
+
+
+class BitMLP(nn.Module):
+    def __init__(self, nin, nout, h=256):
+        super().__init__()
+        self.net = nn.Sequential(nn.Linear(nin, h), nn.ReLU(),
+                                 nn.Linear(h, h), nn.ReLU(), nn.Linear(h, nout))
+    def forward(self, x): return self.net(x)
+
+
+def _ok(net, X, Y):
+    with torch.no_grad():
+        outs = []
+        for i in range(0, X.shape[0], 65536):
+            outs.append((net(X[i:i+65536]) > 0).float() == Y[i:i+65536])
+        return bool(torch.cat(outs).all())
+
+def train_verify(name, X, Y, lr=3e-3, bs=4096, max_steps=60000, cap=600):
+    X = torch.tensor(X); Y = torch.tensor(Y)
+    net = BitMLP(X.shape[1], Y.shape[1])
+    path = os.path.join(CACHE, f"{name}.pt")
+    if os.path.exists(path):
+        net.load_state_dict(torch.load(path, weights_only=True))
+        if _ok(net, X, Y):
+            print(f"  {name:9s} {X.shape[0]:6d}/{X.shape[0]:<6d} EXACT (cached)", flush=True)
+            return net
+    opt = torch.optim.Adam(net.parameters(), lr)
+    lossf = nn.BCEWithLogitsLoss(); N = X.shape[0]; t0 = time.time()
+    for s in range(1, max_steps + 1):
+        idx = torch.randint(0, N, (min(bs, N),))
+        opt.zero_grad(); lossf(net(X[idx]), Y[idx]).backward(); opt.step()
+        if s % 500 == 0 and (_ok(net, X, Y) or time.time() - t0 > cap):
+            break
+    ok = _ok(net, X, Y)
+    print(f"  {name:9s} {X.shape[0]:6d}/{X.shape[0]:<6d} "
+          f"{'EXACT' if ok else 'NOT EXACT'} ({time.time()-t0:.0f}s)", flush=True)
+    if not ok:
+        raise RuntimeError(f"unit {name} failed exact verification")
+    torch.save(net.state_dict(), path)
+    return net
+
+
+# ===================== golden slice semantics, full domains =====================
+def dom_abc():
+    i = np.arange(131072); return i >> 9, (i >> 1) & 0xFF, i & 1
+
+def u_ADC8():
+    a, b, c = dom_abc(); t = a + b + c; res = t & 0xFF
+    CF = t > 0xFF
+    OF = ((~(a ^ b)) & (a ^ res) & 0x80) != 0
+    SF = res >> 7; ZF = res == 0
+    AF = ((a & 0xF) + (b & 0xF) + c) > 0xF
+    X = np.concatenate([bits(a, 8), bits(b, 8), c[:, None].astype(np.float32)], 1)
+    Y = np.stack([CF, OF, SF, ZF, AF], 1).astype(np.float32)
+    return X, np.concatenate([bits(res, 8), Y], 1)
+
+def u_SBB8():
+    a, b, c = dom_abc(); t = a - b - c; res = t & 0xFF
+    CF = t < 0
+    OF = (((a ^ b)) & (a ^ res) & 0x80) != 0
+    SF = res >> 7; ZF = res == 0
+    AF = ((a & 0xF) - (b & 0xF) - c) < 0
+    X = np.concatenate([bits(a, 8), bits(b, 8), c[:, None].astype(np.float32)], 1)
+    Y = np.stack([CF, OF, SF, ZF, AF], 1).astype(np.float32)
+    return X, np.concatenate([bits(res, 8), Y], 1)
+
+def u_logic(f):
+    a = np.repeat(np.arange(256), 256); b = np.tile(np.arange(256), 256)
+    res = f(a, b) & 0xFF
+    SF = res >> 7; ZF = res == 0
+    X = np.concatenate([bits(a, 8), bits(b, 8)], 1)
+    Y = np.concatenate([bits(res, 8),
+                        np.stack([SF, ZF], 1).astype(np.float32)], 1)
+    return X, Y
+
+def u_SHL1():     # (byte, carry_in_bit) -> (byte<<1 | cin, carry_out = old bit7)
+    v = np.repeat(np.arange(256), 2); c = np.tile(np.arange(2), 256)
+    res = ((v << 1) | c) & 0xFF; co = v >> 7
+    X = np.concatenate([bits(v, 8), c[:, None].astype(np.float32)], 1)
+    return X, np.concatenate([bits(res, 8), co[:, None].astype(np.float32)], 1)
+
+def u_SHR1():     # (byte, carry_in_bit_into_top) -> (cin<<7 | byte>>1, carry_out = old bit0)
+    v = np.repeat(np.arange(256), 2); c = np.tile(np.arange(2), 256)
+    res = (v >> 1) | (c << 7); co = v & 1
+    X = np.concatenate([bits(v, 8), c[:, None].astype(np.float32)], 1)
+    return X, np.concatenate([bits(res, 8), co[:, None].astype(np.float32)], 1)
+
+def u_MASK8():    # (byte, bit) -> byte*bit : the multiplier partial-product slice
+    v = np.repeat(np.arange(256), 2); c = np.tile(np.arange(2), 256)
+    res = v * c
+    X = np.concatenate([bits(v, 8), c[:, None].astype(np.float32)], 1)
+    return X, bits(res, 8)
+
+def u_NOT8():
+    v = np.arange(256); return bits(v, 8), bits(~v & 0xFF, 8)
+
+def u_FLAGS8():   # res byte -> SF, ZF8, PF (post-hoc flag extraction for shifts etc.)
+    v = np.arange(256)
+    return bits(v, 8), np.stack([v >> 7, v == 0, PARITY[v]], 1).astype(np.float32)
+
+
+# ===================== decode tables (enumerable lookups) =====================
+# prefix classification of a byte in 32-bit code
+PFX = {0x66: 1, 0x67: 2, 0xF0: 3, 0xF2: 4, 0xF3: 5,
+       0x26: 6, 0x2E: 6, 0x36: 6, 0x3E: 6, 0x64: 6, 0x65: 6}
+
+def u_prefix():   # byte -> is_prefix(1) + class(3 bits)
+    v = np.arange(256)
+    isp = np.array([1 if b in PFX else 0 for b in v], np.float32)
+    cls = np.array([PFX.get(b, 0) for b in v])
+    return bits(v, 8), np.concatenate([isp[:, None], bits(cls, 3)], 1)
+
+def u_modrm():    # modrm byte -> mod(2) reg(3) rm(3)
+    v = np.arange(256)
+    return bits(v, 8), np.concatenate([bits(v >> 6, 2), bits((v >> 3) & 7, 3),
+                                       bits(v & 7, 3)], 1)
+
+def u_sib():      # sib byte -> scale(2) index(3) base(3)
+    v = np.arange(256)
+    return bits(v, 8), np.concatenate([bits(v >> 6, 2), bits((v >> 3) & 7, 3),
+                                       bits(v & 7, 3)], 1)
+
+
+# ===================== build / load all =====================
+def build_all():
+    print("Training/loading + exhaustively verifying x86 datapath units:", flush=True)
+    u = {}
+    u["ADC8"]  = train_verify("ADC8", *u_ADC8())
+    u["SBB8"]  = train_verify("SBB8", *u_SBB8())
+    u["AND8"]  = train_verify("AND8", *u_logic(lambda a, b: a & b))
+    u["OR8"]   = train_verify("OR8",  *u_logic(lambda a, b: a | b))
+    u["XOR8"]  = train_verify("XOR8", *u_logic(lambda a, b: a ^ b))
+    u["SHL1"]  = train_verify("SHL1", *u_SHL1(), bs=512, cap=60)
+    u["SHR1"]  = train_verify("SHR1", *u_SHR1(), bs=512, cap=60)
+    u["MASK8"] = train_verify("MASK8", *u_MASK8(), bs=512, cap=60)
+    u["NOT8"]  = train_verify("NOT8", *u_NOT8(), bs=256, cap=40)
+    u["FLAGS8"] = train_verify("FLAGS8", *u_FLAGS8(), bs=256, cap=40)
+    u["PREFIX"] = train_verify("PREFIX", *u_prefix(), bs=256, cap=60)
+    u["MODRM"] = train_verify("MODRM", *u_modrm(), bs=256, cap=60)
+    u["SIB"]   = train_verify("SIB", *u_sib(), bs=256, cap=60)
+    return u
+
+
+# ===================== unit APIs: golden vs neural, one signature =====================
+class GoldenUnits:
+    def adc8(self, a, b, c):
+        t = a + b + c; r = t & 0xFF
+        return (r, int(t > 0xFF), int(((~(a ^ b)) & (a ^ r) & 0x80) != 0), r >> 7,
+                int(r == 0), int(((a & 0xF) + (b & 0xF) + c) > 0xF))
+    def sbb8(self, a, b, c):
+        t = a - b - c; r = t & 0xFF
+        return (r, int(t < 0), int((((a ^ b)) & (a ^ r) & 0x80) != 0), r >> 7,
+                int(r == 0), int(((a & 0xF) - (b & 0xF) - c) < 0))
+    def logic8(self, kind, a, b):
+        r = {"AND8": a & b, "OR8": a | b, "XOR8": a ^ b}[kind] & 0xFF
+        return r, r >> 7, int(r == 0)
+    def shl1(self, v, c): return ((v << 1) | c) & 0xFF, v >> 7
+    def shr1(self, v, c): return (v >> 1) | (c << 7), v & 1
+    def mask8(self, v, bit): return v * bit
+    def not8(self, v): return ~v & 0xFF
+    def flags8(self, v): return v >> 7, int(v == 0), int(PARITY[v])
+    def prefix(self, b): return (1 if b in PFX else 0), PFX.get(b, 0)
+    def modrm(self, b): return b >> 6, (b >> 3) & 7, b & 7
+    def sib(self, b): return b >> 6, (b >> 3) & 7, b & 7
+
+
+class NeuralUnits:
+    def __init__(self, nets): self.n = nets
+    def _run(self, name, ib):
+        with torch.no_grad():
+            o = self.n[name](torch.tensor(np.array([ib], np.float32)))[0]
+        return (o > 0).long().numpy()
+    @staticmethod
+    def _i(o, a, n): return int(sum(int(o[a + i]) << i for i in range(n)))
+
+    def adc8(self, a, b, c):
+        o = self._run("ADC8", list(bits([a], 8)[0]) + list(bits([b], 8)[0]) + [c])
+        return (self._i(o, 0, 8),) + tuple(int(o[8 + i]) for i in range(5))
+    def sbb8(self, a, b, c):
+        o = self._run("SBB8", list(bits([a], 8)[0]) + list(bits([b], 8)[0]) + [c])
+        return (self._i(o, 0, 8),) + tuple(int(o[8 + i]) for i in range(5))
+    def logic8(self, kind, a, b):
+        o = self._run(kind, list(bits([a], 8)[0]) + list(bits([b], 8)[0]))
+        return self._i(o, 0, 8), int(o[8]), int(o[9])
+    def shl1(self, v, c):
+        o = self._run("SHL1", list(bits([v], 8)[0]) + [c])
+        return self._i(o, 0, 8), int(o[8])
+    def shr1(self, v, c):
+        o = self._run("SHR1", list(bits([v], 8)[0]) + [c])
+        return self._i(o, 0, 8), int(o[8])
+    def mask8(self, v, bit):
+        o = self._run("MASK8", list(bits([v], 8)[0]) + [bit])
+        return self._i(o, 0, 8)
+    def not8(self, v): return self._i(self._run("NOT8", list(bits([v], 8)[0])), 0, 8)
+    def flags8(self, v):
+        o = self._run("FLAGS8", list(bits([v], 8)[0]))
+        return int(o[0]), int(o[1]), int(o[2])
+    def prefix(self, b):
+        o = self._run("PREFIX", list(bits([b], 8)[0]))
+        return int(o[0]), self._i(o, 1, 3)
+    def modrm(self, b):
+        o = self._run("MODRM", list(bits([b], 8)[0]))
+        return self._i(o, 0, 2), self._i(o, 2, 3), self._i(o, 5, 3)
+    def sib(self, b):
+        o = self._run("SIB", list(bits([b], 8)[0]))
+        return self._i(o, 0, 2), self._i(o, 2, 3), self._i(o, 5, 3)
+
+
+# ===================== composed wide ops (wiring over verified slices) =====================
+class ALU:
+    """Composed 8/16/32-bit x86 ALU over the slice units. Returns (result, flags-dict).
+    Flag wiring: CF chained; OF/SF from top slice; AF/PF from low slice; ZF = AND."""
+    def __init__(self, u): self.u = u
+
+    def _split(self, v, size): return [(v >> (8 * i)) & 0xFF for i in range(size // 8)]
+    def _join(self, b): return sum(x << (8 * i) for i, x in enumerate(b))
+
+    def addsub(self, sub, a, b, size, cin=0):
+        u = self.u; outs = []; c = cin
+        fl = {}
+        for i, (ab, bb) in enumerate(zip(self._split(a, size), self._split(b, size))):
+            r, c, OF, SF, ZF, AF = (u.sbb8 if sub else u.adc8)(ab, bb, c)
+            outs.append(r)
+            if i == 0: fl["AF"], fl["PF"] = AF, u.flags8(r)[2]
+            fl["OF"], fl["SF"] = OF, SF
+            fl.setdefault("ZF", 1); fl["ZF"] &= ZF
+        fl["CF"] = c
+        return self._join(outs), fl
+
+    def logic(self, kind, a, b, size):
+        u = self.u; outs = []; fl = {"CF": 0, "OF": 0, "AF": 0}
+        for i, (ab, bb) in enumerate(zip(self._split(a, size), self._split(b, size))):
+            r, SF, ZF = u.logic8(kind + "8", ab, bb)
+            outs.append(r)
+            if i == 0: fl["PF"] = u.flags8(r)[2]
+            fl["SF"] = SF
+            fl.setdefault("ZF", 1); fl["ZF"] &= ZF
+        return self._join(outs), fl
+
+    def not_(self, a, size):
+        return self._join([self.u.not8(b) for b in self._split(a, size)])
+
+    def shl1(self, a, size):
+        c = 0; outs = []
+        for b in self._split(a, size):
+            r, c = self.u.shl1(b, c); outs.append(r)
+        return self._join(outs), c
+    def shr1(self, a, size, top=0):
+        outs = [0] * (size // 8); c = top
+        for i in reversed(range(size // 8)):
+            r, c = self.u.shr1((a >> (8 * i)) & 0xFF, c); outs[i] = r
+        return self._join(outs), c
+
+    def flags_of(self, v, size):
+        """SF/ZF/PF wiring for shift/rotate results."""
+        bs = self._split(v, size)
+        SF = ZF = PF = None
+        ZF = 1
+        for i, b in enumerate(bs):
+            s, z, p = self.u.flags8(b)
+            if i == 0: PF = p
+            SF = s; ZF &= z
+        return SF, ZF, PF
+
+    def mul(self, a, b, size):
+        """unsigned multiply: binary long multiplication -- for each bit j of b,
+        a MASK8-sliced partial product of a is shifted (wiring) and ADC-summed."""
+        ab = self._split(a, size)
+        acc = 0
+        for j in range(size):
+            bit = (b >> j) & 1
+            masked = self._join([self.u.mask8(x, bit) for x in ab])
+            acc = self.add_wide(acc, masked << j, 2 * size)
+        return acc
+    def add_wide(self, a, b, bits_):
+        """carry-rippled add of arbitrary width (wiring over adc8)."""
+        c = 0; out = 0
+        for i in range(bits_ // 8):
+            r, c, *_ = self.u.adc8((a >> (8*i)) & 0xFF, (b >> (8*i)) & 0xFF, c)
+            out |= r << (8 * i)
+        return out
+    def sub_wide(self, a, b, bits_):
+        c = 0; out = 0
+        for i in range(bits_ // 8):
+            r, c, *_ = self.u.sbb8((a >> (8*i)) & 0xFF, (b >> (8*i)) & 0xFF, c)
+            out |= r << (8 * i)
+        return out, c          # c = borrow
+
+    def divmod_(self, num, den, nbits):
+        """restoring division: nbits iterations of verified shift/sub/restore."""
+        if den == 0:
+            raise ZeroDivisionError("#DE")
+        q = 0; rem = 0
+        for i in reversed(range(nbits)):
+            rem = (rem << 1) | ((num >> i) & 1)        # wiring (bit select)
+            diff, borrow = self.sub_wide(rem, den, ((nbits + 7) // 8) * 8 + 8)
+            if not borrow:
+                rem = diff; q |= (1 << i)
+        return q, rem
+
+
+if __name__ == "__main__":
+    build_all()
+    print("\nALL x86 DATAPATH UNITS VERIFIED EXACT.")