@voltro/cli 0.40.0 → 0.42.0

package/dist/{webhooksCommand-DubZWNOx.js → webhooksCommand-D7ZpH7w0.js}

@@ -222,7 +222,7 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev-D8JSKlBM.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-DuqBJC7g.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
 	return r((await n(await t(e))).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -622,6 +622,12 @@
         "title": "a rejected credential answers `Unauthenticated`, widening three guard results",
         "kind": "manual"
       },
+      {
+        "version": "0.41.0",
+        "id": "0.41.0/01_middleware-defines-where-it-runs",
+        "title": "`middleware.ts` exports `defineMiddleware(...)` and can say where it runs",
+        "kind": "transform"
+      },
       {
         "version": "0.5.0",
         "id": "0.5.0/01_one-terminal-exactly-one",
@@ -709,22 +715,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.40.0",
-    "@voltro/cache": "0.40.0",
-    "@voltro/data-transfer": "0.40.0",
-    "@voltro/database": "0.40.0",
-    "@voltro/env": "0.40.0",
-    "@voltro/kv": "0.40.0",
-    "@voltro/logger": "0.40.0",
-    "@voltro/plugin-auth": "0.40.0",
-    "@voltro/plugin-broadcast": "0.40.0",
-    "@voltro/plugin-mail": "0.40.0",
-    "@voltro/plugin-storage": "0.40.0",
-    "@voltro/plugin-webhooks": "0.40.0",
-    "@voltro/protocol": "0.40.0",
-    "@voltro/runtime": "0.40.0",
-    "@voltro/serverless": "0.40.0",
-    "@voltro/workflow": "0.40.0",
+    "@voltro/ai": "0.42.0",
+    "@voltro/cache": "0.42.0",
+    "@voltro/data-transfer": "0.42.0",
+    "@voltro/database": "0.42.0",
+    "@voltro/env": "0.42.0",
+    "@voltro/kv": "0.42.0",
+    "@voltro/logger": "0.42.0",
+    "@voltro/plugin-auth": "0.42.0",
+    "@voltro/plugin-broadcast": "0.42.0",
+    "@voltro/plugin-mail": "0.42.0",
+    "@voltro/plugin-storage": "0.42.0",
+    "@voltro/plugin-webhooks": "0.42.0",
+    "@voltro/protocol": "0.42.0",
+    "@voltro/runtime": "0.42.0",
+    "@voltro/serverless": "0.42.0",
+    "@voltro/workflow": "0.42.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -707,7 +707,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.40.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.42.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.40.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.42.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_manifest.json

@@ -242,7 +242,7 @@
       "group": null,
       "description": "Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework.",
       "path": "agent-docs/routing.md",
-      "files": 8
+      "files": 9
     },
     {
       "id": "scheduling",

package/templates/agent-docs/cli.md

@@ -2525,6 +2525,7 @@ Both stream — a table or a blob is never fully held in memory — and both sur
 voltro data export ./backup-2026-07-01
 voltro data export ./out --tenant org_abc            # one tenant + its FK closure
 voltro data export ./out --tables users,posts         # an explicit set
+voltro data export ./out --exclude cluster_locks       # everything else
 voltro data export ./out --assets                      # include stored blobs
 voltro data export ./out --compression gzip            # zstd (default) | gzip | none
 voltro data export ./out --consistency snapshot        # point-in-time (see below)
@@ -2596,6 +2597,11 @@ Rows are written as newline-delimited JSON — streamable, resumable by line, an
 | *(none)* | Every table (the default). |
 | `--tenant <id>` | Every `tenant()`-scoped table filtered to that tenant, **plus** the FK closure in BOTH directions: (1) the transitive **FK-parent** closure of those rows — closure-pulled shared tables (a global `users` / reference table) are **row-subset to the ids the tenant's rows actually reference**, never exported in full; and (2) the **child** closure — rows that *reference* the tenant's rows (the comments on the tenant's projects) come along too, each scoped to the ids that actually point into the tenant set. The child walk is anchored on the `tenant()` tables, so a row that references **only a shared parent** (a global `users` another tenant also references) is **not** pulled — that would be a cross-tenant leak. A `--tenant` bundle therefore carries the tenant's parents AND children and **no other tenant's rows** — that's what makes it safe as a GDPR / per-tenant takeout. |
 | `--tables a,b` | An explicit set (you own referential integrity; the importer's deferred-FK resolution covers load-order dangles, see below). |
+| `--exclude a,b` | Everything EXCEPT these, expanded against the live table list. Direct target only. Cannot be combined with `--tables` or `--tenant`; a name that does not exist is refused, because an exclusion that excludes nothing leaves the run looking like it worked. |
+
+**Every table needs a single-column primary key.** The export is keyset-paginated, so it orders by one column and resumes from the last value on the next page. That column comes from the real primary key — a declared `id()` where there is one, otherwise the table's actual PK, whatever it is called.
+
+A table with a **composite** primary key, or none at all, is **refused by name** rather than exported. Ordering by one column of a composite key splits equal values across page boundaries, which drops or duplicates rows into a bundle that reports success — and a short backup is discovered at the restore. Leave such a table out with `--exclude`.
 
 Tenant-scope details:
 
@@ -2619,8 +2625,42 @@ voltro data import --target api --api-url https://api.example.com --token $SECRE
 voltro data import ./out --assets            # also restore blobs
 voltro data import ./out --no-verify         # skip checksum/row-count verification
 voltro data import ./out --force             # import despite schema drift AND cross-dialect warnings
+voltro data import ./out --tables users,teams   # load only these tables out of the bundle
+voltro data import ./out --dry-run              # report what would move; write nothing
+```
+
+**`--dry-run` and `--tables` work on BOTH targets**, including `--target api`. On the api
+path they travel as `x-import-dry-run` / `x-import-tables`, and the response echoes
+`{ "dryRun": true, "wrote": false }` so a preview is never mistaken for a write.
+
+A dry run reaches every verdict a real run reaches — schema fit, cross-dialect portability,
+mode legality, the table selection — and stops at the first line that would write. It does
+NOT read per-table checksums (those stream during the load) and cannot see a conflict that
+depends on the target's current rows; the command says both out loud, because a preview
+over-read is worse than no preview.
+
+`--tables` names tables the BUNDLE carries. A name it does not carry is refused, listing
+what it does — a silently-ignored table name is how a run scoped to one table writes the
+whole bundle.
+
+### A flag this command does not read is an ERROR
+
+Every `voltro data` subcommand declares the flags it reads, per target, and refuses anything
+else instead of ignoring it:
+
+```text
+✗ voltro data import: --no-verify is not read with --target api (it is a --target direct
+  flag). Remove it, or change --target.
+✗ voltro data export: --mode is not a `export` flag (it belongs to `voltro data import`).
+✗ voltro data import: unknown flag --drynrun. Run `voltro data --help` for the flags this
+  command reads.
 ```
 
+The refusal happens before anything boots, so a mistyped flag costs you a message rather
+than a run. On a command whose job is moving data into a live system, silence is the wrong
+default: an accepted-and-ignored flag turns a typo into a no-op whose only evidence of
+working is that nothing complained.
+
 Import is **integrity-checked** (each table's checksum + row count verified as it decodes; each asset re-hashed against its content address), applies tables in **FK-parent-first order**, and a resumed run skips already-applied tables via the ledger.
 
 ### Postgres targets bulk-load via COPY
@@ -2645,16 +2685,31 @@ identical, only the speed differs.
 
 ### Schema-drift pre-flight
 
-Every bundle records the **schema fingerprint** of the source it was exported from (a stable hash of the schema shape — the same fingerprint prod boot uses to detect drift). Before touching the target, `import` **recomputes the target app's fingerprint the same way** and compares it to the bundle's. On a mismatch it **refuses, fail-closed, before any row lands** — a drifted target (a missing column, a renamed table) would otherwise fail mid-load with a raw database error after some rows already committed:
+The question the pre-flight asks is **"will the rows this bundle carries fit this target?"** — not "are these two schemas identical". It compares the **intersection**: for every table the bundle carries, the columns and types must exist on the target, and a column the target REQUIRES (NOT NULL, no default) that the bundle carries no value for is refused too. On a problem it **refuses, fail-closed, before any row lands**:
 
 ```text
-✗ schema drift: the target schema (fingerprint d6ba94b0…) differs from the bundle's
-  source (f67942f6…). Refusing before the table phase.
-    items.extra: in the target, not in the bundle
-  Re-export against the current schema, or pass --force to import anyway.
+✗ schema drift: refusing before the table phase.
+    table 'items' is in the bundle but MISSING from the target — its rows have nowhere to go
+    orders.total: type 'integer' (bundle) vs 'text' (target)
+    users.region: the target requires it (NOT NULL, no default) and the bundle carries no
+      value — every row of this table would fail
 ```
 
-The error names the drift — the tables/columns that moved (down to per-column granularity for the tables the bundle carries) — so you can see exactly what changed. **`--force`** downgrades the refusal to a **loud warning** and proceeds (the operator has accepted that the shapes differ). Over the `--target api` path the same check runs **on the instance** against its declared schema and returns **`409` schema drift** with the fingerprints + diff; `--force` sends `x-import-force: 1` to override.
+Every line is something that would break the load. Tables and columns the target has and
+the bundle does not are **untouched by definition** and are never reported — that is the
+normal shape of any cross-environment seed, and refusing on it would make `--force` the
+routine way to run an import and take the protection with it.
+
+Both fingerprints are still reported (they are what you paste when asking for help), and an
+identical pair is a fast path that skips the comparison. But **differing fingerprints are
+not on their own a refusal**: a bundle's fingerprint covers its SOURCE schema regardless of
+export scope, so a one-table export out of a 75-table database carries the 75-table
+fingerprint.
+
+**`--force`** downgrades the refusal to a **loud warning** and proceeds. Over the
+`--target api` path the same check runs **on the instance** against its declared schema and
+returns **`409` schema drift** with the fingerprints + diff; `--force` sends
+`x-import-force: 1` to override.
 
 The pre-flight only runs when the importer has a target schema (the CLI introspects it; the API endpoint uses the instance's declared schema). Importing into a fresh/empty database with no comparable schema simply skips the check.
 
@@ -2751,6 +2806,17 @@ Both export and import checkpoint into a small **`.ledger.json`** and can be re-
 
 Net: interrupt an export or import at any point — network drop, `Ctrl-C`, OOM-killed pod — and re-running the same command finishes the job without duplicating work or corrupting the target.
 
+**A re-run of a COMPLETED import writes nothing, and says so.** The ledger lives in the bundle directory, so re-importing a bundle whose tables are all recorded skips every one of them. That is resume working — but the returned report counts the BUNDLE's rows either way, so `import complete … 10593 rows` would otherwise print over a target you had just truncated. The import warns instead:
+
+```text
+⚠ resume: 5 of 5 table(s) were already applied by an earlier run of THIS bundle
+  directory, so this run wrote NO rows for them — that is every table in the
+  bundle, so nothing was written at all. Tables: tenants, teams, projects,
+  actors, auditLogs. Delete ./out/.import.ledger.json to force a full re-import.
+```
+
+The `--target api` path is unaffected: the instance unpacks each upload into a fresh temp directory, so it never carries a ledger between runs.
+
 ### Progress & observability
 
 A multi-hour job is not a black box. Both pipelines signal per **table** — never per row, so the reporting never slows the hot path:
@@ -2921,6 +2987,13 @@ The opt-out is `onUnclassified: 'keep'` (or `'null'`), which makes masking **fai
 unclassified columns. Discouraged — it defeats the guarantee; prefer classifying the column.
 See [why fail-closed](/docs/database/sensitivity#why-fail-closed).
 
+**A policy this build cannot carry out is refused too**, before a row is read. An action of a
+shape the applier does not understand — a typo like `{ action: 'fake', kind: 'email' }` where
+the shape is `{ fake: 'email' }` — used to fall through to "copy the value", so the export
+succeeded and shipped the raw column while the audit line counted it as masked. It is now a
+`MaskingError` with `invalidActions`, reported separately from `unclassified` because the two
+have different fixes: one needs a classification, the other needs the policy corrected.
+
 ## `--dry-run` — preview without writing
 
 Preview a masking export **without writing a bundle** — the trust surface before real data

package/templates/agent-docs/data.md

@@ -4767,6 +4767,7 @@ declared it anyway, that is harmless — the union is the same either way.
 | `ServerOnlyColumnWrite` | `@voltro/runtime` | A `crud.create` / `crud.update` input tried to set a [`.serverOnly()`](/docs/database/sensitivity) column — `{ table, columns }`. |
 | `StoreOperationFailed` | `@voltro/runtime` | The underlying store operation failed (transient). |
 | `TableValidationFailed` | `@voltro/runtime` | A `table().validate(Schema)` row check rejected the write. |
+| `ConstraintViolation` | `@voltro/runtime` | The database refused the write on a foreign key / unique / NOT NULL / CHECK — `{ kind, table, operation, constraint?, column? }`. See below. |
 | `CacheError` | `@voltro/cache` | A cache backend op failed — `{ operation, key, cause }`. |
 | `RateLimited` | `@voltro/plugin-ratelimit` | The limiter rejected the call — `{ limit, retryAfterMs, resetAtMs }`. |
 | `TenantMismatch` | `@voltro/plugin-multitenancy` | `assertOwnTenant(input.tenantId, subject)` rejected a cross-tenant write. |
@@ -4775,6 +4776,38 @@ Each plugin that ships an error (`RateLimited`, `EntitlementExceeded`, `StorageE
 
 All carry `_tag` + typed payloads, all narrow correctly on the client.
 
+### When the database refuses the write
+
+An integrity rule your schema declares — a `reference()`, a `.unique()`, a non-nullable column, a `.check()` — is enforced by the database, not by the handler. When it fires you get a `ConstraintViolation`:
+
+```ts
+{ _tag: 'ConstraintViolation',
+  kind: 'foreignKey', table: 'tasks', operation: 'insert',
+  constraint: 'tasks_laneId_fkey' }
+```
+
+`kind` is the field to branch on, and it is the one field every dialect can always fill:
+
+| `kind` | Means | The caller's fix |
+|---|---|---|
+| `foreignKey` | the row you referenced does not exist | point at a real row |
+| `foreignKeyInUse` | this row may not go — others still reference it | delete the children first, or don't delete |
+| `unique` | a row with this value already exists | pick another value |
+| `notNull` | the column requires a value | send one |
+| `check` | the row does not satisfy a declared `.check()` | fix the value |
+
+`constraint` and `column` are filled where the dialect names them. sqlite reports a foreign-key failure as the bare sentence `FOREIGN KEY constraint failed` — no name, no column — so `constraint` is absent there and the direction is inferred from the operation.
+
+**It carries names, never the driver's sentence, and that is deliberate.** The message the database produces contains row DATA on most engines: postgres attaches `Failing row contains (…)` — the *complete* row, every column, [`.sensitive()`](/docs/database/sensitivity) ones included — to a not-null and a check violation; mysql and mssql echo the duplicate value on a unique violation. A constraint name is schema, the same class of fact `TableValidationFailed.table` already puts on the wire. A row is data, and the caller who provoked the error is not automatically entitled to it. The full driver text is in the server log, with the trace id.
+
+Declare it in `error:` to pattern-match it:
+
+```ts
+error: Schema.Union(ConstraintViolation, MyDomainError),
+```
+
+If you do not, it still reaches the client — collapsed to `InternalError` like any undeclared error, but carrying its own sentence (`ConstraintViolation: foreign key tasks_laneId_fkey on tasks: the referenced row does not exist`) rather than the opaque `Failed to execute statement` a raw `SqlError` produces.
+
 ## Loader errors
 
 Loaders run in the web app — they receive `{ params, query, headers, signal }`, NOT a server `ctx` with `.store`. A loader reaches the backend through `query(...)` (the `POST /rpc` path, server-side only). It short-circuits with the branded control-flow signals `NotFoundError` / `RedirectError`:

package/templates/agent-docs/plugins/governance.md

@@ -232,6 +232,14 @@ const token = decryptField(row.token)   // a non-ciphertext value returns unchan
 
 `decryptField` returns a non-`enc:v1:…` value **unchanged**, so you can switch a raw-SQL path to encryption while pre-existing plaintext rows keep working until they're re-written. Both throw a clear error if no cipher is registered (enable `fieldEncryption`). Encryption stops being all-or-nothing tied to going through `ctx.store`.
 
+**One encoding, both directions.** These helpers and the store middleware write the same thing, so a value written by `encryptField` reads through `ctx.store` and vice versa. That was not always true: the store encoded JSON and the helpers did not, both under the same `enc:v1:` envelope, and a value written by one and read by the other either threw blaming the KEY — while the key was fine — or came back with the JSON quotes still on it and raised nothing.
+
+**Rows written under the OLD encoding still read — nothing has to be rewritten.** Both forms are resolved on read, deterministically: after decrypting, a value that does not parse as JSON is the raw form, one that parses to a string is the JSON form, and one that parses to a non-string is decided by the column's declared type (a text column cannot hold a number, so `12345` is a raw string that parsed by accident). This matters because the old form is already on staging and production disks, and a fix that needs the data rewritten before the app works is an outage with a migration attached.
+
+Normalising is optional hygiene, and `voltro db encrypt-column` does it: it re-encodes rows in the old form as it goes and reports them separately from the ones it encrypts. It skips anything ambiguous and anything it cannot decrypt.
+
+**Backups are unaffected either way.** `voltro data export` reads through the raw store, so an encrypted column travels as ciphertext in whichever encoding it holds, and comes back unchanged.
+
 ## Dashboard panel
 
 Both dashboards ship a **Governance** panel (api apps): retention-policy status + field-encryption state + last-sweep results (with a **Run sweep now** button), a **GDPR runner** (enter a subject id → Export / Erase delete / Erase anonymize), a consent-ledger lookup, and the erasure log. Write-actions gate on the `canRunGovernance` capability. Backed by `/_voltro/inspect/plugins/governance/{status,erasures,consent,export,erase,sweep}`.

package/templates/agent-docs/routing.md

@@ -1160,35 +1160,12 @@ and `preload` on the page fails.
 You cannot fix that in a loader. `ctx.query` and every `preload` entry are bound
 from ONE cookie string **before any loader runs**, so a layout loader that
 renews the session cannot reach them. `middleware.ts` at the web app root runs
-earlier than both:
+earlier than both, says which routes it covers, and writes the rotated cookie
+back so this render and the browser agree.
 
-```ts
-// middleware.ts — server-only. NOT app.config.ts, which is imported into the
-// client bundle whenever an api declares `authHeaders`.
-export default async (req) => {
-  const fresh = await refreshSession(req.cookies['sb-session'])
-  if (!fresh) return
-  return {
-    headers:    { authorization: `Bearer ${fresh.accessToken}` },
-    setCookies: [{ name: 'sb-session', value: fresh.cookie, maxAge: 3600 }],
-  }
-}
-```
-
-**Write the cookie back.** An IdP that rotates refresh tokens (Supabase does, and
-detects reuse) will invalidate the session if you renew server-side and leave the
-browser holding the consumed one. `setCookies` is not an optimisation.
-
-**It cannot redirect or refuse a request**, deliberately: authorization belongs
-on the api, which is the only thing that sees the data, and a web-side hook that
-could refuse would be a second authorization layer beside the real one. For a
-login redirect, throw `RedirectError` from the loader.
-
-Headers you return are merged over the request's, and only auth-shaped ones
-(`authorization`, `x-tenant`, `x-voltro-*`) are forwarded to the api. Cookies
-default to `HttpOnly`, `Path=/`, `SameSite=lax`. The file is loaded once per
-boot; if it throws, the request fails rather than rendering with the credential
-you asked to replace.
+See [Middleware](/docs/routing/middleware) for the full contract: `match`
+(`under` / `routes` / `except` / `assets`), the one-middleware-per-route rule,
+and what it deliberately cannot do.
 
 ## Errors from loaders
 
@@ -2002,3 +1979,139 @@ matches (workspace link and npm install alike).
 How to verify: `curl -sS http://localhost:<port>/@fs/<abs>/src/globals.css | grep
 animate-` should list every kit animation utility you use. If a class is missing,
 the `@source` is misconfigured.
+
+
+
+---
+
+<!-- source: en/routing/middleware.md -->
+## Middleware
+
+_'`middleware.ts` — the web app''s one server-only hook: renew a credential before the SSR render uses it, and say which routes it runs on.'_
+
+`middleware.ts` at the web app root runs **before** a server render binds its data. It exists for one job — renewing a credential — and it is deliberately narrow about everything else.
+
+```ts
+// middleware.ts — server-only. NOT app.config.ts, which is imported into the
+// client bundle whenever an api declares `authHeaders`.
+import { defineMiddleware } from '@voltro/web/middleware'
+
+export const session = defineMiddleware({
+  match: { under: '/app' },
+  run: async (req) => {
+    const fresh = await refreshSession(req.cookies['sb-session'])
+    if (!fresh) return
+    return {
+      headers:    { authorization: `Bearer ${fresh.accessToken}` },
+      setCookies: [{ name: 'sb-session', value: fresh.cookie, maxAge: 3600 }],
+    }
+  },
+})
+```
+
+## The problem it solves
+
+A cookie older than the IdP's token lifetime — practically every first page view of the day for a 1-hour token — makes the api resolve the caller to anonymous, and every loader and `preload` on the page fails.
+
+**You cannot fix that in a loader.** `ctx.query` and every `preload` entry are bound from ONE cookie string *before any loader runs*, so a layout loader that renews the session cannot reach them. The middleware runs earlier than both.
+
+## What it receives, and what it can return
+
+`run` gets a read-only request and returns `{ headers?, setCookies? }` — or nothing, to change nothing.
+
+| Field | |
+|---|---|
+| `req.pathname` | matched path, no query string |
+| `req.search` | raw query string including `?`, or `''` |
+| `req.headers` | incoming headers, lowercased keys |
+| `req.cookies` | the parsed `Cookie` header |
+| `req.route` | the matched **route pattern** (`/notes/[id]`), or `undefined` for a non-page request |
+
+Returned headers are merged over the request's, and only auth-shaped names (`authorization`, `x-tenant`, `x-voltro-*`) are forwarded to the api — a returned `host` would otherwise produce failures that look like anything but a header copy. Cookies default to `HttpOnly`, `Path=/`, `SameSite=lax`, and several are written as separate header lines, never comma-joined (a cookie's `Expires` contains a comma).
+
+**Write the cookie back.** An IdP that rotates refresh tokens (Supabase does, and detects reuse) will invalidate the session if you renew server-side and leave the browser holding the consumed one. `setCookies` is not an optimisation.
+
+**A cookie your IdP SDK reads in the browser needs `httpOnly: false`.** The default is `HttpOnly` — right for a cookie only the server touches, and wrong for this one. Supabase's `createBrowserClient` reads the session from `document.cookie`, so a forgotten `false` hands the browser a session it cannot see: the SSR render is perfect, every server-side check passes, and the user is signed out at the first client-side call. `voltro dev` warns once per cookie when a session-shaped name is written with no `httpOnly` decision; setting it explicitly either way silences that.
+
+## What you return applies to THIS render
+
+The middleware produces one view of the request that everything downstream reads:
+
+| Reader | sees |
+|---|---|
+| `ctx.query` and every `preload` | your headers, and the renewed cookie |
+| `ctx.headers` in a loader | your headers |
+| `useServerRequest().cookies` / `.headers` | the jar after `setCookies` was applied |
+| locale resolution (`cookie`, `accept-language`) | the same jar |
+
+So a hook that renews **only** via `setCookies` — no `headers` at all, which is the normal shape for a cookie-session IdP — still authenticates this render's rpc calls: the `Cookie` header is rebuilt from the updated jar. A `maxAge` of `0` deletes, so a hook that signs someone out renders them signed out. If you return an explicit `cookie` header yourself, yours wins.
+
+## `match` — where it runs
+
+Without a `match`, a middleware runs on every server-rendered route, including your marketing pages. That is an IdP round trip on the page least able to afford one.
+
+```ts
+import { defineMiddleware } from '@voltro/web/middleware'
+
+export const session = defineMiddleware({
+  match: { under: '/app', except: ['/app/public'] },
+  run: async (req) => { /* … */ },
+})
+
+export const adminTenant = defineMiddleware({
+  match: { under: '/admin' },
+  run: async () => ({ headers: { 'x-tenant': 'ops' } }),
+})
+```
+
+| Field | Means |
+|---|---|
+| `under` | a route subtree — `/app` covers `/app` and everything below it, on segment boundaries (never `/application`). A string or an array. |
+| `routes` | exact route patterns, as the router spells them: `/notes/[id]`. |
+| `except` | subtrees or patterns to subtract from the two above. |
+| `assets` | also run on requests that matched no page. Off by default. |
+
+**Every path here is a ROUTE path, checked against your routes at boot.** A `under: '/ap'` that covers nothing refuses the boot; it does not become a middleware that quietly never fires. An `except` that excludes nothing is reported the same way — it reads as an active rule and is not.
+
+That is the deliberate difference from the URL-pattern shape you may have met elsewhere:
+
+```ts
+matcher: '/((?!api|_next/static|_next/image|favicon.ico).*)'
+```
+
+You have to know your own asset layout to write that, it breaks when a build tool renames a directory, and it breaks silently. Voltro's hook runs **after** route matching — framework URLs, anything with a file extension, and anything matching no page are already gone — so an app has never had to know an asset path.
+
+## One middleware per route
+
+**At most one middleware may match a given route.** Two hooks writing one `authorization` header have no defensible winner, so an overlap refuses the boot and names both plus the route:
+
+```
+✗ middleware.ts: 1 problem(s)
+
+  • `session` and `admin` both match /app/admin. A route may have at most one
+    middleware — two hooks writing one `authorization` header have no defined
+    winner. Narrow one with `except`, or fold them into one middleware that
+    branches on `req.route`.
+```
+
+Declaration order is not a semantic, "most specific wins" would silently drop the broader hook — for a session renewal, that means a subtree stops renewing with nothing red anywhere — and merging needs a per-field rule nobody remembers.
+
+`voltro doctor` reports overlaps and dead matchers before you deploy, and says so out loud when a matcher is built from a variable and it could not read it statically.
+
+## Reaching non-page requests
+
+`assets: true` extends a middleware to requests that matched no page — your files, and paths the router does not serve. It is opt-in and narrow on purpose: there is no render and no rpc call on such a request, so `headers` has nothing to act on and **only `setCookies` takes effect**. The framework's own surface (`/@vite/*`, `/_voltro/*`) is never reachable.
+
+## What it deliberately cannot do
+
+**It cannot redirect or refuse a request.** Authorization belongs on the api, which is the only thing that sees the data; a web-side hook that could refuse would be a second authorization layer beside the real one, and a hook that cannot refuse also cannot be mistaken for a guard. For a login redirect, throw `RedirectError` from the loader.
+
+It also cannot live in `app.config.ts`: that file is imported into the client bundle whenever an api declares `authHeaders`, and a hook that renews a session reaches for an IdP SDK by definition.
+
+## Lifecycle
+
+The file is loaded **once per boot** — it is app code with a stable identity, and re-importing per request would rebuild whatever an IdP client constructs at module level. A failure to import is fatal rather than degrading to "the app has none", and a middleware that throws fails the request: the render must not proceed on the credential the hook was told to replace.
+
+**`voltro dev` therefore RESTARTS when you edit it**, the same way a hard-restart field in `app.config.ts` does, and says so in the log. Once-per-boot is documented, and it is still the rule most easily forgotten — everything else in a dev server hot-reloads, so a sabotaged middleware that changes nothing reads as a hook that was never wired.
+
+It runs on both SSR boot paths, `voltro dev` and `voltro start`, with the cookies written on every response arm.

package/templates/agent-docs/security.md

@@ -51,6 +51,30 @@ job with no diff to review. Full detail — including how plugin routes are
 covered per-request in the dispatch spine rather than by the boot gate — in
 [Authorization](/docs/authentication/authorization).
 
+### A decode failure on a guarded procedure is NOT a guard verdict
+
+The payload is decoded before the handler runs, so a guard on a procedure with a
+malformed payload never gets the chance to refuse. Calling one with an incomplete
+payload therefore answers with a decode error, not a `ScopeError` — and reading
+that as "the guard is not applied" is the wrong conclusion in the dangerous
+direction.
+
+A consumer reached exactly that conclusion while auditing a guard, and flipped
+back the moment they sent a complete payload. So a guarded procedure says it in
+the failure:
+
+```
+workAreas.create input (guarded — the guard did NOT run: the payload failed to
+decode first, so this says nothing about access)
+└─ ["type"] └─ is missing
+```
+
+**Measure a guard with a VALID payload.** The ordering itself is not fixable at
+that seam — the request never reaches the handler or the auth middleware, so
+"evaluate guards first" means replacing the protocol layer rather than annotating
+a schema. An `openAccess:` declaration is not an enforced guard and gets no such
+sentence.
+
 ## Outbound HTTP is SSRF-guarded by default
 
 The `HttpClient` your handlers `yield*` refuses internal targets: