@voltro/cli 0.44.0 → 0.45.0

package/dist/serveCommand-DY2jLy0o.js

@@ -0,0 +1,2 @@
+import { n as e } from "./serveCommand-BBhT2U94.js";
+export { e as runServeDispatch };

package/dist/serveEntry.d.ts

@@ -20,3 +20,19 @@ export declare const registerDriver: (spec: string, mod: Record<string, unknown>
 export declare const runServe: (args: ReadonlyArray<string>) => Promise<number>;
 
 export { }
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'tasks': true;
+        'task_sub_tasks': true;
+        '_voltro_workflow_runs': true;
+        '_voltro_workflow_run_steps': true;
+        '_voltro_workflow_run_events': true;
+        '_voltro_workflow_events': true;
+        '_voltro_workflow_event_deliveries': true;
+        '_voltro_approvals': true;
+        '_voltro_connections': true;
+        '_voltro_undo_log': 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-BlnAlNQg.js";
+import { t as r } from "./serveCommand-BBhT2U94.js";
 export { e as loadDotEnv, t as registerAppModules, n as registerDriver, r as runServe };

package/dist/startEntry.d.ts

@@ -3,3 +3,19 @@ export declare const loadDotEnv: (argv: ReadonlyArray<string>) => void;
 export declare const runStartCommand: (args: ReadonlyArray<string>) => Promise<number>;
 
 export { }
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'tasks': true;
+        'task_sub_tasks': true;
+        '_voltro_workflow_runs': true;
+        '_voltro_workflow_run_steps': true;
+        '_voltro_workflow_run_events': true;
+        '_voltro_workflow_events': true;
+        '_voltro_workflow_event_deliveries': true;
+        '_voltro_approvals': true;
+        '_voltro_connections': true;
+        '_voltro_undo_log': true;
+    }
+}

package/dist/startup.d.ts

@@ -63,3 +63,19 @@ export declare interface StartupHandle {
 export declare const startupTimeoutMsFromEnv: (envValue: string | undefined) => number;
 
 export { }
+
+
+declare module '@voltro/protocol' {
+    interface VoltroTableNames {
+        'tasks': true;
+        'task_sub_tasks': true;
+        '_voltro_workflow_runs': true;
+        '_voltro_workflow_run_steps': true;
+        '_voltro_workflow_run_events': true;
+        '_voltro_workflow_events': true;
+        '_voltro_workflow_event_deliveries': true;
+        '_voltro_approvals': true;
+        '_voltro_connections': true;
+        '_voltro_undo_log': true;
+    }
+}

package/dist/{test-CLYXrZ2F.js → test-CHb7UwvE.js}

@@ -79,7 +79,7 @@ var d = l({ scope: "voltro:test" }), f = (e) => {
 }, C = async (e) => {
 	let t = m(e);
 	if (!o(t.root)) return console.error(`voltro test: no such directory: ${t.root}`), 1;
-	let { checkRpcGroupFreshness: n } = await import("./codegen-i8QGcHsi.js"), r = await n(t.root);
+	let { checkRpcGroupFreshness: n } = await import("./codegen-DcE2li1i.js"), r = await n(t.root);
 	if (r.kind === "stale") return console.error(`voltro test: ${r.file} is stale — ${r.reason}.`), console.error("  The tests would run against the previously generated procedure group, pass, and prove nothing about the descriptors you just edited.\n  Run `voltro codegen` (or boot `voltro dev` once) and try again."), 1;
 	d.info("running vitest", {
 		root: t.root,

package/dist/updateCommand-BH6EGuCc.js

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

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

@@ -1,4 +1,4 @@
-import { n as e, r as t, t as n } from "./codemodRunner-BKTnaGOz.js";
+import { n as e, r as t, t as n } from "./codemodRunner-5ZhDH3rB.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/{webhooksCommand-BfO_JF2b.js → webhooksCommand-C0iZZfaI.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-BZO5aLdr.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-P4HyeY9W.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.44.0",
+  "version": "0.45.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -640,6 +640,12 @@
         "title": "`runImport` returns an ImportOutcome — read `.manifest` for the bundle",
         "kind": "manual"
       },
+      {
+        "version": "0.45.0",
+        "id": "0.45.0/01_typed-source-table-name",
+        "title": "`source:` is typechecked against the app’s tables, from the next `voltro dev`",
+        "kind": "manual"
+      },
       {
         "version": "0.5.0",
         "id": "0.5.0/01_one-terminal-exactly-one",
@@ -727,22 +733,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.44.0",
-    "@voltro/cache": "0.44.0",
-    "@voltro/data-transfer": "0.44.0",
-    "@voltro/database": "0.44.0",
-    "@voltro/env": "0.44.0",
-    "@voltro/kv": "0.44.0",
-    "@voltro/logger": "0.44.0",
-    "@voltro/plugin-auth": "0.44.0",
-    "@voltro/plugin-broadcast": "0.44.0",
-    "@voltro/plugin-mail": "0.44.0",
-    "@voltro/plugin-storage": "0.44.0",
-    "@voltro/plugin-webhooks": "0.44.0",
-    "@voltro/protocol": "0.44.0",
-    "@voltro/runtime": "0.44.0",
-    "@voltro/serverless": "0.44.0",
-    "@voltro/workflow": "0.44.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",
     "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.44.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.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. |
 | 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.44.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.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. |
 | 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

@@ -1377,6 +1377,22 @@ Docker step) and prints the exact remedy: add a `voltro build .` step before
 `voltro serve .`. Drop it into your image build right after `voltro build` to
 guarantee the artefact is present before the image ships.
 
+### Relations a query loads but does not declare
+
+An eager-loaded relation is part of the RESULT, so its table has to be in `source:` or the view stops updating when it changes:
+
+```
+✗  1 query loads a relation it does not declare:
+   tasks.getById: eager-loads `subTasks` from 'tasks' but does not declare
+   'task_sub_tasks' in `source:` — the view will not update when 'task_sub_tasks' changes.
+```
+
+This is the failure that looks like a broken feature and is not: the write lands, a reload shows it, and every test of the write path is green. The name in `source:` is spelled right and the table exists, so neither the typed `source:` nor the boot audit has anything to say.
+
+The rule has no exception list, deliberately. It resolves `.with({ … })` keys through the relation registry, so the missing table is a fact rather than an inference — and a **many-to-many** is reported twice when needed, because the junction table is where a link add/remove actually writes.
+
+It reads what it can read literally: a computed `.with()` key yields nothing rather than a guess.
+
 ### The access-decision gate
 
 Before the authz scan below — which is a heuristic over executor SOURCE — doctor
@@ -2607,7 +2623,7 @@ Tenant-scope details:
 
 - **A tenant scope without a tenant id refuses loudly** (`ScopeError`): pass `--tenant <id>` (CLI) or `scope.tenantId` (API/profile). It never falls back to an unfiltered export.
 - **Which tables count as tenant-scoped** comes from the `tenant()` mixin metadata when the CLI / admin endpoint can read the declared schema (authoritative — a table can carry a `tenantId` column *without* being tenant-scoped, e.g. a global `users` table's active-org pointer). Without that metadata the exporter falls back to a documented heuristic: any table with a `tenantId` column.
-- A **cross-tenant reference** (a tenant-A row pointing at a tenant-B row) is never followed — the bundle stays tenant-clean and the reference dangles; importing such a bundle reports it loudly (`DanglingReferenceError`) unless the target already has the row.
+- A **cross-tenant reference** (a tenant-A row pointing at a tenant-B row) is never followed — the bundle stays tenant-clean and the reference dangles; importing such a bundle reports it loudly (`RowsRefusedError`) unless the target already has the row.
 
 ### Consistency: `live` vs `snapshot`
 
@@ -2745,7 +2761,41 @@ A row whose write fails on a foreign-key constraint — a forward reference from
 2. **FK-shedding** — rows still stuck are written with their FK-bearing columns set to `NULL` (possible wherever those columns are nullable), which breaks row cycles on every dialect without session-level constraint toggles.
 3. **Patch pass** — shed rows are re-written with the full bundle row, restoring the FK values.
 
-Anything still unresolvable — the parent row exists in **neither the bundle nor the target**, or a `NOT NULL` FK cycle — fails with a typed `DanglingReferenceError` naming each offending table + primary key + the database's own reason. Held rows are the exception set, not the data set: memory is bounded by how many rows dangle at load time.
+Anything still unresolvable — the parent row exists in **neither the bundle nor the target**, a `NOT NULL` FK cycle, or a row the target refuses for a reason of its own — fails with a typed `RowsRefusedError`. Held rows are the exception set, not the data set: memory is bounded by how many rows dangle at load time.
+
+#### Reading a refusal
+
+The error carries three things, and they answer different questions:
+
+| Field | What it is |
+|---|---|
+| `totalCount` / `primaryCount` | how many rows were refused, and how many of those are the actual failures. A row is **derived** when one of its reference columns points at another row that also failed — it could not have landed whatever it contained, so it says nothing about itself. In an FK-dense bundle these dominate. |
+| `byTable` | **complete** per-table counts (`refused`, `primary`), worst first. |
+| `rows` | up to 20 refused rows — primary ones first — each with `table`, `id`, `reason`. |
+
+`rows` is **capped and `byTable` is not**, and that distinction is worth one sentence: tallying the tables in the printed list answers "how big is the cap", not "which tables failed". The CLI prints the `byTable` line above the list and says so when the list is truncated:
+
+```
+import refused 35 row(s), of which 35 are the actual failures — the rest could not land because a row they reference did not.
+  by table: vacations 26, weeklyUpdates 9
+  vacations v1  not-null constraint userId: the column requires a value [ER_BAD_NULL_ERROR/1048]
+  …
+  (the list above is capped at 20 of 35 — the counts by table are complete)
+```
+
+A refused import ends with a **non-zero exit status and that report** — not with a stack trace. A refusal is a condition with a named cause, not a framework defect, so it is not dressed as one. The report is the same on both transports: over `--target api` the refusal crosses as a 500 whose message embeds it, and the CLI renders that rather than printing the body raw.
+
+**`RowsRefusedError` keeps its tag in every mode, `--atomic` included.** That is worth stating because it is the mode `replace` uses by default: the whole table phase runs in one transaction, and rolling that transaction back needs a rejection — but the rejection carries the typed error, not a rendering of it. So `Effect.catchTag('RowsRefusedError', …)` works on the default path, which is the one most likely to raise one.
+
+One trap if you consume `runImport` yourself: what `Effect.runPromise` **rejects** with is a `FiberFailure`, and `err._tag` on one of those reads `undefined` however good the error inside is. Use `Effect.catchTag` on the effect, or `asImportError(err)` (exported from `@voltro/data-transfer`) on the rejection — reading the tag off the caught value takes the "not my error" branch every time.
+
+A row's `reason` is stated as precisely as the driver allows, in three tiers:
+
+1. **the rule, in your schema's vocabulary** — `unique constraint PRIMARY: a row with this value already exists [ER_DUP_ENTRY/1062]`, `foreign key teams_ibfk_1: the referenced row does not exist (import it first, or check the bundle's table order) [ER_NO_REFERENCED_ROW_2/1452]`. The driver's own code is appended, because that is what you grep a log for;
+2. **the driver's own message + code**, for anything it refused that is not one of the five integrity rules — `Data too long for column 'v' at row 1 [ER_DATA_TOO_LONG/1406]`;
+3. **that there was nothing**, when no driver detail is reachable at all: `the database refused the write and the driver gave no detail` — plus `(via …)`, the chain of wrappers, whenever that chain has more than one layer to name. Read this tier as "not a constraint": a guard, a row filter, or a failure whose words did not survive. When it fires, the run also **logs the full rendering** of the first three such rows (table, primary key, and the whole error as it rendered) and counts the rest. That log line is never returned over the wire — it carries our stack frames, and on some engines a driver's sentence carries row data — so on `--target api` you read it in the instance's log.
+
+Unlike the rpc wire, this string DOES include the driver's own words. The audience is the difference: it is read only by whoever ran `voltro data import` — the holder of the data-transfer secret, who supplied the rows and can export the whole target anyway.
 
 ### Write modes (`--mode`)
 
@@ -2878,6 +2928,16 @@ voltro data import ./out --target api --api-url https://api.example --token $SEC
 
 Note the asymmetry when a deadline *is* hit: re-running an `upsert` after the first run has finished is safe (it is idempotent); re-running a **`replace`** while the first is still mid-flight would empty the target under it. Check the instance's log before deciding — the message says so too.
 
+An instance that is **not answering at all** is a different message, and it names the instance rather than a database:
+
+```
+voltro: api import: the instance at api.example.com is not answering (ETIMEDOUT).
+  That address came from --api-url (or VOLTRO_API_URL) — it is the running instance, not the database.
+  Nothing was sent, so nothing was imported. …
+```
+
+Worth one line because the alternative was measured: a connect failure carries an address, a port and an errno, which is the same shape a database driver's carries — so without this the api host was reported as an unreachable *database*, attributed to `DB_URL`, a variable not in play on that run. Every word after the address was wrong, and the address being right is what made it convincing.
+
 **Import** (`POST /_voltro/admin/import`) applies a bundle **in the instance's own process** through its store — full app pipeline (validation, mixins, **field encryption**, hooks) AND automatic reactivity. Two transports, neither needs a server-readable path:
   - **upload** (default) — the CLI **packs the bundle and uploads the bytes**; the server unpacks to its own temp dir, imports in-process, cleans up. Buffered → small/moderate bundles.
   - **storage-pull** (`--bundle-key <key>`) — the CLI sends only `{ "bundleKey": "<key>" }`; the instance **streams that archive from its configured object storage** (S3 / Azure / MinIO / filesystem, resolved from the storage env — `STORAGE_PROVIDER`, `S3_*`, `AZURE_*`, …), no body buffering → arbitrarily large bundles.
@@ -2977,7 +3037,7 @@ yield* runImport({
 
 Every pipeline failure is a **tagged error**, caught by tag with `Effect.catchTag(...)`. The errors that appear on the `runExport` / `runImport` error channels — the **wire errors**, and therefore exactly what the `--target api` admin endpoints surface — are `Schema.TaggedError`, so a handler can declare them on an rpc procedure's `error:` schema and the rpc encoder marshals them across the wire round-trip-safely (no hand-rolled JSON per tag):
 
-`BundleError`, `CodecError`, `IntegrityError`, `CrossDialectError`, `ImportModeError`, `DanglingReferenceError`, `SchemaDriftError`, `MaskingError`, `ScopeError`.
+`BundleError`, `CodecError`, `IntegrityError`, `CrossDialectError`, `ImportModeError`, `RowsRefusedError`, `SchemaDriftError`, `MaskingError`, `ScopeError`.
 
 The two internal errors — `NativeToolError` (native `backup`/`restore`) and `CompressionError` (folded into `BundleError` by the pipelines) — never cross the wire, so they stay plain `Data.TaggedError`: still catchable by tag, just no Schema surface.
 

package/templates/agent-docs/data.md

@@ -1638,14 +1638,44 @@ warning](#fan-out--how-many-subscribers-may-one-change-wake) is the only signal
 for a subscription that has gone permanently quiet, and an exemption for a name
 you invented disables it for the one case it was built for.
 
+### A table `source:` is typechecked
+
+`voltro dev` writes `voltro-tables.generated.d.ts` beside your generated rpc group, listing every table the app has — your entities, your plugins' `extendSchema.tables`, and the framework's own. `source:` is narrowed to those names, so a typo or a table you renamed away is a **compile error**:
+
+```ts
+source: 'task_subtasks',   // ✗ Type '"task_subtasks"' is not assignable to type 'TableName'
+source: 'task_sub_tasks',  // ✓
+```
+
+That matters because the failure it replaces is silent. A `source:` is matched by NAME against change events, so one that matches nothing does not break the query — it makes it never update. The write still lands, a reload still shows it, and the panel keeps showing the old value.
+
+The file is generated, so **commit it** like the rpc group and let `voltro dev` rewrite it. Before the first run — and in a project that never generates it — `source:` is plain `string` again, which is exactly the previous behaviour; there is no configuration and nothing to opt into.
+
+Two things it deliberately does not narrow. A **plugin's** route `source:` stays `string`: a plugin ships against many apps and cannot know any of their tables. And nothing that READS a descriptor's source at runtime narrows either — a reader that refused an unknown name would reject the stale name it exists to report.
+
+**It does not check the other direction — except for relations.** A `source:` that omits a table the query genuinely reads is silent: the name is right, the table exists, and nothing has an opinion. That is the failure that costs a user report — they type, the row lands, and the panel does not move.
+
+`voltro doctor` closes the part of it that can be closed without guessing:
+
+```
+✗  1 query loads a relation it does not declare:
+   tasks.getById: eager-loads `subTasks` from 'tasks' but does not declare
+   'task_sub_tasks' in `source:` — the view will not update when 'task_sub_tasks' changes.
+```
+
+An eager-loaded relation is composition by definition — its rows are IN the result — and its table comes from the relation registry, so the rule has no heuristic and no exception list. A **many-to-many** wants the junction table too, and says so separately: adding or removing a link writes only the junction row, so declaring the target alone leaves the list stale on exactly the operation a user performs to change it.
+
+What doctor deliberately does NOT do is derive every table an executor reads. That needs a judgement — does this read **compose** the result or merely **restrict** it? — and only composing reads belong in `source:`; a restricting one re-running on every unrelated write puts a hundred lists back on the wire. A scan has to infer that from syntax, and a rule that guesses on a correct codebase teaches you to ignore it.
+
+So: when a live view does not update, check the writing table is in the reading query's `source:` before anything else.
+
 ### Pass the channel, not its key
 
 A channel's routing key is `channel:<name>`, and you can read it off
 `jobQueue.key`. **Do not write that string into `source:`.** Passing the object
 creates an import edge from the query to the declaration, which removes the
-entire class of stale-source bugs for channels: a table `source:` is a string,
-so a rename leaves the old one behind and `tsc` cannot see it, while a channel
-that is not imported does not exist to be named. The boot audit reports a
+entire class of stale-source bugs for channels: a channel that is not imported
+does not exist to be named. The boot audit reports a
 `channel:` key nothing declared, for the two ways round it.
 
 Names are lowercase kebab segments separated by dots — `presence`, `job-queue`,

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

@@ -27,6 +27,8 @@ export default {
 
 Every committed change to a listed table appends a row to `_voltro_row_history` (`tableName`, `rowId`, monotonic `version`, `op`, the full `data` snapshot, `changedBy`, `changedAt`, `traceId`, `subjectId`, `procedure`).
 
+The history row's own `id` is **derived** from `(tableName, rowId, version)` and has a fixed width — it is a surrogate, and every part of it is already a column beside it, so do not parse or construct it. That width is the point: an `id()` column is `VARCHAR(64)` on mysql/mariadb and `NVARCHAR(64)` on mssql, so a key built by concatenating those parts grew with your **table name** and stopped fitting past 22 characters — which failed every write to that table, not merely an import.
+
 
 ### What gets versioned — opt OUT, not in
 

package/templates/agent-docs/whats-new.md

@@ -1,4 +1,4 @@
-# What's new in 0.44.0
+# What's new in 0.45.0
 
 Read this FIRST when a task touches an area you have not worked in recently.
 It is the cheapest way to notice that the framework grew the thing you were
@@ -9,30 +9,99 @@ BREAKING entries name a codemod; run `voltro update` to apply it.
 
 ### ⚠ BREAKING
 
-- **@voltro/data-transfer, @voltro/cli** — `runImport` returns an `ImportOutcome` instead of the bundle's `Manifest`, and `--mode replace` runs as ONE transaction by default.
+- **@voltro/protocol, @voltro/cli, @voltro/voltro** — `source:` on a query is now typed against the app's own tables, so a typo or a missed rename is a compile error instead of a subscription that goes quiet.
 
-  **Why the return type changed.** The summary line counted the rows the BUNDLE carries, not the rows the run wrote. Those differ most exactly where it matters: a bundle directory carries its own resume ledger, so a copied directory imports nothing — correctly, with a warning naming the file to delete — and the run then printed `import complete … rows: 242950` over a target it had not touched. The warning was one line above, which is one line too far for anyone piping the output through `tail -1`. The outcome carries `rowsWritten`, `rowsSkipped` and `fullyResumed`, the CLI reports written-vs-carried, and a fully-skipped run says so on its LAST line.
+  A `source:` is matched by NAME against change events, so a name matching nothing does not break the query — it makes it permanently silent: it compiles, boots, serves its first snapshot and never updates. From the outside that reads as a feature that does nothing, with a correct write path and green tests behind it. The boot has warned about this since 0.26.0, on both paths; a warning is read once, and a rename lands in a diff where nobody is checking strings.
 
-  Migration: `runImport(...)` now resolves to `{ manifest, tablesWritten, rowsWritten, tablesSkipped, rowsSkipped, fullyResumed }`. Read `.manifest` where you read the manifest before.
+  `voltro dev` writes `voltro-tables.generated.d.ts` beside the generated rpc group, augmenting `VoltroTableNames` with the FULL live set — app entities, plugin `extendSchema.tables` and the framework's own — from the same binding the boot audit resolves against, so the type and the warning cannot disagree about which tables exist. `source:` narrows to those names.
 
-  **Why replace is atomic now.** The all-or-nothing guarantee was written for the emptying step, and read — reasonably — as covering the run. A replace that died partway through the LOAD left the target emptied of its old rows and holding part of the new ones, measured on a live instance over sixteen minutes. There is no useful state for a replace to stop in, so it is a default rather than a flag you have to know about. It also closes the window that produced that failure: with the tables emptied and the load uncommitted, a concurrent writer in the application waits instead of inserting a row the bundle is about to insert too.
+  Nothing changes at runtime: these are still string literals, so a descriptor carrying them is as browser-loadable as before. That is what ruled out accepting the table VALUE — a descriptor is loaded value-level by the web client, and a table value drags `@voltro/database` across that boundary.
 
-  `--no-atomic` (CLI) / `atomic: false` (API) opts out. The trade is stated where it bites: every write to those tables waits for the load, and on postgres the bulk `COPY` loader cannot join a transaction it does not own — an atomic run now says that once rather than being quietly slower.
+  **Breaking, and filed that way after being written up as additive.** The test is not whether a symbol disappeared, it is whether code that compiled can stop: `['tasks', 'agent_messages']` was assignable and is not, which is the whole point where the name is stale and an obstacle where the source is genuinely computed. `normalizeSource`'s parameter narrowed with it. The wide shape stays public as `ReactivitySourceValue` for the computed case.
 
-  Two smaller things from the same report: `--mode replace` against a running instance warns about the empty-target window when it is NOT atomic, and the `--target api` upload reports progress per chunk plus a line explaining that the final request stays open for the whole import — sixteen minutes of silence is indistinguishable from a hang, and one operator killed a run that had finished.
+  The break does NOT land at upgrade time, which is why the codemod is a written note rather than a transform: right after `voltro update` the generated file does not exist, `keyof VoltroTableNames` is `never`, `TableName` falls back to `string`, and everything compiles as before. The narrowing switches on at the next `voltro dev` — a different command, by which point the change that caused it is no longer what the reader is looking at. A transform could not have found the sites either, since the type that rejects them has not been generated yet. And the two things `tsc` flags — a stale name versus a runtime-computed one — want opposite fixes, so the mechanical one (widen the annotation) would convert every defect this surfaces back into the quiet subscription it exists to expose.
 
-  **`voltro update` carries you across this** — codemod `0.44.0/01_import-outcome`.
+  Delete the generated file and `source:` widens back to `string`.
+
+  One deliberate asymmetry, stated because it is one: runtime READERS of a descriptor's source stay wide (`ReactivitySourceValue`). Narrow where an author writes, stay wide where the framework reads — a reader that refused an unknown name would be asserting a fact it cannot check, and the first thing it would reject is the stale name it exists to report.
+
+### Added
+
+- **@voltro/cli** — `voltro doctor` reports a query that eager-loads a relation and does not declare its table in `source:` — the failure that looks like a broken feature and is not.
+
+  The write lands, a reload shows it, every test of the write path is green, the name in `source:` is spelled right and the table exists. So neither the typed `source:` nor the boot audit has anything to say, and the only observer is a user watching a panel that does not move.
+
+  ```
+  ✗  1 query loads a relation it does not declare:
+     tasks.getById: eager-loads `subTasks` from 'tasks' but does not declare
+     'task_sub_tasks' in `source:` — the view will not update when 'task_sub_tasks' changes.
+  ```
+
+  No exception list, deliberately. An eager-loaded relation is composition by definition — its rows are IN the result — and its table comes from the relation registry, so the missing name is a fact rather than an inference. A many-to-many is reported twice when needed: adding or removing a link writes only the JUNCTION row, so declaring the target alone leaves the list stale on exactly the operation a user performs to change it. A computed `.with()` key yields nothing rather than a guess.
+
+  The general question — every table an executor reads — is NOT answered, on purpose: it needs a compose-versus-restrict judgement a scan can only infer from syntax, and a rule that guesses on a correct codebase teaches its reader to ignore it. Design in `plans/open/framework/source-completeness.md`.
+
+  Two things around it:
+
+  - **The stale-`source:` audit covered queries only, on both boot paths.** A stream carries a `source:` too, and a stale one there is the same permanently quiet subscription with a longer-lived connection behind it. Both paths now take the set from one `auditableSources`. - **`voltro codegen` writes the typed-`source:` declaration too**, from the same shared `declaredTableNames` merge the boots use. Letting it lag was the bad direction: a table added since the last `voltro dev` would make a CORRECT `source:` a type error. Both commands now say what they wrote — the narrowing has a silent no-op if the app's tsconfig does not pick the file up, so the write has to be loud enough that a reader can check.
 
 ### Fixed
 
-- **@voltro/sql-mysql, @voltro/sql-postgres, @voltro/sql-sqlite, @voltro/sql-mssql, @voltro/data-transfer** — A write and its write-recorders now succeed or fail together on every SQL dialect, and the data importer's retry is idempotent.
+- **@voltro/database, @voltro/sql-mysql** — A binding failure names the TYPE of every value, so the culprit is read rather than guessed.
+
+  `ER_WRONG_ARGUMENTS` / 1210 reads like a count problem and often is not: a statement with twelve columns and twelve placeholders is internally consistent, and the driver is refusing one VALUE it cannot bind. Measured against a live mariadb 11.8 and mysql 8.4 (mysql2 3.22), binding to a PREPARED statement:
+
+  | value | mariadb | mysql | |---|---|---| | plain object | **1210** | accepted | | array | **1210** | accepted | | bigint | accepted | accepted | | Invalid Date | accepted | 1292 |
+
+  So the same row binds on one engine of the family and not the other — which is how a suite comes to fail on mariadb and pass on mysql in the SAME run, and why the type of each binding is the diagnosis rather than a detail.
+
+  `describeDriverError` now reports `bindings: id:string data:Object changedAt:Date …` beside the placeholder count and the statement. Types only; a value there would be row data in a log line, the same reason the statement is carried only in its placeholder form.
+
+  The types travel as a FIELD, not in a message. That is load-bearing: a failing write recorder rethrows with its own sentence, so anything said only in text is dropped exactly where it is needed. `extractDbCause` collects it like any driver field, so it survives every wrapper between the failing statement and the log.
+- **@voltro/database, @voltro/testing** — A driver error now carries the two numbers a binding failure is made of.
+
+  `ER_WRONG_ARGUMENTS` / errno 1210 means the parameter count did not match the placeholder count — reproduced against mariadb 11.8 by sending one parameter for two `?` — and the message says only `Incorrect arguments to mysqld_stmt_execute`. Neither number was reachable from the error, so an investigation into one of these starts by eliminating hypotheses instead of subtracting.
+
+  `describeDriverError` reports `placeholders=N` and the statement, and the statement is carried ONLY in its placeholder form. That restriction is measured, not cautious: against mysql2 3.22 the prepared path (`execute`) leaves `?` in `err.sql` because the server did the binding, while the text path (`query`) interpolates and the same field then holds row DATA. The placeholder is the discriminator, and the form that keeps it is exactly the form 1210 arises in.
+
+  Alongside it, `reportEngineVersion` (`@voltro/testing`): a dialect suite prints the engine BUILD it ran against. A suite that is green on a developer machine and red in CI is only comparable if both name their software, and the test compose file uses moving tags — so "the same tag" is not the same build, and checking the tag locally observes what it points at today rather than what the runner resolved.
+- **@voltro/database, @voltro/plugin-versioning, @voltro/plugin-flags** — A versioned table whose NAME was long enough could not be written to at all.
+
+  `id()` is `VARCHAR(64)` on mysql / mariadb and `NVARCHAR(64)` on mssql, and unbounded `TEXT` on postgres and sqlite. The versioning recorder built its history key by concatenation — `rowver_<tableName>_<rowId>_<version>`, which is `42 + len(tableName)` characters for a 32-character row id — so a 22-character table name fit and a 23-character one produced `ERROR 1406 (22001): Data too long for column 'id' at row 1`. A recorder runs on EVERY write, so this was not a refused import: it was a table nobody could write to, on three of five dialects, at a boundary no one can see when naming a table.
+
+  `derivedRowId(prefix, …parts)` (`@voltro/database`) derives a deterministic key of CONSTANT width — `rowver_<32 hex>`, 39 characters whatever goes in — joined over a `\u0000` separator so the parts stay injective (a `_`-joined key cannot tell `('a_b','c')` from `('a','b_c')`). Widening the column was the alternative and moves the wall rather than removing it; `id()` is also every user table's PK type. Nothing legible is lost: every table deriving a key this way already stores the parts in their own columns.
+
+  The same construction was in `plugin-flags` (`flag_<key>`, over an unbounded user-chosen flag key) and is fixed with it. A guard scans framework sources for an `id:` composed by interpolation and requires the helper, with an allowlist whose entries each name why their parts cannot grow — and which fails if an entry stops matching.
+
+  Also fixed: the versioning suite's live coverage was postgres-only, and postgres is one of the two dialects where that column is unbounded, so it was structurally incapable of seeing this. `@voltro/sql-mysql` is a test devDep of `@voltro/plugin-versioning` now, with a mysql+mariadb case driving an ordinary insert and update against a 33-character table name.
+- **@voltro/database, @voltro/cli** — Two gaps on the `--target api` path, both about a failure that is present and unreadable.
+
+  **The driver was unreachable behind a WRAPPED rejection.** `extractDbCause` unwrapped a `FiberFailure` at the root only, so one reached through a `.cause` link stopped the walk — it carries `stack`, `message` and `name` and nothing else, which is indistinguishable from "no driver under this". That is exactly the shape a failing write recorder produces: it rethrows `new Error(<what it was doing>, { cause: err })` where `err` is the rejection its own insert made. So the same database refusal classified where no recorder runs and degraded to the bare runtime rendering where one does — which is the difference between the direct importer and an import through a running app with versioning or audit on. The walk now unwraps at every link.
+
+  **And the refusal report was never printed on that transport.** A refusal that crossed HTTP arrives as a 500 whose message embeds the `RowsRefusedError` as JSON; the CLI printed that body raw. So the operator on the transport that exists for "the database is somewhere you cannot open a shell" got the one output that has to be triaged by hand — and tallying the capped row list is how a per-table distribution gets reported that is not the real one. `--target api` now prints the same report as the direct path, `byTable` line and cap notice included.
+- **@voltro/data-transfer, @voltro/cli** — Two reporting defects that made a refused import unreadable, both of the shape "the payload is present and property access is not the way to it".
+
+  **A refusal lost its tag on the mode that raises it most.** `--mode replace` runs in one transaction by default, and rolling that back needs a rejection — which the atomic wrapper obtained by throwing `new Error(Cause.pretty(cause))`, a rendering rather than the failure. From there the typed error could not come back: it was re-wrapped as a `BundleError` carrying itself as text. So `Effect.catchTag('RowsRefusedError', …)` matched nothing on the default path, `ImportError`'s union was a claim that path could not honour, and the CLI's refusal report — which branches on the tag — printed nothing at all. The typed error is thrown and passed through now; `asImportError` is exported for callers who catch the rejection rather than the effect.
+
+  **And the report read the tag off a `FiberFailure`.** What `Effect.runPromise` rejects with does not expose `_tag` by property access, so the renderer took its "not my error" branch on every direct-path run while being wired, tested and correct — the test drove the renderer with the error object, which is not the shape the call site produces. A reported refusal now also ENDS the command instead of being rethrown into `fatal unhandled cli error`: a refusal is a condition with a named cause, not a framework defect.
+
+  **An api host is no longer reported as an unreachable database.** A connect failure carries an address, a port and an errno — the same shape a database driver's carries — and one global handler renders that shape, so `--target api --api-url https://…` against a stopped instance printed `the database is not reachable at <api-host>:443 … Configured by: DB_URL` with `DB_URL` not in play. The transport names its own failure now (`InstanceUnreachable`), and the database explainer declines an endpoint whose PORT cannot be a database — judged by port because a driver reports the resolved address, so a host comparison would silence the real message for anyone naming their database by hostname.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/sql-postgres** — A test teardown terminated connections its own pool was still closing, and the resulting error failed the RUN rather than any test.
+
+  `clusterColdStart` drops a per-run database, and the runners it spawned are killed with SIGKILL, so their backends never close — hence the deliberate `pg_terminate_backend` before the `DROP`. But `pool.end()` resolves once it has ASKED the pool to close, not once every socket is down, so the terminate could also land on a connection belonging to the test itself. `pg` reports that as an `error` event on the idle client, and an unhandled one takes down the process.
+
+  The shape it took on a release gate is the reason this is written down: **36 of 36 test files green, and the suite exiting 1.** Nothing points at the teardown — the failure is attributed to whichever suite happened to run last, which is a different one each time. A connection error while we are tearing the database down carries no signal, so it is handled where it arises.
 
-  A recorder (a versioning trail, an audit log) runs on the caller's connection and is ALLOWED to fail — a recorder that throws must take the write down with it, that is its contract. Outside a caller transaction the two were not one unit: the row's statement committed on its own, and the recorder's INSERT ran afterwards as a second autocommit statement. So a recorder that threw left a COMMITTED row behind a write that reported failure. Measured directly: `insert` throws, the row is in the table, and a second attempt at the same row is `ER_DUP_ENTRY` on PRIMARY.
+  Test-only; no product code changed.
+- **@voltro/plugin-auth** — The TOTP skew-window test uses a fixed secret. Test-only; no product code changed, and the assertion is unchanged.
 
-  Anything that retries a failed write then meets its own row. The data importer retries by design — it holds a row whose write failed and tries again once the remaining tables have streamed — so a `--mode replace` that had just emptied a table failed on a duplicate key IN that table. From outside, that is the impossible-looking thing: an import that emptied a table and then failed because something was already in it. Reproduced verbatim, including the table name and `[ER_DUP_ENTRY/1062]`, by putting the old retry back.
+  It failed once on a release gate — `expected true to be false`, meaning a code two steps outside the ±1 window verified. That is the shape of a security defect, so it was treated as one until measured:
 
-  Both ends are closed, and they are independent on purpose:
+  - `TOTP_SKEW` is 1 and the verify loop checks exactly three counters, compared with `timingSafeEqual`; - `T0` is a constant and the clock is injected, so the only varying input was `generateTotpSecret()`; - over **50 000 fresh secrets**: zero collisions between the ±2 codes and the ±1 window (pure chance predicts ~0.3), zero degenerate secrets, uniform length; - **60 consecutive runs** of the file: green.
 
-  - **The cause.** A table that HAS recorders writes inside a transaction now, so the row and the trail commit together or not at all — on mysql, mariadb, postgres, sqlite and mssql, verified by one suite that asks all five the same question. A table with no recorders — the default — takes the direct path unchanged; `recordsTable` is a Map-size check first, so it costs one comparison. - **The defence.** The importer's retry upserts instead of inserting in `replace` mode. That covers every OTHER way a write can land while reporting failure: a driver timeout on a write the server applied, a connection lost after the commit, a concurrent writer inserting the same key. It is sound precisely because the table was emptied by this same run — there is nothing in it that is not ours.
+  So the implementation is sound and that red was two 6-digit codes coinciding — about six in a million per run. Worth stating plainly: that makes the observed failure a one-in-167 000 event, which fits every measurement and is still remarkable. It was not reproduced.
 
-  The test that pinned the divergence went red when the fix landed, exactly as its own note said it would, and is inverted with that note kept.
+  The fix is to remove the coin flip rather than to re-run until green. A random secret buys this test nothing — the property under test is the WIDTH of the window, which does not depend on which secret is used. It only buys a rare red that costs a diagnosis cycle and teaches the reader to re-run. Pinned, so the next failure there means the window moved.

package/templates/apps/api-ai/package.json

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/ai": "0.44.0",
-    "@voltro/cli": "0.44.0",
-    "@voltro/database": "0.44.0",
-    "@voltro/env": "0.44.0",
-    "@voltro/protocol": "0.44.0",
-    "@voltro/runtime": "0.44.0",
+    "@voltro/ai": "0.45.0",
+    "@voltro/cli": "0.45.0",
+    "@voltro/database": "0.45.0",
+    "@voltro/env": "0.45.0",
+    "@voltro/protocol": "0.45.0",
+    "@voltro/runtime": "0.45.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.44.0",
+    "@voltro/testing": "0.45.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

package/templates/apps/api-auth/package.json

@@ -13,17 +13,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.44.0",
-    "@voltro/database": "0.44.0",
-    "@voltro/env": "0.44.0",
-    "@voltro/plugin-auth": "0.44.0",
-    "@voltro/protocol": "0.44.0",
-    "@voltro/runtime": "0.44.0",
-    "@voltro/sql-postgres": "0.44.0",
+    "@voltro/cli": "0.45.0",
+    "@voltro/database": "0.45.0",
+    "@voltro/env": "0.45.0",
+    "@voltro/plugin-auth": "0.45.0",
+    "@voltro/protocol": "0.45.0",
+    "@voltro/runtime": "0.45.0",
+    "@voltro/sql-postgres": "0.45.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.44.0",
+    "@voltro/testing": "0.45.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

package/templates/apps/api-backend/package.json

@@ -16,16 +16,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.44.0",
-    "@voltro/database": "0.44.0",
-    "@voltro/env": "0.44.0",
-    "@voltro/plugin-multitenancy": "0.44.0",
-    "@voltro/protocol": "0.44.0",
-    "@voltro/runtime": "0.44.0",
+    "@voltro/cli": "0.45.0",
+    "@voltro/database": "0.45.0",
+    "@voltro/env": "0.45.0",
+    "@voltro/plugin-multitenancy": "0.45.0",
+    "@voltro/protocol": "0.45.0",
+    "@voltro/runtime": "0.45.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.44.0",
+    "@voltro/testing": "0.45.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"