@voltro/cli 0.43.0 → 0.43.2

package/dist/serveCommand-DUm2-ikx.js

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

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-C8xzYCwa.js";
+import { t as r } from "./serveCommand-CgK7Kj6j.js";
 export { e as loadDotEnv, t as registerAppModules, n as registerDriver, r as runServe };

package/dist/{webhooksCommand-BXUP5YjW.js → webhooksCommand-BVNtNsI0.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-D0E5x2Ue.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-DMx-MF2s.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.43.0",
+  "version": "0.43.2",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -721,22 +721,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.43.0",
-    "@voltro/cache": "0.43.0",
-    "@voltro/data-transfer": "0.43.0",
-    "@voltro/database": "0.43.0",
-    "@voltro/env": "0.43.0",
-    "@voltro/kv": "0.43.0",
-    "@voltro/logger": "0.43.0",
-    "@voltro/plugin-auth": "0.43.0",
-    "@voltro/plugin-broadcast": "0.43.0",
-    "@voltro/plugin-mail": "0.43.0",
-    "@voltro/plugin-storage": "0.43.0",
-    "@voltro/plugin-webhooks": "0.43.0",
-    "@voltro/protocol": "0.43.0",
-    "@voltro/runtime": "0.43.0",
-    "@voltro/serverless": "0.43.0",
-    "@voltro/workflow": "0.43.0",
+    "@voltro/ai": "0.43.2",
+    "@voltro/cache": "0.43.2",
+    "@voltro/data-transfer": "0.43.2",
+    "@voltro/database": "0.43.2",
+    "@voltro/env": "0.43.2",
+    "@voltro/kv": "0.43.2",
+    "@voltro/logger": "0.43.2",
+    "@voltro/plugin-auth": "0.43.2",
+    "@voltro/plugin-broadcast": "0.43.2",
+    "@voltro/plugin-mail": "0.43.2",
+    "@voltro/plugin-storage": "0.43.2",
+    "@voltro/plugin-webhooks": "0.43.2",
+    "@voltro/protocol": "0.43.2",
+    "@voltro/runtime": "0.43.2",
+    "@voltro/serverless": "0.43.2",
+    "@voltro/workflow": "0.43.2",
     "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.43.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.43.2** | `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.43.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.43.2** | `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

@@ -2643,6 +2643,29 @@ over-read is worse than no preview.
 what it does — a silently-ignored table name is how a run scoped to one table writes the
 whole bundle.
 
+### Every `import` option, in one place
+
+| Option | Default | What it does |
+|---|---|---|
+| `--mode upsert\|append\|replace` | `upsert` | How rows are written. See the table below. |
+| `--on-conflict skip\|fail` | `skip` | `append` only: what to do when the primary key already exists. |
+| `--atomic` | off | Wrap the whole table phase in ONE transaction — live readers see the import all-or-nothing. The live-safe `replace`. |
+| `--tables a,b` | every table | Import only these tables from the bundle. |
+| `--dry-run` | off | Run every pre-flight and report what WOULD move; write nothing. |
+| `--force` | off | Proceed despite schema drift AND cross-dialect warnings. |
+| `--no-verify` | off | Skip per-table checksum verification (direct target only). |
+| `--allow-live` | off | Override the refusal to write directly into a database a live instance is serving (direct target only). |
+| `--assets` | off | Restore blobs as well as rows. |
+| `--passphrase <s>` | — | Decrypt an `--encrypt`ed bundle (direct target only; over the api the CLI decrypts before sending). |
+| `--target direct\|api` | `direct` | Write straight to the database, or through a running instance's admin endpoint. |
+| `--api-url <url>` / `--token <secret>` | — | Required by `--target api`. The token must equal the instance's data-transfer secret. |
+| `--bundle-key <key>` | — | `--target api`: have the instance PULL the archive from object storage instead of uploading it. |
+| `--chunk-size <mb>` | 16 | `--target api`: bytes per upload chunk. Chunking engages automatically above one chunk. |
+| `--timeout <seconds>` | none | `--target api`: give up waiting for the instance. Default is to wait as long as the import takes. |
+| `--json` | off | Machine-readable result. |
+
+A flag this subcommand does not read is refused, not ignored — see below.
+
 ### A flag this command does not read is an ERROR
 
 Every `voltro data` subcommand declares the flags it reads, per target, and refuses anything
@@ -2729,9 +2752,63 @@ Anything still unresolvable — the parent row exists in **neither the bundle no
 |---|---|---|---|
 | `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` | TRUNCATE the target tables (children-first) then INSERT | full refresh — target ends up **exactly** the bundle | — |
+| `replace` | empty the target tables, 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.)
+
+#### How `replace` empties the target, and what it refuses
+
+The bundle's tables are emptied **as one unit, in one transaction, with referential integrity suspended for the duration** — not table by table. Both halves matter:
+
+- **All or nothing.** A run that cannot finish leaves the target exactly as it found it. Emptying table by table and stopping at the first refusal leaves the target in neither state — and makes a second attempt destroy *more* than the first.
+- **No ordering can replace the suspension.** MySQL, MariaDB and SQL Server check a foreign key as each *row* is deleted, so a table that references **itself** cannot be emptied at all by ordering tables — the conflict is between two rows of one of them. `createdBy → actors` on the `actors` table is exactly that shape, and it is what an audit mixin on an actor table produces. (Postgres needs no suspension: a multi-table `TRUNCATE` covers the whole set at once.)
+
+What it will **not** do is reach outside the bundle. If a table the bundle does **not** carry holds rows that reference one it does, `replace` refuses **before deleting anything** and names them:
+
+```
+replace cannot empty this target: 1 table(s) OUTSIDE the bundle hold rows that reference
+tables INSIDE it. Emptying the bundle's tables would leave those rows pointing at nothing,
+and the bundle cannot restore them.
+  webhookDeliveries (4021 rows): createdBy → actors, updatedBy → actors
+Nothing has been deleted. Either re-export with a scope that includes those tables, or use
+--mode upsert if those rows are meant to survive.
+```
+
+An **empty** table outside the bundle blocks nothing — a schema always carries tables an environment has never written to.
+
+One consequence of emptying in bulk: the delete itself emits **no change events** (one per row is not affordable at bundle scale). Over `--target api` that is covered — an import through the instance's own process asks every live subscription to re-read once it lands, the same coarse refresh the framework uses after a broadcast gap. Over `--target direct` there is no live instance to tell, which is the whole reason that path is guarded.
+
+#### Which mode for which job
+
+| You want | Mode | Why |
+|---|---|---|
+| Keep a staging database in step with a production export, re-runnable | `upsert` | Idempotent per row: run it as often as you like, the result is the same. |
+| Add an event log / new seed data without touching what is there | `append --on-conflict skip` | Insert-only, and a row that already exists is left alone rather than overwritten. |
+| Catch a duplicate instead of silently skipping it | `append --on-conflict fail` | The import stops and names the row. Use when a duplicate means the bundle is wrong. |
+| Make a target become **exactly** a bundle — replace an environment | `replace` (full-scope bundle) | Empties the bundle's tables first, so rows the bundle does not carry are gone. |
+| The same, against a database that is being served right now | `replace --atomic` | One transaction: readers see the old state until commit, the new one after. Never a half-loaded table. |
+| The same, against a live instance, honouring app invariants | `replace --target api` | Runs in the instance's process: validation, mixins, field encryption, hooks, and live subscriptions re-read afterwards. |
+
+Two things `replace` will refuse, both before writing anything: a **partial bundle** (subset / tenant / table scope), because emptying would delete rows the bundle never carried; and a target where a table **outside** the bundle holds rows referencing one inside it, because those rows cannot be put back. Both refusals name what to do instead.
+
+#### Recipe: replace a dev environment from your local database
+
+```sh
+# 1. Full-scope export of the source, locally.
+voltro data export ./dev-refresh
+
+# 2. Preview against the target first — every pre-flight runs, nothing is written.
+voltro data import ./dev-refresh --target api \
+  --api-url https://dev.example --token "$VOLTRO_DATA_TRANSFER_SECRET" \
+  --mode replace --dry-run
+
+# 3. Do it. A big bundle chunks itself; a failed run can be re-run and resumes.
+voltro data import ./dev-refresh --target api \
+  --api-url https://dev.example --token "$VOLTRO_DATA_TRANSFER_SECRET" \
+  --mode replace --atomic
+```
 
-`replace` **refuses a partial bundle** (a subset / tenant / table scope): truncating 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.)
+If step 3 dies halfway — a dropped connection, a laptop closing — run **exactly the same command again**. The upload continues where it stopped, and the import is a single all-or-nothing step, so the target is either the old state or the new one.
 
 ### Importing into a LIVE instance
 
@@ -2753,6 +2830,49 @@ A plain import connects **straight to the database** (not through the running ap
 - **Secret gate, constant-time.** Every request must present that secret as a **Bearer token** (`Authorization: Bearer <secret>`), compared in constant time over SHA-256 digests (neither length nor content leaks via timing). The gate is a framework-owned secret **independent of app RBAC** — enabling data transfer can never accidentally ride on a user role. The CLI sends it via `--token` / `VOLTRO_DATA_TRANSFER_SECRET` (it must equal the server's secret). Wrong/absent token → `401`.
 - **One secret, both directions.** The same secret gates export (read) and import (write). If you need to grant export without import (e.g. a backup job that must never overwrite), split it into a per-operation credential deliberately — the default is one credential for the whole surface.
 
+#### A big bundle goes up in chunks, and resumes (`--chunk-size`)
+
+A bundle bigger than one chunk is uploaded as a **series of short requests** instead of one long one, and the switch is automatic: the packer's stream is buffered one chunk ahead, so a bundle that fits inside that buffer is sent exactly as before — one request, no protocol — and a bigger one chunks itself. **You never have to know in advance which table is the big one.**
+
+Each chunk is its own request, so a proxy body cap or an ingress read timeout has nothing large to choke on. The **import still runs once**, at the end, over the whole bundle — same modes, same deferred-FK repair, same all-or-nothing emptying. Only the transport changes.
+
+**Resume is real.** The upload id is derived from the bundle itself, so re-running the same command after a failure asks the instance how far it got and continues from there:
+
+```
+api import: resuming a chunked upload the instance already holds { bytes: 50331648 }
+api import: uploaded in chunks { chunks: 7, bytes: 62914560, resumedFrom: 50331648 }
+```
+
+That is safe because `packBundle` over a bundle directory is byte-identical across runs, and because each chunk carries the bundle's **key** (the hash of its manifest). Uploading a *different* bundle under the same id is refused rather than spliced into the partial one, and a chunk that does not start exactly where the instance left off is refused with the offset it does expect.
+
+`--chunk-size <mb>` overrides the default of 16 MiB. Unfinished uploads are discarded by the instance after 24 hours.
+
+##### The chunk protocol, for when you are reading proxy logs
+
+Worth knowing if an ingress sits in the way, because these requests are what it will show you. All of them are `POST` to the same `/_voltro/admin/import` path, gated by the same Bearer secret:
+
+| Request | Headers | Answer |
+|---|---|---|
+| probe | `x-import-upload-id`, `x-import-probe: 1`, empty body | `200 {uploadId, bytes}` — how much the instance already holds |
+| chunk | `x-import-upload-id`, `x-import-upload-key`, `x-import-chunk-offset` | `202 {uploadId, bytes}` — accepted, nothing imported yet |
+| final chunk | the same plus `x-import-chunk-final: 1` | `200` with the import's own result — this is the long one |
+
+A `409` means the instance refused the chunk and says which of three things happened: `offset-mismatch` (with the `expectedOffset` to continue from), `key-mismatch` (a different bundle under this upload id — use a new id), or `bad-id`. None of them is retryable by simply repeating the request, which is why each one names the fix.
+
+Only the FINAL request runs the import, so only that one is long. If it is the request your proxy times out on, that is the one to raise `proxy_read_timeout` for — or use `--bundle-key` and have the instance pull the archive from object storage instead of receiving it.
+
+#### How long an `--target api` call may take (`--timeout`)
+
+Both api-target calls **wait as long as the instance needs**. There is no default deadline, and that is deliberate: the response arrives only when the *import* (or export) has finished, so any fixed bound is really a bound on the size of your database. A full bundle of a grown database routinely takes longer than five minutes to apply.
+
+Pass `--timeout <seconds>` when you want one. If it is hit, the message says what it means — the upload finished long ago and **the instance is very probably still importing**:
+
+```
+voltro data import ./out --target api --api-url https://api.example --token $SECRET --timeout 900
+```
+
+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.
+
 **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.
@@ -3128,6 +3248,10 @@ flag is the one-off override.
 | GDPR / per-tenant takeout | `voltro data export --tenant <id> --assets` |
 | A small self-consistent slice of the data | `voltro data export --profile <env>` with a `subset` |
 | Move Postgres → MySQL | `voltro data export` then `import` (cross-dialect lint applies) |
+| Replace a dev/staging environment with your local state | `voltro data import <dir> --target api --mode replace --atomic` |
+| Seed a fresh cluster through the running app (invariants + encryption) | `voltro data import <dir> --target api` (default `upsert`) |
+| Move a bundle too big for one request | nothing extra — the upload chunks itself; `--chunk-size` only if you need a different size |
+| Resume an upload that died | re-run the identical command |
 
 
 

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

@@ -1004,6 +1004,18 @@ The usual cause on MariaDB is a **UNIQUE constraint on an unbounded text column*
 
 The reader finds such tables when CDC starts, reports each once, and **excludes** it — so there is no reconnect loop. Cross-instance change events for that table are lost; own-node reactivity is unaffected, because writes still emit inline.
 
+**How long that verdict lasts.** It is a reading of the schema at the moment the reader attached, and applying the remedy does not lift it by itself. `voltro dev` builds its store before it migrates — kv, cross-replica broadcast and the analytics mirror all need one — so on a boot whose own migration bounds the column, the finding is a second older than the fix. That boot therefore **re-checks the exclusion set once all its schema work is done and re-admits the table in the same run**:
+
+```
+cdc: table 'sessions' looks undecodable … Not a verdict yet; the definitive line follows.
+auto-migrate: applied 74 op(s) in 1157ms
+cdc: table 'sessions' re-admitted to binlog capture — the hidden-column condition is gone.
+```
+
+The re-check runs in both directions: schema work that *creates* an unbounded unique on a captured table excludes it there and then, rather than after the reader has failed on three writes.
+
+`voltro serve` has no equivalent step and needs none — it builds its store *after* every schema step and never applies DDL itself, so its reading at attach is already the final one. Everywhere else the exclusion holds until the process restarts.
+
 **The remedy is to bound the column:**
 
 ```ts

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

@@ -1,4 +1,4 @@
-# What's new in 0.43.0
+# What's new in 0.43.2
 
 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
@@ -7,89 +7,29 @@ workaround for something that shipped two versions ago.
 
 BREAKING entries name a codemod; run `voltro update` to apply it.
 
-### ⚠ BREAKING
-
-- **@voltro/data-transfer, @voltro/cli** — `DanglingReferenceError` is now `RowsRefusedError`, and it separates the rows that failed from the rows that failed because those rows did.
-
-  **The name.** The import raised it for EVERY row still refused after deferred-FK resolution, whatever the reason — a NOT NULL violation, a duplicate key, a value the database computes for itself. The tag named ONE possible cause and put it where a reader looks first, so any other refusal arrived mislabelled. The new name states the outcome; each row's `reason` states the cause, which is where a cause can honestly be claimed.
-
-  **The split.** A row is `derived` when one of its reference columns holds the primary key of another row that also failed in this run: it could not have landed whatever it contained, so its reason describes the parent's problem. The relation is transitive, decided from the DATA (the failed ids against the reference-typed values), so no schema knowledge is needed. `primaryCount` is the number an operator acts on, `rows` lists primary failures FIRST so the cap never spends its budget on consequences, and the CLI leads with both numbers:
-
-  ```
-  import refused 300 row(s), of which 1 are the actual failures — the rest could
-  not land because a row they reference did not.
-    teams t1  foreign key teams_ibfk_1: the referenced row does not exist [1452]
-    … and 299 row(s) behind them. Fix the 1 above and re-run; they resolve with
-    their parents.
-  ```
-
-  In an FK-dense bundle one refused parent takes its whole subtree with it, so the length of a flat list says how connected the data is, not how many problems there are — and the single row that explains all of them sits somewhere in the middle of it.
-
-  The codemod rewrites the import and every use of the symbol. It does NOT rewrite a tag STRING (`Effect.catchTag('DanglingReferenceError', …)`, `err._tag === '…'`) — change those to `'RowsRefusedError'` — and the payload gained `primaryCount` plus a `derived` flag per row.
-
 ### Fixed
 
-- **@voltro/cli** — `voltro doctor`'s `subject-write-no-guard` rule reads the DESCRIPTOR before it reports. It looked only at the executor, and the access decision is not declared there.
-
-  Every form of access decision the framework has — `internal: true`, `guards: [...]`, `openAccess:` — is declared on the DESCRIPTOR. So an app that declares them properly got a finding for each one, and on a codebase whose procedures are mostly `internal: true` the rule fires on essentially all of them and is wrong essentially every time.
-
-  That is worse than a rule that finds nothing: it is the longest line in the report and it reads like a security finding, so it teaches the reader to skim the place a real finding would have appeared.
-
-  The premise was structurally impossible for most of them, and the framework says so itself: `security.defaultDeny` refuses at boot any wire-exposed procedure declaring neither `guards:` nor `openAccess:`. So "an anonymous caller reaches the write" can only be true of an `openAccess` procedure. That is what the rule looks for now — plus the handler check it always honoured, plus an ownership comparison against `subject.id`, which is the refusal the rule says is missing. Where no descriptor can be read, it says nothing: the claim is about a declaration, and a finding whose evidence was never opened is the failure mode this fixes.
-
-  The `use:` line changed with it. It recommended `.guard(requireScope('…'))`; the shipped guide teaches declarative `guards:` and calls a hand-written per-executor scope check the thing `guards:` exists to delete. A rule may not recommend the shape the guide argues against.
-- **@voltro/database, @voltro/data-transfer** — A `voltro data` transfer no longer carries GENERATED column values, and no longer loses every row that has one.
-
-  The export wrote the computed values into the bundle and the import sent them back in the `INSERT` column list. MariaDB refuses that for any value except NULL (`1906: The value specified for generated column 'x' in table 't' has been ignored`); postgres refuses a non-DEFAULT value outright. So the transfer failed per ROW, not per table, and only for the rows whose generated value was non-NULL.
-
-  That selectivity is the dangerous part. `.uniqueActive()` lowers to exactly such a column on mysql/mariadb — a STORED generated column holding the key while the row is live and NULL once it is soft-deleted — so the refused rows are the LIVE ones and the accepted ones are the tombstones. A table can come out looking like "a few rows failed" or empty, depending only on how many of its rows are deleted, and any table with a foreign key into it fails behind it.
-
-  Both ends are fixed from one source of truth: **introspection now reports generated columns on every dialect** (`generatedAs`, from `information_schema.generation_expression` on mysql/mariadb, `is_generated` on postgres, `PRAGMA table_xinfo`'s hidden flag on sqlite, `sys.computed_columns` on mssql). It was declared-side only before — invisible to the planner, which does not compare it, and load-bearing for anything that writes rows back.
-
-  The exporter omits those columns, values and all. The importer strips them from every incoming row using the TARGET's snapshot, because a bundle already written still carries them and a file on disk is data, read where it is.
-
-  **`voltro serve`'s admin export/import needed a second fix, and without it this one reached only the direct transport.** The running instance hands those handlers `declaredSnapshot(tables)` — no dialect — and `.uniqueActive()` lowers to a generated column only when the snapshot knows the engine. So over `--target api` the snapshot described a schema with no generated columns while the database had several, and the export wrote their values back into the bundle exactly as before. It passes the dialect now (the variable was already on the next line).
-
-  `generatedAs` is also kept OUT of the schema fingerprint. Introspection can read the fact back but not a comparable value — the engine returns its own normalisation of the expression, never the declared spelling — so hashing it would make declared and live disagree permanently: a schema nobody touched reporting a changed declaration on every boot, and a transfer target that matches its bundle exactly refused as drifted.
-
-  Covered by a live mariadb→mariadb and mysql→mysql round trip over a `.uniqueActive()` table with live and soft-deleted rows, asserting the target recomputed the value rather than that the row merely arrived.
-- **@voltro/sql-mysql** — On mysql/mariadb, a write REJECTED by the database through `insertIgnore` was reported as a conflict when the caller was not inside a transaction — and never reached the caller as a typed `ConstraintViolation` at all.
-
-  Two causes, both measured against live MySQL 8.4 and MariaDB 11.
-
-  **The connection.** `INSERT IGNORE` demotes every error to a warning, so the store reads `SHOW WARNINGS` to tell a rejection from a conflict. That describes the last statement on a CONNECTION, and outside a transaction every statement acquires its own from the pool — so the read was unattributable and came back empty. The rejected write then surfaced as "the insert was skipped as a conflict, but no existing row matches conflictColumns […] the constraint that fired is unknown", whose enumeration lists only conflict causes. A rejection described as a conflict is the exact sentence this path was fixed once already for producing; it survived on the path that had no transaction to read on. The store now pins one connection for the whole decision — the same pinning `insertRecoverAutoId` does for `LAST_INSERT_ID()`.
-
-  **The classification.** The store swallowed the driver's error and raised a prose one of its own, so `classifyConstraintViolation` had nothing to read: this was the one write path where the typed error could not fire, while every other one produced it. The warning IS the driver's payload — `INSERT IGNORE` only changed how it was delivered — so it is handed on in the shape the driver would have thrown. A rejection now arrives as the same `ConstraintViolation { kind: 'foreignKey', … }` a plain `insert` produces. Nothing new crosses the wire: the classifier extracts the constraint NAME as a delimited group, never the sentence.
-
-  This is the default `voltro data import` path (`--mode append`, `--on-conflict skip`, without `--atomic`), so a row rejected by a foreign key was reported to the operator as a conflict with an unknown cause.
-
-  `constraintViolation.integration.test.ts` now asserts the `insertIgnore` seam per dialect against live postgres 17, MySQL 8.4, MariaDB 11 and SQL Server 2022. It was the missing assertion behind a claim derived from the wiring — the classification does sit on all ten write paths, which is not the same as a classifiable error arriving on all ten.
-- **@voltro/protocol, @voltro/runtime** — The framework's store errors — `ConstraintViolation`, `TenantScopeViolation`, `TenantRowNotFound`, `ServerOnlyColumnWrite`, `TableValidationFailed`, `StoreOperationFailed` — are exported from `@voltro/protocol` and can therefore be declared in a descriptor's `error:` union. They could not be.
-
-  They lived in `@voltro/runtime`, which reaches `node:child_process`, `node:http` and `node:crypto`. A descriptor is loaded VALUE-LEVEL by the web client (the `RpcClient` needs every procedure's Schema), so a descriptor importing from there is refused at boot by the browser-safety guard — correctly. The typed half of these errors was therefore unreachable: the docs told you to declare them, and the boot said no.
+- **@voltro/sql-mysql, @voltro/database, @voltro/cli** — The mysql-family binlog reader no longer keeps a table excluded after the very migration that fixed it.
 
-  What that leaves is the untyped half only. The error still arrives as an `InternalError` carrying a readable sentence, so telling `foreignKey` ("the row you picked is gone") from `foreignKeyInUse` ("this row is still referenced") — two different messages for the user — means parsing that sentence. Over a set of generated delete mutations that is a string comparison per procedure, which is the thing the typed error exists to delete.
+  A UNIQUE on an unbounded text column is a MariaDB hash long-unique, whose hidden `DB_ROW_HASH_n` column the reader can never account for — so the table is held out of binlog capture and the exclusion is reported. `voltro dev` builds its store BEFORE it migrates (kv, cross-replica broadcast and the analytics mirror all need one), so on a boot whose own auto-migration bounds the column, that finding was drawn from a schema that stopped existing about a second later. The exclusion then outlived its cause for the life of the process, and the message — correct when written, and typically the only error line in the boot log — went on describing the pre-migration database.
 
-  `@voltro/runtime` re-exports all six, so server code is unchanged. The classes have no server dependency of any kind — the file imports `Schema` from `effect` and nothing else, and `browserSafetyGuard.test.ts` now pins a descriptor that declares one, so moving them back reads as a boot failure rather than as a passing rename.
-- **@voltro/database, @voltro/sql-mysql** — A blocked `alter-column-type` told every dialect to write a postgres cast.
+  Three changes:
 
-  The refusal is correct — a bare type change may not be value-preserving, so it is refused until acknowledged. Its `fix:` line was not:
+  - `DataStore.refreshChangeCaptureExclusions()` (optional; implemented by the mysql-family store) re-runs the probe and re-points the LIVE reader, in both directions — schema work that CREATES the condition now excludes the table immediately instead of after three failed writes. `voltro dev` calls it once, after all its schema work. `voltro serve` needs no equivalent: it builds its store after every schema step and never applies DDL itself. - The definitive message now states its own durability — that it is the schema as read at reader attach, and that applying the remedy does not by itself lift the exclusion. - On a boot that will re-check, the finding is reported as a provisional note rather than as a verdict, so a boot that fixes the condition leaves no error line about it. The note escalates to the full verdict on its own if the re-check never runs. - Two reader fixes the re-check depended on: applying a new exclusion set now WAITS for a reconnect already in flight (it is what applies the set, so resolving before it landed meant the caller's next write hit the old filter), and the reconnect loop no longer keeps resuming from an offset it has just jumped away from — that turned one purged offset into a reconnect every watchdog interval, forever, delivering nothing.
+- **@voltro/data-transfer, @voltro/database, @voltro/sql-mysql, @voltro/sql-postgres, @voltro/sql-sqlite, @voltro/sql-mssql, @voltro/cli** — `voltro data import --mode replace` no longer leaves a target in neither state, and now works against schemas that have foreign keys.
 
-  ```
-  acknowledge it on the column: `.narrowedFrom('json', { using: 'meta::text' })`
-  ```
+  The delete step ran table by table and stopped at the first refusal, so a run that could not finish left dozens of tables emptied and nothing loaded — and a second attempt destroyed more than the first, because it got further before hitting the same wall. The wall itself was not exotic: MySQL, MariaDB and SQL Server check a foreign key as each ROW is deleted, so a table that references ITSELF cannot be emptied by any ordering of the tables. `createdBy → actors` on the `actors` table is exactly that shape, and it is what an audit mixin on an actor table produces.
 
-  `USING <expr>` is postgres syntax and a postgres capability. The mysql arm of the applier emits `MODIFY COLUMN`, the mssql arm `ALTER COLUMN`, and sqlite rebuilds the table — none of them can carry a cast expression and none of them reads `using`. So an operator on any other engine was handed a line to paste into their schema containing syntax their database has never seen, inside an argument that is discarded. A refusal is read as an instruction, and the more carefully it is read the more thoroughly a wrong one is followed.
+  - `DataStore.emptyTables()` (per dialect) empties the whole set as one unit, in one transaction, with referential integrity suspended for the duration — `FOREIGN_KEY_CHECKS` on the mysql family, a multi-table `TRUNCATE` on postgres, `defer_foreign_keys` on sqlite, per-table `NOCHECK`/`WITH CHECK CHECK` on mssql. All-or-nothing on every engine, including under `--atomic`, where it runs on the transaction the import already holds. - A **pre-flight refusal**: if a table OUTSIDE the bundle holds rows referencing one inside it, the import refuses before deleting anything and names the tables, the columns and the row counts. Those rows cannot be restored from the bundle, so forcing it is not an option. An EMPTY outside table blocks nothing. - Table-level failures carry the driver's own reason and code, the way row-level failures already did. `truncate <table> failed: Failed to execute statement` fits every plausible cause equally; the classification that produced `foreign key <name>: … [ER_NO_REFERENCED_ROW_2/1452]` one level down now applies one level up. The word "truncate" is gone from the message too — the step issues DELETE, and naming a statement it does not run sends whoever reads it to reproduce the wrong thing. - A typed refusal reaching the `--target api` transport keeps its text: the admin import endpoint answers `409` with the reason instead of flattening it to `import failed`, on the one transport where the operator has no other way to see it.
 
-  The fix line is dialect-aware now: postgres keeps the `using` half, everything else gets `.narrowedFrom('<type>')` plus the fact that the engine converts in place — because a refusal that offers no expressible fix reads as "the framework cannot do this at all".
+  The bulk empty emits no change events, where the per-table loop emitted one per row. An import through `--target api` now asks every live subscription to re-read once it lands — the coarse refresh the framework already uses after a broadcast gap — so neither the missing deletes nor a table the bundle carries EMPTY leaves a subscriber holding rows that are gone. Wired where the route is mounted, which is the one place both boot paths share.
 
-  Covered on live MySQL and MariaDB by both halves at once: what the refusal SAYS, and that following it applies AND converges with the row intact. A message test alone would keep passing over a broken apply; a convergence test alone is what let the wrong message survive this long.
+  On postgres the emptying is a `DELETE` per table, not a `TRUNCATE`, and the difference is not performance: postgres refuses `TRUNCATE` on a table with ANY incoming foreign key, rows or not, while the mysql family refuses a DELETE only when rows actually reference the doomed ones. A `TRUNCATE` version made an EMPTY table outside the bundle block a replace on postgres and not on mariadb — one import, refused on one engine and accepted on the other, over a table holding nothing.
 
-  Also on the same path: `upsert` with a PARTIAL row (one omitting a NOT NULL column that has no default) failed on MariaDB and succeeded on MySQL. The native `INSERT … ON DUPLICATE KEY UPDATE` validates its insert half even when only the update half runs, so the row was rejected although the target existed and only needed patching. A partial row takes the lookup path on both engines now; the single-statement form still covers the complete-row case, which is what a data transfer and every generated CRUD write send.
-- **@voltro/sql-mysql** — On MariaDB, `upsert` could write a DIFFERENT row than the one it was given and report success.
+  `--target api` also no longer times out on a full bundle. Both api-target calls went through `fetch`, whose undici default gives up after 300 s — a bound on the caller's database size, on a call whose response arrives only when the import does. They wait as long as the instance needs now, stream the body instead of buffering the whole bundle, and take `--timeout <seconds>` when a deadline is wanted. If one is hit, the message says the instance is probably still importing — and gives different advice for `replace` than for the idempotent modes, since re-running the first while it is mid-flight would empty the target under it.
 
-  `INSERT … ON DUPLICATE KEY UPDATE` fires on ANY unique key, not on the one named in `conflictColumns`. So an incoming row whose (say) `email` already belonged to a different primary key updated THAT row instead — and since `id` is excluded from the SET list, the row the caller handed over was never written. Measured on a live server: the call returned a row, the target kept the old id, the new row was absent, and the existing row had silently taken the incoming values. A bulk transfer on top of that prints `import complete` over missing data, which is the worst failure shape available: there is nothing to investigate.
+  Two more, found by measuring rather than by reading:
 
-  The two engines of the family disagreed here, which is part of why it survived. The non-RETURNING path (MySQL) looks the row up by `conflictColumns` first, does not find it, and lets the INSERT fail with a duplicate-key error. Loud was always right.
+  - **`--atomic` on postgres could not import a bundle that needed the deferred-FK repair at all.** A failed statement aborts the transaction there, and that repair depends on a row whose parent has not loaded yet failing, being held, and being retried — so the first such row poisoned every write after it. Every tolerated write now runs inside a savepoint. Per-row savepoints measured 2.40x the time of none on 5 000 rows, so they are amortised: one savepoint per batch of 200, and a batch that fails rolls back whole and replays row by row. The mysql family and sqlite leave a transaction usable after a failed statement and pay nothing for any of this. - **The replace pre-flight asked the caller's snapshot.** Over `--target api` that is the app's DECLARED schema, which cannot show a table the app stopped declaring but the database still has — and rows in a table nobody declares are exactly the rows nobody is watching. `DataStore.incomingForeignKeys()` reads the live catalog per dialect; the snapshot remains the fallback for stores without one.
 
-  Both refuse now, with a message naming both ids and the fact that the collision was on a constraint other than the one named. The check runs inside a transaction — a short one of the store's own when the caller is not already in one — so the wrong row is rolled back rather than reported after the fact: detecting this afterwards still leaves someone else's row overwritten.
+  A bundle bigger than one chunk is now uploaded as a series of short requests, so a proxy body cap or an ingress read timeout has nothing large to choke on, and the switch is automatic — the packer's stream is buffered one chunk ahead, so a small bundle is sent exactly as before and nobody has to know in advance which table is the big one. The import still runs ONCE, at the end, over the whole bundle. Resume is byte-exact (`packBundle` is deterministic over a directory, which this package now asserts), guarded by a bundle key so a different bundle under the same upload id is refused rather than spliced into the partial one, and by a contiguity check so a mis-ordered append cannot produce an archive that only fails later during decode. `--chunk-size <mb>` overrides the 16 MiB default.

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.43.0",
-    "@voltro/cli": "0.43.0",
-    "@voltro/database": "0.43.0",
-    "@voltro/env": "0.43.0",
-    "@voltro/protocol": "0.43.0",
-    "@voltro/runtime": "0.43.0",
+    "@voltro/ai": "0.43.2",
+    "@voltro/cli": "0.43.2",
+    "@voltro/database": "0.43.2",
+    "@voltro/env": "0.43.2",
+    "@voltro/protocol": "0.43.2",
+    "@voltro/runtime": "0.43.2",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.43.0",
+    "@voltro/testing": "0.43.2",
     "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.43.0",
-    "@voltro/database": "0.43.0",
-    "@voltro/env": "0.43.0",
-    "@voltro/plugin-auth": "0.43.0",
-    "@voltro/protocol": "0.43.0",
-    "@voltro/runtime": "0.43.0",
-    "@voltro/sql-postgres": "0.43.0",
+    "@voltro/cli": "0.43.2",
+    "@voltro/database": "0.43.2",
+    "@voltro/env": "0.43.2",
+    "@voltro/plugin-auth": "0.43.2",
+    "@voltro/protocol": "0.43.2",
+    "@voltro/runtime": "0.43.2",
+    "@voltro/sql-postgres": "0.43.2",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.43.0",
+    "@voltro/testing": "0.43.2",
     "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.43.0",
-    "@voltro/database": "0.43.0",
-    "@voltro/env": "0.43.0",
-    "@voltro/plugin-multitenancy": "0.43.0",
-    "@voltro/protocol": "0.43.0",
-    "@voltro/runtime": "0.43.0",
+    "@voltro/cli": "0.43.2",
+    "@voltro/database": "0.43.2",
+    "@voltro/env": "0.43.2",
+    "@voltro/plugin-multitenancy": "0.43.2",
+    "@voltro/protocol": "0.43.2",
+    "@voltro/runtime": "0.43.2",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.43.0",
+    "@voltro/testing": "0.43.2",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

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

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

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

@@ -13,18 +13,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.43.0",
-    "@voltro/database": "0.43.0",
-    "@voltro/env": "0.43.0",
-    "@voltro/plugin-mail": "0.43.0",
-    "@voltro/plugin-multitenancy": "0.43.0",
-    "@voltro/protocol": "0.43.0",
-    "@voltro/runtime": "0.43.0",
+    "@voltro/cli": "0.43.2",
+    "@voltro/database": "0.43.2",
+    "@voltro/env": "0.43.2",
+    "@voltro/plugin-mail": "0.43.2",
+    "@voltro/plugin-multitenancy": "0.43.2",
+    "@voltro/protocol": "0.43.2",
+    "@voltro/runtime": "0.43.2",
     "effect": "^3.22.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.43.0",
+    "@voltro/testing": "0.43.2",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

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

@@ -13,18 +13,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.43.0",
-    "@voltro/database": "0.43.0",
-    "@voltro/env": "0.43.0",
-    "@voltro/plugin-multitenancy": "0.43.0",
-    "@voltro/plugin-storage": "0.43.0",
-    "@voltro/protocol": "0.43.0",
-    "@voltro/runtime": "0.43.0",
-    "@voltro/sql-mysql": "0.43.0",
+    "@voltro/cli": "0.43.2",
+    "@voltro/database": "0.43.2",
+    "@voltro/env": "0.43.2",
+    "@voltro/plugin-multitenancy": "0.43.2",
+    "@voltro/plugin-storage": "0.43.2",
+    "@voltro/protocol": "0.43.2",
+    "@voltro/runtime": "0.43.2",
+    "@voltro/sql-mysql": "0.43.2",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.43.0",
+    "@voltro/testing": "0.43.2",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"