@pramen/server 0.0.13 → 0.0.15

package/dist/durable-object.js

@@ -18,6 +18,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";
@@ -52,6 +53,14 @@ export class PramenDOBase extends DurableObject {
      * task context — a DO can't introspect its own idFromName. */
     identityPersisted = false;
     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. */
+    subsBySocket = new Map();
     constructor(ctx, env, app) {
         super(ctx, env);
         this.app = app;
@@ -124,7 +133,8 @@ export class PramenDOBase extends DurableObject {
         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 });
         }
         const name = new URL(request.url).pathname.replace(/^\/rpc\//, "");
@@ -134,10 +144,13 @@ export class PramenDOBase extends DurableObject {
         }
         try {
             const { result, kind, touched, enqueued } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(this.tenant), this.envBag, this.ctxFor(identity), 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) {
@@ -151,11 +164,13 @@ export class PramenDOBase extends DurableObject {
         await this.ctx.storage.setAlarm(Date.now() + 50);
     }
     /** 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. */
+     * 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). */
     taskCtx() {
         const 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 = {
             db,
             kv: this.kv,
             files: this.filesFor(this.tenant),
@@ -163,7 +178,9 @@ export class PramenDOBase extends DurableObject {
             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
      * task context is scoped correctly. No-op once loaded/persisted this instance. */
@@ -182,22 +199,34 @@ export class PramenDOBase extends DurableObject {
         this.identityLoaded = true;
     }
     /** 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. */
+     * (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). */
     async drainTasks() {
         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] };
     }
     async alarm() {
         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));
     }
     async handleDrain() {
         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));
@@ -224,18 +253,16 @@ export class PramenDOBase extends DurableObject {
         // 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();
         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:
@@ -243,6 +270,7 @@ export class PramenDOBase extends DurableObject {
         }
     }
     async webSocketClose(ws) {
+        this.subsBySocket.delete(ws); // release the in-memory subscription list for this socket
         ws.close();
     }
     async webSocketError(ws, error) {
@@ -256,19 +284,20 @@ export class PramenDOBase extends DurableObject {
     }
     // --- live-query internals ---
     async onSubscribe(ws, id, name, input) {
-        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) {
@@ -276,44 +305,65 @@ export class PramenDOBase extends DurableObject {
         }
     }
     async onCall(ws, id, name, input) {
-        const state = this.getState(ws);
+        const att = this.getAttachment(ws);
+        let outcome;
         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).
     async broadcast(touched) {
         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);
         }
     }
     // --- helpers ---
@@ -401,7 +451,9 @@ export class PramenDOBase extends DurableObject {
                     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));
@@ -418,6 +470,10 @@ export class PramenDOBase extends DurableObject {
                 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 });
@@ -458,16 +514,26 @@ export class PramenDOBase extends DurableObject {
             return null;
         }
     }
-    getState(ws) {
+    /** 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. */
+    getAttachment(ws) {
         return (ws.deserializeAttachment() ?? {
             identity: null,
             tenant: this.tenant,
             partition: this.partition,
-            subs: [],
         });
     }
-    setState(ws, state) {
-        ws.serializeAttachment(state);
+    setAttachment(ws, att) {
+        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. */
+    getSubs(ws) {
+        return this.subsBySocket.get(ws) ?? [];
+    }
+    setSubs(ws, subs) {
+        this.subsBySocket.set(ws, subs);
     }
     send(ws, msg) {
         ws.send(JSON.stringify(msg));

package/dist/index.d.ts

@@ -13,6 +13,10 @@ export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runt
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
 export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
+export { Queue, CloudflareQueueAdapter, MemoryQueueAdapter, createQueue, discoverQueueBindings } from "./runtime/queue";
+export type { QueueAdapter, QueueProducerBinding, QueueSendOptions, QueueSendRequest, QueueBatchOptions, QueueContentType } from "./runtime/queue";
+export { routeQueue, dispatchQueueBatch } from "./runtime/queue-consumer";
+export type { QueueContext, QueueHandler, QueueMessage, QueueBatch, AppQueueMap } from "./runtime/queue-consumer";
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 export { sqliteDialect, postgresDialect, DoSqliteDriver, D1Driver } from "./runtime/driver";
 export type { Driver, Dialect, Row } from "./runtime/driver";

package/dist/index.js

@@ -17,6 +17,9 @@ export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny,
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
 // --- mail (ctx.mail) ---
 export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+// --- queue (ctx.queue — Cloudflare Queues) ---
+export { Queue, CloudflareQueueAdapter, MemoryQueueAdapter, createQueue, discoverQueueBindings } from "./runtime/queue";
+export { routeQueue, dispatchQueueBatch } from "./runtime/queue-consumer";
 // --- errors ---
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 // --- substrate seam (advanced: bring your own SQL backend) ---

package/dist/pramen.d.ts

@@ -2,6 +2,7 @@ import { type Env } from "./worker";
 import { pramenDO, type DoEnv } from "./durable-object";
 import { type SchemaDef } from "./sdk/schema";
 import type { AppTaskMap, HandlerMap } from "./sdk/handlers";
+import type { AppQueueMap, QueueBatch } from "./runtime/queue-consumer";
 import type { Role } from "./sdk/acl";
 /** Injected into a public route's handler — forward a privileged mutation into the
  * tenant's DO without the handler importing any deploy-side code (so app.ts stays
@@ -36,6 +37,10 @@ export interface PramenApp {
     /** Deferred side-effect handlers keyed by `kind` — drained from the outbox after a
      * mutation enqueues via `ctx.tasks.enqueue`. For notification email, webhooks, etc. */
     tasks?: AppTaskMap;
+    /** Cloudflare Queues consumers keyed by queue name — process messages produced via
+     * `ctx.queue.send(...)`. Dispatched by `createPramen(app).queue` (a consumer is
+     * Worker-level: no `ctx.db`, reach a tenant via `ctx.callPrivileged`). */
+    queues?: AppQueueMap;
 }
 export type { Env, DoEnv };
 /** Build the deployable pair for an app. `scheduled` is a Cron Trigger entry that
@@ -44,5 +49,6 @@ export type { Env, DoEnv };
 export declare function createPramen(app: PramenApp): {
     fetch: (request: Request, env: Env) => Promise<Response>;
     scheduled: (event: unknown, env: Env) => Promise<void>;
+    queue: (batch: QueueBatch, env: Env) => Promise<void>;
     PramenDO: ReturnType<typeof pramenDO>;
 };

package/dist/pramen.js

@@ -20,5 +20,5 @@ import { validateTriggerTasks } from "./sdk/schema";
 export function createPramen(app) {
     validateTriggerTasks(app.schema, Object.keys(app.tasks ?? {})); // fail fast on a typo'd trigger task
     const worker = makeWorker(app);
-    return { fetch: worker.fetch, scheduled: worker.scheduled, PramenDO: pramenDO(app) };
+    return { fetch: worker.fetch, scheduled: worker.scheduled, queue: worker.queue, PramenDO: pramenDO(app) };
 }

package/dist/runtime/acl.js

@@ -145,6 +145,13 @@ function resolveMarkers(rule, identity, input) {
             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;
         }
     }
@@ -164,6 +171,26 @@ function pkOf(schema, entity) {
                 return n;
     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, target, fields, ctx) {
+    const targetRels = (ctx.schema?.[target]?.relations ?? {});
+    for (const [k, v] of Object.entries(where)) {
+        if (k === "AND" || k === "OR") {
+            for (const g of v)
+                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. */
@@ -189,13 +216,7 @@ function relationPredicate(rel, nested, parentEntity, ctx, depth) {
         }
         else {
             if (tScope.fields !== null) {
-                const targetRels = (ctx.schema?.[rel.target]?.relations ?? {});
-                for (const k of Object.keys(nested)) {
-                    if (k === "AND" || k === "OR" || targetRels[k])
-                        continue;
-                    if (!tScope.fields.includes(k))
-                        throw new AclDenied(rel.target, "read", k);
-                }
+                assertReadableRelationWhere(nested, rel.target, tScope.fields, ctx);
             }
             if (tScope.where)
                 inner = and(inner, tScope.where);

package/dist/runtime/db.d.ts

@@ -115,6 +115,9 @@ export declare class Db<S extends SchemaDef = SchemaDef> {
         aggregations: A;
     }): Promise<AggregateResult<FieldsOf<S[T]>, G, A>[]>;
     private readWhere;
+    /** Walk a compiled predicate and add every relation-subquery target table to
+     * `touched` (the live-query read-set). Recurses into nested subqueries. */
+    private addTouchedTables;
     /** Reject a user `where` that filters on a column the caller cannot read (closes
      * the same info-leak as ordering by a hidden column: a filter is an oracle for a
      * hidden field's values). Mirrors `assertReadableCols`. Relation keys are skipped
@@ -124,6 +127,9 @@ export declare class Db<S extends SchemaDef = SchemaDef> {
     private assertReadableWhere;
     private selectRaw;
     private jsonColsOf;
+    /** 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;
     /** Columns marked `hidden()` — never projected on an ORM read (even SYSTEM/full). */
     private hiddenColsOf;
     /** Drop hidden columns from a row (copying only if any are present). */

package/dist/runtime/db.js

@@ -11,7 +11,7 @@
 // which the live-query layer uses to decide which subscriptions to re-check.
 // Create a fresh Db per handler run so identity and `touched` are scoped.
 import { AclDenied, ALLOW_ALL, compileScopedWhere, effectiveFields, projectRow, resolveRelationScope, resolveScope, resolveWriteRules, } from "./acl";
-import { and, cmp, compileAggregate, compileCount, compileExpr, compileSelect, eq, inList, or, TRUE, } from "./read-engine";
+import { and, cmp, compileAggregate, compileCount, compileExpr, compileSelect, eq, FALSE, inList, isNull, or, TRUE, } from "./read-engine";
 import { BadRequest } from "./errors";
 import { enqueueTask } from "./outbox";
 import { partitionOf, triggersOf, triggerFires } from "../sdk/schema";
@@ -48,16 +48,29 @@ function decodeCursor(s) {
         throw new BadRequest("invalid cursor");
     }
 }
+// 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, value) {
+    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, values) {
     const ors = [];
     for (let i = 0; i < order.length; i++) {
         const parts = [];
         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);
@@ -140,6 +153,12 @@ export class Db {
      * and the keyset cursor would otherwise expose a hidden column's values). Columns
      * granted only conditionally are NOT orderable. */
     assertReadableCols(from, scope, cols) {
+        // 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)
@@ -223,6 +242,17 @@ export class Db {
                 throw new BadRequest(`cannot aggregate a json column: ${agg.column}`);
             }
         }
+        // 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))
+                throw new AclDenied(from, "read", agg.column);
+        }
         if (scope.fields) {
             const refs = new Set(groupBy);
             for (const agg of Object.values(spec.aggregations))
@@ -243,7 +273,30 @@ export class Db {
         if (userWhere)
             this.assertReadableWhere(from, scope, userWhere);
         const userExpr = userWhere ? compileScopedWhere(userWhere, 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. */
+    addTouchedTables(expr) {
+        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
      * the same info-leak as ordering by a hidden column: a filter is an oracle for a
@@ -282,6 +335,16 @@ export class Db {
             .filter(([, f]) => f.type === "json" || f.type === "fileRef")
             .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. */
+    boolColsOf(table) {
+        const fields = this.schema[table]?.fields;
+        if (!fields)
+            return [];
+        return Object.entries(fields)
+            .filter(([, f]) => f.type === "boolean")
+            .map(([n]) => n);
+    }
     /** Columns marked `hidden()` — never projected on an ORM read (even SYSTEM/full). */
     hiddenColsOf(table) {
         const fields = this.schema[table]?.fields;
@@ -369,7 +432,8 @@ export class Db {
     }
     decodeRows(table, rows) {
         const cols = this.jsonColsOf(table);
-        if (cols.length === 0)
+        const boolCols = this.boolColsOf(table);
+        if (cols.length === 0 && boolCols.length === 0)
             return rows;
         for (const row of rows) {
             for (const c of cols) {
@@ -383,6 +447,14 @@ export class Db {
                     }
                 }
             }
+            // 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;
     }
@@ -441,7 +513,9 @@ export class Db {
         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) => 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) => 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, values) => {
@@ -462,15 +536,17 @@ export class Db {
                 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();
             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) ?? [];
+                r[relName] = grouped.get(r[pk]) ?? [];
         }
     }
     /** Insert a single row, returning the persisted row. */