@voltro/cli 0.21.0 → 0.22.1

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

@@ -1,4 +1,4 @@
-# What's new in 0.21.0
+# What's new in 0.22.1
 
 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,147 +7,65 @@ workaround for something that shipped two versions ago.
 
 BREAKING entries name a codemod; run `voltro update` to apply it.
 
-### ⚠ BREAKING
-
-- **@voltro/database, @voltro/runtime, @voltro/workflow, @voltro/voltro** — `text().maxLength(n)` on an EXISTING column now actually applies. It planned zero operations and reported "schema is up to date" while the live column stayed `longtext` — the documented remedy for MariaDB's hash long-unique was a silent no-op, which is worse than no remedy because you stop looking.
-
-  **The differ was not comparing lengths wrongly — it could not see them.** `maxLength` was absent from the schema snapshot entirely: it lived on the column definition, was read only when rendering CREATE DDL, and never reached the comparison. A consumer pinned the mechanism with a contrast: a column bounded AT CREATION was `varchar(64)` (DDL path, fine); one bounded afterwards stayed `longtext` (diff path, blind).
-
-  It is now carried on both sides — declared from the definition, live from introspection — compared as its own dimension, and rendered by the applier from the declared snapshot (a bare `text` tag would emit DDL that applies successfully and changes nothing, the silent no-op the applier's convergence check exists to catch).
-
-  **Three guards against the real risk, which is not missing a change but re-emitting one forever:**
-
-  - Only the VARCHAR family contributes a live length. MariaDB reports `character_maximum_length = 4294967295` for `longtext` and 65535 for `text`; postgres reports NULL. Reading a type's theoretical maximum would make a declared `text()` differ from its own live column on every boot. - Only `text()` columns are compared. `id()` renders as `VARCHAR(64)` on mysql/mariadb while its declaration carries no length — measured on live MariaDB while building this, and it would have emitted an ALTER for every id column, forever. - Never on sqlite (no length-enforced type), and never when the caller omitted the dialect — an unknown dialect behaves exactly as before this field existed.
-
-  Proven by round-trip suites against live MariaDB and live Postgres: the same schema re-plans to NOTHING, a length change produces exactly one operation on the right column, applying it lands the new width, and re-planning after that is clean.
-
-  Classification follows the nullability precedent: **widening is `safe`** (no data can be lost), **narrowing is `needs-backfill`** and says so, with the count query to run first. Narrowing is deliberately not blocked — blocking it would leave the remedy just as unusable as the silence did.
-
-  **Also: `_voltro_api_keys.hashedKey` is now bounded at 64**, since the value is `sha256Hex(token)` and narrowing it can never fail. The other four unbounded unique columns in framework tables are deliberately left alone, each with the reason at the column: `_voltro_kv.key` is the caller's own key, `idempotencyKey` comes from a user-supplied function, and the two workflow `executionId`s have no shape the framework guarantees. A narrowing ALTER that fails on existing data during a framework upgrade is a worse outcome than the index-size concern it would fix — and the MariaDB hash long-unique is harmless on those tables anyway, since `_voltro_*` is filtered out of the binlog reader's include list.
-
-  **Migration** — `voltro update` prints it (`0.21.0/01_maxlength-now-migrates`, `manual`, and it fires only for projects that declare a bound). Your source does not change; every `.maxLength(n)` already written keeps compiling. What changes is that the next `voltro db apply` — or a `voltro dev` / `voltro serve` boot with auto-migrate — emits ALTERs it used to skip. Run `voltro db plan` first: it prints exactly which columns would be altered without touching anything, and an empty plan means this does not affect you. Widening is `safe` and can simply run; narrowing is `needs-backfill` and the plan carries the count query to run before it.
-
-  *Why this is `BREAKING` and not `Fixed`: the API is compatible — nothing is removed, renamed or narrowed, and the same call compiles. But an upgrade now performs DDL against YOUR tables that the previous version silently skipped, and on MariaDB `longtext → varchar(n)` is a full table rebuild that locks. The DB-changes-need-no-codemod exemption is written for `_voltro_*` tables riding the differ; this reaches user tables, so the operator deserves the warning at `voltro update` time rather than in a changelog section they may never open.*
-
-### Added
-
-- **@voltro/cli, @voltro/voltro** — **`voltro schedule run <name>`** fires one scheduled job on demand, against `voltro dev` or `voltro serve`.
-
-  Asked for by a consumer whose nightly jobs correct business data and whose workaround was: edit the cron expression to a minute out, wait for the reload, put it back. "Run it once now and watch" is a normal thing to want.
-
-  **Most of it already existed, and that is why it took a measurement to find the gap.** `SchedulerHandle.fireNow` has been there, and so has `POST /_voltro/inspect/schedules/:name/fire`. What was missing was the way in: no CLI verb, and — the part that mattered — **`voltro serve` mounted no inspect surface at all**. Every `/_voltro/inspect/*` route existed only under `voltro dev`, which is the one place a nightly data-correcting job is not running.
-
-  So production now mounts it. Two things make that safe rather than a new attack surface, and both were checked rather than assumed:
-
-  - `handleInspectRequest` is **closed by default**: with no `VOLTRO_INSPECT_TOKEN` every request is 401 carrying the remedy, the compare is constant-time, and the token is never minted outside dev. Opening it is an operator's deliberate act. - Only the handlers production can answer TRUTHFULLY are wired. Everything else stays absent and replies "not configured" — an empty array would claim the app has no procedures. `inspectSchedules` is deliberately still absent: dev computes `nextFiringAt` and the EFFECTIVE coordination from its own boot closure, and reporting a guessed coordination mode to a post-deploy gate is worse than reporting nothing.
-
-  The manifest's `rpc` / `workflows` entries come from a builder both boot paths now share (`inspectEntries.ts`). They are the same facts on both sides, and a second hand-written copy of the descriptor→entry mapping is the shape this repo keeps paying for.
-
-  **A run id of `null` is reported as its own outcome**, not as success: the run was coordinated away — another replica holds the lock, or `onOverlap: 'skip'` found the previous run still going. Printing "ok" would claim work that never started.
-
-  **Also fixed, and it affects every command in the inspect family.** `fetchJson` collapsed a non-2xx into the body's `error` field alone, discarding `message`. The surface answers `{ error: <category>, message: <what happened> }`, so firing an unknown schedule printed "fire failed" while the server had said `scheduler.fireNow: unknown schedule "…"`, and a closed surface printed "unauthorized" while the body named the missing env var. It now prefers `message`, then `reason`, then `error` — fixed in the shared fetch rather than per command.
-
-  Verified end to end against `voltro-starter/apps/v-api-durable`: the fire returns a run id and the job's own output appears in the server log; an unknown name reports the server's reason; `--format json` round-trips.
-
 ### Fixed
 
-- **@voltro/database, @voltro/sql-postgres, @voltro/sql-mysql, @voltro/sql-sqlite, @voltro/sql-mssql, @voltro/voltro** — <!-- apiSurface: compatible — reasoned, not rubber-stamped. `attributionFields()` gained an OPTIONAL parameter and `withCapturedAttribution` is new. Both are additive, and it was CHECKED rather than assumed, because this repo has already paid once for a narrowing that read as additive: a zero-arg call still compiles, the value is still assignable to the old `() => …` type, and it still passes as a callback typed with the old shape. All three probed under `--strict`. Nothing was removed. -->
-
-  Write attribution is now CARRIED down the write path instead of re-read from the ambient async-local scope, so a connection-pool handoff can no longer strand a write's `traceId` / `subjectId`.
-
-  `routeEvent` read the identity with `attributionFields()`, and it runs after `await runPromise(...)`. `AsyncLocalStorage` propagates through continuations the current context CREATES; one scheduled by ANOTHER context — exactly what a pool handoff does when an acquisition queues — resumes with that other context's store. So under contention the write landed with the identity absent. Absent is a LEGAL value there meaning "no request behind this write", so the result does not look like a defect: it looks like a schedule. In a compliance trail that asymmetry is the whole problem, and it is why this is closed structurally rather than left as unlikely.
-
-  The value is captured ONCE at each public store method, before any await (`withCapturedAttribution`), and threaded explicitly through every `execute*` and into `routeEvent` — in all four dialect stores, including the transactional view, which is the path every framework mutation takes. The ambient scope is kept as a FALLBACK: a site that has not been threaded behaves exactly as before rather than worse, which is what made the change verifiable site by site.
-
-  **On what is and is not proven.** A pool handoff cannot be reproduced deterministically from a test — the resume context is the driver's choice. Two attempts are worth recording because both produced misleading green: a load-based regression test passed in isolation and failed in the full gate twice (a coin flip that also blocked releases), and a "deterministic" replacement that left the scope before the write finished PASSED against the unthreaded store, because the store re-enters its own scope internally. It proved nothing while looking like proof, so it was deleted.
-
-  What is proven: the pure semantics (`writeAttributionCapture.test.ts` — explicit wins over the ambient scope, explicit wins over ANOTHER request's scope, "no request" stays "no request", keys omitted rather than `undefined`), and the threading itself (`attributionThreadingParity.test.ts` — every store accepts and uses the carried value, no store still calls a bare `attributionFields()`, every transactional view carries it). The guarantee is structural, and it is stated that way rather than dressed up as a reproduction.
-
-  Raised by a consumer who could NOT reproduce the loss across 2700 writes at 96-way concurrency with every core saturated, and who asked for the fix anyway on the right grounds: *"impossible beats unlikely when the failure is invisible."*
-- **@voltro/database, @voltro/sql-postgres, @voltro/sql-mysql, @voltro/voltro** — <!-- apiSurface: compatible — `beginLocalWrite`, `endLocalWrite` and `resolveEchoAttribution` are new exports on `@voltro/database`; nothing was removed, renamed or narrowed. Checked rather than assumed, because this repo has already paid once for a narrowing that read as additive. -->
-
-  Under CDC, a plain `store.insert(...)` could deliver its change with `traceId` and `subjectId` ABSENT — not always, and more often the busier the process.
-
-  **The registration was racing the echo, and only winning on a margin.** The write path registers the request identity so the transport echo (a postgres NOTIFY, a mysql binlog row) can be re-united with it, and `pendingAttribution.ts` stated the ordering as a guarantee: the registration happens "BEFORE the transport can possibly echo it, because a NOTIFY fires at COMMIT". That is true INSIDE a transaction, where `routeEvent` runs before COMMIT. It is false for a plain write, whose statement commits ITSELF — the trigger fires while the write path is still awaiting the driver, and the registration lands afterwards. The echo has to make a round trip through the LISTEN/binlog connection, and that round trip was the only thing keeping the order right.
-
-  **Why it stayed hidden.** An unattributed event is a LEGAL event meaning "no request behind this write", so a lost identity is indistinguishable from a background job — there is no error, no warning, and nothing that looks wrong in a trace. It surfaced as one failing assertion in the full test suite, which is the only place this machine is loaded enough to flip the order, and it passed on every isolated re-run.
-
-  **Closed by construction, not by widening the margin.** A store now brackets each non-transactional write (`beginLocalWrite` / `endLocalWrite`) and delivers echoes through `resolveEchoAttribution`. An echo arriving while a write to that table is mid-registration is HELD until that write has had its chance, then answered. Held echoes keep arrival order — a subscriber seeing an update before the insert it updates would be worse off than one missing a `traceId` — and a write that never registers releases the table after a bound rather than parking its stream.
-
-  Three narrowings, each deliberate:
-
-  - **Only under `cdc`.** Nothing is injected in `inline` mode, so there is no echo to order against. - **Only non-transactional writes.** `transactional()` registers before COMMIT already; bracketing it would hold OTHER replicas' echoes for the length of the transaction to fix a race that path does not have. Asserted, so the narrowing is on the record rather than something a later reader "fixes". - **A remote write is still never attributed.** The barrier may delay an answer; it must never invent one. Nothing is registered locally for another replica's write, and that stays true while echoes are held.
-
-  **Both CDC stores had a hand-written copy of the claim-and-emit tail**, which is the shape of the previous three attribution defects in this package. The decision now lives in one function both call, and `echoBarrierParity.test.ts` fails if either store claims for itself, leaves a public write outside the bracket, or brackets the transactional path. The ordering itself is proven against the primitive (`pendingAttribution.test.ts`) — a live suite cannot force it, because the resume point is the driver's choice, and the four barrier tests were verified to go red against the pre-fix behaviour before being trusted.
-
-  Also fixed: `mysql`'s `updateMany` / `deleteMany` route their events after their transaction commits, so they carried the same race despite not going through the per-row write path. They are bracketed too.
-- **@voltro/cli, @voltro/voltro** — `voltro build` could fail to build the **start bundle** with `Could not resolve "@voltro/cli/startEntry"`, degrading `voltro start` to the slower per-module boot. The serve bundle carried the identical latent failure.
-
-  Both bundles generate an entry importing a narrow CLI export and build it with `absWorkingDir: <app root>` — so esbuild resolved that bare specifier from the APP's `node_modules`. Under strict pnpm the app has `@voltro/cli` there only if it DECLARES it, and an app normally depends on `voltro` / `@voltro/web` and gets the CLI transitively. The CLI now resolves its own entry from `import.meta.url` and hands esbuild an absolute alias.
-
-  Same shape as the tsx bug (`tsxLoader.ts`): a package that is OUR dependency, resolved from the user's directory, invisible under strict pnpm. Same answer — the CLI knows where it lives, so it stops asking the app.
-
-  **The published export was not the problem.** It is present in the tarball — checked against the real 0.20.1 and 0.20.2 packages, `./startEntry` → `./dist/startEntry.js`, file included. Only resolution failed, which is why re-adding the export would have changed nothing.
-
-  This monorepo hoists everything, so the bare specifier resolves here and the build passes with or without the alias. The test therefore asserts the alias directly rather than inferring it from a green build — the hoisted layout is exactly what hid the strict-pnpm failure in the first place.
+- **@voltro/cli** — **Two things a QUERY could not do that a mutation beside it could — and a redirect that answered 500 in dev and 303 in production.**
 
-  **Also pinned, after a wrong turn worth recording.** A consumer reported that the framework provides no Suspense boundary, so any suspend during SSR throws. The obvious repair — a root `<Suspense>` — was implemented, measured, and REVERTED:
+  ### `useAggregate` in a subscription handler: `Service not found`
 
-  - With a root boundary, a page that THROWS answered **200** with `<template data-msg="Switched to client rendering">`. React downgrades an errored boundary to client rendering, which silently undid the hard failure shipped moments earlier. - Without one, a suspending page renders fine anyway: `renderToPipeableStream` treats the root as an implicit boundary, so a suspend delays the shell flush rather than failing.
+  The documented way to read an aggregate from a handler (`useAggregate(def).read(...)`) failed at runtime with `Service not found: @voltro/AggregateRegistry`, on every delivery.
 
-  So the reported problem does not exist on the streaming path, and the obvious fix for it breaks something that does. Both halves are now fixtures with assertions side by side (`ssr-suspends` must render, `ssr-throws` must 500) — adding a root boundary flips the second, and that pair is what makes it visible instead of shipping it. Docs corrected in both languages, including the two places a suspend genuinely is unsupported (`renderToString` behind static prerender, and the client render), neither of which is the framework's choice.
-- **@voltro/cli, @voltro/voltro** — <!-- apiSurface: compatible — `CliRuntime` keeps its exported signature and its behaviour (NodeContext + logger); only `runCli`'s internal composition changed. `loggerConfig` is module-private. -->
+  Both boot paths hand the subscription/query executor a `provideEffect` callback, and each had written its own — smaller — layer set:
 
-  Every one-shot `voltro` command printed each log line TWICE. Measured on `voltro agents-md`: 76 lines for 38 events.
+  | path | provided to an Effect-returning query | |---|---| | `voltro dev` | store + actionBase (**no** `mergedUserLayer`) | | `voltro serve` | store, and nothing else | | either, handler path | the full set |
 
-  `runCli` installed two loggers. It provided `CliRuntime` (which contains a `LoggerLayer`) to the program, then provided a second `LoggerLayer` around the `matchCauseEffect` wrapping it — so the program ran inside both. Two `LoggerLayer`s in one fiber do not compose the way the name suggests: `LoggerLayer` is `Logger.replace(Logger.defaultLogger, …)`, which removes the DEFAULT logger and adds its own. The second one finds no default left to remove, the removal is a no-op, and the add still happens. Replace composes as replace only against the default — never against another replace.
+  So a query could not `yield*` the aggregate registry, the cache, the kv store, a plugin's service or the app's own `layers:` — while a mutation in the same app could. `useAggregate` was one symptom of the set being wrong, not a bug of its own.
 
-  The duplicates were distinguishable only because the outer layer was built without the command's `defaultScope`, so half the output carried `scope` and half did not. Had both been configured identically the output would have been byte-identical pairs, which is a good deal harder to notice than a stray field.
+  The cost the reporter measured is worth repeating: a subscription whose delivery fails renders NOTHING, so their working-time card showed `00:00` — no error, no empty state. Silence is the worst failure shape a data path has.
 
-  **The failure branch is the half that survives a partial fix**, and it did. Moving the second layer from around `matchCauseEffect` onto the error handler repairs the success path and leaves the failure path doubling, because that branch runs while the program's scope is still open and INHERITS its logger. Verified by measuring three shapes rather than reasoning about scopes: handler-provides → 2 lines, handler-inherits → 1, provide-once-outermost → 1.
+  Both paths now provide the same set, and `serveApi` reaches it through the single helper its handler path already used (it had two, one complete and one not).
 
-  The last is what shipped. The logger is a FiberRef, not a service the program requires, so it is provided ONCE at the outermost boundary and the program gets only `NodeContext`. That covers both branches by construction, rather than by the handler happening to still be inside a scope that has not closed yet. `CliRuntime` is unchanged and still used by `runCliMain`, which provides it once and never had the problem.
+  **Why their tests could not see it**, in their words: `@voltro/testing` supplies `aggregateRegistryLayer(...)` and the existing example uses it, so the suite provided exactly what production lacked — *"wenn der Layer im Test nötig ist und in der Laufzeit fehlt, ist er genau der falsche Default."* That is the sharpest line in the report. A harness that hands the code under test something the runtime does not is a second implementation, not a harness. The runtime supplies it now; the layer stays available for tests that genuinely stand alone.
 
-  Guarded by `cliRuntime.test.ts`, which asserts the COUNT (any second provision doubles it regardless of what it logs) and that every line carries the command scope. It was checked against the reverted fix in both of its shapes before being trusted. Its capture spies on stdout AND stderr, deliberately: diagnostics route to stderr by level, and a stdout-only capture reported zero lines for the failure path — reading as "nothing was logged" when the truth was "logged on the other stream", which had the test accusing the fix it was written to protect.
-- **@voltro/cli, @voltro/voltro** — Three corrections to the `db drift` baseline shipped in 0.20.2, all reported by the consumer who verified the fix — and all of them defects in that fix rather than in older code.
+  ### A loader that throws `RedirectError` answers 303 in dev too
 
-  **1. The first `db drift` after upgrading CRASHED.** `liveFingerprint` is a new column and does not exist until a `db apply` adds it, so naming it in the ledger read died on `SqlError: Failed to execute statement` instead of reaching the "no baseline yet" branch written for exactly that moment. The documented sequence was `0 → apply → clean`; the real one was `crash → apply → clean`, with the crash landing in the first CI run after an upgrade. Proven by dropping and re-adding the column: absent → exit 1 and a driver error, present → exit 0 and the honest message. The read is now `SELECT *`, which cannot go stale against an older ledger.
+  `agent-docs/routing.md` promises a 303 with `Location`. `voltro start` did it; `voltro dev` caught the same throw as a render failure and answered **500 with no `Location`**.
 
-  **2. A no-op `db apply` established no baseline.** The baseline is written per applied plan row, so an already-current schema produced none — and "cannot compare" then persisted indefinitely rather than for one run, for any app whose schema was current when it upgraded. A no-op apply now backfills the latest row's `liveFingerprint` instead of inserting a history entry for a migration that did not happen.
+  The divergence was written down as intended — *"each path maps it onto its own convention"* — and recording it is what let it stand. A redirect is CONTROL FLOW. Two renderers that disagree about that disagree about what the app does, and the one they disagreed on is the one every developer and every dev-environment probe hits first. It cost the reporter a rollout: a readiness probe walked a redirecting route, got the 500, and the deployment never became ready.
 
-  **3. "No baseline" gets its own exit code: 3.** Previously it exited 0, so a CI gate could not distinguish "compared and matched" from "did not compare" — and on a stable schema the second could persist forever. The consumer named that as their reason for NOT adding a drift gate: it would pass vacuously, which is the failure this whole thread is about. Now `0` = matched, `3` = no baseline, `4` = diverged.
+  One mapper (`loaderControlResponse`) now answers for both, brand-checked rather than `instanceof` because the error crosses a bundle boundary — and since the CLI cannot import `@voltro/web`, a test reads that package's source so a renamed brand cannot silently put dev back to 500.
 
-  **And the SQL-error reporter added in the same release did not work on this path.** It walked `.cause`, and an `Effect` `FiberFailure` has none — its cause hides behind `Symbol(effect/Runtime/FiberFailure/Cause)`, with only `stack`, `message` and `name` as own keys. So the helper returned `undefined` and not even its "no statement attached" fallback fired. The consumer reproduced that against an empty database and checked field by field; all absent.
+  `NotFoundError` → 404 comes with it, for the same reason.
+- **@voltro/client, @voltro/cli** — **A hot reload no longer takes every page down, and a route that owns the whole origin says so.**
 
-  The reason the tests missed it is worth recording: every fixture was a hand-built object WITH a `.cause` — the shape assumed, not the shape the runtime produces. The suite now builds a real `FiberFailure` through `Effect.runPromise`, and the walk unwraps the symbol and flattens the `Cause` tree (`Fail`/`Die`/`Sequential`).
+  ### `defineStore` and module re-evaluation
 
-  Their note on the irony is fair and is the reason this is one entry rather than two: defect 1 above IS the "next DB-shaped error in your CI" that the reporter existed to make readable, and it arrived as a bare wrapper plus a driver stack. With the statement printed it would have named the missing column immediately.
+  The duplicate-name guard keyed on the NAME alone and threw. It is right about the danger — two stores sharing a name silently share state — and wrong about one case: a module RE-EVALUATING, which is exactly what a hot reload does.
 
-  **A FOURTH copy of both defects was found in `voltro dev`'s migrations inspect endpoint, and it was the worst one.** It carried the same postgres-only `::text` casts, wrapped in `orElseSucceed(() => [])` — so on every non-postgres dialect the syntax error became an EMPTY history rather than a failure: the devtools migrations panel showed nothing, and with no history row the drift verdict came out `false`. A silent, permanent "no drift" on every mysql/mariadb/mssql/sqlite app. It also compared the declared hash against a live one, exactly like the CLI did.
+  A consumer measured the cost on one running dev server:
 
-  Both are fixed there too, and `ledgerReadPortability.test.ts` now fails if any query touching `_voltro_migration_plans` grows a `::type` cast again. Three copies were fixed in one change and the fourth was missed in the same change, which is the argument for the test rather than another paragraph in a maintainer note.
-- **@voltro/cli, @voltro/voltro** — `voltro dev` served a client-only shell — with a **200** — whenever a `renderMode: 'ssr'` page failed to render on the server. It now answers 500 with the cause, exactly as `voltro start` does.
+  | | status | bytes | |---|---|---| | fresh boot | 200 | 43629 | | touch any `*.store.ts` | 500 | 2328 | | three further requests | 500 | — |
 
-  **Reported as "voltro dev does not SSR". It does**, and has since before 0.20.0 — the middleware, its intent stated in a comment ("mirroring what `voltro start` does in production"), is an ancestor of every 0.20.x tag. What the reporter saw was the masking: their pages suspended during the server render (a lazily-loaded i18n catalog above any Suspense boundary), all 225 degraded to Vite's SPA shell, and an empty `<div id="root">` is indistinguishable from a framework that never server-renders. Their conclusion was the only one the evidence supported.
+  One edit to a store — or to anything importing one — took all 225 of their pages down for the rest of the session, with no self-recovery. Their workaround memoised registrations by name on `globalThis`, which works and costs the thing HMR is for: editing a store's initial state stopped taking effect until a restart.
 
-  **The 200 is the part that mattered.** The same render is a hard 500 under `voltro start`, so those pages were down in production while dev reported success — the inverse of the usual "works in dev, breaks in prod", and worse, because nothing prompts you to look. Measured before the fix: `HTTP 200`, no `x-voltro-rendered-by` header at all, and the thrown error present in the dev log but nowhere in the response.
+  Registration is keyed by ORIGIN **and evaluation PASS** now — the calling module's stack frame, without `line:column` so that shifting the call down a line is still the same origin. The same module may redefine its own store and gets the LIVE handle back, so state survives the edit. A DIFFERENT module still throws, and the error now names both files, because "rename one" is only actionable if you know which two to look at.
 
-  Three sites did this (both streaming `onShellError` handlers and the outer catch); all three now fail through one helper. The pattern was already in the file — the `isDeferralNotSupported` branch refuses rather than degrades and says why in the same words ("falling through would leave the developer with an unstyled page and a log line, which is exactly the silent degradation the hard error exists to prevent"). One of the removed fallbacks sat directly under a comment stating that falling through would mask the bug.
+  Origin alone was not enough, and the existing suite caught it: two `defineStore('x')` calls in ONE file share an origin, so origin-keying merged them — the exact silent state-sharing the guard exists for. A module body runs synchronously, so two registrations in one file land in the same pass; a hot reload re-evaluates in a LATER tick. Same origin AND same pass is a collision; same origin, later pass is a reload.
 
-  Dev puts the cause and stack in the response body; production keeps its bare `server error`, so a stack never reaches a public response. That is a difference in what the failure says, never in whether it fails.
+  (`line:column` would separate those two as well, and was rejected: stripping the position is what lets an edit ABOVE a `defineStore` call shift it down a line without reading as a new origin — and that edit is the common case this is about.)
 
-  **Also fixed, found while reproducing it: a page added while `voltro dev` runs was never server-rendered.** The middleware matched against a route table built once at boot, so a new page missed matching entirely and returned before its module was ever loaded — Vite's SPA shell, 200, and *no log line at all*, because the middleware never ran. The page tree the middleware reads is now refreshed by the same regeneration that rewrites the route table (`dirs` too, or a layout added after boot would be invisible to the spa-shell decision).
+  When the runtime gives no usable stack, it behaves like a collision rather than a redefinition: if the two cannot be told apart, silently sharing state is the worse outcome, and that is what the guard exists for.
 
-  Both are covered by `webDevSsrLayoutLoader.test.ts` against a real dev server: `/ssr-throws` must answer 500 + `x-voltro-rendered-by: ssr-dev-failed` + the cause and must never contain the empty shell, and a page written while the server runs must be server-rendered without a restart. Each assertion was verified red against its own reverted fix — separately, because the first failure aborts the test and would have left the second unproven.
+  ### A route whose first segment is dynamic
 
-  One thing this does NOT change: the framework still provides a Suspense boundary only for its own deferral (`<Await>`), not a blanket one at the root. Code that suspends outside it needs a boundary you mount yourself. That is now documented next to the failure behaviour, since a hard 500 is how you will meet it.
+  `voltro doctor` reports a page route like `[id]/[playerCode]` — its FIRST segment dynamic, so it answers every two-segment URL on that origin, `/api/health` included.
 
-### Internal (no consumer-facing effect)
+  The pattern is not a bug; that is what it means. It is invisible until something requests such a URL, and then the page renders, its loader runs, and the failure reads as an application error rather than as a route claiming a path nobody meant it to. Advisory, and scoped so it stays readable: `orders/[id]` is not flagged — a dynamic segment under a literal one is bounded by that literal.
 
-- **@voltro/cli** — Maintainer notes only — no shipped behaviour changes.
+  The same report described this as REST routes losing to page segments. They do not compete: `restRoutes` are served by the API server and pages by the web server, on different ports. The three-segment probe paths they adopted worked because the pattern is two-segment, not because precedence changed.
 
-  `mssqlClusterPatch.ts`'s header said the `@effect/cluster` patch covers "two mssql-only bugs" (it is four: the `deliver_at` INT-overflow, the MERGE…OUTPUT with correlated sub-SELECTs, `FOR UPDATE`, and `USING (SELECT * FROM (VALUES …))`) and implied that a version bump needs nothing but a re-key, because 0.59.0 → 0.60.0 happened to apply unchanged. On 0.60.2 the same patch fails on 3 of its 6 files — upstream refactored `SqlMessageStorage` and moved the context the hunks match on. A bump can require REGENERATING the patch.
+  ### Two items from the same report were already shipped
 
-  The regeneration recipe now lives in `packages/sql-mssql/CLAUDE.md`, together with the two measurements that produced confidently wrong answers while working this out: reading an already-patched `node_modules/.pnpm/*patch_hash=*` copy and concluding upstream had fixed it, and un-patching one of the several installed copies and concluding the patch was not load-bearing. Both look like evidence.
+  Both were measured against 0.20.1 and landed in **0.21.0**, so they need no change — only saying so:
 
-  Also recorded there: verify by BREAKING it. `git apply --check` proves the patch lands, not that it still fixes anything. Un-patched, the mssql cluster suite fails with `Incorrect syntax near ')'`; patched, 5/5 against the live fixture.
+  - `Could not resolve "@voltro/cli/startEntry"` during the start-bundle build → fixed by `resolve @voltro/cli/{start,serve}Entry from the CLI, not the app root`. It is the same class as the `tsx` bare-specifier bug: a specifier for a package the APP never declared is invisible from the app root under strict pnpm. - `voltro schedule run <name>` exists, with `--process`, `--trigger manual|external` and `--url`. Note it POSTs to a mutating inspect endpoint, so it now needs `VOLTRO_INSPECT_WRITE_TOKEN` outside dev.

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

@@ -11,16 +11,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/ai": "0.21.0",
-    "@voltro/cli": "0.21.0",
-    "@voltro/database": "0.21.0",
-    "@voltro/env": "0.21.0",
-    "@voltro/protocol": "0.21.0",
-    "@voltro/runtime": "0.21.0",
+    "@voltro/ai": "0.22.1",
+    "@voltro/cli": "0.22.1",
+    "@voltro/database": "0.22.1",
+    "@voltro/env": "0.22.1",
+    "@voltro/protocol": "0.22.1",
+    "@voltro/runtime": "0.22.1",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.21.0",
+    "@voltro/testing": "0.22.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

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

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

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

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

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

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

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

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

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

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

@@ -10,17 +10,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.21.0",
-    "@voltro/database": "0.21.0",
-    "@voltro/env": "0.21.0",
-    "@voltro/plugin-multitenancy": "0.21.0",
-    "@voltro/plugin-storage": "0.21.0",
-    "@voltro/protocol": "0.21.0",
-    "@voltro/runtime": "0.21.0",
+    "@voltro/cli": "0.22.1",
+    "@voltro/database": "0.22.1",
+    "@voltro/env": "0.22.1",
+    "@voltro/plugin-multitenancy": "0.22.1",
+    "@voltro/plugin-storage": "0.22.1",
+    "@voltro/protocol": "0.22.1",
+    "@voltro/runtime": "0.22.1",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.21.0",
+    "@voltro/testing": "0.22.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-data-advanced/package.json

@@ -11,17 +11,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.21.0",
-    "@voltro/database": "0.21.0",
-    "@voltro/env": "0.21.0",
-    "@voltro/plugin-governance": "0.21.0",
-    "@voltro/plugin-multitenancy": "0.21.0",
-    "@voltro/protocol": "0.21.0",
-    "@voltro/runtime": "0.21.0",
+    "@voltro/cli": "0.22.1",
+    "@voltro/database": "0.22.1",
+    "@voltro/env": "0.22.1",
+    "@voltro/plugin-governance": "0.22.1",
+    "@voltro/plugin-multitenancy": "0.22.1",
+    "@voltro/protocol": "0.22.1",
+    "@voltro/runtime": "0.22.1",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.21.0",
+    "@voltro/testing": "0.22.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -11,17 +11,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.21.0",
-    "@voltro/database": "0.21.0",
-    "@voltro/env": "0.21.0",
-    "@voltro/plugin-multitenancy": "0.21.0",
-    "@voltro/protocol": "0.21.0",
-    "@voltro/runtime": "0.21.0",
-    "@voltro/workflow": "0.21.0",
+    "@voltro/cli": "0.22.1",
+    "@voltro/database": "0.22.1",
+    "@voltro/env": "0.22.1",
+    "@voltro/plugin-multitenancy": "0.22.1",
+    "@voltro/protocol": "0.22.1",
+    "@voltro/runtime": "0.22.1",
+    "@voltro/workflow": "0.22.1",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.21.0",
+    "@voltro/testing": "0.22.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-feature-flags/package.json

@@ -12,18 +12,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.21.0",
-    "@voltro/database": "0.21.0",
-    "@voltro/env": "0.21.0",
-    "@voltro/plugin-flags": "0.21.0",
-    "@voltro/plugin-multitenancy": "0.21.0",
-    "@voltro/protocol": "0.21.0",
-    "@voltro/runtime": "0.21.0",
-    "@voltro/sql-postgres": "0.21.0",
+    "@voltro/cli": "0.22.1",
+    "@voltro/database": "0.22.1",
+    "@voltro/env": "0.22.1",
+    "@voltro/plugin-flags": "0.22.1",
+    "@voltro/plugin-multitenancy": "0.22.1",
+    "@voltro/protocol": "0.22.1",
+    "@voltro/runtime": "0.22.1",
+    "@voltro/sql-postgres": "0.22.1",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.21.0",
+    "@voltro/testing": "0.22.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -12,17 +12,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.21.0",
-    "@voltro/database": "0.21.0",
-    "@voltro/env": "0.21.0",
-    "@voltro/plugin-audit": "0.21.0",
-    "@voltro/plugin-governance": "0.21.0",
-    "@voltro/protocol": "0.21.0",
-    "@voltro/runtime": "0.21.0",
+    "@voltro/cli": "0.22.1",
+    "@voltro/database": "0.22.1",
+    "@voltro/env": "0.22.1",
+    "@voltro/plugin-audit": "0.22.1",
+    "@voltro/plugin-governance": "0.22.1",
+    "@voltro/protocol": "0.22.1",
+    "@voltro/runtime": "0.22.1",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.21.0",
+    "@voltro/testing": "0.22.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -11,17 +11,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.21.0",
-    "@voltro/database": "0.21.0",
-    "@voltro/env": "0.21.0",
-    "@voltro/kv": "0.21.0",
-    "@voltro/plugin-multitenancy": "0.21.0",
-    "@voltro/protocol": "0.21.0",
-    "@voltro/runtime": "0.21.0",
+    "@voltro/cli": "0.22.1",
+    "@voltro/database": "0.22.1",
+    "@voltro/env": "0.22.1",
+    "@voltro/kv": "0.22.1",
+    "@voltro/plugin-multitenancy": "0.22.1",
+    "@voltro/protocol": "0.22.1",
+    "@voltro/runtime": "0.22.1",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.21.0",
+    "@voltro/testing": "0.22.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }