@voltro/cli 0.33.0 → 0.34.0

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

@@ -42,13 +42,14 @@ export default {
 
 What it provides:
 
-- The `_voltro_billing_*` tables (customers, subscriptions, invoices, usage, flush_claims) via `extendSchema.tables`.
+- The `_voltro_billing_*` tables (customers, subscriptions, invoices, usage, flush_claims, dunning_notices) via `extendSchema.tables`.
 - The `BillingService` Context.Tag — yield it in any handler.
 - The `requireEntitlement(ctx, key, cost)` in-handler quota guard + the declarative `enforce` map.
 - A webhook receiver at `POST /billing/webhook`.
-- The rpc routes `billing.startCheckout`, `billing.portalUrl`, `billing.subscription`, `billing.reportUsage`, `billing.changePlan`, `billing.changeSeats`.
+- The rpc routes `billing.startCheckout`, `billing.portalUrl`, `billing.subscription`, `billing.entitlementStatus`, `billing.reportUsage`, `billing.changePlan`, `billing.changeSeats`.
 - **Seat-based billing**; proration and failed-payment retries are Stripe's.
-- The typed `BillingError` + `EntitlementExceeded` errors, merged into every procedure's wire error union.
+- **Dunning** — a past-due notification sequence, a grace period and a lockout, composed on Stripe's outcomes.
+- The typed `BillingError`, `EntitlementExceeded` + `SubscriptionLocked` errors, merged into every procedure's wire error union.
 - A browser-safe `useStartCheckout()` hook on the `/web` subpath.
 
 ## The BillingService
@@ -68,7 +69,7 @@ export default (input: { tenantId: string }, _ctx) =>
   })
 ```
 
-The subscription row lives in your DB; the provider is the source of truth and webhooks keep the row in sync. `plan()` returns `'free'` when there is no active (or trialing) subscription.
+The subscription row lives in your DB; the provider is the source of truth and webhooks keep the row in sync. `plan()` returns the plan whose **limits apply right now**: `'free'` with no subscription, the paid plan while active or trialing, and — because a bounced card should not downgrade a customer on the same second — the paid plan for the whole [grace period](#failed-payments--stripe-retries-dunning-composes-on-the-outcome) after a failed payment, falling back only once the lockout is real.
 
 ## Entitlement checks
 
@@ -142,6 +143,8 @@ billingPlugin({
 
 `onEvent` keys are the normalized `BillingEvent` tags (`subscriptionUpserted`, `invoicePaid`, `invoicePaymentFailed`, `customerLinked`, `subscriptionCanceled`), not raw Stripe types.
 
+Every event carries an `occurredAt` (Stripe's `event.created`). Webhook delivery is at-least-once **and unordered**, so the subscription and invoice rows compare it against the timestamp of the state they already reflect and **drop anything older** — a redelivered `active` from before a decline cannot un-do the past-due, and a late `payment_failed` cannot flip a paid invoice back to `open`.
+
 ## Checkout + upgrade flows
 
 The `/web` subpath ships a browser-safe hook. It imports nothing from the server module — no secret, no node-only lib ever reaches the browser bundle. Pass it the generated `billing.startCheckout` rpc binding:
@@ -196,13 +199,14 @@ yield* billing.flushUsage()
 
 ## Tables
 
-All five are `_voltro_`-prefixed and built from the cross-dialect schema DSL (no raw SQL, no pg-only types, no `TEXT` defaults). Money is `integer` minor units + a `currency` text column:
+All six are `_voltro_`-prefixed and built from the cross-dialect schema DSL (no raw SQL, no pg-only types, no `TEXT` defaults). Money is `integer` minor units + a `currency` text column:
 
 - `_voltro_billing_customers` — tenant ↔ provider customer link.
 - `_voltro_billing_subscriptions` — one subscription per tenant (plan, status, seat `quantity`, period start + end, cancel-at).
 - `_voltro_billing_invoices` — invoice history (`amountMinor` integer + `currency`).
 - `_voltro_billing_usage` — per-tenant metered counters keyed by `(tenantId, entitlementKey, period)`.
 - `_voltro_billing_flush_claims` — INSERT-wins flush-window claims (multi-instance autopilot coordination); short-lived, retention defaults to 1 hour via `VOLTRO_BILLING_FLUSH_CLAIM_TTL_HOURS`.
+- `_voltro_billing_dunning_notices` — the sent-notice ledger, `UNIQUE (tenantId, episode, stepId)`. It is the **send gate**, not a report: a notice is claimed here before it goes out, so a duplicated webhook sends nothing. Retention defaults to ~400 days via `VOLTRO_BILLING_DUNNING_TTL_HOURS` — deliberately generous, because pruning a row belonging to a still-open episode would let its notice go out a second time.
 
 `_voltro_billing_usage` is append-only — one upserted counter row per `(tenant, key, period)` — so a closed period's row would otherwise live forever. The plugin registers a retention sweep on the row's `updatedAt`: a row is only touched while its window is current, so once a period closes it ages out, while the live period's row stays fresh and survives regardless. The bound defaults to ~400 days (a conservative window with headroom for end-of-period flush + back-dated reads) and is tunable via the `VOLTRO_BILLING_USAGE_TTL_HOURS` env var; the boot retention sweep drains rows past the TTL.
 
@@ -285,9 +289,9 @@ const quote = yield* billing.previewChange(tenantId, { quantity: 40 })
 
 Never quote a locally estimated number. The one Stripe previews is the one it charges.
 
-## Failed payments — Stripe retries, you read the status
+## Failed payments — Stripe retries, dunning composes on the outcome
 
-There is no dunning subsystem here. Stripe Smart Retries runs the retry schedule (configured in the Stripe Dashboard, where it can use Stripe's own timing models) and reports the outcome as a subscription status change:
+Stripe Smart Retries runs the retry schedule (configured in the Stripe Dashboard, where it can use Stripe's own timing models) and reports the outcome as a subscription status change:
 
 | From | On | To |
 | --- | --- | --- |
@@ -295,21 +299,134 @@ There is no dunning subsystem here. Stripe Smart Retries runs the retry schedule
 | `pastDue` | payment recovers | `active` |
 | `pastDue` | Stripe gives up | `canceled` |
 
-Those transitions arrive as `customer.subscription.updated` webhooks and land on the subscription row. **Key your UI on `subscription.status`**, not on a retry record:
+The framework does not reimplement that cadence and never will — a local retry schedule ran here once, on a fixed `[1,3,5,7]`-day rhythm, and drifted from Stripe's the moment the two disagreed. What the plugin adds is the part Stripe does not do for your app: a **past-due notification sequence**, a **grace period**, and a **lockout** your entitlement checks can read.
+
+### The grace clock is a column, not a timer
+
+When the provider confirms a subscription is past due, the plugin stamps `pastDueSince` on the subscription row. Everything else is derived from it at read time — so there is no job to miss a tick, fire twice, or run on two replicas at once, and nothing "expires" a grace period in the background.
+
+Two rules keep it honest, and both exist because sending an email and locking a customer out cannot be undone:
+
+- **`pastDueSince` is only written after the provider confirms it.** A failed-payment event triggers a *reconcile* that reads the subscription's current status from Stripe (`subscriptions.retrieve`) and writes the row from that — never from the event body. Webhook delivery is at-least-once **and unordered**, so a `payment_failed` genuinely can arrive after the retry that succeeded; reconciling against the object settles it.
+- **An unreachable provider never escalates.** If the reconcile cannot reach Stripe, `pastDueSince` stays unset — and without it there is no clock to expire, so the tenant stays in grace. Failing open is the only safe direction: the alternative is locking a paying customer out because your network was down.
+
+### Asking the truthful question
+
+`entitlementStatus()` is the one answer to "is this tenant entitled right now". It is a pure read of the local row — no provider call — so it is safe on a hot path:
 
 ```ts
-const sub = yield* billing.subscription(tenantId)
-if (sub?.status === 'pastDue') {
-  // Show a "update your payment method" banner + a link to the billing portal.
-  const { url } = yield* billing.portalUrl(tenantId, returnUrl)
-}
+import { Effect } from 'effect'
+import { BillingService } from '@voltro/plugin-billing'
+
+export default (input: { tenantId: string }, _ctx) =>
+  Effect.gen(function* () {
+    const billing = yield* BillingService
+    const status  = yield* billing.entitlementStatus(input.tenantId)
+    // { plan, billedPlan, status, entitled, inGrace, graceEndsAt, lockedSince, lockout }
+    return status
+  })
 ```
 
-`pastDue` deliberately keeps the customer's entitlements: a bounced card is a payment problem, and locking an organisation out of its own data over a bank decline is a support incident, not enforcement. Stripe cancels when it has genuinely given up, and `canceled` is what removes access.
+- `entitled: false` means **dunning has locked this tenant out**. A canceled subscription is not a lockout — it is simply the free tier.
+- `inGrace: true` with a `graceEndsAt` is the "your payment failed, you have until …" state. Show the banner and a billing-portal link.
+- `plan` is the plan whose **limits apply right now**; `billedPlan` is what they are subscribed to. Under a hard lockout the two differ.
+
+The same shape is available to the browser as the `billing.entitlementStatus` rpc query (timestamps as ISO strings).
+
+For a feature with no numeric quota to degrade — an export, an admin action — guard it directly:
+
+```ts
+import { Effect } from 'effect'
+import { requireEntitled } from '@voltro/plugin-billing'
+
+export default (input: { id: string }, ctx) =>
+  Effect.gen(function* () {
+    yield* requireEntitled(ctx)   // fails SubscriptionLocked once grace expired
+    return { ok: true }
+  })
+```
+
+`SubscriptionLocked` is a typed `Schema.TaggedError` carrying `{ tenantId, status, lockedSince, lockout }`, decoded on the client like every other framework error — so the UI can route to the billing portal instead of showing a generic failure.
+
+### The sequence
+
+Steps are declared with an `afterHours` measured from `pastDueSince`, so a step cannot be pulled forward by how often the provider happens to retry. Each provider event is the tick that evaluates whichever steps have come due:
+
+```ts
+import { billingPlugin, dunningMailNotifier } from '@voltro/plugin-billing'
+import { MailService } from '@voltro/plugin-mail'
+
+billingPlugin({
+  plans: { /* … */ },
+  dunning: {
+    graceHours: 168,                       // default: 7 days
+    steps: [                               // default: exactly these three
+      { id: 'payment-failed', afterHours: 0 },
+      { id: 'reminder',       afterHours: 72 },
+      { id: 'final-warning',  afterHours: 144 },
+    ],
+    lockout: 'hard',                       // default | 'soft'
+    portalReturnUrl: 'https://acme.com/billing',
+    notify: (notice) => Effect.sync(() => { /* your transport */ }),
+  },
+})
+```
+
+Each notice carries `{ stepId, tenantId, to, plan, status, pastDueSince, graceEndsAt, locked, lockout, portalUrl }` **plus** ready-to-send default `subject` / `html` / `text` — plain and unbranded, so the sequence works the moment `notify` is wired without inviting you to ship it unchanged.
+
+**With no `notify`, nothing is sent.** The sequence claims and logs. That is the deliberate default: the framework cannot address a customer on your behalf, and an email is irreversible.
+
+To send with `@voltro/plugin-mail`, bridge it — the plugin types the mail service structurally, so it takes on no dependency:
+
+```ts
+const mail = yield* MailService
+billingPlugin({ dunning: { notify: dunningMailNotifier(mail) } })
+```
+
+The recipient is resolved as: your `dunning.resolveRecipient(tenantId)` first, then the provider's customer email. A notice with no resolvable recipient still reaches `notify` (with `to: null`) so you can route it in-product.
+
+### Idempotency, and what happens when delivery lies
+
+Every send is claimed in `_voltro_billing_dunning_notices` under a `UNIQUE (tenantId, episode, stepId)` **before** it goes out. The episode key IS the clock — the epoch-ms of `pastDueSince` — so:
+
+- a **duplicated** webhook lands on a claimed key and sends nothing;
+- a **recovery** clears `pastDueSince`, which cancels every step still pending for that episode — a later failure opens a genuinely new episode and legitimately starts over;
+- a **stale** `customer.subscription.updated` cannot un-do a past-due, and a stale `invoice.payment_failed` cannot flip a paid invoice back to `open`: both rows carry the event's timestamp and drop anything older than the state they already reflect.
+
+Claim-then-send is on purpose. Its failure mode is one notice that never arrives; send-then-claim's is a customer receiving the same dunning email twice.
+
+### The lockout
+
+Once `graceEndsAt` passes, `entitled` turns false and one `locked` notice fires on the next reconcile.
+
+- **`lockout: 'hard'`** (default) — entitlement limits fall to the `'free'` plan's. Every existing `requireEntitlement` / `enforce` check starts answering with the free tier's numbers; you write no new code.
+- **`lockout: 'soft'`** — limits stay on the paid plan and only `entitlementStatus()` reports the lockout, so your app decides what to withhold.
+
+Recovery at any point — including after the lockout — restores the paid entitlements on the next reconcile.
+
+### Tunables
+
+Every number the framework picked on your behalf is a field with a default and an env override:
+
+| Option | Env | Default |
+| --- | --- | --- |
+| `dunning.enabled` | `VOLTRO_BILLING_DUNNING` (`on` / `off`) | `true` |
+| `dunning.graceHours` | `VOLTRO_BILLING_GRACE_HOURS` | `168` (7 days) |
+| `dunning.steps[].afterHours` | `VOLTRO_BILLING_DUNNING_STEP_HOURS` (positional, comma-separated) | `0,72,144` |
+| `dunning.lockout` | `VOLTRO_BILLING_LOCKOUT` (`hard` / `soft`) | `hard` |
+| notice-ledger retention | `VOLTRO_BILLING_DUNNING_TTL_HOURS` | `9600` (~400 days) |
+
+The env parsers **fail the boot** on a value they cannot read, and `VOLTRO_BILLING_DUNNING_STEP_HOURS` refuses a list whose length differs from the declared sequence — an operator re-timing a sequence they are not looking at is exactly the quiet wrong number this refuses to become.
+
+With `dunning.enabled: false` there is no grace clock and no reconcile: `pastDue` degrades entitlements at once, which is what this plugin did before dunning existed.
+
+### The optional sweep
+
+Provider events drive the sequence, and that covers the normal case — Stripe emits an event per retry attempt. `billing.dunningSweep()` reconciles every past-due tenant in one pass, for a step configured at an hour the provider happens not to emit an event at, or a reconcile missed during a provider outage. **Nothing schedules it for you**; wire it from your own `*.cron.tsx` if you want it. It is idempotent, it never charges anything, and it never asks the provider to retry.
 
 ## Provider portability
 
-The surface (`BillingService`, the entitlement engine, the DB rows) is provider-agnostic. A `BillingProvider` is a dumb adapter: checkout/portal URL minting, usage push, and a pure `normalizeEvent` mapping the provider's payload to a `BillingEvent`. Stripe and an in-memory mock ship in the box; a new provider is a new adapter against the same contract — pass it directly:
+The surface (`BillingService`, the entitlement engine, the DB rows) is provider-agnostic. A `BillingProvider` is a dumb adapter: checkout/portal URL minting, usage push, a `fetchSubscription` direct read (the current status dunning refuses to lock a customer out without), and a pure `normalizeEvent` mapping the provider's payload to a `BillingEvent`. Stripe and an in-memory mock ship in the box; a new provider is a new adapter against the same contract — pass it directly:
 
 ```ts
 import { billingPlugin } from '@voltro/plugin-billing'

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,