@voltro/ui-shadcn 0.72.0 → 0.74.0

package/CHANGELOG.md

@@ -39,6 +39,221 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.74.0] — 2026-09-18
+
+### Added
+
+- **An app can assert it still agrees with the framework** — `@voltro/cli`
+
+  `@voltro/cli/contract` publishes the three things an app needs to check itself against the framework's own implementation rather than against a copy of it:
+
+  - `assertBrowserSafeRpcGroup(path)` — the generated rpc group is loaded value-level by the browser, so a descriptor that transitively imports a server-only module drags the schema graph into the client bundle. `voltro dev` runs this at boot; until now an app could not ask the same question from its own suite, before a deploy. - `observeInspectResponse(path, response, fleetSize)` — the envelope every inspect answer is wrapped in. An app whose output schema decodes an inspect payload is making a claim about this function's shape, and a test that rebuilds the envelope by hand asserts against its own reconstruction instead. - `buildClusterInspect(deps)` — the cluster snapshot as the framework assembles it, for the same reason.
+
+  ```ts
+  import { assertBrowserSafeRpcGroup } from '@voltro/cli/contract'
+  
+  it('keeps the generated rpc descriptor graph browser-safe', async () => {
+    await expect(assertBrowserSafeRpcGroup(rpcGroupPath)).resolves.toBeUndefined()
+  }, 30_000)
+  ```
+
+  One consequence is worth stating rather than leaving to be discovered: `observeInspectResponse` is default-deny over its route-scope table — a path with no declared scope is answered with a 500 naming the fix, not wrapped bare — and publishing it makes that part of the public promise.
+
+  The surface is for asserting, not for building on: nothing in it mounts a route, serves a request or writes a file.
+
+### Fixed
+
+- **A file migration records the body that ran, so a later edit to it is visible** — `@voltro/database`, `@voltro/cli`
+
+  An applied `migrations/<timestamp>_<slug>.ts` file was looked up by its id and nothing else:
+
+  ```sql
+  SELECT id FROM _voltro_migration_plans WHERE source = 'file'
+  ```
+
+  So its body could be rewritten after it had been applied and nothing would say so. The file then reads like a description of what ran against the database, and is not one — which is the state every other migration tool checks for, and which the framework's own `*.migration.ts` runner has recorded a hash for and warned about since it shipped. The file runner wrote an empty string into the same column.
+
+  It records the body hash now, and reports a body that no longer matches:
+
+  ```
+  file migration: the body on disk is not the one that was applied —
+  the file no longer describes this database  id=20260915_054800_vacation_days
+  ```
+
+  Two things about it are deliberate:
+
+  - **A row written before this shipped carries an empty hash, and that reads as "cannot compare", never as "changed".** The other way round, the first run after upgrading would report drift for every migration a database has ever applied — the loudest possible way to make a true warning ignorable. - **It warns; it does not fail.** Nothing can be re-run to fix it: the change is in the database, and the edit is usually deliberate. What was missing is that anyone could tell.
+
+  The hash is one function shared by both runners rather than spelled twice — a hash is only comparable to one computed identically, and two definitions of "the hash of this file" become two answers the moment either is touched.
+- **A new unique column arrives with its unique, and a part-applied schema says so** — `@voltro/database`
+
+  Adding a NOT NULL column that declares `.unique()` produced a migration that executed without error and then failed its own convergence proof:
+
+  ```
+  applyPlan: the migration did not converge. 14 operation(s) were executed without
+  error, but re-planning against the live schema still finds 1:
+    - add-unique _voltro_ai_usage.receiptKey
+  ```
+
+  The second run succeeded with exactly that one operation, because by then the column existed.
+
+  A column-level `.unique()` is a column flag, not a snapshot index, so a unique appearing on an EXISTING column is caught by the column-change comparison. A column the same plan CREATES has no live side to compare against, which leaves the add-column emitter as the only thing that can carry the flag — and it read the flag on one of its three branches. A nullable add rendered `UNIQUE` inline; the NOT NULL branches (with a default, or with a backfill) dropped it. So the column was created, filled and enforced, the unique was never created, and the re-plan proposed it.
+
+  The three-step add cannot render `UNIQUE` inline — the column is NULL for the length of the backfill — so the emitter now reports the unique as still owed and the applier creates it after the NOT NULL enforcement, through the same per-dialect statements `add-unique` already uses. It is reachable without `.backfill()`: a NOT NULL column with a default and a unique lost it the same way.
+
+  The failure message changed too, and independently. It ended with *"the schema is unchanged and safe"* in every case, while the applier already knew — twenty lines earlier, on its other failure path — whether the dialect applies a plan atomically. On postgres and mssql the sentence was true; on mysql and mariadb it was not, and a deployment that read it went looking for an untouched schema and found thirteen of fourteen operations committed. It now states which of the two situations it is, and on a non-atomic dialect lists the operations that took effect.
+- **Change-trigger drift is measured against the name postgres stores** — `@voltro/database`
+
+  On postgres, a table whose name carries an uppercase letter — or is long enough to reach the identifier limit — was reported as having no change trigger on every boot, while its trigger was present and firing. `voltro db apply` then re-installed every one of them, every run, and the count never went down:
+
+  ```text
+  db apply: installing change triggers on 71 table(s)
+  db apply: change triggers converged (214 statement(s))
+  ```
+
+  `CREATE TRIGGER` is emitted with the trigger identifier unquoted — the table name beside it IS quoted, which is what made the asymmetry easy to miss — so postgres stores the name the way it stores any unquoted identifier: downcased, then clipped to 63 bytes. Measured on postgres 17.10:
+
+  ```text
+  activityEvents                     ->  framework_changes_activityevents
+  aVeryLongTableNameOverTheLimit…    ->  framework_changes_averylongtablenameoverthelimit… (63)
+  ```
+
+  The drift detector compared `pg_trigger` against the name the framework DERIVES, so the two could never match for an affected table. It reads the stored form now. The emission is deliberately unchanged: `CREATE TRIGGER` and its `DROP TRIGGER IF EXISTS` fold identically and therefore already agree with each other, so quoting only the create would have left every existing database's trigger undroppable and added a second one beside it.
+
+  The truncation half is reachable with no uppercase letter at all, so folding alone would have fixed the reported case and left the other.
+
+  The comparison also asks which RELATION carries a trigger, rather than matching on the name alone. Trigger names are unique per table in postgres, not per schema, so two tables whose names differ only in case legitimately carry the same trigger name — and keyed by name alone, one table's trigger answered for the other's. Folding without that would have traded a table wrongly reported as untriggered for a table wrongly reported as triggered, which is the same defect in the more dangerous direction.
+- **voltro db status reports both migration conventions** — `@voltro/cli`
+
+  Run against the same project, seconds apart:
+
+  ```text
+  voltro db status .   ->  no migrations found
+  voltro db files  .   ->  no pending file-based migrations (4 already applied)
+  ```
+
+  Neither answer was about the database's state. The two commands walk for different files: `db status` (with `db migrate` and `db rollback`) walks `*.migration.ts` anywhere under the project root, while `db files` — and `db apply`, and the boot path — walks `migrations/<timestamp>_<slug>.ts`. Both conventions are supported; only one of them was ever reported.
+
+  `no migrations found` is the worst available answer for the other one. It is not a warning that invites a second look, it is a statement that there is nothing to see, and it was being given to a project with four applied migrations sitting in the directory the same CLI had just listed.
+
+  `db status` now reports both, marks a file migration as `applied` or `pending`, and flags one whose body no longer matches what was recorded when it ran. It says `no migrations found` only when BOTH conventions are empty — and a database it cannot reach is not reported as "no migrations" either, which would be the same false statement one layer along.
+
+  The count in `db files` was right, for the record: `4 already applied` counts the migrations found in the ledger, not the ones a `skipUnless` precondition skipped. Those are recorded as applied with `skipped: <reason>` in their notes, which is a different thing that the same word describes.
+- **A migration's truncate tolerates a missing table and emits no per-row event** — `@voltro/database`
+
+  `ctx.schema.truncate(table)` was the one schema operation that did not look at the live schema first. Its neighbours — `dropTable`, `dropIndex`, `dropColumn`, `dropForeignKey`, `renameColumn` — all answer `already-absent` when there is nothing to do, and the documentation states that as a property of every schema operation. So a migration run against a database that predates the table died on the truncate while the `dropForeignKey` on the line above it, naming the same table, had answered `already-absent`:
+
+  ```text
+  ctx.schema.dropForeignKey('timers', 'roadmapId')  ->  already-absent
+  ctx.schema.truncate('timers')                     ->  SqlError
+    Table 'app.timers' doesn't exist  (ER_NO_SUCH_TABLE / 1146 / 42S02)
+  ```
+
+  It returns `'applied' | 'already-absent'` now, like the rest.
+
+  The statement it runs changed too, and that half is the more expensive one. The truncate went through the store's set-based delete, which is `DELETE … WHERE … RETURNING *` **by design**: the rows it returns are the old-images the store fans out as one change event per row. Correct for an application write, wrong for a truncate — emptying a large table pulled every row back to the client and notified every subscriber once per deleted row. It now issues a plain `DELETE FROM <table>` through the migration's own client: no rows returned, no per-row event.
+
+  `DELETE FROM` rather than `TRUNCATE` is unchanged and deliberate — it is a data statement on every dialect, so it stays inside a transactional migration, where `TRUNCATE` (DDL on the MySQL family and SQL Server) would commit it.
+
+### Internal (no consumer-facing effect)
+
+- **A test's fixture probe cannot outlive its test** — `@voltro/cli`
+
+  `frameworkSourceTypo.integration.test.ts` writes a query descriptor into the shared `memory-api` fixture for a few seconds and removes it again. Another task generates from that same fixture — `web-form-post`'s typecheck runs `voltro codegen ../memory-api` — and codegen emits one import per query file it finds. A codegen landing inside that window bakes the probe into `rpcGroup.generated.ts`; the probe is then deleted, and the generated file is left importing a module that no longer exists.
+
+  Measured rather than reasoned: plant a probe and run `voltro codegen .` and seven references appear; delete the probe and all seven remain. What the next reader gets is `TS2307: Cannot find module './queries/<probe>.query'` in a generated file, with nothing pointing at where it came from.
+
+  The artefact is gitignored, which is what makes it silent — `git status` reports a clean tree over a poisoned one, so the usual check answers the wrong question.
+
+  Two changes, for the two ways the residue survives. The `finally` now restores the fixture's generated files from a snapshot taken before the probe was written, so a concurrent codegen is undone along with the probe. And the suite sweeps leftover probe files at start, because a killed process never runs a `finally` — this file already records a saturated machine having the OS kill its child.
+
+---
+
+## [0.73.0] — 2026-09-17
+
+### Added
+
+- **Typed writes on the Effect channel — the row check and StoreError compose** — `@voltro/runtime`
+
+  `insertRow`, `insertManyRows`, `upsertRow`, `upsertRowOutcome` and `insertIgnoreRowOutcome` check their payload against the table — a required column the row omits is a compile error at the call site — and return a `Promise`. `EffectStore` carries every one of those operations on the typed error channel and takes `(table, row)` with an unchecked `Row`.
+
+  So the two properties excluded each other. A handler that wanted the row checked gave up `StoreError`; one that wanted the channel passed an unchecked row. There was no third option: wrapping a typed helper in `Effect.promise` runs the write outside the Effect and discards exactly the channel at issue.
+
+  Five helpers close it, with the same signatures over a store whose methods return Effects:
+
+  ```ts
+  const store = yield* EffectStore
+  const saved = yield* insertRowEffect(store, players, { tenantId, name })
+  const { row, outcome } = yield* upsertRowOutcomeEffect(store, players, player, {
+    conflictColumns: ['tenantId', 'externalId'],
+    update: ['name', 'score'],
+  })
+  ```
+
+  `EffectStore` satisfies each helper's store parameter structurally, so it is the argument at every call site. The row type, the conflict-key constraint and the return type are spelled as the Promise forms spell them, so moving between the two families means reading one signature rather than two.
+
+  One deliberate difference: `upsertRowOutcome` throws when a hand-written `DataStore` lacks `upsertWithOutcome`. `EffectStore` always provides it, so the Effect form does not carry that failure — an error case for an unreachable condition is one every caller must handle and none can trigger.
+
+### Fixed
+
+- **A module that re-exports the generated route builder is not a hand-roll** — `@voltro/cli`
+
+  `voltro doctor`'s `hand-route-module` rule read the importing file and asked whether it mentioned `.framework/routes.generated`. An app that keeps exactly one module importing the generated builder and re-exports it — so that a single file owns the dependency — therefore had every consumer of that alias reported, while using the typed builders the rule recommends.
+
+  The rule now resolves the imported module and stays silent when it re-exports the generated builder. A genuinely hand-maintained route or url module is reported as before.
+
+  An alias onto a generated artefact is the adoption of this rule, and a finding that fires on the adoption is an argument for deleting the seam that made it clean.
+- **The migration codemod no longer re-indents the body it rewrites** — `@voltro/cli`
+
+  `0.72.0/01_migration-context-raw` rewrites two lines per migration and produced diffs of 85 to 133 changed lines. Two causes, both removed.
+
+  A migration whose body is an expression — `up: (ctx) => Effect.gen(function* () { … })`, the common shape — was hoisted into a block so the `raw(reason)` binding had somewhere to live, which indented the entire body one level. The binding is placed inside the generator instead, so the body keeps its position and the change is the two lines it actually is.
+
+  Separately, every node any codemod inserted was printed with four-space indentation while this framework's own templates use two. That is fixed for all codemods, not just this one.
+
+  Neither changes what the codemod means. It changes whether the diff can be read — which matters here more than most, because every `raw(reason)` it writes is a placeholder its author has to fill in before committing.
+- **voltro serve refuses a serve bundle built by a different framework version** — `@voltro/cli`
+
+  `voltro serve` loads the precompiled serve bundle, and a bundle built before an upgrade imports perfectly — it simply runs the previous version's code. Nothing said so. Updating `@voltro/*` without re-running `voltro build` therefore left a process serving the old framework while the installed one had moved on, and the only way to notice was to recognise a log line's shape as belonging to the older release.
+
+  The bundle already carries the version that built it. `voltro serve` now reads it before importing and refuses when it disagrees with the installed CLI, naming both versions and the command that fixes it:
+
+  ```
+  FATAL: the serve bundle was built by @voltro/cli 0.71.1, but 0.72.0 is installed.
+    Serving it would run 0.71.1's code against 0.72.0's dependencies.
+    Rebuild it:  voltro build .
+  ```
+
+  A mismatch refuses rather than falling back to the slower boot path: it is a build error of the deployment, and quietly running a different version is the failure being fixed. A bundle carrying no version marker is left alone — those predate the marker and are not evidence of anything.
+- **A workflow step can reach the store under the test runner** — `@voltro/testing`
+
+  A workflow step may `yield* EffectStore`, and in production it gets one: the runtime provides the layer from the context's store. `makeWorkflowRunner` provided the step recorder and the workflow's own layer and nothing else, so the step died under test with
+
+  ```
+  Service not found: @voltro/EffectStore
+  ```
+
+  while the identical code ran in production. The only supported way to drive a workflow in a test could not run the form the framework documents, which left `Effect.promise` as the shape people shipped instead.
+
+  The runner now provides the same layer from the same place production does, from the context it already receives. A context without a store stays runnable, so a test that never touches the store does not acquire a requirement.
+- **The AI usage receipt key no longer refuses to migrate an existing ledger** — `@voltro/ai`, `@voltro/cli`
+
+  `_voltro_ai_usage.receiptKey` arrived NOT NULL with neither a default nor a backfill, so adding it to a database that already holds usage rows was refused:
+
+  ```
+  auto-migrate: REFUSED — 1 blocked operation(s):
+    - add-column [_voltro_ai_usage]: NOT NULL column on a table whose row count is unknown
+  auto-migrate failed — aborting boot
+  ```
+
+  The refusal was correct and its advice was not reachable: it asks whoever owns the declaration to add `.backfill()` or `.default()`, and this table is the framework's, not the app's. `VOLTRO_AUTO_MIGRATE=0` left the app on the previous schema and `voltro db apply` refused the same way before a deploy, so an upgrade could not be rolled out at all.
+
+  The column now derives a per-row value from the row's own id. A literal default could not do this job — the column is UNIQUE, so one value for every existing row collides on the second — and the derivation is computed per row rather than in SQL because string concatenation has no dialect-neutral spelling and this table ships on five.
+
+  A guard now plans every framework table against a populated database and fails on any column added since the last release that an app could not migrate onto. Two earlier shapes of that check were built and discarded, each disproved by its own measurement: both asked every framework column to be addable, and a column created together with its table never is.
+
+---
+
 ## [0.72.0] — 2026-09-16
 
 ### ⚠ BREAKING

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/ui-shadcn",
-  "version": "0.72.0",
+  "version": "0.74.0",
   "description": "Voltro's first-party shadcn/ui kit: Tailwind v4 design tokens (light + dark), 30+ primitives, layout compositions, styled widgets for the @voltro/ui seam, and the canonical theme/language preference-cookie helpers.",
   "keywords": [
     "voltro",
@@ -52,7 +52,7 @@
     "@radix-ui/react-toggle-group": "^1.1.19",
     "@shikijs/langs": "^4.4.3",
     "@shikijs/themes": "^4.4.3",
-    "@voltro/ui": "0.72.0",
+    "@voltro/ui": "0.74.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "shiki": "^4.4.3",