@voltro/cli 0.34.0 → 0.36.0

package/templates/agent-docs/deployment.md

@@ -11,7 +11,7 @@
 
 _Voltro Cloud (coming soon) — the managed runtime for your Voltro project. Today the Free control plane registers + observes your self-hosted apps._
 
-Voltro Cloud is the managed tier of the same open-core runtime you run locally. It's not a fork — `voltro start` is what powers your production instances, just with custom domains, multi-region routing, provisioned Postgres / Redis / object storage, and a control plane that handles deploys.
+Voltro Cloud is the managed tier of the same runtime you run yourself. It's not a fork — `voltro start` is what powers your production instances, just with custom domains, multi-region routing, provisioned Postgres / Redis / object storage, and a control plane that handles deploys.
 
 **Status:** managed cloud **deploy + provisioning is coming soon** and is not yet available. What's live today is the **Free control plane**: sign up and use it to **register and observe your self-hosted apps** (hosted observability, quotas, governance, teams). The managed-tier features described below are the planned shape of Voltro Cloud — see the per-section notes.
 
@@ -117,7 +117,7 @@ voltro cloud import   # scaffold voltro.cloud.toml from the app's app.config.ts
 
 _Run Voltro on your own infra — Docker compose, env vars, reverse proxy, scaling._
 
-Voltro is open-core. The runtime that powers Voltro Cloud is the same runtime you run locally with `voltro start`. Self-hosting is fully supported — no separate "lite" runtime, no feature gates around the core API.
+The runtime that powers Voltro Cloud is the same runtime you run yourself with `voltro start` — one codebase, one license. Self-hosting is fully supported — no separate "lite" runtime, no feature gates around the core API.
 
 ## The shape of a self-hosted deploy
 
@@ -1129,11 +1129,16 @@ Durable in-DB traces are **off in production by default** — traces belong in y
 
 ## 7. Graceful shutdown
 
-On `SIGTERM` / `SIGINT`, `voltro serve` shuts down cleanly (exit 0): it stops
-schedulers, detaches subscribers / reactions / aggregates, drains the analytics
-sink, stops accepting new connections while **finishing already-accepted
-requests**, and closes the SQL connection pool **last** (waiting for in-flight
-transactions). Verified under concurrent load — accepted requests complete.
+On `SIGTERM` / `SIGINT`, `voltro serve` shuts down cleanly (exit 0), in this
+order: it stops accepting new connections and lets **in-flight requests finish
+against a fully-alive app** (bounded — the request drain gets 60% of the
+shutdown grace, so the teardown behind it always fits inside the deadline),
+then stops schedulers, detaches subscribers / reactions / aggregates, drains
+the analytics sink and mirror, ends any remaining WebSocket, and closes the
+SQL connection pool **last** (waiting for in-flight transactions). Verified
+against a real serve under signal: a request in flight when `SIGTERM` lands
+completes with a full response before the process exits — no preStop hook, no
+orchestrator. A bare `voltro serve` under docker compose drains itself.
 
 The **transactional-outbox worker** is part of that sequence: its poll timer and
 its change subscription are released, and a delivery already in flight is
@@ -1141,11 +1146,12 @@ awaited, before the pool closes. An outbox row that was still pending is not
 lost — it is durable, and the next process's first pass picks it up, which is
 one of the three reasons that poll exists.
 
-**But the app cannot drain a rolling update by itself.** The runtime
-(`NodeRuntime`) owns the `SIGTERM` signal and closes the HTTP listener promptly —
-so a request that *arrives* during shutdown is refused. Failing readiness from
-inside the process doesn't help: the listener is already closing. Draining is a
-**k8s-layer** job, done with a **preStop hook**:
+**What an orchestrator still adds: routing.** The app finishes every request
+it has *accepted* — but a request that *arrives* after `SIGTERM` is refused
+(the listener closes immediately, on purpose), and only the layer that routes
+traffic can stop sending it. Failing readiness from inside the process doesn't
+help: the listener is already closed. Under k8s, close that window with a
+**preStop hook**:
 
 ```yaml
 spec:
@@ -1163,10 +1169,15 @@ spec:
             command: ["sh", "-c", "sleep 5"]
 ```
 
-Without the preStop hook, a rolling update drops the small window of requests
-that route to a terminating pod before k8s finishes removing it from the Service
-endpoints. With it, that window is drained. `terminationGracePeriodSeconds` must
-be larger than the sleep plus the app's own teardown, or k8s SIGKILLs mid-drain.
+Without the preStop hook, a rolling update refuses the small window of requests
+that still route to a terminating pod before k8s finishes removing it from the
+Service endpoints — refused with a connection error, not truncated mid-response
+(everything already accepted completes either way). With it, that window is
+served too. `terminationGracePeriodSeconds` must be larger than the sleep plus
+the app's own teardown, or k8s SIGKILLs mid-drain. Environments with no
+endpoint removal at all — docker compose above all — need nothing: there is no
+routing layer to lag behind the shutdown, so the built-in drain is the whole
+story.
 
 **Bound the app's own teardown with `VOLTRO_SHUTDOWN_GRACE_MS`.** After
 `SIGTERM`, the runtime runs its finalizers (pool close, plugin `onDeactivate`,
@@ -1190,10 +1201,10 @@ spec:
           value: "22000"
 ```
 
-The close is clean on the client side too: on shutdown each live WebSocket is
-closed with a proper close frame (not an abrupt socket drop), and the web
-client's supervisor reconnects on any close — so an open dashboard re-attaches
-to a healthy replica across a rolling deploy without a page reload.
+Live WebSockets are ENDED promptly at shutdown — the drain never lets an open
+socket hold the process to the deadline — and the web client's supervisor
+treats any close as a reconnect signal, so an open dashboard re-attaches to a
+healthy replica across a rolling deploy without a page reload.
 
 ## 8. Multiple replicas
 
@@ -1367,7 +1378,7 @@ VOLTRO_WORKFLOW_FAILOVER_HEARTBEAT=5    # lease-refresh cadence (default 10; kee
 
 Lower the lease for **faster failover**, at the cost of **false-positive reclaims**: if a *healthy* replica is paused longer than the lease by a GC pause or a DB-latency spike, another replica may briefly also claim its shards. Keep the heartbeat around a third of the lease so one slow refresh doesn't trip a reclaim. For crash detection that doesn't depend on the timeout at all, pair it with a K8s **liveness probe** so a dead pod is removed promptly.
 
-(A separate concern is *new*-message pickup: a workflow triggered on the replica that owns its shard starts immediately, but one owned by ANOTHER replica is otherwise picked up on that replica's next storage poll — up to 10s. **If you run a broadcast broker (Redis/NATS — which a multi-replica deployment already does for cross-replica reactivity), this is automatic and near-instant**: a trigger pushes a "wake" over the bus and the shard owner re-polls at once, on any SQL dialect. Without a broker, tune `VOLTRO_WORKFLOW_POLL_INTERVAL=2` instead. Unrelated to the failover path above.)
+(A separate concern is *new*-message pickup: a workflow triggered on the replica that owns its shard starts immediately, but one owned by ANOTHER replica is otherwise picked up on that replica's next storage poll — up to 10s. **If you run a broadcast broker (Redis/NATS — which a multi-replica deployment already does for cross-replica reactivity), this is automatic and near-instant**: a trigger pushes a "wake" over the bus and the shard owner re-polls at once, on any SQL dialect. **Without a broker, the change stream does the same job wherever remote changes reach the spine** — a Postgres-only multi-replica fleet (LISTEN/NOTIFY CDC) is the common case: a remote replica's signal, start context, or run transition arrives as a change event and triggers an immediate, coalesced re-poll, so signal/step latency stops being poll-bounded there too. Only with *neither* a broker *nor* CDC does the poll interval remain the bound — tune `VOLTRO_WORKFLOW_POLL_INTERVAL=2` then. Unrelated to the failover path above.)
 
 ## Checklist
 
@@ -1561,3 +1572,185 @@ Air-gapped and enterprise deployments attest seats contractually instead; no tel
 
 - [Voltro Cloud](./voltro-cloud.md) — the control plane these features live in
 - [Self-hosting](./self-hosting.md) — running Voltro yourself
+
+
+
+---
+
+<!-- source: en/deployment/platforms.md -->
+## Platform recipes
+
+_Deploy the same container to Fly.io, Railway, Render, or a Hetzner VM — one image, four wrappers._
+
+Every recipe on this page deploys the **same artifact**: the production image
+from the compose baseline's `docker/api.Dockerfile` (`voltro baseline set
+compose` writes it into your project). The platforms differ only in the wrapper
+— how they build it, which env vars they inject, and how they health-check it.
+
+**What is verified, stated exactly.** The container itself is the tested part:
+it builds from a clean context, boots `voltro serve` from the precompiled serve
+bundle, survives the `pnpm deploy` relocation, and answers
+`/internal/readiness` with 200 — that loop runs in this repo's own validation.
+The platform wrapper files below are written against each platform's current
+config format and have **not** been executed against a live account of that
+platform; if one drifts from what the platform ships today, the container is
+still right and the fix is in the wrapper.
+
+Three properties of the image every platform relies on:
+
+- **`PORT` wins.** The port precedence is `PORT` > `--port` > `app.config.ts` —
+  deliberately, because platforms assign through `PORT`. You never configure a
+  port in the wrapper beyond telling the platform which one the app answers on.
+- **A missing secret refuses to boot.** `VOLTRO_SESSION_SECRET` unset is a
+  clean, named boot refusal — not a server that signs with a default. Set
+  secrets in the platform's secret store before the first deploy, or read the
+  refusal message; both are correct outcomes.
+- **`/internal/readiness` flips to 200 only after the whole boot.** Use it as
+  the health check everywhere; routing traffic on process-up instead of
+  readiness is how a deploy serves 502s for the first seconds.
+
+## Fly.io
+
+```toml
+# fly.toml
+app = "my-voltro-api"
+primary_region = "fra"
+
+[build]
+  dockerfile = "docker/api.Dockerfile"
+  build-args = { APP_PATH = "apps/my-app/api" }
+
+[env]
+  DB_DIALECT = "postgres"
+
+[http_service]
+  internal_port = 4000
+  force_https = true
+  auto_stop_machines = "stop"
+  auto_start_machines = true
+  min_machines_running = 0
+
+  [[http_service.checks]]
+    path = "/internal/readiness"
+    interval = "10s"
+    timeout = "2s"
+```
+
+```sh
+fly secrets set VOLTRO_SESSION_SECRET=$(openssl rand -base64 32) DB_URL=<from fly postgres attach>
+fly deploy
+```
+
+The one Fly-specific decision: `auto_stop_machines` gives you scale-to-zero,
+and a cold start pays the container boot. The serve bundle exists for exactly
+this — the framework-boot slice of a cold start is ~180–210 ms instead of ~1 s.
+Read [Scale to zero](/docs/deployment/scale-to-zero) before choosing
+`min_machines_running = 0` for an api that owns schedules: a machine that is
+never awake fires no cron.
+
+## Railway
+
+Railway detects the Dockerfile; point it at the right one and set the build
+context to the repo root (the Dockerfile copies the whole workspace for
+`pnpm install`).
+
+```json
+// railway.json
+{
+  "build": {
+    "builder": "DOCKERFILE",
+    "dockerfilePath": "docker/api.Dockerfile"
+  },
+  "deploy": {
+    "healthcheckPath": "/internal/readiness",
+    "restartPolicyType": "ON_FAILURE"
+  }
+}
+```
+
+Set `VOLTRO_SESSION_SECRET` and `DB_URL` as service variables; Railway injects
+`PORT` and the image binds to it — no port config anywhere. The
+`APP_PATH` build arg goes into the service's build settings.
+
+## Render
+
+```yaml
+# render.yaml
+services:
+  - type: web
+    name: my-voltro-api
+    runtime: docker
+    dockerfilePath: ./docker/api.Dockerfile
+    dockerContext: .
+    healthCheckPath: /internal/readiness
+    envVars:
+      - key: DB_DIALECT
+        value: postgres
+      - key: VOLTRO_SESSION_SECRET
+        sync: false
+      - key: DB_URL
+        fromDatabase:
+          name: my-voltro-db
+          property: connectionString
+
+databases:
+  - name: my-voltro-db
+    plan: basic-1gb
+```
+
+`sync: false` makes the secret a dashboard-entered value that never lands in
+the blueprint file — the same "we ship no secret values" rule the framework
+enforces on its own templates applies to yours.
+
+## Hetzner (or any bare VM)
+
+A VM is the compose baseline with a process manager on top — this is the one
+recipe whose whole stack is the already-validated path from
+[Self-hosting](/docs/deployment/self-hosting).
+
+```sh
+# once, on the VM
+apt-get install -y docker.io docker-compose-plugin
+git clone <your-repo> /srv/app && cd /srv/app
+cp .env.example .env   # then fill in real values — nothing boots without them
+docker compose up -d --build
+```
+
+```ini
+# /etc/systemd/system/voltro.service — survive reboots
+[Unit]
+Description=voltro stack
+Requires=docker.service
+After=docker.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=true
+WorkingDirectory=/srv/app
+ExecStart=/usr/bin/docker compose up -d
+ExecStop=/usr/bin/docker compose down
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Caddy (in the baseline compose) terminates TLS with an automatic Let's Encrypt
+certificate — point the domain's A record at the VM and the certificate is
+provisioned on first request. What a VM does NOT give you: rolling deploys
+(compose restarts in place — expect seconds of downtime per deploy, or put two
+VMs behind a load balancer), and managed Postgres backups —
+[`voltro data backup`](/docs/cli/data) plus the restore drill is your baseline,
+and the drill is the part people skip.
+
+## Which one
+
+| | scale-to-zero | managed DB | rolling deploys | cost floor |
+|---|---|---|---|---|
+| Fly.io | yes (`auto_stop`) | Fly Postgres | yes | ~0 idle |
+| Railway | usage-based sleep | built-in | yes | ~0 idle |
+| Render | paid plans only | built-in | yes | fixed/instance |
+| Hetzner VM | no | bring your own | no (single VM) | fixed, cheapest at steady load |
+
+An api that owns cron schedules should not scale to zero. An api with bursty
+traffic and no schedules is exactly what scale-to-zero is for. When in doubt,
+the boring answer — one always-on instance — is also the cheapest to operate.

package/templates/agent-docs/introduction.md

@@ -127,7 +127,7 @@ Voltro is deliberately opinionated about boring things (HTTP, state, transport,
 
 ## What we won't do
 
-- **Lock you in.** Self-hosting is fully supported. Cloud is the premium tier of the same open-core runtime, not a fork.
+- **Lock you in.** Self-hosting is fully supported. Cloud is the premium tier of the same runtime, not a fork.
 - **Multi-runtime grab-bag.** Effect-TS end-to-end — no Restate, no Temporal, no Inngest, not even opt-in.
 - **Magic.** Every file convention is documented; every generated file lives in `.framework/` and you can read it.
 - **Codegen you have to remember to run.** Schema flows from your tables to your React components automatically via Vite's module graph.

package/templates/agent-docs/multi-tenancy.md

@@ -158,6 +158,20 @@ export default {
 
 Or via env — `VOLTRO_TENANT_ISOLATION=namespace` — which overrides the config field. The same flag is read by `voltro dev` and `voltro serve`, so the topology can't drift between dev and prod.
 
+### Provisioning — a new tenant's first request creates its namespace
+
+The namespace is provisioned **lazily, on first use**: a tenant nobody has seen
+before gets its schema and tables created — and its
+[`lifecycle: 'onTenantCreate'` seeds](/docs/data/queries) fired — the first time
+a request touches its store, memoised per process afterwards. There is nothing
+to pre-register, and a failed provision is retried on the next request rather
+than cached.
+
+Eager provisioning is **your** move, because only your app knows its tenants:
+call `provisionTenantNamespace(tables, namespace, sqlLayer, dialect)` from a
+seed or startup file over your own tenant table when you want the DDL paid at
+deploy time instead of on a tenant's first request.
+
 ### One mechanism, per-dialect mapping
 
 Namespace isolation is **one** mechanism — a per-request namespace `tenant_<sanitised-id>`, derived from `subject.tenantId` — mapped to each dialect's native physical container:
@@ -657,43 +671,100 @@ tenant's data.
 > `TenantResidencyUnresolved`. Home region not served here → typed
 > `TenantRegionUnavailable`. Both fail closed; that's the whole point.
 
-## Configure it
+## Declare it
+
+Residency is declared in `app.config.ts` and wired by both boot paths — `voltro
+dev` and `voltro serve` open one store per servable region and route every
+request through it. There is nothing to call from your own code.
 
 ```ts
-import { setResidencyConfig } from '@voltro/database'
-
-setResidencyConfig({
-  // tenant → home region (+ optional named connection for the home DB).
-  homes: [
-    { tenantId: 'acme',  region: 'eu-west' },
-    { tenantId: 'globex', region: 'us-east' },
-  ],
-  // The regions THIS deployment can actually serve (it holds their stores).
-  servableRegions: ['us-east'],
+export default defineApiApp({
+  tenancy: {
+    isolation: 'namespace',
+    residency: {
+      // The regions THIS deployment holds stores for.
+      servableRegions: ['eu-west'],
+      // region → the NAME of the env var holding that region's database URL.
+      regionUrlEnv: { 'eu-west': 'DB_URL_EU', 'us-east': 'DB_URL_US' },
+      // tenant → home region. An array, or a function resolving one at boot.
+      homes: [
+        { tenantId: 'acme', region: 'eu-west' },
+        { tenantId: 'globex', region: 'us-east' },
+      ],
+    },
+  },
 })
 ```
 
-A tenant mapped to two different regions is rejected at config time (ambiguous
-routing), and `servableRegions` must be non-empty.
+`regionUrlEnv` takes a variable NAME, not a URL: a connection string is a
+secret and `app.config.ts` is committed. Everything else about a region's store
+— pool bounds, TLS, `search_path`, statement timeouts — is inherited from the
+primary connection, so a region cannot silently run with different limits than
+the deployment it belongs to.
+
+`homes` may be a function (`() => Promise<TenantHome[]>`) if the mapping lives
+in your own table or control plane. It is resolved **once, at boot**: adding a
+tenant home needs a restart. That is deliberate — the alternative is a cache
+with a staleness window on a decision whose entire value is that it is never
+wrong.
+
+### It requires namespace isolation, and refuses to boot without it
+
+`residency` without `isolation: 'namespace'` is a **boot refusal**, not a
+warning. The region keeps regions apart; the namespace keeps tenants apart
+inside a region. With only the first, every tenant in a region would share one
+set of tables — the region boundary held and the tenant boundary dropped, which
+looks like residency and is not.
+
+The other boot refusals, all for the same reason (a deployment that looks like
+it enforces residency and does not is worse than one that will not start):
 
-## Resolve + bind per request
+- a servable region with no `regionUrlEnv` entry;
+- a servable region whose env var is unset;
+- an empty `servableRegions`;
+- a tenant mapped to two different regions.
 
-`bindResidentStore` picks the store for the subject's home region from the
-per-region handles this deployment holds — failing closed if the home is
-unresolved or not served here:
+## What a request gets
+
+Every request resolves its subject's tenant → home region → **that region's
+store**, and only then binds the tenant's namespace inside it. Residency picks
+which database; the namespace picks which tenant's tables in it.
+
+Three refusals, none of which falls back:
+
+| Situation | Result |
+|---|---|
+| Subject has no resolvable tenant | `TenantResidencyUnresolved` |
+| Tenant has no home mapped | `TenantResidencyUnresolved` |
+| Tenant homed in a region this deployment does not serve | `TenantRegionUnavailable`, naming the region so a gateway can route it |
+
+`ctx.storeForTenant(id)` resolves residency for **that** tenant, not the
+caller's — so a handler acting on another tenant either reaches that tenant's
+region or is refused. It is the seam background work must use: a schedule or a
+workflow runs with no request and, under the system subject, no tenant, so
+`ctx.store` on those paths is the primary store. A job that touches one tenant's
+rows has to say which tenant, and `storeForTenant` is how it says so.
+
+A transaction is never re-routed. When a mutation hands its transaction-scoped
+store to a nested call, that store is used as given — it already went through
+residency to exist, and moving writes off the connection holding the lock would
+be a worse failure than the one residency prevents.
+
+## Driving it yourself
+
+The resolvers are exported for a control plane that owns the mapping itself —
+`setResidencyConfig`, `residentPlacement`, `bindResidentStore`. The declaration
+above calls the first two for you; reach for them directly only if you are
+building the region topology outside the framework.
 
 ```ts
 import { bindResidentStore } from '@voltro/database'
 
-// stores: ReadonlyMap<region, StoreHandle> — what THIS deployment wired.
+// stores: ReadonlyMap<region, StoreHandle>
 const { store, placement } = bindResidentStore(subject, config, stores)
 // placement = { region, namespace, connectionKey? }
-// throws TenantRegionUnavailable for an EU-homed tenant on a US deployment.
 ```
 
-`residentPlacement(subject, config)` gives the placement alone (region +
-the tenant's namespace within that region's store) without needing the handles.
-
 ## Provision a new resident tenant
 
 `provisionResidentTenant` runs an injected provisioner against the tenant's HOME

package/templates/agent-docs/plugins/ai-flows.md

@@ -165,10 +165,96 @@ A flow authored as DATA carries the same setting in `_voltro_ai_flows.humanTimeo
 When the bound does expire, the run row is written `status: 'failed'` naming the
 bound that elapsed — it no longer dies with the row still reading `waiting`.
 
+## Conditional steps and fan-out
+
+```ts
+defineFlow({
+  name: 'campaign',
+  brief: [{ key: 'mode', label: 'Mode', type: 'text' }],
+  steps: [
+    flowStep.text({ prompt: 'Draft the copy', outputKey: 'copy' }),
+
+    // Runs only when the brief asked for the full treatment.
+    flowStep.text({
+      prompt: 'Write a long-form variant of {{copy}}',
+      outputKey: 'longform',
+      when: { ref: 'mode', op: 'eq', value: 'full' },
+    }),
+
+    // These two run CONCURRENTLY — same group, consecutive.
+    flowStep.media('image', { prompt: 'Hero image for {{copy}}', outputKey: 'hero', group: 'assets' }),
+    flowStep.media('image', { prompt: 'Square crop for {{copy}}', outputKey: 'square', group: 'assets' }),
+
+    // Both group outputs are available again after the group completes.
+    flowStep.note({ prompt: 'Ship {{hero}} and {{square}}', outputKey: 'summary' }),
+  ],
+})
+```
+
+### `when:` — run a step only sometimes
+
+A step with a `when:` runs only if the condition holds against the run context
+(brief fields ⊕ earlier `outputKey`s). A step whose condition is false is
+**skipped**, not failed: it produces no output, so anything referencing it sees
+an absent value — which is what makes `when` compose with the dependency guard
+instead of fighting it. The run timeline shows the step as `skipped` with the
+rendered reason (`{{mode}} equals "full"`), so a step that vanished is never
+indistinguishable from a step nobody declared.
+
+| `op` | True when |
+|---|---|
+| `truthy` / `falsy` | the value is present and not `false` / an empty array |
+| `eq` / `neq` | the value equals the literal (structural for objects and arrays) |
+| `contains` | the array contains the value, or the string contains the substring |
+
+Two deliberate choices, because both look like bugs until you know why:
+
+- **A condition is structured data, not an expression string.** A flow can be
+  authored as a stored row a user edits in a browser, and an expression there
+  would be an evaluator running user-authored source on your server. It also
+  lets the boot-time validator refuse a condition on a key nothing produces —
+  the alternative silently skips its step on every run, forever.
+- **`0` and `''` are TRUTHY here.** A step gated on a generated count or string
+  means "did the producer run", not "is it non-zero". The second is `{ op:
+  'neq', value: 0 }`, which you can say when you mean it.
+
+A compound condition needs two steps, or a `structured` step that computes the
+boolean. That is a real limit of a parser-free design.
+
+### `group:` — run steps concurrently
+
+**Consecutive** steps sharing a `group` name run at the same time. Each keeps its
+own durable step, so a replay resolves every branch from the journal exactly as
+it would sequentially — the concurrency is in the execution, not in the
+durability.
+
+Three rules, all enforced at registration rather than at run time:
+
+- Steps in one group **cannot read each other's outputs** — they have no order
+  between them. Their outputs become available to everything *after* the group.
+- A group must be **contiguous**. A group name that stops and resumes would
+  execute as two sequential fan-outs, which is the opposite of what it reads as.
+- A **`human` review cannot join a group** — it suspends the whole run, which
+  one branch of a fan-out cannot do.
+
+One failing branch fails the run; the siblings that succeeded keep their
+journaled results, so a retry does not re-pay for them.
+
 ## Chaining & cadence
 
 - **`chainTo`** launches a follow-up flow on success (result ⊕ input → the child's
   brief); `requireConfirmation` stages it for the user to confirm.
+- **A chain is bounded.** `chainTo` used to carry one guard — a flow could not
+  chain to itself — so `A → B → A`, or a chain that simply ran deep, was
+  unbounded: every hop starts a child run with a fresh idempotency key, and
+  nothing was counting. A run now carries the chain that led to it, and a chain
+  is refused when the target is already in that path (a cycle) or when the depth
+  reaches `maxChainDepth` (default 5; `aiFlowsPlugin({ maxChainDepth })` or
+  `VOLTRO_AI_FLOW_MAX_CHAIN_DEPTH`). The refusal lands on the run row's
+  `chainRefusal` naming the path — a chain that silently does not fire is
+  indistinguishable from one nobody declared. The parent run still **succeeds**:
+  a refused follow-up is a configuration problem, not a reason to destroy a
+  completed result.
 - **`cadence`** schedules runs — `weekly` (with `intervalWeeks` + `anchorDate`) or
   `monthly` (`weekOfMonth`, incl. `'last'`). `cadenceMatches` / `nextRuns` are
   exported so the editor's "next 3 runs" preview and the scheduler agree exactly.

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

@@ -46,7 +46,7 @@ What it provides:
 - 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.entitlementStatus`, `billing.reportUsage`, `billing.changePlan`, `billing.changeSeats`.
+- The rpc routes `billing.startCheckout`, `billing.portalUrl`, `billing.subscription`, `billing.entitlementStatus`, `billing.reportUsage`, `billing.previewChange`, `billing.invoices`, `billing.changePlan`, `billing.changeSeats`. Every route resolves the tenant from the caller's subject, and each declares its access decision: `billing.subscription` + `billing.entitlementStatus` are `openAccess` (the tenant-scoped reads every member's account UI renders), while the routes that change what the tenant pays — `startCheckout`, `portalUrl`, `previewChange`, `changePlan`, `changeSeats` — and the invoice history (`invoices`) require the **`billing:manage`** scope, and `reportUsage` requires **`billing:report`** (a metering credential's scope — an unguarded usage report would let any session inflate its tenant's counters). Grant the scopes via an rbac role or your auth strategy's `resolveScopes`; `admin:full` passes, as always.
 - **Seat-based billing**; proration and failed-payment retries are Stripe's.
 - **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.

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

@@ -63,6 +63,37 @@ on graceful shutdown.
 | `table` | `string` | `'events'` | Override the events-table name. |
 | `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. |
+| `batch` | `{ maxSize?, flushIntervalMs? } \| false` | **on** — `{ maxSize: 20, flushIntervalMs: 5000 }` | Client-side batching of `track()` inserts. `false` opts out (one immediate, confirmed insert per event). |
+
+## Batching is on by default
+
+One HTTP insert per event is how a MergeTree gets **part-exploded** under load —
+every single-row insert creates a data part the server must merge away. So
+`track()` **batches by default**: rows buffer in the process and flush in ONE
+multi-row insert once 20 events are pending, 5 seconds after the first buffered
+event (whichever comes first), and on graceful shutdown (the `dispose` hook
+drains the buffer before the client closes).
+
+What changes observably with batching on:
+
+- A successful `track()` means **"buffered"**, not "ClickHouse accepted the
+  row" — the insert happens later, off the call path.
+- Events become visible to reads up to `flushIntervalMs` later than they were
+  tracked.
+- A flush failure is logged and that batch **dropped** (best-effort analytics —
+  re-queuing a partially-applied insert would risk duplicates). A hard crash
+  loses whatever is still buffered; a graceful shutdown loses nothing.
+
+If you need per-event delivery confirmation, opt out explicitly:
+
+```ts
+analytics: clickhouseAnalytics({
+  url: process.env.CLICKHOUSE_URL!,
+  batch: false,   // one immediate insert per track(); success = row accepted
+})
+```
+
+…or tune the window: `batch: { maxSize: 500, flushIntervalMs: 2000 }`.
 
 `database`, `table`, and each `mirrorTables` entry are validated as SQL
 identifiers at boot (they're interpolated into DDL) — a bad name fails loudly at

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

@@ -46,7 +46,7 @@ export default {
 
 The plugin declares `onChangeEvent`. On every committed write to a configured table, `applyChange` maps the row via `map(row)` and upserts (insert/update) or removes (delete) the index document. No `*.subscribe.ts`, no manual indexing calls — the tap is the single sync path, and it runs under both `voltro dev` and `voltro serve`.
 
-For pre-existing rows, `backfillIndex(backend, spec, rows)` indexes the rows you supply (call it from a `*.startup.tsx` or a one-off script) — or use the **Reindex** button / `POST /reindex` inspect endpoint, which reads the table's current rows for you.
+For pre-existing rows, `backfillIndex(backend, spec, rows)` indexes the rows you supply (call it from a `*.startup.tsx` or a one-off script) — or use the **Reindex** button / `POST /reindex` inspect endpoint, which reads the table's current rows for you. The endpoint **streams** the table (keyset-paginated) and upserts one bounded page at a time — `sync.reindexBatchSize`, default 1000 rows — so memory stays flat no matter how large the table is. `backfillIndex` itself stays a plain array API for small explicit seeds.
 
 ## When the engine is down
 
@@ -69,6 +69,9 @@ searchPlugin({
     retryMaxDelayMs: 10_000,  // ceiling for any single wait
     resyncIntervalMs: 60_000, // repair-sweep interval. 0 turns the sweep off (POST /resync still repairs on demand)
     resyncBatchSize: 200,     // max ledger entries repaired per sweep
+    reindexBatchSize: 1000,   // rows per page for POST /reindex (streamed keyset walk — memory stays flat)
+    statsFlushIntervalMs: 5_000, // buffered sync-counter flush cadence. 0 = one durable write per event
+    statsFlushMaxBuffered: 1000, // flush early once this many counts are pending
   },
 })
 ```
@@ -258,9 +261,9 @@ Two things to be clear about before you reach for it:
 
 ## Dashboard panel
 
-Both dashboards ship a **Search** panel (api apps): the configured indexes with per-index sync stats (docs synced/removed, last reindex) + the resolved backend, and a **Reindex** button per index that re-seeds it from the table's current rows (`backfillIndex`). Reindex gates on the `canReindexSearch` capability. Backed by `/_voltro/inspect/plugins/search/{indexes,reindex}`.
+Both dashboards ship a **Search** panel (api apps): the configured indexes with per-index sync stats (docs synced/removed/dropped, last reindex) + the resolved backend, per-index **drift badges** (`pendingDrift` / `drifted` / last drift time), the **repair queue itself** (the drift-ledger rows, oldest first, with attempt counts and the engine's last error), and two actions — **Reindex** per index (streams the table's current rows back in) and **Resync now** (repairs the drifted rows on demand). Reindex gates on the `canReindexSearch` capability, resync on `canResyncSearch`. Backed by `/_voltro/inspect/plugins/search/{indexes,drift,reindex,resync}`.
 
-The sync stats behind this panel are **durable and aggregated across replicas**. They live in a framework-owned `_voltro_search_stats` table (contributed via `extendSchema.tables`; the plugin declares `store:write`), one row per `(index, replica)`, each bumped with an atomic compare-and-set. `/indexes` aggregates every replica's row — summed under `local` change scope, maxed under `fleet` (see [Under multiple replicas](#under-multiple-replicas)) — and takes the most-recent reindex, so the counts are truthful under multiple instances and survive a restart. Zero-infra dev/tests use an in-process stats store; `bindDataStore` swaps in the durable one at boot, along with the drift ledger.
+The sync stats behind this panel are **durable and aggregated across replicas** — and counted **in memory first**: each replica buffers its per-event counts and flushes them to the stats table once per window (`sync.statsFlushIntervalMs`, default 5 s; early once `statsFlushMaxBuffered` counts are pending), so an indexed-table write never pays a per-write read+CAS against your primary. A graceful shutdown flushes the tail; a hard crash loses at most the current window of *counters* (never a change — the drift ledger, not these counters, is the durable record of what did not reach the engine). `GET /indexes` drains the buffer before reading, so the panel is always current. `statsFlushIntervalMs: 0` restores one durable write per event. They live in a framework-owned `_voltro_search_stats` table (contributed via `extendSchema.tables`; the plugin declares `store:write`), one row per `(index, replica)`, each bumped with an atomic compare-and-set. `/indexes` aggregates every replica's row — summed under `local` change scope, maxed under `fleet` (see [Under multiple replicas](#under-multiple-replicas)) — and takes the most-recent reindex, so the counts are truthful under multiple instances and survive a restart. Zero-infra dev/tests use an in-process stats store; `bindDataStore` swaps in the durable one at boot, along with the drift ledger.
 
 ## Permissions
 

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

@@ -417,6 +417,17 @@ procedure's wire-error union so they decode typed on the client:
 `storage.revoke`, `storage.listGrants`, `storage.listRefs`. (The upload hook picks
 the right ones per `prefer`; you rarely call them directly.)
 
+Every route declares its access decision. The self-service upload/read flow is
+`openAccess` — what bounds it is structural (mints bind the caller's subject +
+tenant into a signed ticket, finalize/complete refuse another subject's token,
+reads go through the per-object access policy + grants, the grant RPCs enforce
+owner-or-admin in-handler). Three routes require a scope instead: **`storage.mintUploadUrl`**
+(the raw bring-your-own-key PUT, which bypasses limits + scan) and
+**`storage.ingestUrl`** (the server fetches a caller-supplied URL — an SSRF
+surface) need `storage:manage`; **`storage.listRefs`** (the tenant-WIDE media
+library index) needs `storage:browse`. Grant them via an rbac role or
+`resolveScopes`; `admin:full` passes.
+
 ### The grant RPCs are owner-only
 
 `storage.share`, `storage.revoke` and `storage.listGrants` require that the