@fitzzero/quickdraw-core 5.0.0 → 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
@@ -734,16 +787,23 @@ export const taskService = qd.defineService(task, {
   (`qd:access`), and in-process callers load the grants again.
 - Policies: `owner(field)`, `jsonAcl(field, { owner? })`,
   `members({ model, entry, user, level, levels? })`, `inherit({ from, via })`,
-  `anyOf(...)`, `resolver({ levelsFor, where? })` and `everyone(level)`
+  `anyOf(...)`, `resolver({ levelsFor, where?, reads })` and `everyone(level)`
   (every signed-in user has `level` on every row, reading nothing: public
   profiles are `anyOf(owner("id"), everyone("Read"))`; unlike `rowless: true`
-  on a method, it covers subscriptions and lists too). Their column names are
-  checked against the Prisma client's models at compile time. A lookup is one
-  batched query per table, memoized for the call, so checking 60 ids costs
-  what checking one does. `entry` access needs a policy; a service without
-  `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.
+  on a method, it covers subscriptions and lists too). A `resolver` is app
+  code, so it says what its levels depend on: `reads: { columns, memberships }`
+  names columns of the service's model and membership tables as `members`
+  takes them (`entry` holding this service's row id), and tracked writes to
+  them re-check what it decided, as for the other policies; `reads: "none"`
+  says nothing a tracked write changes can change a level (the principal's
+  grants alone, say). A resolver with neither is never re-checked, and the
+  server warns `[quickdraw:resolver-without-reads]` when it starts. Their
+  column and table names are checked against the Prisma client's models at
+  compile time. A lookup is one batched query per table, memoized for the
+  call, so checking 60 ids costs what checking one does. `entry` access
+  needs a policy; a service without `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.
 - 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
@@ -970,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
@@ -991,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"]],
+    },
   },
 });
 ```
@@ -1134,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.
@@ -1210,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
@@ -1517,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: {
@@ -1534,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.",
+    }),
   },
 });
 ```
@@ -1679,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: {
@@ -1693,6 +1846,7 @@ export const task = defineContract("taskService", {
   },
   collections: {
     byProject: {
+      describe: "A project's tasks, in board order.",
       scope: "projectId",
       item: "card",
       order: [
@@ -1818,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
@@ -1831,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"]],
@@ -1924,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: {
@@ -1948,6 +2105,8 @@ export const taskService = qd.defineService(task, {
       displayName: "Tasks",
       // never shown, returned or written
       hiddenFields: ["notes"],
+      // the only fields adminCreate and adminUpdate write; the rest are read-only
+      editable: ["title", "status"],
       fieldOverrides: { assigneeId: { type: "relation", relationService: "userService" } },
     }),
   },
@@ -2005,12 +2164,24 @@ export function AdminTasks() {
   `adminUpdate({ id, data })` write the entity's fields through the tracked
   client, so subscribers and collections get the same frames as for any
   other write; `adminDelete({ id })` returns `null`. `id`, `createdAt` and
-  `updatedAt` are never writable, nor are hidden fields or those an override
-  made read-only (`VALIDATION`); without a 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`.
+  `updatedAt` are never writable, nor are hidden fields, those an override
+  made read-only or those `editable` leaves out (`VALIDATION`); without a
+  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`.
+- `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
+  naming one is `VALIDATION` ("is not editable"). Each must be a field the
+  kit shows, never `id` or a timestamp, and a `fieldOverrides` entry may
+  not say otherwise. `admin.contract({ entity, editable })` takes the same
+  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.
 - `adminMeta()` returns `{ serviceName, displayName, fields }`, one
   `{ name, type, label, required, editable, showInTable, sortable, filterable, enumValues?, relationService?, kind?, showInForm? }`
   per field: `type` is
@@ -2093,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.",
+    },
   },
 });
 ```
@@ -2774,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
 
@@ -2856,6 +3123,7 @@ one format and names the method call it happened in:
 | `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                                                      |
 
 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
@@ -2873,9 +3141,10 @@ fails: the call it happened in fails with `INTERNAL` and the error as its
 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 one raised when
-the app is made, `tiered-field-in-output`, is thrown from `createTestApp`
-itself, so a strict app over such a method does not start.
+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.
 
 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
@@ -3061,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
@@ -3080,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
@@ -3098,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
 
@@ -3106,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.
 
@@ -3160,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                                                                                                                                                                                                          |