@voltro/runtime 0.69.0 → 0.70.0

package/CHANGELOG.md

@@ -39,6 +39,174 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.70.0] — 2026-09-11
+
+### ⚠ BREAKING
+
+- **@voltro/cli** — The DevTools dashboard has a lock of its own: `VOLTRO_DASHBOARD_TOKEN`. A deployed dashboard that holds other apps' inspect tokens in `VOLTRO_DASHBOARD_APPS` refuses to boot in production without it, `/api/dashboard/config` no longer serves token values, and the proxy attaches a configured target's credentials itself.
+
+  Before this the dashboard had no door: whoever reached its URL got every configured app's inspect read AND write token from `/api/dashboard/config` in one request, and the proxy forwarded whatever bearer that browser then presented. The URL was the credential.
+
+  Three rules now, on both boot paths: the browser proves the dashboard token once (`POST /api/dashboard/login`) and gets an HttpOnly, SameSite=Strict session cookie derived from it by HMAC (12 h; a rotated lock invalidates every cookie); every other `/api/dashboard/*` route answers 401 without a session; the config route says where the targets are and whether the pod holds credentials (`hasToken`, `hasWriteToken`), never which. A dashboard with nothing to guard (no configured targets, a loopback dev registry) boots open as before — setting the token locks it anyway. `voltro secret generate dashboard` prints the variable paste-ready. `codemod: none`: no user code changes; the operator sets one variable, and the chart's `dashboardToken` renders it.
+
+  **No codemod** — this break touches no user-authored code.
+
+### Added
+
+- **@voltro/protocol, @voltro/plugin-openapi, @voltro/cli, @voltro/testing** — The `publicApi` surface speaks a REST profile, chosen once in the api's `app.config.ts` (`publicApi: { profile }`) and overridable per descriptor (`publicApi.format`): `'rpc'` — the default, today's wire — `'standard'`, `'jsonapi'`, or a `RestFormat` object of the app's own, with building blocks (`dates`, `errors`, `envelope`, `pagination`, `naming`, `etag`) that override the preset. `'standard'` is the Zalando / Google AIP / Microsoft intersection: `timestampMs` as RFC 3339 (accepted inbound too), every failure as RFC 9457 Problem Details — the transport's refusals included — no envelope, a `nextCursor` as a `Link: <…>; rel="next"` header, a weak `ETag` on GET with `If-None-Match` → 304. `'jsonapi'` answers `{ data, links }` as `application/vnd.api+json`. The spec follows the profile (`format: date-time`, the `ProblemDetails` component, `Link`/`ETag` headers, snake-case names). `makeTestApp({ publicApiProfile })` measures the same wire.
+
+  A path with `{teamId}` or `:teamId` binds that segment to the input field of the same name — always, under every profile — with the remaining fields from the query string (GET) or the body; the brace form used to be no route, the colon form a `400`, so `GET /v1/teams/{teamId}` was unreachable for a projection.
+- **@voltro/testing, @voltro/database** — `makeTestContext({ fieldEncryptionKey })` registers the field cipher for `.encrypted()` columns under test. Setting `VOLTRO_FIELD_ENCRYPTION_KEY` — in `process.env` or the context's `env` — did nothing here, because the harness runs no boot gate and the gate is what turns the variable into a cipher; the only working route was `setFieldCipher(makeFieldCipher(key))` from another package, which nothing pointed at. The refusal now names the option.
+- **@voltro/database, @voltro/runtime** — `insertIgnoreWithOutcome` on the framework store (and on `yield* EffectStore` plus the `tx` view), with the typed helper `insertIgnoreRowOutcome`: `{ row, outcome: 'inserted' | 'ignored' }`.
+
+  `insertIgnore` returns the existing row on the ignore path, and that row is indistinguishable from one it just wrote — so a loop that plants missing rows reported every row it visited as planted unless it read the destination first, per row. The answer is decided the way `upsertWithOutcome` decides it: the id the store minted before the statement is not the id the ignore path hands back; where the id cannot decide (caller-supplied, or database-assigned) the destination is read first and the answer stays exact. Plain `insertIgnore` never pays for that read.
+- **@voltro/protocol, @voltro/client, @voltro/web** — `defineMutation({ serialize: { key, maxPending? } })` — calls of one mutation to the SAME resource run in invocation order on the client, for every caller of the tag. A row lock serialises transactions, not the order a browser invoked them in: two quick saves of one snapshot could take the lock in reverse order and the older snapshot then overwrote the newer one; server-side idempotency does not see it, and `.version()` detects the conflict and replays the older write. `key` names the resource from the input; calls sharing it run one at a time, FIFO, per subject, the permit spanning connection setup, the request, replay and its acknowledgement — optimistic previews stay immediate, different keys run independently. An unknown outcome (a transport failure after the request started) blocks the key for that subject rather than let a later write pass it; a subject change drops the queue; admission beyond `maxPending` (default 32) rejects with `MutationSerialExecutionError`. `useMutation`'s `pending` now counts every concurrent call, not only the one that settled last.
+
+  Declared on the descriptor — where `concurrency` lives for workflows — rather than as a hook builder, because a hook-scoped queue orders one component's calls and lets a second component writing the same resource interleave. Not a durable outbox, a distributed lock or a cross-tab merge.
+- **@voltro/cli** — API `fonts:` declarations now package validated native-readable fonts and relocatable Fontconfig artifacts during build. Dev, serve and direct production entries activate them before startups and handlers; missing or corrupt artifacts refuse boot. Native renderers no longer depend on undeclared host fonts or original workspace font paths.
+- **@voltro/plugin-openapi** — Every mounted API version has an OpenAPI document of its own — `/openapi/v2.json` beside `/openapi.json`, or `?version=v2` — the same spec filtered to that version, every operation fact included; the unversioned URL keeps serving everything. With more than one version mounted the docs page shows Swagger UI's "Select a definition" dropdown: one entry per version, newest first and preselected, an expiring version named with its earliest `sunset` (`v1 — sunset 2027-03-01`), the whole document last.
+
+  Before this `v1` and `v2` shared one document and one viewer: a consumer integrating `v2` scrolled past every `v1` path, and a generator built both into one client.
+- **@voltro/protocol, @voltro/cli, @voltro/plugin-openapi** — `onProcedureSurface` — a plugin hook told the app's wire-reachable rpc procedures (every query, mutation, action and stream discovery found, minus `internal`) once discovery has run, on both boot paths; the procedure counterpart of `onRestSurface`. `openapiPlugin({ includeAppProcedures: true })` documents them as `POST /rpc/<name>` operations without the app listing them: opt-in, so the spec stays REST-only unless asked, and a procedure also passed in `procedures` is documented once.
+
+  Before this `procedures` was the only way in, and filling it meant importing every descriptor module into `app.config.ts` — evaluated before discovery on every load of the config, the pattern the `onRestSurface` docs name as a boot that hung — while `voltro serve` loads no TypeScript at runtime, so a plugin could not read them later either.
+- **@voltro/protocol, @voltro/plugin-openapi** — A `publicApi` projection documents itself completely: `tags` from the rpc tag's prefix (`teams.list` → `teams`; `publicApi.tags` overrides) with a top-level `tags[]` and `tagDescriptions` on the OpenAPI plugin; an `operationId` from the tag (`teamsList`; `publicApi.operationId` overrides); `security` on every operation — required, or optional under `openAccess` (`[{ bearerAuth: [] }, {}]`), `publicApi.security: false` for none — with `securitySchemes.bearerAuth` published once any projection exists; one response per `errorStatus` entry carrying the error's own schema, `422` for the union's other tags, `429` for a mounted rate limiter; `publicApi.example: { request?, response? }`; path parameters `in: path` and query parameters typed from the input.
+
+  Before this the plugin wrote `tags` only for an explicit `version`, `security` only for a `guards:` route — so after "Authorize" Swagger UI sent the token to those alone and "Try it out" on every other route ran without a key — no `operationId`, no `errorStatus` response, no example, and no query parameter at all for a GET projection.
+
+### Fixed
+
+- **@voltro/protocol** — A `publicApi.path` segment that names no input field refuses the boot, naming the descriptor and the segment (`descriptor 'bookings.get' — path '/v1/bookings/:uuid' binds ':uuid', and the input declares no field of that name (fields: bookingId)`). A field the path binds may repeat in the body or query string with the same value — a PATCH carrying the whole resource — but another value answers `400` naming the field.
+
+  Before this the segment was bound silently: the route mounted, the handler never saw the value, and a body that carried the same field with another value was overwritten by the path without a word.
+- **@voltro/protocol, @voltro/runtime, @voltro/plugin-openapi, @voltro/plugin-prometheus** — A plugin route answers the path it declared, byte for byte: the dispatcher refuses a request whose path is not the route's own — case-folded twins and a bare trailing slash included — with `404`, before the body is read. `PluginHttpRoute.match: 'exact'` narrows a route to its path alone, no sub-path; the default stays `'prefix'`, the contract every route that branches on its tail was written against. A REST descriptor is an exact route; the OpenAPI spec and docs routes and the Prometheus scrape route declare `'exact'`.
+
+  Before this the router matched without case and ignored a trailing slash, and every route owned its sub-paths: `/OPENAPI.JSON`, `/openapi.json/`, `/Docs` and `/Metrics` all answered, so a path guard at the ingress that named the one documented spelling covered none of the others. The docs of both plugins now say the guard can name the path as written.
+- **@voltro/workflow, @voltro/cli** — A run that ended outside the engine no longer leaves its unanswered requests in the cluster journal. Cancelling a run (`timeouts.finish`, `cancelOn`, the operator's button, the bulk action) discards its unprocessed messages at once, and the staleness tick discards those of every ended run (`succeeded`, `failed`, `cancelled`) that a runner last read more than a minute ago — logged as `workflow.cluster: discarded unprocessed messages of runs that have ended`.
+
+  Before this, the `activity` request a killed executor was inside stayed unprocessed after the run was cancelled: every runner that acquired the shard re-read it every ten minutes for the rest of time, its handler waited on a latch that never opens, and the `unprocessed messages` warning was printed again on every engine start. An unprocessed `run` request of a cancelled run would have gone further and executed it. The engine's own reset deletes one request; this deletes the ended run's, and `ClusterDiagnostics.discardMessages` is the one write on that service.
+- **@voltro/cli** — `voltro db encrypt-column <table>.<column> .` accepts the app directory every other `db` command takes as its last argument — accepted and not needed, the connection comes from env. It used to parse `.` as a column reference and refuse. A positional that is neither a `<table>.<column>` nor a directory is named in the refusal.
+- **@voltro/runtime, @voltro/cli, @voltro/database** — Every API key has its `actors` row after the first boot on this version. Both boot paths plant, after the schema is applied, one row per `_voltro_api_keys.id` that has none — through the same `ensureActor` a new key goes through (the built-in row, or the app's `apiKeys.ensureActor` handed the issue input rebuilt from the row). Idempotent; two queries when nothing is missing; `api keys: planted actors rows for keys that had none` with the count, and a key whose row cannot be written is named in a warning rather than failing the boot.
+
+  Two release notes had asked the operator to run a loop once. The first was printed to the wrong group; the second printed `store.select(...)` for a `*.startup.ts`, and `StartupContext.store` is a `DataStore` with no fluent builder — both API pods refused to boot on it. The 0.69.1 note now says what the boot does and which line to look for. The framework tables `@voltro/database` exports (`_voltroApiKeysTable` and the others) are typed `SchemaTable` instead of `TableLike`, so `queryFor(_voltroApiKeysTable)` compiles where a hand-written read is still wanted.
+- **@voltro/runtime** — Idempotent WebSocket mutations acquire and finalize their claims safely across request interruption. A closed socket cannot orphan a claim acquired by a still pending store Promise; synchronous executor failures release fresh claims too. Already-started Promise executors finish their actual write and record the result before interruption completes, preventing a replay from duplicating the write. Effect executors remain interruptible and release only after cleanup. A late interrupt never deletes the completion receipt of a successful write.
+
+  Codemod: none — no application source or configuration changes. Claim TTL, replay limits, transport guards and process-crash recovery guarantees are unchanged.
+- **@voltro/cli** — Docker deployments retain optional native platform bindings until runtime tracing, and the pruner traces both conditional import and require entries so relocated API and web images can still execute native image processing.
+- **@voltro/workflow, @voltro/cli** — `own` on a shard-lock holder in the stall report and the `workflow.cluster` warning is now the engine's own account (`Sharding.hasShardId`), and a holder that is this runner reads `this runner (pid N)`.
+
+  The first version compared the holder's pid with `pg_backend_pid()` of the query that asked. The advisory lock lives on the runner's reserved connection, and the pool hands every other query a different backend — so a runner's own 300 locks read as a stranger's, always, and behind a connection pooler nothing in `pg_stat_activity` could have told them apart either. The report's stated lever for a stranger, ending the holder's session, would have ended the runner. The hint now distinguishes the three cases (another runner, a session that outlived its runner, this runner re-reading a request nobody answers), and the docs say to read `own` before `pg_terminate_backend`.
+- **@voltro/cli** — Production HTTP proxies release upstream resources when the browser abandons an unfinished response, including SSE, and propagate truncated upstream responses as transport failures instead of hanging. Complete responses retain payloads and keep-alive; no application configuration change is needed.
+- **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/testing, @voltro/plugin-ratelimit** — `publicApi.rateLimit` on a descriptor is that endpoint's own rule for calls through the `/v1` projection — ahead of the plugin's `rules` and `default`, one bucket per caller per endpoint, under `enabled`. A REST call now carries `surface: 'rest'` and the descriptor's `publicApi` spec on the interceptor context, so a plugin can tell a projected call from an rpc one.
+
+  The field said "rides @voltro/plugin-ratelimit when mounted" and nothing read it: three calls at `limit: 1` answered `200 200 200`, no bucket, no `onLimited`. The plugin never learned which calls came through the projection, let alone what it declared. Without the plugin mounted the spec is inert, as the comment always implied.
+- **@voltro/cli** — The retention sweep arms its policies on the `_voltro_workflow_*` tables only where the workflow engine that creates those tables is composed. An api with no `*.workflow.tsx` has no engine and no such tables, and the five policies still armed on them were five failing `DELETE`s per tick, each an `ERROR` line in the database log, for the life of the deployment — not switchable off from the app. The boot line `retention: N policy(ies) armed` now lists exactly what is swept.
+- **@voltro/plugin-mail** — SMTP replies are classified by SMTP rules instead of HTTP rules: 4xx replies remain retryable, permanent 5xx rejections do not trigger automatic retries (RFC 5321 §4.2.1). HTTP providers keep their existing policy. Tests exercise actual loopback connections, envelope, MIME and attachment encoding without sending external mail.
+
+  Codemod: none — corrected SMTP reply semantics require no application source or configuration migration.
+- **@voltro/workflow** — The workflow engine's boot check for its cluster tables asks whether a table exists with a query that succeeds either way (`to_regclass` on postgres, `information_schema` on mysql, `OBJECT_ID` on mssql, `sqlite_master` on sqlite) instead of selecting from the table and reading the failure as "no" — which the database server logged as an `ERROR` on every first boot of a database. The probes `@effect/cluster` itself makes for its legacy tables are upstream and still fail-as-answer.
+- **@voltro/cli** — `voltro dev` acquires the workflow runtime as a boot step, as `voltro serve` always has — `workflow runtime ready — N entity type(s) registered` on both paths, through one shared helper with a parity test.
+
+  A `ManagedRuntime` builds its layer on first use, and `voltro dev` never used it at boot. A fleet of dev pods therefore had NO cluster runner after a restart — no runner row, no shard locks, no re-delivery — until something asked the runtime for a service. The first thing that asked, in a deployment, was the once-per-fleet staleness tick, five minutes after the boot, in the one pod that ran it: a run orphaned by the restart waited exactly that long and was then adopted by that pod alone.
+- **@voltro/cli** — `voltro baseline sync` writes its `docker/Caddyfile` with tabs, the way `caddy fmt` writes it. Caddy warned on every proxy start that the file "is not formatted", and a project that checks its generated files for drift could not fix it on its side — the next sync undid it.
+- **@voltro/plugin-ratelimit** — `redisStore({ url })` binds its client on the first `consume` when nobody activated it — from `url` or the env it reads at activation — so a limit holds in the test harness, where `makeTestContext` runs no lifecycle hooks. A store with neither stays fail-open (`failOpenReason: 'unbound'`), as at activation.
+
+  Before this a suite that "checked the redis store" ran every call through an unbound store: `200 200 200` at `limit: 2`, no key in Redis, no warning — and nothing a test could read told "the limit held" from "the store was never there".
+- **@voltro/cli, @voltro/i18n** — A `src/pages/[locale]/…` route renders in the locale it matched, on both web boot paths: `voltro start` and `voltro dev` hand the matched `[locale]` parameter to the same i18n resolver (also for the ISR key and for an app without catalogs), and `resolveLocale` takes it as `routeLocale` — ahead of the `voltro:locale` cookie, `Accept-Language` and the default, and only on an exact supported spelling. The build's static prerender already did this; the runtime render fell back to cookie or browser language, so `/en` answered with a German head and `html lang="de"`. In the same change `voltro dev`'s buffered SPA and ISR responses merge a page's `meta.title` into the shell the way production does — there was a second `<title>` before.
+- **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/testing, @voltro/plugin-ratelimit** — A rate-limited call on the `/v1` projection answers `429` with `Retry-After` and the `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` headers, the tag and fields as the body — on both boot paths and in `makeTestApp`. A `PluginErrorSchema` may declare `rest: { status, headers }`; the projection encodes a plugin's cross-cutting error under that status (`422` when it names none; the descriptor's own `errorStatus` entry wins), and the plugin declares `429` for `RateLimited`.
+
+  The plugin merged `RateLimited` into every rpc's wire union at boot and the client decoded it typed, but the REST projection encoded through the descriptor's own `error:` union only — the one surface with no typed channel to fall back on answered `500 Internal Server Error` with no `Retry-After`. The only way to a `429` was to import a plugin error into every descriptor file. A `500`'s cause now rides on the response value off the wire, so the `GET /v1/… → 500` log line names the reason on `voltro serve` too.
+
+---
+
+## [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/dist/index.d.ts

@@ -43,6 +43,7 @@ import { IdempotencyStore } from '@voltro/protocol';
 import { IdScheme } from '@voltro/database';
 import { InMemoryMetricExporter } from '@opentelemetry/sdk-metrics';
 import { InMemorySpanExporter } from '@opentelemetry/sdk-trace-base';
+import { InsertIgnoreResult } from '@voltro/database';
 import { InspectedStep } from '@voltro/workflow';
 import { InspectedWorkflow } from '@voltro/workflow';
 import { InspectStore } from '@voltro/workflow';
@@ -63,6 +64,7 @@ import { PendingApproval } from '@voltro/protocol';
 import { PluginHttpRoute } from '@voltro/protocol';
 import { PluginRefOrphanPolicy } from '@voltro/database';
 import { Predicate } from '@voltro/database';
+import { PublicApiSpec } from '@voltro/protocol';
 import { Query } from '@voltro/database';
 import { QueryDescriptor } from '@voltro/database';
 import { Redis } from 'ioredis';
@@ -106,6 +108,7 @@ import { TenantScopeViolation } from '@voltro/protocol';
 import { Tracer } from 'effect';
 import { Unauthenticated } from '@voltro/protocol';
 import { UpsertOptions } from '@voltro/database';
+import { UpsertResult } from '@voltro/database';
 import { ValidationError } from '@voltro/protocol';
 import { ValidationErrors } from '@voltro/protocol';
 import { VersionConflict } from '@voltro/database';
@@ -865,6 +868,41 @@ export declare const API_CSP = "default-src 'none'; frame-ancestors 'none'; base
 
 export declare const API_KEYS_TABLE = "_voltro_api_keys";
 
+/** What `ApiKeyStore.ensureActor` is handed for the row it plants. */
+export declare interface ApiKeyActor {
+    readonly id: string;
+    readonly displayName: string | null;
+    /**
+     * The `issue()` input, verbatim — and on a rotation, the input the rotation
+     * rebuilt from the old row (`onBehalfOf`, `metadata` and all).
+     *
+     * An app may declare its own `actors`, which takes precedence over the
+     * built-in table and need not carry `kind` or `displayName` at all. For
+     * that table `{ id, displayName }` cannot produce a row: which KIND of key
+     * this is, whom it belongs to, which team it acts for — all of it lives in
+     * the input (`metadata`, `onBehalfOf`) and nowhere else. Without the input
+     * the only complete row was one written AFTER `issue()` returned, and a
+     * hook writing a minimal row first collided with it on the table's own
+     * unique keys. The two framework stores read `id` and `displayName` and
+     * ignore the rest.
+     */
+    readonly input: IssueInput;
+}
+
+/** What one boot's actor backfill did. */
+export declare interface ApiKeyActorBackfillResult {
+    /** Keys the store lists. */
+    readonly keys: number;
+    /** Keys that had no `actors` row and got one on this boot. */
+    readonly planted: number;
+    /** Keys whose row could not be written — the app's `ensureActor` refused, or
+     *  the built-in row does not fit a declared `actors`. One entry per key. */
+    readonly failed: ReadonlyArray<{
+        readonly id: string;
+        readonly reason: string;
+    }>;
+}
+
 /** Admin-gated management routes (issue / list / revoke) for the built-in keys.
  *  Mounted under `basePath` (default `/v1/api-keys`) when `apiKeys` is on. */
 export declare const apiKeyManagementRoutes: (service: ApiKeyServiceShape, basePath?: string) => ReadonlyArray<RestRouteDescriptor<any, any>>;
@@ -972,10 +1010,7 @@ export declare interface ApiKeyStore {
      *
      * Idempotent by contract: it is called on every issue, including a rotation.
      */
-    readonly ensureActor: (actor: {
-        readonly id: string;
-        readonly displayName: string | null;
-    }) => Promise<void>;
+    readonly ensureActor: (actor: ApiKeyActor) => Promise<void>;
 }
 
 export declare interface ApiKeyUsageBuffer {
@@ -2947,7 +2982,21 @@ export declare interface DataLoader {
 
 export { DataStore }
 
-export declare const dataStoreApiKeyStore: (store: DataStore) => ApiKeyStore;
+export declare const dataStoreApiKeyStore: (store: DataStore, options?: DataStoreApiKeyStoreOptions) => ApiKeyStore;
+
+/**
+ * The one thing an app can put into the built-in store: how its `actors` row
+ * is written. The built-in `ensureActor` writes `{ id, kind: 'apiKey',
+ * displayName }`, which fits the framework's `actors` and no other — an app
+ * that declares its own `actors` (it takes precedence) may have no `kind` and
+ * columns of its own, and for that table the built-in write fails at the
+ * actor row, i.e. before any key exists. `app.config.ts` `apiKeys.ensureActor`
+ * lands here, on BOTH boot paths, and replaces exactly that write.
+ */
+export declare interface DataStoreApiKeyStoreOptions {
+    /** Handed the store the key row goes to, so the row lands beside it. */
+    readonly ensureActor?: ((actor: ApiKeyActor, store: DataStore) => Promise<void>) | undefined;
+}
 
 export declare const dataStoreIdempotencyStore: (store: DataStore) => IdempotencyStore;
 
@@ -3703,9 +3752,27 @@ export declare interface EffectStoreOps {
         readonly where: Predicate;
     }) => Effect.Effect<number, StoreError>;
     readonly upsert: (table: string, row: Row, options: UpsertOptions) => Effect.Effect<Row, StoreError>;
+    /**
+     * `upsert`, plus whether the row was INSERTED or UPDATED — the Effect form of
+     * `upsertRowOutcome`. On this service AND on the `transaction` view
+     * `transactional` hands out, because the ingest that needs `created` is the
+     * one that runs inside a transaction: `upsertRowOutcome` required
+     * `store.upsertWithOutcome`, which `ctx.store` had and `yield* EffectStore`
+     * did not, so an Effect handler kept its pre-read for an answer the store
+     * already knew.
+     */
+    readonly upsertWithOutcome: (table: string, row: Row, options: UpsertOptions) => Effect.Effect<UpsertResult, StoreError>;
     readonly insertIgnore: (table: string, row: Row, options: {
         readonly conflictColumns: ReadonlyArray<string>;
     }) => Effect.Effect<Row, StoreError>;
+    /**
+     * `insertIgnore`, plus whether it inserted or found the row there — the
+     * Effect form of `insertIgnoreRowOutcome`, on this service and on the
+     * `transaction` view, for the same reason `upsertWithOutcome` is on both.
+     */
+    readonly insertIgnoreWithOutcome: (table: string, row: Row, options: {
+        readonly conflictColumns: ReadonlyArray<string>;
+    }) => Effect.Effect<InsertIgnoreResult, StoreError>;
     /**
      * The single-row reads, on the typed channel — the same three `ctx.store`
      * offers, taking a builder or a descriptor.
@@ -6809,8 +6876,13 @@ export declare interface OneShotQueryRunnerDeps<D> extends QueryProducerDeps<D>
      * subject-aware wire-column strip the dispatcher does (`.serverOnly()` ∪ the
      * `.readableBy(...)` columns this subject lacks) — the parity that keeps the
      * REST projection from shipping a column the socket path would strip.
+     *
+     * `store` is the REQUEST-SCOPED store — what `buildContext(context).store`
+     * returns, with this request's row filter and tenant scope applied. Read the
+     * descriptor through it, never through the raw store the app was booted
+     * with: the raw read returned every row of the table to a filtered caller.
      */
-    readonly queryRows: (descriptor: D, context: ServeRequestContext) => Promise<ReadonlyArray<unknown>>;
+    readonly queryRows: (descriptor: D, context: ServeRequestContext, store: unknown) => Promise<ReadonlyArray<unknown>>;
 }
 
 /**
@@ -7160,6 +7232,29 @@ export declare const pendingApprovalsFor: (store: DataStore, subject: Subject |
     readonly now?: () => number;
 }) => Promise<ReadonlyArray<PendingApproval>>;
 
+/**
+ * Plant the `actors` row of every key that has none — at boot, on both boot
+ * paths, idempotent.
+ *
+ * Keys issued before the actor row existed keep authenticating and fail on the
+ * audit foreign key at their first stamped write. A note told each operator to
+ * run a loop once; it was printed to the wrong group in one release and did not
+ * run where it said to in the next, so the loop lives here now: the framework
+ * owns both tables, knows the row's shape through the same `ensureActor` the
+ * issue path uses (the app's own, when declared), and can tell which keys are
+ * missing in one read. When nothing is missing this costs two queries.
+ *
+ * Never throws: a key whose row cannot be written is reported, not fatal — the
+ * boot line says which, and the key fails exactly where it failed before.
+ */
+export declare const plantMissingApiKeyActors: (input: {
+    readonly apiKeyStore: Pick<ApiKeyStore, "ensureActor">;
+    /** Every key the store holds — the framework store lists all for `null`. */
+    readonly keys: () => Promise<ReadonlyArray<ApiKeyRow>>;
+    /** The store the actor rows live in, for the one read that finds the gaps. */
+    readonly store: Pick<DataStore, "query">;
+}) => Promise<ApiKeyActorBackfillResult>;
+
 /** One resolved rule: "when <targetTable> loses a row, do <policy> to <table.column>". */
 export declare interface PluginRefRule {
     readonly table: string;
@@ -10113,6 +10208,12 @@ export declare interface ServeRequestContext {
     readonly subject: unknown;
     readonly traceId: string;
     readonly spanId?: string;
+    /** `'rest'` when the request came through the `publicApi` projection —
+     *  carried onto the plugin interceptor meta so a per-endpoint policy on
+     *  the projection can apply to exactly those calls. Absent on the wire. */
+    readonly surface?: 'rest';
+    /** The descriptor's `publicApi` spec, on a projected call. */
+    readonly publicApi?: PublicApiSpec;
     /**
      * Caller-side cancellation (the gRPC deadline / client-cancel path).
      * Honoured at the ONE place the executor effect runs to a promise, so an
@@ -10174,6 +10275,9 @@ export declare type ServeRpcInterceptor = (base: Effect.Effect<unknown, unknown,
      * written; a change-set carry (the rows/ids) is a separate, heavier seam.
      */
     readonly target?: ReadonlyArray<string>;
+    /** See `ServeRequestContext.surface` — present on a REST-projected call. */
+    readonly surface?: 'rest';
+    readonly publicApi?: PublicApiSpec;
 }) => Effect.Effect<unknown, unknown, never>;
 
 /** The published tracer, or `undefined` when tracing is off / no server booted. */