@voltro/plugin-audit 0.39.1 → 0.40.0

package/CHANGELOG.md

@@ -39,6 +39,164 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.40.0] — 2026-08-16
+
+### ⚠ BREAKING
+
+- **@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.
+
+  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:
+
+  > 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.
+
+  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.
+
+  `failed` is a positive discriminant, so the check reads as one:
+
+  ```tsx
+  if (s.loading) return <Skeleton/>
+  if (s.failed)  return <RetryPanel error={s.error}/>
+  return <Table rows={s.data}/>
+  ```
+
+  **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.
+
+  **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.
+
+  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`.
+
+  Measured by a consumer: a user's tab outlived their IdP's token lifetime. The strategy logged it plainly —
+
+  ```
+  WARN auth strategy "supabase" rejected request: supabase jwt expired
+  WARN mutation.tasks.update failed: missing required scope 'task:u:o'
+  ```
+
+  — 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.
+
+  **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.
+
+  Three details worth knowing if you touch it:
+
+  - **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.
+
+  A caller who presented NO credential still gets `ScopeError`. Collapsing both would send a genuinely under-privileged user to the login page.
+
+  **Why this is BREAKING although nothing was removed.** Three published results gained a union member:
+
+  ```ts
+  checkGuards(…)        // ScopeError | Unauthenticated | null   (was ScopeError | null)
+  checkGuardsEffect(…)  // Effect<ScopeError | Unauthenticated | null>
+  bindEvent(…)          // Stream<…, ScopeError | Unauthenticated, …>
+  ```
+
+  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.
+
+  `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.
+
+### Added
+
+- **@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.
+
+  `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.
+
+  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.
+
+  `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.
+
+  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.
+
+  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.
+
+  ```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 }],
+    }
+  }
+  ```
+
+  **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.
+
+  **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.
+
+  **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`.
+
+  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.
+
+  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.
+
+  `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.
+
+  **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.
+
+  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:
+
+  ```ts
+  const seen = ctx.eventBus.subscribe(orderPlaced, { orderId })
+  await invoke(placeOrder, executor, input, ctx)
+  expect(seen.received).toHaveLength(1)
+  ```
+
+  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.
+
+### Fixed
+
+- **@voltro/cli** — `voltro agents-md --force` no longer exits 0 when it wrote nothing.
+
+  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 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.
+
+  Failures are collected and reported now, and the command **exits 1** when the seed is incomplete:
+
+  ```
+  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.
+  ```
+
+  `--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.
+
+  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`.
+
+  `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.
+
+  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.
+
+  **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.
+
+  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`.
+
+  Measured by a consumer over the wire, same session, same foreign team:
+
+  | 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'` ✓ |
+
+  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.
+
+  **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.
+
+  `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.
+
+  **Two more error classes were collapsed the same way, and neither was reported:**
+
+  - **`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".
+
+  `openAccess:` still merges nothing: a procedure advertising a denial it cannot produce is what makes an error union stop meaning anything.
+
+  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.
+
+---
+
 ## [0.39.1] — 2026-08-16
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-audit",
-  "version": "0.39.1",
+  "version": "0.40.0",
   "description": "Audit plugin — ships the `audit()` schema mixin (createdAt/updatedAt/createdBy/updatedBy → Actor) plus an optional mutation interceptor that records every call to a configurable sink (console / memory / custom function).",
   "keywords": [
     "voltro",
@@ -38,9 +38,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.39.1",
-    "@voltro/logger": "0.39.1",
-    "@voltro/protocol": "0.39.1"
+    "@voltro/database": "0.40.0",
+    "@voltro/logger": "0.40.0",
+    "@voltro/protocol": "0.40.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"