@visual-z/xeno 0.1.0

package/src/runtime/usage.ts

@@ -0,0 +1,225 @@
+/**
+ * Per-request usage accounting.
+ *
+ * This exists to answer the question the whole design rests on: is the prompt
+ * prefix actually stable? The core's claim is that appending within a node
+ * only appends, so every turn should read the entire accumulated prefix from
+ * cache and write only what the last turn added. That is checkable, and the
+ * shape of a healthy loop is specific:
+ *
+ *   cache_read grows turn over turn and covers the whole prior prefix
+ *   cache_creation is small -- only the delta
+ *   input_tokens (uncached) stays near zero after the first turn
+ *
+ * A cache_read that sits at zero across turns with the same prefix means a
+ * silent invalidator got in. Since that failure costs money without ever
+ * raising an error, measuring it is the only way to know.
+ *
+ * Pure: the aggregator takes samples and returns totals. The caller records
+ * the timestamps.
+ *
+ * The field names below are a NORMALISED internal vocabulary, not one
+ * provider's wire format. Every adapter maps onto them: a provider that bills
+ * nothing for cache writes reports 0 there rather than leaving the field to
+ * mean something else.
+ */
+
+import type { CacheKind, CacheRates, Price } from "./model.ts";
+
+/** What one API response reports, normalised by the adapter. */
+export interface UsageSample {
+  input_tokens: number;
+  output_tokens: number;
+  cache_creation_input_tokens: number;
+  cache_read_input_tokens: number;
+  /** Which node the request belonged to, so per-node costs stay separable. */
+  node: number;
+  /** Wall-clock milliseconds for the request. */
+  ms: number;
+}
+
+export interface UsageTotals {
+  requests: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_creation_input_tokens: number;
+  cache_read_input_tokens: number;
+  ms: number;
+  /**
+   * Total prompt size is the sum of all three input fields -- `input_tokens`
+   * alone is only the uncached remainder. An agent that ran for hours can show
+   * 4K there while the real prefix was 200K.
+   */
+  prompt_tokens: number;
+  /**
+   * Fraction of prompt tokens served from cache. The number that says whether
+   * the append-only property is holding in practice.
+   */
+  cache_hit_rate: number;
+}
+
+export function emptyTotals(): UsageTotals {
+  return {
+    requests: 0,
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_creation_input_tokens: 0,
+    cache_read_input_tokens: 0,
+    ms: 0,
+    prompt_tokens: 0,
+    cache_hit_rate: 0,
+  };
+}
+
+export function totalUsage(samples: readonly UsageSample[]): UsageTotals {
+  const t = emptyTotals();
+  for (const s of samples) {
+    t.requests += 1;
+    t.input_tokens += s.input_tokens;
+    t.output_tokens += s.output_tokens;
+    t.cache_creation_input_tokens += s.cache_creation_input_tokens;
+    t.cache_read_input_tokens += s.cache_read_input_tokens;
+    t.ms += s.ms;
+  }
+  t.prompt_tokens =
+    t.input_tokens + t.cache_creation_input_tokens + t.cache_read_input_tokens;
+  t.cache_hit_rate =
+    t.prompt_tokens === 0 ? 0 : t.cache_read_input_tokens / t.prompt_tokens;
+  return t;
+}
+
+/**
+ * Cost in equivalent base-input tokens, the unit appendix A's model uses.
+ *
+ * Reported as a multiplier rather than dollars so it stays true across models
+ * and price changes. The rates come from the model rather than from this
+ * module: they are not a property of the unit, they are a property of the
+ * provider's contract, and they differ by an order of magnitude. Anthropic
+ * bills reads at 0.1x and 5-minute writes at 1.25x; DeepSeek bills reads at
+ * 0.033x and writes at nothing. Output is counted separately because its rate
+ * is a different multiple of input and varies by model.
+ */
+export interface EquivalentCost {
+  input_equivalent: number;
+  output_tokens: number;
+  /** What the same prompts would have cost with no caching at all. */
+  uncached_equivalent: number;
+  /** uncached / actual. 1.0 means caching bought nothing. */
+  savings_ratio: number;
+}
+
+/**
+ * Dollar cost of a session: complete, partial, or an explicit unknown.
+ *
+ * Unknown is a distinct member, not the number 0: a missing price times any
+ * token count is not "this session was free", and collapsing the two is how
+ * `/usage` would silently misreport every unpriced model.
+ *
+ * Partial is a distinct member, not `{kind:"usd", amount, note}`. A caller
+ * that only reads `amount` on `usd` must not be able to print a total that
+ * silently omitted cache spend as if the unknown rate were zero. `known`
+ * is the part we can prove; `uncounted` is why it is not a complete bill.
+ */
+export type ReportedCost =
+  | { kind: "unknown" }
+  | { kind: "usd"; amount: number }
+  | { kind: "partial"; known: number; uncounted: "cache" };
+
+export function reportedCost(t: UsageTotals, price: Price | undefined): ReportedCost {
+  if (price === undefined) return { kind: "unknown" };
+  const known =
+    (t.input_tokens * price.input + t.output_tokens * price.output) / 1_000_000;
+  if (price.cacheRead !== undefined && price.cacheWrite !== undefined) {
+    const amount =
+      known +
+      (t.cache_read_input_tokens * price.cacheRead +
+        t.cache_creation_input_tokens * price.cacheWrite) /
+        1_000_000;
+    return { kind: "usd", amount };
+  }
+  // One or both cache rates are missing. Add the ones we have; never
+  // substitute 0 for the ones we do not — that is the low-bill path.
+  let extra = 0;
+  if (price.cacheRead !== undefined) {
+    extra += (t.cache_read_input_tokens * price.cacheRead) / 1_000_000;
+  }
+  if (price.cacheWrite !== undefined) {
+    extra += (t.cache_creation_input_tokens * price.cacheWrite) / 1_000_000;
+  }
+  return { kind: "partial", known: known + extra, uncounted: "cache" };
+}
+
+export function equivalentCost(t: UsageTotals, rates: CacheRates): EquivalentCost {
+  const actual =
+    t.input_tokens +
+    t.cache_creation_input_tokens * rates.write +
+    t.cache_read_input_tokens * rates.read;
+  const uncached = t.prompt_tokens;
+  return {
+    input_equivalent: actual,
+    output_tokens: t.output_tokens,
+    uncached_equivalent: uncached,
+    savings_ratio: actual === 0 ? 1 : uncached / actual,
+  };
+}
+
+/**
+ * Per-turn diagnosis of whether the prefix held.
+ *
+ * `cache_creation` above the delta means something ahead of the new content
+ * changed, which is the signature of an invalidator rather than of growth.
+ *
+ * What counts as a symptom depends on who controls the cache. Under `explicit`
+ * caching the caller placed the breakpoint, so a miss on a follow-up request
+ * means the prefix moved and that is worth shouting about. Under `automatic`
+ * caching the provider decides: DeepSeek documents its cache as best-effort
+ * with no guaranteed hit rate and writes that "take seconds", so an early miss
+ * is the normal case. Reporting it would light a warning at the start of every
+ * session, and a warning that is always on stops being read.
+ */
+export type PrefixVerdict =
+  | { kind: "cold"; detail: string }
+  | { kind: "healthy"; read: number; wrote: number }
+  | { kind: "suspicious"; detail: string };
+
+export function diagnosePrefix(
+  sample: UsageSample,
+  previous: UsageSample | undefined,
+  cache: CacheKind,
+): PrefixVerdict {
+  if (!previous) {
+    return { kind: "cold", detail: "first request of the session; nothing to reuse yet" };
+  }
+  if (sample.cache_read_input_tokens === 0) {
+    return cache === "automatic"
+      ? {
+          kind: "cold",
+          detail:
+            "no cache hit yet -- this provider caches on its own, best-effort, and " +
+            "a write takes seconds to land. Only a problem if it persists across turns",
+        }
+      : {
+          kind: "suspicious",
+          detail:
+            "cache_read is 0 on a follow-up request -- the prefix changed, or it is " +
+            "below the model's minimum cacheable size",
+        };
+  }
+  const previousPrompt =
+    previous.input_tokens +
+    previous.cache_creation_input_tokens +
+    previous.cache_read_input_tokens;
+  if (sample.cache_read_input_tokens < previousPrompt * 0.5) {
+    return {
+      kind: "suspicious",
+      detail:
+        `cache_read (${sample.cache_read_input_tokens}) covers less than half of the ` +
+        `previous prompt (${previousPrompt}) -- part of the prefix was invalidated`,
+    };
+  }
+  return {
+    kind: "healthy",
+    read: sample.cache_read_input_tokens,
+    wrote: sample.cache_creation_input_tokens,
+  };
+}

package/src/runtime/window-trial.ts

@@ -0,0 +1,140 @@
+/** N.13: real sessions with independent file verdicts at every stage. */
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { verifyWindowArtifact, windowPrompt, type WindowFixture } from "../core/window-trial.ts";
+import type { BenchmarkPrice } from "../core/benchmark.ts";
+import { projectContext } from "../core/project.ts";
+import { readNodeHistory } from "../store/restore.ts";
+import { manifestPath, nodePath } from "../store/log.ts";
+import { Session, type SessionConfig } from "./loop.ts";
+import { buildRequest, OpenAICompletionsProvider } from "./openai.ts";
+import type { Provider, ProviderConfig } from "./provider.ts";
+import { COMPARISON_SYSTEM, COMPARISON_TOOLS, comparisonGateway, comparisonPayload, comparisonTools, type ComparisonBackend, type ComparisonLedger, type GatewayRecord } from "./harness-comparison.ts";
+import { DEFAULT_TOOL_CONTEXT } from "./tools.ts";
+
+const sha = (body: string) => createHash("sha256").update(body).digest("hex");
+export interface WindowStageResult {
+  stage: number; status: "answered" | "stopped" | "balance" | "error"; reason: string;
+  artifact: { ok: boolean; reason: string }; artifactSha256: string | null;
+  fullPageRead: boolean; inputsUnchanged: boolean; passed: boolean;
+  lastEvent: string | null; inputs: Record<string, string | null>;
+  requestBegin: number; requestEnd: number; nodeBefore: number; nodeAfter: number;
+  restart: { beforeSha256: string; afterSha256: string } | null;
+}
+export interface WindowTrialResult {
+  policy: "windowed" | "continuous"; planned: number; stages: WindowStageResult[]; unrun: number;
+  cuts: number; firstCutStage: number | null; restartedAt: number | null;
+  requests: number; knownCost: number; reservedUnknown: number; peakPrompt: number;
+  promptTokens: number; cacheTokens: number; outputTokens: number; prefixMutationsWithinNode: number;
+  toolExecutions: number; toolFailures: number; wallMs: number;
+  stopped: "budget" | "balance" | "error" | "limit" | null;
+}
+
+export async function runWindowTrial(options: {
+  directory: string; fixture: WindowFixture; policy: WindowTrialResult["policy"];
+  config: ProviderConfig; price: BenchmarkPrice; ledger: ComparisonLedger; backend: ComparisonBackend;
+  maxTurns: number; stageTimeoutMs: number; maxOutputBytes: number;
+  /** windowed restarts after its first cut; continuous uses that same stage. */
+  restartAfterStage?: number | null;
+  onProgress?: (event: Record<string, unknown>) => Promise<void>;
+}): Promise<WindowTrialResult> {
+  const started = performance.now(), workspace = join(options.directory, "workspace"), logDir = join(options.directory, "log");
+  await mkdir(workspace, { recursive: true }); await mkdir(logDir);
+  const result: WindowTrialResult = { policy: options.policy, planned: options.fixture.pages.length, stages: [], unrun: options.fixture.pages.length,
+    cuts: 0, firstCutStage: null, restartedAt: null, requests: 0, knownCost: 0, reservedUnknown: 0, peakPrompt: 0,
+    promptTokens: 0, cacheTokens: 0, outputTokens: 0, prefixMutationsWithinNode: 0, toolExecutions: 0, toolFailures: 0, wallMs: 0, stopped: null };
+  let stage = 0, lastNode: number | null = null, sentNode = 0;
+  const gateway = comparisonGateway({ config: options.config, price: options.price, ledger: options.ledger,
+    maxRequests: options.maxTurns * options.fixture.pages.length, backend: options.backend, record: async record => {
+      await appendFile(join(options.directory, "requests.jsonl"), JSON.stringify({ stage, node: sentNode, ...record }) + "\n");
+      if (record.kind === "settled") {
+        result.requests++;
+        if (record.measured === null) result.reservedUnknown += record.reservation; else result.knownCost += record.measured;
+        const usage = record.usage;
+        if (usage) {
+          const prompt = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
+          result.peakPrompt = Math.max(result.peakPrompt, prompt); result.promptTokens += prompt;
+          result.cacheTokens += usage.cache_read_input_tokens; result.outputTokens += usage.output_tokens;
+        }
+        if (lastNode === sentNode && record.prefixUnchanged === false) result.prefixMutationsWithinNode++;
+        lastNode = sentNode;
+      }
+      await options.onProgress?.({ phase: record.kind, policy: options.policy, stage, request: record.request,
+        measured: record.measured, failure: record.failure, result });
+    } });
+  const config = { ...options.config, spec: { ...options.config.spec, baseUrl: gateway.url } };
+  const actual = new OpenAICompletionsProvider(config, gateway.token, { retry: { maxRetries: 0, maxRetryDelayMs: 0 } });
+  const sessionConfig: SessionConfig = { logDir, blobDir: join(options.directory, "blobs"),
+    frozen: { system: COMPARISON_SYSTEM, tools: comparisonTools() },
+    tools: { ...DEFAULT_TOOL_CONTEXT, root: workspace, allow: COMPARISON_TOOLS, maxOutputBytes: options.maxOutputBytes,
+      outputStore: join(options.directory, "observations") }, contextPolicy: options.policy, maxTurns: options.maxTurns, harnessReviews: false };
+  const provider: Provider = { config, async send(frozen, messages, node, signal, onDelta) {
+    sentNode = node;
+    await appendFile(join(options.directory, "dispatch.jsonl"), JSON.stringify({ stage, request: gateway.requests + 1, node,
+      lastEvent: session.state.events.at(-1)?.id,
+      inputSha256: sha(JSON.stringify(comparisonPayload(config, buildRequest(config, frozen, messages).messages, true))) }) + "\n");
+    return actual.send(frozen, messages, node, signal, onDelta);
+  } };
+  let session = new Session(sessionConfig, provider);
+  try {
+    await session.start();
+    for (const page of options.fixture.pages) {
+      if (options.ledger.halted) break;
+      stage = page.stage;
+      const file = join(workspace, page.path); await mkdir(dirname(file), { recursive: true });
+      await writeFile(file, page.body, { flag: "wx" });
+      const row: WindowStageResult = { stage, status: "stopped", reason: "no completion", artifact: { ok: false, reason: "not checked" },
+        artifactSha256: null, fullPageRead: false, inputsUnchanged: false, passed: false, lastEvent: null, inputs: {}, requestBegin: gateway.requests,
+        requestEnd: gateway.requests, nodeBefore: session.state.node, nodeAfter: session.state.node, restart: null };
+      const signal = AbortSignal.timeout(options.stageTimeoutMs);
+      try {
+        for await (const event of session.send(windowPrompt(options.fixture, stage), signal)) {
+          if (event.kind === "cut") { result.cuts++; result.firstCutStage ??= stage; }
+          if (event.kind === "tool_call") result.toolExecutions++;
+          if (event.kind === "tool_result" && event.ok === false) result.toolFailures++;
+          if (event.kind === "done") row.reason = event.reason ?? "unknown completion";
+        }
+        if (["stop", "end_turn"].includes(row.reason)) row.status = "answered";
+      } catch {
+        row.status = gateway.stopped === "balance" ? "balance" : "error";
+        row.reason = signal.aborted ? "stage deadline" : gateway.stopped === "balance" ? "upstream balance; awaiting topup" : "trial stopped on error";
+      }
+      row.nodeAfter = session.state.node; row.requestEnd = gateway.requests;
+      const body = await readFile(join(workspace, "ledger.json"), "utf8").catch(() => null);
+      row.artifact = verifyWindowArtifact(body, page.expected); row.artifactSha256 = body === null ? null : sha(body);
+      // Preserve failed outputs as well, before the next stage can repair them.
+      await writeFile(join(options.directory, `artifact-${stage}.json`), JSON.stringify({ body }), { flag: "wx" });
+      const history = await readNodeHistory(logDir, session.state.node, undefined, "context");
+      if (!history.ok) throw new Error(history.error);
+      const events = history.nodes.flatMap(node => node.events);
+      row.lastEvent = events.at(-1)?.id ?? null;
+      row.fullPageRead = events.some(event => event.t === "tool_result" && event.ok && event.effect?.kind === "read" &&
+        event.effect.path === page.path && event.effect.sha256 === sha(page.body) && event.effect.ranges?.some(range => range[0] === 1 && range[1] === page.body.split("\n").length) &&
+        event.content_ref === undefined && event.content.includes(page.body.split("\n").at(-1)!));
+      for (const prior of options.fixture.pages.slice(0, stage + 1)) {
+        const content = await readFile(join(workspace, prior.path), "utf8").catch(() => null);
+        row.inputs[prior.path] = content === null ? null : sha(content);
+      }
+      row.inputsUnchanged = options.fixture.pages.slice(0, stage + 1).every(prior => row.inputs[prior.path] === sha(prior.body));
+      row.passed = row.status === "answered" && row.artifact.ok && row.fullPageRead && row.inputsUnchanged;
+      const restart = options.policy === "windowed" ? result.firstCutStage : options.restartAfterStage;
+      if (row.status === "answered" && result.restartedAt === null && restart === stage) {
+        const view = () => sha(JSON.stringify(projectContext({ frozen: session.config.frozen, handoff: session.state.handoff, events: session.state.events,
+          logHint: { manifestPath: manifestPath(logDir), segmentPath: nodePath(logDir, Math.max(0, session.state.node - 1)) } })));
+        const beforeSha256 = view(); session = new Session(sessionConfig, provider); await session.start();
+        row.restart = { beforeSha256, afterSha256: view() }; result.restartedAt = stage;
+        if (row.restart.beforeSha256 !== row.restart.afterSha256) throw new Error("restart changed the context projection");
+      }
+      result.stages.push(row); result.unrun = result.planned - result.stages.length;
+      await writeFile(join(options.directory, `stage-${stage}.json`), JSON.stringify(row, null, 2) + "\n", { flag: "wx" });
+      await options.onProgress?.({ phase: "stage", policy: options.policy, stage, result });
+      if (row.status !== "answered") break;
+    }
+  } finally { await gateway.close(); }
+  result.stopped = gateway.stopped; result.wallMs = performance.now() - started;
+  await writeFile(join(options.directory, "result.json"), JSON.stringify(result, null, 2) + "\n", { flag: "wx" });
+  return result;
+}
+
+export type WindowRequest = GatewayRecord & { stage: number; node: number };

package/src/runtime/working-notes.ts

@@ -0,0 +1,30 @@
+/** O.2/O.6: validate annotations against the full projection before they can be appended. */
+import type { LogEvent } from "../core/events.ts";
+import { deriveHandoff } from "../core/derive.ts";
+import { scopedWorkId, workChangeError } from "../core/work-state.ts";
+import { replayContext } from "../store/replay.ts";
+import { digestNode, nodePath } from "../store/log.ts";
+import { resolveEvidenceNote } from "./evidence-notes.ts";
+import type { ToolResult } from "./tools.ts";
+
+export async function prepareWorkingNote(logDir: string, node: number, namespace: string, annotation: LogEvent | undefined, out: ToolResult): Promise<{ out: ToolResult; annotation?: LogEvent }> {
+  if (!annotation) return { out };
+  if (annotation.t !== "evidence_link" && !("work_id" in annotation && annotation.work_id !== undefined)) return { out, annotation };
+  const replayed = await replayContext(logDir, node);
+  const input = { prev: replayed.fullHandoff, events: replayed.events, depth: replayed.depth,
+    self: { node, log_ref: nodePath(logDir, node), sha256: await digestNode(logDir, node) } };
+  const current = deriveHandoff(input);
+  if (annotation.t === "evidence_link") {
+    const resolved = await resolveEvidenceNote(logDir, node, namespace, current, annotation);
+    return { out: resolved.result, ...(resolved.event ? { annotation: resolved.event } : {}) };
+  }
+  if (!("work_id" in annotation) || annotation.work_id === undefined) throw new Error("missing identified work annotation");
+  const workId = scopedWorkId(namespace, annotation.work_id, current.state.work_items ?? []);
+  annotation = { ...annotation, work_id: workId };
+  const error = workChangeError(current.state.work_items ?? [], annotation);
+  if (error) return { out: { ok: false, content: error } };
+  const proposed = deriveHandoff({ ...input, events: [...input.events, annotation] });
+  const item = proposed.state.work_items?.find(item => item.id === workId);
+  return { annotation, out: { ok: annotation.t !== "claim" || item?.verification === "verified",
+    content: JSON.stringify({ recorded: true, work_item: item }) } };
+}

package/src/store/atomic.ts

@@ -0,0 +1,31 @@
+/** Durable replacement for small derived metadata (D3/D8). */
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { dirname, join, basename } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export async function atomicWrite(path: string, content: string | Uint8Array): Promise<void> {
+  const directory = dirname(path);
+  await mkdir(directory, { recursive: true });
+  const temporary = join(directory, `.${basename(path)}.${randomUUID()}.tmp`);
+  try {
+    const file = await open(temporary, "wx", 0o600);
+    try {
+      await file.writeFile(content);
+      await file.sync();
+    } finally { await file.close(); }
+    await rename(temporary, path);
+    const folder = await open(directory, "r");
+    try { await folder.sync(); } finally { await folder.close(); }
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+/** The record must reach durable storage before its side effect is dispatched. */
+export async function durableAppend(path: string, record: string): Promise<void> {
+  const file = await open(path, "a", 0o600);
+  try { await file.writeFile(record); await file.sync(); }
+  finally { await file.close(); }
+  const directory = await open(dirname(path), "r");
+  try { await directory.sync(); } finally { await directory.close(); }
+}

package/src/store/auth-store.ts

@@ -0,0 +1,50 @@
+/**
+ * Read-modify-write for `auth.json`.
+ *
+ * The file holds API keys and OAuth tokens under one lock so a refresh cannot
+ * clobber a login that landed between the read and the write. 0600 is applied
+ * on every write -- an older world-readable file would otherwise keep leaking
+ * after we started storing refresh tokens in it.
+ */
+
+import { authPath, readJsonFile, writeJsonFile } from "./config.ts";
+
+export type StoredAuthEntry =
+  | { type: "api_key"; key: string }
+  | {
+      type: "oauth";
+      access: string;
+      refresh: string;
+      expires: number;
+      accountId?: string;
+      enterpriseUrl?: string;
+    };
+
+export type AuthFileContents = {
+  [provider: string]: StoredAuthEntry | undefined;
+};
+
+export async function readAuthFile(): Promise<AuthFileContents> {
+  const got = await readJsonFile<AuthFileContents>(authPath());
+  return got.value ?? {};
+}
+
+export async function writeAuthFile(auth: AuthFileContents): Promise<void> {
+  await writeJsonFile(authPath(), auth, true);
+}
+
+export async function upsertCredential(
+  provider: string,
+  credential: StoredAuthEntry,
+): Promise<void> {
+  const current = await readAuthFile();
+  const next: AuthFileContents = { ...current, [provider]: credential };
+  await writeAuthFile(next);
+}
+
+export async function deleteCredential(provider: string): Promise<void> {
+  const current = await readAuthFile();
+  const next: AuthFileContents = { ...current };
+  delete next[provider];
+  await writeAuthFile(next);
+}

package/src/store/blobs.ts

@@ -0,0 +1,142 @@
+/**
+ * Content-addressed blob store.
+ *
+ * A directory of sha256-named files, sharded two hex digits deep so no single
+ * directory holds every blob. Writes are immutable: the same bytes always land
+ * at the same address, so storing a file twice costs nothing and a stored blob
+ * is never modified in place.
+ *
+ * Why not git's object database, which is exactly this and comes free with
+ * every repository: git's lifetime contract is REACHABILITY. A blob with no
+ * ref pointing at it is by definition unreachable, which is precisely what
+ * `git gc` deletes -- and gc runs automatically on pull, merge, rebase and
+ * commit. The default two-week grace period would be the only thing between a
+ * restore and data loss, and a write-heavy store also trips git's
+ * "too many unreachable loose objects" warning, after which git refuses
+ * further automatic cleanup until its log is cleared by hand. Keeping a ref
+ * per blob is more work than this file, and it would tie the lifetime of our
+ * data to the user's git operations.
+ *
+ * What that costs: no packing and no delta compression, so a large file
+ * edited many times is stored in full each time. Acceptable while the
+ * granularity is a turn rather than a keystroke, and revisitable behind this
+ * interface if it stops being.
+ */
+
+import { readFile, access, mkdir, open, rename, rm, copyFile, stat, chmod } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { join, dirname } from "node:path";
+import { atomicWrite } from "./atomic.ts";
+
+export function blobAddress(content: string | Uint8Array): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+/** Hash and archive in bounded chunks, so large ordinary files need no cap. */
+export async function digestFile(path: string): Promise<string> {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) hash.update(chunk as Uint8Array);
+  return hash.digest("hex");
+}
+
+export async function putFileBlob(dir: string, source: string): Promise<string> {
+  await mkdir(dir, { recursive: true });
+  const temp = join(dir, `.${randomUUID()}.blob`);
+  const file = await open(temp, "wx", 0o600);
+  const hash = createHash("sha256");
+  try {
+    try {
+      for await (const chunk of createReadStream(source)) {
+        const bytes = chunk as Uint8Array;
+        hash.update(bytes);
+        await file.writeFile(bytes);
+      }
+      await file.sync();
+    } finally { await file.close(); }
+    const sha = hash.digest("hex");
+    const dest = blobFilePath(dir, sha);
+    if (await hasBlob(dir, sha)) {
+      if (await digestFile(dest) !== sha) throw new Error(`blob integrity failure: ${sha}`);
+      return sha;
+    }
+    await mkdir(dirname(dest), { recursive: true });
+    await rename(temp, dest);
+    const parent = await open(dirname(dest), "r");
+    try { await parent.sync(); } finally { await parent.close(); }
+    return sha;
+  } finally { await rm(temp, { force: true }); }
+}
+
+export async function verifyBlob(dir: string, sha: string): Promise<boolean> {
+  try {
+    if (await digestFile(blobFilePath(dir, sha)) !== sha) throw new Error(`blob integrity failure: ${sha}`);
+    return true;
+  } catch (error) {
+    if ((error as { code?: string }).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+/** Stage before replacing; never expose half of a large restored file. */
+export async function restoreBlob(dir: string, sha: string, destination: string): Promise<void> {
+  await mkdir(dirname(destination), { recursive: true });
+  const temp = `${destination}.${randomUUID()}.restore`;
+  try {
+    await copyFile(blobFilePath(dir, sha), temp);
+    if (await digestFile(temp) !== sha) throw new Error(`blob integrity failure: ${sha}`);
+    try { await chmod(temp, (await stat(destination)).mode); }
+    catch (error) { if ((error as { code?: string }).code !== "ENOENT") throw error; }
+    const file = await open(temp, "r");
+    try { await file.sync(); } finally { await file.close(); }
+    await rename(temp, destination);
+  } finally { await rm(temp, { force: true }); }
+}
+
+export function blobFilePath(dir: string, sha: string): string {
+  if (!/^[a-f0-9]{64}$/.test(sha)) throw new Error("invalid blob digest");
+  // Two-digit shard: a flat directory of tens of thousands of files is slow
+  // to list on most filesystems, and listing is how a human inspects this.
+  return join(dir, sha.slice(0, 2), sha.slice(2));
+}
+
+/** Stores content and returns its address. Storing the same bytes twice is free. */
+export async function putBlob(dir: string, content: string | Uint8Array): Promise<string> {
+  const sha = blobAddress(content);
+  const path = blobFilePath(dir, sha);
+  // Content addressing means an existing blob already holds these exact
+  // bytes, so rewriting it could only turn a good file into a torn one.
+  if (await hasBlob(dir, sha)) {
+    await getBlobBytes(dir, sha);
+    return sha;
+  }
+  await atomicWrite(path, content);
+  return sha;
+}
+
+/** Null rather than throwing: a missing blob is a state callers must handle. */
+export async function getBlob(dir: string, sha: string): Promise<string | null> {
+  const bytes = await getBlobBytes(dir, sha);
+  return bytes === null ? null : Buffer.from(bytes).toString("utf8");
+}
+
+/** Restore uses bytes; decoding binary data is an irreversible transformation. */
+export async function getBlobBytes(dir: string, sha: string): Promise<Uint8Array | null> {
+  try {
+    const bytes = await readFile(blobFilePath(dir, sha));
+    if (blobAddress(bytes) !== sha) throw new Error(`blob integrity failure: ${sha}`);
+    return bytes;
+  } catch (err) {
+    if ((err as { code?: string }).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export async function hasBlob(dir: string, sha: string): Promise<boolean> {
+  try {
+    await access(blobFilePath(dir, sha));
+    return true;
+  } catch {
+    return false;
+  }
+}