@ultimat3/cli 29.4.0 → 30.1.0

package/wiki/Auth.md

@@ -0,0 +1,195 @@
+# Auth
+
+**The output of authentication is an `Actor`.** Nothing downstream authorizes on a session row, a
+user row or an api key: HTTP, actions, jobs and MCP all read `ctx.actor` and hand it to the one
+policy system ([Policies and authz](Policies-And-Authz)). Package `@ultimat3/auth` (tier 2) — the
+full reference is
+[`packages/auth/README.md`](https://github.com/developerz-ai/ultimate/blob/main/packages/auth/README.md);
+the walk-through is [Tutorial 3](Tutorial-03-Auth-And-Admin).
+
+```ts
+import { defineAuth, login, oauthLogin, postgresAuthAdapter } from '@ultimat3/auth';
+
+export const auth = defineAuth({
+  adapter: postgresAuthAdapter(),            // or memoryAuthAdapter()
+  session: { absoluteTtlMs: 30 * 864e5, idleTtlMs: 7 * 864e5 },
+  password: { minLength: 12 },
+  mfa: { issuer: 'Acme' },
+  providers: ['github', 'google'],         // required to serve any OAuth route — the default is []
+});
+
+const { actor, token, cookie } = await login(auth, { email, password, ip });
+const { start, callback } = oauthLogin(auth);   // /auth/oauth/:provider and its callback
+```
+
+The tables (`x_users`, `x_sessions`, `x_accounts`, `x_verifications`, `x_api_keys`, and the
+passkeys' `x_passkeys`, `x_passkey_challenges`, `x_passkey_evidence`) are created by every boot; an
+app writes no migration for them.
+
+**Signing in by handle** (`As of 2026-10`): an app whose users are `@ada` names the lookup once —
+`defineAuth({ adapter, handles: async (handle) => (await db.users.where({ handle }).one())?.id ?? null })`
+— and calls `login(auth, { handle, password })`. The handle arrives trimmed and lowercased
+(`normaliseHandle`), its failures count against a bucket of its own, and an unknown handle is the
+same `X_UNAUTHENTICATED` after the same hash as a wrong password. The app's `users` row and the auth
+user share one id: `register(auth, { id, email, password })` creates the auth user under it. A handle
+login on an app that declared no `handles` is `X_CONFIG_INVALID`. The deployed demo
+(`dummy/social-media-clone/apps/web/app/auth/`) signs in this way.
+
+## Sessions
+
+| Property | How |
+|---|---|
+| opaque tokens | only `sha256(secret)` reaches the database |
+| two expiries, independent | absolute and idle; activity never moves the absolute ceiling (`X_SESSION_EXPIRED` names which) |
+| not a write per request | `lastSeenAt` moves at most once per `idleSlideMs` (default `idleTtlMs / 20`); a changed IP or user agent is written at once |
+| revocation is immediate | the user row is re-read on every request, so a revoked role takes effect on the next one |
+| the cookie | `__Host-x_session`, `HttpOnly`, `Secure`, `SameSite=Lax`, `Path=/`, `Max-Age` |
+| brute force | per-IP, per-account and per-org buckets (`X_ACCOUNT_LOCKED`); every login failure is one indistinguishable `X_UNAUTHENTICATED`. `rateLimit: { scope: 'shared' }` makes the count one for the fleet. The org bucket (`orgMaxAttempts`, default 100 per window) can be exhausted by someone who knows about 20 of an org's addresses, locking its password sign-in — kept by decision ([`SECURITY.md`](https://github.com/developerz-ai/ultimate/blob/main/SECURITY.md#known-gaps)) |
+
+**Signing out** is `logout(auth, token)` for the row plus `signOutHeaders()` on the response: it
+expires the session cookie and sends `Clear-Site-Data: "cache", "storage"`
+(`SIGN_OUT_CLEAR_SITE_DATA`), so the browser drops the previous principal's IndexedDB, storage,
+service worker and cached pages. Revocation at scale is `revokeUserSessions`, `revokeOrgSessions`,
+`revokeSessionsCreatedBefore` (after rotating a secret) and `disableUser`, which also revokes the
+user's live API keys. A `passwordHash` change through `updatePrivileges` ends every other session
+of that user — all of them when no session of theirs is passed, as in a reset.
+
+**A sign-in page is one command**, `As of 2026-11`: `x g sign-in --password` (a native form over
+`login()`, its second leg over `completeMfa()`) or `x g sign-in --oidc <provider>` (an OpenID Connect
+issuer, discovered on the first sign-in). Both write the sign-in page, the `destroySession` action,
+`auth.signInPath`, and a boot guard: outside `development` and `test` a `web` or `sync` role with
+its sign-in keys unset refuses to start (`X_AUTH_SIGN_IN_UNCONFIGURED`). `--password` also writes
+`createSession` / `confirmSession` and the second-factor page; `--oidc` writes the start and
+callback routes and drops `x new`'s development viewer while its files are still `x new`'s own. What each writes:
+[CLI reference](CLI-Reference#x-g).
+
+## OAuth
+
+`github` and `google` ship; `registerOAuthProvider` adds one. PKCE is mandatory on every
+provider — `usesPkce: false` does not typecheck — and the handshake is a signed `__Host-` cookie
+bound to its provider. An id token is verified against the provider's JWKS. An identity links to an
+**existing** account only when both the provider and that account have verified the address
+(`link: 'verified-email'`, the default); `'never'` is the only alternative. Credentials are
+`<PROVIDER>_CLIENT_ID` / `<PROVIDER>_CLIENT_SECRET`.
+
+| Rule (`As of 2026-10`) | |
+|---|---|
+| `redirect_uri` origin | `oauthLogin(auth, { baseUrl })`, else `APP_URL`. With neither the start leg answers `X_ENV_MISSING` — never the request's `Host` |
+| a refused leg's body | `code`, `title`, `docs`, one fixed `cause`, `fix: x errors explain <CODE> --json`. The authored cause and fix are the `auth.oauth.refused` log line |
+| `discoverOAuthProvider` | refuses a document whose `issuer` is not the one asked for (a trailing slash aside) |
+| a public client (`As of 2026-10-18`) | `tokenEndpointAuth: 'none'` on the provider, `discoverOAuthProvider` or `credentials`: no `<PROVIDER>_CLIENT_SECRET` is read and no `client_secret` is sent; PKCE still is. `'client_secret_basic'` sends the pair in `Authorization: Basic`. Absent: `'client_secret_post'`, unchanged |
+| `apple` | not a built-in since 26.0.0 ([#709](https://github.com/developerz-ai/ultimate/issues/709)): Apple POSTs its callback and both callback routes are GET, so it could never complete a sign-in. An app that needs it registers its own with `registerOAuthProvider` |
+
+## Passkeys
+
+**WebAuthn, verified by hand on WebCrypto — no dependency** (`As of 2026-11`). Two uses, one
+declaration: `defineAuth({ passkeys: { rpId, origins } })`. ES256 and RS256; CBOR, COSE and DER are
+parsed in this package, every malformed byte a refusal.
+
+```ts
+import { canonicalJson } from '@ultimat3/core';
+import {
+  defineAuth,
+  memoryAuthAdapter,
+  passkeyLogin,
+  passkeyStepUp,
+  sha256Hex,
+  verifyPasskeyEvidence,
+} from '@ultimat3/auth';
+
+const auth = defineAuth({
+  adapter: memoryAuthAdapter(),
+  passkeys: { rpId: 'example.com', origins: ['https://example.com'] },
+});
+
+// Sign-in: register onto a signed-in account, then usernameless sign-in to the same session login() mints.
+const { registerOptions, register, loginOptions, login } = passkeyLogin(auth);
+
+// Step-up: the proof is bound to bytes the SERVER derives from the input, and stored as evidence.
+const stepUp = passkeyStepUp<{ readonly to: string; readonly minor: number }>(auth, {
+  ttlMs: 60_000,
+  digest: ({ input }) => sha256Hex(canonicalJson(input)),
+});
+
+declare const userId: string;
+declare const response: unknown;
+const evidence = await stepUp.verify({ userId, input: { to: 'acct-7', minor: 12_500 }, response });
+// Later, in another process, with the row alone:
+const approved = await verifyPasskeyEvidence(evidence, { rpId: 'example.com', origins: ['https://example.com'] });
+```
+
+| Rule | |
+|---|---|
+| tier | functions over `Auth`, wrapped by the app's own actions (tier 2 constructs no `action`) — like `login` and `completeMfa` |
+| browser | `@ultimat3/auth/client`: `newPasskey(options)` / `getPasskey(options)` answer `{ status: 'ok', response }`, `'cancelled'`, `'unsupported'` or `'failed'` — never a throw. Its graph is two files, ~2.3 kB minified (`client-bundle.test.ts`); an island never loads the server barrel |
+| checked, every ceremony | `clientDataJSON` type, the origin against the declared list exactly (no cross-origin iframe), `rpIdHash`, **UP and UV** (user verification is required, never preferred), the signature with the STORED key's algorithm |
+| challenge | 32 random bytes, stored as its sha256 in `x_passkey_challenges` with a TTL, consumed by one `DELETE … RETURNING` — single-use across the fleet, never a process map. Unknown, spent and late are one code: `X_PASSKEY_CHALLENGE_EXPIRED` |
+| counter | a signature counter that did not move forward is a cloned authenticator (`X_PASSKEY_INVALID`); both zero is an authenticator that keeps none, allowed. Advanced compare-and-set |
+| registration | `attestation: 'none'` — the statement is parsed, not trusted; a credential id already registered to anyone is `X_AUTH_WRITE_FAILED`; a challenge issued to one account never registers onto another |
+| sign-in | the session is `mfaSatisfied`: a user-verified passkey is possession plus the device's PIN or biometric |
+| step-up challenge | `SHA-256("ultimate.passkey.step-up.v1\0" ‖ nonce ‖ len ‖ digest ‖ userId)` — never supplied by a caller. A proof for other bytes, or none, is `X_PASSKEY_STEP_UP_REQUIRED` |
+| evidence | `x_passkey_evidence`: the signed bytes, the nonce, the digest and the key itself, so `verifyPasskeyEvidence` re-checks it with no adapter and no clock; any edit to digest, nonce, user, key or signed bytes is `false`. `auth.adapter.listPasskeyEvidence(digest)` finds the approvals of one digest |
+| refusals | `X_PASSKEY_INVALID` (which check failed is the `auth.passkey.refused` log line, never the cause), `X_PASSKEY_CHALLENGE_EXPIRED`, `X_PASSKEY_STEP_UP_REQUIRED`; a bad `passkeys` block is `X_CONFIG_INVALID` at `defineAuth` |
+
+## MFA, verification, API keys, workloads
+
+| Capability | Calls |
+|---|---|
+| TOTP + recovery codes | `enrolTotp`, `saveTotpSecret`, `generateRecoveryCodes`. The secret is **sealed at rest** under the app's master key and a plaintext one is refused, never read (`X_MFA_SECRET_UNSEALED`; `x auth seal-mfa` seals rows from before); a recovery code is consumed in one statement, so it works once. A password proven with a factor outstanding is `X_MFA_REQUIRED`, whose `meta.challenge` is a sealed five-minute credential; `completeMfa(auth, challenge, code)` finishes the sign-in, meters the guess against the same lockout buckets a password guess spends, and refuses a spent code on every replica (`x_totp_steps`, installed by the boot) |
+| email verification, password reset, any other mailed credential | `defineVerificationPurpose({ name, template, ttlMs, identifier? })` → `{ issue, consume }` (`As of 2026-11`); `emailVerification` and `passwordReset` are its two built-in instances, and `issueVerification` / `consumeVerification` take any declared name. A token is consumed only when its hash matches, so a wrong guess cannot burn the victim's live link, and one purpose's token never consumes another's. A name declared twice or with no template is `X_VERIFICATION_PURPOSE_INVALID` at boot; an undeclared one at the call is `X_VERIFICATION_PURPOSE_UNKNOWN` (400). `VerificationPurpose` is `string`: a `switch` over it needs a default arm. The mail is sent through an injected `MailSender` ([Mail](Mail)) |
+| API keys — how an agent authenticates | `issueApiKey` → `ult_<env>_<id>_<secret>`, shown once; `verifyApiKey` + `apiKeyActor` give a `kind: 'agent'` actor whose scopes are the key's and never the owner's roles (`X_API_KEY_INVALID`). A key is its owner's credential: a missing or disabled owner refuses it on the next use, a wildcard scope (`*`, `<resource>:*`) is refused at issue, and an owned key keeps only the scopes its owner's grants cover — pass `grantsOf` to expand roles ([`packages/auth/README.md`](https://github.com/developerz-ai/ultimate/blob/main/packages/auth/README.md)); a key with no `userId` is unchanged. `apiKeyResolver(() => store)` is both as the `resolveToken` a bearer mount and `defineAppMcp()` take: `{ actor, scopes }` for a live key, one `null` for every wrong one, and a store fault left a throw. In a test the store is `memoryAuthAdapter()` |
+| service-to-service | `verifyWorkloadToken` reads a Kubernetes service-account token, a SPIFFE JWT-SVID or a cloud IMDS token (they are all one JWT); `actorFromService` gives a `kind: 'service'` actor. The returned `WorkloadToken` carries `raw`, the whole decoded payload, read only after every check held. mTLS is the mesh's job |
+| an external issuer's bearer (`As of 2026-11`) | `jwtBearerResolver({ keys, issuers, audience, requiredScope?, accept?, actorOf })` — `apiKeyResolver`'s twin for JWTs, the `resolveToken` a bearer mount and `defineAppMcp()` take. `keys` is a thunk read when a token arrives (no discovery at import); `accept(raw)` is the app's own claim check after the signature; `actorOf(token)` builds the actor. Every refusal — signature, issuer, audience, expiry, scope, `accept`, and a key set that cannot be read — is `null` plus one `auth.jwt_bearer.refused` log line naming the check, never a claim's value. The mount answers that `null` as `401 X_UNAUTHENTICATED` |
+
+## Authorization server
+
+`As of 2026-11`. `authorizationServer({ issuer, store, consentPath, lifetimes, scopes, registration?, grants?, resources? })`
+is one OAuth 2.1 server for an app's MCP endpoint, public API, CLI and partners alike. It ships the
+RFC rules; the consent page, who may be a client and what a subject becomes are the app's.
+
+```ts
+import type { Actor, PgExecutor } from '@ultimat3/core';
+import { authorizationServer, oauthBearerResolver, postgresAuthServerStore } from '@ultimat3/auth';
+
+declare const executor: PgExecutor;
+declare function actorFor(subject: string): Promise<Actor | null>;
+
+export const oauth = authorizationServer({
+  issuer: 'https://www.example.com',
+  store: postgresAuthServerStore({ executor }),
+  consentPath: '/oauth/consent',               // the app's page; the advertised authorization_endpoint
+  lifetimes: { accessSeconds: 600, refreshIdleDays: 30, clientSeconds: 900 },
+  scopes: ['cases:read', 'cases:write'],
+  grants: ['authorization_code', 'refresh_token', 'client_credentials'],
+});
+export const runtime = { routes: [...oauth.routes] };           // apps/web/runtime.ts
+const resolveToken = oauthBearerResolver(oauth, { actor: (grant) => actorFor(grant.subject) });
+```
+
+| Piece | What it does |
+|---|---|
+| `routes` | `GET /.well-known/oauth-authorization-server` (RFC 8414), `POST /oauth/token`, `/oauth/revoke` (RFC 7009), `/oauth/introspect` (RFC 7662), plus `/oauth/register` (RFC 7591, `registration: 'dynamic'`) and `/oauth/device` (RFC 8628). Plain `Route`s for `runtime.routes`, public, no cookie authenticates them. Every answer is `no-store` RFC 6749 JSON |
+| consent | the page calls `readRequest(url)` → `{ client, scopes, resource, redirectUri }` or a refusal; an unknown client or unregistered redirect has `redirectTo: null` — render it, never redirect. Its action calls `approve({ subject, request, scopes? })` / `deny({ request })` for the redirect URL (`code`, `state`, `iss`). A forged request is `X_AUTH_CONSENT_INVALID` (422) |
+| device | the verification page calls `readDevice({ userCode, key })`, `approveDevice` / `denyDevice`; `key` is the caller's bucket — 10 misses lock it (`X_ACCOUNT_LOCKED`) |
+| `registerClient(...)` | a client the app creates itself — a partner's `client_credentials` client; the secret is shown once and stored hashed |
+| `resolve(token)` | `{ subject, scopes, clientId, resource } \| null`. `oauthBearerResolver(server, { actor, resource? })` is the `resolveToken` a bearer mount and `defineAppMcp` take; `actor` runs per call, so a removed member loses access at once |
+| `revoke({ subject, clientId? })` · `purge({ before })` | immediate; `purge` is the app's `task` to schedule, nothing here runs on a timer |
+
+| Rule | Held by |
+|---|---|
+| redirect URIs match byte for byte | `authorization-server-request.test.ts` |
+| S256 only; an absent method is `plain` and refused | same |
+| a code lives 2 minutes, is stored hashed, is single use; a replay revokes what it minted | `authorization-server.test.ts`, `authorization-server-store.contract.test.ts` (racing redemptions on Postgres) |
+| refresh rotates; a retired one's replay revokes the grant; idle past `refreshIdleDays` is dead | `authorization-server.test.ts` |
+| `resource` (RFC 8707) binds the grant; one not in `resources` is `invalid_target` | `authorization-server-request.test.ts`, `oauth-bearer-resolver.test.ts` |
+| tokens are opaque and stored hashed, never a JWT, so `revoke` holds on the next lookup | `token-endpoints.test.ts` |
+| an `https://` `client_id` is a metadata document, fetched through `outbound({ dial: 'public' })`, 5 KiB, cached 5 minutes, public clients only | `authorization-server-clients.test.ts` |
+| `client_credentials`: confidential only, no refresh token, subject is the client | `grant-client-credentials.test.ts` |
+| dynamic registration never hands out `client_credentials` and is counted per address | `authorization-server-clients.test.ts` |
+
+Bad configuration is `X_AUTH_SERVER_INVALID` naming the field; a grant not in `grants` answers
+`unsupported_grant_type` and is logged `X_AUTH_GRANT_DISABLED`. The five tables (`x_oauth_*`) are
+applied by the boot. For one MCP endpoint, `mcpAuthorizationServer` ([MCP and AI](MCP-And-AI)).
+
+Every auth code — `X_UNAUTHENTICATED`, `X_SESSION_EXPIRED`, `X_MFA_REQUIRED`, `X_OAUTH_*`,
+`X_ACCOUNT_LOCKED`, `X_API_KEY_INVALID` and the rest — is in [Error codes](Error-Codes).

package/wiki/Bare-VM.md

@@ -0,0 +1,111 @@
+# Bare VM
+
+A fresh Ubuntu box with **bun** and **git** runs a scaffolded app's whole gate. No Docker daemon, no
+Postgres, no Redis, no NATS, no object store, no `.env` editing. Bun runs all four commands below;
+git is what commits the scaffold, and `--no-git` is the form that skips it.
+
+```sh
+bunx create-ultimate demo --no-git
+cd demo
+bun run setup
+bun run verify
+```
+
+| Command | What it needs from the box |
+|---|---|
+| `bunx create-ultimate demo --no-git` | bun, and a network the npm registry answers on. `--no-git` skips `git init`, which is the form an automated provisioner uses; without it the scaffold is committed, and that is git's only job here |
+| `cd demo` | — |
+| `bun run setup` | bun. Six steps: `bun install`, an `.env.development.local` touch, `x db gen "initial"` when `packages/db/migrations` holds no `.sql`, `x db migrate`, `x db seed`, `x manifest` |
+| `bun run verify` | bun. `x verify`, the whole gate: its `budgets` step runs `x build --target static` itself, because `.x/build-stats.json` does not exist yet on a fresh box (`As of 30.0`) |
+
+`x new` installs nothing, so `bun run setup` is not optional and `cd demo && bun run verify` stops on
+`X_BUILD_FAILED` naming `bun install` ([Installation](Installation)).
+
+## Why no service is needed
+
+The scaffold's `.env.development` ships committed non-secret defaults, and it leaves `DATABASE_URL`
+empty. An empty `DATABASE_URL` is not a hole to fill — it is the switch that selects the embedded
+database, in `resolveServices`
+([`packages/cli/src/runtime-bindings.ts`](https://github.com/developerz-ai/ultimate/blob/main/packages/cli/src/runtime-bindings.ts)),
+which is the one place the three service bindings are decided:
+
+| Binding | Unset env | Resolves to | Set it to |
+|---|---|---|---|
+| db | `DATABASE_URL` | `pglite://<app>/.x/pgdata` — Postgres compiled to WASM, running **inside this process** | a `postgres:` URL |
+| events | `NATS_URL` | `inproc://events` — in-process fanout | a NATS URL |
+| storage | `S3_ENDPOINT` | `file://<app>/.x/storage` | an S3 endpoint |
+
+The database is
+[`packages/db/src/pglite.ts`](https://github.com/developerz-ai/ultimate/blob/main/packages/db/src/pglite.ts):
+a real Postgres, WASM-compiled, opened on a directory under `.x/`, so `x db migrate` and `x db seed`
+write to the same engine the app then reads — no container to wait for, no port to publish, and a
+restart keeps the data. The module is an **optional peer resolved at first query, never at import**,
+so an image that only ever talks to a managed Postgres does not carry the WASM it will never load.
+`@electric-sql/pglite` is a `devDependencies` entry of the generated app, which is what puts it on
+the box during step 1 of `bun run setup`.
+
+**Its absence is a coded refusal, never a silent skip**: `X_DB_UNAVAILABLE`, whose `fix:` is
+`bun add @electric-sql/pglite, or set DATABASE_URL to a Postgres server and re-run` — a command the
+reader runs, on a box that has just told them what is wrong.
+
+`x doctor` says it earlier than the first query does. Its external-database probe answers nothing
+where `DATABASE_URL` is unset, and that silence is exactly this box, so it asks the embedded
+question too: does the peer **resolve** from the app root — a resolve, never an import, since
+loading it boots the WASM and takes the single-writer lock the next command needs. Red only where
+`DATABASE_URL` is unset *and* the peer is unresolvable ([CLI reference](CLI-Reference)).
+
+The gate's `live`, `job` and `e2e` steps need no service of their own in a generated app: the
+queue is Postgres (`SELECT … FOR UPDATE SKIP LOCKED`), the fanout is in-process, and both resolve
+through the table above.
+
+## What the embedded database does not do
+
+**No logical replication.** PGlite has no walsender, so there is no write-ahead log to decode and no
+slot to take. A `--live` query still works: `x dev` installs the in-process bridge instead — the
+same row observer the framework's own live tests run on — and the boot line says which feed you
+got, `live=in-process` under the embedded database and `live=replication` under a real one
+(`packages/cli/src/runtime-live-feed.ts`). Its honest bound is that a write made by **another process**
+is invisible to it, which holds by construction under `x dev`, where every role is this one process
+([Realtime](Realtime)).
+
+Reach for the dev compose file only when you want parity against a real Postgres, NATS and S3
+([Deployment](Deployment)). Nothing on this page uses it.
+
+## Wall time
+
+Both tables predate 30.0 and time `bun run check`, the scaffold's old wrapper: `x build --target
+static`, then `x verify`. `bun run verify` does the same work in one command, the build inside
+`budgets`, so the figures are its order of magnitude, not its measurement.
+
+On a **WSL2 developer box — not a bare VM, and not a CI runner** — on a Bun the CLI's own floor
+accepts (`x doctor`), against real `x new` scaffolds, first pass, nothing waived and no fix-follow,
+warm Bun cache, `As of 2026-09-11`:
+
+| Measure | Default scaffold | `--no-example` |
+|---|---|---|
+| files written | 161 | 133 |
+| `bun run setup` | **6,802ms** | **5,135ms** |
+| `bun run check` | **5,389ms** | **3,909ms** |
+| the first `bun run check`'s verdict | **green, every step**, `budgets` included | **green, every step**, `budgets` included |
+
+The cache is the variable to watch, not the box: a **cold** first install takes the `bun install`
+inside `bun run setup` to **12.0s** on the same machine.
+
+And on a **free `ubuntu-latest` runner**, which is the measurement that speaks for a provisioned
+box — `ci.yml`'s `scaffold-smoke` job, running these same two scripts on a scaffold written outside
+the checkout, `As of 2026-09-12`:
+
+| Measure | Default scaffold | `--no-example` |
+|---|---|---|
+| files written | 161 | 133 |
+| `bun run setup` | **6,665ms** | **5,994ms** |
+| `bun run check` | **7,279ms** | **4,886ms** |
+| the first `bun run check`'s verdict | **green, every step passes** | **green, every step passes** |
+
+On both dates the gate was 20 steps; `exercise` joined it in 2026-11, so a run today counts 21.
+
+`budgets` is green on that first pass on every one of those runs, because the gate builds before
+it weighs — nothing is waived to get there, and no printed `fix:` is followed before the verdict
+is taken. The job prints the table itself, one row per command and one per gate step, so the run is
+its own measurement rather than a number this page asserts: read it from the job's log when you want
+today's.

package/wiki/Batching-And-Preloading.md

@@ -0,0 +1,136 @@
+# Batching and preloading
+
+The entity layer never sends one statement per row. A relation is a foreign key read a second way, not a second declaration, and every batching path — automatic or named — reads the same `references()` columns [Entities and migrations](Entities-And-Migrations) already derives relations from.
+
+`As of 2026-08`. Source: [`packages/entity/src/relations.ts`](https://github.com/developerz-ai/ultimate/blob/main/packages/entity/src/relations.ts), [`query.ts`](https://github.com/developerz-ai/ultimate/blob/main/packages/entity/src/query.ts), [`pg-driver.ts`](https://github.com/developerz-ai/ultimate/blob/main/packages/entity/src/pg-driver.ts).
+
+## Relations are derived, never declared twice
+
+`belongsTo`/`hasMany` come out of the `.references(() => orgs.id)` calls an entity's columns already make — there is no `hasMany: […]` init key, and adding one would put two declarations of one fact in the schema. A `belongsTo` reads the FK's own column (`authorId` → `author`); a `hasMany` reads it from the other side (`posts` inbound to `orgs`). When two foreign keys would collide on one name, **every** member of that colliding group takes its long form together — never just the newcomer — so a second FK declared later cannot silently rename the first relation. What the two tiers still cannot separate is refused as `X_INVARIANT_VIOLATED`, naming both columns, never collapsed into one relation.
+
+There is exactly one flat namespace of relation names per entity, `belongsTo` and `hasMany` mixed, resolved through `relationNamed(entity, name)` — a name no foreign key produces is `X_PRELOAD_UNKNOWN_RELATION`, listing the relations that do exist.
+
+## Three ways the same batching shows up
+
+| Form | Trigger | Statements |
+|---|---|---|
+| Point-lookup coalescing | several `findById` calls in one microtask | one `where id in (…)` |
+| JIT (sibling-aware) preload | a `findById` whose id is a FK value on a page already read | one `where <key> in (…)` for the whole loop |
+| `.preload('name')` | named on the chain | one extra statement per relation, resolved concurrently |
+
+The first two are automatic — nothing to opt into, no `dataloader()`, no `batch()` call. `.preload()` is the explicit, declarative third: name the relation once and every row of the page carries it, resolved *before* the caller sees a row.
+
+### Same-microtask coalescing
+
+`findById` called several times inside one microtask of one request is one `select … where "id" in (…)`. The store is a per-request `WeakMap<Ctx, …>`, so a batch dies with the request and never crosses one; a sequential `for … of` loop shares no microtask — its `await` ends the window — which is what the sibling preload below exists for.
+
+### JIT preload — the sibling-aware case
+
+`findMany` tags the rows it returns with their own foreign key **values** (never the rows) under a per-request store. The first `findById` whose id matches one of those values then resolves that key for **every** row of the page in one statement, and the rest of a `for … of` loop is served from memory:
+
+```ts
+const page = await db.posts.findMany({ orgId });
+for (const post of page.rows) {
+  // Two statements for the whole loop: the page, then one `where "id" in (…)` over every
+  // author on it. Every lookup after the first is memory.
+  const author = await db.users.findById(post.authorId, { orgId });
+}
+```
+
+Controlled by the `jitPreload` option, default `true`, on `postgresDriver({ jitPreload })` / `postgresRepo(entity, { jitPreload })`. **Not** an `app.config.ts` key — nothing reads config at the seam that builds a repository, so a `database.jitPreload` field would be a switch the framework cannot read. Set it where the driver is built.
+
+### `.preload('relation')` — named on the chain
+
+```ts
+export const db = database({ orgs, posts, members });
+
+// Two statements: the page, then one `select … where "id" in (…)` over its authors.
+const page = await db.posts.where({ orgId }).preload('author').page();
+page.rows[0].author;   // the member row, or null — always present
+```
+
+A `belongsTo` attaches the row or `null`; a `hasMany` attaches an array, always present so "no author" and "nobody preloaded the author" cannot read the same. `preload()` is resolved on the chain (`relationNamed`), so an unknown relation fails there and not a page later. Attachment happens after the projection — `select()` is widened internally with every preloaded relation's own key, so a projection can never drop what a preload needs; `plan().select` reports the widened list that actually ran. Only the terminals that read a row resolve it: `page()`, `all()`, `one()` — never `count()`, `countBy()` or `plan()`, since none of those has a row to attach one to.
+
+A preload is **bounded**: one relation attaches at most `max` related rows to one page — `preload('comments', { max: 2000 })`, default 10,000 (`MAX_PRELOADED_ROWS`). Past it the read is refused (`X_INVARIANT_VIOLATED`, naming the raised ceiling and the `inBatches` form), never truncated — an array one row short reads as "these are the children".
+
+Reach for `.preload()` when the relation is part of what the page *is* — a list rendered with its authors, rows handed somewhere that will not call back into the repo, or a read a reviewer should see stated rather than inferred from a loop. The other two forms ask for nothing.
+
+## The tenancy guarantee — a security boundary, not a perf detail
+
+**A coalesced or JIT-preloaded statement carries exactly the scope every single lookup it replaces would have carried — same tenant predicate, same soft-delete visibility, same projection, same entity, same client.** This is enforced, not incidental:
+
+- The coalescer's scope key (`scopeKey` in `batch-read.ts`) is built from the entity, the table, `includeDeleted`, the projection and every `where` predicate — two lookups share a statement only when all of that matches. A predicate whose value cannot be rendered to a string declines the batch rather than guess.
+- The JIT preload's bucket is keyed the same way, and a bucket is only reused when its client and its write-generation still match; a write to that entity drops the bucket before the statement goes out (`forgetPreloaded`), so a row a request just changed is re-read, never served stale.
+- `.preload()`'s tenancy is *carried*, never inferred: the page's own tenant predicate reaches the related read only when **both** entities are scoped by a column of the same name. A source scoped by `workspaceId` may still carry an ordinary `orgId` predicate of its own — a filter, not its tenancy — and matching on the target's column name alone would lift that filter into the target's tenant scope. Carrying nothing is not a failure of this rule: the related read builds its own plan, and `assertScoped` refuses it as `X_TENANCY_UNSCOPED` rather than answer with a guess.
+
+`pg-driver.test.ts`, `jit-preload.test.ts` and `preload.test.ts` each pin this against a real cross-tenant fixture — another tenant's row is unreachable from every one of the three paths, never served by whichever tenant asks.
+
+## Bulk writes — the same idea on the write side
+
+A loop of `insert()` calls is the same defect a per-row read loop is, on the other side of the statement:
+
+```ts
+await db.tags.insertAll(names.map((name) => ({ orgId, name })));         // one statement, n rows
+
+await db.likes.upsertAll(rows, {                                         // insert, or leave what's there
+  onConflict: ['postId', 'memberId'],   // the declared unique index, verbatim — `likes` keys on the pair
+  onMatch: 'nothing',                   // …so the tenant column is not in the target: see below
+});
+
+const n = await db.posts.updateWhere({ orgId, status: 'draft' }, { status: 'archived' });
+const removed = await db.likes.deleteWhere({ orgId, postId, memberId });
+```
+
+| Call | Shape |
+|---|---|
+| `insertAll(rows)` | one multi-row `insert`, every row parsed through `$parse` exactly as `insert(row)` parses one |
+| `upsertAll(rows, { onConflict, onMatch })` | `on conflict (…) do update` / `do nothing`; a collision overwrites every column the batch names except the conflict target, the primary key, and the soft-delete stamp |
+| `updateWhere(filter, patch)` | the bulk form of `update(id, patch)` — and the only write path for a composite-key entity (`likes`, `blocks`, any join table) with no single-column id to address |
+| `deleteWhere(filter)` | the bulk form of `delete(id)`, same reason |
+| `countBy(column)` | one grouped count, the aggregate a `count()` per row is the N+1 of — see [Entities and migrations → A count per row is one grouped count](Entities-And-Migrations#a-count-per-row-is-one-grouped-count) |
+
+`onConflict` names the columns of a **declared unique index**, never a convenient superset: `likes` is `primaryKey: ['postId', 'memberId']` with `orgId` as its tenant column, so `['orgId', 'postId', 'memberId']` matches no index and is refused. The tenant column belongs in the conflict target only under `onMatch: 'update'`, where a collision writes — a target without it would match and overwrite another tenant's row, which is `X_TENANCY_UNSCOPED` and not an N+1 code. Under `onMatch: 'nothing'` no write happens to a row you do not own, so the pair alone is right. Every other call still passes its tenant filter: `deleteWhere({ orgId, postId, memberId })`, not `deleteWhere({ postId, memberId })`.
+
+`deleteWhere({})` and `updateWhere({}, patch)` are `X_WRITE_UNFILTERED`, never every row; an empty patch is `X_PATCH_EMPTY`. Both are covered in full, including the tenancy rule on `onMatch: 'update'`, in [Entities and migrations → Writing many rows is one statement](Entities-And-Migrations#writing-many-rows-is-one-statement).
+
+## `inBatches(size)` — sweeping a whole table
+
+The chain's own terminal for "every row, not one page":
+
+```ts
+await using batches = db.posts.where({ orgId }).preload('author').inBatches(500);
+for await (const batch of batches) {
+  await search.index(batch);
+}
+```
+
+`inBatches` returns a disposable async iterator (`AsyncIterable & AsyncDisposable`) — `break`, `return`, a throw, and `await using` all stop the *next* statement rather than the one in flight, and `close()` is idempotent by construction. Its `.cursor` is where the next batch starts, advanced before the yield, so a consumer that stops early can persist it and resume later with `.after(cursor).inBatches(size)`. Every batch is exactly the page `page()` would have sent at that position — same filters, tenancy, soft delete, projection and every `.preload()` — so this is not a second read path.
+
+Keyset only, the same reason there is no `offset()` anywhere in this package: an insert before an OFFSET shifts every later page, silently skipping or repeating rows under concurrent writes. Two refusals happen at `inBatches()` itself rather than one batch later: a size that is not a whole number of rows ≥ 1, and a chain that also called `limit()` — one number would then carry two meanings, and neither reading is safe to guess. An ordering that cannot carry a cursor (a nullable sort column) is refused there too.
+
+This is also the mechanism `backfill()` runs on — see [Migrations and backfills](Migrations-And-Backfills).
+
+## The jobs `PgExecutor` carve-out
+
+`@ultimat3/jobs`' Postgres driver (`driver-pg.ts`) does **not** go through any of the above. It speaks the one-method `PgExecutor` interface (`query(sql, params)`, declared once in `@ultimat3/core`), and has no `@ultimat3/db` or `@ultimat3/entity` dependency at all — a claim, an ack, a nack, an enqueue or a heartbeat is compiled straight to SQL against that executor, never through a repository. This is a documented exception, not a gap: **queue traffic is invisible to this batching machinery by design**, because there is no repository call for the coalescer, the JIT preload or `.preload()` to attach to. It follows that a job driver statement carries no statement attribution either (see `packages/jobs/CLAUDE.md`), which is a separate, narrower observability note and not something this page's tenancy guarantee needs to answer for.
+
+## Errors
+
+Each code carries its own `fix:` line, computed from the call that raised it — the entity's real name, its real columns, the relations it really has. The table below shows the *shape* that line takes; the authority is the error itself, and `x errors explain <CODE> --json` prints it.
+
+| Code | Owner | Cause | `fix:` shape |
+|---|---|---|---|
+| `X_PRELOAD_UNKNOWN_RELATION` | `entity` | `<entity>` has no relation named `"<name>"` | `relationNamed('<entity>', '<known>')   # or: <the other names>` — and `x entities list --json` when the entity declares none |
+| `X_TENANCY_UNSCOPED` | `entity` | `<entity>.<op>()` was built without an org predicate but the entity has an `orgId` column | `pass { orgId } to <entity>.<op>(), or wrap the plan with orgScoped(entity, orgId, plan)` |
+| `X_TENANCY_UNSCOPED` (upsert) | `entity` | the collision is judged on columns that exclude the tenant column, so another tenant's row would match | `<entity>.upsertAll(rows, { onConflict: ['orgId', …] })   # or onMatch: 'nothing'` |
+| `X_N_PLUS_ONE_QUERY` | `entity` | `<subject>` ran `<n>` times in one request — one read per row | `db.<entity>.preload('<relation>')`, or `db.<entity>.andWhere('id', 'in', ids).all()` |
+| `X_N_PLUS_ONE_WRITE` | `entity` | `<subject>` ran `<n>` times in one request — one write per row | `db.<entity>.insertAll(rows)` (or `upsertAll`/`updateWhere`/`deleteWhere`), or `expectedQueryLoop('<why one per row is optimal>', fn)` |
+| `X_QUERY_SCALES_WITH_ROWS` | `testing` | `x exercise`'s scale sweep: `<primitive>` sent `<shape>` `<n>`× at 2 rows a table and `<m>`× at 8 — a loop no test named ([Testing](Testing#the-plan-and-scale-sweeps)) | `x exercise <primitive> --json   # after preload() …, or expectedQueryLoop('<why>', fn)` |
+| `X_WRITE_UNFILTERED` | `entity` | `<entity>.<op>()` named no filter columns — an empty filter would reach every row | `<entity>.<op>({ <primary key columns> }, …)`; a deliberate whole-table write is `x db gen "<name>"` |
+| `X_PATCH_EMPTY` | `entity` | `<entity>.<op>()` named no columns to write | `<entity>.<op>(filter, { <column>: <value> })   # pick a column from: <the entity's columns>` |
+
+```bash
+x errors explain X_N_PLUS_ONE_QUERY --json    # the canonical cause + fix for any code above
+```
+
+Full list with `--json` shapes: [Error codes](Error-Codes). Resource lifetimes referenced above — the `using pinned` client and the advisory-lock RAII shape — are covered once in [Resource management](Resource-Management).