spatial-computing 0.5.0__py3-none-any.whl

spatial/compute/scheduler.py

@@ -0,0 +1,168 @@
+"""Strategy comparison and selection for the Spatial Compute Engine.
+
+compare(): run every feasible strategy for a task, MEASURE it, verify the result
+matches the reference, then choose() by objective (time | cpu | energy).
+"""
+from __future__ import annotations
+
+import multiprocessing as mp
+import threading
+from concurrent.futures import ProcessPoolExecutor
+from dataclasses import dataclass
+from typing import Callable
+
+from ..core.ledger import Ledger
+from ..core.model import Measurement, Node, ResourceKind
+from . import workloads
+from .monitor import Measure
+
+
+def _chunk(args):
+    name, params = args
+    return workloads.run(name, **params)
+
+
+def _row_chunks(n: int, parts: int) -> list[tuple[int, int]]:
+    step = max(1, n // parts)
+    return [(r, min(n, r + step)) for r in range(0, n, step)]
+
+
+@dataclass
+class Strategy:
+    name: str
+    fn: Callable[[dict], object]
+    kind: str   # local | optimized | parallel | distributed | remote
+    needs_worker: bool = False
+
+
+class ComputeScheduler:
+    def __init__(self, node: Node, ledger: Ledger | None = None, worker_client=None):
+        self.node = node
+        self.ledger = ledger or Ledger()
+        self.worker = worker_client
+        self.cores = int(node.by_kind(ResourceKind.CPU)[0].capacity)
+        self._pool = None
+
+    # ---- mandelbrot family -------------------------------------------------
+    def mandel_strategies(self) -> list[Strategy]:
+        S = [
+            Strategy("local_python", lambda p: workloads.mandel_python(**p), "local"),
+            Strategy("local_numpy", lambda p: workloads.mandel_numpy(**p), "optimized"),
+        ]
+        if workloads.HAVE_NUMBA:
+            S += [
+                Strategy("local_numba_jit", lambda p: workloads.mandel_numba(**p), "optimized"),
+                Strategy("local_numba_threads", lambda p: workloads.mandel_numba_parallel(**p), "parallel"),
+                Strategy("multiprocess_numba", self._mp, "parallel"),
+                Strategy("multiprocess_warm_pool", self._mp_warm, "parallel"),
+            ]
+            if self.worker is not None:
+                S += [
+                    Strategy("remote_worker", self._remote, "remote", needs_worker=True),
+                    Strategy("distributed_local+worker", self._distributed, "distributed", needs_worker=True),
+                ]
+        return S
+
+    def _mp(self, p: dict):
+        chunks = _row_chunks(p["n"], self.cores * 8)
+        with ProcessPoolExecutor(self.cores, mp_context=mp.get_context("spawn")) as ex:
+            return sum(ex.map(_chunk, [("mandel_numba", {**p, "r0": a, "r1": b}) for a, b in chunks]))
+
+    def _mp_warm(self, p: dict):
+        """Same split as _mp but on a pool started (and JIT-warmed) beforehand: isolates the
+        cost of process start-up + imports that _mp pays on every call."""
+        if self._pool is None:
+            self._start_pool()
+        chunks = _row_chunks(p["n"], self.cores * 8)
+        return sum(self._pool.map(_chunk, [("mandel_numba", {**p, "r0": a, "r1": b}) for a, b in chunks]))
+
+    def _start_pool(self):
+        self._pool = ProcessPoolExecutor(self.cores, mp_context=mp.get_context("spawn"))
+        list(self._pool.map(_chunk, [("mandel_numba", {"n": 8, "iters": 8})] * (self.cores * 4)))
+
+    def close(self):
+        if self._pool is not None:
+            self._pool.shutdown()
+            self._pool = None
+
+    def _remote(self, p: dict):
+        rh, _ = self.worker.call({"op": "run", "workload": "mandel_numba", "params": p})
+        self._last_remote = rh
+        return rh["result"]
+
+    def _distributed(self, p: dict):
+        """Interleave row chunks: odd chunks to the worker, even chunks locally."""
+        chunks = _row_chunks(p["n"], 32)
+        mine, theirs = chunks[0::2], chunks[1::2]
+        out = {}
+
+        def remote():
+            tot = 0
+            for a, b in theirs:
+                rh, _ = self.worker.call({"op": "run", "workload": "mandel_numba",
+                                          "params": {**p, "r0": a, "r1": b}})
+                tot += rh["result"]
+            out["r"] = tot
+
+        t = threading.Thread(target=remote)
+        t.start()
+        local = sum(workloads.mandel_numba(**{**p, "r0": a, "r1": b}) for a, b in mine)
+        t.join()
+        return local + out["r"]
+
+    # ---- generic -----------------------------------------------------------
+    def warmup(self):
+        """Compile JIT code outside the timed region (compile time is reported separately)."""
+        if workloads.HAVE_NUMBA:
+            workloads.mandel_numba(8, 8)
+            workloads.mandel_numba_parallel(8, 8)
+            if self._pool is None:
+                self._start_pool()
+            if self.worker is not None:
+                self.worker.call({"op": "run", "workload": "mandel_numba", "params": {"n": 8, "iters": 8}})
+
+    def compare(self, experiment: str, params: dict, strategies: list[Strategy],
+                reference: object | None = None, skip: set[str] = frozenset()) -> list[Measurement]:
+        rows = []
+        for s in strategies:
+            if s.name in skip:
+                continue
+            holder = {}
+            with Measure("compute", experiment, s.name) as m:
+                holder["r"] = s.fn(dict(params))
+            m.metrics["kind"] = s.kind
+            m.metrics["params"] = params
+            if m.ok:
+                if reference is None:
+                    reference = holder["r"]
+                m.metrics["result"] = holder["r"]
+                m.metrics["matches_reference"] = holder["r"] == reference
+                if not m.metrics["matches_reference"]:
+                    m.ok = False
+                    m.notes = "result differs from reference"
+            if s.needs_worker and m.ok:
+                m.notes = "worker is a separate process on this same machine (loopback)"
+            rows.append(self.ledger.record(m))
+        return rows
+
+    def predict_best(self, n: int, iters: int) -> tuple[str, float] | None:
+        """Ask the Intelligence Engine which strategy should be fastest for this size, from the
+        ledger's past measurements, WITHOUT running anything. None when history is too thin."""
+        from ..intelligence import PowerLawPredictor
+        return PowerLawPredictor.from_ledger(self.ledger.rows()).best(n * n * iters)
+
+    def choose(self, rows: list[Measurement], objective: str = "time") -> Measurement:
+        ok = [r for r in rows if r.ok]
+        if not ok:
+            raise RuntimeError("no strategy succeeded")
+        if objective == "cost":            # $ = CPU-seconds actually burnt, priced per core-hour
+            usd_core_h = getattr(self, "usd_per_core_hour", 0.045)     # assumption, override on the instance
+            for r in ok:
+                r.cost_usd = (r.cpu_s or r.wall_s) / 3600 * usd_core_h
+        key = {"time": lambda r: r.wall_s, "cpu": lambda r: r.cpu_s, "cost": lambda r: r.cost_usd,
+               "energy": lambda r: r.energy_j if r.energy_j is not None else float("inf")}[objective]
+        best = min(ok, key=key)
+        self.ledger.decide("compute", f"choose {best.strategy}", f"min {objective}",
+                           experiment=best.experiment,
+                           candidates={r.strategy: round(key(r), 4) for r in ok if key(r) != float("inf")})
+        return best

spatial/compute/taskqueue.py

@@ -0,0 +1,107 @@
+"""Priority task queue over a local executor slot and N remote workers.
+
+Tasks are allow-listed workloads (name + params), so they are safe to re-run: when a
+worker fails mid-task the task is re-queued and the worker is retired. Lower `priority`
+runs first; ties keep submission order.
+"""
+from __future__ import annotations
+
+import heapq
+import itertools
+import threading
+import time
+from concurrent.futures import Future
+from dataclasses import dataclass, field
+
+from . import workloads
+
+
+@dataclass(order=True)
+class _Item:
+    priority: int
+    seq: int
+    workload: str = field(compare=False)
+    params: dict = field(compare=False)
+    future: Future = field(compare=False)
+    attempts: int = field(compare=False, default=0)
+
+
+class TaskQueue:
+    def __init__(self, workers: dict | None = None, local_slots: int = 1, max_attempts: int = 3):
+        """workers: {name: RpcClient}. local_slots: tasks run concurrently in this process."""
+        self._heap: list[_Item] = []
+        self._cv = threading.Condition()
+        self._seq = itertools.count()
+        self._closed = False
+        self.max_attempts = max_attempts
+        self.log: list[dict] = []          # one entry per finished attempt: who ran what, how long
+        self.retired: list[str] = []
+        self._threads = []
+        for i in range(local_slots):
+            self._spawn(f"local-{i}", None)
+        for name, client in (workers or {}).items():
+            self._spawn(name, client)
+
+    def _spawn(self, name, client):
+        t = threading.Thread(target=self._loop, args=(name, client), daemon=True)
+        t.start()
+        self._threads.append(t)
+
+    def submit(self, workload: str, params: dict | None = None, priority: int = 10) -> Future:
+        if workload not in workloads.REGISTRY:
+            raise KeyError(f"workload '{workload}' is not allow-listed")
+        f: Future = Future()
+        with self._cv:
+            if self._closed:
+                raise RuntimeError("queue is closed")
+            heapq.heappush(self._heap, _Item(priority, next(self._seq), workload, params or {}, f))
+            self._cv.notify()
+        return f
+
+    def _loop(self, name, client):
+        while True:
+            with self._cv:
+                while not self._heap and not self._closed:
+                    self._cv.wait()
+                if not self._heap:
+                    return
+                item = heapq.heappop(self._heap)
+            t0 = time.perf_counter()
+            try:
+                if client is None:
+                    result = workloads.run(item.workload, **item.params)
+                else:
+                    result = client.call({"op": "run", "workload": item.workload, "params": item.params})[0]["result"]
+            except (ConnectionError, OSError) as e:        # executor is gone: give the task back
+                item.attempts += 1
+                self.log.append({"executor": name, "workload": item.workload, "ok": False, "error": str(e)})
+                with self._cv:
+                    self.retired.append(name)
+                    alive = sum(t.is_alive() for t in self._threads) - 1
+                    if item.attempts >= self.max_attempts or alive <= 0:
+                        item.future.set_exception(RuntimeError(f"task failed after {item.attempts} attempt(s): {e}"))
+                    else:
+                        heapq.heappush(self._heap, item)
+                        self._cv.notify()
+                return                                      # retire this executor
+            except Exception as e:                           # the task itself is wrong: do not retry
+                self.log.append({"executor": name, "workload": item.workload, "ok": False, "error": str(e)})
+                item.future.set_exception(e)
+                continue
+            self.log.append({"executor": name, "workload": item.workload, "priority": item.priority,
+                             "ok": True, "wall_s": time.perf_counter() - t0})
+            item.future.set_result(result)
+
+    def close(self, wait: bool = True):
+        with self._cv:
+            self._closed = True
+            self._cv.notify_all()
+        if wait:
+            for t in self._threads:
+                t.join(timeout=60)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        self.close()

spatial/compute/worker.py

@@ -0,0 +1,89 @@
+"""Compute worker: executes whitelisted workloads by name over SWP/0.
+
+Run:  python -m spatial.compute.worker --token-file <path> [--port 0]
+Binds 127.0.0.1 only. Exposing it on a LAN requires --allow-remote AND --host,
+which is a deliberate, explicit act by the machine owner.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import secrets
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from ..core.protocol import RpcClient, RpcServer
+from . import workloads
+
+
+def _handler(header: dict, blob: bytes):
+    op = header.get("op")
+    if op == "ping":
+        return {"pong": True, "pid": os.getpid()}, b""
+    if op == "run":
+        t = os.times()
+        c0, w0 = t.user + t.system, time.perf_counter()
+        result = workloads.run(header["workload"], **header.get("params", {}))
+        t = os.times()
+        return {"result": result, "wall_s": time.perf_counter() - w0,
+                "cpu_s": t.user + t.system - c0}, b""
+    raise ValueError(f"unknown op {op!r}")
+
+
+def serve(token: bytes, host: str = "127.0.0.1", port: int = 0, allow_remote: bool = False) -> RpcServer:
+    return RpcServer(_handler, token, host=host, port=port, allow_remote=allow_remote)
+
+
+class LocalWorkerProcess:
+    """Spawns a worker as a separate OS process on loopback (stand-in for a second machine:
+    it validates the protocol and its overhead, NOT the gain of extra hardware)."""
+
+    def __init__(self):
+        self.token = secrets.token_bytes(32)
+        self._tf = Path(os.environ.get("TMPDIR", "/tmp")) / f"spatial-token-{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.compute.worker", "--token-file", str(self._tf)],
+            cwd=root, stdout=subprocess.PIPE, text=True)
+        line = self.proc.stdout.readline()
+        if not line.startswith("PORT "):
+            raise RuntimeError(f"worker failed to start: {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("--allow-remote", action="store_true",
+                    help="explicit consent to accept non-loopback connections")
+    a = ap.parse_args()
+    srv = serve(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()

spatial/compute/workloads.py

@@ -0,0 +1,148 @@
+"""Whitelisted workloads. Every variant of a workload must return the same checksum,
+so a faster strategy is only accepted if it computes the same thing."""
+from __future__ import annotations
+
+import hashlib
+import os
+
+import numpy as np
+
+# workqueue: no TBB/OpenMP dependency, safe with subprocess use from helper threads
+os.environ.setdefault("NUMBA_THREADING_LAYER", "workqueue")
+
+try:
+    import numba
+    from numba import njit, prange
+    HAVE_NUMBA = True
+except Exception:  # pragma: no cover
+    HAVE_NUMBA = False
+
+# Mandelbrot window
+X0, X1, Y0, Y1 = -2.0, 0.6, -1.3, 1.3
+
+
+def mandel_python(n: int, iters: int, r0: int = 0, r1: int | None = None) -> int:
+    r1 = n if r1 is None else r1
+    total = 0
+    for i in range(r0, r1):
+        ci = Y0 + (Y1 - Y0) * i / n
+        for j in range(n):
+            cr = X0 + (X1 - X0) * j / n
+            zr = zi = 0.0
+            k = 0
+            while k < iters and zr * zr + zi * zi <= 4.0:
+                zr, zi = zr * zr - zi * zi + cr, 2.0 * zr * zi + ci
+                k += 1
+            total += k
+    return total
+
+
+def mandel_numpy(n: int, iters: int, r0: int = 0, r1: int | None = None) -> int:
+    r1 = n if r1 is None else r1
+    ci = (Y0 + (Y1 - Y0) * np.arange(r0, r1) / n)[:, None]
+    cr = (X0 + (X1 - X0) * np.arange(n) / n)[None, :]
+    c = cr + 1j * ci
+    z = np.zeros_like(c)
+    count = np.zeros(c.shape, dtype=np.int64)
+    alive = np.ones(c.shape, dtype=bool)
+    for _ in range(iters):
+        alive &= (z.real * z.real + z.imag * z.imag) <= 4.0
+        if not alive.any():
+            break
+        count[alive] += 1
+        z[alive] = z[alive] * z[alive] + c[alive]
+    return int(count.sum())
+
+
+if HAVE_NUMBA:
+    @njit(cache=True, fastmath=False, nogil=True)   # nogil: usable from threads
+    def _mandel_nb(n, iters, r0, r1):
+        total = 0
+        for i in range(r0, r1):
+            ci = Y0 + (Y1 - Y0) * i / n
+            for j in range(n):
+                cr = X0 + (X1 - X0) * j / n
+                zr = 0.0
+                zi = 0.0
+                k = 0
+                while k < iters and zr * zr + zi * zi <= 4.0:
+                    t = zr * zr - zi * zi + cr
+                    zi = 2.0 * zr * zi + ci
+                    zr = t
+                    k += 1
+                total += k
+        return total
+
+    @njit(cache=True, parallel=True, fastmath=False)
+    def _mandel_nb_par(n, iters, r0, r1):
+        total = 0
+        for i in prange(r0, r1):
+            ci = Y0 + (Y1 - Y0) * i / n
+            row = 0
+            for j in range(n):
+                cr = X0 + (X1 - X0) * j / n
+                zr = 0.0
+                zi = 0.0
+                k = 0
+                while k < iters and zr * zr + zi * zi <= 4.0:
+                    t = zr * zr - zi * zi + cr
+                    zi = 2.0 * zr * zi + ci
+                    zr = t
+                    k += 1
+                row += k
+            total += row
+        return total
+
+
+def mandel_numba(n: int, iters: int, r0: int = 0, r1: int | None = None) -> int:
+    return int(_mandel_nb(n, iters, r0, n if r1 is None else r1))
+
+
+def mandel_numba_parallel(n: int, iters: int, r0: int = 0, r1: int | None = None) -> int:
+    return int(_mandel_nb_par(n, iters, r0, n if r1 is None else r1))
+
+
+def montecarlo_pi(samples: int, seed: int = 0) -> float:
+    rng = np.random.default_rng(seed)
+    inside = 0
+    left = samples
+    while left > 0:
+        k = min(left, 2_000_000)
+        xy = rng.random((k, 2))
+        inside += int(((xy * xy).sum(axis=1) <= 1.0).sum())
+        left -= k
+    return 4.0 * inside / samples
+
+
+def sha256_chain(rounds: int, size: int = 1 << 20) -> str:
+    """Hash-bound workload (memory-bandwidth + SHA extensions if any)."""
+    buf = bytes(size)
+    h = hashlib.sha256()
+    for _ in range(rounds):
+        h.update(buf)
+    return h.hexdigest()
+
+
+def matmul(n: int, seed: int = 0) -> float:
+    rng = np.random.default_rng(seed)
+    a = rng.random((n, n), dtype=np.float32)
+    b = rng.random((n, n), dtype=np.float32)
+    return float((a @ b).trace())
+
+
+REGISTRY = {
+    "mandel_python": mandel_python,
+    "mandel_numpy": mandel_numpy,
+    "montecarlo_pi": montecarlo_pi,
+    "sha256_chain": sha256_chain,
+    "matmul": matmul,
+}
+if HAVE_NUMBA:
+    REGISTRY["mandel_numba"] = mandel_numba
+    REGISTRY["mandel_numba_parallel"] = mandel_numba_parallel
+
+
+def run(name: str, **params):
+    if name not in REGISTRY:
+        raise KeyError(f"workload '{name}' is not whitelisted")
+    return REGISTRY[name](**params)

spatial/core/__init__.py

@@ -0,0 +1 @@
+from .model import Resource, Node, Task, Measurement, ResourceKind  # noqa: F401

spatial/core/energy.py

@@ -0,0 +1,101 @@
+"""Whole-machine power sampling from the battery gauge (no sudo).
+
+MEASURED LIMITATION (MacBookPro14,1, 2026-11-14): the gauge value exposed by ioreg stayed
+constant (32.5 W) for 24 s across idle -> full CPU load -> idle. Its refresh period is far
+longer than a benchmark run, so per-run energy from this source is only
+"last gauge reading x duration". `PowerSampler.static` flags that case; callers must not
+derive marginal (above-idle) energy from it. Proper per-run energy needs `powermetrics`
+(root) or an external power meter.
+
+Only valid on battery power: on AC the gauge reports charge current, not system
+draw, so `available()` is False and energy is reported as None (never guessed).
+The value is the power of the WHOLE machine (screen included), so benchmarks
+report it next to an idle baseline.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+import threading
+import time
+
+
+def _read() -> tuple[float, bool] | None:
+    """Returns (watts drawn, on_battery) or None when no gauge is present."""
+    try:
+        out = subprocess.run(["ioreg", "-rn", "AppleSmartBattery"], capture_output=True,
+                             text=True, timeout=5).stdout
+    except Exception:
+        return None
+    amp = re.search(r'^\s*"InstantAmperage" = (\d+)', out, re.M)
+    volt = re.search(r'^\s*"Voltage" = (\d+)', out, re.M)
+    ext = re.search(r'^\s*"ExternalConnected" = (\w+)', out, re.M)
+    if not (amp and volt and ext):
+        return None
+    ma = int(amp.group(1))
+    if ma >= 1 << 63:           # gauge exposes a signed value as u64
+        ma -= 1 << 64
+    watts = abs(ma) / 1000.0 * int(volt.group(1)) / 1000.0
+    return watts, ext.group(1) == "No"
+
+
+def available() -> bool:
+    r = _read()
+    return bool(r and r[1])
+
+
+class PowerSampler:
+    """Context manager: integrates battery power over the block (trapezoid)."""
+
+    def __init__(self, period_s: float = 0.5):
+        self.period = period_s
+        self.samples: list[tuple[float, float]] = []
+        self._stop = threading.Event()
+        self._t: threading.Thread | None = None
+        self.valid = False
+
+    def _loop(self):
+        while not self._stop.is_set():
+            r = _read()
+            if r is None or not r[1]:
+                self.valid = False
+                return
+            self.samples.append((time.perf_counter(), r[0]))
+            self._stop.wait(self.period)
+
+    def __enter__(self):
+        self.valid = available()
+        if self.valid:
+            self._t = threading.Thread(target=self._loop, daemon=True)
+            self._t.start()
+        self.t0 = time.perf_counter()
+        return self
+
+    def __exit__(self, *exc):
+        self.t1 = time.perf_counter()
+        self._stop.set()
+        if self._t:
+            self._t.join(timeout=6)
+        return False
+
+    @property
+    def mean_watts(self) -> float | None:
+        if not self.valid or not self.samples:
+            return None
+        return sum(w for _, w in self.samples) / len(self.samples)
+
+    @property
+    def static(self) -> bool:
+        """True when the gauge never changed during the window (reading is stale/coarse)."""
+        return len({w for _, w in self.samples}) <= 1
+
+    @property
+    def joules(self) -> float | None:
+        mw = self.mean_watts
+        return None if mw is None else mw * (self.t1 - self.t0)
+
+
+def idle_watts(seconds: float = 4.0) -> float | None:
+    with PowerSampler(0.5) as p:
+        time.sleep(seconds)
+    return p.mean_watts

spatial/core/ledger.py

@@ -0,0 +1,76 @@
+"""Append-only, hash-chained JSONL ledger of measurements and decisions (the R&D trace).
+
+Every row carries `prev` (hash of the previous row) and `hash` = SHA-256(prev | canonical
+JSON of the row). `verify()` detects an edited, removed or reordered row. This is tamper
+EVIDENCE, not a signature: someone who can rewrite the whole file can rebuild the chain.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+
+from .model import Measurement
+
+ROOT = Path(__file__).resolve().parents[2]
+RESULTS = ROOT / "benchmarks" / "results"
+GENESIS = "0" * 64
+
+
+def _digest(prev: str, row: dict) -> str:
+    body = json.dumps(row, sort_keys=True, separators=(",", ":"), default=str)
+    return hashlib.sha256((prev + body).encode()).hexdigest()
+
+
+class Ledger:
+    def __init__(self, path: str | os.PathLike | None = None):
+        self.path = Path(path) if path else RESULTS / "ledger.jsonl"
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._last = self._tail_hash()
+
+    def _tail_hash(self) -> str:
+        last = GENESIS
+        if self.path.exists():
+            for line in self.path.read_text().splitlines():
+                if line.strip():
+                    last = json.loads(line).get("hash", last)
+        return last
+
+    def _append(self, row: dict) -> None:
+        row = json.loads(json.dumps(row, default=str))      # normalise before hashing
+        h = _digest(self._last, row)
+        with open(self.path, "a") as f:
+            f.write(json.dumps({**row, "prev": self._last, "hash": h}) + "\n")
+        self._last = h
+
+    def record(self, m: Measurement) -> Measurement:
+        self._append({"type": "measurement", **m.to_dict()})
+        return m
+
+    def decide(self, engine: str, decision: str, reason: str, **data) -> None:
+        self._append({"type": "decision", "ts": time.time(), "engine": engine,
+                      "decision": decision, "reason": reason, **data})
+
+    def rows(self, type_: str | None = None) -> list[dict]:
+        if not self.path.exists():
+            return []
+        out = []
+        for line in self.path.read_text().splitlines():
+            if line.strip():
+                r = json.loads(line)
+                if type_ is None or r.get("type") == type_:
+                    out.append(r)
+        return out
+
+    def verify(self) -> tuple[bool, int | None]:
+        """(True, None) when the chain is intact, else (False, index of the first bad row).
+        Rows written before chaining existed (no `hash`) are reported as bad."""
+        prev = GENESIS
+        for i, r in enumerate(self.rows()):
+            h, p = r.pop("hash", None), r.pop("prev", None)
+            if h is None or p != prev or _digest(prev, r) != h:
+                return False, i
+            prev = h
+        return True, None