@voltro/cli 0.33.0 → 0.34.0

package/templates/apps/api-saas-starter/mutations/projects.create.mutation.ts

@@ -9,6 +9,15 @@ import { Schema } from 'effect'
 export const createProject = defineMutation({
   name:   'projects.create',
   target: { table: 'projects', op: 'insert' },
+  // Members only. Note the ORDER, because it is the whole reason this line
+  // exists next to `requireEntitlement`: the guard runs in the dispatch spine
+  // BEFORE the executor and before the transaction opens, so an anonymous call
+  // is refused without ever consuming a paying tenant's metered quota. A quota
+  // gate alone would let a stranger burn the free plan's three projects.
+  //
+  // Satisfiable as shipped: a matched session gets `projects:write` from
+  // `auth.resolveScopes` (authz.ts); anonymous callers hold no scopes.
+  guards: [{ scope: 'projects:write' }],
   input:  Schema.Struct({ name: Schema.NonEmptyString }),
   output: Schema.Struct({
     id:       Schema.String,

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

@@ -3,30 +3,34 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
+  "exports": {
+    "./rpcGroup": "./rpcGroup.generated.ts"
+  },
   "scripts": {
     "dev": "voltro dev .",
     "lint": "voltro doctor .",
     "migrate": "voltro migrate",
     "test": "voltro test",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "voltro codegen . && tsc --noEmit"
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-auth": "0.33.0",
-    "@voltro/plugin-billing": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-postgres": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-auth": "0.34.0",
+    "@voltro/plugin-billing": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
+    "@voltro/sql-postgres": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-saas-starter/queries/invites.list.query.ts

@@ -1,17 +1,28 @@
 // Streaming subscription of the tenant's teammate invites. Tenant-scoped like
 // projects.list — read live from the frontend's team page with
-// `useSubscription('app', 'invites.list')`.
+// `useSubscription('invites.list')`.
 import { defineQuery } from '@voltro/protocol'
 import { Schema } from 'effect'
 
 export const listInvites = defineQuery({
   name: 'invites.list',
+  // Members only — and of the four domain procedures this is the one whose
+  // guard is load-bearing rather than tidy: the rows are teammates' EMAIL
+  // ADDRESSES. `tenant()` keeps them inside the tenant; this keeps them away
+  // from a caller who has not signed in to that tenant at all.
+  //
+  // Satisfiable as shipped: a matched session gets `team:read` from
+  // `auth.resolveScopes` (authz.ts). Anonymous callers hold no scopes and are
+  // refused with a typed `ScopeError`.
+  guards: [{ scope: 'team:read' }],
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:        Schema.String,
-    email:     Schema.String,
-    status:    Schema.String,
-    tenantId:  Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:        Schema.String,
+      email:     Schema.String,
+      status:    Schema.String,
+      tenantId:  Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-saas-starter/queries/projects.list.query.ts

@@ -1,6 +1,6 @@
 // Streaming subscription of the tenant's projects. Every change to `projects`
 // for the caller's tenant lands as a delta — the frontend upgrades its first
-// paint to live with `useSubscription('app', 'projects.list')`. The runtime
+// paint to live with `useSubscription('projects.list')`. The runtime
 // AND-merges the tenant predicate (the table carries `tenant()`), so this never
 // leaks across tenants — no manual `eq('tenantId', ...)` needed.
 import { defineQuery } from '@voltro/protocol'
@@ -8,11 +8,22 @@ import { Schema } from 'effect'
 
 export const listProjects = defineQuery({
   name: 'projects.list',
+  // Members only. `tenant()` decides WHICH rows; this decides WHO may open the
+  // subscription at all — and the guard is re-checked on EVERY delivery, so a
+  // member whose access is revoked mid-session stops receiving rows instead of
+  // keeping a live feed open on a grant that has expired.
+  //
+  // Satisfiable by this app as shipped: sign in → `voltroPasswordStrategy`
+  // matches the cookie → `auth.resolveScopes` (authz.ts) grants
+  // `projects:read`. Anonymous → no scopes → refused.
+  guards: [{ scope: 'projects:read' }],
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:        Schema.String,
-    name:      Schema.String,
-    tenantId:  Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:        Schema.String,
+      name:      Schema.String,
+      tenantId:  Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-saas-starter/tests/accessDecisions.test.ts

@@ -0,0 +1,135 @@
+// The app's ACCESS POSTURE, asserted from BOTH sides against the real resolver.
+//
+// Why this file exists rather than one guard assertion per handler test: a
+// per-procedure test hands `invoke` a subject it constructed itself, so it
+// passes with a scope literal no real caller could ever obtain. The question it
+// structurally cannot ask is the one that matters —
+// **can the caller this app actually has satisfy these guards, and is there
+// anything that still cannot?** Both halves, or the suite stays green on an app
+// that is either wide open or completely dead.
+//
+// The second failure is the easy one to ship by accident. A guard nobody can
+// satisfy is not strict security; it is a 100% outage wearing security's
+// clothes, and every unit test in this directory keeps passing while the
+// dashboard answers `ScopeError` to its own sign-in flow. So the subjects below
+// are built the way the framework builds them (`applyScopeDecision` over this
+// app's real `resolveScopes`), never by writing the scopes the assertions want.
+
+import { describe, it, expect } from 'vitest'
+import {
+  anonymousSubject,
+  applyScopeDecision,
+  checkGuards,
+  ScopeError,
+  type Subject,
+} from '@voltro/protocol'
+import { MEMBER_SCOPES, resolveScopes } from '../authz'
+
+import { listProjects } from '../queries/projects.list.query'
+import { listInvites } from '../queries/invites.list.query'
+import { createProject } from '../mutations/projects.create.mutation'
+import { createInvite } from '../mutations/invites.create.mutation'
+import { me } from '../actions/me.action'
+
+/** The Subject a browser with no session cookie gets: `voltroPasswordStrategy`
+ *  finds nothing to match, so the composer falls back to anonymous. */
+const visitor = anonymousSubject('acme')
+
+/** The Subject a signed-in member gets. The cookie resolves to a `user` Subject
+ *  carrying NO scopes (a cookie never carries authority), then the composer
+ *  applies this app's own `resolveScopes`. Built through the framework's
+ *  `applyScopeDecision` so this file cannot disagree with the runtime about how
+ *  a grant lands on a subject. */
+const member = (): Subject => {
+  const matched: Subject = { type: 'user', id: 'user_1', tenantId: 'acme', scopes: [] }
+  return applyScopeDecision(matched, { kind: 'grant', scopes: resolveScopes(matched) }).subject
+}
+
+/** Exactly what the dispatch spine asks before an executor runs — and, for the
+ *  two creates, before `requireEntitlement` can spend the tenant's quota. */
+const decide = (
+  descriptor: { readonly name: string; readonly guards?: ReadonlyArray<unknown> | undefined },
+  subject: Subject,
+): ScopeError | null =>
+  checkGuards(
+    subject,
+    descriptor.guards as Parameters<typeof checkGuards>[1],
+    { defaultDeny: true, procedure: descriptor.name },
+  )
+
+const GUARDED = [listProjects, listInvites, createProject, createInvite] as const
+
+describe('the caller this app actually has — a signed-in member', () => {
+  // If any of these regress the dashboard boots and shows nothing but denials,
+  // which no other test in this directory can see.
+  it.each(GUARDED.map((d) => [d.name, d] as const))('%s is callable', (_name, descriptor) => {
+    expect(decide(descriptor, member())).toBeNull()
+  })
+
+  it('is not just passing because the guards are empty', () => {
+    // The silent-zero shape: `checkGuards` with no guards returns null too.
+    for (const d of GUARDED) expect(d.guards?.length ?? 0).toBeGreaterThan(0)
+    expect(GUARDED).toHaveLength(4)
+  })
+})
+
+describe('the caller with no session — every domain procedure is refused', () => {
+  it.each(GUARDED.map((d) => [d.name, d] as const))('%s denies an anonymous visitor', (_name, descriptor) => {
+    expect(decide(descriptor, visitor)).toBeInstanceOf(ScopeError)
+  })
+
+  it('so a stranger cannot read teammate emails or spend a seat', () => {
+    // The two that carry real cost. `invites.list` returns email addresses;
+    // `invites.create` consumes the tenant's metered `seats` entitlement, and
+    // the guard runs BEFORE that gate — a quota is not an access control.
+    expect(decide(listInvites, visitor)).toBeInstanceOf(ScopeError)
+    expect(decide(createInvite, visitor)).toBeInstanceOf(ScopeError)
+  })
+
+  it('…and that is structural, not a resolver quirk', () => {
+    // Pinned so a framework change would surface here: `applyScopeDecision`
+    // returns an anonymous Subject UNTOUCHED under both decision kinds (the
+    // schema has no `scopes` field to write). `auth.resolveScopes` also never
+    // runs for one — it fires only on a MATCHED subject — so a session cookie
+    // is the only way into the granted set.
+    const granted = applyScopeDecision(visitor, { kind: 'grant', scopes: [...MEMBER_SCOPES] })
+    expect(granted.subject).toEqual(visitor)
+    expect(decide(createProject, granted.subject)).toBeInstanceOf(ScopeError)
+  })
+})
+
+describe('session.me stays open, and that is the point', () => {
+  it('answers an anonymous caller instead of denying them', () => {
+    // A guard here would return `ScopeError` to the dashboard's SSR gate, which
+    // would then have nothing to branch on and would never redirect to /login.
+    expect(decide(me, visitor)).toBeNull()
+    expect(me.openAccess).toBeTruthy()
+  })
+})
+
+describe('the vocabulary is a boundary, not a rubber stamp', () => {
+  it('grants no wildcard and no admin bypass', () => {
+    expect(MEMBER_SCOPES).not.toContain('*')
+    expect(MEMBER_SCOPES).not.toContain('admin:full')
+  })
+
+  it('separates inviting a person from creating a project', () => {
+    // Split by blast radius: one spends a seat and lets an outsider into the
+    // tenant, the other does not. Collapsing them into one scope is what makes
+    // a later `owner` role impossible to express.
+    const scopeOf = (d: { readonly guards?: ReadonlyArray<unknown> | undefined }): string =>
+      ((d.guards ?? []) as ReadonlyArray<{ scope?: string }>)[0]?.scope ?? ''
+    expect(scopeOf(createInvite)).not.toBe(scopeOf(createProject))
+  })
+
+  it('every guard names a scope the resolver actually grants', () => {
+    // The other half of unsatisfiability: a typo'd scope makes a procedure
+    // permanently uncallable, and nothing else in this app would notice.
+    const granted = new Set(resolveScopes(member()))
+    for (const d of GUARDED) {
+      for (const g of (d.guards ?? []) as ReadonlyArray<{ scope?: string }>) {
+        expect(granted.has(g.scope ?? '')).toBe(true)
+      }
+    }
+  })
+})

package/templates/apps/api-search/mutations/articles.create.mutation.ts

@@ -8,6 +8,20 @@ import { Schema } from 'effect'
 
 export const createArticle = defineMutation({
   name: 'articles.create',
+  // Open — with one consequence worth naming because it reaches OUTSIDE the
+  // database: on commit the search plugin's ChangeEvent tap mirrors the row
+  // into the external index (Typesense / Meilisearch / Algolia). So an
+  // unguarded write here is an unguarded write there too, and the index is
+  // usually not tenant-partitioned by the same machinery your tables are.
+  //
+  // `assertOwnTenant` still rejects a `tenantId` that does not match the
+  // resolved subject, and no auth strategy or rbac ships in this template, so a
+  // `guards: [{ scope: 'articles:write' }]` would deny every caller. Add an
+  // identity, then that guard — before you point `search` at a real cluster.
+  openAccess:
+    'inserts an article carrying only caller-supplied fields into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch). On commit it also mirrors the row into the '
+    + 'external search index, so guard it before pointing the plugin at a real cluster.',
   target: {
     table: 'articles',
     op: 'insert',

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

@@ -13,18 +13,19 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/plugin-search": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/plugin-search": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-search/queries/articles.list.query.ts

@@ -7,13 +7,26 @@ import { Schema } from 'effect'
 
 export const listArticles = defineQuery({
   name: 'articles.list',
+  // Open: the rows are this template's own seeded demo articles
+  // (`seeds/articles.seed.ts`), and `tenant()` confines every delivery to the
+  // tenantId on the request. No auth strategy and no rbac ship here, so a
+  // `guards: [{ scope }]` would be unsatisfiable and deny 100% of traffic.
+  //
+  // The plugin's own `search.query` procedure is a SEPARATE surface with its
+  // own decision, made by the plugin — this line covers only the list.
+  openAccess:
+    'lists the request tenant\'s seeded demo articles (`tenant()` scopes every delivery); the '
+    + 'seed holds no personal data. No auth strategy ships here, so the tenant comes from the '
+    + 'caller\'s `x-tenant` header.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id: Schema.String,
-    title: Schema.String,
-    body: Schema.String,
-    tag: Schema.String,
-    tenantId: Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      body: Schema.String,
+      tag: Schema.String,
+      tenantId: Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-status/README.md

@@ -14,15 +14,22 @@ voltro dev
 
 A status page is read by everyone and written by a few — so:
 
-- **Reads are PUBLIC.** `incidents.live`, `updates.list`, `components.list`
-  carry **no guard**, so an anonymous browser can `useSubscription('app',
-  'incidents.live')` and the timeline updates live.
+- **Reads are PUBLIC.** `incidents.live`, `updates.list`, `components.list` each
+  declare `openAccess: '<why>'`, so an anonymous browser can
+  `useSubscription('app', 'incidents.live')` and the timeline updates live.
 - **Writes are OPERATOR-ONLY.** Every mutation declares
   `guards: [{ scope: 'status:write' }]`, enforced by `@voltro/plugin-rbac` in the
   dispatch spine before the executor. The demo resolver (`authz.ts`) grants the
   `operator` role to the `ops` tenant; everyone else — anonymous included — is
   denied.
 
+Note that **both** of those are DECISIONS, and the framework requires one or the
+other: under `security.defaultDeny` (on by default) a wire-exposed procedure
+that declares neither `guards:` nor `openAccess:` refuses to boot. `openAccess`
+is not the lax option — it is the honest spelling of an open endpoint, and the
+reason it carries is what a reviewer reads and what `voltro doctor` prints. This
+template is the clearest place in the library to see the two side by side.
+
 ## Surface
 
 | Tag | Kind | Guard |

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

@@ -2,10 +2,15 @@
 //
 // The shape of a status page is asymmetric, and this config encodes it:
 //   • READS are PUBLIC — `incidents.live` / `updates.list` / `components.list`
-//     carry NO guard, so an anonymous visitor's browser can subscribe and see
-//     the live timeline. (A status page that requires a login is useless during
-//     an outage.)
+//     each declare `openAccess: '<why>'`, so an anonymous visitor's browser can
+//     subscribe and see the live timeline. (A status page that requires a login
+//     is useless during an outage.)
 //   • WRITES are OPERATOR-ONLY — every mutation declares a `status:write` guard.
+//
+// Both halves are DECISIONS, and the framework insists on one or the other:
+// under `security.defaultDeny` a wire-exposed procedure declaring neither does
+// not boot. `openAccess` is not the lax option — it is the honest spelling of an
+// open endpoint, and it leaves the reason where a reviewer will read it.
 //     `rbacPlugin` resolves each caller's ROLES to SCOPES and the framework
 //     enforces the guard in the dispatch spine, before the executor. `voltro
 //     check` can see the guard statically.

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

@@ -3,9 +3,11 @@
 // test that redeclares the roles only proves its own copy is self-consistent).
 //
 // A status page has exactly two kinds of caller: the PUBLIC (anonymous
-// visitors, who only READ — the live queries carry no guard) and OPERATORS
-// (who post incidents). So there is one write scope, `status:write`, held by
-// the `operator` role; `admin` gets the wildcard bypass.
+// visitors, who only READ — the live queries declare `openAccess` with their
+// reason) and OPERATORS (who post incidents). So there is one write scope,
+// `status:write`, held by the `operator` role; `admin` gets the wildcard
+// bypass. Both kinds of caller are DECIDED about: `security.defaultDeny`
+// refuses to boot a procedure that declares neither form.
 //
 // This map is ALSO the app's declared scope vocabulary: `rbacPlugin` publishes
 // its union, and `voltro check` errors on any descriptor guard requiring a

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

@@ -13,18 +13,19 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-rbac": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-postgres": "0.33.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-rbac": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
+    "@voltro/sql-postgres": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-status/queries/components.list.query.ts

@@ -1,13 +1,21 @@
-// Live list of service components + their current status. Public (no guard).
+// Live list of service components + their current status — public by design.
+// `components.create` beside it is `status:write`-guarded: reads are for
+// visitors, writes are for operators.
 import { defineQuery } from '@voltro/protocol'
 import { Schema } from 'effect'
 
 export const componentsList = defineQuery({
   name: 'components.list',
+  openAccess:
+    'the public component roster a status page exists to publish — this operator\'s own '
+    + 'service names and their current status, nothing caller-derived and no personal data. '
+    + 'Writing that roster is `status:write`-guarded.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:     Schema.String,
-    name:   Schema.String,
-    status: Schema.String,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:     Schema.String,
+      name:   Schema.String,
+      status: Schema.String,
+    }),
+  ),
 })

package/templates/apps/api-status/queries/incidents.live.query.ts

@@ -1,20 +1,33 @@
-// The live incident feed — the heart of the status page. NO `guards:`, so an
-// anonymous visitor's browser can subscribe: `useSubscription('app',
+// The live incident feed — the heart of the status page. Deliberately OPEN, so
+// an anonymous visitor's browser can subscribe: `useSubscription('app',
 // 'incidents.live')`. Every insert/update to `incidents` lands as a delta, so a
 // newly-declared incident (or a resolve) shows up on every open status page
 // within seconds — no polling.
+//
+// This template is the clearest place in the library to see that `openAccess:`
+// and `guards:` are two spellings of the SAME obligation, not a strict option
+// and a lax one. The reads here are open on purpose; the four mutations beside
+// them carry `guards: [{ scope: 'status:write' }]` and are satisfiable through
+// the real role map in `authz.ts`. Both are decisions. What the framework
+// refuses to boot on is neither.
 import { defineQuery } from '@voltro/protocol'
 import { Schema } from 'effect'
 
 export const incidentsLive = defineQuery({
   name: 'incidents.live',
+  openAccess:
+    'the public incident feed a status page exists to publish — title, impact, status and '
+    + 'timestamps of THIS operator\'s own incidents, nothing caller-derived and no personal '
+    + 'data. A status page that requires a login is useless during the outage it reports.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:         Schema.String,
-    title:      Schema.String,
-    impact:     Schema.String,
-    status:     Schema.String,
-    startedAt:  Schema.Date,
-    resolvedAt: Schema.NullOr(Schema.Date),
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:         Schema.String,
+      title:      Schema.String,
+      impact:     Schema.String,
+      status:     Schema.String,
+      startedAt:  Schema.Date,
+      resolvedAt: Schema.NullOr(Schema.Date),
+    }),
+  ),
 })

package/templates/apps/api-status/queries/updates.list.query.ts

@@ -1,17 +1,24 @@
-// Live feed of incident timeline entries. Public (no guard). The page joins
+// Live feed of incident timeline entries — public by design. The page joins
 // these to incidents by `incidentId` client-side to render each incident's
-// update history.
+// update history. `incidents.update`, which writes them, is
+// `status:write`-guarded.
 import { defineQuery } from '@voltro/protocol'
 import { Schema } from 'effect'
 
 export const updatesList = defineQuery({
   name: 'updates.list',
+  openAccess:
+    'the public incident timeline a status page exists to publish — the operator\'s own '
+    + 'update posts, nothing caller-derived and no personal data. Posting one is '
+    + '`status:write`-guarded.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id:         Schema.String,
-    incidentId: Schema.String,
-    body:       Schema.String,
-    status:     Schema.String,
-    createdAt:  Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id:         Schema.String,
+      incidentId: Schema.String,
+      body:       Schema.String,
+      status:     Schema.String,
+      createdAt:  Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-status/tests/status.test.ts

@@ -54,10 +54,18 @@ describe('incidents.create — operator-gated', () => {
 })
 
 describe('incidents.live — reads are PUBLIC', () => {
-  it('an anonymous visitor may subscribe (no guard on the query)', async () => {
+  it('an anonymous visitor may subscribe — the query declares `openAccess`', async () => {
     const ctx = ctxFor(subjectFor(null, null, 'anonymous'))
     await expect(invoke(incidentsLive, incidentsLiveHandler, {}, ctx)).resolves.toBeDefined()
   })
+
+  it('…which is a DECISION, not an omission', () => {
+    // Before `openAccess` existed, "nobody decided" and "we decided it is open"
+    // were the same descriptor and a reviewer could not tell them apart. Assert
+    // the marker is present, or this suite would keep passing on a query whose
+    // guard someone deleted by accident.
+    expect(incidentsLive.openAccess).toBeTruthy()
+  })
 })
 
 describe('incidents.create — descriptor', () => {

package/templates/apps/api-versioning/actions/documents.asOf.action.ts

@@ -6,6 +6,18 @@ import { Schema } from 'effect'
 
 export const documentAsOf = defineAction({
   name: 'documents.asOf',
+  // Open, with the same load-bearing detail as `documents.history`: the
+  // executor passes `ctx.request.subject.tenantId` into `rowAsOf` explicitly,
+  // because a version table is not auto-scoped by the `tenant()` mixin. That
+  // argument is what keeps a caller-supplied id from reading another tenant's
+  // past values; do not drop it.
+  //
+  // No auth strategy and no rbac ship in this template, so a scope guard would
+  // deny every caller rather than the wrong ones.
+  openAccess:
+    'returns one past value of a document in the CALLER\'S OWN tenant — `rowAsOf` is passed '
+    + '`subject.tenantId` explicitly, so an id from another tenant returns null. Time travel '
+    + 'reaches only where the live read already could.',
   input: Schema.Struct({ id: Schema.String, at: Schema.Number }),
   output: Schema.NullOr(Schema.Struct({
     title: Schema.String,

package/templates/apps/api-versioning/actions/documents.history.action.ts

@@ -6,6 +6,19 @@ import { Schema } from 'effect'
 
 export const documentHistory = defineAction({
   name: 'documents.history',
+  // Open — and this one needs its bound named, because a version table is a
+  // second copy of your data that the `tenant()` mixin does NOT scope for you.
+  // The executor passes `ctx.request.subject.tenantId` to `rowHistory`
+  // explicitly, so a caller-supplied id from another tenant yields nothing.
+  // Read that as the load-bearing line it is: drop the argument and this
+  // becomes a cross-tenant read of every past value.
+  //
+  // No auth strategy and no rbac ship in this template, so a
+  // `guards: [{ scope: 'documents:history' }]` would deny every caller.
+  openAccess:
+    'lists past versions of a document in the CALLER\'S OWN tenant — `rowHistory` is passed '
+    + '`subject.tenantId` explicitly, so an id from another tenant returns nothing (a version '
+    + 'table is not auto-scoped by `tenant()`). No auth strategy ships here to guard against.',
   input: Schema.Struct({ id: Schema.String }),
   output: Schema.Array(Schema.Struct({
     version: Schema.Number,

package/templates/apps/api-versioning/mutations/documents.create.mutation.ts

@@ -8,6 +8,15 @@ import { Schema } from 'effect'
 export const createDocument = defineMutation({
   name: 'documents.create',
   target: { table: 'documents', op: 'insert' },
+  // Open: writes only the title + content the caller sent, into the request's
+  // tenant (`tenant()` auto-stamps `tenantId`), and touches no existing row.
+  // No auth strategy and no rbac ship in this template, so every caller is an
+  // anonymous Subject holding no scopes and a `guards: [{ scope }]` would deny
+  // all of them rather than the wrong ones.
+  openAccess:
+    'inserts a document built only from caller-supplied fields into the request\'s tenant; '
+    + 'reads nothing and modifies no existing row. No auth strategy ships here, so there is no '
+    + 'identity a scope guard could name.',
   input: Schema.Struct({
     title: Schema.NonEmptyString,
     content: Schema.String,