@voltro/cli 0.30.1 → 0.31.0

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

@@ -0,0 +1,324 @@
+# Billing
+
+> Subscriptions, plans, entitlements, and usage metering over a pluggable provider (Stripe + mock). Money is integer minor units.
+
+
+
+---
+
+<!-- source: en/plugins/billing.md -->
+## Billing
+
+_Subscriptions, plans, entitlements, and usage metering over a pluggable provider (Stripe + mock). Money is integer minor units._
+
+`@voltro/plugin-billing` wires a billing provider into Voltro's runtime. Subscriptions become rows in your DB; provider webhooks update them; entitlements gate features by quota. It rides `@voltro/plugin-webhooks` for inbound event signature verification + idempotency, so it never re-implements that machinery.
+
+All monetary amounts are **integer minor units** (cents for USD/EUR, pence for GBP) paired with a `currency` string — never a float, never a decimal column.
+
+## Install
+
+```ts
+// app.config.ts
+import { billingPlugin } from '@voltro/plugin-billing'
+
+export default {
+  type: 'api' as const,
+  plugins: [
+    billingPlugin({
+      provider:      'stripe',                       // | 'mock' | a BillingProvider
+      apiKey:        process.env.STRIPE_SECRET_KEY,   // server-only; default STRIPE_SECRET_KEY
+      webhookSecret: process.env.STRIPE_WEBHOOK_SECRET, // default STRIPE_WEBHOOK_SECRET
+      plans: {
+        free: { entitlements: { aiCalls: 100,  storageBytes: 1_000_000_000 } },
+        pro:  { priceId: 'price_…', entitlements: { aiCalls: 5000, storageBytes: 50_000_000_000 } },
+        ent:  { priceId: 'price_…', entitlements: { aiCalls: 'unlimited', storageBytes: 1_000_000_000_000 } },
+      },
+    }),
+  ],
+}
+```
+
+`plans` is the single source of tier→limit truth — it lives in code, not the DB, so limits change by redeploy, not migration. Entitlement values are `number | 'unlimited'`. With no provider configured (and no `STRIPE_SECRET_KEY`), the plugin uses an in-memory **mock provider** — zero-config for dev and tests.
+
+What it provides:
+
+- The `_voltro_billing_*` tables (customers, subscriptions, invoices, usage, flush_claims) 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`.
+- **Seat-based billing**; proration and failed-payment retries are Stripe's.
+- The typed `BillingError` + `EntitlementExceeded` errors, merged into every procedure's wire error union.
+- A browser-safe `useStartCheckout()` hook on the `/web` subpath.
+
+## The BillingService
+
+Yield the service in any handler:
+
+```ts
+import { Effect } from 'effect'
+import { BillingService } from '@voltro/plugin-billing'
+
+export default (input: { tenantId: string }, _ctx) =>
+  Effect.gen(function* () {
+    const billing = yield* BillingService
+    const sub  = yield* billing.subscription(input.tenantId)  // Subscription | null
+    const plan = yield* billing.plan(input.tenantId)          // resolves tier, defaults 'free'
+    return { plan, status: sub?.status ?? 'none' }
+  })
+```
+
+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.
+
+## Entitlement checks
+
+There is **no `guards:` field** on `defineMutation` — procedures carry only `name / input / output / error / target`. Quota enforcement happens one of two real ways.
+
+### In-handler — `requireEntitlement`
+
+The Effect-native guard, mirroring `requireScope` / `permission()`. It resolves the caller's `tenantId` from the subject, atomically checks-and-decrements the quota, and fails with the typed `EntitlementExceeded` when exhausted:
+
+```ts
+import { Effect } from 'effect'
+import { requireEntitlement } from '@voltro/plugin-billing'
+
+export default (input: { tokens: number }, ctx) =>
+  Effect.gen(function* () {
+    yield* requireEntitlement(ctx, 'aiCalls', Math.ceil(input.tokens / 1000))
+    // … the work the quota gates …
+    return { ok: true }
+  })
+```
+
+`requireEntitlement` declares `BillingService` in its Effect requirements — the plugin's `services` layer provides it automatically. Compute the cost however you like; pass `1` for a flat per-call charge or a derived integer for metered work.
+
+### Declarative — the `enforce` map
+
+For per-tag enforcement without touching the handler body, pass an `enforce` map (the rate-limit-plugin pattern). It installs an interceptor that consumes the entitlement BEFORE the executor runs — an over-quota call never reaches your code:
+
+```ts
+billingPlugin({
+  plans: { /* … */ },
+  enforce: {
+    'ai.heavy': { entitlement: 'aiCalls', cost: 1 },
+  },
+})
+```
+
+Either form fails with `EntitlementExceeded` (a `Schema.TaggedError` carrying `{ entitlement, limit, used, cost }`), decoded typed on the client. An `'unlimited'` plan limit short-circuits without touching the counter.
+
+Quota windows are per calendar month (`YYYY-MM`) per `(tenantId, entitlementKey)`. The check + decrement is a store-level atomic consume — a compare-and-set on the usage row (`UNIQUE(tenant, key, period)`), safe across replicas — that runs OUTSIDE the mutation's transaction: a handler that fails after consuming does not refund the quota.
+
+Entitlements are orthogonal to RBAC scopes: a scope answers "may you call this proc"; an entitlement answers "do you have quota left". A procedure can require both.
+
+## Webhook handling
+
+Provider events land at `POST /billing/webhook`. The plugin rides `@voltro/plugin-webhooks`' Stripe provider preset, so signature verification (the `Stripe-Signature` `t=…,v1=…` scheme, 5-minute replay window) and idempotency (Stripe event `id`, 30-day TTL) come for free. The handler maps the verified payload to a provider-agnostic `BillingEvent`, applies it to the DB rows, then runs any `onEvent` side effect.
+
+Events handled:
+
+- `customer.subscription.created` / `updated` / `deleted`
+- `invoice.paid` / `invoice.payment_failed`
+- `customer.created` (links the tenant via Stripe metadata)
+
+`applyEvent` upserts by provider id, so it's idempotent even under a cross-process replay where the LRU idempotency cache wouldn't catch the duplicate. The webhook needs `tenantId` (and, for subscriptions, `plan`) in the Stripe object's `metadata` — `startCheckout` sets it automatically.
+
+Per-event side effects run AFTER the row is updated:
+
+```ts
+import { Effect } from 'effect'
+
+billingPlugin({
+  plans: { /* … */ },
+  onEvent: {
+    invoicePaymentFailed: (event) =>
+      Effect.sync(() => {
+        // event: { _tag: 'invoicePaymentFailed', tenantId, providerInvoiceId, amountMinor, currency }
+        console.warn('payment failed for', event.tenantId, event.amountMinor, event.currency)
+      }),
+  },
+})
+```
+
+`onEvent` keys are the normalized `BillingEvent` tags (`subscriptionUpserted`, `invoicePaid`, `invoicePaymentFailed`, `customerLinked`, `subscriptionCanceled`), not raw Stripe types.
+
+## 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:
+
+```tsx
+import { useStartCheckout } from '@voltro/plugin-billing/web'
+import { useAppClient } from '@voltro/web'
+
+const UpgradeButton = () => {
+  const app = useAppClient('app')
+  const { startCheckout, pending } = useStartCheckout((input) => app.billing.startCheckout(input))
+  return (
+    <button
+      disabled={pending}
+      onClick={() => startCheckout({ plan: 'pro', successUrl: location.href, cancelUrl: location.href })}
+    >
+      Upgrade to Pro
+    </button>
+  )
+}
+```
+
+The rpc calls the provider, returns a hosted checkout URL, and the hook redirects. The provider captures the card; on success it redirects back to your `successUrl` and the webhook updates the subscription row. `startCheckout` fails with `BillingError` for a plan that has no `priceId` (free plans aren't paid checkouts).
+
+## Customer portal
+
+For self-service plan changes, payment-method updates, and invoice download, mint a provider-hosted portal URL. The tenant must already have a linked provider customer (created on first checkout / `customer.created`):
+
+```ts
+import { Effect } from 'effect'
+import { BillingService } from '@voltro/plugin-billing'
+
+export default (input: { tenantId: string; returnUrl: string }, _ctx) =>
+  Effect.gen(function* () {
+    const billing = yield* BillingService
+    return yield* billing.portalUrl(input.tenantId, input.returnUrl) // { url }
+  })
+```
+
+## Usage reporting
+
+For metered billing, record usage locally; the service flushes the aggregate to the provider in one batched push per `(tenant, key)`:
+
+```ts
+const billing = yield* BillingService
+yield* billing.reportUsage(tenantId, 'aiCalls', count)
+// later — typically from a schedule:
+yield* billing.flushUsage()
+```
+
+`flushUsage` is a no-op on providers that report `supportsMeteredUsage: false`. Counters that have already been pushed are not re-sent.
+
+## 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:
+
+- `_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_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.
+
+Card data never touches the DB — the provider's hosted portal owns it, so there is no payment-methods table.
+
+## Usage-based billing autopilot
+
+Make the app meter + bill its **own** per-tenant usage with one declaration — no hand-wired counters. Pass `metering` and the plugin derives usage from the graph's own telemetry, then flushes it to the provider on a schedule:
+
+```ts
+billingPlugin({
+  provider: 'stripe',
+  plans: { pro: { priceId: 'price_…', entitlements: { apiCalls: 100_000 } } },
+  metering: {
+    apiCalls: { from: 'rpc', match: /^orders\./ },  // count SUCCESSFUL rpc calls (match: string | RegExp; optional kind)
+    rows:     { from: 'cdc', table: 'orders' },       // count row writes (default op: insert)
+    aiTokens: { from: 'ai' },                         // sum the _voltro_ai_usage ledger (metric: 'tokens' | 'costMicroUsd')
+  },
+  // flushIntervalMs: 60_000,  // 0 disables the self-scheduled flush — call billing.flushUsage() from your own *.cron.tsx
+})
+```
+
+Each source taps something the framework **already tracks**:
+
+- **`rpc`** — the rpc interceptor counts matching calls per tenant, AFTER they succeed (a quota-rejected or failed call isn't counted).
+- **`cdc`** — the post-commit ChangeEvent stream counts row writes to `table`; the tenant comes from the row's `tenantId`.
+- **`ai`** — at flush time the autopilot sums the `_voltro_ai_usage` ledger (written by `@voltro/ai`'s `recordAiUsage`) per tenant for the current period and reports the **delta** vs. what's already accrued — so re-running is idempotent.
+
+All three route through the existing `BillingService.reportUsage` (a local per-period counter) + `flushUsage` (the batched provider push). Anonymous (tenant-less) calls aren't metered.
+
+**Idempotency + multi-instance.** The self-scheduled flush is per-period idempotent (`markReported` makes a re-flush a no-op) AND **cluster-coordinated by default**: each replica self-schedules, but an INSERT-wins claim on the flush window (`_voltro_billing_flush_claims`) means exactly one replica flushes a given window — so two replicas never double-push it, with no extra wiring. Set `flushIntervalMs: 0` to disable the timer entirely and drive `billing.flushUsage()` from your own `*.cron.tsx` instead.
+
+**Boundaries (v1).** Metering captures writes the framework observes through `ctx.store` — the bulk helpers (`updateMany` / `deleteMany`) emit per-row ChangeEvents that ARE counted, but a single bulk SQL escape-hatch write isn't. The meter is best-effort post-commit telemetry, not a financial ledger of record.
+
+## Plans, seats & the billed amount
+
+A plan carries an optional per-seat **unit amount** (integer minor units) and a `currency`, alongside its entitlement limits:
+
+```ts
+billingPlugin({
+  plans: {
+    free:    { entitlements: { seats: 3 } },
+    starter: { priceId: 'price_starter', unitAmountMinor: 1000, currency: 'usd', entitlements: { seats: 10 } },
+    pro:     { priceId: 'price_pro',     unitAmountMinor: 3000, currency: 'usd', entitlements: { seats: 'unlimited' } },
+  },
+})
+```
+
+A subscription carries a **seat `quantity`** (default 1). The billed amount is `plan.unitAmountMinor × quantity` — all integer minor units, no float. The quantity comes off the provider event (Stripe's first line-item quantity) and round-trips through the subscription row.
+
+## Proration — Stripe's, and it is actually billed
+
+A mid-cycle change (plan upgrade/downgrade, seat change) settles the difference for the unused remainder of the period. **Stripe computes it and invoices it** — the framework does not do this arithmetic, because a number we computed ourselves would differ from the charge by Stripe's rounding, its tax calculation, and any credit balance on the customer, and every one of those differences is a support ticket.
+
+`changePlan` / `changeSeats` apply the change AT Stripe with `proration_behavior: create_prorations` and return what Stripe booked:
+
+```ts
+import { Effect } from 'effect'
+import { BillingService } from '@voltro/plugin-billing'
+
+export default (input: { tenantId: string }, _ctx) =>
+  Effect.gen(function* () {
+    const billing = yield* BillingService
+    const change = yield* billing.changePlan(input.tenantId, 'pro')
+    const seats  = yield* billing.changeSeats(input.tenantId, 5)
+    return { prorationMinor: change.prorationMinor, seatsProration: seats.prorationMinor }
+  })
+```
+
+Each returns `{ plan, quantity, prorationMinor, currency }`, where `prorationMinor` is the sum of Stripe's proration lines on the upcoming invoice — positive is a charge, negative a credit. The local subscription row is written from Stripe's answer, not from what was requested, so the two cannot drift.
+
+### Quote before you charge
+
+To show a figure in a confirmation dialog, use `previewChange` — it reads Stripe's invoice preview without applying anything:
+
+```ts
+const quote = yield* billing.previewChange(tenantId, { quantity: 40 })
+// → { plan, quantity, prorationMinor, currency }   nothing has changed yet
+```
+
+Never quote a locally estimated number. The one Stripe previews is the one it charges.
+
+## Failed payments — Stripe retries, you read the status
+
+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:
+
+| From | On | To |
+| --- | --- | --- |
+| `active` | payment fails | `pastDue` |
+| `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:
+
+```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)
+}
+```
+
+`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.
+
+## 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:
+
+```ts
+import { billingPlugin } from '@voltro/plugin-billing'
+import { myProvider } from './my-provider'
+
+billingPlugin({ provider: myProvider(), plans: { /* … */ } })
+```
+
+## See also
+
+- [plugin-webhooks](/docs/plugins/webhooks) — the inbound signature + idempotency machinery billing rides
+- [plugin-rbac](/docs/plugins/rbac) — scopes (the orthogonal "may you call this" axis)

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

@@ -0,0 +1,144 @@
+# Broadcast
+
+> Cross-replica reactivity over a pub/sub bus (Redis / NATS) for non-postgres dialects — closes the single-instance gap so a write on one pod surfaces on another.
+
+
+
+---
+
+<!-- source: en/plugins/broadcast.md -->
+## Broadcast
+
+_Cross-replica reactivity over a pub/sub bus (Redis / NATS) for non-postgres dialects — closes the single-instance gap so a write on one pod surfaces on another._
+
+`@voltro/plugin-broadcast` closes the cross-replica reactivity gap for dialects that have no native cross-instance change feed. Postgres fans out natively via `LISTEN/NOTIFY` and mariadb via binlog CDC; every other dialect (mysql / mssql / cockroach / planetscale / azure) emits change events **in-process on the writing instance only**. Without a bus, a write on one pod never wakes a subscription on another pod.
+
+**Status:** ✓ shipped.
+
+> For the full cross-replica reactivity story — when you need it, the dialect matrix, and the boot-log signals — see [Database → Multi-replica](/docs/database/multi-replica). This page documents the plugin itself.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { broadcastPlugin } from '@voltro/plugin-broadcast'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [broadcastPlugin()],
+}
+```
+
+**Broadcast is opt-in — it never turns on from a shared `REDIS_URL` alone.** The bus enables only on an explicit signal: `BROADCAST_URL`, `BROADCAST_REDIS_URL`, `BROADCAST_PROVIDER`, or the `connection` / `provider` / `url` option. So a deployment running the cache on `REDIS_URL` keeps broadcast on the single-process memory bus until you deliberately switch it on. This differs from `ctx.cache` / `ctx.kv`, which are gated by their own `CACHE_BACKEND` / `KV_BACKEND` selectors — same principle, explicit per concern.
+
+Once enabled on redis, the connection resolves own → shared: an explicit `url` / broker-agnostic `BROADCAST_URL` → `BROADCAST_REDIS_URL` (this connection's own) → the shared `REDIS_URL`. A `redis://` / `rediss://` URL selects Redis; a `nats://` URL selects NATS.
+
+```ts
+broadcastPlugin({ connection: 'broadcast' }) // opt in + share the app's redis: BROADCAST_REDIS_URL → REDIS_URL
+broadcastPlugin({ provider: 'redis', url: process.env.BROADCAST_URL }) // or an explicit url / provider
+```
+
+The `connection` option follows the same `<NAME>_REDIS_URL` → `REDIS_URL` convention as the [cache, KV and rate limiter](/docs/caching/key-value) — but setting it (or another explicit signal) is the deliberate opt-in; the shared `REDIS_URL` is only the connection detail. NATS stays broker-agnostic via `BROADCAST_URL`.
+
+`BroadcastPluginOptions`: `provider` (`'redis' | 'nats' | 'memory'` or a `BroadcastProvider`), `url`, `connection` (named redis connection, default `'broadcast'`), and `name` (disambiguates multiple instances of the plugin in one app — the second instance's name becomes `@voltro/plugin-broadcast#<name>`).
+
+## How it works
+
+The plugin is mostly a **carrier**: it resolves a `BroadcastProvider` at construction and exposes it so the serve pipeline can attach the bus to the live `DataStore` **after** the store is built (the bus needs the store's `onChange` + `injectExternalChange` seam, which doesn't exist at plugin-activation time).
+
+The bus is **additive** to the inline emit path:
+
+- It publishes `{ origin, event }` on the `<namespace>:changes` channel.
+- It injects remote events into every other replica's store, skipping its own origin so there's no double-emit.
+- A broker outage degrades cross-replica fan-out only — local reactivity keeps working.
+
+The plugin declares the `network:outbound:*` permission. The boot banner names the resolved tier (cross-instance via redis/nats, or off for the dialect when no broker is configured).
+
+## A dropped message cannot leave a client stale
+
+Pub/sub has no retention. If a replica's broker connection blips it simply never
+learns that a change happened — and its clients keep their sockets, so the
+client-side reconnect never fires and their live queries never re-run. They would
+show stale rows until something else touched the same table, which on a quiet
+table can be never.
+
+Every change carries a **per-origin serial**, so a receiving replica can tell
+exactly how many it missed — a count, not an estimate. On a gap it re-runs every
+live subscription.
+
+That works because **a live query is idempotent**: re-running one always lands on
+the truth, so a proven loss is repaired by refreshing rather than by replaying
+something nobody kept. The refresh goes through each subscription's own
+descriptor, so guards, row filters and tenant predicates apply unchanged — and it
+is a re-query, not a push: if the snapshot has not moved, the subscriber sees
+nothing.
+
+A replica that just started reports no gap however high a peer's serial is. It
+missed nothing; it was not there.
+
+Nothing to configure. It follows from having a broker.
+
+## Sharing one broker between apps — the namespace
+
+Every framework channel on the broker hangs off **one namespace**: `<ns>:changes`,
+`<ns>:events:<name>`, `<ns>:members`, `<ns>:presence`.
+
+It defaults to your app's name, so **two different apps pointed at one Redis or
+NATS separate on their own** — nothing to configure, and nothing to forget.
+
+```ts
+broadcast({ provider: 'redis', namespace: 'shop-prod' })
+```
+
+Set it explicitly for the one case the default cannot see: **several deployments
+of the same app on one broker.** Staging and production share a name, share the
+code and share every fingerprint, so nothing derivable tells them apart. There,
+this option — or `VOLTRO_BROADCAST_NAMESPACE` — is the only thing that works.
+
+<Callout type="warn">
+If you are upgrading and used `broadcast({ channel })`, note what the codemod
+tells you: **that option never took effect.** It was declared, and documented as
+the fix for exactly this, and nothing read it — your deployments were sharing
+channels regardless of what you set. `voltro update` rewrites it to `namespace`
+and strips the trailing `:changes`, since the framework appends the channel kind
+itself.
+</Callout>
+
+Resolution order: `broadcast({ namespace })` → `VOLTRO_BROADCAST_NAMESPACE` →
+your app's name. The value is lowercased and reduced to `a-z0-9_-`, which closes
+three things NATS punishes (measured against nats:2 — Redis is indifferent):
+
+| In a name | What NATS does |
+| --- | --- |
+| a `.` beside a `>` (`shop.>`) | matches `shop.other` — wildcards are token-level, and tokens are dot-separated |
+| a name that IS `>` or `*` | matches **every** subject on the server |
+| whitespace (`My App`) | rejects the subject outright — the app receives nothing at all |
+
+A wildcard *inside* a token is harmless (`shop>:changes` does not match
+`other:changes`), so the dangerous inputs are narrower than they look — and a
+name that reduces to nothing falls through to the next candidate rather than
+becoming an empty prefix.
+
+## The namespace is a broker subject — and it is normalised
+
+```sh
+VOLTRO_BROADCAST_NAMESPACE="prod env"   # → resolves to "prod-env"
+VOLTRO_BROADCAST_NAMESPACE="prod.env"   # → ALSO "prod-env" — same channel
+```
+
+Whitespace, dots and wildcards are folded to `-` and the result is lowercased,
+because the value becomes a broker subject: NATS refuses a subject containing
+whitespace outright and delivers nothing, with no error on the publishing side.
+
+**Two differently-configured deployments can therefore collapse onto one
+channel** — which is what this option exists to prevent. Nothing refuses (the
+resolved value is safe either way, and failing a boot over a dot would be worse
+than the collapse), but the boot logs the substitution whenever it changes what
+you wrote. If you see it, check that the RESOLVED names differ, not the ones you
+typed.
+
+
+## Caveat — app-mutation changes only
+
+The bus carries changes written through `ctx.store` (app mutations). It does **not** capture out-of-band DB writes (a `psql` session, another service) — only postgres `LISTEN/NOTIFY` and mariadb binlog observe those. Without a broker URL the plugin falls back to the in-process memory bus (single-process only) and warns at boot.

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

@@ -0,0 +1,116 @@
+# CDC-out (reverse-ETL)
+
+> Declaratively mirror table changes outward to external sinks (webhook / Kafka / Snowflake / BigQuery) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered.
+
+
+
+---
+
+<!-- source: en/plugins/cdc-out.md -->
+## CDC-out (reverse-ETL)
+
+_Declaratively mirror table changes outward to external sinks (webhook / Kafka / Snowflake / BigQuery) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered._
+
+# CDC-out — declarative reverse-ETL
+
+`@voltro/plugin-cdc-out` streams your table changes OUTWARD to an external
+sink. Declare `{ table → sink, map }` and the plugin mirrors every change
+through a **durable outbox** in your app's own database — no separate
+Debezium / Fivetran pipeline. The data-team wedge: app data in the warehouse,
+declared in code, composed onto the change stream you already have.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { cdcOutPlugin, webhookSink } from '@voltro/plugin-cdc-out'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    cdcOutPlugin({
+      sinks: [
+        {
+          table: 'orders',
+          sink:  webhookSink('https://warehouse.example.com/ingest'),
+          // Map a row → the outbound record body (default: the row unchanged).
+          map:   (row) => ({ id: row.id, total: row.total, status: row.status }),
+          // Optional: only mirror some changes.
+          filter: (event) => event.op !== 'delete',
+          batchSize: 500,          // max records per delivered batch (default 100)
+        },
+      ],
+      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
+    }),
+  ],
+}
+```
+
+One sink config per table per instance — a duplicate `table` is a **loud boot
+error**. For multiple sinks on one table, wire a second instance with a
+`name` (`cdcOutPlugin({ name: 'analytics', sinks: […] })`); it suffixes the
+plugin name (`@voltro/plugin-cdc-out#analytics`) and the inspect mount
+(`/_voltro/inspect/plugins/cdc-out--analytics/…`).
+
+## Sinks
+
+- **`memorySink()`** — in-process, records every delivered batch. Dev + tests.
+- **`webhookSink(url, { headers? })`** — POSTs each batch as
+  `{ records: [...] }` JSON, honoring the engine's per-attempt abort signal.
+  Its host is declared as a `network:outbound:<host>` permission automatically.
+- **Warehouse / Kafka** — implement the `CdcSink` interface
+  (`{ name, deliver(batch, ctx), outboundHost? }`). `deliver` may return a
+  **Promise or an Effect** — both compose without wrapping. The engine is
+  connector-agnostic; the sink is the only thing that changes.
+
+## Delivery guarantees — exactly what holds
+
+Every mirrored change becomes a row in `_voltro_cdcout_outbox` (contributed
+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.
+- **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
+  restarts, retries with exponential backoff + jitter, and re-sends the SAME
+  `deliveryKey`s — a sink that upserts on them dedupes safely.
+- **Ordered per pipe.** One in-flight batch per pipe, consumed strictly in
+  commit (id) order; the queue is head-blocking, so a batch waiting out its
+  retry backoff is never overtaken.
+- **Dead-letter, never silent drop.** A record that exhausts `maxAttempts`
+  moves to status `dead` with its last error — queryable at
+  `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.
+
+## Multi-tenancy
+
+The change tap fires for **every tenant's rows**, and a sink is app-global,
+developer-authored config: whatever `map` returns (default: the raw row,
+including `tenantId`) is mirrored to ONE external endpoint. Use `filter` /
+`map` to scope or strip tenant data, and only ever point sinks at
+**operator-controlled** URLs — never at a tenant-supplied one.
+
+## Backfill
+
+Seed a pipe with existing rows once — they flow through the SAME durable
+outbox as live changes (ordered, retried, dead-lettered, stable per-row
+`deliveryKey`s). Call from a `*.startup.tsx` or a CLI with the app's store:
+
+```ts
+import { enqueueBackfill } from '@voltro/plugin-cdc-out'
+import { sinkConfig } from './cdc'
+
+const n = await enqueueBackfill(store, sinkConfig, rows) // every current row, enqueued as an insert
+```