@voltro/cli 0.39.0 → 0.40.0

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

@@ -1,4 +1,4 @@
-# What's new in 0.39.0
+# What's new in 0.40.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,222 +7,156 @@ workaround for something that shipped two versions ago.
 
 BREAKING entries name a codemod; run `voltro update` to apply it.
 
-### Added
+### ⚠ BREAKING
 
-- **@voltro/client, @voltro/web, @voltro/cli** — A preload that fails server-side now says so in the hydration payload, so a page can tell "still loading" from "actually empty".
+- **@voltro/client, @voltro/web** — A subscription whose COLD START failed is its own state — `failed: true`, `loading: false` — so "it is loading" is a true statement again.
 
-  Reported by a consumer whose session cookie had outlived the IdP's token lifetime — for them, practically every first page view of the day. Every `preload` on the page failed at once, the api having resolved the caller to anonymous:
+  The old shape left `loading: true` for a subscription where nothing was in flight and nothing more was coming. The type's own comment predicted the consequence:
 
-  WARN [voltro:dev:web] preload seed failed tag=projects.getById … ScopeError — missing required scope 'project:r:o'
+  > A cold-start failure leaves `loading` TRUE … so a component that branches on > `loading` alone renders a skeleton forever. Check `error` to break out of it.
 
-  The page rendered a skeleton title over an empty table, and that WARN was the only record anywhere. **The client saw exactly what it sees for a page that declares no preload at all** — both arrive as the absence of a seed — so no app could distinguish the two without inventing a convention of its own. The reporting consumer did exactly that, page by page.
+  A consumer quoted that back with the right conclusion: **a comment that predicts the misbehaviour of its own field is an API resting on discipline.** `loading` means "something is coming" everywhere else; here it meant "something is coming OR never again", and the escape hatch was a second field that the natural shape of a wrapper — pass `{ data, loading }` through — silently drops. They had three such wrappers. The framework had six, in `useWorkflow.ts`, and the compiler named all six the moment the state existed.
 
-  `usePreloadedSubscription` now returns `preloadFailed: true` in that case:
+  `failed` is a positive discriminant, so the check reads as one:
 
   ```tsx
-  const projects = usePreloadedSubscription<Project[]>('api', 'projects.list')
-  
-  if (projects.loading) return <Skeleton/>
-  if (projects.preloadFailed) return <Spinner label="Loading…"/>   // not empty — unasked
-  return <Table rows={projects.data}/>
+  if (s.loading) return <Skeleton/>
+  if (s.failed)  return <RetryPanel error={s.error}/>
+  return <Table rows={s.data}/>
   ```
 
-  It says nothing about WHY, deliberately: the server's failure text is a refused call's error message and belongs in the server log, which is the one place a browser cannot read. A boolean is the whole contract. It also says nothing about the LIVE subscription, which usually recovers on its own — the browser reconnects with a credential the SSR request did not have. So the honest reading is "the first paint has no server data, and that was not for lack of asking", which is exactly enough to choose a spinner over an empty state.
-
-  `seedPreloadedSubscriptionFailure` is exported from `@voltro/web/ssr` beside `seedPreloadedSubscription` for a loader that runs its own preloads.
-
-  Two shape notes, both deliberate:
-
-  - **The field is widened on THIS hook, not on `SubscriptionState`**, so no existing `useSubscription` call site is un-narrowed by it — the same scoping rule the `skip`/`idle` overload follows. - **`seedFailure` is REQUIRED on the internal preload runner, not optional.** This is the hook whose omission WAS the defect, and an optional hook is an omissible one — the same mistake with a nicer name that cost us `startOutboxRunner`'s teardown. Making it required is what listed all three render paths (dev, start, static prerender) at the compiler rather than at review.
-- **@voltro/web, @voltro/cli** — `LoaderContext.isServer`, and the type now says a loader runs TWICE.
-
-  Reported after two days of debugging: a loader carried a server-only call, and nothing in `LoaderContext` said the same function runs again in the browser on every in-app navigation. The consumer read "runs once per request" into the gap, which is the reading the wording invited.
-
-  **The docs were worse than a gap — they contradicted themselves.** The loaders page opened with "the page's server-side data hook" and its first code sample carried the comment `// Server-side fetch — runs on the Node side, never in the browser`, while 230 lines further down the same page said "on a client-side navigation … the loader runs in the browser". A reader who hits the false line first stops looking. Both are corrected, in both languages, and the precondition is now the first thing the page states.
-
-  **Why it survived two days is the part worth repeating:** a client-only failure is invisible to every probe that does not NAVIGATE. A fresh page load, a `curl`, any SSR check all take the server path and pass. Only clicking a link inside the running app reaches the other one.
+  **BREAKING**: `!loading` no longer proves `data` is present, so every call site that reads `data` after a bare `loading` check is a type error naming file and line. Nothing fails silently. The codemod is `manual` on purpose — a transform could add `|| s.failed` everywhere and would be wrong about half of them, since an infinite skeleton is precisely what this removes.
 
-  `ctx.isServer` is the supported discriminator, because the two things that look like they answer the same question do not:
+  **Measured blast radius**, because the estimate was worse than the reality: 20 errors inside `@voltro/client` (mostly its own `useWorkflow` wrapper and the type-tests) and **zero** in `@voltro/web`, `devtools-ui`, the devtools app, the cloud app, and all 45 templates. Most consumers were already using a `fallback` or a wrapper, which is what made the original defect so quiet.
 
-  - `query` is absent in the browser, so `if (ctx.query)` appears to work — but it branches on the ABSENCE OF A FUNCTION, which says nothing about why it is absent and breaks the moment anything else becomes conditional; - `headers` is `{}` in the browser, **not** `undefined`, so `if (ctx.headers)` is TRUE on both paths. The reporter checked exactly that, and it silently did nothing.
+  Unchanged: a failure AFTER the first snapshot still leaves good data on screen with `error` set — only the cold start is `failed`. A `fallback` subscription still has `data` always present, so `failed` reports there rather than gating. `idle` stays opt-in by overload; `failed` is not opt-in, because any subscription's cold start can fail. And the state is terminal for one TRANSPORT: a reconnect discards the error and re-subscribes.
+- **@voltro/protocol, @voltro/runtime, @voltro/voltro** — A guard refusing a caller whose credential was REJECTED now answers `Unauthenticated`, not `ScopeError`.
 
-  It is REQUIRED rather than optional: an optional boolean is omissible, and a server path that forgot it would read as `undefined` — falsy — and claim to be the browser, which is the precise failure the field exists to prevent. The compiler names every client construction site; the three SERVER render paths build their context as untyped literals, so `loaderIsServer.test.ts` derives those by shape and fails on one that omits it (red-verified against a removed line, which named the file and offset).
-- **@voltro/react-native, @voltro/client, @voltro/web, @voltro/cli** — React Native gets the whole client, not half of it. `startMobileApis()` connects and re-dials over the **same** supervisor `@voltro/web` uses — the supervisor moved into `@voltro/client` rather than being copied, because a second copy of its stale-seed gate (the rule that stops one subject's rows appearing in the next subject's screens) is a second thing to keep correct. Web's two browser-specific behaviours are injected options now: the devtools status entry and the dev-only wedge reload.
+  Measured by a consumer: a user's tab outlived their IdP's token lifetime. The strategy logged it plainly —
 
-  `voltro codegen` in a mobile app writes `.framework/mobileApis.generated.ts` from `voltro.mobile.ts` — which apis the app talks to, and where each one's rpc group and descriptors come from. Only the binding is generated; the procedure types ride the import of the api's own `rpcGroup`, so a schema change needs no regeneration. The ws URL is a runtime parameter and deliberately not baked in: `localhost` on a phone is the phone, and `resolveDevWsUrl()` takes the LAN host Expo already knows.
-
-  `createAsyncStoragePersistence()` makes `defineStore({ persist })` work on a device. A store reads during render and a render cannot await, so it hydrates into memory once — awaited before the first screen — then serves reads synchronously and writes through, coalescing per tick. A storage with no `getAllKeys()` and no declared `keys` refuses rather than hydrating empty: an empty cache is indistinguishable from a first run.
-
-  `useMobileConnectionStatus()` takes an optional `onlineSource`. Its default reads `navigator.onLine`, which React Native does not have — so on a device it answered "online" forever, airplane mode included. Pass `netInfoOnlineSource(NetInfo)`. `isInternetReachable` is believed only when it is a boolean, because NetInfo reports `null` while its probe is out and reading that as offline flashes a banner on every cold start.
-
-  Two type declarations were WRONG, and running the mobile template through the scaffold harness is what said so — nothing else in the repo typechecks a generated entry, on web either.
-
-  `ClientDescriptorMap` was a structural copy of `@voltro/protocol`'s `ClientDescriptor` that narrowed `source` to one string while the real descriptors carry several. It is now that type, not a copy of it. And an api's `group` is the erased `RpcGroup.Any`: `RpcGroup` is declared `in out` in @effect/rpc, so the CONCRETE group codegen emits was never assignable to `RpcGroup<Rpc.Any>` — the boundary rejected the only value anyone passes it. Erasing at the boundary and restoring at the call site is what `ApiHandle.client` already does; the one cast is where the rpc client is built.
+  ```
+  WARN auth strategy "supabase" rejected request: supabase jwt expired
+  WARN mutation.tasks.update failed: missing required scope 'task:u:o'
+  ```
 
-  `dispatchDeepLink()` is new for the same class of defect. `matchFirstDeepLink` returns a descriptor from a heterogeneous array, so its handler declares `Record<string, never>` params while the match hands back `Record<string, string>` — the result could not be invoked by anyone.
+  — and the wire said the caller lacked a scope. Technically true (an anonymous caller holds none) and it sends everyone who reads it into the permissions system while the problem is an expired session. They did that round; the subject was their administrator, and the same call with a fresh token worked.
 
-  `apiSurface: compatible` — every changed declaration either widens what a producer may pass or replaces a type that misdescribed its own values. Code written against the narrow `source` was already wrong at runtime, and no call that compiled before stops compiling. `useMobileConnectionStatus` gained an optional parameter.
+  **The obvious fix would have broken more than it fixed**, which is why this shape and not that one. Failing hard when a strategy rejects would break every `openAccess` procedure for anyone holding a stale cookie — a public page that needs no session at all would start refusing. So the FACT travels instead: a rejected credential stamps `credentialRejected` on the anonymous subject it falls back to, and only a guard that actually refuses spends it. `openAccess` never reaches that point and is untouched.
 
-  Not verified here, and not implied: that the loop runs on a device. Everything above is unit-tested without a simulator, and only a simulator can prove Metro. That is an Expo/EAS CI step.
-- **@voltro/runtime** — A `TupleSource` receives the whole `subject`, not just `subjectId`.
+  Three details worth knowing if you touch it:
 
-  Reported precisely, from a guard review rather than an outage. `subjectId` cannot express a CREDENTIAL that is narrower than the person holding it, and an API key is exactly that: the key's binding lives in the subject's `metadata` (`keyType`, `teamId`), while `subject.id` is the OWNING USER. A tuple source could therefore only resolve the owner's memberships and was blind to which team the key was minted for — so an owner who belongs to two teams passed the guard for both. The comment beside their hand-written check says what that costs:
+  - **The stamp happens AFTER the app's `fallback`.** That callback builds its own anonymous subject and knows nothing about the rejection; stamping before it would be silently discarded — the shape of every "wired on one path" defect in this codebase. - **ONE conversion point** (`asRefusal`), at the exit rather than at each `return`. Every branch builds the `ScopeError` it always built; one place decides what it MEANS. - **`Unauthenticated` is merged into the wire union** for guarded procedures AND guarded events, beside `ScopeError`. Without that it would be a tagged error the descriptor cannot represent, and the server would collapse it to `InternalError` — the defect another consumer reported the same week.
 
-  > Without the binding check below a key minted for team A worked on every team > in the org.
+  A caller who presented NO credential still gets `ScopeError`. Collapsing both would send a genuinely under-privileged user to the login page.
 
-  Nothing was ever wrong in their app, because they kept the executor-side check. The defect is that a DECLARED guard could not replace it:
+  **Why this is BREAKING although nothing was removed.** Three published results gained a union member:
 
   ```ts
-  setTupleSource(async (req) => {
-    const boundTeam = req.subject.metadata?.teamId
-    if (boundTeam !== undefined && boundTeam !== req.resourceId) return []
-    return loadResourceTuples(store, req.subjectId, req.resourceType, req.resourceId)
-  })
+  checkGuards(…)        // ScopeError | Unauthenticated | null   (was ScopeError | null)
+  checkGuardsEffect(…)  // Effect<ScopeError | Unauthenticated | null>
+  bindEvent(…)          // Stream<…, ScopeError | Unauthenticated, …>
   ```
 
-  A guard that must always run paired with a hand-written check is not a declaration — it is a comment with a type signature. And the pairing is exactly the thing nobody re-derives when they delete the "redundant" half a year later; the reporter had already written the reason into their parity test to stop that happening.
-
-  `subject` is typed as the full union deliberately: its system and anonymous members carry no `scopes` or `metadata`, so the narrowing is the caller's to do and is visible where it happens.
-- **@voltro/cli** — A declared relationship guard whose `resourceType` is not registered now refuses the boot instead of denying every caller forever.
-
-  The report described the shape exactly: an app arms its authorization from a startup (`defineResourcePolicy` + `setTupleSource`). If that registration does not happen, the app boots **clean**, takes traffic, and every procedure with a declared guard refuses from then on. Fail-closed, so nothing leaks — and a total outage of the guarded surface whose only signal is a log line nobody reads, because the boot was green. At their size: 39 procedures — team settings, hours import, role administration.
-
-  Since 0.38.0 a `*.startup.tsx` that THROWS already refuses the boot, so the sequence they described is closed. This gate exists because that fix covers only the throwing case, while the same silent outage arrives by three doors no startup-error handling can see:
-
-  - the startup registers some types and not the one a guard names — a typo in a `resourceType` is not a compile error, it is a string on one side and a string on the other; - the file was renamed out of the discovery pattern, so it never ran and never threw; - the registration was conditional on something false at boot.
-
-  All three end in the same place, and the framework can rule out all three by asking one question it already holds both halves of: which `resourceType`s does the discovered surface NAME, and which are REGISTERED?
-
-  The refusal names the type, the count and the procedures that demanded it — grouped by type, because the fix is one `defineResourcePolicy` per type while the damage is per procedure. It also names the spelling trap, since nothing else in the system compares those two strings.
-
-  **Why refuse rather than warn**, because "fail-closed already, so it is safe" is the plausible objection: safe is not working. The procedures are DOWN, and down-with-a-warning is precisely the state being reported. A refusal is recoverable in seconds and impossible to miss.
-
-  It runs after the startups have settled, on both boot paths — not beside `assertProcedureAccessDecisions`, which reads declarations and can run at discovery. This one reads a registry the app fills during its startups, and placing it earlier would have failed every app that registers from one, which is all of them. A check that fails on everything gets deleted rather than fixed.
-
-### Fixed
-
-- **@voltro/client** — A timer no longer discards the optimistic preview of a write the server confirmed. **A rollback happens if and only if the write FAILED.**
-
-  Measured by a consumer on a Gantt bar: drag it, the server writes, the mutation reports success — and five seconds later the bar jumps back. They suspected the server first and proved it was holding the data correctly, reasons included, before finding that the client was throwing the confirmed patch away itself.
+  The test for breaking is not "did a symbol disappear", it is whether code that COMPILED can stop compiling — and a widened return does that wherever the old union is named (`const refusal: ScopeError | null = checkGuards(…)`), or narrowed exhaustively. It was filed as `Added` first; the golden diff is what showed otherwise, and the rule is worth more than the classification that felt right. `anonymousSubject`'s new second parameter is OPTIONAL and breaks nothing.
 
-  The cause was one line: `confirmByMutation` armed a `setTimeout` calling `revertByMutation` — **the same function the FAILURE path calls**. Success and failure ended in the same discard, one immediately and the other five seconds later.
+  `voltro update` carries you across it — codemod `0.40.0/02_rejected-credential-widens-guard-results`, a written note. A transform would widen each annotation, which compiles and keeps the reported behaviour: the decision at each site is what an expired session should do that a missing permission should not.
 
-  What makes it unambiguous is WHEN that timer could fire at all. Any server event already retires confirmed patches through the seamless hand-off, so the window only ever expired while `base` was still STALE. The revert therefore replaced a value that reflects the committed write with one the client knows does not:
-
-  | | keep the patch | revert (before) | |---|---|---| | delta arrives later | invisible hand-off | 5s of stale, then a jump back and forth | | delta never arrives | matches what is saved | **contradicts what is saved, permanently** |
-
-  The bottom-right cell is the damage: the user watches their saved change disappear and either redoes it or plans on a state they believe was not stored. A "leaked" patch is gone on the next subscription; a silent revert is healed by nothing.
-
-  Expiry is now a **resync**: the client re-issues that subscription, keeps the patch, and says so loudly on the error bus (`voltro logs`) — the silence was the second half of the report, because in the UI this is indistinguishable from "the server did not save it", which is the false trail they followed first.
-
-  **Two more seams of the same defect, both found while fixing it:**
-
-  - **An `error` event retired confirmed patches.** An error does not advance `base` — it sets `baseError` and leaves the rows where they were — so dropping there discarded a committed write's preview for nothing. - **A resync whose snapshot comes back UNCHANGED must not retire them either.** The first version of this fix had exactly that hole: it re-asked the server, the answer was byte-identical, and the patch was dropped anyway — the reported bug reached by a longer route. The hand-off rule is now explicit (`supersedesConfirmedPatches`): a delta always supersedes, an error never does, and a snapshot only when it actually MOVED the base.
-
-  The rule is pinned against the source, not only behaviourally: no `setTimeout` in the cache may name a revert. The defect was never inside a function — it was which function a timer pointed at, and a behavioural test only sees that if somebody thought to write the case. Nobody had: `CONFIRMED_PATCH_TTL_MS` was named nowhere in the test file, which the reporter also pointed out. It is now, red-verified by restoring the original line.
-- **@voltro/ui-shadcn** — `AnimatedNumber` rendered `0` into static markup. It initialised its state to zero and counted up on hydration, so every statically rendered page SHIPPED the zero — the landing site's own stats row went out as "0 … 0 … 0% … 0", which is what a crawler, an answer engine and any reader with JavaScript off saw. A number that only exists after hydration is not a number on the page.
-
-  It now renders the target value (so the server's markup and the first client render agree — no hydration mismatch) and drops to zero inside the observer callback, at the one moment the animation is actually about to run. The count-up is decoration layered on a correct page rather than the only way to see the value.
-
-  The test that covered this asserted `toBe('0')` before scrolling — it was pinning the defect. It asserts the final value now, with the reason written next to it, plus a second case for the count-up itself.
-
-  `CodeCompare`'s corner tags take an `eyebrow` prop instead of hardcoding "Before" / "With Voltro". This kit renders a bilingual site, and an English label over German copy is the same defect as any other hardcoded string. The English default keeps every existing call working.
-- **@voltro/cli** — `voltro dev` reports the db-pool budget too, and the out-of-pool count is right on every dialect.
-
-  The line was `voltro serve`-only, and the module said so with its reasoning: a dev machine has one process and no replicas, so `max × replicas` is noise. It even asked a future reader not to "fix the parity gap" by moving it.
-
-  The reasoning was fine and its PREMISE was false. `voltro dev` is not always a dev machine — at least one consumer runs it as their deployment, two API pods against a shared pooler, and `retentionSweep.ts` already reasons about that same consumer in its own header. Two modules cannot both be right about what `voltro dev` is. The cost was not theoretical: that consumer REPORTED the out-of-pool `LISTEN` connection, we answered it in this line, and they could not see the answer, because the one boot path they run does not print it.
-
-  So the exception is conditional rather than per-command now. `voltro serve` always reports; `voltro dev` reports when the environment shows the process is not a laptop — `REPLICA_COUNT` (a process cannot know how many of itself are running, so a platform set it), `DB_MAX_CONNECTIONS` / `PG_MAX_CONNECTIONS` (somebody is already reasoning about this number), or `DB_REPLICA_URLS` (which multiplies the pools inside ONE process — the case most likely to be mis-budgeted, because it does not look like a fleet). A bare `voltro dev` with nothing set stays silent, which is the half of the original decision that was right.
-
-  **And the out-of-pool arithmetic was wrong for two dialects.** It was derived inline as `dialect === 'postgres' && CDC !== '0'`. The mysql/mariadb ROW-binlog reader speaks the REPLICATION protocol, which is a separate connection from the SQL pool by construction, so a mariadb deployment read a line that under-reported its own process by one. It is counted now. mssql Change Tracking is NOT counted, and that zero is verified rather than omitted — it reads through the store's own `SqlClient` and its module says "the CT reader needs no second pool".
-
-  Both boot paths go through one `reportDbPoolLine`, and the CDC derivation takes the ARMED state as a parameter instead of re-reading the env: a binlog reader stands down when every app table is `.nonReactive()`, and billing a connection nobody opened is the same class of error as missing one.
-- **@voltro/cli** — The 0.37.0 strict-input note under-sold the one case that breaks hardest, and the correction is RE-ISSUED rather than edited.
-
-  0.37.0 made an undeclared input field reject the call. Its note described the general case correctly and then, under WHAT DOES NOT CHANGE, said "an empty input to a procedure that declares none is still fine". True about sending `{}`, and it reads as reassurance to the owner of an `input: Schema.Struct({})` — whose procedure is the one shape that did NOT move from "silently drops the extra field" to "rejects it". It moved from accepting EVERYTHING to accepting nothing, because an empty `TypeLiteral` has no expected keys for excess-property checking to compare against. The strongest-looking declaration was the only one enforcing nothing.
-
-  A consumer measured the upgrade across 2 705 procedures and found three real breaks. The most expensive was exactly this: a `getMy` declaring `Schema.Struct({})` while a shared table hook always sent `{ limit }`. Before, the limit was discarded and the call worked; after, the live subscription AND the SSR seed of that page both die.
+### Added
 
-  **Why a new codemod and not an edit.** `selectCodemods` filters `from < version <= to`, so anyone who has already crossed 0.37.0 — including the consumer who reported this — will never see that note again, whatever it says. A correction filed there reaches only users who have not upgraded yet, i.e. not the ones holding the broken app. `0.39.0/01_empty-input-schema-rejects-every-field` carries it to the people who need it. (The 0.37.0 note is corrected too, for users still short of it. That edit is necessary and not sufficient, and the difference between those two words is why there are two files.)
+- **@voltro/client, @voltro/web** — The client re-resolves `authHeaders` when the server says the credential was rejected — and `client.refreshAuth()` for an app that knows earlier.
 
-  Its `appliesTo` is deliberately BROADER than the original's. 0.37.0's fires on a spread into a procedure input or the untyped string form of `ctx.query` — the constructs that carry a field the author never typed, which is the right gate for the general case and the wrong one here. The payload does not have to be invisible for this to break: the reporting consumer reached it through an untyped wrapper hook passing an explicit `{ limit }`. So this one gates on the DECLARATION — an empty struct anywhere in the app — which is the population that actually changed behaviour.
-- **@voltro/cli** — All three ways a mutating inspect request can be refused now name the variable, the header, AND where the value comes from.
+  `authHeaders` is resolved once per CONNECTION and attached per frame, so a tab open longer than the IdP's token lifetime keeps presenting a dead token until something reconnects. A consumer measured it: dragging a card on a board failed, their ADMINISTRATOR's token had simply expired while the page stood, and nothing in `@voltro/client` could force the re-resolve.
 
-  A consumer verifying a row filter hit this one:
+  The trigger is the `Unauthenticated` error — which only became distinguishable from `ScopeError` in this same release. Before that the client could not have told "your session died" from "you lack a permission", and reconnecting on the second would have been wrong.
 
-  401 {"error":"unauthorized","reason":"inspect: POST needs the write credential — send it as the `x-voltro-inspect-write` header alongside the bearer. The read token authorises reads only."}
+  `refreshAuth()` is a SAME-SUBJECT rebuild, and the difference from `reconnect()` is one flag and a security boundary: `reconnect()` exists for a login / logout / tenant switch, where the next subject may be entitled to strictly LESS, so the cache must not be seeded from the old one. A token refresh is the same person with a fresh credential, so seeding is correct and the screen keeps its rows instead of blanking for the round trip. Getting that backwards is silent in both directions — seed on a subject change and you paint one user's rows into another's; refuse to seed on a refresh and every open screen blinks on every rotation.
 
-  Their words for it: the message is good, and the missing half is **where the value comes from**. They knew what to send and not what to send AS. They gave up on our tooling and hand-signed a session token instead.
+  The policy lives in ONE function (`wireAuthRefresh`) that every host wires, because "when do we reconnect on an auth error" is exactly the kind of decision this repo has watched drift when it was written twice. Two guards, answering different questions: a **rate** ceiling (one rebuild per window — a rejected mutation arrives alongside every rejected subscription on the page) and a **total** ceiling (stop after N refreshes with no successful call between, because at that point the credential is not stale, it is refused, and the answer is a sign-in screen rather than another socket).
+- **@voltro/cli** — `middleware.ts` — a web app's one server-only hook, for renewing a credential before the SSR render uses it.
 
-  That half is exactly the part a user cannot guess, because in dev nobody ever typed it: `voltro dev` MINTS `VOLTRO_INSPECT_WRITE_TOKEN` into the project's gitignored `.env.local`. Every arm says so now.
+  Reported: a consumer's SSR detail pages arrived empty on the first request of every day. Their cookie token had outlived the IdP's lifetime, the api resolved the caller to anonymous, and every `preload` on the page failed. They could not fix it in the app, and the reason is structural: `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 — and a `type: 'web'` app has no auth middleware.
 
-  **It is a function over the set, not a fix to the reported member** — this is the third message on this surface to be fixed one at a time. The three refusals were three hand-written strings of decreasing usefulness:
+  ```ts
+  // middleware.ts — web app root, server-only
+  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 }],
+    }
+  }
+  ```
 
-  - `unset` — named the variable. Fine. - `absent` — named the header and not the variable. The reported one. - `mismatch` — `inspect: write-credential mismatch`, which named neither, and is the case where knowing WHICH of the two values to look at is the entire remedy. Nobody had reported it, which is not evidence that it was fine.
+  **Why not `app.config.ts`.** That file is imported into the CLIENT bundle, verbatim, the moment any api declares `authHeaders` — the thunk is a function, so it cannot be serialised. A hook that renews a session reaches for an IdP SDK by definition, so putting it there drags the server graph into the browser. The consumer proposed exactly that shape (`serverAuthHeaders` beside `authHeaders`) and it is the one place it cannot go.
 
-  They come from one `inspectWriteHint(refusal, method)` beside the existing read- token hint, so the next arm cannot be added without the vocabulary. The method is folded in because the surface answers for `/erase` and for `/routes` in the same words, and a caller who did not know their call was a mutation is the caller most likely to be reading it.
-- **@voltro/cli** — `ctx.isServer` reaches a LAYOUT loader too, on every server path. It was threaded into the page loader and left off the segment chain, so a layout loader read `undefined` — falsy, i.e. it concluded it was in the browser while server-rendering.
+  **Why `setCookies` is not optional.** We asked whether writing cookies back was in scope, expecting the answer to be about a round trip. It was about correctness: Supabase ROTATES refresh tokens and detects reuse, so a hook that renews server-side and does not write the result back leaves the browser holding a consumed token. Without it the hook is not "slower but correct" — it can destroy the session.
 
-  Three of the five constructions never passed it: the prerender context in `build.ts`, the dev SSR renderer's layout call, and the test fixture pinning the shape. The two that did are the ones a `tsc` run named, because `SegmentLoaderContext` — the CLI's mirror of `LoaderContext` — had not grown the field at all.
+  **Deliberately not a general middleware.** It can replace credentials and set cookies. It cannot redirect, return a response, or rewrite a route — because authorization belongs on the API, which is the only thing that sees the data, and a web-side hook that can refuse a request becomes a second authorization layer beside the real one. A hook that cannot refuse also cannot be mistaken for a guard. For a login redirect, a loader already throws `RedirectError`.
 
-  Making it REQUIRED rather than optional is what found the other three, and it is the same reasoning the flag itself ships with: an optional `isServer` cannot distinguish "the server forgot to pass it" from "this is the browser", and both spellings of that mistake claim the browser. A field whose whole job is to answer one question must not have a third answer.
+  Details worth knowing: only auth-shaped headers (`authorization`, `x-tenant`, `x-voltro-*`) are forwarded to the api, so a returned `host` or `content-length` cannot produce a failure that looks like anything but a header copy; cookies default to `HttpOnly` + `Path=/` + `SameSite=lax`; multiple cookies are written as separate header lines, never comma-joined (a cookie's `Expires` contains a comma); the file is loaded ONCE per boot; a failure to IMPORT is fatal rather than degrading to "no middleware", and a middleware that THROWS fails the request — the render must not proceed on the credential it was told to replace.
 
-  `webDevSegmentChain.test.ts` asserts the loader argument with an exact `toEqual`, so a field added to one loader's context and not the other fails there. That assertion is the reason this is one release and not two: `tsc` was already green on the test file while the run would have gone red.
-- **@voltro/cli** — The pre-bundled api client is fingerprinted from the DESCRIPTOR SOURCES, so a schema change reaches the browser.
+  Wired on BOTH SSR boot paths (`voltro dev` and `voltro start`), with the cookies written on every response arm — streamed, buffered, redirect and 404. A partial application would renew a rotating token and drop it.
+- **@voltro/testing** — `makeTestContext` supplies `ctx.events`, so an executor that publishes can be unit-tested at all.
 
-  Reported: a consumer changed an input schema on a descriptor and `voltro dev` kept serving the old client. The failure is quiet in the worst way — the CLIENT rejects the call, so the api logs nothing, because no request ever arrives.
+  `ctx.events` is a field PRODUCTION puts on every `AppContext`, and the test harness did not — so any handler containing `ctx.events.publish(...)` died on `Cannot read properties of undefined (reading 'publish')` the moment it ran under test.
 
-  Vite pre-bundles the workspace api client and its optimize-cache hash keys on the lockfile and package.json, never on a pre-bundled dep's source content. So the framework fingerprints the client itself and flips `optimizeDeps.force`. That machinery was right and it was watching the wrong file:
+  **The shipped `api-durable` template demonstrates exactly that pattern** (publish inside the mutation's transaction, so it fires on COMMIT and not on rollback), and its own test passed anyway — because it called the executor with `await` instead of running it. An executor written in the Effect style RETURNS an Effect, and awaiting a non-thenable hands the object straight back, unrun. The assertion then failed on `row.status` being `undefined` and pointed at the assertion rather than at the call. Two defects propping each other up: the harness could not have run that handler, and the test never asked it to.
 
-  **`rpcGroup.generated.ts` imports each descriptor by export name and lifts it. It contains no schemas.** Codegen's own header says so. The generated file is therefore byte-identical across any schema edit, and BOTH mechanisms were structurally blind to it — the across-boot check hashed it, and the in-session watcher watched it.
+  It is the REAL `makeEventPublisher` over a real `EventBus`, not a stub. A fake would re-implement the payload validation and the tenant stamping and would be wrong the first time either gains a case — the lesson `plugin-broadcast` paid for twice. `ctx.eventBus` is the read side:
 
-  The in-session watcher's own comment already described the symptom ("the browser kept decoding responses against the stale schema"): the cache-busting half was fixed when that was hit, and the DETECTION half kept asking the file that cannot answer. So it never fired. The consumer's third reason — "runs only at boot" — is not quite right, and it does not matter: the in-session mechanism exists and was blind for the same reason. One fingerprint feeds both now.
+  ```ts
+  const seen = ctx.eventBus.subscribe(orderPlaced, { orderId })
+  await invoke(placeOrder, executor, input, ctx)
+  expect(seen.received).toHaveLength(1)
+  ```
 
-  It hashes every `*.query.ts` / `*.mutation.ts` / `*.action.ts` / `*.stream.ts` / `*.event.ts` and every `*.workflow.tsx` descriptor, plus the generated group itself (which is what moves when a procedure is added or removed without a descriptor file changing content). Paths are hashed with contents, so a rename cannot come out as a no-op. `*.server.ts` executors are deliberately excluded — they never reach the browser, and including them would force a re-optimize on every handler edit, which is the whole working day and is how a forced re-optimize gets turned off.
+  One bus for the whole harness so a `withSubject` / `withTenant` re-scope still publishes where the test is listening; the PUBLISHER is per-subject, because the tenant it stamps is the caller's.
 
-  **The `proxyTarget` skip is gone from both.** It stood in for "is this api external", and a workspace api served on its own origin has no `proxyTarget` while still being edited locally. `findWorkspaceApiDir` returning a directory is the question that was meant. It survives in exactly one place — the ws proxy, where without a target there is nothing to proxy to — and the test asserts that count rather than its absence.
-- **@voltro/cli** — `voltro probe access` now names the one thing that makes its red meaningless.
+### Fixed
 
-  The command asks "does a declared guard refuse a caller presenting nothing". It turns out that under `voltro dev` a caller presenting nothing is not anonymous: dev resolves a login-less request to a FALLBACK TENANT (`$TENANT ?? 'acme'`). An app whose scopes derive from the tenant therefore admits, and the probe reported `ANSWERED an unauthenticated call` against a guard that is perfectly fine.
+- **@voltro/cli** — `voltro agents-md --force` no longer exits 0 when it wrote nothing.
 
-  That is not an occasional false positive, it is a structural one: the local registry only ever holds `voltro dev` / `voltro start` processes — `voltro serve` does not register — so every target the command picks up WITHOUT `--url` is in exactly that state.
+  Reported: a consumer's `agent-docs/` is owned by the pod (root). They ran the command as `admin`, and it **overwrote nothing, said nothing, and exited 0**. They read the unchanged file as "the framework has not fixed this yet" — it had — and lost a full round to it.
 
-  The failure block now says so, and says what to do instead:
+  The cause was three `orElseSucceed`s in the agent-docs copy. `makeDirectory`, `readDirectory` and every `copyFile` degraded to success, so a destination the process could not write produced an empty run that reported itself as done. An unreadable source directory came back as `[]` and did the same.
 
-  voltro probe access --url http://<host>:<port>
+  Failures are collected and reported now, and the command **exits 1** when the seed is incomplete:
 
-  against a `voltro serve` process, where an anonymous request carries `tenantId: null` — the case a guard actually has to refuse.
+  ```
+  agents-md: 12 file(s) could NOT be written — the seed is INCOMPLETE.
+  The commonest cause is ownership: a container wrote these as root and you are
+  running as someone else.
+  ```
 
-  Found by running the command as a FINDER for the first time rather than as a test: it flagged a shipped template, and the flag was wrong in dev and right about production, for two different reasons. A tool whose red needs a paragraph of context should carry the paragraph.
-- **@voltro/protocol** — A rejected rpc payload no longer answers with the procedure's whole input type.
+  `--force` is an explicit instruction to overwrite, so silently not overwriting is the one outcome that must never be reported as done. `stat` is the single remaining silent degrade, deliberately: a source entry that vanished mid-walk is not a write failure and must not fail the run.
 
-  Measured by a consumer against 0.38.0, anonymously, with no session at all:
+  Pinned in both directions — a real unwritable directory yields failures, a clean copy yields none, and a source guard asserts that `stat` is the ONLY call on that path allowed to swallow. Red-verified by restoring the original `orElseSucceed`.
+- **@voltro/cli** — Every server-side loader context is now checked by the compiler, and the static prerender stopped handing loaders a context missing `search` and `headers`.
 
-  POST /rpc {"tag":"workAreas.create","payload":{"name":"x"}} → { readonly name: string; readonly storeId?: string | null | undefined; readonly type: "department" | "location" | "zone" | "station"; readonly parentId?: string | null | undefined; … } └─ ["type"] └─ is missing
+  `ctx.isServer` shipped with a source-reading guard, and that guard had the defect it exists to prevent: it matched context literals by shape (`loader({` / `ctx: {`) and therefore found ONE of the two in `build.ts`, missing the one built as a typed arrow return. Its tripwire — "at least 5 sites" — passed, because a floor cannot tell 5-of-8 from 5-of-5. The gap was found by a parallel report, not by the guard.
 
-  That procedure declares `guards: [{ scope: 'workArea:c:o' }]`. The refusal never happened — the payload decode runs first and failed first — so the caller got a field-by-field description of a write they are not allowed to make. On an app with ~700 write procedures that is a free enumeration of the entire write surface for anyone who can reach the port: no session, nothing that looks like rate-limit abuse, and no log line.
+  The invariant moved from "the literal mentions `isServer`" to "the literal is CHECKED BY THE COMPILER": every server loader context is now `satisfies SegmentLoaderContext`, whose `isServer` is required. A site that forgets it is a type error naming the file and line — strictly stronger than any regex over shapes, and verified by removing one.
 
-  The rendered TITLE is now the procedure name, and the issue PATH is untouched:
+  **It caught a second defect immediately.** The static prerender built its page loader context with only `params`, `pathname`, `signal` — no `search`, no `headers`, no `query` — while `LoaderContext.search` is declared `string`. A static page's loader reading `ctx.search` got `undefined` where the type promised a value. The segment context twenty lines above it in the same file already passed `search: ''` with a comment explaining why.
 
-  workAreas.create input └─ ["type"] └─ is missing
+  Two smaller things worth knowing if you touch the guard: the closing brace is part of its pattern because the bare phrase also appears in the comment explaining the rule (the first version counted its own documentation), and the CLI's `SegmentLoaderContext` mirror keeping `isServer` non-optional is what the whole enforcement rests on — `isServer?:` would make every `satisfies` pass while a forgetful site reports itself as the browser.
+- **@voltro/protocol, @voltro/cli** — A guard's `ScopeError` reaches the client as `ScopeError` on a mutation, not as `InternalError`.
 
-  So the half that made the 0.37.0 strict-input change cheap to adopt — WHICH key, and whether it is missing or unexpected — survives intact, while the types and the enum members do not. The excess-property case still lists the accepted key NAMES, deliberately: the caller already sent the key, that list is what makes the fix a one-line read, and names without types were not what was reported.
+  Measured by a consumer over the wire, same session, same foreign team:
 
-  **What this does NOT do, stated because the report asked for it.** It does not run `guards:` before the decode. In `@effect/rpc`, a `Request` is decoded against the payload schema and answered on failure without ever reaching `server.write` — so it never reaches the handler and never reaches `applyMiddleware`. Auth middleware runs strictly after the decode, and there is no point in that path holding both a resolved subject and an undecoded payload. Evaluating guards first means replacing the protocol layer, not annotating a schema, and `voltro probe access` therefore still reports a guarded procedure whose input it cannot guess as `inconclusive` rather than `refused`.
+  | kind | declared `error:` | denial arrived as | |---|---|---| | query `webhooks.list` | `AccessDeniedError` | `_tag: 'ScopeError'` ✓ | | mutation `…updateReferenceLabels` | `AccessDeniedError` | `InternalError` ✗ | | the same mutation, after adding `ScopeError` to its union | | `_tag: 'ScopeError'` ✓ |
 
-### Internal (no consumer-facing effect)
+  Their client maps `ScopeError` to *forbidden* and `InternalError` to *something went wrong*, so a permissions refusal looked like a crash — on every relationship-guarded write in the app.
 
-- **@voltro/datetime, @voltro/local-first, @voltro/react-native** — `@voltro/datetime`, `@voltro/local-first` and `@voltro/react-native` shipped with no api-extractor golden, so the public-surface drift tripwire did not cover them — and the docs-audit finding that motivated this landed in exactly that gap (the docs promised a `useTimezone()` hook that `@voltro/datetime` never exported, and no gate could see it). All three are wired now, root + subpath entry (`./context`, `./react`, `./schema`): six goldens, `api:check` green on each, and no existing golden changed (the new `paths` entries every sibling map gained are purely additive).
+  **Their observation was exact; the mechanism was not, and the difference is where the fix goes.** They diagnosed it as "the merge only happens on the streaming path". `withGuardError` is called by every lifter, so the wire union carries `ScopeError` on both. What differs is a SECOND reader: the server refuses to ship a tagged error the descriptor cannot represent, collapsing it to `InternalError` rather than emitting a raw defect tree — and it was handed `descriptor.error`, the RAW declaration, while the union it protects is the WIDENED one. It judged against a narrower set than it had advertised. A query never reaches that check (it is delivered through `wireErrorFromCause`, which preserves the tag), which is exactly why the split fell along query/mutation.
 
-  Root cause fixed in the generator rather than by hand: `gen-api-extractor.mjs` now creates the package's `etc/` directory with the wiring. api-extractor refuses to create its own report folder, so a package wired without one failed at its first `api:report` instead of at generation — which is how these three went live uncovered. Internal: no consumer-facing behaviour changes.
-- **@voltro/cli** — `gen-api-extractor.mjs --check` verifies the api-surface wiring instead of writing it, and runs in CI (and therefore in `pnpm gate`, which derives its steps from `ci.yml`). It fails when a published entry point has no api-extractor config, no golden, an EMPTY golden, a stale config/golden for a dropped export, or no `api:check` script.
+  `wireErrorUnion(descriptor, kind)` is now the single owner of "what can this procedure put on the wire", used by the lifters AND by both bind sites.
 
-  It is derived from `publishConfig.exports` inside the generator's own loop — not a curated list and not a second copy of the derivation — so a package that joins the workspace is covered without anyone remembering to add it. It carries a floor (60 packages) for the reason every check in `scripts/` has one: the failure mode of a wiring check is a green line over a walk that found nothing.
+  **Two more error classes were collapsed the same way, and neither was reported:**
 
-  Verified by injecting each defect and watching it go red (missing golden, empty golden), confirming exit code 1, and confirming `--check` mutates no file. Internal: tooling only.
-- **@voltro/cli** — `rpcSurfaceFingerprint.ts` wrote its composite-key separator as a literal NUL byte instead of ``. Same runtime value, no behaviour change — the file's own 16 tests pass identically before and after.
+  - **`BusinessRuleViolation`** — unconditional for mutations. `withRuleError`'s own comment says it MUST be in the union "or the violation crosses the wire as an untyped defect". It was in the union, and collapsed before it got there. - **The `requiresApproval` refusals** — `ApprovalRequired` / `ApprovalExpired` / `ApprovalUnavailable`, so "parked for approval" was indistinguishable from "the server broke".
 
-  It matters because of what the byte does to the FILE rather than to the hash: a source file containing a NUL is binary to every text tool, so `grep` skips it and prints nothing, which is indistinguishable from a clean file. This repo has been bitten by exactly that — a 1020-line module that every grep-based audit had silently skipped, including one searching for a string that file declares.
+  `openAccess:` still merges nothing: a procedure advertising a denial it cannot produce is what makes an error union stop meaning anything.
 
-  The guard (`noLiteralNulInSources.test.ts`) caught it on the release gate, in a file added earlier in this same release. The rule was already written down; what enforced it was the test.
+  If you worked around this by declaring `ScopeError` yourself, the declaration is now redundant rather than wrong — the union is the same either way, and you can delete it whenever you like.

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.0",
-    "@voltro/cli": "0.39.0",
-    "@voltro/database": "0.39.0",
-    "@voltro/env": "0.39.0",
-    "@voltro/protocol": "0.39.0",
-    "@voltro/runtime": "0.39.0",
+    "@voltro/ai": "0.40.0",
+    "@voltro/cli": "0.40.0",
+    "@voltro/database": "0.40.0",
+    "@voltro/env": "0.40.0",
+    "@voltro/protocol": "0.40.0",
+    "@voltro/runtime": "0.40.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.39.0",
+    "@voltro/testing": "0.40.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.0",
-    "@voltro/database": "0.39.0",
-    "@voltro/env": "0.39.0",
-    "@voltro/plugin-auth": "0.39.0",
-    "@voltro/protocol": "0.39.0",
-    "@voltro/runtime": "0.39.0",
-    "@voltro/sql-postgres": "0.39.0",
+    "@voltro/cli": "0.40.0",
+    "@voltro/database": "0.40.0",
+    "@voltro/env": "0.40.0",
+    "@voltro/plugin-auth": "0.40.0",
+    "@voltro/protocol": "0.40.0",
+    "@voltro/runtime": "0.40.0",
+    "@voltro/sql-postgres": "0.40.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.39.0",
+    "@voltro/testing": "0.40.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

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

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

package/templates/apps/api-backend-deactivation/package.json

@@ -13,16 +13,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.39.0",
-    "@voltro/database": "0.39.0",
-    "@voltro/env": "0.39.0",
-    "@voltro/plugin-deactivation": "0.39.0",
-    "@voltro/protocol": "0.39.0",
-    "@voltro/runtime": "0.39.0",
+    "@voltro/cli": "0.40.0",
+    "@voltro/database": "0.40.0",
+    "@voltro/env": "0.40.0",
+    "@voltro/plugin-deactivation": "0.40.0",
+    "@voltro/protocol": "0.40.0",
+    "@voltro/runtime": "0.40.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.39.0",
+    "@voltro/testing": "0.40.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

package/templates/apps/api-backend-mail/package.json

@@ -13,18 +13,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.39.0",
-    "@voltro/database": "0.39.0",
-    "@voltro/env": "0.39.0",
-    "@voltro/plugin-mail": "0.39.0",
-    "@voltro/plugin-multitenancy": "0.39.0",
-    "@voltro/protocol": "0.39.0",
-    "@voltro/runtime": "0.39.0",
+    "@voltro/cli": "0.40.0",
+    "@voltro/database": "0.40.0",
+    "@voltro/env": "0.40.0",
+    "@voltro/plugin-mail": "0.40.0",
+    "@voltro/plugin-multitenancy": "0.40.0",
+    "@voltro/protocol": "0.40.0",
+    "@voltro/runtime": "0.40.0",
     "effect": "^3.22.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.39.0",
+    "@voltro/testing": "0.40.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"