@voltro/cli 0.11.4 → 0.13.0

package/templates/agent-docs/database/migrations.md

@@ -2600,6 +2600,38 @@ export const users = table('users', {
 
 The planner folds the diff into one `ALTER TABLE users RENAME COLUMN firstName TO givenName`, classified `safe`. After the rename is applied in every env, the marker can be removed (covered in [rename-and-drop.md](./rename-and-drop.md)).
 
+## "the migration did not converge" (apply refuses to record a fingerprint)
+
+```
+applyPlan: the migration did not converge. 31 operation(s) were executed without
+error, but re-planning against the live schema still finds 31:
+  - alter-column-default todos.attachments
+  …
+No fingerprint was recorded — recording one would make the next boot report
+"schema up to date" for a schema that was never applied.
+```
+
+Every statement ran and the database accepted every one of them, and none of them
+changed anything. That is possible because DDL that changes nothing succeeds
+exactly as quietly as DDL that works — `ALTER COLUMN x TYPE text` on a column
+that is already `text` is a valid, successful no-op.
+
+This message exists because the alternative is worse. Before the convergence
+check, such a plan reported `applied 31 op(s)`, recorded a fingerprint, and every
+later boot short-circuited on "schema up to date" — for a schema that had never
+been applied. One app ran that way for two releases. The apply now proves it
+worked before it records anything: the same planner, run against the database as
+it now is, must have nothing left to do.
+
+**It is a framework bug, not a mistake in your schema.** The named operations
+emit DDL that does not take effect. Report the operation kinds plus the column
+types involved. In the meantime the schema is unchanged and safe — nothing was
+half-applied, and no fingerprint was written, so `voltro db plan` still shows you
+the truth.
+
+If you need to move forward before a fix lands, apply the equivalent DDL by hand
+and re-run `voltro db plan` to confirm it converges.
+
 ## "Schema fingerprint mismatch" (prod refuse)
 
 Full error:

package/templates/agent-docs/database/transactions.md

@@ -235,6 +235,37 @@ The `where` predicate is a regular [Predicate](/docs/database/query-builder#pred
 AST — same shape `.where()` uses. Sub-queries via `inSubquery` /
 `exists` are supported.
 
+### Typed: `updateManyRow`
+
+`updateMany` takes a string table name and an untyped patch, so a misspelled
+column or a wrongly-typed value is only found by the database — or not at all,
+if the column happens to exist. `updateManyRow` takes the TABLE OBJECT instead
+and checks the patch against the row type:
+
+```ts
+import { updateManyRow, eq } from '@voltro/database'
+
+await updateManyRow(ctx.store, posts, { hidden: true }, {
+  where: eq('userId', bannedId),
+})
+
+await updateManyRow(ctx.store, posts, { hiddne: true }, { where: … })
+//                                      ^^^^^^^ compile error: not a column
+```
+
+It is worth using rather than the string form, and the evidence is concrete: one
+app migrating 29 `store.upsert` call sites to the typed `upsertRow` got 15 `tsc`
+errors across 8 distinct defects that no test had caught — including seven
+per-user mutations with no authentication check at all, which wrote
+`ctx.request.subject.id` (typed `string | null`) into a NOT NULL column, so an
+anonymous caller reached the database and got a raw statement failure instead of
+a typed refusal.
+
+The subtlest one is the most persuasive: a value spread from a plain object
+literal widens to `string`, and a column's `.oneOf()` union rejects it even
+though the value IS one of the members. Neither a reviewer nor a test would
+plausibly find that; only the row type asks the question. (`as const` fixes it.)
+
 ### Reactivity
 
 `updateMany` emits ONE ChangeEvent per affected row, so reactive

package/templates/agent-docs/scheduling.md

@@ -208,7 +208,15 @@ timezone: 'Europe/Berlin'   // 09:00 Berlin — DST handled by effect's Cron
 
 ## The handler context
 
-The handler receives a `ScheduleContext` — the same `app` a mutation gets, plus firing metadata:
+The handler receives a `ScheduleContext` — the same `app` a mutation gets, plus firing metadata.
+
+> **The API is identical; the subject is not.** `ctx.app.store` here is **not
+> tenant-scoped** — a schedule runs as `system` with no tenant. Reads see every
+> tenant's rows, and a write to a `tenant()` table fails with
+> `TenantScopeViolation` unless you pass `tenantId` explicitly. See
+> [below](#a-schedule-runs-as-the-system-subject--no-tenant). This sentence is
+> here rather than only further down because "same shape as a mutation" is what
+> sets the expectation that gets violated.
 
 ```tsx
 handler: async (ctx) => {
@@ -250,6 +258,32 @@ Writes to a `tenant()` table need the same treatment: pass `tenantId`
 explicitly, or the write fails with `TenantScopeViolation` rather than landing
 somewhere arbitrary.
 
+### `ctx.app.storeForTenant(id)` — the fan-out shortcut
+
+Doing that by hand means every `.where('tenantId', …)` and every explicit
+`tenantId:` is one forgotten call away from reading or writing across tenants.
+`storeForTenant` hands you a store scoped to exactly one:
+
+```tsx
+handler: async (ctx) => {
+  for (const t of await ctx.app.store.select('tenants').all()) {
+    const scoped = ctx.app.storeForTenant(t.id)
+    await scoped.insert('digests', { body: summary })   // tenantId stamped, not passed
+  }
+}
+```
+
+Inside a REQUEST this is almost always the wrong tool — the subject already
+carries a tenant, and reaching for another one is a cross-tenant access with
+extra steps. It exists because the system subject has *no* tenant to infer.
+
+One implementation detail worth knowing, because it is counter-intuitive: the
+scoped store does **not** run as a `system` subject with a tenant attached. A
+system subject carries `tenantId: null` by construction and the tenant mixin
+special-cases it to skip scoping entirely — on a system subject, a null tenant
+means *all* tenants. So the scoped view runs as a `serviceAccount` bound to that
+one tenant, keeping the schedule's scopes.
+
 This behaves identically under `voltro dev` and `voltro serve`. It did not
 always — before 0.10.0, dev scoped schedules to `$TENANT` (default `acme`)
 while production ran them unscoped, so the same cron read one tenant in

package/templates/agent-docs/security.md

@@ -22,6 +22,54 @@ Please report suspected vulnerabilities **privately** — never in public issues
 
 You'll get an **acknowledgement within 3 business days**, an assessment once we've reproduced the issue, and a **coordinated disclosure** timeline agreed with you — with credit in the release notes if you'd like it. We don't run a paid bug-bounty program yet, but we genuinely value responsible disclosure.
 
+## Outbound HTTP is SSRF-guarded by default
+
+The `HttpClient` your handlers `yield*` refuses internal targets:
+
+- loopback, RFC-1918, CGNAT and link-local addresses — including the
+  `169.254.169.254` cloud-metadata endpoint
+- the hostnames `localhost`, `*.internal`, `*.local`
+- any non-`http(s)` scheme
+
+**Every redirect hop is revalidated, not just the URL you passed.** A public URL
+that `302`s to the metadata endpoint is the actual attack; checking only the
+initial target catches none of it.
+
+This matters because a caller-supplied URL is ordinary product surface — a
+scraper, a webhook-registration form, an importer, a "test this connection"
+button. Those reach `HttpClient` with whatever the user typed.
+
+### Allowing a target on purpose
+
+```ts
+// app.config.ts
+export default defineApiConfig({
+  http: { allowHosts: ['*.svc.cluster.local', 'billing.internal'] },
+})
+```
+
+An entry may be an exact host, a `*.suffix` wildcard (which does **not** match the
+apex — one that did would silently widen your exception), or `host:port` when only
+one port should be reachable.
+
+There is no boolean off-switch, deliberately: *"we call one internal service"* and
+*"we do not check URLs"* are different postures, and a boolean cannot tell them
+apart six months later.
+
+### In tests, allow the stub — don't mock the guard
+
+Use the same `allowHosts` to reach a local stub server (`['127.0.0.1:8787']`).
+That keeps the test on the real guarded code path with a narrow exception. Mocking
+the guard away instead means the production path is never exercised — which is
+exactly how this framework's own webhook delivery once ended up behind a
+`NODE_ENV` check.
+
+### What this does NOT cover
+
+DNS is not resolved. A public hostname that *resolves* to a private address (DNS
+rebinding) still passes. That vector needs network-layer egress control; it is
+stated here rather than silently implied.
+
 ## Supply-chain assurance
 
 Every release passes automated supply-chain gates in CI before a single package is published:

package/templates/agent-docs/templates/apibackends.md

@@ -2615,9 +2615,9 @@ done
 <!-- source: en/templates/api-rbac.md -->
 ## API · RBAC
 
-_Role-based access control with @voltro/plugin-rbac — a role→scope map, an interceptor that resolves the caller's roles to scopes, and an in-handler permission(ctx, 'notes:write') guard that fails typed ScopeError. admin:full bypasses. Config-only, zero infra; useCan() for web UI._
+_Role-based access control with @voltro/plugin-rbac — a role→scope map, an interceptor that resolves the caller's roles to scopes, declarative descriptor guards (statically checked by voltro check), resource-scoped guards, and the in-handler permission()/can() guards. admin:full bypasses. Config-only, zero infra._
 
-Roles → scopes → guards. `@voltro/plugin-rbac` compiles a role map and an rpc interceptor resolves each caller's **roles** to **scopes**, stamped on the subject. Guard handlers with `permission(ctx, 'notes:write')`, the Effect-native guard that fails typed `ScopeError`. The `admin:full` scope is a blanket bypass. Config-only, zero infra. Template id: **`api-rbac`**.
+Roles → scopes → guards. `@voltro/plugin-rbac` compiles a role map, and an rpc interceptor resolves each caller's **roles** into **scopes** published to the framework's effective-scope seam. From there both authorization forms see them. The `admin:full` scope is a blanket bypass. Config-only, zero infra. Template id: **`api-rbac`**.
 
 ## Scaffold
 
@@ -2627,40 +2627,99 @@ voltro create-project acme --api=api-rbac
 
 ## Roles as config
 
-```ts
-// app.config.ts
-import { rbacPlugin } from '@voltro/plugin-rbac'
+The role map is the app's **declared scope vocabulary**, not just a lookup table: `rbacPlugin` publishes the union of it, and [`voltro check`](/docs/cli/overview) fails on any descriptor guard requiring a scope that appears nowhere in it.
 
-const roles = {
+```ts
+// authz.ts — split out of app.config.ts so tests build the real plugin
+export const roles = {
   viewer: ['notes:read'],
   editor: ['notes:read', 'notes:write'],
-  admin:  ['admin:full'],                 // blanket bypass — passes every check
+  owner:  ['notes:read', 'notes:write', 'notes:delete', 'teams:rename'],
+  admin:  ['*'],                          // wildcard → admin:full blanket bypass
 }
+```
+
+```ts
+// app.config.ts
+import { rbacPlugin } from '@voltro/plugin-rbac'
+import { demoRolesForTenant, roles, rolesOnTeam } from './authz'
 
 rbacPlugin({
   roles,
   // PRODUCTION: the default resolver reads subject.metadata.roles (set by your
   // auth strategy), or do a DB lookup. The shipped DEMO maps tenant → role so
-  // you can try each via the x-tenant header with zero auth setup:
-  resolveRoles: (subject) =>
-    ({ acme: ['admin'], editors: ['editor'], readers: ['viewer'] })[subject.tenantId ?? ''] ?? ['viewer'],
+  // you can try each via the x-tenant header with zero auth setup.
+  resolveRoles: (subject) => demoRolesForTenant(subject.tenantId),
+  // PER-RESOURCE roles — see "Resource-scoped guards" below.
+  resolveResourceRoles: (subject, resource) => rolesOnTeam(subject.id, resource),
 })
 ```
 
-## Guard with `permission()`
+## Two guard forms — prefer the declarative one
 
 ```ts
-// notes.create.mutation.server.ts
-import { permission } from '@voltro/plugin-rbac'
+// notes.create.mutation.ts — DECLARATIVE, on the descriptor
+export const createNote = defineMutation({
+  name: 'notes.create',
+  target: { table: 'notes', op: 'insert' },
+  guards: [{ scope: 'notes:write' }],
+  input: Schema.Struct({ title: Schema.NonEmptyString, body: Schema.String }),
+  output: Schema.Struct({ id: Schema.String, title: Schema.String }),
+})
+```
+
+The framework enforces this in the dispatch spine — before the executor, and before a mutation's transaction opens — so an unauthorized call never touches the DB. Declaring `guards:` also merges `ScopeError` into the wire error union automatically, so no `error:` field is needed and the client still decodes the denial typed. Reads take guards too, re-checked on every delivery, so a revoked role stops a live subscription.
 
+The reason to prefer it is **static checkability**: a declarative guard lands in the capability manifest, so `voltro check` catches a scope no role grants. An in-handler call is invisible to that check.
+
+```ts
+// notes.delete.mutation.server.ts — IN-HANDLER, for what needs the loaded row
 export default (input, ctx) => Effect.gen(function* () {
-  yield* permission(ctx, 'notes:write')       // fails typed ScopeError for viewer
   const store = yield* EffectStore
-  return yield* store.insert('notes', { title: input.title, body: input.body })
+  const rows = yield* Effect.promise(() =>
+    ctx.store.query(database.notes.where(eq('id', input.id)).limit(1).descriptor))
+  const note = rows[0]
+  if (note === undefined) return yield* Effect.fail(new NoteNotFound({ id: input.id }))
+
+  // Only decidable AFTER the row is loaded — no descriptor guard can express it.
+  const hard = note['archived'] === true || can(ctx, 'notes:purge')
+  if (hard) { yield* store.delete('notes', input.id); return { id: input.id, mode: 'hard' } }
+  yield* store.update('notes', input.id, { archived: true })
+  return { id: input.id, mode: 'soft' }
 })
 ```
 
-Declare `error: ScopeError` (from `@voltro/protocol`). Companions: `anyPermission(ctx, [...])` (OR), `assertPermission` (sync throw), `can(ctx, scope)` (boolean).
+Rule of thumb: put in `guards:` everything decidable from the **subject** and the **input**; reach for `permission()` / `can()` only for what needs loaded data. Companions: `anyPermission(ctx, [...])` (OR), `assertPermission` (sync throw), `can(ctx, scope)` (boolean, branches instead of refusing).
+
+## Resource-scoped guards
+
+`guards: [{ scope, resource }]` makes a grant mean "owner **of this team**" instead of "owner globally".
+
+```ts
+// teams.rename.mutation.ts
+guards: [{ scope: 'teams:rename', resource: (input: { teamId: string }) => input.teamId }],
+```
+
+The `resource` extractor pulls the id out of the decoded input; rbac's `resolveResourceRoles` returns the roles the caller holds on that id, compiled through the same role map. A **globally** held scope (or `admin:full`) satisfies the guard without the resolver ever being called — only the gap falls through. That fall-through is **fail-closed**: a resolver that throws or rejects denies, it does not degrade to the global answer.
+
+## Failure postures, deliberately different
+
+| Resolver | On throw / reject |
+| --- | --- |
+| `resolveRoles` / `resolvePermissions` | logs, degrades to the subject's **own** scopes — never grants, but an api key with valid scopes still works |
+| `resolveResourceRoles` | **denies** (fail-closed) |
+
+Both hold for a synchronous throw as well as a rejected promise.
+
+## Static check
+
+```bash
+voltro check --offline      # no running app needed — usable as a CI gate
+```
+
+A guard requiring `notes:wirte` when the roles grant `notes:write` is not merely misconfigured: that procedure is permanently, silently uncallable by everyone. `voltro check` reports it as `rbac/unknown-scope` and exits non-zero.
+
+The registry stays **dormant** when a custom `resolvePermissions` is configured — that resolver merges scopes from outside the role map by design, so publishing the map alone would flag correct code.
 
 ## Try it
 
@@ -2676,6 +2735,18 @@ curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json
 # → { ok:false, error:{ _tag:"ScopeError", required:"notes:write" } }
 ```
 
+## Testing authorization
+
+The shipped `tests/authz.test.ts` drives the **real** plugin: `makeTestContext({ plugins: [rbacPlugin({ roles, … })] })` composes the actual interceptor chain, and `invoke` enforces the descriptor's guards with the same function the serve pipeline calls.
+
+```ts
+const ctx = makeTestContext({ subject, store: mockStore({ notes: [] }), plugins: [plugin()] })
+await expect(invoke(createNote, createNoteHandler, { title: 'x', body: '' }, ctx))
+  .rejects.toMatchObject({ _tag: 'ScopeError', required: 'notes:write' })
+```
+
+Do **not** hand-set `subject.scopes` to the value you expect. That tests the guard while assuming the resolution which produces it — and the resolution is the half that actually breaks (a renamed role, a throwing resolver, a scope no role grants). Those all pass a pre-stamped test and fail a real one.
+
 ## On the web side
 
 ```tsx
@@ -2686,7 +2757,7 @@ const canWrite = useCan('notes:write')
 {canWrite && <NewNoteButton />}      // hide affordances the user can't use
 ```
 
-The UI gate ships in [`@voltro/client`](/docs/ui/client-utilities/use-can), not in the plugin: scopes are a framework concept, so gating a button must not require an rbac dependency. `useCan` is a UI affordance only — the server `permission()` guard is the enforcement.
+The UI gate ships in [`@voltro/client`](/docs/ui/client-utilities/use-can), not in the plugin: scopes are a framework concept, so gating a button must not require an rbac dependency. `useCan` is a UI affordance only — the server guard is the enforcement.
 
 ## Persisted roles
 
@@ -2695,6 +2766,8 @@ Set `tables: true` to store assignments in `roles` / `userRoles` tables and reso
 ## Anti-patterns
 
 - **Returning scopes from `resolveRoles`.** It returns role SLUGS (`['editor']`); the `roles` map turns those into scopes. Returning scopes directly bypasses the map.
+- **Re-checking a descriptor guard inside its own executor.** Two copies of one rule, and the copy `voltro check` reads is the descriptor's.
+- **Reaching for `permission()` when `guards:` would do.** It works, but it opts that procedure out of the static check.
 - **Scopes ≠ entitlements.** RBAC answers "may you call this"; billing entitlements (see [`api-saas`](/docs/templates/api-saas)) answer "do you have quota left". A procedure can need both.
 
 

package/templates/agent-docs/testing.md

@@ -66,6 +66,30 @@ voltro e2e     # boot api + web siblings, run tests, tear down
 
 _makeTestContext — the in-memory request ctx for handler and tool tests. The real mixin-wrapped store, mockStore seeding, subject/tenant re-scoping, and the deterministic clock / email / LLM mocks._
 
+## tsconfig `paths` aliases
+
+`voltro test` derives Vite's `resolve.alias` from your app's tsconfig
+`compilerOptions.paths`, so an app that maps `@/* → ./src/*` can test modules
+that import through it without any extra config:
+
+```jsonc
+// tsconfig.json
+{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./src/*"] } } }
+```
+
+```ts
+import { greeting } from '@/locales/en'   // resolves under `voltro test`
+```
+
+Before this, the first person to write a test for each aliased file discovered
+`Cannot find package '@/locales/en' imported from src/lib/i18n.ts` — one file at
+a time — and worked around it with a local `vitest.config.ts` restating what
+tsconfig already said. The dev and build pipelines resolve these already (your
+app runs), so the test runner disagreeing with them was a gap, not a policy.
+
+A project-local `vitest.config.ts` still merges on top, so an app that already
+wrote the workaround keeps working.
+
 ## `makeTestContext`
 
 `makeTestContext(options?)` returns an **`AppContext`** — the exact `ctx` a mutation / query / action / tool executor receives at runtime — with the deterministic test doubles added on top. Because it *is* an `AppContext`, you pass it straight into a handler: `await myHandler(input, makeTestContext({ … }))`. The acting subject is at `ctx.request.subject`; `ctx.store` is the **real** mixin-wrapped store backed by an in-memory data store (so tenant auto-scoping, soft-delete filtering, audit auto-fill, and the fluent `select` / `update` / `delete` builders behave exactly as in production); `ctx.cache` is a real in-memory cache whose TTLs honour `ctx.clock`.

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

@@ -0,0 +1,81 @@
+# What's new in 0.13.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
+about to hand-roll — the failure this section exists for is a team building a
+workaround for something that shipped two versions ago.
+
+BREAKING entries name a codemod; run `voltro update` to apply it.
+
+### ⚠ BREAKING
+
+- **@voltro/protocol, @voltro/plugin-scim, @voltro/plugin-prometheus** — SCIM was served UNAUTHENTICATED whenever its token was an empty string.
+
+  `checkBearer(headers, expected)` returned `true` when `expected` was unset or empty, documented as "no token configured = open; the caller decided not to gate this surface". Its one production caller had decided the opposite: `scimPlugin` declares `token: string`, and `scimPlugin({ token: process.env.SCIM_TOKEN ?? '' })` — the shape anyone writes — turned the gate off silently. The result was SCIM 2.0 Users and Groups readable with no credentials: a full directory dump plus the provisioning surface that can deactivate accounts. Likeliest exactly where it hurts, too: an env var set in production and missing in a preview environment.
+
+  `checkBearer` is now fail-closed by default, with the permissive behaviour available as an explicit `{ openWhenUnset: true }` — a two-argument helper cannot know its caller's intent, so it must not assume the permissive one. `@voltro/plugin-prometheus` passes it (its token is documented as optional), and `scimPlugin` now throws at construction — i.e. at boot — rather than answering the first anonymous request.
+- **@voltro/database, @voltro/cli** — `voltro db apply` and boot auto-migrate could report success while applying nothing, and then record a fingerprint that made every later boot short-circuit on "schema up to date".
+
+  Reported from a live pod: `applied 31 op(s)` on every boot for two releases, with none of the 31 present in the database. Nothing was wrong with the transport, the lock or the transaction — the applier emitted statements that postgres accepted and that changed nothing. Two independent causes:
+
+  - A `ColumnSnapshot` carried no `vector` dimension / `array` element / `enum` name, so the applier's type renderers collapsed all three to `text`. A declared `vector(1536)` over a live `text` column planned an `alter-column-type` that emitted `ALTER COLUMN … TYPE text`. Valid, applied, no-op, re-planned forever. (Also meant an `add-column` for a vector, array, enum or PostGIS column created a plain `text` column.) - The default-clause renderers excluded ARRAYS, returning `null`, and the call site turned that into `SET DEFAULT NULL`. A declared `.default([])` on a `json()` column therefore never landed — thirty columns were stuck this way in the reporting schema.
+
+  Fixed: the snapshot carries the type parameters and the renderers delegate to `migrate.ts`'s canonical `sqlType`, so the applier and the CREATE-TABLE emitter cannot disagree; array defaults render (a real `text[]` literal on a native `array()` column, a jsonb literal otherwise); and a default the renderer cannot express now FAILS instead of degrading to `DEFAULT NULL`.
+
+  And the structural guard, which is the part that matters: **`applyPlan` re-plans against the live schema before it records a fingerprint, and refuses to record one if any operation remains.** DDL that changes nothing succeeds exactly as quietly as DDL that works, so the only evidence a plan applied is that the same planner has nothing left to do. `ApplyPlanCtx` gains a required `replan`; `AppliedMigration` gains `appliedOps` (what EXECUTED, not `plan.operations.length`), and the boot log quotes that.
+- **@voltro/plugin-storage** — `storage.share`, `storage.revoke` and `storage.listGrants` performed no authorization at all.
+
+  Each took an object id straight off the wire and passed it to a service method that (correctly, for a trusted server-side API) checks nothing, with nothing in between. Any authenticated caller could grant themselves read or write on any object in the installation, revoke anyone else's grants, and enumerate who an object is shared with.
+
+  All three now require that the caller owns the object, or carries `admin:full`. A missing object and an unowned object report the same 403 — a 404 would let an unauthorized caller probe which ids exist. `GrantStore` gains `getById`, which `revoke` needs to resolve a grant id back to its object.
+
+### Added
+
+- **@voltro/runtime, @voltro/database** — API keys carry app-owned `metadata` — the second ownership axis.
+
+  `tenantId` and `onBehalfOf` are the two relationships the framework models. Plenty of apps have a third that actually authorizes the key: a team, a project, an environment. `ApiKeyRecord` in `@voltro/protocol` has carried a `metadata` slot all along — its doc comment even names `teamId` as the example — but the SERVICE had nowhere to store it and nowhere to return it. So an app with a team axis could authenticate through the built-in strategy and still not authorize, and `apiKeys: true` was unusable for it. Reported as the one thing that stopped an otherwise complete adoption; their alternatives were a second table joined on the hot auth path, or smuggling `team:<id>` into `scopes`, where `hasScope` would then see a scope that is not a scope.
+
+  `IssueInput`, `ApiKeyRow` and `ResolvedApiKey` now carry it, stored as JSON on `_voltro_api_keys`, and it survives `rotate` — a rotated key is the same credential with a new secret, so dropping it would silently de-authorize every rotated key.
+
+  It is app data, never identity. The strategy merges it UNDER the framework's own claims: `provider` and the acting `userId` are written afterwards from `onBehalfOf` and always win, including when the answer is "none". A bag that could set `userId` would let whoever minted the key choose who the request is. Pinned end-to-end, not just at the protocol layer.
+
+  `PublicApiKey` also gains `createdBy` and `onBehalfOf`, so `service.list` can answer the two questions an admin actually asks about a shared credential. Neither is a secret — they are the accountability record, and omitting them hid them from the person responsible for the key.
+- **@voltro/protocol, @voltro/cli** — A boot warning when two auth strategies claim the same bearer-token prefix.
+
+  The chain is first-match-wins, so a duplicate claim is not a harmless redundancy: whichever strategy runs first decides the Subject. An app that already has its own `sk_` keys and then sets `apiKeys: true` gets the framework strategy appended on the same prefix — resolving without the app's own team binding — and *which strategy answered* decides whether authorization works. Reported by an app that had to pin a test asserting it never enables the flag.
+
+  `AuthStrategy` gains an optional `claimsBearerPrefix`, set by `apiKeyStrategy` from its `prefix` option. Making the claim declarative is what makes the collision detectable at all — the same "only what is declared can be checked" argument the scope rules run on. Checked in `buildResolveSubject`, which both `voltro dev` and `voltro serve` call, so the two boot paths cannot drift.
+
+  A warning rather than a refusal: two strategies on one prefix can be deliberate (a migration window where old and new keys share a shape). What must not happen is that it goes unmentioned.
+- **@voltro/protocol, @voltro/cli** — `auth.resolveScopes` — add scopes to an authenticated Subject from your own data, so ROLE-based authorization becomes declarable.
+
+  An app whose authorization is a database role (`requireCallerAdmin(ctx)` reading an `employees.role` column) is invisible to every static check the framework has: `voltro check`'s `rbac/unguarded-mutation` reports its writes as unguarded, and it is right to — nothing about the decision is declared. But the declarative alternative was unusable for exactly those apps: their subjects come from an external IdP's JWTs and carry no scopes, so `requireScope('employee:admin')` would lock out every real user. One app measured 1566 findings it had no way to act on.
+
+  Lifting the role into `subject.scopes` makes the SAME authorization declarable, visible in the manifest and checkable in CI. Deliberately narrow: the hook returns SCOPES, never a Subject — it cannot change `id` or `tenantId` (identity belongs to the auth strategy), and the result is unioned with the strategy's own scopes, so it can grant but never revoke. It runs per matched request, so cache the lookup yourself; the framework does not, because only the app knows how fast a role change must take effect. Wired identically in `voltro dev` and `voltro serve`.
+- **@voltro/cli** — `voltro doctor` reports packages resolved at more than one version.
+
+  A consumer reported type errors inside the GENERATED `rpcGroup.generated.ts` — `Property '[TypeId]' is missing`, `typeof Never is not assignable to All`, an `Rpc<…, Stream<…>, …>` refused where `Any` was expected — and reasonably concluded the framework emits bad types, because the errors land in a file they cannot edit and did not write. That is the signature of two copies of `effect` in one install: Effect's types are nominal, so a Schema built by one copy is not the type the other expects.
+
+  It deserves its own check because the RUNTIME usually stays green — two instances only diverge where identity matters — so an app boots, serves and passes its tests while `tsc` is red, which sends people looking at the compiler instead of the dependency tree. The report names the versions, the paths, and the errors it explains. Only identity-sensitive packages count (`effect`, `@effect/*`, `@voltro/*`, react/react-dom); a duplicated string utility is wasteful, not a bug class.
+- **@voltro/cli** — `voltro doctor` flags an executor that never names its own descriptor.
+
+  Descriptor/executor pairing is by FILENAME, which is right — and it means a `*.server.ts` can be a complete, correct executor with no reference at all to the contract it implements. Those are exactly the files where a hand-written input drifts from the wire.
+
+  Reported after a 426-executor migration to `ExecutorInput<typeof descriptor>`: three files were skipped by the app's own codemod for a reason no reviewer would guess — they never imported their descriptor, so there was no `typeof` to point at. In the same codebase, six executors had written `boardPurpose: string` where their descriptor declared `Schema.Literal(...)`, discarding the contract at the executor boundary. Only imports of a SIBLING module clear the finding: an executor importing nothing but `@voltro/*` and `node:*` has still not named its contract.
+- **@voltro/database** — `updateManyRow(store, table, patch, { where })` — the last untyped write is now typed against its table.
+
+  `insertRow` and `upsertRow` already were; `ctx.store.updateMany(table, row, { where })` still took a string table name and an untyped row literal. Worth closing because the typed versions were measured: migrating 29 `store.upsert` call sites to `upsertRow` produced 15 `tsc` errors across 8 distinct defects that no test had caught — including seven per-user mutations with no authentication check at all (they wrote `ctx.request.subject.id`, typed `string | null`, into a NOT NULL column, so an anonymous caller reached the database and got a raw statement failure instead of a typed refusal).
+
+### Fixed
+
+- **@voltro/runtime** — A `cache:` declared on a query whose handler returns a COMPUTED value was silently ignored; it now says so.
+
+  The snapshot cache wraps the store read, and a computed query has none — its handler has already run by the time the binding is built. Caching one would mean wrapping the handler invocation, which is a different feature. Until that exists, the honest failure is a loud one: silently ignoring the config is how an author ends up believing a hot query is cached while every subscriber re-runs it. The data stays correct, so nothing else would ever tell them. Warned once per query name, not per subscribe.
+- **@voltro/cli** — The minted `.env.local` is handed to the workspace's owner, and an unreadable env file explains itself.
+
+  A dev container running as root with the host workspace bind-mounted wrote `apps/api/.env.local` as `root:root 0600` INTO THE SHARED WORKSPACE. On the host, everything that loads env then died with EACCES — vitest, `voltro doctor`, the editor — and the developer could not even read the file, while the next container boot recreated it. Container-with-bind-mount is the ordinary dev shape, not an edge case.
+
+  `0600` stays (the file holds a real signing key), because loosening it to `0644` would make that key readable by every account on the machine for the far more common single-user case. Ownership was the wrong variable, so that is the one corrected: the mint chowns the file to whoever owns the directory, which root can do — exactly the case that needs it — and reports loudly when it cannot. A plain EACCES while loading an env file now names the owning uid, the mode and the current uid, because that pair IS the diagnosis and none of it appears in node's message.
+- **@voltro/cli** — Four tooling fixes, all from downstream reports:
+
+  - **`voltro check --offline` crashed on any app that declares a workflow.** It built workflow entries as `{ name }` behind an `as never` while `InspectWorkflowEntry` is keyed by `tag`, so the manifest's sort read `undefined` and threw — surfacing as "could not assemble the graph from source" rather than the type error underneath. The cast is what let the two shapes disagree. - **`voltro check --offline` reported plugin tables as `dangling-source`.** It collected only the app's own `*.entity.ts` tables, so a query reading `_voltro_storage_refs` was an `error` — which sets the exit code, failing the CI gate the offline mode exists for. It now uses the same `assembleFrameworkTables` the migrator does. - **`voltro test` now derives `resolve.alias` from the app's tsconfig `paths`.** An app mapping `@/* → ./src/*` could not test any module importing through it (`Cannot find package '@/locales/en'`), and the workaround was a local `vitest.config.ts` restating what tsconfig already said. - **The `raw-fetch` doctor rule follows the import graph.** Keyed on filename conventions it caught 9 of 39 outbound calls on the reporting app; the other 30 were in `lib/*.ts` helpers only server code imports. A file reachable from a server-convention file and from nothing else is server code; one a page also imports is not, and stays unflagged.

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

@@ -11,16 +11,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/ai": "0.11.4",
-    "@voltro/cli": "0.11.4",
-    "@voltro/database": "0.11.4",
-    "@voltro/env": "0.11.4",
-    "@voltro/protocol": "0.11.4",
-    "@voltro/runtime": "0.11.4",
+    "@voltro/ai": "0.13.0",
+    "@voltro/cli": "0.13.0",
+    "@voltro/database": "0.13.0",
+    "@voltro/env": "0.13.0",
+    "@voltro/protocol": "0.13.0",
+    "@voltro/runtime": "0.13.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.4",
+    "@voltro/testing": "0.13.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,17 +12,17 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.11.4",
-    "@voltro/database": "0.11.4",
-    "@voltro/env": "0.11.4",
-    "@voltro/plugin-auth": "0.11.4",
-    "@voltro/protocol": "0.11.4",
-    "@voltro/runtime": "0.11.4",
-    "@voltro/sql-postgres": "0.11.4",
+    "@voltro/cli": "0.13.0",
+    "@voltro/database": "0.13.0",
+    "@voltro/env": "0.13.0",
+    "@voltro/plugin-auth": "0.13.0",
+    "@voltro/protocol": "0.13.0",
+    "@voltro/runtime": "0.13.0",
+    "@voltro/sql-postgres": "0.13.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.4",
+    "@voltro/testing": "0.13.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.11.4",
-    "@voltro/database": "0.11.4",
-    "@voltro/env": "0.11.4",
-    "@voltro/plugin-multitenancy": "0.11.4",
-    "@voltro/protocol": "0.11.4",
-    "@voltro/runtime": "0.11.4",
+    "@voltro/cli": "0.13.0",
+    "@voltro/database": "0.13.0",
+    "@voltro/env": "0.13.0",
+    "@voltro/plugin-multitenancy": "0.13.0",
+    "@voltro/protocol": "0.13.0",
+    "@voltro/runtime": "0.13.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.4",
+    "@voltro/testing": "0.13.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.11.4",
-    "@voltro/database": "0.11.4",
-    "@voltro/env": "0.11.4",
-    "@voltro/plugin-deactivation": "0.11.4",
-    "@voltro/protocol": "0.11.4",
-    "@voltro/runtime": "0.11.4",
+    "@voltro/cli": "0.13.0",
+    "@voltro/database": "0.13.0",
+    "@voltro/env": "0.13.0",
+    "@voltro/plugin-deactivation": "0.13.0",
+    "@voltro/protocol": "0.13.0",
+    "@voltro/runtime": "0.13.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.4",
+    "@voltro/testing": "0.13.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend-deactivation/tests/users.deactivate.test.ts

@@ -15,7 +15,7 @@ import { database } from '../database/schema' // registers users / actors / tena
 import createUser from '../mutations/users.create.mutation.server'
 import deactivateUser from '../mutations/users.deactivate.mutation.server'
 
-const subject = { type: 'user' as const, id: 'user_1', tenantId: null }
+const subject = { type: 'user' as const, id: 'user_1', tenantId: 'acme' }
 
 describe('users.create', () => {
   it('inserts a user with an auto-injected id and no deactivation timestamp', async () => {

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

@@ -12,18 +12,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.11.4",
-    "@voltro/database": "0.11.4",
-    "@voltro/env": "0.11.4",
-    "@voltro/plugin-mail": "0.11.4",
-    "@voltro/plugin-multitenancy": "0.11.4",
-    "@voltro/protocol": "0.11.4",
-    "@voltro/runtime": "0.11.4",
+    "@voltro/cli": "0.13.0",
+    "@voltro/database": "0.13.0",
+    "@voltro/env": "0.13.0",
+    "@voltro/plugin-mail": "0.13.0",
+    "@voltro/plugin-multitenancy": "0.13.0",
+    "@voltro/protocol": "0.13.0",
+    "@voltro/runtime": "0.13.0",
     "effect": "^3.21.2",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.4",
+    "@voltro/testing": "0.13.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }