@voltro/cli 0.39.0 → 0.40.0

package/dist/{webhooksCommand-BVvOtZ1B.js → webhooksCommand-DubZWNOx.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-alhkKoEX.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-D8JSKlBM.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.0",
+  "version": "0.40.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -610,6 +610,18 @@
         "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.5.0",
         "id": "0.5.0/01_one-terminal-exactly-one",
@@ -697,22 +709,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.39.0",
-    "@voltro/cache": "0.39.0",
-    "@voltro/data-transfer": "0.39.0",
-    "@voltro/database": "0.39.0",
-    "@voltro/env": "0.39.0",
-    "@voltro/kv": "0.39.0",
-    "@voltro/logger": "0.39.0",
-    "@voltro/plugin-auth": "0.39.0",
-    "@voltro/plugin-broadcast": "0.39.0",
-    "@voltro/plugin-mail": "0.39.0",
-    "@voltro/plugin-storage": "0.39.0",
-    "@voltro/plugin-webhooks": "0.39.0",
-    "@voltro/protocol": "0.39.0",
-    "@voltro/runtime": "0.39.0",
-    "@voltro/serverless": "0.39.0",
-    "@voltro/workflow": "0.39.0",
+    "@voltro/ai": "0.40.0",
+    "@voltro/cache": "0.40.0",
+    "@voltro/data-transfer": "0.40.0",
+    "@voltro/database": "0.40.0",
+    "@voltro/env": "0.40.0",
+    "@voltro/kv": "0.40.0",
+    "@voltro/logger": "0.40.0",
+    "@voltro/plugin-auth": "0.40.0",
+    "@voltro/plugin-broadcast": "0.40.0",
+    "@voltro/plugin-mail": "0.40.0",
+    "@voltro/plugin-storage": "0.40.0",
+    "@voltro/plugin-webhooks": "0.40.0",
+    "@voltro/protocol": "0.40.0",
+    "@voltro/runtime": "0.40.0",
+    "@voltro/serverless": "0.40.0",
+    "@voltro/workflow": "0.40.0",
     "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.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.40.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | 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.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.40.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | 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/authentication.md

@@ -2143,10 +2143,19 @@ setTupleSource((req) =>
   loadResourceTuples(store, req.subjectId, req.resourceType, req.resourceId))
 ```
 
-`voltro dev` / `voltro serve` register exactly this default for you, reading
-`_voltro_rebac_tuples`. Register your own when your relationships already live
-in your own tables — a `teamMembers` row is a relation; you should not have to
-copy it into a framework table to authorize against it.
+`voltro dev` / `voltro serve` register this default for you, reading
+`_voltro_rebac_tuples` — **but only if you registered nothing**. Register your
+own when your relationships already live in your own tables: a `teamMembers` row
+is a relation; you should not have to copy it into a framework table to authorize
+against it. Yours wins, wherever you register it (`app.config.ts` or a
+`*.startup.tsx`), and the boot says so:
+
+```
+policy guards: using the app-registered tuple source
+```
+
+That line is worth knowing, because its absence is the diagnosis when your own
+source is not being consulted.
 
 **Every unanswerable case denies.** No tuple source registered, no policy for
 that `resourceType`, an input that doesn't identify a resource, a tuple source

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/routing.md

@@ -1150,6 +1150,46 @@ 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:
+
+```ts
+// middleware.ts — server-only. NOT app.config.ts, which is imported into the
+// client bundle whenever an api declares `authHeaders`.
+export default async (req) => {
+  const fresh = await refreshSession(req.cookies['sb-session'])
+  if (!fresh) return
+  return {
+    headers:    { authorization: `Bearer ${fresh.accessToken}` },
+    setCookies: [{ name: 'sb-session', value: fresh.cookie, maxAge: 3600 }],
+  }
+}
+```
+
+**Write the cookie back.** An IdP that rotates refresh tokens (Supabase does, and
+detects reuse) will invalidate the session if you renew server-side and leave the
+browser holding the consumed one. `setCookies` is not an optimisation.
+
+**It cannot redirect or refuse a request**, deliberately: authorization belongs
+on the api, which is the only thing that sees the data, and a web-side hook that
+could refuse would be a second authorization layer beside the real one. For a
+login redirect, throw `RedirectError` from the loader.
+
+Headers you return are merged over the request's, and only auth-shaped ones
+(`authorization`, `x-tenant`, `x-voltro-*`) are forwarded to the api. Cookies
+default to `HttpOnly`, `Path=/`, `SameSite=lax`. The file is loaded once per
+boot; if it throws, the request fails rather than rendering with the credential
+you asked to replace.
+
 ## Errors from loaders
 
 If the loader throws, the framework: