spatial-computing 0.5.0__py3-none-any.whl

spatial/q/runtime.py

@@ -0,0 +1,274 @@
+"""SPATIAL Q runtime + orchestrator.
+
+Executes `main` (classical control), dispatches:
+  * classical tasks  -> local CPU or a compute worker (SWP/0), per `on` clause / load;
+  * quantum kernels  -> compiled to SQIR, optimised, sent to a backend chosen from the
+                        circuit's ResourceEstimate (or the explicit `on <backend>`).
+Every dispatch is appended to `trace` (what ran where, why, how long).
+"""
+from __future__ import annotations
+
+import time
+from concurrent.futures import ThreadPoolExecutor
+
+import psutil
+
+from ..compute import workloads
+from . import backends
+from .compiler import CONSTS, FUNCS, SQCompileError, compile_kernel, div
+from .parser import Program, parse
+
+
+class SQRuntimeError(Exception):
+    pass
+
+
+class _Return(Exception):
+    def __init__(self, v):
+        self.v = v
+
+
+class Runtime:
+    def __init__(self, program: Program, worker_client=None, seed: int | None = None,
+                 ram_fraction: float = 0.5, out=print, default_backend: str = "statevector",
+                 noise: float = 0.0):
+        self.noise = noise
+        self.p = program
+        self.worker = worker_client
+        self.seed = seed
+        self.ram_fraction = ram_fraction
+        self.out = out
+        self.default_backend = default_backend
+        self.trace: list[dict] = []
+        self._cache: dict = {}
+        self._backends: dict[str, backends.Backend] = {}
+
+    # ---- quantum dispatch
+    def _circuit(self, name: str, args: list):
+        if name not in self.p.kernels:
+            raise SQRuntimeError(f"unknown quantum kernel '{name}'")
+        key = (name, repr(args))
+        if key not in self._cache:
+            t0 = time.perf_counter()
+            c, info = compile_kernel(self.p.kernels[name], args, kernels=self.p.kernels)
+            info["compile_s"] = time.perf_counter() - t0
+            self._cache[key] = (c, info)
+        return self._cache[key]
+
+    def _backend(self, requested: str, est) -> backends.Backend:
+        name = requested
+        reason = "explicit"
+        if requested == "auto":
+            avail = psutil.virtual_memory().available
+            if est.statevector_bytes > self.ram_fraction * avail:
+                raise SQRuntimeError(
+                    f"{est.qubits} qubits need {est.statevector_bytes / 2**30:.1f} GiB for an exact "
+                    f"state vector; only {avail / 2**30:.1f} GiB available. Not simulable here: needs "
+                    "a QPU, a larger machine or an approximate simulator.")
+            name = self.default_backend
+            reason = f"auto: state vector {est.statevector_bytes} B fits in RAM"
+        if name not in self._backends:
+            self._backends[name] = backends.get(name)
+        self._last_reason = reason
+        return self._backends[name]
+
+    def _sample(self, name, args, shots, backend):
+        c, info = self._circuit(name, args)
+        est = c.estimate()
+        b = self._backend(backend, est)
+        t0 = time.perf_counter()
+        if self.noise and b.name != "statevector":
+            raise SQRuntimeError(f"the noise option is only implemented for the built-in statevector backend, not '{b.name}'")
+        counts = b.sample(c, shots, self.seed, noise=self.noise) if self.noise else b.sample(c, shots, self.seed)
+        self.trace.append({"op": "sample", "kernel": name, "backend": b.name, "why": self._last_reason,
+                           "shots": shots, "wall_s": time.perf_counter() - t0, "resources": est.to_dict(),
+                           "optimizer": info, **({"noise": self.noise} if self.noise else {})})
+        return counts
+
+    def _expect(self, pauli, name, args, backend):
+        c, info = self._circuit(name, args)
+        est = c.estimate()
+        b = self._backend(backend, est)
+        t0 = time.perf_counter()
+        v = b.expectation(c, pauli)
+        self.trace.append({"op": "expect", "kernel": name, "backend": b.name, "pauli": pauli,
+                           "wall_s": time.perf_counter() - t0, "qubits": est.qubits})
+        return v
+
+    # ---- classical dispatch
+    def _workload(self, wname: str, kwargs: dict, target: str):
+        where, why = "cpu", "task target"
+        if target == "worker" or (target == "any" and self.worker is not None
+                                  and psutil.cpu_percent(interval=0.05) > 75):
+            if self.worker is None:
+                raise SQRuntimeError("task targets a worker but none is attached to the runtime")
+            where = "worker"
+            why = "task target" if target == "worker" else "local CPU busy > 75%"
+        elif target == "any":
+            why = "local CPU has headroom" if self.worker is not None else "no worker attached"
+        t0 = time.perf_counter()
+        if where == "worker":
+            rh, _ = self.worker.call({"op": "run", "workload": wname, "params": kwargs})
+            r = rh["result"]
+        else:
+            r = workloads.run(wname, **kwargs)
+        self.trace.append({"op": "workload", "workload": wname, "where": where, "why": why,
+                           "wall_s": time.perf_counter() - t0})
+        return r
+
+    def _call_task(self, name: str, args: list):
+        t = self.p.tasks[name]
+        if len(args) != len(t.params):
+            raise SQRuntimeError(f"task {name} expects {len(t.params)} argument(s)")
+        env = dict(zip(t.params, args))
+        try:
+            self._block(t.body, env, t.target)
+        except _Return as r:
+            return r.v
+        return None
+
+    # ---- evaluation
+    def ev(self, e, env: dict, target: str = "cpu"):
+        k = e[0]
+        if k in ("num", "str"):
+            return e[1]
+        if k == "var":
+            if e[1] in env:
+                return env[e[1]]
+            if e[1] in CONSTS:
+                return CONSTS[e[1]]
+            raise SQRuntimeError(f"line {e[2]}: unknown name '{e[1]}'")
+        if k == "neg":
+            return -self.ev(e[1], env, target)
+        if k == "not":
+            return not self.ev(e[1], env, target)
+        if k == "list":
+            return [self.ev(x, env, target) for x in e[1]]
+        if k == "index":
+            return self.ev(e[1], env, target)[self.ev(e[2], env, target)]
+        if k == "bin":
+            op = e[1]
+            a = self.ev(e[2], env, target)
+            if op == "and":
+                return a and self.ev(e[3], env, target)
+            if op == "or":
+                return a or self.ev(e[3], env, target)
+            b = self.ev(e[3], env, target)
+            return {"+": lambda: a + b, "-": lambda: a - b, "*": lambda: a * b, "/": lambda: div(a, b),
+                    "%": lambda: a % b, "==": lambda: a == b, "!=": lambda: a != b, "<": lambda: a < b,
+                    "<=": lambda: a <= b, ">": lambda: a > b, ">=": lambda: a >= b}[op]()
+        if k == "call":
+            args = [self.ev(a, env, target) for a in e[2]]
+            if e[1] in self.p.tasks:
+                return self._call_task(e[1], args)
+            if e[1] in FUNCS:
+                return FUNCS[e[1]](*args)
+            if e[1] in self.p.kernels:
+                raise SQRuntimeError(f"line {e[3]}: quantum kernel '{e[1]}' must be used with 'sample' or 'expect'")
+            raise SQRuntimeError(f"line {e[3]}: unknown function '{e[1]}'")
+        if k == "sample":
+            return self._sample(e[1], [self.ev(a, env, target) for a in e[2]],
+                                int(self.ev(e[3], env, target)), e[4])
+        if k == "expect":
+            return self._expect(e[1], e[2], [self.ev(a, env, target) for a in e[3]], e[4])
+        if k == "workload":
+            return self._workload(e[1], {kk: self.ev(v, env, target) for kk, v in e[2].items()}, target)
+        if k == "measure":
+            raise SQRuntimeError(f"line {e[2]}: 'measure' is only valid inside a quantum kernel")
+        raise SQRuntimeError(f"cannot evaluate {k}")
+
+    def _block(self, stmts, env: dict, target: str = "cpu"):
+        for s in stmts:
+            k = s[0]
+            if k == "let" or k == "assign":
+                if k == "assign" and s[1] not in env:
+                    raise SQRuntimeError(f"line {s[3]}: assignment to undeclared variable '{s[1]}'")
+                env[s[1]] = self.ev(s[2], env, target)
+            elif k == "print":
+                self.out(*[self.ev(x, env, target) for x in s[1]])
+            elif k == "for":
+                for i in range(self.ev(s[2], env, target), self.ev(s[3], env, target)):
+                    env[s[1]] = i
+                    self._block(s[4], env, target)
+            elif k == "while":
+                while self.ev(s[1], env, target):
+                    self._block(s[2], env, target)
+            elif k == "if":
+                self._block(s[2] if self.ev(s[1], env, target) else s[3], env, target)
+            elif k == "return":
+                raise _Return(self.ev(s[1], env, target))
+            elif k == "expr":
+                self.ev(s[1], env, target)
+            elif k == "parallel":
+                lets = [x for x in s[1] if x[0] in ("let", "assign")]
+                if len(lets) != len(s[1]):
+                    raise SQRuntimeError(f"line {s[2]}: a parallel block may only contain let/assignment statements")
+                t0 = time.perf_counter()
+                with ThreadPoolExecutor(len(lets)) as ex:
+                    futs = [ex.submit(self.ev, x[2], dict(env), target) for x in lets]
+                    for x, f in zip(lets, futs):
+                        env[x[1]] = f.result()
+                self.trace.append({"op": "parallel", "branches": len(lets), "wall_s": time.perf_counter() - t0})
+            else:
+                raise SQRuntimeError(f"line {s[-1]}: statement '{k}' not allowed here")
+
+    def run(self, compiled: bool = False) -> dict:
+        """compiled=True runs the classical part through generated Python (see codegen.py)
+        instead of the tree-walking interpreter; results are identical."""
+        if compiled:
+            from .codegen import run_compiled
+            return run_compiled(self)
+        env: dict = {}
+        try:
+            self._block(self.p.main, env)
+        except _Return:
+            pass
+        return env
+
+
+def run_source(src: str, compiled: bool = False, **kw) -> tuple[dict, Runtime]:
+    rt = Runtime(parse(src), **kw)
+    return rt.run(compiled=compiled), rt
+
+
+def main():
+    import argparse
+    import json
+    ap = argparse.ArgumentParser(prog="spatialq", description="SPATIAL Q compiler/runtime")
+    ap.add_argument("cmd", choices=["run", "check", "qasm", "qasm2", "ir", "qir"])
+    ap.add_argument("file")
+    ap.add_argument("--kernel", help="kernel name for qasm/ir")
+    ap.add_argument("--args", default="[]", help="JSON list of kernel arguments")
+    ap.add_argument("--seed", type=int)
+    ap.add_argument("--trace", action="store_true")
+    ap.add_argument("--compiled", action="store_true", help="compile the classical part to Python bytecode")
+    ap.add_argument("--noise", type=float, default=0.0, help="depolarising error probability per gate and qubit")
+    a = ap.parse_args()
+    src = open(a.file).read()
+    prog = parse(src)
+    if a.cmd == "check":
+        print(f"ok: {len(prog.kernels)} kernel(s), {len(prog.tasks)} task(s)")
+        return
+    if a.cmd in ("qasm", "qasm2", "ir", "qir"):
+        name = a.kernel or next(k for k, v in prog.kernels.items() if "qubit" not in v.ptypes)
+        c, info = compile_kernel(prog.kernels[name], json.loads(a.args), kernels=prog.kernels)
+        if a.cmd == "qir":
+            from .qir import to_qir
+            print(to_qir(c))
+        elif a.cmd == "qasm2":
+            print(c.to_qasm2())
+        else:
+            print(c.to_qasm3() if a.cmd == "qasm" else c.to_json())
+        return
+    rt = Runtime(prog, seed=a.seed, noise=a.noise)
+    rt.run(compiled=a.compiled)
+    if a.trace:
+        for t in rt.trace:
+            print("TRACE", json.dumps(t, default=str))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (SyntaxError, SQCompileError, SQRuntimeError, backends.BackendUnavailable) as e:
+        raise SystemExit(f"spatialq: {e}")

spatial/q/sim.py

@@ -0,0 +1,218 @@
+"""Built-in exact state-vector simulator (NumPy).
+
+Conventions (same as Qiskit, to make cross-checks direct):
+  * qubit 0 is the least-significant bit of the basis-state index;
+  * printed bitstrings show qubit n-1 on the left, qubit 0 on the right;
+  * multi-qubit gate matrices list their first qubit argument as the most significant.
+Memory: 16 bytes x 2^n. This is a classical simulation: it shows correctness, not speed-up.
+"""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from .ir import Circuit
+
+_S2 = 1 / math.sqrt(2)
+I2 = np.eye(2, dtype=complex)
+FIXED = {
+    "h": np.array([[_S2, _S2], [_S2, -_S2]], dtype=complex),
+    "x": np.array([[0, 1], [1, 0]], dtype=complex),
+    "y": np.array([[0, -1j], [1j, 0]], dtype=complex),
+    "z": np.array([[1, 0], [0, -1]], dtype=complex),
+    "s": np.array([[1, 0], [0, 1j]], dtype=complex),
+    "sdg": np.array([[1, 0], [0, -1j]], dtype=complex),
+    "t": np.array([[1, 0], [0, np.exp(1j * math.pi / 4)]], dtype=complex),
+    "tdg": np.array([[1, 0], [0, np.exp(-1j * math.pi / 4)]], dtype=complex),
+    "sx": 0.5 * np.array([[1 + 1j, 1 - 1j], [1 - 1j, 1 + 1j]], dtype=complex),
+    "cx": np.array([[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 0, 1], [0, 0, 1, 0]], dtype=complex),
+    "cz": np.diag([1, 1, 1, -1]).astype(complex),
+    "swap": np.array([[1, 0, 0, 0], [0, 0, 1, 0], [0, 1, 0, 0], [0, 0, 0, 1]], dtype=complex),
+}
+_ccx = np.eye(8, dtype=complex)
+_ccx[6:, 6:] = [[0, 1], [1, 0]]
+FIXED["ccx"] = _ccx
+
+
+def matrix(name: str, params: tuple) -> np.ndarray:
+    if name in FIXED:
+        return FIXED[name]
+    t = params[0]
+    c, s = math.cos(t / 2), math.sin(t / 2)
+    if name == "rx":
+        return np.array([[c, -1j * s], [-1j * s, c]], dtype=complex)
+    if name == "ry":
+        return np.array([[c, -s], [s, c]], dtype=complex)
+    if name == "rz":
+        return np.array([[np.exp(-1j * t / 2), 0], [0, np.exp(1j * t / 2)]], dtype=complex)
+    if name == "p":
+        return np.array([[1, 0], [0, np.exp(1j * t)]], dtype=complex)
+    if name == "cp":
+        return np.diag([1, 1, 1, np.exp(1j * t)]).astype(complex)
+    if name == "crz":
+        return np.diag([1, 1, np.exp(-1j * t / 2), np.exp(1j * t / 2)]).astype(complex)
+    raise KeyError(f"unknown gate {name}")
+
+
+class State:
+    def __init__(self, n: int):
+        self.n = n
+        self.psi = np.zeros((2,) * n, dtype=complex)
+        self.psi[(0,) * n] = 1.0
+
+    def apply(self, U: np.ndarray, qubits: tuple[int, ...]):
+        k = len(qubits)
+        axes = [self.n - 1 - q for q in qubits]
+        self.psi = np.moveaxis(
+            np.tensordot(U.reshape((2,) * (2 * k)), self.psi, axes=(list(range(k, 2 * k)), axes)),
+            list(range(k)), axes)
+
+    def prob1(self, q: int) -> float:
+        ax = self.n - 1 - q
+        return float(np.sum(np.abs(np.take(self.psi, 1, axis=ax)) ** 2))
+
+    def measure(self, q: int, rng) -> int:
+        p1 = self.prob1(q)
+        r = int(rng.random() < p1)
+        ax = self.n - 1 - q
+        sl = [slice(None)] * self.n
+        sl[ax] = 1 - r
+        self.psi[tuple(sl)] = 0
+        self.psi /= math.sqrt(p1 if r else 1 - p1)
+        return r
+
+    def reset(self, q: int, rng):
+        if self.measure(q, rng):
+            self.apply(FIXED["x"], (q,))
+
+    def probs(self) -> np.ndarray:
+        return np.abs(self.psi.reshape(-1)) ** 2
+
+    def vector(self) -> np.ndarray:
+        return self.psi.reshape(-1)
+
+
+def run_static(c: Circuit) -> State:
+    """Circuit without mid-circuit measurement / feed-forward."""
+    s = State(c.n_qubits)
+    for o in c.ops:
+        s.apply(matrix(o.name, o.params), o.qubits)
+    return s
+
+
+def is_static(c: Circuit) -> bool:
+    return all(o.name not in ("measure", "reset") and not o.cond for o in c.ops)
+
+
+_NOISE_PAULIS = ("x", "y", "z")
+
+
+def run_shot(c: Circuit, rng, noise: float = 0.0) -> State:
+    """One trajectory. noise = probability, after each gate and for each qubit it touches,
+    of a uniformly random Pauli error (single-qubit depolarising channel, Monte-Carlo)."""
+    s = State(c.n_qubits)
+    bits = [0] * c.n_cbits
+    for o in c.ops:
+        if o.cond and any(bits[b] != v for b, v in o.cond):
+            continue
+        if o.name == "measure":
+            bits[o.cbit] = s.measure(o.qubits[0], rng)
+        elif o.name == "reset":
+            s.reset(o.qubits[0], rng)
+        else:
+            s.apply(matrix(o.name, o.params), o.qubits)
+            if noise:
+                for q in o.qubits:
+                    if rng.random() < noise:
+                        s.apply(FIXED[_NOISE_PAULIS[rng.integers(3)]], (q,))
+    return s
+
+
+def branch_distribution(c: Circuit, max_branches: int = 4096) -> np.ndarray | None:
+    """Exact output distribution of a dynamic circuit by enumerating measurement branches
+    (each mid-circuit measurement splits the state in two, weighted by its probability).
+    Returns None when the branch count would exceed `max_branches`."""
+    n = c.n_qubits
+    total = np.zeros(1 << n)
+    stack = [(1.0, State(n), [0] * c.n_cbits, 0)]
+    leaves = 0
+    while stack:
+        w, s, bits, pc = stack.pop()
+        while pc < len(c.ops):
+            o = c.ops[pc]
+            pc += 1
+            if o.cond and any(bits[b] != v for b, v in o.cond):
+                continue
+            if o.name in ("measure", "reset"):
+                q = o.qubits[0]
+                p1 = s.prob1(q)
+                ax = n - 1 - q
+                for r, pr in ((0, 1 - p1), (1, p1)):
+                    if pr < 1e-15:
+                        continue
+                    s2 = State(n)
+                    s2.psi = s.psi.copy()
+                    sl = [slice(None)] * n
+                    sl[ax] = 1 - r
+                    s2.psi[tuple(sl)] = 0
+                    s2.psi /= math.sqrt(pr)
+                    b2 = list(bits)
+                    if o.name == "measure":
+                        b2[o.cbit] = r
+                    elif r:
+                        s2.apply(FIXED["x"], (q,))
+                    stack.append((w * pr, s2, b2, pc))
+                if len(stack) + leaves > max_branches:
+                    return None
+                break
+            s.apply(matrix(o.name, o.params), o.qubits)
+        else:
+            total += w * s.probs()
+            leaves += 1
+    return total
+
+
+def sample(c: Circuit, shots: int, seed: int | None = None, dynamic: str = "branch",
+           noise: float = 0.0) -> dict[str, int]:
+    """dynamic="branch": exact branch enumeration then one multinomial draw (fast);
+       dynamic="shots" : one full simulation per shot (reference implementation)."""
+    rng = np.random.default_rng(seed)
+    n = c.n_qubits
+    p = None
+    if noise:
+        if not 0 <= noise <= 1:
+            raise ValueError("noise must be a probability")
+        dynamic = "shots"                  # noisy runs are simulated trajectory by trajectory
+    elif is_static(c):
+        p = run_static(c).probs()
+    elif dynamic == "branch":
+        p = branch_distribution(c)
+    if p is not None:
+        p = p / p.sum()
+        draws = rng.multinomial(shots, p)
+        return {format(i, f"0{n}b"): int(k) for i, k in enumerate(draws) if k}
+    counts: dict[str, int] = {}
+    for _ in range(shots):
+        p = run_shot(c, rng, noise).probs()
+        i = int(rng.choice(len(p), p=p / p.sum()))
+        key = format(i, f"0{n}b")
+        counts[key] = counts.get(key, 0) + 1
+    return counts
+
+
+_PAULI = {"I": I2, "X": FIXED["x"], "Y": FIXED["y"], "Z": FIXED["z"]}
+
+
+def expectation(c: Circuit, pauli: str) -> float:
+    """Exact <psi|P|psi>. `pauli` is written like a bitstring: leftmost char acts on qubit n-1."""
+    if not is_static(c):
+        raise ValueError("expect needs a kernel without mid-circuit measurement")
+    if len(pauli) != c.n_qubits or any(ch not in _PAULI for ch in pauli):
+        raise ValueError(f"Pauli string must have {c.n_qubits} characters from IXYZ")
+    s = run_static(c)
+    psi0 = s.psi.copy()
+    for pos, ch in enumerate(pauli):
+        if ch != "I":
+            s.apply(_PAULI[ch], (c.n_qubits - 1 - pos,))
+    return float(np.real(np.vdot(psi0.reshape(-1), s.psi.reshape(-1))))

spatial/runtime/__init__.py

@@ -0,0 +1,3 @@
+"""Spatial Runtime Engine: inspect artifacts, plan an execution route, run it."""
+from .inspect import inspect, Artifact  # noqa: F401
+from .planner import plan, execute, host_caps  # noqa: F401

spatial/runtime/envs.py

@@ -0,0 +1,74 @@
+"""Environment detection and isolated Python environments (dependency management).
+
+Isolation level: separate interpreter + site-packages (venv). It protects the host's
+packages; it is NOT a security sandbox (same user, same filesystem)."""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def detect_interpreters() -> list[dict]:
+    """Language runtimes actually present on the host."""
+    out = []
+    probes = {"python3": ["--version"], "python3.14": ["--version"], "node": ["--version"],
+              "swift": ["--version"], "clang": ["--version"], "java": ["-version"], "go": ["version"],
+              "rustc": ["--version"], "ruby": ["--version"], "perl": ["-e", "print $^V"]}
+    for exe, flag in probes.items():
+        p = shutil.which(exe) or (f"/opt/local/bin/{exe}" if Path(f"/opt/local/bin/{exe}").exists() else None)
+        if not p:
+            out.append({"runtime": exe, "present": False})
+            continue
+        try:
+            r = subprocess.run([p, *flag], capture_output=True, text=True, timeout=15)
+            ver = (r.stdout or r.stderr).strip().splitlines()[0] if (r.stdout or r.stderr).strip() else ""
+            out.append({"runtime": exe, "present": r.returncode == 0, "path": p, "version": ver})
+        except Exception as e:
+            out.append({"runtime": exe, "present": False, "error": str(e)})
+    return out
+
+
+def check_requirements(python: str, requirements: list[str]) -> dict[str, str | None]:
+    """Which requirement names are missing/incompatible in `python` (installed version or None)."""
+    code = ("import importlib.metadata as m,json,sys;"
+            "print(json.dumps({n:(m.version(n) if any(d.metadata['Name'].lower()==n.lower() "
+            "for d in m.distributions()) else None) for n in sys.argv[1:]}))")
+    import json
+    names = [r.split("==")[0].split(">=")[0].strip() for r in requirements]
+    r = subprocess.run([python, "-c", code, *names], capture_output=True, text=True, timeout=60)
+    return json.loads(r.stdout)
+
+
+class IsolatedEnv:
+    def __init__(self, path: str, python: str | None = None):
+        self.path = Path(path)
+        self.python_src = python
+
+    @property
+    def python(self) -> str:
+        return str(self.path / "bin" / "python")
+
+    def create(self, requirements: list[str] | None = None) -> float:
+        import time
+        t0 = time.perf_counter()
+        uv = shutil.which("uv")
+        if uv:
+            cmd = [uv, "venv", str(self.path)] + (["--python", self.python_src] if self.python_src else [])
+            subprocess.run(cmd, check=True, capture_output=True, timeout=300)
+            if requirements:
+                subprocess.run([uv, "pip", "install", "--python", self.python, *requirements],
+                               check=True, capture_output=True, timeout=600)
+        else:
+            import sys
+            subprocess.run([self.python_src or sys.executable, "-m", "venv", str(self.path)], check=True, timeout=300)
+            if requirements:
+                subprocess.run([self.python, "-m", "pip", "install", *requirements], check=True,
+                               capture_output=True, timeout=600)
+        return time.perf_counter() - t0
+
+    def run(self, code: str, timeout: float = 120) -> subprocess.CompletedProcess:
+        return subprocess.run([self.python, "-c", code], capture_output=True, text=True, timeout=timeout)
+
+    def destroy(self):
+        shutil.rmtree(self.path, ignore_errors=True)

spatial/runtime/inspect.py

@@ -0,0 +1,48 @@
+"""Artifact inspection: identify executable format, target OS and CPU from file headers."""
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+_MACHO_CPU = {0x01000007: "x86_64", 0x0100000C: "arm64", 7: "i386", 12: "arm"}
+_ELF_MACHINE = {0x3E: "x86_64", 0xB7: "aarch64", 0x03: "i386", 0x28: "arm", 0xF3: "riscv"}
+_PE_MACHINE = {0x8664: "x86_64", 0xAA64: "aarch64", 0x014C: "i386"}
+
+
+@dataclass
+class Artifact:
+    path: str
+    format: str            # macho | elf | pe | wasm | script | unknown
+    os: str | None         # macos | linux | windows | any
+    arch: list[str]
+    detail: str = ""
+
+
+def inspect(path: str) -> Artifact:
+    with open(path, "rb") as f:
+        head = f.read(4096)
+    if len(head) >= 8 and head[:4] in (b"\xcf\xfa\xed\xfe", b"\xce\xfa\xed\xfe"):
+        cpu = struct.unpack("<I", head[4:8])[0]
+        return Artifact(path, "macho", "macos", [_MACHO_CPU.get(cpu, hex(cpu))])
+    if head[:4] in (b"\xca\xfe\xba\xbe", b"\xca\xfe\xba\xbf"):
+        n = struct.unpack(">I", head[4:8])[0]
+        if n < 20:   # fat Mach-O (a Java class file has a large "count" here)
+            archs = [_MACHO_CPU.get(struct.unpack(">I", head[8 + 20 * i:12 + 20 * i])[0], "?") for i in range(n)]
+            return Artifact(path, "macho", "macos", archs, "universal binary")
+    if head[:4] == b"\x7fELF":
+        little = head[5] == 1
+        mach = struct.unpack("<H" if little else ">H", head[18:20])[0]
+        osabi = head[7]
+        return Artifact(path, "elf", "linux" if osabi in (0, 3) else f"elf-osabi-{osabi}",
+                        [_ELF_MACHINE.get(mach, hex(mach))], "64-bit" if head[4] == 2 else "32-bit")
+    if head[:2] == b"MZ" and len(head) >= 0x40:
+        off = struct.unpack("<I", head[0x3C:0x40])[0]
+        if off + 6 <= len(head) and head[off:off + 4] == b"PE\0\0":
+            mach = struct.unpack("<H", head[off + 4:off + 6])[0]
+            return Artifact(path, "pe", "windows", [_PE_MACHINE.get(mach, hex(mach))])
+        return Artifact(path, "pe", "windows", ["?"], "DOS/unknown PE")
+    if head[:4] == b"\0asm":
+        return Artifact(path, "wasm", "any", ["wasm32"], f"version {struct.unpack('<I', head[4:8])[0]}")
+    if head[:2] == b"#!":
+        return Artifact(path, "script", "any", ["any"], head.split(b"\n", 1)[0][2:].decode(errors="replace").strip())
+    return Artifact(path, "unknown", None, [])