@fitzzero/quickdraw-core 5.0.0-rc.1 → 5.0.0-rc.3

package/README.md

@@ -716,7 +716,10 @@ export const taskService = qd.defineService(task, {
   (`qd:access`).
 - Policies: `owner(field)`, `jsonAcl(field, { owner? })`,
   `members({ model, entry, user, level, levels? })`, `inherit({ from, via })`,
-  `anyOf(...)` and `resolver({ levelsFor, where? })`. Their column names are
+  `anyOf(...)`, `resolver({ levelsFor, where? })` and `everyone(level)`
+  (every signed-in user has `level` on every row, reading nothing: public
+  profiles are `anyOf(owner("id"), everyone("Read"))`; unlike `rowless: true`
+  on a method, it covers subscriptions and lists too). Their column names are
   checked against the Prisma client's models at compile time. A lookup is one
   batched query per table, memoized for the call, so checking 60 ids costs
   what checking one does. `entry` access needs a policy; a service without
@@ -766,7 +769,11 @@ tracked client as `db`; the server finds the rest on it.
   (`writes: ["taskLabel"]`); the `no-foreign-write` lint rule checks it.
 - Jobs, scripts and webhooks wrap their writes in `qd.run(fn)`, which
   flushes before it returns. A write made outside any unit of work flushes
-  on its own on the next tick, with a development warning.
+  on its own on the next tick, with a development warning. Inside a
+  handler `qd.run` joins the handler's unit; background work the reply does
+  not wait for (a push sent after a message, pruning what it reports dead)
+  runs in `qd.run(fn, { detached: true })`, a unit of its own that flushes
+  when `fn` settles (catch what the promise rejects with: nothing awaits it).
 
 <!-- example: apps/api/src/jobs/overdue.ts#run -->
 
@@ -828,14 +835,16 @@ export const taskService = qd.defineService(task, {
   // a write to a subtask sends its parent again
   affects: [{ service: task, id: "parentTaskId" }],
   project: {
-    // a relation count: read with select, built by a pure, synchronous map
+    // a relation count: read with select, built by a pure, synchronous map. Read the relation's
+    // ids, which Prisma fetches for the rows read only; its _count aggregates the whole TaskLabel
+    // table (a GROUP BY over every row) on every snapshot and flush
     card: {
-      select: { title: true, status: true, _count: { select: { labels: true } } },
-      map: (row: { id: string; title: string; status: string; _count: { labels: number } }) => ({
+      select: { title: true, status: true, labels: { select: { id: true } } },
+      map: (row: { id: string; title: string; status: string; labels: { id: string }[] }) => ({
         id: row.id,
         title: row.title,
         status: row.status,
-        labelCount: row._count.labels,
+        labelCount: row.labels.length,
       }),
     },
   },
@@ -848,13 +857,19 @@ export const taskService = qd.defineService(task, {
       handler: ({ input, db }) =>
         db.task.findUniqueOrThrow({
           where: { id: input.id },
-          select: { id: true, title: true, status: true, _count: { select: { labels: true } } },
+          select: { id: true, title: true, status: true, labels: { select: { id: true } } },
         }),
     },
   },
 });
 ```
 
+- A count over a relation reads the relation's ids (`labels: { select: { id: true } }`)
+  and counts them in `map`: Prisma reads them for the rows read only (a
+  second SQL query, `WHERE "taskId" IN (...)`). Its `_count` compiles to a
+  `GROUP BY` over the whole relation table, joined in, on every snapshot,
+  page and flush that reads the projection. For a relation too large to read
+  (a chat's members), keep a counter column that the writes maintain.
 - A projection's keys come from its schema's JSON Schema (Zod 4.2 or later),
   or from `project: { <name>: { keys } }`; a service whose projection has
   neither fails when it is defined. A handler returning a projection returns
@@ -959,6 +974,11 @@ export const taskService = qd.defineService(task, {
   ends in `id`; `limit` (default 100) and `maxLimit` (default 500) size its
   pages; `where` is an equality filter on membership; `access` is the level
   needed on the anchor (default `Read`).
+- A junction write adds or removes its entry in the one scope it links.
+  When the item reads the junction (a chat's `memberCount`), declare
+  `via({ model, entry, scope, refreshEntry: true })`: every junction write
+  then also sends the entry again, `updated`, to each scope that still
+  holds it, for one more read of the item per flush.
 - `qd:col:sub { s, c, scope }` authorizes the scope through its anchor's
   policy, then answers a page and joins the scope's room; flushes send `qd:c`
   deltas to it (`added`, `updated`, `patched`, `removed`, or `reset` for more
@@ -1105,7 +1125,9 @@ createMcpStdioServer({ registry, name: "my-app", version: "1.0.0" });
 
 - **stdio** speaks JSON-RPC (MCP protocol version 2024-11-05). One process is
   one session: its queries share one concurrency lane, and
-  `notifications/cancelled` cancels a call. Start its module through
+  `notifications/cancelled` cancels a call. When stdin ends, the calls still
+  running finish and their replies are written before `closed` resolves
+  (`server.close()` cancels them instead). Start its module through
   `bootstrapMcpServer(new URL("./mcp-server.js", import.meta.url))`, which
   sends console output to stderr so only the protocol reaches stdout.
 - **HTTP**: `GET /mcp/tools` and `POST /mcp/invoke`, which takes
@@ -1115,6 +1137,11 @@ createMcpStdioServer({ registry, name: "my-app", version: "1.0.0" });
   `"public"` methods, and custom tools that declare `access: "public"`; any
   other tool answers `UNAUTHENTICATED` before it runs. A failed call reaches
   the agent as a tool error carrying the code.
+- The tool list is the registry's, the same for every caller: `tools/list`
+  and `GET /mcp/tools` are not filtered by the principal, so an agent sees
+  tools it may not call (and its call is refused). Keep a tool out of the
+  list with `exclude` or `include`, per registry, and serve agents of
+  different reach from separate registries.
 
 ## The client
 
@@ -1153,6 +1180,7 @@ export function TaskDetail({ id }: { readonly id: string }) {
   if (isRemoved) {
     return <p>This task was deleted.</p>;
   }
+  // notes reach Admins only (the contract's fields), so its type is optional: guard it
   return (
     <div>
       <h1>{task?.title}</h1>
@@ -1166,6 +1194,10 @@ export function TaskDetail({ id }: { readonly id: string }) {
 }
 ```
 
+- A field the contract's `fields` map tiers (`notes` here) is optional in
+  every row type a reader gets (`useEntity`, collection items, `"entity"`
+  outputs, `EntityOf`, `ItemOf`), because a reader below its level receives
+  the row without it. Handlers still return the full row.
 - A mutation whose input has `id` and whose output is `"entity"` is
   optimistic by default: its input's fields show over the cached row and its
   collection items from the moment it is sent, are dropped if it fails, and
@@ -1784,6 +1816,15 @@ export function AdminTasks() {
   configurations written for 4.x still type); `id` and the
   timestamps come first and are not editable; `acl`, `serviceAccess` and
   `service_access` are hidden.
+- Grants: on a users service, `admin.handlers(user, { grants: true })`
+  shows and writes the entity's `serviceAccess` (a `json` field the entity
+  schema checks), so the admin screen edits grants through `adminUpdate`.
+  Only a caller whose own service-wide grant on that service is `Admin`
+  reads or writes it, whatever `access` gives the method: anyone else gets
+  rows without it and `FORBIDDEN` for a write, filter or sort naming it.
+  The write is tracked, so with `auth.serviceAccessSource` naming the column
+  the user's open sockets get the new grants at once, on every node. Such
+  an Admin can grant any service, themself included.
 - `adminSubscribers({ id })` counts the sockets subscribed to a row per
   access level (`{ id, count, levels, complete }`; behind a Redis adapter
   the counts are this server's and `complete` is `false`), and
@@ -1830,7 +1871,11 @@ export const task = defineContract("taskService", {
       requires: { room: (cursor) => `board:${cursor.projectId}` },
     },
   },
-  events: { cursorMoved: { payload: cursorSchema } },
+  events: {
+    cursorMoved: { payload: cursorSchema },
+    // a user's last socket left a board: `onRoomLeave` sends it
+    leftBoard: { payload: z.object({ projectId: z.string(), userId: z.string() }) },
+  },
 });
 ```
 
@@ -1934,14 +1979,69 @@ export function TaskRoom({
   `ctx.rooms.join(room)` and `leave` put the calling socket in an app room
   (calls without a socket get `false`; names starting with `qd:` or `user:`
   are refused with `VALIDATION`; at most 100 per socket; a method that shares
-  its runs, `share`, may not join or leave: `INTERNAL`), and the room's
-  sockets get `qd:presence` frames: the list on joining, then who joins and
-  who leaves. `usePresence(room)` shows them.
+  its runs, `share`, may not join or leave with its caller's socket:
+  `INTERNAL`), and the room's sockets get `qd:presence` frames: the list on
+  joining, then who joins and who leaves. `usePresence(room)` shows them.
 - Events: `ctx.rooms.emit(room, contract, event, payload)` and
   `emitToUser(userId, ...)` check the payload first (`INTERNAL`, nothing
   sent, when it fails), then send the validated payload as
   `qd:event [service, event, payload]`; `useEvent` hears them.
 
+Code that is not a handler (a game loop, a timer, a job) reaches rooms
+through `qd.rooms` (also `server.rooms`), and `onRoomLeave` hears sockets
+leave:
+
+<!-- example: apps/api/src/services/kits/rooms.ts#rooms -->
+
+```ts
+import type { RoomLeaveHandler } from "@fitzzero/quickdraw-core/server";
+
+const boardRoom = (projectId: string): string => `board:${projectId}`;
+
+// a timer or a game loop's tick, outside any handler: every socket in the room, on every node
+export function showCursor(projectId: string, taskId: string, x: number): void {
+  qd.rooms.emit(boardRoom(projectId), task, "cursorMoved", { projectId, taskId, x });
+}
+
+// a member removed from the project: their sockets leave its board on every node, so they hear
+// nothing more of it and its cursor channel drops their messages (also ctx.rooms.leave)
+export async function removeFromBoard(projectId: string, userId: string): Promise<void> {
+  await qd.rooms.leave(boardRoom(projectId), { userId });
+}
+
+// qd.createServer({ ..., onRoomLeave }): once per socket that leaves app rooms, in a unit of its own
+export const onRoomLeave: RoomLeaveHandler<AppPrincipal> = ({ principal, rooms }) => {
+  for (const { room, last } of rooms) {
+    // last: no socket of the user is in the room any more (a second tab keeps it false)
+    if (principal !== null && last && room.startsWith("board:")) {
+      const projectId = room.slice("board:".length);
+      qd.rooms.emit(room, task, "leftBoard", { projectId, userId: principal.userId });
+    }
+  }
+};
+```
+
+- `qd.rooms.emit` and `emitToUser` are `ctx.rooms`' own, from anywhere,
+  reaching every node behind a cluster adapter.
+- `leave(room, { userId })` (on `qd.rooms`, and on `ctx.rooms` beside the
+  calling socket's own `leave(room)`) takes every socket of the user out of
+  an app room, on every node: they hear nothing more of it, a channel that
+  `requires` the room drops their messages, each gets
+  `qd:presence { room, users: [] }`, and the room hears `left`. Behind a
+  cluster it is broadcast and answered, so await it before sending what the
+  user must not receive. Joining again is the app's to refuse.
+- `createServer({ onRoomLeave })` runs once per socket that leaves app
+  rooms, on the node that held it: its own `leave` (`reason: "leave"`), a
+  removal (`"removed"`), or a disconnect, which leaves every app room it was
+  in (`"disconnect"`; `qd:rotate` reconnects with a new socket). Each room
+  comes with `last`: true when no socket of that user is in the room any
+  more, on any node, which is what a game's `playerLeft` waits for. It runs
+  in a unit of work of its own (never the unit of the handler that left), a
+  throw is logged, and `close()` waits for it. Behind a cluster `last` is
+  decided by asking every node once the socket left, so two sockets of one
+  user leaving two nodes at the same moment may both see the other (a
+  removal never misses: each node reports its own last socket).
+
 ### Auth routes kit
 
 Sign-in for Google, Discord, a development mock and guests, as one Express
@@ -1976,7 +2076,8 @@ app.set("trust proxy", 1);
 app.use(
   createAuthRoutes({
     providers: [
-      google({ clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET }),
+      // nothing without its credentials: the routes skip it
+      google.optional({ clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET }),
       discord({ clientId: env.DISCORD_CLIENT_ID, clientSecret: env.DISCORD_CLIENT_SECRET }),
       // served only while isMockOAuthEnabled()
       mock({ listUsers: listSeededUsers }),
@@ -2025,7 +2126,7 @@ nothing is cached:
 | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
 | `GET /{provider}/start?returnTo=<url>` | 302 to the provider                                                                                                   |
 | `GET /{provider}/callback`             | 302 to `{origin}{successPath}` with the session cookie, or to `{origin}{errorPath}?error=state`, `denied` or `failed` |
-| `POST /guest`                          | `createUser(body)`, then `{ userId }` with the session cookie                                                         |
+| `POST /guest`                          | `createUser(body)`, then `{ userId, name? }` with the session cookie (and `token` with `guest({ token: true })`)      |
 | `GET /me`                              | `{ userId }`, or 401                                                                                                  |
 | `POST /logout`                         | 204: revokes the session, clears the cookie                                                                           |
 | `POST /logout-all`                     | 204: revokes every session of the user; 401 without a live session                                                    |
@@ -2074,6 +2175,27 @@ nothing is cached:
   `allowMissingOrigin: true` is set for native clients that keep cookies.
   Bearer tokens need no Origin, and HTTP calls are guarded by their JSON
   content type instead.
+- `socketAuth({ devCredentials })` signs a socket in by the user id its
+  handshake names (`auth: { userId }`, no token), as the function answers
+  (the principal, or `null` to refuse): for a game editor or load-test bots
+  in development. `socketAuth` throws when it is given while `NODE_ENV` is
+  `production`, and refuses such a handshake there anyway; pass it only
+  behind the app's own flag.
+- `google.optional(...)` and `discord.optional(...)` build nothing when
+  neither credential is set (only one is a misconfiguration, refused), and
+  `providers` skips `undefined`, `null` and `false` entries, so an
+  environment without a provider's app leaves it out in place.
+- A guest's `createUser` may return `{ userId, name }` when the name it gave
+  differs from the one asked (a numbered one after a collision), and the
+  route answers it; `guest({ createUser, token: true })` also answers the
+  session's token, for clients that keep no cookies (a game engine, a page
+  in a third-party iframe), at the cost of the token being readable by the
+  page's scripts.
+- `requireSession({ sessions, jwtSecret })` guards the app's own REST
+  routes: the credential is read as `/me` reads it, the JWT verified once
+  and the session checked in the store, then `req.userId` and
+  `req.sessionId` are set; otherwise 401 `{ error: "UNAUTHENTICATED", message }`.
+  4.1's `createRequireAuth` stays for token-keyed sessions.
 - Rate limits: the sign-in routes share `createAuthLimiter({ max: 60 })` (60
   requests per 15 minutes per IP) and the session routes
   `createAuthStatusLimiter()` (120); pass `rateLimit: { signIn, session }`
@@ -2231,7 +2353,11 @@ it("lets the owner rename, members read, and nobody else in", async () => {
 
 `"deny"` (the default for everyone `allow` does not name) means
 `UNAUTHENTICATED` without a principal and `FORBIDDEN` with one. Mutations run
-for real, once per allowed principal: give inputs that can run again.
+for real, once per allowed principal: give inputs that can run again, or
+`input` as a function of the cell (`({ name, principal }) => input`, sync or
+async), called before each cell's call, that makes a row of its own (a task
+to delete, an unused name), so no cell depends on the order of the
+principals.
 
 ### Performance budgets
 
@@ -2514,7 +2640,9 @@ contracts from the method maps, `defineService` from the service classes,
 the typed client for the hooks, and a report of everything left to decide.
 [`MIGRATION.md`](../../MIGRATION.md) explains each step, the access mapping and
 the defaults that changed; [`UPGRADE-PROMPT.md`](../../UPGRADE-PROMPT.md) is the
-procedure for an agent.
+procedure for an agent. Both ship with the codemod, at
+`node_modules/@fitzzero/quickdraw-codemod/MIGRATION.md` and
+`node_modules/@fitzzero/quickdraw-codemod/UPGRADE-PROMPT.md`.
 
 ```bash
 bunx @fitzzero/quickdraw-codemod@next v5 .

package/dist/{admin-DufEkep0.d.ts → admin-BiVNyWdI.d.ts}

@@ -1,4 +1,4 @@
-import { e as StandardSchemaWithJSON, x as SortDirection, d as StandardSchemaV1, I as InferInput, c as InferOutput, L as RowSchema, Q as QueryDef, P as ProjectionList, p as MutationDef, A as AccessLevel, G as AnyContract, ak as MethodName } from './infer-CEfvP0_I.js';
+import { e as StandardSchemaWithJSON, x as SortDirection, d as StandardSchemaV1, I as InferInput, c as InferOutput, L as RowSchema, Q as QueryDef, P as ProjectionList, p as MutationDef, A as AccessLevel, G as AnyContract, al as MethodName } from './infer-Dlplloxi.js';
 
 /** A schema a kit generates: validation, and its JSON Schema. */
 type KitSchema<Input, Output = Input> = StandardSchemaWithJSON<Input, Output>;

package/dist/{auth-5yi_rUSM.d.ts → auth-DlFtykbn.d.ts}

@@ -1,7 +1,7 @@
 import { IncomingHttpHeaders, IncomingMessage } from 'node:http';
 import { Socket } from 'socket.io';
-import { A as AccessLevel } from './infer-CEfvP0_I.js';
-import { P as Principal, M as MaybePromise } from './types-CIq6xwng.js';
+import { A as AccessLevel } from './infer-Dlplloxi.js';
+import { P as Principal, M as MaybePromise } from './types-B3N6xKkl.js';
 
 /** A principal's service-wide grants by service name: `{ taskService: "Admin" }`. */
 type ServiceGrants = Readonly<Record<string, AccessLevel>>;

package/dist/{caller-JNTbbD37.d.ts → caller-D4cgj-Xl.d.ts}

@@ -1,7 +1,7 @@
-import { ad as Version, a5 as Revision } from './envelope-CR2A9lrd.js';
+import { ad as Version, a5 as Revision } from './envelope-CKQEC7e-.js';
 import { L as Logger } from './logger-BY28acW-.js';
-import { A as AccessLevel, G as AnyContract, w as CollectionWhere, O as OrderBy, k as MethodKind, d as StandardSchemaV1, ac as EventName, ad as EventPayloadOf, a6 as ChannelName, a7 as ChannelPayloadOf, at as StreamName, ah as IsScopedStream, as as StreamItemOf, aa as ContractMap, ak as MethodName, ag as InputOf, am as OutputOf } from './infer-CEfvP0_I.js';
-import { P as Principal, Q as QuickdrawTypes, M as MaybePromise, c as PrincipalOf, a as McpContext, T as Transport, C as ContextExtensionOf, b as McpContextOf, D as DbOf } from './types-CIq6xwng.js';
+import { A as AccessLevel, G as AnyContract, w as CollectionWhere, O as OrderBy, k as MethodKind, d as StandardSchemaV1, ac as EventName, ad as EventPayloadOf, a6 as ChannelName, a7 as ChannelPayloadOf, av as StreamName, ai as IsScopedStream, au as StreamItemOf, aa as ContractMap, al as MethodName, ah as InputOf, an as OutputOf } from './infer-Dlplloxi.js';
+import { P as Principal, Q as QuickdrawTypes, M as MaybePromise, c as PrincipalOf, a as McpContext, T as Transport, C as ContextExtensionOf, b as McpContextOf, D as DbOf } from './types-B3N6xKkl.js';
 
 /** What a development warning is about. */
 type DevWarningKind = "n-plus-one" | "unbounded-read" | "oversized-response" | "nested-write" | "ambient-write" | "batch-read" | "batch-create-many" | "repeated-call";
@@ -194,7 +194,7 @@ interface ForeignColumns {
     readonly columns: string;
 }
 /** The builder a policy came from. */
-type PolicyKind = "owner" | "jsonAcl" | "members" | "inherit" | "anyOf" | "resolver";
+type PolicyKind = "owner" | "jsonAcl" | "members" | "inherit" | "anyOf" | "resolver" | "everyone";
 /**
  * A service's access policy, from one of the builders. `Columns` names the
  * columns of the service's own model it reads and `Foreign` the other models
@@ -299,6 +299,8 @@ type CollectionScope = {
     readonly entry: string;
     /** The junction column holding the scope value. */
     readonly scope: string;
+    /** A junction write sends its entry again to every scope that still holds it (`via`'s `refreshEntry`). */
+    readonly refreshEntry: boolean;
 };
 /** One collection of a service: its contract declaration and the service's option, checked. */
 interface ServiceCollection {
@@ -574,12 +576,55 @@ interface Presence {
     /** The ids of the users with a socket in `room`, each once. */
     users(room: string): Promise<string[]>;
 }
+/** Whose sockets `rooms.leave(room, target)` takes out of a room: every socket of one user. */
+interface RoomTarget {
+    readonly userId: string;
+}
+/**
+ * App rooms from code that is not a handler (a game loop, a job, a webhook):
+ * `qd.rooms`, `server.rooms` and `dispatcher.rooms`, the half of `ctx.rooms`
+ * that needs no calling socket. Behind a cluster adapter each reaches every
+ * node.
+ *
+ * @example
+ * // a game loop's tick, outside any handler
+ * qd.rooms.emit(WORLD_ROOM, gameContract, "death", { id: playerId });
+ * // a moderator removed a member: their sockets stop hearing the room
+ * await qd.rooms.leave(chatRoom(chatId), { userId });
+ */
+interface ServerRooms {
+    /**
+     * Sends the contract's event to every socket in `room` as `qd:event`, on
+     * every node. The payload is checked against the event's schema first: a
+     * payload that fails it throws `INTERNAL` and nothing is sent. Without a
+     * server it does nothing more.
+     */
+    emit<C extends AnyContract, E extends EventName<C>>(room: string, contract: C, event: E, payload: EventPayloadOf<C, E>): void;
+    /** `emit` to every socket of one user (their `user:{userId}` room), on every node. */
+    emitToUser<C extends AnyContract, E extends EventName<C>>(userId: string, contract: C, event: E, payload: EventPayloadOf<C, E>): void;
+    /**
+     * Takes every socket of `target.userId` out of the app room `room`, on
+     * every node: they stop receiving the room's events and `qd:presence`
+     * frames, and a channel that `requires: { room }` drops their messages.
+     * Each socket taken out gets `qd:presence { room, users: [] }`, as after
+     * its own leave, and `onRoomLeave` hears of it with reason `"removed"`.
+     * Behind a cluster adapter the request is broadcast and answered: it
+     * resolves once every node took the user's sockets out (at most
+     * `cluster.timeoutMs`), so await it before emitting what the user must not
+     * receive. Room names are checked as `join` checks them (`VALIDATION`). A
+     * user with no socket in the room is nothing to do; joining again is the
+     * app's to refuse.
+     */
+    leave(room: string, target: RoomTarget): Promise<void>;
+}
 /**
  * `ctx.rooms` (RFC 0003 sections 3, 12.5 and 15): app-defined rooms the
  * calling socket joins and leaves, and typed room events. It replaces 4.1's
  * `emitToRoom` and `emitToUserRoom` (`legacy-src/server/BaseService.ts:378-441`).
+ * Everything that needs no calling socket is also on `qd.rooms`
+ * ({@link ServerRooms}).
  */
-interface ContextRooms {
+interface ContextRooms extends ServerRooms {
     /**
      * Puts the calling socket in an app-defined room (a lobby), so it receives
      * the room's events and `qd:presence` frames. Returns `false`, doing
@@ -592,16 +637,49 @@ interface ContextRooms {
     join(room: string): boolean;
     /** Takes the calling socket out of an app room; `false` when it was not in it, or the call has no socket. */
     leave(room: string): boolean;
+    /** See {@link ServerRooms.leave}: every socket of the user, on every node, from any call. */
+    leave(room: string, target: RoomTarget): Promise<void>;
+}
+/** Why a socket left app rooms, as `onRoomLeave` hears it. */
+type RoomLeaveReason = 
+/** The socket's own `ctx.rooms.leave(room)`. */
+"leave"
+/** `rooms.leave(room, { userId })` took its user out. */
+ | "removed"
+/** The socket disconnected (a closed tab, a lost network, `qd:rotate`, the server closing): every app room it was in. */
+ | "disconnect";
+/** One app room a socket left. */
+interface RoomLeft {
+    readonly room: string;
     /**
-     * Sends the contract's event to every socket in `room` as `qd:event`. The
-     * payload is checked against the event's schema first: a payload that
-     * fails it throws `INTERNAL` and nothing is sent. Without a server it does
-     * nothing more.
+     * True when no socket of the user is in the room any more, on any node:
+     * the user is gone from it, not just one of their sockets (another tab
+     * keeps it false). Always true for an anonymous socket. Behind a cluster
+     * adapter it is decided by asking every node once this socket left, as
+     * the room's `left` presence frame is; when they cannot be asked it is
+     * true. For a removal every node reports its own last socket of the user
+     * as last, so it is never missed and may come from more than one node.
      */
-    emit<C extends AnyContract, E extends EventName<C>>(room: string, contract: C, event: E, payload: EventPayloadOf<C, E>): void;
-    /** `emit` to every socket of one user (their `user:{userId}` room). */
-    emitToUser<C extends AnyContract, E extends EventName<C>>(userId: string, contract: C, event: E, payload: EventPayloadOf<C, E>): void;
+    readonly last: boolean;
 }
+/** What `onRoomLeave` receives: one socket leaving one or more app rooms. */
+interface RoomLeave<P = Principal> {
+    /** The socket's principal; `null` for an anonymous socket (a spectator). */
+    readonly principal: P | null;
+    /** The socket that left. */
+    readonly socketId: string;
+    readonly reason: RoomLeaveReason;
+    /** The app rooms it left: one for a leave or a removal, every one it was in for a disconnect. */
+    readonly rooms: readonly RoomLeft[];
+}
+/**
+ * `createServer`'s `onRoomLeave`: called once per socket that leaves app
+ * rooms, on the node that holds the socket, in a unit of work of its own
+ * (detached: never the unit of the handler whose `ctx.rooms.leave` caused
+ * it), after the room heard the socket go. `ctx` is a `qd.run` context. An
+ * error it throws is logged; a server's `close()` waits for it.
+ */
+type RoomLeaveHandler<P = Principal> = (leave: RoomLeave<P>, ctx: RunContext) => void | PromiseLike<void>;
 /** The arguments of a stream's `push`: `(scope, item)` for a scoped stream, `(item)` for a global one. */
 type StreamPushArgs<C extends AnyContract, K extends StreamName<C>> = IsScopedStream<C, K> extends true ? [scope: string, item: StreamItemOf<C, K>] : [item: StreamItemOf<C, K>];
 /** The arguments of a stream's `pushMany`: `(scope, items)` for a scoped stream, `(items)` for a global one. */
@@ -826,6 +904,26 @@ interface RunContext {
     readonly log: Logger;
     readonly principal: null;
 }
+/** Options of `qd.run(fn, options)` and `dispatcher.run(fn, options)`. */
+interface RunOptions {
+    /**
+     * Run `fn` in a unit of work of its own even inside a method call or a
+     * transaction: for background work a handler starts and does not await
+     * (a push sent after the reply, pruning what it reports dead). Its writes
+     * flush once `fn` settles, on their own, instead of joining the handler's
+     * unit, which may have flushed long before (they would then flush as
+     * ambient writes, with a development warning). A failed flush is logged.
+     * Default `false`: inside an open unit of work or transaction, `fn` joins
+     * it.
+     *
+     * @example
+     * // in a handler, not awaited: the reply does not wait for the push
+     * void qd.run(() => sendPushes(db, message), { detached: true }).catch((error) => {
+     *   ctx.log.error("Pushing the message failed", { error: String(error) });
+     * });
+     */
+    readonly detached?: boolean;
+}
 
 /**
  * The `fields` of a write whose changed fields are unknown, such as a
@@ -881,6 +979,14 @@ interface UnitOfWorkScope {
      * dispatcher's own calls throw. Without them, the attached dispatcher's.
      */
     readonly warnings?: DevWarnings;
+    /**
+     * A unit of its own even where another unit or a transaction is open (a
+     * handler's background work, `qd.run(fn, { detached: true })`): its writes
+     * flush when it does, never with the unit around it, and its statements
+     * are not counted there. Default `false`: a unit begun inside an open
+     * one joins it.
+     */
+    readonly detached?: boolean;
 }
 /**
  * The writes of one handler run. The dispatcher calls `run` once, with the
@@ -924,7 +1030,7 @@ interface UnitOfWorkFactory {
 }
 
 /** What a sink learns about a flush besides its writes: where they came from, and the flush's revision. */
-interface FlushInfo extends Omit<UnitOfWorkScope, "sink" | "warnings"> {
+interface FlushInfo extends Omit<UnitOfWorkScope, "sink" | "warnings" | "detached"> {
     /**
      * The flush's revision (RFC 0003 section 5.3, step 2), taken once for the
      * whole batch before any sink runs, so before any row is read.
@@ -972,4 +1078,4 @@ type CallerFor<T extends QuickdrawTypes> = T extends {
     readonly contracts: infer Contracts extends ContractMap;
 } ? Caller<Contracts[keyof Contracts]> : Caller<AnyContract>;
 
-export { DEFAULT_BULK_THRESHOLD as $, type AnyService as A, type ShareMode as B, type CountArgs as C, DevWarningError as D, type ChannelOptions as E, type FindManyArgs as F, type ChannelsRequired as G, type HandlerContext as H, type BaseContext as I, type CallerFor as J, type AccessPolicy as K, type AnyAccessPolicy as L, type ModelName as M, type PolicyColumns as N, type PolicyForeign as O, type Presence as P, type PolicyTools as Q, type RowLevels as R, type StorageAdapter as S, type RowAccess as T, type UnitOfWorkFactory as U, type AffectsLink as V, type WriteRecord as W, type ProjectedOutput as X, type Projection as Y, type TierGroup as Z, type Tiers as _, type StorageRow as a, type CollectionScope as a0, type ServiceCollection as a1, type ContextRooms as a2, type ContextServices as a3, type TouchOptions as a4, type ChannelAccess as a5, type ChannelContext as a6, type ChannelHandler as a7, type ChannelImplementation as a8, type ServiceChannel as a9, type ServiceStream as aa, type StreamPushArgs as ab, type StreamPushManyArgs as ac, type CallOptions as ad, type MethodCaller as ae, type ServiceCaller as af, type ForeignColumns as ag, type ForeignColumnsOf as ah, type MembershipRead as ai, type ParentLink as aj, type PolicyKind as ak, type PolicyReads as al, type RowLevel as am, type AccessForm as an, type AccessRequest as ao, type AuthenticatedAccess as ap, type EntryAccess as aq, type IdKeyOf as ar, type IdSelector as as, type ScopeAccess as at, type ServiceAccess as au, ANY_FIELD as av, type UnitOfWork as aw, type UnitOfWorkScope as ax, formatDevWarning as ay, N_PLUS_ONE_STATEMENTS as az, type StorageWhere as b, type StatementCount as c, type FlushSink as d, type FlushInfo as e, type Service as f, type DevWarning as g, type DevWarningKind as h, type Caller as i, type ServiceMethod as j, type AccessFilter as k, type RunContext as l, type StreamHandle as m, type AnyContext as n, type AccessEngine as o, type AppRooms as p, type StreamSubscriptions as q, type PolicyFor as r, storageOf as s, type RowForms as t, type AccessFor as u, type ModelColumn as v, type WatchAccess as w, type PublicAccess as x, type HandlerArgs as y, type CustomAccess as z };
+export { type Projection as $, type AnyService as A, type PublicAccess as B, type CountArgs as C, DevWarningError as D, type HandlerArgs as E, type FindManyArgs as F, type CustomAccess as G, type HandlerContext as H, type ShareMode as I, type ChannelOptions as J, type ChannelsRequired as K, type BaseContext as L, type ModelName as M, type CallerFor as N, type AccessPolicy as O, type Presence as P, type AnyAccessPolicy as Q, type RowLevels as R, type StorageAdapter as S, type PolicyColumns as T, type UnitOfWorkFactory as U, type PolicyForeign as V, type WriteRecord as W, type PolicyTools as X, type RowAccess as Y, type AffectsLink as Z, type ProjectedOutput as _, type StorageRow as a, type TierGroup as a0, type Tiers as a1, DEFAULT_BULK_THRESHOLD as a2, type CollectionScope as a3, type ServiceCollection as a4, type ContextRooms as a5, type ContextServices as a6, type TouchOptions as a7, type ChannelAccess as a8, type ChannelContext as a9, type ScopeAccess as aA, type ServiceAccess as aB, ANY_FIELD as aC, type UnitOfWork as aD, type UnitOfWorkScope as aE, formatDevWarning as aF, N_PLUS_ONE_STATEMENTS as aG, type ChannelHandler as aa, type ChannelImplementation as ab, type RoomLeave as ac, type RoomLeaveReason as ad, type RoomLeft as ae, type RoomTarget as af, type ServiceChannel as ag, type ServiceStream as ah, type StreamPushArgs as ai, type StreamPushManyArgs as aj, type CallOptions as ak, type MethodCaller as al, type ServiceCaller as am, type ForeignColumns as an, type ForeignColumnsOf as ao, type MembershipRead as ap, type ParentLink as aq, type PolicyKind as ar, type PolicyReads as as, type RowLevel as at, type AccessForm as au, type AccessRequest as av, type AuthenticatedAccess as aw, type EntryAccess as ax, type IdKeyOf as ay, type IdSelector as az, type StorageWhere as b, type StatementCount as c, type FlushSink as d, type FlushInfo as e, type Service as f, type DevWarning as g, type DevWarningKind as h, type Caller as i, type ServiceMethod as j, type AccessFilter as k, type RunContext as l, type RunOptions as m, type ServerRooms as n, type StreamHandle as o, type AnyContext as p, type AccessEngine as q, type AppRooms as r, storageOf as s, type StreamSubscriptions as t, type RoomLeaveHandler as u, type PolicyFor as v, type RowForms as w, type AccessFor as x, type ModelColumn as y, type WatchAccess as z };

package/dist/{chunk-UJQJM7EG.js → chunk-3ONXZP2X.js}

@@ -6,7 +6,8 @@ function via(junction) {
     kind: "via",
     model: junction.model,
     entry: junction.entry,
-    scope: junction.scope
+    scope: junction.scope,
+    ...junction.refreshEntry === void 0 ? {} : { refreshEntry: junction.refreshEntry }
   });
 }
 
@@ -27,4 +28,4 @@ export {
   CHANNEL_DEFAULT_RATE,
   isScopedStream
 };
-//# sourceMappingURL=chunk-UJQJM7EG.js.map
+//# sourceMappingURL=chunk-3ONXZP2X.js.map

package/dist/chunk-3ONXZP2X.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contract/collections.ts","../src/contract/realtime.ts"],"sourcesContent":["// Collection declarations for a contract (RFC 0003 section 7.1). A collection\n// is the rows of one service grouped by a scope value. Membership is declared\n// (a scope column or a junction table, plus an equality filter), never\n// computed by a function, so the framework knows which writes can move a row.\n// This replaces 4.1's `defineCollection({ resolveScopeId, checkScopeAccess,\n// snapshot, toItem })`.\n\nimport type { AccessLevel } from \"./access\";\n\n/** Page size of a collection snapshot when the collection sets no `limit`. */\nexport const DEFAULT_COLLECTION_LIMIT = 100;\n\n/** Largest page a client may ask for when the collection sets no `maxLimit`. */\nexport const DEFAULT_COLLECTION_MAX_LIMIT = 500;\n\n/**\n * A scope that comes from a junction table instead of a column on the row:\n * the rows of `model` link an entry (`entry` holds the row's id) to a scope\n * value (`scope`). For example, a chat appears in each member's list through\n * `via({ model: \"chatMember\", entry: \"chatId\", scope: \"userId\" })`.\n */\nexport interface ViaScope<\n  Model extends string = string,\n  Entry extends string = string,\n  Scope extends string = string,\n> {\n  readonly kind: \"via\";\n  readonly model: Model;\n  readonly entry: Entry;\n  readonly scope: Scope;\n  /**\n   * The item is computed from the junction (a member count): every junction\n   * write sends its entry again, whole, to each scope that still holds it.\n   * Without it a junction write only adds or removes the entry in the scope\n   * it links, so a count over the junction goes stale everywhere else.\n   */\n  readonly refreshEntry?: boolean;\n}\n\n/** What `via(...)` takes: the junction model, its entry and scope columns, and `refreshEntry`. */\nexport interface ViaOptions<\n  Model extends string = string,\n  Entry extends string = string,\n  Scope extends string = string,\n> {\n  /** The junction model, as the database client names it: `\"chatMember\"`. */\n  readonly model: Model;\n  /** The junction column holding the entry's id: `\"chatId\"`. */\n  readonly entry: Entry;\n  /** The junction column holding the scope value: `\"userId\"`. */\n  readonly scope: Scope;\n  /**\n   * Set when the item reads the junction, as a `memberCount` mapped from a\n   * relation count does: a junction create, update or delete then sends the\n   * entry again, as `updated`, to every scope that still holds it (one read\n   * of the entry's item per flush). Default `false`: a junction write adds\n   * or removes the entry for the scope it links, and nothing else.\n   */\n  readonly refreshEntry?: boolean;\n}\n\n/**\n * Declares a collection scope that comes from a junction table.\n *\n * @example\n * myChats: {\n *   scope: via({ model: \"chatMember\", entry: \"chatId\", scope: \"userId\", refreshEntry: true }),\n *   item: \"listItem\",\n *   order: [[\"id\", \"asc\"]],\n * }\n */\nexport function via<\n  const Model extends string,\n  const Entry extends string,\n  const Scope extends string,\n>(junction: ViaOptions<Model, Entry, Scope>): ViaScope<Model, Entry, Scope> {\n  return Object.freeze({\n    kind: \"via\",\n    model: junction.model,\n    entry: junction.entry,\n    scope: junction.scope,\n    ...(junction.refreshEntry === undefined ? {} : { refreshEntry: junction.refreshEntry }),\n  });\n}\n\nexport type SortDirection = \"asc\" | \"desc\";\n\n/**\n * Sort columns for the keyset cursor, ending in `id` so every row has a\n * unique position: `[[\"ordinal\", \"asc\"], [\"id\", \"asc\"]]`.\n */\nexport type OrderBy<Column extends string = string> = readonly [\n  ...(readonly [Column, SortDirection])[],\n  readonly [\"id\", SortDirection],\n];\n\n/** Who a view is evaluated for, on the client. */\nexport interface Viewer {\n  readonly userId: string;\n}\n\n/**\n * A view: a named pure predicate evaluated on the client over the index rows\n * of a scope (RFC 0003 section 7.5). `row` holds only `id` and the\n * collection's `index` fields, which the type enforces.\n */\nexport type ViewPredicate<Row> = (row: Row, who: Viewer) => boolean;\n\n/** The equality filter that decides membership, for example `{ archived: false }`. */\nexport interface CollectionWhere {\n  readonly [column: string]: string | number | boolean | null;\n}\n\n/** Any collection of any contract, as `defineContract` stores it. */\nexport interface CollectionDef {\n  /** A string column of the entity, or `via(...)` for a junction table. */\n  readonly scope: string | ViaScope;\n  /** The projection each item is sent as: `\"entity\"` or a named projection. */\n  readonly item: string;\n  /** Sort columns for the keyset cursor; the last one is `id`. */\n  readonly order: OrderBy;\n  /** Equality filter that decides membership. */\n  readonly where?: CollectionWhere | undefined;\n  /** Page size. Default {@link DEFAULT_COLLECTION_LIMIT}. */\n  readonly limit?: number | undefined;\n  /** Largest page a client may ask for. Default {@link DEFAULT_COLLECTION_MAX_LIMIT}. */\n  readonly maxLimit?: number | undefined;\n  /** Item fields sent for every member of the scope (RFC 0003 section 7.4). */\n  readonly index?: readonly string[] | undefined;\n  /** Named predicates over index rows. Requires `index`. */\n  readonly views?: { readonly [view: string]: ViewPredicate<never> } | undefined;\n  /** Level required on the scope's anchor row. Default `\"Read\"`, through the anchor's policy. */\n  readonly access?: AccessLevel | undefined;\n}\n","// Streams, channels and typed room events in a contract (RFC 0003 section\n// 12.5). A stream is server-to-client append-only data a subscriber receives\n// with a seed of recent items; a channel is fire-and-forget client-to-server\n// input (cursors, typing) behind a per-socket token bucket; an event is a\n// typed custom frame a handler sends to a room. 4.1 declared channels on the\n// service class (`legacy-src/server/BaseService.ts:915-942`) and typed room\n// events through the augmentable `QuickdrawEventMap`; here all three live in\n// the contract, so the client is typed from it.\n//\n// Methods, collections, streams, channels and events share one namespace:\n// the client exposes each as `qd.<service>.<name>`.\n\nimport type { AccessLevel } from \"./access\";\nimport type { AnyContract } from \"./defineContract\";\nimport type { StandardSchemaV1 } from \"./standardSchema\";\n\n/** The `scope` of a stream with one feed for the whole service: the default. */\nexport const GLOBAL_STREAM = \"global\";\n\n/** The most items a stream may keep per scope as the seed for new subscribers. */\nexport const STREAM_MAX_SEED = 1000;\n\n/** A channel's sustained rate when it declares none: messages per second per socket. */\nexport const CHANNEL_DEFAULT_RATE = 30;\n\n/**\n * Who may subscribe to a stream (RFC 0003 section 4.1's forms, as data). A\n * scoped stream's scope value is the row an `entry` or `scope` form is about:\n * `{ entry: L }` needs level `L` on the row of this service whose id is the\n * scope, `{ scope: L, of }` level `L` on that row of `of`'s service. A\n * stream that declares none is closed: no client may subscribe.\n */\nexport type StreamAccess =\n  | \"public\"\n  | \"authenticated\"\n  | {\n      readonly service: AccessLevel;\n      readonly entry?: undefined;\n      readonly scope?: undefined;\n      readonly of?: undefined;\n    }\n  | {\n      readonly entry: AccessLevel;\n      readonly service?: AccessLevel;\n      readonly scope?: undefined;\n      readonly of?: undefined;\n    }\n  | {\n      readonly scope: AccessLevel;\n      readonly of: AnyContract;\n      readonly service?: undefined;\n      readonly entry?: undefined;\n    };\n\n/** A server-to-client stream of append-only items (RFC 0003 section 12.5). */\nexport interface StreamDef<Item extends StandardSchemaV1 = StandardSchemaV1> {\n  /** One item's schema. Pushed items are checked against it before they are sent. */\n  readonly item: Item;\n  /**\n   * What a scope value is (`\"taskId\"`): the stream has one feed per scope.\n   * `\"global\"`, the default, makes one feed for the whole service.\n   */\n  readonly scope?: string;\n  /**\n   * How many of the latest items the server keeps per scope, in memory on\n   * each process, and sends a new subscriber first. Default 0; at most 1,000.\n   */\n  readonly seed?: number;\n  /** Send items volatile: dropped for a client whose connection is backed up. Default `false`. */\n  readonly volatile?: boolean;\n  /** Who may subscribe. Without it the stream is closed. */\n  readonly access?: StreamAccess;\n}\n\n/**\n * Where a channel requirement finds its row id or scope value in the parsed\n * payload: the name of a key holding a string, or a function of the payload.\n */\nexport type PayloadSelector = string | ((payload: never) => string | null | undefined);\n\n/**\n * The app room a channel requirement names: the room itself (`\"world\"`, a\n * game's one world), or a function of the parsed payload that returns it\n * (`(payload) => \\`lobby:${payload.lobbyId}\\``). Unlike a\n * {@link PayloadSelector}, a string here is the room's name, not a payload\n * key. A name starting with `qd:` or `user:` is never an app room: a literal\n * one is refused when the contract is defined, and a computed one drops the\n * message.\n */\nexport type RoomSelector = string | ((payload: never) => string | null | undefined);\n\n/**\n * What a channel message requires of the socket that sends it: a live\n * subscription (`qd:sub`) to the row of this service `entity` names, or\n * (`qd:col:sub`) to the scope of `collection` that `scope` names; or that\n * the socket is in the app room `room` names, which a method called over\n * that same socket joined with `ctx.rooms.join` (a room another socket of\n * the user joined does not count, and a reconnected socket is in none until\n * it joins again). Each is checked in memory against the sending socket's\n * own records, on the node it is connected to. A message whose payload names\n * none is dropped.\n */\nexport type ChannelRequires =\n  | {\n      readonly entity: PayloadSelector;\n      readonly collection?: undefined;\n      readonly scope?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly collection: string;\n      readonly scope: PayloadSelector;\n      readonly entity?: undefined;\n      readonly room?: undefined;\n    }\n  | {\n      readonly room: RoomSelector;\n      readonly entity?: undefined;\n      readonly collection?: undefined;\n      readonly scope?: undefined;\n    };\n\n/** A client-to-server fire-and-forget channel (RFC 0003 section 12.5). */\nexport interface ChannelDef<Payload extends StandardSchemaV1 = StandardSchemaV1> {\n  /** One message's schema. A message that fails it is dropped. */\n  readonly payload: Payload;\n  /** Messages one socket may send per second, sustained. Default 30. */\n  readonly ratePerSecond?: number;\n  /** How many messages one socket may send at once. Default twice `ratePerSecond`. */\n  readonly burst?: number;\n  /** What the sender must already be subscribed to, or the app room it must be in. */\n  readonly requires?: ChannelRequires;\n}\n\n/** A typed custom room event, delivered as `qd:event` (RFC 0003 section 8.3). */\nexport interface EventDef<Payload extends StandardSchemaV1 = StandardSchemaV1> {\n  readonly payload: Payload;\n}\n\n/** True when a stream has one feed per scope value; false for a global stream. */\nexport function isScopedStream(def: Pick<StreamDef, \"scope\">): boolean {\n  return def.scope !== undefined && def.scope !== GLOBAL_STREAM;\n}\n"],"mappings":";AAUO,IAAM,2BAA2B;AAGjC,IAAM,+BAA+B;AA0DrC,SAAS,IAId,UAA0E;AAC1E,SAAO,OAAO,OAAO;AAAA,IACnB,MAAM;AAAA,IACN,OAAO,SAAS;AAAA,IAChB,OAAO,SAAS;AAAA,IAChB,OAAO,SAAS;AAAA,IAChB,GAAI,SAAS,iBAAiB,SAAY,CAAC,IAAI,EAAE,cAAc,SAAS,aAAa;AAAA,EACvF,CAAC;AACH;;;AClEO,IAAM,gBAAgB;AAGtB,IAAM,kBAAkB;AAGxB,IAAM,uBAAuB;AAqH7B,SAAS,eAAe,KAAwC;AACrE,SAAO,IAAI,UAAU,UAAa,IAAI,UAAU;AAClD;","names":[]}

package/dist/{chunk-4QNDKNDK.js → chunk-5CXPEEWF.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-V3KNCTXJ.js";
 
 // src/version.ts
-var QUICKDRAW_VERSION = "5.0.0-rc.1";
+var QUICKDRAW_VERSION = "5.0.0-rc.3";
 
 // src/contract/names.ts
 function entityRoom(service, id, level) {
@@ -114,4 +114,4 @@ export {
   MAX_SUBSCRIBE_IDS,
   MAX_SCOPE_LENGTH
 };
-//# sourceMappingURL=chunk-4QNDKNDK.js.map
+//# sourceMappingURL=chunk-5CXPEEWF.js.map