phantomrt 0.1.0__py3-none-any.whl

atlas/analysis/graph_annotator.py

@@ -0,0 +1,147 @@
+"""
+Atlas -> spectrIDA graph: the annotation edge.
+
+spectrIDA builds the static map (Function/Binary nodes in Neo4j). Atlas runs the
+code and learns what actually happens. This writes Atlas's *runtime* findings back
+onto the matching Function node as ``atlas_*`` properties, so anything reading the
+graph (an LLM, the spectrIDA UI) instantly sees "this function is reachable and
+crashes on long input".
+
+Schema it targets (confirmed live):
+    (:Function {name, addr, binary, size, pseudocode, disasm, id})
+    (:Binary   {tag, i64_path})
+
+Design choices:
+  * Match by (binary, addr) primarily — addresses are stable; names get renamed.
+  * Only ever SET on EXISTING nodes (never MERGE) — Atlas annotates spectrIDA's
+    map, it does not invent functions. A miss returns 0 and is reported, not hidden.
+  * All properties are namespaced ``atlas_`` so they never collide with spectrIDA's,
+    and can be cleared wholesale.
+  * If the graph is unreachable, findings can still be dumped to JSON as a fallback.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Optional
+
+
+_PRIM = (str, int, float, bool)
+
+
+def _coerce(v):
+    """Neo4j properties must be primitives or lists of primitives; JSON-encode
+    anything richer (dicts, mixed lists) so nothing is silently dropped."""
+    if isinstance(v, _PRIM) or v is None:
+        return v
+    if isinstance(v, (list, tuple)) and all(isinstance(x, _PRIM) for x in v):
+        return list(v)
+    return json.dumps(v, default=str)
+
+
+class GraphAnnotator:
+    def __init__(self, uri: str = "bolt://localhost:7687", user: str = "neo4j",
+                 password: Optional[str] = None, driver=None, log=print,
+                 prefix: str = "atlas_"):
+        self.log = log
+        # property namespace: "atlas_" standalone, "dyn_" when driven from spectrIDA.
+        self.prefix = prefix
+        if driver is not None:
+            self._driver = driver
+        else:
+            from neo4j import GraphDatabase
+            self._driver = GraphDatabase.driver(uri, auth=(user, password))
+
+    @classmethod
+    def from_spectrida_config(cls, path: Optional[str] = None, log=print):
+        """Build from ~/.spectrida/config.toml ([graph] password)."""
+        import tomllib
+        p = Path(path) if path else Path.home() / ".spectrida" / "config.toml"
+        cfg = tomllib.loads(p.read_text())
+        pw = cfg.get("graph", {}).get("password")
+        uri = cfg.get("graph", {}).get("uri", "bolt://localhost:7687")
+        return cls(uri=uri, user=cfg.get("graph", {}).get("user", "neo4j"),
+                   password=pw, log=log)
+
+    def close(self):
+        self._driver.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # ── matching helper ──────────────────────────────────────────────────────
+    @staticmethod
+    def _match(addr, name):
+        if addr is not None:
+            return "MATCH (f:Function {binary:$binary, addr:$addr})", {"addr": addr}
+        if name is not None:
+            return "MATCH (f:Function {binary:$binary, name:$name})", {"name": name}
+        raise ValueError("need addr or name to identify the function")
+
+    # ── write ────────────────────────────────────────────────────────────────
+    def annotate(self, binary: str, facts: dict, *, addr=None, name=None) -> int:
+        """Stamp prefixed runtime facts onto a Function node. Returns #matched."""
+        match, key = self._match(addr, name)
+        p = self.prefix
+        props = {(k if k.startswith(p) else f"{p}{k}"): _coerce(v)
+                 for k, v in facts.items()}
+        props[f"{p}updated"] = time.strftime("%Y-%m-%dT%H:%M:%S")
+        with self._driver.session() as s:
+            n = s.run(f"{match} SET f += $props RETURN count(f) AS n",
+                      binary=binary, props=props, **key).single()["n"]
+        if n == 0:
+            self.log(f"[annotate] no match for binary={binary} {key} — nothing written")
+        else:
+            self.log(f"[annotate] wrote {len(props)} {p}* props to {n} node(s) "
+                     f"(binary={binary} {key})")
+        return n
+
+    def annotate_fuzz_run(self, binary: str, fuzz_env, *, addr=None, name=None) -> int:
+        """Convenience: turn a BinaryFuzzEnv's findings into function facts."""
+        s = fuzz_env.summary()
+        crashed = s["unique_crashes"] > 0
+        kinds = sorted({k.split(":")[0] for k in s["crash_inputs"]})
+        facts = {
+            "reachable": True,
+            "crashes": crashed,
+            "crash_kinds": kinds,
+            "functions_covered": s["functions_covered"],
+            "unique_crashes": s["unique_crashes"],
+            "sample_crash_input": next(iter(s["crash_inputs"].values()), None),
+            "verdict": ("crashes on fuzzed input" if crashed
+                        else "exercised, no crash found"),
+        }
+        return self.annotate(binary, facts, addr=addr, name=name)
+
+    # ── read / clear ─────────────────────────────────────────────────────────
+    def read(self, binary: str, *, addr=None, name=None) -> dict:
+        match, key = self._match(addr, name)
+        with self._driver.session() as s:
+            rec = s.run(f"{match} RETURN properties(f) AS p",
+                        binary=binary, **key).single()
+        if not rec:
+            return {}
+        return {k: v for k, v in rec["p"].items() if k.startswith(self.prefix)}
+
+    def clear(self, binary: str, *, addr=None, name=None) -> int:
+        """Remove all prefixed props (leaves spectrIDA's own data untouched)."""
+        match, key = self._match(addr, name)
+        with self._driver.session() as s:
+            rec = s.run(f"{match} RETURN [k IN keys(f) WHERE k STARTS WITH $p] "
+                        f"AS ks", binary=binary, p=self.prefix, **key).single()
+            if not rec or not rec["ks"]:
+                return 0
+            removes = ", ".join(f"f.`{k}`" for k in rec["ks"])
+            n = s.run(f"{match} REMOVE {removes} RETURN count(f) AS n",
+                      binary=binary, **key).single()["n"]
+        return n
+
+    # ── fallback when the graph is down ──────────────────────────────────────
+    @staticmethod
+    def export_json(path: str, findings: dict) -> None:
+        Path(path).write_text(json.dumps(findings, indent=2, default=str))

atlas/analysis/spectrida_bridge.py

@@ -0,0 +1,84 @@
+"""
+The connector: spectrIDA's FormatHandler -> Atlas's emulation harness.
+
+Reuses spectrIDA's own format plugins (`spectrida.analysis.formats`) to load ANY
+supported binary (PE/Windows, NSO/Switch, ELF, .so), decompress if needed, and
+hand back the real section bytes + arch. Atlas then maps the whole image (so
+internal calls resolve = "chain emulation") and fuzzes a chosen function.
+
+This is the honest edge: real bytes, real arch, from the same plugin spectrIDA
+already trusts — no re-implementing loaders, no guessing addresses.
+"""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+from pathlib import Path
+
+from .unicorn_harness import EmulationHarness, EmuResult
+
+DEFAULT_SPECTRIDA = r"C:\Users\Administrator\Desktop\scrape\mini-mythos\spectrIDA"
+
+_PE_MACHINE = {0x8664: "x86_64", 0xAA64: "arm64", 0x14C: "x86", 0x1C0: "arm"}
+_ELF_MACHINE = {0x3E: "x86_64", 0xB7: "arm64", 0x28: "arm", 0x03: "x86"}
+
+
+def _detect_arch(path: str) -> str:
+    """Read the true CPU from the PE/ELF header (the handler may hand back None)."""
+    import struct
+    with open(path, "rb") as f:
+        head = f.read(0x40)
+        if head[:2] == b"MZ":                          # PE
+            e_lfanew = struct.unpack_from("<I", head, 0x3C)[0]
+            f.seek(e_lfanew + 4)                        # skip "PE\0\0" signature
+            machine = struct.unpack("<H", f.read(2))[0]
+            return _PE_MACHINE.get(machine, "x86_64")
+        if head[:4] == b"\x7fELF":                      # ELF
+            return _ELF_MACHINE.get(struct.unpack_from("<H", head, 18)[0], "x86_64")
+    return "x86_64"
+
+
+class EmulatedBinary:
+    """A binary loaded via spectrIDA's FormatHandler, ready to emulate functions."""
+
+    def __init__(self, path: str, spectrida_path: str = DEFAULT_SPECTRIDA):
+        if spectrida_path and spectrida_path not in sys.path:
+            sys.path.insert(0, spectrida_path)
+        from spectrida.analysis.formats.registry import detect
+
+        self.path = path
+        self.handler = detect(path)
+        self.image = self.handler.prepare(path, tempfile.mkdtemp())
+        # The handler's arch hint can be None (PE/ELF: it lets IDA decide). Never
+        # guess — read the real machine type from the header, else emulation runs
+        # the wrong CPU (e.g. x86-64 droid.exe mis-run as arm64 = garbage).
+        self.arch = self.image.arch or _detect_arch(path)
+        self._regions = None
+
+    @property
+    def format(self) -> str:
+        return self.handler.name
+
+    def regions(self):
+        """Whole-image sections as (va, bytes), cached — real bytes so internal
+        calls land on real code; .bss/short sections zero-padded to full size."""
+        if self._regions is None:
+            regs = []
+            for s in self.image.sections:
+                va = self.image.image_base + s.va
+                data = self.handler.read_bytes(self.image, va, va + s.vsize)
+                if len(data) < s.vsize:
+                    data = data + b"\x00" * (s.vsize - len(data))
+                regs.append((va, data))
+            self._regions = regs
+        return self._regions
+
+    def emulate(self, entry_addr: int, input_bytes: bytes = b"",
+                max_insns: int = 20000) -> EmuResult:
+        """Emulate the function at ``entry_addr`` with the whole image mapped and
+        out-of-chain calls / syscalls stubbed. arg0 points at the fuzzable input
+        buffer (so a C++ ``this`` reads fuzzed object memory)."""
+        h = EmulationHarness(self.arch, max_insns=max_insns)
+        return h.run(regions=self.regions(), entry=entry_addr,
+                     input_bytes=input_bytes, stub_calls=True)

atlas/analysis/unicorn_harness.py

@@ -0,0 +1,337 @@
+"""
+The hard edge: exercise ONE function by CPU emulation — no OS, any architecture.
+
+spectrIDA's targets are ARM64 (Switch NSO) and Android .so — they can't run in
+the WSL VM. So instead of *running the program*, we emulate the function's raw
+machine code with Unicorn: map its bytes, set up a stack + an input buffer, point
+the first argument at the input, run for a bounded number of instructions, and
+catch the faults. A function that dereferences an input-derived bad pointer, walks
+off a buffer, etc. shows up as an unmapped-memory fault — a real crash signal,
+found without a Switch in sight.
+
+Arch-agnostic: pass ``arch`` ("arm64", "x86_64", "arm", "x86") — which is exactly
+what spectrIDA's FormatHandler hands us via ``PreparedImage.arch``. So the same
+harness fuzzes a Windows PE function (x86-64) and an Odyssey NSO function (arm64).
+
+Honest limits: this emulates a function *in a vacuum*. Pure-computation functions
+(parsers, crypto, validation, string/math) work great. Functions that call into
+the OS / other libs will fetch-fault at the call unless those are stubbed — that's
+standard harness work (or graduate to Qiling for full OS emulation).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from unicorn import (
+    Uc, UcError,
+    UC_ARCH_ARM64, UC_ARCH_ARM, UC_ARCH_X86,
+    UC_MODE_ARM, UC_MODE_32, UC_MODE_64, UC_MODE_LITTLE_ENDIAN,
+    UC_HOOK_BLOCK, UC_HOOK_MEM_UNMAPPED, UC_HOOK_INSN_INVALID, UC_HOOK_INTR,
+    UC_PROT_ALL,
+    UC_MEM_READ_UNMAPPED, UC_MEM_WRITE_UNMAPPED, UC_MEM_FETCH_UNMAPPED,
+)
+
+_PAGE = 0x1000
+# a single "return" instruction per arch — used to stub out-of-chain calls
+_RET = {"arm64": b"\xc0\x03\x5f\xd6", "x86_64": b"\xc3", "arm": b"\x1e\xff\x2f\xe1"}
+
+
+def _align_down(x): return x & ~(_PAGE - 1)
+def _align_up(x): return (x + _PAGE - 1) & ~(_PAGE - 1)
+
+# memory layout (well-separated so a wild pointer lands in unmapped space = fault)
+CODE_BASE = 0x0100_0000
+CODE_SIZE = 0x0010_0000
+STACK_BASE = 0x0200_0000
+STACK_SIZE = 0x0010_0000
+INPUT_BASE = 0x0300_0000
+INPUT_SIZE = 0x0010_0000
+RET_MAGIC = 0x0AAA_0000       # unmapped sentinel: function "returns" here → clean stop
+
+_FAULT = {
+    UC_MEM_READ_UNMAPPED: "read_unmapped",
+    UC_MEM_WRITE_UNMAPPED: "write_unmapped",
+    UC_MEM_FETCH_UNMAPPED: "fetch_unmapped",
+}
+
+
+@dataclass
+class EmuResult:
+    crashed: bool
+    crash_kind: str          # read_unmapped / write_unmapped / fetch_unmapped / invalid_insn / ""
+    fault_addr: int
+    cov_ids: frozenset       # basic-block addresses hit (as hex strings)
+    blocks: int
+    returned: bool           # reached the return sentinel cleanly
+    timed_out: bool          # hit instruction budget without returning
+    new_coverage: int = 0    # blocks not seen before — the env fills this in
+    stubbed_calls: int = 0   # out-of-chain calls stubbed (return 0) instead of faulting
+    syscalls: int = 0        # svc/syscall instructions skipped
+
+    @property
+    def status(self) -> str:
+        if self.crashed:
+            # a fault on a near-null address is almost always an uninitialized
+            # global/`this` pointer (missing live state), NOT a real bug — say so
+            # honestly instead of crying crash.
+            return "needs_state" if self.fault_addr < 0x10000 else "crash"
+        if self.returned:
+            return "clean"
+        return "inconclusive"    # ran out of budget / couldn't complete faithfully
+
+    @property
+    def note(self) -> str:
+        return {
+            "needs_state": f"null-ish deref @+{hex(self.fault_addr)} — uninitialized "
+                           f"global/this; needs live engine state (LLM reasons statically)",
+            "crash": f"{self.crash_kind} @ {hex(self.fault_addr)} on a wild address — "
+                     f"candidate bug (verify: is that field input-controlled?)",
+            "clean": f"returned cleanly; {self.stubbed_calls} calls stubbed",
+            "inconclusive": "hit instruction budget without returning",
+        }[self.status]
+
+    # duck-typed shims so the fuzz/annotate reuse works unchanged
+    @property
+    def exit_code(self) -> int:
+        return 139 if self.crashed else (124 if self.timed_out else 0)
+
+    @property
+    def stdout(self) -> str:
+        return ""
+
+
+class EmulationHarness:
+    """Emulates a single function's machine code with fuzzed inputs."""
+
+    def __init__(self, arch: str = "arm64", max_insns: int = 20000):
+        self.arch = arch
+        self.max_insns = max_insns
+        self._cfg = self._arch_config(arch)
+        self.arch_key = self._cfg["key"]        # normalized: arm64 / x86_64 / arm
+
+    @staticmethod
+    def _arch_config(arch: str) -> dict:
+        a = arch.lower().replace("-", "").replace("_", "")
+        if a in ("arm64", "aarch64"):
+            from unicorn import arm64_const as C
+            return {"key": "arm64", "uc": (UC_ARCH_ARM64, UC_MODE_ARM), "sp": C.UC_ARM64_REG_SP,
+                    "pc": C.UC_ARM64_REG_PC, "lr": C.UC_ARM64_REG_LR,
+                    "args": [C.UC_ARM64_REG_X0, C.UC_ARM64_REG_X1, C.UC_ARM64_REG_X2,
+                             C.UC_ARM64_REG_X3], "push_ret": False}
+        if a in ("x8664", "x64", "amd64"):
+            from unicorn import x86_const as C
+            return {"key": "x86_64", "uc": (UC_ARCH_X86, UC_MODE_64), "sp": C.UC_X86_REG_RSP,
+                    "pc": C.UC_X86_REG_RIP, "lr": None,
+                    "args": [C.UC_X86_REG_RDI, C.UC_X86_REG_RSI, C.UC_X86_REG_RDX,
+                             C.UC_X86_REG_RCX], "push_ret": True}
+        if a in ("arm", "arm32", "thumb"):
+            from unicorn import arm_const as C
+            return {"key": "arm", "uc": (UC_ARCH_ARM, UC_MODE_ARM), "sp": C.UC_ARM_REG_SP,
+                    "pc": C.UC_ARM_REG_PC, "lr": C.UC_ARM_REG_LR,
+                    "args": [C.UC_ARM_REG_R0, C.UC_ARM_REG_R1, C.UC_ARM_REG_R2,
+                             C.UC_ARM_REG_R3], "push_ret": False}
+        raise ValueError(f"unsupported arch: {arch}")
+
+    def run(self, code: bytes | None = None, input_bytes: bytes = b"", *,
+            regions=None, entry: int | None = None, stub_calls: bool = False,
+            extra_args=()) -> EmuResult:
+        """Emulate a function with fuzzed input.
+
+        Single-function mode (default): pass ``code`` — it's mapped at CODE_BASE.
+        Chain mode: pass ``regions`` = [(va, bytes), ...] (whole sections, so
+        internal calls land on real code) and ``entry`` (the function's VA).
+        ``stub_calls=True`` turns out-of-chain calls into RET-stubs (return 0) and
+        skips syscalls, so only real data faults count as crashes.
+        """
+        cfg = self._cfg
+        uc = Uc(*cfg["uc"])
+        uc.mem_map(STACK_BASE, STACK_SIZE, UC_PROT_ALL)
+        uc.mem_map(INPUT_BASE, INPUT_SIZE, UC_PROT_ALL)
+
+        if regions is None:                          # single-function mode
+            uc.mem_map(CODE_BASE, CODE_SIZE, UC_PROT_ALL)
+            uc.mem_write(CODE_BASE, code or b"")
+            start = CODE_BASE
+        else:                                        # chain mode: map sections
+            # merge page ranges first — adjacent sections can round into the same
+            # page and mapping them separately raises UC_ERR_MAP.
+            ranges = sorted((_align_down(va), _align_up(va + len(d))) for va, d in regions)
+            merged: list[list[int]] = []
+            for st, en in ranges:
+                if merged and st <= merged[-1][1]:
+                    merged[-1][1] = max(merged[-1][1], en)
+                else:
+                    merged.append([st, en])
+            for st, en in merged:
+                uc.mem_map(st, en - st, UC_PROT_ALL)
+            for va, data in regions:
+                uc.mem_write(va, data)
+            start = entry
+        if input_bytes:
+            uc.mem_write(INPUT_BASE, input_bytes[:INPUT_SIZE])
+
+        sp = STACK_BASE + STACK_SIZE // 2
+        argvals = [INPUT_BASE, len(input_bytes), *extra_args]   # arg0=input ptr, arg1=len
+        for reg, val in zip(cfg["args"], argvals):
+            uc.reg_write(reg, val & 0xFFFFFFFFFFFFFFFF)
+        if cfg["push_ret"]:
+            sp -= 8
+            uc.mem_write(sp, RET_MAGIC.to_bytes(8, "little"))
+        else:
+            uc.reg_write(cfg["lr"], RET_MAGIC)
+        uc.reg_write(cfg["sp"], sp)
+
+        cov: set[int] = set()
+        fault = {"kind": "", "addr": 0}
+        stats = {"stubbed": 0, "syscalls": 0}
+        ret_bytes = _RET.get(self.arch_key, b"\xc3")
+
+        uc.hook_add(UC_HOOK_BLOCK, lambda u, a, s, d: cov.add(a))
+
+        def on_bad_mem(u, access, address, size, value, data):
+            # a call/branch to unmapped code = an out-of-chain call → stub it
+            if stub_calls and access == UC_MEM_FETCH_UNMAPPED:
+                page = _align_down(address)
+                try:
+                    u.mem_map(page, _PAGE, UC_PROT_ALL)
+                    u.mem_write(page, ret_bytes * (_PAGE // len(ret_bytes)))
+                except UcError:
+                    pass
+                u.reg_write(cfg["args"][0], 0)      # stubbed call returns 0
+                stats["stubbed"] += 1
+                return True                          # resume → executes RET → returns
+            fault["kind"] = _FAULT.get(access, "mem_unmapped")
+            fault["addr"] = address
+            return False                             # real data fault → crash
+        uc.hook_add(UC_HOOK_MEM_UNMAPPED, on_bad_mem)
+
+        def on_bad_insn(u, data):
+            fault["kind"] = "invalid_insn"
+            fault["addr"] = u.reg_read(cfg["pc"])
+            return False
+        uc.hook_add(UC_HOOK_INSN_INVALID, on_bad_insn)
+
+        if stub_calls:                               # skip syscalls (svc/int)
+            def on_intr(u, intno, data):
+                stats["syscalls"] += 1
+                u.reg_write(cfg["args"][0], 0)
+            uc.hook_add(UC_HOOK_INTR, on_intr)
+
+        crashed = False
+        try:
+            uc.emu_start(start, RET_MAGIC, timeout=0, count=self.max_insns)
+        except UcError:
+            crashed = True
+            if not fault["kind"]:
+                fault["kind"] = "cpu_fault"
+
+        pc = uc.reg_read(cfg["pc"])
+        returned = (not crashed) and (pc == RET_MAGIC)
+        return EmuResult(
+            crashed=crashed, crash_kind=fault["kind"], fault_addr=fault["addr"],
+            cov_ids=frozenset(hex(a) for a in cov), blocks=len(cov),
+            returned=returned, timed_out=(not crashed and not returned),
+            stubbed_calls=stats["stubbed"], syscalls=stats["syscalls"],
+        )
+
+
+# ── Atlas environment: fuzz an emulated function with the curiosity loop ──────
+EMU_STATE_DIM = 14
+
+
+class EmulatedFuzzEnv:
+    """Presents a single emulated function as an Atlas env, so SelfTrainer's
+    curiosity loop learns which INPUTS crash it. Same interface as
+    BinaryFuzzEnv, so the trainer/proposer/annotator all reuse unchanged."""
+
+    def __init__(self, code: bytes, arch: str = "arm64", max_insns: int = 20000,
+                 log=print, binary: str = "emulated", addr: int = 0):
+        import numpy as np
+        from collections import Counter
+        self._np = np
+        self.harness = EmulationHarness(arch, max_insns=max_insns)
+        self.code = code
+        self.arch = arch
+        self.log = log
+        self.binary = binary
+        self.addr = addr
+        self.covered_global: set = set()
+        self.crash_inputs: dict[str, bytes] = {}
+        self.seen = Counter()
+        self._last = np.zeros(EMU_STATE_DIM, dtype=np.float32)
+        self.recoveries = 0            # emulation is sandboxed; nothing to recover
+        self.steps = 0
+
+    def get_action_dim(self):
+        from .binary_fuzz import FUZZ_ACTION_DIM
+        return FUZZ_ACTION_DIM
+
+    def get_observation_dim(self):
+        return EMU_STATE_DIM
+
+    def reset(self):
+        self._last = self._np.zeros(EMU_STATE_DIM, dtype=self._np.float32)
+        return self._last.copy()
+
+    def render(self):
+        return None
+
+    def _run(self, token: str, record: bool):
+        from .binary_fuzz import parse_token
+        _, payload = parse_token(token)
+        res = self.harness.run(self.code, payload)
+        fresh = res.cov_ids - self.covered_global
+        res.new_coverage = len(fresh)
+        if record:
+            self.covered_global |= res.cov_ids
+        return payload, res
+
+    def step(self, token: str):
+        from .binary_fuzz import input_family
+        self.steps += 1
+        payload, res = self._run(token, record=True)
+        obs = self.featurize(token, res)
+        sig = (res.crash_kind or ("timeout" if res.timed_out else "ok"),
+               min(res.blocks, 16))
+        self.seen[sig] += 1
+        reward = float(res.new_coverage) + (3.0 if res.crashed else 0.0)
+        if res.crashed:
+            key = f"{res.crash_kind}@{hex(res.fault_addr)}"
+            if key not in self.crash_inputs:
+                self.crash_inputs[key] = payload
+                self.log(f"[emu] CRASH {res.crash_kind} @ {hex(res.fault_addr)} "
+                         f"on {payload[:24]!r} — {len(self.crash_inputs)} unique")
+        self._last = obs
+        info = {"command": token, "result": res, "family": input_family(token),
+                "recovered": False, "coverage": len(self.covered_global),
+                "crashed": res.crashed}
+        return obs, reward, False, info
+
+    def run_probe(self, token: str):
+        _, res = self._run(token, record=False)
+        return self.featurize(token, res)
+
+    def featurize(self, token: str, res: EmuResult):
+        np = self._np
+        v = np.zeros(EMU_STATE_DIM, dtype=np.float32)
+        v[0] = 1.0 if res.crashed else 0.0
+        v[1] = 1.0 if res.returned else 0.0
+        v[2] = 1.0 if res.timed_out else 0.0
+        v[3] = 1.0 if res.crash_kind == "read_unmapped" else 0.0
+        v[4] = 1.0 if res.crash_kind == "write_unmapped" else 0.0
+        v[5] = 1.0 if res.crash_kind == "fetch_unmapped" else 0.0
+        v[6] = 1.0 if res.crash_kind == "invalid_insn" else 0.0
+        v[7] = min(res.blocks / 16.0, 1.0)
+        v[8] = min(res.new_coverage / 4.0, 1.0)
+        v[9] = min(len(self.covered_global) / 32.0, 1.0)
+        v[10] = 1.0 if res.fault_addr else 0.0
+        v[11] = 1.0 if res.crash_kind.startswith("write") else 0.0
+        v[13] = 1.0
+        return v
+
+    def summary(self) -> dict:
+        return {"functions_covered": len(self.covered_global),
+                "unique_crashes": len(self.crash_inputs),
+                "crash_inputs": {k: v.hex() for k, v in self.crash_inputs.items()}}
+

atlas/core/__init__.py

@@ -0,0 +1,14 @@
+from .world_model import WorldModel
+from .encoder import Encoder
+from .decoder import Decoder
+from .dynamics import DynamicsFunction, NeuralODE
+from .surprise import SurpriseDetector
+
+__all__ = [
+    "WorldModel",
+    "Encoder",
+    "Decoder",
+    "DynamicsFunction",
+    "NeuralODE",
+    "SurpriseDetector",
+]

atlas/core/decoder.py

@@ -0,0 +1,65 @@
+"""
+Decoder: Latent State → Predicted Observation
+
+The mirror of the encoder. Takes the internal
+representation and reconstructs what the
+observation SHOULD look like.
+
+If the decoder can reconstruct reality from the
+latent state, it means the latent state captured
+the important information — the model UNDERSTOOD
+what it was seeing.
+"""
+
+import torch
+import torch.nn as nn
+
+
+class Decoder(nn.Module):
+    """
+    Decodes latent state back into observation space.
+    
+    Input:  latent_state [batch, latent_dim]
+    Output: predicted_observation [batch, obs_dim]
+    """
+
+    def __init__(self, latent_dim: int, obs_dim: int, hidden_dims: list = None):
+        super().__init__()
+        
+        self.latent_dim = latent_dim
+        self.obs_dim = obs_dim
+        
+        if hidden_dims is None:
+            hidden_dims = [512, 512]
+        
+        layers = []
+        prev_dim = latent_dim
+        
+        for h_dim in hidden_dims:
+            layers.extend([
+                nn.Linear(prev_dim, h_dim),
+                nn.LayerNorm(h_dim),
+                nn.SiLU(),
+            ])
+            prev_dim = h_dim
+        
+        # Final layer: map back to observation space
+        layers.append(nn.Linear(prev_dim, obs_dim))
+        
+        self.net = nn.Sequential(*layers)
+        
+        # Initialize final layer for reasonable initial reconstructions
+        nn.init.xavier_uniform_(self.net[-1].weight, gain=0.1)
+        nn.init.zeros_(self.net[-1].bias)
+    
+    def forward(self, latent_state: torch.Tensor) -> torch.Tensor:
+        """
+        Decode latent state into predicted observation.
+        
+        Args:
+            latent_state: [batch, latent_dim]
+            
+        Returns:
+            predicted_obs: [batch, obs_dim]
+        """
+        return self.net(latent_state)