@voltro/cli 0.5.0 → 0.7.0

package/dist/startEntry.d.ts

@@ -0,0 +1,5 @@
+export declare const loadDotEnv: (argv: ReadonlyArray<string>) => void;
+
+export declare const runStartCommand: (args: ReadonlyArray<string>) => Promise<number>;
+
+export { }

package/dist/startEntry.js

@@ -0,0 +1,3 @@
+import { k as e } from "./inspectMetrics-BLUBAWLb.js";
+import { t } from "./start-CWZW_4Et.js";
+export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -31,6 +31,11 @@
       "import": "./dist/inspectState.js",
       "default": "./dist/inspectState.js"
     },
+    "./devActivity": {
+      "types": "./dist/devActivity.d.ts",
+      "import": "./dist/devActivity.js",
+      "default": "./dist/devActivity.js"
+    },
     "./startup": {
       "types": "./dist/startup.d.ts",
       "import": "./dist/startup.js",
@@ -52,22 +57,22 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.5.0",
-    "@voltro/cache": "0.5.0",
-    "@voltro/data-transfer": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/kv": "0.5.0",
-    "@voltro/logger": "0.5.0",
-    "@voltro/plugin-auth": "0.5.0",
-    "@voltro/plugin-broadcast": "0.5.0",
-    "@voltro/plugin-mail": "0.5.0",
-    "@voltro/plugin-storage": "0.5.0",
-    "@voltro/plugin-webhooks": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
-    "@voltro/serverless": "0.5.0",
-    "@voltro/workflow": "0.5.0",
+    "@voltro/ai": "0.7.0",
+    "@voltro/cache": "0.7.0",
+    "@voltro/data-transfer": "0.7.0",
+    "@voltro/database": "0.7.0",
+    "@voltro/env": "0.7.0",
+    "@voltro/kv": "0.7.0",
+    "@voltro/logger": "0.7.0",
+    "@voltro/plugin-auth": "0.7.0",
+    "@voltro/plugin-broadcast": "0.7.0",
+    "@voltro/plugin-mail": "0.7.0",
+    "@voltro/plugin-storage": "0.7.0",
+    "@voltro/plugin-webhooks": "0.7.0",
+    "@voltro/protocol": "0.7.0",
+    "@voltro/runtime": "0.7.0",
+    "@voltro/serverless": "0.7.0",
+    "@voltro/workflow": "0.7.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "ts-morph": "^28.0.0"

package/templates/AGENTS.core.md

@@ -126,6 +126,14 @@ line below replaces something real apps write by hand hundreds of times.
    delivery happens after commit, with backoff and a dead-letter. Do NOT call
    the remote from the mutation (not transactional), and do not hand-build a
    deliveries table + drain cron — that IS this primitive.
+11. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
+   grant)? → **`defineConnection({ id, kind: 'oauth2' | 'pat' })`** in a
+   `*.connection.ts`, then **`ctx.connections.get(id)`**. One declaration yields
+   the encrypted per-user token store, the OAuth authorize/callback pair,
+   refresh-before-use, and the `useConnection` + `<ConnectAccount>` connect UI.
+   The credential is bound to the REQUEST's subject — there is no parameter for
+   another subject. Do NOT hand-build a per-user token table, an OAuth action
+   pair, or a "credentials resolver" over your own schema.
 
 | You're about to write | Reach for instead |
 |---|---|
@@ -139,11 +147,13 @@ line below replaces something real apps write by hand hundreds of times.
 | hand-rolled limit+1 / `hasMore` cursor paging | `paginateBy` / `paginateById` |
 | a loop issuing one `store.query` per node of a walk | `ctx.load` / `ctx.loadMany` |
 | a deliveries table + drain cron + retry worker | `ctx.outbox.enqueue` + `defineOutboxHandler` |
+| a per-user `integrationTokens` table + OAuth actions + a refresh check | `defineConnection` + `ctx.connections.get(id)` |
 | `row['name'] as string` on every field you read | nothing — `ctx.store.query(database.t….descriptor)` already returns the table's row type. A cast here means the descriptor was hand-built, or you are casting out of habit |
 
 Deep dive: **`data.md`** (`.one()`, subscribers, reactions, aggregates),
 **`database/querying.md`** (relations + `.with`), **`authentication.md`**
-(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`).
+(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`),
+**`data.md`** (`defineConnection`, the credentials vault).
 
 ### Pick the CLIENT primitive (decision rubric)
 
@@ -264,6 +274,31 @@ export default { type: 'web' as const, name: 'myWeb',
 Env, secrets, auth strategies, layers, plugins config → **`configuration.md`**.
 `store: 'memory'` loses data on restart — default to `postgres` for real work.
 
+**NEVER hardcode a secret, not even as a fallback.** Not
+`process.env.X ?? 'dev-only-change-me'`, not a value committed to `.env`. A
+hardcoded fallback means every environment that forgot to configure the
+variable shares one key that is readable by anyone with the repo — and it looks
+completely healthy until someone forges a session. Declare it instead:
+
+```ts
+env: defineEnv({
+  VOLTRO_SESSION_SECRET: envVar.secret({ generate: 'base64url' }),  // ours → minted
+  STRIPE_SECRET_KEY:     envVar.secret({ minLength: 20 }),          // theirs → must be set
+})
+```
+
+`generate` makes `voltro dev` mint a unique per-project value into a gitignored
+`.env.local` on first boot, so local development needs no placeholder at all.
+Omit it for third-party credentials — an invented API key authenticates nobody,
+and failing the boot gate is the useful outcome. Deployment values come from
+`voltro secret generate <purpose>`; `voltro serve` refuses to start without them.
+
+Also: don't read `process.env` for a secret at config time to pass it to a
+plugin. `app.config.ts` is evaluated BEFORE the env gate and before minting, so
+that read is what pushes you into writing a fallback. `authRoutesPlugin` and
+`voltroPasswordStrategy` resolve `VOLTRO_SESSION_SECRET` themselves — omit
+`secret:` entirely.
+
 ## The browser/server boundary (load-bearing — verify when you touch it)
 
 Codegen pulls every **descriptor** (`*.query.ts` / `*.mutation.ts` /

package/templates/AGENTS.md

@@ -126,6 +126,14 @@ line below replaces something real apps write by hand hundreds of times.
    delivery happens after commit, with backoff and a dead-letter. Do NOT call
    the remote from the mutation (not transactional), and do not hand-build a
    deliveries table + drain cron — that IS this primitive.
+11. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
+   grant)? → **`defineConnection({ id, kind: 'oauth2' | 'pat' })`** in a
+   `*.connection.ts`, then **`ctx.connections.get(id)`**. One declaration yields
+   the encrypted per-user token store, the OAuth authorize/callback pair,
+   refresh-before-use, and the `useConnection` + `<ConnectAccount>` connect UI.
+   The credential is bound to the REQUEST's subject — there is no parameter for
+   another subject. Do NOT hand-build a per-user token table, an OAuth action
+   pair, or a "credentials resolver" over your own schema.
 
 | You're about to write | Reach for instead |
 |---|---|
@@ -139,11 +147,13 @@ line below replaces something real apps write by hand hundreds of times.
 | hand-rolled limit+1 / `hasMore` cursor paging | `paginateBy` / `paginateById` |
 | a loop issuing one `store.query` per node of a walk | `ctx.load` / `ctx.loadMany` |
 | a deliveries table + drain cron + retry worker | `ctx.outbox.enqueue` + `defineOutboxHandler` |
+| a per-user `integrationTokens` table + OAuth actions + a refresh check | `defineConnection` + `ctx.connections.get(id)` |
 | `row['name'] as string` on every field you read | nothing — `ctx.store.query(database.t….descriptor)` already returns the table's row type. A cast here means the descriptor was hand-built, or you are casting out of habit |
 
 Deep dive: **`data.md`** (`.one()`, subscribers, reactions, aggregates),
 **`database/querying.md`** (relations + `.with`), **`authentication.md`**
-(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`).
+(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`),
+**`data.md`** (`defineConnection`, the credentials vault).
 
 ### Pick the CLIENT primitive (decision rubric)
 
@@ -264,6 +274,31 @@ export default { type: 'web' as const, name: 'myWeb',
 Env, secrets, auth strategies, layers, plugins config → **`configuration.md`**.
 `store: 'memory'` loses data on restart — default to `postgres` for real work.
 
+**NEVER hardcode a secret, not even as a fallback.** Not
+`process.env.X ?? 'dev-only-change-me'`, not a value committed to `.env`. A
+hardcoded fallback means every environment that forgot to configure the
+variable shares one key that is readable by anyone with the repo — and it looks
+completely healthy until someone forges a session. Declare it instead:
+
+```ts
+env: defineEnv({
+  VOLTRO_SESSION_SECRET: envVar.secret({ generate: 'base64url' }),  // ours → minted
+  STRIPE_SECRET_KEY:     envVar.secret({ minLength: 20 }),          // theirs → must be set
+})
+```
+
+`generate` makes `voltro dev` mint a unique per-project value into a gitignored
+`.env.local` on first boot, so local development needs no placeholder at all.
+Omit it for third-party credentials — an invented API key authenticates nobody,
+and failing the boot gate is the useful outcome. Deployment values come from
+`voltro secret generate <purpose>`; `voltro serve` refuses to start without them.
+
+Also: don't read `process.env` for a secret at config time to pass it to a
+plugin. `app.config.ts` is evaluated BEFORE the env gate and before minting, so
+that read is what pushes you into writing a fallback. `authRoutesPlugin` and
+`voltroPasswordStrategy` resolve `VOLTRO_SESSION_SECRET` themselves — omit
+`secret:` entirely.
+
 ## The browser/server boundary (load-bearing — verify when you touch it)
 
 Codegen pulls every **descriptor** (`*.query.ts` / `*.mutation.ts` /

package/templates/agent-docs/_manifest.json

@@ -17,7 +17,7 @@
       "group": null,
       "description": "How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol.",
       "path": "agent-docs/authentication.md",
-      "files": 11
+      "files": 12
     },
     {
       "id": "caching",
@@ -53,7 +53,7 @@
       "group": null,
       "description": "How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies.",
       "path": "agent-docs/data.md",
-      "files": 14
+      "files": 15
     },
     {
       "id": "database/advancedqueries",
@@ -161,7 +161,7 @@
       "group": null,
       "description": "Voltro Cloud (coming soon) — the managed runtime for your Voltro project. Today the Free control plane registers + observes your self-hosted apps.",
       "path": "agent-docs/deployment.md",
-      "files": 6
+      "files": 7
     },
     {
       "id": "internationalization",

package/templates/agent-docs/ai.md

@@ -438,7 +438,18 @@ So one agent can run GPT-5.5 on a dedicated key while another inherits the env d
 **Model picker / routing** — the input selects among server-owned configs (UI picker, cost/size routing, plan tiers):
 
 ```tsx
-// descriptor: input: Schema.Struct({ prompt: Schema.String, tier: Schema.Literal('fast', 'smart') })
+// support.agent.tsx — DESCRIPTOR: the picker is constrained to server-known tiers
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({ prompt: Schema.String, tier: Schema.Literal('fast', 'smart') }),
+})
+
+// support.agent.server.tsx — EXECUTOR: map the tier onto server-owned configs
+import { defineAgentExecutor } from '@voltro/ai'
+
 export default defineAgentExecutor(support, {
   model: (input) => input.tier === 'smart'
     ? { name: 'openai', model: 'gpt-5.5' }
@@ -449,7 +460,18 @@ export default defineAgentExecutor(support, {
 **BYOK (bring your own key)** — the caller supplies their OWN key; you fold it into the returned config:
 
 ```tsx
-// descriptor: input: Schema.Struct({ prompt: Schema.String, apiKey: Schema.String })
+// support.agent.tsx — DESCRIPTOR: the caller's own key is part of the input
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({ prompt: Schema.String, apiKey: Schema.String }),
+})
+
+// support.agent.server.tsx — EXECUTOR: fold the caller's key into the config
+import { defineAgentExecutor } from '@voltro/ai'
+
 export default defineAgentExecutor(support, {
   model: (input) => ({ name: 'openai', model: 'gpt-5.5', apiKey: input.apiKey }),
 })
@@ -505,10 +527,20 @@ System prompts go in the agent definition's `system` field, NOT in the messages
 The `system` field lives on the **executor**. Template it with per-call values (locale, persona, plan-specific instructions) — the function receives the input typed from the descriptor's schema:
 
 ```tsx
+// support.agent.tsx — DESCRIPTOR: every field `system` reads must be declared here
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({ prompt: Schema.String, plan: Schema.optional(Schema.String) }),
+})
+
 // support.agent.server.tsx — `plan` comes from the descriptor's input schema
+import { defineAgentExecutor } from '@voltro/ai'
+
 export default defineAgentExecutor(support, {
   system: (input) => `You are speaking with a user on the ${input.plan ?? 'free'} plan.`,
-  // …
 })
 ```
 

package/templates/agent-docs/authentication.md

@@ -351,6 +351,29 @@ if (ctx.subject.type === 'anonymous') {
 }
 ```
 
+## App metadata — `subjectFromUser(user, { metadata })`
+
+`metadata` is the free-form slot the framework itself never reads. It is where a provider credential captured at login belongs — a plugin's `credentialsResolver` reads it back per request (`@voltro/plugin-atlassian` looks for `subject.metadata.jiraToken`, say), so nothing has to be re-fetched or stored server-side per call.
+
+Pass it when you build the Subject:
+
+```ts
+import { subjectFromUser } from '@voltro/plugin-auth'
+
+const subject = subjectFromUser(user, {
+  memberships,                              // → metadata.memberships
+  metadata: { jiraToken: atlassianPat },    // → metadata.jiraToken
+})
+```
+
+The two merge — neither clobbers the other. **When a `memberships` key appears in both,** the dedicated `memberships` option wins: it is the typed input, and it is the one projected into the `{ tenantId, role }` shape `subjectMemberships()` and the tenant switcher read. Without the option, a `memberships` key inside `metadata` passes through unchanged. A Subject built with neither option has no `metadata` key at all.
+
+Keys set this way survive the login paths: the sign-in / sign-up / magic-link / passkey handlers merge `sessionId` onto the existing slot, and the password strategy merges `provider` — they add, they don't replace. The one exception is naming a key `sessionId` or `provider` yourself; those two are overwritten by design.
+
+**It survives a tenant switch too.** A switch rebuilds the Subject from the user record, so the built-in `/switch-tenant` route passes the caller's current `subject.metadata` through to `handleSwitchTenant` — a credential parked here keeps working after the user changes tenant. Calling `handleSwitchTenant` yourself? Pass `metadata` or the credential is dropped, and the symptom is unpleasant to diagnose: the user stays signed in while every call to the provider starts failing. `memberships` is deliberately *not* carried — it is re-derived for the target tenant, and a carried copy would report a role the user does not hold there.
+
+Two things not to put here. **Anything the caller could benefit from changing** — the slot rides the signed session cookie, so it is tamper-evident, but it is also stale by design: it reflects the moment of sign-in, not the current database. And **anything large** — it is re-serialised into every session cookie.
+
 ## Resolution
 
 `AuthMiddleware` resolves a `Subject` on every request by running the [strategy chain](/docs/authentication/strategies) — `composeAuthStrategies` evaluates each strategy in order, first `matched` wins, first `failed` short-circuits to anonymous. A typical chain resolves, in order:
@@ -1771,6 +1794,12 @@ guards: [
 ]
 ```
 
+A guard answers **may you call this**. It cannot answer **which rows may you
+see** — a list has no single resource to name. For visibility that follows from a
+relationship ("tickets on teams I hold a role on"), declare a
+[row filter](/docs/authentication/row-level-security) instead; it AND-merges a
+subject-derived predicate into every read, so it narrows and never grants.
+
 ### Activate it: register a tuple source
 
 A relationship guard needs to read the caller's relations. That comes from the
@@ -1858,3 +1887,238 @@ Full API — including the batch `useResourceCans` for per-row gating — in
 `rebacPolicyGraph()` returns every resource type, its actions, the relations each
 grants, and the implication edges — the policy graph a dashboard or an AI agent
 reads to reason about authority without grepping the code.
+
+
+
+---
+
+<!-- source: en/authentication/row-level-security.md -->
+## Row-level security
+
+_setRowFilter — a subject-derived predicate AND-merged into every read, so relational visibility ("rows on teams I hold a role on") is declared once instead of hand-written into every list handler and every subscription._
+
+Reads already scope themselves by tenant and by soft-delete, and a descriptor's
+[`guards:`](/docs/authentication/authorization#enforce-it-declaratively-guards)
+decide whether you may call a procedure **at all**. Neither of those says which
+**rows** you may see.
+
+That gap matters as soon as visibility is *relational* — "tickets on teams I hold
+a role on". Without a row filter, that predicate has to be hand-written into
+every list handler and every subscription, and a filter you have to remember is a
+filter you only have to forget once.
+
+`setRowFilter` declares it once. The framework AND-merges the resulting predicate
+into every read.
+
+## The two phases
+
+```ts no-check
+setRowFilter({
+  load:      (subject) => Effect<Ctx>,                    // ASYNC, once per request
+  predicate: (ctx, table) => Predicate | undefined,       // PURE + SYNC, per read
+})
+```
+
+- **`load`** resolves everything the predicates need — the memberships, the role
+  rows, the project ids — **once per request**. It may read the store. This is
+  the expensive half.
+- **`predicate`** derives the filter for one table from what `load` already
+  fetched. It runs on **every read**, so it must be pure and synchronous. Return
+  `undefined` for a table this filter does not constrain — which is most tables.
+
+### Why two halves rather than one function
+
+A single async `(subject, table) => Promise<Predicate>` would be simpler to
+declare and much worse to run. Every read on the hot path would await, and the
+obvious implementation would re-query the membership tables **once per query** —
+so a handler that reads five tables pays five membership lookups.
+
+Splitting the phases makes the per-read cost a map lookup and makes the
+per-request cost explicit and visible: one load, reused.
+
+## A worked example
+
+The motivating shape — rows on teams the caller holds a role on:
+
+```ts no-check
+// apps/api/rls.startup.ts
+import { Effect } from 'effect'
+import { eq, inSet } from '@voltro/database'
+import { setRowFilter } from '@voltro/runtime'
+import { database } from './database/index'
+
+setRowFilter({
+  // ASYNC — once per request. Read your own tables here.
+  load: (subject) =>
+    Effect.promise(async () => {
+      const rows = await database.teamMembers
+        .where(eq('userId', subject.id ?? ''))
+        .all()
+      return rows.map((row) => row.teamId)
+    }),
+
+  // PURE + SYNC — runs on every read.
+  predicate: (teamIds: ReadonlyArray<string>, table: string) =>
+    table === 'tickets' ? inSet('teamId', teamIds) : undefined,
+})
+```
+
+Register it at boot — `app.config.ts` or a `*.startup.ts`. It is process-global
+and last-write-wins. `Ctx` is whatever your `load` returns; the framework never
+inspects it.
+
+With that registered, an ordinary list query needs no filter of its own:
+
+```ts no-check
+// apps/api/queries/tickets.list.query.server.ts
+export default () => database.tickets.orderBy('createdAt', 'desc')
+```
+
+A caller with no memberships gets zero rows. Nothing in the handler says so.
+
+## It can only narrow, never grant
+
+The predicate is **AND-merged** onto whatever the handler already asked for — it
+never replaces it. A row filter cannot widen a query, so it can never become an
+accidental grant:
+
+```ts no-check
+// the handler asks for one ticket; the filter still applies
+database.tickets.where(eq('id', 'ticket-42'))
+// → id = 'ticket-42' AND teamId IN (…the caller's teams)
+```
+
+## Both read paths are filtered
+
+The filter applies to descriptor reads **and** to the fluent builder. A filter
+present on only one read path is not a filter, it is a detour:
+
+```ts no-check
+await ctx.store.query(tickets.descriptor)   // filtered
+await ctx.store.select('tickets').all()     // filtered
+```
+
+## When `load` fails
+
+`load` reads your store — for relational visibility it *must* — which makes it
+exactly the kind of call that blips. Two separate questions follow from a
+failure, and the answers are deliberately different.
+
+### First: is the failure even real? (`retry`)
+
+A transient failure must never reach the decision below, because once it gets
+there it is indistinguishable from an authorization answer. So `load` runs under
+a bounded retry before anything is concluded from it:
+
+```ts no-check
+import { Schedule } from 'effect'
+
+setRowFilter({
+  load,
+  predicate,
+  retry: Schedule.recurs(5),   // your own schedule
+  // retry: false,             // exactly one attempt
+})
+```
+
+The default is `DEFAULT_ROW_FILTER_RETRY` (exported from `@voltro/runtime`):
+**three attempts, backing off exponentially from 20ms** — about 60ms of added
+latency in the worst case. It is sized for a blip (a connection reaped from the
+pool, a failover flap), not for an outage. A `load` still failing after that is
+not having a bad moment, and stretching the schedule only turns a fast honest
+error into a slow one while holding the request open.
+
+### Then: what does a real failure mean? (`onLoadError`)
+
+Not "you may see nothing". **We cannot tell what you may see.** Those are
+different facts and only one of them is a fact — so the default raises a typed
+error:
+
+```ts no-check
+setRowFilter({
+  load,
+  predicate,
+  onLoadError: 'fail',   // default — raises RowFilterUnavailable
+  // onLoadError: 'deny', // degrade to zero rows instead
+})
+```
+
+- **`'fail'` (default)** — the request fails with the typed
+  `RowFilterUnavailable`. Handle it in your UI as an error state, the same as any
+  other failed request.
+- **`'deny'`** — refusal is expressed as a predicate matching nothing, so the
+  read returns an empty result. Choose this only if you have looked at the screen
+  and are content for it to render empty during an outage. Your `onError`
+  reporter still fires, so the failure stays findable in logs even though the
+  response is a 200.
+
+The default changed *to* `'fail'`, and the reasoning is worth stating plainly
+because the old default looked defensible: an empty result for an infrastructure
+failure is byte-identical to legitimate emptiness. The user reads "you have no
+tickets". The operator reads a healthy 200. The outage is invisible to both —
+the most misleading outcome on offer. Every constrained page **is** broken when
+this happens, and saying so is the only outcome either party can act on.
+
+### There is no fail-open option
+
+A frequent request, and a deliberate refusal: there is no policy that serves
+**unfiltered** rows when the filter is unavailable, falling back to whatever
+check the handler carries.
+
+Failing open on an authorization filter leaks data precisely when the system is
+under stress and nobody is reading dashboards. And it is only safe if every
+handler still carries its own row-level check — which is the entire thing a row
+filter exists to remove. A codebase where fail-open is safe is a codebase that
+did not need `setRowFilter`.
+
+Both policies above are fail-**closed**: neither can ever produce an unfiltered
+read.
+
+### Subscriptions
+
+A resolution failure mid-stream **revokes** the subscription and emits a typed
+error frame, rather than delivering an empty snapshot — an empty snapshot on a
+live subscription reads to a client as "every row you could see was just
+deleted". Make sure your subscription error handling surfaces it.
+
+## What does *not* bypass it
+
+| | Bypasses the row filter? |
+|---|---|
+| `.unscoped()` / `crossTenant` | **No** |
+| a `system` subject | Yes |
+
+`.unscoped()` and `crossTenant` exist for legitimate cross-tenant admin reads.
+They opt out of **tenant isolation**, not out of **authorization** — letting them
+also drop row visibility would turn an isolation opt-out into an authorization
+one, which is exactly the silent widening this feature exists to prevent.
+
+Only a `system` subject bypasses, because a system subject is the framework
+acting as itself — janitor sweeps, migrations, the scheduler — rather than on
+behalf of a user. That bypass is deliberately the narrow, explicit one.
+
+Apps that register no filter pay nothing.
+
+## Subscriptions re-resolve it
+
+A subscription is the one read path that stays open for hours, so it is the one
+where a stale filter would matter most. Before every delivery the runtime
+re-derives the read from the **unfiltered base descriptor** and re-applies the
+freshly resolved filter.
+
+A membership that ends mid-subscription therefore stops serving rows — the
+caller's open ticket list drops the rows they can no longer see, without a
+refresh and without the subscription having to be torn down.
+
+## Row filters vs. guards
+
+They answer different questions, and a complete policy usually wants both:
+
+| | Question | Failure |
+|---|---|---|
+| [`guards:`](/docs/authentication/authorization#enforce-it-declaratively-guards) | May you call this procedure? | typed `ScopeError`, before the executor runs |
+| `setRowFilter` | Which rows may you see? | the rows are simply absent — unless the filter itself could not load, which is a typed `RowFilterUnavailable` |
+
+A guard is the right tool for "may this caller edit *this* ticket". A row filter
+is the right tool for "which tickets appear in the list at all" — a question a
+guard cannot answer, because there is no single resource to name.