@voltro/cli 0.54.0 → 0.56.0

package/dist/{webhooksCommand-BvzXNHji.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-cKUiZZsB.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.54.0",
+  "version": "0.56.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -754,6 +754,54 @@
         "title": "WidgetKind gained 'array' and 'reference' — total widget registries need two new entries",
         "kind": "manual"
       },
+      {
+        "version": "0.55.0",
+        "id": "0.55.0/01_target-relations-declare-columns",
+        "title": "A target's `relations:` names the junction's two columns now, not just the table",
+        "kind": "manual"
+      },
+      {
+        "version": "0.55.0",
+        "id": "0.55.0/02_widget-kind-gained-rich-text",
+        "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",
@@ -836,24 +884,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.54.0",
-    "@voltro/cache": "0.54.0",
-    "@voltro/client": "0.54.0",
-    "@voltro/content": "0.54.0",
-    "@voltro/data-transfer": "0.54.0",
-    "@voltro/database": "0.54.0",
-    "@voltro/env": "0.54.0",
-    "@voltro/kv": "0.54.0",
-    "@voltro/logger": "0.54.0",
-    "@voltro/plugin-auth": "0.54.0",
-    "@voltro/plugin-broadcast": "0.54.0",
-    "@voltro/plugin-mail": "0.54.0",
-    "@voltro/plugin-storage": "0.54.0",
-    "@voltro/plugin-webhooks": "0.54.0",
-    "@voltro/protocol": "0.54.0",
-    "@voltro/runtime": "0.54.0",
-    "@voltro/serverless": "0.54.0",
-    "@voltro/workflow": "0.54.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.54.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.54.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/authentication.md

@@ -2617,10 +2617,14 @@ Optional, one line, and it buys back a feature the filter otherwise switches
 off for the whole app:
 
 ```ts
+const OWNED = new Set(['documents', 'comments'])
+
 setRowFilter({
   load,
-  predicate,
-  tables: ['bookmarks', 'recentSearches', 'todoSchedules', 'todoTags'],
+  predicate: (ctx, table) => (OWNED.has(table) ? eq('ownerId', ctx.userId) : undefined),
+  // Derived from the same set the predicate reads. Two hand-kept lists is the
+  // shape in which a table lands in exactly one of them.
+  tables: [...OWNED],
 })
 ```
 
@@ -2629,10 +2633,49 @@ is excluded for a subscription whose row set is re-resolved per delivery —
 replaying deltas could serve rows the subject has since lost. Without a
 declaration the framework cannot tell which tables your predicate may reach, so
 it excludes them all: one registration disables cheap reconnects for every
-subscription in the process. A deployment measured a filter over 4 tables
-costing it on all 173 of their query descriptors, 55 of whose source tables the
-filter never touches. With the declaration, only subscriptions on the listed
-tables are excluded.
+subscription in the process, including every one reading a table your predicate
+never returns anything for. With the declaration, only subscriptions on the
+listed tables are excluded.
+
+**What it does not buy, and this bounds the whole feature.** A subscription only
+has a delta chain when its executor returns a **descriptor**. One that returns a
+mapped value or a page envelope —
+
+```ts
+export default async ({ database }) => {
+  const rows = await database.notifications.where(...)
+  return { notifications: rows.map(toDto), hasMore: rows.length === 20 }
+}
+```
+
+— re-runs an opaque handler and emits snapshots, with or without a filter. So
+the count `tables:` gives back is the count of descriptor-returning
+subscriptions, not the number of queries in your app. Declare it anyway (it
+costs nothing, and it applies the moment such a query returns the builder), but
+measure before expecting a change.
+
+**How to see which of yours are which.** The two shapes are indistinguishable
+from the outside — a subscription that resumed and one that was never eligible
+both reconnect with rows on the screen. So the runtime records its own verdict
+at the moment it decides, per query label:
+
+```sh
+curl -s localhost:4000/_voltro/inspect/subscriptions | jq .resume
+```
+
+```json
+[
+  { "label": "documents.list", "resumable": 12, "excluded": {} },
+  { "label": "notifications.list", "resumable": 0, "excluded": { "computed": 8 } },
+  { "label": "comments.list", "resumable": 0, "excluded": { "row-filter": 3 } }
+]
+```
+
+A label appears once something has subscribed to it, so click through the app
+first. `computed` means no declaration can ever help that query; `row-filter`
+means the filter narrows its source and the exclusion is the point;
+`eager-load` means dropping the `.with(...)` would flip it. `voltro dev` also
+logs each verdict once per label under the `voltro:resume` scope.
 
 **Why a declaration and not a probe.** Resolving the scope at subscribe time
 and treating "returns `undefined` for this table" as safe is cheaper and

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:
@@ -2969,17 +3072,67 @@ the swap could not run: 2 row(s) in the bundle reference a row the bundle does n
   The target is UNCHANGED — the swap runs in one transaction and none of it committed.
 ```
 
-Staging tables from a run that died mid-load are collected by the next
-`replace` over the same tables. One over a DIFFERENT set leaves them, and
-nothing else removes them:
+### Staging tables a dead run left behind
+
+A staged run RECORDS the scratch tables it creates, in the same
+`_voltro_replace_in_progress` table an interrupted destructive `replace` writes
+to — with one difference that matters: **a staging record never refuses a boot.**
+Nothing was destroyed, so there is nothing to refuse over. The boot reports
+instead:
+
+```
+staged data-import leftovers:
+  - 3 staging table(s) from a `replace` over api, last active 74 minute(s) ago — DROPPED: the run
+    is not resumable and has been silent long enough that nothing is loading into them.
+  The target of a staged `replace` is untouched until one short swap at the end, so none of this is
+  a reason to refuse the boot — it is a reason to know the disk is holding a copy of a bundle.
+```
+
+The run refreshes a heartbeat on that record every couple of seconds while rows
+land, which is what lets a boot tell the three cases apart:
+
+| what the record says | what the boot does |
+|---|---|
+| silent past the threshold, started without `--no-atomic` | **drops** the tables it names |
+| still beating | leaves them — an import is loading into them right now, here or on another replica |
+| started `--no-atomic` | leaves them — its staging IS the resume point |
+
+The threshold is `30` minutes by default. It is deliberately generous: the cost
+of collecting too early is that an in-flight import's swap fails with a missing
+table and you re-run it — the target is untouched either way — but the cost is
+still a re-run.
+
+Declare a different one for a deployment whose imports routinely pause longer
+than that, waiting on an upstream export or a maintenance window:
+
+```ts
+// app.config.ts
+export default {
+  dataTransfer: {
+    stagingStaleMinutes: 90,
+  },
+}
+```
+
+`VOLTRO_STAGING_STALE_MINUTES` overrides the declaration in turn — an operator
+acting on a running deployment outranks what the project declared. Note that the
+threshold decides only what a boot DROPS: leftover staging tables are named in
+the boot log either way.
+
+What the boot does NOT collect, you can:
 
 ```bash
 voltro data clear-staging --yes
 ```
 
-Deliberately a command and not a boot sweep: a booting process cannot tell a
-leftover from a staging table another replica is loading into right now, and
-deleting the second would destroy an import in flight.
+It now labels each table with what its own run says, so a resume point is
+distinguishable from a leftover before you drop it:
+
+```
+2 staging table(s) from an earlier `--mode replace`:
+    _voltro_staging_tasks — RESUMABLE: a `--no-atomic` re-run continues from it, last active 4 min ago
+    _voltro_staging_notes — no run claims it (an orphan, or from before the marker)
+```
 
 A **cycle** in the bundle's foreign keys is detected before the load, not after
 it. The swap inserts parents first, so two tables referencing each other cannot
@@ -3562,7 +3715,14 @@ A native run reports **blobs**, not rows: the vendor tool reports no row count w
 
 ### The provenance stamp — a restore that refuses the wrong DB
 
-A native dump is opaque: it doesn't say which dialect made it, which schema shape it carries, or when. `backup` writes a sidecar `voltro-backup-stamp.json` next to the artifact recording exactly that — `dialect`, the live schema `fingerprint`, the `@voltro/cli` version, and the timestamp.
+A native dump is opaque: it doesn't say which dialect made it, which schema shape it carries, or when. `backup` writes a sidecar `voltro-backup-stamp.json` next to the artifact recording exactly that — `dialect`, the `@voltro/cli` version, the timestamp, and **two** schema fingerprints.
+
+Two, because they are different facts and only one of them is a claim about the artifact:
+
+- **`schemaFingerprint`** — the source database's whole live schema at backup time. This is what the skew warning below compares against a target.
+- **`dumpFingerprint`** — the schema the **artifact carries**: that same snapshot minus the tables the dump excludes. On postgres and the mysql family those are `_voltro_replace_in_progress` and `_voltro_data_transfers` (see above); on sqlite, turso and mssql nothing is excluded and the two values are equal.
+
+The distinction is not bookkeeping. `voltro data backup` opens its own run row in `_voltro_data_transfers` *before* it dumps, so on any database the framework has run against, the artifact is two tables short of the live schema it was taken from. Anything comparing a restored schema against a stamped one has to compare against `dumpFingerprint` — the drill did not, and failed every healthy backup with *"the artifact is inconsistent."*
 
 `restore` reads the stamp **before touching the DB** and acts on two failures that are otherwise silent until they corrupt:
 
@@ -3578,13 +3738,39 @@ voltro data restore ./backups/2026-07-01 --drill --drill-url postgres://…/scra
 # or set DRILL_DB_URL and just: voltro data restore ./backups/2026-07-01 --drill
 ```
 
-`--drill` restores the artifact into a **throwaway** database (from `--drill-url` / `DRILL_DB_URL`) and verifies it — **without ever touching the live DB**. It refuses a drill target that resolves to your live connection (a drill that `--clean`s production is the disaster it exists to rehearse against). After the restore it introspects the throwaway DB and compares its schema fingerprint to the backup's stamp:
+`--drill` restores the artifact into a **throwaway** database (from `--drill-url` / `DRILL_DB_URL`) and verifies it — **without ever touching the live DB**. It refuses a drill target that resolves to your live connection (a drill that `--clean`s production is the disaster it exists to rehearse against). After the restore it introspects the throwaway DB and probes its migration ledger:
 
 - **zero tables restored** → FAIL (the dump is empty or unreadable — this backup would not recover you),
-- **fingerprint disagrees with the stamp** → FAIL (the restore didn't reproduce what was backed up),
-- **tables + matching fingerprint** → PASS.
+- **schema fingerprint disagrees with the stamp's `dumpFingerprint`** → FAIL (the restore didn't reproduce what was backed up),
+- **`_voltro_migration_plans` restored EMPTY** → FAIL (see below),
+- **tables + matching fingerprint + a populated or absent ledger** → PASS.
+
+A stamp too old to carry a `dumpFingerprint` gives a **PASS (partial)** that says the shape could not be cross-checked. It does not fall back to `schemaFingerprint`: that is the comparison that fails a healthy backup, and a check that is red on every real input gets switched off — taking its genuine failures with it.
+
+It exits non-zero on any FAIL, so a scheduled CI job turns a silently-broken backup into a red build. Run it against your latest artifact on a cron — a backup you've never restored is a hypothesis, and this is how you keep it a fact.
+
+#### The ledger check — the one thing a schema comparison cannot see
+
+A fingerprint answers *"is the shape right?"*. A drill's real question is *"would my app come up against this?"*, and the gap between them is **content** — a framework table that restored with the right columns and the wrong rows.
 
-It exits non-zero on any FAIL, so a scheduled CI job turns a silently-broken backup into a red build. Run it against your latest artifact on a cron — a backup you've never restored is a hypothesis, and this is how you keep it a fact. (The verify is schema-level; a full app boot against the restored DB is a heavier check you can layer on top.)
+`voltro serve`'s boot gate reads the newest row of `_voltro_migration_plans` and refuses with `prod-mismatch` when there is none. So a ledger table that restores with exactly the right columns and **zero rows** is a database no source tree can boot, and its schema fingerprint is identical to a healthy one's. The drill fails that, and names it:
+
+```
+FAIL — restored 30 table(s) with the right shape, but `_voltro_migration_plans`
+       came back EMPTY.
+       `voltro serve` reads the newest row of that table as its boot gate and
+       refuses with `prod-mismatch` when there is none.
+```
+
+A restored database with **no ledger table at all** is not a voltro-managed schema (a hand-made dump, someone else's database) — the drill says so and claims nothing about booting it, rather than failing it.
+
+What the drill deliberately does **not** judge is a ledger whose fingerprint differs from what your code declares. It has no way to know which commit you will deploy next to this database, and `voltro db apply` clears that state anyway; failing a backup for it would make the drill red for a reason that is not about the backup.
+
+#### Why there is no full app boot
+
+Booting a real app against the restored database sounds like the stronger check, and it would be a weaker one. There is no app in the drill's path — it would have to boot a **fixture**, and a fixture booting says nothing about whether *your* app boots. It moves the drill from *"proves your backup"* to *"proves our fixture"* while reading as the bigger claim.
+
+The part worth having does not need a process: the boot gate is a comparison, not a startup sequence, so the one boot-fatal condition that holds regardless of which code you deploy is reachable with a `SELECT`. That is the ledger check above.
 
 ### Point-in-time recovery (PITR) is your database's job, not the framework's
 
@@ -4465,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.