@voltro/cli 0.39.1 → 0.41.0

package/dist/{webhooksCommand-EccPZQZ4.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-CjJAasDs.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.39.1",
+  "version": "0.41.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -610,6 +610,24 @@
         "title": "@voltro/plugin-rbac/web removed — the UI gate lives in @voltro/client",
         "kind": "transform"
       },
+      {
+        "version": "0.40.0",
+        "id": "0.40.0/01_cold-start-failure-is-its-own-state",
+        "title": "a failed cold start is `failed: true`, not `loading: true`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.40.0",
+        "id": "0.40.0/02_rejected-credential-widens-guard-results",
+        "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",
@@ -697,22 +715,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.39.1",
-    "@voltro/cache": "0.39.1",
-    "@voltro/data-transfer": "0.39.1",
-    "@voltro/database": "0.39.1",
-    "@voltro/env": "0.39.1",
-    "@voltro/kv": "0.39.1",
-    "@voltro/logger": "0.39.1",
-    "@voltro/plugin-auth": "0.39.1",
-    "@voltro/plugin-broadcast": "0.39.1",
-    "@voltro/plugin-mail": "0.39.1",
-    "@voltro/plugin-storage": "0.39.1",
-    "@voltro/plugin-webhooks": "0.39.1",
-    "@voltro/protocol": "0.39.1",
-    "@voltro/runtime": "0.39.1",
-    "@voltro/serverless": "0.39.1",
-    "@voltro/workflow": "0.39.1",
+    "@voltro/ai": "0.41.0",
+    "@voltro/cache": "0.41.0",
+    "@voltro/data-transfer": "0.41.0",
+    "@voltro/database": "0.41.0",
+    "@voltro/env": "0.41.0",
+    "@voltro/kv": "0.41.0",
+    "@voltro/logger": "0.41.0",
+    "@voltro/plugin-auth": "0.41.0",
+    "@voltro/plugin-broadcast": "0.41.0",
+    "@voltro/plugin-mail": "0.41.0",
+    "@voltro/plugin-storage": "0.41.0",
+    "@voltro/plugin-webhooks": "0.41.0",
+    "@voltro/protocol": "0.41.0",
+    "@voltro/runtime": "0.41.0",
+    "@voltro/serverless": "0.41.0",
+    "@voltro/workflow": "0.41.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.39.1** | `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.41.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.39.1** | `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.41.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:
 

package/templates/agent-docs/data.md

@@ -1728,6 +1728,33 @@ const { data } = useSubscription(
 
 While skipped, no WebSocket subscription opens and `data` stays `undefined`.
 
+### A failed cold start is `failed`, not `loading`
+
+If the first snapshot never arrives because the subscription ERRORED, the state
+is **`failed: true`, `loading: false`, `data: undefined`** — nothing is in
+flight and nothing more is coming, so "it is loading" would be a false
+statement. `error` carries the cause.
+
+```tsx
+const s = useSubscription<Team[]>('app', 'teams.list')
+
+if (s.loading) return <Skeleton/>
+if (s.failed)  return <RetryPanel error={s.error}/>
+return <TeamsTable teams={s.data}/>
+```
+
+`failed` is a positive check on purpose. The state used to be `loading: true`
+with `error` set, and the escape hatch was reading that second field — which the
+natural shape of a wrapper (`{ data, loading }` passed through) drops. **If you
+wrap this state, carry `failed` with it**, or your callers inherit an infinite
+skeleton through your hook.
+
+Two things this does NOT cover. A failure AFTER the first snapshot leaves the
+good data on screen and sets `error` — replacing working rows with an error
+because the socket hiccuped is worse than the hiccup. And the failed state is
+terminal for one TRANSPORT, not forever: a reconnect discards the error and
+re-subscribes, so the entry returns to loading on its own.
+
 ### Skipped is `idle`, not `loading`
 
 A skipped subscription reports **`idle: true`, `loading: false`**. The two are
@@ -4711,6 +4738,22 @@ To distinguish "we know about this" from "this surprised us":
 | `throw new Error('oops')` | Surfaces as a defect — full log + trace, generic failure to client |
 | Unexpected exception from a library | Same — caught, logged, generic failure |
 
+## What the framework merges into your `error:` union
+
+You do not declare the errors the framework itself can raise for a procedure —
+they are unioned into the wire contract for you, and only when the procedure can
+actually produce them:
+
+| Merged | Into | When |
+|---|---|---|
+| `ScopeError` | query · mutation · action · event | the procedure declares a real `guards:` entry. NOT for `openAccess:` — a procedure advertising a denial it cannot produce is what makes an error union stop meaning anything |
+| `Unauthenticated` | query · mutation · action · event | the same condition. A guard can refuse for TWO reasons and they mean different things: the caller is known and lacks the scope (`ScopeError`), or they presented a credential that was REJECTED and so arrived anonymous (`Unauthenticated`). Without the second, an expired session reads as a permissions problem |
+| `BusinessRuleViolation` | mutation | always. A cross-table `rule()` on any table the mutation writes can fail it, and the descriptor cannot know which tables carry rules |
+| `ApprovalRequired` · `ApprovalExpired` · `ApprovalUnavailable` | mutation · action | the procedure declares `requiresApproval:` |
+
+So a guarded mutation does **not** need `ScopeError` in its own `error:`. If you
+declared it anyway, that is harmless — the union is the same either way.
+
 ## Framework-shipped error variants
 
 `@voltro/protocol` exports exactly two tagged errors. The rest of your typed errors are ones you declare yourself (above) or ones a plugin / the runtime contributes.

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

@@ -1150,6 +1150,23 @@ Auth is resolved by the **api**, never the web app. Two rules follow:
 
 So a cookie-mode Supabase app configures `supabaseStrategy({ cookieName: 'sb-<ref>-auth-token' })` on the **api**; the web loader's `ctx.query` then authenticates for free. See [Supabase Auth](/docs/plugins/auth-supabase).
 
+### Renewing an EXPIRED session — `middleware.ts`
+
+The rules above assume the cookie is still valid. When it is not — a token older
+than the IdP's lifetime, which for a 1-hour token is practically every first
+page view of the day — the api resolves 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. `middleware.ts` at the web app root runs
+earlier than both, says which routes it covers, and writes the rotated cookie
+back so this render and the browser agree.
+
+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
 
 If the loader throws, the framework:
@@ -1962,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:

package/templates/agent-docs/whats-new.md

@@ -1,4 +1,4 @@
-# What's new in 0.39.1
+# What's new in 0.41.0
 
 Read this FIRST when a task touches an area you have not worked in recently.
 It is the cheapest way to notice that the framework grew the thing you were
@@ -7,50 +7,72 @@ workaround for something that shipped two versions ago.
 
 BREAKING entries name a codemod; run `voltro update` to apply it.
 
+### ⚠ BREAKING
+
+- **@voltro/web, @voltro/cli** — `middleware.ts` exports `defineMiddleware(...)` (from `@voltro/web/middleware`) instead of a bare function, and each export carries its own `match`. Several middlewares per file are allowed; **at most one may match a given route**.
+
+  Migration: the codemod wraps the existing default export. That is behaviour-preserving — no `match` means every server-rendered route, which is what an unwrapped middleware did — and its note explains how to replace a hand-written path gate with a `match`.
+
+  **Why it was worth a break.** A hand-written `if (!req.pathname.startsWith('/app')) return` is invisible: nothing can tell you a middleware runs nowhere, or that two of them claim one route. `match` puts it where both the boot and `voltro doctor` can read it.
+
+  **The matcher speaks ROUTES, not URL patterns** — `under` / `routes` / `except`, validated against the app's own route patterns. A path matching no route refuses the boot instead of silently never firing. This is the deliberate difference from the `'/((?!api|_next/static|…).*)'` shape: our hook runs after route matching, so an app has never needed to know its own asset layout, and non-page requests are reachable only by asking (`assets: true`) — where, note, there is no render, so only `setCookies` takes effect.
+
+  An overlap refuses the boot and names both middlewares plus the route. Declaration order is not a semantic, "most specific wins" silently drops the broader hook, and merging needs a per-field rule nobody remembers — so two hooks writing one `authorization` header is a refusal, not a resolution.
+
+  **The web bundle budget moved UP, and the split is worth stating** because only one half is a cost the framework imposes:
+
+  | measured | before | after | | --- | --- | --- | | first load | 184 955 B | 185 309 B (**+354**) | | lazy route chunks | 3 502 B | 4 415 B (+913) |
+
+  The **+354 B of first load is the real price** — one `serverContext` chunk, 0.2 KB gz, which every app now carries whether or not it declares a middleware. That is the number to argue with, and it leaves 6.7 KB of headroom under the ceiling.
+
+  The +913 B is NOT a per-route regression: the fixture gained four routes (`exact`, `exact/[id]`, `mw`, `mw/skip`) to exercise the feature end to end, at 0.1–0.2 KB gz each, which accounts for the growth without remainder. Re-pinned with `--update` rather than by hand, so the `slackFloor` keeps ratcheting — a ceiling nobody lowers again silently permits re-inflating to the old number.
+
 ### Fixed
 
-- **@voltro/runtime, @voltro/cli** — An app-registered tuple source is no longer replaced by the framework default.
+- **@voltro/data-transfer, @voltro/cli** — `voltro data export` could not export a table whose primary key is not named `id`, and one of its two failure modes reported success.
+
+  The keyset column was `columns.find(c => c.type === 'id')?.name ?? 'id'`, and `type: 'id'` is tagged only on a column that is BOTH the single-column primary key AND literally named `id` — identically in all four dialect introspectors. So any introspected table with another PK name was ordered by a column that does not exist. It now comes from the real primary key (the synthesised `<table>_pkey` index), with the declared `id()` column still winning where there is one.
+
+  **A composite or absent primary key is now REFUSED**, not silently ordered by the first column: keyset pagination on a non-unique order splits equal values across page boundaries, so rows are dropped or duplicated into a bundle that reports success. Bounded exports are recoverable; a quietly short backup is discovered at the restore.
 
-  Both boot paths carried this comment, verbatim:
+  **A requested table missing from the schema is refused too.** `scope: { kind: 'tables' }` used to drop unknown names, so a run that explicitly named a table wrote `"tables": []` and printed `export complete` with exit 0. `kind: 'all'` over an empty database is still a legal empty export — the asymmetry is deliberate: a named table is an expectation.
 
-  > An app whose relationships live in its own tables overrides with > `setTupleSource`.
+  **Failure reasons survive.** `String(e?.message ?? e)` produced `"write table failed: "` with nothing after the colon — `??` falls back on null/undefined, and an Effect `TaggedError` carries an empty-string `message`. Every catch site in the exporter now reports tag, message or cause.
 
-  and then called `setTupleSource(default)` **unconditionally**. That call runs AFTER the app's startups — `runBootLifecycle` at `dev.ts:3910` and `serveCommand.ts:869`, against the registration at `dev.ts:4065` and `serveApi.ts:937` — and `setTupleSource` is last-write-wins. So the framework won every time: an app registering its own source in a `*.startup.tsx`, which is what the docs tell it to do, had it silently replaced.
+  **New: `voltro data export --exclude a,b`** — everything except these, resolved against the live table list. It is the escape hatch the refusals above require; without it a single unkeyable table would block a whole-database export. An unknown name is refused for the same reason. Direct target only (the expansion needs the live table list), and it expands to an explicit `tables` scope, so the manifest records what was actually exported.
 
-  The consequence is not subtle. Every relationship guard would then be answered from `_voltro_rebac_tuples` — empty, for exactly the app that keeps its relations in its own tables — so every guard DENIES, fail-closed, with a `no tuple source` warning that never fires because a source *is* registered: the wrong one.
+  Reported with a reduced repro, a four-way variation over PK TYPES that ruled type out, and two disproved hypotheses. The affected tables include `@effect/cluster`'s own (`cluster_locks`, `cluster_migrations`), so no app running workflows could take a whole-database export.
+- **@voltro/database, @voltro/runtime, @voltro/cli** — `.encrypted()` had three writers and two encodings. The store wrote `encrypt(JSON.stringify(v))`; `encryptField` — the documented raw-SQL escape hatch — and `voltro db encrypt-column` wrote `encrypt(v)`. All three produce the same `enc:v1:` envelope and nothing distinguished them, so a value written by one and read by another either threw with the wrong diagnosis or came back subtly wrong (`decryptField` handed back the JSON encoding verbatim, quotes and all, raising nothing).
 
-  The comment was not wrong about the design; it described the design while the code removed it. Same shape as the `DORMANCY_WAKEUP_TENANT` scar — equal by value at both call sites, so nothing could fail, and the comment was the only place the intent survived.
+  There is one encoding for every WRITE now, and every READ resolves BOTH forms — so **no data has to be rewritten and nothing is blocked**. That second half is the point: the old form is already on staging and production disks, and a fix that needs the rows rewritten before the app works is an outage with a migration attached.
 
-  `registerDefaultTupleSource` fills the gap only when nobody else did, and returns whether it acted so the boot can say which source is live instead of leaving an operator to guess. `setTupleSource` itself is unchanged: an app calling it twice still gets the second one, because narrowing that would trade one silent surprise for another.
+  Reading two forms is deterministic, not a heuristic. After decrypting, a parse failure is the raw form; a parse to a STRING is the JSON form; a parse to a non-string depends on the column's declared type (a text column cannot hold a number, so `12345` is a raw string that parsed by accident). The one case nothing can separate — a raw secret whose literal text is `"abc"`, quotes included — is stated in the code rather than hidden.
 
-  Found while re-checking a consumer's claim that a different item was still open. It was not — but it sits beside this, and this is the one that would have bitten them. Pinned in both directions: a unit test for the registrar, and a source guard asserting neither boot path installs `loadResourceTuples` through `setTupleSource` again. Red-verified by restoring the original line.
-- **@voltro/cli** — `voltro doctor` no longer reports "scope vocabulary: none found" when it could not read the config at all.
+  **`voltro db encrypt-column` verified itself against the wrong decoder.** It wrote the raw form and checked it with `cipher.decrypt` — a decoder nothing reads these columns with — so it reported success over columns the app could not read. It round-trips through `decodeFieldValue` now, the same function the store calls. A self-check against a decoder the runtime does not use is not a weaker check; it is a second opinion from the same mistake.
 
-  A consumer HAD configured `doctor.scopeVocabulary` and still read `none found`. The cause was not their vocabulary: `app.config.ts` could not be imported outside their pod — an auth strategy demands its secret while the config is evaluated — so the vocabulary was never read. Inside the pod the message disappears and the rule runs.
+  The command also NORMALISES rows in the old encoding as it goes (reported separately from the ones it encrypts), so an operator does not write a script per column. It skips anything ambiguous and anything it cannot decrypt.
 
-  "You have no vocabulary" and "I could not look" are different states, and only the first is a statement about their app. This section already made exactly that distinction one member earlier — its own comment reads **DORMANT AND CLEAN MUST NOT PRINT THE SAME** — and then collapsed the third.
+  **The width pre-flight measured the wrong thing after the encoding changed.** It sized the ciphertext from the PLAINTEXT's byte length while the cipher is handed the JSON encoding — two characters more at minimum, and more for every escape. Measured on a real MariaDB: a 63-byte value in a `varchar(135)` passed the check and the UPDATE answered `ER_DATA_TOO_LONG`, which is the failure that check exists to prevent, mid-column with the rest already converted. It measures the encoded length now, and the refusal says "encodes to" rather than "is" so an operator measuring their own column finds the number it names.
 
-  The signal existed and was not connected. `offlineManifest` deliberately survives an unimportable config (a doctor run must not die on one), so the empty vocabulary arrived looking like a real absence, while the same failure was reported a hundred lines earlier under plugin tables. The consumer read the section about scopes and searched at the wrong end — which is the correct way to read a report.
+  **Two dialect defects, both found by running the command against real servers.** SQL Server reports `-1` for `NVARCHAR(MAX)` — its spelling of unbounded — and the pre-flight read it as a one-character column, so it refused the widest column the dialect has and printed `declared as -1` at the operator. And SQLITE has no `information_schema` at all: the shared catalog query died there with `Failed to prepare statement` and no statement attached, on a dialect the command claims to support. It uses `pragma_table_info` now, reporting no length because sqlite enforces none.
 
-  The rule now probes importability before claiming an absence, and says so:
+  Measured end to end on postgres, mysql, mariadb, mssql and sqlite: a table holding plaintext, the old encoding and the current encoding side by side converts, every row decodes back to its original value, a re-run writes nothing, and a wrong key refuses with exit 1.
 
-  ```
-  •  scope vocabulary: NOT EVALUATED — `app.config.ts` could not be imported.
-     This is not a statement about your scopes: the rule never got to read them.
-     … The same import failure is reported above for plugin tables; both sections
-     have this one cause.
-  ```
+  **Backups and restores were never affected and now say so.** `voltro data export` reads through the raw dialect store, so ciphertext travels verbatim in either encoding — pinned by a test, because a future change that wrapped that store would put plaintext credentials in a bundle.
+- **@voltro/protocol, @voltro/cli** — Three findings from one consumer round, all of the same shape: something the framework knows and does not say.
 
-  The dormant case keeps its own wording, so a quiet run on an app that genuinely publishes no vocabulary is not relabelled as a broken config.
+  **A decode failure on a GUARDED procedure now says the guard did not run.** The payload decodes before the handler, so a guard on a procedure with a malformed payload never gets the chance to refuse. A consumer auditing a guard called one with an incomplete payload, got a decode error instead of a `ScopeError`, and concluded the guard was not applied — the wrong conclusion in the dangerous direction. The title now carries `(guarded — the guard did NOT run: the payload failed to decode first, so this says nothing about access)`. It discloses nothing new: that a procedure is guarded is already visible to anyone who sends a VALID payload. An `openAccess:` declaration is not an enforced guard and gets no such sentence — `hasEnforcedGuard` is the one predicate, read by both the label and the wire error union, because two copies of that rule would disagree invisibly.
 
-### Internal (no consumer-facing effect)
+  **`middleware.ts`'s `httpOnly` default is documented at the field, and warned about.** It defaults to `HttpOnly`, which is wrong for a session cookie a browser SDK reads back: Supabase's `createBrowserClient` reads `document.cookie`, so a forgotten `httpOnly: false` gives the browser a session it cannot see — the SSR render is perfect and the user is signed out at the first client-side call. The consumer only avoided shipping it because their probes already set the flag. `voltro dev` warns once per cookie when a session-shaped name is written with no `httpOnly` decision; an explicit decision either way silences it, because warning on a decision is how a diagnostic becomes noise.
 
-- **@voltro/cache, @voltro/kv** — The RESP TTL tests in `@voltro/cache` and `@voltro/kv` stopped measuring the machine. Test-only; no product code changed.
+  **`voltro dev` restarts when `middleware.ts` changes.** It is loaded once per boot, that is documented, and a consumer read it and still lost an afternoon: they sabotaged the middleware, saw no change, and concluded it was not wired — in an environment where everything else hot-reloads. It now restarts through the same respawn a hard-restart field in `app.config.ts` uses, extracted so there is one copy of the `execArgv` inheritance and the signal forwarding.
+- **@voltro/cli** — `middleware.ts` now produces ONE view of the request that every downstream reader takes. Previously only `buildLoaderQuery` saw the hook's result, while the loader context (`ctx.headers`), the SSR request snapshot (`useServerRequest()`) and the locale resolver kept reading the raw request — four readers, two answers, within eighty lines of one function.
 
-  Both wrote a key with `ttlMs: 150`, asserted it was still there, then slept 300 ms and asserted it was gone. The second half is fine — waiting LONGER only strengthens "it expired". The first half was a race: the write and the read are two round-trips, so on a loaded runner the key legitimately expired before the liveness assertion, and the test reported a defect that was not there. It failed exactly that way on a release gate, in the keydb engine, while passing locally with 24/24 green.
+  The consequence was worse than an inconsistency: a hook that renews purely via `setCookies` — no `headers` at all, which is the normal shape for a cookie-session IdP and the reason the response half exists — moved nothing for the render that ran it. The rpc call still sent the old `Cookie` header, because a renewed cookie only reached the browser.
 
-  Now: a 2 s window, so liveness has real headroom rather than 150 ms of it, and the expiry is awaited as a CONDITION (`awaitGone` polls) rather than as a duration. Idle machines finish in about the TTL; loaded ones take as long as they need; a key that never expires still fails, because the ceiling is a failure mode and not a timing assumption.
+  `setCookies` is applied to the cookie jar before the render, the `Cookie` header is rebuilt from that jar (an explicit `cookie` in the hook's own `headers` still wins), and `maxAge <= 0` deletes, so a hook that signs someone out renders them signed out. Both SSR boot paths shadow the raw headers out of scope after the hook runs, so a new reader added below is correct without knowing any of this.
+- **@voltro/cli** — `voltro start` dropped `middleware.ts`'s `Set-Cookie` on **streamed** responses — which is the arm a plain `renderMode: 'ssr'` page takes, so it was the common case. The hook renewed the session server-side, the render used the fresh value, and the browser kept the consumed one. Against an IdP that rotates refresh tokens and detects reuse, that is worse than not renewing at all.
 
-  Fixed in BOTH packages in one change. The two files carried the identical construction, and this repo's standing lesson is that a fix landing in one copy of a duplicated shape leaves the other one broken — `@voltro/kv` had not failed yet, which is a statement about luck rather than about the test.
+  The cause is worth stating because it read as handled: a streamed response hands the socket to `stream(res)` and the caller never looks at the returned `headers`, so the `withCookies(...)` wrapper on that arm was dead code — sitting under a comment promising the cookies were written on every arm. The cookies now travel with the headers `streamSsrResponse` itself writes, and the dead wrapper is gone.
 
-  `@voltro/kv`'s header also pointed at `../cache/test/docker-compose.yml` for bringing the engines up. That path does not exist; there is one compose file, at the repo root.
+  Found by booting real `voltro dev` and `voltro start` servers against a fixture and reading the response. Every unit test was green throughout, and the render's own HTML was correct — only the wire was wrong.

package/templates/apps/api-ai/package.json

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/ai": "0.39.1",
-    "@voltro/cli": "0.39.1",
-    "@voltro/database": "0.39.1",
-    "@voltro/env": "0.39.1",
-    "@voltro/protocol": "0.39.1",
-    "@voltro/runtime": "0.39.1",
+    "@voltro/ai": "0.41.0",
+    "@voltro/cli": "0.41.0",
+    "@voltro/database": "0.41.0",
+    "@voltro/env": "0.41.0",
+    "@voltro/protocol": "0.41.0",
+    "@voltro/runtime": "0.41.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.39.1",
+    "@voltro/testing": "0.41.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

package/templates/apps/api-auth/package.json

@@ -13,17 +13,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.39.1",
-    "@voltro/database": "0.39.1",
-    "@voltro/env": "0.39.1",
-    "@voltro/plugin-auth": "0.39.1",
-    "@voltro/protocol": "0.39.1",
-    "@voltro/runtime": "0.39.1",
-    "@voltro/sql-postgres": "0.39.1",
+    "@voltro/cli": "0.41.0",
+    "@voltro/database": "0.41.0",
+    "@voltro/env": "0.41.0",
+    "@voltro/plugin-auth": "0.41.0",
+    "@voltro/protocol": "0.41.0",
+    "@voltro/runtime": "0.41.0",
+    "@voltro/sql-postgres": "0.41.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.39.1",
+    "@voltro/testing": "0.41.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"