@cloudhal/storage 0.0.0-stage → 0.1.0

package/dist/migrations/0018_query_indexes.js

@@ -0,0 +1,22 @@
+                                                   
+
+/**
+ * Indexes for queries that scanned `nodes` or `media_uploads` (D1 bills rows read):
+ * - `nodes_sites`: `listSites()` (`WHERE kind = 'site' ORDER BY created_at, id`), which Studio's
+ *   notification poll runs, scanned every node of every site;
+ * - `nodes_site_kind_created`: per-site lists by kind in creation order (pages, media library)
+ *   sorted in a temporary B-tree. It covers `(site_id, kind)`, so `nodes_site_kind` goes;
+ * - `nodes_assets_created`: a key's daily upload limit (`created_at >= ?` over assets);
+ * - `media_uploads_expires`: removing expired upload tickets.
+ * Index-only: no table or row changes.
+ */
+export const migration0018QueryIndexes            = {
+  name: "0018_query_indexes",
+  sql: `
+CREATE INDEX nodes_sites ON nodes (created_at, id) WHERE kind = 'site';
+CREATE INDEX nodes_site_kind_created ON nodes (site_id, kind, created_at, id);
+DROP INDEX nodes_site_kind;
+CREATE INDEX nodes_assets_created ON nodes (created_at) WHERE kind = 'asset';
+CREATE INDEX media_uploads_expires ON media_uploads (expires_at);
+`,
+};

package/dist/migrations/0019_body_proposals.d.ts

@@ -0,0 +1,8 @@
+import type { Migration } from "../src/migrate.js";
+/**
+ * Body proposals (RFC-0014 §5, ADR-0028): `edit_body` in `propose` mode files its operations here
+ * instead of writing. A row, not a graph node, until a person accepts it: snapshots, diffs and
+ * rollbacks never read this table. `base` holds the hashes of the blocks the operations name, as
+ * the agent read them, so an operation whose block changed since is refused as stale.
+ */
+export declare const migration0019BodyProposals: Migration;

package/dist/migrations/0019_body_proposals.js

@@ -0,0 +1,24 @@
+                                                   
+
+/**
+ * Body proposals (RFC-0014 §5, ADR-0028): `edit_body` in `propose` mode files its operations here
+ * instead of writing. A row, not a graph node, until a person accepts it: snapshots, diffs and
+ * rollbacks never read this table. `base` holds the hashes of the blocks the operations name, as
+ * the agent read them, so an operation whose block changed since is refused as stale.
+ */
+export const migration0019BodyProposals            = {
+  name: "0019_body_proposals",
+  sql: `
+CREATE TABLE body_proposals (
+  id TEXT PRIMARY KEY, site_id TEXT NOT NULL,
+  node_id TEXT NOT NULL, section_id TEXT,
+  base_rev INTEGER NOT NULL, base TEXT NOT NULL, ops TEXT NOT NULL,
+  actor TEXT NOT NULL, note TEXT,
+  status TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  decided_by TEXT, decided_at TEXT, accepted_ops TEXT, result_rev INTEGER
+);
+CREATE INDEX body_proposals_node ON body_proposals (site_id, node_id, created_at);
+CREATE INDEX body_proposals_open ON body_proposals (site_id, created_at) WHERE status = 'open';
+`,
+};

package/dist/migrations/0020_ai.d.ts

@@ -0,0 +1,8 @@
+import type { Migration } from "../src/migrate.js";
+/**
+ * In-editor AI (RFC-0016): per-site settings and per-day usage.
+ * - ai_settings: a missing row = AI off. `model` is a Workers AI id or a gateway `provider/model`;
+ *   `gateway` an AI Gateway id. CAS on `rev`.
+ * - ai_usage: one row per site and UTC day, bumped by one upsert per command; the daily cap reads it.
+ */
+export declare const migration0020Ai: Migration;

package/dist/migrations/0020_ai.js

@@ -0,0 +1,31 @@
+                                                   
+
+/**
+ * In-editor AI (RFC-0016): per-site settings and per-day usage.
+ * - ai_settings: a missing row = AI off. `model` is a Workers AI id or a gateway `provider/model`;
+ *   `gateway` an AI Gateway id. CAS on `rev`.
+ * - ai_usage: one row per site and UTC day, bumped by one upsert per command; the daily cap reads it.
+ */
+export const migration0020Ai            = {
+  name: "0020_ai",
+  sql: `
+CREATE TABLE ai_settings (
+  site_id TEXT PRIMARY KEY,
+  enabled INTEGER NOT NULL,
+  model TEXT NOT NULL,
+  gateway TEXT,
+  daily_limit INTEGER NOT NULL,
+  rev INTEGER NOT NULL,
+  updated_at TEXT NOT NULL,
+  updated_by TEXT
+);
+CREATE TABLE ai_usage (
+  site_id TEXT NOT NULL,
+  day TEXT NOT NULL,
+  requests INTEGER NOT NULL,
+  input_tokens INTEGER NOT NULL,
+  output_tokens INTEGER NOT NULL,
+  PRIMARY KEY (site_id, day)
+);
+`,
+};

package/dist/migrations/0021_search.d.ts

@@ -0,0 +1,12 @@
+import type { Migration } from "../src/migrate.js";
+/**
+ * Site search (RFC-0019 §3): an FTS5 index of the published articles, rewritten from the snapshot
+ * a publish or rollback makes live, so it always matches what readers see. `search_state` records
+ * which snapshot the index reflects; a page whose site points elsewhere says "index updating".
+ * Time gates are columns, not filters: an embargoed article is indexed and found only once its
+ * `from` has passed, an expired one only before its `until`.
+ *
+ * `wrangler d1 export` skips virtual tables: a restored backup rebuilds the index on the next
+ * publish or with `cloudhal search reindex`.
+ */
+export declare const migration0021Search: Migration;

package/dist/migrations/0021_search.js

@@ -0,0 +1,29 @@
+                                                   
+
+/**
+ * Site search (RFC-0019 §3): an FTS5 index of the published articles, rewritten from the snapshot
+ * a publish or rollback makes live, so it always matches what readers see. `search_state` records
+ * which snapshot the index reflects; a page whose site points elsewhere says "index updating".
+ * Time gates are columns, not filters: an embargoed article is indexed and found only once its
+ * `from` has passed, an expired one only before its `until`.
+ *
+ * `wrangler d1 export` skips virtual tables: a restored backup rebuilds the index on the next
+ * publish or with `cloudhal search reindex`.
+ */
+export const migration0021Search            = {
+  name: "0021_search",
+  sql: `
+CREATE VIRTUAL TABLE search_index USING fts5(
+  site_id UNINDEXED, node_id UNINDEXED, locale UNINDEXED,
+  title, summary, body,
+  href UNINDEXED, published_at UNINDEXED, gate_from UNINDEXED, gate_until UNINDEXED,
+  tokenize = 'unicode61 remove_diacritics 2'
+);
+CREATE TABLE search_state (
+  site_id TEXT PRIMARY KEY,
+  snapshot_id TEXT NOT NULL,
+  entries INTEGER NOT NULL,
+  updated_at TEXT NOT NULL
+);
+`,
+};

package/dist/migrations/0022_search_kinds.d.ts

@@ -0,0 +1,12 @@
+import type { Migration } from "../src/migrate.js";
+/**
+ * Search kinds (RFC-0029 §2): the index holds pages, terms and authors next to articles. FTS5
+ * tables cannot gain columns, so `search_index` is rebuilt with `kind` and `context`, and
+ * `search_state` is emptied: the next publish, release, import or `cloudhal search reindex`
+ * writes the whole index again.
+ *
+ * `search_links` lists the terms each indexed article carries, with the article's locale and time
+ * gates, so a term or author is found only while its archive lists at least one article the
+ * reader can see (the archive's own 404 rule, RFC-0002 §7).
+ */
+export declare const migration0022SearchKinds: Migration;

package/dist/migrations/0022_search_kinds.js

@@ -0,0 +1,35 @@
+                                                   
+
+/**
+ * Search kinds (RFC-0029 §2): the index holds pages, terms and authors next to articles. FTS5
+ * tables cannot gain columns, so `search_index` is rebuilt with `kind` and `context`, and
+ * `search_state` is emptied: the next publish, release, import or `cloudhal search reindex`
+ * writes the whole index again.
+ *
+ * `search_links` lists the terms each indexed article carries, with the article's locale and time
+ * gates, so a term or author is found only while its archive lists at least one article the
+ * reader can see (the archive's own 404 rule, RFC-0002 §7).
+ */
+export const migration0022SearchKinds            = {
+  name: "0022_search_kinds",
+  sql: `
+DROP TABLE IF EXISTS search_index;
+CREATE VIRTUAL TABLE search_index USING fts5(
+  site_id UNINDEXED, node_id UNINDEXED, locale UNINDEXED, kind UNINDEXED,
+  title, summary, body,
+  href UNINDEXED, context UNINDEXED, published_at UNINDEXED, gate_from UNINDEXED, gate_until UNINDEXED,
+  tokenize = 'unicode61 remove_diacritics 2'
+);
+DELETE FROM search_state;
+CREATE TABLE search_links (
+  site_id TEXT NOT NULL,
+  node_id TEXT NOT NULL,
+  term_id TEXT NOT NULL,
+  locale TEXT NOT NULL,
+  gate_from TEXT,
+  gate_until TEXT
+);
+CREATE INDEX search_links_term ON search_links (site_id, term_id, locale);
+CREATE INDEX search_links_node ON search_links (site_id, node_id);
+`,
+};

package/dist/migrations/0023_search_usage.d.ts

@@ -0,0 +1,7 @@
+import type { Migration } from "../src/migrate.js";
+/**
+ * Semantic search budgets (RFC-0029 §3, Security): calls a site's readers made to the Cloudflare AI
+ * Search provider per UTC day. Past the deployment's daily limit the site answers from FTS5 alone.
+ * One row per site and day; nothing about the reader or the query.
+ */
+export declare const migration0023SearchUsage: Migration;

package/dist/migrations/0023_search_usage.js

@@ -0,0 +1,18 @@
+                                                   
+
+/**
+ * Semantic search budgets (RFC-0029 §3, Security): calls a site's readers made to the Cloudflare AI
+ * Search provider per UTC day. Past the deployment's daily limit the site answers from FTS5 alone.
+ * One row per site and day; nothing about the reader or the query.
+ */
+export const migration0023SearchUsage            = {
+  name: "0023_search_usage",
+  sql: `
+CREATE TABLE search_usage (
+  site_id TEXT NOT NULL,
+  day TEXT NOT NULL,
+  calls INTEGER NOT NULL,
+  PRIMARY KEY (site_id, day)
+);
+`,
+};

package/dist/migrations/0024_search_quota.d.ts

@@ -0,0 +1,8 @@
+import type { Migration } from "../src/migrate.js";
+/**
+ * The semantic search quota (RFC-0029 §3): Cloudflare AI Search includes 1,000 semantic queries a
+ * month per account, so the deployment counts its own calls per UTC month (`2026-11`), not per
+ * site and day (`0023_search_usage`, which this replaces; it never held a call on a live
+ * deployment). Past the limit the site answers from FTS5 until the month ends.
+ */
+export declare const migration0024SearchQuota: Migration;

package/dist/migrations/0024_search_quota.js

@@ -0,0 +1,18 @@
+                                                   
+
+/**
+ * The semantic search quota (RFC-0029 §3): Cloudflare AI Search includes 1,000 semantic queries a
+ * month per account, so the deployment counts its own calls per UTC month (`2026-11`), not per
+ * site and day (`0023_search_usage`, which this replaces; it never held a call on a live
+ * deployment). Past the limit the site answers from FTS5 until the month ends.
+ */
+export const migration0024SearchQuota            = {
+  name: "0024_search_quota",
+  sql: `
+DROP TABLE IF EXISTS search_usage;
+CREATE TABLE search_quota (
+  period TEXT PRIMARY KEY,
+  calls INTEGER NOT NULL
+);
+`,
+};

package/dist/migrations/0025_translation_groups.d.ts

@@ -0,0 +1,7 @@
+import type { Migration } from "../src/migrate.js";
+/**
+ * RFC-0033 invariant 2: a translation group has at most one page (or entry) per locale in a site.
+ * An expression index over the node body backs the store's check against concurrent writes; nodes
+ * without `translation` are left out by the partial `WHERE`.
+ */
+export declare const migration0025TranslationGroups: Migration;

package/dist/migrations/0025_translation_groups.js

@@ -0,0 +1,15 @@
+                                                   
+
+/**
+ * RFC-0033 invariant 2: a translation group has at most one page (or entry) per locale in a site.
+ * An expression index over the node body backs the store's check against concurrent writes; nodes
+ * without `translation` are left out by the partial `WHERE`.
+ */
+export const migration0025TranslationGroups            = {
+  name: "0025_translation_groups",
+  sql: `
+CREATE UNIQUE INDEX nodes_translation_locale ON nodes (
+  site_id, kind, json_extract(body, '$.translation.group'), json_extract(body, '$.locale')
+) WHERE json_extract(body, '$.translation.group') IS NOT NULL;
+`,
+};

package/dist/migrations/0026_search_cjk.d.ts

@@ -0,0 +1,8 @@
+import type { Migration } from "../src/migrate.js";
+/**
+ * RFC-0033 §5: an index for languages written without spaces between words (Chinese, Japanese,
+ * Korean, Thai and their neighbours), with FTS5's `trigram` tokenizer; the columns match
+ * `search_index`. `search_state` is emptied so the next publish, release, import or
+ * `cloudhal search reindex` writes every row again, each into its locale's table.
+ */
+export declare const migration0026SearchCjk: Migration;

package/dist/migrations/0026_search_cjk.js

@@ -0,0 +1,20 @@
+                                                   
+
+/**
+ * RFC-0033 §5: an index for languages written without spaces between words (Chinese, Japanese,
+ * Korean, Thai and their neighbours), with FTS5's `trigram` tokenizer; the columns match
+ * `search_index`. `search_state` is emptied so the next publish, release, import or
+ * `cloudhal search reindex` writes every row again, each into its locale's table.
+ */
+export const migration0026SearchCjk            = {
+  name: "0026_search_cjk",
+  sql: `
+CREATE VIRTUAL TABLE search_index_cjk USING fts5(
+  site_id UNINDEXED, node_id UNINDEXED, locale UNINDEXED, kind UNINDEXED,
+  title, summary, body,
+  href UNINDEXED, context UNINDEXED, published_at UNINDEXED, gate_from UNINDEXED, gate_until UNINDEXED,
+  tokenize = 'trigram'
+);
+DELETE FROM search_state;
+`,
+};

package/dist/migrations/0027_multi_site.d.ts

@@ -0,0 +1,14 @@
+import type { Migration } from "../src/migrate.js";
+/**
+ * RFC-0034 §4: multi-site installations.
+ *
+ * - `site_hosts` maps a hostname to the one site it serves. It is derived from `Site.domains` and
+ *   `Site.localization.domains` and written by the store in the site's own batch. A per-locale
+ *   domain carries its locale.
+ * - `site_workers` lists the site Workers attached to this installation, so a publish purges the
+ *   Worker that serves the site.
+ *
+ * The backfill keeps the earliest site when two sites claim the same hostname (`OR IGNORE`, oldest
+ * first); `cloudhal site list` and the API report the loser as a domain conflict.
+ */
+export declare const migration0027MultiSite: Migration;

package/dist/migrations/0027_multi_site.js

@@ -0,0 +1,44 @@
+                                                   
+
+/**
+ * RFC-0034 §4: multi-site installations.
+ *
+ * - `site_hosts` maps a hostname to the one site it serves. It is derived from `Site.domains` and
+ *   `Site.localization.domains` and written by the store in the site's own batch. A per-locale
+ *   domain carries its locale.
+ * - `site_workers` lists the site Workers attached to this installation, so a publish purges the
+ *   Worker that serves the site.
+ *
+ * The backfill keeps the earliest site when two sites claim the same hostname (`OR IGNORE`, oldest
+ * first); `cloudhal site list` and the API report the loser as a domain conflict.
+ */
+export const migration0027MultiSite            = {
+  name: "0027_multi_site",
+  sql: `
+CREATE TABLE site_hosts (
+  host TEXT PRIMARY KEY,
+  site_id TEXT NOT NULL,
+  locale TEXT,
+  primary_host INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX site_hosts_site ON site_hosts (site_id);
+CREATE TABLE site_workers (
+  name TEXT PRIMARY KEY,
+  url TEXT NOT NULL,
+  theme TEXT NOT NULL,
+  site_ids TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+INSERT OR IGNORE INTO site_hosts (host, site_id, locale, primary_host)
+  SELECT lower(json_extract(d.value, '$.hostname')), n.site_id, NULL,
+         CASE WHEN json_extract(d.value, '$.primary') THEN 1 ELSE 0 END
+  FROM nodes n, json_each(n.body, '$.domains') d
+  WHERE n.kind = 'site' AND json_extract(d.value, '$.hostname') IS NOT NULL
+  ORDER BY n.created_at, n.id;
+INSERT OR IGNORE INTO site_hosts (host, site_id, locale, primary_host)
+  SELECT lower(d.value), n.site_id, d.key, 0
+  FROM nodes n, json_each(n.body, '$.localization.domains') d
+  WHERE n.kind = 'site'
+  ORDER BY n.created_at, n.id;
+`,
+};

package/dist/migrations/0028_site_members.d.ts

@@ -0,0 +1,8 @@
+import type { Migration } from "../src/migrate.js";
+/**
+ * RFC-0034 phase A2 (RFC-0005 open question 10): per-site roles. A row limits an Editor, Author or
+ * Contributor to that site with that role; a member without rows keeps their installation role on
+ * every site. `invitation.sites` carries the assignments (JSON `{siteId: role}`) until the invite
+ * is accepted, when they become rows in the same batch as the membership.
+ */
+export declare const migration0028SiteMembers: Migration;

package/dist/migrations/0028_site_members.js

@@ -0,0 +1,22 @@
+                                                   
+
+/**
+ * RFC-0034 phase A2 (RFC-0005 open question 10): per-site roles. A row limits an Editor, Author or
+ * Contributor to that site with that role; a member without rows keeps their installation role on
+ * every site. `invitation.sites` carries the assignments (JSON `{siteId: role}`) until the invite
+ * is accepted, when they become rows in the same batch as the membership.
+ */
+export const migration0028SiteMembers            = {
+  name: "0028_site_members",
+  sql: `
+CREATE TABLE site_members (
+  site_id TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  role TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (site_id, user_id)
+);
+CREATE INDEX site_members_user ON site_members (user_id);
+ALTER TABLE "invitation" ADD COLUMN "sites" text;
+`,
+};

package/dist/migrations/index.d.ts

@@ -0,0 +1,3 @@
+import type { Migration } from "../src/migrate.js";
+/** All Cloudhal storage migrations, in order. */
+export declare const migrations: readonly Migration[];

package/dist/migrations/index.js

@@ -0,0 +1,61 @@
+                                                   
+import { migration0001Init } from "./0001_init.js";
+import { migration0002Auth } from "./0002_auth.js";
+import { migration0003Agent } from "./0003_agent.js";
+import { migration0004AuditActorName } from "./0004_audit_actor_name.js";
+import { migration0005AuthRateLimit } from "./0005_auth_rate_limit.js";
+import { migration0006Approvals } from "./0006_approvals.js";
+import { migration0007AuditMode } from "./0007_audit_mode.js";
+import { migration0008PolicyDetail } from "./0008_policy_detail.js";
+import { migration0009AuditElevation } from "./0009_audit_elevation.js";
+import { migration0010ApprovalResult } from "./0010_approval_result.js";
+import { migration0011OpGuards } from "./0011_op_guards.js";
+import { migration0012Roles } from "./0012_roles.js";
+import { migration0013Media } from "./0013_media.js";
+import { migration0014Analytics } from "./0014_analytics.js";
+import { migration0015AnalyticsPrivacySignal } from "./0015_analytics_privacy_signal.js";
+import { migration0016Comments } from "./0016_comments.js";
+import { migration0017Schedules } from "./0017_schedules.js";
+import { migration0018QueryIndexes } from "./0018_query_indexes.js";
+import { migration0019BodyProposals } from "./0019_body_proposals.js";
+import { migration0020Ai } from "./0020_ai.js";
+import { migration0021Search } from "./0021_search.js";
+import { migration0022SearchKinds } from "./0022_search_kinds.js";
+import { migration0023SearchUsage } from "./0023_search_usage.js";
+import { migration0024SearchQuota } from "./0024_search_quota.js";
+import { migration0025TranslationGroups } from "./0025_translation_groups.js";
+import { migration0026SearchCjk } from "./0026_search_cjk.js";
+import { migration0027MultiSite } from "./0027_multi_site.js";
+import { migration0028SiteMembers } from "./0028_site_members.js";
+
+/** All Cloudhal storage migrations, in order. */
+export const migrations                       = [
+  migration0001Init,
+  migration0002Auth,
+  migration0003Agent,
+  migration0004AuditActorName,
+  migration0005AuthRateLimit,
+  migration0006Approvals,
+  migration0007AuditMode,
+  migration0008PolicyDetail,
+  migration0009AuditElevation,
+  migration0010ApprovalResult,
+  migration0011OpGuards,
+  migration0012Roles,
+  migration0013Media,
+  migration0014Analytics,
+  migration0015AnalyticsPrivacySignal,
+  migration0016Comments,
+  migration0017Schedules,
+  migration0018QueryIndexes,
+  migration0019BodyProposals,
+  migration0020Ai,
+  migration0021Search,
+  migration0022SearchKinds,
+  migration0023SearchUsage,
+  migration0024SearchQuota,
+  migration0025TranslationGroups,
+  migration0026SearchCjk,
+  migration0027MultiSite,
+  migration0028SiteMembers,
+];

package/dist/src/blob/fs.d.ts

@@ -0,0 +1,19 @@
+import { type BlobMeta, type BlobPutOptions, type BlobRange, type BlobStore, type BlobStream } from "../types.js";
+/** Filesystem blob store: keys map to files under a root directory (self-host / local dev). */
+export declare class FsBlobStore implements BlobStore {
+    #private;
+    readonly name = "fs";
+    constructor(rootDir: string);
+    get(key: string): Promise<Uint8Array | null>;
+    head(key: string): Promise<BlobMeta | null>;
+    put(key: string, data: Uint8Array, options?: BlobPutOptions): Promise<void>;
+    putStream(key: string, data: ReadableStream<Uint8Array>, options: BlobPutOptions & {
+        size: number;
+        sha256: string;
+    }): Promise<void>;
+    getStream(key: string, options?: {
+        range?: BlobRange;
+    }): Promise<BlobStream | null>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+}

package/dist/src/blob/fs.js

@@ -0,0 +1,172 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import {
+  assertBlobKey,
+  BlobIntegrityError,
+                
+                      
+                 
+                 
+                  
+  resolveBlobRange,
+  SHA256_HEX,
+  StorageError,
+  verifyBlob,
+} from "../types.js";
+
+/** Uploads stream here first and are renamed into place once verified (same filesystem). */
+const TMP_DIR = ".tmp";
+
+/** Filesystem blob store: keys map to files under a root directory (self-host / local dev). */
+export class FsBlobStore                      {
+           name = "fs";
+           #root        ;
+
+  constructor(rootDir        ) {
+    this.#root = path.resolve(rootDir);
+  }
+
+  #pathFor(key        )         {
+    assertBlobKey(key);
+    if (key === TMP_DIR || key.startsWith(`${TMP_DIR}/`))
+      throw new StorageError(`invalid blob key "${key}"`);
+    const file = path.resolve(this.#root, ...key.split("/"));
+    // Containment: whatever the key, the file stays under the root (RFC-0004 §4.1).
+    if (!file.startsWith(`${this.#root}${path.sep}`))
+      throw new StorageError(`invalid blob key "${key}"`);
+    return file;
+  }
+
+  async get(key        )                             {
+    try {
+      return new Uint8Array(await readFile(this.#pathFor(key)));
+    } catch (e) {
+      if ((e                         ).code === "ENOENT") return null;
+      throw e;
+    }
+  }
+
+  async head(key        )                           {
+    try {
+      const s = await stat(this.#pathFor(key));
+      return s.isFile() ? { size: s.size } : null;
+    } catch (e) {
+      if ((e                         ).code === "ENOENT") return null;
+      throw e;
+    }
+  }
+
+  async #tmpFile()                  {
+    const dir = path.join(this.#root, TMP_DIR);
+    await mkdir(dir, { recursive: true });
+    return path.join(dir, randomUUID());
+  }
+
+  /** Writes to a temporary file and renames it into place (atomic on one filesystem). */
+  async #commit(file        , tmp        )                {
+    await mkdir(path.dirname(file), { recursive: true });
+    await rename(tmp, file);
+  }
+
+  async put(key        , data            , options                 = {})                {
+    const file = this.#pathFor(key);
+    if (options.sha256 !== undefined) await verifyBlob(data, options.sha256);
+    const tmp = await this.#tmpFile();
+    try {
+      await writeFile(tmp, data);
+      await this.#commit(file, tmp);
+    } catch (e) {
+      await rm(tmp, { force: true });
+      throw e;
+    }
+  }
+
+  async putStream(
+    key        ,
+    data                            ,
+    options                                                   ,
+  )                {
+    const file = this.#pathFor(key);
+    if (!SHA256_HEX.test(options.sha256))
+      throw new BlobIntegrityError("sha256 must be 64 lower-case hex");
+    const tmp = await this.#tmpFile();
+    const hash = createHash("sha256");
+    const out = createWriteStream(tmp, { flags: "wx" });
+    let total = 0;
+    try {
+      const reader = data.getReader();
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > options.size) {
+          await reader.cancel().catch(() => {});
+          throw new BlobIntegrityError(`stream is longer than ${options.size} bytes`);
+        }
+        hash.update(value);
+        if (!out.write(value)) await new Promise      ((r) => out.once("drain", () => r()));
+      }
+      await new Promise      ((resolve, reject) =>
+        out.end((err               ) => (err ? reject(err) : resolve())),
+      );
+      if (total !== options.size)
+        throw new BlobIntegrityError(`expected ${options.size} bytes, got ${total}`);
+      if (hash.digest("hex") !== options.sha256)
+        throw new BlobIntegrityError("data does not match the declared sha256");
+      await this.#commit(file, tmp);
+    } catch (e) {
+      out.destroy();
+      await rm(tmp, { force: true });
+      throw e;
+    }
+  }
+
+  async getStream(key        , options                        = {})                             {
+    const file = this.#pathFor(key);
+    let size        ;
+    try {
+      const s = await stat(file);
+      if (!s.isFile()) return null;
+      size = s.size;
+    } catch (e) {
+      if ((e                         ).code === "ENOENT") return null;
+      throw e;
+    }
+    const range = options.range ? resolveBlobRange(options.range, size) : undefined;
+    if (options.range && !range) throw new StorageError("range not satisfiable");
+    const stream = createReadStream(
+      file,
+      range ? { start: range.offset, end: range.offset + range.length - 1 } : {},
+    );
+    const body = Readable.toWeb(stream)                                         ;
+    return range ? { body, size, range } : { body, size };
+  }
+
+  async delete(key        )                {
+    await rm(this.#pathFor(key), { force: true });
+  }
+
+  async list(prefix = "")                    {
+    const out           = [];
+    const walk = async (dir        , rel        )                => {
+      let entries                            ;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch (e) {
+        if ((e                         ).code === "ENOENT") return;
+        throw e;
+      }
+      for (const entry of entries) {
+        if (!rel && entry.name === TMP_DIR) continue;
+        const key = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) await walk(path.join(dir, entry.name), key);
+        else if (entry.isFile() && key.startsWith(prefix)) out.push(key);
+      }
+    };
+    await walk(this.#root, "");
+    return out.sort();
+  }
+}