@voltro/cli 0.45.0 → 0.46.0

package/dist/serveEntry.d.ts

@@ -36,3 +36,11 @@ declare module '@voltro/protocol' {
         '_voltro_undo_log': true;
     }
 }
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'invoices': true;
+        'invoice_lines': true;
+    }
+}

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
 import { t as e } from "./loadEnv-D9nEOClM.js";
 import { r as t } from "./appModuleLoader-C9r9mxZt.js";
 import { i as n } from "./dialectDriver-czCHYpeH.js";
-import { t as r } from "./serveCommand-BBhT2U94.js";
+import { t as r } from "./serveCommand-CHOr74WM.js";
 export { e as loadDotEnv, t as registerAppModules, n as registerDriver, r as runServe };

package/dist/{start-Ds3xyn8R.js → start-7HcSIKEp.js}

@@ -1,6 +1,6 @@
 import { i as e, t } from "./nodeEnvironment-cGFAj1J8.js";
 import { r as n } from "./appPort-B_HpJ_ck.js";
-import { A as r, C as i, D as a, E as o, F as s, H as c, I as l, J as ee, L as u, M as d, N as f, O as te, P as p, R as m, S as h, T as ne, V as g, W as re, X as _, Y as v, Z as y, a as b, b as x, d as S, f as C, ht as w, i as ie, j as T, k as E, n as D, nt as O, q as k, s as ae, tt as A, vt as j, x as oe, y as M, z as se } from "./webDev-101csg6Q.js";
+import { A as r, C as i, D as a, E as o, F as s, H as c, I as l, J as ee, L as u, M as d, N as f, O as te, P as p, R as m, S as h, T as ne, V as g, W as re, X as _, Y as v, Z as y, a as b, b as x, d as S, f as C, ht as w, i as ie, j as T, k as E, n as D, nt as O, q as k, s as ae, tt as A, vt as j, x as oe, y as M, z as se } from "./webDev-B4IEMB0n.js";
 import { o as N, t as P } from "./connectionConfig-Bk9IC7D0.js";
 import { A as F, D as I, a as ce, h as le, j as ue, k as de } from "./inspect-B7U7Cl_Z.js";
 import { a as fe, c as L, d as pe, f as R, l as me, p as he, u as ge } from "./renderModeScan-D7J1B7Kw.js";

package/dist/{start-BAlGcjF5.js → start-DvlYDyAr.js}

@@ -1,3 +1,3 @@
 import "./renderModeScan-D7J1B7Kw.js";
-import { t as e } from "./start-Ds3xyn8R.js";
+import { t as e } from "./start-7HcSIKEp.js";
 export { e as runStartCommand };

package/dist/startEntry.d.ts

@@ -19,3 +19,11 @@ declare module '@voltro/protocol' {
         '_voltro_undo_log': true;
     }
 }
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'invoices': true;
+        'invoice_lines': true;
+    }
+}

package/dist/startEntry.js

@@ -1,3 +1,3 @@
 import { t as e } from "./loadEnv-D9nEOClM.js";
-import { t } from "./start-Ds3xyn8R.js";
+import { t } from "./start-7HcSIKEp.js";
 export { e as loadDotEnv, t as runStartCommand };

package/dist/startup.d.ts

@@ -79,3 +79,11 @@ declare module '@voltro/protocol' {
         '_voltro_undo_log': true;
     }
 }
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'invoices': true;
+        'invoice_lines': true;
+    }
+}

package/dist/{updateCommand-rCnhaj84.js → updateCommand-BlyXavoG.js}

@@ -1,4 +1,4 @@
-import { n as e, r as t, t as n } from "./codemodRunner-5ZhDH3rB.js";
+import { n as e, r as t, t as n } from "./codemodRunner-DSZjgyCL.js";
 import { basename as r, dirname as i, join as a, relative as o, resolve as s } from "node:path";
 import { existsSync as c, readFileSync as l, readdirSync as u, statSync as d, writeFileSync as f } from "node:fs";
 import { totalmem as p } from "node:os";

package/dist/updateCommand-CT5AvVg7.js

@@ -0,0 +1,2 @@
+import { f as e, p as t } from "./updateCommand-BlyXavoG.js";
+export { e as runApplyCodemods, t as runUpdateCommand };

package/dist/{webDev-101csg6Q.js → webDev-B4IEMB0n.js}

@@ -14,8 +14,8 @@ import { existsSync as j, promises as M, readFileSync as N, readdirSync as P, st
 import { fileURLToPath as te, pathToFileURL as L } from "node:url";
 import { addSink as R, createLogger as z, printReadyBlock as ne } from "@voltro/logger";
 import { createRequire as B } from "node:module";
-import { homedir as V } from "node:os";
-import { currentTraceContext as re, resolveSecret as H } from "@voltro/runtime";
+import { currentTraceContext as V, resolveSecret as re } from "@voltro/runtime";
+import { homedir as H } from "node:os";
 import { FRAMEWORK_ENV_CATALOG as U, appEnvEntries as ie, checkEnvNaming as W, formatEnvErrors as ae, installEnvSnapshot as G, isEnvContract as oe, pluginEnvEntries as se, renderDotEnvExample as ce, resolveEnv as le } from "@voltro/env";
 import { __installPublicEnv as ue } from "@voltro/env/public";
 import { mkdir as de, writeFile as fe } from "node:fs/promises";
@@ -68,7 +68,7 @@ __installPublicEnv(publicEnvValues)
 }, Ce = async (e) => {
 	let t = oe(e.rawEnv) ? e.rawEnv : void 0, n = await le({
 		contract: t,
-		resolveSecret: H
+		resolveSecret: re
 	}), r = [...n.errors, ...W(t, e.appType)];
 	if (r.length > 0) throw Error(ae(r));
 	G(n.values), e.appType === "web" && ue(n.publicValues);
@@ -780,7 +780,7 @@ __installPublicEnv(publicEnvValues)
 		if (zt(t[i], a), !r) {
 			r = !0;
 			try {
-				let t = a.length > 0 ? It(a[0]) : "", r = t.length > 500 ? t.slice(0, 500) + "…" : t, o = re();
+				let t = a.length > 0 ? It(a[0]) : "", r = t.length > 500 ? t.slice(0, 500) + "…" : t, o = V();
 				e.emit("log", {
 					level: i,
 					message: r,
@@ -818,7 +818,7 @@ __installPublicEnv(publicEnvValues)
 					argsCount: 1,
 					...t.scope === void 0 ? {} : { scope: t.scope }
 				});
-				let a = re(), o = a !== void 0 && t.fields.traceId === void 0 ? {
+				let a = V(), o = a !== void 0 && t.fields.traceId === void 0 ? {
 					...t.fields,
 					traceId: a.traceId
 				} : t.fields;
@@ -1190,7 +1190,7 @@ import {
 		a || (a = !0, i.destroy(), r(e));
 	};
 	i.once("connect", () => o(!0)), i.once("error", () => o(!1)), setTimeout(() => o(!1), n);
-}), Dn = () => !!(process.env.VOLTRO_DASHBOARD === "off" || process.argv.includes("--disable-dashboard")), On = () => process.env[Tn] === "1", kn = () => process.stdout.isTTY === !0, An = O(V(), ".voltro", "dashboard-launch.lock"), jn = 1e4, Mn = async () => {
+}), Dn = () => !!(process.env.VOLTRO_DASHBOARD === "off" || process.argv.includes("--disable-dashboard")), On = () => process.env[Tn] === "1", kn = () => process.stdout.isTTY === !0, An = O(H(), ".voltro", "dashboard-launch.lock"), jn = 1e4, Mn = async () => {
 	try {
 		await M.mkdir(D(An), { recursive: !0 });
 		let e = await M.open(An, "wx");

package/dist/webDev-B79ji8M5.js

@@ -0,0 +1,2 @@
+import { _ as e, y as t } from "./webDev-B4IEMB0n.js";
+export { e as tryRunWebServe, t as walkPagesTree };

package/dist/{webhooksCommand-C0iZZfaI.js → webhooksCommand-BRrG_sGf.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-P4HyeY9W.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-DyoYst4j.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -646,6 +646,12 @@
         "title": "`source:` is typechecked against the app’s tables, from the next `voltro dev`",
         "kind": "manual"
       },
+      {
+        "version": "0.46.0",
+        "id": "0.46.0/01_typed-aggregate-source",
+        "title": "an aggregate’s `incremental.source` is typechecked against the app’s tables",
+        "kind": "manual"
+      },
       {
         "version": "0.5.0",
         "id": "0.5.0/01_one-terminal-exactly-one",
@@ -733,22 +739,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.45.0",
-    "@voltro/cache": "0.45.0",
-    "@voltro/data-transfer": "0.45.0",
-    "@voltro/database": "0.45.0",
-    "@voltro/env": "0.45.0",
-    "@voltro/kv": "0.45.0",
-    "@voltro/logger": "0.45.0",
-    "@voltro/plugin-auth": "0.45.0",
-    "@voltro/plugin-broadcast": "0.45.0",
-    "@voltro/plugin-mail": "0.45.0",
-    "@voltro/plugin-storage": "0.45.0",
-    "@voltro/plugin-webhooks": "0.45.0",
-    "@voltro/protocol": "0.45.0",
-    "@voltro/runtime": "0.45.0",
-    "@voltro/serverless": "0.45.0",
-    "@voltro/workflow": "0.45.0",
+    "@voltro/ai": "0.46.0",
+    "@voltro/cache": "0.46.0",
+    "@voltro/data-transfer": "0.46.0",
+    "@voltro/database": "0.46.0",
+    "@voltro/env": "0.46.0",
+    "@voltro/kv": "0.46.0",
+    "@voltro/logger": "0.46.0",
+    "@voltro/plugin-auth": "0.46.0",
+    "@voltro/plugin-broadcast": "0.46.0",
+    "@voltro/plugin-mail": "0.46.0",
+    "@voltro/plugin-storage": "0.46.0",
+    "@voltro/plugin-webhooks": "0.46.0",
+    "@voltro/protocol": "0.46.0",
+    "@voltro/runtime": "0.46.0",
+    "@voltro/serverless": "0.46.0",
+    "@voltro/workflow": "0.46.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -707,7 +707,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.45.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.46.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.45.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.46.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/cli.md

@@ -2610,11 +2610,25 @@ Rows are written as newline-delimited JSON — streamable, resumable by line, an
 
 | Flag | Selects |
 |---|---|
-| *(none)* | Every table (the default). |
+| *(none)* | Every table the app has DATA in (the default) — see the note below on the handful that describe a deployment rather than filling it. |
 | `--tenant <id>` | Every `tenant()`-scoped table filtered to that tenant, **plus** the FK closure in BOTH directions: (1) the transitive **FK-parent** closure of those rows — closure-pulled shared tables (a global `users` / reference table) are **row-subset to the ids the tenant's rows actually reference**, never exported in full; and (2) the **child** closure — rows that *reference* the tenant's rows (the comments on the tenant's projects) come along too, each scoped to the ids that actually point into the tenant set. The child walk is anchored on the `tenant()` tables, so a row that references **only a shared parent** (a global `users` another tenant also references) is **not** pulled — that would be a cross-tenant leak. A `--tenant` bundle therefore carries the tenant's parents AND children and **no other tenant's rows** — that's what makes it safe as a GDPR / per-tenant takeout. |
 | `--tables a,b` | An explicit set (you own referential integrity; the importer's deferred-FK resolution covers load-order dangles, see below). |
 | `--exclude a,b` | Everything EXCEPT these, expanded against the live table list. Direct target only. Cannot be combined with `--tables` or `--tenant`; a name that does not exist is refused, because an exclusion that excludes nothing leaves the run looking like it worked. |
 
+#### What `all` deliberately leaves out
+
+A few framework tables hold rows **about a deployment** rather than an app's data — its migration ledger, its file-migration and seed records, its CDC offsets, its schedule claims and wakeups, its workflow watermarks / pending starts / admissions / pauses. They are dropped from `all`, skipped on import, and never emptied by a `replace`, and the run says which ones and why.
+
+The reason is worth one paragraph, because it cost a real environment ninety minutes. A `scope: all` bundle carried `_voltro_migration_plans`, `replace` wrote it, and the target's next boot refused:
+
+```
+auto-migrate: SCHEMA FINGERPRINT MISMATCH — declared=6e2c61081a9ed80c  live=28af9a54414f22f1
+```
+
+The refusal was right. That fingerprint is computed over the **declared table set**, which legitimately differs per environment — `NODE_ENV=production` declares `_voltro_traces` and `_voltro_undo_log`, a `development` run does not. So the imported row was not out of date, it was **foreign**: it stated a schema decision made somewhere else. Two of the others would have made the target *act* — a pending workflow start runs a workflow somebody queued elsewhere, a pause silently stops one here.
+
+`all` is the only scope filtered. **Name one of these in `--tables` and you get it** — an explicit name is an expectation, and this command refuses to drop those silently.
+
 **Every table needs a single-column primary key.** The export is keyset-paginated, so it orders by one column and resumes from the last value on the next page. That column comes from the real primary key — a declared `id()` where there is one, otherwise the table's actual PK, whatever it is called.
 
 A table with a **composite** primary key, or none at all, is **refused by name** rather than exported. Ordering by one column of a composite key splits equal values across page boundaries, which drops or duplicates rows into a bundle that reports success — and a short backup is discovered at the restore. Leave such a table out with `--exclude`.
@@ -2753,6 +2767,128 @@ returns **`409` schema drift** with the fingerprints + diff; `--force` sends
 
 The pre-flight only runs when the importer has a target schema (the CLI introspects it; the API endpoint uses the instance's declared schema). Importing into a fresh/empty database with no comparable schema simply skips the check.
 
+### `replace` writes down what it is about to destroy
+
+Before the first delete, a `replace` exports the target's **current** rows for exactly the tables it is going to empty, as an ordinary bundle beside yours:
+
+```
+rollback capture: 240172 row(s) across 75 table(s) → ./out.rollback-2026-08-21T09-10-11-000Z
+  If this run does not finish, restore with:  voltro data import ./out.rollback-… --mode replace
+```
+
+It is on disk **before** anything is destroyed, so it does not depend on a transaction, or on the process being alive to roll one back. That distinction is the whole reason it exists: a deployment lost 240 172 rows to a `replace` whose api pod disappeared nine minutes in, and recovered from an export they had taken twenty minutes earlier out of habit. This is that habit, made into the tool's behaviour.
+
+**It is fail-closed.** A capture that cannot be taken stops the import before it starts, and the target is untouched. A safety net you believe in and do not have is worse than none — the belief is what stops you taking your own export.
+
+`--no-rollback` turns it off, and `--rollback-dir <path>` puts it somewhere else. It is only taken for `replace`: `upsert` and `append` do not destroy, so there is no moment where the old state has silently become unreachable.
+
+**Over `--target api` it goes to the instance's object storage**, because there the process that would roll a transaction back IS the instance — a capture in the pod's filesystem would go away with the failure it exists for. Name a key:
+
+```bash
+voltro data import ./out --target api --api-url <url> --token $SECRET --mode replace --rollback-key backups/before.vbundle
+```
+
+The instance writes the capture there **before the first delete**, and refuses the run (409) if it has no storage configured — asking for a capture and being served without one is the answer that removes your own precaution while looking like agreement. A `replace` that names no key still runs, and says what it did not keep.
+
+### `replace` loads somewhere else first
+
+The target keeps its rows until the load stands. `replace` creates a staging
+table per table, loads the bundle into those, and then swaps the CONTENT across
+in one short transaction of server-side SQL. It says so when it does:
+
+```
+staging 114 table(s) before the swap — the target keeps its rows until the load stands.
+  The destructive step is one server-side transaction at the end, not the whole load.
+```
+
+The difference is what a dead process costs. Loading straight into the target
+holds the destructive transaction open for the whole load — minutes, for a large
+bundle — and the target only survives because the database rolls that
+transaction back. With staging, a process that dies during the load leaves the
+target exactly as it was, because nothing has been deleted yet.
+
+Not every run can take it, and a run that cannot **says why** rather than quietly
+taking the slower path:
+
+- a store the framework cannot send DDL to (the in-memory store).
+- a **write recorder** on any table in the set — `versioningPlugin({ timing:
+  'in-transaction' })` and friends. A recorder is keyed by table name, so a
+  staged write would find none and the recorder would silently not run. Its
+  promise is "if the change committed, the entry is there", so the run keeps the
+  path that can keep it.
+
+**`--no-atomic` stages too, and that is where it changes the most.** The flag
+exists for resumability on a large bundle, and it used to be the mode with the
+worst failure: the target emptied and partially refilled, in neither state.
+Staged, the ledger keeps its exact meaning — a recorded table is one fully
+loaded, it just lands in staging — while the target stays untouched until the
+swap. Resumable and all-or-nothing at once, which the two could not be before.
+
+A resumed run continues from what it already staged rather than reloading it,
+and a run whose swap has not happened keeps its staged rows and says so:
+
+```
+the staged rows are KEPT so a re-run can continue from them rather than reload.
+  If you are not going to re-run this bundle, drop them: voltro data clear-staging --yes
+```
+
+**A failed swap names every offending row, not the first.** Staging carries no
+foreign keys — a staged row whose parent has not been staged yet must not be
+refused — so a dangling reference surfaces at the swap, where the database
+reports one constraint. The importer then asks staging the same question and
+lists every row that fails it:
+
+```
+the swap could not run: 2 row(s) in the bundle reference a row the bundle does not carry.
+    tasks.t_41: ownerId = "u_9" — no such row in users
+    tasks.t_88: ownerId = "u_12" — no such row in users
+  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:
+
+```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.
+
+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
+both be satisfied by a bulk copy on postgres, sqlite or SQL Server — `SET
+CONSTRAINTS ALL DEFERRED` does not help, because postgres only defers a
+constraint declared `DEFERRABLE`. Such a run says so and takes the row-by-row
+path, whose deferred-FK pass exists for exactly that shape. A table referencing
+ITSELF is not a cycle: one statement carries the whole table.
+
+### An interrupted `replace` cannot be silent
+
+The capture only helps if somebody knows to reach for it. A half-replaced database is indistinguishable from an empty one **from the inside** — every table exists, every constraint holds, every query returns nothing without erroring — so a run that emptied a target and disappeared can be served over for hours before anyone asks the right question.
+
+So a `replace` writes one row before the first delete and removes it after the last insert. Finding it at boot is a **refusal**, not a warning:
+
+```
+refusing to start: a destructive import did not finish.
+  - a `replace` over api began emptying 114 table(s) 12 minute(s) ago and never reported finishing.
+    The target's previous rows were captured first:
+      ./out.rollback-2026-08-21T09-10-11-000Z
+    Restore them with:  voltro data import ./out.rollback-… --mode replace
+```
+
+The row lives in the same transaction as the emptying, so it is present **exactly when the emptying is**: a run that rolls back cleanly takes the marker with it, and a boot over a database nothing happened to is not refused. A completed `replace` clears its own marker and any older one — so the recovery import both restores the data and silences the alarm, in one command.
+
+Nothing expires. A half-replaced database does not become whole with time, so clearing it is a decision:
+
+```bash
+voltro data clear-replace-marker --yes
+```
+
+The devtools import panel takes the same two precautions as the command line — a capture before the first delete, and the marker — because a button is easier to press than a command is to type.
+
 ### Deferred-FK resolution
 
 A row whose write fails on a foreign-key constraint — a forward reference from a `live`-consistency export, a genuine FK **cycle** between tables (which the exporter orders by breaking the closing edge), or an intra-table self-reference to a later row — does **not** fail the import. It is held and resolved after every table has streamed:
@@ -2803,7 +2939,7 @@ Unlike the rpc wire, this string DOES include the driver's own words. The audien
 |---|---|---|---|
 | `upsert` (default) | INSERT-or-UPDATE by primary key | sync / idempotent re-import | overwrites per row |
 | `append` | INSERT only | additive data (event log, new seed) | `--on-conflict skip` (default) or `fail` |
-| `replace` | empty the target tables, then INSERT | full refresh — target ends up **exactly** the bundle | — |
+| `replace` | capture the target, empty it, then INSERT | full refresh — target ends up **exactly** the bundle | — |
 
 `replace` **refuses a partial bundle** (a subset / tenant / table scope): emptying would delete rows the bundle never carried. Re-export with full scope, or use `upsert`. (`append --on-conflict fail` throws on a duplicate primary key only where the store enforces the constraint — every SQL dialect does; the in-memory dev store overwrites.)
 

package/templates/agent-docs/data.md

@@ -397,10 +397,59 @@ changes. **That is an authorization staleness, not a cosmetic one:** revoke
 someone's membership and their open subscription keeps serving rows they may no
 longer see, until something else happens to invalidate it.
 
-Nothing warns about this at runtime — a query that silently stops reacting looks
-exactly like one with nothing to report. Reported by a team whose own invariant
-caught it after five computed queries under-declared their `source`; the fix was
-array sources.
+Reported by a team whose own invariant caught it after five computed queries
+under-declared their `source`; the fix was array sources.
+
+### `voltro dev` now says when a query reads a table it did not declare
+
+That paragraph used to end "nothing warns about this at runtime". It does now.
+
+While `voltro dev` is running, every read a query makes is attributed to it and
+compared against its own `source:`. Read a table you did not declare and the
+terminal says so, once:
+
+```
+source: tasks.list: read `task_sub_tasks` without declaring it in `source:`.
+  A write to that table will not re-run this query, so an open view keeps
+  showing what it showed before. The write itself is fine, which is why nothing
+  else reports this.
+```
+
+It is deliberately narrow, and knowing where its edges are is the difference
+between acting on it and learning to skim it:
+
+- **It reports what it SAW.** A branch that did not run contributes nothing, so
+  it never claims your `source:` is otherwise complete — only that a table it
+  watched you read is missing from it.
+- **Once per query per boot.** A per-request warning on a hot list would be its
+  own outage.
+- **A query with no `source:` at all is left alone.** It has made no claim; the
+  finding is about an incomplete list, not a missing one.
+- **An eager-loaded relation COUNTS**, and it is the case worth knowing about.
+  `.with({ subTasks: true })` issues no second read — the whole spec folds into
+  one round trip — so the loaded table never appears as a read of its own. The
+  recorder resolves it through the relation registry instead, target and (for a
+  many-to-many) junction alike. A write to the junction changes membership,
+  which is exactly the change a user makes.
+- **A table read only to NARROW a result is not counted** — a parent reached
+  through `inSubquery(...)`, or a read the framework made to resolve your row
+  filter. Those decide which rows come back rather than contributing rows, and
+  putting every one of them in `source:` would re-run every list on every
+  membership write.
+
+That last rule is a judgement the recorder makes for the common case and
+deliberately does not make for yours. The section above is the case where you
+want a restricting read in `source:` anyway — an authorization read whose
+staleness you care about. The recorder will not nag you into it and will not
+argue when you add it.
+
+**Dev only.** `voltro serve` installs none of it — it costs a wrapper per read,
+and a production log is not where this gets read. `VOLTRO_SOURCE_RECORDER=off`
+turns it off in dev.
+
+If your own helper resolves access somewhere the framework does not call it, wrap
+it in `restrictingReads` (from `@voltro/runtime`) and its reads stop counting —
+inside or outside a recording session, so it is safe to leave in place.
 
 ## `output` is the serializer — `timestampMs`
 
@@ -3168,6 +3217,23 @@ When a shape can't be incremental, leave `incremental` off and use a refresh
 policy — the engine recomputes. Incremental is an optimisation for hot, bounded
 aggregates, not a different result.
 
+### `source` is a table name, and it is checked
+
+`incremental.source` is typed against your app's own tables — the same
+`TableName` a query's `source:` uses — so a misspelled or renamed-away name is a
+compile error from your next `voltro dev`.
+
+That check exists because the failure has no other symptom. A source matching no
+table does not error: the runner subscribes to something nothing writes, no delta
+ever arrives, and the aggregate quietly stops tracking its input while every read
+of it still succeeds and still returns a number.
+
+The boot says it too. An aggregate whose CDC source resolves to no live table is
+named in the same stale-`source:` warning queries and streams appear in, on both
+boot paths — a name can be correct at the type level and still be a table this
+deployment does not have. An aggregate with no `incremental` block declares no
+source and is not audited.
+
 ## Boot strategy
 
 Each aggregate declares `bootRefresh` (default `'persistent'`). All three modes are wired in the aggregate runner (`attachAggregates`):