sproutboat 0.4.4 → 0.4.6

package/SURFACE.md

@@ -3,7 +3,7 @@
 > Generated by `src/surface.test.ts` from `src/surface.ts` + the pinned
 > toolchain constants. Do not edit by hand — run `UPDATE_SURFACE=1 bun test`.
 
-**Package:** `sproutboat` 0.4.4 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.4.6 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -18,11 +18,12 @@
 | `tail` | `[project-dir] [--sprout]` | Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead. |
 | `domains` | `[list | add <host> | verify <host> | rm <host>] [project-dir]` | Attach a custom domain to the project (TXT-verified). No sub-command lists. |
 | `secrets` | `[list | set <NAME> [value] | rm <NAME>] [project-dir]` | Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy. |
+| `resource` | `[list [kind] | create <kind> <name> | rename <id> <name> | delete <id>]` | Manage account-level storage resources (kv | d1 | r2 | queue). `create` prints the id to reference from sproutboat.jsonc bindings. |
 | `delete` | `[project-dir] [--name <project>] --yes` | Delete the project, every version, and its route. |
 | `login` | `[--api-url <url>] [--token <token>]` | Device-code browser flow, or store <token> for <url> directly. |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] | versions list [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | domains [list | add <host> | verify <host> | rm <host>] [project-dir] | secrets [list | set <NAME> [value] | rm <NAME>] [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>]>
+usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] | versions list [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | domains [list | add <host> | verify <host> | rm <host>] [project-dir] | secrets [list | set <NAME> [value] | rm <NAME>] [project-dir] | resource [list [kind] | create <kind> <name> | rename <id> <name> | delete <id>] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>]>
 ```
 
 ## Environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "license": "MIT",
   "type": "module",

package/src/broker.ts

@@ -17,7 +17,7 @@
  * re-validation and private-IP blocking are v2 — the exact-host allowlist is
  * the only SSRF control today.
  */
-import { Database } from "bun:sqlite";
+import { Database, type Statement } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join, normalize, resolve } from "node:path";
@@ -36,6 +36,13 @@ export type Bindings = {
   crons: string[];
   /** Static-asset binding name, or `""` when assets are edge-only. */
   assets: string;
+  /**
+   * #74 — binding name -> account-level resource it resolves to. A binding with
+   * an entry here stores in a per-resource SQLite file under `resourceDir`,
+   * keyed by `id`, shared across this owner's deployments; a binding without one
+   * falls back to the per-broker `db` partitioned by its own name (local dev).
+   */
+  resources: Record<string, { kind: "kv" | "d1" | "r2" | "queue"; id: string }>;
 };
 export type Frame = Record<string, unknown>;
 
@@ -43,6 +50,13 @@ export type BrokerOptions = {
   db?: string;
   /** Directory for per-D1-binding SQLite files. Defaults to `<dirname(db)>/d1`, or in-memory when `db` is `:memory:`. */
   dataDir?: string;
+  /**
+   * #74 — directory holding one `<resource-id>.sqlite` per account-level KV / R2 /
+   * queue / D1 resource. Defaults to `<dirname(db)>/resources`, in-memory when
+   * `db` is `:memory:`. The supervisor points this at an owner-stable path so the
+   * data outlives a redeploy.
+   */
+  resourceDir?: string;
   token?: string;
   bindings?: Partial<Bindings>;
   secrets?: Record<string, string>;
@@ -80,7 +94,7 @@ export type Broker = {
 };
 
 export function createBroker(opts: BrokerOptions = {}): Broker {
-  const bindings: Bindings = { kv: [], secrets: [], outbound: [], d1: [], r2: [], queues: [], analytics: [], do: [], crons: [], assets: "", ...opts.bindings };
+  const bindings: Bindings = { kv: [], secrets: [], outbound: [], d1: [], r2: [], queues: [], analytics: [], do: [], crons: [], assets: "", resources: {}, ...opts.bindings };
   const secrets = opts.secrets ?? {};
 
   // Static assets: read the manifest once. Files are read from disk per request
@@ -106,24 +120,32 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   const dbPath = opts.db ?? ":memory:";
   const inMemory = dbPath === ":memory:" || dbPath === "";
   const d1Dir = opts.dataDir ?? (inMemory ? null : join(dirname(resolve(dbPath)), "d1"));
+  const resourceDir = opts.resourceDir ?? (inMemory ? null : join(dirname(resolve(dbPath)), "resources"));
 
-  const db = new Database(dbPath);
-  db.exec("PRAGMA journal_mode = WAL");
   // WAL + NORMAL is the standard pairing: a write no longer fsyncs the WAL, so
   // host power loss can drop the last few committed txns, but a process crash
   // never can and the file never corrupts. Right trade for a single-VPS
   // KV/queue/DO store; on real block storage this is ~10-100x on writes.
-  db.exec("PRAGMA synchronous = NORMAL");
-  db.exec("CREATE TABLE IF NOT EXISTS kv (ns TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (ns, key))");
-  db.exec(
-    "CREATE TABLE IF NOT EXISTS r2 (bucket TEXT NOT NULL, key TEXT NOT NULL, body TEXT NOT NULL, size INTEGER NOT NULL, " +
-      "etag TEXT NOT NULL, uploaded TEXT NOT NULL, http_json TEXT NOT NULL DEFAULT '{}', custom_json TEXT NOT NULL DEFAULT '{}', " +
-      "PRIMARY KEY (bucket, key))",
-  );
-  db.exec(
-    "CREATE TABLE IF NOT EXISTS mq (queue TEXT NOT NULL, id TEXT PRIMARY KEY, body TEXT NOT NULL, " +
-      "visible_at INTEGER NOT NULL, attempts INTEGER NOT NULL DEFAULT 0, dead INTEGER NOT NULL DEFAULT 0)",
-  );
+  const openStore = (path: string): Database => {
+    const conn = new Database(path, { create: true });
+    conn.exec("PRAGMA journal_mode = WAL");
+    conn.exec("PRAGMA synchronous = NORMAL");
+    conn.exec("CREATE TABLE IF NOT EXISTS kv (ns TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, PRIMARY KEY (ns, key))");
+    conn.exec(
+      "CREATE TABLE IF NOT EXISTS r2 (bucket TEXT NOT NULL, key TEXT NOT NULL, body TEXT NOT NULL, size INTEGER NOT NULL, " +
+        "etag TEXT NOT NULL, uploaded TEXT NOT NULL, http_json TEXT NOT NULL DEFAULT '{}', custom_json TEXT NOT NULL DEFAULT '{}', " +
+        "PRIMARY KEY (bucket, key))",
+    );
+    conn.exec(
+      "CREATE TABLE IF NOT EXISTS mq (queue TEXT NOT NULL, id TEXT PRIMARY KEY, body TEXT NOT NULL, " +
+        "visible_at INTEGER NOT NULL, attempts INTEGER NOT NULL DEFAULT 0, dead INTEGER NOT NULL DEFAULT 0)",
+    );
+    return conn;
+  };
+
+  const db = openStore(dbPath);
+  // Durable Object storage and Analytics Engine rows stay in the per-broker db —
+  // neither is an account-level resource (#74).
   db.exec(
     "CREATE TABLE IF NOT EXISTS do_storage (cls TEXT NOT NULL, id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL, " +
       "PRIMARY KEY (cls, id, key))",
@@ -132,10 +154,51 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     "CREATE TABLE IF NOT EXISTS ae (dataset TEXT NOT NULL, ts INTEGER NOT NULL, indexes_json TEXT NOT NULL, " +
       "blobs_json TEXT NOT NULL, doubles_json TEXT NOT NULL)",
   );
-  const kvGet = db.query<{ value: string }, [string, string]>("SELECT value FROM kv WHERE ns = ? AND key = ?");
-  const kvPut = db.query("INSERT INTO kv (ns, key, value) VALUES (?1, ?2, ?3) ON CONFLICT (ns, key) DO UPDATE SET value = ?3");
-  const kvDel = db.query("DELETE FROM kv WHERE ns = ? AND key = ?");
-  const kvList = db.query<{ key: string }, [string, string]>("SELECT key FROM kv WHERE ns = ? AND key LIKE ? || '%' ORDER BY key LIMIT 1000");
+
+  // #74 — one SQLite file per account-level resource id, opened on first use.
+  const resourceDbs = new Map<string, Database>();
+  const resourceDb = (id: string): Database => {
+    let conn = resourceDbs.get(id);
+    if (!conn) {
+      if (resourceDir) mkdirSync(resourceDir, { recursive: true });
+      conn = openStore(resourceDir ? join(resourceDir, `${id}.sqlite`) : ":memory:");
+      resourceDbs.set(id, conn);
+    }
+    return conn;
+  };
+
+  /**
+   * Where a KV / R2 / queue binding stores: its resource's own file keyed by
+   * `id` when the config bound it to one, else the per-broker `db` partitioned
+   * by the binding name (bare-string bindings / local dev).
+   */
+  const storeFor = (kind: "kv" | "r2" | "queue", binding: string): { store: Database; part: string } => {
+    const resource = bindings.resources[binding];
+    return resource && resource.kind === kind
+      ? { store: resourceDb(resource.id), part: resource.id }
+      : { store: db, part: binding };
+  };
+
+  type KvStmts = {
+    get: Statement<{ value: string }, [string, string]>;
+    put: Statement<unknown, [string, string, string]>;
+    del: Statement<unknown, [string, string]>;
+    list: Statement<{ key: string }, [string, string]>;
+  };
+  const kvStmtCache = new Map<Database, KvStmts>();
+  const kvStmts = (store: Database): KvStmts => {
+    let stmts = kvStmtCache.get(store);
+    if (!stmts) {
+      stmts = {
+        get: store.query<{ value: string }, [string, string]>("SELECT value FROM kv WHERE ns = ? AND key = ?"),
+        put: store.query("INSERT INTO kv (ns, key, value) VALUES (?1, ?2, ?3) ON CONFLICT (ns, key) DO UPDATE SET value = ?3"),
+        del: store.query("DELETE FROM kv WHERE ns = ? AND key = ?"),
+        list: store.query<{ key: string }, [string, string]>("SELECT key FROM kv WHERE ns = ? AND key LIKE ? || '%' ORDER BY key LIMIT 1000"),
+      };
+      kvStmtCache.set(store, stmts);
+    }
+    return stmts;
+  };
 
   const bound = (list: string[], kind: string) => (name: unknown): string => {
     const n = str(name);
@@ -155,16 +218,22 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   };
   const newId = () => createHash("sha256").update(`${Date.now()}:${Math.random()}`).digest("hex").slice(0, 24);
 
-  // One SQLite database per bound D1 name — they are independent SQL namespaces.
+  // One SQLite database per bound D1 binding — independent SQL namespaces. A
+  // binding wired to an account-level resource (#74) opens `<resource-id>.sqlite`
+  // under `resourceDir` (survives redeploys); a bare-string binding keeps its
+  // per-broker `<name>.sqlite` under `d1Dir`.
   const d1Conns = new Map<string, Database>();
   const d1 = (name: string): Database => {
-    let conn = d1Conns.get(name);
+    const resource = bindings.resources[name];
+    const key = resource && resource.kind === "d1" ? resource.id : name;
+    let conn = d1Conns.get(key);
     if (!conn) {
-      if (d1Dir) mkdirSync(d1Dir, { recursive: true });
-      conn = new Database(d1Dir ? join(d1Dir, `${name}.sqlite`) : ":memory:", { create: true });
+      const dir = resource && resource.kind === "d1" ? resourceDir : d1Dir;
+      if (dir) mkdirSync(dir, { recursive: true });
+      conn = new Database(dir ? join(dir, `${key}.sqlite`) : ":memory:", { create: true });
       conn.exec("PRAGMA journal_mode = WAL");
       conn.exec("PRAGMA synchronous = NORMAL");
-      d1Conns.set(name, conn);
+      d1Conns.set(key, conn);
     }
     return conn;
   };
@@ -224,17 +293,24 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       case "ping":
         return { ok: true, op: "pong", echo: msg.msg ?? null, pid: process.pid };
       case "kv.get": {
-        const row = kvGet.get(requireKv(msg.ns), str(msg.key));
+        const { store, part } = storeFor("kv", requireKv(msg.ns));
+        const row = kvStmts(store).get.get(part, str(msg.key));
         return row ? { ok: true, found: true, value: row.value } : { ok: true, found: false, value: null };
       }
-      case "kv.put":
-        kvPut.run(requireKv(msg.ns), str(msg.key), str(msg.value));
+      case "kv.put": {
+        const { store, part } = storeFor("kv", requireKv(msg.ns));
+        kvStmts(store).put.run(part, str(msg.key), str(msg.value));
         return { ok: true };
-      case "kv.delete":
-        kvDel.run(requireKv(msg.ns), str(msg.key));
+      }
+      case "kv.delete": {
+        const { store, part } = storeFor("kv", requireKv(msg.ns));
+        kvStmts(store).del.run(part, str(msg.key));
         return { ok: true };
-      case "kv.list":
-        return { ok: true, keys: kvList.all(requireKv(msg.ns), str(msg.prefix)).map((r) => r.key) };
+      }
+      case "kv.list": {
+        const { store, part } = storeFor("kv", requireKv(msg.ns));
+        return { ok: true, keys: kvStmts(store).list.all(part, str(msg.prefix)).map((r) => r.key) };
+      }
       case "secret.get": {
         const name = str(msg.name);
         if (!bindings.secrets.includes(name)) throw new Error(`secret not bound: ${name}`);
@@ -261,10 +337,10 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       }
 
       case "r2.put": {
-        const bucket = requireR2(msg.bucket);
+        const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
         const body = str(msg.body);
         const etag = createHash("sha256").update(body).digest("hex");
-        db.query(
+        store.query(
           "INSERT INTO r2 (bucket, key, body, size, etag, uploaded, http_json, custom_json) VALUES (?1,?2,?3,?4,?5,?6,?7,?8) " +
             "ON CONFLICT (bucket, key) DO UPDATE SET body=?3, size=?4, etag=?5, uploaded=?6, http_json=?7, custom_json=?8",
         ).run(
@@ -281,22 +357,22 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       }
       case "r2.get":
       case "r2.head": {
-        const bucket = requireR2(msg.bucket);
-        const row = db.query<R2Row, [string, string]>("SELECT * FROM r2 WHERE bucket = ? AND key = ?").get(bucket, str(msg.key));
+        const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
+        const row = store.query<R2Row, [string, string]>("SELECT * FROM r2 WHERE bucket = ? AND key = ?").get(bucket, str(msg.key));
         if (!row) return { ok: true, found: false };
         return { ok: true, found: true, object: r2Row(row), body: msg.op === "r2.get" ? row.body : undefined };
       }
       case "r2.delete": {
-        const bucket = requireR2(msg.bucket);
-        db.query("DELETE FROM r2 WHERE bucket = ? AND key = ?").run(bucket, str(msg.key));
+        const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
+        store.query("DELETE FROM r2 WHERE bucket = ? AND key = ?").run(bucket, str(msg.key));
         return { ok: true };
       }
       case "r2.list": {
-        const bucket = requireR2(msg.bucket);
+        const { store, part: bucket } = storeFor("r2", requireR2(msg.bucket));
         const prefix = str(msg.prefix);
         const cursor = str(msg.cursor);
         const limit = Math.min(Math.max(Number(msg.limit) || 1000, 1), 1000);
-        const rows = db.query<R2Row, [string, string, string, number]>(
+        const rows = store.query<R2Row, [string, string, string, number]>(
           "SELECT * FROM r2 WHERE bucket = ? AND key LIKE ? || '%' AND key > ? ORDER BY key LIMIT ?",
         ).all(bucket, prefix, cursor, limit + 1);
         const truncated = rows.length > limit;
@@ -310,16 +386,16 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
       }
 
       case "queue.send": {
-        const q = requireQueue(msg.queue);
+        const { store, part: q } = storeFor("queue", requireQueue(msg.queue));
         const at = Date.now() + Math.max(0, Number(msg.delaySeconds) || 0) * 1000;
-        db.query("INSERT INTO mq (queue, id, body, visible_at) VALUES (?, ?, ?, ?)").run(q, newId(), str(msg.body), at);
+        store.query("INSERT INTO mq (queue, id, body, visible_at) VALUES (?, ?, ?, ?)").run(q, newId(), str(msg.body), at);
         return { ok: true };
       }
       case "queue.send_batch": {
-        const q = requireQueue(msg.queue);
+        const { store, part: q } = storeFor("queue", requireQueue(msg.queue));
         const msgs = Array.isArray(msg.messages) ? (msg.messages as Frame[]) : [];
-        const ins = db.query("INSERT INTO mq (queue, id, body, visible_at) VALUES (?, ?, ?, ?)");
-        db.transaction(() => {
+        const ins = store.query("INSERT INTO mq (queue, id, body, visible_at) VALUES (?, ?, ?, ?)");
+        store.transaction(() => {
           for (const m of msgs) ins.run(q, newId(), str(m.body), Date.now() + Math.max(0, Number(m.delaySeconds) || 0) * 1000);
         })();
         return { ok: true, count: msgs.length };
@@ -444,18 +520,21 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
   function drainQueuesOnce(): void {
     if (!opts.sproutUrl || bindings.queues.length === 0) return;
     const now = Date.now();
-    for (const q of bindings.queues) {
-      const rows = db.query<{ id: string; body: string; attempts: number }, [string, number, number]>(
+    for (const binding of bindings.queues) {
+      // `store`/`part` route the rows to this queue's backing file (#74); the
+      // trigger payload still carries the binding name the sprout matches on.
+      const { store, part } = storeFor("queue", binding);
+      const rows = store.query<{ id: string; body: string; attempts: number }, [string, number, number]>(
         "SELECT id, body, attempts FROM mq WHERE queue = ? AND dead = 0 AND visible_at <= ? ORDER BY visible_at LIMIT ?",
-      ).all(q, now, QUEUE_BATCH);
+      ).all(part, now, QUEUE_BATCH);
       if (rows.length === 0) continue;
       // hide the batch so the next tick doesn't re-deliver it while in flight
       const hideUntil = now + 30_000;
-      const hide = db.query("UPDATE mq SET visible_at = ? WHERE id = ?");
+      const hide = store.query("UPDATE mq SET visible_at = ? WHERE id = ?");
       for (const r of rows) hide.run(hideUntil, r.id);
 
       void deliverTrigger("queue", {
-        queue: q,
+        queue: binding,
         messages: rows.map((r) => ({ id: r.id, body: r.body, timestamp: now, attempts: r.attempts + 1 })),
       }).then(async (res) => {
         let ack: string[] = rows.map((r) => r.id); // default: ack all if the sprout did not say
@@ -469,9 +548,9 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
         } else {
           ack = []; retry = rows.map((r) => r.id); // delivery failed → retry all
         }
-        const del = db.query("DELETE FROM mq WHERE id = ?");
+        const del = store.query("DELETE FROM mq WHERE id = ?");
         for (const id of ack) del.run(id);
-        const bump = db.query(
+        const bump = store.query(
           "UPDATE mq SET attempts = attempts + 1, visible_at = ?, dead = CASE WHEN attempts + 1 >= ? THEN 1 ELSE 0 END WHERE id = ?",
         );
         for (const id of retry) bump.run(Date.now() + 5_000, QUEUE_MAX_ATTEMPTS, id);
@@ -501,6 +580,7 @@ export function createBroker(opts: BrokerOptions = {}): Broker {
     close: () => {
       for (const t of timers) clearInterval(t);
       for (const conn of d1Conns.values()) conn.close();
+      for (const conn of resourceDbs.values()) conn.close();
       db.close();
     },
   };
@@ -572,6 +652,7 @@ if (import.meta.main) {
       token: { type: "string" },
       db: { type: "string" },
       "data-dir": { type: "string" },
+      "resource-dir": { type: "string" },
       bindings: { type: "string" },
       secrets: { type: "string" },
       "sprout-url": { type: "string" },
@@ -587,6 +668,7 @@ if (import.meta.main) {
   const broker = createBroker({
     db: values.db,
     dataDir: values["data-dir"],
+    resourceDir: values["resource-dir"],
     token: values.token ?? process.env.SB_BROKER_TOKEN,
     bindings,
     secrets,

package/src/build.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { walkAssets, type AssetManifest } from "./assets";
-import type { SproutboatConfig } from "./config";
+import { resourceRefs, type SproutboatConfig } from "./config";
 import { compileSprout } from "./compile";
 import { ARTIFACT_SCHEMA_VERSION, CAPABILITY_PROFILE, RUNTIME, type ArtifactManifest } from "./manifest";
 import { ensureZig, esbuildVersion, porfforVersion, toolchainStamp } from "./toolchain";
@@ -36,17 +36,31 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
   const sproutPath = resolve(artifactDir, "sprout");
   await mkdir(artifactDir, { recursive: true });
 
+  // #74 — split each storage-binding array into its binding-name list (the
+  // legacy shape the prelude/broker read) plus a `resources` map { binding ->
+  // { kind, id } } for the entries that name an account-level resource id.
+  const refsByKind = {
+    kv: resourceRefs(input.config.kv_namespaces),
+    d1: resourceRefs(input.config.d1_databases),
+    r2: resourceRefs(input.config.r2_buckets),
+    queue: resourceRefs(input.config.queues),
+  };
+  const resources: Record<string, { kind: string; id: string }> = {};
+  for (const [kind, refs] of Object.entries(refsByKind)) {
+    for (const ref of refs) if (ref.id) resources[ref.binding] = { kind, id: ref.id };
+  }
   const bindings = {
-    kv: input.config.kv_namespaces ?? [],
+    kv: refsByKind.kv.map((ref) => ref.binding),
     secrets: input.config.secrets ?? [],
     outbound: input.config.outbound ?? [],
-    d1: input.config.d1_databases ?? [],
-    r2: input.config.r2_buckets ?? [],
-    queues: input.config.queues ?? [],
+    d1: refsByKind.d1.map((ref) => ref.binding),
+    r2: refsByKind.r2.map((ref) => ref.binding),
+    queues: refsByKind.queue.map((ref) => ref.binding),
     analytics: input.config.analytics_engine_datasets ?? [],
     do: Object.entries(input.config.durable_objects ?? {}).map(([binding, className]) => ({ binding, className })),
     crons: input.config.triggers?.crons ?? [],
     assets: input.config.assets?.binding ?? "",
+    resources,
   };
 
   const zigBin = await ensureZig();
@@ -78,7 +92,9 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
   // frozen at v2. The control plane reads this to configure the per-deployment
   // broker (KV / D1 / R2 / queue names, secret names, outbound allowlist, cron
   // schedules, Durable Object classes).
-  if (Object.values(bindings).some((names) => names.length > 0)) {
+  const hasBindings = Object.values(bindings).some((value) => Array.isArray(value) && value.length > 0)
+    || Object.keys(bindings.resources).length > 0;
+  if (hasBindings) {
     await writeFile(resolve(artifactDir, "bindings.json"), `${JSON.stringify(bindings, null, 2)}\n`);
   }
 

package/src/config.ts

@@ -1,24 +1,38 @@
 const slugPattern = /^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])?$/;
 
+/**
+ * A storage binding entry (#74). Either a bare `"BINDING"` — resolved to an
+ * ephemeral local resource for `sproutboat dev`, rejected by a real deploy — or
+ * `{ binding, id }` pointing at an account-level resource created with
+ * `sproutboat resource create`. The id carries its own `<kind>_` prefix.
+ */
+export type ResourceBinding = { binding: string; id: string };
+export type ResourceRef = string | ResourceBinding;
+
+/** Normalizes a storage-binding array to `{ binding, id? }` rows. */
+export function resourceRefs(field: readonly ResourceRef[] | undefined): Array<{ binding: string; id?: string }> {
+  return (field ?? []).map((entry) => (isString(entry) ? { binding: entry } : { binding: entry.binding, id: entry.id }));
+}
+
 export type SproutboatConfig = {
   $schema?: string;
   name: string;
   main: string;
   compatibility_date: string;
   vars?: Record<string, string>;
-  /** KV namespace binding names, exposed as `env.<NAME>`. */
-  kv_namespaces?: string[];
+  /** KV namespace bindings, exposed as `env.<NAME>`. */
+  kv_namespaces?: ResourceRef[];
   /** Secret binding names, exposed as `env.<NAME>` (value fetched at use). */
   secrets?: string[];
   /** Hostnames the sprout's `fetch()` may reach (exact host match). */
   outbound?: string[];
-  /** D1 (SQLite) database binding names, exposed as `env.<NAME>`. */
-  d1_databases?: string[];
-  /** R2 (object storage) bucket binding names, exposed as `env.<NAME>`. */
-  r2_buckets?: string[];
-  /** Queue producer binding names, exposed as `env.<NAME>.send()`. A `queue(batch)` handler consumes them. */
-  queues?: string[];
-  /** Analytics Engine dataset binding names, exposed as `env.<NAME>.writeDataPoint()`. */
+  /** D1 (SQLite) database bindings, exposed as `env.<NAME>`. */
+  d1_databases?: ResourceRef[];
+  /** R2 (object storage) bucket bindings, exposed as `env.<NAME>`. */
+  r2_buckets?: ResourceRef[];
+  /** Queue producer bindings, exposed as `env.<NAME>.send()`. A `queue(batch)` handler consumes them. */
+  queues?: ResourceRef[];
+  /** Analytics Engine dataset binding names, exposed as `env.<NAME>.writeDataPoint()`. No id — the dataset is created on first write. */
   analytics_engine_datasets?: string[];
   /** Durable Object bindings: `{ BINDING_NAME: "ClassName" }`. The class is defined in the handler module. */
   durable_objects?: Record<string, string>;
@@ -101,7 +115,7 @@ function validateConfig(value: ConfigInput): ConfigValidation {
   const bindingName = /^[A-Z][A-Z0-9_]*$/;
   const hostPattern = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
   const stringArray = (
-    field: "kv_namespaces" | "secrets" | "outbound" | "d1_databases" | "r2_buckets" | "queues" | "analytics_engine_datasets",
+    field: "secrets" | "outbound" | "analytics_engine_datasets",
     item: RegExp,
     label: string,
   ): string[] | undefined => {
@@ -118,13 +132,48 @@ function validateConfig(value: ConfigInput): ConfigValidation {
     }
     return out;
   };
-  const kv_namespaces = stringArray("kv_namespaces", bindingName, "binding names (UPPER_SNAKE_CASE)");
+
+  /**
+   * A storage-binding array (#74): each entry is a bare `"BINDING"` or
+   * `{ binding: "BINDING", id: "<kind>_<24hex>" }`. `kind` is the field's own
+   * resource kind, so an r2 id can't be pasted into `kv_namespaces`.
+   */
+  const resourceArray = (
+    field: "kv_namespaces" | "d1_databases" | "r2_buckets" | "queues",
+    kind: string,
+  ): ResourceRef[] | undefined => {
+    if (value[field] === undefined) return undefined;
+    const raw = value[field];
+    if (!Array.isArray(raw)) {
+      errors.push(`${field} must be an array of binding names or { binding, id } objects`);
+      return undefined;
+    }
+    const idPattern = new RegExp(`^${kind}_[0-9a-f]{24}$`);
+    const out: ResourceRef[] = [];
+    for (const entry of raw) {
+      if (isString(entry)) {
+        if (bindingName.test(entry)) out.push(entry);
+        else errors.push(`${field}: "${entry}" must be an UPPER_SNAKE binding name`);
+      } else if (isRecord(entry) && isString(entry.binding) && isString(entry.id)
+        && bindingName.test(entry.binding) && idPattern.test(entry.id)
+        && Object.keys(entry).every((key) => key === "binding" || key === "id")) {
+        out.push({ binding: entry.binding, id: entry.id });
+      } else {
+        errors.push(`${field} entries must be an UPPER_SNAKE name or { binding: "NAME", id: "${kind}_…" }`);
+      }
+    }
+    return out;
+  };
+
   const secrets = stringArray("secrets", bindingName, "binding names (UPPER_SNAKE_CASE)");
   const outbound = stringArray("outbound", hostPattern, "hostnames");
-  const d1_databases = stringArray("d1_databases", bindingName, "binding names (UPPER_SNAKE_CASE)");
-  const r2_buckets = stringArray("r2_buckets", bindingName, "binding names (UPPER_SNAKE_CASE)");
-  const queues = stringArray("queues", bindingName, "binding names (UPPER_SNAKE_CASE)");
+  // Analytics Engine datasets aren't provisioned — the dataset name springs into
+  // existence on first writeDataPoint(), so there's no resource id to bind (#74).
   const analytics_engine_datasets = stringArray("analytics_engine_datasets", bindingName, "binding names (UPPER_SNAKE_CASE)");
+  const kv_namespaces = resourceArray("kv_namespaces", "kv");
+  const d1_databases = resourceArray("d1_databases", "d1");
+  const r2_buckets = resourceArray("r2_buckets", "r2");
+  const queues = resourceArray("queues", "queue");
 
   let durable_objects: Record<string, string> | undefined;
   if (value.durable_objects !== undefined) {
@@ -190,9 +239,11 @@ function validateConfig(value: ConfigInput): ConfigValidation {
     }
   }
 
+  const resourceNames = (refs: ResourceRef[] | undefined): string[] =>
+    resourceRefs(refs).map((ref) => ref.binding);
   const bindingSlots = [
-    ...(kv_namespaces ?? []), ...(secrets ?? []), ...(d1_databases ?? []), ...(r2_buckets ?? []),
-    ...(queues ?? []), ...(analytics_engine_datasets ?? []), ...Object.keys(durable_objects ?? {}), ...Object.keys(vars ?? {}),
+    ...resourceNames(kv_namespaces), ...(secrets ?? []), ...resourceNames(d1_databases), ...resourceNames(r2_buckets),
+    ...resourceNames(queues), ...(analytics_engine_datasets ?? []), ...Object.keys(durable_objects ?? {}), ...Object.keys(vars ?? {}),
     ...(assets?.binding ? [assets.binding] : []),
   ];
   if (new Set(bindingSlots).size !== bindingSlots.length) errors.push("vars and binding names must not collide");

package/src/main.ts

@@ -266,11 +266,10 @@ async function deploy(args: string[]) {
     console.warn(dim(`  The previous live version stays frozen at ${drift.from}; this one is built with ${drift.to}.`));
     console.warn(dim(`  The alpha compiler's output can differ between pins (see COMPAT.md) — roll back if this version misbehaves.`));
   }
-  if (!args.includes("--no-wait")) {
-    const healthy = await waitForHealthy(deployed.url, 90_000);
-    console.log(healthy
-      ? `  ${ok("serving")}`
-      : amber("  ! not serving after 90s — Caddy may still be issuing the cert, or the sprout is crashing (`sproutboat tail`)"));
+  // Verify the edge actually answers (cert issuance + sprout boot). Say nothing
+  // on success — "Deployed" already implied that; only speak up if it doesn't.
+  if (!args.includes("--no-wait") && !(await waitForHealthy(deployed.url, 90_000))) {
+    console.warn(amber("  ! not serving after 90s — Caddy may still be issuing the cert, or the sprout is crashing (`sproutboat tail`)"));
   }
 }
 
@@ -463,6 +462,63 @@ async function secrets(args: string[]) {
   console.log(`Set ${name} — applies on the next deploy or sprout restart`);
 }
 
+const RESOURCE_KINDS = ["kv", "d1", "r2", "queue"];
+
+/**
+ * #74 — account-level storage resources. Unlike `secrets`/`domains` these are
+ * not project-scoped, so there's no `readProject` here. `create` prints the
+ * `<kind>_<id>` handle to paste into `sproutboat.jsonc` bindings.
+ */
+async function resource(args: string[]) {
+  const sub = args[0] && ["list", "create", "rename", "delete"].includes(args[0]) ? args.shift()! : "list";
+  const { apiUrl, token } = await apiCredentials();
+  const base = `${apiUrl}/api/resources`;
+  const auth = { "x-api-key": token };
+
+  if (sub === "list") {
+    const kindFilter = args[0];
+    const body = await responseText(await fetch(base, { headers: auth }), "could not list resources");
+    const parsed = jsonObject(parseJsonValue(body));
+    const rows = (parsed && Array.isArray(parsed.resources) ? parsed.resources : [])
+      .map((entry) => jsonObject(entry))
+      .filter((entry): entry is JsonObject => Boolean(entry) && (!kindFilter || entry!.kind === kindFilter));
+    if (rows.length === 0) { console.log(kindFilter ? `no ${kindFilter} resources` : "no resources"); return; }
+    for (const row of rows) console.log(`${String(row.kind).padEnd(9)} ${String(row.id).padEnd(30)} ${String(row.name)}`);
+    return;
+  }
+
+  if (sub === "create") {
+    const [kind, name] = args;
+    if (!kind || !RESOURCE_KINDS.includes(kind)) usageError(`resource create: kind must be one of ${RESOURCE_KINDS.join(", ")}`, "resource create <kind> <name>");
+    if (!name) usageError("resource create: missing <name>", "resource create <kind> <name>");
+    const body = await responseText(
+      await fetch(base, { method: "POST", headers: { ...auth, "content-type": "application/json" }, body: JSON.stringify({ kind, name }) }),
+      "create rejected",
+    );
+    const record = jsonObject(jsonObject(parseJsonValue(body))?.resource ?? null);
+    if (!record || !isString(record.id)) fail("create response was not a resource");
+    console.log(ok(`created ${kind} ${bold(String(record.name))}`));
+    console.log(record.id);
+    return;
+  }
+
+  if (sub === "rename") {
+    const [id, name] = args;
+    if (!id || !name) usageError("resource rename: need <id> <name>", "resource rename <id> <name>");
+    await responseText(
+      await fetch(`${base}/${id}`, { method: "PATCH", headers: { ...auth, "content-type": "application/json" }, body: JSON.stringify({ name }) }),
+      "rename rejected",
+    );
+    console.log(ok(`renamed ${id} → ${name}`));
+    return;
+  }
+
+  const id = args[0];
+  if (!id) usageError("resource delete: missing <id>", "resource delete <id>");
+  await responseText(await fetch(`${base}/${id}`, { method: "DELETE", headers: auth }), "delete rejected");
+  console.log(ok(`deleted ${id}`));
+}
+
 async function deleteProject(args: string[]) {
   // `sproutboat delete [project-dir] [--name <project>] --yes` — flags in any order.
   const positional: string[] = [];
@@ -522,6 +578,7 @@ switch (command) {
   case "rollback": await rollback(args); break;
   case "domains": await domains(args); break;
   case "secrets": await secrets(args); break;
+  case "resource": await resource(args); break;
   case "tail": await tail(args); break;
   case "delete": await deleteProject(args); break;
   default: usage();

package/src/report.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { gzipSync } from "bun";
-import type { SproutboatConfig } from "./config";
+import { resourceRefs, type SproutboatConfig } from "./config";
 import type { ArtifactManifest } from "./manifest";
 import { bold, dim, leaf, sprout } from "./style";
 
@@ -33,11 +33,16 @@ function bindingRows(config: SproutboatConfig): string[][] {
   const list = (names: string[] | undefined, type: string, detail = "") => {
     for (const name of names ?? []) rows.push([`env.${name}`, type, detail]);
   };
-  list(config.kv_namespaces, "kv");
+  const resourceList = (refs: Parameters<typeof resourceRefs>[0], type: string) => {
+    for (const ref of resourceRefs(refs)) {
+      rows.push([`env.${ref.binding}`, type, ref.id ?? "no id — local dev only, a deploy needs `sproutboat resource create`"]);
+    }
+  };
+  resourceList(config.kv_namespaces, "kv");
   list(config.secrets, "secret", "value withheld — set with `sproutboat secrets`");
-  list(config.d1_databases, "d1");
-  list(config.r2_buckets, "r2");
-  list(config.queues, "queue");
+  resourceList(config.d1_databases, "d1");
+  resourceList(config.r2_buckets, "r2");
+  resourceList(config.queues, "queue");
   list(config.analytics_engine_datasets, "analytics");
   for (const [name, className] of Object.entries(config.durable_objects ?? {})) rows.push([`env.${name}`, "durable object", className]);
   for (const host of config.outbound ?? []) rows.push([`fetch()`, "outbound", host]);

package/src/surface.ts

@@ -46,6 +46,9 @@ export const COMMANDS: readonly Command[] = [
   { name: "secrets", group: "Configure", emoji: "🔑",
     args: "[list | set <NAME> [value] | rm <NAME>] [project-dir]", brief: "[list | set | rm]",
     summary: "Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy." },
+  { name: "resource", group: "Configure", emoji: "📦",
+    args: "[list [kind] | create <kind> <name> | rename <id> <name> | delete <id>]", brief: "[list | create | rename | delete]",
+    summary: "Manage account-level storage resources (kv | d1 | r2 | queue). `create` prints the id to reference from sproutboat.jsonc bindings." },
   { name: "delete", group: "Configure", emoji: "🗑",
     args: "[project-dir] [--name <project>] --yes", brief: "[project-dir] --yes",
     summary: "Delete the project, every version, and its route." },