@voltro/cli 0.32.0 → 0.34.0

package/templates/agent-docs/plugins/cdc-out.md

@@ -44,6 +44,11 @@ export default {
       maxAttempts: 5,              // per-record delivery attempts before dead-letter
       backoffBaseMs: 200,          // first retry delay; doubles per attempt, jittered
       deliveryTimeoutMs: 10_000,   // per-attempt timeout — aborts the sink call
+      leaseTtlMs: 15_000,          // leader lease; heartbeat renews at ttl/3
+      // Fleet-scope handoff (see "Delivery guarantees"):
+      dedupWindowMs: 60_000,       // how long an enqueue claim is kept — must exceed leaseTtlMs
+      handoffBufferMs: 60_000,     // how far back each replica buffers for a takeover to drain
+      handoffBufferSize: 10_000,   // hard ceiling on buffered changes per replica
     }),
   ],
 }
@@ -73,12 +78,44 @@ via `extendSchema`, migrated by `voltro dev`). The row's TypeID id **is** the
 record's `deliveryKey` — unique across replicas, stable across restarts and
 retries.
 
-- **Exactly-once ENQUEUE, fleet-wide.** On `changeScope: 'local'` stores each
-  replica enqueues only its OWN commits (injected cross-replica events are
-  skipped). On `'fleet'` stores (postgres `changeStrategy: 'cdc'`
-  LISTEN/NOTIFY, mysql binlog) only the holder of the leader lease
-  (`_voltro_cdcout_leases`, TTL-heartbeat) enqueues. Fail closed: no lease,
-  no enqueue.
+- **Enqueue is de-duplicated per observed change, fleet-wide, across leadership
+  handovers — with one hole: a replica that dies between winning a change's
+  claim and inserting its outbox row loses that change, because the claim
+  survives and nothing rescans orphan claims.** (Those are two statements with
+  no transaction around them, which is why this does not say "exactly-once".)
+
+  On `changeScope: 'local'` stores each replica enqueues only its OWN commits
+  (injected cross-replica events are skipped), so a change is observed by
+  exactly one process and needs nothing further.
+
+  On `'fleet'` stores (postgres `changeStrategy: 'cdc'` LISTEN/NOTIFY, mysql
+  binlog) EVERY replica sees the full stream, so every replica **buffers** it
+  in memory (`handoffBufferMs`, capped at `handoffBufferSize` entries, oldest
+  dropped first). The holder of the leader lease (`_voltro_cdcout_leases`,
+  TTL-heartbeat) enqueues as it goes; a replica that WINS the lease drains the
+  window its predecessor never got to. Enqueue is **idempotent per change
+  identity**: each change is keyed by a `changeKey` every replica computes
+  alike — a digest of `(pipe, op, row id, new image, old image)` plus an
+  occurrence counter that keeps two byte-identical changes to one row apart —
+  and claimed in `_voltro_cdcout_claims` under `unique(pipe, changeKey)`. So
+  the rows the dying leader already wrote collapse instead of duplicating, and
+  the ones it never reached are written by its successor.
+
+  A replica that boots into a fleet that is **already running** adopts the
+  fleet's occurrence counters from the claims already in the database before it
+  keys anything — otherwise its first sighting of an already-claimed change
+  would key occurrence 0, collide, and be dropped as a duplicate it is not.
+  `GET /_voltro/inspect/plugins/cdc-out/sinks` reports `handoff.seeded` and
+  `handoff.awaitingSeed` so you can see that happen rather than assume it.
+
+  What still bounds it, stated plainly: a change **no surviving replica
+  observed** is gone (the transport delivered it only to the dead process); a
+  handoff that takes longer than `handoffBufferMs` loses whatever aged out of
+  the buffer, and that count is reported as `handoff.dropped` on
+  `GET /_voltro/inspect/plugins/cdc-out/sinks` rather than dropped silently.
+  `dedupWindowMs` (default `max(60_000, 4 × leaseTtlMs)`) is how long a claim
+  is kept; it **must exceed `leaseTtlMs`** — a claim that expires mid-handoff
+  is a duplicate window, and the plugin refuses to boot with one.
 - **At-least-once FROM ENQUEUE.** The tap is post-commit — a crash in the
   narrow window between commit and the outbox insert loses that one event;
   the plugin does not claim better. From enqueue on, delivery survives
@@ -92,7 +129,9 @@ retries.
   `GET /_voltro/inspect/plugins/cdc-out/dead-letter` — and unblocks the pipe.
 - **Bounded storage.** Delivered/dead rows are purged by the framework
   retention sweep after `retentionHours` (default 72, env
-  `CDCOUT_RETENTION_HOURS`); pending rows are never purged.
+  `CDCOUT_RETENTION_HOURS`); pending rows are never purged. Enqueue claims are
+  short-lived by design — purged after `dedupWindowMs`, which only has to
+  outlive a leadership handoff.
 
 ## Multi-tenancy
 

package/templates/agent-docs/plugins/clickhouse.md

@@ -61,7 +61,7 @@ on graceful shutdown.
 | `password` | `string` | — | |
 | `database` | `string` | `'default'` | The plugin creates the events table inside it on first boot. |
 | `table` | `string` | `'events'` | Override the events-table name. |
-| `mirrorTables` | `ReadonlyArray<string>` | `[]` (events-only) | Reactive tables to CDC-mirror into `voltro_mirror_<table>` (a `ReplacingMergeTree`) so analytical queries JOIN events against live user data. |
+| `mirrorTables` | `ReadonlyArray<string>` | `[]` (events-only) | Reactive tables to CDC-mirror into `voltro_mirror_<table>` (a `ReplacingMergeTree(version)` over `{ id, data, version, is_deleted }`) so analytical queries JOIN events against live user data. The version is the framework's commit-order stamp, so a change that arrives late loses the collapse. |
 | `mirrorPrimaryKey` | `string` | `'id'` | Primary-key column on the mirrored source rows. |
 
 `database`, `table`, and each `mirrorTables` entry are validated as SQL

package/templates/agent-docs/plugins/duckdb.md

@@ -53,7 +53,7 @@ connection + instance are closed on graceful shutdown.
 | Option | Type | Default | Notes |
 |---|---|---|---|
 | `path` | `string` | in-memory | A file path (`.voltro/analytics.duckdb`) → durable across restarts, single-process. Omit or pass `:memory:` → events live in process memory, lost on restart (ephemeral dev / tests). |
-| `mirrorTables` | `ReadonlyArray<string>` | `[]` (events-only) | Reactive tables to CDC-mirror into `voltro_mirror_<table>` inside DuckDB so analytical queries JOIN events against live user data. |
+| `mirrorTables` | `ReadonlyArray<string>` | `[]` (events-only) | Reactive tables to CDC-mirror into `voltro_mirror_<table>` (`{ id, data, version, is_deleted }`) inside DuckDB so analytical queries JOIN events against live user data. Deletes write a tombstone — filter `is_deleted = false`. |
 | `mirrorPrimaryKey` | `string` | `'id'` | Primary-key column on the mirrored source rows. |
 
 ```ts

package/templates/agent-docs/plugins/flags.md

@@ -109,6 +109,138 @@ GET /_voltro/inspect/plugins/flags/audit?flag=beta # one flag's history
 
 The `POST /toggle` body accepts an optional `actor` (the acting admin id) that is stored on the audit row. On the `memory` tier there is no durable audit (the endpoint returns an empty trail with a note).
 
+## Typed flags — `defineFlag()`
+
+A flag's VALUE had no type. `FlagVariant.value` is the `FlagVariantValue` union (`string | number | boolean | null | array | object`), so `{ name: 'big', value: 'lots' }` on a flag every reader treats as a number typechecked, and the mistake showed up at the call site as `NaN`.
+
+`defineFlag()` gives a flag a value **Schema**, and the flag is browser-safe by construction — ONE declaration, imported by `app.config.ts` and by the component that reads it.
+
+```ts
+// apps/api/lib/flags.ts
+import { Schema } from 'effect'
+import { defineFlag } from '@voltro/plugin-flags'
+
+export const checkoutButton = defineFlag({
+  key: 'checkout.button',
+  value: Schema.Literal('blue', 'green'),
+  default: 'blue',
+  variants: [{ name: 'control', value: 'blue' }, { name: 'green', value: 'green' }],
+})
+
+export const pageSize = defineFlag({
+  key: 'search.pageSize',
+  value: Schema.Number,
+  default: 20,
+// default: 'twenty',   ← Type 'string' is not assignable to type 'number'
+})
+```
+
+Register them with `flagsPlugin({ typedFlags: [checkoutButton, pageSize] })`. Keys share one namespace with `flags: { … }`; declaring a key in both is refused at construction.
+
+Read them typed on either side:
+
+```ts
+import { flagValue, flagVariant } from '@voltro/plugin-flags'
+const size: number = flagValue(ctx, pageSize)          // server
+const arm = flagVariant(ctx, checkoutButton)           // the served variant NAME, or null
+```
+
+```tsx
+import { useFlagValue } from '@voltro/plugin-flags/web'
+const colour = useFlagValue(checkoutButton)            // 'blue' | 'green'
+```
+
+### Which half a Schema reaches, precisely
+
+**Authored** values — `default`, every `variants[].value` — are checked by `tsc`. That is the headline and it is enforced by tests that fail `typecheck` if those lines ever start compiling.
+
+**Runtime** values cannot be. A postgres-tier override row, or a dashboard edit, is JSON long after `tsc` ran. So the same Schema is the runtime gate: an override whose variant values do not decode is **refused whole**, the code-declared definition stands, and the refusal is logged and shown in the dashboard panel. Not partially applied — dropping the one bad arm re-normalises the weights of the rest, silently reallocating every subject.
+
+Declaration also DECODES the authored default, which catches what a type cannot: `Schema.Int`'s TypeScript type is `number`, so `default: 20.5` typechecks and is a value the flag could never legally serve.
+
+## Dead-flag detection
+
+Every flag system accumulates flags nobody removes. `GET /_voltro/inspect/plugins/flags/list` carries a lifecycle report (rendered by the dashboard panel) built on two independent axes — and only some of it is a proof.
+
+**`shape`** is decided from the DEFINITION alone. No observation, no window:
+
+| shape | meaning |
+|---|---|
+| `constantOn` | `rollout` 100, no targeting, no variants, no live schedule — resolves `true` for everyone, forever |
+| `constantOff` | `enabled: false`, or `rollout: 0` |
+| `expired` | a `schedule.deactivateAt` that has passed — it can never be on again |
+| `notYetActive` | a future `activateAt` — pending, not dead |
+| `conditional` | genuinely selects between callers |
+
+**`usage`** is decided from observed evaluations, and exactly one state is a proof:
+
+| usage | meaning |
+|---|---|
+| `evaluated` | read server-side inside the threshold |
+| `stale` | reads EXIST in the window and the newest is older than the threshold. **Provable** |
+| `neverObserved` | no server-side read at all. Consistent with "dead" AND with "declared last Tuesday" — reported, never asserted, **never a removal candidate** |
+| `untracked` | nothing is recording |
+
+`removalCandidate` is set only by a proof: a constant/expired shape, or `stale`.
+
+### What it cannot see
+
+Shipped in the payload and rendered in the panel, not buried here:
+
+- **Reachability is not decided.** "Not evaluated since \<date>" is a measurement; "this code path is dead" is not decidable in general. A Black-Friday flag, a flag behind an admin route nobody visited this month, and a flag whose last call site was deleted are indistinguishable.
+- **Only SERVER-side reads count** — `isFlagEnabled` / `requireFlag` / `flagValue` / a `gatedBy` interception. `useFlag()` in the browser reads from the bulk set the server already sent, so the key never arrives as a named read. Bulk deliveries are recorded separately and never counted as use: one `useFlags()` poll evaluates the whole registry and would otherwise mark every flag in the app alive forever.
+- **The window is finite**, bounded by the observation table's retention. A flag last read BEFORE the window has no observation at all and reads `neverObserved` — exactly what a flag declared this morning reads.
+- On the day you turn tracking on, nothing has been observed, so every flag is `neverObserved` and nothing is proposed for removal. It is that SPLIT that prevents the day-one "everything is dead" report, not a coverage gate on top of it: such a gate is unreachable, because the observation that dates a stale flag is itself inside the window.
+
+### Tunables
+
+```ts
+flagsPlugin({
+  store: 'postgres',
+  usage: {
+    track: true,            // default: on with store:'postgres' (there is nowhere to write on memory)
+    flushIntervalMs: 300_000,   // the report resolves to a DAY, so a tighter interval buys nothing
+    staleAfterDays: 30,
+    retentionDays: 90,      // also VOLTRO_FLAG_USAGE_TTL_HOURS; the report's observation ceiling
+  },
+})
+```
+
+Observations land in `_voltro_feature_flag_usage`, one row per (flag, UTC day, source), retention-swept. `track: true` on the `memory` tier is refused at construction rather than silently observing nothing, and `staleAfterDays > retentionDays` is refused because staleness could then never be proven.
+
+## A flag can carry an experiment
+
+`defineExperiment` (`@voltro/runtime`) maintains standing A/B results as **live IVM aggregates recomputed per-write from CDC deltas** — real-time uplift with no batch pipeline. A flag can name one:
+
+```ts
+export const checkoutButton = defineFlag({
+  key: 'checkout.button',
+  value: Schema.Literal('blue', 'green'),
+  default: 'blue',
+  variants: [{ name: 'control', value: 'blue' }, { name: 'green', value: 'green' }],
+  experiment: 'checkout-colour',
+})
+
+// apps/api/experiments/checkoutColour.experiment.ts
+export default defineExperiment({
+  name: 'checkout-colour',
+  on: { table: 'orders' },
+  variantFrom: 'checkoutArm',                        // ← the arm the FLAG served
+  variants: [{ name: 'control' }, { name: 'green' }],
+  metric: { kind: 'conversionRate', column: 'completed' },
+})
+```
+
+Persist the served arm on the row you want to measure:
+
+```ts
+await ctx.store.insert('orders', { …, checkoutArm: flagVariant(ctx, checkoutButton) })
+```
+
+**Why `variantFrom` and not just a name.** The flag assigns by hashing FNV-1a over `${key}:variant`; an experiment in `subject` mode hashes over the EXPERIMENT name. Both are stable and uniform, and they are INDEPENDENT — roughly half the subjects served `green` land in the experiment's `control` arm. The uplift would be live, precise, and measuring a split nobody experienced. One assignment, persisted, read by the experiment.
+
+`flagsPlugin({ typedFlags, experiments })` **refuses to construct** when the link is wrong: a missing experiment, an experiment still in `subject` mode, an experiment-side holdout (carved AT assignment, which this experiment does not do), or arm names that do not match. Each of those is otherwise a wrong number rather than an error — a name mismatch shows up as a permanently-empty arm beside a permanently-full one, which reads as "the treatment has no effect".
+
 ## Three ways to use a flag
 
 **1. Declarative gate** — `gatedBy: { '<rpcTag>': '<flag>' }` (exact tag or `/regex/`). An off flag fails the call with typed `FlagDisabled` before the handler runs (merged into every procedure's wire-error union → typed on the client).

package/templates/agent-docs/plugins/governance.md

@@ -29,11 +29,11 @@ export default {
         { table: 'events', ttlMs: 90 * 86_400_000 },                                  // delete after 90 days
         { table: 'users', ttlMs: 365 * 86_400_000, action: 'anonymize', anonymizeFields: ['email', 'name'] },
       ],
-      // GDPR: which tables reference a subject + by which column.
+      // GDPR: DERIVE which tables hold a subject's data from the schema.
+      deriveSubjectScopes: { subjectTable: 'users' },
+      // …plus anything the schema cannot encode (see below).
       subjectScopes: [
-        { table: 'users', subjectField: 'id' },
-        { table: 'posts', subjectField: 'userId' },
-        { table: 'comments', subjectField: 'authorId' },
+        { table: 'audit_trail', subjectField: 'actorRef' },
       ],
       sweepIntervalMs: 3_600_000,   // default 1h
     }),
@@ -47,13 +47,111 @@ export default {
 
 ## GDPR — export + erasure (admin-gated)
 
-Two admin-only routes (guarded by `requireScope(ADMIN_SCOPE)`) walk `subjectScopes`:
+Two admin-only routes (guarded by `requireScope(ADMIN_SCOPE)`):
 
-- **`governance.export`** `{ subjectId }` → a portable bundle `{ [table]: rows[] }` of everything referencing the subject.
-- **`governance.erase`** `{ subjectId, mode? }` → deletes (or anonymises) the subject across every scope; returns an immutable `ErasureLogEntry` (`{ subjectId, at, mode, affected: [{ table, count }] }`).
+- **`governance.export`** `{ subjectId }` → a portable bundle `{ [table]: rows[] }` of everything belonging to the subject.
+- **`governance.erase`** `{ subjectId, mode? }` → deletes (or anonymises) the subject across every scope; returns an immutable `ErasureLogEntry` (`{ subjectId, at, mode, affected: [{ table, count }], truncated? }`).
 
 The same operations are available in-handler via `GovernanceService` (`exportSubject` / `eraseSubject`).
 
+Erasure runs **deepest-first** — children before parents — so a real foreign key
+neither refuses the delete nor cascades through rows the log entry never counted.
+
+### The subject scope is DERIVED from your schema
+
+A hand-written list of "every table holding this person's data" is wrong the day
+after someone adds a table — and that list *is* the compliance claim. So
+`deriveSubjectScopes: { subjectTable: 'users' }` walks the schema instead: the
+relations registry plus the `reference()` column graph, outward from the subject.
+
+That reaches rows a flat `{ table, subjectField }` entry cannot even express —
+`users → posts → comments` is two hops, so a comment on the subject's post is in
+the export without anyone listing `comments`.
+
+**Only CHILD edges are followed** — a table holding a reference to the subject's
+row. Never a parent or lookup edge, and a `manyToMany` follows the JUNCTION only.
+Getting that backwards would not be an over-broad export; it would be an erasure
+that walks from one member into their organisation and deletes everybody else's
+rows.
+
+| declaration | followed? |
+|---|---|
+| `many(posts, { foreignKey: 'authorId' })` | ✓ the target carries the FK |
+| `one(profile)` with the FK on the target | ✓ a 1:1 child |
+| `one(country, { sourceKey: 'countryId' })` | — a lookup this row points AT |
+| `manyToMany(orgs, { through: memberships })` | ✓ `memberships` only, never `orgs` |
+| a `reference()` column with no `relations()` block | ✓ found in the column graph |
+
+`subjectScopes` is still first-class and is **unioned on top**, never replaced.
+It is the only way to reach a link the schema does not encode: a subject id in a
+plain (non-`reference()`) column, a polymorphic `(ownerType, ownerId)` pair, an
+id inside JSON.
+
+### What the derivation cannot see — and says so
+
+A list of reachable tables, printed alone, reads as a completeness claim. So the
+blind spots ship in the same payload:
+
+```ts
+const gov = yield* GovernanceService
+const { paths, limitations } = gov.subjectGraph()
+```
+
+…and at `GET /_voltro/inspect/plugins/governance/subject-graph`. `limitations`
+names every table nothing links to the subject (`unreachable`), everything cut by
+the depth ceiling (`depth-truncated`, default 4 hops) and everything you excluded.
+Structurally outside the graph in every case: **object storage and uploaded
+files, external processors, log and metric sinks, backups, and any subject id
+embedded in JSON or free text.**
+
+The plugin also warns at boot if a derived scope reaches one table or fewer —
+that is what a typo'd `subjectTable` looks like, and it is otherwise
+indistinguishable from a working configuration until the first DSAR.
+
+### `voltro privacy`
+
+```bash
+voltro privacy scope --subject-table users        # the graph + its blind spots, OFFLINE
+voltro privacy scope --json                       # { reachable, unreachable, depthTruncated }
+voltro privacy export usr_123 --url https://api.example.com --out bundle.json
+voltro privacy erase  usr_123 --url https://api.example.com --confirm
+```
+
+`scope` needs no database and no running app — schema only, so it belongs in CI
+and in a PR review, where "does our erasure still reach every table" is a question
+somebody can still act on.
+
+`export` / `erase` deliberately go through the **running app's** admin-gated
+governance endpoint rather than opening their own connection. A CLI that erased
+directly would bypass your configured `anonymizeFields` and exclusions, bypass the
+erasure log (which is the compliance artefact, not a nicety), and work against a
+schema the deployed app may not be running. `erase` refuses without `--confirm`,
+without `--url`, and without an inspect credential.
+
+### Scale
+
+Every read is `WHERE <column> IN (<keys>)` on an indexed column, chunked at 500
+keys and memoised across paths that share a prefix — not a full table scan per
+scope. Per table, 50 000 rows is the ceiling; hitting it sets `truncated` on the
+erasure-log entry and exits non-zero from the CLI, because a short erasure
+presented as complete is exactly the failure this is built to prevent.
+
+### Crypto-shredding is NOT supported — and should not be faked
+
+"Erase a subject by destroying their key" needs a key **per subject**. The shipped
+cipher is one app-wide passphrase-derived key, so there is nothing subject-shaped
+to destroy: deleting it would make *every* subject's `.encrypted()` columns
+unreadable, which is an outage, not an erasure. Per-subject shredding needs
+envelope encryption — a DEK per subject, wrapped by a KEK, with every existing
+ciphertext re-wrapped — which is a re-architecture of the cipher rather than a
+mode of `eraseSubject`.
+
+What makes its absence cost less than it sounds: `.encrypted()` columns are
+decrypted transparently on read, so `delete` removes the ciphertext row and
+`anonymize` overwrites the ciphertext with a null. Both erase the data itself
+rather than the key guarding it. Crypto-shredding is an optimisation for erasure
+at rest across backups; it is not the only route to Art. 17.
+
 ## Consent ledger
 
 `governance.consent` `{ purpose, granted }` records the calling subject's decision; `governance.hasConsent` `{ purpose }` reads the latest (latest-write-wins per `(subject, purpose)`).

package/templates/agent-docs/plugins/multitenancy.md

@@ -1,6 +1,6 @@
 # Multi-tenancy
 
-> The tenant() schema mixin (auto-scope reads + auto-fill writes), the assertOwnTenant write-guard, and the typed TenantMismatch error.
+> The tenant() schema mixin (auto-scoped reads, auto-filled inserts, tenant-resolved keyed writes), the assertOwnTenant write-guard, and the typed TenantMismatch error.
 
 
 
@@ -9,7 +9,7 @@
 <!-- source: en/plugins/multitenancy.md -->
 ## Multi-tenancy
 
-_The tenant() schema mixin (auto-scope reads + auto-fill writes), the assertOwnTenant write-guard, and the typed TenantMismatch error._
+_The tenant() schema mixin (auto-scoped reads, auto-filled inserts, tenant-resolved keyed writes), the assertOwnTenant write-guard, and the typed TenantMismatch error._
 
 `@voltro/plugin-multitenancy` is the first-party multi-tenancy primitive. It has two surfaces: a **schema mixin** (`tenant()`) and a **write-time guard** (`assertOwnTenant` + the typed `TenantMismatch` error).
 
@@ -37,11 +37,13 @@ for projects that don't want the full barrel.
 What the runtime does for a `tenant()`-marked table:
 
 - **Reads are auto-scoped.** The runtime AND-merges `eq('tenantId', subject.tenantId)` into every subscription predicate against the table — tenant A never sees tenant B's rows, and a write in tenant A never wakes a subscription in tenant B.
-- **Writes are auto-filled.** On insert, `tenantId` is stamped from `ctx.request.subject.tenantId` when the caller didn't pass it explicitly. The wrapper never overrides a value the caller did pass.
+- **Inserts are auto-filled.** On insert, `tenantId` is stamped from `ctx.request.subject.tenantId` when the caller didn't pass it explicitly. The wrapper never overrides a value the caller did pass, and it refuses the insert outright when the subject has no tenant.
+- **Set-based writes are auto-scoped.** `updateMany` / `deleteMany` and the fluent `update(t).where(...)` / `delete(t).where(...)` builders get the same `eq('tenantId', …)` AND-merged onto their `WHERE`, so a tenant-blind predicate is confined rather than executed as written.
+- **Keyed-by-id writes are resolved inside the tenant.** `update(t, id, patch)`, `delete(t, id)`, `hardDelete(t, id)` and `patchJson(t, id, …)` address a row by primary key, so the runtime resolves that key within `subject.tenantId` first and fails with `TenantRowNotFound` (`@voltro/runtime`) when there is no such row there. The error is raised identically whether the row is missing or belongs to another tenant — reporting the two differently would let a caller probe for row ids in other tenants.
 
 ## The write-guard — `assertOwnTenant`
 
-Read isolation is automatic. **Writes are not** — a mutation receives raw, user-supplied input including `tenantId`, so without an explicit check a client authenticated as tenant A could submit `tenantId: 'B'` and land the row in B's data. Guard every tenant-scoped mutation:
+Isolation itself is enforced by the runtime on every path above. What `assertOwnTenant` covers is the one question the framework deliberately does not answer for you: a mutation whose input carries an explicit `tenantId` it intends to USE. Without a check, a client authenticated as tenant A could submit `tenantId: 'B'` and your handler would happily read that claim. Guard such a mutation:
 
 ```ts
 import { assertOwnTenant, TenantMismatch } from '@voltro/plugin-multitenancy'
@@ -54,6 +56,8 @@ const execute = async (input: { tenantId: string }, ctx) => {
 
 `assertOwnTenant(inputTenantId, subject)` throws `TenantMismatch` when `inputTenantId` doesn't equal the subject's `tenantId`. Anonymous subjects have no tenant scope at all, so the guard always throws for them — anonymous + tenant-scoped writes need an `apiKey` / `serviceAccount` subject instead.
 
+It checks a **claimed** `input.tenantId`, so a mutation whose input carries none never reaches it. That is why it is an early, typed convenience and not the boundary — the boundary is the store enforcement listed above.
+
 ## The typed error — `TenantMismatch`
 
 `TenantMismatch` is a `Schema.TaggedError` carrying `inputTenantId` + `subjectTenantId` (empty string for anonymous subjects). Declare it on the mutation's `error:` schema so the rpc layer surfaces the rejection typed. **Import it from the browser-safe `@voltro/plugin-multitenancy/guard` subpath in the descriptor (`*.mutation.ts`)** — the package root also re-exports the schema mixin, which pulls `@voltro/database` into the client rpcGroup bundle (a browser-safety violation):
@@ -65,6 +69,7 @@ import { Schema } from 'effect'
 
 export const createProject = defineMutation({
   name:   'projects.create',
+  guards: [{ scope: 'projects:write' }],   // WHO may call; TenantMismatch bounds WHICH tenant
   input:  Schema.Struct({ tenantId: Schema.String, name: Schema.String }),
   output: Schema.Struct({ id: Schema.String }),
   error:  TenantMismatch,

package/templates/agent-docs/plugins/presence.md

@@ -45,7 +45,16 @@ const Room = ({ channel }: { channel: string }) => {
 }
 ```
 
-`usePresence(channel, opts)` heartbeats on an interval (`heartbeatMs`, default 15s) and publishes per-member `meta` (status, cursor position, …). The roster is **push-driven** — `presence.list` is a reactive plugin query (`source: '_voltro_presence'`), so the framework pushes a fresh roster over the subscription transport on every roster change (heartbeat / leave / sweep / a peer departing) with NO client polling. `key` defaults to the subject id; pass an explicit `key` for anonymous members.
+`usePresence(channel, opts)` heartbeats on an interval (`heartbeatMs`, default 15s) and publishes per-member `meta` (status, cursor position, …). The roster is **push-driven** — `presence.list` is a reactive plugin query whose `source:` is a [reactivity channel](/docs/data/subscriptions#reactivity-channels), so the framework pushes a fresh roster over the subscription transport with NO client polling. `key` defaults to the subject id; pass an explicit `key` for anonymous members.
+
+A member is `{ key, meta }`. **It pushes only when the roster actually moves** — a join, a leave, a change to someone's `meta`, a sweep, a peer's delta, a peer's death. A heartbeat that repeats what the server already knows pushes nothing, which is what keeps a large steady room free.
+
+> **There is a second `usePresence`, and it is a different hook.**
+> [`@voltro/local-first/react`](/docs/local-first/overview#presence--awareness)
+> exports one for peer-to-peer *awareness* — `usePresence(roomId, self, { channel })`
+> → `{ presence, others, setPresence }` — carrying high-frequency cursor and
+> selection state over a pub/sub channel. This one is the server-backed roster.
+> Different packages, different signatures; pick by the question you are asking.
 
 ## Typing indicator
 
@@ -85,7 +94,9 @@ an event declared `delivery: 'latest'` rather than in presence metadata.
 
 ## Notes
 
-- The roster is push-driven: `presence.list` is a reactive plugin query (`source: '_voltro_presence'`), so the framework re-runs it and pushes deltas over the subscription transport on every roster change — no client polling. There is no such TABLE any more; the name survives purely as the reactivity key the framework routes on, which is why the roster push needed no second mechanism when presence moved into memory. Any plugin query route that names a `source` table becomes push-driven the same way.
+- The roster is push-driven: `presence.list` declares a [reactivity channel](/docs/data/subscriptions#reactivity-channels) as its `source:`, so the framework re-runs it and pushes deltas over the subscription transport — no client polling. There is **no table**, and there is no longer a table NAME either: presence used to declare `_voltro_presence` and never write to it, purely to own a name the reactivity layer would route on. If you have an existing `_voltro_presence`, it is empty and the upgrade does not drop it (the differ never plans a drop for a framework table no app declares) — remove it by hand when convenient.
+- **A repeat heartbeat does not push.** Measured on this machine at 2.7 µs per subscriber per publish, an unconditional push cost a steady room of N clients N² × that per heartbeat interval — ~107 ms of CPU per 15s at N=200, and a per-node ceiling around 750 subscribers that nothing in the app controlled. Publishing only on a real change removes that term entirely; what remains is linear in actual roster churn. Reproduce with `node --import tsx packages/plugin-presence/scripts/rosterFanoutBody.ts`.
+- **A member has no `lastSeen`.** It used to, and it was the owning replica's clock — "active 3 minutes ago" rendered from it is wrong by whatever the skew between two pods is. Use `meta` for anything you need to show.
 - A member counts as online for `timeoutMs` after its last heartbeat. The sweep runs every `timeoutMs / 3`, so a vanished member is gone within roughly 1.3× the window.
 - The sweep needs **no cluster coordination**, and that follows from the design rather than being a shortcut: every member is owned by exactly one replica and nobody else may touch it, so each replica sweeps its own and there is nothing to contend over. (The table version *did* need coordination — its rows were shared.)
 

package/templates/agent-docs/plugins/ratelimit.md

@@ -22,6 +22,15 @@ upgrade — never the individual calls. The Effect-native rpc interceptors are
 the only surface that sees each call **and** the resolved subject (needed for
 per-tenant limits).
 
+> **This plugin is opt-in, and nothing rate-limits your RPC surface until you add it.**
+> There is no built-in per-IP, per-API-key or per-tenant request cap — an app that
+> does not install and configure `@voltro/plugin-ratelimit` accepts calls as fast as
+> they arrive. The one throttle that *is* on by default is `plugin-auth`'s
+> [brute-force lockout](/docs/authentication/passwords#brute-force-lockout) on sign-in,
+> and it only covers credential attempts. Put a per-IP cap at your ingress as well —
+> see [production hardening](/docs/deployment/production-hardening); that layer holds
+> per-IP state across replicas, which an in-process limiter cannot.
+
 Live — `demo.limited` is capped at 5/min per visitor; the 6th call within a
 minute fails with the typed `RateLimited` error (carrying `retryAfterMs`):