@voltro/cli 0.55.0 → 0.56.0

package/dist/{webhooksCommand-B1LVcyO3.js → webhooksCommand-uuPu8qQX.js}

@@ -222,7 +222,7 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev-DfVZaoys.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-B9Gz0k85.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
 	return r((await n(await t(e))).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor

package/dist/{workflowsCmd-BGF-mRZ5.js → workflowsCmd-g-DNpaUc.js}

@@ -1,5 +1,5 @@
 import { n as e } from "./cliOutput-D1tSBoRM.js";
-import { n as t, o as n, r, t as i } from "./inspectFetch-EMuhTG_9.js";
+import { n as t, o as n, r, t as i } from "./inspectFetch-BU1NyzxV.js";
 import { ansi as a } from "@voltro/logger";
 //#region src/workflowsCmd.ts
 var o = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -766,6 +766,42 @@
         "title": "WidgetKind gained 'rich-text' — total widget registries need one new entry",
         "kind": "manual"
       },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/01_inspect_answers_are_observations",
+        "title": "inspect answers are `Observation`s — the payload is `.data`",
+        "kind": "manual"
+      },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/02_broadcast_gap_is_one_object",
+        "title": "attachBroadcastBus's onGap now receives a single BroadcastGap object",
+        "kind": "manual"
+      },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/03_outbox_drain_needs_an_identity",
+        "title": "drainOutbox now requires claimedBy — the fleet-wide exactly-once gate",
+        "kind": "manual"
+      },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/04_reaction_dedupe_is_one_claim",
+        "title": "runReaction's dedupe is a single atomic claim",
+        "kind": "manual"
+      },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/05_plugin_bind_context_claims_a_change",
+        "title": "PluginBindContext requires claimChange; change identity moved to @voltro/database",
+        "kind": "manual"
+      },
+      {
+        "version": "0.56.0",
+        "id": "0.56.0/06_serve_is_api_only",
+        "title": "`voltro serve` on a WEB app now refuses — use `voltro start`",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -848,24 +884,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.55.0",
-    "@voltro/cache": "0.55.0",
-    "@voltro/client": "0.55.0",
-    "@voltro/content": "0.55.0",
-    "@voltro/data-transfer": "0.55.0",
-    "@voltro/database": "0.55.0",
-    "@voltro/env": "0.55.0",
-    "@voltro/kv": "0.55.0",
-    "@voltro/logger": "0.55.0",
-    "@voltro/plugin-auth": "0.55.0",
-    "@voltro/plugin-broadcast": "0.55.0",
-    "@voltro/plugin-mail": "0.55.0",
-    "@voltro/plugin-storage": "0.55.0",
-    "@voltro/plugin-webhooks": "0.55.0",
-    "@voltro/protocol": "0.55.0",
-    "@voltro/runtime": "0.55.0",
-    "@voltro/serverless": "0.55.0",
-    "@voltro/workflow": "0.55.0",
+    "@voltro/ai": "0.56.0",
+    "@voltro/cache": "0.56.0",
+    "@voltro/client": "0.56.0",
+    "@voltro/content": "0.56.0",
+    "@voltro/data-transfer": "0.56.0",
+    "@voltro/database": "0.56.0",
+    "@voltro/env": "0.56.0",
+    "@voltro/kv": "0.56.0",
+    "@voltro/logger": "0.56.0",
+    "@voltro/plugin-auth": "0.56.0",
+    "@voltro/plugin-broadcast": "0.56.0",
+    "@voltro/plugin-mail": "0.56.0",
+    "@voltro/plugin-storage": "0.56.0",
+    "@voltro/plugin-webhooks": "0.56.0",
+    "@voltro/protocol": "0.56.0",
+    "@voltro/runtime": "0.56.0",
+    "@voltro/serverless": "0.56.0",
+    "@voltro/workflow": "0.56.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -142,6 +142,24 @@ line below replaces something real apps write by hand hundreds of times.
    notify-helper at the tail of the mutation body instead makes the reactivity
    invisible — you can only find it by reading every executor. Both are
    best-effort, so genuinely critical delivery still belongs in a workflow.
+   **A subscriber runs on EVERY replica.** That is right for a handler that
+   refreshes an index or drops a process-local cache, and wrong for one whose
+   effect IS a write someone receives — two pods send two mails. When the
+   handler is an effect, add `once:` (a deterministic key per change) and
+   exactly one replica runs it:
+   ```ts
+   defineSubscriber({
+     table: 'absence_requests', on: ['insert'],
+     once: true,
+     handler: notifyApprovers,
+   })
+   ```
+   `once: true` derives the key from the change (content + its position among
+   content-identical repeats) — prefer it. A function is for when you want to be
+   COARSER than one-per-change; a key you write must tell two genuine changes
+   apart, and a row id does not for `update`. `once` is AT MOST once — a replica
+   that wins and dies takes the event with it. `defineReaction`'s `dedupeKey`
+   gives its act the same fleet-wide gate.
 4. **A roll-up / counter recomputed on every read?** → **`defineAggregate`**
    (`*.aggregate.ts`). Add `incremental:` for `count|sum|avg|min|max` group-bys
    and it is MAINTAINED on write rather than recomputed. `read({ where })`
@@ -217,6 +235,7 @@ line below replaces something real apps write by hand hundreds of times.
 | `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
 | 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
 | a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| a subscriber that sends a mail / notification / webhook | the same, plus **`once:`** — without it, one per replica |
 | `WHERE ownerId = me` in every list handler | `setRowFilter` (covers the SUBSCRIPTION too) |
 | a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
 | `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
@@ -358,7 +377,7 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.workflow.tsx` + `*.workflow.server.tsx` | durable multi-step work |
 | `*.trigger.tsx` | domain event → workflow |
 | `*.cron.tsx` | scheduled job (single file) |
-| `*.subscribe.ts` | best-effort post-commit reaction to a table |
+| `*.subscribe.ts` | best-effort post-commit reaction to a table (every replica; `once:` for one) |
 | `*.reaction.tsx` | standing reactive agent |
 | `*.aggregate.ts` | scheduled materialised query |
 | `*.startup.tsx` | run-once boot hook holding a resource |

package/templates/AGENTS.md

@@ -142,6 +142,24 @@ line below replaces something real apps write by hand hundreds of times.
    notify-helper at the tail of the mutation body instead makes the reactivity
    invisible — you can only find it by reading every executor. Both are
    best-effort, so genuinely critical delivery still belongs in a workflow.
+   **A subscriber runs on EVERY replica.** That is right for a handler that
+   refreshes an index or drops a process-local cache, and wrong for one whose
+   effect IS a write someone receives — two pods send two mails. When the
+   handler is an effect, add `once:` (a deterministic key per change) and
+   exactly one replica runs it:
+   ```ts
+   defineSubscriber({
+     table: 'absence_requests', on: ['insert'],
+     once: true,
+     handler: notifyApprovers,
+   })
+   ```
+   `once: true` derives the key from the change (content + its position among
+   content-identical repeats) — prefer it. A function is for when you want to be
+   COARSER than one-per-change; a key you write must tell two genuine changes
+   apart, and a row id does not for `update`. `once` is AT MOST once — a replica
+   that wins and dies takes the event with it. `defineReaction`'s `dedupeKey`
+   gives its act the same fleet-wide gate.
 4. **A roll-up / counter recomputed on every read?** → **`defineAggregate`**
    (`*.aggregate.ts`). Add `incremental:` for `count|sum|avg|min|max` group-bys
    and it is MAINTAINED on write rather than recomputed. `read({ where })`
@@ -217,6 +235,7 @@ line below replaces something real apps write by hand hundreds of times.
 | `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
 | 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
 | a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| a subscriber that sends a mail / notification / webhook | the same, plus **`once:`** — without it, one per replica |
 | `WHERE ownerId = me` in every list handler | `setRowFilter` (covers the SUBSCRIPTION too) |
 | a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
 | `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
@@ -358,7 +377,7 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.workflow.tsx` + `*.workflow.server.tsx` | durable multi-step work |
 | `*.trigger.tsx` | domain event → workflow |
 | `*.cron.tsx` | scheduled job (single file) |
-| `*.subscribe.ts` | best-effort post-commit reaction to a table |
+| `*.subscribe.ts` | best-effort post-commit reaction to a table (every replica; `once:` for one) |
 | `*.reaction.tsx` | standing reactive agent |
 | `*.aggregate.ts` | scheduled materialised query |
 | `*.startup.tsx` | run-once boot hook holding a resource |
@@ -730,7 +749,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.55.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.56.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.55.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.56.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_manifest.json

@@ -206,7 +206,7 @@
       "group": null,
       "description": "OpenTelemetry tracing in Voltro — the auto-emitted spans for every primitive, span attributes and nesting, the three enabling modes (console / OTLP / buffer), and adding your own spans with Effect.withSpan.",
       "path": "agent-docs/observability.md",
-      "files": 4
+      "files": 5
     },
     {
       "id": "plugins",

package/templates/agent-docs/cli.md

@@ -1441,6 +1441,86 @@ Type mapping is faithful: `string → String`, `integer → Int`, `number → Do
 
 **Scope — this is the SDK code generator, not a native runtime.** Deliberately out of scope (they need a native runtime or managed infra, not generated client code): native module bindings (camera, biometrics), the APNs/FCM push **sender** (per-tenant Apple/Firebase credentials, provisioned server-side), and the managed OTA / EAS build pipeline. The generated source is verified at the generator level (golden-string tests over the emitted Swift + Kotlin). Compiling it with `swiftc` / Gradle is the remaining step in your own mobile CI — the framework harness has no Swift/Kotlin toolchain.
 
+## Serving: asset prefix, pre-compression, sourcemaps, keep-alive
+
+Four knobs that decide what leaves the container. All are `voltro start`
+concerns; none change what your code does.
+
+```ts
+// apps/web/app.config.ts
+web: {
+  // Serve `assets/` from a CDN. Becomes vite's `base`, so every emitted URL —
+  // entry, modulepreloads, CSS, images, fonts — is written with the prefix at
+  // BUILD time. Pre-rendered HTML still comes from the app; upload
+  // `dist/assets/` to the prefix on deploy. Filenames are content-hashed, so a
+  // previous deploy's assets stay valid for a visitor mid-navigation.
+  assetPrefix: 'https://cdn.example.com/_assets',
+
+  // Emit `.map` files WITHOUT a `//# sourceMappingURL` comment, so nothing in
+  // the shipped JS points at them. For `plugin-sentry`: upload them in your
+  // deploy step and DELETE them before the image is built. `voltro start`
+  // refuses to serve a `.map` regardless, so a forgotten delete is not a leak.
+  sourcemaps: 'hidden',
+},
+http: {
+  // Node hangs up an idle keep-alive connection after 5s; every proxy in front
+  // holds one longer, and the request that lands in that window comes back as
+  // a 502. Default 72000 clears nginx-60/ALB-60; raise it above YOUR proxy's
+  // idle timeout. `headersTimeoutMs` must exceed it and is derived if omitted.
+  keepAliveTimeoutMs: 72_000,
+},
+```
+
+**Pre-compression is automatic.** `voltro build` writes `.br` (quality 11) and
+`.gz` beside every content-hashed asset over 1 KB, and `voltro start` serves the
+variant when the client accepts it. Measured on one 321 KB chunk, three requests:
+
+| | time | bytes |
+|---|---:|---:|
+| compressed per request (before) | 5.6 / 5.0 / 4.6 ms | 100 665 |
+| pre-compressed (now) | 1.6 / 1.7 ms | **86 083** |
+
+Faster *and* smaller: a build can afford brotli q11 where a per-request path
+cannot. Both encodings of one asset carry the same `ETag` — it is computed over
+the uncompressed file, so a shared cache sees one representation.
+
+**A cross-origin api gets a `preconnect`.** When an api's `wsUrl` is on another
+host, the shell carries `<link rel="preconnect" href="…" crossorigin>` so DNS +
+TCP + TLS overlap the bundle download instead of following it. Same-origin apis
+are skipped — the browser already has that connection.
+
+## `voltro serve <appDir>` — API apps only
+
+`voltro serve` is the production server for an **API** app. On a **web** app it
+refuses and points you at `voltro start`:
+
+```text
+`voltro serve` is the production server for an API app — this is a WEB app.
+
+  production   voltro start .
+  development  voltro dev .
+```
+
+That is a refusal, not a missing feature. `serve` used to build a web app a
+second time and hand it to `vite preview`, and both halves were wrong:
+
+- **In production it never ran.** The launcher's serve fast path requires
+  `.framework/dist-api/serveBundle/serveEntry.js` — an artefact a web build does
+  not produce — so a web app exited 1 pointing at a path that cannot exist,
+  directly after a `voltro build` that had just succeeded.
+- **Below production it destroyed the build.** That second build had no
+  `@tailwindcss/vite`, no image pipeline and no per-page islands entries. With
+  Tailwind it aborted; without it, it succeeded — and since both builds write
+  `.framework/dist`, which Vite empties, it deleted `dist/server`, the island
+  shells and every pre-rendered page. `voltro start` could then not boot at all.
+
+So the table is:
+
+| app | development | production |
+|---|---|---|
+| web | `voltro dev` | `voltro start` |
+| api | `voltro dev` | `voltro serve` |
+
 ## `voltro doctor` — preflight a production serve
 
 Production `voltro serve` for an **API** app boots ONLY from the precompiled serve
@@ -1775,6 +1855,7 @@ It covers both halves of the stack:
 | server | `requireScope(...)` at the top of an executor | `guards:` on the descriptor |
 | server | a `token` / `secret` / `password` column with no encryption | `.encrypted()` |
 | server | a notify / webhook helper called at a mutation's tail | `defineSubscriber` / `defineReaction` |
+| server | a `*.subscribe.ts` handler that writes or publishes, with no `once:` | `once: true` on `defineSubscriber` |
 | server | `hasMore` + `limit + 1` | `paginateById` |
 | server | `.getTime()` / `.toISOString()` mapping a row on the way out | `timestampMs` / `timestampMsOrNull` from `@voltro/database/wire` in the descriptor's `output` struct |
 | client | per-field `useState` + a submit flag | `useFormBinding` |
@@ -1801,6 +1882,28 @@ already uses `.one()`, stays silent.
 
 Two of them are worth spelling out, because their advice is not one-line:
 
+**The subscriber rule is the second half of the mutation-tail rule.** That one
+moves an effect OUT of a mutation and into a subscriber, which is right — and
+lands it on a channel every replica listens to. `store.onChange` is a broadcast:
+correct for a READER (a cache drop, an index refresh, a live query must run
+everywhere) and a multiplier for an EFFECT, because there is nothing to make
+idempotent — the effect IS the write, so each run produces another one. One
+`INSERT` behind two replicas therefore writes two notification rows, and four
+with a broadcast bus in front.
+
+So the rule fires when a handler WRITES (`ctx.store.insert` / `update` /
+`upsert` / …), publishes (`ctx.publish`), or calls a `notify` / `sendWebhook` /
+`sendMail`-shaped helper, and the subscriber declares no `once:`. Any `once:`
+silences it — `true` or a key function — because the question is whether the
+decision was made, not which way. It reads the handler through the AST, so
+`handler: notifyApprovers` naming a function in the same file is judged exactly
+like an inline arrow; a handler IMPORTED from another module is not judged at
+all, since its body is not in the file being read.
+
+It stays quiet on a reader on purpose. `once:` on a cache-warming subscriber
+would silence it on every replica but one, which is worse than the repetition it
+removes — only the handler's author knows which of the two they wrote.
+
 **The credential-column rule skips names that aren't credentials.** A name ending
 in `Id` / `_id`, a name ending in `Hash` / `_hash`, and a name beginning with
 `vault` are all left alone:
@@ -4548,6 +4651,25 @@ prints only because your tree matched it.
 
 Codemods that span multiple versions run in order (e.g. upgrading `0.2.0 → 0.4.0` runs the `0.3.0` and `0.4.0` codemods in sequence).
 
+### When nothing changed, read WHICH nothing
+
+Two states end an update with no diff, and they mean opposite things: the jump
+ships no codemods, or it ships some and every one of them decided your project
+is not affected. The summary names which:
+
+```text
+codemods: 2 ship for this jump; none matched your project.
+  · 0.55.0/01_target-relations-declare-columns — its own check found nothing to change
+  · 0.55.0/02_widget-kind-gained-rich-text — its own check found nothing to change
+```
+
+`none ship for this jump` is the first. The second lists the ids, because a
+codemod's own check is a predicate that can be wrong — and a gate that reads
+the wrong files answers "does not apply" for a project that is fully affected.
+If you recognise a subject in that list as something your app *does* use, that
+is a bug in the check rather than a fact about your code; the CHANGELOG entry
+for the version says what each one looks for.
+
 ## The database is separate
 
 `voltro update` does **not** touch your database. Framework-owned `_voltro_*` tables (workflow runs, schedules, …) are reconciled by the declarative differ, not by codemods: when a release changes one of those tables, your next `voltro db apply` (or `voltro dev` boot, which auto-applies) picks up the change.

package/templates/agent-docs/data.md

@@ -2346,6 +2346,38 @@ The contract, in the order it protects you:
 
 **The boundary to keep:** if your own UI needs live data, that is a query + `useSubscription`, never a gateway. A gateway hands you raw frames and none of the subscription protocol's guarantees — reach for it only when the CLIENT dictates the protocol.
 
+## When the api connects — `web.api.connect`
+
+Every declared api opens its WebSocket at mount by default. That is `'eager'`,
+and it is what the framework has always done.
+
+```ts
+// apps/web/app.config.ts
+web: { api: { connect: 'lazy' } }
+```
+
+`'lazy'` defers the connection to the FIRST hook that asks for that api —
+`useSubscription`, `useMutation`, `useAppClient`, any of them. A page that reads
+no data never opens a socket.
+
+Two measurements decide whether you want it. Both are from a real browser
+against a `voltro start`:
+
+- **`interactive: 'full'` is the default, and it connected regardless.** A
+  pre-rendered documentation page that subscribes to nothing opened a socket;
+  pages set to `interactive: 'none'` or `'islands'` opened none. So the pages
+  paying for a connection they never use are exactly the ordinary ones.
+- **An open socket keeps a dormancy-managed instance awake.** `isIdleNow`
+  returns false while `connectedClients() > 0` (see
+  [scale-to-zero](/docs/deployment/scale-to-zero)), so one browser tab left open
+  on a pricing page prevents scale-to-zero for as long as it stays open.
+
+`'eager'` remains the default because `'lazy'` moves WHEN a connection error
+surfaces — from page load to first data use — and an app that opens its socket
+for a side effect (a presence ping, an inspect stream) rather than through a data
+hook would notice the difference. If your app subscribes on every page, the two
+behave identically.
+
 ## See also
 
 - [Subscribers (`*.subscribe.ts`)](/docs/data/subscribers) — server-side, best-effort post-commit reactivity to a table (NOT the client hook on this page).
@@ -3988,7 +4020,7 @@ These helpers give you the secure **handler**, not schema derivation. Deriving t
 
 _Per-table post-commit reactivity via file convention. Default-exported defineSubscriber({ table, on, handler }) — fires AFTER commit, best-effort, fire-and-forget for async handlers._
 
-Use a `*.subscribe.ts` file when you want code to **run after every commit** to a specific table — refresh a search index, emit an external notification, invalidate a cache, push to a worker queue. The file convention is parallel to `*.startup.ts` / `*.cron.tsx` / `*.webhook.tsx`: drop a file matching the suffix anywhere under `apps/<api>/`, default-export a `defineSubscriber({...})`, the framework discovers + binds it at boot.
+Use a `*.subscribe.ts` file when you want code to **run after every commit** to a specific table — refresh a search index, invalidate a cache, push to a worker queue, emit an external notification. The handler runs on **every replica**; when its effect must not repeat, add [`once:`](#how-often-does-it-run-once-per-replica-unless-you-say-otherwise). The file convention is parallel to `*.startup.ts` / `*.cron.tsx` / `*.webhook.tsx`: drop a file matching the suffix anywhere under `apps/<api>/`, default-export a `defineSubscriber({...})`, the framework discovers + binds it at boot.
 
 Subscribers are deliberately **best-effort** + **non-durable**. For crash-safe async work — "a row changed, now run a workflow" — reach for a [reaction](/docs/data/reactions) instead.
 
@@ -4059,6 +4091,90 @@ The `on` filter narrows by operation:
 
 Other-table events get filtered out before your handler sees them. The matcher does this at the dispatcher level so subscribers add zero hot-path overhead to writes that don't match their table.
 
+## How often does it run? Once per replica — unless you say otherwise
+
+A subscriber binds to the change stream on **every api instance**. One `INSERT`
+behind three replicas calls your handler three times.
+
+That is the right default and not a gap. A handler that refreshes a per-process
+cache, warms a local index, or updates in-memory state *has* to run everywhere —
+a fleet-wide gate would leave every other replica stale. The default assumes the
+handler is **idempotent**.
+
+It is the wrong default for an **effect** — a notification, a mail, a webhook, a
+payment — because there is nothing to make idempotent: the effect IS a write, so
+each run produces another one. Three replicas send three mails.
+
+`once: true` is the whole answer for most handlers — the framework derives the
+key:
+
+```ts
+export default defineSubscriber({
+  table: 'absence_requests',
+  on:    ['insert'],
+  once:  true,          // exactly one replica runs the handler per change
+  handler: notifyApprovers,
+})
+```
+
+It names the change by its CONTENT plus its position among content-identical
+repeats. That is not a detail: a fleet change carries no LSN, no commit id and no
+`traceId` (the last one deliberately, so a local trace is never mis-attributed to
+a remote write), so content is the only thing two replicas provably agree on —
+and `A→B`, then `B→A`, then `A→B` again has to count as three changes, not two.
+
+Pass a **function** when you want to be COARSER than one-per-change: two updates
+that differ only in a field you do not care about are two changes to `once: true`
+and can be one to a key you write yourself.
+
+```ts
+// apps/api/subscribers/notifyApprovers.subscribe.ts
+export default defineSubscriber({
+  table: 'absence_requests',
+  on:    ['insert'],
+  // Cluster-wide: exactly one replica runs the handler for each change.
+  once:  (event) => String((event.new as { id?: string } | null)?.id ?? ''),
+  handler: async (event, ctx) => {
+    for (const approver of await approversOf(ctx, event.new)) {
+      await sendNotification(ctx, { toEmployeeId: approver.id })
+    }
+  },
+})
+```
+
+**A key you write must tell two genuine changes apart.** A row id is enough for
+`insert` and `delete`, where a row changes state once. It is not enough for
+`update`: two edits to the same row produce the same id, and the second would be
+dropped as a duplicate of the first — an effect that silently stops happening for
+a row that keeps changing. Put something that moves in the key, or use
+`once: true`:
+
+```ts
+once: (event) => {
+  const row = event.new as { id?: string; updatedAt?: Date } | null
+  return `${row?.id ?? ''}:${row?.updatedAt?.toISOString() ?? ''}`
+},
+```
+
+**`once` is AT MOST once, not exactly once.** The claim is taken before the
+handler runs, so a replica that wins and then dies takes the event with it, and a
+claim that cannot be written at all (database unreachable) is taken by nobody.
+Both are loud in the log and neither is retried — a subscriber is best-effort by
+construction. When the effect must not be lost, the change stream is the wrong
+seam: run it inside the mutation, or start a workflow from a
+[reaction](/docs/data/reactions), where durability is the primitive's job.
+
+The boot log says which one each subscriber got:
+
+```
+subscriber: registered table=absence_requests on=["insert"] once=fleet
+subscriber: registered table=posts on=["insert","update"] once=per-replica
+```
+
+Claims live in `_voltro_change_claims` and are swept after an hour
+(`VOLTRO_CHANGE_CLAIMS_TTL_HOURS`). The key is namespaced per subscriber file, so
+two subscribers watching one table never lock each other out.
+
 ## Semantics — best-effort, fire-and-forget
 
 Subscribers are **non-durable** by design:
@@ -4132,6 +4248,8 @@ export default defineSubscriber({
 export default defineSubscriber({
   table: 'organizations',
   on:    'insert',
+  // The POST is an effect: without `once` every replica sends one.
+  once:  (event) => String((event.new as { id?: string } | null)?.id ?? ''),
   handler: async (event, ctx) => {
     if (!event.new) return
     const slug = event.new.slug as string
@@ -4248,9 +4366,17 @@ into the agent's prompt.
 
 ## Guards (the point)
 
-- **`dedupeKey` (required)** — the same logical change acts exactly once. This is
-  what stops a reaction whose act writes the watched table from self-triggering
+- **`dedupeKey` (required)** — the same logical change acts exactly once, across
+  the whole fleet. The key is claimed in `_voltro_change_claims` before the act
+  runs (INSERT-wins on a UNIQUE — the same arbiter the cron scheduler uses), so
+  two replicas seeing one change start one workflow, not two. This is also what
+  stops a reaction whose act writes the watched table from self-triggering
   forever. `defineReaction` throws at boot if it's missing.
+
+  The claim is taken BEFORE the act, which is what makes it a gate rather than a
+  report — and the cost is stated rather than hidden: an act that THROWS has
+  already consumed its key and is not re-run by a later duplicate. Durability
+  belongs to the workflow the act starts, not to the trigger.
 - **`rateLimit` (optional)** — at most `limit` firings per `windowMs`.
 - **`costBudgetUsd` (optional)** — a per-tenant AI spend ceiling; over budget,
   the reaction refuses (fails closed).
@@ -4271,8 +4397,9 @@ into the agent's prompt.
 - Best-effort + fire-and-forget (like subscribers) — a failing act logs +
   continues; it can't back-pressure the change stream. Durability comes from a
   workflow act (an agent act is best-effort).
-- `dedupeKey` is in-memory per process in v1 (it stops the self-trigger storm
-  within a run); a durable cross-restart dedupe table is a follow-up.
+- `dedupeKey` claims survive a restart but not forever: `_voltro_change_claims`
+  is swept after an hour (`VOLTRO_CHANGE_CLAIMS_TTL_HOURS`). A change whose key
+  reappears after that window acts again.
 
 ## When to use what
 
@@ -4717,6 +4844,19 @@ available without a distributed transaction into the target system, so:
 **Handlers must be idempotent.** A process that dies between "the remote
 accepted it" and "we recorded that" will retry.
 
+**On several replicas, that used to be the smaller reason.** Every replica runs
+the drain, and the drain read every pending row — so an effect was dispatched
+once *per replica*, on the happy path, every time. It is claimed now: a row moves
+`pending → delivering` in one atomic statement stamped with the claiming
+process, so a racing replica loses the row rather than duplicating it, and a
+claim whose holder stops responding is returned to the queue after its lease
+(`claimLeaseMs`, default 5 minutes — raise it above your slowest handler).
+
+That removes the routine duplicate. It does not make delivery exactly-once, and
+nothing can: the process can still die between the remote accepting and the row
+being marked. The idempotency requirement stands — it is now about the failure
+case it was always meant to describe, rather than about every single delivery.
+
 ## Declaring the handler
 
 One `*.outbox.ts` file per effect:

package/templates/agent-docs/database/scaling.md

@@ -148,6 +148,13 @@ deployments (k8s with `replicas: 3`, multi-pod ECS, etc.) need a
 shared store, otherwise a write on instance A doesn't pin reads on
 instance B.
 
+**The boot says so now.** When replicas are configured and the RYW store falls
+back to memory on a deployment whose environment says several replicas
+(`POD_NAME`, `FLY_ALLOC_ID`, `K_REVISION`, … — or `REPLICA_COUNT`, which is a
+declaration in both directions), the boot warns and names the two ways out. It
+used to log `ryw policy 'fallback'` as though the policy were in force, and the
+first symptom was a user reloading and seeing their own save gone.
+
 Wire Redis:
 
 ```sh
@@ -306,6 +313,31 @@ The bus is **additive** to the inline emit path. Local reactivity must survive a
 
 Because the inline path is never removed, a broker outage degrades **cross-replica** fan-out only — local reactivity keeps working, and the framework logs a warning. The bus reconnects when the broker returns.
 
+## When the connection drops
+
+Every cross-replica mechanism here rides a connection, and a connection that dies quietly is worse than one that fails loudly: the app keeps serving, the clients keep their sockets, and their live queries simply stop updating. So each path is required to notice, recover, and then **say that it lost something**.
+
+**A hole is never patched — it is re-derived.** None of these transports keeps a log. Postgres queues nothing for a listener that is not there; Redis and NATS pub/sub retain nothing at all. So there is nothing to replay, and the only complete recovery is to re-run every live query. That is safe precisely because a live query is idempotent, and it is what the framework does on every one of the events below:
+
+| What happened | How it is noticed | What you see |
+|---|---|---|
+| The postgres `LISTEN` connection died (failover, proxy, `pg_terminate_backend`) | A heartbeat sent through the pool goes unanswered on the LISTEN stream | `cdc: reconnecting` → `cdc: reconnected`, then every live query refreshes |
+| A peer's serial jumped — the broker dropped messages | Per-origin serial accounting; the count is exact | `broadcast: missed N change(s) from …` |
+| This replica could not subscribe at boot (the broker was restarting) | The subscribe is retried in the background | `broadcast: could not subscribe` → `broadcast: subscribed`, then a refresh |
+| The Redis or NATS transport re-dialled underneath us | The driver's connection lifecycle | `broadcast: transport disconnected` → a refresh on reconnect |
+
+Two consequences worth knowing:
+
+- **A broker that is down at boot does not stop the boot.** The replica starts, serves, keeps local reactivity, and joins the bus when the broker returns. A crash loop across the whole fleet is the wrong answer to a broker restart — which is exactly when every replica is dialling at once.
+- **A replica that restarts under a stable name is recognised as a new process.** A StatefulSet pod keeps its `POD_NAME`, and `VOLTRO_REPLICA_ID` is stable by definition, so the name alone cannot tell a restart from a continuation. Each publish carries a per-process epoch so peers reset their watermark instead of quietly ignoring the new process's serials.
+
+The postgres heartbeat is idle-only: any traffic on the channel — including another replica's heartbeat — counts as proof the connection works, so a busy channel never pays for one and a fleet pays roughly one probe per idle window however many replicas it has. Tune it with:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `VOLTRO_CDC_HEARTBEAT_MS` | `20000` | Silence on the channel before a probe is sent |
+| `VOLTRO_CDC_HEARTBEAT_TIMEOUT_MS` | `10000` | How long an unanswered probe may go before the consumer is declared dead |
+
 ## The honest caveat — app-mutation changes only
 
 The bus carries changes that flow through **`ctx.store`** (the framework's mutation path). It does **not** capture **out-of-band DB writes** — a `psql` session, a cron job, or a second service writing the same database directly. Those changes never hit `store.onChange`, so they never reach the bus.
@@ -340,7 +372,14 @@ A changelog table that every replica polls (`SELECT … WHERE seq > :last`) woul
 will NOT reach clients on other replicas. Add @voltro/plugin-broadcast (Redis / NATS) to close the gap…
 ```
 
-When BOTH a native path and the broadcast plugin are wired (e.g. postgres + broadcast), both stay active — the own-origin skip dedups, so there's no double-emit. The native path is the primary; the bus is harmless redundancy.
+When BOTH a native path and the broadcast plugin are wired (e.g. postgres + broadcast), both stay active — and they carry **different things**. The native path carries table changes to every replica. The bus carries reactivity *channels* (`publishReactivity`), which are not database writes and so have no native transport at all.
+
+```
+[voltro:dev] reactivity: native LISTEN/NOTIFY (postgres) carries table changes;
+@voltro/plugin-broadcast (redis) carries reactivity channels
+```
+
+This page used to say the two paths were harmless redundancy because "the own-origin skip dedups". They were not. The own-origin skip only ever covered a replica's own publish coming back to itself — so a change the native transport had already delivered to every replica was re-published by every replica under *its own* origin, and each peer injected it again. N replicas turned one change into N² deliveries: every subscriber, every live-query wake, every plugin tap. At two replicas a `*.subscribe.ts` handler ran **four** times for one `INSERT`, twice per instance.
 
 ## sqlite and the memory store behind replicas