@pramen/server 0.0.13 → 0.0.15

package/src/cli.ts

@@ -0,0 +1,336 @@
+#!/usr/bin/env bun
+// pramen CLI — ships as the `pramen` bin of @pramen/server (see package.json `bin`).
+// In-repo it's invoked via `bun run pramen <command>` (scripts/cli.ts is a thin
+// wrapper around this module); published consumers get it as `pramen <command>`.
+//
+//   pramen help
+//   pramen init [dir]
+//   pramen schema sql                 print CREATE TABLE for the schema
+//   pramen schema hash                print the schema hash
+//   pramen schema snapshot            save the current schema to .pramen/schema.json
+//   pramen schema diff                compare the schema to the snapshot (safe vs unsafe changes)
+//   pramen schema status [--tenant t] [--url u] [--token jwt]   compare a deployed tenant to the schema
+//   pramen token <sub> [roles...] [--tenant a,b]                mint a dev JWT
+//
+// The bin uses a `bun` shebang: the `schema *` commands import your app module (a .ts
+// file), and the built package's dist/ uses extensionless ESM imports — both of which
+// bun resolves out of the box. Under plain Node the extensionless imports don't resolve
+// (a property of the whole @pramen/server dist, not just this file), so run via bun.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createTableSql } from "./runtime/ddl";
+import { schemaHash } from "./runtime/migrate";
+import { diffSchemaShape, schemaShape, type SchemaShape } from "./runtime/schema-diff";
+import { entitiesInPartition, partitionsOf, type SchemaDef } from "./sdk/schema";
+
+/** Mint an HS256 JWT — mirrors what a real auth service would issue, for local
+ * dev/testing (`pramen token`, and the default token for `schema status`). Signs
+ * with AUTH_SECRET when set, else the dev secret from the scaffolded oblaka.ts. */
+const DEV_SECRET = "dev-secret-change-me";
+
+function bytesToB64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+const strToB64url = (s: string) => bytesToB64url(new TextEncoder().encode(s));
+
+async function sign(payload: Record<string, unknown>): Promise<string> {
+  const secret = process.env.AUTH_SECRET || DEV_SECRET;
+  const now = Math.floor(Date.now() / 1000);
+  const header = strToB64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+  const body = strToB64url(JSON.stringify({ iat: now, exp: now + 3600, ...payload }));
+  const data = `${header}.${body}`;
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
+  return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
+}
+
+/** The sub-schema of a single partition (used to mirror the DO's per-partition hash,
+ * which migrate() computes over exactly this subset). For a single-partition app the
+ * subset equals the whole schema, so the hash is identical to the unpartitioned case. */
+function partitionSchema(schema: SchemaDef, partition: string): SchemaDef {
+  return Object.fromEntries(entitiesInPartition(schema, partition).map((t) => [t, schema[t]!]));
+}
+
+const argv = process.argv.slice(2);
+
+function flag(name: string): string | undefined {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+function positionals(args: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i]!.startsWith("--")) i++; // skip flag + its value
+    else out.push(args[i]!);
+  }
+  return out;
+}
+
+function fail(msg: string): never {
+  console.error(`pramen: ${msg}`);
+  process.exit(1);
+}
+
+async function loadApp(): Promise<{ schema: SchemaDef }> {
+  const explicit = flag("app");
+  const candidates = explicit ? [explicit] : ["./app.ts", "./example/app.ts"];
+  for (const c of candidates) {
+    const p = resolve(process.cwd(), c);
+    if (existsSync(p)) {
+      const mod = (await import(p)) as { app?: { schema?: SchemaDef } };
+      if (mod.app?.schema) return mod.app as { schema: SchemaDef };
+      fail(`${c} does not export { app }`);
+    }
+  }
+  return fail(`no app found (looked for ${candidates.join(", ")}); pass --app <path>`);
+}
+
+const HELP = `pramen — reactive backend on Cloudflare
+
+Usage: pramen <command>
+
+  help                      show this help
+  init [dir]                scaffold a new project (app.ts + worker.ts + oblaka.ts)
+  schema sql                print CREATE TABLE statements for the schema
+  schema hash               print the schema hash
+  schema snapshot           save the schema shape to .pramen/schema.json
+  schema diff               compare the schema to the snapshot (safe vs unsafe)
+  schema status             compare a deployed tenant's schema to the local schema
+                            [--tenant t] [--url u] [--token jwt]
+  token <sub> [roles...]    mint a dev JWT [--tenant a,b]
+
+Flags: --app <path> to point at your app module (default ./app.ts or ./example/app.ts).`;
+
+async function schemaCmd(sub: string | undefined): Promise<void> {
+  const snapshotPath = resolve(process.cwd(), ".pramen/schema.json");
+
+  if (sub === "sql") {
+    const { schema } = await loadApp();
+    for (const [table, def] of Object.entries(schema)) console.log(createTableSql(table, def) + ";");
+    return;
+  }
+  if (sub === "hash") {
+    const { schema } = await loadApp();
+    console.log(schemaHash(schema));
+    return;
+  }
+  if (sub === "snapshot") {
+    const { schema } = await loadApp();
+    mkdirSync(dirname(snapshotPath), { recursive: true });
+    const snap = { hash: schemaHash(schema), shape: schemaShape(schema) };
+    writeFileSync(snapshotPath, JSON.stringify(snap, null, 2) + "\n");
+    console.log(`wrote ${snapshotPath} (${Object.keys(snap.shape).length} tables)`);
+    return;
+  }
+  if (sub === "diff") {
+    const { schema } = await loadApp();
+    const next = schemaShape(schema);
+    if (!existsSync(snapshotPath)) {
+      console.log("no snapshot — run `pramen schema snapshot` to set a baseline.");
+      return;
+    }
+    const prev = (JSON.parse(readFileSync(snapshotPath, "utf8")) as { shape: SchemaShape }).shape;
+    const changes = diffSchemaShape(prev, next);
+    if (changes.length === 0) {
+      console.log("no changes since snapshot.");
+      return;
+    }
+    for (const c of changes) {
+      const where = c.column ? `${c.table}.${c.column}` : c.table;
+      const note = c.detail ? ` (${c.detail})` : "";
+      const glyph = c.destructive ? "⚠" : !c.appliesOnBoot ? "•" : "+";
+      const tags =
+        (c.destructive ? "  [destructive]" : "") + (!c.appliesOnBoot ? "  [NOT applied on boot]" : "");
+      console.log(`  ${glyph} ${c.kind} ${where}${note}${tags}`);
+    }
+    console.log(
+      "\nOn the next DO boot: additive changes (new table/column) auto-apply; destructive changes\n" +
+        "(drops, type changes, table rebuilds) are SKIPPED unless the deploy sets PRAMEN_ALLOW_DESTRUCTIVE=true\n" +
+        "(the schema hash is then left unwritten so a later opt-in deploy retries).",
+    );
+    if (changes.some((c) => c.destructive))
+      console.log(
+        "⚠ destructive changes rebuild the table and CAN lose data. A drop+add is applied as such unless\n" +
+          "  the column declares `renamedFrom` (which migrates the data).",
+      );
+    if (changes.some((c) => !c.appliesOnBoot))
+      console.log(
+        "• [NOT applied on boot] a partition move — the entity's data lives in a different Durable Object,\n" +
+          "  which needs a manual cross-DO data migration. The boot migrator won't move it; apply it yourself.\n" +
+          "  (Modifier/constraint changes on an existing column ARE applied on boot now — a tightening one\n" +
+          "  like adding NOT NULL/UNIQUE is gated by PRAMEN_ALLOW_DESTRUCTIVE and skipped if it can't apply.)",
+      );
+    return;
+  }
+  if (sub === "status") {
+    const { schema } = await loadApp();
+    const url = flag("url") ?? "http://localhost:8787";
+    const tenant = flag("tenant") ?? "main";
+    const token = flag("token") ?? (await sign({ sub: "cli", roles: ["admin"] }));
+    // Each partition is a distinct Durable Object class, migrated and hashed
+    // independently — so compare them one at a time, fetching each partition's applied
+    // schema from its DO. A single-(default-)partition app loops exactly once and reads
+    // identically to before. The default partition is addressed with no partition param.
+    const partitions = partitionsOf(schema);
+    console.log(`tenant:  ${tenant}`);
+    for (const partition of partitions) {
+      if (partitions.length > 1) console.log(`\npartition: ${partition}`);
+      const qs = partition === "default" ? "" : `&partition=${encodeURIComponent(partition)}`;
+      const res = await fetch(`${url}/admin/schema?tenant=${encodeURIComponent(tenant)}${qs}`, {
+        headers: { authorization: `Bearer ${token}` },
+      });
+      const body = (await res.json().catch(() => ({}))) as {
+        ok?: boolean;
+        result?: { hash: string | null; tables: Record<string, string[]> };
+        error?: string;
+      };
+      if (!res.ok || !body.ok || !body.result) fail(`status failed (partition ${partition}): ${body.error ?? res.status}`);
+      const live = body.result!;
+      // The DO hashes only its partition's entities — mirror that here so the compared
+      // hashes line up (for a single partition this equals the whole-schema hash).
+      const subset = partitionSchema(schema, partition);
+      const current = schemaHash(subset);
+      const upToDate = live.hash === current;
+      console.log(`live:    ${live.hash ?? "(none)"}`);
+      console.log(`current: ${current}`);
+      console.log(upToDate ? "✓ up to date" : "⚠ BEHIND — migrates on the tenant's next boot");
+      const want = schemaShape(subset);
+      for (const table of Object.keys(want)) {
+        const liveCols = new Set(live.tables[table] ?? []);
+        const missing = Object.keys(want[table]!.columns).filter((col) => !liveCols.has(col));
+        if (!live.tables[table]) console.log(`  + table ${table} (not yet created live)`);
+        else if (missing.length) console.log(`  + ${table}: ${missing.join(", ")} (not yet added live)`);
+      }
+    }
+    return;
+  }
+  console.log(HELP);
+}
+
+async function tokenCmd(args: string[]): Promise<void> {
+  const pos = positionals(args);
+  const sub = pos[0];
+  if (!sub) fail("token: <sub> required");
+  const roles = pos.slice(1);
+  const tenants = flag("tenant")?.split(",");
+  console.log(await sign({ sub, roles: roles.length ? roles : ["admin"], ...(tenants ? { tenants } : {}) }));
+}
+
+function initCmd(args: string[]): void {
+  const dir = resolve(process.cwd(), positionals(args)[0] ?? ".");
+  mkdirSync(dir, { recursive: true });
+  const write = (name: string, content: string) => {
+    const p = resolve(dir, name);
+    if (existsSync(p)) return void console.log(`  skip ${name} (exists)`);
+    writeFileSync(p, content);
+    console.log(`  + ${name}`);
+  };
+  write("app.ts", APP_TEMPLATE);
+  write("worker.ts", WORKER_TEMPLATE);
+  write("oblaka.ts", OBLAKA_TEMPLATE);
+  console.log(`\nScaffolded a pramen project in ${dir}.\n`);
+  console.log("Next steps:");
+  console.log("  1. Install deps:    bun add @pramen/server && bun add -d oblaka-iac wrangler");
+  console.log("  2. Generate config: bunx oblaka oblaka.ts    (writes wrangler.jsonc)");
+  console.log("  3. Run locally:     bunx wrangler dev         (serves http://localhost:8787)");
+  console.log("");
+  console.log("First request: POST http://localhost:8787/rpc/listNotes returns [] (not 403) —");
+  console.log("the scaffold's ACL grants the anonymous role read+create on `notes`. Tighten it");
+  console.log("in app.ts before shipping (see the comments there).");
+}
+
+const APP_TEMPLATE = `import { Entity, defineSchema, createApp, role, policy, allow } from "@pramen/server";
+
+const schema = defineSchema({
+  notes: Entity((t) => ({ id: t.id(), title: t.text(), body: t.text(), createdAt: t.int() })),
+});
+
+const { query, mutation } = createApp(schema);
+
+const handlers = {
+  listNotes: query((ctx) => ctx.db.find({ from: "notes", orderBy: { column: "id", dir: "desc" } })),
+  createNote: mutation((ctx, input: { title: string; body: string }) =>
+    ctx.db.insert("notes", { title: input.title, body: input.body, createdAt: Date.now() }),
+  ),
+};
+
+// ACL — deny-by-default; roles only GRANT. A caller with no verified token is the
+// \`anonymous\` role, so this grants the scaffold's handlers on the first request (no
+// token needed). TIGHTEN THIS before shipping: gate writes behind an authenticated
+// role and scope reads with \`$identity(...)\` (see @pramen/auth and the pramen docs).
+const acl = [
+  role("anonymous", [
+    policy("anon:notes:read", "notes", "read", allow()),
+    policy("anon:notes:create", "notes", "create", allow()),
+  ]),
+];
+
+export const app = { schema, handlers, acl };
+`;
+
+const WORKER_TEMPLATE = `// The whole server entry: hand your app to createPramen and re-export the pair.
+import { createPramen } from "@pramen/server/worker";
+import { app } from "./app";
+
+const pramen = createPramen(app);
+
+export default { fetch: pramen.fetch };
+export const PramenDO = pramen.PramenDO; // wrangler binds this by class_name
+`;
+
+const OBLAKA_TEMPLATE = `import { define, DurableObject, KVNamespace, R2Bucket, Worker } from "oblaka-iac";
+
+const PROJECT = "my-pramen-app"; // unique per project — namespaces all CF resources
+
+export default define(({ env }) => {
+  const vars =
+    env === "local" ? { AUTH_SECRET: "dev-secret-change-me", FILES_SECRET: "dev-files-secret-change-me" } : {};
+  return new Worker({
+    dir: ".",
+    name: PROJECT,
+    main: "./worker.ts",
+    compatibility_date: "2026-06-19",
+    compatibility_flags: ["nodejs_compat"],
+    observability: { enabled: true },
+    bindings: {
+      PRAMEN: new DurableObject({ name: PROJECT + "-store", className: "PramenDO" }),
+      KV: new KVNamespace({ name: PROJECT + "-kv" }),
+      FILES: new R2Bucket({ name: PROJECT + "-files" }),
+    },
+    vars,
+  });
+});
+`;
+
+async function main(): Promise<void> {
+  const cmd = argv[0];
+  switch (cmd) {
+    case undefined:
+    case "help":
+    case "-h":
+    case "--help":
+      console.log(HELP);
+      return;
+    case "init":
+      return initCmd(argv.slice(1));
+    case "schema":
+      return schemaCmd(argv[1]);
+    case "token":
+      return tokenCmd(argv.slice(1));
+    default:
+      console.error(`pramen: unknown command "${cmd}"\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+await main();

package/src/durable-object.ts

@@ -19,6 +19,7 @@ import { DurableObject } from "cloudflare:workers";
 import { migrate } from "./runtime/migrate";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { createMail } from "./runtime/mail";
+import { createQueue } from "./runtime/queue";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
@@ -34,14 +35,17 @@ import type { HandlerContext } from "./sdk/handlers";
 import type { PramenApp } from "./pramen";
 import type { ClientMsg, ServerMsg, Subscription } from "./runtime/protocol";
 
-interface SocketState {
+/** Durable per-socket state — kept SMALL and stable, since it rides the WebSocket
+ * attachment which workerd caps at ~2 KB. Only auth/routing identity lives here so it
+ * survives hibernation; the (potentially large) subscription list does NOT — see
+ * `subsBySocket`. */
+interface SocketAttachment {
   identity: Identity | null;
   /** Tenant fixed at connect time (survives hibernation via the attachment). */
   tenant: string;
   /** Partition fixed at connect time (read from x-pramen-partition at upgrade);
    * survives hibernation via the attachment, like `tenant`. */
   partition: string;
-  subs: Subscription[];
 }
 
 export interface DoEnv {
@@ -83,6 +87,14 @@ export class PramenDOBase extends DurableObject<DoEnv> {
    * task context — a DO can't introspect its own idFromName. */
   private identityPersisted = false;
   private identityLoaded = false;
+  /** Live subscriptions per socket — held IN MEMORY, not in the WS attachment. The
+   * attachment is capped at ~2 KB by workerd, and 64 subs (each with arbitrary input
+   * JSON + a read-set + digest) blow past that well before MAX_SUBSCRIPTIONS. The
+   * tradeoff: this map is lost on DO hibernation/eviction, so a woken socket has no
+   * entry and is treated as having no active subscriptions — acceptable because the
+   * client replays its subscriptions on (re)connect. Keyed by the WebSocket object;
+   * cleaned up in webSocketClose. */
+  private readonly subsBySocket = new Map<WebSocket, Subscription[]>();
 
   constructor(ctx: DurableObjectState, env: DoEnv, app: PramenApp) {
     super(ctx, env);
@@ -160,7 +172,8 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     if (request.headers.get("Upgrade") === "websocket") {
       const { 0: client, 1: server } = new WebSocketPair();
       this.ctx.acceptWebSocket(server); // hibernatable
-      this.setState(server, { identity, tenant: this.tenant, partition: this.partition, subs: [] });
+      this.setAttachment(server, { identity, tenant: this.tenant, partition: this.partition });
+      this.subsBySocket.set(server, []);
       return new Response(null, { status: 101, webSocket: client });
     }
 
@@ -182,8 +195,11 @@ export class PramenDOBase extends DurableObject<DoEnv> {
         name,
         input,
       );
-      if (kind === "mutation" && touched.length > 0) await this.broadcast(touched);
+      // Arm the drain BEFORE broadcasting so enqueued tasks are always scheduled even
+      // if broadcast has trouble (broadcast is best-effort and never throws — a failed
+      // push must not 500 a COMMITTED write nor skip the alarm).
       if (enqueued > 0) await this.armDrain();
+      if (kind === "mutation" && touched.length > 0) await this.broadcast(touched);
       return Response.json({ ok: true, result });
     } catch (err) {
       const { status, body } = toResponse(err);
@@ -198,15 +214,17 @@ export class PramenDOBase extends DurableObject<DoEnv> {
   }
 
   /** A privileged, system-scoped context for running task handlers (outside a request).
-   * Task handlers get full db access + env (e.g. ctx.env.EMAIL) + their own ctx.tasks. */
-  private taskCtx(): HandlerContext {
+   * Task handlers get full db access + env (e.g. ctx.env.EMAIL) + their own ctx.tasks.
+   * Returns the `db` alongside the ctx so the drainer can broadcast the tables the task
+   * handlers touched (live queries would otherwise go stale after deferred/trigger work). */
+  private taskCtx(): { ctx: HandlerContext; db: Db } {
     const identity: Identity = { roles: ["admin"] };
     const db = new Db(
       this.driver,
       { acl: this.acl, identity, system: true, schema: this.app.schema, partition: this.partition, suppressTriggers: true },
       this.app.schema,
     );
-    return {
+    const ctx: HandlerContext = {
       db,
       kv: this.kv,
       files: this.filesFor(this.tenant),
@@ -214,7 +232,9 @@ export class PramenDOBase extends DurableObject<DoEnv> {
       identity,
       tasks: tasksFacade(this.driver),
       mail: createMail(this.envBag, this.kv),
+      queue: createQueue(this.envBag),
     };
+    return { ctx, db };
   }
 
   /** Restore (tenant, partition) on a cold wake (e.g. an alarm with no request) so the
@@ -235,23 +255,33 @@ export class PramenDOBase extends DurableObject<DoEnv> {
   }
 
   /** Drain due tasks. Called by the alarm (DO path) and the /__admin/tasks/drain route
-   * (manual / cron). Returns the drain stats incl. `nextRunAt` for rescheduling. */
-  private async drainTasks(): Promise<Awaited<ReturnType<typeof drainOutbox>>> {
+   * (manual / cron). Returns the drain stats incl. `nextRunAt` for rescheduling, plus
+   * the union of tables the drained task handlers touched (for a post-commit broadcast). */
+  private async drainTasks(): Promise<{ result: Awaited<ReturnType<typeof drainOutbox>>; touched: string[] }> {
     await ensureOutbox(this.driver); // idempotent — the table may predate this instance (cold alarm)
-    return drainOutbox(this.driver, bindTasks(this.app.tasks, this.taskCtx()), Date.now());
+    const { ctx, db } = this.taskCtx();
+    const result = await drainOutbox(this.driver, bindTasks(this.app.tasks, ctx), Date.now());
+    return { result, touched: [...db.touched] };
   }
 
   override async alarm(): Promise<void> {
     await this.loadIdentity(); // cold wake: restore tenant/partition before building taskCtx
-    const { nextRunAt } = await this.drainTasks();
+    // A post-deploy cold alarm may run against the old schema — reconcile it first, or a
+    // task handler writing a new column dead-letters. loadIdentity() restored the partition.
+    await this.ensureMigrated();
+    const { result, touched } = await this.drainTasks();
+    // Deferred/triggered writes are invisible to live queries unless we broadcast the
+    // tables the task handlers touched (post-commit — the drain has already committed).
+    if (touched.length > 0) await this.broadcast(touched);
     // Reschedule to the NEXT task's due time (a backed-off retry, or the next batch if
     // the drain hit its limit) so a failed task can't stall waiting for a new enqueue.
-    if (nextRunAt != null) await this.ctx.storage.setAlarm(Math.max(nextRunAt, Date.now() + 250));
+    if (result.nextRunAt != null) await this.ctx.storage.setAlarm(Math.max(result.nextRunAt, Date.now() + 250));
   }
 
   private async handleDrain(): Promise<Response> {
     await this.loadIdentity();
-    const result = await this.drainTasks();
+    const { result, touched } = await this.drainTasks();
+    if (touched.length > 0) await this.broadcast(touched);
     // Keep the alarm honest even when drained manually: ensure a backed-off retry wakes.
     if (result.nextRunAt != null) await this.ctx.storage.setAlarm(Math.max(result.nextRunAt, Date.now() + 250));
     return Response.json({ ok: true, result });
@@ -280,7 +310,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     // socket's (tenant, partition) — fixed at connect time, survives via the attachment
     // — and ensure the schema is migrated before any handler/ctx.db work. Idempotent
     // (the `migrated` flag), so a no-op after the first call.
-    const { tenant, partition } = this.getState(ws);
+    const { tenant, partition } = this.getAttachment(ws);
     this.tenant = tenant;
     this.partition = partition;
     await this.ensureMigrated();
@@ -288,11 +318,9 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     switch (msg.type) {
       case "subscribe":
         return this.onSubscribe(ws, msg.id, msg.name, msg.input);
-      case "unsubscribe": {
-        const state = this.getState(ws);
-        this.setState(ws, { ...state, subs: state.subs.filter((s) => s.id !== msg.id) });
+      case "unsubscribe":
+        this.setSubs(ws, this.getSubs(ws).filter((s) => s.id !== msg.id));
         return;
-      }
       case "call":
         return this.onCall(ws, msg.id, msg.name, msg.input);
       default:
@@ -301,6 +329,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
   }
 
   override async webSocketClose(ws: WebSocket): Promise<void> {
+    this.subsBySocket.delete(ws); // release the in-memory subscription list for this socket
     ws.close();
   }
 
@@ -316,19 +345,20 @@ export class PramenDOBase extends DurableObject<DoEnv> {
   // --- live-query internals ---
 
   private async onSubscribe(ws: WebSocket, id: string, name: string, input: unknown): Promise<void> {
-    const state = this.getState(ws);
+    const att = this.getAttachment(ws);
+    const subs = this.getSubs(ws);
     try {
-      const replacing = state.subs.some((s) => s.id === id);
-      if (!replacing && state.subs.length >= MAX_SUBSCRIPTIONS) {
+      const replacing = subs.some((s) => s.id === id);
+      if (!replacing && subs.length >= MAX_SUBSCRIPTIONS) {
         return this.send(ws, toWsError(id, new BadRequest("subscription limit reached")));
       }
-      const { result, kind, touched } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity, state.partition), name, input);
+      const { result, kind, touched } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(att.tenant), this.envBag, this.ctxFor(att.identity, att.partition), name, input);
       if (kind !== "query") {
         return this.send(ws, toWsError(id, new BadRequest(`${name} is not a query`)));
       }
-      const subs = state.subs.filter((s) => s.id !== id);
-      subs.push({ id, name, input, tables: touched, digest: digest(result) });
-      this.setState(ws, { ...state, subs });
+      const next = subs.filter((s) => s.id !== id);
+      next.push({ id, name, input, tables: touched, digest: digest(result) });
+      this.setSubs(ws, next);
       this.send(ws, { type: "data", id, result });
     } catch (err) {
       this.send(ws, toWsError(id, err));
@@ -336,38 +366,57 @@ export class PramenDOBase extends DurableObject<DoEnv> {
   }
 
   private async onCall(ws: WebSocket, id: string, name: string, input: unknown): Promise<void> {
-    const state = this.getState(ws);
+    const att = this.getAttachment(ws);
+    let outcome: Awaited<ReturnType<typeof dispatch>>;
     try {
-      const { result, kind, touched, enqueued } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity, state.partition), name, input);
-      this.send(ws, { type: "result", id, result });
-      if (kind === "mutation" && touched.length > 0) await this.broadcast(touched);
-      if (enqueued > 0) await this.armDrain();
+      outcome = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(att.tenant), this.envBag, this.ctxFor(att.identity, att.partition), name, input);
     } catch (err) {
-      this.send(ws, toWsError(id, err));
+      return this.send(ws, toWsError(id, err));
     }
+    // The mutation is committed — send its result FIRST, then run post-commit
+    // side-effects that must never turn a committed write into a spurious error frame:
+    // arm the drain (independent of broadcast), then broadcast (best-effort, never throws).
+    const { result, kind, touched, enqueued } = outcome;
+    this.send(ws, { type: "result", id, result });
+    if (enqueued > 0) await this.armDrain();
+    if (kind === "mutation" && touched.length > 0) await this.broadcast(touched);
   }
 
   // Re-run every subscription whose read-set intersects the written tables, each
-  // under its own socket's identity, and push only when its result changed.
+  // under its own socket's identity, and push only when its result changed. Best-effort:
+  // a failure for one subscription or socket is logged and skipped — it must NEVER throw,
+  // because it runs after a mutation has committed (a throw here would 500 that write).
   private async broadcast(touched: string[]): Promise<void> {
     const written = new Set(touched);
     for (const ws of this.ctx.getWebSockets()) {
-      const state = this.getState(ws);
-      let dirty = false;
-      for (const sub of state.subs) {
-        if (!sub.tables.some((t) => written.has(t))) continue;
-        try {
-          const { result } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity, state.partition), sub.name, sub.input);
-          const next = digest(result);
-          if (next === sub.digest) continue; // result unchanged for this subscription
-          sub.digest = next;
-          dirty = true;
-          this.send(ws, { type: "data", id: sub.id, result });
-        } catch (err) {
-          this.send(ws, toWsError(sub.id, err));
+      try {
+        const att = this.getAttachment(ws);
+        const subs = this.getSubs(ws);
+        let dirty = false;
+        for (const sub of subs) {
+          if (!sub.tables.some((t) => written.has(t))) continue;
+          try {
+            const { result } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(att.tenant), this.envBag, this.ctxFor(att.identity, att.partition), sub.name, sub.input);
+            const next = digest(result);
+            if (next === sub.digest) continue; // result unchanged for this subscription
+            sub.digest = next;
+            dirty = true;
+            this.send(ws, { type: "data", id: sub.id, result });
+          } catch (err) {
+            // One subscription failing (re-dispatch error, or a send to a dead socket)
+            // must not abort the other subs — surface it to that sub, swallow otherwise.
+            try {
+              this.send(ws, toWsError(sub.id, err));
+            } catch {
+              /* socket already gone */
+            }
+          }
         }
+        if (dirty) this.setSubs(ws, subs);
+      } catch (err) {
+        // A bad socket must not stop the loop over the others.
+        console.error("pramen: broadcast to a socket failed", err);
       }
-      if (dirty) this.setState(ws, state);
     }
   }
 
@@ -466,7 +515,9 @@ export class PramenDOBase extends DurableObject<DoEnv> {
           result = await db.count({ from: table, where: b.where });
           break;
         case "get":
-          result = (await db.find({ from: table, where: { id: b.id }, limit: 1 }))[0] ?? null;
+          // Resolve the PK from the schema — a custom-PK table (e.g. auth_users keyed on
+          // `username`) has no `id` column, so a hardcoded `{ id }` would 500.
+          result = (await db.find({ from: table, where: { [db.pkOf(table)]: b.id }, limit: 1 }))[0] ?? null;
           break;
         case "create":
           result = await this.driver.transaction(() => db.insert(table, b.values));
@@ -483,6 +534,9 @@ export class PramenDOBase extends DurableObject<DoEnv> {
         default:
           return Response.json({ ok: false, error: `unknown op: ${op}`, code: "bad_request" }, { status: 400 });
       }
+      // Admin-data writes fire triggers too — arm the drain if any task was enqueued
+      // (independent of broadcast), then broadcast the touched tables to live queries.
+      if (mutated && db.taskEnqueues > 0) await this.armDrain();
       if (mutated && db.touched.size > 0) await this.broadcast([...db.touched]);
       return Response.json({ ok: true, result });
     } catch (err) {
@@ -524,19 +578,31 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     }
   }
 
-  private getState(ws: WebSocket): SocketState {
+  /** The durable per-socket auth/routing state (identity + tenant + partition), read
+   * from the WS attachment. Survives hibernation; kept tiny to stay under workerd's cap. */
+  private getAttachment(ws: WebSocket): SocketAttachment {
     return (
-      (ws.deserializeAttachment() as SocketState | null) ?? {
+      (ws.deserializeAttachment() as SocketAttachment | null) ?? {
         identity: null,
         tenant: this.tenant,
         partition: this.partition,
-        subs: [],
       }
     );
   }
 
-  private setState(ws: WebSocket, state: SocketState): void {
-    ws.serializeAttachment(state);
+  private setAttachment(ws: WebSocket, att: SocketAttachment): void {
+    ws.serializeAttachment(att);
+  }
+
+  /** This socket's live subscriptions from the in-memory map (see `subsBySocket`). A
+   * hibernated/woken socket has no entry → no active subscriptions until the client
+   * replays them on reconnect. */
+  private getSubs(ws: WebSocket): Subscription[] {
+    return this.subsBySocket.get(ws) ?? [];
+  }
+
+  private setSubs(ws: WebSocket, subs: Subscription[]): void {
+    this.subsBySocket.set(ws, subs);
   }
 
   private send(ws: WebSocket, msg: ServerMsg): void {