@voltro/ui-shadcn 0.69.0 → 0.69.1

package/CHANGELOG.md

@@ -39,6 +39,94 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.69.1] — 2026-09-11
+
+### Added
+
+- **@voltro/cli** — `voltro dev` and `voltro build` refuse a published artefact. A publish step writes `.framework/dist/.voltro-artifact.json` into a package that ships its build and no source; both commands look for it before loading the config or booting anything and exit 1 with the reason. An image built without the dev toolchain is a hindrance; this is the rule — a toolchain installed by hand into that image still cannot develop or rebuild the package. A developer's own tree never carries the marker, built or not, so nothing changes there.
+- **@voltro/database, @voltro/cli** — `voltro db plan` names the tables on which the live and the declared fingerprint part — in the JSON record, and on a TTY for an empty plan.
+
+  `fingerprintLive` hashes the whole live introspection, every table included; `fingerprintDeclared` hashes the declaration. A plan of zero operations says the schemas agree, and the two hashes can still differ — over a table the diff never compares (`cluster_*`, an undeclared `_voltro_*`, a soft-drop snapshot, a name in `VOLTRO_DB_IGNORE_TABLES`), or over a detail the diff calls equal that introspection reports differently from how it was declared. The TTY printed a caveat under the two; the JSON record a migrate job writes carried none, so `0 operations` under two different hashes read as a contradiction and raised the question whether the computation had changed.
+
+  The plan carries `fingerprintDivergence: { outsideDiff, diffEquivalent }` now, both lists of table names, and the record carries it with a one-line `fingerprintNote`. On a TTY the fingerprint line lists them, and an empty plan prints it only when the two part somewhere, so a clean schema stays a one-liner. The earlier wording — "a live hash never equals a declared one" — was wrong as a rule: a schema whose every detail introspects back as declared hashes the same on both sides, and does.
+
+  `voltro serve` is not part of this: its boot check compares the declared fingerprint against the one the last `voltro db apply` RECORDED, never the live hash.
+- **@voltro/client, @voltro/web** — The client diagnostics snapshot carries `runtime` — per api, what the runtime resolved to (`scheduler`, `generation`) — outside the event ring.
+
+  `runtime.resolved` is recorded when the runtime is built, which makes it one of the first events of a session, and the first events are exactly what a `clear()` before a measurement or the ring's eviction removes. An export taken after either carried every reconnect event and no statement about which scheduler produced them; a reader checking whether the yield channel was in use had to inspect the bundle by hand. The snapshot keeps the last resolved record per api in its own field now, and `clear()` leaves it in place — it describes the runtime, not the timeline.
+- **@voltro/plugin-openapi, @voltro/protocol, @voltro/cli** — `openapiPlugin` documents the app's own REST surface as the framework mounts it — every `restRoutes` descriptor and every `publicApi` projection — without the app listing them (`includeAppRoutes`, default `true`). A plugin can implement the new `onRestSurface(routes)` hook and is told the mounted routes on both boot paths once they exist. Importing descriptor modules into `app.config.ts` to build that list is no longer needed, which is the path on which a boot had hung.
+- **@voltro/workflow, @voltro/cli** — A `run-stalled` report on the durable engine carries the engine's view of the run — its journal messages, whether each was processed and last read, and who holds the lock on its shard — and the staleness tick warns about unprocessed messages no runner has read for the engine's own re-read window.
+
+  The engine's recovery for a run whose process died is real and silent: a runner that acquires a shard re-delivers the shard's unprocessed messages, and re-reads any whose `last_read` is older than ten minutes. The state with no symptom is the one where no runner acquires the shard — a postgres advisory lock held by a session that is not a live runner (a backend the server has not reaped, a pooled connection that outlived its client) — and the run then sits `running` with nothing moving while every process reports healthy. `ClusterDiagnostics` (provided by `workflowEngineLayer`) reads that state: `messagesFor(executionId)`, `unreadMessages()`, `shardLockHolders(shardIds)` (postgres advisory holders from `pg_locks` + `pg_stat_activity`, row leases from `cluster_locks`), `runners()`. Both boot paths attach it to the stall report as `cluster` and log `workflow.cluster: unprocessed messages no runner has read for the re-read window` with the holders, so the report names the pid to terminate — or the lease mode (`VOLTRO_WORKFLOW_SHARD_LOCK=row`) that bounds the wait.
+- **@voltro/runtime, @voltro/voltro** — `EffectStoreOps.upsertWithOutcome` — the Effect form of `upsertRowOutcome`, on `yield* EffectStore` and on the `tx` view `transactional` hands out.
+
+  `upsertRowOutcome` required `store.upsertWithOutcome`, which `ctx.store` provides and `EffectStoreOps` did not declare, so an Effect handler running its ingest inside `transactional` — the place the outcome was built for — kept a pre-read to report `created`. The operation answers `{ row, outcome: 'inserted' | 'updated' }` on the `StoreError` channel like every other op; a hand-written `DataStore` without it is refused with the same message the typed helper gives.
+
+### Changed
+
+- **@voltro/cli** — `voltro test` exits 1 when it executed no test, on every invocation — a bare `voltro test` included.
+
+  A filter that matched nothing and an explicitly named directory with no tests already failed. The bare command was the exception, kept as "a fresh app with no tests yet shouldn't fail its pipeline" — and that is the one exception a CI cannot see: a tree whose tests were all misnamed, moved or deleted printed green forever, with `if voltro test` seeing nothing. Every scaffold ships tests, so nothing needs the exception. The refusal for a stale `rpcGroup.generated.ts` already exited 1; this closes the remaining route to a green line over zero tests.
+
+  vitest's own `--passWithNoTests` is honoured verbatim when a green run over nothing is what you want; it used to be overridden.
+- **@voltro/runtime, @voltro/voltro, @voltro/cli** — `ApiKeyStore.ensureActor` receives the `issue()` input, and the built-in `apiKeys:` wiring takes an `ensureActor` of your own.
+
+  0.69.0 made issuing a key plant its `actors` row through a required `ensureActor({ id, displayName })`, and its note said the framework stores need nothing from you. Both were written for the BUILT-IN `actors`. An app may declare its own — it takes precedence over the built-in table — and that table need not carry `kind` or `displayName` at all and may require columns the hook never saw: which kind of key this is, whom it belongs to, which team it acts for. All of that is in the `issue()` input (`metadata`, `onBehalfOf`) and nowhere else, so the only complete row was one written AFTER `issue()` returned — and a hook that wrote a minimal row first collided with it on the table's own unique keys.
+
+  The hook receives `input` now — verbatim, and on a rotation the input the rotation rebuilt from the old row, so ownership survives rotation there too. The two framework stores read `id` and `displayName` and ignore the rest; a hand-written store can build the complete row before the key exists. Additive for an implementor: a function taking the narrower object is still assignable.
+
+  For an app that declares its own `actors` and uses the built-in wiring, the 0.69.0 write (`{ id, kind: 'apiKey', displayName }`) does not fit that table, and since 0.69.0 that meant `issue()` failed at the actor write. `apiKeys: { ensureActor }` in the config replaces exactly that write, on both boot paths.
+
+  A note under an already-crossed version is never seen again, so the corrected guidance is re-issued as codemod `0.69.1/01_ensure-actor-receives-the-issue-input`, gated on a hand-written `ApiKeyStore` OR an app-declared `actors` — the second group is affected without ever having written the first, and the 0.69.0 gate did not reach it.
+- **@voltro/protocol** — A `GET` projection coerces the query string toward the descriptor's input before decoding: `?limit=5` reaches a `Schema.Number` as `5`, `?archived=true` a `Schema.Boolean` as `true`, and a repeated parameter a `Schema.Array` as its elements; a value that does not read as the target is left for the schema's own `400`. A projection of a procedure without an `openAccess` decision now carries `requireAuthenticated()` — an anonymous caller answers `401` before the handler runs, where it used to reach the handler and surface that refusal as a `500`. A typed error the handler fails with, one of the descriptor's declared `error:` variants, answers with its tag and fields as the body under the status `publicApi.errorStatus` assigns it (`422` when unlisted); an undeclared error stays a `500`.
+- **@voltro/cli** — `voltro dashboard` has no dev fallback any more. A dashboard tree without a build used to be served by `voltro dev` — right for the monorepo source layout, and exactly the mode a deployed dashboard must never enter: a package that lacked its build would have booted a Vite dev server with a freshly minted inspect token on a public hostname, with a `mode: 'dev'` log line as the only sign. The command now refuses a tree without a build in every environment and says where a source tree is served from (`voltro dev <path>`, which the auto-launcher already picks on its own). Removed rather than gated: a gate is one environment variable away from open. The dashboard image is built to have no such door at all — installed without optional dependencies, so the build and dev toolchain is absent, and started through the bin's in-process start path.
+- **@voltro/database, @voltro/cli** — A declared snapshot and the live snapshot of a database the planner has converged on hash the SAME — the fingerprint canonicalises by the planner's own equivalence rules, and the declared snapshot carries the widths the emitter renders.
+
+  `fingerprint.ts` promised that two snapshots of identical observable shape produce identical fingerprints. Measured on a MariaDB: a plan of zero operations under two different hashes, and practically every table hashing apart from its own declaration. The planner decided "nothing to do" through helpers the fingerprint never saw — `restrict` folded into `noAction` on every foreign key (MySQL reports RESTRICT, SQL Server NO ACTION), `now` against `current_timestamp(6)` on every timestamp, a boolean default against the engine's `0`/`1`, `oneOf` compared as a set — and hashed the raw fields instead. And the emitter renders widths the declaration never spells out: `VARCHAR(255)` for a `oneOf` text, `VARCHAR(64)` for a typeid `id()`, a bounded key on mssql for indexed text; introspection reports them as `maxLength`, the declared snapshot carried nothing.
+
+  Those rules live in one module now (`columnEquivalence.ts`), imported by the planner and the fingerprint alike — a second copy is how the two disagreed. The fingerprint hashes the canonical column: references through `normRef`, defaults as the comparable token, `oneOf` sorted, a postgres BIGSERIAL's implicit sequence as the no-default it is to a numeric id, a soft-drop snapshot column left out as the planner leaves it out. `declaredSnapshot(tables, dialect)` materialises the width `sqlType` renders — the same function that renders CREATE TABLE, so the DDL is byte-for-byte what it was; an explicit `.maxLength(n)` is never touched, and a `text()` that renders unbounded stays unbounded. Verified against the database that showed it: the six remaining `diffEquivalent` tables after the first pass were all boolean defaults, and none remain.
+
+  **What this changes for a running deployment: the declared fingerprint of every schema with a foreign key, a default or a `oneOf` moves once.** A `voltro dev` boot runs the plan, finds nothing, and records the new value on its own. `voltro serve` compares the declared fingerprint against the last one `voltro db apply` recorded, so the pre-deploy `voltro db apply` your pipeline already runs is what records it — an apply that finds nothing to do records exactly for this case. `voltro db drift` reports the live side moved once too, until that apply re-baselines it.
+
+  `voltro db squash` now passes the dialect to the declared snapshot it fingerprints; it was the one caller that did not, and its hash disagreed with the boot's.
+- **@voltro/cli** — A production `voltro start` no longer reads `src/`. `voltro build` writes the route tree beside the SSR bundle (`dist/server/pagesTree.json`, the same walk the bundle's lazy page loaders were generated from), and `start` boots from it; the font head was already baked into the built shell. So a deployed web app is `.framework/` plus `app.config.ts` and its `node_modules` — the TypeScript source can stay out of the image and out of a published app package. Only an unbuilt tree (the Vite middleware fallback that is not a production path) still walks `src/pages`. A production start that finds an SSR bundle without the tree beside it refuses with the instruction to rebuild, rather than quietly falling back to the source.
+- **@voltro/cli** — `voltro start` drains on SIGTERM the way `voltro serve` does: readiness flips to `503`, the long-lived inspect streams are ended (their client reconnects), the listener closes and in-flight requests finish inside 60% of `VOLTRO_SHUTDOWN_GRACE_MS`, then the SSR loader, cache backend and registry entry close and the process exits `0` with a `drained in <ms>` line. Before this the web path closed its listener and exited: a render in flight when the signal landed was cut, and the docs described a drain with an env var (`SHUTDOWN_GRACE_MS`) that nothing read. The docs now name the real variable and the real order.
+
+### Fixed
+
+- **@voltro/cli** — `voltro agents-md` finds the project's `@voltro/cli` under the app it was run from, not only at the workspace root.
+
+  Its provenance line looked in `<root>/node_modules/@voltro/cli` alone, so a pnpm-strict install (`apps/<name>/node_modules/@voltro/cli`) reported `project has no resolvable @voltro/cli … installed: null` — from a command that was running that very cli. The candidates are now the directory the command started in and every directory up to the root, the root, then every discovered app, in that order.
+- **@voltro/cli** — `voltro update` prints the backfill for API keys issued before 0.69.0 to the apps that have them.
+
+  The 0.69.0 note `05_api-key-store-plants-its-actor` carried the instruction — one `actors` row per existing key — in its last paragraph, and gated the whole note on a hand-written `ApiKeyStore`. An app on the framework store, which is the app that holds such keys, saw `1 skipped (own check found nothing)`. A note under an already-crossed version is never printed again, so the paragraph is re-issued under `0.69.1/02_existing-api-keys-get-their-actors-row`, gated on using api keys at all (`apiKeys:` in the config, `apiKeyStrategy`, or an `ApiKeyStore`), with the loop that plants the rows idempotently through `insertIgnore`.
+- **@voltro/workflow, @voltro/cli** — `onFailure` fires for a run whose body failed — the route the documentation listed first and the one that was not wired.
+
+  The three flow-control routes into the failure signal (an expired `timeouts.start`, a `timeouts.finish` cancellation, a dead-lettered intent) reached the handler through the drainer's `onAbandoned`; the run recorder's terminal hook only released the admission lease. So a deployment saw its `onFailure` workflow run for a finish-timeout cancellation and stay silent for the runs that had actually failed. The recorder's `onTerminal` now carries the payload and the error on `failed`, and both boot paths build their hook with `makeWorkflowTerminalHook`: release the lease, then — for a workflow that declares `onFailure` — start it with the same `WorkflowFailureReport` the other routes send (`reason: 'the run failed with <errorTag>'`, `runId`, `executionId`, the payload). A workflow that declares nothing stays exactly as loud as before.
+- **@voltro/cli, @voltro/protocol** — A `publicApi` projection — and every hand-written `restRoutes` entry — now runs under the app's row filter. Both boot paths built the REST request's context from the subject alone, so for an app that registered `setRowFilter` the context builder's unfiltered-read guard refused every REST request before its handler ran: `500` on every route, in development and production alike. The shared REST surface now resolves the row filter for each request (`withRowFilter`, the same spine the rpc runners walk) before the context exists, and the context builder runs inside the route's failure mapping rather than escaping it as a transport defect.
+
+  Behind that refusal sat a second defect the refusal had been hiding: the one-shot read of a projected query went through the raw store, so once the request had a row filter it still returned every row of the table — the filter was resolved and never applied to the read. The one-shot runner now reads through the request-scoped store the context builder wraps (row filter and tenant scope applied), the store the handler itself would read from. The subscription and socket arms were already filtered.
+
+  The REST failure mapping is one function for every place a route can fail: `RestRouteError` and `{ status }` errors keep their status; the framework's `ScopeError` answers `403`, or `401` for an anonymous caller; `Unauthenticated` answers `401`; everything else is the reported `500`. A repeated query parameter (`?tag=a&tag=b`) reaches the input as an array of every value instead of the last one.
+- **@voltro/workflow, @voltro/cli** — `timeouts.finish` cancels at the deadline plus at most one drain tick — not at whatever start next happened to wake an idle drainer.
+
+  The bound is enforced by the admission drainer's tick, and the drainer disarms when nothing is pending. A run admitted straight through writes nothing to the queue, so with an empty queue the drainer slept while the run passed its bound and cancelled it only when an unrelated arrival woke it — measured as cancellations landing tens of minutes late by amounts that depended on traffic. Two changes: the finish sweep reports the earliest deadline among the running runs it saw, and `drainTick` folds it into `nextDueAt`, the instant the drainer arms for; and a run STARTING wakes the drainer in an app that declares a finish bound, so the tick that follows reads the new deadline. Both boot paths, through the shared wiring.
+- **@voltro/cli** — The `helm` baseline (`voltro baseline set helm`) probed `/healthz` on the api and `/` on the web — the first answers 404 on every Voltro boot path, so an api pod could never become ready; the second is answered by the SPA shell with 200 for anything, so a web pod could never become unready. Both deployments now probe what the framework answers before routing — `<path>/startup`, `<path>/readiness`, `<path>/liveness` — with a `probes` block per app (path, periods, thresholds) and a `shutdown` block that renders the `preStop` sleep, `terminationGracePeriodSeconds` and `VOLTRO_SHUTDOWN_GRACE_MS` together, since they are one budget. `PORT` is set from the chart's port so the Service and the listener agree.
+- **@voltro/cli** — `/_voltro/inspect/stream` under `voltro serve` no longer refuses a non-loopback `Host`. The DNS-rebinding host guard is a `voltro dev` measure — the dev api binds every interface and has no hostname of its own — and the JSON inspect door has only ever applied it there. The live stream's shared wiring applied it on every boot path, so behind a Kubernetes Service, a docker network name or an ingress host every JSON endpoint answered the dashboard's bearer with 200 while the stream answered the same bearer with `401 forbidden host` — a refusal that reads as a token problem and is not one. The stream now takes the guard from its door: on in dev, off in serve, where the surface is fail-closed on the token alone.
+- **@voltro/cli** — `voltro dev` stops, with exit code `3`, when the project's installed `@voltro/cli` is no longer the one it is running — instead of restarting on the old one and reporting it as complete.
+
+  The supervisor respawns the api child from its own entry, resolved once at boot. Swap `node_modules` under a running `voltro dev` (a `voltro update`, an install that bumps the cli, a volume replaced under a pod) and every restart after that booted the cli the supervisor started from, printing `restart complete — api ready` for an api composed by code the disk no longer had; nothing in the log said which cli built it. The supervisor cannot re-exec itself, so on the next file change it compares what the root installs with its own version and stops on a difference, naming both and the path — under a restart policy the process comes back on the installed version, in a terminal `voltro dev` is started again. The ready line now carries `cli=<version>`, and a first boot on a cli the project does not install is warned about rather than stopped, because a workspace binary against a checkout is legitimate.
+- **@voltro/cli** — `voltro update` puts every `package.json` it bumped back, byte for byte, when the install fails without ever fetching the target version.
+
+  The bump is written before the install runs — that is what the install resolves against — and an install can fail for a reason the tree had no part in. A lockstep release lands on the registry one package at a time, so the moment the FIRST `@voltro/*` package is there the latest version resolves to the new release; an update started in that minute bumped every manifest and then met `NO_MATCHING_VERSION` on a sibling that was seconds from landing. What it left behind was the worst of the three states: manifests saying the new version, lockfile and `node_modules` saying the old one, and `voltro update` itself reading the manifests as "already there".
+
+  Which state a failure leaves is now measured off the tree, not read off the exit code. A bumped package present in `node_modules` at the target version means the install fetched the release and failed after — a postinstall, a peer — so the bump stands and the message names the codemods as the missing half, as before. Nothing at the target version means the install never got that far, and the originals go back. The message says which of the two happened, and for the first names the publish window as the likely cause: wait a minute, re-run.
+
+  Nothing here reaches `--no-install`, which writes the bump on purpose and says what is left.
+- **@voltro/cli** — `voltro logs` and the dev log buffer keep the error a record was written with. `log.error(message, fields, err)` under `voltro serve` printed `cause` on stdout; the dev capture dropped it, so a route that threw showed `… threw path=/v1/x` and nothing else on any level. The record now carries the error's message and first stack frames, and the text renderer prints them under the line. `voltro dev` also warns when `VOLTRO_SESSION_SECRET` is shorter than the floor `voltro serve` refuses, instead of accepting in silence what production will reject.
+
+---
+
 ## [0.69.0] — 2026-09-10
 
 ### ⚠ BREAKING

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/ui-shadcn",
-  "version": "0.69.0",
+  "version": "0.69.1",
   "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.69.0",
+    "@voltro/ui": "0.69.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "shiki": "^4.4.3",