@fitzzero/quickdraw-core 5.1.1 → 5.1.3

package/README.md

@@ -48,6 +48,7 @@ entries you import need.
 | `./server/otel`                         | `@opentelemetry/api`                                                    |
 | `./prisma`                              | `@prisma/client` 7                                                      |
 | `./client`                              | `socket.io-client`, `@tanstack/react-query` 5, `react` 19               |
+| `./client/core`                         | `socket.io-client`                                                      |
 | `./utils`, `./parser`                   | nothing more                                                            |
 | `./testing`                             | `socket.io`, `socket.io-client`                                         |
 | `./testing/client`                      | the `./client` peers, and `@testing-library/react`                      |
@@ -157,6 +158,8 @@ export interface AppPrincipal extends Principal {
 export const qd = initQuickdraw<{
   db: typeof db;
   principal: AppPrincipal;
+  // what the MCP bridge's context hook gives an agent's calls, as ctx.mcp
+  mcp: { readonly scopes: readonly string[] };
   contracts: typeof contracts;
 }>();
 ```
@@ -353,7 +356,9 @@ export const cardSchema = taskSchema.omit({ notes: true });
 
 The sessions, the secret and the grants the server reads,
 `apps/api/src/auth.ts`. Sessions are issued by the auth routes, mounted on
-the same `app` (see the [auth routes kit](#auth-routes-kit)):
+the same `app` (see the [auth routes kit](#auth-routes-kit)). `verifySession`
+checks a bearer token against the session store on every call
+(`bearerAuth`), so a signed-out or revoked session stops at once:
 
 <!-- example: apps/api/src/auth.ts -->
 
@@ -361,7 +366,7 @@ the same `app` (see the [auth routes kit](#auth-routes-kit)):
 // The app's sessions, token check and grants, for the README's server examples.
 
 import type { AccessLevel } from "@fitzzero/quickdraw-core";
-import { createMemorySessionStore, verifyJWT } from "@fitzzero/quickdraw-core/server/auth";
+import { bearerAuth, createMemorySessionStore } from "@fitzzero/quickdraw-core/server/auth";
 import { db } from "./db";
 import type { AppPrincipal } from "./quickdraw";
 
@@ -371,14 +376,17 @@ export const jwtSecret = process.env.JWT_SECRET ?? "";
 /** The sessions the auth routes issue. In production, a store over the database (see the auth routes kit). */
 export const sessions = createMemorySessionStore();
 
-/** The user a bearer token signs in, or `null` for no token. */
-export async function verifySession(token: unknown): Promise<AppPrincipal | null> {
-  if (typeof token !== "string") {
-    return null;
-  }
-  const payload = await verifyJWT(token, jwtSecret);
-  return payload === null ? null : { userId: payload.userId, kind: "user" };
-}
+/**
+ * The agent a bearer token signs in, or `null` for no token: checked against
+ * the session store on every call, so a signed-out or revoked session stops
+ * at once. An agent, so methods with `kinds: ["user"]` refuse it. Never
+ * `verifyJWT` alone, which checks no session.
+ */
+export const verifySession = bearerAuth({
+  sessions,
+  jwtSecret,
+  loadPrincipal: (userId): AppPrincipal => ({ userId, kind: "agent" }),
+});
 
 /** A user's service-wide grants, as stored in `User.serviceAccess`. */
 export async function loadGrants(userId: string): Promise<Record<string, AccessLevel>> {
@@ -422,6 +430,9 @@ model Project {
 }
 
 // A membership table: role holds an access level ("Read" | "Moderate" | "Admin").
+// It has an id, and its pair is unique by @@unique: the write tracker keys
+// rows by id, so a table keyed by a composite @@id is never tracked, and a
+// member removed from it would never be revoked.
 model ProjectMember {
   id        String  @id @default(cuid())
   projectId String
@@ -541,6 +552,9 @@ export const healthContract = defineContract("healthService", {
   because the client exposes each as `qd.<service>.<name>`. `subscribe`,
   `unsubscribe`, `call`, `then`, `useEntity`, `useEntities`, `admin` and
   names starting with `$` are reserved.
+- A service name holds no `:` or `@`: it is part of every room name of the
+  service (`qd:e:{service}:{id}@{level}`, `qd:c:{service}:{collection}:{scope}`),
+  which must split one way only, so `defineContract` throws on one.
 - Schemas are any Standard Schema. A projection's keys, admin field
   metadata, MCP tool schemas and `quickdraw-docs` read Standard JSON Schema,
   which Zod 4.2 or later provides; a projection whose schema cannot describe
@@ -583,6 +597,10 @@ export const taskService = qd.defineService(task, {
       // instead of the dispatcher's callTimeoutMs (30 s)
       timeoutMs: 5_000,
       handler: async ({ input, ctx, db }) => {
+        // an agent's call carries its token's scopes as ctx.mcp; a user's call has none
+        if (ctx.mcp !== undefined && !ctx.mcp.scopes.includes("tasks")) {
+          throw new QuickdrawError("FORBIDDEN", "This token may not assign tasks");
+        }
         const found = await db.task.findUnique({ where: { id: input.id } });
         if (found === null) {
           // the caller receives the code
@@ -608,12 +626,26 @@ export const taskService = qd.defineService(task, {
   Each call runs the whole pipeline with transport `"internal"` (input
   check, access, handler, output check), so access is checked on the inner
   call too; its writes join the calling method's unit of work, so both
-  flush together once; and it is cancelled with `ctx.signal`. It is typed
-  by the `contracts` of `initQuickdraw`'s types, as `qd.caller` is.
+  flush together once; and it is cancelled with `ctx.signal`. It carries
+  the calling method's `ctx.mcp` as well: every call an MCP call makes
+  through `ctx.services`, nested ones included, sees the MCP call's fields
+  with transport `"internal"`, so tell a token's call apart by `ctx.mcp`,
+  never by `ctx.transport`. It is typed by the `contracts` of
+  `initQuickdraw`'s types, as `qd.caller` is.
 - `share: "caller"` runs identical concurrent calls of one principal once,
-  `share: "all"` across principals (not with `custom` access); `ttlMs` keeps
-  a shared result. Callers of a shared run whose levels hide the same fields
-  get one copy of its result, encoded once for all of their sockets.
+  `share: "all"` across principals; `ttlMs` keeps a shared result. A
+  `"all"` run's handler sees the first caller's `ctx` and every caller gets
+  its result, so a result shared across principals must depend on the
+  input only: it never reads `ctx.principal`, `ctx.services`, `ctx.mcp`,
+  `ctx.access` or a context field made from them (in development, reading
+  one of the first four warns `[quickdraw:shared-principal]`; copying or
+  logging the whole `ctx` reads them too). `"all"` is refused with
+  `custom` access and on the kit methods whose result depends on the caller
+  (the read/write kit's `list` and `getMany`, `search`, the sharing kit's
+  `listShares` and `listMembers`, the admin kit's `adminList` and
+  `adminGet`): give those `"caller"`. Callers of a shared run whose levels
+  hide the same fields get one copy of its result, encoded once for all of
+  their sockets.
   `version(input, ctx)` answers "not modified" for a query whose result the
   caller already holds.
 - Every call runs a pipeline: look up, concurrency (16 queries in flight per
@@ -728,13 +760,30 @@ export const taskService = qd.defineService(task, {
         db.task.update({ where: { id: input.id }, data: { assigneeId: ctx.principal.userId } }),
     },
     triage: {
-      // a check on a token's claims stays a custom form
-      access: custom(
-        (ctx, input) => ctx.principal.claims?.scope === "triage" && input.status !== "archived",
-      ),
+      // Moderate on the task's project, from a token that may triage: claims add to the form
+      access: { entry: "Moderate" },
+      claims: (claims, input) => claims?.scope === "triage" && input.status !== "archived",
       handler: ({ input, db }) =>
         db.task.update({ where: { id: input.id }, data: { status: input.status } }),
     },
+    assigned: {
+      // Read on the project the input names, asked through ctx.access; none named, the caller's
+      // own that they may still read
+      access: custom(
+        async (ctx, input) =>
+          input.projectId === undefined || (await ctx.access.can(project, input.projectId, "Read")),
+      ),
+      handler: async ({ input, ctx, db }) => {
+        const readable = await ctx.access.where(task, "Read");
+        if (readable === "none") return [];
+        return db.task.findMany({
+          where: {
+            AND: [{ assigneeId: ctx.principal.userId, projectId: input.projectId }, readable],
+          },
+          take: 100,
+        });
+      },
+    },
   },
 });
 ```
@@ -745,7 +794,10 @@ export const taskService = qd.defineService(task, {
   `{ scope: L, of, id }` (the level on a row of another service) and
   `custom(fn)`. Without a principal every form but `"public"` answers
   `UNAUTHENTICATED`; a principal that fails gets `FORBIDDEN`. The levels,
-  lowest first, are `Public`, `Read`, `Moderate` and `Admin`.
+  lowest first, are `Public`, `Read`, `Moderate` and `Admin`. A `custom`
+  form replaces the row check, and a service-wide `Admin` grant skips it: a
+  check on the caller's claims is `claims` (below), and one that needs the
+  caller's level on a row asks `ctx.access` (`assigned` above, and below).
 - `kinds`, beside `access`, says which kinds of principal
   (`principal.kind`) may call: `initQuickdraw({ kinds: ["user", "agent"] })`
   for every service the app defines, `defineService(contract, { kinds })`
@@ -758,26 +810,44 @@ export const taskService = qd.defineService(task, {
   `"public"` method takes no `kinds` of its own: a refused caller would call
   it signed out. A service's list also holds for its entity, collection,
   topic and stream subscriptions, and its channels drop the messages of
-  other kinds. A check on a claim, such as a token's `scope`, stays a
-  `custom` form (`triage` above).
+  other kinds.
+- `claims: (claims, input) => boolean`, beside `access` on a method, is a
+  requirement on the caller's verified claims (`principal.claims`, a
+  token's `scope`; `triage` above). It adds to the form, so `triage` needs
+  Moderate on the task's project and a triage token. It runs right after
+  `kinds`, outside the access engine, so no grant passes it, a service-wide
+  `Admin` grant included. Without a principal the call is
+  `UNAUTHENTICATED`; when it returns anything but `true`, `FORBIDDEN`. It is
+  synchronous, and a `"public"` method takes none. A token narrowed by
+  `claims` is narrowed only on the methods that declare it; elsewhere it
+  acts with its user's grants (`kinds` keeps a kind of token out).
 - On a service with a policy, a method whose input has `id` under a form
-  that checks no row (`"public"`, `"authenticated"`, `{ service: L }` below
-  `Admin`) would let anyone that form admits reach any row by its id, so
-  `defineService` refuses it, naming the method and the two ways out: a form
-  the policy decides (`{ entry: L }`, or `{ service: L, entry: L }` to keep
-  the grant), or `rowless: true` on the method when every such caller may
-  reach any row on purpose (the `title` method above; public profiles,
-  lookups by an id that tells nothing). A kit's methods take it as
+  that asks the policy nothing about the row that id names would let anyone
+  that form admits reach any row by its id, so `defineService` refuses it,
+  naming the method and the ways out. Those forms are the ones that check
+  no row (`"public"`, `"authenticated"`, `{ service: L }` below `Admin`),
+  `custom(fn)`, `{ scope, of, id }` (a row of another service) and
+  `{ entry, id }` naming another key. The ways out: a form the policy
+  decides (`{ entry: L }`, or `{ service: L, entry: L }` to keep the grant,
+  with `claims` beside it for a check on the caller's claims), or
+  `rowless: true` on the method when every such caller may reach any row on
+  purpose (the `title` method above; public profiles, lookups by an id that
+  tells nothing), or when `id` names a row the method creates (an id the
+  client made, under a `scope` form). A `rowless` query under a form that
+  checks no row also answers "not modified" for any `id`; under any other
+  form it runs its handler every time. A kit's methods take it as
   `rowless: ["get"]` in the kit's options. The input's keys come from its
   JSON Schema: an `id` in any branch of a union counts, and so does one
   beside a value JSON Schema cannot write (a `Date`, a `Set`). Not checked:
   an input without JSON Schema (Zod 3) or whose JSON Schema names no keys (a
   `todoSchema` without `keys`), one that is no object (a bare string
-  that is the id itself) and a row named by another key (`ids`, `taskId`, a
-  nested `where.id`).
-- A service-wide `Admin` grant passes every check on its service
-  (`adminBypass: false` turns that off). A grant below `Admin` counts only
-  where the form names `service`: a `Read` grant does not read every row.
+  that is the id itself), a row named by another key (`ids`, `taskId`, a
+  nested `where.id`) under a form that checks the row `id` names, and an
+  `entry` form whose `id` is a function, which names its row in code.
+- A service-wide `Admin` grant passes every access form on its service
+  (`adminBypass: false` turns that off), though not `kinds` or `claims`. A
+  grant below `Admin` counts only where the form names `service`: a `Read`
+  grant does not read every row.
 - Grants come from `principal.serviceAccess`, as `authenticate` returns it or
   `createServer({ auth: { loadServiceAccess } })` loads it for a principal
   that carries none: at a socket's handshake, for each HTTP call, and for
@@ -803,20 +873,51 @@ export const taskService = qd.defineService(task, {
   call, so checking 60 ids costs what checking one does. `entry` access
   needs a policy; a service without `model` may only use `"public"`,
   `"authenticated"`, `{ service }` and `custom`. `inherit` uses the
-  parent's policy only: grants on the parent's service do not flow down.
+  parent's policy only: grants on the parent's service do not flow down. A
+  membership table needs an `id` column (the pair unique by `@@unique`),
+  or its writes are not tracked and a removed member is never revoked.
 - One policy decides every surface: method calls, entity subscriptions,
   collection scopes, the kits' lists and searches, streams and channels.
-- When a tracked write lowers or removes someone's access, their sockets
-  leave the rooms anchored on that row and get `qd:revoked`; a changed level
-  moves them to that level's room. In a cluster the change is broadcast to
-  every node.
+- When a tracked write lowers or removes someone's access, a relation-form
+  foreign key included (`project: { connect }`), their sockets leave the
+  rooms anchored on that row and get `qd:revoked`; a changed level moves
+  them to that level's room. In a cluster the change is broadcast to every
+  node. Every socket's re-resolution settles before the flush's frames go
+  out, a failed one included.
 - `server.dispatcher.access` gives the same answers to other code:
   `levelsFor(service, principal, ids)`, `accessWhere(service, principal, level)`
   (a `where` filter for `findMany`, or `"none"`) and `onAccessChanged(listener)`.
+- `ctx.access` gives them to a handler or a `custom` form, as the caller:
+  `levelsFor(service, ids)`, `can(service, id, level)` and
+  `where(service, level)` are those bound to `ctx.principal`, with the
+  grants the call runs with (a socket's, or those an in-process caller
+  loaded); `service` is a contract or a service name. A form can then check
+  a row no `{ entry }` or `{ scope }` form names: a parent the input
+  names, or a key that is optional, as in `assigned` above, which passes
+  without a project and needs Read on one it names. Its handler adds
+  `where(task, "Read")` to its query with `AND`, so a list without a
+  project still follows the row policy. Never spread the filter into
+  `where`: it and the input both set `projectId`, and whichever comes last
+  wins, widening a list with a project or dropping the policy from one
+  without. `ctx.access` counts levels as
+  `{ entry }` does: a service-wide `Admin` grant reaches every row (with
+  `adminBypass`), a row that is not found gives anyone else no level
+  (`can` is `false`), and an anonymous caller has none anywhere (an empty
+  map, `false`, `"none"`). So a form that asks it about a parent counts a
+  service-wide `Admin` grant on the parent's service, which
+  `{ scope, of }` does not: prefer `{ scope: L, of, id }` when the input
+  always names the parent. A `custom` form is still no row check of the
+  method's own `id`: a method whose input has one needs `rowless: true`
+  beside it (above). Every method call has it, MCP and `ctx.services` calls
+  included, and so do the `ctx` the kits pass to their forms and callbacks;
+  a context no dispatcher built throws `INTERNAL` on its use, and `qd` has
+  none: a job asks `server.dispatcher.access`.
 - `createServer({ access: { cacheMs: 30_000 } })` keeps policy lookups across
   requests; tracked writes to the columns and membership tables the policies
   read evict them. Writes the tracked client cannot see are picked up only
-  when the time passes, so the cache is off by default.
+  when the time passes, so the cache is off by default. A lookup inside a
+  transaction (`db.$transaction`, a sharing change) reads the database,
+  never the cache.
 
 ## Tracked writes
 
@@ -882,8 +983,53 @@ export async function markStale(before: Date): Promise<number> {
 }
 ```
 
-- Not seen: nested writes (`{ labels: { create: [...] } }`, which warn in
-  development), raw SQL and database cascades. Record raw SQL with
+- A helper that writes takes the tracked client by its type. `trackPrisma`
+  returns `Tracked<C>`: still a `C` wherever one is asked for, while the
+  untracked client is no `Tracked<C>`. Type the helper's client
+  `Tracked<PrismaClient>`, or `TrackedTransaction<PrismaClient>` when it
+  may also run inside `db.$transaction(async (tx) => ...)`, whose `tx` is
+  one (`db` is one too), and the untracked client passed to it is a type
+  error. A helper typed `PrismaClient` takes either client. Both types are
+  type-only, on `./prisma` and on the root export, so a shared package
+  names them without Prisma. `no-untracked-write` reads the type too: a
+  parameter so typed may be named `prisma`.
+
+<!-- example: apps/api/src/jobs/overdue.ts#helper -->
+
+```ts
+import type { TrackedTransaction } from "@fitzzero/quickdraw-core/prisma";
+import type { PrismaClient } from "@project/db";
+
+// takes the tracked client, or a transaction's: passing the untracked `prisma` is a type error
+export async function reopenStale(
+  client: TrackedTransaction<PrismaClient>,
+  projectId: string,
+): Promise<number> {
+  const { count } = await client.task.updateMany({
+    where: { projectId, status: "stale" },
+    data: { status: "open" },
+  });
+  return count;
+}
+
+export async function restoreProject(projectId: string): Promise<number> {
+  return await qd.run(() =>
+    db.$transaction(async (tx) => {
+      await tx.project.update({ where: { id: projectId }, data: { archived: false } });
+      return await reopenStale(tx, projectId);
+    }),
+  );
+}
+```
+
+- Not seen: the related rows of a nested write
+  (`{ labels: { create: [...] } }`, which warns in development), raw SQL and
+  database cascades. A foreign key a nested write sets on the written row
+  (`project: { connect }`, `parent: { disconnect: true }`) is seen: such an
+  `update` or `upsert` reads the row's interested columns first, one more
+  statement. Before deleting a row, delete or clear through `db` the rows
+  a cascade would take with it (for the admin kit's `adminDelete`, in its
+  `prepare`). Record raw SQL with
   `ctx.touch("task", ids)`, or `{ removed: true }` for deleted rows. A job
   gets the same `touch` from `qd.run`, whose `fn` receives
   `{ touch, log, principal: null }`:
@@ -905,7 +1051,13 @@ export async function spreadOrdinals(projectId: string): Promise<void> {
 ```
 
 - Tracked models need a string `id` column; writes to other models pass
-  through untracked, with one warning.
+  through untracked, with one warning. Membership and junction tables
+  included: give them `id String @id @default(cuid())` and keep the pair
+  unique with `@@unique([...])`, never a composite `@@id`. `createServer`
+  checks, at start, every model a policy, a membership table or a `via`
+  junction depends on, and logs `[quickdraw:untracked-access-model]` as an
+  error, in every environment, for one it cannot track; a test app made
+  with `strictWarnings` fails to start.
 - `createServer({ flushSink })` adds the app's own sinks (an audit log, say);
   `createRecordingSink()` on `./testing` records what is flushed, for tests.
 
@@ -1003,7 +1155,14 @@ export const taskService = qd.defineService(task, {
   by `id`) comes from `versionColumn`, or from an in-process change log of
   recent flushes. The change log sees only this process's writes: an app
   running several processes without a Socket.IO cluster adapter declares
-  `versionColumn`s or passes `changeLog: false`.
+  `versionColumn`s or passes `changeLog: false`. For a query, it comes only
+  when its form checked the row `id` names (an `entry` form on `id`, a
+  `scope` form on the service's own rows by `id`, `{ service: "Admin" }`),
+  for a caller the service's `Admin` bypass passes, or for a `rowless`
+  method under a form that checks no row (`"public"`, `"authenticated"`,
+  `{ service: L }`): it answers before the handler runs, so it would tell
+  any other caller that the row exists and has not changed. Any other
+  query runs its handler.
 - Revisions are microseconds since the epoch: a flush takes
   `max(Date.now() * 1000, last + 1)`. Clients compare them as numbers.
 - Behind a cluster adapter (`setupRedisAdapter`), every touched row is read
@@ -1015,10 +1174,14 @@ export const taskService = qd.defineService(task, {
   Flushes take their revisions from a counter in the cluster's Valkey, on
   Valkey's clock in microseconds, so revisions from all nodes are one order;
   its key needs persistence or replication. A node whose Valkey connection
-  comes back has its clients reconnect to catch up.
+  comes back has its clients reconnect to catch up. Give each deployment its
+  own Valkey, or its own `cluster.keyPrefix` (which `setupRedisAdapter` takes
+  as its key): a node applies only its own deployment's events (once every
+  deployment that shares the Valkey runs this version), and a Valkey's `db`
+  does not separate pub/sub.
   [docs/deploying.md](https://github.com/fitzzero/quickdraw/blob/main/docs/deploying.md) has the wiring, what holds across
-  nodes, what it costs, and what happens when a node or Valkey stops
-  answering.
+  nodes, what it costs, what happens when a node or Valkey stops
+  answering, and a production checklist.
 
 ## Collections and change topics
 
@@ -1075,7 +1238,7 @@ export const taskService = qd.defineService(task, {
   collections: {
     // Read on the project opens its scope
     byProject: { anchor: projectContract },
-    // a user opens only the scope that is their id
+    // a user opens only the scope that is their id; its items still follow access above
     assigned: { scopeAccess: "self" },
   },
   // opens the service topic to Read grants; closed without it
@@ -1090,7 +1253,13 @@ export const taskService = qd.defineService(task, {
   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
+  Over the item service's own `members` table (a `members` read of the
+  policy, alone or inside `anyOf`, whose `entry` is the via's `entry` and
+  whose `user` is the via's `scope`), a link counts only when its
+  role gives at least the collection's `access`: a role change across that
+  line adds or removes the entry, and a link below it is in no page, count,
+  index, `qd:col:items` or scoped search. 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.
@@ -1099,13 +1268,35 @@ export const taskService = qd.defineService(task, {
   deltas to it (`added`, `updated`, `patched`, `removed`, or `reset` for more
   than `bulkThreshold` rows, default 200). A `"self"` scope is the
   subscriber's own user id: its items are stripped at `Read`, and it may not
-  declare a higher `access`.
-- Items are visible to everyone in the scope: no per-row policy or field
-  tier applies inside a collection. Derive the item service's own access
-  from the anchor (`inherit` from it, as above): a per-row policy on the item
-  service (an owner column, a row's access list) is not applied to
-  collection items, so a row it would hide still reaches everyone in its
-  scope.
+  declare a higher `access`. On a service with an access policy its items
+  still follow that policy: a page, `qd:col:items` and every flush hold only
+  the rows its user may read at `Read`. A row the user loses goes out
+  `removed`, and a change to their membership of a parent row (or a reload
+  of their grants) sends `reset`, so the list loads again; a client that
+  resumes the list after such a change reads a page. A change to a parent
+  row's own access columns (a project's owner or access list) reaches the
+  list only at the rows' next write or the list's next load.
+- `requires: { service: L }`, beside `anchor` or `scopeAccess`, also asks
+  for a service-wide grant of at least `L` on the collection's service, as
+  its methods under `{ service: L }` do: both checks must pass, and a
+  service-wide `Admin` passes either. It is for a list whose methods need
+  the grant, `mine: { scopeAccess: "self", requires: { service: "Read" } }`
+  beside methods under `{ service: "Read" }`; a list whose rows its users
+  read by their level on each row (`assigned` above) takes none. Without
+  the grant, `qd:col:sub` (cursor pages included), the scope's change
+  topic and a search kept to the scope are `FORBIDDEN`. The grant comes
+  from the socket's principal, never a read: when the user's grants reload
+  below it (`server.access.refresh`, a tracked write of the grants column,
+  on any node), each of their sockets leaves the scope with `qd:revoked`
+  (`reason: "access"`) and gets nothing more of it. A collection without
+  `requires` is unchanged.
+- Items are visible to everyone in an anchored scope: no per-row policy or
+  field tier applies inside it. Derive the item service's own access from
+  the anchor (`inherit` from it, as above): a per-row policy on the item
+  service (an owner column, a row's access list) is not applied to an
+  anchored scope's items, so a row it would hide still reaches everyone in
+  its scope. A `"self"` scope is the exception: its items follow the item
+  service's policy for its user.
 - `index` sends one small row per member (`[id, rev, ...fields]`, up to
   50,000) with the first page, so the client knows the whole membership and
   order at once; `views` are pure predicates over index rows the client runs.
@@ -1128,11 +1319,27 @@ export const taskService = qd.defineService(task, {
   changed it (`models`). The service topic is closed
   (`FORBIDDEN`) unless the service declares `watchAccess` (`"public"`,
   `"authenticated"` or `{ service: level }`). A watcher that loses access
-  leaves the topic after one last `qd:changed`.
+  leaves the topic after one last `qd:changed`. A watch whose access
+  changed while it was answered is authorized again before it joins the
+  topic, with the socket's principal as it is then, and answered
+  `FORBIDDEN` when it lost access; it hears nothing until it joins. Entity
+  and collection subscribes re-check the same way, with the grants the
+  socket holds then (a grant lowered mid-subscribe denies, a raised one
+  answers at its level), but from inside their room, which they need to
+  catch every change after the snapshot they read: a frame sent while they
+  re-check can reach a socket that is then refused, and the client drops
+  it with the refusal.
 - The socket rate limiter does not count subscription events; each socket
   runs `qd:sub`, `qd:col:sub`, `qd:col:items` and `qd:watch` in a lane
   instead: `limits.subscriptions` (8 at once, 64 waiting), then
-  `RATE_LIMITED`.
+  `RATE_LIMITED`. A socket holds at most 10,000 entity ids, 1,000
+  collection scopes, 1,000 topic watches and 500 stream feeds at once:
+  one more is `CONFLICT` (a `qd:sub` whose new ids would pass the cap is
+  refused whole, and a row that batches running at once left no room for
+  is answered `CONFLICT` on its own), one held already never counts again,
+  and `qd:hello`
+  announces the caps (`limits.subscriptions.maxEntityIds`, `maxScopes`,
+  `maxTopics`).
 
 ## The server and its transports
 
@@ -1151,21 +1358,38 @@ over three transports (design: sections 3, 8 and 10):
   events per minute per socket; channels, cancels and subscription events not
   counted); configure it with `rateLimit`, or turn it off with
   `rateLimit: false`. There is no default CORS origin: pass `cors`.
+  `peers: true` serves peer links between the clients of an app room
+  ([Peer links](#peer-links)).
+  Socket.IO's connection state recovery is refused: `createServer` throws
+  for `socket: { connectionStateRecovery }`, since a recovered socket would
+  come back with its principal and rooms without authenticating again, so a
+  revoked session or a lowered grant would return. Clients resume by
+  revision on every reconnect instead.
 - **HTTP**: `POST /qd/{service}/{method}` with the input as a JSON body and
   `Content-Type: application/json` (required, even without a body, so a
   cross-site page cannot use a session cookie without a CORS preflight). The
   principal comes from the session cookie (`__Host-session` over HTTPS,
   `session` over plain HTTP or with `COOKIE_DOMAIN`, as the auth routes name
   it) or an `Authorization: Bearer` token through the same
-  `authenticate`, which is told which one it was (`request.credential`):
-  `socketAuth` answers a cookie sent from a page outside `allowedOrigins`
-  with `FORBIDDEN`, as it refuses such a socket; the reply is `{ ok: true, d }` or
+  `authenticate`, which is told which one the transport chose
+  (`request.credential`): `socketAuth` answers a cookie sent from a page
+  outside `allowedOrigins` with `FORBIDDEN`, as it refuses such a socket.
+  The cookie is `auth.token` only for `socketAuth`'s `authenticate`; any
+  other finds it in `request.sessionCookie` alone, and `auth.token` holds
+  only a bearer token. The reply is `{ ok: true, d }` or
   `{ ok: false, e: { code, message, data? } }` with the code's HTTP status.
   Works on Express 4 and 5, and on a bare Node server. Move it with
   `http: { path }`, turn it off with `http: false`, or mount
   `createHttpRouter({ dispatcher, auth })` yourself. It has no rate limit of
   its own: on Express, set `http: { rateLimit: createCallLimiter() }` (from
-  `./server/express`), which refuses with the `RATE_LIMITED` reply.
+  `./server/express`), which refuses with the `RATE_LIMITED` reply. An app
+  without sockets makes its dispatcher with
+  `createDispatcher({ services, db, serviceAccessSource })` when users'
+  grants are stored in a column (the admin kit protects that column only
+  where the dispatcher names it, as `createServer` does from
+  `auth.serviceAccessSource`), and `createHttpRouter` throws when its
+  `auth.serviceAccessSource` is not its dispatcher's. An MCP process made
+  with `createDispatcher` names it the same way.
 - **In process**: `server.dispatcher.caller(principal)` or
   `qd.caller(principal)`: `await qd.caller(user).taskService.rename(input)`,
   typed by the `contracts` of `initQuickdraw`'s types. A principal that
@@ -1176,9 +1400,15 @@ over three transports (design: sections 3, 8 and 10):
   `auth.serviceAccessSource`). One that carries grants (even `{}`) keeps
   exactly those. A load that fails rejects the call with `INTERNAL`.
 
-`authenticate` takes one request (`{ transport, auth, headers, socket | req }`)
-for both transports and returns a principal, a user id, or nothing for an
-anonymous caller; throwing `QuickdrawError("UNAUTHENTICATED", ...)` refuses.
+`authenticate` takes one request (`{ transport, auth, headers, socket | req }`,
+plus `credential` and `sessionCookie` on HTTP) for both transports and
+returns a principal, a user id, or nothing for an anonymous caller; throwing
+`QuickdrawError("UNAUTHENTICATED", ...)` (or `"FORBIDDEN"`) refuses. Anything
+else it, or `loadServiceAccess`, throws is the server's failure (its session
+store or database down): a socket's handshake is refused `INTERNAL`, and a
+quickdraw client keeps the user and connects again by itself, while an HTTP
+call is answered `UNAUTHENTICATED`, as before. On HTTP the session cookie
+is in `auth.token` only for `socketAuth`'s `authenticate`.
 Pass your own HTTP server as `httpServer` together with the `app` it was
 created from (or with `http: false`).
 
@@ -1231,13 +1461,25 @@ one, by `service.method (kind)`, which tells an agent nothing), with the
 input schema's JSON Schema as its arguments and `readOnlyHint` on every
 query. The API docs print each method's default tool name and its read-only
 hint. Every tool call goes through the dispatcher with transport `"mcp"`,
-so input validation, access checks and limits apply exactly as on a socket.
-A method whose input cannot describe itself as JSON Schema stops the
-registry at startup, naming the method, unless it is excluded.
+so input validation and access checks apply as on a socket. Queries share
+a concurrency lane per caller (16 run and 64 wait by default, the
+dispatcher's `limits`, then `RATE_LIMITED`): a stdio process, and on HTTP
+a bearer token, a user without a token, or the address of an anonymous
+caller (Express's `req.ip`, an IPv6 address by its /56). Behind a proxy,
+set Express's `trust proxy`, or every anonymous caller shares the proxy's
+lane. A `principal` hook that authenticates by anything but the bearer
+token (a cookie, an API key header) must refuse a request whose bearer
+token it does not verify, or a caller makes a lane per made-up token. The
+HTTP routes have no rate limit of their own: limit them per address, as
+below (`createPublicApiLimiter` answers 429 with `{ error }`, not the
+routes' `{ success: false, code }`). A method whose input cannot describe
+itself as JSON Schema stops the registry at startup, naming the method,
+unless it is excluded.
 
 <!-- example: apps/api/src/mcp.ts#mcp -->
 
 ```ts
+import { createPublicApiLimiter } from "@fitzzero/quickdraw-core/server/express";
 import {
   createMcpHttpRouter,
   createMcpRegistry,
@@ -1249,7 +1491,7 @@ const summarizeInput = z.object({ projectId: z.string() });
 const registry = createMcpRegistry({
   services: [projectService, taskService],
   dispatcher: server.dispatcher,
-  // who a stdio session or an HTTP bearer token stands for; nothing is anonymous
+  // an agent acting for the user of a session token, checked on every call; no token is anonymous
   principal: (request) =>
     verifySession(request.transport === "http" ? request.token : process.env.AGENT_TOKEN),
   // handlers read it as ctx.mcp
@@ -1269,7 +1511,9 @@ const registry = createMcpRegistry({
   ],
 });
 
-// GET /mcp/tools, POST /mcp/invoke
+// GET /mcp/tools, POST /mcp/invoke; the routes have no rate limit of their own, so limit them per
+// address (never by the bearer token, which nothing has checked yet)
+app.use("/mcp", createPublicApiLimiter({ max: 600 }));
 app.use(createMcpHttpRouter({ registry }));
 // in an MCP client's process
 createMcpStdioServer({ registry, name: "my-app", version: "1.0.0" });
@@ -1284,7 +1528,17 @@ createMcpStdioServer({ registry, name: "my-app", version: "1.0.0" });
   sends console output to stderr so only the protocol reaches stdout.
 - **HTTP**: `GET /mcp/tools` and `POST /mcp/invoke`, which takes
   `{ name, arguments }` and answers `{ success: true, data }`, or
-  `{ success: false, error, code, data? }` with the code's HTTP status.
+  `{ success: false, error, code, data? }` with the code's HTTP status. A
+  request from a web page (one with an `Origin` header) is answered 403
+  unless `createMcpHttpRouter({ allowedOrigins })` lists its origin (exact
+  origins or anchored patterns, as `socketAuth` takes them; none by
+  default); an MCP client sends no `Origin`. `allowedOrigins` adds no CORS
+  headers: a page on another origin still needs the app's CORS setup. For a
+  server on a developer's machine or a LAN,
+  `allowedHosts: ["localhost", "127.0.0.1", "::1"]` also refuses a request
+  for any other `Host`, which a DNS-rebinding page would send. An entry with
+  a port matches that port only (a `Host` without one is for port 80 or
+  443).
 - An anonymous caller (the `principal` hook returned nothing) may call
   `"public"` methods, and custom tools that declare `access: "public"`; any
   other tool answers `UNAUTHENTICATED` before it runs. A failed call reaches
@@ -1294,6 +1548,19 @@ createMcpStdioServer({ registry, name: "my-app", version: "1.0.0" });
   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.
+- `kinds` sees only what the `principal` hook labels: `verifySession` above
+  labels every MCP caller `kind: "agent"`, so a method with
+  `kinds: ["user"]` refuses it. Check a session token against the store on
+  every call (`bearerAuth`), never with `verifyJWT` alone, which a
+  signed-out session still passes. A custom tool obeys the app's
+  `initQuickdraw({ kinds })` too, and takes `kinds` of its own within it
+  (`FORBIDDEN` for another kind, before its arguments are read); a
+  `"public"` tool takes none. Custom tools served beside the services of
+  apps that admit no kind in common stop the registry at startup.
+- To refuse a token, the `principal` hook throws
+  `QuickdrawError("UNAUTHENTICATED")`, which is logged at debug, as the
+  caller's doing; anything else it throws is logged as an error. Never put
+  the token in the message.
 
 `bind` fills chosen arguments from who is calling instead of from the agent,
 so an agent bound to one project cannot name another in its calls. Here an
@@ -1322,9 +1589,14 @@ app.use(createMcpHttpRouter({ registry: projectAgents, path: "/agents" }));
 
 - Each bound argument is left out of the `inputSchema` of every method's tool
   whose object input has it: `create_task` lists `id` and `title`, and
-  `count_tasks` takes no arguments. Every call of such a tool gets the
-  binder's value before its input is validated, through `tools/call` and both
-  shapes of `POST /mcp/invoke` alike.
+  `count_tasks` takes no arguments. An object schema with `.meta({ id })`,
+  which JSON Schema writes as a `$ref`, counts as the object it names; a
+  schema made from it (`.optional()`, `.refine()`, `.default()` and the
+  like) is not an object input. Every call of such a tool gets the binder's
+  value before its input is validated, through `tools/call` and both shapes
+  of `POST /mcp/invoke` alike, and a call of any other method's tool that
+  sends a bound argument is `FORBIDDEN`. Only top-level arguments are
+  bound.
 - A call fails closed, before the method runs: `UNAUTHENTICATED` for an
   anonymous caller, and `FORBIDDEN` when the binder returns `undefined` or
   `null`, or when the agent sent the argument with another value. A binder
@@ -1332,9 +1604,10 @@ app.use(createMcpHttpRouter({ registry: projectAgents, path: "/agents" }));
   `QuickdrawError` it threw.
 - `createMcpRegistry` throws at startup when a bound argument is in no
   selected method's object input (a misspelled name would leave the real
-  argument to the agent), and when it is a property of an input that is not
-  an object, which it names: leave that method out, or make its input an
-  object.
+  argument to the agent), and when an input may hold it anywhere it cannot
+  be filled (an input that is not an object, or a branch of a union or an
+  intersection, behind a `$ref` too), which it names: leave that method
+  out, or make its input an object.
 - Custom tools are never bound, and neither are the calls their `caller`
   makes: a custom tool reads `principal` itself. `describeTools` and the API
   docs list the inputs as the contracts declare them, with nothing bound.
@@ -1342,18 +1615,69 @@ app.use(createMcpHttpRouter({ registry: projectAgents, path: "/agents" }));
   socket or HTTP with nothing bound, so the method's access must still
   confine it to its project.
 
+An app that signs the caller in itself, such as its own MCP transport over
+`callMethod` or an in-process assistant, passes the caller as `principal`
+in the call's options, and the registry's `principal` hook is not asked:
+
+<!-- example: apps/api/src/mcp.ts#signed-in -->
+
+```ts
+import { requireSession, sessionOf } from "@fitzzero/quickdraw-core/server/auth";
+import { toToolResult } from "@fitzzero/quickdraw-core/server/mcp";
+
+// the app's own MCP route: its sessions sign the caller in, as an agent of their user
+const signedIn = requireSession(
+  { sessions, jwtSecret },
+  { loadPrincipal: (userId): AppPrincipal => ({ userId, kind: "agent" }) },
+);
+
+app.post("/assistant/:service/:method", signedIn, (req, res) => {
+  void (async () => {
+    const result = await registry.callMethod(req.params.service, req.params.method, req.body, {
+      // no bearer token: the call's queries share its user's lane
+      request: {
+        transport: "http",
+        sessionId: crypto.randomUUID(),
+        token: null,
+        headers: req.headers,
+        req,
+      },
+      // the registry's principal hook is not asked; the user's grants load as qd.caller's do
+      principal: sessionOf<AppPrincipal>(req).principal,
+    });
+    res.json(toToolResult(result));
+  })();
+});
+```
+
+- `principal: null` calls anonymously; without the key, the hook says who
+  calls, as before. `registry.call` takes it as `callMethod` does. The
+  `context` hook, bound arguments and the call's concurrency lane see the
+  given principal, and `request` is still needed: the lane and `context`
+  read it.
+- A principal that carries no `serviceAccess` gets the grants the server's
+  `auth.loadServiceAccess` loads, at each call, as `qd.caller` gives them;
+  one that carries grants (`{}` included) keeps exactly those. The `principal`
+  hook's principal is used as the hook returns it.
+- It is an in-process option: `POST /mcp/invoke` never reads a principal
+  from its body.
+
 Two more needs are met by the options above, with nothing added:
 
 - **A tool set per kind of caller.** Make one registry per kind, each with its
   own `include`, `bind` and `principal`, and serve each at its own `path` or
   from its own stdio entry, as above. A registry's `principal` hook refuses
-  the other kinds: throwing fails their calls with `UNAUTHENTICATED`.
+  the other kinds: throwing `QuickdrawError("UNAUTHENTICATED")` fails their
+  calls with `UNAUTHENTICATED` and logs at debug; never put a token in the
+  message.
 - **Frozen public tools.** `name` gives a method's tool any public name, as
   `create_task` above. When agents depend on tool names and argument shapes
   that must never change, give that surface a contract of its own: its
   methods' inputs and `describe` texts are the frozen shapes, its handlers
   call the app's services through `ctx.services`, and a registry with
-  `name: (_service, method) => method` serves it. The bridge never reshapes a
+  `name: (_service, method) => method` serves it. Those calls carry the
+  tool call's `ctx.mcp`, so a guard that reads it in a method they reach
+  holds as it does on that method's own tool. The bridge never reshapes a
   tool's arguments on the way in: such a tool would be invisible to the API
   docs and to lint, which read the contracts.
 
@@ -1462,7 +1786,9 @@ export function TaskDetail({ id }: { readonly id: string }) {
   the chat's messages open). A row-level grant with neither sends nothing
   the client could notice: remount the view, or call `refresh()`.
 - The cache follows the user: a hello naming another user removes everything
-  quickdraw cached; new credentials for the same user refetch it; new grants
+  quickdraw cached, and no `useQuery` of the client shows a placeholder made
+  from it (`placeholderData` such as `keepPreviousData`), nor `useSearch` its
+  last results; new credentials for the same user refetch it; new grants
   (`qd:access`) refetch every query.
 - A protocol mismatch reloads the page once per session by default
   (`onProtocolMismatch`); `RATE_LIMITED` answers back off with jitter per
@@ -1551,16 +1877,31 @@ for an anonymous socket and before the server's hello, so a gate waits for
 `isKnown` (the hello on the current credentials arrived; false again from
 new credentials until theirs). `isConnected` turns true before the hello and
 false while the connection reconnects; `reconnecting` says the user and the
-page stay meanwhile:
+page stay meanwhile. When the server ends the session (signed out on
+another device, revoked, expired) or refuses a connect for it (its
+`authenticate` refused the credentials, or the handshake was
+`FORBIDDEN`), the hello is forgotten: `isKnown` is false, `status` is
+`"disconnected"` or `"refused"`, and everything quickdraw cached is gone,
+so a gate that finds the connection stopped with nobody known shows the
+sign-in. A server that could not check the credentials (its session store
+down: the handshake is refused `INTERNAL`) signs nobody out: the
+connection keeps the hello and the cache, stays `"connecting"`
+(`reconnecting` after a connect on these credentials) and connects again
+by itself after Socket.IO's reconnection delays, so the gate below shows
+the page with "Reconnecting…", or "Connecting…" before a first connect.
+Another protocol (`refusal.code` `"PROTOCOL_MISMATCH"`) keeps the hello;
+the provider reloads the page once for it:
 
 <!-- example: apps/web/src/components/AuthGate.tsx#gate -->
 
 ```tsx
 export function AuthGate({ children }: { readonly children: ReactNode }) {
   // isKnown: the server's hello named the user, so userId is final (null: signed out)
-  const { isKnown, userId, reconnecting } = useQuickdraw();
+  const { status, isKnown, userId, reconnecting } = useQuickdraw();
   if (!isKnown) {
-    return <p>Connecting…</p>;
+    // stopped with nobody known: the server ended or refused the session (signed out elsewhere,
+    // revoked, expired), and what quickdraw cached is gone
+    return status === "disconnected" || status === "refused" ? <SignIn /> : <p>Connecting…</p>;
   }
   if (userId === null) {
     return <SignIn />;
@@ -1601,13 +1942,18 @@ export async function TasksPage({ projectId, cookie }: { projectId: string; cook
 }
 ```
 
-A script, a worker or a React Native module without hooks uses the
-connection directly:
+A script, a CLI or a worker uses the connection directly, from
+`@fitzzero/quickdraw-core/client/core`: the client without React, for a
+process that installs neither React nor TanStack Query. It holds the
+connection, `call` and `callData`, `newId`, the auth helpers, peer links,
+host mode and everything on `./utils`. Nothing it imports, in its code or
+its types, is React or TanStack, and it carries no `"use client"`.
+`./client` re-exports all of it, the same functions:
 
 <!-- example: apps/api/scripts/report.ts#script -->
 
 ```ts
-import { callData, createQuickdrawConnection } from "@fitzzero/quickdraw-core/client";
+import { callData, createQuickdrawConnection } from "@fitzzero/quickdraw-core/client/core";
 
 const connection = createQuickdrawConnection({
   url: "http://localhost:4000",
@@ -1624,9 +1970,11 @@ process.stdout.write(`${String(count)} tasks\n`);
 connection.close();
 ```
 
-`liveDataOf(connection, queryClient)` holds live rows and collections for
-such code, and `createInvalidationCoordinator(queryClient)` invalidates as
-the hooks do.
+Live rows and collections take a TanStack `QueryClient`, so they are on
+`./client` only, still without React: `liveDataOf(connection, queryClient)`
+holds them for code without hooks (a React Native module, a Node client
+that keeps a `QueryClient`), and `createInvalidationCoordinator(queryClient)`
+invalidates as the hooks do.
 
 A client in another language (a Godot game, a native app) speaks the wire
 itself: [`docs/protocol-v5.md`](https://github.com/fitzzero/quickdraw/blob/main/docs/protocol-v5.md) is its specification,
@@ -1710,7 +2058,8 @@ export const taskService = qd.defineService(task, {
         delete: { entry: "Admin" },
         reorder: { entry: "Moderate" },
         bulkUpdate: "authenticated",
-        bulkDelete: "authenticated",
+        // all or nothing: Admin on every id, as delete needs
+        bulkDelete: { entry: "Admin", id: "ids" },
       },
       // what `create` writes: columns from the principal, the next ordinal
       prepare: async (input, ctx, db) => ({
@@ -1720,7 +2069,7 @@ export const taskService = qd.defineService(task, {
       }),
     }),
     archive: {
-      access: { entry: "Admin" },
+      access: { entry: "Moderate" },
       handler: ({ input, db }) =>
         db.task.update({ where: { id: input.id }, data: { status: "archived" } }),
     },
@@ -1736,11 +2085,20 @@ export const taskService = qd.defineService(task, {
   `get`, `update`, `delete` and `reorder` act on `input.id`, which
   `{ entry: L }` checks; a write on one row also needs the row level
   (`Moderate`, or the form's `entry`) on that row whatever its form, so
-  `update: "authenticated"` edits no row. `list`, `getMany`, `bulkUpdate`
+  `update: "authenticated"` edits no row. `create` makes a new row and
+  checks no row of its own: it needs that row level on each parent its new
+  row names (each anchor column it writes, below), whatever its form, so
+  `create: "authenticated"` writes into no project its caller cannot
+  moderate; give it `{ scope: "Moderate", of: project, id: "projectId" }`.
+  `list`, `getMany`, `bulkUpdate`
   and `bulkDelete` act on many rows, so they also keep only the rows the
   service's policy gives the caller at the form's `entry` or `scope` level
-  (else `Read` for reads and `Moderate` for writes): a list never shows a
-  row `get` would refuse. A service-wide `Admin` grant reaches every row,
+  (else `Read` for reads and `Moderate` for writes; a bulk method's form
+  that names none takes `update`'s or `delete`'s row level when it is
+  higher): a list never shows a row `get` would refuse, and a bulk delete
+  never deletes a row `delete`'s `{ entry: L }` would refuse. When the
+  single-row form names no row level (`{ service: L }`, `custom`), give the
+  bulk method the same form. A service-wide `Admin` grant reaches every row,
   and a grant a `{ service: L }` form names is a row level of the grant on
   every row (the read is not filtered, and its rows are stripped at the
   grant). A `"public"` read's rows are not filtered (a public bulk write
@@ -1754,26 +2112,59 @@ export const taskService = qd.defineService(task, {
   above the caller's level is `FORBIDDEN`, and a default sort on one falls
   back to `id`), keyset cursors that stay put when rows are inserted, 50
   items by default and at most 200 (a larger `limit` is clamped), and a
-  total only when asked (a second statement). Items are the `item`
+  total only when asked (a second statement). A sort value too long for a
+  cursor (4,096 characters) makes the cursor name its row instead: the next
+  page reads that row first, and the cursor is `VALIDATION` once the row has
+  left the list (or for a caller whose list never held it). Such a cursor
+  follows its row: a change to that row's sort value between pages can skip
+  or repeat rows. Items are the `item`
   projection, stripped of fields above the level the page was read at, as
   collection items are.
 - `getMany({ ids })` (at most 200) leaves out ids the caller cannot read and
   ids with no row. Bulk writes skip rows the caller cannot write, run in one
-  transaction and return `{ count }`.
+  transaction and return `{ count }`; give one `{ entry: L, id: "ids" }` to
+  refuse the whole call instead of skipping rows (an empty `ids`, or an id
+  with no row, is then `FORBIDDEN`).
 - Writes go through the tracked client: `create` sends `added`, `update` a
   patch and `delete` `removed`, and a bulk write past a scope's
   `bulkThreshold` sends it one `reset`. A missing row is `NOT_FOUND`, a
   unique violation `CONFLICT`.
-- `update` and `bulkUpdate` (and the admin kit's writes) never let a caller
-  without a service-wide `Admin` grant set a column the policy reads (an
-  owner column, an access list), and move a row into another parent (an
-  `inherit` policy's `via`, an anchored collection's scope column) only
-  when the caller's level on the new parent meets the method's row level:
-  `FORBIDDEN` otherwise.
+- Without a service-wide `Admin` grant, `update` and `bulkUpdate` (and the
+  admin kit's writes) never set a column the policy reads (an owner column,
+  an access list), even one an anchored collection also scopes by. They
+  never set a membership table's entry, user or role column that any policy
+  reads either: change memberships with the sharing kit. They move a row
+  into another parent (an `inherit` policy's `via`, an anchored
+  collection's scope column) only when the caller's level on the new parent
+  meets the method's row level. Each refusal is `FORBIDDEN`. An `inherit`
+  `via` column stays movable, so never inherit a row's access from the
+  users' own rows (`inherit({ from: user, via: "ownerId" })`): a caller
+  would hand the row to themself.
+- `create` takes a column the policy reads, and a membership column, only
+  from `prepare` (`ownerId: ctx.principal.userId`), never from a caller
+  without a service-wide `Admin` grant. It writes a parent only where the
+  caller has the row level on it, after `prepare` ran.
+- Every kit write holds column values only, in every environment and for
+  every caller, a service-wide Admin included: a key that is a relation of
+  the model (one a projection selects with a nested `select`) or a value
+  that is a Prisma nested write (`{ connect }`, `{ update }`, a to-many
+  `{ set: [...] }`) is `VALIDATION`, since nested writes are not tracked
+  and would skip the checks above. A `prepare` that returns one is
+  `INTERNAL`. A Json value whose own key is a relation operation holding an
+  object or list, or `delete`/`disconnect` set to `true`, is refused too;
+  keep such data one level deeper. Any `{ set: [...] }` is refused, a scalar
+  list's included: write a scalar list as the list itself.
 - `reorder({ id, beforeId?, afterId? })` puts the row between its new
   neighbors (`beforeId` comes right before it) with one write, or renumbers
   the `within` list in steps of 1,024 when no gap is left, in a transaction
-  given 5 s plus 10 ms per row of the list. Moves run SERIALIZABLE: two at
+  given 5 s plus 10 ms per row of the list. The neighbors it names need the
+  method's row level, as the moved row does (a neighbor below it is
+  `NOT_FOUND`, as a missing one is), and the list is the rows sharing the
+  `within` values that the caller may write: a list with no `within` or a
+  null one is each caller's own. The rows it names are read through that
+  same filter, so a policy whose filter matches no row (a `resolver` without
+  `where`) moves nothing below a service-wide grant, as its lists show
+  nothing. Moves run SERIALIZABLE: two at
   once into one gap fail one of them with `CONFLICT` (try again).
 - The generated inputs carry JSON Schema, so the kit's methods are MCP tools
   too. For hand-written handlers, `./server` has `requireRow(row, message?)`
@@ -1895,8 +2286,8 @@ export function TaskSearch({ projectId }: { readonly projectId: string }) {
 - `search({ q, scope?, cursor?, limit? })` returns `{ items, nextCursor }`
   (and `rev`, below). `q` is trimmed, and one shorter than `minLength`
   (default 2) finds nothing and reads nothing. 20 results by default, at
-  most 100, with keyset cursors as for `list`. There is no ranking: results
-  come in the scope collection's order, else by id.
+  most 100, with keyset cursors as for `list`. There is no ranking: a call
+  with `scope` comes in the scope collection's order, one without by id.
 - By default a row matches when one of the declared `fields` contains `q`,
   ignoring case; `%`, `_` and `\` in `q` are taken literally. `fields` is an
   explicit list because an unbounded "contains" over every column is slow. A
@@ -1984,7 +2375,7 @@ export const project = defineContract("projectService", {
     }),
   },
   collections: {
-    // each user's projects: an invite adds the project, a remove or a leave takes it out
+    // each user's projects: an invite adds the project; a remove, a leave or a role below Read takes it out
     mine: {
       describe: "The projects a user is a member of.",
       scope: via({ model: "projectMember", entry: "projectId", scope: "userId" }),
@@ -2009,12 +2400,27 @@ export const projectService = qd.defineService(project, {
   collections: { mine: { scopeAccess: "self" } },
   methods: {
     ...sharing.handlers(project, {
-      // finds the user inviteByName means; none is NOT_FOUND
-      resolveUser: async ({ name, email }) =>
-        (await db.user.findFirst({ where: name === undefined ? { email } : { name } }))?.id,
+      // the one user a by-name call means, or null (NOT_FOUND): an email is unique
+      // (and wins when both are given), a display name counts only when exactly
+      // one user has it
+      resolveUser: async ({ name, email }) => {
+        if (email !== undefined) {
+          return (await db.user.findUnique({ where: { email }, select: { id: true } }))?.id;
+        }
+        if (name === undefined) {
+          return null;
+        }
+        const named = await db.user.findMany({ where: { name }, select: { id: true }, take: 2 });
+        return named.length === 1 ? named[0]?.id : null;
+      },
       // runs inside the change's transaction: its writes commit with it, a throw undoes it
-      onChange: (change, ctx) => {
+      onChange: async (change, ctx) => {
         ctx.log.info("sharing changed", { kind: change.kind, id: change.id, user: change.userId });
+        // the flush revokes their subscriptions, but rooms are the app's: a user whose entry or
+        // membership is gone leaves the project's board on every node (removeFromBoard, rooms.ts)
+        if (change.after === null) {
+          await removeFromBoard(change.id, change.userId);
+        }
       },
     }),
   },
@@ -2022,8 +2428,9 @@ export const projectService = qd.defineService(project, {
 ```
 
 - Access list methods: `share({ id, userId, level })` gives a user `Read`,
-  `Moderate` or `Admin` (replacing any level they had), `setLevel` changes
-  the level of a user the row is shared with, `unshare({ id, userId })`
+  `Moderate` or `Admin` (replacing a level they had, unless it is above the
+  caller's), `setLevel` changes the level of a user the row is shared
+  with, `unshare({ id, userId })`
   takes it away, and `listShares({ id })` lists the row's shares; each
   returns the list as `[{ userId, level }]`, one entry per user. Membership
   methods: `invite({ entryId, userId, role? })` and
@@ -2032,22 +2439,32 @@ export const projectService = qd.defineService(project, {
   `leave({ entryId })` return `null`, and
   `listMembers({ entryId, cursor?, limit? })` pages the members in user id
   order (50 by default, at most 200). `shareByName` and `inviteByName` take
-  `name` or `email` instead of `userId`, and need `resolveUser`; a mode adds
-  every method but those two unless `methods` names its own list.
+  `name` or `email` instead of `userId`, and need `resolveUser`, which
+  returns exactly one user's id or `null` (`NOT_FOUND`): an email by
+  `findUnique`, a name only when exactly one user has it, as above, never
+  the first of several (a `findFirst` by name shares with whoever
+  registered that name first); a mode adds every method but those two
+  unless `methods` names its own list.
 - Who may call: a change needs `{ entry: "Admin" }` on the row, a list
   `{ entry: "Read" }`, and `leave` a signed-in member (`FORBIDDEN` for
   anyone else). `access: { share: { entry: "Moderate" } }` replaces one
   method's form. Whatever the form, no caller shares, sets or invites at a
-  level above their own on the row (`FORBIDDEN`; a service-wide grant
-  counts where the form names `service`), and each change reads the
-  caller's level again inside its transaction, refusing one lowered by a
-  concurrent change (`FORBIDDEN`).
+  level above their own on the row, nor changes or removes a user whose
+  current level there is above their own (`FORBIDDEN`; a service-wide
+  grant counts where the form names `service`; equal levels may, so one
+  Admin changes another), and each change reads the caller's level again
+  inside its transaction, refusing one lowered by a concurrent change
+  (`FORBIDDEN`).
 - The kit changes the list or the table the service's policy reads, alone
   or inside `anyOf`, and takes their names from it: a service whose policy
   has none for a mode the contract uses (or two) fails when it is defined.
   Roles are the policy's `levels` keys, or the level names `Read`,
   `Moderate` and `Admin` without it; another role is `VALIDATION`, and
   `invite` without a role gives the lowest one that can read the row.
+  Roles that map to one level are peers: with
+  `{ owner: "Admin", admin: "Admin" }` an `admin` may demote or remove the
+  `owner`, so protect an owner with an owner column
+  (`anyOf(owner("ownerId"), members(...))`).
 - The owner's access never changes (`CONFLICT`). A row keeps its last
   Admin, counted across every policy of an `anyOf`: an owner column, an
   `Admin` entry of the access list, an `Admin` member (so a project's owner
@@ -2065,6 +2482,17 @@ export const projectService = qd.defineService(project, {
   the `via` collections over the table `added` and `removed`; the kit sends
   nothing itself. The by-name methods tell a row's owner whether an account
   exists; list them only where that is acceptable.
+- App rooms are not subscriptions: a user who loses access stays in the
+  rooms a method joined them to until the app takes them out. The example's
+  `onChange` does that when the change leaves the user with no entry or
+  role (`change.after === null`): `removeFromBoard` takes their sockets out
+  of the project's board on every node. With custom `members` `levels`, a
+  role below the join's level must take the user out too. Under `anyOf` a user who still has
+  the other list is taken out too, and joins again on their next connection
+  (`useJoin`). `onChange` runs inside the change's transaction, before it
+  commits: a join that runs before the commit (a check that still sees the
+  old list) puts the user back until they disconnect, and a change whose
+  commit fails has still taken them out until their next connection.
 
 ### Admin kit
 
@@ -2121,8 +2549,12 @@ export function AdminTasks() {
   const { services } = useAdminServices(qd);
   const { data } = qd.task.admin.adminList.useQuery({ page: 1, sort: { field: "title" } });
   const update = qd.task.admin.adminUpdate.useMutation({
-    // adminList is a query, not live data: read the page again after this screen's own write
-    onSuccess: () => qd.invalidate(qd.task.admin.adminList),
+    // the kit's reads are queries, not live data: after this screen's own write,
+    // read the page again and put the row the write returned in adminGet's cache
+    onSuccess: (row) => {
+      qd.invalidate(qd.task.admin.adminList);
+      qd.task.admin.adminGet.setData({ id: row.id }, row);
+    },
   });
   return (
     <table aria-label={services[0]?.displayName}>
@@ -2169,8 +2601,10 @@ export function AdminTasks() {
   service-wide `Admin` grant, nor are the columns the policy reads, and a
   row moves to another parent only with the row level on it (`FORBIDDEN`,
   as for the read/write kit); each value is checked by the entity schema
-  itself, and a value the database refuses is `VALIDATION`. A missing row
-  is `NOT_FOUND`.
+  itself, and a value the database refuses is `VALIDATION`. A relation of
+  the model (a key a projection selects with a nested `select`) or a nested
+  write (`{ connect }`, `{ update }`) is `VALIDATION`, for every caller: the
+  kit writes column values only. A missing row is `NOT_FOUND`.
 - `editable: ["title", "status"]` names the only fields `adminCreate` and
   `adminUpdate` write: `adminMeta` reports every other field
   `editable: false`, so a generic form leaves it read-only, and a write
@@ -2180,8 +2614,10 @@ export function AdminTasks() {
   list, so the writes' input checks, types and JSON Schema (and the MCP
   tools made from it) name only those fields; given to both halves, the
   two lists must name the same fields. Without either list the kit writes
-  what it wrote in 5.0.0: every field it shows but `id` and the timestamps,
-  less those an override made read-only.
+  what it wrote in 5.0.0: every field it shows but `id`, the timestamps and
+  the model's relations, less those an override made read-only. An `editable` list, or a
+  `fieldOverrides` entry with `editable: true`, that names a relation of the
+  model fails when the service is defined.
 - `adminMeta()` returns `{ serviceName, displayName, fields }`, one
   `{ name, type, label, required, editable, showInTable, sortable, filterable, enumValues?, relationService?, kind?, showInForm? }`
   per field: `type` is
@@ -2190,11 +2626,19 @@ export function AdminTasks() {
   `sortable` and `filterable` are the declared fields (`filterable` is
   optional in the `AdminFieldConfig` type, default `false`, so field
   configurations written for 4.x still type); `id` and the
-  timestamps come first and are not editable; `acl`, `serviceAccess` and
-  `service_access` are hidden.
+  timestamps come first and are not editable; a relation of the model (a
+  field a projection selects with a nested `select`) is `editable: false`;
+  `acl`, `serviceAccess` and `service_access` are hidden, and so is the
+  column `auth.serviceAccessSource` (a bare dispatcher's
+  `serviceAccessSource`) names on this service's model, whatever its name.
 - 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`.
+  shows and writes the entity's grants field (`serviceAccess`, or the
+  column `auth.serviceAccessSource` names, whatever its name and type; the
+  entity schema checks what is written), so the admin screen edits grants
+  through `adminUpdate`. Options that clash with that column (hiding it
+  beside `grants: true`, or naming it in `editable`, `fieldOverrides`, a
+  filter or a sort without), and `grants: true` on an entity with no grants
+  field, fail when the server is made.
   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.
@@ -2217,10 +2661,61 @@ before?, after }, ctx, db)` after each `adminCreate`, `adminUpdate` and
   unit of work of its own: the reply does not wait for it, its writes flush
   on their own, and a throw is logged, the write standing. Apply an edit to
   what runs in memory (a game's simulation) there, so an edit that rolled
-  back is never applied. Without either hook the kit opens no transaction.
-  Each handler `admin.handlers` returns resolves with its method's output
-  type (`AdminOutputOf<C, M>`), so a wrapper reads the row and returns it
-  with no cast.
+  back is never applied. Without a hook (these two or `prepare`, below) the
+  kit opens no transaction. Each handler `admin.handlers` returns resolves
+  with its method's output type (`AdminOutputOf<C, M>`), so a wrapper reads
+  the row and returns it with no cast.
+- `admin.handlers(contract, { prepare })` runs `prepare(call, ctx, db)`
+  before each `adminCreate`, `adminUpdate` and `adminDelete`, once the
+  caller's access and data were checked, in one transaction with the write
+  and `onWrite` (`db` is the transaction's tracked client; a throw undoes
+  its writes and the write, and fails the call). `call` is
+  `{ method: "adminCreate", data }`, `{ method: "adminUpdate", id, data, before }`
+  or `{ method: "adminDelete", id, before }`: `data` is the caller's, and
+  `before` the row, every field, as `onWrite` hears it. Before a create or
+  an update it may return column values, written over the caller's data:
+  a column the server computes (a hash, a slug, the next ordinal), even one
+  the caller may not write (hidden, not editable, above their level), but
+  never `id`, a timestamp, a relation or a nested write (`VALIDATION`). An
+  anchor column it sets (a parent's id, an anchored collection's scope)
+  needs the method's row level on the row it names, as the caller's data
+  and the read/write kit's `prepare` do (`FORBIDDEN`), so a lowered form
+  never moves a row into a parent its caller cannot reach. Returning
+  nothing, or `undefined` for a key, keeps the caller's data, and what it
+  returns before a delete is ignored. The tracked client never sees
+  what the database deletes or clears with a row (`onDelete: Cascade`,
+  `SetNull`), so those rows stay in the lists and entities open on them;
+  delete or clear them through `db` in `prepare`, and their subscribers are
+  told. `prepare` shares the write's transaction, and so its time limit
+  (Prisma's default is 5 seconds; a client's `transactionOptions` sets
+  another):
+
+<!-- example: apps/api/src/services/kits/admin.ts#prepare -->
+
+```ts
+import type { TrackedTransaction } from "@fitzzero/quickdraw-core/prisma";
+import { nextOrdinal } from "@fitzzero/quickdraw-core/server";
+import type { PrismaClient } from "@project/db";
+
+export const taskAdmin = admin.handlers(task, {
+  editable: ["projectId", "title", "status"],
+  // runs before each write, in its transaction: `db` is that transaction's tracked client
+  prepare: async (call, _ctx, db: TrackedTransaction<PrismaClient>) => {
+    if (call.method === "adminCreate" && call.data.projectId !== undefined) {
+      // written over the caller's data, a read-only column too: the new task goes last
+      return { ordinal: await nextOrdinal(db, "task", { projectId: call.data.projectId }) };
+    }
+    if (call.method === "adminDelete") {
+      // the database deletes the task's label links and clears its subtasks' parent,
+      // unseen: do both here, tracked, so the rows and lists open on them are told
+      await db.taskLabel.deleteMany({ where: { taskId: call.id } });
+      await db.task.updateMany({ where: { parentTaskId: call.id }, data: { parentTaskId: null } });
+    }
+    return undefined;
+  },
+});
+```
+
 - `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
@@ -2237,14 +2732,20 @@ before?, after }, ctx, db)` after each `adminCreate`, `adminUpdate` and
   is not asked again until the user's grant on it changes, reconnects
   included.
 - The kit's rows are not live: `adminList` and `adminGet` are queries that
-  watch nothing, so a screen reads them again after its own writes (the
+  watch nothing, so after its own write a screen reads the page again and
+  puts the row the write returned in `adminGet`'s cache with `setData` (the
   `onSuccess` above), and sees other admins' writes when it next reads.
+  Their `useQuery`, and `adminSubscribers`', defaults to `staleTime: 0`, so a
+  screen reads them again whenever it mounts (pass `staleTime` to keep a
+  result longer; `adminMeta` keeps the provider's five minutes).
 - A screen that serves every service from its metadata (the route names the
   service) takes `adminOf(qd, key)`: the same members, keyed by what the kit
   made them for and typed by field name (`AdminScreen`: rows are
   `AdminRow`, `adminList` takes `{ page, pageSize, filter, sort: { field, direction } }`
   with names read from `adminMeta`), so no cast is needed over a union of
-  keys; a method the contract does not expose is absent.
+  keys; a method the contract does not expose is absent. Its query members
+  have `setData` too: `admin.adminGet?.setData({ id: row.id }, row)` shows
+  the row `adminUpdate` or `adminCreate` returned, with no read.
 
 ### Presence, streams and channels
 
@@ -2325,9 +2826,9 @@ export const taskService = qd.defineService(task, {
     },
   },
   channels: {
-    // relay each cursor to the board's room
+    // relay each cursor to the board's room, the one its requires matched (ctx.room)
     cursor: (payload, ctx) => {
-      ctx.rooms.emit(`board:${payload.projectId}`, task, "cursorMoved", payload);
+      ctx.rooms.emit(ctx.room, task, "cursorMoved", payload);
     },
   },
   // once per socket that leaves app rooms, in every server this service runs in, in a unit of its own
@@ -2347,6 +2848,17 @@ export function logLine(taskId: string, line: string): void {
   qd.stream(task, "logs").push(taskId, { line });
 }
 
+// a job skips the work nobody watches: the feed's subscribers on every node
+export async function tailLogs(taskId: string, read: () => Promise<string[]>): Promise<void> {
+  if ((await qd.stream(task, "logs").subscribers(taskId)) > 0) {
+    const lines = await read();
+    qd.stream(task, "logs").pushMany(
+      taskId,
+      lines.map((line) => ({ line })),
+    );
+  }
+}
+
 export async function isOnline(userId: string): Promise<boolean> {
   // also ctx.presence and server.presence
   return await qd.presence.isOnline(userId);
@@ -2395,17 +2907,37 @@ export function TaskRoom({
   out as its own frame, in order; use it rather than `push` in a loop
   (`no-emit-in-loop`). `qd:stream:sub` is authorized with the
   stream's `access` through the access engine, the scope being the row an
-  `entry` or `scope` form checks; `access: { room }` (a name, `{ prefix }`,
-  or for a scoped stream a function of the scope) opens it to the sockets
-  in that app room instead, signed in or not, and a socket that leaves the
-  room, or is taken out, leaves the feed; a stream without `access` is
-  closed. The answer is the seed; `useStream` then appends, keeps the
+  `entry` or `scope` form checks; `access: { room }` opens it to the
+  sockets in an app room instead, signed in or not, and a socket that
+  leaves the room, or is taken out, leaves the feed; a stream without
+  `access` is closed. A global stream names the room, or `{ prefix }` for
+  any room whose name starts with it; a scoped stream computes it from the
+  scope, ``(worldId) => `world:${worldId}` ``, because a name or a prefix
+  would let a socket in that room read every scope (`defineContract`
+  refuses both on a scoped stream, by type and when it runs). The answer is the seed; `useStream` then appends, keeps the
   latest `max` (default 500), and subscribes again after a reconnect, when
-  the seed replaces what it held. A socket holds at most 500 feeds. A
+  the seed replaces what it held. A subscribe an access change overlapped
+  is authorized again before it joins the feed, with the socket's
+  principal as it is then, and answered `FORBIDDEN` when it lost access;
+  nothing pushed meanwhile reaches it as a frame, and its seed is read as
+  it joins. A subscribe an unsubscribe overtook answers `seed: []`. A
+  socket holds at most 500 feeds. A
   subscriber whose access is lowered is authorized again; one refused
   leaves the feed and gets
   `qd:revoked { kind: "stream", reason: "access", s, stream, scope? }`, and
   `useStream` shows `FORBIDDEN` until the next connect.
+- A job skips the work nobody watches (`tailLogs` above):
+  `await qd.stream(task, "logs").subscribers(taskId)` (`subscribers()` for
+  a global stream; also on `server.stream` and `dispatcher.stream`) is how
+  many sockets subscribe to the feed, on every node, anonymous ones
+  included: the sockets a push reaches. Behind a cluster adapter the other
+  nodes answer one request with a count each, never their sockets; an
+  answer that does not arrive within `cluster.timeoutMs` counts as 0
+  (warned at most once every 10 minutes), and so does a node of an earlier
+  version. `qd.rooms` refuses the stream rooms' reserved `qd:` names, and
+  Socket.IO's own rooms hold one node's sockets: count with `subscribers`.
+  A host-served stream's handle refuses it, as it refuses `push`: only the
+  host's client knows who subscribes.
 - A service's `streams: { <name>: { seed, validate } }` (type
   `StreamImplementation`) computes a stream's seed per subscriber, `seed: (scope, ctx) => items` (the current state,
   where the items that follow are deltas; on whichever node the subscriber
@@ -2433,20 +2965,40 @@ export function TaskRoom({
   sending socket's own: a room another socket of the user joined does not
   count, a reconnected socket must join again, and behind a cluster the
   check runs on the node the socket is connected to, with no round trip.
-- Presence: `isOnline`, `lastSeen` (now while online, else when the user's
-  last socket on this process disconnected), `count` and `users` (each user
-  once, anonymous sockets left out; app rooms only) come from this process's
-  sockets, and from every node's (`fetchSockets`) behind a Redis adapter.
+  A channel without `requires` takes a message from every signed-in socket,
+  about any row or room its payload names: a handler that relays it to a
+  room (``ctx.rooms.emit(`project:${payload.projectId}`, ...)``) lets any
+  user reach that room. The server warns `channel-without-requires` for
+  each such channel when it starts (a strict test app does not start). Give
+  the channel a `requires` and relay to `ctx.room`, the room it matched; or,
+  when any signed-in user may send it, say so on the service, `channels: {
+ping: { access: "authenticated", handler } }`, which delivers as before
+  and silences the warning.
+- Presence: `isOnline` and `lastSeen` (now while online, else when the
+  user's last socket on this process disconnected) come from this process's
+  sockets, whatever rooms they are in; `count` and `users` (each user once,
+  anonymous sockets left out; app rooms only) come from this process's
+  records of the rooms `ctx.rooms.join` joined (a socket a raw
+  `socket.join` put in a room is not counted). Behind a Redis adapter each
+  also asks the other nodes, which answer from the same records with user
+  ids alone (or whether they hold a socket of the user); concurrent reads
+  of one room or user share one request.
   `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 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.
+  are refused with `VALIDATION`, and so are names with the shape of a
+  Socket.IO socket id, 20 letters, digits, `_` or `-`, because every socket
+  is alone in the room of its id: give such an id a prefix, `doc:${id}`; at
+  most 100 per socket; a method that shares 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. `rooms.size`, `rooms.leave` and presence
+  refuse the same names.
 - 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.
+  `qd:event [service, event, payload]`; `useEvent` hears them. `emit`
+  refuses the framework's rooms (`qd:`, `user:`) with `VALIDATION`: a
+  user's sockets are reached with `emitToUser`.
 - Rooms belong to a socket: a reconnect (a lost network, `qd:rotate`, new
   credentials) is a new socket in no room, which hears none of its events
   and whose channel messages requiring it are dropped. `useJoin(member,
@@ -2474,8 +3026,9 @@ 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)
+// a member removed from the project (the sharing kit's onChange calls it): 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 });
 }
@@ -2519,6 +3072,440 @@ export function hasAudience(projectId: string): boolean {
   user leaving two nodes at the same moment may both see the other (a
   removal never misses: each node reports its own last socket).
 
+### Peer links
+
+Two players of one app room can link their clients: WebRTC data channels
+between them, or the server's relay when those cannot form (a browser
+behind a symmetric NAT, Node, a headless game client), with the same
+messages either way (design: section 12.5). A server opts in with
+`createServer({ peers: true })`: it forwards the signals that set a link
+up and relays its messages, only between two signed-in sockets of the
+room, and never reads what a link carries. A link has two channels: `rel`,
+ordered and reliable (state, chat), and `fast`, unordered and never resent
+(input, positions). The app tells players each other's socket ids, here
+with an event:
+
+<!-- example: apps/api/src/services/kits/peers.ts#service -->
+
+```ts
+// on a server created with peers: true, which forwards the links' signals and relays their messages
+export const matchService = qd.defineService(match, {
+  methods: {
+    enterMatch: {
+      // any signed-in user here: a real game checks the caller's seat in the match first
+      access: "authenticated",
+      handler: ({ input, ctx }) => {
+        const room = `match:${input.matchId}`;
+        const joined = ctx.rooms.join(room);
+        if (joined && ctx.socketId !== undefined) {
+          // the socket's own id, which a peer links to
+          ctx.rooms.emit(room, match, "playerJoined", {
+            matchId: input.matchId,
+            userId: ctx.principal.userId,
+            socketId: ctx.socketId,
+          });
+        }
+        return joined;
+      },
+    },
+  },
+});
+```
+
+<!-- example: apps/web/src/components/kits/MatchLinks.tsx#hook -->
+
+```tsx
+function track(links: Map<string, PeerLink>, link: PeerLink, onMove: { current: OnMove }): void {
+  links.set(link.peer, link);
+  link.on("message", (data) => {
+    // a peer's message is its word, never checked by the server: parse it as any input
+    const move = moveSchema.safeParse(data);
+    // userId: the peer's user, as the server named it (known once the link is open)
+    if (move.success && link.userId !== undefined) {
+      onMove.current(link.userId, move.data);
+    }
+  });
+  link.on("close", () => links.delete(link.peer));
+}
+
+// each player of a match linked to every other: send a move to all of them, hear theirs
+export function useMatchLinks(matchId: string, onMove: OnMove): (move: Move) => void {
+  const { connection } = useQuickdraw();
+  const room = `match:${matchId}`;
+  const [links] = useState(() => new Map<string, PeerLink>());
+  const heard = useRef(onMove);
+  useEffect(() => {
+    heard.current = onMove;
+  });
+  // on every connection: a link lives as long as its socket, and a reconnect is a new socket
+  useJoin(qd.match.enterMatch, { matchId });
+  // a player who joins later: this side offers (when both offer, the link settles who answers)
+  qd.match.playerJoined.useEvent((player) => {
+    const self = connection.socket.id;
+    if (player.matchId === matchId && player.socketId !== self && !links.has(player.socketId)) {
+      track(links, createPeerLink(connection, { room, to: player.socketId, offerer: true }), heard);
+    }
+  });
+  // the players here before: they offer, this side answers
+  useEffect(
+    () =>
+      onPeerRequest(connection, (request) => {
+        if (request.room === room) {
+          track(links, request.accept(), heard);
+        }
+      }),
+    [connection, room, links],
+  );
+  useEffect(
+    () => () => {
+      for (const link of links.values()) {
+        link.close();
+      }
+    },
+    [connection, room, links],
+  );
+  // direct when WebRTC connects, the server's relay when it cannot; fast: unordered, never resent
+  return (move) => {
+    for (const link of links.values()) {
+      link.send("fast", move);
+    }
+  };
+}
+```
+
+- `createPeerLink(connection, { room, to, offerer })` (from `./client`, or
+  `./client/core` without React) opens a link to socket `to` in app room `room`. One side
+  offers; when both do (each heard of the other at once), the side whose
+  socket id sorts after the other's answers instead.
+  `onPeerRequest(connection, listener)` hears a socket of the room that
+  signals this one with no link yet (`{ room, from, userId }`):
+  `request.accept(options?)` answers with a link, `request.reject()`
+  refuses it, and a request nobody answers is dropped after 15 s.
+- A link has `state` (`connecting`, `open`, `closed`), `path` (`direct` or
+  `relay`), `peer` and `userId` (the peer's socket and user, as the server
+  named them), `on("open" | "message" | "state" | "close", listener)` and
+  `close()`, which tells the peer. `send(label, data)` takes any JSON value
+  of at most 64 KiB as UTF-8 JSON (a `RangeError` above) and returns false
+  when it dropped it: the link is not open, `fast` is backed up, or the
+  relay's rate is spent (`stats` counts what was sent, received and
+  dropped). `closeReason` says why it closed: `closed` (this side), `bye`
+  (the peer closed it, or left the room, was taken out of it or
+  disconnected: the server says so at once), `left` (this socket left the
+  room), `disconnected` (a link lives as long as its socket: open it again
+  after a reconnect), `timeout` (nothing opened within 15 s), `lost`
+  (nothing heard for 8 s, or a `relay: "never"` link's direct path
+  dropped), `failed`, `refused` (the server refused a
+  signal) or `unsupported` (a server without `peers`).
+- The direct path comes first, over the platform's `RTCPeerConnection`
+  (`peerConnection` takes another, such as react-native-webrtc's;
+  `iceServers` defaults to Google's and Cloudflare's public STUN servers,
+  with no TURN). The relay takes over when ICE fails, when the direct path
+  does not open within 5 s or drops after it opened (`rel` messages in
+  flight on it may be lost: the link emits `state`, so the app can
+  resync; when a data channel closes, the link first waits 2 s for the
+  peer's bye, since a peer that closes its link closes its channels too),
+  and at once on a side without WebRTC or with
+  `relay: "always"`; `relay: "never"` closes the link instead. A link never
+  moves back from the relay.
+- `link.clock` reads the peer's clock from pings on `fast` (six quick ones
+  as the link opens, then one every 500 ms): `now()` (the peer's clock, in
+  its milliseconds), `offset`, `rtt`, `jitter` and `synced`.
+- The server's limits: a socket signals at most 64 peers at once
+  (`CONFLICT`) and 20 signals a second (a burst of 40; `RATE_LIMITED`).
+  It relays only between two sockets that signalled each other, at most
+  120 messages a second to each peer (a burst of 240) and 1 MiB a second
+  in all (a burst of 2 MiB), and drops the rest silently; the client keeps
+  under these itself, from the hello's `limits.peers`. A socket that keeps
+  flooding either is disconnected, as for channels. A socket that leaves a
+  room, is taken out of it or disconnects ends its links there: the server
+  tells each peer it signalled, and each that signalled it. Behind a
+  cluster adapter the node that holds a socket checks it, and the relay
+  crosses nodes.
+- What a peer sends is the peer's word: the server checks who may link,
+  never what a link carries. Parse a link's messages as any input, and
+  check on the server whatever a client reports there.
+- Tests: `createLoopbackPeerLink({ ms, jitter, loss })` (from `./testing`)
+  links two ends in one process, with a delay and jitter per message and
+  loss on `fast` alone; its ends take `setLag` too.
+
+A browser test, a bench or a host plays a link over a bad network on its
+real path, direct or relay, with `setLag`:
+
+<!-- example: apps/web/src/components/kits/MatchLinks.tsx#lag -->
+
+```tsx
+// a browser test or a bench plays the match over a bad network, on the links' real paths: each
+// holds every message 150 ms plus up to 40 ms more, each way, and loses 5% of fast ones
+export function playOverBadNetwork(links: readonly PeerLink[]): () => void {
+  for (const link of links) {
+    link.setLag({ ms: 150, jitter: 40, loss: 0.05 });
+  }
+  // rel messages are never lost and keep their order; clock.rtt now reads about 300 ms more
+  return () => {
+    for (const link of links) {
+      // what the lag holds goes on the next task, in order
+      link.setLag(null);
+    }
+  };
+}
+```
+
+- `link.setLag({ ms, jitter, loss })` holds every message of the link,
+  both ways, `ms` plus up to `jitter` milliseconds, and loses a `fast` one
+  with probability `loss`, from 0 to 1: `stats.simulatedLoss` counts the
+  app's, and `dropped` still counts only what the link dropped. `rel`
+  messages are never lost and keep their order; a held one its path
+  refuses as it comes due (the relay's rate spent) goes again a little
+  later, and `send` on `rel` returns false meanwhile. `send` returns true
+  for a message it holds, and `stats.sent` counts it once a path took it.
+  The clock's pings and host mode's messages wait too, so `link.clock.rtt`
+  reads the lagged round trip. A new lag leaves what is held on its time;
+  `setLag(null)` (or all zeros) ends it, and what is held goes on the next
+  task, in order. `link.lag` reads it, and `random` takes a seeded
+  generator, so a run repeats. The server never sees the lag.
+
+### Host mode
+
+One player's client can run a room's authoritative simulation as the
+room's host (design: section 12.5). A contract declares the channels and
+streams the host serves (`serve: "host"`): a player's messages and feeds
+of them go to the room's host over the player's link, and never reach the
+server. The server only says who hosts: a method makes the calling socket
+the room's host (`ctx.rooms.setHost(room)`), and each socket of the room
+hears it (`qd:host`). Host mode runs over peer links, so the server needs
+`peers: true` (`createServer` throws without it):
+
+<!-- example: packages/shared/src/kits/host.ts#contract -->
+
+```ts
+export const arena = defineContract("arenaService", {
+  describe: "Arenas whose simulation one player's client runs, as the arena's host.",
+  methods: {
+    enterArena: mutation({
+      input: z.object({ arenaId: z.string() }),
+      output: z.boolean(),
+      describe: "Joins the caller's socket to an arena's room.",
+    }),
+    hostArena: mutation({
+      input: z.object({ arenaId: z.string() }),
+      output: z.boolean(),
+      describe: "Makes the caller's socket the arena's host, while it has none.",
+    }),
+  },
+  channels: {
+    // a player's input: to the arena's host over the player's link, never to the server
+    steer: {
+      payload: z.object({
+        arenaId: z.string(),
+        dx: z.number().min(-1).max(1),
+        dy: z.number().min(-1).max(1),
+      }),
+      ratePerSecond: 30,
+      requires: { room: (steer) => arenaRoom(steer.arenaId) },
+      serve: "host",
+    },
+  },
+  streams: {
+    // the host's world, to each player of the arena: the latest snapshot seeds a newcomer
+    world: {
+      item: snapshotSchema,
+      scope: "arenaId",
+      seed: 1,
+      volatile: true,
+      access: { room: arenaRoom },
+      serve: "host",
+    },
+  },
+});
+```
+
+<!-- example: apps/api/src/services/kits/host.ts#service -->
+
+```ts
+// on a server created with peers: true, as host mode runs over peer links
+export const arenaService = qd.defineService(arena, {
+  methods: {
+    enterArena: {
+      access: "authenticated",
+      handler: ({ input, ctx }) => ctx.rooms.join(arenaRoom(input.arenaId)),
+    },
+    hostArena: {
+      // the app picks the host, never the server: here the first player who asks
+      access: "authenticated",
+      handler: ({ input, ctx }) => {
+        const room = arenaRoom(input.arenaId);
+        return ctx.rooms.hostOf(room) === null && ctx.rooms.setHost(room);
+      },
+    },
+  },
+  // no handler for steer and no options for world: the arena's host serves both
+});
+```
+
+A player reads and sends as with a server's stream and channel:
+
+<!-- example: apps/web/src/components/kits/ArenaHost.tsx#player -->
+
+```tsx
+// a player reads the world and sends input as with any stream and channel: both reach the host
+export function useArena(arenaId: string) {
+  useJoin(qd.arena.enterArena, { arenaId });
+  const { items } = qd.arena.world.useStream(arenaId);
+  const { send } = qd.arena.steer.useChannel();
+  return {
+    world: items.at(-1),
+    // on the link's fast: never resent, so send input every frame, not once
+    steer: (dx: number, dy: number) => send({ arenaId, dx, dy }),
+  };
+}
+```
+
+The host's client serves the contract's host-served members with
+`defineHost`, while the server names its socket the room's host:
+
+<!-- example: apps/web/src/components/kits/ArenaHost.tsx#host -->
+
+```tsx
+// the arenas this client simulates as their host: each player's position, by user
+const arenas = new Map<string, { tick: number; players: Map<string, { x: number; y: number }> }>();
+
+// a peer's input arrives checked against the contract (schema, room, rate), but it is still
+// that player's word: the simulation applies it as it would any input
+const arenaHost = defineHost(arena, {
+  channels: {
+    steer: (steer, { peer }) => {
+      const players = arenas.get(steer.arenaId)?.players;
+      const at = players?.get(peer.userId) ?? { x: 0, y: 0 };
+      players?.set(peer.userId, { x: at.x + steer.dx, y: at.y + steer.dy });
+    },
+  },
+});
+
+// serves the arena while the server names this socket its host (qd:host), and stops when not
+export function useArenaHost(arenaId: string): void {
+  const { connection } = useQuickdraw();
+  useEffect(() => {
+    const room = arenaRoom(arenaId);
+    let host: Host<typeof arena> | undefined;
+    const settle = (): void => {
+      const hosting = hostOf(connection, room) === connection.socket.id;
+      if (hosting && host === undefined) {
+        arenas.set(arenaId, { tick: 0, players: new Map() });
+        host = arenaHost.serve(connection, { room });
+      } else if (!hosting && host !== undefined) {
+        host.close();
+        host = undefined;
+      }
+    };
+    const stop = onHostChange(connection, (changed) => {
+      if (changed === room) {
+        settle();
+      }
+    });
+    settle();
+    // the host's loop: twenty snapshots a second to every player of the arena
+    const loop = setInterval(() => {
+      const state = arenas.get(arenaId);
+      if (host !== undefined && state !== undefined) {
+        state.tick += 1;
+        host.stream("world").push(arenaId, {
+          tick: state.tick,
+          players: Object.fromEntries(state.players),
+        });
+      }
+    }, 50);
+    return () => {
+      stop();
+      clearInterval(loop);
+      host?.close();
+    };
+  }, [connection, arenaId]);
+}
+```
+
+- A host-served channel declares `requires: { room }`, the room whose
+  host takes its messages (a name, a function of the payload, or
+  `{ prefix }`); a host-served stream declares a scope and
+  `access: { room: (scope) => room }`, and its `seed: n` is how many items
+  the host keeps per scope for a newcomer. The service gives a host-served
+  channel no handler and a host-served stream no options (`defineService`
+  refuses them). The server drops a `qd:ch` to one (with a development
+  warning), refuses a `qd:stream:sub` to one (`VALIDATION`), and
+  `qd.stream(...).push` throws for one.
+- `ctx.rooms.setHost(room)` makes the calling socket the room's host and
+  returns true (false for a call without a socket); the socket must be in
+  the room (`FORBIDDEN`). A new `setHost` replaces the host. `hostOf(room)`
+  (on `ctx.rooms`, `qd.rooms` and `server.rooms`) returns the host's
+  socket id or `null`, and `clearHost(room)` clears it.
+- When the host leaves the room, is taken out of it or disconnects, the
+  room has no host: its sockets hear `qd:host` with `null`, and
+  `onHostLeave({ room, socketId, principal, reason })` (the service's and
+  `createServer`'s) runs once. The server never picks the next host; the
+  app does, as `hostArena` above lets the next player who asks. Behind a
+  cluster adapter each node knows each room's host. A node that dies
+  without closing its sockets leaves the hosts it held recorded on the
+  other nodes until each room's host is set or cleared again, and no
+  `onHostLeave` runs for them. So an app that picks a host only while
+  `hostOf(room)` is `null`, as `hostArena` does, also needs a way for a
+  player to take over a host that stops answering: a method that calls
+  `ctx.rooms.setHost(room)` or `clearHost(room)` after a timeout of the
+  app's own.
+- `defineHost(contract, { channels, streams })` (from `./client`, or
+  `./client/core` without React) takes one handler per host-served channel, whose `ctx` is
+  `{ peer: { socketId, userId, link }, room }` (the user as the server
+  named it, and the host's end of the player's link), and
+  `streams.<name>.seed(scope)` to compute a newcomer's seed
+  (default: the latest items pushed, as many as the contract's `seed`).
+  `serve(connection, { room })` answers the links of the room's players and
+  returns a `Host` with `stream(name).push(scope, item)` (checked against
+  the stream's schema), `peers` and `close()`. The host checks each message
+  as the server checks a channel's: its schema, its room, and a bucket per
+  player and channel; it ends the link of a player who floods. A player
+  subscribes at most 500 times at once and then 50 times a second
+  (`RATE_LIMITED`). A seed goes whole or not at all: one with an item too
+  large for a message of its own is refused (`INTERNAL`), and what the
+  relay drops on `rel` is sent again, in order. The host's own
+  `useChannel` and `useStream` for its room reach it over an in-process
+  link, so the host's own client is one of its `peers` too. One
+  connection serves several contracts in a room, one `serve` each, over
+  the same links; serving one contract twice in a room throws.
+- `hostOf(connection, room)` and `onHostChange(connection, listener)`
+  (from `./client`) say who hosts a room the socket is in. A player's feed
+  subscribes again each time a link to the room's host opens (a new host,
+  a reconnect), and its seed replaces what it showed. A channel message is
+  dropped while no link is open, and goes on the link's `fast`, never
+  resent: send input every frame. After a link to the host
+  closed, the next waits 1 s, doubling to 15 s while links keep closing
+  unopened.
+- The server never sees what a host and its players send each other. A
+  host is one player's client: trust what it reports no more than any
+  client's word, and check on the server whatever a service keeps of it.
+  A service's `kinds` does not reach its host-served members either: the
+  host knows each player's user, not its kind, so any signed-in socket of
+  the room can link to it. Guard who joins the room.
+
+Each of a host's `peers` comes with `link`, the host's end of that
+player's link: `link.clock.rtt` is the player's round trip, and
+`link.setLag(...)` lags that player's messages both ways. The host's own
+client is one of them, over its in-process link, so a host can play over
+a link as laggy as its players':
+
+<!-- example: apps/web/src/components/kits/ArenaHost.tsx#fair -->
+
+```tsx
+// the host's own play goes through an in-process link, one of host.peers: lag it to the median
+// player's one-way delay, at most 100 ms, so the host plays over a link as laggy as its players'
+export function matchPlayersLag(host: Host<typeof arena>, self: string | undefined): void {
+  const oneWay = host.peers
+    .filter((peer) => peer.socketId !== self)
+    .map((peer) => peer.link.clock.rtt / 2)
+    .sort((a, b) => a - b);
+  const median = oneWay[Math.floor(oneWay.length / 2)] ?? 0;
+  // call it now and then, as the players' round trips change: what is held keeps its time
+  host.peers.find((peer) => peer.socketId === self)?.link.setLag({ ms: Math.min(100, median) });
+}
+```
+
 ### Auth routes kit
 
 Sign-in for Google, Discord, a development mock and guests, as one Express
@@ -2605,17 +3592,25 @@ nothing is cached:
 | `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, name? }` with the session cookie (and `token` with `guest({ token: true })`)      |
 | `GET /providers`                       | `{ providers: [{ id, name, kind }] }`: the sign-ins served now (`routes.providers()` on the server)                   |
-| `GET /me`                              | `{ userId }`, or 401                                                                                                  |
+| `GET /me`                              | `{ userId }`, or 401; 403 for a cookie from a page `allowedOrigins` does not list                                     |
 | `POST /logout`                         | 204: revokes the session, clears the cookie                                                                           |
 | `POST /logout-all`                     | 204: revokes every session of the user; 401 without a live session                                                    |
 | `/mock/provider/*`                     | the mock provider's own endpoints, while `isMockOAuthEnabled()`                                                       |
 
 - The OAuth state is 256 random bits, sent to the provider and kept in a
   10-minute HttpOnly, SameSite=Lax cookie (`__Host-qd_oauth` on `/` over a
-  secure request, else `qd_oauth` on `basePath`). The callback clears it
-  whatever happens, and accepts only that state, for that provider, within
-  its 10 minutes, once (each redeemed state is remembered by the process),
-  so a sign-in cannot be finished in another browser or replayed.
+  secure request or whenever `publicUrl` is https, else `qd_oauth` on
+  `basePath`). The `__Host-` name is what keeps another site under the
+  same parent domain from planting a state of its own (a state the routes
+  issued to an attacker, to sign the browser in as them): only this host,
+  over HTTPS, can set it. So serve the API over HTTPS with an https
+  `publicUrl`: a plain `qd_oauth` keeps that risk. The cookie is also
+  signed with an HMAC under a key derived from `jwtSecret`, so its state,
+  return origin, provider and age cannot be forged; the MAC does not say
+  which browser a state was issued to. The callback clears it whatever
+  happens, and accepts only that state, for that provider, within its 10
+  minutes, once (each redeemed state is remembered by the process), so a
+  sign-in cannot be finished in another browser or replayed.
 - `returnTo` is an origin or a URL on one; only its origin is kept, and only
   when `allowedOrigins` lists it (exact origins, or patterns anchored with
   `^` and `$`; nothing is read from the environment, and localhost or
@@ -2638,7 +3633,11 @@ nothing is cached:
   the same name, and the server cannot tell which is its own.
 - `me` answers the same 401 whether the request had no credential, a forged
   or expired one, or one whose session was revoked. It, `logout` and
-  `logout-all` read the cookie, else an `Authorization: Bearer` token.
+  `logout-all` read the cookie, else an `Authorization: Bearer` token. A
+  cookie sent from a page `allowedOrigins` does not list is answered 403
+  (`FORBIDDEN`), as on the HTTP transport, and `guest`, which sets the
+  cookie, refuses such a page whatever it sends; a bearer token is not
+  ambient, so any page may send it.
 - `socketAuth` reads a socket's `auth.token` (a bearer token, for clients
   without cookies), else the session cookie from its handshake; an HTTP
   call's credential is the one the transport found. No credential is
@@ -2657,17 +3656,24 @@ nothing is cached:
   a browser sends `Origin` with every POST, so it comes from curl or a
   server rendering a page with the user's forwarded cookie (refused only
   when `Sec-Fetch-Site` names another site). Bearer tokens need no Origin
-  on either transport. An app's own `authenticate` learns where an HTTP
-  call's token came from in `request.credential` (`"cookie"` or
-  `"bearer"`, type `HttpCredentialSource`), applies the same rule with
-  `cookieOriginAllowed(request, allowedOrigins)`, and a
-  `QuickdrawError("FORBIDDEN")` it throws on HTTP is answered as it is.
+  on either transport. An app's own `authenticate` finds an HTTP call's
+  session cookie in `request.sessionCookie`, never in `auth.token` (which
+  holds only a bearer token for it), and `request.credential` says which
+  one the transport chose (`"cookie"` or `"bearer"`, type
+  `HttpCredentialSource`). One that accepts the cookie applies the same
+  rule with `cookieOriginAllowed(request, allowedOrigins)` and checks the
+  session in the store on every call (`liveSession`); a
+  `QuickdrawError("FORBIDDEN")` it throws on HTTP is answered as it is. A
+  hook that takes bearer tokens only (the MCP bridge's `principal`, an
+  `authenticate` reading `auth.token`) uses `bearerAuth`.
 - `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.
+  in development. It runs only when `NODE_ENV` is `development` or `test`:
+  `socketAuth` throws when it is given otherwise (an unset `NODE_ENV`
+  included: set `NODE_ENV=development`), refuses such a handshake once
+  `NODE_ENV` says otherwise, and `createServer` warns at startup while it
+  is on; 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
@@ -2706,8 +3712,10 @@ nothing is cached:
   many users calls from one address: give it its own `keyGenerator` or a
   higher `max`.
 - The mock provider is mounted only while `isMockOAuthEnabled()`
-  (`ENABLE_MOCK_OAUTH=true` and `NODE_ENV` other than `production`), and
-  every request checks again. Set `mock({ internalUrl })` where the API
+  (`ENABLE_MOCK_OAUTH=true` and `NODE_ENV` `development` or `test`; an
+  unset `NODE_ENV` mounts nothing and logs an error saying to set
+  `NODE_ENV=development`), mounting it logs a warning, and every request
+  checks again. Set `mock({ internalUrl })` where the API
   cannot reach itself at `publicUrl`. Routes made with nothing that can
   sign anyone in (only a mock that is off) warn when they are made.
 - `publicUrl` is where providers send the browser back, so a deployment
@@ -2718,33 +3726,57 @@ nothing is cached:
   (`X-Forwarded-Host`, else `Host`) logs an error naming it, once.
 - One rule names the session cookie, written and read: the routes,
   `setSessionCookie`, `socketAuth` and the HTTP transport give a request
-  the same name, and read first the name they would set on it. Without a
+  the same name, and read `__Host-session` first wherever it is present:
+  only this host, over a secure context, can have set it. Without a
   domain, a request over HTTPS reads only `__Host-session`, never
   `session`: another site under the same parent domain can set that cookie
   for the whole domain, and while the user holds no `__Host-session` it
   would sign them in as whoever set it. A plain HTTP request reads
-  `session`, then `__Host-session`. A configured name is read as it is, on
+  `__Host-session`, then `session` (the name the routes set there); when
+  the routes or `setSessionCookie` and `clearSessionCookie` set or clear
+  `session`, they also clear a stale `__Host-session` the request carries,
+  which would otherwise shadow it, or outlive a sign-out. A configured name is read as it is, on
   any request, so a changed name goes in all three places:
   `createAuthRoutes({ cookie: { name } })`, `socketAuth({ cookieName })`
   and `createServer({ http: { cookieName } })`. The transports see the
   cookie's domain through `COOKIE_DOMAIN` only: share the cookie with
   subdomains by setting `COOKIE_DOMAIN`; a `cookie.domain` given only to
   the routes needs `cookieName: "session"` on the other two, and the routes
-  warn at startup until the cookie is named. Behind a proxy that ends TLS,
+  warn at startup until the cookie is named. They also warn for
+  `cookie.domain: ""` while `COOKIE_DOMAIN` is set: the transports then
+  take a `session` cookie over HTTPS too, which the routes never set there
+  and any site under that domain can. Behind a proxy that ends TLS,
   have it send `X-Forwarded-Proto`, which every request carries, so the
   name does not depend on which requests carry an `Origin`.
-- A socket keeps the principal it authenticated with until it reconnects,
-  so a revoked session's open sockets are ended with
+- A socket whose session expires is disconnected then (`io server
+disconnect`; `socketAuth` records the expiry, and an app's own
+  `authenticate` may, through `recordSocketSession(socket, sessionId,
+expiresAt)`, with `expiresAt` a `Date` or epoch milliseconds: a JWT's
+  `exp` is in seconds). A handshake whose recorded session expired before
+  it ended (a slow `loadPrincipal`) is refused, `UNAUTHENTICATED`. Otherwise a socket keeps the principal it authenticated
+  with until it reconnects, so a revoked session's open sockets are ended with
   `server.access.disconnectUser(userId, { sessionId?, reason? })`: every
   socket of the user, or those `socketAuth` recorded for one session
   (`recordSocketSession` on `./server` for an app's own `authenticate`), on
   every node behind a cluster adapter. `onRevoke(userId, sessionId | null)`
   tells the app when `logout` (the session's id) or `logout-all` (`null`)
   revoked; wire it as above. A disconnected client does not reconnect on
-  its own; its next connect is authenticated afresh.
+  its own; its next connect is authenticated afresh. It forgets the user
+  and everything quickdraw cached (`isKnown` false, `status`
+  `"disconnected"`), and calls waiting to be sent when a reconnect is
+  refused fail with `CANCELLED`, so a shared machine shows nothing of
+  theirs.
 - `issueSession({ sessions, jwtSecret }, userId, { provider })` starts a
   session for an app's own sign-in flow (login codes, an embedded activity),
   and `liveSession` reads a token back; both work with `socketAuth`.
+- `bearerAuth({ sessions, jwtSecret, loadPrincipal? })` is `socketAuth`'s
+  counterpart for a hook handed a bearer token alone (the MCP bridge's
+  `principal`, `authenticate: ({ auth }) => verify(auth.token)`): no token
+  is anonymous, a token whose session is not live is refused with
+  `UNAUTHENTICATED`, on every call, and it never reads cookies. It records
+  no socket session: use `socketAuth` for `createServer`. `verifyJWT`
+  checks a token's signature and expiry only, never the store, and warns
+  once in development when it verifies a session token.
 
 From the browser, `./client` speaks to these routes: `authProviders({
 apiUrl })` lists the sign-ins the API serves (`GET /providers`: a provider
@@ -2759,7 +3791,8 @@ and the token `setAuthToken` stored, if any, as a bearer token; the stored
 token is forgotten either way, and a refusal or an unreachable server
 rejects with a `QuickdrawError`. A socket keeps the user it signed in as
 until it connects again, so reconnect the provider's connection after
-signing out (with a token in `auth`, clearing it does that):
+signing out: `connection.close()`, then `open()`, as below, or a reload
+(with a token in `auth`, clearing it does that):
 
 <!-- example: apps/web/src/components/SignIn.tsx#browser -->
 
@@ -2918,9 +3951,10 @@ it("sends a rename to the other members' boards", async () => {
 - Seed rows with the untracked client (`prisma`), or inside `qd.run` once
   an app runs: a tracked write outside any unit of work flushes on its own,
   with an `ambient-write` warning.
-- `app.as(principal)` calls in process and `app.connect(principal)` over a
-  real socket (`{ call, socket, hello, close }`); both are keyed by service
-  name. `app.frames(match?)` lists every frame the server sent, with its
+- `app.as(principal)` calls in process (with transport `"internal"`, or
+  another, below) and `app.connect(principal)` over a real socket
+  (`{ call, socket, hello, close }`); both are keyed by service name.
+  `app.frames(match?)` lists every frame the server sent, with its
   socket and user; `frames.waitFor(match)` waits for one. A query of one
   event (`EventQuery`) takes `where`, a predicate over its frames typed by
   the event (`{ event: "qd:presence", where: ({ data }) => data.joined === id }`), and
@@ -2930,6 +3964,40 @@ it("sends a rename to the other members' boards", async () => {
   `userId`. `emitWithAck` and `waitForEvent` send raw frames and wait for
   events.
 
+`app.as(principal, { transport, mcp })` calls in process as another
+transport would, so a guard that reads `ctx.mcp` or `ctx.transport` is
+tested like any other access. Here the handler example's `assign` (under
+Services), which refuses an agent's token without the `tasks` scope:
+
+<!-- example: apps/api/src/services/task.test.ts#token -->
+
+```ts
+it("lets an agent's token assign tasks only with the tasks scope", async () => {
+  // the handler example's assign, which reads the token's scopes from ctx.mcp
+  const app = await createTestApp({ services: [assigningService], db });
+  const agent: AppPrincipal = { ...ada, kind: "agent", serviceAccess: { taskService: "Moderate" } };
+  const input = { id: taskId, assigneeId: bo.userId };
+  // in process, as an MCP tool call arrives: transport "mcp", and the context hook's fields as ctx.mcp
+  const reader = app.as(agent, { transport: "mcp", mcp: { scopes: [] } });
+  await expect(reader.taskService.assign(input)).rejects.toMatchObject({ code: "FORBIDDEN" });
+  const writer = app.as(agent, { transport: "mcp", mcp: { scopes: ["tasks"] } });
+  expect(await writer.taskService.assign(input)).toMatchObject({ assigneeId: bo.userId });
+  await app.close();
+});
+```
+
+- `transport` is `"internal"` (the default), `"http"` or `"mcp"`; a
+  socket's call is `app.connect`'s. `mcp` is the call's `ctx.mcp`, typed by
+  the app's `QuickdrawTypes["mcp"]`: with `transport: "mcp"` the call is an
+  MCP tool call's, and with the default transport it is a call an MCP call
+  made through `ctx.services`.
+- Bound arguments and the registry's `principal` and `context` hooks belong
+  to the MCP registry, not the dispatcher, so test them through the
+  registry: `registry.callMethod(service, method, input, { request })`
+  calls a method's tool as an agent would, with the input as the method
+  takes it, and resolves with `{ ok: true, data }` or
+  `{ ok: false, error }`.
+
 ### Access matrices
 
 `describeAccessMatrix(app, { service, principals, cases, via? })` runs each
@@ -3097,43 +4165,52 @@ What it does with them:
   (ids and timestamps vary in length) without counting as a change.
 - Await, inside `run`, everything the step should cost: the replies and the
   frames it is about. Measure one step at a time.
-- A few reads happen once per process (the storage adapter asks once
-  whether an order column may hold null). When a step could be the first to
-  pay for one, run it once before measuring it, so its budget does not
-  depend on the order tests run in.
+- Whether an order column may hold null comes from the client's own schema,
+  with no statement; only a client that carries no schema text makes the
+  storage adapter ask the database, once per column and process. When a step
+  could be the first to pay for such a read, run it once before measuring it,
+  so its budget does not depend on the order tests run in.
 
 ### Development warnings
 
 While `NODE_ENV` is not `"production"`, a running app warns about the slow
 and untracked patterns lint cannot see, as they happen. Every warning has
-one format and names the method call it happened in:
+one format and names the method call it happened in (one exception:
+`untracked-access-model` is checked as the server starts and logged as an
+error under `category: "quickdraw.access"`, in every environment, at each
+start):
 
 ```text
 [quickdraw:n-plus-one] taskService.board: task.findUnique by id ran 10 times in one call, once per item (N+1); ...
 ```
 
-| Kind                     | Raised when                                                                                                                                                                                        |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `n-plus-one`             | a call ran 10 statements of one shape (model, operation, `where` keys), outside a `$transaction([])`                                                                                               |
-| `unbounded-read`         | a call ran `findMany` with neither `take` nor ids to read (`id`, `{ in }` or `{ equals }`)                                                                                                         |
-| `oversized-response`     | a reply was larger than `maxResponseBytes` (default 1 MiB)                                                                                                                                         |
-| `nested-write`           | a write's `data` wrote a related row, which is not tracked                                                                                                                                         |
-| `ambient-write`          | a tracked write ran outside any unit of work                                                                                                                                                       |
-| `batch-read`             | a write in an array-form `$transaction` read its rows outside the batch                                                                                                                            |
-| `batch-create-many`      | a `createMany` in an array-form `$transaction` could not report its rows                                                                                                                           |
-| `repeated-call`          | one connection repeated a call or was refused `RATE_LIMITED` again and again (below)                                                                                                               |
-| `tiered-field-in-output` | a method's own output schema declares a field the contract tiers, which only projection outputs strip; raised when the server is made (for an output without JSON Schema, when a reply carries it) |
-| `resolver-without-reads` | a service's policy is, or combines in `anyOf`, a `resolver` without `reads`, so no tracked write re-checks it; raised when the server is made                                                      |
+| Kind                       | Raised when                                                                                                                                                                                                               |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `n-plus-one`               | a call ran 10 statements of one shape (model, operation, `where` keys), outside a `$transaction([])`                                                                                                                      |
+| `unbounded-read`           | a call ran `findMany` with neither `take` nor ids to read (`id`, `{ in }` or `{ equals }`)                                                                                                                                |
+| `oversized-response`       | a reply was larger than `maxResponseBytes` (default 1 MiB)                                                                                                                                                                |
+| `nested-write`             | a write's `data` wrote a related row, which is not tracked                                                                                                                                                                |
+| `ambient-write`            | a tracked write ran outside any unit of work                                                                                                                                                                              |
+| `batch-read`               | a write in an array-form `$transaction` read its rows outside the batch                                                                                                                                                   |
+| `batch-create-many`        | a `createMany` in an array-form `$transaction` could not report its rows                                                                                                                                                  |
+| `repeated-call`            | one connection repeated a call or was refused `RATE_LIMITED` again and again (below)                                                                                                                                      |
+| `tiered-field-in-output`   | a method's own output schema declares a field the contract tiers, which only projection outputs strip; raised when the server is made (for an output without JSON Schema, when a reply carries it)                        |
+| `resolver-without-reads`   | a service's policy is, or combines in `anyOf`, a `resolver` without `reads`, so no tracked write re-checks it; raised when the server is made                                                                             |
+| `untracked-access-model`   | a model a policy, a membership table or a `via` junction depends on has no `id` the write tracker can key its rows by, so no write to it revokes; checked when the server starts, logged as an error in every environment |
+| `shared-principal`         | the handler of a `share: "all"` run (an app's, not a kit's) read `ctx.principal`, `ctx.services`, `ctx.mcp` or `ctx.access`: the run has the first caller's, and every caller gets its result                             |
+| `channel-without-requires` | a channel's contract declares no `requires` and its service no `access`, so every signed-in user may send it; raised when the server is made                                                                              |
 
 Updates and deletes by id inside an interactive transaction are not counted
 toward `n-plus-one`: that is how per-row writes are written (see tracked
 writes). Each is logged once per kind, service, method and subject (the
-model, or the field of a nested write), under `category: "quickdraw.dev"`.
+model, the field of a nested write, or the member a shared run read), under
+`category: "quickdraw.dev"`.
 Only an app's own statements are checked: the framework's reads and the
 kits' own reads are not, while the app's callbacks a kit calls (`prepare`,
 `onChange`, `resolveUser`, a search strategy) are. A statement filtered by
 an `id` list (`{ id: { in: ids } }`, one per chunk of ids) never counts
-toward `n-plus-one`. In tests, `createTestApp({ strictWarnings: true })`
+toward `n-plus-one`, and neither does a `createMany` (one per chunk of
+rows, as a large insert is split). In tests, `createTestApp({ strictWarnings: true })`
 (under vitest or jest) throws every warning raised in that app's method
 calls as a `DevWarningError` where it is raised, so the test that caused it
 fails: the call it happened in fails with `INTERNAL` and the error as its
@@ -3142,9 +4219,10 @@ once the reply was recorded (over a socket or HTTP the reply was already
 sent, so that error is logged, not thrown). Strictness belongs to the app:
 warnings outside its calls (an ambient write while seeding, another app's
 calls) are logged as usual, and `app.close()` ends it. The ones raised when
-the app is made, `tiered-field-in-output` and `resolver-without-reads`, are
-thrown from `createTestApp` itself, so a strict app over such a method or
-policy does not start.
+the app is made, `tiered-field-in-output`, `resolver-without-reads`,
+`untracked-access-model` and `channel-without-requires`, are thrown from
+`createTestApp` itself, so a strict app over such a method, policy, table
+or channel does not start.
 
 A `repeated-call` warning names a client caught in a loop (a mutation fired
 from an effect that its own result runs again, a refetch that triggers
@@ -3280,6 +4358,16 @@ to the test client exactly as in production.
 
 ## Observability
 
+Logs go to `createServer({ logger })`, any logger with Winston's methods
+(default `consoleLogger`). The console default drops `debug` when
+`NODE_ENV` is `"production"`, since a call's record logs at debug with its
+caller's user id: `createConsoleLogger({ level: "debug" })` keeps it, and
+`level: "warn"` drops `info` too. An error is logged with its message and
+stack, but a Prisma client error only with its class, `code`, the schema
+names and codes of its `meta` (never a value, nor the database's own text,
+which quotes the row), the reason a validation error gives, and its stack
+frames: its message renders the call, values included.
+
 `createServer({ stallWatchdog: true })` watches the event loop. It samples
 the loop's delay every 20 ms (`perf_hooks.monitorEventLoopDelay`), reads it
 every 10 s, and logs a warning (`category: "quickdraw.stall"`) when the 99th
@@ -3406,8 +4494,8 @@ so an app can adopt it before fixing old code.
 
 The guards follow one order of preference, so an agent moving fast meets a
 mistake as early as it can be caught: a type error; then a refusal when the
-service is defined (an access form that checks no row on a method that
-takes an `id`, unless it says `rowless: true`); then lint; then a
+service is defined (an access form that asks the policy nothing about the
+row a method's `id` names, unless it says `rowless: true`); then lint; then a
 development warning as it happens (`repeated-call`, `repeated-mutation` and
 `repeated-invalidation` name a client loop before the rate limit does).
 
@@ -3442,22 +4530,23 @@ bunx @fitzzero/quickdraw-codemod v5 .
 
 ## Package exports
 
-| Export             | Holds                                                                                                                                                                                                                                           |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.`                | `defineContract`, `query`, `mutation`, `nullable`, `listOf`, `via`, the kits' contract halves, inference types, `QuickdrawError`, error codes, protocol types, room and topic names                                                             |
-| `./server`         | `initQuickdraw`, `createServer`, `createDispatcher`, `createHttpRouter`, policies, `custom`, the kits' handlers, `requireRow`, `nextOrdinal`, `storageOf`, dev warnings, the Redis adapter, the socket rate limiter, env and encryption helpers |
-| `./server/auth`    | `createAuthRoutes`, `socketAuth`, `requireSession` and `sessionOf`, providers (`google`, `discord`, `mock`, `guest`), session stores, `issueSession`, `liveSession`, JWT, cookie and origin helpers                                             |
-| `./server/express` | Express rate limits: `createAuthLimiter`, `createAuthStatusLimiter`, `createCallLimiter`, `createPublicApiLimiter`, `createWebhookLimiter`                                                                                                      |
-| `./server/mcp`     | `createMcpRegistry`, `describeTools`, `createMcpStdioServer`, `createMcpHttpRouter`, `bootstrapMcpServer`                                                                                                                                       |
-| `./server/otel`    | `otelOnCall`                                                                                                                                                                                                                                    |
-| `./prisma`         | `trackPrisma`, `storageOf`                                                                                                                                                                                                                      |
-| `./client`         | `createQuickdrawClient`, `QuickdrawProvider`, `useQuickdraw`, `usePresence`, `useAdminServices`, `createQuickdrawConnection`, `call`, `callData`, `liveDataOf`, the coordinator; everything in `./utils`                                        |
-| `./utils`          | `createServerCaller`, cache keys (`methodKey`, `entityKey`, `collectionKey`), formatting, navigation, `parseJWTPayload`                                                                                                                         |
-| `./parser`         | the JSON-only Socket.IO parser                                                                                                                                                                                                                  |
-| `./testing`        | `createTestApp`, `describeAccessMatrix`, `snapshotAccessMatrix`, `expectBudget`, `createRecordingSink`, `DevWarningError`                                                                                                                       |
-| `./testing/client` | `renderWithQuickdraw`, and everything in `./testing/mock`                                                                                                                                                                                       |
-| `./testing/mock`   | `createMockClient` alone, without Testing Library: for browser bundles such as Storybook                                                                                                                                                        |
-| `./testing/prisma` | test databases on PostgreSQL or PGlite                                                                                                                                                                                                          |
+| Export             | Holds                                                                                                                                                                                                                                                                        |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.`                | `defineContract`, `query`, `mutation`, `nullable`, `listOf`, `via`, the kits' contract halves, inference types, `QuickdrawError`, error codes, protocol types, room and topic names, `consoleLogger` and `createConsoleLogger`, the types `Tracked` and `TrackedTransaction` |
+| `./server`         | `initQuickdraw`, `createServer`, `createDispatcher`, `createHttpRouter`, policies, `custom`, the kits' handlers, `requireRow`, `nextOrdinal`, `storageOf`, dev warnings, the Redis adapter, the socket rate limiter, env and encryption helpers                              |
+| `./server/auth`    | `createAuthRoutes`, `socketAuth`, `bearerAuth`, `requireSession` and `sessionOf`, providers (`google`, `discord`, `mock`, `guest`), session stores, `issueSession`, `liveSession`, JWT, cookie and origin helpers                                                            |
+| `./server/express` | Express rate limits: `createAuthLimiter`, `createAuthStatusLimiter`, `createCallLimiter`, `createPublicApiLimiter`, `createWebhookLimiter`                                                                                                                                   |
+| `./server/mcp`     | `createMcpRegistry`, `describeTools`, `createMcpStdioServer`, `createMcpHttpRouter`, `bootstrapMcpServer`                                                                                                                                                                    |
+| `./server/otel`    | `otelOnCall`                                                                                                                                                                                                                                                                 |
+| `./prisma`         | `trackPrisma`, `storageOf`, the types `Tracked` and `TrackedTransaction`                                                                                                                                                                                                     |
+| `./client`         | `createQuickdrawClient`, `QuickdrawProvider`, `useQuickdraw`, `usePresence`, `useAdminServices`, `createQuickdrawConnection`, `call`, `callData`, `liveDataOf`, the coordinator; everything in `./utils`                                                                     |
+| `./client/core`    | the client without React or TanStack: `createQuickdrawConnection`, `call`, `callData`, `newId`, the auth helpers, `createPeerLink`, `defineHost`; everything in `./utils`                                                                                                    |
+| `./utils`          | `createServerCaller`, cache keys (`methodKey`, `entityKey`, `collectionKey`), formatting, navigation, `parseJWTPayload`                                                                                                                                                      |
+| `./parser`         | the JSON-only Socket.IO parser                                                                                                                                                                                                                                               |
+| `./testing`        | `createTestApp`, `describeAccessMatrix`, `snapshotAccessMatrix`, `expectBudget`, `createRecordingSink`, `DevWarningError`                                                                                                                                                    |
+| `./testing/client` | `renderWithQuickdraw`, and everything in `./testing/mock`                                                                                                                                                                                                                    |
+| `./testing/mock`   | `createMockClient` alone, without Testing Library: for browser bundles such as Storybook                                                                                                                                                                                     |
+| `./testing/prisma` | test databases on PostgreSQL or PGlite                                                                                                                                                                                                                                       |
 
 The package also ships the `quickdraw-docs` command.