@voltro/cli 0.12.0 → 0.14.0

package/templates/apps/api-rbac/database/schema.ts

@@ -1,7 +1,9 @@
-// Schema for the {{projectName}} RBAC backend — a tiny `notes` domain to
-// guard. `actors` + `tenants` are the framework core tables.
+// Schema for the {{projectName}} RBAC backend — a `notes` domain guarded by
+// GLOBAL scopes, plus a `teams` domain guarded PER RESOURCE. `actors` +
+// `tenants` are the framework core tables.
 
 import {
+  boolean,
   databaseHandle,
   id,
   table,
@@ -25,13 +27,26 @@ export const tenants = table('tenants', {
 })
 
 export const notes = table('notes', {
-  id:    id({ prefix: 'note' }),
-  title: text(),
-  body:  text(),
+  id:       id({ prefix: 'note' }),
+  title:    text(),
+  body:     text(),
+  // `notes.delete` demonstrates authz that a descriptor guard CANNOT express:
+  // whether a note may be hard-deleted depends on this column, which is only
+  // known after the row is loaded.
+  archived: boolean().default(false),
+})
+  .with(tenant())
+
+// Guarded per-resource rather than globally: holding `teams:rename` on
+// `team_core` must not let you rename `team_marketing`. The grant comes from
+// `resolveResourceRoles` in app.config.ts.
+export const teams = table('teams', {
+  id:   id({ prefix: 'team' }),
+  name: text(),
 })
   .with(tenant())
-  .reactive()
 
 export type Note = InferRow<typeof notes>
+export type Team = InferRow<typeof teams>
 
-export const database = databaseHandle({ actors, tenants, notes })
+export const database = databaseHandle({ actors, tenants, notes, teams })

package/templates/apps/api-rbac/mutations/notes.create.mutation.server.ts

@@ -1,13 +1,15 @@
+// No authz in here — deliberately. The descriptor's `guards: [{ scope:
+// 'notes:write' }]` already refused an unscoped caller before this executor
+// was reached. Re-checking the same scope by hand would be a second copy of
+// the rule that can drift from the first, and the one `voltro check` reads is
+// the descriptor's.
+
 import { EffectStore } from '@voltro/runtime'
 import type { AppContext } from '@voltro/runtime'
-import { permission } from '@voltro/plugin-rbac'
 import { Effect } from 'effect'
 
-const execute = (input: { title: string; body: string }, ctx: AppContext) =>
+const execute = (input: { title: string; body: string }, _ctx: AppContext) =>
   Effect.gen(function* () {
-    // RBAC guard — passes for editor/admin, fails typed ScopeError for viewer.
-    yield* permission(ctx, 'notes:write')
-
     const store = yield* EffectStore
     // tenant() auto-fills tenantId from the subject — no need to pass it.
     const row = yield* store.insert('notes', { title: input.title, body: input.body })

package/templates/apps/api-rbac/mutations/notes.create.mutation.ts

@@ -1,17 +1,25 @@
-// Creates a note — requires the `notes:write` scope. The executor guards with
-// `permission(ctx, 'notes:write')`, the Effect-native RBAC guard that fails
-// typed `ScopeError` when the caller's resolved scopes don't include it.
-// Declaring `error: ScopeError` surfaces that to the client typed.
+// Creates a note — requires the `notes:write` scope, declared DECLARATIVELY.
 //
-// `ScopeError` is the ONE framework-wide denial tag, from the browser-safe
-// `@voltro/protocol` (rbac guards and declarative `guards:` fail with it alike).
+// This is the form to reach for by default. The framework enforces it in the
+// dispatch spine: before the executor, and before the transaction opens, so an
+// unauthorized call never touches the DB. It also lands in the capability
+// manifest, which is what lets `voltro check` fail on a guard requiring a scope
+// no role grants — an in-handler `permission()` call is invisible to that
+// check. Compare `notes.delete`, which needs the in-handler form for a reason.
+//
+// Declaring `guards:` merges the framework-wide `ScopeError` into the
+// descriptor's error union automatically, so the client receives the denial
+// typed without an explicit `error:` field. `ScopeError` is the ONE denial tag
+// — declarative guards and `permission()` both fail with it, so a client
+// branches once.
 
-import { defineMutation, ScopeError } from '@voltro/protocol'
+import { defineMutation } from '@voltro/protocol'
 import { Schema } from 'effect'
 
 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,
@@ -22,5 +30,4 @@ export const createNote = defineMutation({
     body: Schema.String,
     tenantId: Schema.String,
   }),
-  error: ScopeError,
 })

package/templates/apps/api-rbac/mutations/notes.delete.mutation.server.ts

@@ -0,0 +1,54 @@
+// The authz that needs the ROW. `notes:delete` was already enforced by the
+// descriptor guard; what is decided here could not have been:
+//
+//   archived note            → hard delete
+//   active note + notes:purge → hard delete
+//   active note, no purge     → archive instead (soft)
+//
+// `can()` is the non-throwing form — it BRANCHES rather than refusing, which
+// is the right shape when the caller is authorized to do *something* and the
+// scope only selects which. Use `permission()` (Effect, typed failure) when
+// the answer is "you may not do this at all".
+//
+// Note that `notes:purge` is granted by NO named role in app.config.ts — only
+// the wildcard `admin` role reaches it. That is deliberate and worth
+// understanding: scopes used in `can()` / `permission()` are invisible to
+// `voltro check`, so they are NOT validated against the declared vocabulary.
+// A typo here fails silently as a branch that is never taken; a typo in a
+// descriptor `guards:` is caught before the app boots. One more reason to
+// prefer the declarative form wherever the decision doesn't need loaded data.
+
+import { EffectStore } from '@voltro/runtime'
+import type { AppContext } from '@voltro/runtime'
+import { can } from '@voltro/plugin-rbac'
+import { eq } from '@voltro/database'
+import { Effect } from 'effect'
+import { database } from '../database/schema'
+import { NoteNotFound } from './notes.delete.mutation'
+
+const execute = (input: { id: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    const store = yield* EffectStore
+
+    // tenant() scopes this read to the caller's tenant automatically, so a
+    // cross-tenant id simply does not resolve.
+    // `.where(...)` takes the predicate AST (`eq(...)`), not three arguments.
+    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 }))
+    }
+
+    const hard = note['archived'] === true || can(ctx, 'notes:purge')
+    if (hard) {
+      yield* store.delete('notes', input.id)
+      return { id: input.id, mode: 'hard' as const }
+    }
+
+    yield* store.update('notes', input.id, { archived: true })
+    return { id: input.id, mode: 'soft' as const }
+  })
+
+export default execute

package/templates/apps/api-rbac/mutations/notes.delete.mutation.ts

@@ -0,0 +1,43 @@
+// Deleting a note needs BOTH forms of authorization, which is why this file
+// exists next to `notes.create`.
+//
+//   • The declarative guard below is the coarse gate: you need `notes:delete`
+//     to be in this conversation at all. It is checked before the transaction.
+//   • The executor then makes a decision the descriptor CANNOT: a note that is
+//     already archived may be hard-deleted, an active one is only soft-
+//     deleted unless the caller also holds `notes:purge`. That depends on the
+//     loaded ROW, which no descriptor guard can see.
+//
+// The rule of thumb the two illustrate: put in `guards:` everything decidable
+// from the SUBJECT and the INPUT; use `permission()` / `can()` only for what
+// needs loaded data. Guards are statically checkable, in-handler calls are not.
+
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+/**
+ * Lives HERE, in the descriptor file, because the web client imports this
+ * module value-level and must be able to construct/match the error. Keeping
+ * typed errors in a file with zero server imports is what stops a descriptor
+ * from dragging the database handle into the browser bundle.
+ */
+export class NoteNotFound extends Schema.TaggedError<NoteNotFound>()('NoteNotFound', {
+  id: Schema.String,
+}) {}
+
+export const deleteNote = defineMutation({
+  name: 'notes.delete',
+  target: { table: 'notes', op: 'update' },
+  guards: [{ scope: 'notes:delete' }],
+  input: Schema.Struct({
+    id: Schema.NonEmptyString,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    // 'hard' when the row was removed, 'soft' when it was only archived.
+    mode: Schema.Literal('hard', 'soft'),
+  }),
+  // `ScopeError` is merged in automatically by `guards:` — only the app's own
+  // error needs declaring.
+  error: NoteNotFound,
+})

package/templates/apps/api-rbac/mutations/teams.rename.mutation.server.ts

@@ -0,0 +1,19 @@
+// Authz-free again: by the time this runs, the framework has already asked
+// `resolveResourceRoles` whether the caller holds `teams:rename` on THIS
+// `teamId`. Re-checking membership here would duplicate the rule.
+
+import { EffectStore } from '@voltro/runtime'
+import type { AppContext } from '@voltro/runtime'
+import { Effect } from 'effect'
+
+const execute = (input: { teamId: string; name: string }, _ctx: AppContext) =>
+  Effect.gen(function* () {
+    const store = yield* EffectStore
+    const row = yield* store.update('teams', input.teamId, { name: input.name })
+    return {
+      id: input.teamId,
+      name: (row?.['name'] as string | undefined) ?? input.name,
+    }
+  })
+
+export default execute

package/templates/apps/api-rbac/mutations/teams.rename.mutation.ts

@@ -0,0 +1,37 @@
+// A RESOURCE-SCOPED guard: "owner of THIS team", not "owner globally".
+//
+// The `resource` extractor pulls the resource id out of the decoded input; the
+// framework then asks rbac's `resolveResourceRoles` (app.config.ts) which roles
+// the caller holds on that specific id, compiles them through the SAME role
+// map, and grants the scope only if the compiled set contains it.
+//
+// The order is worth knowing, because it decides how much your membership
+// lookup gets hit: a GLOBALLY held scope (or `admin:full`) satisfies the guard
+// without the resolver ever being called. Only the gap — "no global grant" —
+// falls through to the per-resource question. And that fall-through is
+// fail-CLOSED: a resolver that throws or rejects denies, it does not degrade
+// to the global answer.
+//
+// Without this, an app has to choose between a global grant (too broad) and
+// hand-rolled membership checks inside every handler (untestable, easy to
+// forget, invisible to `voltro check`).
+
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const renameTeam = defineMutation({
+  name: 'teams.rename',
+  target: { table: 'teams', op: 'update' },
+  guards: [{
+    scope: 'teams:rename',
+    resource: (input: { teamId: string }) => input.teamId,
+  }],
+  input: Schema.Struct({
+    teamId: Schema.NonEmptyString,
+    name: Schema.NonEmptyString,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+  }),
+})

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

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

package/templates/apps/api-rbac/queries/notes.list.query.server.ts

@@ -0,0 +1,12 @@
+// The executor is authz-free on purpose: the descriptor's `guards:` already
+// refused an unscoped caller before this ran. Tenant scoping is likewise
+// automatic — `notes` carries `tenant()`, so the runtime AND-merges
+// `eq('tenantId', subject.tenantId)` into the query.
+
+import type { AppContext } from '@voltro/runtime'
+import { database } from '../database/schema'
+
+const route = (_input: Record<string, never>, _ctx: AppContext) =>
+  database.notes.orderBy('id', 'desc').limit(100)
+
+export default route

package/templates/apps/api-rbac/queries/notes.list.query.ts

@@ -0,0 +1,26 @@
+// Reads are guarded too. A write-only authorization model is the quiet half
+// of a leak: the data still goes out, just without anyone writing it.
+//
+// `guards:` on a QUERY is enforced when the subscription opens AND re-checked
+// on every delivery — so a caller whose role is revoked mid-subscription stops
+// receiving rows rather than keeping a live feed open on an expired grant.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listNotes = defineQuery({
+  name:   'notes.list',
+  source: 'notes',
+  // Declarative — the framework enforces it, and `voltro check` can SEE it.
+  // No `error: ScopeError` needed: declaring `guards:` merges `ScopeError`
+  // into the descriptor's error union automatically.
+  guards: [{ scope: 'notes:read' }],
+  input:  Schema.Struct({}),
+  output: Schema.Array(Schema.Struct({
+    id:       Schema.String,
+    title:    Schema.String,
+    body:     Schema.String,
+    archived: Schema.Boolean,
+    tenantId: Schema.String,
+  })),
+})

package/templates/apps/api-rbac/template.json

@@ -1,6 +1,6 @@
 {
   "id": "api-rbac",
   "kind": "api",
-  "summary": "Role-based access control — @voltro/plugin-rbac compiles a role→scope map and an interceptor resolves the caller's roles to scopes; guard handlers with permission(ctx, 'notes:write') (Effect-native, fails typed Forbidden). admin:full bypasses. Memory/config-only, zero infra; useCan() for web UI affordance.",
-  "tags": ["api", "rbac", "authz", "roles", "permissions", "plugin"]
+  "summary": "Role-based access control — @voltro/plugin-rbac compiles a role→scope map and an interceptor resolves the caller's roles to scopes. Shows all three guard forms: declarative descriptor guards (statically checked by `voltro check`), resource-scoped guards (owner of THIS team), and in-handler permission()/can() for authz that needs the loaded row. Fails typed ScopeError; admin:full bypasses. Memory/config-only, zero infra; useCan() for web UI affordance.",
+  "tags": ["api", "rbac", "authz", "roles", "permissions", "scopes", "guards", "plugin"]
 }

package/templates/apps/api-rbac/tests/authz.test.ts

@@ -0,0 +1,233 @@
+// Authorization tests, driven through the REAL rbac plugin.
+//
+// The important detail is `makeTestContext({ plugins: [...] })` plus `invoke`:
+// that composes this app's actual interceptor chain with
+// `composeRpcInterceptors` and enforces the descriptor's `guards:` with the
+// same `checkGuardsEffect` the serve pipeline calls. So these tests exercise
+// the whole path — role slugs → compiled scopes → effective-scope seam →
+// guard — rather than asserting against hand-set `subject.scopes`.
+//
+// That distinction is the point. Putting the expected scopes on the subject
+// yourself tests the guard while ASSUMING the resolution that produces them,
+// which is the half that actually breaks: a role renamed in `authz.ts`, a
+// resolver that throws, a scope no role grants. Those all pass a test that
+// pre-stamps its own scopes and fail these.
+//
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect, afterEach } from 'vitest'
+import { Schema } from 'effect'
+import { makeTestContext, mockStore, invoke } from '@voltro/testing'
+import { rbacPlugin } from '@voltro/plugin-rbac'
+import { mutationToRpc, ScopeError, setResourceScopeResolver, type Subject } from '@voltro/protocol'
+
+import { roles, rolesOnTeam, demoRolesForTenant } from '../authz'
+import { database } from '../database/schema' // registers notes / teams / actors / tenants
+import { createNote } from '../mutations/notes.create.mutation'
+import createNoteHandler from '../mutations/notes.create.mutation.server'
+import { deleteNote, NoteNotFound } from '../mutations/notes.delete.mutation'
+import deleteNoteHandler from '../mutations/notes.delete.mutation.server'
+import { renameTeam } from '../mutations/teams.rename.mutation'
+import renameTeamHandler from '../mutations/teams.rename.mutation.server'
+import { listNotes } from '../queries/notes.list.query'
+
+/** The app's real plugin, built from the app's real role map. */
+const plugin = () =>
+  rbacPlugin({
+    roles,
+    resolveRoles: (subject) => demoRolesForTenant(subject.tenantId),
+    resolveResourceRoles: (subject, resource) => rolesOnTeam(subject.id, resource),
+  })
+
+/** A caller in the tenant that the demo resolver maps to `role`. */
+const caller = (id: string, tenantId: string): Subject =>
+  ({ type: 'user', id, tenantId, scopes: [] }) as Subject
+
+const ctxFor = (subject: Subject, seed: Record<string, ReadonlyArray<Record<string, unknown>>> = {}) =>
+  makeTestContext({ subject, store: mockStore({ notes: [], teams: [], ...seed }), plugins: [plugin()] })
+
+// `rbacPlugin` registers its resource resolver process-globally; clear it so
+// cases stay isolated from each other.
+afterEach(() => { setResourceScopeResolver(undefined) })
+
+describe('notes.create — a global declarative guard', () => {
+  it('an editor holds notes:write, so the note is written', async () => {
+    const ctx = ctxFor(caller('u_ed', 'editors'))
+
+    const note = await invoke(createNote, createNoteHandler, { title: 'Ship it', body: 'x' }, ctx)
+
+    expect(note.title).toBe('Ship it')
+    expect(note.tenantId).toBe('editors') // tenant() auto-stamped from the subject
+    expect(note.id).toMatch(/^note_/)
+  })
+
+  it('a reader is refused with a typed ScopeError, and nothing is written', async () => {
+    const ctx = ctxFor(caller('u_read', 'readers'))
+
+    await expect(invoke(createNote, createNoteHandler, { title: 'nope', body: '' }, ctx))
+      .rejects.toMatchObject({ _tag: 'ScopeError', required: 'notes:write' })
+
+    // The refusal has to be a refusal — not an error thrown after the insert.
+    const rows = await ctx.store.query(database.notes.descriptor)
+    expect(rows).toHaveLength(0)
+  })
+
+  it('the admin wildcard role passes', async () => {
+    const ctx = ctxFor(caller('u_root', 'acme'))
+    await expect(invoke(createNote, createNoteHandler, { title: 'ok', body: '' }, ctx)).resolves.toBeDefined()
+  })
+})
+
+describe('notes.list — reads are guarded too', () => {
+  it('a caller with no role at all cannot subscribe', async () => {
+    // An unknown tenant falls to the resolver's `['viewer']` default, so use a
+    // subject the app grants nothing: the guard must still hold.
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u_x', tenantId: 'nobody', scopes: [] } as Subject,
+      store: mockStore({ notes: [] }),
+      plugins: [rbacPlugin({ roles, resolveRoles: () => [] })],
+    })
+
+    await expect(invoke(listNotes, async () => [], {}, ctx))
+      .rejects.toMatchObject({ _tag: 'ScopeError', required: 'notes:read' })
+  })
+
+  it('a viewer may read', async () => {
+    const ctx = ctxFor(caller('u_v', 'readers'))
+    await expect(invoke(listNotes, async () => [], {}, ctx)).resolves.toEqual([])
+  })
+})
+
+describe('notes.delete — the decision the descriptor cannot make', () => {
+  it('an editor lacks notes:delete entirely', async () => {
+    const ctx = ctxFor(caller('u_ed', 'editors'))
+
+    await expect(invoke(deleteNote, deleteNoteHandler, { id: 'note_1' }, ctx))
+      .rejects.toMatchObject({ _tag: 'ScopeError', required: 'notes:delete' })
+  })
+
+  it('an owner SOFT-deletes an active note (no notes:purge)', async () => {
+    const ctx = ctxFor(caller('u_own', 'owners'))
+    const row = await ctx.store.insert('notes', { title: 'live', body: '', archived: false })
+
+    const out = await invoke(deleteNote, deleteNoteHandler, { id: row['id'] as string }, ctx)
+
+    expect(out.mode).toBe('soft')
+    const rows = await ctx.store.query(database.notes.descriptor)
+    expect(rows).toHaveLength(1)
+    expect(rows[0]!['archived']).toBe(true)
+  })
+
+  it('an owner HARD-deletes an already-archived note', async () => {
+    const ctx = ctxFor(caller('u_own', 'owners'))
+    const row = await ctx.store.insert('notes', { title: 'old', body: '', archived: true })
+
+    const out = await invoke(deleteNote, deleteNoteHandler, { id: row['id'] as string }, ctx)
+
+    expect(out.mode).toBe('hard')
+    expect(await ctx.store.query(database.notes.descriptor)).toHaveLength(0)
+  })
+
+  it('admin holds notes:purge via the wildcard, so an active note is hard-deleted', async () => {
+    const ctx = ctxFor(caller('u_root', 'acme'))
+    const row = await ctx.store.insert('notes', { title: 'live', body: '', archived: false })
+
+    const out = await invoke(deleteNote, deleteNoteHandler, { id: row['id'] as string }, ctx)
+
+    expect(out.mode).toBe('hard')
+  })
+
+  it('a missing note fails with the app\'s own typed error, not a scope error', async () => {
+    const ctx = ctxFor(caller('u_own', 'owners'))
+
+    await expect(invoke(deleteNote, deleteNoteHandler, { id: 'note_gone' }, ctx))
+      .rejects.toBeInstanceOf(NoteNotFound)
+  })
+})
+
+describe('teams.rename — a resource-scoped guard', () => {
+  it('alice is owner OF team_core, so she may rename it', async () => {
+    const ctx = ctxFor(caller('u_alice', 'nobody'))
+    await ctx.store.insert('teams', { id: 'team_core', name: 'Core' })
+
+    const out = await invoke(renameTeam, renameTeamHandler, { teamId: 'team_core', name: 'Platform' }, ctx)
+
+    expect(out.name).toBe('Platform')
+  })
+
+  it('the SAME caller is refused on a team where she is only a viewer', async () => {
+    // The whole reason resource scoping exists: the grant must not generalize.
+    const ctx = ctxFor(caller('u_alice', 'nobody'))
+    await ctx.store.insert('teams', { id: 'team_marketing', name: 'Marketing' })
+
+    await expect(invoke(renameTeam, renameTeamHandler, { teamId: 'team_marketing', name: 'Growth' }, ctx))
+      .rejects.toMatchObject({ _tag: 'ScopeError', required: 'teams:rename' })
+  })
+
+  it('a caller with no membership at all is refused', async () => {
+    const ctx = ctxFor(caller('u_stranger', 'nobody'))
+    await ctx.store.insert('teams', { id: 'team_core', name: 'Core' })
+
+    await expect(invoke(renameTeam, renameTeamHandler, { teamId: 'team_core', name: 'Mine' }, ctx))
+      .rejects.toMatchObject({ _tag: 'ScopeError' })
+  })
+
+  it('a GLOBAL grant satisfies it without consulting memberships', async () => {
+    // `owners` tenant → the `owner` role → `teams:rename` globally. The
+    // membership table is never asked, which is why an admin does not need a
+    // row in it for every resource.
+    const ctx = ctxFor(caller('u_nobody_in_memberships', 'owners'))
+    await ctx.store.insert('teams', { id: 'team_new', name: 'New' })
+
+    await expect(invoke(renameTeam, renameTeamHandler, { teamId: 'team_new', name: 'Renamed' }, ctx))
+      .resolves.toMatchObject({ name: 'Renamed' })
+  })
+})
+
+describe('the declared scope vocabulary `voltro check` reads', () => {
+  it('every scope any descriptor guard requires is granted by some role', () => {
+    // This is the assertion `voltro check` makes at build time, kept here as
+    // well because it is cheap and it fails with the offending scope named.
+    // A guard requiring a scope no role grants is not "misconfigured" — that
+    // procedure is permanently, silently uncallable by everyone.
+    const declared = new Set(rbacPlugin({ roles }).declaredScopes ?? [])
+    const guardScopes = [createNote, deleteNote, renameTeam, listNotes]
+      .flatMap((d) => (d.guards ?? []).flatMap((g) => {
+        const scope = (g as { scope?: string | ReadonlyArray<string> }).scope
+        return scope === undefined ? [] : typeof scope === 'string' ? [scope] : [...scope]
+      }))
+
+    expect(guardScopes.length).toBeGreaterThan(0) // the check must not be vacuous
+    for (const scope of guardScopes) expect([...declared]).toContain(scope)
+  })
+
+  it('the wildcard is not published as a literal scope name', () => {
+    const declared = rbacPlugin({ roles }).declaredScopes ?? []
+    expect(declared).not.toContain('*')
+    expect(declared).not.toContain('admin:full')
+  })
+})
+
+describe('descriptor wire contracts', () => {
+  it('notes.create decodes a valid input and rejects a blank title', () => {
+    const decode = Schema.decodeUnknownSync(createNote.input)
+    expect(decode({ title: 'ok', body: 'b' })).toEqual({ title: 'ok', body: 'b' })
+    expect(() => decode({ title: '', body: '' })).toThrow()
+  })
+
+  it('a guarded descriptor carries ScopeError in the WIRE error union', () => {
+    // The merge happens in `mutationToRpc` — the same conversion both the
+    // server group and the generated client group go through — not on the raw
+    // descriptor object. Asserting it on `createNote.error` would test the
+    // wrong layer and pass for the wrong reason: that field is `Schema.Never`
+    // here, because this descriptor declares no error of its own.
+    //
+    // This is why none of these descriptors writes `error: ScopeError` by hand
+    // and a client can still branch on one denial tag.
+    const wire = mutationToRpc(createNote)
+    const denial = new ScopeError({ required: 'notes:write', message: 'nope' })
+    // `Rpc`'s `errorSchema` is typed as the broad `Schema.All`; narrow it to
+    // the context-free form `Schema.is` takes.
+    expect(Schema.is(wire.errorSchema as Schema.Schema.AnyNoContext)(denial)).toBe(true)
+  })
+})

package/templates/apps/api-rest/database/schema.ts

@@ -43,9 +43,6 @@ export const products = table('products', {
   priceCents: integer(),
   createdAt:  timestamp().default('now'),
 })
-  // Opt into the matcher engine so a future reactive WS query over the
-  // same table stays live. The REST routes don't need it, but it's free.
-  .reactive()
 
 export type Product = InferRow<typeof products>
 

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

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.12.0",
-    "@voltro/database": "0.12.0",
-    "@voltro/plugin-openapi": "0.12.0",
-    "@voltro/protocol": "0.12.0",
-    "@voltro/runtime": "0.12.0",
-    "@voltro/sql-postgres": "0.12.0",
+    "@voltro/cli": "0.14.0",
+    "@voltro/database": "0.14.0",
+    "@voltro/plugin-openapi": "0.14.0",
+    "@voltro/protocol": "0.14.0",
+    "@voltro/runtime": "0.14.0",
+    "@voltro/sql-postgres": "0.14.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.12.0",
+    "@voltro/testing": "0.14.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-saas/database/schema.ts

@@ -43,7 +43,6 @@ export const projects = table('projects', {
   // createdBy / updatedBy (auto-stamped). Creating a project is gated by the
   // billing `projects` entitlement (see mutations/projects.create).
   .with(tenant())
-  .reactive()
 
 export type Project = InferRow<typeof projects>
 

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

@@ -12,20 +12,20 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.12.0",
-    "@voltro/database": "0.12.0",
-    "@voltro/plugin-analytics-postgres": "0.12.0",
-    "@voltro/plugin-billing": "0.12.0",
-    "@voltro/plugin-multitenancy": "0.12.0",
-    "@voltro/plugin-notifications": "0.12.0",
-    "@voltro/plugin-presence": "0.12.0",
-    "@voltro/protocol": "0.12.0",
-    "@voltro/runtime": "0.12.0",
-    "@voltro/sql-postgres": "0.12.0",
+    "@voltro/cli": "0.14.0",
+    "@voltro/database": "0.14.0",
+    "@voltro/plugin-analytics-postgres": "0.14.0",
+    "@voltro/plugin-billing": "0.14.0",
+    "@voltro/plugin-multitenancy": "0.14.0",
+    "@voltro/plugin-notifications": "0.14.0",
+    "@voltro/plugin-presence": "0.14.0",
+    "@voltro/protocol": "0.14.0",
+    "@voltro/runtime": "0.14.0",
+    "@voltro/sql-postgres": "0.14.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.12.0",
+    "@voltro/testing": "0.14.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }