spatial-computing 0.5.0__py3-none-any.whl

spatial/__init__.py

@@ -0,0 +1,6 @@
+"""SPATIAL COMPUTING — research prototype.
+
+Status of every engine is declared in spatial.core.registry and must be backed
+by a test or benchmark before being set to OPERATIONAL.
+"""
+__version__ = "0.5.0"

spatial/ai/__init__.py

@@ -0,0 +1,18 @@
+"""Spatial AI Engine: first components in the public repository.
+
+kvcache.py: a toy NumPy transformer with a real key/value cache, used to measure recompute
+versus restore through the tiered memory store (CPU, toy sizes: says nothing about GPUs).
+
+The model-placement planner (layers over heterogeneous nodes, memory, network, availability)
+lives in the private `spatial_pro` package. When that package is installed, `plan_pipeline`
+and friends are re-exported here; otherwise they are None and nothing pretends to work.
+No real language model is executed by this repository.
+"""
+try:  # pragma: no cover - depends on a private package
+    from spatial_pro.placement import ModelSpec, NodeSpec, plan_pipeline  # noqa: F401
+    HAVE_PLANNER = True
+except ImportError:
+    ModelSpec = NodeSpec = plan_pipeline = None
+    HAVE_PLANNER = False
+
+from .kvcache import ToyTransformer, measure_restore_vs_recompute  # noqa: E402,F401

spatial/ai/kvcache.py

@@ -0,0 +1,81 @@
+"""Toy causal transformer with a key/value cache, to MEASURE recompute versus restore.
+
+A small random-weight decoder (NumPy, CPU). It is not a language model and its speed says
+nothing about GPUs. It exists so the KV-cache mechanics are real and testable:
+  * prefill(tokens) builds the per-layer K/V tensors;
+  * continuing from a restored cache gives exactly the same logits as recomputing;
+  * the cache can be parked in a TieredStore, so restore time and bytes are measured.
+"""
+from __future__ import annotations
+
+import time
+
+import numpy as np
+
+
+class ToyTransformer:
+    def __init__(self, layers: int = 4, d: int = 64, heads: int = 4, vocab: int = 256, seed: int = 0):
+        rng = np.random.default_rng(seed)
+        self.L, self.d, self.h, self.vocab = layers, d, heads, vocab
+        g = lambda *s: (rng.standard_normal(s) / np.sqrt(s[0])).astype(np.float32)
+        self.emb = g(vocab, d)
+        self.W = [{k: g(d, d) for k in ("q", "k", "v", "o", "m1", "m2")} for _ in range(layers)]
+        self.out = g(d, vocab)
+
+    def _pos(self, i0: int, n: int) -> np.ndarray:
+        pos = np.arange(i0, i0 + n)[:, None] / (10000 ** (np.arange(self.d)[None, :] / self.d))
+        return np.sin(pos).astype(np.float32)
+
+    def forward(self, tokens, cache: list | None = None):
+        """Process `tokens` after the positions already in `cache`. Returns (logits of the last
+        token, new cache). cache = [(K, V)] per layer, K and V of shape [positions, d]."""
+        n0 = 0 if cache is None else cache[0][0].shape[0]
+        x = self.emb[np.asarray(tokens)] + self._pos(n0, len(tokens))
+        new, dh = [], self.d // self.h
+        for li, w in enumerate(self.W):
+            k_new, v_new = x @ w["k"], x @ w["v"]
+            K = k_new if cache is None else np.concatenate([cache[li][0], k_new])
+            V = v_new if cache is None else np.concatenate([cache[li][1], v_new])
+            q = (x @ w["q"]).reshape(len(tokens), self.h, dh).transpose(1, 0, 2)
+            Kh = K.reshape(-1, self.h, dh).transpose(1, 0, 2)
+            Vh = V.reshape(-1, self.h, dh).transpose(1, 0, 2)
+            att = q @ Kh.transpose(0, 2, 1) / np.sqrt(dh)
+            mask = np.arange(K.shape[0])[None, :] > (n0 + np.arange(len(tokens)))[:, None]   # causal
+            att = np.where(mask[None], np.float32(-1e30), att)
+            att = np.exp(att - att.max(-1, keepdims=True))
+            att /= att.sum(-1, keepdims=True)
+            x = x + (att @ Vh).transpose(1, 0, 2).reshape(len(tokens), self.d) @ w["o"]
+            x = x + np.maximum(x @ w["m1"], 0) @ w["m2"]
+            x = x.astype(np.float32)          # keep the cache in one dtype (float32)
+            new.append((K, V))
+        return x[-1] @ self.out, new
+
+
+def cache_to_pages(cache: list) -> list[bytes]:
+    return [a.tobytes() for kv in cache for a in kv]
+
+
+def cache_from_pages(pages: list[bytes], d: int) -> list:
+    arrs = [np.frombuffer(p, dtype=np.float32).reshape(-1, d) for p in pages]
+    return [(arrs[i], arrs[i + 1]) for i in range(0, len(arrs), 2)]
+
+
+def measure_restore_vs_recompute(model: ToyTransformer, prefix, store, repeat: int = 3) -> dict:
+    """Times, on this machine: recomputing the prefix cache versus restoring it from `store`."""
+    t0 = time.perf_counter()
+    _, cache = model.forward(prefix)
+    recompute_s = time.perf_counter() - t0
+    for _ in range(repeat - 1):
+        t0 = time.perf_counter()
+        model.forward(prefix)
+        recompute_s = min(recompute_s, time.perf_counter() - t0)
+    pages = cache_to_pages(cache)
+    for i, p in enumerate(pages):
+        store.put(i, p)
+    restore_s = float("inf")
+    for _ in range(repeat):
+        t0 = time.perf_counter()
+        restored = cache_from_pages([store.get(i) for i in range(len(pages))], model.d)
+        restore_s = min(restore_s, time.perf_counter() - t0)
+    return {"prefix_tokens": len(prefix), "cache_bytes": sum(map(len, pages)), "recompute_s": recompute_s,
+            "restore_s": restore_s, "restore_faster": restore_s < recompute_s, "cache": cache, "restored": restored}

spatial/cli.py

@@ -0,0 +1,135 @@
+"""`spatial` command line: one entry point for the three operational engines."""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+BENCHES = {"cpu": "bench_cpu", "memory": "bench_memory", "gpu": "bench_gpu",
+           "runtime": "bench_runtime", "q": "bench_q"}
+
+
+def cmd_audit(a):
+    from .compute import detect_node, limitations, snapshot
+    from .compute.monitor import underused
+    node, snap = detect_node(), snapshot()
+    if a.json:
+        print(json.dumps({"node": node.to_dict(), "snapshot": snap, "limitations": limitations(node)},
+                         indent=1, default=str))
+        return 0
+    print(f"{node.attrs.get('model')} | {node.attrs.get('cpu_brand')} | {node.os} | {node.arch}")
+    for r in node.resources:
+        cap = f"{r.capacity / 2**30:.1f} GiB" if r.unit == "bytes" else f"{r.capacity:g} {r.unit}"
+        if "utilization_percent" in r.attrs:
+            cap += f"  ({r.attrs['utilization_percent']:.0f}% busy)"
+        print(f"  {r.kind.value:<11} {r.name:<42} {cap}")
+    print(f"memory pressure: {snap.get('memory_pressure')} | compressor ratio: {snap.get('compressor_ratio')} "
+          f"| swap used: {snap['swap_used'] / 2**30:.2f} GiB")
+    for u in underused(snap):
+        print("  idle:", u)
+    print("limitations:")
+    for x in limitations(node):
+        print("  -", x)
+    return 0
+
+
+def cmd_status(a):
+    from .core.registry import ENGINES
+    for e in ENGINES:
+        print(f"{e.name:<42} {e.status.value:<24} not done: {e.not_done}")
+    return 0
+
+
+def cmd_plan(a):
+    from .runtime import inspect, plan
+    art = inspect(a.file)
+    print(f"{a.file}: {art.format} / {art.os} / {','.join(art.arch)} {art.detail}")
+    for r in plan(art):
+        print(f"  [{'x' if r.feasible else ' '}] {r.name:<16} {r.reason}")
+    return 0
+
+
+def cmd_run(a):
+    from .runtime import execute
+    e = execute(a.file, a.args, route=a.route, timeout_s=a.timeout)
+    if e.stdout:
+        print(e.stdout)
+    print(f"[spatial] route={e.route} ok={e.ok} wall={e.wall_s:.2f}s "
+          + (f"reason: {e.extra.get('not_runnable')}" if not e.ok and e.extra.get("not_runnable") else ""),
+          file=sys.stderr)
+    return 0 if e.ok else 1
+
+
+def cmd_q(a):
+    from .q import runtime
+    sys.argv = ["spatialq", *a.rest]
+    runtime.main()
+    return 0
+
+
+def cmd_bench(a):
+    names = list(BENCHES) if a.name == "all" else [a.name]
+    bdir = ROOT / "benchmarks"
+    if not bdir.exists():
+        print("benchmarks/ not found: run from a source checkout", file=sys.stderr)
+        return 2
+    rc = 0
+    for n in names:
+        rc |= subprocess.run([sys.executable, f"{BENCHES[n]}.py"], cwd=bdir).returncode
+    rc |= subprocess.run([sys.executable, "report.py"], cwd=bdir).returncode
+    return rc
+
+
+def cmd_worker(a):
+    mod = {"compute": "spatial.compute.worker", "memory": "spatial.memory.pageserver",
+           "runtime": "spatial.runtime.runner"}[a.kind]
+    cmd = [sys.executable, "-m", mod, "--token-file", a.token_file, "--host", a.host, "--port", str(a.port)]
+    if a.allow_remote:
+        cmd.append("--allow-remote")
+    return subprocess.run(cmd).returncode
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="spatial", description="SPATIAL COMPUTING — measure, decide, prove")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("audit", help="detect hardware, usage and limits of this machine")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_audit)
+    sub.add_parser("status", help="honest status of every engine").set_defaults(fn=cmd_status)
+    p = sub.add_parser("plan", help="inspect a binary and list execution routes")
+    p.add_argument("file")
+    p.set_defaults(fn=cmd_plan)
+    p = sub.add_parser("run", help="run a binary through the best feasible route")
+    p.add_argument("file")
+    p.add_argument("args", nargs="*")
+    p.add_argument("--route")
+    p.add_argument("--timeout", type=float, default=300)
+    p.set_defaults(fn=cmd_run)
+    p = sub.add_parser("q", help="SPATIAL Q: run|check|qasm|ir <file.sq>")
+    p.add_argument("rest", nargs=argparse.REMAINDER)
+    p.set_defaults(fn=cmd_q)
+    p = sub.add_parser("bench", help="run benchmarks and regenerate docs/RESULTATS.md")
+    p.add_argument("name", choices=[*BENCHES, "all"])
+    p.set_defaults(fn=cmd_bench)
+    p = sub.add_parser("serve", help="start a compute worker, a page server or a sandboxed binary runner (loopback by default)")
+    p.add_argument("kind", choices=["compute", "memory", "runtime"])
+    p.add_argument("--token-file", required=True)
+    p.add_argument("--host", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=0)
+    p.add_argument("--allow-remote", action="store_true", help="explicit consent to accept LAN connections")
+    p.set_defaults(fn=cmd_worker)
+    a = ap.parse_args(argv)
+    try:
+        return a.fn(a)
+    except (Exception, SystemExit) as e:  # user-facing tool: one clean line, no traceback
+        if isinstance(e, SystemExit) and not isinstance(e.code, str):
+            raise
+        print(f"spatial: {type(e).__name__}: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

spatial/compute/__init__.py

@@ -0,0 +1,3 @@
+"""Spatial Compute Engine: detect, monitor, compare strategies, offload, cost."""
+from .detect import detect_node, limitations  # noqa: F401
+from .monitor import snapshot, Measure  # noqa: F401

spatial/compute/cost.py

@@ -0,0 +1,69 @@
+"""Cost model. Every price is an ASSUMPTION with a stated basis; override via CostModel(...).
+
+Local cost is derived from MEASURED time/energy. Remote/cloud cost is an ESTIMATE:
+no cloud machine was rented for these experiments, so cloud rows are labelled
+`estimated=True` and assume the measured local runtime scaled by `speed_ratio`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CloudOffer:
+    name: str
+    usd_per_hour: float
+    vcpus: int
+    gpu: str | None
+    basis: str            # where the number comes from; to be re-checked before any business use
+
+
+# List prices recalled from public price pages (us-east-1 on-demand). NOT re-verified today.
+OFFERS = {
+    "aws_c7i_large": CloudOffer("AWS c7i.large", 0.0893, 2, None, "AWS on-demand list price, unverified"),
+    "aws_c7i_4xlarge": CloudOffer("AWS c7i.4xlarge", 0.714, 16, None, "AWS on-demand list price, unverified"),
+    "aws_g4dn_xlarge": CloudOffer("AWS g4dn.xlarge (T4)", 0.526, 4, "T4", "AWS on-demand list price, unverified"),
+}
+
+
+@dataclass
+class CostModel:
+    usd_per_kwh: float = 0.17                 # assumption: ~US residential average
+    laptop_price_usd: float = 0.0             # sunk by default; set to amortise hardware
+    laptop_life_hours: float = 4 * 365 * 8    # 4 years x 8 h/day
+    egress_usd_per_gb: float = 0.09           # assumption: typical hyperscaler internet egress
+    min_billing_s: float = 60.0               # assumption: per-second billing, 60 s minimum
+    offers: dict = field(default_factory=lambda: dict(OFFERS))
+
+    def local(self, wall_s: float, energy_j: float | None, idle_watts: float | None = None) -> dict:
+        """Cost of a measured local run. Energy cost uses the marginal energy above idle
+        when an idle baseline is known, otherwise the whole-machine energy."""
+        out = {"estimated": False, "hardware_usd": 0.0, "energy_usd": None, "total_usd": None}
+        if self.laptop_price_usd:
+            out["hardware_usd"] = self.laptop_price_usd / self.laptop_life_hours * wall_s / 3600
+        if energy_j is not None:
+            j = energy_j - (idle_watts * wall_s if idle_watts else 0.0)
+            out["marginal_energy_j"] = max(j, 0.0)
+            out["energy_usd"] = max(j, 0.0) / 3.6e6 * self.usd_per_kwh
+            out["total_usd"] = out["hardware_usd"] + out["energy_usd"]
+        return out
+
+    def cloud(self, offer_key: str, local_wall_s: float, speed_ratio: float,
+              payload_bytes: int = 0, result_bytes: int = 0, startup_s: float = 0.0) -> dict:
+        """ESTIMATE of running the same job on a cloud offer.
+        speed_ratio = assumed (cloud throughput / local throughput)."""
+        o = self.offers[offer_key]
+        run_s = local_wall_s / speed_ratio + startup_s
+        billed = max(run_s, self.min_billing_s)
+        compute = o.usd_per_hour * billed / 3600
+        net = result_bytes / 1e9 * self.egress_usd_per_gb     # ingress assumed free
+        return {"estimated": True, "offer": o.name, "basis": o.basis, "assumed_speed_ratio": speed_ratio,
+                "run_s": run_s, "billed_s": billed, "compute_usd": compute, "network_usd": net,
+                "total_usd": compute + net}
+
+    def break_even_seconds(self, offer_key: str, local_watts_marginal: float) -> float | None:
+        """Local run time above which cloud min-billing stops dominating (same speed)."""
+        o = self.offers[offer_key]
+        local_per_s = local_watts_marginal / 3.6e6 * self.usd_per_kwh
+        cloud_per_s = o.usd_per_hour / 3600
+        return None if cloud_per_s <= local_per_s else self.min_billing_s

spatial/compute/detect.py

@@ -0,0 +1,139 @@
+"""Hardware detection (macOS first; degrades gracefully elsewhere). Nothing is assumed."""
+from __future__ import annotations
+
+import json
+import platform
+import shutil
+import subprocess
+import uuid
+
+import psutil
+
+from ..core.model import Node, Resource, ResourceKind
+
+
+def _sysctl(key: str) -> str | None:
+    try:
+        r = subprocess.run(["sysctl", "-n", key], capture_output=True, text=True, timeout=5)
+        return r.stdout.strip() or None
+    except Exception:
+        return None
+
+
+def _os_name() -> str:
+    if platform.system() == "Darwin":
+        try:   # platform.mac_ver() can report a compatibility version (10.16)
+            v = subprocess.run(["sw_vers", "-productVersion"], capture_output=True, text=True, timeout=5).stdout.strip()
+            return f"macOS {v}"
+        except Exception:
+            pass
+    return f"{platform.system()} {platform.release()}"
+
+
+def _gpus() -> list[dict]:
+    try:
+        out = subprocess.run(["system_profiler", "SPDisplaysDataType", "-json"],
+                             capture_output=True, text=True, timeout=30).stdout
+        return json.loads(out).get("SPDisplaysDataType", [])
+    except Exception:
+        return []
+
+
+def parse_nvidia_smi(csv: str) -> list[dict]:
+    """Parse `nvidia-smi --query-gpu=name,memory.total,memory.used,utilization.gpu --format=csv,noheader,nounits`."""
+    out = []
+    for line in csv.strip().splitlines():
+        parts = [p.strip() for p in line.split(",")]
+        if len(parts) != 4:
+            continue
+        name, total, used, util = parts
+        try:
+            out.append({"name": name, "vram_bytes": int(float(total)) * 2**20,
+                        "vram_used_bytes": int(float(used)) * 2**20, "utilization_percent": float(util)})
+        except ValueError:
+            continue
+    return out
+
+
+def _nvidia_gpus() -> list[dict]:
+    exe = shutil.which("nvidia-smi")
+    if not exe:
+        return []
+    try:
+        r = subprocess.run([exe, "--query-gpu=name,memory.total,memory.used,utilization.gpu",
+                            "--format=csv,noheader,nounits"], capture_output=True, text=True, timeout=20)
+        return parse_nvidia_smi(r.stdout) if r.returncode == 0 else []
+    except Exception:
+        return []
+
+
+def virtualization() -> dict:
+    """What can actually run guests here."""
+    info = {"hvf": _sysctl("kern.hv_support") == "1"}
+    for tool in ("qemu-system-x86_64", "qemu-system-aarch64", "docker", "podman", "limactl",
+                 "wine", "wine64", "node", "wasmtime"):
+        info[tool] = shutil.which(tool)
+    return info
+
+
+def detect_node() -> Node:
+    vm = psutil.virtual_memory()
+    arch = platform.machine()
+    node = Node(node_id=uuid.uuid5(uuid.NAMESPACE_DNS, platform.node()).hex[:12],
+                hostname="local", os=_os_name(),
+                arch=arch)
+    node.attrs["model"] = _sysctl("hw.model")
+    node.attrs["cpu_brand"] = _sysctl("machdep.cpu.brand_string")
+    node.attrs["virtualization"] = virtualization()
+    feats = (_sysctl("machdep.cpu.features") or "") + " " + (_sysctl("machdep.cpu.leaf7_features") or "")
+    simd = [f for f in ("SSE4.2", "AVX1.0", "AVX2", "AVX512F", "FMA") if f in feats.split()]
+    node.resources.append(Resource(
+        ResourceKind.CPU, node.attrs["cpu_brand"] or "cpu",
+        capacity=psutil.cpu_count(logical=False) or 1, unit="physical cores",
+        attrs={"logical": psutil.cpu_count(logical=True), "simd": simd,
+               "l2_bytes": int(_sysctl("hw.l2cachesize") or 0),
+               "l3_bytes": int(_sysctl("hw.l3cachesize") or 0)}))
+    node.resources.append(Resource(ResourceKind.RAM, "physical RAM", capacity=vm.total,
+                                   unit="bytes", available=vm.available))
+    sw = psutil.swap_memory()
+    node.resources.append(Resource(
+        ResourceKind.FAR_MEMORY, "OS swap (SSD-backed, NOT RAM)", capacity=sw.total, unit="bytes",
+        available=sw.free, attrs={"compressor_mode": _sysctl("vm.compressor_mode")}))
+    for g in _gpus():
+        node.resources.append(Resource(
+            ResourceKind.GPU, g.get("sppci_model", "gpu"), capacity=1, unit="device",
+            attrs={"vram": g.get("spdisplays_vram_shared") or g.get("spdisplays_vram") or g.get("_spdisplays_vram"),
+                   "metal": g.get("spdisplays_mtlgpufamilysupport"),
+                   "vendor": g.get("spdisplays_vendor"), "integrated": "builtin" in str(g.get("sppci_bus", "")).lower().replace("-", "")}))
+    for g in _nvidia_gpus():
+        node.resources.append(Resource(
+            ResourceKind.GPU, g["name"], capacity=g["vram_bytes"], unit="bytes",
+            available=g["vram_bytes"] - g["vram_used_bytes"],
+            attrs={"vendor": "NVIDIA", "cuda": True, "integrated": False,
+                   "utilization_percent": g["utilization_percent"]}))
+    du = psutil.disk_usage("/System/Volumes/Data" if platform.system() == "Darwin" else "/")
+    node.resources.append(Resource(ResourceKind.STORAGE, "system volume", capacity=du.total,
+                                   unit="bytes", available=du.free))
+    return node
+
+
+def limitations(node: Node) -> list[str]:
+    """Hard limits derived from what was detected (used by the scheduler and the audit)."""
+    out = []
+    cpu = node.by_kind(ResourceKind.CPU)[0]
+    if cpu.capacity <= 2:
+        out.append(f"Only {int(cpu.capacity)} physical cores: parallel speed-up is bounded near 2x "
+                   "(hyper-threads add little for compute-bound code).")
+    if "AVX512F" not in cpu.attrs.get("simd", []):
+        out.append("No AVX-512; SIMD width limited to AVX2 (256-bit).")
+    if node.arch == "x86_64":
+        out.append("Intel Mac: no Apple Neural Engine/NPU, no MLX, no Apple Virtualization.framework "
+                   "Rosetta-for-Linux; ARM guests run under slow TCG emulation only.")
+    for g in node.by_kind(ResourceKind.GPU):
+        if g.attrs.get("integrated"):
+            out.append(f"GPU {g.name} is integrated: shares system RAM, no CUDA, low compute throughput.")
+    if not node.attrs["virtualization"].get("wine") and not node.attrs["virtualization"].get("wine64"):
+        out.append("No Wine installed: Windows PE binaries cannot be executed locally.")
+    if not node.attrs["virtualization"].get("docker"):
+        out.append("No Docker/Podman: OCI containers unavailable; QEMU micro-VM is the Linux path.")
+    return out

spatial/compute/monitor.py

@@ -0,0 +1,111 @@
+"""Resource monitoring: CPU, RAM, macOS compressor and swap, memory pressure."""
+from __future__ import annotations
+
+import os
+import re
+import resource
+import subprocess
+import sys
+import time
+
+import psutil
+
+from ..core import energy
+from ..core.model import Measurement
+
+_PRESSURE = {1: "normal", 2: "warning", 4: "critical"}
+
+
+def vm_stat() -> dict[str, int]:
+    """Parsed `vm_stat` in bytes (macOS). Empty dict elsewhere."""
+    try:
+        out = subprocess.run(["vm_stat"], capture_output=True, text=True, timeout=5).stdout
+    except Exception:
+        return {}
+    page = int(re.search(r"page size of (\d+)", out).group(1))
+    d = {}
+    for k, v in re.findall(r'^"?([^":]+)"?:\s+(\d+)\.', out, re.M):
+        d[k.strip().lower().replace(" ", "_").replace("-", "_")] = int(v)
+    for k in list(d):
+        if k.startswith("pages_"):
+            d[k + "_bytes"] = d[k] * page
+    d["page_size"] = page
+    return d
+
+
+def snapshot() -> dict:
+    vm = psutil.virtual_memory()
+    sw = psutil.swap_memory()
+    vs = vm_stat()
+    snap = {
+        "ts": time.time(),
+        "cpu_percent": psutil.cpu_percent(interval=0.3),
+        "load1": os.getloadavg()[0],
+        "ram_total": vm.total, "ram_available": vm.available, "ram_used_percent": vm.percent,
+        "swap_used": sw.used, "swap_total": sw.total,
+    }
+    if vs:
+        stored = vs.get("pages_stored_in_compressor_bytes", 0)
+        occupied = vs.get("pages_occupied_by_compressor_bytes", 0)
+        snap.update({
+            "compressor_logical_bytes": stored,          # uncompressed size held by compressor
+            "compressor_physical_bytes": occupied,       # RAM actually used to hold it
+            "compressor_ratio": round(stored / occupied, 2) if occupied else None,
+            "compressor_saved_bytes": stored - occupied,
+            "swapins": vs.get("swapins"), "swapouts": vs.get("swapouts"),
+        })
+    try:
+        lvl = int(subprocess.run(["sysctl", "-n", "kern.memorystatus_vm_pressure_level"],
+                                 capture_output=True, text=True, timeout=5).stdout.strip())
+        snap["memory_pressure"] = _PRESSURE.get(lvl, str(lvl))
+    except Exception:
+        snap["memory_pressure"] = None
+    return snap
+
+
+def underused(snap: dict) -> list[str]:
+    """Flag resources that are idle right now (input for the optimizer)."""
+    out = []
+    if snap["cpu_percent"] < 25:
+        out.append(f"CPU {snap['cpu_percent']:.0f}% busy: {100 - snap['cpu_percent']:.0f}% idle capacity")
+    if snap["ram_available"] / snap["ram_total"] > 0.4:
+        out.append(f"RAM {snap['ram_available'] / 2**30:.1f} GiB available of {snap['ram_total'] / 2**30:.0f}")
+    return out
+
+
+def _peak_rss() -> int:
+    r = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    return r if sys.platform == "darwin" else r * 1024   # bytes on macOS, KiB on Linux
+
+
+class Measure:
+    """Measure a block: wall, CPU (self + waited children), peak RSS, battery energy."""
+
+    def __init__(self, engine: str, experiment: str, strategy: str, power: bool = True):
+        self.m = Measurement(engine, experiment, strategy, ok=False, wall_s=0.0)
+        self._power = energy.PowerSampler() if power else None
+
+    def __enter__(self) -> Measurement:
+        t = os.times()
+        self._cpu0 = t.user + t.system + t.children_user + t.children_system
+        if self._power:
+            self._power.__enter__()
+        self._t0 = time.perf_counter()
+        return self.m
+
+    def __exit__(self, et, ev, tb):
+        self.m.wall_s = time.perf_counter() - self._t0
+        if self._power:
+            self._power.__exit__(et, ev, tb)
+            self.m.energy_j = self._power.joules
+            if self._power.mean_watts is not None:
+                self.m.metrics["mean_watts_machine"] = round(self._power.mean_watts, 2)
+                self.m.metrics["power_gauge_static"] = self._power.static
+        t = os.times()
+        self.m.cpu_s = t.user + t.system + t.children_user + t.children_system - self._cpu0
+        self.m.peak_rss_bytes = _peak_rss()
+        if et is None:
+            self.m.ok = True
+        else:
+            self.m.notes = f"{et.__name__}: {ev}"
+        return True   # failures are recorded, not raised