@voltro/cli 0.7.0 → 0.9.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { k as e } from "./inspectMetrics-BLUBAWLb.js";
-import { t } from "./start-CWZW_4Et.js";
+import { I as e } from "./inspectMetrics-DVCKKSPk.js";
+import { t } from "./start-CYe-7ueh.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -57,24 +57,25 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.7.0",
-    "@voltro/cache": "0.7.0",
-    "@voltro/data-transfer": "0.7.0",
-    "@voltro/database": "0.7.0",
-    "@voltro/env": "0.7.0",
-    "@voltro/kv": "0.7.0",
-    "@voltro/logger": "0.7.0",
-    "@voltro/plugin-auth": "0.7.0",
-    "@voltro/plugin-broadcast": "0.7.0",
-    "@voltro/plugin-mail": "0.7.0",
-    "@voltro/plugin-storage": "0.7.0",
-    "@voltro/plugin-webhooks": "0.7.0",
-    "@voltro/protocol": "0.7.0",
-    "@voltro/runtime": "0.7.0",
-    "@voltro/serverless": "0.7.0",
-    "@voltro/workflow": "0.7.0",
+    "@voltro/ai": "0.9.0",
+    "@voltro/cache": "0.9.0",
+    "@voltro/data-transfer": "0.9.0",
+    "@voltro/database": "0.9.0",
+    "@voltro/env": "0.9.0",
+    "@voltro/kv": "0.9.0",
+    "@voltro/logger": "0.9.0",
+    "@voltro/plugin-auth": "0.9.0",
+    "@voltro/plugin-broadcast": "0.9.0",
+    "@voltro/plugin-mail": "0.9.0",
+    "@voltro/plugin-storage": "0.9.0",
+    "@voltro/plugin-webhooks": "0.9.0",
+    "@voltro/protocol": "0.9.0",
+    "@voltro/runtime": "0.9.0",
+    "@voltro/serverless": "0.9.0",
+    "@voltro/workflow": "0.9.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
+    "tinyglobby": "^0.2.17",
     "ts-morph": "^28.0.0"
   },
   "optionalDependencies": {

package/templates/AGENTS.core.md

@@ -313,10 +313,21 @@ helper from a `lib/` file that ALSO imports the `database` handle drags the whol
 server graph (and any `node:crypto` behind it) into the browser bundle. Keep
 browser-safe symbols (typed errors, Schemas, pure helpers) in files with ZERO
 server imports; put DB-backed guards/helpers in `.server.ts` or a server-only
-module. Some plugins ship a browser-safe subpath for exactly this (e.g.
-`@voltro/plugin-multitenancy/guard`, `@voltro/plugin-webhooks/errors`,
-`@voltro/ai/events`) — import typed errors / Schemas from there in descriptors,
-never from the package root.
+module. Several packages ship a browser-safe subpath for exactly this (e.g.
+`@voltro/database/wire`, `@voltro/plugin-multitenancy/guard`,
+`@voltro/plugin-webhooks/errors`, `@voltro/ai/events`) — import typed errors /
+Schemas from there in descriptors, never from the package root.
+
+A consequence worth stating, because it is not obvious: a descriptor's `output`
+can never be **derived from a table**. `rowSchema(table)` / `columnSchema(def)`
+take the table as a VALUE, so reaching one means importing your
+`database/schema.ts`, which imports `@voltro/database` — the boot aborts with
+the import chain. Write `output` as your own `Schema.Struct` and take the field
+schemas from `@voltro/database/wire` (`timestampMs` for a `timestamp()` column,
+`timestampMsOrNull` when it is `.nullable()`, `Schema.optional(timestampMs)`
+when the field may be absent). `rowSchema` is a row CODEC for server-only code
+(`*.server.ts`, `*.seed.ts`, jobs, scripts) — file exports, queue payloads,
+validating seed data — not a descriptor helper.
 
 **Symptom of a leak:** the web app fires hundreds of module requests / tens of MB
 on first load, or crashes with `Module "node:crypto" has been externalized for

package/templates/AGENTS.md

@@ -313,10 +313,21 @@ helper from a `lib/` file that ALSO imports the `database` handle drags the whol
 server graph (and any `node:crypto` behind it) into the browser bundle. Keep
 browser-safe symbols (typed errors, Schemas, pure helpers) in files with ZERO
 server imports; put DB-backed guards/helpers in `.server.ts` or a server-only
-module. Some plugins ship a browser-safe subpath for exactly this (e.g.
-`@voltro/plugin-multitenancy/guard`, `@voltro/plugin-webhooks/errors`,
-`@voltro/ai/events`) — import typed errors / Schemas from there in descriptors,
-never from the package root.
+module. Several packages ship a browser-safe subpath for exactly this (e.g.
+`@voltro/database/wire`, `@voltro/plugin-multitenancy/guard`,
+`@voltro/plugin-webhooks/errors`, `@voltro/ai/events`) — import typed errors /
+Schemas from there in descriptors, never from the package root.
+
+A consequence worth stating, because it is not obvious: a descriptor's `output`
+can never be **derived from a table**. `rowSchema(table)` / `columnSchema(def)`
+take the table as a VALUE, so reaching one means importing your
+`database/schema.ts`, which imports `@voltro/database` — the boot aborts with
+the import chain. Write `output` as your own `Schema.Struct` and take the field
+schemas from `@voltro/database/wire` (`timestampMs` for a `timestamp()` column,
+`timestampMsOrNull` when it is `.nullable()`, `Schema.optional(timestampMs)`
+when the field may be absent). `rowSchema` is a row CODEC for server-only code
+(`*.server.ts`, `*.seed.ts`, jobs, scripts) — file exports, queue payloads,
+validating seed data — not a descriptor helper.
 
 **Symptom of a leak:** the web app fires hundreds of module requests / tens of MB
 on first load, or crashes with `Module "node:crypto" has been externalized for

package/templates/agent-docs/authentication.md

@@ -1033,12 +1033,12 @@ const result = await handleSignIn(
 What it does:
 
 1. `userStore.findByEmail(email)` — fetch the user (or pretend, see [timing oracle](/docs/authentication/passwords#timing-oracle-defence)).
-2. `verifyPassword(password, user.passwordHash)` — always run, even on unknown email.
+2. `verifyPassword(password, user.passwordHash)` — always run, even on unknown email, and even when the user exists but has **no** stored hash.
 3. On success: `issueSession(subject, config.secret, {...})` → set the `Set-Cookie` header.
 4. If `redirectAfter` is true (form POST): 302 to `AUTH_CONFIG.successRedirect`.
 5. If `redirectAfter` is false (XHR / fetch): 200 + JSON `{ ok: true, subject }`.
 
-Failures return a 401 `HandlerResult` with a generic `{ error: 'invalid credentials' }` body — no email-existence disclosure. The handlers encode failures as 4xx/5xx `HandlerResult`s rather than throwing domain errors across the wire.
+Failures return a 401 `HandlerResult` with a generic `{ error: 'invalid credentials' }` body — no email-existence disclosure. That includes an account with no `passwordHash` at all (SSO-only, magic-link-only, passkey-only, provider PAT): the password strategy **refuses** it, taking the same branch as an unknown email — same decoy scrypt, same status, same body, no cookie. An absent hash is never "nothing to compare, let them in", and the response does not reveal which accounts are password-less. The handlers encode failures as 4xx/5xx `HandlerResult`s rather than throwing domain errors across the wire.
 
 ## handleSignUp
 
@@ -1233,7 +1233,7 @@ interface UserStore {
 interface UserRecord {
   readonly id: string
   readonly email: string
-  readonly passwordHash: string
+  readonly passwordHash?: string | null   // absent = this account has no password
   readonly tenantId: string
   readonly createdAt: Date
   readonly mfaSecret?: string | null      // base32 TOTP secret; null = not enrolled
@@ -1241,6 +1241,10 @@ interface UserRecord {
 }
 ```
 
+`passwordHash` is **optional** — not every identity has a password. An SSO-only, magic-link-only, passkey-only or provider-PAT app simply omits it, and the `users` table column is nullable to match. Do not invent a placeholder: a fake hash is a real value sitting in the column a verifier compares against, which is strictly worse than storing nothing. `null`, `undefined` and `''` all mean "no password".
+
+`handleSignIn` refuses a password sign-in for such an account the same way it refuses an unknown email — it still burns a decoy scrypt and returns the identical 401 with no cookie — so the response reveals neither that the account exists nor that it is password-less. Assigning a hash later (password reset, set-password) promotes the account to a password user normally. `createdAt` stays required; every store can supply it, and `insert` takes `Omit<UserRecord, 'createdAt'>` so you never pass one yourself.
+
 There is no `updatePasswordHash` method and no `updatedAt` field. The interface is deliberately small. Add your own fields (display name, avatar URL, locale) on a sibling table joined by `userId` — keep the auth-critical fields in the auth table.
 
 ## memoryUserStore
@@ -1318,7 +1322,6 @@ const okta = (): UserStore => ({
       return {
         id:           `okta:${oktaUser.id}`,
         email:        oktaUser.profile.email,
-        passwordHash: '', // we never auth password locally — see below
         tenantId:     oktaUser.profile.tenantId,
         createdAt:    new Date(oktaUser.created),
       }

package/templates/agent-docs/cli.md

@@ -421,13 +421,51 @@ voltro dev apps/acme/api            # explicit path
 
 1. Reads `app.config.ts`. Bails if not `type: 'web'`.
 2. Walks `src/pages/` for queries + special files.
-3. Generates `.framework/main.tsx`, `.framework/app.tsx`, `index.html`.
+3. Generates `.framework/main.tsx`, `.framework/app.tsx`, `.framework/routeTable.ts`, `index.html`.
 4. Starts Vite with the framework's plugin chain (React, Tailwind v4, page discovery, inspect, dashboard registry).
 5. Binds to the configured port from `app.config.ts.port` (strict — fails on conflict).
 6. Watches `src/`. On save, Vite HMR fires:
-   - TSX changes → React Refresh updates the live component.
+   - A page / layout **component** change → React Fast Refresh patches the live
+     component in place; client state survives (see below).
+   - A page / layout **`loader`** (or other non-component export) change → a
+     full page reload, on purpose (see below).
    - CSS changes → swap stylesheets in place.
-   - New page file → regen `.framework/app.tsx` → reload the query tree.
+   - New page file → regen the entry files → reload the route tree.
+
+`renderMode: 'ssr'` pages compile on demand the first time each route is hit. To
+keep a burst of cold pages — several browser tabs, or a health-check sweep across
+many routes — from spiking memory, `voltro dev` compiles at most **4** of them at
+once and collapses duplicate concurrent requests for the same route into a single
+compile. Already-compiled (warm) pages are never throttled, so a hot app stays
+fully concurrent. Tune the cap with `VOLTRO_DEV_SSR_COMPILE_CONCURRENCY` (below) —
+drop it on a low-memory box, raise it on a big machine.
+
+
+### Fast Refresh: what hot-updates and what reloads
+
+Editing a **page or layout component** applies as a hot update — the React tree
+stays mounted, so form input, scroll position, open dialogs and every `useState`
+survive. Editing a **`loader`** (or `meta` / `renderMode` / any other
+non-component export of a route module) triggers a full page reload instead.
+
+That split is deliberate, not a gap. A `loader` also runs on the server: the page
+in front of you was rendered from the OLD one, and the router caches loader
+results per route + params, so hot-swapping the function would leave stale data
+on screen with nothing to signal it. A reload re-runs SSR with the new loader.
+
+The mechanism, in case you hit an edge: React Fast Refresh only accepts a module
+whose exports are all components, and a page exporting `loader` beside its
+component fails that test. `voltro dev` registers each route module's
+non-component exports with the React plugin's ignore hook, and decides the
+reload itself by comparing those exports' VALUES across the update — a function
+by its source text, anything else by its JSON form — so a JSX-only edit (which
+recreates the `loader` object) is correctly read as "unchanged".
+
+One consequence worth knowing: a page that exports a non-component value which
+changes on the same save as its JSX — a `const COLUMNS = [...]` you edit
+together with the table that renders it — reloads rather than hot-updates. Move
+that value into a sibling module (`./columns.ts`) and the page hot-updates
+again; the sibling's own edits still propagate through the page's boundary.
 
 ### The in-page devtools overlay
 
@@ -485,6 +523,7 @@ A `<DevtoolsStringsProvider strings={…}>` mounted above the overlay works too;
 | `PORT=4001` | Override the listen port (api or web). Both kinds read `PORT`, then `app.config.ts` `port:`, then the default. |
 | `VOLTRO_DASHBOARD_PORT=5180` | Override the auto-launched dashboard port (default `5179`). |
 | `VOLTRO_LOG_LEVEL=debug` | Verbose framework logs. |
+| `VOLTRO_DEV_SSR_COMPILE_CONCURRENCY=4` | Max `ssr` pages compiled on demand at once (default `4`). Lower it (`1`/`2`) on a low-memory box if a burst of first-time `ssr` page loads spikes memory; raise it on a big machine. Warm (already-compiled) pages are never throttled. |
 
 ## Multi-app dev (turbo)
 
@@ -585,6 +624,7 @@ If you must override per-process from the shell, set `PORT` inline on each one (
 
 - **Running `voltro dev` against a `voltro start` build directory.** The dev server expects source files; pointing it at `dist/` confuses it. Use `voltro start` for that.
 - **Ignoring `app.config.ts` changes.** They require a process restart (the discovery walker re-reads them at boot only). Save, watch the process die + come back up.
+- **Reading "the page reloaded" as "HMR is broken".** A page/layout component edit hot-updates and keeps client state; a `loader` edit reloads *by design* — it also runs server-side, and the rendered page came from the old one. If a pure component edit reloads, look for a non-component export on that route module that changed in the same save.
 - **Expecting a `.env` edit to hot-reload.** It can't — `process.env` is read once at boot. `voltro dev` hard-restarts the server on a `.env` change (you'll see `.env changed … — hard-restarting`); wait for the process to come back before testing, rather than assuming the new value is already live.
 - **Disabling the dashboard "to save resources".** It's a few MB of RAM + the inspect endpoints fail gracefully. Keep it on; it's the best debugging tool you have.
 
@@ -771,7 +811,7 @@ It covers both halves of the stack:
 | server | a `token` / `secret` / `password` column with no encryption | `.encrypted()` |
 | server | a notify / webhook helper called at a mutation's tail | `defineSubscriber` / `defineReaction` |
 | server | `hasMore` + `limit + 1` | `paginateById` |
-| server | `.getTime()` / `.toISOString()` mapping a row on the way out | `rowSchema(table)` as the descriptor's `output` |
+| server | `.getTime()` / `.toISOString()` mapping a row on the way out | `timestampMs` / `timestampMsOrNull` from `@voltro/database/wire` in the descriptor's `output` struct |
 | client | per-field `useState` + a submit flag | `useFormBinding` |
 | client | a table with local sort/filter state | `useDataTable` |
 | client | `FileReader` / `readAsDataURL` | `useUpload` |
@@ -842,13 +882,52 @@ voltro doctor . --json          # the complete scan: every file path, machine-re
       "use": ".one() — fails with the typed NoRowFound on zero rows AND on more than one",
       "files": ["queries/team.get.ts", "queries/user.get.ts", "…"]
     }
-  ]
+  ],
+  "spaCandidates": []
 }
 ```
 
 That is the form to hand an agent, or to pipe into a script that works the list
 file by file.
 
+### `renderMode:'spa'` candidates
+
+`voltro doctor` also flags web pages that could adopt `renderMode: 'spa'` without
+losing their server-rendered shell. A page under a layout renders that LAYOUT
+chain on the server — nav, sidebar, auth gate, via the layout's own loader — even
+when the page itself is `'spa'`. So a page whose BODY needs no SSR can skip its
+per-page SSR compile while the shell still server-renders. Like the hand-roll
+detector, this is **advisory and never blocking**.
+
+A page is listed when ALL of these hold:
+
+- it is a **page file** — not `layout.tsx` / `loading.tsx` / `error.tsx` /
+  `not-found.tsx`;
+- it exports **no `loader`** (so `'spa'` loses nothing the page contributed
+  server-side);
+- its `renderMode` is **`'ssr'` or unset/default** — not a page that already
+  opted into a non-SSR render (`'spa'` / `'static'` / `'isr'`, or any other
+  explicit mode);
+- a **`layout.tsx` sits somewhere in its directory chain** — root, an ancestor, or
+  the page's own dir. This is the load-bearing condition: only then does a layout
+  still SSR the shell. A page with no layout would, as `'spa'`, ship no server
+  HTML at all — so it is never flagged.
+
+```text
+•  renderMode:'spa' candidates (2 pages — loader-free, under a layout, currently ssr/default):
+   src/pages/dashboard/index.tsx  (/dashboard) — default renderMode
+   src/pages/admin/settings.tsx  (/admin/settings) — renderMode:'ssr'
+     → renderMode:'spa' skips this page's SSR compile while its layout shell still renders server-side — adopt it if the page BODY does not need SSR (internal/authenticated pages); keep 'ssr' if the page content needs SEO or server first-paint.
+```
+
+Adopt `'spa'` for internal or authenticated pages whose content needs no SEO or
+server first-paint; keep `'ssr'` (or the `'static'` default) when it does. There
+is deliberately **no codemod** to flip pages automatically — dropping a page
+body's server render is a per-page product decision, not a mechanically-safe
+transform. Every candidate (with its `file`, `pattern`, and `currentMode`) is
+also in `voltro doctor --json` under a `spaCandidates` array; the human view
+above caps at ten pages and points to `--json` for the rest.
+
 ## `voltro capabilities` — what the framework actually exports
 
 Asked "what does this framework export", a language model will produce a

package/templates/agent-docs/data.md

@@ -304,7 +304,7 @@ defineMutation({ name: 'notes.create', target: { table: 'notes', op: 'insert' },
 
 With that pairing, `useMutation('app', 'notes.create')` can stage an optimistic row in active `notes.list` caches without client-side cache plumbing.
 
-## `output` is the serializer — `rowSchema(table)`
+## `output` is the serializer — `timestampMs`
 
 A descriptor's `output` is not documentation of the shape. It **is** the
 serializer: it is handed to the rpc as the success schema, so a handler's result
@@ -325,32 +325,81 @@ output: Schema.Array(Schema.Struct({ createdAt: Schema.Number })),
 return rows.map((row) => ({ ...row, createdAt: row.createdAt.getTime() }))
 ```
 
-Declaring `Schema.DateFromNumber` instead makes the conversion automatic — but
-nobody wants to hand-map thirty columns to work that out per table.
-`rowSchema(table)` derives the whole struct from the table definition:
+Declaring `Schema.DateFromNumber` instead makes the conversion automatic.
+`@voltro/database/wire` ships that mapping under names you can drop straight
+into your own struct — including the nullable case, which is the one that goes
+wrong silently:
 
 ```ts
-// apps/api/queries/notes.list.query.ts
+// apps/api/queries/projects.list.query.ts
 import { defineQuery } from '@voltro/protocol'
-import { rowSchema } from '@voltro/database'
+import { timestampMs, timestampMsOrNull } from '@voltro/database/wire'
 import { Schema } from 'effect'
-import { notes } from '../database/schema'
 
-export const listNotes = defineQuery({
-  name:   'notes.list',
-  source: 'notes',
+export const listProjects = defineQuery({
+  name:   'projects.list',
+  source: 'projects',
   input:  Schema.Struct({}),
-  output: Schema.Array(rowSchema(notes)),
+  output: Schema.Array(
+    Schema.Struct({
+      id:             Schema.String,
+      name:           Schema.String,
+      jiraProjectKey: Schema.String,
+      addedAt:        timestampMs,        // Date in the handler, epoch ms on the wire
+      archivedAt:     timestampMsOrNull,  // for a nullable timestamp column
+      seenAt:         Schema.optional(timestampMs),
+    }),
+  ),
 })
 ```
 
-The executor returns rows straight from the store. No converters:
+The executor returns its rows and computes nothing at the tail:
 
 ```ts no-check
-// apps/api/queries/notes.list.query.server.ts
-export default () => database.notes.orderBy('createdAt', 'desc').limit(100)
+// apps/api/queries/projects.list.query.server.ts
+export default () => database.projects.orderBy('addedAt', 'desc').limit(100)
+```
+
+- `timestampMs` — `Date` in the handler, `number` (epoch ms) on the wire.
+- `timestampMsOrNull` — for a `.nullable()` timestamp. Use this rather than
+  converting a null by hand: `new Date(null)` is `1970-01-01`, so "never
+  archived" renders as a plausible date instead of as nothing.
+- An **optional** field is `Schema.optional(timestampMs)` — there is no third
+  export for it.
+
+This also matches the shape real handlers have. Most return a struct assembled
+by hand across several tables — `{ id, name, slug, addedAt, jiraProjectKey }` —
+where there is no single table to derive an output schema from anyway, and those
+are exactly the places the hand-written `Date → epoch` converters pile up.
+
+### Why the field schemas import from `@voltro/database/wire`
+
+`@voltro/database/wire` is a **browser-safe** entry: it contains plain
+`effect/Schema` values and imports `effect` and nothing else. That matters
+because a descriptor is loaded **value-level by the web client** — the rpc client
+needs every procedure's schema — so everything a `*.query.ts` transitively
+imports ends up in the browser bundle.
+
+The package root is not browser-safe, and neither is anything that reaches a
+**table value**. Importing `../database/schema` to get at `notes` imports
+`@voltro/database` itself, which pulls the store, the query builder and the SQL
+driver into the client graph. `voltro dev` refuses to boot in that case and
+prints the import chain:
+
+```
+browser-safety violation — the generated rpcGroup pulls a SERVER-ONLY module
+into the client bundle.
+  import chain:
+      → rpcGroup.generated.ts
+      → ./queries/notes.list.query
+      → ../database/schema
+      → @voltro/database
 ```
 
+So a descriptor's `output` is always written as your own `Schema.Struct` with
+field schemas — never derived from a table. Deriving from a table is a
+server-side operation; see below.
+
 ### The Encoded / Type split
 
 That split is the whole point — the handler works in domain types, the wire
@@ -369,79 +418,50 @@ carries something JSON can represent:
 number rounds silently past 2^53, and a value that is quietly wrong is worse than
 one that is rejected.
 
-`json()` / `vector()` / `raw()` map to `Schema.Unknown` rather than a guess.
-These are shapes the column declaration does not pin down, and a schema that
-guesses **wrong** rejects valid rows at the wire boundary — reporting the failure
-far from the column responsible. Loose beats wrong here; declare the precise
-shape yourself when you want one.
-
 A `.nullable()` column wraps its mapped type, so a null timestamp round-trips as
 `null` rather than becoming epoch 0 (which would render as a plausible
 `1970-01-01` instead of "never").
 
-### Computed outputs — `timestampMs`
+### Row codecs for server-side code — `rowSchema`, `columnSchema`
 
-`rowSchema(table)` only helps a handler that returns a **raw, full table row**.
-Most handlers don't: they return a struct assembled by hand from several tables
-— `{ id, name, slug, addedAt, jiraProjectKey }` — where there is no single table
-to derive from. That is exactly where the hand-written `Date → epoch` converters
-pile up.
+`rowSchema(table)` builds the whole struct from a table definition, and
+`columnSchema(def)` maps one column. Both take the table as a **value**, so by
+the section above they can only be used in code that already runs on the server
+alone — a `*.query.server.ts` / `*.mutation.server.ts` executor, a `*.seed.ts`,
+a startup or job module, a maintenance script, a test. **Not** a descriptor's
+`output`.
 
-For those, use the field-level exports directly in your own `Schema.Struct`:
+What they are for is encoding or decoding table rows outside the rpc path, where
+no `output` schema is doing it for you: writing rows to a file export or a queue
+payload, or validating seed / import data against the actual table shape before
+it is written.
 
-```ts
-// apps/api/queries/projects.list.query.ts
-import { defineQuery } from '@voltro/protocol'
-import { timestampMs, timestampMsOrNull } from '@voltro/database'
+```ts no-check
+// apps/api/database/notes.seed.ts — server-only, so the table value is fine
+import { rowSchema } from '@voltro/database'
 import { Schema } from 'effect'
+import { notes } from './schema'
 
-export const listProjects = defineQuery({
-  name:   'projects.list',
-  source: 'projects',
-  input:  Schema.Struct({}),
-  output: Schema.Array(
-    Schema.Struct({
-      id:             Schema.String,
-      name:           Schema.String,
-      jiraProjectKey: Schema.String,
-      addedAt:        timestampMs,        // Date in the handler, epoch ms on the wire
-      archivedAt:     timestampMsOrNull,  // for a nullable timestamp column
-      seenAt:         Schema.optional(timestampMs),
-    }),
-  ),
-})
+const rows = Schema.decodeUnknownSync(Schema.Array(rowSchema(notes)))(
+  JSON.parse(await readFile('seed/notes.json', 'utf8')),
+)
 ```
 
-Same semantics as a `timestamp()` column inside `rowSchema` — literally the same
-schema, which `columnSchema` reads from, so the two can never drift into
-different wire representations.
-
-- `timestampMs` — `Date` in the handler, `number` (epoch ms) on the wire.
-- `timestampMsOrNull` — for a `.nullable()` timestamp. Use this rather than
-  converting a null by hand: `new Date(null)` is `1970-01-01`, so "never
-  archived" renders as a plausible date instead of as nothing.
-- An **optional** field is `Schema.optional(timestampMs)` — there is no third
-  export for it.
-
-### Keeping a column off the wire — `omit`
-
-```ts
-import { rowSchema } from '@voltro/database'
-import { users } from '../database/schema'
+`omit` drops columns from the schema — the way to keep an internal column out of
+an export:
 
+```ts no-check
 rowSchema(users, { omit: ['passwordHash'] })
 ```
 
-`omit` is a **convenience, not a security boundary**. The column is simply absent
-from *this* schema; a handler that returns the same row under a different schema
-still sends it. For a real boundary, see
+It is a **convenience, not a security boundary**. The column is simply absent
+from *this* schema; code that serializes the same row under a different schema
+still emits it. For a real boundary, see
 [`.encrypted()` and column sensitivity](/docs/database/sensitivity).
 
-### One column at a time — `columnSchema`
-
-`columnSchema` maps a single column, and it takes a column **definition** — what
-`table.fields` holds — not the builder that `text()` or `timestamp()` returns
-(a builder's definition is private, so it cannot be read from outside):
+`columnSchema` takes a column **definition** — what `table.fields` holds — not
+the builder that `text()` or `timestamp()` returns (a builder's definition is
+private, so it cannot be read from outside):
 
 ```ts no-check
 import { columnSchema } from '@voltro/database'
@@ -450,6 +470,10 @@ columnSchema(notes.fields.createdAt)   // ✅ a definition, from table.fields
 columnSchema(timestamp())              // ❌ a builder — not readable
 ```
 
+The mapping is single-sourced: `columnSchema` returns the very same
+`timestampMs` value for a `timestamp()` column, so a derived row schema and a
+hand-written descriptor struct can never disagree about the wire shape.
+
 ## What gets sent on the wire
 
 Queries are streaming RPCs whose elements are **subscription events**: an initial `snapshot` followed by `delta`s. See [Wire protocol](/docs/data/wire-protocol#subscription-events-snapshot-delta) for the envelope shape. For plain element streams, use [Streams](/docs/data/streams).

package/templates/agent-docs/database/schema.md

@@ -423,7 +423,7 @@ the framework ships richer types for specific use cases:
 - **`timestamp` without `tz`.** Use `timestamp()` which is `timestamptz`.
 - **Storing JSON blobs as `text`.** Use `json<T>()` for type-safety + JSONB performance.
 - **`references('table')`.** The constructor is `reference(() => table)` — singular, thunk-arg.
-- **Declaring a `timestamp()` column as `Schema.Number` in a descriptor's `output`.** That describes the *wire* type, not the domain type, so the schema has nothing left to convert and the handler ends up doing it by hand. Derive the row schema instead — [`rowSchema(table)`](/docs/data/queries#output-is-the-serializer-rowschema-table) for a whole row, or [`timestampMs` / `timestampMsOrNull`](/docs/data/queries#computed-outputs-timestampms) for one field of a hand-written struct.
+- **Declaring a `timestamp()` column as `Schema.Number` in a descriptor's `output`.** That describes the *wire* type, not the domain type, so the schema has nothing left to convert and the handler ends up doing it by hand. Declare the field schema instead — [`timestampMs` / `timestampMsOrNull`](/docs/data/queries#output-is-the-serializer-timestampms) from `@voltro/database/wire`. Do **not** reach for `rowSchema(table)` here: a descriptor cannot import a table value without dragging `@voltro/database` into the browser bundle, and the boot aborts. `rowSchema` is a [server-side row codec](/docs/data/queries#row-codecs-for-server-side-code-rowschema-columnschema).
 
 
 

package/templates/agent-docs/reference.md

@@ -630,6 +630,26 @@ Available in:
 
 Returns `null` on pages without a `loader`. The generic narrows the type.
 
+Precisely, it returns `LoaderData<T>`. For every ordinary loader that IS `T`. For
+a loader that returned `defer()`, `LoaderData<T>` flattens the two buckets into
+one object — eager fields as values, deferred fields as `Promise<T>` — so the
+compiler tells you which fields have to be rendered through
+[`<Await>`](/docs/routing/loaders-and-meta#deferring-slow-data-defer--await):
+
+```tsx
+export const loader = async ({ query }) => defer(
+  { user: await query('users.me') },
+  { report: query('reports.quarterly') },
+)
+
+// user: User            report: Promise<Report>
+const { user, report } = useLoaderData<Awaited<ReturnType<typeof loader>>>()
+```
+
+If you wrap this hook in your own generic helper, propagate the mapped type
+(`<D,>(): LoaderData<D> => useLoaderData<D>()`) — `LoaderData<D>` is not
+assignable to a bare type parameter `D`.
+
 See [Loaders & meta](/docs/routing/loaders-and-meta) for the server-side counterpart.
 
 ## Compositions