@aloud/runner 0.2.0

package/src/evidence/uploading-store.ts

@@ -0,0 +1,166 @@
+import { checksumOf, type AccessGrant, type ObjectStore, type StoredObject } from "@aloud/engine";
+import type { Clock } from "@aloud/core";
+import type { RunnerClient } from "../protocol/client";
+import type { BlobSpool } from "../protocol/blob-spool";
+
+/**
+ * The `ObjectStore` the runner hands to `EvidencePipeline`.
+ *
+ * `put` is write-behind, and that is a correctness requirement rather than an optimisation.
+ * `EvidencePipeline.ingest` is awaited inline inside `recordMoment`, inside the participant loop,
+ * so a synchronous round trip there would stall every moment on three uploads.
+ *
+ * Write-behind is also free to do honestly: `StoredObject` needs a key, a byte size, a checksum and
+ * a content type, and all four are computable on this machine. Nothing is guessed and nothing is
+ * reported that has not actually happened.
+ */
+export interface UploadingObjectStoreDeps {
+  client: RunnerClient;
+  spool: BlobSpool;
+  leaseId: string;
+  clock: Clock;
+  /** Evidence uploads are throughput, not latency. Two at a time keeps the loop's bandwidth free. */
+  concurrency?: number;
+  onError?: (key: string, error: Error) => void;
+}
+
+interface Pending {
+  key: string;
+  hash: string;
+  contentType: string;
+}
+
+export class UploadingObjectStore implements ObjectStore {
+  private readonly queue: Pending[] = [];
+  private readonly inFlight = new Set<Promise<void>>();
+  private readonly local = new Map<string, StoredObject>();
+  private readonly concurrency: number;
+  /**
+   * Uploads in flight, keyed by hash.
+   *
+   * The original and the redacted derivative are frequently byte-identical, and with two workers
+   * both would look at `serverHas` before either had finished and each would send the bytes. The
+   * spool's acknowledgement is only set *after* an upload returns, so it cannot deduplicate on its
+   * own.
+   */
+  private readonly uploading = new Map<string, Promise<void>>();
+  private failures = 0;
+
+  constructor(private readonly deps: UploadingObjectStoreDeps) {
+    this.concurrency = deps.concurrency ?? 2;
+  }
+
+  async put(key: string, bytes: Buffer, contentType: string): Promise<StoredObject> {
+    const hash = await this.deps.spool.put(bytes);
+    const stored: StoredObject = {
+      key,
+      byteSize: bytes.byteLength,
+      checksumSha256: checksumOf(bytes),
+      contentType,
+    };
+    this.local.set(key, stored);
+
+    this.queue.push({ key, hash, contentType });
+    this.pump();
+    return stored;
+  }
+
+  /**
+   * Served from the spool, never from the network.
+   *
+   * `EvidencePipeline` reads back the redacted variant to build a thumbnail from it. A round trip
+   * to fetch bytes this process created milliseconds ago would be absurd.
+   */
+  async get(key: string): Promise<Buffer> {
+    const stored = this.local.get(key);
+    if (!stored) throw new Error(`No such object: ${key}`);
+    const bytes = await this.deps.spool.get(stored.checksumSha256);
+    if (!bytes) throw new Error(`The local copy of ${key} is gone.`);
+    return bytes;
+  }
+
+  async head(key: string): Promise<StoredObject | null> {
+    return this.local.get(key) ?? null;
+  }
+
+  /** The spool only. The server owns retention, and SPEC 16.4 requires deletion to be recorded. */
+  async delete(key: string): Promise<void> {
+    this.local.delete(key);
+  }
+
+  /**
+   * Minting access is a server responsibility and nothing in the runner's call path asks for it.
+   * Throwing rather than returning a plausible no-op means a future mistake surfaces here instead
+   * of producing a grant that grants nothing.
+   */
+  async grant(_key: string, _ttlSeconds: number, _nowMs: number): Promise<AccessGrant> {
+    throw new Error("A local runner does not mint access grants. The server does.");
+  }
+
+  async resolveGrant(_token: string, _nowMs: number): Promise<string | null> {
+    throw new Error("A local runner does not resolve access grants. The server does.");
+  }
+
+  /** The barrier the run loop awaits before telling the server the study is finished. */
+  async flush(timeoutMs = 120_000): Promise<{ pending: number; failed: number }> {
+    const deadline = Date.now() + timeoutMs;
+    while ((this.queue.length > 0 || this.inFlight.size > 0) && Date.now() < deadline) {
+      this.pump();
+      await Promise.race([...this.inFlight, delay(50)]);
+    }
+    return { pending: this.queue.length + this.inFlight.size, failed: this.failures };
+  }
+
+  private pump(): void {
+    while (this.inFlight.size < this.concurrency && this.queue.length > 0) {
+      const next = this.queue.shift()!;
+      const task = this.upload(next).finally(() => this.inFlight.delete(task));
+      this.inFlight.add(task);
+    }
+  }
+
+  private async uploadBytesOnce(pending: Pending): Promise<void> {
+    const existing = this.uploading.get(pending.hash);
+    if (existing) return existing;
+
+    const task = (async () => {
+      const bytes = await this.deps.spool.get(pending.hash);
+      if (!bytes) throw new Error("The local copy is gone before it was uploaded.");
+      await this.deps.client.request(`api/runner/blobs/${pending.hash}`, {
+        method: "PUT",
+        raw: { bytes, contentType: pending.contentType },
+      });
+      this.deps.spool.markAcknowledged(pending.hash);
+    })().finally(() => this.uploading.delete(pending.hash));
+
+    this.uploading.set(pending.hash, task);
+    return task;
+  }
+
+  private async upload(pending: Pending): Promise<void> {
+    try {
+      if (!this.deps.spool.serverHas(pending.hash)) {
+        await this.uploadBytesOnce(pending);
+      }
+
+      // Binding the key to the hash is a separate, tiny call, so re-sending a key after a failure
+      // never re-sends the bytes.
+      await this.deps.client.request("api/runner/objects", {
+        method: "POST",
+        body: {
+          leaseId: this.deps.leaseId,
+          key: pending.key,
+          sha256: pending.hash,
+          contentType: pending.contentType,
+        },
+      });
+    } catch (error) {
+      this.failures += 1;
+      this.deps.onError?.(pending.key, error as Error);
+    }
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @aloud/runner: the local runner.
+ *
+ * SPEC Phase 5: "Cloud control plane never gains arbitrary access to the customer's local network."
+ * The connection is outbound only. The cloud holds no address for this machine, and the machine
+ * keeps its own allowlist that nothing arriving over the wire can edit.
+ *
+ * Note what this package does *not* depend on: `@aloud/app`. The runner reuses `RunCoordinator`,
+ * `PlaywrightWorkerFactory`, `ModelGateway` and `EvidencePipeline` unchanged, and proxies the only
+ * two ports that need a server behind them.
+ */
+export * from "./config/credentials";
+export * from "./config/policy";
+export * from "./protocol/client";
+export * from "./protocol/blob-spool";
+export * from "./model/proxy-adapter";
+export * from "./evidence/uploading-store";
+export * from "./run/sanitise";
+export * from "./run/guarded-workers";
+export * from "./run/event-shipper";
+export * from "./run/execute";
+export * from "./ui/output";
+export * from "./preflight";
+export * from "./loop";

package/src/loop.ts

@@ -0,0 +1,117 @@
+import { systemClock, type JobLease, type StudyRun } from "@aloud/core";
+import { OfflineError, RunnerClient, LeaseLostError, ServerError } from "./protocol/client";
+import { BlobSpool } from "./protocol/blob-spool";
+import { executeLease, type ExecuteResult, type RunReporter } from "./run/execute";
+import type { StageRouting } from "./model/proxy-adapter";
+import type { LocalPolicy } from "./config/policy";
+
+/**
+ * Claim, run, repeat.
+ *
+ * The poll interval is adaptive because on a serverless control plane every poll is an invocation.
+ * Two seconds right after `start`, when someone has just launched the runner and is about to press
+ * go; five after that; fifteen once nothing has happened for a while. So a study begins within two
+ * to fifteen seconds of being launched in the web app, which is worth saying out loud rather than
+ * leaving people to wonder.
+ */
+export const POLL_FAST_MS = 2_000;
+export const POLL_NORMAL_MS = 5_000;
+export const POLL_IDLE_MS = 15_000;
+const FAST_WINDOW_MS = 30_000;
+const IDLE_AFTER_MS = 5 * 60_000;
+
+interface ClaimResponse {
+  lease?: JobLease;
+  run?: StudyRun;
+  productId?: string;
+  routing?: Partial<Record<string, StageRouting>>;
+}
+
+export interface LoopDeps {
+  client: RunnerClient;
+  local: LocalPolicy;
+  ui: RunReporter & { waiting?(url: string): void };
+  webUrl: string;
+  /** Claim one lease, run it, and stop. For CI, and for `aloud start --once`. */
+  once?: boolean;
+  spool?: BlobSpool;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  signal?: AbortSignal;
+  workers?: Parameters<typeof executeLease>[0]["workers"];
+}
+
+export async function runLoop(deps: LoopDeps): Promise<ExecuteResult[]> {
+  const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = deps.now ?? (() => Date.now());
+  const spool = deps.spool ?? new BlobSpool();
+
+  const startedAt = now();
+  let lastActivityAt = now();
+  const results: ExecuteResult[] = [];
+  deps.ui.waiting?.(deps.webUrl);
+
+  while (!deps.signal?.aborted) {
+    let claim: ClaimResponse | null = null;
+    try {
+      const response = await deps.client.request<ClaimResponse>("api/runner/claim", {
+        method: "POST",
+        // A poll should fail fast and come back, not block for a minute holding the loop.
+        retry: false,
+        ...(deps.signal ? { signal: deps.signal } : {}),
+      });
+      claim = response.status === 204 ? null : response.body;
+    } catch (error) {
+      if (error instanceof LeaseLostError) throw error;
+      if (!(error instanceof ServerError) && !(error instanceof OfflineError)) {
+        // A transport failure while idle is not interesting. Wait and try again.
+        await sleep(POLL_NORMAL_MS);
+        continue;
+      }
+      if (error instanceof ServerError && error.status >= 500) {
+        await sleep(POLL_IDLE_MS);
+        continue;
+      }
+      throw error;
+    }
+
+    if (claim?.lease && !claim.run) {
+      // The server offered work without saying what it is. Better to say so than to invent a run
+      // row and write a report whose methodology section is fiction.
+      deps.ui.failed("The server offered a lease with no run attached. Nothing was started.");
+      await sleep(POLL_IDLE_MS);
+      continue;
+    }
+
+    if (!claim?.lease || !claim.run) {
+      const sinceStart = now() - startedAt;
+      const sinceActivity = now() - lastActivityAt;
+      const wait =
+        sinceStart < FAST_WINDOW_MS ? POLL_FAST_MS : sinceActivity > IDLE_AFTER_MS ? POLL_IDLE_MS : POLL_NORMAL_MS;
+      await sleep(wait);
+      continue;
+    }
+
+    lastActivityAt = now();
+    const result = await executeLease({
+      client: deps.client,
+      lease: claim.lease,
+      run: claim.run,
+      productId: claim.productId ?? "",
+      routing: (claim.routing ?? {}) as never,
+      local: deps.local,
+      spool,
+      ui: deps.ui,
+      ...(deps.workers ? { workers: deps.workers } : {}),
+      ...(deps.now ? { now: deps.now } : {}),
+    });
+    results.push(result);
+    lastActivityAt = now();
+
+    if (deps.once) break;
+    deps.ui.waiting?.(deps.webUrl);
+  }
+
+  void systemClock;
+  return results;
+}

package/src/model/proxy-adapter.ts

@@ -0,0 +1,188 @@
+import { ModelError, type AdapterRequest, type AdapterResponse, type ModelAdapter } from "@aloud/engine";
+import type { ProviderName, PromptStage } from "@aloud/core";
+import { LeaseLostError, ServerError, type RunnerClient } from "../protocol/client";
+import type { BlobSpool } from "../protocol/blob-spool";
+
+/**
+ * A `ModelAdapter` that spends the server's key instead of one on this machine.
+ *
+ * The runner never holds a provider credential. That is not only a security property: it is the
+ * only place the free allowance can be enforced, because the model proxy is the single point where
+ * money is actually spent.
+ *
+ * Which model each stage uses is decided **by the server** and validated there on every call. If
+ * the runner chose, it could route every stage to the most expensive model available and the
+ * server would pay for it.
+ */
+export interface StageRouting {
+  provider: ProviderName;
+  modelId: string;
+  supportsImages: boolean;
+}
+
+export interface ProxyModelAdapterDeps {
+  client: RunnerClient;
+  spool: BlobSpool;
+  leaseId: string;
+  stage: PromptStage;
+  routing: StageRouting;
+  onSpend?: (spent: { costCents: number; spentCents: number; remainingCents: number | null }) => void;
+  /**
+   * Called when the server refuses to spend any more.
+   *
+   * Worth surfacing separately because of how it looks otherwise: every participant fails with an
+   * infrastructure error, the run "completes", and the report says nobody could do the task. The
+   * reason was money, and saying so is the difference between a confusing report and a fixable one.
+   */
+  onBudgetExhausted?: (message: string) => void;
+  /**
+   * Called when the server says this runner no longer holds the lease.
+   *
+   * Without it the sessions die one by one with what looks like an infrastructure error, the run
+   * "completes", and a report gets written for a study that was revoked halfway through.
+   */
+  onLeaseLost?: (message: string) => void;
+}
+
+interface ModelProxyResponse {
+  text?: string;
+  usage?: AdapterResponse["usage"];
+  stopReason?: AdapterResponse["stopReason"];
+  costCents?: number;
+  spentCents?: number;
+  remainingCents?: number | null;
+  missingBlobs?: string[];
+}
+
+export class ProxyModelAdapter implements ModelAdapter {
+  readonly provider: ProviderName;
+  readonly modelId: string;
+  readonly supportsImages: boolean;
+
+  constructor(private readonly deps: ProxyModelAdapterDeps) {
+    this.provider = deps.routing.provider;
+    this.modelId = deps.routing.modelId;
+    this.supportsImages = deps.routing.supportsImages;
+  }
+
+  async generate(request: AdapterRequest): Promise<AdapterResponse> {
+    const images = await this.prepareImages(request);
+
+    try {
+      const first = await this.post(request, images);
+      if (!first.missingBlobs?.length) return this.toResponse(first);
+
+      // The server lost a blob it had acknowledged. Send those bytes inline once, and stop
+      // claiming it has them.
+      for (const hash of first.missingBlobs) this.deps.spool.markMissing(hash);
+      const inlined = await this.prepareImages(request, new Set(first.missingBlobs));
+      const second = await this.post(request, inlined);
+      if (second.missingBlobs?.length) {
+        throw new ModelError("The server could not find the screenshots for this call.", "transport", true, this.deps.stage);
+      }
+      return this.toResponse(second);
+    } catch (error) {
+      const translated = this.translate(error);
+      if (translated instanceof LeaseLostError) this.deps.onLeaseLost?.(translated.message);
+      throw translated;
+    }
+  }
+
+  private async post(request: AdapterRequest, images: unknown[]): Promise<ModelProxyResponse> {
+    const { body } = await this.deps.client.request<ModelProxyResponse>("api/runner/model", {
+      method: "POST",
+      body: {
+        leaseId: this.deps.leaseId,
+        stage: this.deps.stage,
+        // Sent so the server can reject a mismatch loudly rather than silently billing for
+        // something the runner did not ask for. The server's own table is the authority.
+        modelId: this.modelId,
+        system: request.system,
+        prompt: request.prompt,
+        responseShape: request.responseShape,
+        maxOutputTokens: request.maxOutputTokens,
+        temperature: request.temperature,
+        images,
+      },
+      ...(request.signal ? { signal: request.signal } : {}),
+    });
+    return body ?? {};
+  }
+
+  /** A hash if the server already has the bytes, the bytes if it does not. */
+  private async prepareImages(request: AdapterRequest, forceInline?: Set<string>): Promise<unknown[]> {
+    const out: unknown[] = [];
+    for (const image of request.images) {
+      const hash = await this.deps.spool.put(image.data);
+      if (!forceInline?.has(hash) && this.deps.spool.serverHas(hash)) {
+        out.push({ mimeType: image.mimeType, sha256: hash });
+        continue;
+      }
+
+      // First sighting. The model genuinely needs these pixels, so this upload is unavoidable and
+      // correct; every later reference to the same screenshot costs sixty-four characters.
+      await this.deps.client.request(`api/runner/blobs/${hash}`, {
+        method: "PUT",
+        raw: { bytes: image.data, contentType: image.mimeType },
+        ...(request.signal ? { signal: request.signal } : {}),
+      });
+      this.deps.spool.markAcknowledged(hash);
+      out.push({ mimeType: image.mimeType, sha256: hash });
+    }
+    return out;
+  }
+
+  private toResponse(body: ModelProxyResponse): AdapterResponse {
+    if (typeof body.text !== "string") {
+      throw new ModelError("The model proxy returned no text.", "invalid_output", false, this.deps.stage);
+    }
+    if (this.deps.onSpend && typeof body.costCents === "number" && typeof body.spentCents === "number") {
+      this.deps.onSpend({
+        costCents: body.costCents,
+        spentCents: body.spentCents,
+        remainingCents: body.remainingCents ?? null,
+      });
+    }
+    return {
+      text: body.text,
+      usage: body.usage ?? { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningTokens: 0, imageCount: 0 },
+      stopReason: body.stopReason ?? "complete",
+    };
+  }
+
+  /**
+   * Maps the server's answer onto what `ModelGateway` already knows how to handle.
+   *
+   * The distinction that matters is retryable versus not. A rate limit should back off and try
+   * again; running out of allowance should stop immediately, because retrying it is just a slower
+   * way to fail.
+   */
+  private translate(error: unknown): Error {
+    if (error instanceof ModelError) return error;
+    if (error instanceof LeaseLostError) return error;
+
+    if (error instanceof ServerError) {
+      if (error.status === 409) return new LeaseLostError("This lease is no longer claimed by this runner.");
+      if (error.status === 402 || codeOf(error.body) === "budget") {
+        this.deps.onBudgetExhausted?.(error.message);
+        return new ModelError(error.message, "budget", false, this.deps.stage);
+      }
+      if (error.status === 429 || error.status === 503) {
+        return new ModelError(error.message, "rate_limit", true, this.deps.stage);
+      }
+      if (error.status >= 500) return new ModelError(error.message, "transport", true, this.deps.stage);
+      return new ModelError(error.message, "invalid_output", false, this.deps.stage);
+    }
+
+    // A dropped connection, a DNS failure, an offline horizon reached.
+    return new ModelError((error as Error).message, "transport", true, this.deps.stage);
+  }
+}
+
+function codeOf(body: unknown): string | null {
+  if (body && typeof body === "object" && "code" in body) {
+    const code = (body as { code?: unknown }).code;
+    if (typeof code === "string") return code;
+  }
+  return null;
+}

package/src/preflight.ts

@@ -0,0 +1,96 @@
+import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+/**
+ * Checks that must pass before a lease is claimed.
+ *
+ * The ordering matters more than it looks. `chromium.launch()` failing throws *outside*
+ * `ParticipantSession`'s try/catch, so it rejects `Promise.all` and takes the whole run down with a
+ * generic failure. Claiming a lease with no browser installed would make that a new user's first
+ * experience of the product.
+ */
+export interface PreflightResult {
+  chromiumInstalled: boolean;
+  chromiumPath: string | null;
+  problems: string[];
+}
+
+export async function preflight(): Promise<PreflightResult> {
+  const problems: string[] = [];
+  let chromiumPath: string | null = null;
+
+  try {
+    const { chromium } = await import("playwright");
+    // `executablePath()` returns where the binary is expected without checking that it is there,
+    // so the existence check is ours to make.
+    chromiumPath = chromium.executablePath();
+  } catch (error) {
+    problems.push(`Playwright could not be loaded: ${(error as Error).message}`);
+  }
+
+  const installed = Boolean(chromiumPath && existsSync(chromiumPath));
+  if (!installed) {
+    problems.push("Chromium is not installed yet.");
+  }
+
+  return { chromiumInstalled: installed, chromiumPath, problems };
+}
+
+/**
+ * Downloads Chromium, having said how big it is first.
+ *
+ * `--no-shell` matters: the default installs both full Chromium (about 356 MB) and the headless
+ * shell (about 196 MB), and `PlaywrightBrowserWorker` launches the full one. Installing both would
+ * cost an extra 196 MB that nothing here ever runs.
+ */
+export async function installChromium(log: (line: string) => void): Promise<boolean> {
+  log("Chromium is not installed yet. It is about 350 MB and downloads once.");
+  log("");
+
+  const cli = playwrightCli();
+  const [command, args] = cli
+    ? [process.execPath, [cli, "install", "chromium", "--no-shell"]]
+    : ["npx", ["playwright", "install", "chromium", "--no-shell"]];
+
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
+    });
+    child.stdout?.on("data", (chunk: Buffer) => log(chunk.toString("utf8").trimEnd()));
+    child.stderr?.on("data", (chunk: Buffer) => log(chunk.toString("utf8").trimEnd()));
+    child.on("error", () => resolve(false));
+    child.on("close", (code) => {
+      if (code !== 0) {
+        // Corporate proxies are the usual reason. Naming the command is more useful than a stack.
+        log("");
+        log("That download did not work. Behind a proxy, try:");
+        log("  PLAYWRIGHT_DOWNLOAD_HOST=<your mirror> npx playwright install chromium --no-shell");
+      }
+      resolve(code === 0);
+    });
+  });
+}
+
+/**
+ * The Playwright CLI belonging to *this* install, if it can be found.
+ *
+ * `npx playwright` was fine while this only ever ran from the repo, and wrong the moment it ships
+ * as a global install: npx searches the current directory, then the registry, so on a machine with
+ * no local playwright it downloads a second, newer one and installs that version's Chromium build.
+ * The playwright we import then looks for its own build number, does not find it, and preflight
+ * fails forever with a browser sitting on disk. Resolving the CLI next to the playwright we
+ * actually import cannot drift. `playwright/cli.js` is not in the package's exports map, so this
+ * goes via its package.json, which is.
+ */
+function playwrightCli(): string | null {
+  try {
+    const require = createRequire(import.meta.url);
+    const cli = join(dirname(require.resolve("playwright/package.json")), "cli.js");
+    return existsSync(cli) ? cli : null;
+  } catch {
+    return null;
+  }
+}

package/src/protocol/blob-spool.ts

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Content-addressed local storage for screenshots, and the reason the runner is usable on a normal
+ * home connection.
+ *
+ * The same PNG is sent up to five times per moment today: once for the participant's decision, once
+ * for their reaction, then again as the original, redacted and thumbnail evidence variants. At a
+ * realistic 300 KB per screenshot that is over a megabyte per moment, and 300 KB of it sits on the
+ * critical path of every single model call. On a 1 Mbps upstream that adds about two and a half
+ * seconds to each of roughly 120 calls, which is five minutes of wall clock spent re-uploading
+ * bytes the server already has.
+ *
+ * So every buffer is hashed on sight. The first time the server sees a hash it gets the bytes; from
+ * then on it gets sixty-four hex characters.
+ *
+ * The spool is keyed **only** by sha256 hex. Never by a server-supplied object key: those are built
+ * from workspace, study, run and session ids that all arrive over the wire, and a `runId` of
+ * `../../..` would otherwise be a path traversal on the customer's own machine.
+ */
+export function sha256(bytes: Uint8Array | Buffer): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export function spoolRoot(home = homedir()): string {
+  return join(home, ".aloud", "spool");
+}
+
+export class BlobSpool {
+  /** Hashes the server has acknowledged. Cleared when the server says it lost one. */
+  private readonly acknowledged = new Set<string>();
+  private readonly memory = new Map<string, Buffer>();
+
+  constructor(
+    private readonly root: string | null = spoolRoot(),
+    /** Bytes held in memory before falling back to disk only. Roughly forty screenshots. */
+    private readonly memoryLimitBytes = 24 * 1024 * 1024,
+  ) {}
+
+  private memoryBytes = 0;
+
+  serverHas(hash: string): boolean {
+    return this.acknowledged.has(hash);
+  }
+
+  markAcknowledged(hash: string): void {
+    this.acknowledged.add(hash);
+  }
+
+  /** The server lost a blob (evicted, different region, cold store). Send the bytes again. */
+  markMissing(hash: string): void {
+    this.acknowledged.delete(hash);
+  }
+
+  /** Stores bytes and returns their hash. Cheap to call repeatedly with the same bytes. */
+  async put(bytes: Buffer): Promise<string> {
+    const hash = sha256(bytes);
+    if (this.memory.has(hash)) return hash;
+
+    if (this.memoryBytes + bytes.byteLength <= this.memoryLimitBytes) {
+      this.memory.set(hash, bytes);
+      this.memoryBytes += bytes.byteLength;
+    }
+
+    if (this.root) {
+      const path = this.pathFor(hash);
+      await mkdir(join(path, ".."), { recursive: true });
+      await writeFile(path, bytes).catch(() => undefined);
+    }
+    return hash;
+  }
+
+  async get(hash: string): Promise<Buffer | null> {
+    const held = this.memory.get(hash);
+    if (held) return held;
+    if (!this.root) return null;
+    return readFile(this.pathFor(hash)).catch(() => null);
+  }
+
+  /** Only the hash decides the path, so nothing from the wire can steer a write. */
+  private pathFor(hash: string): string {
+    if (!/^[0-9a-f]{64}$/.test(hash)) throw new Error(`Not a sha256 hash: ${hash}`);
+    return join(this.root!, hash.slice(0, 2), hash.slice(2, 4), hash);
+  }
+}