@voltro/cli 0.19.0 → 0.20.1

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { Q as e } from "./inspectMetrics-D1DmLeJs.js";
-import { t } from "./start-Clvz4IJb.js";
+import { et as e } from "./inspectMetrics-DvPNXmGA.js";
+import { t } from "./start-CXQ7WL1W.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -62,22 +62,22 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.19.0",
-    "@voltro/cache": "0.19.0",
-    "@voltro/data-transfer": "0.19.0",
-    "@voltro/database": "0.19.0",
-    "@voltro/env": "0.19.0",
-    "@voltro/kv": "0.19.0",
-    "@voltro/logger": "0.19.0",
-    "@voltro/plugin-auth": "0.19.0",
-    "@voltro/plugin-broadcast": "0.19.0",
-    "@voltro/plugin-mail": "0.19.0",
-    "@voltro/plugin-storage": "0.19.0",
-    "@voltro/plugin-webhooks": "0.19.0",
-    "@voltro/protocol": "0.19.0",
-    "@voltro/runtime": "0.19.0",
-    "@voltro/serverless": "0.19.0",
-    "@voltro/workflow": "0.19.0",
+    "@voltro/ai": "0.20.1",
+    "@voltro/cache": "0.20.1",
+    "@voltro/data-transfer": "0.20.1",
+    "@voltro/database": "0.20.1",
+    "@voltro/env": "0.20.1",
+    "@voltro/kv": "0.20.1",
+    "@voltro/logger": "0.20.1",
+    "@voltro/plugin-auth": "0.20.1",
+    "@voltro/plugin-broadcast": "0.20.1",
+    "@voltro/plugin-mail": "0.20.1",
+    "@voltro/plugin-storage": "0.20.1",
+    "@voltro/plugin-webhooks": "0.20.1",
+    "@voltro/protocol": "0.20.1",
+    "@voltro/runtime": "0.20.1",
+    "@voltro/serverless": "0.20.1",
+    "@voltro/workflow": "0.20.1",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -595,7 +595,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.19.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.20.1** | `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.19.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.20.1** | `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

@@ -545,6 +545,21 @@ fully concurrent. Tune the cap with `VOLTRO_DEV_SSR_COMPILE_CONCURRENCY` (below)
 drop it on a low-memory box, raise it on a big machine.
 
 
+Under `VOLTRO_LOG_LEVEL=debug` each cold compile logs its own duration, so a slow
+first paint can be attributed to a specific module:
+
+```
+[voltro:dev:web] ssr cold-compile start id=/app/src/pages/layout.tsx
+[voltro:dev:web] ssr cold-compile start id=/app/src/pages/(main)/layout.tsx
+[voltro:dev:web] ssr cold-compile end 3743ms id=/app/src/pages/layout.tsx
+```
+
+Read the `ms` on the **end** line rather than subtracting timestamps: compiles run
+concurrently up to the cap, so the start and end lines interleave and adjacent
+lines usually belong to different modules. The duration is measured inside the
+concurrency permit, so it is that module's own compile cost and not time spent
+queued behind the cap. A compile that threw says `FAILED` instead of `end`.
+
 ### Fast Refresh: what hot-updates and what reloads
 
 Editing a **page or layout component** applies as a hot update — the React tree
@@ -835,6 +850,24 @@ apps/acme/web/.framework/dist/
     └── ssrEntry.js                     # SSR bundle for voltro start
 ```
 
+## Unresolvable optional peers
+
+The SSR bundle inlines everything it reaches (`ssr: { noExternal: true }`), which is what lets a production web image ship without a framework dependency tree. A package that cannot be **resolved at all** is externalised instead of failing the build — almost always an uninstalled optional native peer reached through a library's Node entry point:
+
+```
+Rolldown failed to resolve import "canvas" from ".../konva/lib/index-node.js"
+```
+
+`konva`'s `main` is its Node build, which requires the optional `canvas`; its `browser` field points at one that does not. An app that never renders to a canvas server-side has nothing to install, and there is no app-side workaround: making the import dynamic does not help (the bundler must still resolve it to form the chunk), and `renderMode: 'spa'` does not either — the generated router imports every page statically, so the module is in the SSR graph whatever the render mode.
+
+Every specifier externalised this way is named on the success line:
+
+```
+[voltro:build] SSR bundle ready { path: 'dist/server/ssrEntry.js', externalizedOptionalPeers: 'canvas' }
+```
+
+Read that list. Externalising is right for an optional peer you never use, and wrong for a dependency you forgot to install — it turns a build failure into a runtime one, and only you can tell the two apart. Framework packages (`@voltro/*`, `@effect/*`, `effect`) are never externalised.
+
 ## `voltro start <appDir>`
 
 ```bash

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

@@ -1937,6 +1937,19 @@ source of truth. Just restoring the snapshot brings the data back
 but the declared schema still says the column shouldn't exist; the
 next apply would re-drop it.
 
+## The differ leaves snapshots alone
+
+A soft drop leaves an object in the database that no schema declares —
+that is the whole point of it. The planner treats every
+`<name>__dropped_<ts>` as framework-managed and never plans a drop for
+it, the same way it skips `_voltro_*` and the cluster engine's tables.
+This holds for columns and for tables.
+
+You do not need `VOLTRO_DB_IGNORE_TABLES` for a snapshot, and you should
+not add one: that list is for YOUR unmanaged infra tables, and an entry
+there would still be in your config long after `gc-snapshots` reclaimed
+the snapshot.
+
 ## GC
 
 Snapshot columns aren't automatically dropped. They survive until
@@ -2612,7 +2625,15 @@ export default migration({
 // VOLTRO_DESTRUCTIVE_OK=1 voltro db apply --note 'retiring oldUsersTable per ticket #...'
 ```
 
-**Two tables this never proposes dropping:**
+**Delete the entity and drop the table in the SAME change.** The intuitive
+order — remove the code first, sort the schema out after — is the broken one:
+with `VOLTRO_AUTO_MIGRATE=1` the very next boot sees an undeclared table,
+refuses, and the app crashloops until the drop is authorised. There is nothing
+to recover from, but the app is down while you work it out. Take the entity out
+together with the `VOLTRO_DESTRUCTIVE_OK` apply that removes its table, or leave
+the entity in place until you are ready to run both.
+
+**Three tables this never proposes dropping:**
 
 - **`actors`** — the framework-provided audit subject. You don't declare an
   `actors.entity.ts`; `db plan` / `db apply` auto-include the built-in `actors`
@@ -2633,6 +2654,10 @@ export default migration({
   Strapi→Voltro `_strapi_id_map` sitting in the DB won't refuse-to-boot on a
   `drop-table`. (The framework already self-excludes its own `_voltro_*` /
   `cluster_*` runtime tables; this is the user list on top of that.)
+- **Soft-drop snapshots** — a `<name>__dropped_<ts>` left behind by
+  `VOLTRO_SOFT_DROP=1`. The differ treats it as framework-managed until
+  `voltro db gc-snapshots` reclaims it, so do NOT add one to
+  `VOLTRO_DB_IGNORE_TABLES`.
 
 ## A migrate / apply DDL statement failed — find which one
 
@@ -2699,7 +2724,15 @@ it now is, must have nothing left to do.
 
 **It is a framework bug, not a mistake in your schema.** The named operations
 emit DDL that does not take effect. Report the operation kinds plus the column
-types involved. In the meantime the schema is unchanged and safe — nothing was
+types involved.
+
+**Read the named operations before you trust the "no-op" wording**, though —
+the message states a CAUSE, and a cause can be wrong. One release told users
+`drop-table <name>__dropped_<ts>` was a no-op when the DDL had worked perfectly:
+`VOLTRO_SOFT_DROP=1` had renamed the table, and the planner then read its own
+snapshot as one more undeclared table and proposed dropping it again. Fixed, and
+worth knowing as the shape to look for: an operation naming an object that the
+PREVIOUS operation created or renamed is a planner blind spot, not dead DDL. In the meantime the schema is unchanged and safe — nothing was
 half-applied, and no fingerprint was written, so `voltro db plan` still shows you
 the truth.
 

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

@@ -271,6 +271,22 @@ entirely. The downgrades are documented rather than hidden because the
 alternative to a stated escape hatch is deleting the marker — and a check whose
 only way out is to disable it gets disabled.
 
+### Gate CI on the audit having RUN, not on its silence
+
+`voltro doctor` can only run this audit if it can load your descriptors. When it
+cannot, it says so instead of claiming a pass:
+
+```
+•  serverOnly: NOT CHECKED — the app's descriptors could not be loaded (not a pass)
+   reason: Transform failed with 1 error:
+   src/queries/broken.query.ts:2:5: ERROR: Expected ";" but found "is"
+```
+
+`voltro doctor --json` carries the same answer as `serverOnly: { checked, reason?, leaks? }`.
+Assert on `checked` — an app that leans on `.serverOnly()` should treat a
+persistent skip as a failure, because a skipped audit and a clean one look
+identical from the outside.
+
 (`voltro check` does **not** run this audit. It has a live-api mode that has no
 access to your table definitions, and a rule that fires in one of its two modes
 would be worse than one that fires in neither.)

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

@@ -802,6 +802,31 @@ Each replica persists its progress in the **`_voltro_cdc_offsets`** table — on
 
 If the persisted offset has been purged (`err 1236`) or rejected after a failover, the reader jumps to the current binlog end and signals a resync so dependent subscriptions re-query rather than missing the gap.
 
+### A table the reader cannot decode
+
+`@vlasky/zongji` reads each event's column layout from the binlog's `Table_map` (fixed on disk) and compares it to a fresh `information_schema` fetch. A mismatch throws:
+
+```
+Table app.sessions schema changed between binlog event and metadata fetch:
+  the event has 9 columns, fetched metadata has 8
+```
+
+The usual cause on MariaDB is a **UNIQUE constraint on an unbounded text column**. MariaDB can only back that with a **HASH long-unique index**, and that index adds a hidden `DB_ROW_HASH_n` column to the InnoDB row — present in the binlog row image, absent from `information_schema.COLUMNS`. So the counts can never agree, and every write to that table trips it. Nothing is broken; the table is shaped that way.
+
+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.
+
+**The remedy is to bound the column:**
+
+```ts
+tokenHash: text().maxLength(64).unique()   // VARCHAR(64) → ordinary B-tree index
+```
+
+`ALTER TABLE … FORCE` does **not** help. The rebuild recreates the index and therefore recreates the hidden column — measured before and after: same column count both times. If you already tried it, that was not your mistake.
+
+A bounded unique is worth having anyway: it is also what keeps the key inside the index-size limits on every dialect.
+
+The other cause of the same message is a **backlog event that predates a migration** — the reader was down while a table changed. That one is unreplayable but transient: the reader skips to the current binlog end, signals a resync, and recovers. One warning, then it is over.
+
 ### Boot summary
 
 ```

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

@@ -217,6 +217,21 @@ Common uses:
 
 Returns the FINAL row in both cases (newly-inserted or pre-existing).
 
+### One conflict target, and only conflicts
+
+`conflictColumns` names ONE constraint. A duplicate on a *different* unique index is not something `insertIgnore` can resolve — it cannot know which existing row you meant — so it throws, naming the constraint that actually fired.
+
+It also throws when the insert was **rejected** rather than skipped. This matters most on MariaDB, where the statement lowers to `INSERT IGNORE`: that downgrades *every* error to a warning — foreign key, NOT NULL, CHECK, truncation — not just the unique violation the API models. So "no row was inserted" does not imply "a conflict happened", and reporting one as the other would turn a rejected write into a silent no-op: the row is not there and the caller is told it already was.
+
+```
+MysqlStore.insertIgnore: the insert into 'docs' was REJECTED, not skipped as a
+conflict. INSERT IGNORE downgrades every error to a warning, and the warning was:
+[1452] Cannot add or update a child row: a foreign key constraint fails …
+Nothing was written and nothing conflicted — fix the cause above.
+```
+
+The real cause comes from `SHOW WARNINGS` on the same connection, which is only attributable inside a transaction — so outside one the message says the constraint is unknown rather than guessing at it. Framework mutations are auto-transactional, so the common path has the cause.
+
 ## `updateMany` — one-statement bulk update
 
 ```ts

package/templates/agent-docs/routing.md

@@ -258,6 +258,19 @@ No naming trick is needed to keep something out of the router: the absence of th
 
 > Before this convention, every `.tsx` under `src/pages/` became a route, so a co-located component silently got a URL. That route rendered nothing and nobody visited it in dev; the failure surfaced at the first production build. If you are upgrading, `voltro update` renames your pages for you.
 
+## Two routes, one screen
+
+When two URLs must render the same component — a versioned path kept alive because devices in the field are configured against it, say — re-export it instead of copying it:
+
+```tsx
+// src/pages/v2/page.tsx → /v2, rendering exactly what / renders
+export { default, renderMode } from '../page'
+```
+
+`export { default } from '…'` satisfies the page contract: the module has a default export, it just did not declare it here. Forwarding `renderMode` alongside it is what keeps the two routes from drifting apart — the build follows the forward when it computes the render profile, so `/v2` is classified the same as `/`, not silently as `static`.
+
+`export { default as Screen } from '../page'` is the opposite: it renames the default away, leaving this module without one. That still fails the contract.
+
 ## Trailing slashes
 
 The canonical form is **no trailing slash** — always link with `<Link to="/about">`, not `<Link to="/about/">`.