@fitzzero/quickdraw-skills 5.1.2 → 5.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitzzero/quickdraw-skills",
-  "version": "5.1.2",
+  "version": "5.1.3",
   "description": "Agent rules and skills for quickdraw 5.0 apps, linked into .claude/ by the quickdraw-skills command",
   "keywords": [
     "agents",

package/rules/quickdraw-access.md

@@ -109,6 +109,53 @@ triage: {
   it; elsewhere it acts with its user's grants (`kinds` keeps a kind of
   token out).
 
+## A row the form cannot name
+
+A check of the caller's level on a row no declared form names (a parent
+the input names, a key that is optional) is a `custom` form that asks
+`ctx.access`: never a check in the handler, and never a module that holds
+the dispatcher.
+
+```ts
+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,
+    });
+  },
+},
+```
+
+- `ctx.access.can(service, id, level)`, `levelsFor(service, ids)` and
+  `where(service, level)` count levels as `{ entry }` does, for
+  `ctx.principal` with the grants the call runs with: never load the user's
+  grants again. `service` is a contract or a service name.
+- A list the form lets through without its key still follows the row
+  policy: add `ctx.access.where(service, "Read")` to its `findMany` with
+  `AND` (`"none"` lists nothing). Never spread it into `where`: the filter
+  and the input share a column (`inherit`'s `projectId`), so whichever
+  comes last replaces the other. The filter's widens the keyed list to
+  every project the caller reads; the input's `undefined` drops the policy
+  from the list without a key.
+- Prefer a declared form when one says it: `{ entry: L }` for the method's
+  own row, `{ scope: L, of, id }` for a parent whose key is always there.
+  A `ctx.access` form counts a service-wide `Admin` grant on the service it
+  asks (the parent's); `{ scope, of }` counts only one on the method's own
+  service. `custom` replaces the row check and a
+  service-wide `Admin` grant skips it, so a method whose input has `id`
+  still needs `rowless: true` beside it (below).
+- An anonymous caller has no level anywhere (`false`, an empty map,
+  `"none"`). `qd` has no `access`: a job asks `server.dispatcher.access`.
+
 ## A method that takes a row id
 
 On a service with a policy, a method whose input has `id` reads or writes
@@ -231,6 +278,12 @@ channel `requires`.
   item service `inherit` from the anchor, or use separate scopes. A self
   scope (`scopeAccess: "self"`) is the exception: its items follow the item
   service's policy, so its user gets only the rows they may read.
+- A list whose methods need a service-wide grant (`{ service: "Read" }`)
+  needs it too: `requires: { service: "Read" }` beside its `anchor` or
+  `scopeAccess`, in `defineService`'s `collections`. Both checks apply (a
+  service-wide `Admin` passes either), a scope without the grant is
+  `FORBIDDEN`, and a reload of the user's grants below it revokes the scope
+  on their sockets. Without it a self list opens for any signed-in user.
 - A hand-written method that reads many rows authorizes the parent
   (`{ scope: "Read", of: project, id: "projectId" }`) and filters by it, or
   uses the read/write kit's `list` or a collection, which filter by policy.

package/rules/quickdraw-client.md

@@ -34,7 +34,9 @@ export function Providers({ children }: { readonly children: React.ReactNode })
   (`qd.taskService.board`); the examples here key theirs short (`qd.task`).
 - `auth` is a token (sent as `auth.token`) or handshake fields; leave it out
   for cookie sessions. Changing it reconnects, and a hello naming another
-  user empties everything quickdraw cached.
+  user empties everything quickdraw cached, the placeholder a member's
+  `useQuery` or `useSearch` would make from it (`keepPreviousData`, the
+  last results) included.
 - `useQuickdraw()` gives
   `{ connection, status, isConnected, isKnown, reconnecting, userId, serviceAccess, hello, refusal, isRateLimited }`.
   Gate on `isKnown` (the server's hello named the user; `userId` is then
@@ -45,7 +47,14 @@ export function Providers({ children }: { readonly children: React.ReactNode })
   signed out: the server ended the session (signed out elsewhere, revoked,
   expired) or refused a connect for it, the hello is gone and quickdraw's
   cache is empty; any other status is still connecting. Never keep showing
-  data the app holds itself once `isKnown` turns false.
+  data the app holds itself once `isKnown` turns false. A server that could
+  not check the credentials (its session store down: the handshake is
+  refused `INTERNAL`) signs nobody out: the connection keeps the user and
+  the cache, stays `connecting` (`reconnecting` once it had connected) and
+  connects again by itself, so never treat that as a sign-out. On the
+  server, `authenticate` refuses credentials only by throwing
+  `QuickdrawError("UNAUTHENTICATED")` (or `"FORBIDDEN"`); anything else it
+  throws is an outage.
   `hello.serverId` changes when the server restarts (or the socket lands
   on another node): compare it to tell a new server from a network blip.
 - Sign-in and out in the browser go through the auth routes kit's routes:
@@ -157,6 +166,35 @@ await rename.mutateAsync({ id, title }); // resolves with the output, rejects wi
   the user's say). Never join from a plain `useQuery` or a
   mount effect: a reconnect leaves the socket out of the room while the
   cached answer still looks fine. Without React, `connection.onHello`.
+- Peer links: on a server created with `peers: true`,
+  `createPeerLink(connection, { room, to, offerer })` (in React,
+  `useQuickdraw().connection`) links two sockets of an app room over
+  WebRTC data channels, or over the server's relay when those cannot form.
+  The peer's socket id comes from the app (an event carrying
+  `ctx.socketId`, a method's answer); `onPeerRequest(connection, listener)`
+  answers a peer that linked first. Send input at a tick rate on `fast`
+  (unordered, never resent) and state on `rel` (ordered, reliable). A link
+  dies with its socket: open it again on every connection, as `useJoin`
+  joins again. What a peer sends is the peer's word, never checked by the
+  server: parse each message with its schema as untrusted input. Never
+  send `qd:peer` or `qd:relay` by hand (`no-raw-socket`). To play over a
+  bad network in a browser test or a bench, `link.setLag({ ms, jitter,
+loss })` lags the link's own messages both ways on its real path (`rel`
+  never lost, `stats.simulatedLoss` for the rest); never a proxy or a
+  hand-made delay around `send`.
+- Host mode: a player's `useStream` and `useChannel` of a host-served
+  member (`serve: "host"`) reach the room's host over a link, with no
+  change in the app; a channel's messages go on `fast`, so send input
+  every frame, never once. The host's client serves the members with
+  `defineHost(contract, { channels, streams }).serve(connection, { room })`
+  while `hostOf(connection, room)` is its own socket's id
+  (`onHostChange(connection, listener)` hears it change), and calls
+  `close()` when it is not. A host checks what players send it against the
+  contract, but each message stays that player's word, and what the host
+  sends is the host's word. Each of `host.peers` (and a handler's
+  `ctx.peer`) has `link`: read a player's round trip from
+  `link.clock.rtt`, and give the host's own play its players' lag with
+  `setLag` on the host's own entry, whose link is in process.
 - Admin screens: `qd.task.admin.adminList.useQuery(input)` and the other
   admin kit members; `useAdminServices(qd)` lists the services whose
   `adminMeta` answers the user, asking only those the hello's grants allow
@@ -164,9 +202,14 @@ await rename.mutateAsync({ id, title }); // resolves with the output, rejects wi
   `adminMeta` wider). A screen served from metadata for every service takes
   `adminOf(qd, key)`, one shape typed by field name: never cast
   `qd[key].admin`. The kit's rows are not live: after the screen's own
-  write, `onSuccess: () => qd.invalidate(qd.task.admin.adminList)`. A
-  generic form shows the fields whose `showInForm` is not `false`; a user's
-  grants field says `kind: "grants"`: find it by that, never by its name.
+  write, read the page again (`qd.invalidate(qd.task.admin.adminList)`)
+  and put the row the write returned in the cache
+  (`qd.task.admin.adminGet.setData({ id: row.id }, row)`; `adminOf`'s
+  query members have `setData` too), never in React state. Its reads of
+  rows default to `staleTime: 0`, read again on every mount (`adminMeta`
+  stays cached): pass a `staleTime` only to keep a page longer. A generic
+  form shows the fields whose `showInForm` is not `false`; a user's grants
+  field says `kind: "grants"`: find it by that, never by its name.
 
 ## Server components and other runtimes
 
@@ -177,10 +220,13 @@ await rename.mutateAsync({ id, title }); // resolves with the output, rejects wi
   `caller.task.get.prefetch(queryClient, input)` fills the keys the hooks
   read, for `dehydrate` and `HydrationBoundary`.
 - React Native uses the same client and provider (no DOM is needed).
-  React-free code (a Node script, a worker) makes a connection with
+  React-free code (a Node script, a CLI, a worker) imports
+  `@fitzzero/quickdraw-core/client/core`, which needs neither React nor
+  TanStack Query installed: it makes a connection with
   `createQuickdrawConnection({ url, auth })`, calls `open()`, and calls
-  `callData(connection, { service: "taskService", method: "get", input })`
-  from `./client`; `liveDataOf(connection, queryClient)` holds live rows.
+  `callData(connection, { service: "taskService", method: "get", input })`.
+  `./client` re-exports the same functions. Live rows need a TanStack
+  `QueryClient`: `liveDataOf(connection, queryClient)` from `./client`.
 - A client in another language (a Godot game, a native app) speaks the wire
   itself: `docs/protocol-v5.md` in the quickdraw repository is the
   specification, `examples/godot` a GDScript client written from it, and

package/rules/quickdraw-services.md

@@ -86,8 +86,8 @@ export const taskService = qd.defineService(task, {
 - `share: "all"` runs one handler for every caller, with the first caller's
   `ctx`, and gives every caller its result: use it only for a result that
   depends on the input alone. Its handler reads nothing of the caller
-  (`ctx.principal`, `ctx.services`, `ctx.mcp`, or a context field made from
-  them); in development a read of one of the first three warns
+  (`ctx.principal`, `ctx.services`, `ctx.mcp`, `ctx.access`, or a context
+  field made from them); in development a read of one of the first four warns
   `[quickdraw:shared-principal]`. It 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
@@ -111,6 +111,10 @@ export const taskService = qd.defineService(task, {
   and is cancelled with `ctx.signal`; it is typed by the app's `contracts`
   (`initQuickdraw<{ ...; contracts }>()`). Never write another service's
   model directly to skip its access checks.
+- A call through `ctx.services` carries this call's `ctx.mcp`, nested calls
+  too, so in an MCP call the method it reaches sees the token's fields. Its
+  `ctx.transport` is `"internal"`: tell a token's call apart by `ctx.mcp`,
+  never by `ctx.transport === "mcp"`.
 
 ## REST routes call the services
 
@@ -155,12 +159,25 @@ once:
 - `requireSession(keys)` guards the app's own REST routes.
 - `bearerAuth(...)` is for a hook handed a bearer token alone: the MCP
   bridge's `principal`, an `authenticate` that reads `auth.token`.
+- An app's own MCP transport, or an in-process assistant, that signs the
+  caller in itself (with `requireSession`, say) passes that caller to the
+  registry: `registry.callMethod(service, method, input, { request, principal })`.
+  The registry's `principal` hook is not asked (`null` calls anonymously),
+  the `context` hook and bound arguments see that principal, and its grants
+  load as `qd.caller`'s do. Never take it from a request body, and never
+  smuggle the user to the hook some other way (a map keyed by the request).
 - Never `verifyJWT` alone: it checks the signature and expiry, not the
   session store.
 - A custom `authenticate` takes the session cookie only from
   `request.sessionCookie` (HTTP), after `cookieOriginAllowed(request,
 allowedOrigins)`, and checks it with `liveSession`; `auth.token` holds
   only a bearer token for it.
+- `authenticate` refuses credentials only by throwing
+  `QuickdrawError("UNAUTHENTICATED")` (or `"FORBIDDEN"`). Anything else it
+  or `loadServiceAccess` throws is an outage (the store or the database
+  down): a socket's handshake is refused `INTERNAL`, and the client keeps
+  the user and connects again by itself. Never throw a plain `Error` for
+  bad credentials, which the client would retry for ever.
 
 ## Writes are tracked; frames are derived
 
@@ -172,6 +189,16 @@ writes made through `db`, after the response is sent:
   wrap the work in `qd.run(async (ctx) => ...)`, which flushes before it
   returns; a boot-time seed may run it before `createServer` too (its writes
   then reach no subscriber). Never write through the untracked client.
+- A helper that writes takes the tracked client by its type:
+  `client: Tracked<PrismaClient>`, or `TrackedTransaction<PrismaClient>`
+  when it may run inside `db.$transaction(async (tx) => ...)` (`tx` is
+  one, and so is `db`). `trackPrisma` returns a `Tracked<PrismaClient>`;
+  the untracked client is none, so passing it is a type error. Both types
+  are on `@fitzzero/quickdraw-core/prisma` and the root export. Never type
+  such a parameter `PrismaClient`, which the untracked client is too;
+  `no-untracked-write` reads the type, whatever the parameter's name. A
+  `db` declared `PrismaClient` (a lazy `Proxy`, say) carries no mark:
+  declare it `Tracked<PrismaClient>` to pass it to such a helper.
 - Background work a handler starts and does not await (a push sent after
   the reply) runs in `qd.run(fn, { detached: true })`: a unit of its own,
   flushed when `fn` settles. Without `detached` it joins the handler's unit,
@@ -184,7 +211,10 @@ writes made through `db`, after the response is sent:
   `db.$transaction(async (tx) => ...)` when they must commit together.
 - Raw SQL writes and database cascades are not seen: record them with
   `ctx.touch("task", ids)` (`{ removed: true }` for deleted rows); `qd.run`
-  passes `fn` the same `touch`.
+  passes `fn` the same `touch`. Before deleting a row whose dependents the
+  database deletes or clears (`onDelete: Cascade`, `SetNull`), delete or
+  clear them through `db` first, in the same transaction, so the lists
+  holding them are told; for the admin kit, in its `prepare`.
 - A write to one row that changes how another service's row looks (a
   parent's counts) declares `affects: [{ service: task, id: "parentTaskId" }]`.
 
@@ -196,7 +226,11 @@ in `id`), and optionally `where`, `limit`, `maxLimit`, `index` (small fields
 sent for the whole scope), `views` (`(row, who) => boolean` over index rows)
 and `access`. The service says who may open a scope: `{ anchor: project }`
 (the level on the row the scope value names) or `{ scopeAccess: "self" }`
-(the subscriber's own user id). Everyone in an anchored scope sees every
+(the subscriber's own user id), plus `requires: { service: "Read" }` when
+the list must need the service-wide grant its methods ask for
+(`{ scopeAccess: "self", requires: { service: "Read" } }`: the user's own
+rows, for holders of the Read grant); both checks then apply, and a socket
+whose grants reload below it leaves the scope. Everyone in an anchored scope sees every
 item, so derive the item service's access from the anchor (`inherit`); a
 self scope's items follow the item service's policy, so its user gets only
 the rows they may read. A `via` scope over the item service's own `members`
@@ -250,12 +284,23 @@ Contract halves come from `@fitzzero/quickdraw-core`, handlers from
   `onCommitted`, which runs once it committed, in a unit of its own (a
   game applying an edited definition to its running simulation, so a
   rolled-back edit is never applied); never wrap the kit's handlers.
+  What must happen before an edit goes in `prepare(call, ctx, db)`, in
+  the same transaction: a column the server computes (a content hash) is
+  returned from it and written over the caller's data, even a hidden or
+  read-only one (never `id`, a timestamp or a relation; a parent it sets
+  needs the caller's row level on it, as in the read/write kit), so it
+  need not be an editable field of the entity; and before an `adminDelete`
+  it deletes or clears through `db` the rows the database would cascade,
+  so their subscribers and lists are told.
 
 ## Realtime
 
 - Streams: `streams: { logs: { item, scope: "taskId", seed: 50, access } }`;
   push with `qd.stream(task, "logs").push(taskId, item)`, and several items
-  at once with `pushMany(taskId, items)`, never `push` in a loop. When the
+  at once with `pushMany(taskId, items)`, never `push` in a loop. A job that
+  skips feeds nobody watches asks
+  `await qd.stream(task, "logs").subscribers(taskId)` (the sockets on every
+  node), never Socket.IO's adapter rooms, which hold one node's. When the
   items are deltas (a game's ticks), give the service a computed seed,
   `streams: { world: { seed: (worldId, ctx) => [snapshotOf(worldId)] } }`,
   never a bootstrap call beside the stream; `validate: "development"` there
@@ -290,6 +335,38 @@ Contract halves come from `@fitzzero/quickdraw-core`, handlers from
 - A game loop asks `qd.rooms.size(room)` (this node's sockets, spectators
   included, synchronous) at its tick rate, never Socket.IO's adapter;
   `ctx.socketId` names the calling socket in a method.
+- Peer links: `createServer({ peers: true })` lets two clients of an app
+  room link directly (`createPeerLink` on the client). The server forwards
+  their signals and relays their messages only between signed-in sockets
+  of the room, and ends a player's links when they leave it or
+  `rooms.leave(room, { userId })` takes them out. Tell players each other's
+  socket ids with an event or a method's answer (`ctx.socketId`). The
+  server never sees what a link carries: a method that records what a
+  client reports from a link (a score, a winner) checks it as untrusted
+  input, and its contract's `describe` says so.
+- Host mode: a channel or stream declared `serve: "host"` is served by the
+  room's host, one player's client (`defineHost` on the client), over peer
+  links; the server needs `peers: true` and never handles it. A
+  host-served channel declares `requires: { room }` and a host-served
+  stream a scope and `access: { room: (scope) => room }`. Give a
+  host-served channel no handler and a host-served stream no options or
+  seed: `defineService` refuses them. Pick the host in a method,
+  `ctx.rooms.setHost(room)` for the calling socket (after a check of the
+  app's own: a seat, a role), never by election; read it with
+  `ctx.rooms.hostOf(room)`, clear it with `clearHost(room)`, and decide
+  what follows in `onHostLeave({ room, socketId, principal, reason })`.
+  Behind a cluster adapter, 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
+  when the app picks a host only while `hostOf(room)` is `null`, also let
+  a player take over a host that stops answering: a method that calls
+  `setHost(room)` or `clearHost(room)` after a timeout of the app's own.
+  The server never sees what a host and its players send each other: what
+  a host reports to a method (a result, a score) is one player's word,
+  checked as untrusted input, and the contract's `describe` says so. The
+  service's `kinds` does not reach host-served members: any signed-in
+  socket of the room can link to the host, so guard the method that joins
+  the room.
 - Events: `events: { moved: { payload } }`, sent with
   `ctx.rooms.emit(room, task, "moved", payload)` to an app room
   (`ctx.rooms.join(room)` in a method puts the caller's socket in one), and
@@ -322,8 +399,10 @@ Contract halves come from `@fitzzero/quickdraw-core`, handlers from
 
 Bound every `findMany` with `take`; batch per-item reads with `in:` filters;
 filter in `where`, not after loading. Write many rows in one statement when
-they all get the same data (`updateMany`, `createMany`). When each row's
-data differs, loop over the rows inside an interactive
+they all get the same data (`updateMany`, `createMany`); a large insert may
+go in fixed-size `createMany` chunks, which neither `no-db-call-in-loop` nor
+the N+1 warning counts. When each row's data differs, loop over the rows
+inside an interactive
 `db.$transaction(async (tx) => ...)` and await one `tx.task.update(...)` by
 id per row, not an array-form `$transaction([...])`, which cannot read a
 moved row inside its batch. A projection's relation count selects the

package/rules/quickdraw-testing.md

@@ -51,6 +51,16 @@ await app.close();
   `{ call, socket, hello, close }` once the server said hello. Pass `null`
   for an anonymous caller. Both callers are keyed by service name
   (`taskService`), where the web client uses the contract map's keys.
+- Test a guard that reads `ctx.mcp` (an agent token's scopes) or
+  `ctx.transport` in process too, never through `app.server.dispatcher.call`:
+  `app.as(agent, { transport: "mcp", mcp: { scopes: [] } })` calls as an
+  MCP tool call arrives, its `mcp` typed by the app's
+  `QuickdrawTypes["mcp"]`, and `{ mcp }` alone as a call an MCP call made
+  through `ctx.services`. `transport` takes `"internal"` (the default),
+  `"http"` or `"mcp"`; a socket's call is `app.connect`'s. Bound arguments
+  and the registry's `principal` and `context` hooks belong to the MCP
+  registry: test them through
+  `registry.callMethod(service, method, input, { request })`.
 - `app.frames(match?)` lists every frame the server sent, each with its
   `event`, `data`, `socketId`, `userId` and `at`;
   `frames.waitFor(match, timeoutMs?)` waits for one, `frames.clear()`

package/skills/quickdraw-migrate-v5/SKILL.md

@@ -106,7 +106,10 @@ guide's sections as the report sends you to them.
    "Hand-built auth to the auth routes kit"). Until then the server's
    interim `authenticate` checks the app's session store on every handshake
    and call, and the session cookie's `Origin` (`cookieOriginAllowed`);
-   never `verifyJWT` alone, which a signed-out session still passes.
+   never `verifyJWT` alone, which a signed-out session still passes. It
+   refuses by throwing `QuickdrawError("UNAUTHENTICATED")`, never a plain
+   `Error`, which a socket's handshake answers `INTERNAL` (an outage, which
+   the client retries, keeping the user).
 
 4. **Delete each marker when its item is done**, and run the codemod again:
    it changes no code a second time and rewrites the report from the markers