@pramen/server 0.0.14 → 0.0.16

package/src/durable-object.ts

@@ -35,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 {
@@ -84,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);
@@ -161,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 });
     }
 
@@ -183,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);
@@ -199,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),
@@ -217,6 +234,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
       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
@@ -237,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 });
@@ -282,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();
@@ -290,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:
@@ -303,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();
   }
 
@@ -318,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));
@@ -338,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);
     }
   }
 
@@ -468,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));
@@ -485,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) {
@@ -526,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 {

package/src/runtime/acl.ts

@@ -225,6 +225,12 @@ function resolveMarkers(rule: Record<string, unknown>, identity: Identity | null
     } else {
       const rv = resolveValue(v, identity, input);
       if (rv === UNRESOLVED) return null;
+      // A bare-value marker must only ever produce an EQUALITY comparison. If it
+      // resolves to a caller-controlled non-primitive (object/array), compileWhere
+      // would read it as an operator predicate (`{"gte":""}` → full-table
+      // enumeration), defeating the intended equality. Treat that as unresolvable so
+      // the branch matches nothing (the safe-deny path). Primitives resolve as today.
+      if (isMarker && rv !== null && typeof rv === "object") return null;
       out[key] = rv;
     }
   }
@@ -244,6 +250,24 @@ function pkOf(schema: SchemaDef | undefined, entity: string): string {
   return "id";
 }
 
+/** Reject a relation `where` that filters the target on a column it can't read —
+ * anywhere in the clause, including inside nested AND/OR groups (else a hidden/
+ * unreadable column is LIKE-oracle'able through the subquery). Nested relation keys
+ * are skipped: they're re-scoped against THEIR own target's read scope downstream.
+ * Mirrors Db.assertReadableWhere's recursion for the top-level user `where`. */
+function assertReadableRelationWhere(where: Record<string, unknown>, target: string, fields: string[], ctx: AclContext): void {
+  const targetRels = (ctx.schema?.[target]?.relations ?? {}) as Record<string, unknown>;
+  for (const [k, v] of Object.entries(where)) {
+    if (k === "AND" || k === "OR") {
+      for (const g of v as Record<string, unknown>[]) assertReadableRelationWhere(g, target, fields, ctx);
+    } else if (targetRels[k]) {
+      continue;
+    } else if (!fields.includes(k)) {
+      throw new AclDenied(target, "read", k);
+    }
+  }
+}
+
 /** Compile a relation predicate `{ rel: { … } }` to a subquery, AND-merging the
  * related entity's read scope (and rejecting filters on fields it can't read) so
  * traversal can never widen access beyond a direct read of the target. */
@@ -268,11 +292,7 @@ function relationPredicate(rel: RelationDef, nested: unknown, parentEntity: stri
       inner = FALSE; // can't filter through a relation you can't read
     } else {
       if (tScope.fields !== null) {
-        const targetRels = (ctx.schema?.[rel.target]?.relations ?? {}) as Record<string, unknown>;
-        for (const k of Object.keys(nested as Record<string, unknown>)) {
-          if (k === "AND" || k === "OR" || targetRels[k]) continue;
-          if (!tScope.fields.includes(k)) throw new AclDenied(rel.target, "read", k);
-        }
+        assertReadableRelationWhere(nested as Record<string, unknown>, rel.target, tScope.fields, ctx);
       }
       if (tScope.where) inner = and(inner, tScope.where);
     }

package/src/runtime/db.ts

@@ -32,7 +32,9 @@ import {
   compileExpr,
   compileSelect,
   eq,
+  FALSE,
   inList,
+  isNull,
   or,
   TRUE,
   type AggFn,
@@ -147,15 +149,28 @@ function decodeCursor(s: string): unknown[] {
   }
 }
 
+// Strictly-after predicate for a single order column, NULL-aware. SQLite sorts
+// NULLs FIRST for ASC and LAST for DESC, so a naive `col > v` (which is NULL, never
+// TRUE, when col or v is NULL) would re-match already-seen NULL rows forever.
+//   ASC:  v null    -> any non-null row is after it        (col IS NOT NULL)
+//         v non-null-> col > v (NULL cols excluded, they sort before)
+//   DESC: v null    -> nothing is strictly after a null    (FALSE; PK tiebreak advances)
+//         v non-null-> col < v OR col IS NULL (nulls sort after all non-nulls)
+function keysetCmp(o: OrderBy, value: unknown): SqlExpr {
+  const desc = o.dir === "desc";
+  if (value === null) return desc ? FALSE : isNull(o.column, true);
+  return desc ? or(cmp("<", o.column, value), isNull(o.column)) : cmp(">", o.column, value);
+}
+
 // Strictly-after predicate for a composite key: lexicographic comparison,
-// e.g. (a,b) after (a0,b0) => a>a0 OR (a=a0 AND b>b0); DESC columns flip to <.
+// e.g. (a,b) after (a0,b0) => a>a0 OR (a=a0 AND b>b0); DESC columns flip to <. Each
+// column's comparison and the eq-tiebreaker are NULL-aware (eq() maps null→IS NULL).
 function keysetAfter(order: OrderBy[], values: unknown[]): SqlExpr {
   const ors: SqlExpr[] = [];
   for (let i = 0; i < order.length; i++) {
     const parts: SqlExpr[] = [];
     for (let j = 0; j < i; j++) parts.push(eq(order[j]!.column, values[j]));
-    const o = order[i]!;
-    parts.push(o.dir === "desc" ? cmp("<", o.column, values[i]) : cmp(">", o.column, values[i]));
+    parts.push(keysetCmp(order[i]!, values[i]));
     ors.push(parts.length === 1 ? parts[0]! : and(...parts));
   }
   return ors.length === 1 ? ors[0]! : or(...ors);
@@ -247,6 +262,10 @@ export class Db<S extends SchemaDef = SchemaDef> {
    * and the keyset cursor would otherwise expose a hidden column's values). Columns
    * granted only conditionally are NOT orderable. */
   private assertReadableCols(from: string, scope: Scope, cols: string[]): void {
+    // Hidden columns are never readable through the ORM — not orderable either,
+    // regardless of scope (else the order/keyset cursor leaks the hidden value).
+    const hidden = new Set(this.hiddenColsOf(from));
+    for (const c of cols) if (hidden.has(c)) throw new AclDenied(from, "read", c);
     if (scope.fields === null) return;
     for (const c of cols) if (!scope.fields.includes(c)) throw new AclDenied(from, "read", c);
   }
@@ -344,6 +363,15 @@ export class Db<S extends SchemaDef = SchemaDef> {
       }
     }
 
+    // Hidden columns are never readable through the ORM — reject group-by / aggregating
+    // them UNCONDITIONALLY (independent of scope.fields, which is null under full/SYSTEM
+    // read), else min/max/groupBy over a hidden column exposes its values.
+    const hiddenCols = new Set(this.hiddenColsOf(from));
+    for (const c of groupBy) if (hiddenCols.has(c)) throw new AclDenied(from, "read", c);
+    for (const agg of Object.values(spec.aggregations)) {
+      if (agg.column && hiddenCols.has(agg.column as string)) throw new AclDenied(from, "read", agg.column as string);
+    }
+
     if (scope.fields) {
       const refs = new Set<string>(groupBy);
       for (const agg of Object.values(spec.aggregations)) if (agg.column) refs.add(agg.column as string);
@@ -362,7 +390,29 @@ export class Db<S extends SchemaDef = SchemaDef> {
     // subqueries), then AND-merges the entity's own ACL row scope.
     if (userWhere) this.assertReadableWhere(from, scope, userWhere);
     const userExpr: SqlExpr = userWhere ? compileScopedWhere(userWhere as Record<string, unknown>, from, this.acl) : TRUE;
-    return scope.where ? and(userExpr, scope.where) : userExpr;
+    const where = scope.where ? and(userExpr, scope.where) : userExpr;
+    // A relation-traversal `where` (or a relation-traversing ACL scope) compiles to a
+    // `sub` node over another table. Record those tables in `touched` so the live-query
+    // layer re-checks the subscription when the traversed table changes — else a write
+    // there never intersects the sub's read-set and the client stays stale.
+    this.addTouchedTables(where);
+    return where;
+  }
+
+  /** Walk a compiled predicate and add every relation-subquery target table to
+   * `touched` (the live-query read-set). Recurses into nested subqueries. */
+  private addTouchedTables(expr: SqlExpr | null | undefined): void {
+    if (!expr) return;
+    switch (expr.t) {
+      case "sub":
+        this.touched.add(expr.from);
+        this.addTouchedTables(expr.where);
+        break;
+      case "and":
+      case "or":
+        for (const p of expr.parts) this.addTouchedTables(p);
+        break;
+    }
   }
 
   /** Reject a user `where` that filters on a column the caller cannot read (closes
@@ -401,6 +451,16 @@ export class Db<S extends SchemaDef = SchemaDef> {
       .map(([n]) => n);
   }
 
+  /** Boolean columns — stored as INTEGER 0/1 (SQLite has no boolean), decoded back to
+   * true/false on read so handlers see the `boolean` the InferRow type promises. */
+  private boolColsOf(table: string): string[] {
+    const fields = this.schema[table]?.fields;
+    if (!fields) return [];
+    return Object.entries(fields)
+      .filter(([, f]) => (f as FieldDef).type === "boolean")
+      .map(([n]) => n);
+  }
+
   /** Columns marked `hidden()` — never projected on an ORM read (even SYSTEM/full). */
   private hiddenColsOf(table: string): string[] {
     const fields = this.schema[table]?.fields;
@@ -487,7 +547,8 @@ export class Db<S extends SchemaDef = SchemaDef> {
 
   private decodeRows(table: string, rows: Row[]): Row[] {
     const cols = this.jsonColsOf(table);
-    if (cols.length === 0) return rows;
+    const boolCols = this.boolColsOf(table);
+    if (cols.length === 0 && boolCols.length === 0) return rows;
     for (const row of rows) {
       for (const c of cols) {
         const v = row[c];
@@ -499,6 +560,12 @@ export class Db<S extends SchemaDef = SchemaDef> {
           }
         }
       }
+      // INTEGER 0/1 -> boolean (leave NULL as null for a nullable bool column).
+      for (const c of boolCols) {
+        const v = row[c];
+        if (typeof v === "number") row[c] = v !== 0;
+        else if (typeof v === "bigint") row[c] = v !== 0n;
+      }
     }
     return rows;
   }
@@ -556,7 +623,9 @@ export class Db<S extends SchemaDef = SchemaDef> {
     const scope = this.acl.system ? ALLOW_ALL : resolveRelationScope(this.acl, parentEntity, relName, rel.target);
     if (!scope.allowed) throw new AclDenied(rel.target, "read");
 
-    const project = (row: Row): Row => projectRow(row, effectiveFields(scope, row, this.acl.identity));
+    // Strip hidden() columns from the relation load, like every other read path —
+    // projectRow alone keeps them under a full/allow()/SYSTEM scope (fields === null).
+    const project = (row: Row): Row => this.stripHidden(rel.target, projectRow(row, effectiveFields(scope, row, this.acl.identity)));
     // One IN query per relation (no N+1). Match column before projecting (which
     // may drop the join column).
     const fetchBy = async (col: string, values: unknown[]): Promise<Array<{ key: unknown; row: Row }>> => {
@@ -574,14 +643,16 @@ export class Db<S extends SchemaDef = SchemaDef> {
       for (const { key, row } of await fetchBy(this.pkOf(rel.target), keys)) byId.set(key, row);
       for (const r of rows) r[relName] = r[rel.column] != null ? (byId.get(r[rel.column]) ?? null) : null;
     } else {
-      // hasMany: target[column] -> parent.id
-      const ids = [...new Set(rows.map((r) => r.id).filter((v) => v != null))];
+      // hasMany: target[column] -> parent.<pk> (NOT hardcoded `id` — a parent keyed by
+      // slug/username would otherwise join on an undefined `r.id` and get []).
+      const pk = this.pkOf(parentEntity);
+      const ids = [...new Set(rows.map((r) => r[pk]).filter((v) => v != null))];
       const grouped = new Map<unknown, Row[]>();
       for (const { key, row } of await fetchBy(rel.column, ids)) {
         const bucket = grouped.get(key) ?? grouped.set(key, []).get(key)!;
         bucket.push(row);
       }
-      for (const r of rows) r[relName] = grouped.get(r.id) ?? [];
+      for (const r of rows) r[relName] = grouped.get(r[pk]) ?? [];
     }
   }
 

package/src/runtime/ddl.ts

@@ -15,14 +15,27 @@ export const sqlType = (f: FieldDef): string =>
       ? "TEXT"
       : f.type.toUpperCase();
 
-/** Render a DEFAULT literal. Strings are single-quote-escaped; booleans → 0/1. */
-function defaultLiteral(v: DefaultValue): string {
+/** Render a DEFAULT literal. Strings are single-quote-escaped; booleans → 0/1.
+ * Exported for the migrator, which reconstructs a column's expected DEFAULT text to
+ * compare against the live `PRAGMA table_info.dflt_value`. */
+export function defaultLiteral(v: DefaultValue): string {
   if (v === null) return "NULL";
   if (typeof v === "boolean") return v ? "1" : "0";
   if (typeof v === "number") return String(v);
   return `'${v.replace(/'/g, "''")}'`;
 }
 
+/** The SQL text of a column's DEFAULT value (the part after `DEFAULT `), or null when
+ * the column declares no default. A raw-SQL `defaultExpr` is returned unquoted (e.g.
+ * `datetime('now')`); a literal `default` is rendered via {@link defaultLiteral}. Used
+ * by the migrator both to detect a default add/change on an existing column and to
+ * COALESCE-backfill a NOT NULL column during a rebuild. */
+export function defaultSqlValue(f: FieldDef): string | null {
+  if (f.defaultExpr !== undefined) return f.defaultExpr;
+  if (f.default !== undefined) return defaultLiteral(f.default);
+  return null;
+}
+
 /** The ` DEFAULT x` fragment for a column, or "" when it has no default. A raw-SQL
  * `defaultExpr` (e.g. `datetime('now')`) is emitted UNQUOTED; a literal `default` is
  * quote-escaped. UNIQUE/index are NOT inline — they're emitted as separate index
@@ -65,11 +78,15 @@ export function indexName(table: string, col: string): string {
 }
 
 /** CREATE [UNIQUE] INDEX statements for a table's unique/index columns (idempotent
- * via IF NOT EXISTS). Unique wins if a column declares both. */
-export function indexStatements(table: string, def: { fields: EntityFields }): string[] {
+ * via IF NOT EXISTS). Unique wins if a column declares both. `skipCols` omits specific
+ * columns — the migrator uses it to avoid emitting a UNIQUE index that would throw
+ * (duplicate values present on a column that just gained `unique()`); that delta is
+ * reported as skipped instead. */
+export function indexStatements(table: string, def: { fields: EntityFields }, skipCols?: ReadonlySet<string>): string[] {
   const out: string[] = [];
   for (const [col, f] of Object.entries(def.fields)) {
     if (!f.unique && !f.index) continue;
+    if (skipCols?.has(col)) continue;
     const kind = f.unique ? "UNIQUE INDEX" : "INDEX";
     out.push(`CREATE ${kind} IF NOT EXISTS ${quoteIdent(indexName(table, col))} ON ${quoteIdent(table)} (${quoteIdent(col)})`);
   }