@fitzzero/quickdraw-core 5.0.0-rc.4 → 5.0.0-rc.6

package/README.md

@@ -531,7 +531,9 @@ export type Card = ItemOf<typeof taskContract, "board">;
 
 `InputOf`, `ParsedInputOf`, `OutputOf`, `EntityOf`, `ProjectionOf`,
 `ItemOf`, `ScopeOf`, `IndexRowOf`, `ViewName` and the rest are exported from
-the package root.
+the package root. `FullProjectionOf<C, P>` is a projection's full row (what
+a handler builds, every tiered field present), and `ReceivedRow<C, Row>`
+makes a row's tiered fields optional, as a reader receives it.
 
 ## Services
 
@@ -587,9 +589,21 @@ export const taskService = qd.defineService(task, {
 - Every call runs a pipeline: look up, concurrency (16 queries in flight per
   socket and 64 queued, then `RATE_LIMITED`; mutations are not queued behind
   queries), input validation, access, "not modified", sharing, the handler
-  under a time limit (30 s by default), output validation outside
-  production, the reply, the flush, and one completion record (`onCall`).
-  A mutation ignores the caller's cancel: only its time limit stops it.
+  under a time limit (30 s by default), the result shaped to its output
+  (below), output validation outside production, the reply, the flush, and
+  one completion record (`onCall`). A mutation ignores the caller's cancel:
+  only its time limit stops it.
+- A method's output is sent as it declares it, on every transport and in
+  production too, so a handler may return the whole row: a projection
+  output (`"entity"`, a named projection) sends the projection's keys,
+  stripped per caller (below), and an output schema of the method's own
+  sends what its JSON Schema declares (Zod 4.2 or later). An object keeps
+  the keys its `properties` declare, and every key only where
+  `additionalProperties` allows them (`z.looseObject`, `.catchall`) or it is
+  a record; an array keeps its items, each reduced by its item schema; a
+  union keeps what any branch declares; a value the schema allows to be
+  anything (`z.unknown()`, a `Date`) goes as it is. An output schema
+  without JSON Schema (Zod 3) is sent as the handler returns it.
 
 Errors are `QuickdrawError(code, message, data?)`. Anything else a handler
 throws reaches the caller as `INTERNAL` with a generic message, and is
@@ -753,6 +767,16 @@ tracked client as `db`; the server finds the rest on it.
   recorded with its row ids, merged per row, and handed to the flush sinks
   once the response has been sent, with one revision per flush. A handler
   may return `db.task.update(...)` without awaiting it.
+- A write that certainly changed nothing is not recorded, so it sends no
+  frame, no collection delta, no topic change and no `refreshEntry`: an
+  `updateMany`, `updateManyAndReturn` or `deleteMany` that matched no row,
+  and a `data` (or an upsert's `update`) with nothing to write, `{}`. An
+  upsert with `update: {}` ("make sure this row exists") reads the row
+  first in its place: one statement when the row is there, and the upsert
+  after it when it is not. Every other write is recorded, one that sets a
+  column to the value it already held too: the values the framework reads
+  before a write cannot prove it changed nothing, since another write may
+  land between that read and the write.
 - Writes inside `db.$transaction` join the unit only when it commits; a
   rollback drops them. Prefer the interactive form
   (`db.$transaction(async (tx) => ...)`): an array-form
@@ -879,10 +903,26 @@ export const taskService = qd.defineService(task, {
 - A projection's keys come from its schema's JSON Schema (Zod 4.2 or later),
   or from `project: { <name>: { keys } }`; a service whose projection has
   neither fails when it is defined. A handler returning a projection returns
-  rows (a `Date` is fine where the wire has a string, extra columns are
-  dropped); with `map`, it returns what `map` takes.
+  rows (a `Date` is fine where the wire has a string, a Prisma `Json` column
+  (`JsonColumnValue`) where it has an object, an array or a record, and
+  extra columns are dropped); with `map`, it returns what `map` takes.
 - Fields the contract's `fields` map puts above the caller's level on a row
-  are stripped from that caller's copy, after any shared run.
+  are stripped from that caller's copy, after any shared run. Only a
+  projection output is stripped per caller (`"entity"`, a named projection,
+  and `nullable(...)` or `listOf(...)` of one): a method whose output is a
+  schema of its own sends what that schema declares to every caller its
+  access admits, so a tiered key the schema declares, at any depth (`email`
+  in a hand-written `{ id, name, email }`, or in `{ user: { id, email } }`),
+  reaches callers below its level. When a server is made, each such method
+  raises the development warning `[quickdraw:tiered-field-in-output]`
+  (thrown by `createTestApp({ strictWarnings: true })`, so the test app
+  fails to start): answer `"entity"` or a projection, or drop the key from
+  the schema. Not warned: a method whose access admits no caller below the
+  field's level (`{ service: "Admin" }` with the Admin bypass on,
+  `{ entry: L }` with `L` at the field's level or above), and a kit's
+  methods, which strip their own replies. An output without JSON Schema
+  (Zod 3) cannot be reduced, so in development each tiered key its replies
+  carry raises the warning when a reply first carries it.
 - `affects` names rows of other services a write changes too
   (`{ service, id: column }`, or `{ service, id: (row) => ids, columns }`);
   they are sent again after the flush, one hop.
@@ -1009,7 +1049,14 @@ export const taskService = qd.defineService(task, {
   authorized like a subscribe to that scope, or `service`, which changes
   whenever any row of the service does, or a row of a model it lists in
   `writes` (a game's high scores, which no service owns). A query declares
-  `watch: "service"` to be invalidated by it. The service topic is closed
+  `watch: "service"` to be invalidated by it. A query over some of those
+  models names them, `watch: { service: ["gameScore"] }` (type
+  `ServiceModelsWatch`; the service's `model` and models in its `writes`;
+  `defineService` refuses others), and
+  is invalidated only after a flush that wrote one of them: high scores are
+  not read again when a chat membership the same service writes changes.
+  It is the same topic: its `qd:changed` frame names the models that
+  changed it (`models`). The service topic is closed
   (`FORBIDDEN`) unless the service declares `watchAccess` (`"public"`,
   `"authenticated"` or `{ service: level }`). A watcher that loses access
   leaves the topic after one last `qd:changed`.
@@ -1041,7 +1088,9 @@ over three transports (design: sections 3, 8 and 10):
   principal comes from the session cookie (`__Host-session` over HTTPS,
   `session` over plain HTTP or with `COOKIE_DOMAIN`, as the auth routes name
   it) or an `Authorization: Bearer` token through the same
-  `authenticate`; the reply is `{ ok: true, d }` or
+  `authenticate`, which is told which one it was (`request.credential`):
+  `socketAuth` answers a cookie sent from a page outside `allowedOrigins`
+  with `FORBIDDEN`, as it refuses such a socket; the reply is `{ ok: true, d }` or
   `{ ok: false, e: { code, message, data? } }` with the code's HTTP status.
   Works on Express 4 and 5, and on a bare Node server. Move it with
   `http: { path }`, turn it off with `http: false`, or mount
@@ -1211,6 +1260,19 @@ export function TaskDetail({ id }: { readonly id: string }) {
 }
 ```
 
+- A row that does not exist is refused the way a row the reader may not
+  see is: `FORBIDDEN`, for a subscribe and for a method whose access names
+  the row (`{ entry }`), since a policy that cannot find the row grants
+  nothing (fail closed), and telling the two apart would tell a stranger
+  which ids exist (a service-wide `Admin` grant, which needs no row to
+  pass, gets `NOT_FOUND`). So a page cannot tell "deleted" from "no access" by the
+  refusal: it learns of a delete while it holds the row, live: the `r`
+  frame sets `useEntity`'s `isRemoved` (as above), and a collection's
+  `removed` delta takes the item out of `items`. A page opened after the
+  delete (a link, a reload, a reconnect after the row went) gets only
+  `FORBIDDEN`; where the difference matters, say "not found or not shared
+  with you", or ask a method of the parent row (a list of the project's
+  tasks) that can answer without leaking.
 - A field the contract's `fields` map tiers (`notes` here) is optional in
   every row type a reader gets (`useEntity`, collection items, `"entity"`
   outputs, `EntityOf`, `ItemOf`), because a reader below its level receives
@@ -1243,7 +1305,13 @@ export function TaskDetail({ id }: { readonly id: string }) {
   items loaded, and `loadMore`/`loadItems`; `view` filters the members by a
   view of the contract, for the user the server's hello names; `load: "all"`
   keeps every page loaded. A `null` scope holds nothing; `enabled: false`
-  subscribes to nothing.
+  subscribes to nothing. A scope the server refused shows its `error`
+  (`FORBIDDEN`) and is loaded once more each time the user's access may
+  have changed: on a connect, on new service grants (`qd:access`), and when
+  another scope the client holds gets an `added` delta for the scope's
+  anchor row (an invite adds the chat to the user's own list of chats, and
+  the chat's messages open). A row-level grant with neither sends nothing
+  the client could notice: remount the view, or call `refresh()`.
 - The cache follows the user: a hello naming another user removes everything
   quickdraw cached; new credentials for the same user refetch it; new grants
   (`qd:access`) refetch every query.
@@ -1260,7 +1328,26 @@ A create shows its row before the server answers with `cache.addItem(collection,
 scope, item)`: the item appears in the scope at once, in its place by the
 collection's `order` (give it the order's fields; without them it goes
 last), and `useCollection`'s `pending` names it while the call is in flight.
-A refused call removes it. The reply's `id` (the created row's) and values
+A refused call removes it, unless it was added with `{ onRefused: "keep" }`
+(`cache.addItem(collection, scope, item, { onRefused: "keep" })`, or the
+same for `addEntity`): it then leaves `items` for `useCollection`'s
+`refused`, each `{ item, error, dismiss(), retry() }`, in the render that
+shows the mutation's error, until the app dismisses it or sends the same
+call again with `retry()` (through the mutation hook that sent it, so its
+`isPending` and callbacks follow; it shows the item `pending` again, and
+never rejects: a second refusal shows in `refused` again), so a chat shows
+a failed message with "retry" without a copy of its own. A call whose outcome is unknown is not refused: when the
+connection drops after the call was sent, or it times out, the server may
+have made the write (`isUnknownOutcome(error)` on `./client` says so). Its
+items stay, `pending`, and `useCollection`'s `checking` names them until
+the scope's next load (the reconnect's resume, or a load asked for at once
+while the socket is up): a load that holds an item's id ends it, its own
+copy shown, and one sent after the failure that answers without it refuses
+it (into `refused` with `onRefused: "keep"`). Only an id the client made,
+which the server keeps, can be found that way, and only with one is
+`retry()` safe after an unknown outcome: the second call fails `CONFLICT`
+instead of writing a second row. A refused item ends too once its scope
+holds its id. The reply's `id` (the created row's) and values
 replace the item's own, and once the scope's own copy arrives (its `added`
 delta, or a load) that copy shows in its place: never both, never a gap.
 `cache.addEntity(row)` adds a row to every collection of entity rows whose
@@ -1397,8 +1484,10 @@ The methods most services write by hand, as one-line opt-ins (design:
 section 12). Each kit's contract half comes from the package root and makes
 ordinary contract entries; its handlers come from `./server`. Lint's
 `prefer-kit` reports a method written by hand that a kit implements (`get`,
-`list`, `create`, `getTask`, ...) in a service that uses no kit; one that
-must stay hand-written says why in a `// quickdraw: hand-written because ...`
+`list`, `create`, `getTask`, ...) in a service that uses no kit, and one
+that duplicates what a kit spread beside it serves (a `getNote` beside
+`crud.handlers(note, { access: { get } })`); one that must stay
+hand-written says why in a `// quickdraw: hand-written because ...`
 comment above it.
 
 ### Read/write kit
@@ -1943,9 +2032,15 @@ before?, after }, ctx, db)` after each `adminCreate`, `adminUpdate` and
   transaction's tracked client; a throw undoes the write and fails the
   call): what an admin edit must set off, such as a game reloading its
   tunables, without wrapping the kit's handlers. The rows are the entity,
-  every field. Without it the kit opens no transaction. Each handler
-  `admin.handlers` returns resolves with its method's output type, so a
-  wrapper reads the row and returns it with no cast.
+  every field. `onCommitted({ method, id, before?, after }, ctx)` runs once
+  the write has committed (after `onWrite`'s transaction), in a detached
+  unit of work of its own: the reply does not wait for it, its writes flush
+  on their own, and a throw is logged, the write standing. Apply an edit to
+  what runs in memory (a game's simulation) there, so an edit that rolled
+  back is never applied. Without either hook the kit opens no transaction.
+  Each handler `admin.handlers` returns resolves with its method's output
+  type (`AdminOutputOf<C, M>`), so a wrapper reads the row and returns it
+  with no cast.
 - `adminSubscribers({ id })` counts the sockets subscribed to a row per
   access level (`{ id, count, levels, complete }`; behind a Redis adapter
   the counts are this server's and `complete` is `false`), and
@@ -2111,8 +2206,8 @@ export function TaskRoom({
   leaves the feed and gets
   `qd:revoked { kind: "stream", reason: "access", s, stream, scope? }`, and
   `useStream` shows `FORBIDDEN` until the next connect.
-- A service's `streams: { <name>: { seed, validate } }` computes a stream's
-  seed per subscriber, `seed: (scope, ctx) => items` (the current state,
+- A service's `streams: { <name>: { seed, validate } }` (type
+  `StreamImplementation`) computes a stream's seed per subscriber, `seed: (scope, ctx) => items` (the current state,
   where the items that follow are deltas; on whichever node the subscriber
   is on, under its principal, in the tick it joins the feed; a contract
   `seed: n` and a seed function cannot both be declared), and
@@ -2133,7 +2228,8 @@ export function TaskRoom({
   limiter does not count channels. `{ room: { prefix: "world:" } }` takes
   a socket in any app room whose name starts with the prefix (a game of many
   worlds), and every room form gives the handler the room it matched as
-  `ctx.room`, so the payload need not repeat it. Every requirement is the
+  `ctx.room` (typed `ChannelRoomOf<C, Name>`: `string` for a channel that
+  requires a room, else `undefined`), so the payload need not repeat it. Every requirement is the
   sending socket's own: a room another socket of the user joined does not
   count, a reconnected socket must join again, and behind a cluster the
   check runs on the node the socket is connected to, with no round trip.
@@ -2158,8 +2254,10 @@ input, { enabled?, onJoined? })` (from `./client`) runs the joining call
   (`enterBoard` above) on every `qd:hello` and when its input changes by
   value, never on a re-render, and shows `status` (`idle` with no socket to
   join with, `joining`, `joined`, `error`), `isJoined`, `data` and `error`;
-  a refusal stands until the next hello, `RATE_LIMITED` is tried again after
-  its backoff, and it never leaves the room itself.
+  a refusal stands until the next hello or `retry()` (which runs the call
+  again at once on the current socket, and does nothing while there is
+  none or `enabled` is false), `RATE_LIMITED` is tried again after its
+  backoff, and it never leaves the room itself.
   `connection.onHello(listener)` is the same hook without React.
 
 Code that is not a handler (a game loop, a timer, a job) reaches rooms
@@ -2212,8 +2310,9 @@ export function hasAudience(projectId: string): boolean {
   the node that held the socket: its own `leave` (`reason: "leave"`), a
   removal (`"removed"`), or a disconnect, which leaves every app room it was
   in (`"disconnect"`; `qd:rotate` reconnects with a new socket). Each room
-  comes with `last`: true when no socket of that user is in the room any
-  more, on any node, which is what a game's `playerLeft` waits for. It runs
+  (a `RoomLeft`) comes with `last`: true when no socket of that user is in
+  the room any more, on any node, which is what a game's `playerLeft` waits
+  for. It runs
   in a unit of work of its own (never the unit of the handler that left), a
   throw is logged, and `close()` waits for it. Behind a cluster `last` is
   decided by asking every node once the socket left, so two sockets of one
@@ -2248,8 +2347,8 @@ const allowedOrigins = [env.CLIENT_URL];
 const sessions = createMemorySessionStore();
 
 export const app: Express = express();
-// behind a proxy, so the rate limits see the client's IP
-app.set("trust proxy", 1);
+// behind a proxy, so the rate limits see the client's IP; with none, a client would pick its own
+app.set("trust proxy", env.TRUST_PROXY);
 // a web app on another origin also needs CORS with credentials on these routes
 app.use(
   createAuthRoutes({
@@ -2305,6 +2404,7 @@ nothing is cached:
 | `GET /{provider}/start?returnTo=<url>` | 302 to the provider                                                                                                   |
 | `GET /{provider}/callback`             | 302 to `{origin}{successPath}` with the session cookie, or to `{origin}{errorPath}?error=state`, `denied` or `failed` |
 | `POST /guest`                          | `createUser(body)`, then `{ userId, name? }` with the session cookie (and `token` with `guest({ token: true })`)      |
+| `GET /providers`                       | `{ providers: [{ id, name, kind }] }`: the sign-ins served now (`routes.providers()` on the server)                   |
 | `GET /me`                              | `{ userId }`, or 401                                                                                                  |
 | `POST /logout`                         | 204: revokes the session, clears the cookie                                                                           |
 | `POST /logout-all`                     | 204: revokes every session of the user; 401 without a live session                                                    |
@@ -2351,8 +2451,17 @@ nothing is cached:
   any page's handshake). A handshake without `Origin` is refused unless it
   is a browser's same-origin request (`Sec-Fetch-Site: same-origin`) or
   `allowMissingOrigin: true` is set for native clients that keep cookies.
-  Bearer tokens need no Origin, and HTTP calls are guarded by their JSON
-  content type instead.
+  An HTTP call (`/qd/...`) that sends the cookie is checked the same way
+  and answered `FORBIDDEN` (403) from an `Origin` outside `allowedOrigins`,
+  besides needing its JSON content type. One without `Origin` is accepted:
+  a browser sends `Origin` with every POST, so it comes from curl or a
+  server rendering a page with the user's forwarded cookie (refused only
+  when `Sec-Fetch-Site` names another site). Bearer tokens need no Origin
+  on either transport. An app's own `authenticate` learns where an HTTP
+  call's token came from in `request.credential` (`"cookie"` or
+  `"bearer"`, type `HttpCredentialSource`), applies the same rule with
+  `cookieOriginAllowed(request, allowedOrigins)`, and a
+  `QuickdrawError("FORBIDDEN")` it throws on HTTP is answered as it is.
 - `socketAuth({ devCredentials })` signs a socket in by the user id its
   handshake names (`auth: { userId }`, no token), as the function answers
   (the principal, or `null` to refuse): for a game editor or load-test bots
@@ -2369,11 +2478,17 @@ nothing is cached:
   session's token, for clients that keep no cookies (a game engine, a page
   in a third-party iframe), at the cost of the token being readable by the
   page's scripts.
-- `requireSession({ sessions, jwtSecret }, { loadPrincipal? })` guards the
-  app's own REST routes (below): the credential is read as `/me` reads it,
-  the JWT verified once and the session checked in the store; otherwise
-  401 `{ error: "UNAUTHENTICATED", message }`. 4.1's `createRequireAuth`
-  stays for token-keyed sessions.
+- `requireSession({ sessions, jwtSecret }, { loadPrincipal?, allowedOrigins? })`
+  guards the app's own REST routes (below): the credential is read as `/me`
+  reads it, the JWT verified once and the session checked in the store;
+  otherwise 401 `{ error: "UNAUTHENTICATED", message }`. The session cookie
+  gets the `/qd` calls' Origin rule: from an `Origin` outside
+  `allowedOrigins` (by default the list of the `createAuthRoutes` writing to
+  the same `sessions`) it answers 403 `{ error: "FORBIDDEN", message }`, so
+  another site's form cannot post to a route as the user; a request without
+  `Origin` is accepted unless `Sec-Fetch-Site` names another site, and a
+  bearer token needs none. 4.1's `createRequireAuth` stays for token-keyed
+  sessions.
 - Rate limits: the sign-in routes share `createAuthLimiter({ max: 60 })` (60
   requests per 15 minutes per IP) and the session routes
   `createAuthStatusLimiter()` (120); pass `rateLimit: { signIn, session }`
@@ -2387,7 +2502,14 @@ nothing is cached:
 - The mock provider is mounted only while `isMockOAuthEnabled()`
   (`ENABLE_MOCK_OAUTH=true` and `NODE_ENV` other than `production`), and
   every request checks again. Set `mock({ internalUrl })` where the API
-  cannot reach itself at `publicUrl`.
+  cannot reach itself at `publicUrl`. Routes made with nothing that can
+  sign anyone in (only a mock that is off) warn when they are made.
+- `publicUrl` is where providers send the browser back, so a deployment
+  must set it to the API's public URL. A loopback `publicUrl`
+  (`http://localhost:4000`, the usual fallback for an unset `API_URL`)
+  warns when the routes are made if every allowed origin is a page on
+  another machine, and the first request that arrives for another host
+  (`X-Forwarded-Host`, else `Host`) logs an error naming it, once.
 - One rule names the session cookie, written and read: the routes,
   `setSessionCookie`, `socketAuth` and the HTTP transport give a request
   the same name, and read first the name they would set on it. Without a
@@ -2418,10 +2540,13 @@ nothing is cached:
   session for an app's own sign-in flow (login codes, an embedded activity),
   and `liveSession` reads a token back; both work with `socketAuth`.
 
-From the browser, `./client` speaks to these routes: `signInUrl(provider,
-{ apiUrl, returnTo })` is the start route's URL (to navigate to; `returnTo`
-defaults to the current page's origin), and `signOut()` and
-`signOutEverywhere()` post to `logout` and `logout-all`. Each POST sends the
+From the browser, `./client` speaks to these routes: `authProviders({
+apiUrl })` lists the sign-ins the API serves (`GET /providers`: a provider
+`google.optional` built nothing for is not in it, nor the mock where it is
+off), so a login page shows only those, whatever the web app was built
+with; `signInUrl(provider, { apiUrl, returnTo })` is the start route's URL
+(to navigate to; `returnTo` defaults to the current page's origin), and
+`signOut()` and `signOutEverywhere()` post to `logout` and `logout-all`. Each POST sends the
 session cookie (`credentials: "include"`, so the API's CORS must allow the
 web app's origin with credentials) with `Content-Type: application/json`,
 and the token `setAuthToken` stored, if any, as a bearer token; the stored
@@ -2434,8 +2559,23 @@ signing out (with a token in `auth`, clearing it does that):
 
 ```tsx
 export function SignIn() {
-  // the kit's GET /auth/google/start: back to this page's origin with the session cookie
-  return <a href={signInUrl("google", { apiUrl: API_URL })}>Sign in with Google</a>;
+  // GET /auth/providers: only the sign-ins this API serves (no Google button without its keys)
+  const { data: providers = [] } = useQuery({
+    queryKey: ["auth", "providers"],
+    queryFn: () => authProviders({ apiUrl: API_URL }),
+  });
+  return (
+    <nav>
+      {providers
+        .filter((provider) => provider.kind !== "guest")
+        .map((provider) => (
+          // the kit's GET /auth/{id}/start: back to this page's origin with the session cookie
+          <a key={provider.id} href={signInUrl(provider.id, { apiUrl: API_URL })}>
+            {`Sign in with ${provider.name}`}
+          </a>
+        ))}
+    </nav>
+  );
 }
 
 export function SignOut() {
@@ -2576,8 +2716,8 @@ it("sends a rename to the other members' boards", async () => {
   real socket (`{ call, socket, hello, close }`); both are keyed by service
   name. `app.frames(match?)` lists every frame the server sent, with its
   socket and user; `frames.waitFor(match)` waits for one. A query of one
-  event takes `where`, a predicate over its frames typed by the event
-  (`{ event: "qd:presence", where: ({ data }) => data.joined === id }`), and
+  event (`EventQuery`) takes `where`, a predicate over its frames typed by
+  the event (`{ event: "qd:presence", where: ({ data }) => data.joined === id }`), and
   `streamFrames(contract, stream, where?, scope?)` and
   `eventFrames(contract, event, where?)` match one stream's items or one
   event's payloads, typed by the contract, to spread beside `socketId` or
@@ -2615,8 +2755,9 @@ it("lets the owner rename, members read, and nobody else in", async () => {
 `"deny"` (the default for everyone `allow` does not name) means
 `UNAUTHENTICATED` without a principal and `FORBIDDEN` with one. Mutations run
 for real, once per allowed principal: give inputs that can run again, or
-`input` as a function of the cell (`({ name, principal }) => input`, sync or
-async), called before each cell's call, that makes a row of its own (a task
+`input` as a function of the cell (a `MatrixInputFactory` of the
+`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.
 
@@ -2689,16 +2830,17 @@ one format and names the method call it happened in:
 [quickdraw:n-plus-one] taskService.board: task.findUnique by id ran 10 times in one call, once per item (N+1); ...
 ```
 
-| Kind                 | Raised when                                                                                          |
-| -------------------- | ---------------------------------------------------------------------------------------------------- |
-| `n-plus-one`         | a call ran 10 statements of one shape (model, operation, `where` keys), outside a `$transaction([])` |
-| `unbounded-read`     | a call ran `findMany` with neither `take` nor ids to read (`id`, `{ in }` or `{ equals }`)           |
-| `oversized-response` | a reply was larger than `maxResponseBytes` (default 1 MiB)                                           |
-| `nested-write`       | a write's `data` wrote a related row, which is not tracked                                           |
-| `ambient-write`      | a tracked write ran outside any unit of work                                                         |
-| `batch-read`         | a write in an array-form `$transaction` read its rows outside the batch                              |
-| `batch-create-many`  | a `createMany` in an array-form `$transaction` could not report its rows                             |
-| `repeated-call`      | one connection repeated a call or was refused `RATE_LIMITED` again and again (below)                 |
+| Kind                     | Raised when                                                                                                                                                                                        |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `n-plus-one`             | a call ran 10 statements of one shape (model, operation, `where` keys), outside a `$transaction([])`                                                                                               |
+| `unbounded-read`         | a call ran `findMany` with neither `take` nor ids to read (`id`, `{ in }` or `{ equals }`)                                                                                                         |
+| `oversized-response`     | a reply was larger than `maxResponseBytes` (default 1 MiB)                                                                                                                                         |
+| `nested-write`           | a write's `data` wrote a related row, which is not tracked                                                                                                                                         |
+| `ambient-write`          | a tracked write ran outside any unit of work                                                                                                                                                       |
+| `batch-read`             | a write in an array-form `$transaction` read its rows outside the batch                                                                                                                            |
+| `batch-create-many`      | a `createMany` in an array-form `$transaction` could not report its rows                                                                                                                           |
+| `repeated-call`          | one connection repeated a call or was refused `RATE_LIMITED` again and again (below)                                                                                                               |
+| `tiered-field-in-output` | a method's own output schema declares a field the contract tiers, which only projection outputs strip; raised when the server is made (for an output without JSON Schema, when a reply carries it) |
 
 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
@@ -2716,7 +2858,9 @@ 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.
+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.
 
 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
@@ -2817,6 +2961,13 @@ it("lets a signed-in user through the gate", () => {
 
 In Storybook, a decorator renders every story inside `qd.$Provider`, and a
 story's `beforeEach` sets its session (`qd.$session(...)`) beside its data.
+A docs page renders its stories side by side, where one mock session would
+show the last story's in all of them: give each its own with the
+provider's `session` prop, `<qd.$Provider session={{ userId: null }}>`
+(a `MockSession`, the type `$session(...)` takes too), laid over the
+mock's session field by field for that subtree alone (the
+real `useQuickdraw()` and `usePresence`, and the mock's views and admin
+grants, read it there).
 
 ### Test databases
 
@@ -2916,7 +3067,14 @@ 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`.
+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
+build them first (`bun run build`, or `turbo run build --filter` for those
+packages) in a script that runs the docs on a fresh checkout; the error
+says so when a built file is missing. The contracts module, which imports
+only the shared package's own sources, needs no build.
 
 The module may export each contract, or a map of them as given to
 `createQuickdrawClient`. A TypeScript module loads through Node's type

package/dist/{admin-ByHvKBth.d.ts → admin-CsXR7Zwy.d.ts}

@@ -1,5 +1,5 @@
-import { e as StandardSchemaWithJSON, d as StandardSchemaV1, I as InferInput, c as InferOutput, U as RowSchema, Q as QueryDef, P as ProjectionList, p as MutationDef, H as AnyContract, ao as MethodName } from './infer-Zs7dAWlI.js';
-import { d as ListSort, c as ListQuery, b as ListPage, 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-C1U6_voe.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-Dw21kmLw.js';
+import { d as ListSort, c as ListQuery, b as ListPage, 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-Dufu8r7a.js';
 
 /** A schema a kit generates: validation, and its JSON Schema. */
 type KitSchema<Input, Output = Input> = StandardSchemaWithJSON<Input, Output>;

package/dist/{adminSchemas-C1U6_voe.d.ts → adminSchemas-Dufu8r7a.d.ts}

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

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

@@ -1,7 +1,24 @@
-import { IncomingHttpHeaders, IncomingMessage } from 'node:http';
+import { IncomingMessage, IncomingHttpHeaders } from 'node:http';
 import { Socket } from 'socket.io';
-import { A as AccessLevel } from './infer-Zs7dAWlI.js';
-import { P as Principal, M as MaybePromise } from './types-BBU3rSbi.js';
+import { A as AccessLevel } from './infer-Dw21kmLw.js';
+import { P as Principal, M as MaybePromise } from './types-Bwg3kIEc.js';
+
+/**
+ * A request as Express leaves it: maybe with `body` from `express.json()`,
+ * `cookies` from `cookie-parser`, and Express's own `secure`.
+ */
+type HttpRequest = IncomingMessage & {
+    readonly body?: unknown;
+    readonly cookies?: unknown;
+    readonly secure?: unknown;
+};
+/**
+ * Where an HTTP call's token came from. `"cookie"`: the session cookie, which
+ * a browser sends with a request any page makes, so whoever accepts it checks
+ * the request's `Origin` (`socketAuth` does). `"bearer"`: an
+ * `Authorization: Bearer` header, which a page sends only on purpose.
+ */
+type HttpCredentialSource = "cookie" | "bearer";
 
 /** A principal's service-wide grants by service name: `{ taskService: "Admin" }`. */
 type ServiceGrants = Readonly<Record<string, AccessLevel>>;
@@ -24,6 +41,14 @@ interface SocketAuthenticateRequest extends AuthenticateRequestBase {
 interface HttpAuthenticateRequest extends AuthenticateRequestBase {
     readonly transport: "http";
     readonly req: IncomingMessage;
+    /**
+     * Where `auth.token` came from (finding F7.1): `"cookie"`, the session
+     * cookie, which a browser sends with a request any page makes, so an
+     * `authenticate` that accepts it checks the request's `Origin` as
+     * `socketAuth` does; `"bearer"`, an `Authorization: Bearer` header, which
+     * a page sends only on purpose. Absent without a token.
+     */
+    readonly credential?: HttpCredentialSource;
 }
 /** What `authenticate` is asked about: a socket connecting, or an HTTP call. */
 type AuthenticateRequest = SocketAuthenticateRequest | HttpAuthenticateRequest;
@@ -44,6 +69,10 @@ interface ServerAuth<P extends Principal = Principal> {
      * caller in anonymously, so only `"public"` methods pass. Throw a
      * `QuickdrawError("UNAUTHENTICATED", ...)` for a refusal that is the
      * caller's doing (it logs at debug; anything else thrown logs at error).
+     * On an HTTP call a thrown `QuickdrawError("FORBIDDEN", ...)` is answered
+     * as it is, with 403 (logged at debug): a credential the request may not
+     * use from where it came, as `socketAuth` answers a session cookie sent
+     * from a page outside `allowedOrigins`.
      */
     readonly authenticate?: (request: AuthenticateRequest) => MaybePromise<AuthenticateResult<P>>;
     /**
@@ -77,4 +106,4 @@ interface ServiceAccessSource {
  */
 declare function recordSocketSession(socket: object, sessionId: string): void;
 
-export { type AuthenticateResult as A, type HttpAuthenticateRequest as H, type ServerAuth as S, type ServiceGrants as a, type AuthenticateRequest as b, type ServiceAccessSource as c, type SocketAuthenticateRequest as d, recordSocketSession as r };
+export { type AuthenticateResult as A, type HttpRequest as H, type ServerAuth as S, type ServiceGrants as a, type AuthenticateRequest as b, type HttpAuthenticateRequest as c, type HttpCredentialSource as d, type ServiceAccessSource as e, type SocketAuthenticateRequest as f, recordSocketSession as r };

package/dist/{caller-B-7Ib98g.d.ts → caller-N1zmIB8c.d.ts}

@@ -1,10 +1,10 @@
-import { ad as Version, a5 as Revision } from './envelope-B6TUGKsk.js';
+import { ad as Version, a5 as Revision } from './envelope-nf5eGB-a.js';
 import { L as Logger } from './logger-BY28acW-.js';
-import { A as AccessLevel, H as AnyContract, x as CollectionWhere, O as OrderBy, k as MethodKind, d as StandardSchemaV1, af as EventName, ag as EventPayloadOf, a9 as ChannelName, aa as ChannelPayloadOf, ay as StreamName, al as IsScopedStream, ax as StreamItemOf, ad as ContractMap, ao as MethodName, ak as InputOf, aq as OutputOf } from './infer-Zs7dAWlI.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-BBU3rSbi.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';
 
 /** 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";
+type DevWarningKind = "n-plus-one" | "unbounded-read" | "oversized-response" | "nested-write" | "ambient-write" | "batch-read" | "batch-create-many" | "repeated-call" | "tiered-field-in-output";
 /** One development warning. */
 interface DevWarning {
     readonly kind: DevWarningKind;
@@ -340,6 +340,20 @@ type AnyHandler = (args: {
     readonly ctx: AnyContext;
     readonly db: unknown;
 }) => unknown;
+/**
+ * A method's own output schema, compiled from its JSON Schema when the
+ * service is defined (`pipeline/schemaOutput.ts`).
+ */
+interface SchemaOutput {
+    /** The value reduced to what the schema declares; the value itself when nothing is dropped. */
+    pick(value: unknown): unknown;
+    /**
+     * Each key the schema declares, at any depth, with the first path that
+     * declares it (`email`, `user.email`, `[].email`; `{}` stands for any key
+     * of a record): what the `tiered-field-in-output` warning reads.
+     */
+    keyPaths(): ReadonlyMap<string, string>;
+}
 /** One method of a defined service, checked and ready to dispatch. */
 interface ServiceMethod {
     readonly name: string;
@@ -358,6 +372,14 @@ interface ServiceMethod {
      * its field tiers are stripped per caller.
      */
     readonly projection: ProjectedOutput | undefined;
+    /**
+     * A schema output, compiled from its JSON Schema when the service was
+     * defined (`pipeline/schemaOutput.ts`): the handler's result is reduced to
+     * what the schema declares before the output check, on every transport.
+     * `undefined` for a projection output, and for a schema without JSON
+     * Schema (Zod 3), which is sent as the handler returns it.
+     */
+    readonly schemaOutput: SchemaOutput | undefined;
     readonly access: AccessForm;
     readonly handler: AnyHandler;
     readonly share: ShareMode | undefined;

package/dist/{chunk-Y5YAG75H.js → chunk-4HOXH4V3.js}

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