@voltro/cli 0.12.0 → 0.14.0

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

@@ -10,17 +10,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.12.0",
-    "@voltro/database": "0.12.0",
-    "@voltro/env": "0.12.0",
-    "@voltro/plugin-multitenancy": "0.12.0",
-    "@voltro/plugin-storage": "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-storage": "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-data-advanced/database/authors.entity.ts

@@ -26,5 +26,3 @@ export const authors = table('authors', {
   // tenant() pulls audit() transitively → adds tenantId + createdAt /
   // updatedAt / createdBy / updatedBy (auto-stamped by the runtime).
   .with(tenant())
-  // Opt into the matcher engine so subscriptions react to writes.
-  .reactive()

package/templates/apps/api-data-advanced/database/books.entity.ts

@@ -56,4 +56,3 @@ export const books = table('books', {
   })
   // tenant() pulls audit() transitively (tenantId + audit columns).
   .with(tenant())
-  .reactive()

package/templates/apps/api-data-advanced/package.json

@@ -11,17 +11,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-governance": "0.12.0",
-    "@voltro/plugin-multitenancy": "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-governance": "0.14.0",
+    "@voltro/plugin-multitenancy": "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-data-advanced/tests/queries.test.ts

@@ -71,7 +71,12 @@ describe('authors.withBooks', () => {
     const rows = await ctx.store.query(authorsWithBooksExecute({}, ctx).descriptor)
 
     expect(rows).toHaveLength(1)
-    const ada = rows[0] as { id: string; name: string; books: ReadonlyArray<{ title: string }> }
+    // Narrow BEFORE describing the shape: under `noUncheckedIndexedAccess`
+    // `rows[0]` is `Row | undefined`, and a cast that spans that gap is the one
+    // TypeScript refuses outright ("neither type sufficiently overlaps").
+    const first = rows[0]
+    if (first === undefined) throw new Error('expected one author row')
+    const ada = first as unknown as { id: string; name: string; books: ReadonlyArray<{ title: string }> }
     expect(ada.name).toBe('Ada')
     expect(ada.books.map((b) => b.title).sort()).toEqual(['Analytical Engine', 'Notes'])
   })

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

@@ -56,9 +56,6 @@ export const orders = table('orders', {
   // tenant() pulls audit() transitively → adds tenantId + createdAt /
   // updatedAt / createdBy / updatedBy (auto-stamped by the runtime).
   .with(tenant())
-  // Opt into the matcher engine: the `orderChanges` subscriber + any
-  // live subscription against `orders` fire on every mutation write.
-  .reactive()
 
 export type Order = InferRow<typeof orders>
 

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

@@ -11,17 +11,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/protocol": "0.12.0",
-    "@voltro/runtime": "0.12.0",
-    "@voltro/workflow": "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/protocol": "0.14.0",
+    "@voltro/runtime": "0.14.0",
+    "@voltro/workflow": "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-feature-flags/database/schema.ts

@@ -30,7 +30,6 @@ export const notes = table('notes', {
   body:  text(),
 })
   .with(tenant())
-  .reactive()
 
 export type Note = InferRow<typeof notes>
 

package/templates/apps/api-feature-flags/package.json

@@ -12,18 +12,18 @@
   "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-flags": "0.12.0",
-    "@voltro/plugin-multitenancy": "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/env": "0.14.0",
+    "@voltro/plugin-flags": "0.14.0",
+    "@voltro/plugin-multitenancy": "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-governance/app.config.ts

@@ -44,5 +44,4 @@ export default {
       retention: [{ table: 'profiles', ttlMs: 365 * 86_400_000, action: 'delete' }],
     }),
   ],
-  env,
 }

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

@@ -34,7 +34,6 @@ export const profiles = table('profiles', {
   ssn:   text().encrypted(),
 })
   .with(audit())     // createdAt drives the retention sweep
-  .reactive()
 
 export type Profile = InferRow<typeof profiles>
 

package/templates/apps/api-governance/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-audit": "0.12.0",
-    "@voltro/plugin-governance": "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-audit": "0.14.0",
+    "@voltro/plugin-governance": "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-kv/database/schema.ts

@@ -53,9 +53,6 @@ export const syncedEvents = table('synced_events', {
   // tenant() pulls audit() transitively → tenantId + created/updated columns,
   // auto-stamped by the runtime from the caller's subject.
   .with(tenant())
-  // Opt into the matcher engine so the `events.list` subscription wakes on
-  // every insert.
-  .reactive()
 
 export type SyncedEvent = InferRow<typeof syncedEvents>
 

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

@@ -11,17 +11,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/kv": "0.12.0",
-    "@voltro/plugin-multitenancy": "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/kv": "0.14.0",
+    "@voltro/plugin-multitenancy": "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-kv/tests/sync.test.ts

@@ -38,7 +38,7 @@ describe('sync.pull (durable cursor + idempotency markers)', () => {
     const rows = await ctx.store.query(database.syncedEvents.descriptor)
     expect(rows).toHaveLength(3)
     expect(rows.every((r) => r['tenantId'] === 'acme')).toBe(true)
-    expect((rows.map((r) => r['externalId']) as ReadonlyArray<string>).sort()).toEqual([
+    expect((rows.map((r) => r['externalId']) as string[]).sort()).toEqual([
       'ext-1',
       'ext-2',
       'ext-3',
@@ -63,7 +63,7 @@ describe('sync.pull (durable cursor + idempotency markers)', () => {
 
     const rows = await ctx.store.query(database.syncedEvents.descriptor)
     expect(rows).toHaveLength(4) // 2 + 2, no duplicates
-    expect((rows.map((r) => r['sequence']) as ReadonlyArray<number>).sort((a, b) => a - b)).toEqual([
+    expect((rows.map((r) => r['sequence']) as number[]).sort((a, b) => a - b)).toEqual([
       1, 2, 3, 4,
     ])
   })

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

@@ -30,14 +30,12 @@ export const posts = table('posts', {
   body:  text(),
 })
   .with(tenant())
-  .reactive()
 
 export const comments = table('comments', {
   id:   id({ prefix: 'cmt' }),
   body: text(),
 })
   .with(tenant())
-  .reactive()
 
 export type Post = InferRow<typeof posts>
 export type Comment = InferRow<typeof comments>

package/templates/apps/api-moderation/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-moderation": "0.12.0",
-    "@voltro/plugin-multitenancy": "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-moderation": "0.14.0",
+    "@voltro/plugin-multitenancy": "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-observability/database/schema.ts

@@ -31,7 +31,6 @@ export const notes = table('notes', {
   done:  boolean().default(false),
 })
   .with(tenant())   // tenantId + audit columns, auto-stamped
-  .reactive()
 
 export type Note = InferRow<typeof notes>
 

package/templates/apps/api-observability/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/plugin-multitenancy": "0.12.0",
-    "@voltro/plugin-prometheus": "0.12.0",
-    "@voltro/plugin-sentry": "0.12.0",
-    "@voltro/protocol": "0.12.0",
-    "@voltro/runtime": "0.12.0",
+    "@voltro/cli": "0.14.0",
+    "@voltro/database": "0.14.0",
+    "@voltro/plugin-multitenancy": "0.14.0",
+    "@voltro/plugin-prometheus": "0.14.0",
+    "@voltro/plugin-sentry": "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-ratelimit/database/schema.ts

@@ -30,7 +30,6 @@ export const notes = table('notes', {
   body:  text(),
 })
   .with(tenant())
-  .reactive()
 
 export type Note = InferRow<typeof notes>
 

package/templates/apps/api-ratelimit/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-ratelimit": "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-ratelimit": "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/README.md

@@ -13,19 +13,39 @@ pnpm --filter @{{projectName}}/{{appName}} dev
 
 ## What this shows
 
-- **Roles → scopes, as config** — `app.config.ts` declares a role map
-  (`viewer → notes:read`, `editor → notes:read + notes:write`,
-  `admin → admin:full`). An rpc interceptor resolves each caller's roles to
-  scopes and stamps them on the subject.
-- **Guard with `permission()`** — `notes.create` calls
-  `permission(ctx, 'notes:write')`, the Effect-native guard. It fails typed
-  `ScopeError` when the caller lacks the scope; `admin:full` is a blanket bypass.
-  Companions: `anyPermission(ctx, [...])` (OR), `assertPermission` (sync throw),
-  `can(ctx, scope)` (boolean).
-- **Where roles come from** — the shipped `resolveRoles` is a DEMO that maps
-  the request's **tenant** to a role so you can try each with the `x-tenant`
-  header. Production reads the caller's real roles: the default resolver reads
-  `subject.metadata.roles` (set by your auth strategy), or do a DB lookup.
+- **Roles → scopes, as config** — `authz.ts` declares the role map; an rpc
+  interceptor resolves each caller's roles to scopes and publishes them to the
+  framework's effective-scope seam. That map is also the app's **declared scope
+  vocabulary**: `voltro check` fails on a guard requiring a scope no role grants.
+- **Declarative guards** (`notes.create`, `notes.list`) — `guards: [{ scope }]`
+  on the descriptor. Enforced before the executor and before the transaction,
+  and the only form `voltro check` can inspect. **Prefer this.**
+- **Resource-scoped guards** (`teams.rename`) — `guards: [{ scope, resource }]`
+  plus `resolveResourceRoles`, so "owner" means owner *of that team*.
+- **In-handler guards** (`notes.delete`) — `can()` / `permission()` for the
+  decision a descriptor cannot make, because it depends on the loaded row.
+- **Where roles come from** — the shipped `resolveRoles` is a DEMO mapping the
+  request's **tenant** to a role, so you can try each with an `x-tenant` header.
+  Production reads the caller's real roles (`subject.metadata.roles`, or a DB
+  lookup).
+
+## Which guard form?
+
+Put in `guards:` everything decidable from the **subject** and the **input**.
+Reach for `permission()` / `can()` only for what needs loaded data.
+
+The difference is not style. A declarative guard lands in the capability
+manifest, so `voltro check` catches a scope no role grants — a bug that is
+otherwise invisible, because the procedure simply becomes uncallable by
+everyone, forever, with no error anywhere. An in-handler call is invisible to
+that check; a typo there is a branch that is silently never taken.
+
+## Failure postures
+
+| Resolver | On throw / reject |
+| --- | --- |
+| `resolveRoles` / `resolvePermissions` | logs, degrades to the subject's **own** scopes — never grants |
+| `resolveResourceRoles` | **denies** (fail-closed) |
 
 ## Try it
 
@@ -41,6 +61,25 @@ curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json
 # → { ok:false, error:{ _tag:"ScopeError", required:"notes:write" } }
 ```
 
+```bash
+voltro check --offline     # no running app needed — usable as a CI gate
+```
+
+## Tests
+
+`tests/authz.test.ts` drives the **real** plugin — `makeTestContext({ plugins })`
+composes the actual interceptor chain and `invoke` enforces the descriptor's
+guards with the same function the serve pipeline calls.
+
+Do not hand-set `subject.scopes` to the value you expect. That tests the guard
+while assuming the resolution that produces it, and the resolution is the half
+that actually breaks (a renamed role, a throwing resolver, a scope no role
+grants) — all of which pass a pre-stamped test.
+
+```bash
+pnpm --filter @{{projectName}}/{{appName}} test
+```
+
 ## On the web side
 
 ```tsx
@@ -54,7 +93,7 @@ const canWrite = useCan('notes:write')
 The UI gate ships in `@voltro/client`, 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 real
+`useCan` is a UI affordance only — the server-side guard is the real
 enforcement. Never trust the client.
 
 ## Persisted roles

package/templates/apps/api-rbac/app.config.ts

@@ -1,26 +1,31 @@
 // RBAC backend for the {{projectName}} project.
 //
 // `rbacPlugin` compiles a role→scope map; an rpc interceptor resolves each
-// caller's ROLES to SCOPES and stamps them on the subject, so in-handler
-// guards like `permission(ctx, 'notes:write')` (Effect-native, fails typed
-// `Forbidden`) just work. The `admin:full` scope is a blanket bypass.
+// caller's ROLES to SCOPES and publishes them to the framework's effective-
+// scope seam. From there BOTH authorization forms see them:
 //
-// Config-only — no tables, no infra.
+//   • declarative `guards:` on a descriptor — enforced by the framework in the
+//     dispatch spine, before the executor and (for a mutation) before the
+//     transaction opens. PREFER THIS. It is the only form `voltro check` can
+//     inspect, so a guard requiring a scope no role grants is caught
+//     statically instead of becoming a permanently uncallable procedure.
+//   • in-handler `permission()` / `can()` — for authz that needs LOADED data a
+//     descriptor guard cannot see (see `notes.delete`).
+//
+// The `admin:full` scope is a blanket bypass for both.
+//
+// The role map itself lives in `authz.ts` so the tests can build the real
+// plugin from the real roles.
+//
+// Config-only — no external infra.
 import { defineEnv, envVar } from '@voltro/env'
 import { rbacPlugin } from '@voltro/plugin-rbac'
+import { demoRolesForTenant, roles, rolesOnTeam } from './authz'
 
 export const env = defineEnv({
   LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
 })
 
-// role → the scopes it grants. Scopes are `domain:action`; `admin:full` is the
-// framework's blanket bypass (passes every permission check).
-const roles = {
-  viewer: ['notes:read'],
-  editor: ['notes:read', 'notes:write'],
-  admin:  ['admin:full'],
-}
-
 export default {
   type:  'api' as const,
   name:  '{{capProjectName}}{{capAppName}}',
@@ -28,20 +33,13 @@ export default {
   plugins: [
     rbacPlugin({
       roles,
-      // DEMO resolver — assigns a role by the request's tenant so you can try
-      // each role via the `x-tenant` header with zero auth setup. PRODUCTION
-      // reads the caller's REAL roles: the default resolver reads
-      // `subject.metadata.roles` (set by your auth strategy), or do a DB
-      // lookup here (`subject.id` / `subject.tenantId` → roles). Delete this
-      // whole `resolveRoles` to fall back to the metadata default.
-      resolveRoles: (subject) => {
-        const demo: Record<string, ReadonlyArray<string>> = {
-          acme:    ['admin'],
-          editors: ['editor'],
-          readers: ['viewer'],
-        }
-        return demo[subject.tenantId ?? ''] ?? ['viewer']
-      },
+      resolveRoles: (subject) => demoRolesForTenant(subject.tenantId),
+      // PER-RESOURCE roles — what makes `guards: [{ scope, resource }]` mean
+      // "owner OF THIS TEAM" instead of "owner globally". Consulted only for
+      // the gap: a globally-held scope (or `admin:full`) passes without ever
+      // calling this. Fail-CLOSED — if it throws or rejects the guard DENIES,
+      // it does not fall back to the global answer.
+      resolveResourceRoles: (subject, resource) => rolesOnTeam(subject.id, resource),
     }),
   ],
   env,

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

@@ -0,0 +1,76 @@
+// The app's authorization vocabulary, in ONE place.
+//
+// Split out of `app.config.ts` so the tests can build the real plugin from the
+// real role map. A test that redeclares the roles it is testing proves only
+// that its own copy is self-consistent — the copy drifts, the test stays
+// green, and the drift is exactly the thing worth catching.
+
+/**
+ * role → the scopes it grants. Scopes are `domain:action`; `'*'` expands to
+ * the framework's blanket bypass (`admin:full`), which passes every check.
+ *
+ * This map is ALSO the app's declared scope vocabulary: `rbacPlugin` publishes
+ * the union of it, and `voltro check` errors on any descriptor guard requiring
+ * a scope that appears nowhere here. So: add a scope to a guard → add it to a
+ * role, or the build tells you the procedure is uncallable.
+ *
+ * (`notes:purge`, used by `notes.delete` via `can()`, is deliberately absent —
+ * only the wildcard `admin` role reaches it. See that handler for why that is
+ * a lesson rather than an oversight.)
+ */
+export const roles = {
+  viewer: ['notes:read'],
+  editor: ['notes:read', 'notes:write'],
+  owner:  ['notes:read', 'notes:write', 'notes:delete', 'teams:rename'],
+  admin:  ['*'],
+}
+
+/**
+ * DEMO membership table — which roles a caller holds ON A SPECIFIC team.
+ * PRODUCTION does a DB read (a `memberships` lookup keyed by `subject.id` +
+ * the resource id); this literal keeps the template infra-free.
+ */
+export const teamMemberships: Record<string, Record<string, ReadonlyArray<string>>> = {
+  // subjectId → teamId → the roles held on THAT team
+  u_alice: { team_core: ['owner'], team_marketing: ['viewer'] },
+  u_bob:   { team_marketing: ['owner'] },
+}
+
+/**
+ * Roles the caller holds on ONE resource. `Subject.id` is `string | null`
+ * (an anonymous caller has no id), and an anonymous caller is a member of
+ * nothing — so the null case returns `[]` rather than being coerced into a
+ * lookup key that could collide.
+ */
+export const rolesOnTeam = (
+  subjectId: string | null | undefined,
+  teamId: string,
+): ReadonlyArray<string> =>
+  subjectId == null ? [] : teamMemberships[subjectId]?.[teamId] ?? []
+
+/**
+ * DEMO role resolver — assigns a role by the request's TENANT so every role is
+ * reachable with an `x-tenant` header and zero auth setup.
+ *
+ * PRODUCTION reads the caller's REAL roles: the default resolver reads
+ * `subject.metadata.roles` (set by your auth strategy), or do a DB lookup here
+ * (`subject.id` / `subject.tenantId` → roles). Delete this and omit
+ * `resolveRoles` entirely to fall back to the metadata default.
+ *
+ * Know the failure posture whatever you put here: if this throws or rejects,
+ * rbac logs and degrades to the subject's OWN scopes. It never grants on
+ * failure — but it also does not deny a caller whose api key already carried
+ * valid scopes.
+ */
+export const demoRolesForTenant = (
+  // `Subject.tenantId` is `string | null` — an anonymous caller has no tenant.
+  tenantId: string | null | undefined,
+): ReadonlyArray<string> => {
+  const demo: Record<string, ReadonlyArray<string>> = {
+    acme:    ['admin'],
+    owners:  ['owner'],
+    editors: ['editor'],
+    readers: ['viewer'],
+  }
+  return demo[tenantId ?? ''] ?? ['viewer']
+}