@fitzzero/quickdraw-core 5.0.1 → 5.1.0

package/README.md

@@ -77,6 +77,8 @@ import { z } from "zod";
 import { cardSchema, taskSchema } from "../schemas";
 
 export const taskContract = defineContract("taskService", {
+  // what the service is for: MCP tools and the generated docs show it
+  describe: "Tasks on a project's board.",
   // the full row; it must contain `id: string`
   entity: taskSchema,
   // lean shapes of the row
@@ -103,11 +105,13 @@ export const taskContract = defineContract("taskService", {
       output: z.number(),
       // fetched again whenever the project's board changes
       watch: { collection: "board", scope: (input) => input.projectId },
+      describe: "Counts the tasks on a project's board.",
     }),
   },
   collections: {
     // every task of a project, live, in board order
     board: {
+      describe: "A project's tasks, in board order.",
       scope: "projectId",
       item: "card",
       order: [
@@ -482,25 +486,49 @@ any server code (design: `docs/rfcs/0003-v5.md`, section 2).
 
 ```ts
 export const labelContract = defineContract("labelService", {
+  describe: "Labels a project puts on its tasks.",
   entity: labelSchema,
   projections: { chip: z.object({ id: z.string(), name: z.string() }) },
   methods: {
-    find: query({ input: z.object({ name: z.string() }), output: nullable("entity") }),
-    chips: query({ input: z.object({ projectId: z.string() }), output: listOf("chip") }),
-    usage: query({ input: z.undefined(), output: z.record(z.string(), z.number()) }),
+    find: query({
+      input: z.object({ name: z.string() }),
+      output: nullable("entity"),
+      describe: "Finds a label by its name, or null.",
+    }),
+    chips: query({
+      input: z.object({ projectId: z.string() }),
+      output: listOf("chip"),
+      describe: "Lists a project's labels as chips.",
+    }),
+    usage: query({
+      input: z.undefined(),
+      output: z.record(z.string(), z.number()),
+      describe: "Counts the tasks of each label.",
+    }),
   },
 });
 
 // No entity: an RPC-only service, with no projections, field tiers or collections.
 export const healthContract = defineContract("healthService", {
-  methods: { ping: query({ input: z.undefined(), output: z.literal("pong") }) },
+  describe: "Tells a caller the server is up.",
+  methods: {
+    ping: query({
+      input: z.undefined(),
+      output: z.literal("pong"),
+      describe: "Answers pong while the server runs.",
+    }),
+  },
 });
 ```
 
 - Every method is a `query` or a `mutation`, with an `input` and an
   `output`. The kind decides request sharing, cancellation, the concurrency
-  cap, the MCP read-only hint and which client hook exists. `describe` is the
-  method's description for people and agents (the MCP tool's description).
+  cap, the MCP read-only hint and which client hook exists.
+- Every member takes a `describe`, a sentence or two for people and agents:
+  the contract itself (what the service is for), each method (its MCP tool's
+  description), collection, stream, channel and event. `quickdraw-docs`
+  leads each section of the API docs with it. It is optional in the types;
+  lint's `require-describe` (a warning) lists each member without one.
 - `output` is a schema, or a projection: `"entity"`, a named projection,
   `nullable("entity")` or `listOf("card")`. A handler returns database rows
   for a projection output, and the framework projects them.
@@ -693,10 +721,20 @@ export const taskService = qd.defineService(task, {
       handler: async ({ db }) => (await db.task.updateMany({ data: { status: "archived" } })).count,
     },
     claim: {
-      access: custom((ctx, input) => input.id.length > 0 && ctx.principal.kind === "user"),
+      access: { entry: "Moderate" },
+      // users only: an agent acting for one is refused, whatever its grants
+      kinds: ["user"],
       handler: ({ input, ctx, db }) =>
         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",
+      ),
+      handler: ({ input, db }) =>
+        db.task.update({ where: { id: input.id }, data: { status: input.status } }),
+    },
   },
 });
 ```
@@ -708,6 +746,20 @@ export const taskService = qd.defineService(task, {
   `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`.
+- `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 })`
+  for one service, and a method's own `kinds` (`claim` above). Each level
+  only narrows the one above it: a wider or empty list is refused when the
+  service is defined. A principal of another kind, or without a `kind`,
+  gets `FORBIDDEN` before the form is asked, and no grant passes the check,
+  a service-wide `Admin` grant included, since a token acting with someone's
+  grants is what it stops. An anonymous caller is left to the form, so a
+  `"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).
 - 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
@@ -719,7 +771,8 @@ export const taskService = qd.defineService(task, {
   `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), one that is no object (a bare string
+  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
@@ -977,11 +1030,13 @@ authorizes a scope:
 
 ```ts
 export const task = defineContract("taskService", {
+  describe: "Tasks on a project's board.",
   entity: taskSchema,
   projections: { card: cardSchema },
   methods: { ...crud.contract({ entity: taskSchema, get: true }) },
   collections: {
     byProject: {
+      describe: "A project's open tasks, in board order.",
       // a column holding the scope value
       scope: "projectId",
       // the projection each item is sent as
@@ -998,7 +1053,12 @@ export const task = defineContract("taskService", {
       views: { mine: (row, who) => row.assigneeId === who.userId },
     },
     // each user's own
-    assigned: { scope: "assigneeId", item: "card", order: [["id", "asc"]] },
+    assigned: {
+      describe: "The tasks assigned to a user.",
+      scope: "assigneeId",
+      item: "card",
+      order: [["id", "asc"]],
+    },
   },
 });
 ```
@@ -1141,18 +1201,36 @@ as a 4.x client instead of being refused with `PROTOCOL_MISMATCH`. The shim
 serves request/response calls only: `socket.emit("taskService:get", payload, ack)`
 runs through the 5.0 pipeline and is answered in the 4.x `ServiceResponse`
 shape, `{ success: true, data }` or `{ success: false, error, code }`, with
-the HTTP status of the error code as `code`. 4.x subscriptions, collections
-and channels are not served. Each service, method and principal kind that
-calls through the shim is logged once at `warn`, so the remaining 4.x
-clients can be found.
+the HTTP status of the error code as `code`. A call through the shim runs
+with the `ctx.socketId` and `ctx.rooms` of the socket it arrived on, so a
+handler can put a 4.x client in an app room; it leaves its rooms when it
+disconnects, and `onRoomLeave` and presence hear it as they hear a 5.0
+socket. 4.x subscriptions, collections and channels are not served, and a
+contract's events reach only 5.0 sockets: delivering events to 4.x
+listeners stays the app's own raw emit to the room until those clients
+speak protocol 5. Each service, method and principal kind that calls
+through the shim is logged once at `warn`, so the remaining 4.x clients can
+be found.
+
+A service renamed during the migration keeps its old name for 4.x clients
+through aliases: with `legacyWire: { aliases: { taskService: "cardService" } }`,
+`socket.emit("taskService:get", payload, ack)` runs `cardService.get`, with
+that method's validation, access and `onCall` (grants are read under
+`cardService`, never under the old name). Its log line names the alias, once
+per old name, method and principal kind, so the app can see when the old name
+is no longer called. Each alias must name a registered service and must not be
+one itself, or `createServer` throws. Only 4.x events are aliased: a protocol-5,
+HTTP or MCP call to `taskService` finds no service.
 
 ### MCP bridge
 
 `@fitzzero/quickdraw-core/server/mcp` serves the services to AI agents as MCP
 tools generated from their contracts at startup: one tool per method, named
-`{service}_{method}`, described by the method's `describe` text, with the
+`{service}_{method}`, described by the method's `describe` text (without
+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. Every tool call goes through the dispatcher with transport `"mcp"`,
+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.
@@ -1217,6 +1295,68 @@ createMcpStdioServer({ registry, name: "my-app", version: "1.0.0" });
   list with `exclude` or `include`, per registry, and serve agents of
   different reach from separate registries.
 
+`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
+agent's token names its project as a verified claim (`principal.claims`):
+
+<!-- example: apps/api/src/mcp.ts#bind -->
+
+```ts
+// agents bound to one project: an agent's token names it as a verified claim
+const projectAgents = createMcpRegistry({
+  services: [taskService],
+  dispatcher: server.dispatcher,
+  // agent tokens only: anyone else is anonymous, and every tool here refuses them
+  principal: (request) =>
+    verifyAgentToken(request.transport === "http" ? request.token : process.env.AGENT_TOKEN),
+  // filled from the claim on every call, and left out of every tool's arguments
+  bind: { projectId: ({ principal }) => principal.claims?.projectId },
+  include: ["taskService.create", "taskService.countOnBoard"],
+  // the tools' public names: create_task and count_tasks
+  name: (_service, method) => (method === "create" ? "create_task" : "count_tasks"),
+});
+
+// beside the first registry, at a path of its own: GET /agents/tools, POST /agents/invoke
+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.
+- 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
+  that throws fails the call with `INTERNAL`, or with the code of the
+  `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.
+- 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.
+- Binding is not access control. The same principal reaches the method over a
+  socket or HTTP with nothing bound, so the method's access must still
+  confine it to its project.
+
+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`.
+- **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
+  tool's arguments on the way in: such a tool would be invisible to the API
+  docs and to lint, which read the contracts.
+
 ## The client
 
 `createQuickdrawClient(contracts)` builds one typed client from the
@@ -1524,6 +1664,7 @@ const newTaskSchema = z.object({ projectId: z.string(), title: z.string() });
 const taskPatch = z.object({ title: z.string(), status: z.string() }).partial();
 
 export const task = defineContract("taskService", {
+  describe: "Tasks on a project's board.",
   entity: taskSchema,
   projections: { card: cardSchema },
   methods: {
@@ -1541,7 +1682,11 @@ export const task = defineContract("taskService", {
       bulkUpdate: { input: taskPatch },
       bulkDelete: true,
     }),
-    archive: mutation({ input: z.object({ id: z.string() }), output: "entity" }),
+    archive: mutation({
+      input: z.object({ id: z.string() }),
+      output: "entity",
+      describe: "Archives a task, which leaves its board.",
+    }),
   },
 });
 ```
@@ -1686,6 +1831,7 @@ import { defineContract, search } from "@fitzzero/quickdraw-core";
 import { cardSchema, taskSchema } from "../schemas";
 
 export const task = defineContract("taskService", {
+  describe: "Tasks on a project's board.",
   entity: taskSchema,
   projections: { card: cardSchema },
   methods: {
@@ -1700,6 +1846,7 @@ export const task = defineContract("taskService", {
   },
   collections: {
     byProject: {
+      describe: "A project's tasks, in board order.",
       scope: "projectId",
       item: "card",
       order: [
@@ -1825,6 +1972,7 @@ import { z } from "zod";
 const projectSchema = z.object({ id: z.string(), name: z.string() });
 
 export const project = defineContract("projectService", {
+  describe: "Projects and the people they are shared with.",
   entity: projectSchema,
   methods: {
     // the JSON access list jsonAcl reads: share, unshare, setLevel, listShares
@@ -1838,6 +1986,7 @@ export const project = defineContract("projectService", {
   collections: {
     // each user's projects: an invite adds the project, a remove or a leave takes it out
     mine: {
+      describe: "The projects a user is a member of.",
       scope: via({ model: "projectMember", entry: "projectId", scope: "userId" }),
       item: "entity",
       order: [["id", "asc"]],
@@ -1931,6 +2080,7 @@ import { admin, defineContract } from "@fitzzero/quickdraw-core";
 import { taskSchema } from "../schemas";
 
 export const task = defineContract("taskService", {
+  describe: "Tasks on a project's board.",
   // Zod 4.2 or later: the fields come from its JSON Schema
   entity: taskSchema,
   methods: {
@@ -2114,28 +2264,48 @@ const cursorSchema = z.object({ projectId: z.string(), taskId: z.string(), x: z.
 const logLineSchema = z.object({ line: z.string() });
 
 export const task = defineContract("taskService", {
+  describe: "Tasks on a project's board.",
   entity: taskSchema,
   methods: {
-    enterBoard: mutation({ input: z.object({ projectId: z.string() }), output: z.boolean() }),
+    enterBoard: mutation({
+      input: z.object({ projectId: z.string() }),
+      output: z.boolean(),
+      describe: "Joins the caller's socket to a project's board room.",
+    }),
   },
   streams: {
     // one feed per task; a subscriber needs Read on the task, and first gets the latest 50 lines
-    logs: { item: logLineSchema, scope: "taskId", seed: 50, access: { entry: "Read" } },
+    logs: {
+      item: logLineSchema,
+      scope: "taskId",
+      seed: 50,
+      access: { entry: "Read" },
+      describe: "A task's log lines, as its job writes them.",
+    },
     // one feed for everyone
-    load: { item: z.number(), volatile: true, access: "authenticated" },
+    load: {
+      item: z.number(),
+      volatile: true,
+      access: "authenticated",
+      describe: "The server's load, sampled every second.",
+    },
   },
   channels: {
     // 20 a second per socket; only from a socket in the board's room, which enterBoard joined
     cursor: {
+      describe: "Where a user's cursor is on a task card.",
       payload: cursorSchema,
       ratePerSecond: 20,
       requires: { room: (cursor) => `board:${cursor.projectId}` },
     },
   },
   events: {
-    cursorMoved: { payload: cursorSchema },
+    cursorMoved: { payload: cursorSchema, describe: "Another user's cursor moved." },
     // a user's last socket left a board: `onRoomLeave` sends it
-    leftBoard: { payload: z.object({ projectId: z.string(), userId: z.string() }) },
+    leftBoard: {
+      payload: z.object({ projectId: z.string(), userId: z.string() }),
+      describe: "A user left a project's board.",
+    },
   },
 });
 ```
@@ -2795,7 +2965,83 @@ for real, once per allowed principal: give inputs that can run again, or
 `MatrixCell` `{ name, principal }`, sync or async), called before each
 cell's call, that makes a row of its own (a task
 to delete, an unused name), so no cell depends on the order of the
-principals.
+principals. Each cell of the report records its principal's `kind`, and a
+cell that differs is listed with it: on a service or method with `kinds`,
+give the matrix a principal of each kind it refuses.
+
+### Access snapshots
+
+`snapshotAccessMatrix(app, { principals, reset, rows })` records the whole
+matrix instead of chosen cases: every method of the app's services (or of
+`services`), each entity subscribe (`qd:sub`) and each collection scope
+(`qd:col:sub`), as every principal and anonymously. The first run writes the
+outcomes to `__access__/<test file>.json` beside the test, and every later
+run compares its matrix with that file, so each changed cell is a decision
+someone made. Commit the file. Use it to pin a service's table, and before
+a migration, a policy refactor or a new kind of principal:
+
+<!-- example: apps/api/src/services/task.test.ts#snapshot -->
+
+```ts
+it("pins who may call what, for every method, subscribe and scope", async () => {
+  const app = await createTestApp({ services: [projectService, taskService], db });
+  const report = await snapshotAccessMatrix(app, {
+    principals: { owner: ada, member: bo, stranger: ed },
+    reset: async () => {
+      await resetDatabase(prisma); // at the start, and after each write access let through
+      return await seed();
+    },
+    rows: (board) => ({ projectService: board.projectId, taskService: board.taskId }),
+  });
+  expect(report.inconclusive).toEqual([]); // every cell ran, with an input its schema accepts
+  await app.close();
+});
+```
+
+- `reset()` empties the database and seeds it (`resetDatabase` from
+  `./testing/prisma`, then the app's seed, with the untracked client), and
+  resolves with what the seed made: the fixture. It runs first, and again
+  after every mutation the pipeline did not refuse, so no cell sees the
+  writes of another. `principals` may be a function of the fixture, for a
+  seed that makes new ids; its names stay the same.
+- `rows(fixture)` names the row each service's cells are about: a row id,
+  or named variants (`{ own: p1, other: p2 }`), each a row of the matrix of
+  its own. It names every service an access form, an entity subscribe or a
+  collection anchor of the matrix reads; a missing one is a `TypeError`
+  before any cell runs. A `"self"` scope is subscribed with the caller's own
+  user id.
+- Inputs are made from each method's input schema (Zod 4.2 or later
+  describes itself as JSON Schema): the row goes where the access form reads
+  it (`id`, the key an `entry` or `scope` form names, or where a function
+  `id` finds it; for any other form, the input's `id`), and every other
+  required value is as small as the schema allows. `inputs(ref, fixture)`
+  gives a method's input instead (`ref` names the service, method, kind,
+  variant, row and principal of the cell); `undefined` keeps the made one.
+  A cell whose input fails the schema, or names no row where an `entry` or
+  `scope` form reads it, is never called: it is `VALIDATION`, and the
+  report lists it in `inconclusive`.
+- Each cell is the exact outcome: `"ok"`, or the error code
+  (`UNAUTHENTICATED`, `FORBIDDEN`, `NOT_FOUND`, ...). Each principal's
+  `kind` is recorded beside the cells.
+- A cell whose outcome changed fails, naming the cell, both outcomes and
+  whether the change opens or closes access (a changed `kind` fails too):
+
+  ```text
+  snapshotAccessMatrix: 1 cell differs from the access snapshot (src/services/__access__/task.test.ts.json):
+    taskService.rename as member: FORBIDDEN → ok (opens access)
+  ```
+
+  When each change is meant, run the tests with
+  `QD_UPDATE_ACCESS_SNAPSHOT=1` and commit the file.
+
+- Cells added or removed (a new method, principal or exclusion) rewrite the
+  file in a local run. Under CI (`CI=1` or `CI=true`) they fail, and so do a
+  missing file and `QD_UPDATE_ACCESS_SNAPSHOT`: a snapshot that writes
+  itself pins nothing.
+- Leave out a method whose outcome differs from run to run with
+  `exclude: ["taskService.roll"]`; the file lists it. Take one snapshot per
+  test file (one test file per service keeps merges small), or pass
+  `{ file }`.
 
 ### Performance budgets
 
@@ -3084,10 +3330,13 @@ is also a server span named `service.method`, with an error status for
 ## API docs from contracts
 
 The `quickdraw-docs` command writes Markdown API docs from the contracts:
-one page per service (its entity and field tiers, projections, methods
-with their kind, input fields and output, collections, streams, channels
-and events, from the schemas' JSON Schema where they have one) and a
-`README.md` index. It reads contracts (and, with `--services`, the
+one page per service (its `describe`, its entity and field tiers,
+projections, methods with their `describe`, kind, default MCP tool name
+(`{service}_{method}`: a registry's `name`, `include` and `exclude` options
+are not visible to the command), the MCP read-only hint on a query, input
+fields and output, collections, streams, channels and events with their
+`describe`, from the schemas' JSON Schema where they have one) and a
+`README.md` index that lists each service's `describe`. It reads contracts (and, with `--services`, the
 services' definitions), never source code.
 
 ```bash
@@ -3103,9 +3352,18 @@ definitions: an "Access" section with the row policy, whether a
 service-wide `Admin` grant passes every check, who may watch the change
 topic (`watchAccess`) and the field levels; each method's access form, in
 words, and its `rowless`; who may open a collection's scope; a channel's
-access; a stream's computed seed and when its items are checked. A
-contract the services module has no service for says so, and a service
-without a contract is an error. Pass the same flag to `--check`. The
+access; a stream's computed seed and when its items are checked. Each
+page also gets a "Depends on" section: the other services its
+declarations name, and which declaration names each one. A service depends
+on another when its row policy `inherit`s from it, it `writes` the model
+that service's rows live in, it `affects` that service's rows, one of its
+methods, channels or streams takes a `{ scope, of }` form of it, or one of
+its collections is anchored on that service's rows. A `writes` model that no
+service's rows live in is listed as a model. The index adds a Mermaid
+`graph LR` of the same edges, each labelled with how. Only declarations are
+read: a handler that reads another service's rows without declaring it adds
+nothing. A contract the services module has no service for says so, and a
+service without a contract is an error. Pass the same flag to `--check`. The
 services module is imported with everything it imports, as the server
 loads it: the workspace packages it uses (`@project/db`, `@project/shared`)
 load from their built output when their `package.json` points there, so
@@ -3121,7 +3379,19 @@ extensionless imports and `tsconfig` paths, which Node's loader refuses); a
 module whose own code throws runs once and its error is reported as is. Pages are only ever replaced
 or removed when they start with the generator's marker, and they are laid
 out as oxfmt and Prettier format Markdown, so formatting them changes
-nothing. Run `--check` in CI next to the lint step.
+nothing.
+
+Where the pages live depends on how busy the repository is:
+
+- **Few pull requests at a time:** commit the pages and run `--check` in
+  CI next to the lint step.
+- **Many at a time** (several agents, each changing methods): a committed
+  generated file is a merge conflict in every pair of pull requests that
+  touch contracts. Regenerate the pages on each push to the base branch
+  instead, with the workflow the `quickdraw-api-docs` skill of
+  [`@fitzzero/quickdraw-skills`](https://github.com/fitzzero/quickdraw/tree/main/packages/skills) ships (a job with a
+  read-only token generates them, a second job commits them), and never
+  commit them by hand.
 
 ## Lint rules and agent guidance
 
@@ -3129,7 +3399,8 @@ nothing. Run `--check` in CI next to the lint step.
 config every 5.0 app extends: it reports untracked and foreign writes, nested
 and raw SQL writes, hand-sent frames, inline auth guards, unbounded reads,
 database calls and emits in loops, layering breaks, bypasses of the typed
-client, hand-written copies of kit methods (`prefer-kit`, a warning), and
+client, hand-written copies of kit methods (`prefer-kit`, a warning),
+contract members without a `describe` (`require-describe`, a warning), and
 every removed 4.x API with its replacement. Each rule supports a baseline,
 so an app can adopt it before fixing old code.
 
@@ -3183,7 +3454,7 @@ bunx @fitzzero/quickdraw-codemod v5 .
 | `./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`, `expectBudget`, `createRecordingSink`, `DevWarningError`                                                                                                                                               |
+| `./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                                                                                                                                                                                                          |

package/dist/{admin-CBlTY0do.d.ts → admin-DKwkIh5i.d.ts}

@@ -1,5 +1,5 @@
-import { e as StandardSchemaWithJSON, d as StandardSchemaV1, I as InferInput, c as InferOutput, X as RowSchema, Q as QueryDef, P as ProjectionList, p as MutationDef, J as AnyContract, ap as MethodName } from './infer-Dw21kmLw.js';
-import { d as ListSort, c as ListQuery, b as ListPage, D as AdminWritable, u as AdminListInput, v as AdminListQuery, y as AdminPage, r as AdminCreateInput, s as AdminCreateQuery, B as AdminUpdateInput, C as AdminUpdateQuery, w as AdminMetaInput, n as AdminServiceMeta, z as AdminSubscribers } from './adminSchemas-zji11V74.js';
+import { e as StandardSchemaWithJSON, d as StandardSchemaV1, I as InferInput, c as InferOutput, X as RowSchema, Q as QueryDef, P as ProjectionList, p as MutationDef, J as AnyContract, ap as MethodName } from './infer-Teo1xpsd.js';
+import { d as ListSort, c as ListQuery, b as ListPage, D as AdminWritable, u as AdminListInput, v as AdminListQuery, y as AdminPage, r as AdminCreateInput, s as AdminCreateQuery, B as AdminUpdateInput, C as AdminUpdateQuery, w as AdminMetaInput, n as AdminServiceMeta, z as AdminSubscribers } from './adminSchemas-2DUA_hZ8.js';
 
 /** A schema a kit generates: validation, and its JSON Schema. */
 type KitSchema<Input, Output = Input> = StandardSchemaWithJSON<Input, Output>;

package/dist/{adminSchemas-zji11V74.d.ts → adminSchemas-2DUA_hZ8.d.ts}

@@ -1,4 +1,4 @@
-import { z as SortDirection, A as AccessLevel } from './infer-Dw21kmLw.js';
+import { z as SortDirection, A as AccessLevel } from './infer-Teo1xpsd.js';
 
 /** `list`'s page size when the caller gives none. */
 declare const LIST_DEFAULT_LIMIT = 50;

package/dist/{auth-CMyRkfjZ.d.ts → auth-BhWqdyb-.d.ts}

@@ -1,7 +1,7 @@
 import { IncomingMessage, IncomingHttpHeaders } from 'node:http';
 import { Socket } from 'socket.io';
-import { A as AccessLevel } from './infer-Dw21kmLw.js';
-import { P as Principal, M as MaybePromise } from './types-Bwg3kIEc.js';
+import { A as AccessLevel } from './infer-Teo1xpsd.js';
+import { P as Principal, M as MaybePromise } from './types-Cu0vmx7c.js';
 
 /**
  * A request as Express leaves it: maybe with `body` from `express.json()`,

package/dist/{caller-BqCYnpmC.d.ts → caller-CXTFswBO.d.ts}

@@ -1,7 +1,7 @@
-import { ad as Version, a5 as Revision } from './envelope-nf5eGB-a.js';
+import { ad as Version, a5 as Revision } from './envelope-Cp3YcVxC.js';
 import { L as Logger } from './logger-BY28acW-.js';
-import { A as AccessLevel, J as AnyContract, y as CollectionWhere, O as OrderBy, k as MethodKind, d as StandardSchemaV1, ag as EventName, ah as EventPayloadOf, aa as ChannelName, ab as ChannelPayloadOf, az as StreamName, am as IsScopedStream, ay as StreamItemOf, ae as ContractMap, ap as MethodName, al as InputOf, ar as OutputOf } from './infer-Dw21kmLw.js';
-import { P as Principal, Q as QuickdrawTypes, M as MaybePromise, c as PrincipalOf, a as McpContext, T as Transport, C as ContextExtensionOf, b as McpContextOf, D as DbOf } from './types-Bwg3kIEc.js';
+import { A as AccessLevel, J as AnyContract, y as CollectionWhere, O as OrderBy, k as MethodKind, d as StandardSchemaV1, ag as EventName, ah as EventPayloadOf, aa as ChannelName, ab as ChannelPayloadOf, az as StreamName, am as IsScopedStream, ay as StreamItemOf, ae as ContractMap, ap as MethodName, al as InputOf, ar as OutputOf } from './infer-Teo1xpsd.js';
+import { P as Principal, Q as QuickdrawTypes, M as MaybePromise, c as PrincipalOf, a as McpContext, T as Transport, C as ContextExtensionOf, b as McpContextOf, D as DbOf } from './types-Cu0vmx7c.js';
 
 /** What a development warning is about. */
 type DevWarningKind = "n-plus-one" | "unbounded-read" | "oversized-response" | "nested-write" | "ambient-write" | "batch-read" | "batch-create-many" | "repeated-call" | "tiered-field-in-output" | "resolver-without-reads";
@@ -381,6 +381,14 @@ interface ServiceMethod {
      */
     readonly schemaOutput: SchemaOutput | undefined;
     readonly access: AccessForm;
+    /**
+     * The kinds of principal that may call the method (RFC 0003 section 4.1):
+     * its own `kinds`, else its service's, else the app's (`initQuickdraw`);
+     * `undefined` admits every kind. A principal of another kind, or without
+     * one, gets `FORBIDDEN` before the access form is asked; an anonymous
+     * caller is left to the form.
+     */
+    readonly kinds: readonly string[] | undefined;
     readonly handler: AnyHandler;
     readonly share: ShareMode | undefined;
     /** How long a shared result is reused after its run, in milliseconds. */
@@ -439,6 +447,13 @@ interface Service<T extends QuickdrawTypes = QuickdrawTypes, C extends AnyContra
     readonly watchAccess: WatchAccess | undefined;
     /** Whether a service-wide `Admin` grant passes every access check of this service. */
     readonly adminBypass: boolean;
+    /**
+     * The kinds of principal the service admits (RFC 0003 section 4.1): its
+     * own `kinds`, else the app's (`initQuickdraw`); `undefined` admits every
+     * kind. Its methods narrow it, and its subscriptions (`qd:sub`,
+     * `qd:col:sub`, `qd:watch`, `qd:stream:sub`) and channels check it.
+     */
+    readonly kinds: readonly string[] | undefined;
     /** The checked method records, by method name. */
     readonly methods: Readonly<Record<string, ServiceMethod>>;
     /** The contract's channels with the handlers `defineService` gave them (RFC 0003 section 12.5). */
@@ -905,6 +920,12 @@ interface ServiceChannel {
         readonly prefix: string;
     } | undefined;
     readonly access: ChannelAccess;
+    /**
+     * The kinds of principal the channel's service admits, as a set for the
+     * per-message check: a message from a socket of another kind, or without
+     * one, is dropped. `undefined` admits every kind.
+     */
+    readonly kinds: ReadonlySet<string> | undefined;
     readonly handler: AnyChannelHandler;
 }
 /** One stream of a defined service, checked and ready to serve. */
@@ -982,7 +1003,8 @@ interface BaseContext<P = Principal, M = McpContext> {
     /**
      * The socket the call arrived on: its id, as the client socket's `id`,
      * `onRoomLeave`'s `socketId` and a channel handler's `ctx.socketId` name
-     * it (a game keys a player's input by it). `undefined` for a call that
+     * it (a game keys a player's input by it). A call through the 4.x legacy
+     * shim has it too: it arrived on a socket. `undefined` for a call that
      * did not arrive over a socket: HTTP, MCP, in process, `ctx.services`. In
      * a method that shares its runs (`share`), the first caller's.
      */
@@ -1226,4 +1248,4 @@ type CallerFor<T extends QuickdrawTypes> = T extends {
     readonly contracts: infer Contracts extends ContractMap;
 } ? Caller<Contracts[keyof Contracts]> : Caller<AnyContract>;
 
-export { type ProjectedOutput as $, type AnyService as A, type PublicAccess as B, type CountArgs as C, DevWarningError as D, type HandlerArgs as E, type FindManyArgs as F, type CustomAccess as G, type HandlerContext as H, type ShareMode as I, type ChannelOptions as J, type StreamOptions as K, type ChannelsRequired as L, type ModelName as M, type BaseContext as N, type CallerFor as O, type Presence as P, type AccessPolicy as Q, type RowLevels as R, type StorageAdapter as S, type AnyAccessPolicy as T, type UnitOfWorkFactory as U, type PolicyColumns as V, type WriteRecord as W, type PolicyForeign as X, type PolicyTools as Y, type RowAccess as Z, type AffectsLink as _, type StorageRow as a, type Projection as a0, type TierGroup as a1, type Tiers as a2, DEFAULT_BULK_THRESHOLD as a3, type CollectionScope as a4, type ServiceCollection as a5, type ContextRooms as a6, type ContextServices as a7, type TouchOptions as a8, type ChannelAccess as a9, type AccessForm as aA, type AccessRequest as aB, type AuthenticatedAccess as aC, type EntryAccess as aD, type IdKeyOf as aE, type IdSelector as aF, type ScopeAccess as aG, type ServiceAccess as aH, ANY_FIELD as aI, type UnitOfWork as aJ, type UnitOfWorkScope as aK, formatDevWarning as aL, N_PLUS_ONE_STATEMENTS as aM, type ChannelContext as aa, type ChannelHandler as ab, type ChannelImplementation as ac, type ChannelRoomOf as ad, type RoomLeave as ae, type RoomLeaveReason as af, type RoomLeft as ag, type RoomTarget as ah, type ServiceChannel as ai, type ServiceStream as aj, type StreamImplementation as ak, type StreamPushArgs as al, type StreamPushManyArgs as am, type StreamSeed as an, type StreamSeedContext as ao, type StreamValidation as ap, type CallOptions as aq, type MethodCaller as ar, type ServiceCaller as as, type ForeignColumns as at, type ForeignColumnsOf as au, type MembershipRead as av, type ParentLink as aw, type PolicyKind as ax, type PolicyReads as ay, type RowLevel as az, type StorageWhere as b, type StatementCount as c, type FlushSink as d, type FlushInfo as e, type Service as f, type DevWarning as g, type DevWarningKind as h, type Caller as i, type ServiceMethod as j, type AccessFilter as k, type RunContext as l, type RunOptions as m, type ServerRooms as n, type StreamHandle as o, type AnyContext as p, type AccessEngine as q, type AppRooms as r, storageOf as s, type StreamSubscriptions as t, type RoomLeaveHandler as u, type PolicyFor as v, type RowForms as w, type AccessFor as x, type ModelColumn as y, type WatchAccess as z };
+export { type ProjectedOutput as $, type AnyService as A, type PublicAccess as B, type CountArgs as C, DevWarningError as D, type HandlerArgs as E, type FindManyArgs as F, type CustomAccess as G, type HandlerContext as H, type ShareMode as I, type ChannelOptions as J, type StreamOptions as K, type ChannelsRequired as L, type ModelName as M, type BaseContext as N, type CallerFor as O, type Presence as P, type AccessPolicy as Q, type RowLevels as R, type StorageAdapter as S, type AnyAccessPolicy as T, type UnitOfWorkFactory as U, type PolicyColumns as V, type WriteRecord as W, type PolicyForeign as X, type PolicyTools as Y, type RowAccess as Z, type AffectsLink as _, type StorageRow as a, type Projection as a0, type TierGroup as a1, type Tiers as a2, DEFAULT_BULK_THRESHOLD as a3, type CollectionScope as a4, type ServiceCollection as a5, type ContextRooms as a6, type ContextServices as a7, type TouchOptions as a8, type ChannelAccess as a9, type AccessForm as aA, type AccessRequest as aB, type AuthenticatedAccess as aC, type EntryAccess as aD, type IdKeyOf as aE, type IdSelector as aF, type ScopeAccess as aG, type ServiceAccess as aH, ANY_FIELD as aI, type UnitOfWork as aJ, type UnitOfWorkScope as aK, formatDevWarning as aL, N_PLUS_ONE_STATEMENTS as aM, type ChannelContext as aa, type ChannelHandler as ab, type ChannelImplementation as ac, type ChannelRoomOf as ad, type RoomLeave as ae, type RoomLeaveReason as af, type RoomLeft as ag, type RoomTarget as ah, type ServiceChannel as ai, type ServiceStream as aj, type StreamImplementation as ak, type StreamPushArgs as al, type StreamPushManyArgs as am, type StreamSeed as an, type StreamSeedContext as ao, type StreamValidation as ap, type CallOptions as aq, type MethodCaller as ar, type ServiceCaller as as, type ForeignColumns as at, type ForeignColumnsOf as au, type MembershipRead as av, type ParentLink as aw, type PolicyKind as ax, type PolicyReads as ay, type RowLevel as az, type StorageWhere as b, type StatementCount as c, type Caller as d, type FlushSink as e, type FlushInfo as f, type ServiceMethod as g, type Service as h, type DevWarning as i, type DevWarningKind as j, type AccessFilter as k, type RunContext as l, type RunOptions as m, type ServerRooms as n, type StreamHandle as o, type AnyContext as p, type AccessEngine as q, type AppRooms as r, storageOf as s, type StreamSubscriptions as t, type RoomLeaveHandler as u, type PolicyFor as v, type RowForms as w, type AccessFor as x, type ModelColumn as y, type WatchAccess as z };