spatial-computing 0.5.0__py3-none-any.whl

spatial/core/model.py

@@ -0,0 +1,82 @@
+"""SPATIAL CORE data model shared by every engine.
+
+A Node exposes Resources. A Task declares what it needs. An engine produces a
+Measurement for every execution; nothing is claimed without one.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ResourceKind(str, Enum):
+    CPU = "cpu"
+    GPU = "gpu"
+    NPU = "npu"
+    RAM = "ram"
+    FAR_MEMORY = "far_memory"   # compressed / remote / storage-backed. Never reported as RAM.
+    STORAGE = "storage"
+    NETWORK = "network"
+    QPU = "qpu"
+    QSIM = "qsim"               # classical simulator of a quantum device
+
+
+@dataclass
+class Resource:
+    kind: ResourceKind
+    name: str
+    capacity: float               # cores, bytes, qubits, bits/s
+    unit: str
+    available: float | None = None
+    attrs: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Node:
+    node_id: str
+    hostname: str
+    os: str
+    arch: str
+    resources: list[Resource] = field(default_factory=list)
+    attrs: dict[str, Any] = field(default_factory=dict)
+
+    def by_kind(self, kind: ResourceKind) -> list[Resource]:
+        return [r for r in self.resources if r.kind == kind]
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        for r in d["resources"]:
+            r["kind"] = ResourceKind(r["kind"]).value
+        return d
+
+
+@dataclass
+class Task:
+    """Unit of work. `workload` names a whitelisted callable; no code is shipped."""
+    workload: str
+    params: dict[str, Any] = field(default_factory=dict)
+    needs: dict[str, float] = field(default_factory=dict)   # e.g. {"ram": 2e9, "cpu": 2}
+    task_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+
+
+@dataclass
+class Measurement:
+    """One real execution. `ok=False` rows are kept: failures are results."""
+    engine: str
+    experiment: str
+    strategy: str
+    ok: bool
+    wall_s: float
+    cpu_s: float | None = None
+    peak_rss_bytes: int | None = None
+    energy_j: float | None = None        # None when not measurable (e.g. on AC power)
+    cost_usd: float | None = None
+    metrics: dict[str, Any] = field(default_factory=dict)
+    notes: str = ""
+    ts: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        return asdict(self)

spatial/core/protocol.py

@@ -0,0 +1,167 @@
+"""SPATIAL wire protocol v1 (SWP/1): authenticated AND encrypted RPC over TCP.
+
+Handshake  server -> client : nonce_s (16 bytes)
+           client -> server : HMAC-SHA256(token, nonce_s) (32 bytes) | nonce_c (16 bytes)
+Keys       HKDF-SHA256(token, salt = nonce_s | nonce_c) -> one AES-256-GCM key per direction
+Record     u32 length | AES-GCM(ciphertext | tag), nonce = 4 zero bytes | u64 record counter
+Plaintext  u32 header_len | u32 blob_len | header (JSON utf-8) | blob (raw bytes)
+
+Properties: the token never crosses the wire; every record is confidential and
+integrity-protected; a replayed, reordered or modified record fails authentication.
+Not provided: forward secrecy (a stolen token decrypts recorded sessions) and peer
+identity beyond "knows the token". Use TLS/WireGuard on top for stronger guarantees.
+
+Safety: servers bind to 127.0.0.1 unless allow_remote=True is passed explicitly.
+No code is ever transferred: requests name allow-listed operations.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import socket
+import socketserver
+import struct
+import threading
+from typing import Callable
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+_HDR = struct.Struct(">II")
+_LEN = struct.Struct(">I")
+MAX_FRAME = 256 * 1024 * 1024
+
+
+def _recv_exact(sock: socket.socket, n: int) -> bytes:
+    buf = bytearray(n)
+    view = memoryview(buf)
+    got = 0
+    while got < n:
+        r = sock.recv_into(view[got:], n - got)
+        if r == 0:
+            raise ConnectionError("peer closed")
+        got += r
+    return bytes(buf)
+
+
+class SecureChannel:
+    """Encrypted, ordered record channel over a connected socket."""
+
+    def __init__(self, sock: socket.socket, token: bytes, nonce_s: bytes, nonce_c: bytes, is_server: bool):
+        okm = HKDF(algorithm=hashes.SHA256(), length=64, salt=nonce_s + nonce_c, info=b"SWP/1 keys").derive(token)
+        c2s, s2c = AESGCM(okm[:32]), AESGCM(okm[32:])
+        self._tx, self._rx = (s2c, c2s) if is_server else (c2s, s2c)
+        self._ntx = self._nrx = 0
+        self.sock = sock
+
+    def send(self, header: dict, blob: bytes = b"") -> None:
+        h = json.dumps(header, separators=(",", ":")).encode()
+        plain = _HDR.pack(len(h), len(blob)) + h + blob
+        ct = self._tx.encrypt(b"\0\0\0\0" + struct.pack(">Q", self._ntx), plain, None)
+        self._ntx += 1
+        self.sock.sendall(_LEN.pack(len(ct)) + ct)
+
+    def recv(self) -> tuple[dict, bytes]:
+        (n,) = _LEN.unpack(_recv_exact(self.sock, _LEN.size))
+        if n > MAX_FRAME + 64:
+            raise ValueError("record too large")
+        try:
+            plain = self._rx.decrypt(b"\0\0\0\0" + struct.pack(">Q", self._nrx), _recv_exact(self.sock, n), None)
+        except InvalidTag:
+            raise ConnectionError("record failed authentication (tampered, replayed or wrong key)")
+        self._nrx += 1
+        hl, bl = _HDR.unpack(plain[:_HDR.size])
+        if _HDR.size + hl + bl != len(plain):
+            raise ValueError("malformed record")
+        header = json.loads(plain[_HDR.size:_HDR.size + hl]) if hl else {}
+        return header, plain[_HDR.size + hl:]
+
+
+Handler = Callable[[dict, bytes], tuple[dict, bytes]]
+
+
+class RpcServer:
+    """Threaded RPC server. Loopback-only by default."""
+
+    def __init__(self, handler: Handler, token: bytes, host: str = "127.0.0.1",
+                 port: int = 0, allow_remote: bool = False):
+        if host not in ("127.0.0.1", "localhost", "::1") and not allow_remote:
+            raise PermissionError(
+                "refusing to bind a non-loopback address without allow_remote=True "
+                "(explicit user consent required to expose this machine)")
+        outer = self
+
+        class _H(socketserver.BaseRequestHandler):
+            def handle(self):
+                s = self.request
+                s.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+                nonce_s = os.urandom(16)
+                s.sendall(nonce_s)
+                try:
+                    hello = _recv_exact(s, 48)
+                except ConnectionError:
+                    return
+                if not hmac.compare_digest(hello[:32], hmac.new(token, nonce_s, hashlib.sha256).digest()):
+                    return  # silent drop on bad auth
+                ch = SecureChannel(s, token, nonce_s, hello[32:], is_server=True)
+                while True:
+                    try:
+                        header, blob = ch.recv()
+                    except (ConnectionError, OSError, ValueError):
+                        return
+                    try:
+                        rh, rb = outer.handler(header, blob)
+                        rh.setdefault("ok", True)
+                    except Exception as e:  # report, never crash the server
+                        rh, rb = {"ok": False, "error": f"{type(e).__name__}: {e}"}, b""
+                    ch.send(rh, rb)
+
+        class _S(socketserver.ThreadingTCPServer):
+            allow_reuse_address = True
+            daemon_threads = True
+
+        self.handler = handler
+        self._srv = _S((host, port), _H)
+        self.host, self.port = self._srv.server_address[:2]
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> "RpcServer":
+        self._thread = threading.Thread(target=self._srv.serve_forever, daemon=True)
+        self._thread.start()
+        return self
+
+    def serve_forever(self) -> None:
+        self._srv.serve_forever()
+
+    def stop(self) -> None:
+        self._srv.shutdown()
+        self._srv.server_close()
+
+
+class RpcClient:
+    def __init__(self, host: str, port: int, token: bytes, timeout: float = 120.0):
+        self.sock = socket.create_connection((host, port), timeout=timeout)
+        self.sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        nonce_s = _recv_exact(self.sock, 16)
+        nonce_c = os.urandom(16)
+        self.sock.sendall(hmac.new(token, nonce_s, hashlib.sha256).digest() + nonce_c)
+        self._ch = SecureChannel(self.sock, token, nonce_s, nonce_c, is_server=False)
+        self._lock = threading.Lock()
+
+    def call(self, header: dict, blob: bytes = b"") -> tuple[dict, bytes]:
+        with self._lock:
+            self._ch.send(header, blob)
+            rh, rb = self._ch.recv()
+        if not rh.get("ok", False):
+            raise RuntimeError(rh.get("error", "remote error"))
+        return rh, rb
+
+    def close(self) -> None:
+        try:
+            self.sock.close()
+        except OSError:
+            pass

spatial/core/registry.py

@@ -0,0 +1,59 @@
+"""Engine registry. Status is a claim that must be backed by `evidence`."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Status(str, Enum):
+    OPERATIONAL_PROTOTYPE = "operational-prototype"   # runs, tested, benchmarked on this Mac
+    FIRST_COMPONENTS = "first-components"             # some real tested code, not a product
+    INTERFACE_ONLY = "interface-only"                 # data model / API only
+
+
+@dataclass(frozen=True)
+class Engine:
+    key: str
+    name: str
+    package: str
+    status: Status
+    evidence: str     # test or benchmark that justifies the status
+    not_done: str     # what is explicitly NOT implemented
+
+
+ENGINES: list[Engine] = [
+    Engine("compute", "Spatial Compute Engine", "spatial.compute", Status.OPERATIONAL_PROTOTYPE,
+           "tests/test_compute.py, benchmarks/bench_cpu.py, bench_gpu.py",
+           "no real second machine tested (offload and task queue validated over loopback only); no GPU scheduling"),
+    Engine("resource", "Spatial Resource Engine (memory tiering)", "spatial.memory",
+           Status.OPERATIONAL_PROTOTYPE,
+           "tests/test_memory.py, benchmarks/bench_memory.py",
+           "user-space object store only; not kernel paging; single writer; no RDMA/CXL hardware"),
+    Engine("runtime", "Spatial Runtime Engine", "spatial.runtime", Status.OPERATIONAL_PROTOTYPE,
+           "tests/test_runtime.py, benchmarks/bench_runtime.py",
+           "Windows apps not demonstrated (no Wine / Windows image); no containers; no GUI streaming"),
+    Engine("q", "SPATIAL Q", "spatial.q", Status.OPERATIONAL_PROTOTYPE,
+           "tests/test_q.py, benchmarks/bench_q.py",
+           "no real QPU executed (OpenQASM 3 and QIR export only); simulator limited by RAM"),
+    Engine("ai", "Spatial AI Engine", "spatial.ai", Status.FIRST_COMPONENTS,
+           "tests/test_engines.py (toy transformer KV cache: restore equals recompute)",
+           "toy NumPy model only; no real LLM, no GPU; placement planner is in the private package"),
+    Engine("scientific", "Spatial Scientific & Industrial Engine", "spatial.scientific",
+           Status.FIRST_COMPONENTS, "tests/test_domains.py, tests/test_engines.py (validated jobs)",
+           "two reference jobs; no domain solvers"),
+    Engine("simulation", "Spatial Simulation Engine", "spatial.simulation", Status.FIRST_COMPONENTS,
+           "tests/test_domains.py, tests/test_engines.py (heat diffusion, N-body)", "two small solvers; no multiphysics"),
+    Engine("intelligence", "Spatial Intelligence Engine", "spatial.intelligence",
+           Status.FIRST_COMPONENTS, "tests/test_domains.py, tests/test_engines.py (predictor drives the scheduler)",
+           "least-squares runtime model only"),
+    Engine("holographic", "Spatial Holographic Engine", "spatial.holographic", Status.FIRST_COMPONENTS,
+           "tests/test_engines.py (hologram synthesis + numerical reconstruction)",
+           "numerical optics only; no display hardware, no real-time rendering"),
+]
+
+
+def table() -> str:  # noqa: D103
+    rows = ["| Engine | Status | Evidence | Not done |", "|---|---|---|---|"]
+    for e in ENGINES:
+        rows.append(f"| {e.name} | {e.status.value} | {e.evidence} | {e.not_done} |")
+    return "\n".join(rows)

spatial/holographic/__init__.py

@@ -0,0 +1,8 @@
+"""Spatial Holographic Engine — FIRST COMPONENTS (numerical only).
+
+No display hardware exists in this project. cgh.py synthesises a point-cloud hologram and
+reconstructs it numerically (verified by a test); the rest fixes the data model (voxel grid, light-field specification) and computes the data
+rates such displays would demand from the compute engine, so the requirement is explicit.
+"""
+from .model import VoxelGrid, LightFieldSpec, voxelize  # noqa: F401
+from .cgh import hologram, reconstruct, max_diffraction_angle  # noqa: F401

spatial/holographic/cgh.py

@@ -0,0 +1,40 @@
+"""Computer-generated hologram (point-source method) and numerical reconstruction.
+
+hologram(): complex field on the hologram plane from a cloud of point emitters,
+            H(x, y) = sum_j a_j * exp(i k r_j) / r_j   (textbook Fresnel/Huygens model).
+reconstruct(): angular-spectrum propagation of that field to a depth z; the intensity
+            must peak where a point emitter sits. This is numerical optics on the CPU:
+            it proves the synthesis maths, not a physical display (none exists here).
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def hologram(points: np.ndarray, amplitudes: np.ndarray, n: int, pitch: float, wavelength: float) -> np.ndarray:
+    """points [N,3] in metres (z > 0 in front of the plane); returns complex [n, n]."""
+    k = 2 * np.pi / wavelength
+    ax = (np.arange(n) - n / 2) * pitch
+    X, Y = np.meshgrid(ax, ax, indexing="xy")
+    H = np.zeros((n, n), dtype=complex)
+    for (px, py, pz), a in zip(points, amplitudes):
+        r = np.sqrt((X - px) ** 2 + (Y - py) ** 2 + pz ** 2)
+        H += a * np.exp(1j * k * r) / r
+    return H
+
+
+def reconstruct(H: np.ndarray, z: float, pitch: float, wavelength: float) -> np.ndarray:
+    """Back-propagate the hologram field by distance z (angular spectrum); returns intensity."""
+    n = H.shape[0]
+    fx = np.fft.fftfreq(n, d=pitch)
+    FX, FY = np.meshgrid(fx, fx, indexing="xy")
+    arg = 1 / wavelength ** 2 - FX ** 2 - FY ** 2
+    kz = 2 * np.pi * np.sqrt(np.maximum(arg, 0))
+    field = np.fft.ifft2(np.fft.fft2(H) * np.exp(-1j * kz * z) * (arg > 0))
+    return np.abs(field) ** 2
+
+
+def max_diffraction_angle(pitch: float, wavelength: float) -> float:
+    """Half-angle (radians) a pixel pitch can diffract: sin(theta) = wavelength / (2 * pitch).
+    Shows why holographic displays need sub-micron pixels for a wide field of view."""
+    return float(np.arcsin(min(1.0, wavelength / (2 * pitch))))

spatial/holographic/model.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class VoxelGrid:
+    occupancy: np.ndarray        # bool [nx, ny, nz]
+    origin: tuple[float, float, float]
+    voxel_size: float
+
+    @property
+    def filled(self) -> int:
+        return int(self.occupancy.sum())
+
+
+def voxelize(points: np.ndarray, voxel_size: float) -> VoxelGrid:
+    """Point cloud [N,3] -> occupancy grid."""
+    lo = points.min(axis=0)
+    idx = np.floor((points - lo) / voxel_size).astype(int)
+    shape = tuple(idx.max(axis=0) + 1)
+    occ = np.zeros(shape, dtype=bool)
+    occ[idx[:, 0], idx[:, 1], idx[:, 2]] = True
+    return VoxelGrid(occ, tuple(float(x) for x in lo), voxel_size)
+
+
+@dataclass
+class LightFieldSpec:
+    """A multi-view (light-field) display: `views` distinct images per frame."""
+    views_x: int
+    views_y: int
+    width: int
+    height: int
+    fps: float
+    bytes_per_pixel: int = 3
+
+    @property
+    def pixels_per_second(self) -> float:
+        return self.views_x * self.views_y * self.width * self.height * self.fps
+
+    @property
+    def raw_bytes_per_second(self) -> float:
+        return self.pixels_per_second * self.bytes_per_pixel
+
+    def vs_2d(self, width: int = 3840, height: int = 2160, fps: float = 60) -> float:
+        """How many 2-D displays of the given format this represents in pixel rate."""
+        return self.pixels_per_second / (width * height * fps)

spatial/intelligence/__init__.py

@@ -0,0 +1,6 @@
+"""Spatial Intelligence Engine — FIRST COMPONENTS ONLY.
+
+A power-law runtime predictor fitted on ledger measurements, so the scheduler can
+estimate a strategy's time before running it. No learned world model is claimed.
+"""
+from .predictor import PowerLawPredictor  # noqa: F401

spatial/intelligence/predictor.py

@@ -0,0 +1,51 @@
+"""time ~ a * work^b, fitted per strategy by least squares in log-log space."""
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+
+
+class PowerLawPredictor:
+    def __init__(self):
+        self._obs: dict[str, list[tuple[float, float]]] = defaultdict(list)
+        self._fit: dict[str, tuple[float, float]] = {}
+
+    def observe(self, strategy: str, work: float, seconds: float) -> None:
+        if work > 0 and seconds > 0:
+            self._obs[strategy].append((math.log(work), math.log(seconds)))
+            self._fit.pop(strategy, None)
+
+    def _params(self, strategy: str) -> tuple[float, float] | None:
+        if strategy in self._fit:
+            return self._fit[strategy]
+        pts = self._obs.get(strategy, [])
+        if len({x for x, _ in pts}) < 2:
+            return None
+        n = len(pts)
+        mx = sum(x for x, _ in pts) / n
+        my = sum(y for _, y in pts) / n
+        sxx = sum((x - mx) ** 2 for x, _ in pts)
+        b = sum((x - mx) * (y - my) for x, y in pts) / sxx
+        self._fit[strategy] = (my - b * mx, b)
+        return self._fit[strategy]
+
+    def predict(self, strategy: str, work: float) -> float | None:
+        p = self._params(strategy)
+        return None if p is None else math.exp(p[0] + p[1] * math.log(work))
+
+    def best(self, work: float) -> tuple[str, float] | None:
+        cands = [(s, self.predict(s, work)) for s in self._obs]
+        cands = [(s, t) for s, t in cands if t is not None]
+        return min(cands, key=lambda x: x[1]) if cands else None
+
+    @classmethod
+    def from_ledger(cls, rows: list[dict], work_of=lambda r: r["metrics"]["params"]["n"] ** 2
+                    * r["metrics"]["params"]["iters"]) -> "PowerLawPredictor":
+        p = cls()
+        for r in rows:
+            if r.get("type") == "measurement" and r.get("ok") and "params" in r.get("metrics", {}):
+                try:
+                    p.observe(r["strategy"], work_of(r), r["wall_s"])
+                except (KeyError, TypeError):
+                    continue
+        return p

spatial/memory/__init__.py

@@ -0,0 +1,5 @@
+"""Spatial Resource Engine — memory tiering (hot RAM / compressed RAM / far)."""
+from .tiered import TieredStore, FileBackend, RemoteBackend  # noqa: F401
+from .fararray import FarArray  # noqa: F401
+from .secure import EncryptedBackend, ReplicatedBackend  # noqa: F401
+from .shared import SharedPages, VersionConflict  # noqa: F401

spatial/memory/fararray.py

@@ -0,0 +1,44 @@
+"""FarArray: a 1-D numeric array whose pages live in a TieredStore.
+
+Lets a workload address more data than its local RAM budget. Access outside the
+hot tier is slower by a measured amount; this is tiering, not extra RAM.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from .tiered import TieredStore
+
+
+class FarArray:
+    def __init__(self, store: TieredStore, length: int, dtype=np.float64, page_items: int = 8192):
+        self.store, self.length = store, length
+        self.dtype = np.dtype(dtype)
+        self.page_items = page_items
+        self.npages = (length + page_items - 1) // page_items
+
+    @classmethod
+    def from_chunks(cls, store: TieredStore, chunks, length: int, dtype=np.float64,
+                    page_items: int = 8192) -> "FarArray":
+        """Build from an iterator of arrays of exactly `page_items` items (last may be shorter)."""
+        fa = cls(store, length, dtype, page_items)
+        for i, c in enumerate(chunks):
+            store.put(i, np.ascontiguousarray(c, dtype=fa.dtype).tobytes())
+        return fa
+
+    def page(self, i: int) -> np.ndarray:
+        return np.frombuffer(self.store.get(i), dtype=self.dtype)
+
+    def __getitem__(self, idx: int):
+        return self.page(idx // self.page_items)[idx % self.page_items]
+
+    def sum(self) -> float:
+        return float(sum(self.page(i).sum() for i in range(self.npages)))
+
+    def take(self, indices: np.ndarray) -> np.ndarray:
+        out = np.empty(len(indices), dtype=self.dtype)
+        pages = indices // self.page_items
+        offs = indices % self.page_items
+        for j in range(len(indices)):
+            out[j] = self.page(int(pages[j]))[offs[j]]
+        return out

spatial/memory/pageserver.py

@@ -0,0 +1,141 @@
+"""Remote page server: holds compressed pages in ITS OWN RAM, served over SWP/0.
+
+Run:  python -m spatial.memory.pageserver --token-file <path> [--delay-ms X] [--mbps Y]
+
+--delay-ms / --mbps EMULATE a network (added round-trip delay, bandwidth cap) because the
+test bench has a single machine. Results obtained with them are labelled "emulated link":
+they bound what a real LAN/WAN would do, they are not measurements of one.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import secrets
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+from ..core.protocol import RpcClient, RpcServer
+
+
+class VersionConflict(Exception):
+    pass
+
+
+class PageStore:
+    def __init__(self, delay_ms: float = 0.0, mbps: float = 0.0, max_bytes: int = 4 << 30):
+        self.pages: dict[int, bytes] = {}
+        self.versions: dict[int, int] = {}
+        self._vlock = threading.Lock()
+        self.bytes = 0
+        self.delay = delay_ms / 1000.0
+        self.bps = mbps * 1e6 / 8
+        self.max_bytes = max_bytes
+
+    def _link(self, nbytes: int):
+        d = self.delay + (nbytes / self.bps if self.bps else 0.0)
+        if d > 0:
+            time.sleep(d)
+
+    def handle(self, h: dict, blob: bytes):
+        op = h["op"]
+        if op == "put":
+            if self.bytes + len(blob) > self.max_bytes:
+                raise MemoryError("page server quota exceeded")
+            old = self.pages.get(h["key"])
+            if old is not None:
+                self.bytes -= len(old)
+            self.pages[h["key"]] = blob
+            self.bytes += len(blob)
+            self._link(len(blob))
+            return {}, b""
+        if op == "get":
+            b = self.pages[h["key"]]
+            self._link(len(b))
+            return {}, b
+        if op == "get_many":
+            bl = [self.pages.get(k) for k in h["keys"]]
+            out = b"".join(b for b in bl if b is not None)
+            self._link(len(out))
+            return {"lens": [len(b) if b is not None else -1 for b in bl]}, out
+        if op == "del":
+            b = self.pages.pop(h["key"], None)
+            if b is not None:
+                self.bytes -= len(b)
+            return {}, b""
+        if op == "vget":
+            with self._vlock:
+                b = self.pages.get(h["key"])
+                return {"exists": b is not None, "version": self.versions.get(h["key"], 0)}, b or b""
+        if op == "vput":
+            with self._vlock:                       # compare-and-swap on the page version
+                cur = self.versions.get(h["key"], 0)
+                if h["expected"] != cur:
+                    raise VersionConflict(f"page {h['key']} is at version {cur}, writer expected {h['expected']}")
+                old = self.pages.get(h["key"])
+                if self.bytes - (len(old) if old else 0) + len(blob) > self.max_bytes:
+                    raise MemoryError("page server quota exceeded")
+                self.bytes += len(blob) - (len(old) if old else 0)
+                self.pages[h["key"]] = blob
+                self.versions[h["key"]] = cur + 1
+                return {"version": cur + 1}, b""
+        if op == "stat":
+            return {"pages": len(self.pages), "bytes": self.bytes}, b""
+        raise ValueError(op)
+
+
+class LocalPageServer:
+    """Page server in a separate OS process on loopback."""
+
+    def __init__(self, delay_ms: float = 0.0, mbps: float = 0.0):
+        self.token = secrets.token_bytes(32)
+        self._tf = Path(os.environ.get("TMPDIR", "/tmp")) / f"spatial-ps-{os.getpid()}-{secrets.token_hex(4)}"
+        self._tf.write_bytes(self.token)
+        os.chmod(self._tf, 0o600)
+        root = Path(__file__).resolve().parents[2]
+        self.proc = subprocess.Popen(
+            [sys.executable, "-m", "spatial.memory.pageserver", "--token-file", str(self._tf),
+             "--delay-ms", str(delay_ms), "--mbps", str(mbps)],
+            cwd=root, stdout=subprocess.PIPE, text=True)
+        line = self.proc.stdout.readline()
+        if not line.startswith("PORT "):
+            raise RuntimeError(f"page server failed: {line!r}")
+        self.port = int(line.split()[1])
+
+    def client(self) -> RpcClient:
+        return RpcClient("127.0.0.1", self.port, self.token)
+
+    def stop(self):
+        self.proc.terminate()
+        try:
+            self.proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self.proc.kill()
+        self._tf.unlink(missing_ok=True)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        self.stop()
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--token-file", required=True)
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--port", type=int, default=0)
+    ap.add_argument("--delay-ms", type=float, default=0.0)
+    ap.add_argument("--mbps", type=float, default=0.0)
+    ap.add_argument("--allow-remote", action="store_true")
+    a = ap.parse_args()
+    store = PageStore(a.delay_ms, a.mbps)
+    srv = RpcServer(store.handle, Path(a.token_file).read_bytes(), a.host, a.port, a.allow_remote)
+    print(f"PORT {srv.port}", flush=True)
+    srv.serve_forever()
+
+
+if __name__ == "__main__":
+    main()