# Changelog All notable changes to the `@voltro/*` packages are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## Stability contract — read this before you pin a version Voltro is **`0.x` — pre-1.0, and deliberately so.** Under SemVer, `0.y.z` means "anything MAY change." We hold to exactly that, stated out loud: - **Pin exact versions.** Depend on `@voltro/runtime@0.4.2`, never `^0.4.2` or `~0.4.2`. There is no compatible-range promise below 1.0. - **Every MINOR may break.** Breaking changes land on a minor bump (`0.4.x → 0.5.0`); patches (`0.4.1 → 0.4.2`) are additive or fixes only. This is the standard `0.x` reading of SemVer — the minor slot carries breaking under `0.x`. - **Read this changelog before upgrading.** The `⚠ BREAKING` section of each release lists every incompatible change with its migration. It is the only migration path we provide — there is no deprecation cycle, no compat shim. - **All packages release together (lockstep).** One coordinated version across the whole framework; the git tag is the source of truth. This is not a placeholder disclaimer — it is the contract. The framework is refactored aggressively while it has no external stability obligations, and that velocity is the point. A stable-core tier and per-package `1.0` graduation are planned, but not yet; until then, treat the whole surface as movable and pin exact. The **public API** of each package is its `publishConfig.exports` entry points, minus anything marked `@internal` (those are cross-package internals and are stripped from the published `.d.ts`). Importing a deep path that isn't an exported entry point is unsupported. --- ## [Unreleased] _Changes staged for the next release accumulate here (rolled up from `.changes/*.md` at tag time — see `.changes/README.md`)._ --- ## [0.50.1] — 2026-08-24 ### Added - **@voltro/cli** — A `0.51.0` upgrade note for the case 0.45.0's typed-`source:` note left open: a source that is COMPUTED but whose names are all known — a generic reader that takes its table from `input` or a registry. Both remedies the original offered are wrong there. There is no misspelled name to fix, and widening to `ReactivitySourceValue` (or casting) compiles instantly while taking that entire set of tables permanently out of the check the narrowing exists to provide. The note carries the recipe that keeps the names — `as const satisfies`, with the key set recovered separately — and the trap under it: an ANNOTATION widens the keys back even when the literal carries `as const`, because it is checked against the literal and then replaces its type. Filed under an unreached version because codemod selection is `from < version <= to`: 0.45.0's note can never fire again for anyone already past it. Documented on the subscriptions page in both languages. ### Changed - **@voltro/data-transfer** — The `mariadb-dump`-not-on-PATH hint now also warns that a MariaDB 12.x client requires TLS by default, so running it BY HAND against a server without TLS fails with `TLS/SSL error: SSL is required` (2026) and needs `--skip-ssl`. Our own invocation is unaffected. It is said here because this hint is what sends people to install that client package, and the next thing many of them do is run the tool by hand — where the failure reads like a broken install of the thing we just told them to install. ### Fixed - **@voltro/cli, @voltro/mcp** — `voltro check`'s `rbac/unguarded-mutation` no longer fires on `internal: true` procedures. Those are in no rpc group and on no route, so the finding's own sentence — "any caller who can reach the rpc surface can invoke it" — named a surface that does not exist, and neither remedy it offered was available: a guard protects nothing there, and `openAccess` is refused outright on an internal descriptor. An app with 990 internal mutations got 990 warnings and a `FAILED` exit from the same tree on which `voltro doctor` reported zero procedures without an access decision, which made `check` unusable as the CI gate it exists to be. The capability manifest now carries `internal: true` per procedure (present only when true), and the rule reads it through `isWireReachable` — the same predicate the boot access gate and all three rpc-group assemblies use, rather than a fourth spelling of the same flag. A manifest that does not carry the field is read as REACHABLE, so the rule stays loud on an api older than the field rather than going quiet on it. - **@voltro/data-transfer, @voltro/cli** — `--assets` aborted the whole capture at the first blob reference the storage provider could not resolve. A dangling reference is a fact about the source data — a row pointing at an object that was deleted, or that never arrived because an earlier import ran without the flag — and no backup can put back bytes that are not there. Aborting made the flag unusable for exactly the deployment that needed it: 178 references, one resolvable, and the run stopped at the second. The phase now records the key, steps over it, and the run reports how many were skipped. Only a genuine not-found (`status === 404`) is treated this way; a 403 from a rotated credential or a 5xx from a backend outage still fails the capture, because calling those "the object is gone" turns a recoverable outage into a backup that quietly contains nothing. The same abort also cost the artefact its provenance: `voltro-backup-stamp.json` was written after the asset phase, so a backup taken WITH `--assets` had no stamp at all, and `restore` then greeted an artefact this tool had written minutes earlier as "an older/handmade backup. Cannot verify dialect or schema version." The stamp is now written on every path — it describes the dump, and the dump is on disk and correct by the time the assets run. - **@voltro/cli** — `voltro doctor`'s eager-loaded-relation rule resolves nested relations against their PARENT's target table instead of against the query's roots, so every level is reported in one pass. It flattened the `.with({ … })` tree before resolving, which meant a level-2 relation stayed invisible until level 1's table had been added to `source:` — each fix revealed the next level, and a clean run after the first fix meant nothing. One app ran `doctor → fix → doctor` twice before the output stopped producing new findings. The one case that is still genuinely under-reported is now stated instead of being silent: when the executor's base table is neither declared nor textually readable, nothing resolves, and doctor prints which relation names it could not check rather than reporting clean. - **@voltro/data-transfer** — A native restore whose client exited before consuming its input took the whole CLI down with an unhandled `EPIPE`. `createReadStream(dump).pipe(child.stdin)` had no `error` listener, so Node threw on a write to a pipe with no reader: Error: write EPIPE Emitted 'error' event on Socket instance at: at Socket.onerror (node:internal/streams/readable:1045:14) What that cost is the point. The crash landed before `close`, so the step never resumed: the client's stderr — the one place the reason was written down — was discarded, the transfer row was never closed, the in-progress marker was never re-asserted, and the operator got a raw Node stack trace over a database that was now half replaced. A deployment met it on a 64 MB restore and could not diagnose it at all, because the only diagnosis had been thrown away. Every stream in the step now carries a handler. `EPIPE` on the child's stdin is deliberately swallowed — a child closes the pipe by dying, and its exit code and stderr are the actual failure — while any other stream error is carried and reported. The failure line now always includes the tool's stderr (and says so explicitly when the tool printed none), plus how many bytes of the artefact had been fed before it stopped. A source error also ends the child's stdin, which turns a restore that used to hang forever on a vanished dump into one that fails, and a clean exit over a broken input stream is reported as a failure rather than as a truncated success. - **@voltro/cli** — `voltro check`'s observed-vs-declared findings advised an op that does not exist. The recorder reports what the store did, and `store.upsert` is one call; a `target:` is `InsertTarget | UpdateTarget | DeleteTarget` and has no `upsert` member. So `observed/undeclared-write` said to add `{ table: '…', op: 'upsert' }` — a `TS2322`, from a line whose whole purpose is to be pasted. It now advises both halves, and the observed → declarable mapping is typed `Record>` so a new recorder op cannot ship without a declarable answer. The remedy no longer produces a finding of its own either: declared targets are now collected per table as a SET. `new Map(targets.map(t => [t.table, t.op]))` kept only the last op, so the correct two-entry declaration read as "declares update" and the insert half came back as a `wrong-op`. - **@voltro/data-transfer, @voltro/cli** — The in-progress restore marker did not survive a native restore, on the exact dialects that were documented as safe. The claim — postgres and the mysql family drop only the objects the dump names, so the marker row survives — had a correct argument and a wrong premise: a native dump names the WHOLE database, `_voltro_replace_in_progress` included, and a mysql-family restore writes `DROP TABLE IF EXISTS` in front of each table. The table sorts early, so the guard was removed near the START of the window it exists to cover. Measured downstream as one row before and zero after, twice, once by hand and once through the command — and then a restore died and left a database with a schema, some of its tables, no users and no blobs, with nothing to stop the next boot. Two changes, covering different dumps. `voltro data backup` now excludes the marker table (`--exclude-table` / `--ignore-table`), so an artefact we produce cannot carry the thing that erases the guard on the way back in. And `restore` re-asserts the marker after the tool exits, on the failing path as well as the succeeding one, which covers dumps taken before this change and dumps made by hand: rewritten is a warning, and unwritable is an error, because the guard is then off for that run. - **@voltro/plugin-storage, @voltro/cli** — `--assets` could not be refused when no storage was configured, and resolved the wrong backend when it was. `resolveStorageProvider({})` is total: its final `default:` arm returns an in-process `memoryProvider`. So the three `if (!provider)` refusals in `voltro data backup` / `export` / `restore` — whose entire job is to refuse a flag the app cannot honour — were checking a condition that cannot hold. What they let through is worse than an unchecked flag: with no storage configured, `backup --assets` captured from a fresh memory provider, found nothing in it, and wrote an artefact stamped `assets: { count: 0 }` — a rollback story that says the blobs are in there. It also ignored the provider the app REGISTERED. An app on `storagePlugin({ provider: s3(…) })` had its export/import/backup read and write the env-derived default instead, which surfaces later as "no object at key" — the exact drift `appStorageProvider()` exists to prevent, in call sites that never adopted it. `configuredStorageProvider()` is the honest predicate: the app's registered provider, else the env-named one, else `undefined`. A memory provider nobody asked for is not a decision. The CLI now loads the app config BEFORE resolving — `storagePlugin(...)` registers at construction, so asking first answered with the default no matter what the app had configured. ### Internal (no consumer-facing effect) - **@voltro/cli** — `voltro data backup` / `restore` / `clear-replace-marker` are now driven end to end, one case per declared option and one per refusal, as real CLI subprocesses against a real database. Every defect this command has shipped lived in the SEQUENCE rather than in a function — an unhandled `EPIPE` that discarded the client's stderr before `close` fired, a marker erased by the restore's own artefact, an asset abort that skipped the provenance stamp, a refusal that could not fire — so none of them was reachable by testing a part. `nativeBackupRestore.e2e.test.ts` covers the whole surface against sqlite (a file copy: no vendor binary, runs anywhere) and `nativeBackupRestoreDialects.integration.test.ts` runs the vendor-tool half against postgres, mariadb and mysql, skipping BY NAME when the server or the client binary is absent — including when the client is present but too old for the server, which a "is it on PATH" check reports as ready. The suite checks itself against `DATA_FLAGS`, the command's own declared option list, so an option cannot be added without a case that drives it. --- ## [0.50.0] — 2026-08-23 ### ⚠ BREAKING - **@voltro/cli** — The read-only run-history endpoint moved: GET /_voltro/admin/imports → GET /_voltro/admin/transfers Same secret, same query parameters, same response shape. Only the path changed. It answers for four directions now — import, export, native backup, native restore — and it named one of them. The subcommand and the table were renamed for exactly that reason in 0.49.0 and this path was left behind, which is worse than renaming none of them: a reader who follows a rename tries the matching path, gets a 404, and concludes the instance is too old. `voltro data transfers --target api` uses the new path for you. What needs a hand is anything calling it directly — a monitoring check, an uptime probe, a curl in a runbook, a dashboard datasource. The codemod is `manual` and declares `reach: 'beyond-source'`, so it prints whether or not the path is found in your repository. - **@voltro/database, @voltro/voltro** — `InterruptedReplace.tables` is `number | null`, and the interface gains `kind?: 'replace' | 'restore'`. `_voltro_replace_in_progress` records two destructive operations now — an import's `--mode replace` and a native `voltro data restore`. A restore replaces the whole database from an artefact, so "how many tables was this going to empty and refill" has no answer: not known up front, not meaningful after. Writing `0` would have preserved the type and been worse. That number is rendered into the boot refusal, which is read under pressure, and it would have said `began emptying 0 table(s)` — a measurement that was never taken. The framework's own text says "this database" instead; `Number(null)` is `0`, so coercing it reintroduces exactly the sentence being avoided. `DataTransferRun.direction` also widens to name `'backup'` and `'restore'` explicitly. That one is documentary — the union already ended in `| string`, so no assignability changes. **`voltro update` carries you across this** — codemod `0.50.0/03_interrupted-replace-tables-nullable`. ### Added - **@voltro/cli, @voltro/data-transfer, @voltro/database** — `voltro data backup --assets` and `voltro data restore --assets` now move the stored blobs alongside the vendor dump, through the same content-addressed phase the logical `export` / `import` path uses — streamed, deduped by sha256, verified on the way back, resumable per key. `--assets` was accepted by `backup` and silently ignored, with the only signal a field in the closing JSON reading `NOT included`; `restore` did not accept it at all. A rows-only backup restores a database whose rows reference objects nothing puts back, and the reference and the object are checked at different times, so that state is discovered by a user rather than by the restore. Three refusals, each for a belief that is otherwise acted on silently: `backup --assets` with no storage provider is refused rather than swallowed; `restore --assets` on a rows-only artefact is refused; a restore WITHOUT `--assets` over an artefact that has them warns and proceeds, because restoring rows without blobs is legitimate and refusing it would push people at `--force`. The dump itself still has no resume — a vendor artefact is one opaque file with no offset to restart from, and the logical path is what exists for that. - **@voltro/cli, @voltro/database, @voltro/data-transfer** — A native `backup` / `restore` now writes to the same `_voltro_data_transfers` record `import` and `export` use, so `voltro data transfers` answers "did last night's backup finish" from the instance that ran it. A native run reports blobs rather than rows — a vendor tool reports no row count we can trust, and printing `0 row(s)` over a dump that worked would be a wrong measurement. `restore` also writes the `_voltro_replace_in_progress` marker before its first destructive statement and clears it after the last write, blobs included, so a killed restore refuses the next boot instead of serving a half-loaded database. `--allow-live` guards from the wrong side — it asks you not to — and this guards from the right one. The marker carries a `kind` so the refusal can say something different for a `replace` (re-import the capture) and a `restore` (finish the restore), and `tables` is nullable because a native restore has no table count to claim. The sqlite / turso restore is atomic now (temp file + rename): its marker lives in the very file being replaced, so a plain in-place copy would leave a truncated database with nothing left to catch it. A target with no `_voltro_data_transfers` table still gets its backup; the closing line says it was not recorded rather than implying it was. - **@voltro/cli** — A re-issued migration note for the `voltro data imports` → `voltro data transfers` rename that shipped in 0.49.0. Codemods are selected by `from < version <= to`, so the 0.49.0 note fires once, on the jump that crosses 0.49.0, and cannot be corrected for anyone already past it. Its gate searched `.ts` / `.tsx` while the command it is about lives in shell scripts, CI job definitions and runbooks — so a project whose only occurrence sat in `.gitlab-ci.yml` crossed 0.49.0 and was told there was nothing to apply. The re-issue is filed under 0.50.0, prints unconditionally, and says what to grep for. Redundant for anyone already fixed; the alternative is firing for nobody. ### Fixed - **@voltro/cli** — A `manual` codemod's `appliesTo` can now search every text file the project owns — `.sh`, `.yml`, `.json`, `.md`, `Makefile`, the `.js` scripts — through a new `ctx.text` on the predicate context, and a codemod may declare `reach: 'beyond-source'` to print its note even when nothing matched. Both halves close the same gap, and it was in the codemod most in need of a gate. A manual codemod exists BECAUSE its subject could not be transformed, which usually means it is not source at all — and `appliesTo` was reading the ts-morph project, which holds `.ts` / `.tsx` and nothing else. Measured with one identical CLI invocation in four files: the `.ts` one printed the note, the `.sh`, `.yml` and `.md` ones printed nothing, and the run reported `codemods: nothing to apply for this jump`. That is an acquittal from a check that never looked at the file, and an acquittal gets acted on. `reach: 'beyond-source'` covers what no scan of one repository can reach — an inline script in a CI runner's own UI, a CronJob spec in another repo, a wiki runbook. The note prints either way; only its framing changes, and an uncertain one says plainly that we could not look there. - **@voltro/data-transfer** — When `mariadb-dump` is absent and the mysql-family fallback runs Oracle's `mysqldump` against a MariaDB server, the failure now names the way out. The stderr it prints is the child's own words and is the right first thing to show — and on its own it is a dead end: `Unknown table 'COLUMN_STATISTICS' in information_schema (1109)` names a table nobody asked for, in a schema nobody wrote, about a feature nobody enabled. Everything needed to act on it was known where the fallback was DECIDED: which binary we wanted, which one we took, and why the difference matters. That travels with the step now and prints under the stderr, including the counter-move a reader reaches for on their own (`--column-statistics=0` does not exist on `mariadb-dump`, so it fixes the wrong client and breaks the right one). --- ## [0.49.0] — 2026-08-23 ### ⚠ BREAKING - **@voltro/cli, @voltro/data-transfer, @voltro/database, @voltro/sql-sqlite, @voltro/voltro** — A data transfer is a series of short requests now — no single one may outlive a caller's budget. **The rule:** *a request that carries bytes never runs a transfer; a request that starts a transfer never carries bytes.* It was broken in the worst available place. The upload was already chunked and resumable — many short requests, each abandonable — and then the FINAL chunk fell through and ran the whole import. So the longest request of the flow arrived AFTER the entire upload had succeeded, and a caller under a policy that caps a single request (a job runner that kills a client at ten minutes; a 30 s ingress ceiling) lost the most expensive thing they had already paid for. A single-request upload had the same shape without the excuse, and the export had no protocol at all: one request that read the whole database and streamed it back. **Import.** `POST /_voltro/admin/import` accumulates and answers `202`. `POST /_voltro/admin/import/start` begins the run and answers `202 { runId }` as soon as the run's first row exists. `start` is idempotent per upload — it is a short request and therefore a retryable one, and without a claim a retry would begin a second destructive run from the same bytes. A claim whose run has ENDED is taken over rather than honoured forever, so a process that dies holding one cannot poison a bundle. **Export.** `POST /_voltro/admin/export` answers `202 { runId }` and produces in the background; the bytes come back from `GET /_voltro/admin/export/download?runId=&offset=&length=` in ranges, resumable, with the total in a header. Object storage (`--bundle-key`) remains for a bundle you want to KEEP — it is no longer the only way to get one out, because requiring it would leave an instance without storage unable to export at all. **The client.** `--max-request-seconds` (or `VOLTRO_MAX_REQUEST_SECONDS`) declares the budget — declared rather than probed, because the thing that kills a request is a policy on the caller's side and only they know it. `--detach` returns once the run has started and says the outcome is NOT known. Attached, the CLI polls the record and prints per-table progress; Ctrl-C then loses the watching and never the run. **The trap, stated because it is the one way to get this wrong:** a failure used to arrive in the response (409 on drift, 409 on a refused mode, 500 otherwise). After the split the response is a `202`, so **a client deriving its exit code from the status line reports a failed import as a success.** The exit code comes from the polled record, in one shared function, and the drift check moved into `start` where it can still be a refusal that leaves no history. **Two knobs that were constants.** `VOLTRO_IMPORT_UPLOAD_DIR` and `VOLTRO_EXPORT_ARTIFACT_DIR` move the staging areas off the default temp filesystem — which on a container is frequently a small tmpfs, so an instance simply could not accept a bundle the size a grown database produces, and the failure arrived as a write error halfway through an upload somebody had been waiting on. **Renamed:** `voltro data imports` → `voltro data transfers`, and `_voltro_data_imports` → `_voltro_data_transfers` with a `direction` column. The command showed one direction and now shows both; the table rename carries its rows via the declarative differ on every dialect and needs nothing from you. The CLI rename ships a `manual` codemod — the command lives in scripts, CI jobs and runbooks, which `voltro update` cannot see or rewrite. The four PUBLIC exports that named the same record were renamed with it (`ImportRun`, `describeImportRun`, `IMPORT_RUNS_TABLE`, `_voltroImportRunsTable`); those are application source, they ship their own `transform` codemod, and they have their own entry. - **@voltro/database, @voltro/voltro** — The run-history exports say `transfer`, not `import`. `@voltro/database` (and `voltro/database`) renamed four public exports along with the table behind them: | was | is | |---|---| | `ImportRun` | `DataTransferRun` | | `describeImportRun` | `describeTransferRun` | | `IMPORT_RUNS_TABLE` | `DATA_TRANSFERS_TABLE` | | `_voltroImportRunsTable` | `_voltroDataTransfersTable` | An EXPORT writes to this record now — the row carries a `direction` — so every one of those names described half of what it holds. A `transform` codemod rewrites all four, alias-aware, from either module spelling. It also rewrites a hand-spelled `_voltro_data_imports` in a string, template or raw-SQL fragment, and that is the half worth stating: the four identifiers announce themselves as compile errors, while a query that addresses the table by name has nothing to fail on. The table itself moves with its rows via the declarative differ on every dialect. This is filed apart from the transfer-protocol entry beside it deliberately. That one's codemod is `manual` and is about a CLI invocation living in scripts and CI jobs; this one is application source and is rewritten for you. Reading the first as covering both is what would leave a build broken with a note saying nothing in your source was affected. ### Added - **@voltro/database, @voltro/data-transfer, @voltro/cli** — An import records WHETHER it staged, and a soft-dropped column says so in a drift refusal. **`_voltro_data_imports.staged`.** The pre-upload preflight says what the instance WILL do; the run's own line says what it did — and that line is printed inside the instance, which is exactly where an operator using `--target api` cannot read it. So "we were told it would stage" and "it staged" were two claims with no way to close the gap between them from outside. The column is `null` for a mode where the question does not arise; `voltro data imports` and `GET /_voltro/admin/imports` both carry it. **A soft-dropped column is named as one.** `__dropped_` is what the differ leaves behind when an app stops declaring a column — only the database that did the drop has it, so it drifts against every target. The refusal reported it as an ordinary missing column ("the value has nowhere to go"), which points at the TARGET's schema: the one place the fix does not lie. It now says where the column lives and how to reclaim it. ### Fixed - **@voltro/data-transfer, @voltro/sql-sqlite, @voltro/database** — A successful `--mode replace --no-atomic` left a marker that refused the next boot. Two defects, one visible symptom, and both were silent by construction. **The clear was gated on the WRITE's condition.** `!(useLedger && ledger.truncated)` means "an earlier attempt already recorded this destructive run, do not write a second row" — correct on the write. Copied down to the clear its meaning inverts: `ledger.truncated` is set by the emptying step of THIS run, so on `--no-atomic` (the only mode where `useLedger` is true) the clear was skipped by the very run that wrote the marker. **And a `Date` in a predicate is not bindable on sqlite.** `better-sqlite3` binds numbers, strings, bigints, buffers and null; the row path has coerced Dates since that store was written, and the eager-join compiler carried its own private copy of the fix, but `query` / `updateMany` / `deleteMany` bound the raw value. So every comparison of a timestamp column against a `Date` failed with `Failed to execute statement` — including the marker's clear, which swallows its errors ON PURPOSE (a store with no marker table must not fail an import over a bookkeeping row) and therefore said nothing. The retention sweep compares `lt(column, cutoff)` the same way. Together: a fully successful replace left the marker standing, and the next boot REFUSED with "a destructive import did not finish" over a database that was completely fine. The one recovery is a command the operator has no reason to think they need. It stayed invisible because `atomic` defaults to true for `replace`, and because a staged replace writes no marker at all — two defaults hiding the one mode that exists for large, interruptible loads. The coercion is shared now and applied at all three predicate sites, with a guard that fails on a fourth that forgets. A dry run also closes its trace row: a preview that finished instantly used to leave the record open, so a polling caller waited out its whole budget over a run that was long done. - **@voltro/cli** — `voltro codegen` declared twenty framework tables fewer than a boot. The app half of this was fixed last release and looked like the whole thing. It was not: `codegen` derived the FEATURE MIX from the file list it had just walked, and that list is the entity/relations set — which contains no `*.workflow.tsx`, no `*.agent.ts`, no `*.cron.tsx`. So every feature flag came back false, and the dialect was never passed at all, taking `_voltro_cdc_offsets` with it. Measured on an app with two workflow files: 18 framework tables where the shared assembly produces 33. It calls `assembleFrameworkTables({ root })` now — the same entry `voltro db plan/apply` uses, which detects the mix from the root rather than being handed one. The parity guard moved with it. Comparing the two WALKS could not see this: both walks were right about files, and the divergence was introduced one layer past them. It compares the assembled SETS now, and runs codegen's own table function on a tree whose only feature signals are a workflow file and an agent file — a source assertion that the right function is CALLED cannot see a wrong argument handed to it, and a wrong argument is what this was. - **@voltro/cli** — `voltro data --help` advertised four subcommands out of nine. It printed `` while the command dispatched those four plus `imports`, `inspect`, `unpack`, `clear-replace-marker` and `clear-staging`. A quoted enumeration is read as exhaustive — the same failure `subcommandNames.ts` was written for after a `db` list cost two wrong conclusions — and the missing entry here is the one that answers "what is my import doing right now" for somebody who cannot reach the pod. `subcommandHelpParity.test.ts` had listed `data` among the commands it could not check, loudly and correctly: there was no name list to check against. There is one now (`DATA_SUBCOMMANDS`), the dispatch is a keyed `Record`, so a subcommand with no name and a name with no handler are both compile errors, and the usage line is generated from the same array. `data` is out of the unchecked list. --- ## [0.48.0] — 2026-08-22 ### Added - **@voltro/cli, @voltro/data-transfer** — An import over `--target api` can be asked what it will do, and watched while it does it. The transport's two correct properties combined into one blind spot: the run happens INSIDE the instance, so every line it produces goes to a pod log; and it is deliberately decoupled from the caller, so killing the client does not stop it (which is what keeps a dead client from leaving a half-emptied target). Someone reaching for `--target api` cannot reach the database directly and usually cannot read that log either, so "watch for the staging line" was advice they could not follow. **A preflight, before a byte is uploaded.** A `replace` over the api now asks the instance whether it will stage, and prints the answer — including the reason when it will not. It answers from `decideStaging`, the same function the run itself calls, so the two cannot drift; a second copy of that decision would answer confidently and diverge on the next change. With `--bundle-key`, where the client never holds the bundle, it sends the key and the instance reads the table list out of the archive's own manifest — the caller about to have an instance empty its own database is the last one who should be told to check a log they cannot read. **`voltro data imports`** (and `GET /_voltro/admin/imports`, behind the same data-transfer secret) reads the history and the run in flight. `_voltro_data_imports` was write-only; it is now opened before the first table, **advanced every couple of seconds as tables land**, and closed with the outcome — so polling it is the progress feed. Not a streamed response on the upload connection: a chunked body has to survive every proxy in between, and a buffering reverse proxy turns a progress feed into exactly the silence it was meant to replace. **And a `replace` that does not stage now says why.** The staging set was an early `return []` three conditions deep, and the empty array met a `length > 0` further down and read as "do not stage". A bundle table the target does not have — the ordinary case for a development source against a production target — turned the non-destructive path off in silence. Every reason routes through one message now; the cycle case additionally used to be gated on `atomic`, so the mode where an interrupted run leaves the worst outcome was also the one that said the least. ### Changed - **@voltro/cli** — The declared framework schema no longer depends on `NODE_ENV`. `_voltro_traces` and `_voltro_undo_log` defaulted to on outside production. That was allowed with an explicit justification — one decider makes every command in a deployment agree — and the justification was about the schema FINGERPRINT, which only ever compares processes inside ONE deployment. The declared set has a second reader that spans two, and it was never considered: `voltro data`. A bundle exported from a development database carries the tables that database has, and a staged (non-destructive) `replace` needs every bundle table to exist in the target. So one source tree produced a bundle a production target could not stage, and the run fell back to truncating it — with nothing red anywhere, on the one path where that difference is the entire point. Both tables are declared in **every environment** now. The trade is the one `_voltro_cdc_offsets` already makes: an unused declared table costs one empty table and buys agreement. `VOLTRO_UNDO` / `VOLTRO_TRACING_PERSIST` still decide what a process WRITES; they never decided the schema and still do not. Set `schema: { traces: false, undo: false }` in `app.config.ts` to keep one out — in every environment, or the divergence is back by hand. **Upgrade:** a production app that never declared them gains two empty tables. `voltro db apply` (or a `voltro dev` boot) plans and applies them like any other framework table, on every dialect. Run it before the pods roll, as with any schema change — a migrate job and a fleet that disagree is exactly what this removes. `voltro doctor` now prints the three decided tables and what decided each, on a HEALTHY run. That text existed and was reachable only from the `prod-mismatch` refusal — a message that appears exclusively after a fleet is down is an explanation, not a warning. ### Fixed - **@voltro/cli, @voltro/data-transfer** — `voltro data export --exclude a,b` made the bundle BIGGER, and made it unusable for a `replace`. It expanded into `{ kind: 'tables', tables: }`, on the reasoning that a manifest should record what was exported rather than claim "everything". Right goal, wrong mechanism, and it cost two things at once. `all` is the only scope that filters out the tables which describe a deployment, so excluding two names silently added nine others back — the migration ledger among them, whose foreign row takes an environment down at the next boot. And `replace` refuses a named scope, so the honest way to leave a table out was also the way to make the bundle unusable for the mode it was being prepared for. The exclusion is a FIELD of the `all` scope now: the filter still runs, the manifest still says "everything except these" (a different and truer claim than "these"), and `replace` accepts it while naming the tables it will therefore not touch. `--exclude` also works over `--target api` now — it no longer expands against a table list only the instance has, so the instance resolves it where that list already is. Every framework table is classified as portable or environment-local, with the reason, and a new one fails the build until somebody decides. That guard existed and did not help: it was satisfied by a second, hand-kept list inside its own test, and the two disagreed about `_voltro_traces` and `_voltro_undo_log` — nothing was unclassified, something was classified twice, once wrongly. There is one list now, read by both guards. Traces, undo, the outbox and its attempts, idempotency keys, storage grants, spend and usage accounting, delivery attempts and schedule-firing history joined the environment-local side: a row from elsewhere would make the target act, or claim history it did not live. - **@voltro/sql-turso** — Opening a second pooled turso connection could fail instantly with `database is locked` — from inside the constructor, before a single query ran. `makeConnection` set its pragmas in the order `journal_mode` → `foreign_keys` → `busy_timeout`. The engine defaults `busy_timeout` to **0**, so a statement that meets a held lock fails on the spot instead of waiting — and `journal_mode= experimental_mvcc` needs the file exclusively. Since `makeConnection` runs once per POOLED connection (default 4), opening connection two while connection one held the file hit that exclusive pragma with no lock-wait configured yet: SqlError: Failed to enable Turso MVCC (journal_mode=experimental_mvcc): database is locked `busy_timeout` is set FIRST now. Nothing else changed — same value, same pragmas, same connection. **Why it hid for so long.** The file already carried a long, correct note about `busy_timeout` being mandatory with a pool, and a separate fix had closed the DDL half (`retryFilter` + bounded retries in `applySchema`). Both are about the same lock class, so the constructor read as covered — but a setting cannot protect the two pragmas that run before it. It surfaces as an unrelated flaky test, because the failure lands wherever the second connection happens to be opened: a `CREATE TABLE` in one run, an MVCC pragma in the next. It cost three release gates — twice locally, once on a CI runner — and was twice diagnosed as machine contention and closed. It is contention-DEPENDENT, which is not the same as being the machine's fault. Verified: 8 serial runs and 6 concurrent suites at load 12 — 0 failures, 0 occurrences of the message. The failure was intermittent before, so this is evidence rather than proof; the mechanism, however, is not in doubt. - **@voltro/runtime, @voltro/data-transfer, @voltro/cli** — The `source:` recorder broke every WRITE on the in-memory store, and actions are recorded now. The recording wrapper is a `Proxy`, and it handed methods back unbound — so `this` was the PROXY, and a class with `#private` fields answers that with `TypeError: Receiver must be an instance of class InMemoryDataStore`. Under `voltro dev` on the memory store, where the recorder is installed by default, that is every write in the app. Every test passed throughout, and the reason is worth more than the fix: `query` is the one method the wrapper invokes with an explicit receiver, so everything that only READ through it worked. The wrapper's whole purpose is reading, so nothing in its own suite ever wrote. It was found by a test about something else entirely — asking what `crud.create` reads — which needed a write to answer. **Actions are recorded too now**, and an action's `source:` means something different from a query's. A query's is a reactive trigger set; an action's declares what it TOUCHES, and the field's own documentation records what an undeclared read costs: `voltro check` reported a table five action paths read and wrote as an orphan, and advised removing it. That is not a quiet subscription, it is advice to delete a live table. **Measured rather than reasoned about:** `crud.create`, `crud.update` and `crud.remove` issue NO read at all, so a read recorder has nothing to say about them — but `crud.getById` does read, and with `include:` it eager-loads, so it is covered like `crud.list`. **And a kill test for the one moment nobody had reproduced.** The existing test kills mid-LOAD, which staging turned into the harmless part; the destructive second went untested precisely because it became short. The new case kills as the swap begins and asserts the property rather than the race: the target is one state or the other, never a mix, and never empty. Two defects in the harness came out of writing it — a worker that died SILENTLY (its failure now goes into the marker the parent already reads, instead of looking like a slow start), and an `exit` listener attached only after the SIGKILL, which hung to the full timeout whenever the child finished first. **And the import trace was never written on the path most likely to be used.** A deployment ran a successful `voltro data import` against a database that HAD the table, and got no row and no message at all. The write was gated on this PROCESS's table registry, and `voltro data`'s own boot builds a store and introspects the live schema — it never registers the framework set, so the gate was `undefined` exactly there. The authority for "does the target have this table" is the target's SCHEMA, which that boot already introspects; the table is also registered before the write, because a CLI run has not done it and the write needs the column metadata. The sharper half is the silence, and it was self-inflicted: the skip was written three lines under a comment about how an absent table cannot be detected by the write failing. The message now lives in `voltro data import`, which is the layer that INTROSPECTED — a first attempt put it in the importer, where a `targetSnapshot` may legitimately be narrow rather than complete, so it fired at callers whose snapshot simply did not mention a framework table. ### Internal (no consumer-facing effect) - **@voltro/data-transfer** — `SAVEPOINT_BATCH_SIZE` carries its documentation again. A new `TRACE_ADVANCE_MS` was declared BETWEEN the constant's doc block and the constant, so TypeScript attached the block to whatever now followed it and the exported symbol was left bare — the api golden recorded it as `// @public (undocumented)` and the published report shipped it that way. Third time this exact shape has appeared (`sourceKeys`, `recordsTable`, now this one), always the same mechanism: an insertion above a documented declaration silently re-homes the comment. Nothing warns, because both the code and the doc block are individually valid — only the golden's `(undocumented)` marker notices, and it reads as noise unless someone diffs it against the last TAG. Documentation only; no behaviour, no signature change. **`apiSurface: compatible`, and the reason is the whole point of the change.** The golden line that moved is `// @public (undocumented)` → `// @public`: an api-extractor MARKER describing whether a doc comment is present. No type, no signature, no name. `SAVEPOINT_BATCH_SIZE` is still `= 200`, still exported, still the same literal type — nothing that compiled can stop compiling. --- ## [0.47.0] — 2026-08-22 ### Changed - **@voltro/database, @voltro/data-transfer, @voltro/cli, @voltro/plugin-storage** — A `--mode replace` no longer writes per-row history, and three things that were reported alongside it. **Write recorders are suspended for a `replace`.** A replace SETS a state; it does not change rows, so a per-row history entry describes something that did not happen. A deployment measured what that costs: they run `versioningPlugin({ timing: 'in-transaction' })` on 70 of 80 tables, so one import wrote 242 950 history rows and doubled the write load of the most expensive run they make — and those rows were the source of refused writes they spent three rounds diagnosing. The deciding argument is not the cost. **The import path had already decided this, and the recorder was the one layer that did not hear.** These routes write through the RAW store on purpose — no tenant scoping, no row filter, no `audit()` stamping. A recorder fired anyway because it hangs one level below the wrapper. Suspending it makes the layers agree. Suspended for `replace` only: an `upsert` or an `append` CHANGES existing state, which is exactly what a recorder is for. Scoped per execution context rather than by a switch, because an import runs while the app serves requests and a process-global flag would silently drop recording for everything concurrent with it. And every such run SAYS what it suspended — dropping history quietly would be the same defect in a nicer costume. This also removes the reason a staged `replace` used to fall back. A recorder is keyed by table name, so a staged write found none and the recorder never ran; rather than record inconsistently, the run took the slower path. For the deployment above that meant the staged path could never activate — permanently, on every environment. **`voltro codegen` wrote a truncated table declaration.** It discovered tables with the walk that collects the rpc GROUP's inputs — descriptors, workflows, events, and deliberately no `*.entity.ts`. So the generated `voltro-tables.generated.d.ts` listed the framework's tables plus `actors`, which the framework injects. Measured downstream: 37 names where a `voltro dev` boot writes 117, and 299 `TS2322` errors from every `source:` naming one of their own tables. The way in was our own message — `voltro test` refuses a stale rpc group and tells you to run `voltro codegen`. Table discovery has its own walk now, and a test compares the two walks' RESULTS on a real tree rather than trusting they mean the same thing. **The eager-relation doctor rule missed the state that is most wrong.** It resolved relations only against the tables a query already DECLARED, on the reasoning that the base is virtually always in `source:`. Measured: a query reading `projects` while declaring only `projectTeams` produced no finding at all, while the same query with the base added produced two. The base is a fact about the executor, so it is read from the executor now. **A rollback capture says when its path shares the root filesystem.** The 409 answered "is storage configured", which is not the question — a `filesystem` provider pointed at a container directory with no volume behind it passes it and dies with the pod. What a process CAN observe is that a mounted volume is a different filesystem: `pathDurability` compares device ids, and a capture landing on the same device as `/` says so. Three-valued on purpose, and explicitly not an alarm on a development machine, where everything is one device and nothing is a pod. **And the import records ITSELF, once.** Dropping per-row history left an operator asking "was this data imported, and when" with nothing to read, and trading too much for none is not obviously the better trade. `_voltro_data_imports` carries one row per RUN: the mode, the transport, the bundle, the SOURCE deployment's schema fingerprint, the counts, and — for the run an operator is actually looking for — the failure. It is written for a failed import as well as a finished one; a trail that only records successes goes quiet exactly when it is needed. Best effort, unlike the interrupted-replace marker, and the difference is deliberate: the marker is a safety interlock and a run that cannot write it must not proceed, while history is valuable and not load-bearing. A target that has not been migrated yet still imports, and says the trace could not be written. Two things it learned from being wired. The table is `.nonReactive()` — nobody subscribes to "an import happened", and a reactive bookkeeping write showed up in every suite that counts the LOAD's writes. And it is written only when the target actually DECLARES the table: the in-memory store accepts a write to any name, so an absent table cannot be detected by the write failing, and inventing the row would put a framework write into every embedder's counts. **Measured at the reported magnitude.** 114 tables, 243 048 rows, real MariaDB, staged replace: the whole run takes 56.5s and the DESTRUCTIVE TRANSACTION takes **1.13s**. The window in which a dead process can leave a half-replaced target is the second number; before this it was the first. --- ## [0.46.0] — 2026-08-22 ### ⚠ BREAKING - **@voltro/runtime, @voltro/cli** — An aggregate's `incremental.source` is a table name, and is now typed and audited like one. 0.45.0 narrowed a query's and a stream's `source:` for a specific failure: a name matching no table does not error, it produces a subscription that serves once and goes quiet. An aggregate's CDC source misses the same way and is quieter still — the runner subscribes to a table nothing writes, no delta arrives, and the aggregate stops tracking its input while every read of it succeeds and returns a number. It stayed `string` in that change, and not because anyone weighed it. It reads differently — `incremental.source`, a single name on a definition, rather than a list on a descriptor — so it did not fit the loop, and a shape that does not fit reads as a type mismatch instead of a gap. Both halves close now. The field is `TableName`, so a name no table carries is a compile error from the next `voltro dev`. And the boot audit takes aggregates alongside queries and streams, so a stale one is named in the same warning — the runtime half matters because a source can be correct at the type level and still be a table the deployment does not have. The audit's aggregate half runs on both boot paths and needed its OWN call on each, since aggregates are discovered several hundred lines after the existing one — which is precisely the shape that ends up wired on one path only, so it is asserted by name over both files. A recompute-only aggregate declares no `incremental` at all and is not audited: reporting an absence as an unresolved source would report a choice as a defect. **`voltro update` carries you across this** — codemod `0.46.0/01_typed-aggregate-source`. ### Added - **@voltro/data-transfer, @voltro/cli** — A foreign-key cycle is caught BEFORE a staged `replace` loads, and leftover staging tables have a command. Two things the staged swap left open, closed. **The cycle.** The swap inserts parents first, so two tables referencing each other cannot both be satisfied by a bulk copy on postgres, sqlite or SQL Server — and `SET CONSTRAINTS ALL DEFERRED` does not rescue it, because postgres only defers a constraint declared `DEFERRABLE` and the framework declares none. Until now that surfaced as a FAILED SWAP after the whole bundle had loaded: minutes of work, then a refusal. `topo.ts` already orders parents-first and breaks a cycle at its closing edge, so a cycle is exactly a reference pointing FORWARD in that order — cheap to see before anything is loaded. Such a run says so and takes the row-by-row path, whose deferred-FK pass exists for that shape. A table referencing ITSELF is deliberately not a cycle: one statement carries the whole table, measured on all five engines, and treating it as one would cost every app with an `audit()` mixin the staged path. **The leftovers.** A staged run drops-then-creates, so it collects its own; what survives is staging for a table set a later run does not touch. `voltro data clear-staging --yes` lists them and drops them. It is a COMMAND and not a boot sweep, which is the decision worth recording: a booting process cannot tell a leftover from a staging table another replica is loading into right now, and with several replicas that is not a rare race — one booting pod would delete an import in flight. The refusal without `--yes` says so, and names the tables so the operator can check before answering. **And `--no-atomic` stages too now, which is where the change is largest.** The flag exists for resumability on a large bundle, and it used to be the mode with the WORST failure: the target emptied and partially refilled, in neither state — the kill test measured 889 rows of 8 000. Staged, the ledger keeps its exact meaning (a recorded table is one fully loaded; it just lands in staging) while the target stays untouched until the swap. Resumable AND all-or-nothing, which the two flags could not be at once before. Three things came out of wiring it, and none was visible from the design. Dropping staging in the `finally` destroyed exactly what a resume needs, so a second run read from tables that no longer existed — found by the resume test, not by reasoning; staging is dropped only after a successful swap now, and a run that kept its rows says so. The SUCCESS case needed its own guard: after a completed run the ledger still says every table is done while staging is gone, so a re-run would have copied nothing over the target — `ledger.truncated` has always meant "the destructive step already happened" and the old path is guarded by exactly that flag, so it guards this one too. And the test lever was wrong at first: withholding the snapshot disables staging but also fail-closes the rollback capture, so the run refuses before loading — the unstaged case is now driven by the real reason, a registered write recorder. Two existing assertions inverted, and BOTH truths are kept rather than one replaced: `--no-atomic` now keeps the target when it can stage, and still costs exactly what it always did when it cannot. A killed staged run leaves the target's rows intact and writes no interrupted-replace marker — that state cannot arise on the staged path, so there is nothing for a boot to refuse over. - **@voltro/runtime, @voltro/cli** — `voltro dev` says when a query reads a table it did not declare in `source:`. The other half of the `source:` problem, and the one no static tool can see. A stale name is a compile error now, and the boot warns about one that resolves to nothing. A name that is simply ABSENT has never had an observer: the write lands, the row is in the database, a reload shows it, and the open panel does not move. The type is satisfied, the audit is satisfied, the write path is correct and its tests are green. So while `voltro dev` runs, every read is attributed to the query that made it and compared against that query's own `source:`. The finding names the table and what will not happen, once per query per boot. **The design question was never the recording, it was compose-vs-restrict.** Only a read that CONTRIBUTES rows belongs in `source:` — a restricting read re-running on every unrelated write puts every list back on the wire. An app that scanned its own source for this needed two hand-written exceptions to get from a thousand findings to thirty, and a rule needing an exception list on a correct codebase has already spent its attention. Neither exception is a list here. A table reached only through a predicate subquery is narrowing BY CONSTRUCTION — it returns no column to anybody — so it classifies itself off the descriptor, on every app, with nothing to maintain. And the framework's own restricting reads are ours: they are issued below the wrapper, or, where the framework runs APP code to decide access (a row filter's loader), marked at the call site we control instead of at the ones we do not. Deliberately narrow, and each edge is a decision rather than a limitation: it reports what it SAW and never claims a declaration is otherwise complete; a query with no `source:` at all is left alone, because the finding is about an incomplete list and not a missing one; and it says which tables it did not count, so the classification can be checked rather than trusted. Dev only. `voltro serve` installs no sink, which makes every part of it inert — no wrapper, no async-local write, no comparison. `VOLTRO_SOURCE_RECORDER=off` turns it off in dev. `restrictingReads` (`@voltro/runtime`) is the escape for an app helper that resolves access somewhere the framework does not call it. It is a no-op outside a recording session, so it can be left in place. Measured against a running `voltro dev`, not only in tests: a query declaring one table while reading two is reported once across eleven requests, and the correct queries beside it produce nothing. **Eager-loaded relations count, and they were the hole.** `.with({ subTasks: true })` issues no second read — `compileEagerJson` folds the whole spec into ONE round trip — so the loaded table is never a read's own table and never a join. It is a relation NAME on the descriptor, and the recorder resolves it through the relation registry: the target, and for a many-to-many the JUNCTION as well, since a write there changes membership, which is precisely the change a user makes. Nested `with:` recurses against the target's relations, the same walk the compiler does; an unresolvable name yields nothing rather than an invented table, and a throwing target thunk cannot take the request down with it. This was the reported failure's own shape, so the first version of the recorder could not see the case it was built for. Measured against a running `voltro dev` and real `POST /rpc` calls: twelve requests across four queries produced exactly two findings — the two deliberately-incomplete ones. The SAME eager load declared correctly beside them is silent, and so is a query with no `source:` at all. A check that only ever fires is not evidence that it fires for a reason. - **@voltro/cli** — `--rollback-key ` — a `replace` over `--target api` has the INSTANCE store the target's current rows in its own object storage before deleting them. The direct path already captured beside the bundle. That is useless on this transport, and the reason is the whole point: the process that would roll a transaction back IS the instance, so a capture in the pod's filesystem goes away with exactly the failure it exists for — a deployment lost 240 172 rows to a run whose api pod disappeared nine minutes in. Object storage is durable, is already configured wherever the storage-push export works, and is reachable afterwards from anywhere. Pushed BEFORE the first delete, through the same archive sink the export uses — one sink, not two, because two is how an instance comes to push a bundle and fail to keep one. A failure to store it stops the import with the target untouched. Fail-closed in both directions, deliberately: - asked for and impossible (no storage configured) → **409**, naming the fix. The request is the operator saying "I cannot afford to lose this", and serving them anyway is the one answer that removes their precaution while looking like agreement. - not asked for → the run proceeds and says what it did not keep. A `replace` into a scratch environment is legitimate, and refusing it would push people to the flag that turns the safety off everywhere. The decision is made from the headers alone, before a byte of the bundle is read: a run that cannot take the capture it was asked for must not cost an upload first. - **@voltro/database, @voltro/data-transfer, @voltro/cli** — An interrupted `replace` cannot be silent any more. The capture only helps if somebody knows to reach for it, and a half-replaced database is indistinguishable from an empty one FROM THE INSIDE — every table exists, every constraint holds, every query returns nothing without erroring. A deployment served over one for ninety minutes and only found out through an unrelated fingerprint mismatch. So a `replace` writes one row (`_voltro_replace_in_progress`) before the first delete and removes it after the last insert, and finding it at boot is a REFUSAL — on both boot paths, out of one function. The message names how many tables, how long ago, over which transport, and the capture to restore from, with the command spelled out. The row lives in the SAME transaction as the emptying, so it is present exactly when the emptying is: a run that rolls back cleanly takes the marker with it, and a boot over a database nothing happened to is not refused. A completed `replace` clears its own marker and every older one, so the recovery import restores the data and silences the alarm in one command. Nothing expires — a half-replaced database does not become whole with time, so `voltro data clear-replace-marker --yes` is a decision somebody makes. Measured against a live mariadb by killing a run mid-load: the marker is there, the refusal names the capture, and a completing run clears it. - **@voltro/data-transfer** — The staged-swap primitive for `replace` — load somewhere else, then swap the content in one short transaction. `--mode replace` empties the target and loads into it inside ONE transaction, held open for the whole network-bound load. A deployment measured nine minutes for 242 950 rows, and the promise that the target is left as it was found rests entirely on a live process being there to roll it back. A promise that rests on the process surviving is a promise about the weather. **The design the plan carried was wrong, and measurably so.** Shadow tables plus a final `RENAME` moves every inbound foreign key WITH the renamed table — postgres 17 by OID, MariaDB 11 and MySQL 8.4 by tracking the rename, including inside MySQL's atomic multi-pair `RENAME TABLE`. After the swap every key points at the table the design then DROPS. The atomicity of the rename, which that design reasoned about carefully, was never the hard part. Keeping the table OBJECTS and swapping the CONTENT has none of that: every constraint stays pointed at the same object, and the long client-driven load moves OUT of the destructive transaction, which then holds only server-side bulk SQL. **Four of five engines need no integrity switch, which inverts what the design assumed.** Three self-referencing rows — `actors.createdBy → actors`, the framework's own pattern — inserted by one `INSERT … SELECT`: postgres, SQLite and SQL Server take all three (they check at STATEMENT end); MariaDB and MySQL answer `ERROR 1452` (they check per ROW) and need the switch their own `emptyTables` already uses. Measured on each, and measured again after: a genuine violation attempted following the swap is still refused on all five, so the suspension does not leak past it. The statement builders refuse a table name outside the framework's identifier class. This module concatenates SQL and its names arrive from a bundle MANIFEST — a file an operator can edit — so the rule applied at declaration is re-asserted where the concatenation happens rather than assumed to have survived the round trip. Staging tables are `_voltro_staging_`, so the boot differ's framework-table asymmetry treats them as ours instead of planning them as user tables somebody forgot to declare. **The importer does not use it yet**, and attempting that integration is what surfaced two blockers worth stating: a staged write would fire a change event (waking reactivity, CDC and the analytics mirror for tables nobody declared), and it would miss the target's column metadata (`encodeRowForSchema` looks the table up by NAME, so a `json()` column would be written unencoded — a wrong value, not an error). Both are tractable; neither is a line-level change. Until then the two protections already shipped — the capture written before the first delete, and the marker that refuses the next boot after an interrupted run — remain what covers the reported outcome. - **@voltro/data-transfer, @voltro/cli** — `--mode replace` writes down what it is about to destroy. Before the first delete it exports the target's CURRENT rows — exactly the tables it will empty — as an ordinary bundle beside yours, and says where: rollback capture: 240172 row(s) across 75 table(s) → ./out.rollback-2026-… If this run does not finish, restore with: voltro data import ./out.rollback-… --mode replace It is on disk BEFORE anything is destroyed, so it depends on no transaction and on no process being alive to roll one back. That is the whole point: a deployment lost 240 172 rows to a `replace` whose api pod disappeared nine minutes in, and recovered from an export they had taken twenty minutes earlier out of HABIT. This is that habit as behaviour. It is NOT the fix for the class — the emptying must not become visible until the load stands, which is a rebuild — it is the small half that covers the reported outcome today. **Fail-closed.** A capture that cannot be taken stops the import before it starts, target untouched. A net you believe in and do not have is worse than none: the belief is what stops you taking your own export. The capture is a COMPLETE bundle over a snapshot narrowed to the emptied tables, not a `tables`-scoped one over the whole schema. Same files, different manifest — and the manifest decides whether it can be restored at all, since `replace` refuses a partial bundle for a reason that is exactly false here. `--no-rollback` opts out, `--rollback-dir ` relocates it. Only `replace` takes one: `upsert` and `append` destroy nothing. **Not on `--target api`, and it says so.** The capture would live inside the instance — the thing that can go away, which is the failure it exists for. A replace over that transport warns and names the export to take first. - **@voltro/database, @voltro/data-transfer** — Staging clones — the load-side half of the staged swap for `replace`. The swap primitive shipped without the importer using it, and two things stood in the way. Both are solved by ONE answer. A typed write resolves its table by NAME: `encodeRowForSchema` and `stampGeneratedId` both look it up in the registry. Writing to `_voltro_staging_notes` therefore found nothing — and the failure mode is not an error, it is a `json()` column written UNENCODED. Separately, every dialect store's insert ends in `routeEvent`, whose reactive guard reads `isTableReactive`, which is `isReactive !== false` — so an UNREGISTERED name counts as reactive, and loading a large bundle into staging would emit an event per row for tables nobody declared. A staging table registered as a CLONE of its target, marked `isReactive: false`, answers both: the columns resolve, and the guard the framework already has returns before the emit. `.nonReactive()` is the documented way to say exactly that, so nothing at the store needed a special case — and it is the clone rather than the absence that makes the load quiet, which is the part worth remembering if this is ever simplified. `registerStagingClones` returns a REQUIRED undo instead of trusting a caller to remember one. `allRegisteredTables()` feeds the declared set, the boot differ and `voltro doctor`, so a clone left in the registry reads as a table the app declares and nobody created. A failure part-way through registers nothing at all. `unregisterTable` is new in `@voltro/database` for this: narrow on purpose. `clearTableRegistry` wipes everything and exists for tests; this removes ONE name a bounded operation owns for its duration. **The precision is recovered, and it is strictly better than what it replaces.** Staging carries no foreign keys — required, since a staged row whose parent has not been staged yet must not be refused — so a violation moves from load time to swap time, where the database answers with one message naming a constraint. `stagedReferences` reads the edges INSIDE the replaced set off the snapshot the importer already holds (deliberately not `incomingForeignKeys`, which answers the already-answered question of keys pointing in from OUTSIDE), and `danglingProbeSql` asks STAGING the question the database was asking — against the STAGED parent set, because the swap inserts parents from staging and what matters is whether the reference resolves AFTER it. Measured against a live postgres with four staged children — one good, one NULL, two dangling — driven through a real failing swap: the database named `ghost`; the probe named `ghost` AND `phantom`, skipping the NULL and the good row. The row-by-row path stops at the FIRST failure, so a bundle with four bad references costs four round trips; this reports all of them in one pass. The target was verified unchanged afterwards, which is the first thing the message says. **The importer uses it now.** `--mode replace` stages when it can: create a staging table per table, load into those OUTSIDE any transaction, then swap the content across in one short transaction of server-side SQL. A process that dies during the load leaves the target exactly as it was, because nothing has been deleted yet — the destructive window shrinks from the length of the load to the length of a copy. Wiring it surfaced two more things, and neither was visible from the design. `INSERT … SELECT *` fails the moment the target has a STORED generated column — `CREATE TABLE … (LIKE t)` copies such a column as a PLAIN one (measured: `is_generated: NEVER`), so the select hands the target a value for a column it computes itself: `cannot insert a non-DEFAULT value into column "slug"`. The swap names its columns now, minus the generated ones, and `swapStatements` REFUSES an empty column list rather than falling back to `SELECT *`, so the trap cannot return by omission. And a WRITE RECORDER on any table in the set rules staging out. A recorder is keyed by table NAME, so a staged write looks up `_voltro_staging_notes`, finds none, and never runs — `versioningPlugin({ timing: 'in-transaction' })` promises "if the change committed, the entry is there", and the swap's bulk SQL has no per-row hook to keep that with. Measured, not guessed: the recorder went from more than one call to zero. Such a run keeps the path that honours it and SAYS why, as does a `--no-atomic` run or a store the framework cannot send DDL to. Every staged run says it staged. The two paths are indistinguishable from outside — both end with the target holding the bundle — and an operator deciding whether they can afford to interrupt needs to know which one is running. Verified through the real importer, and falsified before being kept: with staging off, the assertion that the target still holds its own rows WHILE the bundle loads goes red. On real postgres the staged path runs the existing foreign-key replace suite unchanged. ### Fixed - **@voltro/protocol, @voltro/voltro** — A `_voltro_*` name in `source:` is no longer narrowed against the generated table declaration. Which framework tables an app declares is DEPLOYMENT-dependent. The measurement is already in the maintainer notes: at one `NODE_ENV`, on one dialect, flipping a single flag adds or removes `_voltro_traces`, `_voltro_undo_log` or `_voltro_cdc_offsets` from the declared set. The generated `voltro-tables.generated.d.ts` is written by ONE `voltro dev` run, on one machine, with one set of those inputs. Narrowing framework names against it therefore made `source: '_voltro_traces'` compile for whoever generated the file and fail for a colleague — a type error decided by an environment variable, which is the exact class the declared-schema rule forbids one layer up. An app's own tables are unaffected: `_voltro_` is a reserved prefix, so every name a user writes for their own data narrows exactly as before. **How it surfaced is the part worth recording.** Until now `keyof VoltroTableNames` was always `never` inside this repo, so `TableName` was always `string`, so the narrow and wide types were the same type and every rule about them held vacuously. The first time an augmentation was ever present — a fixture that boots a real server writing the declaration beside its generated rpc group — four framework source files stopped compiling. The split had shipped without once being exercised in the direction that matters. Two things now stop that from going quiet again. A type-test program compiles the framework's own sources under an augmentation that deliberately declares NONE of its tables, and it lives in its OWN tsconfig: `declare module` merging is program-global, so a sibling type test's augmentation had silently rescued the very assertion this one exists to make. And `scripts/check-type-tests.mjs` (CI + `pnpm gate`) DISCOVERS type-test programs and runs them — because nothing did. The existing narrowing assertions had never been compiled once: excluded from their package's tsconfig for a good reason, and picked up by nothing else. It refuses a zero-program run, and a program that compiles zero `*.test-d.ts` files, for the same reason every other check here carries a floor. **Why `apiSurface: compatible`, and how to check it rather than take it.** The gate flagged the golden line as CHANGED and asked the right question — can this turn code that compiled into code that does not? Here it cannot, because the edit WIDENS a union, and every public position the type appears in is an INPUT: `source?:` on a descriptor, and `normalizeSource`'s parameter. Nothing in the published surface RETURNS `TableName` or `ReactivitySource`, which is the only direction in which widening breaks a consumer — an assignment FROM the type into something narrower. `@voltro/voltro` is listed beside `@voltro/protocol` because it re-exports the type, so its golden moved too; the gate matches per package, and one package's classification must not vouch for another's. - **@voltro/sql-mssql** — A `json()` column could not take a value on mssql. At all. store.insert(t, { payload: { a: 1 } }) -> TypeError: Invalid string. [EPARAM] store.insert(t, { payload: null }) -> OK So the column worked only while it held nothing. Reached first through `@voltro/plugin-versioning`, whose history row carries a full-row snapshot in exactly such a column: the versioning recorder could not write on that dialect, and therefore neither could any write to a table it covers. The store handed the caller's row straight to `sql.insert(row)`. The mysql store runs `encodeRowForSchema` first — the schema-driven step that turns a json value into text a driver can bind — and mssql had no equivalent anywhere on its write path, so tedious received a JS object for an NVARCHAR parameter and refused it. **Encoding alone would have been worse than the bug.** A value written as text and handed back as text means a WRITE returns a string where a READ of the same row returns an object, and nothing errors — the caller gets a different type depending on how it got there. So every `OUTPUT INSERTED.*` path decodes too (insert, insertMany, update, updateMany, patchJson, the delete old-image, and the MERGE upsert), and the test asserts the ROUND TRIP rather than the absence of an error, against a live SQL Server. With it, the mssql case is back in the versioning key-length suite — the bound on `id()` exists on that dialect too, and it was absent for one release only because nothing could write there. - **@voltro/data-transfer, @voltro/cli** — A `scope: all` bundle carried the exporting deployment's own bookkeeping, and `replace` wrote it into the target. The target's next boot refused to start: auto-migrate: SCHEMA FINGERPRINT MISMATCH — declared=6e2c61081a9ed80c live=28af9a54414f22f1 The refusal was correct and the row was the defect. A migration-ledger row is not DATA — it states which schema THIS deployment applied — and the fingerprint is computed over the declared table set, which legitimately differs per environment (`NODE_ENV=production` declares `_voltro_traces` and `_voltro_undo_log`; a `development` run does not). So the imported row was not stale, it was FOREIGN. The environment was down for ninety minutes, and the ledger row also HID the incident it travelled with: the api would not start, and the reason looked like the failed import rather than a row in a bookkeeping table. Ten framework tables are now classified as environment-local — the migration ledger, the file-migration and seed records, CDC offsets, schedule claims, wakeups, workflow watermarks / pending starts / admissions / pauses. They are dropped from an export's `all` scope, skipped on import, and never emptied by a `replace`, each with the reason a foreign row would be wrong stated beside it. Two of them would have made the target ACT: a pending start runs a workflow somebody queued elsewhere, a pause silently stops one here. `all` is the only scope filtered. A caller who NAMES one of these tables gets it — an explicit name is an expectation, and this module already refuses to drop those silently. The classification refuses to be incomplete: a guard scans every framework table and fails until a new one is decided either way. A hand-list rots by omission, and the omission cost ninety minutes. Also fixed, found while reading that path: the admin import endpoint spread `atomic` only when truthy, so an explicit `atomic: false` was dropped and the importer applied its own default — which for `replace` is `true`. The one value a caller can only express by asking for it was the one the wire discarded. --- ## [0.45.0] — 2026-08-21 ### ⚠ BREAKING - **@voltro/protocol, @voltro/cli, @voltro/voltro** — `source:` on a query is now typed against the app's own tables, so a typo or a missed rename is a compile error instead of a subscription that goes quiet. A `source:` is matched by NAME against change events, so a name matching nothing does not break the query — it makes it permanently silent: it compiles, boots, serves its first snapshot and never updates. From the outside that reads as a feature that does nothing, with a correct write path and green tests behind it. The boot has warned about this since 0.26.0, on both paths; a warning is read once, and a rename lands in a diff where nobody is checking strings. `voltro dev` writes `voltro-tables.generated.d.ts` beside the generated rpc group, augmenting `VoltroTableNames` with the FULL live set — app entities, plugin `extendSchema.tables` and the framework's own — from the same binding the boot audit resolves against, so the type and the warning cannot disagree about which tables exist. `source:` narrows to those names. Nothing changes at runtime: these are still string literals, so a descriptor carrying them is as browser-loadable as before. That is what ruled out accepting the table VALUE — a descriptor is loaded value-level by the web client, and a table value drags `@voltro/database` across that boundary. **Breaking, and filed that way after being written up as additive.** The test is not whether a symbol disappeared, it is whether code that compiled can stop: `['tasks', 'agent_messages']` was assignable and is not, which is the whole point where the name is stale and an obstacle where the source is genuinely computed. `normalizeSource`'s parameter narrowed with it. The wide shape stays public as `ReactivitySourceValue` for the computed case. The break does NOT land at upgrade time, which is why the codemod is a written note rather than a transform: right after `voltro update` the generated file does not exist, `keyof VoltroTableNames` is `never`, `TableName` falls back to `string`, and everything compiles as before. The narrowing switches on at the next `voltro dev` — a different command, by which point the change that caused it is no longer what the reader is looking at. A transform could not have found the sites either, since the type that rejects them has not been generated yet. And the two things `tsc` flags — a stale name versus a runtime-computed one — want opposite fixes, so the mechanical one (widen the annotation) would convert every defect this surfaces back into the quiet subscription it exists to expose. Delete the generated file and `source:` widens back to `string`. One deliberate asymmetry, stated because it is one: runtime READERS of a descriptor's source stay wide (`ReactivitySourceValue`). Narrow where an author writes, stay wide where the framework reads — a reader that refused an unknown name would be asserting a fact it cannot check, and the first thing it would reject is the stale name it exists to report. ### Added - **@voltro/cli** — `voltro doctor` reports a query that eager-loads a relation and does not declare its table in `source:` — the failure that looks like a broken feature and is not. The write lands, a reload shows it, every test of the write path is green, the name in `source:` is spelled right and the table exists. So neither the typed `source:` nor the boot audit has anything to say, and the only observer is a user watching a panel that does not move. ``` ✗ 1 query loads a relation it does not declare: tasks.getById: eager-loads `subTasks` from 'tasks' but does not declare 'task_sub_tasks' in `source:` — the view will not update when 'task_sub_tasks' changes. ``` No exception list, deliberately. An eager-loaded relation is composition by definition — its rows are IN the result — and its table comes from the relation registry, so the missing name is a fact rather than an inference. A many-to-many is reported twice when needed: adding or removing a link writes only the JUNCTION row, so declaring the target alone leaves the list stale on exactly the operation a user performs to change it. A computed `.with()` key yields nothing rather than a guess. The general question — every table an executor reads — is NOT answered, on purpose: it needs a compose-versus-restrict judgement a scan can only infer from syntax, and a rule that guesses on a correct codebase teaches its reader to ignore it. Design in `plans/open/framework/source-completeness.md`. Two things around it: - **The stale-`source:` audit covered queries only, on both boot paths.** A stream carries a `source:` too, and a stale one there is the same permanently quiet subscription with a longer-lived connection behind it. Both paths now take the set from one `auditableSources`. - **`voltro codegen` writes the typed-`source:` declaration too**, from the same shared `declaredTableNames` merge the boots use. Letting it lag was the bad direction: a table added since the last `voltro dev` would make a CORRECT `source:` a type error. Both commands now say what they wrote — the narrowing has a silent no-op if the app's tsconfig does not pick the file up, so the write has to be loud enough that a reader can check. ### Fixed - **@voltro/database, @voltro/sql-mysql** — A binding failure names the TYPE of every value, so the culprit is read rather than guessed. `ER_WRONG_ARGUMENTS` / 1210 reads like a count problem and often is not: a statement with twelve columns and twelve placeholders is internally consistent, and the driver is refusing one VALUE it cannot bind. Measured against a live mariadb 11.8 and mysql 8.4 (mysql2 3.22), binding to a PREPARED statement: | value | mariadb | mysql | |---|---|---| | plain object | **1210** | accepted | | array | **1210** | accepted | | bigint | accepted | accepted | | Invalid Date | accepted | 1292 | So the same row binds on one engine of the family and not the other — which is how a suite comes to fail on mariadb and pass on mysql in the SAME run, and why the type of each binding is the diagnosis rather than a detail. `describeDriverError` now reports `bindings: id:string data:Object changedAt:Date …` beside the placeholder count and the statement. Types only; a value there would be row data in a log line, the same reason the statement is carried only in its placeholder form. The types travel as a FIELD, not in a message. That is load-bearing: a failing write recorder rethrows with its own sentence, so anything said only in text is dropped exactly where it is needed. `extractDbCause` collects it like any driver field, so it survives every wrapper between the failing statement and the log. - **@voltro/database, @voltro/testing** — A driver error now carries the two numbers a binding failure is made of. `ER_WRONG_ARGUMENTS` / errno 1210 means the parameter count did not match the placeholder count — reproduced against mariadb 11.8 by sending one parameter for two `?` — and the message says only `Incorrect arguments to mysqld_stmt_execute`. Neither number was reachable from the error, so an investigation into one of these starts by eliminating hypotheses instead of subtracting. `describeDriverError` reports `placeholders=N` and the statement, and the statement is carried ONLY in its placeholder form. That restriction is measured, not cautious: against mysql2 3.22 the prepared path (`execute`) leaves `?` in `err.sql` because the server did the binding, while the text path (`query`) interpolates and the same field then holds row DATA. The placeholder is the discriminator, and the form that keeps it is exactly the form 1210 arises in. Alongside it, `reportEngineVersion` (`@voltro/testing`): a dialect suite prints the engine BUILD it ran against. A suite that is green on a developer machine and red in CI is only comparable if both name their software, and the test compose file uses moving tags — so "the same tag" is not the same build, and checking the tag locally observes what it points at today rather than what the runner resolved. - **@voltro/database, @voltro/plugin-versioning, @voltro/plugin-flags** — A versioned table whose NAME was long enough could not be written to at all. `id()` is `VARCHAR(64)` on mysql / mariadb and `NVARCHAR(64)` on mssql, and unbounded `TEXT` on postgres and sqlite. The versioning recorder built its history key by concatenation — `rowver___`, which is `42 + len(tableName)` characters for a 32-character row id — so a 22-character table name fit and a 23-character one produced `ERROR 1406 (22001): Data too long for column 'id' at row 1`. A recorder runs on EVERY write, so this was not a refused import: it was a table nobody could write to, on three of five dialects, at a boundary no one can see when naming a table. `derivedRowId(prefix, …parts)` (`@voltro/database`) derives a deterministic key of CONSTANT width — `rowver_<32 hex>`, 39 characters whatever goes in — joined over a `\u0000` separator so the parts stay injective (a `_`-joined key cannot tell `('a_b','c')` from `('a','b_c')`). Widening the column was the alternative and moves the wall rather than removing it; `id()` is also every user table's PK type. Nothing legible is lost: every table deriving a key this way already stores the parts in their own columns. The same construction was in `plugin-flags` (`flag_`, over an unbounded user-chosen flag key) and is fixed with it. A guard scans framework sources for an `id:` composed by interpolation and requires the helper, with an allowlist whose entries each name why their parts cannot grow — and which fails if an entry stops matching. Also fixed: the versioning suite's live coverage was postgres-only, and postgres is one of the two dialects where that column is unbounded, so it was structurally incapable of seeing this. `@voltro/sql-mysql` is a test devDep of `@voltro/plugin-versioning` now, with a mysql+mariadb case driving an ordinary insert and update against a 33-character table name. - **@voltro/database, @voltro/cli** — Two gaps on the `--target api` path, both about a failure that is present and unreadable. **The driver was unreachable behind a WRAPPED rejection.** `extractDbCause` unwrapped a `FiberFailure` at the root only, so one reached through a `.cause` link stopped the walk — it carries `stack`, `message` and `name` and nothing else, which is indistinguishable from "no driver under this". That is exactly the shape a failing write recorder produces: it rethrows `new Error(, { cause: err })` where `err` is the rejection its own insert made. So the same database refusal classified where no recorder runs and degraded to the bare runtime rendering where one does — which is the difference between the direct importer and an import through a running app with versioning or audit on. The walk now unwraps at every link. **And the refusal report was never printed on that transport.** A refusal that crossed HTTP arrives as a 500 whose message embeds the `RowsRefusedError` as JSON; the CLI printed that body raw. So the operator on the transport that exists for "the database is somewhere you cannot open a shell" got the one output that has to be triaged by hand — and tallying the capped row list is how a per-table distribution gets reported that is not the real one. `--target api` now prints the same report as the direct path, `byTable` line and cap notice included. - **@voltro/data-transfer, @voltro/cli** — Two reporting defects that made a refused import unreadable, both of the shape "the payload is present and property access is not the way to it". **A refusal lost its tag on the mode that raises it most.** `--mode replace` runs in one transaction by default, and rolling that back needs a rejection — which the atomic wrapper obtained by throwing `new Error(Cause.pretty(cause))`, a rendering rather than the failure. From there the typed error could not come back: it was re-wrapped as a `BundleError` carrying itself as text. So `Effect.catchTag('RowsRefusedError', …)` matched nothing on the default path, `ImportError`'s union was a claim that path could not honour, and the CLI's refusal report — which branches on the tag — printed nothing at all. The typed error is thrown and passed through now; `asImportError` is exported for callers who catch the rejection rather than the effect. **And the report read the tag off a `FiberFailure`.** What `Effect.runPromise` rejects with does not expose `_tag` by property access, so the renderer took its "not my error" branch on every direct-path run while being wired, tested and correct — the test drove the renderer with the error object, which is not the shape the call site produces. A reported refusal now also ENDS the command instead of being rethrown into `fatal unhandled cli error`: a refusal is a condition with a named cause, not a framework defect. **An api host is no longer reported as an unreachable database.** A connect failure carries an address, a port and an errno — the same shape a database driver's carries — and one global handler renders that shape, so `--target api --api-url https://…` against a stopped instance printed `the database is not reachable at :443 … Configured by: DB_URL` with `DB_URL` not in play. The transport names its own failure now (`InstanceUnreachable`), and the database explainer declines an endpoint whose PORT cannot be a database — judged by port because a driver reports the resolved address, so a host comparison would silence the real message for anyone naming their database by hostname. ### Internal (no consumer-facing effect) - **@voltro/sql-postgres** — A test teardown terminated connections its own pool was still closing, and the resulting error failed the RUN rather than any test. `clusterColdStart` drops a per-run database, and the runners it spawned are killed with SIGKILL, so their backends never close — hence the deliberate `pg_terminate_backend` before the `DROP`. But `pool.end()` resolves once it has ASKED the pool to close, not once every socket is down, so the terminate could also land on a connection belonging to the test itself. `pg` reports that as an `error` event on the idle client, and an unhandled one takes down the process. The shape it took on a release gate is the reason this is written down: **36 of 36 test files green, and the suite exiting 1.** Nothing points at the teardown — the failure is attributed to whichever suite happened to run last, which is a different one each time. A connection error while we are tearing the database down carries no signal, so it is handled where it arises. Test-only; no product code changed. - **@voltro/plugin-auth** — The TOTP skew-window test uses a fixed secret. Test-only; no product code changed, and the assertion is unchanged. It failed once on a release gate — `expected true to be false`, meaning a code two steps outside the ±1 window verified. That is the shape of a security defect, so it was treated as one until measured: - `TOTP_SKEW` is 1 and the verify loop checks exactly three counters, compared with `timingSafeEqual`; - `T0` is a constant and the clock is injected, so the only varying input was `generateTotpSecret()`; - over **50 000 fresh secrets**: zero collisions between the ±2 codes and the ±1 window (pure chance predicts ~0.3), zero degenerate secrets, uniform length; - **60 consecutive runs** of the file: green. So the implementation is sound and that red was two 6-digit codes coinciding — about six in a million per run. Worth stating plainly: that makes the observed failure a one-in-167 000 event, which fits every measurement and is still remarkable. It was not reproduced. The fix is to remove the coin flip rather than to re-run until green. A random secret buys this test nothing — the property under test is the WIDTH of the window, which does not depend on which secret is used. It only buys a rare red that costs a diagnosis cycle and teaches the reader to re-run. Pinned, so the next failure there means the window moved. --- ## [0.44.1] — 2026-08-19 ### Fixed - **@voltro/database, @voltro/data-transfer, @voltro/cli** — A refused import row reported `(FiberFailure) SqlError: Failed to execute statement` — our runtime's rendering of a rejection, marker and stack frames and all — instead of the constraint that fired. It names neither a rule, nor a code, nor even which layer refused, and every row refused for the same cause carries it identically. Two defects, and fixing either alone still leaves a reader stuck. **`Cause.squash` elects a branch, and first is a position, not a ranking.** A `Cause` is a tree, and a transaction routinely produces one with more than one leaf: the statement that failed, and whatever the rollback or a finalizer did on the way out. When the first leaf was the bare wrapper, the driver error sitting in the sibling branch was never looked at. Measured: `sequential(bareSqlError, sqlErrorWithDriver)` classified as nothing while the same two branches in the opposite order classified as `unique constraint PRIMARY … [ER_DUP_ENTRY/1062]`. `extractDbCause` flattens failures AND defects now, in Cause order, expanding a nested `FiberFailure` leaf, and elects the branch that names a driver — the others' chains are appended rather than dropped. **A row's reason may never read like a stack trace.** The runtime rendering is stripped before any tier looks at the text, so the failure mode cannot return invisibly. And when no driver detail is reachable at all, the reason now names the CHAIN of wrappers the failure passed through — the difference between "the database refused this row" and "the connection died mid-import" — while the run logs the full rendering of the first few such failures. Never returned over the wire: it carries frames, and on some engines a driver's sentence carries row data. `RowsRefusedError` also gained `byTable`: **complete** per-table counts. `rows` is capped at 20, so per-table counts tallied off the printed list sum to the cap rather than to the failure — and nothing else in the payload offered any. --- ## [0.44.0] — 2026-08-19 ### ⚠ BREAKING - **@voltro/data-transfer, @voltro/cli** — `runImport` returns an `ImportOutcome` instead of the bundle's `Manifest`, and `--mode replace` runs as ONE transaction by default. **Why the return type changed.** The summary line counted the rows the BUNDLE carries, not the rows the run wrote. Those differ most exactly where it matters: a bundle directory carries its own resume ledger, so a copied directory imports nothing — correctly, with a warning naming the file to delete — and the run then printed `import complete … rows: 242950` over a target it had not touched. The warning was one line above, which is one line too far for anyone piping the output through `tail -1`. The outcome carries `rowsWritten`, `rowsSkipped` and `fullyResumed`, the CLI reports written-vs-carried, and a fully-skipped run says so on its LAST line. Migration: `runImport(...)` now resolves to `{ manifest, tablesWritten, rowsWritten, tablesSkipped, rowsSkipped, fullyResumed }`. Read `.manifest` where you read the manifest before. **Why replace is atomic now.** The all-or-nothing guarantee was written for the emptying step, and read — reasonably — as covering the run. A replace that died partway through the LOAD left the target emptied of its old rows and holding part of the new ones, measured on a live instance over sixteen minutes. There is no useful state for a replace to stop in, so it is a default rather than a flag you have to know about. It also closes the window that produced that failure: with the tables emptied and the load uncommitted, a concurrent writer in the application waits instead of inserting a row the bundle is about to insert too. `--no-atomic` (CLI) / `atomic: false` (API) opts out. The trade is stated where it bites: every write to those tables waits for the load, and on postgres the bulk `COPY` loader cannot join a transaction it does not own — an atomic run now says that once rather than being quietly slower. Two smaller things from the same report: `--mode replace` against a running instance warns about the empty-target window when it is NOT atomic, and the `--target api` upload reports progress per chunk plus a line explaining that the final request stays open for the whole import — sixteen minutes of silence is indistinguishable from a hang, and one operator killed a run that had finished. **`voltro update` carries you across this** — codemod `0.44.0/01_import-outcome`. ### Fixed - **@voltro/sql-mysql, @voltro/sql-postgres, @voltro/sql-sqlite, @voltro/sql-mssql, @voltro/data-transfer** — A write and its write-recorders now succeed or fail together on every SQL dialect, and the data importer's retry is idempotent. A recorder (a versioning trail, an audit log) runs on the caller's connection and is ALLOWED to fail — a recorder that throws must take the write down with it, that is its contract. Outside a caller transaction the two were not one unit: the row's statement committed on its own, and the recorder's INSERT ran afterwards as a second autocommit statement. So a recorder that threw left a COMMITTED row behind a write that reported failure. Measured directly: `insert` throws, the row is in the table, and a second attempt at the same row is `ER_DUP_ENTRY` on PRIMARY. Anything that retries a failed write then meets its own row. The data importer retries by design — it holds a row whose write failed and tries again once the remaining tables have streamed — so a `--mode replace` that had just emptied a table failed on a duplicate key IN that table. From outside, that is the impossible-looking thing: an import that emptied a table and then failed because something was already in it. Reproduced verbatim, including the table name and `[ER_DUP_ENTRY/1062]`, by putting the old retry back. Both ends are closed, and they are independent on purpose: - **The cause.** A table that HAS recorders writes inside a transaction now, so the row and the trail commit together or not at all — on mysql, mariadb, postgres, sqlite and mssql, verified by one suite that asks all five the same question. A table with no recorders — the default — takes the direct path unchanged; `recordsTable` is a Map-size check first, so it costs one comparison. - **The defence.** The importer's retry upserts instead of inserting in `replace` mode. That covers every OTHER way a write can land while reporting failure: a driver timeout on a write the server applied, a connection lost after the commit, a concurrent writer inserting the same key. It is sound precisely because the table was emptied by this same run — there is nothing in it that is not ours. The test that pinned the divergence went red when the fix landed, exactly as its own note said it would, and is inverted with that note kept. --- ## [0.43.2] — 2026-08-18 ### Fixed - **@voltro/sql-mysql, @voltro/database, @voltro/cli** — The mysql-family binlog reader no longer keeps a table excluded after the very migration that fixed it. A UNIQUE on an unbounded text column is a MariaDB hash long-unique, whose hidden `DB_ROW_HASH_n` column the reader can never account for — so the table is held out of binlog capture and the exclusion is reported. `voltro dev` builds its store BEFORE it migrates (kv, cross-replica broadcast and the analytics mirror all need one), so on a boot whose own auto-migration bounds the column, that finding was drawn from a schema that stopped existing about a second later. The exclusion then outlived its cause for the life of the process, and the message — correct when written, and typically the only error line in the boot log — went on describing the pre-migration database. Three changes: - `DataStore.refreshChangeCaptureExclusions()` (optional; implemented by the mysql-family store) re-runs the probe and re-points the LIVE reader, in both directions — schema work that CREATES the condition now excludes the table immediately instead of after three failed writes. `voltro dev` calls it once, after all its schema work. `voltro serve` needs no equivalent: it builds its store after every schema step and never applies DDL itself. - The definitive message now states its own durability — that it is the schema as read at reader attach, and that applying the remedy does not by itself lift the exclusion. - On a boot that will re-check, the finding is reported as a provisional note rather than as a verdict, so a boot that fixes the condition leaves no error line about it. The note escalates to the full verdict on its own if the re-check never runs. - Two reader fixes the re-check depended on: applying a new exclusion set now WAITS for a reconnect already in flight (it is what applies the set, so resolving before it landed meant the caller's next write hit the old filter), and the reconnect loop no longer keeps resuming from an offset it has just jumped away from — that turned one purged offset into a reconnect every watchdog interval, forever, delivering nothing. - **@voltro/data-transfer, @voltro/database, @voltro/sql-mysql, @voltro/sql-postgres, @voltro/sql-sqlite, @voltro/sql-mssql, @voltro/cli** — `voltro data import --mode replace` no longer leaves a target in neither state, and now works against schemas that have foreign keys. The delete step ran table by table and stopped at the first refusal, so a run that could not finish left dozens of tables emptied and nothing loaded — and a second attempt destroyed more than the first, because it got further before hitting the same wall. The wall itself was not exotic: MySQL, MariaDB and SQL Server check a foreign key as each ROW is deleted, so a table that references ITSELF cannot be emptied by any ordering of the tables. `createdBy → actors` on the `actors` table is exactly that shape, and it is what an audit mixin on an actor table produces. - `DataStore.emptyTables()` (per dialect) empties the whole set as one unit, in one transaction, with referential integrity suspended for the duration — `FOREIGN_KEY_CHECKS` on the mysql family, a multi-table `TRUNCATE` on postgres, `defer_foreign_keys` on sqlite, per-table `NOCHECK`/`WITH CHECK CHECK` on mssql. All-or-nothing on every engine, including under `--atomic`, where it runs on the transaction the import already holds. - A **pre-flight refusal**: if a table OUTSIDE the bundle holds rows referencing one inside it, the import refuses before deleting anything and names the tables, the columns and the row counts. Those rows cannot be restored from the bundle, so forcing it is not an option. An EMPTY outside table blocks nothing. - Table-level failures carry the driver's own reason and code, the way row-level failures already did. `truncate failed: Failed to execute statement` fits every plausible cause equally; the classification that produced `foreign key : … [ER_NO_REFERENCED_ROW_2/1452]` one level down now applies one level up. The word "truncate" is gone from the message too — the step issues DELETE, and naming a statement it does not run sends whoever reads it to reproduce the wrong thing. - A typed refusal reaching the `--target api` transport keeps its text: the admin import endpoint answers `409` with the reason instead of flattening it to `import failed`, on the one transport where the operator has no other way to see it. The bulk empty emits no change events, where the per-table loop emitted one per row. An import through `--target api` now asks every live subscription to re-read once it lands — the coarse refresh the framework already uses after a broadcast gap — so neither the missing deletes nor a table the bundle carries EMPTY leaves a subscriber holding rows that are gone. Wired where the route is mounted, which is the one place both boot paths share. On postgres the emptying is a `DELETE` per table, not a `TRUNCATE`, and the difference is not performance: postgres refuses `TRUNCATE` on a table with ANY incoming foreign key, rows or not, while the mysql family refuses a DELETE only when rows actually reference the doomed ones. A `TRUNCATE` version made an EMPTY table outside the bundle block a replace on postgres and not on mariadb — one import, refused on one engine and accepted on the other, over a table holding nothing. `--target api` also no longer times out on a full bundle. Both api-target calls went through `fetch`, whose undici default gives up after 300 s — a bound on the caller's database size, on a call whose response arrives only when the import does. They wait as long as the instance needs now, stream the body instead of buffering the whole bundle, and take `--timeout ` when a deadline is wanted. If one is hit, the message says the instance is probably still importing — and gives different advice for `replace` than for the idempotent modes, since re-running the first while it is mid-flight would empty the target under it. Two more, found by measuring rather than by reading: - **`--atomic` on postgres could not import a bundle that needed the deferred-FK repair at all.** A failed statement aborts the transaction there, and that repair depends on a row whose parent has not loaded yet failing, being held, and being retried — so the first such row poisoned every write after it. Every tolerated write now runs inside a savepoint. Per-row savepoints measured 2.40x the time of none on 5 000 rows, so they are amortised: one savepoint per batch of 200, and a batch that fails rolls back whole and replays row by row. The mysql family and sqlite leave a transaction usable after a failed statement and pay nothing for any of this. - **The replace pre-flight asked the caller's snapshot.** Over `--target api` that is the app's DECLARED schema, which cannot show a table the app stopped declaring but the database still has — and rows in a table nobody declares are exactly the rows nobody is watching. `DataStore.incomingForeignKeys()` reads the live catalog per dialect; the snapshot remains the fallback for stores without one. A bundle bigger than one chunk is now uploaded as a series of short requests, so a proxy body cap or an ingress read timeout has nothing large to choke on, and the switch is automatic — the packer's stream is buffered one chunk ahead, so a small bundle is sent exactly as before and nobody has to know in advance which table is the big one. The import still runs ONCE, at the end, over the whole bundle. Resume is byte-exact (`packBundle` is deterministic over a directory, which this package now asserts), guarded by a bundle key so a different bundle under the same upload id is refused rather than spliced into the partial one, and by a contiguity check so a mis-ordered append cannot produce an archive that only fails later during decode. `--chunk-size ` overrides the 16 MiB default. --- ## [0.43.1] — 2026-08-18 ### Fixed - **@voltro/database** — A write recorder that fails inside someone's transaction now says which recorder, on which write, and what the database actually said. `@effect/sql` renders every driver failure as `SqlError: Failed to execute statement` — one sentence that fits a missing column, a dangling foreign key, an over-long value and a duplicate key equally. The driver's own words hang off a SYMBOL on a `FiberFailure`, so a caller who reaches for `.cause` gets `undefined` and concludes there is nothing there. That is expensive precisely where recorders run: the caller's write was ordinary, and what failed was framework machinery one table over. The message now reads ``` write recorder '_voltro_row_history' failed while recording an update on 'users': Duplicate entry 'rowver_…' for key 'PRIMARY' [code=ER_DUP_ENTRY errno=1062 …] ``` and the original error is kept as `cause` for anyone who does walk the chain. The failure still takes the transaction down — that is the guarantee and it is unchanged. `describeDriverError` (`@voltro/database`) is the shared summariser, built on the existing cause extractor rather than a second walker. It returns nothing when the chain carries nothing driver-shaped, so an ordinary programming error from a recorder arrives as itself instead of wrapped in prose about a database. - **@voltro/database** — On MariaDB, a `varchar` column could introspect as `json` because a DIFFERENT table had a json column with the same column name. MariaDB names a column-level CHECK after the COLUMN, and those names are unique per table, not per schema. `information_schema.check_constraints` on MySQL has no `TABLE_NAME`, so the introspector recovered it by joining `table_constraints` on `(schema, constraint_name)` — which on MariaDB cross-products every same-named check across every table. Measured on 11.8: ``` a.payload LONGTEXT CHECK (json_valid(`payload`)) b.payload VARCHAR(255) CHECK (`payload` in ('x','y')) join result: a → json_valid, a → in(…), b → json_valid, b → in(…) ``` So `b.payload` reads as `json`, and `a.payload` picks up an enum it does not have. Downstream that is not a cosmetic label: the planner emits a blocked `alter-column-type` with `from: 'json'` that no `.narrowedFrom()` can honestly acknowledge, because the premise is false — and since the data-transfer manifest records introspected types, the same misreading travels into the bundle and reappears as schema drift on import. MariaDB's own `check_constraints` HAS `TABLE_NAME`. The introspector asks for it directly now and keeps the join as the MySQL path, where check-constraint names are schema-unique and the join is sound. That asymmetry is why a single-engine test could not see this: the wrong query passes on MySQL. - **@voltro/database** — `voltro db apply` could not drop a CHECK constraint on the mysql family at all, and each of the three reasons hid the next. **1. `DROP CHECK` is MySQL-8 syntax.** MariaDB has never had it — measured on 11.8, `ALTER TABLE t DROP CHECK c` is `ERROR 1064`, while `DROP CONSTRAINT c` works on both engines. A plan containing a `drop-check` therefore died on the first one, on a family whose migrations are NOT atomic: the run stopped with the earlier statements committed and no rollback. **2. The name was assumed, not read.** The applier dropped `
__check` — which is only what its own `add-check` would have named it. A CHECK created at table bring-up is INLINE and UNNAMED, so the server names it (`CONSTRAINT_1` / `
_chk_1` / the column name). Dropping a name that does not exist reports "does not exist", which is indistinguishable from the "already gone" a resume legitimately produces — so the statement succeeded, the constraint stayed, and the plan re-proposed the identical `drop-check` forever. The name comes from the catalog now. **3. A column-level CHECK cannot be dropped by name on MariaDB at all.** Measured: the catalog lists it under the column's name, `DROP CONSTRAINT` on that name answers 1091, and only redefining the column removes it. The applier now drops by catalog name, ASKS whether the constraint survived, and redefines the column when it did — so a rebuild happens only in the case that needs one. **And the same investigation closed the MySQL `.oneOf()` round-trip gap.** `parseEnumCheck` was documented as handling MySQL's rendering and did not: MySQL backslash-escapes the string DELIMITERS (`_utf8mb4\'draft\'`), and the parser rewrote those to the SQL doubling `''` — which is how a quote INSIDE a value is written. Every delimiter became escaped content, every value came back empty, and the filter dropped them. `.oneOf()` now round-trips on MySQL, and the suite that asserted the gap as a known one asserts the round-trip instead. Plus, on a failed apply: the error now states how many operations were already applied and whether this dialect rolls back. The ledger held that number; it never reached the operator, who had to re-plan and diff the counts to learn how far the run got. - **@voltro/plugin-versioning** — `versioningPlugin({ timing: 'in-transaction' })` built its history row's primary key from `(rowId, version)` while the version counter three lines above was scoped to `(tableName, rowId)`. Two versioned tables carrying the same row id therefore collided — permanently. The shape is not exotic: `actors.id === users.id` is what the framework's own audit trail asks for, an `actors` row whose id is the user's so an audited write satisfies `createdBy → actors`. In an app that follows it, every user row has a twin. The collision does not heal, and that is what turns a duplicate into an outage. The second table's insert fails, so its history row is never written, so `maxOf` for that table stays `null`, so the next attempt computes the same version and the same id. Every write to that row is dead from then on — surfacing as `ER_DUP_ENTRY` on an ordinary `store.update`, naming a row id in a table the caller never wrote to. The key is `(table, rowId, version)` now — the same shape the post-commit path always built. It stays deterministic (no clock, no process-local counter), which is what lets it survive a replica restart; it just carries every part of the key it claims to be unique over. **No cleanup is needed for rows already written.** They keep their old ids and belong to whichever table wrote them; the new keys cannot collide with them, and `byRow` is not unique. An app blocked by this is unblocked by the upgrade alone. Covered twice: the recorder against a port that refuses duplicates (the mechanism, including that a repeat does not settle), and two versioned tables sharing an id against live postgres (the real primary key, inside the caller's transaction). The suite that existed exercised ONE table, which cannot produce a collision at all — and read exactly like a suite that covered this. ### Internal (no consumer-facing effect) - **@voltro/sql-mysql** — Two test-only defects in `sql-mysql`, both found by a release gate, both of the same family: a check that could not fail, and a failure reported in the wrong place. No product code changed. **An assertion that could not fail.** `dropCheckSyntax.integration.test.ts` fell back to a HAND-BUILT plan when the planner produced no operations — and the fabricated operation was a `drop-check`, which is exactly what the next line asserts the plan contains. So an engine whose planner stopped emitting it would have been handed one and reported green. The fallback is deleted; both engines produce the operation now, which is what this release fixed, and the assertion is load-bearing again (4/4 on mysql AND mariadb without it). It surfaced as a TYPE error rather than a false pass, because the fallback's object widened `plan` into a union `applyPlan` does not accept. Worth noting which check caught it: `vitest` transpiles without type-checking, so the suite was green and only `tsc` objected — the gate's `typecheck` and `lint` steps are what went red. **A wait that gave up in silence.** `waitFor` in both binlog CDC suites looped to a deadline and then RETURNED, so a "prove the reader is live" wait that expired let the test carry on, kill the binlog dump thread, and fail twenty lines later on `expect(ids).toContain('todo_wd_before')` — an assertion about a different claim, in a different place. It throws now, naming the wait and the window, and all twelve call sites carry a label. The window is named too: `FIRST_ATTACH_MS = 30_000`, up from 12 s. The reasoning is the 40 s window already in the same file, whose comment says a re-attach plus binlog catch-up takes longer under a loaded full-suite run — a FIRST attach does both and only skips the backoff, so 12 s beside 40 s was an asymmetry the file's own reasoning did not support. That is an argument from the neighbouring comment, not a measurement; if it expires again, `waitFor` now says which wait and for how long, and that number is the one to argue with rather than raising this one twice. --- ## [0.43.0] — 2026-08-18 ### ⚠ BREAKING - **@voltro/data-transfer, @voltro/cli** — `DanglingReferenceError` is now `RowsRefusedError`, and it separates the rows that failed from the rows that failed because those rows did. **The name.** The import raised it for EVERY row still refused after deferred-FK resolution, whatever the reason — a NOT NULL violation, a duplicate key, a value the database computes for itself. The tag named ONE possible cause and put it where a reader looks first, so any other refusal arrived mislabelled. The new name states the outcome; each row's `reason` states the cause, which is where a cause can honestly be claimed. **The split.** A row is `derived` when one of its reference columns holds the primary key of another row that also failed in this run: it could not have landed whatever it contained, so its reason describes the parent's problem. The relation is transitive, decided from the DATA (the failed ids against the reference-typed values), so no schema knowledge is needed. `primaryCount` is the number an operator acts on, `rows` lists primary failures FIRST so the cap never spends its budget on consequences, and the CLI leads with both numbers: ``` import refused 300 row(s), of which 1 are the actual failures — the rest could not land because a row they reference did not. teams t1 foreign key teams_ibfk_1: the referenced row does not exist [1452] … and 299 row(s) behind them. Fix the 1 above and re-run; they resolve with their parents. ``` In an FK-dense bundle one refused parent takes its whole subtree with it, so the length of a flat list says how connected the data is, not how many problems there are — and the single row that explains all of them sits somewhere in the middle of it. The codemod rewrites the import and every use of the symbol. It does NOT rewrite a tag STRING (`Effect.catchTag('DanglingReferenceError', …)`, `err._tag === '…'`) — change those to `'RowsRefusedError'` — and the payload gained `primaryCount` plus a `derived` flag per row. ### Fixed - **@voltro/cli** — `voltro doctor`'s `subject-write-no-guard` rule reads the DESCRIPTOR before it reports. It looked only at the executor, and the access decision is not declared there. Every form of access decision the framework has — `internal: true`, `guards: [...]`, `openAccess:` — is declared on the DESCRIPTOR. So an app that declares them properly got a finding for each one, and on a codebase whose procedures are mostly `internal: true` the rule fires on essentially all of them and is wrong essentially every time. That is worse than a rule that finds nothing: it is the longest line in the report and it reads like a security finding, so it teaches the reader to skim the place a real finding would have appeared. The premise was structurally impossible for most of them, and the framework says so itself: `security.defaultDeny` refuses at boot any wire-exposed procedure declaring neither `guards:` nor `openAccess:`. So "an anonymous caller reaches the write" can only be true of an `openAccess` procedure. That is what the rule looks for now — plus the handler check it always honoured, plus an ownership comparison against `subject.id`, which is the refusal the rule says is missing. Where no descriptor can be read, it says nothing: the claim is about a declaration, and a finding whose evidence was never opened is the failure mode this fixes. The `use:` line changed with it. It recommended `.guard(requireScope('…'))`; the shipped guide teaches declarative `guards:` and calls a hand-written per-executor scope check the thing `guards:` exists to delete. A rule may not recommend the shape the guide argues against. - **@voltro/database, @voltro/data-transfer** — A `voltro data` transfer no longer carries GENERATED column values, and no longer loses every row that has one. The export wrote the computed values into the bundle and the import sent them back in the `INSERT` column list. MariaDB refuses that for any value except NULL (`1906: The value specified for generated column 'x' in table 't' has been ignored`); postgres refuses a non-DEFAULT value outright. So the transfer failed per ROW, not per table, and only for the rows whose generated value was non-NULL. That selectivity is the dangerous part. `.uniqueActive()` lowers to exactly such a column on mysql/mariadb — a STORED generated column holding the key while the row is live and NULL once it is soft-deleted — so the refused rows are the LIVE ones and the accepted ones are the tombstones. A table can come out looking like "a few rows failed" or empty, depending only on how many of its rows are deleted, and any table with a foreign key into it fails behind it. Both ends are fixed from one source of truth: **introspection now reports generated columns on every dialect** (`generatedAs`, from `information_schema.generation_expression` on mysql/mariadb, `is_generated` on postgres, `PRAGMA table_xinfo`'s hidden flag on sqlite, `sys.computed_columns` on mssql). It was declared-side only before — invisible to the planner, which does not compare it, and load-bearing for anything that writes rows back. The exporter omits those columns, values and all. The importer strips them from every incoming row using the TARGET's snapshot, because a bundle already written still carries them and a file on disk is data, read where it is. **`voltro serve`'s admin export/import needed a second fix, and without it this one reached only the direct transport.** The running instance hands those handlers `declaredSnapshot(tables)` — no dialect — and `.uniqueActive()` lowers to a generated column only when the snapshot knows the engine. So over `--target api` the snapshot described a schema with no generated columns while the database had several, and the export wrote their values back into the bundle exactly as before. It passes the dialect now (the variable was already on the next line). `generatedAs` is also kept OUT of the schema fingerprint. Introspection can read the fact back but not a comparable value — the engine returns its own normalisation of the expression, never the declared spelling — so hashing it would make declared and live disagree permanently: a schema nobody touched reporting a changed declaration on every boot, and a transfer target that matches its bundle exactly refused as drifted. Covered by a live mariadb→mariadb and mysql→mysql round trip over a `.uniqueActive()` table with live and soft-deleted rows, asserting the target recomputed the value rather than that the row merely arrived. - **@voltro/sql-mysql** — On mysql/mariadb, a write REJECTED by the database through `insertIgnore` was reported as a conflict when the caller was not inside a transaction — and never reached the caller as a typed `ConstraintViolation` at all. Two causes, both measured against live MySQL 8.4 and MariaDB 11. **The connection.** `INSERT IGNORE` demotes every error to a warning, so the store reads `SHOW WARNINGS` to tell a rejection from a conflict. That describes the last statement on a CONNECTION, and outside a transaction every statement acquires its own from the pool — so the read was unattributable and came back empty. The rejected write then surfaced as "the insert was skipped as a conflict, but no existing row matches conflictColumns […] the constraint that fired is unknown", whose enumeration lists only conflict causes. A rejection described as a conflict is the exact sentence this path was fixed once already for producing; it survived on the path that had no transaction to read on. The store now pins one connection for the whole decision — the same pinning `insertRecoverAutoId` does for `LAST_INSERT_ID()`. **The classification.** The store swallowed the driver's error and raised a prose one of its own, so `classifyConstraintViolation` had nothing to read: this was the one write path where the typed error could not fire, while every other one produced it. The warning IS the driver's payload — `INSERT IGNORE` only changed how it was delivered — so it is handed on in the shape the driver would have thrown. A rejection now arrives as the same `ConstraintViolation { kind: 'foreignKey', … }` a plain `insert` produces. Nothing new crosses the wire: the classifier extracts the constraint NAME as a delimited group, never the sentence. This is the default `voltro data import` path (`--mode append`, `--on-conflict skip`, without `--atomic`), so a row rejected by a foreign key was reported to the operator as a conflict with an unknown cause. `constraintViolation.integration.test.ts` now asserts the `insertIgnore` seam per dialect against live postgres 17, MySQL 8.4, MariaDB 11 and SQL Server 2022. It was the missing assertion behind a claim derived from the wiring — the classification does sit on all ten write paths, which is not the same as a classifiable error arriving on all ten. - **@voltro/protocol, @voltro/runtime** — The framework's store errors — `ConstraintViolation`, `TenantScopeViolation`, `TenantRowNotFound`, `ServerOnlyColumnWrite`, `TableValidationFailed`, `StoreOperationFailed` — are exported from `@voltro/protocol` and can therefore be declared in a descriptor's `error:` union. They could not be. They lived in `@voltro/runtime`, which reaches `node:child_process`, `node:http` and `node:crypto`. A descriptor is loaded VALUE-LEVEL by the web client (the `RpcClient` needs every procedure's Schema), so a descriptor importing from there is refused at boot by the browser-safety guard — correctly. The typed half of these errors was therefore unreachable: the docs told you to declare them, and the boot said no. What that leaves is the untyped half only. The error still arrives as an `InternalError` carrying a readable sentence, so telling `foreignKey` ("the row you picked is gone") from `foreignKeyInUse` ("this row is still referenced") — two different messages for the user — means parsing that sentence. Over a set of generated delete mutations that is a string comparison per procedure, which is the thing the typed error exists to delete. `@voltro/runtime` re-exports all six, so server code is unchanged. The classes have no server dependency of any kind — the file imports `Schema` from `effect` and nothing else, and `browserSafetyGuard.test.ts` now pins a descriptor that declares one, so moving them back reads as a boot failure rather than as a passing rename. - **@voltro/database, @voltro/sql-mysql** — A blocked `alter-column-type` told every dialect to write a postgres cast. The refusal is correct — a bare type change may not be value-preserving, so it is refused until acknowledged. Its `fix:` line was not: ``` acknowledge it on the column: `.narrowedFrom('json', { using: 'meta::text' })` ``` `USING ` is postgres syntax and a postgres capability. The mysql arm of the applier emits `MODIFY COLUMN`, the mssql arm `ALTER COLUMN`, and sqlite rebuilds the table — none of them can carry a cast expression and none of them reads `using`. So an operator on any other engine was handed a line to paste into their schema containing syntax their database has never seen, inside an argument that is discarded. A refusal is read as an instruction, and the more carefully it is read the more thoroughly a wrong one is followed. The fix line is dialect-aware now: postgres keeps the `using` half, everything else gets `.narrowedFrom('')` plus the fact that the engine converts in place — because a refusal that offers no expressible fix reads as "the framework cannot do this at all". Covered on live MySQL and MariaDB by both halves at once: what the refusal SAYS, and that following it applies AND converges with the row intact. A message test alone would keep passing over a broken apply; a convergence test alone is what let the wrong message survive this long. Also on the same path: `upsert` with a PARTIAL row (one omitting a NOT NULL column that has no default) failed on MariaDB and succeeded on MySQL. The native `INSERT … ON DUPLICATE KEY UPDATE` validates its insert half even when only the update half runs, so the row was rejected although the target existed and only needed patching. A partial row takes the lookup path on both engines now; the single-statement form still covers the complete-row case, which is what a data transfer and every generated CRUD write send. - **@voltro/sql-mysql** — On MariaDB, `upsert` could write a DIFFERENT row than the one it was given and report success. `INSERT … ON DUPLICATE KEY UPDATE` fires on ANY unique key, not on the one named in `conflictColumns`. So an incoming row whose (say) `email` already belonged to a different primary key updated THAT row instead — and since `id` is excluded from the SET list, the row the caller handed over was never written. Measured on a live server: the call returned a row, the target kept the old id, the new row was absent, and the existing row had silently taken the incoming values. A bulk transfer on top of that prints `import complete` over missing data, which is the worst failure shape available: there is nothing to investigate. The two engines of the family disagreed here, which is part of why it survived. The non-RETURNING path (MySQL) looks the row up by `conflictColumns` first, does not find it, and lets the INSERT fail with a duplicate-key error. Loud was always right. Both refuse now, with a message naming both ids and the fact that the collision was on a constraint other than the one named. The check runs inside a transaction — a short one of the store's own when the caller is not already in one — so the wrong row is rolled back rather than reported after the fact: detecting this afterwards still leaves someone else's row overwritten. --- ## [0.42.0] — 2026-08-17 ### ⚠ BREAKING - **@voltro/cli, @voltro/data-transfer** — **Two security defects on the data-transfer surface, both found by using the feature rather than by reading it.** **A `{ profile }` in an admin-export request could name a PATH.** `loadProfile` resolved the client's string with `resolve(cwd, x)` — which returns an absolute path unchanged and lets `../` traverse — and the resolved file is `await import()`ed, which RUNS it. So a holder of the data-transfer secret could make the api process execute any file on the pod: an escalation from "can export prod data" to "can run code", and chainable on an instance whose object storage is a filesystem the same caller can write to. `POST /_voltro/admin/export` now accepts a NAME only — `[A-Za-z0-9_-]{1,64}`, resolved under `data-profiles/` and checked to be contained there. **Migration: if you passed a path over `--target api`, move the file to `data-profiles/.ts` and pass ``.** `voltro data export --profile` on a DIRECT target still accepts a path: it runs on the operator's own machine, where a path is not an escalation. No user-authored code changes, so `codemod: none`. **An unrecognised masking action copied the value through.** `applyAction` ended in `return input.value`, so a profile with a typo in the action shape (`{ action: 'fake', kind: 'email' }` instead of `{ fake: 'email' }`) exported every row of a `.sensitive()` column verbatim — with a 200 and an audit line counting the column as masked. Measured against a live instance: a masked export of two users came back carrying both real addresses. The applier now throws, and `planMasking` refuses the policy BEFORE a row is read: `MaskingError` gained `invalidActions`, reported separately from `unclassified` because the fixes differ — one needs a classification, the other needs the policy corrected. ### Added - **@voltro/runtime** — A write the database refuses on an integrity rule now raises a typed `ConstraintViolation` instead of an opaque `SqlError`. It carries `{ kind, table, operation, constraint?, column? }`, where `kind` is one of `foreignKey` · `foreignKeyInUse` · `unique` · `notNull` · `check`. Declare it in a procedure's `error:` to pattern-match it; undeclared it still reaches the client as an `InternalError` carrying its own sentence rather than `Failed to execute statement`. It carries NAMES and never the driver's message, which on most engines contains row data — postgres attaches the complete failing row to a not-null and a check violation, mysql and mssql echo the duplicate value. Classification is measured against live postgres 17, MySQL 8.4, MariaDB 11, SQL Server 2022 and sqlite. Raised from one guard covering every write op (insert · insertMany · upsert · insertIgnore · update · updateMany · delete · deleteMany · hardDelete · patchJson); the tenant-FK case still resolves to `TenantScopeViolation` first. ### Fixed - **@voltro/cli, @voltro/data-transfer** — `voltro data import|export` — four defects on the `--target api` path, all found by a consumer seeding a fresh cluster from a bundle. **A flag this command does not read is now an ERROR.** `--dry-run` and `--tables` were accepted on the import path and dropped in silence: a preview against a production-shaped cluster ran the import instead (2905 rows, then a 500), and a run narrowed to a one-row table wrote all 10 593. Both are one defect — an argument parser that ignores what it does not understand — so every `voltro data` subcommand now declares the flags it reads per target and refuses the rest, naming the flag and what to use instead. **`--dry-run` and `--tables` now work on the import, on BOTH targets.** A dry run reaches every verdict a real run reaches (schema fit, cross-dialect portability, mode legality, the table selection) and stops before the first write; the api path carries them as `x-import-dry-run` / `x-import-tables` and echoes `{ dryRun: true, wrote: false }`. A `--tables` name the bundle does not carry is refused, listing what it does. `--dry-run` on an api EXPORT is refused rather than ignored — previewing a read protects nothing. **The schema-drift pre-flight compares the INTERSECTION, not whole schemas.** A bundle's fingerprint covers its source schema regardless of export scope, and two environments never have identical whole schemas, so the check refused every cross-environment seed with a diff whose every line said the difference changes nothing — making `--force` the routine way to import and removing the protection it guards. It now reports only what would break the load: a carried table or column the target lacks, a type mismatch, or a column the target REQUIRES that the bundle carries no value for. **A failed row says why.** `reason` was `Failed to execute statement` for every one of 2905 rows. It now names the constraint and the rule (`foreign key tasks_laneId_fkey: the referenced row does not exist [23503]`), or the driver's own message with its code, or — where there is no driver under the failure — the error from the layer that refused. Also: `voltro data inspect` accepts a directory bundle instead of dying inside the archive reader with a JSON parse error (`--target api` always unpacks into a directory, even when the path ends in `.vbundle`). **Three more, found by running the whole thing against live MariaDB and MySQL** rather than against sqlite: - A re-run of a COMPLETED import wrote nothing and reported the bundle's full row count — the resume ledger lives in the bundle directory, so truncating a target and re-importing printed `import complete … 10593 rows` over an empty database. Resume is right; being quiet about it was not. It now warns, names the skipped tables, and says which ledger file to delete. - The deferred-FK recovery pass OVERWROTE the diagnosis. When a held row cannot be written, the resolver retries it with every `reference` column nulled to break a cycle — and that attempt's failure replaced the original reason, so a row whose real problem was one column reported a not-null violation on a column the framework itself had nulled. The recovery attempt no longer records a reason. - MySQL/MariaDB errno **1364** (a statement that OMITS a column which is NOT NULL with no default) is classified as a not-null violation. postgres reports 23502 for that situation and mssql 515, so the mysql family was the only one where "you did not supply a required column" came back unclassified. - **@voltro/database** — CHECK constraints were invisible to introspection on **MySQL** — and with them every `.oneOf()` column and every `json_valid` marker. `information_schema.check_constraints` differs between the two engines of the family: MariaDB carries `TABLE_NAME`, MySQL does not have that column at all. The introspector selected it, the query errored, and an `Effect.orElseSucceed` turned that into an empty list. A swallowed error and an empty result read identically, which is why this needed a two-engine test to surface. The query JOINs `information_schema.table_constraints` for the name now, which both engines answer. `parseEnumCheck` also learned MySQL's rendering. The same clause is stored differently: mariadb 11 `status` in ('draft','live','done') mysql 8.4 (`status` in (_latin1'draft',_latin1'live',_latin1'done')) MySQL puts a charset introducer before each literal, which the pattern — written against MariaDB's form — did not read. Both are pinned in `enumCheckParity.test.ts`. Neither fix completes the round trip on MySQL: `.oneOf()` still comes back unclassified there. That is asserted as a known gap in `oneOfCheck.mariadb.integration.test.ts` (which fails the moment it starts working) and written up in `plans/open/framework/mysql-oneof-roundtrip.md`. - **@voltro/database** — `voltro db apply` works on MySQL. It could not create a table with an index, and could not drop a column, on that engine at all. `IF [NOT] EXISTS` outside `CREATE`/`DROP TABLE` is a MariaDB extension — MySQL rejects it with ER_PARSE_ERROR (measured on 8.4 for `CREATE INDEX IF NOT EXISTS`, `ALTER TABLE … DROP COLUMN IF EXISTS`, and `ADD COLUMN IF NOT EXISTS`). The applier emitted the first two, because `@effect/sql-mysql2` reports the dialect `mysql` for both engines and the shared branch had only ever run against MariaDB. A `reference()` column gets an index by default, so in practice most tables were affected. The applier now asks the SERVER which engine it is (`SELECT VERSION()`; MariaDB stamps itself into the string) and emits the plain form on MySQL. The idempotency `IF [NOT] EXISTS` provided moves into the statement runner, which tolerates exactly the errnos meaning "already in the requested state" — 1061 for a duplicate index name, 1091 for dropping something absent. The engine is read from the connection rather than from `DB_DIALECT` or `variant`, because the DDL has to be legal for the server that receives it and those are what an operator typed. Verified against live MySQL 8.4 and MariaDB 11: a schema evolution — create, add column, add index, drop column — applied through `applyPlan` on both, converging at every step, plus a replayed plan (what a resume does) that must not error on the statements it repeats. **sqlite had the same defect, found by the new cross-dialect scenario on its first run.** `ALTER TABLE … DROP COLUMN IF EXISTS` is accepted by postgres, mssql and MariaDB and rejected by sqlite — and the generic emitter, shaped for postgres, is what sqlite used. So `voltro db apply` could not drop a column on sqlite either. The conditional form is now emitted only where it is legal, and the "already dropped" case is tolerated per dialect (`idempotentDdl.ts`). `runDialectParity` gained a schema-evolution scenario — create, add column, add index, drop column, applied for real with a convergence check after each step — so the migration APPLIER is now covered on all five dialects. It previously had one scenario covering one op kind, while twenty-two covered the store; that split is why four emitter defects survived. **And a fifth, found by making one MariaDB-only suite two-sided.** `text().unique()` on an unbounded text column created a table on MariaDB and failed the CREATE outright on MySQL: `BLOB/TEXT column 'x' used in key specification without a key length`. The bring-up emitter (`migrate.ts`) wrote an inline `UNIQUE`; the declarative applier had always written a separate PREFIXED unique index. The two emitters disagreeing on one statement is the failure shape this package's own notes describe, and only one engine said so. `migrate.ts` emits the prefixed index now, through the same `indexStmt` that already owns the per-dialect `IF NOT EXISTS` rule, and names it `
__key` to match the applier's — so the two paths produce the same object. **Note the behaviour change on MariaDB.** It accepted the inline form by backing it with a HASH long-unique index, whose hidden `DB_ROW_HASH_n` column breaks the binlog CDC reader (documented in `packages/database/CLAUDE.md`). Uniqueness on such a column is now enforced on the first 191 characters rather than the whole value — which is what `voltro db apply` already did, and what MySQL can express at all. Bound the column with `text().maxLength(n)` if you need full-value uniqueness. - **@voltro/sql-mysql** — `insertIgnore` on MySQL was a different feature from `insertIgnore` on MariaDB — and the difference could turn a conflict into an error. The whole diagnostic apparatus — the refusal to report a REJECTED write as a conflict, and the message naming the constraint that actually fired — sat behind a `variant === 'mariadb'` branch. MySQL took an `else` that used no `INSERT IGNORE` at all: look for a row matching the conflict columns, insert if there is none. That cannot hold the one property the method exists for. A caller that looks before anyone else writes sees nothing, so the write it then makes is the one that raises the duplicate-key error `insertIgnore` promises never to raise — reproduced deterministically against both engines with an uncommitted holder (the lookup cannot see the holder's row; the insert cannot proceed until it commits). Underneath sat the reason a straight port would still have produced nothing: **MySQL answers a PREPARED `SHOW WARNINGS` with 1295 ER_UNSUPPORTED_PS**, and the warning read is deliberately failure-tolerant (a diagnostic must never replace the caller's real problem), so it returned an empty list — indistinguishable from a statement that raised nothing. MariaDB accepts both protocols. The read goes through the text protocol now, the same spelling the binlog path already used for `SHOW MASTER STATUS`. Both engines now run one `INSERT IGNORE` and reach one decision function. What differs is only the probe for "did it land": MariaDB has `INSERT IGNORE … RETURNING *`; MySQL has no RETURNING, so the row's own key answers instead. `SELECT ROW_COUNT()` — the obvious alternative — cannot be used: measured on both engines, it reports 1/0 correctly but CLEARS the warning list on MySQL, and run the other way round returns `-1` because `SHOW WARNINGS` is then the last statement. The count and the diagnosis cannot both be had; the diagnosis is the one worth having. Found by converting the suite that covers this to run on both engines, which is also where every MySQL assertion in it had been reporting the driver's generic `Failed to execute statement`. - **@voltro/database** — A `reference()` column now creates a real foreign key on **MySQL**. It did not before: MySQL/InnoDB parses a column-inline `REFERENCES` clause and discards it — no constraint, no warning, the `CREATE TABLE` succeeds — while MariaDB honours the identical clause. Both engines reach the same emitter (the driver reports the dialect `mysql` for either), and every mysql-family integration suite in the repo runs against MariaDB, so referential integrity that postgres, MariaDB, mssql and sqlite all enforced was silently absent on MySQL. Both emitters now write a table-level `CONSTRAINT
__fkey FOREIGN KEY …` inside the `CREATE TABLE`, which both engines honour and which `CREATE TABLE IF NOT EXISTS` keeps idempotent. Existing MariaDB schemas are unaffected — the introspected snapshot carries no constraint name, so nothing re-plans. Verified against live MySQL 8.4: the constraint is in the catalog, the server refuses an orphan row, introspection reads it back, and the re-plan is empty. - **@voltro/sql-turso, @voltro/testing** — A migration on turso applied correctly and then reported itself as failed: `voltro db apply` ran an `add-column`, re-planned to prove convergence, saw the column still missing, proposed the same operation again, and the second execution died with `duplicate column name`. No fingerprint was recorded, so every subsequent boot re-proposed the same work — and the error named the migration applier, which had done nothing wrong. The client caches one prepared statement per connection per SQL text, and a prepared statement carries the schema it was prepared against. So a cached `PRAGMA table_info(t)` keeps answering with the old columns after a DDL — it is never re-prepared, so sqlite's schema-cookie re-preparation never runs. The invalidation for this existed, on the unprepared path (`sql.unsafe`) only, and the migration path sends its DDL through the PREPARED one. The statement that changed the schema and the cache that had to be dropped were on the same connection, one function apart, with nothing connecting them. Any schema-changing statement now drops that connection's cached statements, whichever path it arrived on. Three hypotheses were measured and disproven before this one — an applier retry (each operation is issued once), an MVCC snapshot (two raw libsql clients both see the DDL), and a pool-wide cache problem (four connections held open together, the PRAGMA prepared on each, a DDL on one: the other three answer correctly, because SQLite bumps the schema cookie and the driver re-prepares on the connections that did not make the change). The two `runDialectParity` scenarios that drive the migration applier were skipped for turso on the strength of that misreading. They run now, and the per-fixture opt-out that carried the skip is deleted: it was holding a defect open while reading like a documented limitation. **`apiSurface: compatible`, and the reason is a date rather than an argument.** Removing `DialectFixture.skipApplierScenarios` moves a line in `@voltro/testing`'s golden, so the changelog's narrowing detector flags it — and it is right to, because that detector's baseline is `origin/main`. But the field never reached a RELEASE: it was added after `v0.41.0` and deleted before this one, both inside the same unreleased range. `git show v0.41.0:packages/testing/etc/testing-dialect.api.md` does not contain it. No published version ever offered it, so no consumer can have set it, and there is nothing to migrate. Worth writing down because the first reading of this was wrong in the safe direction: it was filed `BREAKING` with a codemod on the strength of "an optional field disappeared from a published package's surface", which is the right instinct and the wrong conclusion here. **"Removed relative to main" is not "removed relative to what users have"** — a symbol that lives and dies between two tags trips the detector while breaking nobody, and the difference is only visible by asking the last TAG rather than the last commit. --- ## [0.41.0] — 2026-08-17 ### ⚠ BREAKING - **@voltro/web, @voltro/cli** — `middleware.ts` exports `defineMiddleware(...)` (from `@voltro/web/middleware`) instead of a bare function, and each export carries its own `match`. Several middlewares per file are allowed; **at most one may match a given route**. Migration: the codemod wraps the existing default export. That is behaviour-preserving — no `match` means every server-rendered route, which is what an unwrapped middleware did — and its note explains how to replace a hand-written path gate with a `match`. **Why it was worth a break.** A hand-written `if (!req.pathname.startsWith('/app')) return` is invisible: nothing can tell you a middleware runs nowhere, or that two of them claim one route. `match` puts it where both the boot and `voltro doctor` can read it. **The matcher speaks ROUTES, not URL patterns** — `under` / `routes` / `except`, validated against the app's own route patterns. A path matching no route refuses the boot instead of silently never firing. This is the deliberate difference from the `'/((?!api|_next/static|…).*)'` shape: our hook runs after route matching, so an app has never needed to know its own asset layout, and non-page requests are reachable only by asking (`assets: true`) — where, note, there is no render, so only `setCookies` takes effect. An overlap refuses the boot and names both middlewares plus the route. Declaration order is not a semantic, "most specific wins" silently drops the broader hook, and merging needs a per-field rule nobody remembers — so two hooks writing one `authorization` header is a refusal, not a resolution. **The web bundle budget moved UP, and the split is worth stating** because only one half is a cost the framework imposes: | measured | before | after | | --- | --- | --- | | first load | 184 955 B | 185 309 B (**+354**) | | lazy route chunks | 3 502 B | 4 415 B (+913) | The **+354 B of first load is the real price** — one `serverContext` chunk, 0.2 KB gz, which every app now carries whether or not it declares a middleware. That is the number to argue with, and it leaves 6.7 KB of headroom under the ceiling. The +913 B is NOT a per-route regression: the fixture gained four routes (`exact`, `exact/[id]`, `mw`, `mw/skip`) to exercise the feature end to end, at 0.1–0.2 KB gz each, which accounts for the growth without remainder. Re-pinned with `--update` rather than by hand, so the `slackFloor` keeps ratcheting — a ceiling nobody lowers again silently permits re-inflating to the old number. ### Fixed - **@voltro/data-transfer, @voltro/cli** — `voltro data export` could not export a table whose primary key is not named `id`, and one of its two failure modes reported success. The keyset column was `columns.find(c => c.type === 'id')?.name ?? 'id'`, and `type: 'id'` is tagged only on a column that is BOTH the single-column primary key AND literally named `id` — identically in all four dialect introspectors. So any introspected table with another PK name was ordered by a column that does not exist. It now comes from the real primary key (the synthesised `
_pkey` index), with the declared `id()` column still winning where there is one. **A composite or absent primary key is now REFUSED**, not silently ordered by the first column: keyset pagination on a non-unique order splits equal values across page boundaries, so rows are dropped or duplicated into a bundle that reports success. Bounded exports are recoverable; a quietly short backup is discovered at the restore. **A requested table missing from the schema is refused too.** `scope: { kind: 'tables' }` used to drop unknown names, so a run that explicitly named a table wrote `"tables": []` and printed `export complete` with exit 0. `kind: 'all'` over an empty database is still a legal empty export — the asymmetry is deliberate: a named table is an expectation. **Failure reasons survive.** `String(e?.message ?? e)` produced `"write table failed: "` with nothing after the colon — `??` falls back on null/undefined, and an Effect `TaggedError` carries an empty-string `message`. Every catch site in the exporter now reports tag, message or cause. **New: `voltro data export --exclude a,b`** — everything except these, resolved against the live table list. It is the escape hatch the refusals above require; without it a single unkeyable table would block a whole-database export. An unknown name is refused for the same reason. Direct target only (the expansion needs the live table list), and it expands to an explicit `tables` scope, so the manifest records what was actually exported. Reported with a reduced repro, a four-way variation over PK TYPES that ruled type out, and two disproved hypotheses. The affected tables include `@effect/cluster`'s own (`cluster_locks`, `cluster_migrations`), so no app running workflows could take a whole-database export. - **@voltro/database, @voltro/runtime, @voltro/cli** — `.encrypted()` had three writers and two encodings. The store wrote `encrypt(JSON.stringify(v))`; `encryptField` — the documented raw-SQL escape hatch — and `voltro db encrypt-column` wrote `encrypt(v)`. All three produce the same `enc:v1:` envelope and nothing distinguished them, so a value written by one and read by another either threw with the wrong diagnosis or came back subtly wrong (`decryptField` handed back the JSON encoding verbatim, quotes and all, raising nothing). There is one encoding for every WRITE now, and every READ resolves BOTH forms — so **no data has to be rewritten and nothing is blocked**. That second half is the point: the old form is already on staging and production disks, and a fix that needs the rows rewritten before the app works is an outage with a migration attached. Reading two forms is deterministic, not a heuristic. After decrypting, a parse failure is the raw form; a parse to a STRING is the JSON form; a parse to a non-string depends on the column's declared type (a text column cannot hold a number, so `12345` is a raw string that parsed by accident). The one case nothing can separate — a raw secret whose literal text is `"abc"`, quotes included — is stated in the code rather than hidden. **`voltro db encrypt-column` verified itself against the wrong decoder.** It wrote the raw form and checked it with `cipher.decrypt` — a decoder nothing reads these columns with — so it reported success over columns the app could not read. It round-trips through `decodeFieldValue` now, the same function the store calls. A self-check against a decoder the runtime does not use is not a weaker check; it is a second opinion from the same mistake. The command also NORMALISES rows in the old encoding as it goes (reported separately from the ones it encrypts), so an operator does not write a script per column. It skips anything ambiguous and anything it cannot decrypt. **The width pre-flight measured the wrong thing after the encoding changed.** It sized the ciphertext from the PLAINTEXT's byte length while the cipher is handed the JSON encoding — two characters more at minimum, and more for every escape. Measured on a real MariaDB: a 63-byte value in a `varchar(135)` passed the check and the UPDATE answered `ER_DATA_TOO_LONG`, which is the failure that check exists to prevent, mid-column with the rest already converted. It measures the encoded length now, and the refusal says "encodes to" rather than "is" so an operator measuring their own column finds the number it names. **Two dialect defects, both found by running the command against real servers.** SQL Server reports `-1` for `NVARCHAR(MAX)` — its spelling of unbounded — and the pre-flight read it as a one-character column, so it refused the widest column the dialect has and printed `declared as -1` at the operator. And SQLITE has no `information_schema` at all: the shared catalog query died there with `Failed to prepare statement` and no statement attached, on a dialect the command claims to support. It uses `pragma_table_info` now, reporting no length because sqlite enforces none. Measured end to end on postgres, mysql, mariadb, mssql and sqlite: a table holding plaintext, the old encoding and the current encoding side by side converts, every row decodes back to its original value, a re-run writes nothing, and a wrong key refuses with exit 1. **Backups and restores were never affected and now say so.** `voltro data export` reads through the raw dialect store, so ciphertext travels verbatim in either encoding — pinned by a test, because a future change that wrapped that store would put plaintext credentials in a bundle. - **@voltro/protocol, @voltro/cli** — Three findings from one consumer round, all of the same shape: something the framework knows and does not say. **A decode failure on a GUARDED procedure now says the guard did not run.** The payload decodes before the handler, so a guard on a procedure with a malformed payload never gets the chance to refuse. A consumer auditing a guard called one with an incomplete payload, got a decode error instead of a `ScopeError`, and concluded the guard was not applied — the wrong conclusion in the dangerous direction. The title now carries `(guarded — the guard did NOT run: the payload failed to decode first, so this says nothing about access)`. It discloses nothing new: that a procedure is guarded is already visible to anyone who sends a VALID payload. An `openAccess:` declaration is not an enforced guard and gets no such sentence — `hasEnforcedGuard` is the one predicate, read by both the label and the wire error union, because two copies of that rule would disagree invisibly. **`middleware.ts`'s `httpOnly` default is documented at the field, and warned about.** It defaults to `HttpOnly`, which is wrong for a session cookie a browser SDK reads back: Supabase's `createBrowserClient` reads `document.cookie`, so a forgotten `httpOnly: false` gives the browser a session it cannot see — the SSR render is perfect and the user is signed out at the first client-side call. The consumer only avoided shipping it because their probes already set the flag. `voltro dev` warns once per cookie when a session-shaped name is written with no `httpOnly` decision; an explicit decision either way silences it, because warning on a decision is how a diagnostic becomes noise. **`voltro dev` restarts when `middleware.ts` changes.** It is loaded once per boot, that is documented, and a consumer read it and still lost an afternoon: they sabotaged the middleware, saw no change, and concluded it was not wired — in an environment where everything else hot-reloads. It now restarts through the same respawn a hard-restart field in `app.config.ts` uses, extracted so there is one copy of the `execArgv` inheritance and the signal forwarding. - **@voltro/cli** — `middleware.ts` now produces ONE view of the request that every downstream reader takes. Previously only `buildLoaderQuery` saw the hook's result, while the loader context (`ctx.headers`), the SSR request snapshot (`useServerRequest()`) and the locale resolver kept reading the raw request — four readers, two answers, within eighty lines of one function. The consequence was worse than an inconsistency: a hook that renews purely via `setCookies` — no `headers` at all, which is the normal shape for a cookie-session IdP and the reason the response half exists — moved nothing for the render that ran it. The rpc call still sent the old `Cookie` header, because a renewed cookie only reached the browser. `setCookies` is applied to the cookie jar before the render, the `Cookie` header is rebuilt from that jar (an explicit `cookie` in the hook's own `headers` still wins), and `maxAge <= 0` deletes, so a hook that signs someone out renders them signed out. Both SSR boot paths shadow the raw headers out of scope after the hook runs, so a new reader added below is correct without knowing any of this. - **@voltro/cli** — `voltro start` dropped `middleware.ts`'s `Set-Cookie` on **streamed** responses — which is the arm a plain `renderMode: 'ssr'` page takes, so it was the common case. The hook renewed the session server-side, the render used the fresh value, and the browser kept the consumed one. Against an IdP that rotates refresh tokens and detects reuse, that is worse than not renewing at all. The cause is worth stating because it read as handled: a streamed response hands the socket to `stream(res)` and the caller never looks at the returned `headers`, so the `withCookies(...)` wrapper on that arm was dead code — sitting under a comment promising the cookies were written on every arm. The cookies now travel with the headers `streamSsrResponse` itself writes, and the dead wrapper is gone. Found by booting real `voltro dev` and `voltro start` servers against a fixture and reading the response. Every unit test was green throughout, and the render's own HTML was correct — only the wire was wrong. --- ## [0.40.0] — 2026-08-16 ### ⚠ BREAKING - **@voltro/client, @voltro/web** — A subscription whose COLD START failed is its own state — `failed: true`, `loading: false` — so "it is loading" is a true statement again. The old shape left `loading: true` for a subscription where nothing was in flight and nothing more was coming. The type's own comment predicted the consequence: > A cold-start failure leaves `loading` TRUE … so a component that branches on > `loading` alone renders a skeleton forever. Check `error` to break out of it. A consumer quoted that back with the right conclusion: **a comment that predicts the misbehaviour of its own field is an API resting on discipline.** `loading` means "something is coming" everywhere else; here it meant "something is coming OR never again", and the escape hatch was a second field that the natural shape of a wrapper — pass `{ data, loading }` through — silently drops. They had three such wrappers. The framework had six, in `useWorkflow.ts`, and the compiler named all six the moment the state existed. `failed` is a positive discriminant, so the check reads as one: ```tsx if (s.loading) return if (s.failed) return return
``` **BREAKING**: `!loading` no longer proves `data` is present, so every call site that reads `data` after a bare `loading` check is a type error naming file and line. Nothing fails silently. The codemod is `manual` on purpose — a transform could add `|| s.failed` everywhere and would be wrong about half of them, since an infinite skeleton is precisely what this removes. **Measured blast radius**, because the estimate was worse than the reality: 20 errors inside `@voltro/client` (mostly its own `useWorkflow` wrapper and the type-tests) and **zero** in `@voltro/web`, `devtools-ui`, the devtools app, the cloud app, and all 45 templates. Most consumers were already using a `fallback` or a wrapper, which is what made the original defect so quiet. Unchanged: a failure AFTER the first snapshot still leaves good data on screen with `error` set — only the cold start is `failed`. A `fallback` subscription still has `data` always present, so `failed` reports there rather than gating. `idle` stays opt-in by overload; `failed` is not opt-in, because any subscription's cold start can fail. And the state is terminal for one TRANSPORT: a reconnect discards the error and re-subscribes. - **@voltro/protocol, @voltro/runtime, @voltro/voltro** — A guard refusing a caller whose credential was REJECTED now answers `Unauthenticated`, not `ScopeError`. Measured by a consumer: a user's tab outlived their IdP's token lifetime. The strategy logged it plainly — ``` WARN auth strategy "supabase" rejected request: supabase jwt expired WARN mutation.tasks.update failed: missing required scope 'task:u:o' ``` — and the wire said the caller lacked a scope. Technically true (an anonymous caller holds none) and it sends everyone who reads it into the permissions system while the problem is an expired session. They did that round; the subject was their administrator, and the same call with a fresh token worked. **The obvious fix would have broken more than it fixed**, which is why this shape and not that one. Failing hard when a strategy rejects would break every `openAccess` procedure for anyone holding a stale cookie — a public page that needs no session at all would start refusing. So the FACT travels instead: a rejected credential stamps `credentialRejected` on the anonymous subject it falls back to, and only a guard that actually refuses spends it. `openAccess` never reaches that point and is untouched. Three details worth knowing if you touch it: - **The stamp happens AFTER the app's `fallback`.** That callback builds its own anonymous subject and knows nothing about the rejection; stamping before it would be silently discarded — the shape of every "wired on one path" defect in this codebase. - **ONE conversion point** (`asRefusal`), at the exit rather than at each `return`. Every branch builds the `ScopeError` it always built; one place decides what it MEANS. - **`Unauthenticated` is merged into the wire union** for guarded procedures AND guarded events, beside `ScopeError`. Without that it would be a tagged error the descriptor cannot represent, and the server would collapse it to `InternalError` — the defect another consumer reported the same week. A caller who presented NO credential still gets `ScopeError`. Collapsing both would send a genuinely under-privileged user to the login page. **Why this is BREAKING although nothing was removed.** Three published results gained a union member: ```ts checkGuards(…) // ScopeError | Unauthenticated | null (was ScopeError | null) checkGuardsEffect(…) // Effect bindEvent(…) // Stream<…, ScopeError | Unauthenticated, …> ``` The test for breaking is not "did a symbol disappear", it is whether code that COMPILED can stop compiling — and a widened return does that wherever the old union is named (`const refusal: ScopeError | null = checkGuards(…)`), or narrowed exhaustively. It was filed as `Added` first; the golden diff is what showed otherwise, and the rule is worth more than the classification that felt right. `anonymousSubject`'s new second parameter is OPTIONAL and breaks nothing. `voltro update` carries you across it — codemod `0.40.0/02_rejected-credential-widens-guard-results`, a written note. A transform would widen each annotation, which compiles and keeps the reported behaviour: the decision at each site is what an expired session should do that a missing permission should not. ### Added - **@voltro/client, @voltro/web** — The client re-resolves `authHeaders` when the server says the credential was rejected — and `client.refreshAuth()` for an app that knows earlier. `authHeaders` is resolved once per CONNECTION and attached per frame, so a tab open longer than the IdP's token lifetime keeps presenting a dead token until something reconnects. A consumer measured it: dragging a card on a board failed, their ADMINISTRATOR's token had simply expired while the page stood, and nothing in `@voltro/client` could force the re-resolve. The trigger is the `Unauthenticated` error — which only became distinguishable from `ScopeError` in this same release. Before that the client could not have told "your session died" from "you lack a permission", and reconnecting on the second would have been wrong. `refreshAuth()` is a SAME-SUBJECT rebuild, and the difference from `reconnect()` is one flag and a security boundary: `reconnect()` exists for a login / logout / tenant switch, where the next subject may be entitled to strictly LESS, so the cache must not be seeded from the old one. A token refresh is the same person with a fresh credential, so seeding is correct and the screen keeps its rows instead of blanking for the round trip. Getting that backwards is silent in both directions — seed on a subject change and you paint one user's rows into another's; refuse to seed on a refresh and every open screen blinks on every rotation. The policy lives in ONE function (`wireAuthRefresh`) that every host wires, because "when do we reconnect on an auth error" is exactly the kind of decision this repo has watched drift when it was written twice. Two guards, answering different questions: a **rate** ceiling (one rebuild per window — a rejected mutation arrives alongside every rejected subscription on the page) and a **total** ceiling (stop after N refreshes with no successful call between, because at that point the credential is not stale, it is refused, and the answer is a sign-in screen rather than another socket). - **@voltro/cli** — `middleware.ts` — a web app's one server-only hook, for renewing a credential before the SSR render uses it. Reported: a consumer's SSR detail pages arrived empty on the first request of every day. Their cookie token had outlived the IdP's lifetime, the api resolved the caller to anonymous, and every `preload` on the page failed. They could not fix it in the app, and the reason is structural: `ctx.query` and every `preload` entry are bound from ONE cookie string **before any loader runs**, so a layout loader that renews the session cannot reach them — and a `type: 'web'` app has no auth middleware. ```ts // middleware.ts — web app root, server-only export default async (req) => { const fresh = await refreshSession(req.cookies['sb-session']) if (!fresh) return return { headers: { authorization: `Bearer ${fresh.accessToken}` }, setCookies: [{ name: 'sb-session', value: fresh.cookie, maxAge: 3600 }], } } ``` **Why not `app.config.ts`.** That file is imported into the CLIENT bundle, verbatim, the moment any api declares `authHeaders` — the thunk is a function, so it cannot be serialised. A hook that renews a session reaches for an IdP SDK by definition, so putting it there drags the server graph into the browser. The consumer proposed exactly that shape (`serverAuthHeaders` beside `authHeaders`) and it is the one place it cannot go. **Why `setCookies` is not optional.** We asked whether writing cookies back was in scope, expecting the answer to be about a round trip. It was about correctness: Supabase ROTATES refresh tokens and detects reuse, so a hook that renews server-side and does not write the result back leaves the browser holding a consumed token. Without it the hook is not "slower but correct" — it can destroy the session. **Deliberately not a general middleware.** It can replace credentials and set cookies. It cannot redirect, return a response, or rewrite a route — because authorization belongs on the API, which is the only thing that sees the data, and a web-side hook that can refuse a request becomes a second authorization layer beside the real one. A hook that cannot refuse also cannot be mistaken for a guard. For a login redirect, a loader already throws `RedirectError`. Details worth knowing: only auth-shaped headers (`authorization`, `x-tenant`, `x-voltro-*`) are forwarded to the api, so a returned `host` or `content-length` cannot produce a failure that looks like anything but a header copy; cookies default to `HttpOnly` + `Path=/` + `SameSite=lax`; multiple cookies are written as separate header lines, never comma-joined (a cookie's `Expires` contains a comma); the file is loaded ONCE per boot; a failure to IMPORT is fatal rather than degrading to "no middleware", and a middleware that THROWS fails the request — the render must not proceed on the credential it was told to replace. Wired on BOTH SSR boot paths (`voltro dev` and `voltro start`), with the cookies written on every response arm — streamed, buffered, redirect and 404. A partial application would renew a rotating token and drop it. - **@voltro/testing** — `makeTestContext` supplies `ctx.events`, so an executor that publishes can be unit-tested at all. `ctx.events` is a field PRODUCTION puts on every `AppContext`, and the test harness did not — so any handler containing `ctx.events.publish(...)` died on `Cannot read properties of undefined (reading 'publish')` the moment it ran under test. **The shipped `api-durable` template demonstrates exactly that pattern** (publish inside the mutation's transaction, so it fires on COMMIT and not on rollback), and its own test passed anyway — because it called the executor with `await` instead of running it. An executor written in the Effect style RETURNS an Effect, and awaiting a non-thenable hands the object straight back, unrun. The assertion then failed on `row.status` being `undefined` and pointed at the assertion rather than at the call. Two defects propping each other up: the harness could not have run that handler, and the test never asked it to. It is the REAL `makeEventPublisher` over a real `EventBus`, not a stub. A fake would re-implement the payload validation and the tenant stamping and would be wrong the first time either gains a case — the lesson `plugin-broadcast` paid for twice. `ctx.eventBus` is the read side: ```ts const seen = ctx.eventBus.subscribe(orderPlaced, { orderId }) await invoke(placeOrder, executor, input, ctx) expect(seen.received).toHaveLength(1) ``` One bus for the whole harness so a `withSubject` / `withTenant` re-scope still publishes where the test is listening; the PUBLISHER is per-subject, because the tenant it stamps is the caller's. ### Fixed - **@voltro/cli** — `voltro agents-md --force` no longer exits 0 when it wrote nothing. Reported: a consumer's `agent-docs/` is owned by the pod (root). They ran the command as `admin`, and it **overwrote nothing, said nothing, and exited 0**. They read the unchanged file as "the framework has not fixed this yet" — it had — and lost a full round to it. The cause was three `orElseSucceed`s in the agent-docs copy. `makeDirectory`, `readDirectory` and every `copyFile` degraded to success, so a destination the process could not write produced an empty run that reported itself as done. An unreadable source directory came back as `[]` and did the same. Failures are collected and reported now, and the command **exits 1** when the seed is incomplete: ``` agents-md: 12 file(s) could NOT be written — the seed is INCOMPLETE. The commonest cause is ownership: a container wrote these as root and you are running as someone else. ``` `--force` is an explicit instruction to overwrite, so silently not overwriting is the one outcome that must never be reported as done. `stat` is the single remaining silent degrade, deliberately: a source entry that vanished mid-walk is not a write failure and must not fail the run. Pinned in both directions — a real unwritable directory yields failures, a clean copy yields none, and a source guard asserts that `stat` is the ONLY call on that path allowed to swallow. Red-verified by restoring the original `orElseSucceed`. - **@voltro/cli** — Every server-side loader context is now checked by the compiler, and the static prerender stopped handing loaders a context missing `search` and `headers`. `ctx.isServer` shipped with a source-reading guard, and that guard had the defect it exists to prevent: it matched context literals by shape (`loader({` / `ctx: {`) and therefore found ONE of the two in `build.ts`, missing the one built as a typed arrow return. Its tripwire — "at least 5 sites" — passed, because a floor cannot tell 5-of-8 from 5-of-5. The gap was found by a parallel report, not by the guard. The invariant moved from "the literal mentions `isServer`" to "the literal is CHECKED BY THE COMPILER": every server loader context is now `satisfies SegmentLoaderContext`, whose `isServer` is required. A site that forgets it is a type error naming the file and line — strictly stronger than any regex over shapes, and verified by removing one. **It caught a second defect immediately.** The static prerender built its page loader context with only `params`, `pathname`, `signal` — no `search`, no `headers`, no `query` — while `LoaderContext.search` is declared `string`. A static page's loader reading `ctx.search` got `undefined` where the type promised a value. The segment context twenty lines above it in the same file already passed `search: ''` with a comment explaining why. Two smaller things worth knowing if you touch the guard: the closing brace is part of its pattern because the bare phrase also appears in the comment explaining the rule (the first version counted its own documentation), and the CLI's `SegmentLoaderContext` mirror keeping `isServer` non-optional is what the whole enforcement rests on — `isServer?:` would make every `satisfies` pass while a forgetful site reports itself as the browser. - **@voltro/protocol, @voltro/cli** — A guard's `ScopeError` reaches the client as `ScopeError` on a mutation, not as `InternalError`. Measured by a consumer over the wire, same session, same foreign team: | kind | declared `error:` | denial arrived as | |---|---|---| | query `webhooks.list` | `AccessDeniedError` | `_tag: 'ScopeError'` ✓ | | mutation `…updateReferenceLabels` | `AccessDeniedError` | `InternalError` ✗ | | the same mutation, after adding `ScopeError` to its union | | `_tag: 'ScopeError'` ✓ | Their client maps `ScopeError` to *forbidden* and `InternalError` to *something went wrong*, so a permissions refusal looked like a crash — on every relationship-guarded write in the app. **Their observation was exact; the mechanism was not, and the difference is where the fix goes.** They diagnosed it as "the merge only happens on the streaming path". `withGuardError` is called by every lifter, so the wire union carries `ScopeError` on both. What differs is a SECOND reader: the server refuses to ship a tagged error the descriptor cannot represent, collapsing it to `InternalError` rather than emitting a raw defect tree — and it was handed `descriptor.error`, the RAW declaration, while the union it protects is the WIDENED one. It judged against a narrower set than it had advertised. A query never reaches that check (it is delivered through `wireErrorFromCause`, which preserves the tag), which is exactly why the split fell along query/mutation. `wireErrorUnion(descriptor, kind)` is now the single owner of "what can this procedure put on the wire", used by the lifters AND by both bind sites. **Two more error classes were collapsed the same way, and neither was reported:** - **`BusinessRuleViolation`** — unconditional for mutations. `withRuleError`'s own comment says it MUST be in the union "or the violation crosses the wire as an untyped defect". It was in the union, and collapsed before it got there. - **The `requiresApproval` refusals** — `ApprovalRequired` / `ApprovalExpired` / `ApprovalUnavailable`, so "parked for approval" was indistinguishable from "the server broke". `openAccess:` still merges nothing: a procedure advertising a denial it cannot produce is what makes an error union stop meaning anything. If you worked around this by declaring `ScopeError` yourself, the declaration is now redundant rather than wrong — the union is the same either way, and you can delete it whenever you like. --- ## [0.39.1] — 2026-08-16 ### Fixed - **@voltro/runtime, @voltro/cli** — An app-registered tuple source is no longer replaced by the framework default. Both boot paths carried this comment, verbatim: > An app whose relationships live in its own tables overrides with > `setTupleSource`. and then called `setTupleSource(default)` **unconditionally**. That call runs AFTER the app's startups — `runBootLifecycle` at `dev.ts:3910` and `serveCommand.ts:869`, against the registration at `dev.ts:4065` and `serveApi.ts:937` — and `setTupleSource` is last-write-wins. So the framework won every time: an app registering its own source in a `*.startup.tsx`, which is what the docs tell it to do, had it silently replaced. The consequence is not subtle. Every relationship guard would then be answered from `_voltro_rebac_tuples` — empty, for exactly the app that keeps its relations in its own tables — so every guard DENIES, fail-closed, with a `no tuple source` warning that never fires because a source *is* registered: the wrong one. The comment was not wrong about the design; it described the design while the code removed it. Same shape as the `DORMANCY_WAKEUP_TENANT` scar — equal by value at both call sites, so nothing could fail, and the comment was the only place the intent survived. `registerDefaultTupleSource` fills the gap only when nobody else did, and returns whether it acted so the boot can say which source is live instead of leaving an operator to guess. `setTupleSource` itself is unchanged: an app calling it twice still gets the second one, because narrowing that would trade one silent surprise for another. Found while re-checking a consumer's claim that a different item was still open. It was not — but it sits beside this, and this is the one that would have bitten them. Pinned in both directions: a unit test for the registrar, and a source guard asserting neither boot path installs `loadResourceTuples` through `setTupleSource` again. Red-verified by restoring the original line. - **@voltro/cli** — `voltro doctor` no longer reports "scope vocabulary: none found" when it could not read the config at all. A consumer HAD configured `doctor.scopeVocabulary` and still read `none found`. The cause was not their vocabulary: `app.config.ts` could not be imported outside their pod — an auth strategy demands its secret while the config is evaluated — so the vocabulary was never read. Inside the pod the message disappears and the rule runs. "You have no vocabulary" and "I could not look" are different states, and only the first is a statement about their app. This section already made exactly that distinction one member earlier — its own comment reads **DORMANT AND CLEAN MUST NOT PRINT THE SAME** — and then collapsed the third. The signal existed and was not connected. `offlineManifest` deliberately survives an unimportable config (a doctor run must not die on one), so the empty vocabulary arrived looking like a real absence, while the same failure was reported a hundred lines earlier under plugin tables. The consumer read the section about scopes and searched at the wrong end — which is the correct way to read a report. The rule now probes importability before claiming an absence, and says so: ``` • scope vocabulary: NOT EVALUATED — `app.config.ts` could not be imported. This is not a statement about your scopes: the rule never got to read them. … The same import failure is reported above for plugin tables; both sections have this one cause. ``` The dormant case keeps its own wording, so a quiet run on an app that genuinely publishes no vocabulary is not relabelled as a broken config. ### Internal (no consumer-facing effect) - **@voltro/cache, @voltro/kv** — The RESP TTL tests in `@voltro/cache` and `@voltro/kv` stopped measuring the machine. Test-only; no product code changed. Both wrote a key with `ttlMs: 150`, asserted it was still there, then slept 300 ms and asserted it was gone. The second half is fine — waiting LONGER only strengthens "it expired". The first half was a race: the write and the read are two round-trips, so on a loaded runner the key legitimately expired before the liveness assertion, and the test reported a defect that was not there. It failed exactly that way on a release gate, in the keydb engine, while passing locally with 24/24 green. Now: a 2 s window, so liveness has real headroom rather than 150 ms of it, and the expiry is awaited as a CONDITION (`awaitGone` polls) rather than as a duration. Idle machines finish in about the TTL; loaded ones take as long as they need; a key that never expires still fails, because the ceiling is a failure mode and not a timing assumption. Fixed in BOTH packages in one change. The two files carried the identical construction, and this repo's standing lesson is that a fix landing in one copy of a duplicated shape leaves the other one broken — `@voltro/kv` had not failed yet, which is a statement about luck rather than about the test. `@voltro/kv`'s header also pointed at `../cache/test/docker-compose.yml` for bringing the engines up. That path does not exist; there is one compose file, at the repo root. --- ## [0.39.0] — 2026-08-16 ### Added - **@voltro/client, @voltro/web, @voltro/cli** — A preload that fails server-side now says so in the hydration payload, so a page can tell "still loading" from "actually empty". Reported by a consumer whose session cookie had outlived the IdP's token lifetime — for them, practically every first page view of the day. Every `preload` on the page failed at once, the api having resolved the caller to anonymous: WARN [voltro:dev:web] preload seed failed tag=projects.getById … ScopeError — missing required scope 'project:r:o' The page rendered a skeleton title over an empty table, and that WARN was the only record anywhere. **The client saw exactly what it sees for a page that declares no preload at all** — both arrive as the absence of a seed — so no app could distinguish the two without inventing a convention of its own. The reporting consumer did exactly that, page by page. `usePreloadedSubscription` now returns `preloadFailed: true` in that case: ```tsx const projects = usePreloadedSubscription('api', 'projects.list') if (projects.loading) return if (projects.preloadFailed) return // not empty — unasked return
``` It says nothing about WHY, deliberately: the server's failure text is a refused call's error message and belongs in the server log, which is the one place a browser cannot read. A boolean is the whole contract. It also says nothing about the LIVE subscription, which usually recovers on its own — the browser reconnects with a credential the SSR request did not have. So the honest reading is "the first paint has no server data, and that was not for lack of asking", which is exactly enough to choose a spinner over an empty state. `seedPreloadedSubscriptionFailure` is exported from `@voltro/web/ssr` beside `seedPreloadedSubscription` for a loader that runs its own preloads. Two shape notes, both deliberate: - **The field is widened on THIS hook, not on `SubscriptionState`**, so no existing `useSubscription` call site is un-narrowed by it — the same scoping rule the `skip`/`idle` overload follows. - **`seedFailure` is REQUIRED on the internal preload runner, not optional.** This is the hook whose omission WAS the defect, and an optional hook is an omissible one — the same mistake with a nicer name that cost us `startOutboxRunner`'s teardown. Making it required is what listed all three render paths (dev, start, static prerender) at the compiler rather than at review. - **@voltro/web, @voltro/cli** — `LoaderContext.isServer`, and the type now says a loader runs TWICE. Reported after two days of debugging: a loader carried a server-only call, and nothing in `LoaderContext` said the same function runs again in the browser on every in-app navigation. The consumer read "runs once per request" into the gap, which is the reading the wording invited. **The docs were worse than a gap — they contradicted themselves.** The loaders page opened with "the page's server-side data hook" and its first code sample carried the comment `// Server-side fetch — runs on the Node side, never in the browser`, while 230 lines further down the same page said "on a client-side navigation … the loader runs in the browser". A reader who hits the false line first stops looking. Both are corrected, in both languages, and the precondition is now the first thing the page states. **Why it survived two days is the part worth repeating:** a client-only failure is invisible to every probe that does not NAVIGATE. A fresh page load, a `curl`, any SSR check all take the server path and pass. Only clicking a link inside the running app reaches the other one. `ctx.isServer` is the supported discriminator, because the two things that look like they answer the same question do not: - `query` is absent in the browser, so `if (ctx.query)` appears to work — but it branches on the ABSENCE OF A FUNCTION, which says nothing about why it is absent and breaks the moment anything else becomes conditional; - `headers` is `{}` in the browser, **not** `undefined`, so `if (ctx.headers)` is TRUE on both paths. The reporter checked exactly that, and it silently did nothing. It is REQUIRED rather than optional: an optional boolean is omissible, and a server path that forgot it would read as `undefined` — falsy — and claim to be the browser, which is the precise failure the field exists to prevent. The compiler names every client construction site; the three SERVER render paths build their context as untyped literals, so `loaderIsServer.test.ts` derives those by shape and fails on one that omits it (red-verified against a removed line, which named the file and offset). - **@voltro/react-native, @voltro/client, @voltro/web, @voltro/cli** — React Native gets the whole client, not half of it. `startMobileApis()` connects and re-dials over the **same** supervisor `@voltro/web` uses — the supervisor moved into `@voltro/client` rather than being copied, because a second copy of its stale-seed gate (the rule that stops one subject's rows appearing in the next subject's screens) is a second thing to keep correct. Web's two browser-specific behaviours are injected options now: the devtools status entry and the dev-only wedge reload. `voltro codegen` in a mobile app writes `.framework/mobileApis.generated.ts` from `voltro.mobile.ts` — which apis the app talks to, and where each one's rpc group and descriptors come from. Only the binding is generated; the procedure types ride the import of the api's own `rpcGroup`, so a schema change needs no regeneration. The ws URL is a runtime parameter and deliberately not baked in: `localhost` on a phone is the phone, and `resolveDevWsUrl()` takes the LAN host Expo already knows. `createAsyncStoragePersistence()` makes `defineStore({ persist })` work on a device. A store reads during render and a render cannot await, so it hydrates into memory once — awaited before the first screen — then serves reads synchronously and writes through, coalescing per tick. A storage with no `getAllKeys()` and no declared `keys` refuses rather than hydrating empty: an empty cache is indistinguishable from a first run. `useMobileConnectionStatus()` takes an optional `onlineSource`. Its default reads `navigator.onLine`, which React Native does not have — so on a device it answered "online" forever, airplane mode included. Pass `netInfoOnlineSource(NetInfo)`. `isInternetReachable` is believed only when it is a boolean, because NetInfo reports `null` while its probe is out and reading that as offline flashes a banner on every cold start. Two type declarations were WRONG, and running the mobile template through the scaffold harness is what said so — nothing else in the repo typechecks a generated entry, on web either. `ClientDescriptorMap` was a structural copy of `@voltro/protocol`'s `ClientDescriptor` that narrowed `source` to one string while the real descriptors carry several. It is now that type, not a copy of it. And an api's `group` is the erased `RpcGroup.Any`: `RpcGroup` is declared `in out` in @effect/rpc, so the CONCRETE group codegen emits was never assignable to `RpcGroup` — the boundary rejected the only value anyone passes it. Erasing at the boundary and restoring at the call site is what `ApiHandle.client` already does; the one cast is where the rpc client is built. `dispatchDeepLink()` is new for the same class of defect. `matchFirstDeepLink` returns a descriptor from a heterogeneous array, so its handler declares `Record` params while the match hands back `Record` — the result could not be invoked by anyone. `apiSurface: compatible` — every changed declaration either widens what a producer may pass or replaces a type that misdescribed its own values. Code written against the narrow `source` was already wrong at runtime, and no call that compiled before stops compiling. `useMobileConnectionStatus` gained an optional parameter. Not verified here, and not implied: that the loop runs on a device. Everything above is unit-tested without a simulator, and only a simulator can prove Metro. That is an Expo/EAS CI step. - **@voltro/runtime** — A `TupleSource` receives the whole `subject`, not just `subjectId`. Reported precisely, from a guard review rather than an outage. `subjectId` cannot express a CREDENTIAL that is narrower than the person holding it, and an API key is exactly that: the key's binding lives in the subject's `metadata` (`keyType`, `teamId`), while `subject.id` is the OWNING USER. A tuple source could therefore only resolve the owner's memberships and was blind to which team the key was minted for — so an owner who belongs to two teams passed the guard for both. The comment beside their hand-written check says what that costs: > Without the binding check below a key minted for team A worked on every team > in the org. Nothing was ever wrong in their app, because they kept the executor-side check. The defect is that a DECLARED guard could not replace it: ```ts setTupleSource(async (req) => { const boundTeam = req.subject.metadata?.teamId if (boundTeam !== undefined && boundTeam !== req.resourceId) return [] return loadResourceTuples(store, req.subjectId, req.resourceType, req.resourceId) }) ``` A guard that must always run paired with a hand-written check is not a declaration — it is a comment with a type signature. And the pairing is exactly the thing nobody re-derives when they delete the "redundant" half a year later; the reporter had already written the reason into their parity test to stop that happening. `subject` is typed as the full union deliberately: its system and anonymous members carry no `scopes` or `metadata`, so the narrowing is the caller's to do and is visible where it happens. - **@voltro/cli** — A declared relationship guard whose `resourceType` is not registered now refuses the boot instead of denying every caller forever. The report described the shape exactly: an app arms its authorization from a startup (`defineResourcePolicy` + `setTupleSource`). If that registration does not happen, the app boots **clean**, takes traffic, and every procedure with a declared guard refuses from then on. Fail-closed, so nothing leaks — and a total outage of the guarded surface whose only signal is a log line nobody reads, because the boot was green. At their size: 39 procedures — team settings, hours import, role administration. Since 0.38.0 a `*.startup.tsx` that THROWS already refuses the boot, so the sequence they described is closed. This gate exists because that fix covers only the throwing case, while the same silent outage arrives by three doors no startup-error handling can see: - the startup registers some types and not the one a guard names — a typo in a `resourceType` is not a compile error, it is a string on one side and a string on the other; - the file was renamed out of the discovery pattern, so it never ran and never threw; - the registration was conditional on something false at boot. All three end in the same place, and the framework can rule out all three by asking one question it already holds both halves of: which `resourceType`s does the discovered surface NAME, and which are REGISTERED? The refusal names the type, the count and the procedures that demanded it — grouped by type, because the fix is one `defineResourcePolicy` per type while the damage is per procedure. It also names the spelling trap, since nothing else in the system compares those two strings. **Why refuse rather than warn**, because "fail-closed already, so it is safe" is the plausible objection: safe is not working. The procedures are DOWN, and down-with-a-warning is precisely the state being reported. A refusal is recoverable in seconds and impossible to miss. It runs after the startups have settled, on both boot paths — not beside `assertProcedureAccessDecisions`, which reads declarations and can run at discovery. This one reads a registry the app fills during its startups, and placing it earlier would have failed every app that registers from one, which is all of them. A check that fails on everything gets deleted rather than fixed. ### Fixed - **@voltro/client** — A timer no longer discards the optimistic preview of a write the server confirmed. **A rollback happens if and only if the write FAILED.** Measured by a consumer on a Gantt bar: drag it, the server writes, the mutation reports success — and five seconds later the bar jumps back. They suspected the server first and proved it was holding the data correctly, reasons included, before finding that the client was throwing the confirmed patch away itself. The cause was one line: `confirmByMutation` armed a `setTimeout` calling `revertByMutation` — **the same function the FAILURE path calls**. Success and failure ended in the same discard, one immediately and the other five seconds later. What makes it unambiguous is WHEN that timer could fire at all. Any server event already retires confirmed patches through the seamless hand-off, so the window only ever expired while `base` was still STALE. The revert therefore replaced a value that reflects the committed write with one the client knows does not: | | keep the patch | revert (before) | |---|---|---| | delta arrives later | invisible hand-off | 5s of stale, then a jump back and forth | | delta never arrives | matches what is saved | **contradicts what is saved, permanently** | The bottom-right cell is the damage: the user watches their saved change disappear and either redoes it or plans on a state they believe was not stored. A "leaked" patch is gone on the next subscription; a silent revert is healed by nothing. Expiry is now a **resync**: the client re-issues that subscription, keeps the patch, and says so loudly on the error bus (`voltro logs`) — the silence was the second half of the report, because in the UI this is indistinguishable from "the server did not save it", which is the false trail they followed first. **Two more seams of the same defect, both found while fixing it:** - **An `error` event retired confirmed patches.** An error does not advance `base` — it sets `baseError` and leaves the rows where they were — so dropping there discarded a committed write's preview for nothing. - **A resync whose snapshot comes back UNCHANGED must not retire them either.** The first version of this fix had exactly that hole: it re-asked the server, the answer was byte-identical, and the patch was dropped anyway — the reported bug reached by a longer route. The hand-off rule is now explicit (`supersedesConfirmedPatches`): a delta always supersedes, an error never does, and a snapshot only when it actually MOVED the base. The rule is pinned against the source, not only behaviourally: no `setTimeout` in the cache may name a revert. The defect was never inside a function — it was which function a timer pointed at, and a behavioural test only sees that if somebody thought to write the case. Nobody had: `CONFIRMED_PATCH_TTL_MS` was named nowhere in the test file, which the reporter also pointed out. It is now, red-verified by restoring the original line. - **@voltro/ui-shadcn** — `AnimatedNumber` rendered `0` into static markup. It initialised its state to zero and counted up on hydration, so every statically rendered page SHIPPED the zero — the landing site's own stats row went out as "0 … 0 … 0% … 0", which is what a crawler, an answer engine and any reader with JavaScript off saw. A number that only exists after hydration is not a number on the page. It now renders the target value (so the server's markup and the first client render agree — no hydration mismatch) and drops to zero inside the observer callback, at the one moment the animation is actually about to run. The count-up is decoration layered on a correct page rather than the only way to see the value. The test that covered this asserted `toBe('0')` before scrolling — it was pinning the defect. It asserts the final value now, with the reason written next to it, plus a second case for the count-up itself. `CodeCompare`'s corner tags take an `eyebrow` prop instead of hardcoding "Before" / "With Voltro". This kit renders a bilingual site, and an English label over German copy is the same defect as any other hardcoded string. The English default keeps every existing call working. - **@voltro/cli** — `voltro dev` reports the db-pool budget too, and the out-of-pool count is right on every dialect. The line was `voltro serve`-only, and the module said so with its reasoning: a dev machine has one process and no replicas, so `max × replicas` is noise. It even asked a future reader not to "fix the parity gap" by moving it. The reasoning was fine and its PREMISE was false. `voltro dev` is not always a dev machine — at least one consumer runs it as their deployment, two API pods against a shared pooler, and `retentionSweep.ts` already reasons about that same consumer in its own header. Two modules cannot both be right about what `voltro dev` is. The cost was not theoretical: that consumer REPORTED the out-of-pool `LISTEN` connection, we answered it in this line, and they could not see the answer, because the one boot path they run does not print it. So the exception is conditional rather than per-command now. `voltro serve` always reports; `voltro dev` reports when the environment shows the process is not a laptop — `REPLICA_COUNT` (a process cannot know how many of itself are running, so a platform set it), `DB_MAX_CONNECTIONS` / `PG_MAX_CONNECTIONS` (somebody is already reasoning about this number), or `DB_REPLICA_URLS` (which multiplies the pools inside ONE process — the case most likely to be mis-budgeted, because it does not look like a fleet). A bare `voltro dev` with nothing set stays silent, which is the half of the original decision that was right. **And the out-of-pool arithmetic was wrong for two dialects.** It was derived inline as `dialect === 'postgres' && CDC !== '0'`. The mysql/mariadb ROW-binlog reader speaks the REPLICATION protocol, which is a separate connection from the SQL pool by construction, so a mariadb deployment read a line that under-reported its own process by one. It is counted now. mssql Change Tracking is NOT counted, and that zero is verified rather than omitted — it reads through the store's own `SqlClient` and its module says "the CT reader needs no second pool". Both boot paths go through one `reportDbPoolLine`, and the CDC derivation takes the ARMED state as a parameter instead of re-reading the env: a binlog reader stands down when every app table is `.nonReactive()`, and billing a connection nobody opened is the same class of error as missing one. - **@voltro/cli** — The 0.37.0 strict-input note under-sold the one case that breaks hardest, and the correction is RE-ISSUED rather than edited. 0.37.0 made an undeclared input field reject the call. Its note described the general case correctly and then, under WHAT DOES NOT CHANGE, said "an empty input to a procedure that declares none is still fine". True about sending `{}`, and it reads as reassurance to the owner of an `input: Schema.Struct({})` — whose procedure is the one shape that did NOT move from "silently drops the extra field" to "rejects it". It moved from accepting EVERYTHING to accepting nothing, because an empty `TypeLiteral` has no expected keys for excess-property checking to compare against. The strongest-looking declaration was the only one enforcing nothing. A consumer measured the upgrade across 2 705 procedures and found three real breaks. The most expensive was exactly this: a `getMy` declaring `Schema.Struct({})` while a shared table hook always sent `{ limit }`. Before, the limit was discarded and the call worked; after, the live subscription AND the SSR seed of that page both die. **Why a new codemod and not an edit.** `selectCodemods` filters `from < version <= to`, so anyone who has already crossed 0.37.0 — including the consumer who reported this — will never see that note again, whatever it says. A correction filed there reaches only users who have not upgraded yet, i.e. not the ones holding the broken app. `0.39.0/01_empty-input-schema-rejects-every-field` carries it to the people who need it. (The 0.37.0 note is corrected too, for users still short of it. That edit is necessary and not sufficient, and the difference between those two words is why there are two files.) Its `appliesTo` is deliberately BROADER than the original's. 0.37.0's fires on a spread into a procedure input or the untyped string form of `ctx.query` — the constructs that carry a field the author never typed, which is the right gate for the general case and the wrong one here. The payload does not have to be invisible for this to break: the reporting consumer reached it through an untyped wrapper hook passing an explicit `{ limit }`. So this one gates on the DECLARATION — an empty struct anywhere in the app — which is the population that actually changed behaviour. - **@voltro/cli** — All three ways a mutating inspect request can be refused now name the variable, the header, AND where the value comes from. A consumer verifying a row filter hit this one: 401 {"error":"unauthorized","reason":"inspect: POST needs the write credential — send it as the `x-voltro-inspect-write` header alongside the bearer. The read token authorises reads only."} Their words for it: the message is good, and the missing half is **where the value comes from**. They knew what to send and not what to send AS. They gave up on our tooling and hand-signed a session token instead. That half is exactly the part a user cannot guess, because in dev nobody ever typed it: `voltro dev` MINTS `VOLTRO_INSPECT_WRITE_TOKEN` into the project's gitignored `.env.local`. Every arm says so now. **It is a function over the set, not a fix to the reported member** — this is the third message on this surface to be fixed one at a time. The three refusals were three hand-written strings of decreasing usefulness: - `unset` — named the variable. Fine. - `absent` — named the header and not the variable. The reported one. - `mismatch` — `inspect: write-credential mismatch`, which named neither, and is the case where knowing WHICH of the two values to look at is the entire remedy. Nobody had reported it, which is not evidence that it was fine. They come from one `inspectWriteHint(refusal, method)` beside the existing read- token hint, so the next arm cannot be added without the vocabulary. The method is folded in because the surface answers for `/erase` and for `/routes` in the same words, and a caller who did not know their call was a mutation is the caller most likely to be reading it. - **@voltro/cli** — `ctx.isServer` reaches a LAYOUT loader too, on every server path. It was threaded into the page loader and left off the segment chain, so a layout loader read `undefined` — falsy, i.e. it concluded it was in the browser while server-rendering. Three of the five constructions never passed it: the prerender context in `build.ts`, the dev SSR renderer's layout call, and the test fixture pinning the shape. The two that did are the ones a `tsc` run named, because `SegmentLoaderContext` — the CLI's mirror of `LoaderContext` — had not grown the field at all. Making it REQUIRED rather than optional is what found the other three, and it is the same reasoning the flag itself ships with: an optional `isServer` cannot distinguish "the server forgot to pass it" from "this is the browser", and both spellings of that mistake claim the browser. A field whose whole job is to answer one question must not have a third answer. `webDevSegmentChain.test.ts` asserts the loader argument with an exact `toEqual`, so a field added to one loader's context and not the other fails there. That assertion is the reason this is one release and not two: `tsc` was already green on the test file while the run would have gone red. - **@voltro/cli** — The pre-bundled api client is fingerprinted from the DESCRIPTOR SOURCES, so a schema change reaches the browser. Reported: a consumer changed an input schema on a descriptor and `voltro dev` kept serving the old client. The failure is quiet in the worst way — the CLIENT rejects the call, so the api logs nothing, because no request ever arrives. Vite pre-bundles the workspace api client and its optimize-cache hash keys on the lockfile and package.json, never on a pre-bundled dep's source content. So the framework fingerprints the client itself and flips `optimizeDeps.force`. That machinery was right and it was watching the wrong file: **`rpcGroup.generated.ts` imports each descriptor by export name and lifts it. It contains no schemas.** Codegen's own header says so. The generated file is therefore byte-identical across any schema edit, and BOTH mechanisms were structurally blind to it — the across-boot check hashed it, and the in-session watcher watched it. The in-session watcher's own comment already described the symptom ("the browser kept decoding responses against the stale schema"): the cache-busting half was fixed when that was hit, and the DETECTION half kept asking the file that cannot answer. So it never fired. The consumer's third reason — "runs only at boot" — is not quite right, and it does not matter: the in-session mechanism exists and was blind for the same reason. One fingerprint feeds both now. It hashes every `*.query.ts` / `*.mutation.ts` / `*.action.ts` / `*.stream.ts` / `*.event.ts` and every `*.workflow.tsx` descriptor, plus the generated group itself (which is what moves when a procedure is added or removed without a descriptor file changing content). Paths are hashed with contents, so a rename cannot come out as a no-op. `*.server.ts` executors are deliberately excluded — they never reach the browser, and including them would force a re-optimize on every handler edit, which is the whole working day and is how a forced re-optimize gets turned off. **The `proxyTarget` skip is gone from both.** It stood in for "is this api external", and a workspace api served on its own origin has no `proxyTarget` while still being edited locally. `findWorkspaceApiDir` returning a directory is the question that was meant. It survives in exactly one place — the ws proxy, where without a target there is nothing to proxy to — and the test asserts that count rather than its absence. - **@voltro/cli** — `voltro probe access` now names the one thing that makes its red meaningless. The command asks "does a declared guard refuse a caller presenting nothing". It turns out that under `voltro dev` a caller presenting nothing is not anonymous: dev resolves a login-less request to a FALLBACK TENANT (`$TENANT ?? 'acme'`). An app whose scopes derive from the tenant therefore admits, and the probe reported `ANSWERED an unauthenticated call` against a guard that is perfectly fine. That is not an occasional false positive, it is a structural one: the local registry only ever holds `voltro dev` / `voltro start` processes — `voltro serve` does not register — so every target the command picks up WITHOUT `--url` is in exactly that state. The failure block now says so, and says what to do instead: voltro probe access --url http://: against a `voltro serve` process, where an anonymous request carries `tenantId: null` — the case a guard actually has to refuse. Found by running the command as a FINDER for the first time rather than as a test: it flagged a shipped template, and the flag was wrong in dev and right about production, for two different reasons. A tool whose red needs a paragraph of context should carry the paragraph. - **@voltro/protocol** — A rejected rpc payload no longer answers with the procedure's whole input type. Measured by a consumer against 0.38.0, anonymously, with no session at all: POST /rpc {"tag":"workAreas.create","payload":{"name":"x"}} → { readonly name: string; readonly storeId?: string | null | undefined; readonly type: "department" | "location" | "zone" | "station"; readonly parentId?: string | null | undefined; … } └─ ["type"] └─ is missing That procedure declares `guards: [{ scope: 'workArea:c:o' }]`. The refusal never happened — the payload decode runs first and failed first — so the caller got a field-by-field description of a write they are not allowed to make. On an app with ~700 write procedures that is a free enumeration of the entire write surface for anyone who can reach the port: no session, nothing that looks like rate-limit abuse, and no log line. The rendered TITLE is now the procedure name, and the issue PATH is untouched: workAreas.create input └─ ["type"] └─ is missing So the half that made the 0.37.0 strict-input change cheap to adopt — WHICH key, and whether it is missing or unexpected — survives intact, while the types and the enum members do not. The excess-property case still lists the accepted key NAMES, deliberately: the caller already sent the key, that list is what makes the fix a one-line read, and names without types were not what was reported. **What this does NOT do, stated because the report asked for it.** It does not run `guards:` before the decode. In `@effect/rpc`, a `Request` is decoded against the payload schema and answered on failure without ever reaching `server.write` — so it never reaches the handler and never reaches `applyMiddleware`. Auth middleware runs strictly after the decode, and there is no point in that path holding both a resolved subject and an undecoded payload. Evaluating guards first means replacing the protocol layer, not annotating a schema, and `voltro probe access` therefore still reports a guarded procedure whose input it cannot guess as `inconclusive` rather than `refused`. ### Internal (no consumer-facing effect) - **@voltro/datetime, @voltro/local-first, @voltro/react-native** — `@voltro/datetime`, `@voltro/local-first` and `@voltro/react-native` shipped with no api-extractor golden, so the public-surface drift tripwire did not cover them — and the docs-audit finding that motivated this landed in exactly that gap (the docs promised a `useTimezone()` hook that `@voltro/datetime` never exported, and no gate could see it). All three are wired now, root + subpath entry (`./context`, `./react`, `./schema`): six goldens, `api:check` green on each, and no existing golden changed (the new `paths` entries every sibling map gained are purely additive). Root cause fixed in the generator rather than by hand: `gen-api-extractor.mjs` now creates the package's `etc/` directory with the wiring. api-extractor refuses to create its own report folder, so a package wired without one failed at its first `api:report` instead of at generation — which is how these three went live uncovered. Internal: no consumer-facing behaviour changes. - **@voltro/cli** — `gen-api-extractor.mjs --check` verifies the api-surface wiring instead of writing it, and runs in CI (and therefore in `pnpm gate`, which derives its steps from `ci.yml`). It fails when a published entry point has no api-extractor config, no golden, an EMPTY golden, a stale config/golden for a dropped export, or no `api:check` script. It is derived from `publishConfig.exports` inside the generator's own loop — not a curated list and not a second copy of the derivation — so a package that joins the workspace is covered without anyone remembering to add it. It carries a floor (60 packages) for the reason every check in `scripts/` has one: the failure mode of a wiring check is a green line over a walk that found nothing. Verified by injecting each defect and watching it go red (missing golden, empty golden), confirming exit code 1, and confirming `--check` mutates no file. Internal: tooling only. - **@voltro/cli** — `rpcSurfaceFingerprint.ts` wrote its composite-key separator as a literal NUL byte instead of the `\u0000` escape. Same runtime value, no behaviour change — the file's own 16 tests pass identically before and after. It matters because of what the byte does to the FILE rather than to the hash: a source file containing a NUL is binary to every text tool, so `grep` skips it and prints nothing, which is indistinguishable from a clean file. This repo has been bitten by exactly that — a 1020-line module that every grep-based audit had silently skipped, including one searching for a string that file declares. The guard (`noLiteralNulInSources.test.ts`) caught it on the release gate, in a file added earlier in this same release. The rule was already written down; what enforced it was the test. --- ## [0.38.0] — 2026-08-14 ### ⚠ BREAKING - **@voltro/plugin-audit, @voltro/protocol, @voltro/plugin-auth** — An audit row now says when an action was taken through an IMPERSONATED session, on the default settings, and no redactor can take that away. `AuditEvent` gained `impersonation`, and the datastore sink a nullable json column of the same name. The mark is lifted out of `subject.metadata` BEFORE the redaction chain runs, so `redactSubject` — including a custom function that erases the subject wholesale — never gets a say. **The defect it closes.** `@voltro/plugin-auth` mints the mark into `subject.metadata`, and `auditPlugin`'s default `redactSubject: 'metadata'` replaces that whole bag. That default is right: the bag is where a per-user provider credential lands, and an audit table is the last place a live PAT should be. The consequence was that on defaults an impersonated action was recorded indistinguishably from the user's own — the one distinction an audit trail exists to make. The documented mitigation (`redactSubject: impersonationAuditRedactor()`) worked and was opt-in, and an audit property that depends on somebody wiring it is not a property. The alternative fix — a keep-these-keys option on `redactSubject` — was rejected for the same reason: it leaves the default wrong, and "who really did this" is not the app's metadata to configure away. It is a property of the event, so it is now a field of the event. **BREAKING: `IMPERSONATION_METADATA_KEY` moved from `@voltro/plugin-auth` to `@voltro/protocol`.** It names the one reserved key in `Subject.metadata`, and `Subject` is protocol's type. Two packages need it — plugin-auth writes the mark, plugin-audit reads it — and a plugin must not depend on another plugin, so spelling the string in both would have made it a second definition no guard is watching. Everything else stays: plugin-auth still exports `impersonationOf`, `isImpersonated`, `ImpersonationMark` and `impersonationAuditRedactor`. The codemod repoints the import, preserving an alias and the type-only form. The redactor keeps working and is no longer load-bearing. Set `redactSubject: 'none'` or a custom function for your own reasons; the impersonation mark is recorded either way. No migration is needed for the new column — a `_voltro_*` change rides the declarative differ on `voltro db apply` and on a `voltro dev` boot, on every dialect. - **@voltro/cli** — A `*.startup.ts` that fails now refuses the boot. It used to warn and let the server come up. Measured, on a real `voltro dev` against postgres, while building the row-filter integration test in this same release. A startup reached for `ctx.store.select(...)` — a builder that lives on the request-scoped `MutationStore`, not on the `DataStore` a startup receives — and threw on its first line. The boot printed: ``` warn startup: function rejected info startup: registered <- next line, same file ``` and then served every request with no row filter registered. Two lines contradicting each other, the second asserting exactly the thing that had just failed, and an app that looked healthy while its access control was absent. **The rule this overturns was right when it was written.** The header of `startupRunner.ts` read "Errors are logged but never fatal — a failing startup MUST NOT block the rest of the app", and for the startups it was written for — an SSE bridge, a sync loop, a metric aggregator — that is the correct call. It stopped being right when a startup became the documented seam for REGISTRATION: `setRowFilter` is installed from one. The runner cannot tell a registration from a background loop, and the two failures are not symmetric. "The app refuses to boot" is fixed in seconds and is visible to everyone; "the app serves without its access control" is visible to nobody. So the default is the recoverable one, and an app that genuinely wants best-effort writes the `try`/`catch` inside its own startup — one line, at the site where somebody decided the failure was acceptable, where a reviewer can see it. Deliberately not a flag: a flag moves that decision away from the startup it applies to and makes it one setting for all of them. **Two sibling silences went with it**, because fixing only the rejection would have left two more ways to reach the identical state — the per-seam shape this repo keeps paying for. A startup file that cannot be imported, and one with no default-exported function, used to warn and skip. Both refuse now. The second matters more than it sounds: the convention is a DEFAULT-exported function, a named export is discovered and never runs, and that is indistinguishable from a startup that ran and did nothing. **And the 2-second race is gone, which is the half that made the rest reliable.** The old code did not wait for a startup to settle — it raced it against 2000 ms and let the boot win. A startup slower than that was reported as fine, so a rejection arriving afterwards had nothing left to refuse. The runner now waits for the startup to SETTLE, so every failure is catchable however slow it is. That race existed to protect one shape: a startup that never returns because it holds a fiber until shutdown. Counted before changing it, that shape appears in ZERO of the four startups this framework ships — `warm.startup.tsx` (twice), `searchBackfill.startup.tsx` and the memory fixture's all return. So the race protected the shape we discourage and penalised the shape we teach, and the penalised one includes `searchBackfill`, our own example, which awaits a full-table query plus an index backfill and is the likeliest thing in the box to exceed two seconds. Slow AND failing put a consumer back in exactly the silent state this release removes. **So a startup that never returns now refuses the boot too**, after `VOLTRO_STARTUP_TIMEOUT_MS` (60s default), with a message naming the file and showing the `onShutdown` shape to use instead. That makes a previously-documented capability illegal — "a fiber that resolves only on shutdown" — and it is the deliberate half of this change rather than a side effect. A startup that is merely SLOW is unaffected: it is waited for and registers when it finishes. `startup: registered` is written only when the function actually returned. The old code printed it for a failed startup and for one still running. Verified against a real process in every direction, not only in units: the reintroduced defect exits 1 and never listens; a never-returning startup exits 1 and never listens; a slow-but-successful one still registers; and the healthy fixture boots and serves all eight row-filter assertions. `startupRunner.test.ts` is new — there were no tests on this runner at all, which is part of why the contradiction survived. **`voltro update` carries you across this** — codemod `0.38.0/02_startup-failure-refuses-boot`. ### Fixed - **@voltro/cli** — A table declared through `databaseHandle({ … })` but not exported as a top-level table is now DISCOVERED — so its mixins apply. Discovery kept whatever `isTable()` accepted out of a schema module's `Object.values`, which only ever sees tables the file exports DIRECTLY. A schema that builds its tables programmatically exports the builder's result: ```ts export const blogEntities = contentTypeToEntities(blogPost) // { draft, published } export const database = databaseHandle({ …, blogPostDrafts: blogEntities.draft }) ``` `isTable({ draft, published })` is false, so those tables never entered the schema registry — while `databaseHandle` had registered them for by-name lookup perfectly well. **Two registries with different populations, read by different things.** `getTable()` found the table, so insert validation knew `tenantId` was NOT NULL. The schema registry is what drives the mixins, so nothing stamped it. Measured against a real `voltro dev` boot of the scaffolded `api-cms` template, over real RPC: ``` TableValidationFailed: { "table": "blogPost_drafts", "summary": "missing required column 'tenantId' — NOT NULL with no default and not auto-stamped" } ``` Every `content.saveDraft` in that template, since it shipped. Its own unit test could not see it, because the test builds its schema registry by hand — the one step the running app does not perform. **The write failing was the lucky half.** Reads do not announce themselves: `makeQueryFinalizer` AND-merges `tenantId` from this same registry, so a table missing from it is a table nobody scopes. The visible symptom was a broken mutation; the invisible one was tenant isolation quietly not applied to those tables. The fix takes the by-name registry's DELTA across each schema module's import, so a handle-declared table is attributed to the file that declared it — rather than reading the whole global registry, which by then also holds framework tables that this set deliberately excludes. It lives in `loadDiscovered`, which `voltro dev` and `voltro serve` both call, so the two cannot disagree about it. No app change is needed; the idiomatic `databaseHandle` declaration now works as its documentation always said. - **@voltro/database, @voltro/cli** — A migration that fails because `DB_SCHEMA` names a schema that does not exist now says so. Postgres answers `3F000 no schema has been selected to create in`, and the only thing that puts a non-default schema on the connection's `search_path` here is `DB_SCHEMA`. The error mentions neither the variable nor the schema, so the FIRST `CREATE TABLE` of the boot fails with a message about SQL and the reader goes looking at the DDL — for a typo in an environment variable. Found while building the row-filter integration test below: the boot aborted, the log named `_voltro_migrations` and a postgres routine, and nothing in it pointed at the one line of configuration that caused it. Same shape as a 403 that says nothing about `VOLTRO_INSPECT_TOKEN`, fixed in the same release. The remedy also states what the framework will NOT do: Voltro creates tables, never the schema itself. That is a namespace decision, and inventing one from a typo puts a migration somewhere nobody is looking. `remedyFor` is deliberately a one-entry map and the test asserts the empty case as well as the full one. A remedy is worth printing only where the mapping from driver code to cause is exact; a list of maybes is how a reader learns to skip the section. **Alongside it: the row filter is now driven under `voltro dev` against a real postgres.** Both defects that reached consumers lived between layers that were each individually covered — a module-local `let` that split per instance, then a query producer that built its context from an unscoped request — and three consumer documents carried "we have not run this against a real database" as an honest caveat. `rowFilterDevPostgres.integration.test.ts` boots the fixture twice: handlers with no predicate of their own, a filter registered from a `*.startup.tsx`, and a NEGATIVE CONTROL run with the registration skipped that asserts the same queries return BOTH owners. Without the control, "the caller saw one owner" is equally consistent with a database that only ever held one. - **@voltro/cli** — A shard that cannot be released no longer spins a fiber at full speed. Upstream `@effect/cluster` releases shards through `Effect.eventually` — retry until success, zero delay, logged at DEBUG — so a shard whose storage was unreachable retried as fast as the event loop allowed, in the one place nobody watches. Our patch replaces it with `Effect.retry(Schedule.exponential(100) ∪ Schedule.spaced(5000))`. `union` takes the MINIMUM of the two delays, so the 5s spacing caps the backoff instead of compounding with it, and both schedules recur forever — attempts stay unbounded, which is what the original intended. The persistence was always correct; only the missing delay was the defect. This entry exists because the change would otherwise have shipped undocumented. The patch lives in `packages/cli/templates/patches/`, and the changelog gate requires an entry for `packages/*/src` — so nothing would have demanded one, even though the file is installed into every user project that runs cluster. A rule that cannot see a path is not the same as a path with nothing on it. --- ## [0.37.0] — 2026-08-13 ### ⚠ BREAKING - **@voltro/protocol, @voltro/runtime, @voltro/cli** — A field a procedure's input schema does not declare now REJECTS the call. It used to be discarded and the call ran with what was left. The measurement, from a consumer's root layout: ```ts query?.('userSettings.list', { employeeId }) ``` That procedure declares `userId` / `userIdIn`. Effect's default `onExcessProperty: 'ignore'` decoded the payload to `{}` — not reasoned, measured: ```ts decodeUnknownSync(Struct({ userId: optional(String) }))({ employeeId: 'e' }) // → {} ``` An empty input to a LIST query is not a narrower filter, it is the ABSENCE of one. Their admin, signed in as `2d0add2c…`, was served the settings row of `4410c2f8…` — another user's language and theme in the first paint, with nothing in any log to say so. **Why refuse rather than warn.** The decoder cannot tell a projection field from a FILTER field, and that asymmetry is the whole risk: dropping an unknown `include` costs a caller some data, dropping an unknown `tenantId` hands them somebody else's. Nothing at decode time distinguishes the two, so the safe direction is the only one available — the same fail-closed reasoning as the row filter's refusal, one layer up. A warning would have to be read by someone, in a log, after the wrong rows were already served. The typed loader query that shipped in 0.36.0 closes the same hole for callers we compile. This closes it for the ones we do not: a plain `fetch`, a curl, a still-cached bundle after a field rename, and every untyped caller. Three things measured rather than assumed, because none follows from the annotation's name: it propagates into NESTED structs, through every member of a UNION, and leaves a non-struct payload (`Schema.Void`, a scalar) alone. **`Schema.Struct({})` needed a filter, and only a real process showed it.** The fixture's `notes.list` declares an empty input; `POST /rpc` with `{ employeeId }` came back `200` with a snapshot, which for twenty minutes read as the whole change having failed. An empty `TypeLiteral` has no property signatures, so Effect has no expected key set for a key to be excess OF — self-consistent, and the wrong answer here, because `input: Schema.Struct({})` is the STRONGEST declaration a procedure can make and it was the one shape that accepted everything. It gets an explicit predicate now; `Schema.Record` keeps its open key set, because there the openness is declared. **Verified against a running `voltro serve`, not only in units.** A declared input succeeds and inserts its row; an undeclared field is refused naming the key and the accepted set. The refusal arrives on the channel a payload decode failure ALREADY used — a missing required field produces the same `Die` with a `ParseError` message — so this adds no new error shape for a client to handle, it moves one case onto the channel the sibling case was always on. `strictInput` lives in one module and every `Rpc.make` payload in `@voltro/protocol` goes through it — query, mutation, action, stream, event, plus the workflow start on both the server lifter and the browser-loaded rpc group. `strictInput.test.ts` asserts that SET by scanning the source, not the five lifters somebody remembered: a rule applied at the sites you can list is the shape that let `bootStoreCodec` be fixed twice and break a third time. **`voltro update` carries you across this** — codemod `0.37.0/01_procedure-input-rejects-undeclared-fields`, a written note. A transform would have to guess which declared field a stray one meant, which is the same guess that produced the defect. ### Added - **@voltro/plugin-audit** — `redactInput` / `redactOutcome` gained `'shape'`, and `redactSubject` gained `'metadata-shape'`: the payload's STRUCTURE survives, no value from it. ```json { "__redacted": { "jiraToken": "string(113)", "attempts": "number" } } ``` Requested by the consumer who had asked for the redaction one round earlier, and both requests were right. They spent a day on a bug their own audit trail could have ended in seconds — a value arrived as 113 characters where 44 were due, and the row that would have said so read `{"__redacted":"all"}`. `'all'` remains the default on every field; this is opt-in. The rules, and the two that are decisions rather than details: - A string reports its LENGTH. Never a prefix, never a hash — `enc:v1:` is a prefix and so is the first byte of a private key, so there is no prefix length that is safe for every credential format. - A number, boolean or date reports its TYPE only. A number can BE the secret. - **A key can be the value.** An object keyed by user data puts a datum where a schema name belongs, so a key is reproduced only when it looks like a declared field — a short plain identifier. The first version truncated long keys and documented the weakness instead; this module's own test caught 62 characters of a secret surviving on the first run. A leak with a footnote is still a leak. - **A string's length is a real disclosure, and a small one.** Stated in the docs rather than buried: for a fixed-format credential it carries nothing, for a human-chosen password it is a weak hint. `'all'` stays the default for anyone that matters to. The `'shape'` outcome describes the payload it REPLACES — the value on success, the error on failure — rather than the event. Describing the event would report `{ kind, value, durationMs }` and hide the field, which is the failure the option exists to end. An error's `_tag` still survives, as it does under `'all'`. ### Fixed - **@voltro/cli** — `voltro db --help` listed fifteen of eighteen subcommands. `adopt`, `scan-credentials` and `encrypt-column` shipped and never joined the hand-written string. A consumer wrote both halves of that gap into a requirements document, as separate items, neither of them about help text: - **`voltro db encrypt-column` "does not exist"** — filed as a feature request, quoting the fifteen names they saw as evidence. It shipped in 0.33.0, and enabling `.encrypted()` on a populated column by hand is exactly the migration they were about to write themselves. - **`scan-credentials` "no longer exists"** — filed as CLOSED, a credential scanner struck off their list as removed. It had not moved. A quoted enumeration is read as exhaustive, and the more careful the reader the more thoroughly they act on the missing entry. Same lesson a boot refusal in `procedureAccessGate` had already taught us, in a place nobody thought of as a message. The usage line is now GENERATED from the dispatch table's key type (`Record` in `dbCommand.ts`, names in `subcommandNames.ts`), so a handler with no name or a name with no handler fails to compile. `voltro privacy` is keyed the same way. The prose summary beside it cannot be generated — it carries per-command annotations — so a test asserts it mentions every name, because it carried the identical three omissions and it is what `voltro --help` prints first. `subcommandHelpParity.test.ts` also NAMES the six commands whose subcommand menus have no dispatch table behind them (`webhooks`, `evolve`, `new`, `data`, `storage`, `add`). They dispatch through a switch and are unchecked; a silently-unchecked command reads exactly like a checked one. - **@voltro/cli** — A 401 or 403 from the inspect surface now names `VOLTRO_INSPECT_TOKEN` and says which side is missing. `voltro db plan --against ` printed `remote returned 403` and stopped. A consumer read that as a DATABASE permission problem — the natural reading of a 403 from a command whose entire subject is a database — and went looking at grants. The cause is one unset environment variable, which the command reads four lines above the message. `voltro probe access` had half of it: it named the variable on 401 and not on 403, while classifying both as `refused`. So the two commands somebody needs during an access migration were the two that would not say what was wrong, and one of them said something misleading instead. `inspectGateHint` is shared by both call sites and distinguishes the two statuses, because they call for different actions: a 401 means no credential was sent (set the variable), a 403 means the one sent was not accepted (the two values differ). Both halves of the sentence name the server AND the calling shell — naming one side produces a second failed attempt. - **@voltro/cli** — `VOLTRO_TEMPLATES_DIR` is authoritative when set. It used to be a HINT: if the path it named held no `apps/` (or no `baselines/`), both resolvers fell through to the sibling-checkout walk-up and quietly used a different tree — or none. A pointer that silently isn't followed is worse than a wrong one. A CI job aimed at the wrong path scaffolded from whatever it happened to find, and a job whose checkout had failed reported an empty template catalogue with nothing connecting that emptiness to the variable it was given. `scripts/lib/docsSite.mjs` states the same rule for `VOLTRO_DOCS_DIR`, and arrived at it the same way: you said where it is; it is not there. Behaviourally this only changes the misconfigured case — a correct `VOLTRO_TEMPLATES_DIR` resolved to the same place before and after. What changes is that a wrong one now shows up as "not found, here is the path I was told" at the first thing that reads it, instead of as a different tree three steps later. The unbundled resolution order is otherwise untouched: sibling `voltro-templates` → `.voltro-templates` → the bundled `templates/` a published CLI ships. ### Internal (no consumer-facing effect) - **@voltro/plugin-ai-flows** — Two comments in the flow engine cited task records from a plans tracker that has since been deleted. Comment-only; no behavior, no API, nothing a consumer can observe. Worth writing down because of HOW it surfaced. The tracker was retired in the META repo, and the gate that went red was in THIS one — `check-stale-task-comments.mjs` resolves a comment's `task #NN` against `../plans`, so deleting a plan document in one repo can only be half a change, and the other half is in a repo the deleting commit never touched. Neither comment was WRONG, which is the part that makes the rule earn its keep. The first claims `@voltro/ai` has first-class media generation — true: `generateImage`, `generateSpeech`, `generateVideo` all ship in `packages/ai/src/media.ts`. It now names those three instead of a record number, which is checkable without the deleted document. The second only quoted the retired id inside its own account of a defect (a `"not yet wired (task #35)"` message that outlived the shipped HITL park and misled an audit into filing it as unbuilt); the quote lost the number and kept the whole lesson. The check's own failure text is the reasoning: a plan is retired for exactly two reasons — the work shipped, or it was dropped without shipping — and a comment still citing it asserts the second while usually meaning the first. --- ## [0.36.0] — 2026-08-13 ### ⚠ BREAKING - **@voltro/integration-http, @voltro/plugin-atlassian** — A 401 from an upstream now produces `code: 'unauthorized'`, not `code: 'session_expired'`. The connection vault's own failure — where we DO know the credential is unusable — becomes `code: 'credential_unusable'`. `session_expired` asserted a cause the status cannot support. A 401 says the credential was not accepted and says nothing about why: expired, revoked, insufficient scope and MALFORMED all produce it. A consumer's plugin sent ciphertext as a bearer token (a separate defect, fixed in the same release), the upstream answered 401, this name called it an expired session, and their health check acted on the name and deleted a valid session. Login loop, with every symptom pointing at a revoked credential. Names get acted on, which is the whole reason to split them: - `'unauthorized'` — the upstream refused. Non-transient, so still never retried; `status` rides along so a caller that knows more about its own upstream can decide for itself. Deciding for them is what this gives up. - `'credential_unusable'` — the connection vault could not produce a credential (no grant, revoked grant, refresh failed). Here the claim is ours to make, because the failure is ours rather than the far end's. The 401 message stopped saying "session expired" too. It now says the credential was refused and that the reason is not in the response — which is the honest sentence and the one that would have saved the day this cost. Its test asserts the CLAIM rather than banning the word: the first version forbade `/expired/i` and went red against the corrected message, which lists expiry as one of several things a 401 can mean. That distinction is the point of the change, so the assertion had to be about `session expired` specifically. **`voltro update` carries you across this** — codemod `0.35.1/01_unauthorized-replaces-session-expired`. ### Added - **@voltro/web** — **`apiSurface: compatible` — why the three altered golden lines cannot break a caller.** `LoaderContext` and `LoaderFn` each gained a type parameter WITH a default, so an unparameterised reference still resolves. The one that needed proving is `query?`, which went from a written-out signature to `LoaderQuery` — and `LoaderQuery` is a conditional whose false branch is character-for-character the previous signature. `unknown` does not extend `ProcedureTypeMap`, so the defaulted instantiation takes that branch. Proved with `tsc` rather than by reading it: a probe asserting mutual assignability between `LoaderQuery` and the old signature compiles, and inverting the probe fails — with tsc printing the resolved type as `(tag: string, input?: Record | undefined) => Promise`, which is the old signature verbatim. `LoaderContext` takes the app's procedure map, so a loader's `query` infers its input and output from the descriptor instead of returning `unknown`. ```ts import type { AppProcedures } from '/rpcGroup' export const loader = async ({ query }: LoaderContext) => { const rows = await query?.('bookmarks.list', { limit: 100 }) // ^ inferred; an unknown tag or a wrong input shape is a compile error } ``` `AppProcedures` is generated already and has been for a while — it was wired to `createHooks` on the CLIENT and to nothing on the server, so every loader call site spelled its own output type by hand and a typo in a tag compiled. A consumer reported it twice. The extraction reuses `ProcedureInput` / `ProcedureOutput` from `@voltro/client` rather than re-deriving them: a second answer to "what does this tag return" drifts the first time a descriptor field is renamed, and both answers look right in isolation. Opt-in, and non-breaking: with no map named, the signature is the previous `(tag: string, …)`. The framework cannot import an app's generated file, which is the same reason `createHooks` takes it explicitly. Covered by a `.test-d.ts`, because the failure mode is "it compiles when it should not" and no runtime assertion can observe that. Two of its cases exist because the first version was vacuous: an `interface` fixture does not satisfy the map constraint (no implicit index signature — the codegen emits an alias for exactly this reason), so the typed branch fell back silently and every `@ts-expect-error` came back unused. ### Fixed - **@voltro/cli** — The store a plugin receives through `bindDataStore` now carries the storage codec, so an `.encrypted()` column read through it decrypts. A consumer measured both stores inside one request: `ctx.store` gave a 44-character plaintext PAT, and the store their plugin's `credentialsResolver` received gave 113 characters of `enc:v1:…`. Ciphertext is a syntactically valid bearer token, so nothing threw. Jira answered 401, `@voltro/integration-http` named that `session_expired`, their PAT health check did the reasonable thing with that name and deleted the session, and the user got login → dashboard → login forever. A configuration error in the costume of an authentication refusal, where every symptom pointed at the one explanation that was wrong. The part worth recording is that `bootStoreCodec.ts` was written for exactly this, after it happened at two other seams, and its header predicts this consumer's symptom verbatim: "a route reading an `.encrypted()` column got the literal string `enc:v1:…` back … the failure reads as 'wrong credential'". The fix was applied per-seam. `bindDataStore` was not one of the seams anybody listed, so it happened a third time — and a per-seam test stayed green throughout, because it covered the two seams somebody remembered. `bootStoreHandouts.test.ts` asserts the rule instead: no boot path hands a plugin the raw driver, on either boot path, with the wrapper applied before the handout. The codec needs no Subject — it is how a column is spelled on disk versus in JS — so there was never anything a boot-level store could not carry. Also relevant to anyone who followed the 0.28.0 codemod: that codemod told apps to stop carrying a credential on the Subject and look it up in the resolver instead. Doing exactly that is what put an app on this seam, so the instruction and `.encrypted()` were not simultaneously satisfiable through it. - **@voltro/runtime, @voltro/cli** — The rpc/WebSocket query and stream arms now resolve row visibility before the executor sees a context. Fixes a 0.35.0 regression that made every read throw for an app with a registered row filter, and the older leak underneath it. 0.35.0 shipped two things for the row filter: the registration moved to `globalThis` (so a duplicate `@voltro/runtime` instance cannot hide it), and a scoped store built without a resolved scope started throwing instead of silently serving unfiltered rows. The first was a real fix for a real hazard. The second was correct in principle and immediately fatal in practice, because the framework itself had a path that did exactly what it now refuses. The consumer who reported the original leak ran the two-line check we asked for and `getRowFilter()` was visible from their request path — so the instance split was NOT their cause, and our hypothesis was wrong. Their measurement is what found the real one: the refusal fired, meaning the registration was FOUND and `ctx.rowFilter` was still undefined at the store. Nothing was missing; a step was. Four arms reach a request context. `makeOneShotQueryRunner` (REST) and `makeQuerySubscriber` (SSE) both `await withRowFilter(...)` and say so in a comment. The rpc query handler and the stream handler — each hand-copied into both boot paths — handed the raw request straight through. So a user's executor received a context whose `ctx.store` applied no row filter, on the two arms that carry the most traffic. It survived because subscriptions are refiltered per DELIVERY, which made a descriptor-returning query look correct end to end while the executor's own reads were not. `withScopedRequest` is the seam that fixes it once: a request that already carries a scope passes through untouched (resolving twice would run the app's `load` twice per request), an app with NO filter stays fully synchronous, and an app with one gets an Effect — which every one of these call sites already accepts. A boot-path parity test pins both stream arms and the shared producer. The refusal also stopped firing for a SYSTEM subject. That is not a softening: `resolveRowFilterScopeFor` returns `NO_ROW_FILTER` for a system subject, so the only correct value was already determined, and several legitimate paths (schedules, resumed workflows, the webhook trigger context) build a context directly with no scope. Demanding a decision there is what took the api down. --- ## [0.35.0] — 2026-08-13 ### ⚠ BREAKING - **@voltro/runtime, @voltro/cli, @voltro/plugin-clickhouse, @voltro/plugin-duckdb, @voltro/plugin-analytics-postgres** — The analytics CDC-mirror's version is derived from the CHANGE under `changeScope: 'fleet'` (postgres CDC, mysql binlog) — warehouse baseline plus the change's per-key position in the totally-ordered fleet stream — instead of each replica's own clock. An N-replica deployment still issues N duplicate writes per change (every replica observes the whole stream; that is the transport), but they are now BYTE-IDENTICAL — same row image, same version — so the sinks' existing guards (ClickHouse `ReplacingMergeTree(version)`, DuckDB/postgres `excluded.version > version`) dedupe them for free, with no leader election and no clock anywhere. This closes the real defect behind the N× cost: under clock skew larger than the gap between two changes to one row, a peer's duplicate of the OLDER image could take the higher version and win in the warehouse permanently and silently. A replica joining mid-stream seeds each key's numbering from the warehouse's own high-water mark via the new REQUIRED `AnalyticsMirrorImpl.maxVersion` read (all shipped warehouse sinks implement it; tombstoned deletes keep their version so the read answers after a delete — a custom sink follows the codemod note). The once-per-boot `changeScope=fleet` warning that named this cost is REMOVED — the hazard it named is gone. Local-scope stores keep the hybrid-clock version unchanged. New tunable: `VOLTRO_ANALYTICS_MIRROR_VERSION_STATE_LIMIT` bounds the per-key version state (default 100000; least-recently-changed keys re-seed from the warehouse on their next change). - **@voltro/cli** — The declared framework table set no longer reads a runtime flag. `CDC`, `VOLTRO_UNDO` and `VOLTRO_TRACING_PERSIST` each moved it before this release; `app.config.ts` gained `schema: { traces?, undo? }` to declare the two that still need a decision. A consumer measured two fingerprints from one source tree, one database and one `NODE_ENV`, differing only in `CDC`. Their Helm chart gives the pre-upgrade migrate Job its own `env:` list — `NODE_ENV`, `DB_*`, the obvious migration inputs — while `CDC: "0"` lives in the pods' block, because change data capture is obviously a runtime concern. Nothing about the name reads as schema-affecting, so it was in none of their three overlays' jobs. The declared set is what the schema fingerprint hashes, so that is a GREEN migrate job followed by every pod refusing to boot. Latent for months, and it would have fired on their next deploy. Counting the family after their report found three, not one — measured on a mariadb app at `NODE_ENV=production`, each flag flipped alone: `CDC=0` removed `_voltro_cdc_offsets`, `VOLTRO_UNDO=on` added `_voltro_undo_log`, `VOLTRO_TRACING_PERSIST=all` added `_voltro_traces`. All three are the kind of value an operator puts on the pods and not on the job, and only one of them had been noticed. `NODE_ENV` had already produced this exact failure in 0.34.0 and was fixed by making one decider resolve it for every command. That fix does not generalise here: a job legitimately does not carry an observability flag, so there is nothing to agree on. The rule is therefore stated rather than patched — **the declared set may depend only on inputs every process in one deployment computes identically** (the source tree, `app.config.ts`, the dialect, and `NODE_ENV`), and `declaredSchemaGates.test.ts` sweeps every `VOLTRO_*` / `CDC` / `DB_*` name the framework reads anywhere in `packages/*/src` and fails if any of them moves the set. Derived rather than listed, because a test naming the three known offenders only re-checks what someone already remembered — which is how the two unreported ones survived. The three got two different answers, deliberately. `CDC` left the derivation entirely: `_voltro_cdc_offsets` follows the DIALECT now, so a mariadb or mssql app declares it whether or not that process drives CDC. The cost is one empty offsets table and it is the same trade `impliesScheduleTables` already makes in writing. `VOLTRO_UNDO` and `VOLTRO_TRACING_PERSIST` could not simply be dropped — both can legitimately turn a table on in production, and a declared set that ignored them would leave capture writing to a table nobody created — so they keep their runtime meaning and lose their declaring power. Turning capture OFF still needs no declaration and never will; turning it ON without one is refused at boot, on both boot paths, with the config field named. The `prod-mismatch` refusal also stopped being two hashes and a command. It prints which of the three decided tables THIS process declared and from which input, because the ledger stores no table set to diff against and the command it used to recommend was the one the operator had just run successfully. That half matters beyond the framework's own tables: a plugin's `extendSchema.tables` is app code and can read anything, so the rule above cannot be enforced for it. **`voltro update` carries you across this** — codemod `0.35.0/05_declared-schema-drops-runtime-flags`. - **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/devtools-ui** — A declared event must decide who may listen — the boot gate now covers `defineEvent`, closing SEC-1's sibling. `defineEvent`'s `guards:` was optional and `bindEvent` skipped an empty list, so under `security.defaultDeny` an event with NO access declaration was silently subscribable by anyone who could open the socket, while the identical shape was already refused for every procedure. `defineEvent` now accepts `openAccess: ''` — mutually exclusive with `guards:`, reason string required — exactly as the four procedure definers do. The erased `{ open }` decision rides the same `guards` array every enforcement path reads; `bindEvent` treats it as "no check" (an open event pays what an unguarded one pays: nothing), and `eventToRpc` no longer unions `ScopeError` into the wire contract for an event that cannot produce a denial. **Breaking for `security.defaultDeny` apps (the default):** an app with a `*.event.ts` declaring neither `guards:` nor `openAccess:` now refuses to boot under `voltro dev` and `voltro serve`, naming every undecided event — the same message, from the same gate, procedures get. `voltro doctor` lists the same set. Migration: give each event a decision (`guards: [{ scope: '…' }]` or `openAccess: ''`); an app that wants the old default-allow declares `security: { defaultDeny: false }` once, in `app.config.ts`. Plugin-declared events are not judged — the gate reads the app's own discovered files only. The events inspect snapshot (and the devtools Events panel) now counts only ENFORCEABLE guards and carries the `openAccess` reason, so a deliberately open event renders as "open access" instead of as "1 guard" over an event anyone may subscribe to. **`voltro update` carries you across this** — codemod `0.35.0/01_event-access-decision`. - **@voltro/plugin-ai-flows** — **The breaking half, first:** `RunStepStatus` gained `'skipped'`. A sixth member means an exhaustive switch over it stops compiling and a status-keyed lookup has a hole — so a manual codemod fires on any app that names the type or its literals. Everything else here is additive (optional fields, new exports, one nullable column that rides the declarative differ). Flows can now BRANCH, FAN OUT, and no longer chain without a bound. Three additions, and the third is a defect fix wearing a feature's clothes. **`when:` — a conditional step.** A step runs only if its condition holds against the run context; a false condition SKIPS the step rather than failing it, so it produces no output and anything referencing it sees an absent value. The run timeline carries the rendered reason (`{{mode}} equals "full"`), because a step that silently vanished is indistinguishable from a step nobody declared. The condition is STRUCTURED data (`{ ref, op, value }`), not an expression string, and that is three decisions in one. A flow can be authored as a stored row a user edits in a browser — an expression there is an evaluator running user-authored source on the server. The visual editor can offer a dropdown over a structure and cannot over a string it would have to parse. And `validateFlow` already walks every reference, so a structured `ref` joins that check for free: a typo'd condition would otherwise evaluate absent, take the false branch, and skip its step on every run, forever, with nothing logged. Truthiness here deliberately differs from JavaScript's: `0` and `''` are TRUTHY. A step gated on a generated count or string means "did the producer run", not "is it non-zero" — the second is `{ op: 'neq', value: 0 }`, sayable when meant. **`group:` — concurrent steps.** Consecutive steps sharing a group name run at the same time, each keeping its own durable step, so a replay resolves every branch from the journal exactly as it would sequentially. Kept as a flat field rather than a nested `parallel([...])` because the durable step name, the run timeline and a `human` step's signal name are all INDEX-keyed — nesting would re-index every flow already running. Three rules, all enforced at registration: grouped steps cannot read each other's outputs (they have no order between them), a group must be contiguous (a name that stops and resumes would run as two sequential fan-outs), and a `human` review cannot join a group (it suspends the whole run). Context writes are applied after the whole segment in AUTHORED order — applying them as branches land would make the run context depend on scheduling, which a durable replay must never do. **A chain is bounded — this half is a fix.** `chainTo` carried exactly one guard, a flow could not chain to itself, so `A → B → A` and any deep chain were unbounded: each hop starts a child run with a fresh idempotency key, so nothing collapsed it and nothing was counting the hops. A run now carries the chain that led to it ON THE PAYLOAD — deliberately not reconstructed from the run rows, because a guard whose evidence comes from a query is a guard that permits the loop whenever the query fails. A chain is refused on a cycle, or at `maxChainDepth` (default 5; `aiFlowsPlugin({ maxChainDepth })` or `VOLTRO_AI_FLOW_MAX_CHAIN_DEPTH`), and the refusal lands on the run row's new `chainRefusal` column naming the path. The parent run still SUCCEEDS: a refused follow-up is a configuration problem, not a reason to destroy a completed result. All three are driven through the REAL durable executor in tests, not just their pure helpers — a primitive that is correct and reaches nothing is the defect class this package's own segmentation module exists to prevent. - **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/ai, @voltro/plugin-billing, @voltro/plugin-flags, @voltro/plugin-governance, @voltro/plugin-notifications, @voltro/plugin-presence, @voltro/plugin-storage** — Every first-party plugin rpc route now declares an access decision (`guards:` or `openAccess: ''`), and `security.defaultDeny` is enforced in the DISPATCH spine as defense in depth behind the boot gate: a descriptor that reaches the wire with no decision (a third-party plugin route, an embedder's hand-bound descriptor) is refused per-request with a typed `ScopeError` before the transaction / external I/O. Twelve previously-open routes now require a scope: `billing.startCheckout` / `portalUrl` / `previewChange` / `changePlan` / `changeSeats` / `invoices` → `billing:manage`; `billing.reportUsage` → `billing:report`; `governance.export` / `erase` → `admin:full` (already enforced in-handler, now declared); `storage.mintUploadUrl` / `ingestUrl` → `storage:manage`; `storage.listRefs` → `storage:browse`. Migration: grant the scope to the role/subjects that legitimately hold each capability (rbac role, `resolveScopes`, api-key scopes) — the codemod lists every route and the open-by-design surfaces that did NOT change. `PluginRpcRoute` gains `guards`/`openAccess` fields, carried through the route lift into the enforced descriptor; the synthesized agent/undo/connections built-ins declare `openAccess` so they keep serving under default-deny. ### Added - **@voltro/workflow, @voltro/cli** — `awaitSignal` now logs a one-time hint (once per workflow, never per poll) when its declared `timeoutMs` exceeds a threshold, naming `awaitSignalSuspending` — the drop-in variant that SUSPENDS the run and frees the worker slot for human-approval-length waits (WF-11). Threshold: `workflows: { suspendSignalHintMs }` in `app.config.ts` (default 5 minutes), env override `VOLTRO_WORKFLOW_SUSPEND_HINT_MS`. A hint only — the framework never swaps the variant under a run, because the two journal differently and a silent swap mid-history is a replay trap. - **@voltro/data-transfer, @voltro/sql-postgres, @voltro/cli** — The logical importer bulk-loads postgres targets via `COPY … FROM STDIN` (PERF-13). `voltro data import` engages it automatically wherever plain-INSERT semantics provably hold — `--mode replace`, or the default `upsert` into a table that is empty at import time (the fresh-target shape of every cross-dialect migration) — and never under `--atomic`. A refused COPY batch is atomic (nothing landed), so the importer replays exactly that batch through the per-row path with held-row / deferred-FK semantics intact. MEASURED on a 7-column table (text/int/bool/jsonb/timestamptz), 50 000 rows, local postgres: row-by-row 12.8 s (~3.9 k rows/s) vs COPY 0.59 s (~84.6 k rows/s) — **21.7×**. New seams: `ImportOptions.copyLoader` / `copyBatchSize` (default 5000) in `@voltro/data-transfer`, and `makePgCopySession` / `encodeCopyRow` in `@voltro/sql-postgres` (a submittable CopyIn query over the existing `pg` driver — no new dependency). Other dialects keep the per-row writes. - **@voltro/cli** — `voltro probe access` asks a RUNNING app whether its declared access is actually enforced — the question none of the existing checks ask. `voltro check`, the boot access gate and `security.defaultDeny` all verify that a decision was DECLARED. None of them verifies that the declaration REFUSES anyone. That distinction is not hypothetical here: the dispatch spine and the boot gate were separate for several releases, a procedure filtered out of the rpc group while still bound in the handler map served silently on one path and crashed the other, and `check` itself counted a decided-open route as guarded. Every one was the declaration and the behaviour disagreeing, found by reading rather than by asking. It calls every guarded procedure with NO credentials and reports three verdicts: `refused` (enforcement works), `admitted` (the finding), and `inconclusive` — the call failed for a reason that is not an access refusal, usually payload validation running before the guard. `inconclusive` is never counted as a pass; `--strict` fails on it, which is what CI wants. It probes ANONYMOUSLY on purpose. That is strictly weaker than scope-by-scope differentiation and strictly safer: the alternative puts credential minting into a command that can be pointed at production. Procedures declared `openAccess:` are skipped — probing them would report every deliberately-public route as a finding and bury the real ones, which is the same signal-to-noise failure `kind: 'open'` was added to the wire to fix. `fetchJson` gained an explicit `anonymous` option for this one caller; it is an opt-out, never a default, and both directions are pinned by a test — a bearer attached here would make every result meaningless while still printing green. **Validated against a live app, and it took two corrections to get there.** The first version sent a readable request id, which the transport converts with `BigInt(id)` — so every probe came back as a Defect before any guard ran, and every app looked broken. The second read a top-level `_tag` off an object while `POST /rpc` answers an ARRAY of envelopes, so a correctly-refused call scored as `admitted`. Both versions had a green unit suite, because the fixtures asserted the shape the code assumed. The fixtures are now copied from a real transcript. - **@voltro/cli, @voltro/runtime** — `app.config.ts` gained `reactive: { deliveryConcurrency, rawReadTrackingLimit }` — the delivery-loop tunables were env-only, which left a number the framework picks on the project's behalf undeclarable in the one file that carries every other tunable. Resolution stays inside the Dispatcher constructor (`resolveReactiveConfig`), so neither boot path can drift, and the env vars still win over the declared value: an operator acting on a running deployment outranks the project file. The threading itself is source-pinned across all three files (`dev.ts`, `serveCommand.ts`, `serveApi.ts`) because the serve side is a two-file relay and the union is where an option goes missing invisibly. - **@voltro/cli, @voltro/database** — Data residency is DECLARABLE and wired. `tenancy.residency` in `app.config.ts` opens one store per servable region on both boot paths and routes every request to its tenant's home region — or refuses it. The primitives have existed for two rounds (`setResidencyConfig`, `residentPlacement`, `bindResidentStore`), exported and tested, with **zero callers**. A user could reach them, but nothing in the framework did: there was no way to declare residency and no request ever consulted it. That gap was pinned by a test walking every workspace source, which went red on this change and asked for the module header to be corrected — it now names its consumers instead of asserting it has none, so a SECOND unreviewed caller still fails. ```ts tenancy: { isolation: 'namespace', residency: { servableRegions: ['eu-west'], regionUrlEnv: { 'eu-west': 'DB_URL_EU', 'us-east': 'DB_URL_US' }, homes: [{ tenantId: 'acme', region: 'eu-west' }], }, } ``` `regionUrlEnv` names an env VAR, not a URL — a connection string is a secret and `app.config.ts` is committed. Everything else about a region's store (pool bounds, TLS, `search_path`, timeouts) is inherited from the primary connection, so a region cannot silently run with different limits than its deployment. **Every failure is a refusal, never a fallback**, because a residency system that degrades to a default store violates residency at exactly the moment something is misconfigured. Unresolvable tenant, unmapped home, or a home region this deployment does not serve are all typed refusals; the last one names the region so a gateway can route it. Four declarations are refused at BOOT rather than warned about: residency without `isolation: 'namespace'` (the region keeps regions apart, the namespace keeps tenants apart — one without the other is not isolation), a servable region with no env-var name, one whose env var is unset, and a tenant mapped to two regions. Two boundaries worth knowing: - `ctx.storeForTenant(id)` resolves residency for THAT tenant, not the caller's, so a handler acting on another tenant reaches that tenant's region or is refused. Background work (schedules, workflows) runs with no tenant and must use it — `ctx.store` there is the primary store. - A transaction is never re-routed. A caller-supplied store is used as given; it already went through residency to exist, and moving writes off the connection holding the lock is a worse failure than the one residency prevents. Homes resolve once at boot (an array, or a function reading your own table), so adding a tenant home needs a restart — chosen over a cache with a staleness window on a decision whose whole value is that it is never wrong. - **@voltro/runtime, @voltro/cli** — `voltro schedule backfill --from --to [--yes] [--limit N]` and `POST /_voltro/inspect/schedules/:name/backfill` (WF-14) — fire every cron occurrence of a schedule over an explicit range, sequentially, each recorded against its own cron-derived `scheduledAt` with `trigger: 'manual'`. Fills the gap boot backfill (walks from the last recorded run only) and cluster-cron catch-up (capped at one day) leave open. Bounded and confirmable: above 25 occurrences it refuses without `--yes` (printing the count), above the per-request cap (default 1 000, `--limit` up to a hard ceiling of 10 000) it refuses outright, firing nothing — never a silent prefix. Wired on both boot paths through one shared hook. - **@voltro/devtools-ui, @voltro/plugin-search** — The Search dashboard panel now RENDERS the drift surface REL-1 shipped server-side and no dashboard showed (the additive-JSON silent-drift shape the 4-layer rule exists for): per-index `dropped` / `pendingDrift` / `drifted` / last-drift badges, the repair queue itself (`GET /drift` — oldest first, with attempt counts and the engine's last error), and a **Resync now** action (`POST /resync`) gated on the new `canResyncSearch` capability (its own flag — a resync re-reads only the drifted rows; a reindex re-reads the whole table). Landed across all four layers in one change set: shared `SearchPage` + wire types + capability + EN/DE strings here; HTTP fetchers + page wiring in voltro-devtools; tenant-scoped `apps.inspectSearchDrift` / `apps.inspectSearchResync` proxies + hooks + page wiring in voltro-cloud (the indexes proxy schema carries the new fields as OPTIONAL, so a customer app from before the drift ledger still decodes). `search.query` also now carries an explicit access decision (`openAccess`, with the tenant-scoping rationale in source) instead of the undecided SEC-1 shape. - **@voltro/cli** — Workflow wakes over the change stream (WF-8): on a fleet where remote changes reach the change spine (Postgres LISTEN/NOTIFY CDC — the common broker-less multi-replica deployment), a remote replica's `signal-sent` event, start context, or run transition now triggers an immediate, coalesced `pollStorage` on every replica, so cross-replica signal/step latency stops being bounded by the 10 s storage poll. Honest subset by design: the cluster engine has no per-run wake seam, so the change event wakes the poll early rather than replacing it — the poll tick stays the safety net. Local-origin changes never wake (a replica waking on its own recorder rows would be a poll storm). Wired by the same `makeWorkflowWake` builder on both boot paths. - **@voltro/runtime, @voltro/workflow, @voltro/cli** — `ctx.workflows.start(name, payload, { at: Date })` — delayed one-off starts (WF-13). The start is parked as a durable `_voltro_workflow_pending` row (`mode: 'delayed'`) and fired by the coordinated drainer when `at` arrives, so it survives restarts and fires on whichever replica drains. At `at` it becomes an ordinary ARRIVAL: declared flow control (debounce, singleton, rateLimit, …) judges it as of that moment — `at` never bypasses a control. The handle reports `status: 'queued'` with `deferral: { mode: 'delayed', dueAt }`. An `at` in the past starts immediately; `{ at, wait: true }` is refused. `at` is an absolute instant by design (no `delay` spelling): a delay is ambiguous about its epoch and every queue system answers it differently, while an instant composes with the schedule/backfill surfaces. - **@voltro/workflow, @voltro/cli** — `workflows: { recording: 'coarse' }` in `app.config.ts` (env override `VOLTRO_WORKFLOW_RECORDING`) — turns off the two fire-and-forget per-step writes to `_voltro_workflow_run_steps` (WF-10) for hot high-step workflows. Run rows, run events (signals/timers/cancels/stall reports) and the cluster engine's durable journal are unaffected — replay and redrive work exactly as before; the cost is an empty step timeline for runs recorded under coarse. Measured before it was built (`packages/cli/scripts/admission-throughput.mjs`): the recorder costs exactly 2 store writes per step, off the step's critical path — which is why the knob is a skip, not a batcher. - **@voltro/workflow, @voltro/cli** — `workflow({ schedule })` — the workflow-side cron declaration (WF-12), with Temporal Schedules' overlap vocabulary about the RUN: `onOverlap: 'skip' | 'buffer' | 'cancelOther'`. Pure sugar over the shipped scheduler: at boot it lowers into a real schedule named `workflow:` (same coordinated claims, run rows, Schedules panel, `voltro schedule` verbs). The synthesised firing awaits the workflow run to completion, which is what makes skip/buffer bind on the run's duration; `cancelOther` cancels only the still-running run this schedule itself started. The firing watchdog (`schedule.maxRuntime`) defaults to 24 h here. Cron and timezone are validated at definition time. ### Changed - **@voltro/plugin-clickhouse** — `clickhouseAnalytics` now BATCHES `track()` inserts by default (PERF-11) — 20 events / 5 s, plugin-posthog's conservative numbers — instead of one HTTP insert (and one MergeTree part) per event. What changes observably for an app that never set `batch`: a successful `track()` now means "buffered", not "ClickHouse accepted the row"; events become readable up to 5 s after they were tracked; a flush failure drops that batch with a warning (a hard crash loses whatever is still buffered — graceful shutdown drains via `dispose`). Opt OUT with `batch: false` to restore one immediate, confirmed insert per event; `batch: { maxSize, flushIntervalMs }` tunes the window. No compile break — `batch` widened to `ClickhouseBatchOptions | false`, and the previous opt-in spelling keeps working (its defaults are now 20/5000 rather than 1000/5000). - **@voltro/database, @voltro/cli, @voltro/workflow** — The migration advisory lock is now scoped to the configured schema (`DB_SCHEMA`) instead of one framework-wide constant. A postgres advisory lock is database-scoped and MySQL `GET_LOCK` is server-wide, so two apps sharing one database in different schemas used to serialize each other's migrations and defer each other's boot-time trigger repair — with a log line blaming "another instance". Now: postgres derives a stable 64-bit key from the schema name (FNV-1a 64 of `voltro_migration_lock:`, sign bit cleared; collisions across schemas are possible and only reintroduce serialization, never a race); mysql/mariadb/mssql suffix the lock NAME with the schema (hashed past MySQL's 64-char `GET_LOCK` cap). Every taker moved together in this change — the declarative applier, the file-based runner, the boot auto-migrate, the CLI's reactive-trigger boot repair, and the workflow cluster first-boot gate (its own distinct key, same derivation). On mysql/mariadb, where `GET_LOCK` is server-wide and `DB_SCHEMA` is not a connection pin, setting `DB_SCHEMA` to your database name is how two apps on one server un-share the lock. **Rolling-deploy story.** An app WITHOUT `DB_SCHEMA` (or with `DB_SCHEMA=public`) keeps the EXACT pre-change lock key and name — old and new replicas contend on the same lock throughout the rollout; nothing to do. An app WITH a non-default `DB_SCHEMA` changes its lock key when it lands this version: during that one rollout window, old-generation and new-generation replicas do not mutually exclude their DDL. The boot auto-migrate DDL is idempotent (`IF NOT EXISTS`-shaped), so the practical exposure is the known postgres `CREATE TABLE IF NOT EXISTS` catalog race — worst case one replica's boot fails and restarts. Avoid running `voltro db apply` concurrently with THAT rollout; after it, everything contends on the schema-scoped key. - **@voltro/plugin-search** — `POST /reindex` now STREAMS the source table (keyset-paginated `streamTable`) and upserts one bounded page at a time instead of loading the whole table into memory — the old shape was an OOM on exactly the tables big enough to need a reindex (PERF-12). The page size is a new tunable, `searchPlugin({ sync: { reindexBatchSize } })` (default 1000), and the `/indexes` panel reports it as part of the policy in force. `backfillIndex` keeps its plain-array signature for small explicit seeds. Additive surface only: a new optional `SearchSyncOptions` knob + a new `SYNC_DEFAULTS` key — no existing call site changes meaning. - **@voltro/plugin-search** — Sync-stat counters no longer pay a read+CAS against the OLTP primary on EVERY indexed-table write (PERF-14). Counts buffer in memory and flush per window — `searchPlugin({ sync: { statsFlushIntervalMs } })` (default 5000 ms; `0` restores the per-event durable write) with an early flush at `statsFlushMaxBuffered` (default 1000) pending counts. Mirrors the runtime's api-key usage buffer, SHUTDOWN included: plugin deactivate drains the tail on both boot paths, so a graceful deploy loses nothing; a hard crash loses at most the current window of counters (never a change — the drift ledger stays the durable record). `GET /indexes` drains the buffer before reading, so the panel stays truthful mid-window. `StatsStore` gained a delta-applying `add` (the flush target); both shipped impls carry it and nothing consumes user-provided `StatsStore` implementations. - **@voltro/database, @voltro/plugin-webhooks, @voltro/testing, @voltro/voltro, @voltro/workflow** — Golden churn from this round's signature WIDENINGS, classified per package: - **@voltro/database** — every migration entry point (`applySchema`, `runMigrate`, `runFrameworkBootstrap`, `applyNamespacedSchema`, `provisionTenantNamespace`, the lock functions) gained a trailing OPTIONAL parameter (`SchemaApplyOptions` / `MigrationLockScope`) for the schema-scoped lock and the dialect retry predicate. Every existing call compiles unchanged; omitting the parameter is exactly the old behavior. - **@voltro/workflow / @voltro/testing / @voltro/voltro** — the same widenings re-exported through the aggregates, plus `PresenceWrite`-adjacent type surface already classified in this release's presence entry. - **@voltro/plugin-webhooks** — `deliverWebhookWorkflow`'s payload type inference had COLLAPSED to `AnyStructSchema | Struct`, which made `execute`'s requirements `any` for every consumer: there was no type contract in force to break, only one that silently did not exist. It now infers the real payload struct. The export's only callers are the framework's own boot paths (it exists for cluster-runner registration); an app that passed a wrong-shaped payload under `any` now gets the compile error it should always have had — which is the fix, not collateral. ### Fixed - **@voltro/cli, @voltro/protocol** — `voltro doctor`, the boot refusal, and `GuardSpec.resource`'s own doc comment now name the per-resource form of an access decision. All three listed two ways to decide and there are three. A consumer with 565 undecided procedures set `security: { defaultDeny: false }` across their app, and their reasoning was correct at every step from what they were shown. Their authority is per-team — a viewer in one team, an admin in another — so a subject-global `guards: [{ scope }]` would state a check they do not perform, and the boot refusal warns against exactly that ("reaching for a scope every caller already holds satisfies the gate, reads as protection, and enforces nothing"). `openAccess:` would be untrue. Both offered forms were rightly rejected, so they turned the gate off and kept enforcing in handlers. The form that fits them — `guards: [{ action, resourceType, resource }]`, backed by `defineResourcePolicy` and a tuple source registered over their own tables — has shipped for several releases, is wired on both boot paths, fails closed without a resolver, and is documented under Authentication → Authorization. They looked: they read `GuardSpec.resource`, whose doc comment described the resolver as "a future ReBAC / `accessPolicy()` resolver". That sentence was written before the ReBAC path shipped and never updated, and it is the only thing a reader of that type has. A doc comment that says "future" about something built is not a small inaccuracy — it argued a careful team out of a security gate. An enumeration inside a refusal is read as exhaustive, and the more careful the reader, the more thoroughly they act on it. `accessDecisionForms.test.ts` pins all three forms in all three places, including the `defaultDeny: false` branch — an app that has already given up is precisely the audience that needs to learn there was a third option. - **@voltro/protocol, @voltro/database, @voltro/runtime, @voltro/plugin-broadcast, @voltro/sql-postgres, @voltro/sql-mysql, @voltro/sql-sqlite, @voltro/sql-mssql** — A reactivity-channel publish now says where it came from — `origin: 'inline'`, because it happened in THIS process — instead of borrowing the `'injected'` stamp its transport seam applies by default. Two defects came out of that one mislabel, both silent: - **A channel published synchronously from inside a change listener never left the replica.** `plugin-broadcast` suppresses re-publishes while it is injecting, and the bracket was coarse: it dropped EVERY emission made in that window, not just the event it had injected. So `onChange` → `publishReactivity` woke the local node and no peer ever heard it — no error, no log. The one plugin doing cross-replica fan-out (presence) escaped only because it re-publishes from its own transport callback. The guard now suppresses by provenance, so a local publish made inside the bracket travels like any other. - **A replica could not tell its own channel publish from a peer's.** Both arrived `'injected'`, so a listener fanning a channel onward had nothing to key on and needed a boolean per channel to avoid an echo. `origin` answers it now. Two supporting changes, each with its own failure mode: - `origin` no longer survives the wire. It describes how an event reached THIS process, so the receiving replica strips what the sender serialised and stamps its own. Without this the guard fails OPEN — measured, an arrival still claiming `'inline'` amplified one publish into 163 events and killed the test worker. - The transport-origin stamp has one definition (`externalChangeEvent`, `@voltro/database`) instead of five hand copies across the memory store and the four dialect stores. `injectOriginParity.test.ts` fails if any store grows its own again — a store that hand-stamps would override a caller's stated origin, and the visible result is a channel that stops crossing replicas on that dialect only. `DataStore.injectExternalChange` keeps its shape: an event that states no origin is still stamped `'injected'`. A store passed to `plugin-broadcast` that does not stamp at all (the interface is structural) is detected by identity and falls back to the old coarse suppression rather than amplifying. - **@voltro/cli, @voltro/devtools-ui** — `voltro check` no longer mistakes a deliberate `openAccess:` mutation for an unguarded one — and no longer mistakes it for a guarded one either. The manifest serialises the decision as a `kind: 'open'` guard entry carrying the reason string; `toInput` now translates it into `openAccess` on the graph procedure with `hasGuards: false` (nothing IS checked), and the `rbac/unguarded-mutation` rule skips a procedure whose author already "confirmed it is intentionally public" — the rule's own fix text. Previously the open entry was counted as a guard, so the finding disappeared for the wrong reason: the open mutation read as protected. `@voltro/devtools-ui` gains the hand copy of the `SerialisedGuard` wire union (it is deliberately dependency-free, so it cannot import the CLI's), renders an access badge on the RPC page — guard count, or "open access" with the reason in the tooltip — and the copy is pinned from the owning side by `serialisedGuardParity.test.ts`, in the style of `migrationOpKindParity`. - **@voltro/cli** — `ctx.query` in a loader rejects an `error` event instead of returning it as the query's rows. A consumer put a guard with an unheld scope on a query and called it over HTTP with a valid user JWT. The batch came back 200 with an `error` chunk carrying a `ScopeError` and an `Exit: Success` after it. Both are correct — the transport worked and the guard worked — but `buildLoaderQuery` unwrapped exactly ONE member of the three-member `subscriptionEvent` union and passed the other two through as data. The loader returned the error OBJECT, it went into the SSR seed, and the component called `.map()` on it: `TypeError: kept.map is not a function`, on 135 pages, for every user. The `.catch(() => null)` in our own documented loader pattern could not fire, because nothing was thrown. Neither could `seedPagePreloads`' `onError`, for the same reason. The same rejection over the live socket sets `error` and leaves data empty, so the two transports were saying different things about one event. The unwrap is exhaustive now: `snapshot` yields its rows, `error` rejects with the typed error attached (as `cause` and `voltroError`, so an app can still branch on `ScopeError` rather than parse a string), and a first-event `delta` — structurally impossible today — throws naming itself a framework bug rather than handing a loader an id-keyed patch. `buildLoaderQuery` has one implementation shared by `voltro dev` and `voltro start`, so the fix covers the production path the report did not measure. The HTTP 200 is unchanged, and the reporter is right that it should be: the batch transport did succeed. - **@voltro/database, @voltro/cli** — The schema apply (`applySchema` / boot auto-migrate / framework bootstrap) now consults the dialect's own transient-failure predicate instead of dying on the first `SQLITE_BUSY`. The gap was located in `@voltro/sql-turso`: `busy_timeout` cannot retry the deferred-upgrade lock class, the store path already honoured the dialect's `retryFilter`, and the migration applier never consulted it — so a DDL statement that met the schema lock failed on the first attempt while every equivalent DML statement would have been retried. The CLI threads each loaded dialect's `retryFilter` through the new `SchemaApplyOptions`; retries are bounded (`VOLTRO_MIGRATION_DDL_RETRIES`, default 4, exponential backoff with jitter) and only ever re-run statements that are safe to re-run: per-statement on the per-operation dialects (sqlite/turso/mysql/mariadb, `IF NOT EXISTS`-shaped or covered by the duplicate-index tolerance), whole-transaction on postgres/mssql, whose retryable classes (deadlock victim, serialization failure) roll the transaction back cleanly. No `retryFilter` threaded means no retry — exactly the previous behavior. The declarative plan applier (`applyPlan`) is deliberately unchanged: its operations are not uniformly idempotent, and partial failure there is owned by the resume ledger. - **@voltro/web, @voltro/client** — The web first load no longer ships `msgpackr` — 190.5 → 180.6 KB gz (−9.9 KB, 5.1% of the whole first load) for every app, measured on the zero-procedure fixture and re-pinned into `bundle-budget.json`. It shipped because `@effect/rpc`'s RpcSerialization module top-level-imports msgpackr while every Voltro path selects `layerJson`, and msgpackr declares no `sideEffects` flag — so no bundler was allowed to drop it. The fix is a dependency patch adding `sideEffects: false`, declared at BOTH workspace roots (the @effect/cluster patch rule: a meta-root `pnpm install` must apply it too, or the two installs fight over node_modules). An app that genuinely calls `makeMsgPack` keeps the library — the flag only permits dropping it when unused. The bundle-budget gate's slack floor is what keeps this fixed: the budget is re-pinned to the new number, so quietly re-inflating past it fails CI. - **@voltro/cli, @voltro/database** — Under `tenantIsolation: 'namespace'`, a tenant's namespace is now PROVISIONED on its first use — schema DDL plus the `onTenantCreate` seed lifecycle, memoised per namespace per process. Neither ever happened: `provisionTenantNamespace` — documented as "the entry point the CLI / runtime use, eager at migrate time or lazily on first use" — had zero callers in the entire codebase, `withNamespace` returns a pure view, and so a fresh tenant's first request died on "relation does not exist" while the `onTenantCreate` seeds (recorded as wired) fired only from tests that called the function directly. Found by the claimed-wirings checker the moment it learned to read active-voice claims. Both boot paths build the provisioner from one builder; the namespace view's async methods await the memoised ensure (one resolved-promise await after the first settle), sync members stay sync, and the method classification is a DERIVED guard — a new `DataStore` method fails the test until someone decides whether it must await provisioning. A failed provision is surfaced and forgotten, never cached: one transient DDL failure must not become a permanently broken tenant on a replica. Verified end to end on live postgres, control included: the raw view still fails against a fresh namespace, the provisioned one creates the schema and fires the lifecycle exactly once. Eager provisioning stays the app's move (call `provisionTenantNamespace` from a seed or startup over your own tenant table) — the framework has no tenant registry to enumerate, and the docs now say so instead of implying otherwise. - **@voltro/runtime, @voltro/cli, @voltro/testing** — `setRowFilter`'s registration moved from a module-local variable to a `globalThis` cell, and a scoped store that receives no filter while one is registered now throws instead of serving unfiltered rows. A consumer measured four read paths returning every row of the tenant to every employee — 19/19 contracts, 231/231 time-entry requests, 6/6 user settings, 4637/4637 shifts — on both HTTP and WebSocket, with `row filter registered` in the boot log and 27 green tests. One of those paths was the only thing keeping `userSettings.update` safe, so every user could edit every other user's settings. Their exclusion work was exhaustive and right at every step: the load succeeded, `predicateFor` returned predicates for the right tables, nothing was `unconstrained`, no handler bypassed the store, and a `setRowFilter` + `makeTestContext` pair reproduced CORRECT filtering. That left them concluding the remaining variable was the store — memory in the green reproduction, postgres in the red deployment. It is not the store, and the correction is the transferable part: their reproduction ran inside ONE module instance and production does not necessarily. `ROW_FILTER` was a module-local `let`, so an app's `*.startup.tsx` and the framework's serve pipeline write and read different variables whenever they hold different copies of `@voltro/runtime` — the serve bundle inlines the framework while app modules stay external, and strict pnpm resolves one version into two physical directories when two importers have different peer contexts. The pipeline reads `undefined`, correctly interprets it as "this app registered no filter", and serves everything. `@voltro/database`'s `coreTablesRegistry` carries this exact fix with a comment describing this exact failure, for a value whose worst case is a crash at boot. This one's worst case is silent data exposure and it did not have it. The second half answers the reporter's second ask directly: a filter that cannot be applied must fail loudly rather than pass quietly. `undefined` and "we could not tell" had collapsed into one value, and the doc comment on that option already asserted they must not. Every deliberately unfiltered path — system sweeps, `runAsSystem`, change-stream subscribers, the seeding store in a test — now passes `NO_ROW_FILTER` explicitly, because "this app has no filter" and "this path is unfiltered on purpose" are different claims and only the second is a decision somebody made. - **@voltro/cli** — A bare `voltro serve` under docker compose now drains on SIGTERM — in-flight requests complete against a fully-alive app, the listener refuses new work, live WebSockets are ended cleanly, and the process exits on its own, well inside `VOLTRO_SHUTDOWN_GRACE_MS`. No preStop hook or endpoint removal required. Two real defects closed (both measured against a live server): a single connected WebSocket wedged `nodeServer.close()` — node's `closeAllConnections()`/`closeIdleConnections()` cannot end an upgraded socket while `close()` still waits on it — so EVERY shutdown with a connected web client ran to the 10s deadline cut and the steps queued behind the close (the store's connection-pool close included) silently never ran; and the shutdown hook deactivated plugins and drained the analytics mirror BEFORE the request drain, so a request finishing during shutdown hit dead services and its writes were never mirrored. The drain is bounded: in-flight requests get 60% of the shutdown grace (floor 500ms), stragglers are then destroyed, and idle keep-alive sockets are swept continuously so a finished response never delays exit. The stale `serveApi` comment claiming `NodeRuntime.runMain` owns SIGTERM (and pointing at a k8s preStop hook as the fix) is rewritten to describe the drain that actually runs. Verify against a real serve with `node scripts/serve-drain-check.mjs`. --- ## [0.34.0] — 2026-08-12 ### ⚠ BREAKING - **@voltro/client, @voltro/cli** — **The derived admin gated writes on scope strings nothing produced, so every write affordance was hidden from every caller — and the shipped demo could not show it.** `deriveEntityAdmins` invented three scopes per table (`
:create`, `
:write`, `
:delete`) and the admin template hid any action whose invented scope the subject did not hold. No plugin, role map or resolver ever grants those names. So for any app that named its scopes differently — nearly every app — the back-office rendered read-only for everybody. This is the unsatisfiable-guard failure moved one layer up: a total outage of the surface, wearing a permission check's clothes. It stayed invisible for a precise reason worth recording. `frontend-admin` seeds `admin:full`, the blanket-bypass scope, so the scaffold shows every action. The bug appears only when a user follows the documented advice and feeds their session's real scopes — **the correct move made the admin worse**, which is the worst possible shape for a defect to have. The answer had been on the wire since the manifest gained `guards`, added explicitly so "a UI gate and the server check cannot drift". The client mirror never read it. **What changed:** - `EntityAdminSpec`'s flat `listTag` / `createTag` / `updateTag` / `deleteTag` and the three `*Scope` strings are replaced by `list` / `create` / `update` / `delete`, each an `EntityAction` — `{ tag?, guards? }`, where `guards` is the procedure's OWN `guards:` / `openAccess:` declaration. - New `decideAccess(guards, scopes)` (pure) and `useAccessDecision(guards)` (hook) return **three** values: `allowed` | `denied` | `unknown`. `unknown` is the honest answer for a guard carrying a `resource` extractor — the real check is per ROW and a browser has no row — for a relationship guard, and for a procedure that declared nothing. Collapsing it to `denied` re-creates this exact outage for every multi-tenant app whose subjects are minted with `scopes: []`; collapsing it to `allowed` renders a control that always errors. The template shows those controls and lets the api answer with a typed `ScopeError`. `requiredScopes(guards)` renders the requirement so a refusal is readable. - **`openAccess` no longer vanishes on the wire.** `serialiseGuards` skipped the erased `{ open }` entry, so an intentionally-public procedure serialised identically to an undeclared one and a client's only safe reading was "hide it". It emits `{ kind: 'open', reason }` now — all three access states travel. - **The manifest carries the three exposure axes per column**, from the same classifier the inspect row-mask uses. `deriveEntityAdmins` acts on exactly one of them: `.serverOnly()` columns are EXCLUDED from `columns` (they never cross the wire, and the runtime already refuses them as mutation input) and named in `serverOnlyColumns`. `.encrypted()` and `.sensitive()` columns are KEPT — at-rest encryption is not wire exposure, and `.sensitive()` is the export axis; hiding either is the category error the three-axes rule forbids. `sensitiveColumns` is reported so an export path masks them. - **The manifest carries `pkColumn` + `editable`.** A UI hard-coding `row.id` sent an empty id on every delete for a table keyed on anything else. Migration: `spec.createTag` → `spec.create.tag`; `useCan(spec.createScope)` → `useAccessDecision(spec.create.guards)` plus a decision about `unknown`. The codemod is `manual` because that last part is an authorization posture a tool must not pick on your behalf — see its note. - **@voltro/plugin-ai-flows** — **A flow's SECOND human review used to resolve itself with the FIRST answer.** `awaitSignalSuspending` keys its `DurableDeferred` on workflow-name + signal-name per execution, and `plugin-ai-flows` used one constant — `HUMAN_RESPONSE_SIGNAL = 'flow-human-response'` — for every human step in every flow. The second review therefore awaited a deferred the first answer had already completed, and resolved instantly with that payload. Measured on the real engine before the fix, with a two-review flow and ONE answer sent: `status: 'succeeded'`, `output: { first: 'answer-one', second: 'answer-one' }` — an approval nobody was asked for, never shown as pending. (The same collision aliased the wait's durable timeout clock, so the second park also inherited the first's expiry.) Signal names are per-step now — `flow-human-response:`, derived from the step's position in the plan the run's journal pinned at step 0, so it is identical on every replay. `respondToFlow` reads the parked step off the run row's live timeline and addresses that step, so an app that calls it needs no change beyond dropping the removed import; it also returns the `stepIndex` it answered. Migration: `HUMAN_RESPONSE_SIGNAL` is removed — use `respondToFlow`, or `humanResponseSignalName(waitingStepIndex(runRow))` if you send the signal yourself. Runs already parked when you deploy were parked under the old name: answer them first, or cancel and relaunch. **`voltro update` carries you across this** — codemod `0.34.0/11_ai-flows-per-step-human-signal`. - **@voltro/runtime, @voltro/plugin-clickhouse, @voltro/plugin-duckdb, @voltro/plugin-analytics-postgres, @voltro/cli** — The analytics CDC-mirror said **at-least-once** in its own header and was at-most-once in its body: one forked promise per change, `catchAll → log.warn`, no retry, and no reconcile path anywhere — so a single warehouse blip lost that row from the mirror permanently. Two more defects rode along. The ClickHouse version was `Date.now() * 1000` read INSIDE the sink under `ReplacingMergeTree(version)`, and with no per-key ordering two rapid updates to one row could arrive out of order, which handed the STALE image the higher version and let it win forever (DuckDB and postgres-lite had the same race without the version veneer — plain last-writer-wins). And `catchAll` handles failures, not defects, so a sink that THREW escaped into the fire-and-forget tail as an unhandled promise rejection. The mirror now: - **orders per key.** Writes for one primary key are applied one at a time in commit order; different keys stay concurrent. - **versions from the change, not the clock.** Every write carries a `MirrorVersion` stamped when the change left the store. ClickHouse persists it as the `ReplacingMergeTree` version; DuckDB and postgres-lite apply the write only when it is newer (`ON CONFLICT … WHERE excluded.version > version`). - **retries and repairs.** Exponential backoff (`retryAttempts`, default 5), and a write that outlives its retries goes into a bounded repair queue whose timer re-reads the row's current state and re-applies it. Counted by `voltro_analytics_mirror_{forwarded,retries,repair_queued,dropped}_total`. - **handles defects.** `catchAllCause`, matching the search tap. Delivery guarantee, stated exactly: **at-least-once for the lifetime of the process, ordered per row.** Not durable across a crash — the repair queue is in memory; a change still queued when the process dies is counted as dropped and needs a re-seed. Migration (`voltro update` prints it): - `AnalyticsMirrorImpl.upsert/remove` take one object: `upsert({ table, row, version })` / `remove({ table, primaryKeyValue, version })`. A custom sink is a compile error until updated — deliberately, since the old shape had nowhere to put the version. `AnalyticsMirrorChange` (declared, never used) is deleted. - Mirror tables gained `version` + `is_deleted`. They are created with `CREATE TABLE IF NOT EXISTS`, so drop an existing `voltro_mirror_
` / `_voltro_mirror_
` once and let the next boot re-create it. - A delete writes a **tombstone**, not a row removal (a physical delete leaves a late stale insert nothing to lose against, and the row silently returns). Add `is_deleted = false` (`= 0` / `FINAL` on ClickHouse) to every analytical query that reads a mirror table — dashboards and notebooks included. Tunables, each with an env override: `VOLTRO_ANALYTICS_MIRROR_RETRY_ATTEMPTS` (5), `…_RETRY_BASE_MS` (100), `…_RETRY_MAX_MS` (30000), `…_REPAIR_INTERVAL_MS` (60000, `0` disables), `…_REPAIR_QUEUE_LIMIT` (10000). **`voltro update` carries you across this** — codemod `0.34.0/05_analytics-mirror-versioned-writes`. - **@voltro/plugin-billing** — **Dunning — the past-due sequence, a grace period, and a lockout — composed on the provider's own outcomes.** `invoice.payment_failed` has been mapped to an event since the beginning, and `setStatus` has described itself in-code as "the dunning state machine's transition primitive", but nothing connected a failed payment to the customer or to the app's entitlements. A Cashier switcher named this in the first conversation. What did NOT come back is the retry schedule. A `dunning.ts` used to live here and was deleted because it retried on a fixed `[1,3,5,7]`-day cadence while Stripe retried on its own and the two drifted the moment they disagreed. Stripe still owns the cadence. What is new is the part Stripe does not do for an app: branded notices at most once each, a grace window, and one truthful answer to "is this tenant entitled right now". **Two properties carry the whole design, and both exist because sending an email and locking a customer out are irreversible:** - **The grace clock is a column, not a timer.** `pastDueSince` lives on the subscription row and the lockout is DERIVED at read time. There is no job to miss a tick, double-fire, or run twice across replicas — and no dunning job was reintroduced. - **`pastDueSince` is only ever written after the PROVIDER confirms.** A reconcile reads `stripe.subscriptions.retrieve` and writes the local row from that, never from the event body. So a `payment_failed` that arrives after the retry which succeeded — Stripe's delivery is at-least-once AND unordered — reconciles to `active` and sends nothing, and a provider we cannot reach leaves the tenant in grace rather than escalating on unverified data. Idempotency is a `UNIQUE (tenantId, episode, stepId)` claim on the new `_voltro_billing_dunning_notices` ledger, taken BEFORE the send. The episode key IS the clock (`pastDueSince` epoch-ms), so recovery ends an episode and a later failure starts a genuinely new one with no counters to race. Claim-then-send is deliberate: its failure mode is one email that never arrives, where send-then-claim's is a customer getting the same dunning mail twice. **A behaviour change worth reading even if you write no new code:** `plan()` used to answer `'free'` the instant a subscription went `pastDue` — a bounced card downgraded the customer on the same second, with no grace at all, while the docs promised the opposite. It now answers the paid plan for the whole grace window, and falls back only once the lockout is real (and only under `lockout: 'hard'`). New surface: `billing.entitlementStatus(tenantId)` (a pure read — no provider call, safe on the hot path), `billing.reconcileDunning(tenantId)`, `billing.dunningSweep()`, the `requireEntitled(ctx)` in-handler guard, the typed `SubscriptionLocked` error, the `billing.entitlementStatus` rpc query, and `dunningMailNotifier(mail)` bridging notices to `@voltro/plugin-mail` structurally (no dependency added). Tunables, every one with a default and an env override — `dunning: { enabled, graceHours (168), steps (0h / 72h / 144h), lockout ('hard' | 'soft'), notify, resolveRecipient, portalReturnUrl } ` / `VOLTRO_BILLING_DUNNING`, `VOLTRO_BILLING_GRACE_HOURS`, `VOLTRO_BILLING_DUNNING_STEP_HOURS` (positional, and a count mismatch fails the BOOT rather than silently re-timing the wrong step), `VOLTRO_BILLING_LOCKOUT`. With no `notify` the sequence claims and logs and sends nothing, which is the right default for something the framework cannot address on the app's behalf. Also fixed here, all the same class — a mirror that believed arrival order: - `_voltro_billing_subscriptions` and `_voltro_billing_invoices` now carry a `statusEventAt` and DROP an event older than the state they already reflect. A redelivered `active` from before a decline used to silently un-do the past-due; a late `payment_failed` used to flip a paid invoice back to `open`. - `patchByTenant` declared only `plan | quantity | status`, so the `currentPeriodStart` / `currentPeriodEnd` that `changePlan` / `changeSeats` read back from Stripe were type-checked at the call site (conditional spreads dodge excess-property checking) and then dropped on the floor by the DataStore-backed store. The period bounds Stripe returned after a seat change were never persisted. **Migration.** `BillingProvider` gained a required `fetchSubscription` and an optional `customerEmail`; `BillingEvent` gained `occurredAt` on every variant; `Subscription` gained `pastDueSince` + `statusEventAt`. The Stripe and mock adapters ship both. If you wrote your own `BillingProvider`, implement `fetchSubscription` — returning the subscription's CURRENT status, not a cached one, because it is what dunning refuses to lock a customer out without. A provider that genuinely cannot answer should fail rather than guess: an unreachable provider leaves the tenant in grace, which is the safe direction. `_voltro_billing_dunning_notices` is registered with the retention sweep at ~400 days (`VOLTRO_BILLING_DUNNING_TTL_HOURS`). The bound is deliberately generous because the ledger IS the send gate — pruning a row belonging to a still-open episode would let its notice go out a second time — and an episode lasts weeks at the outside. **`voltro update` carries you across this** — codemod `0.34.0/13_billing-provider-dunning`. - **@voltro/runtime, @voltro/protocol, @voltro/plugin-auth, @voltro/cli** — **Soft re-auth presents a CREDENTIAL; it no longer hands the server a Subject — and it exists in production now (REL-23).** A WebSocket's handshake headers are fixed for the socket's life, so a credential minted *during* the connection — `auth.signin` over the live socket, a tenant switch — cannot reach the server on that connection. That is a transport problem. It was solved as an authorization one: `bindConnectionSubject(clientId, subject)` stored a resolved `Subject`, and the auth middleware began ```ts const override = getConnectionSubject(clientId) if (override) return override ``` so for the **life of that connection** nothing after that line ran again. Three things stopped happening, none of them audible: - the **session-revocation check** — it lives inside the auth strategy, so a user signed out from another device kept working on this socket; - **`resolveScopes` and the scope cache** — authority frozen at re-auth time, so a role removed afterwards was never observed; - the **credential-expiry record** that stops a subscription outliving the token that authorized it. There is no `exp` on a stored object; the only bound was a 24h idle sweep. This is the frozen session cookie that 0.34.0 just removed, one layer down, on a channel with no expiry at all. **And it existed only under `voltro dev`.** `serveApi.ts` had no such fast path, so the framework's own switch-tenant rebind worked in development and was a silent no-op in production. One defect facing two opposite directions: where it worked it bypassed the auth chain, and where it mattered it did nothing. **The override now carries the credential.** `bindConnectionCredential(clientId, { cookies, headers })` patches the connection's headers, and the middleware runs the **same chain a fresh request runs**. There is no property a rebound connection has that a reconnecting one would not, because it is the same code path. `cookies:` sets or replaces named cookies *inside* the `Cookie` header — replacing the header wholesale would drop every other cookie the connection carries, and a caller minting a session knows its own and nothing about the rest. The cost is honest and is the point: **a rebinder must have a credential to present.** A caller with nothing to present could not authenticate a fresh request either, so that connection was asserting authority no request could obtain and nothing could revoke. **The dev/serve half is closed structurally, not by mirroring.** Both boot paths build their middleware from ONE function, `makeAuthMiddlewareLayers` (`@voltro/runtime`), which returns `AuthMiddleware` and `ConnectionInfoMiddleware` as a single merged Layer — they read each other's state (the chain *records* the credential expiry that `ConnectionInfo` *reports*), so neither can be half-adopted. `authMiddlewareParity.test.ts` scans every framework source file and fails if `AuthMiddleware.of(` is constructed anywhere but that builder. `serveCommand` also stopped recording the credential expiry itself: it hands `serveApi` the whole `SubjectResolution` and the shared layer records it once, for both paths. **Two exports are gone with no replacement, because nothing read them.** `onBindConnectionSubject`'s doc claimed the dispatcher re-scoped subscriptions on rebind; it had zero subscribers in the entire framework, so nothing did. The behaviour is unchanged and now stated correctly: a rebind affects subsequent CALLS; a subscription opened under the previous credential runs until the client re-subscribes. `connectionSubjectsSnapshot` was a diagnostics surface with no reader. `unbindConnectionSubject` is `unbindConnection` (it clears the connection's credential *and* its recorded expiry). `authRoutesPlugin({ rebind })` takes the new function; `handleSwitchTenant` mints the session first and hands the rebinder that cookie, so the socket and the next HTTP request cannot end up authenticating as different tenants. Migration: `voltro update` prints the manual codemod. Pass the credential you were already about to `Set-Cookie` (`issueSession(...)` returns `{ value, setCookie }`), or a Bearer header for a token app. - **@voltro/runtime, @voltro/voltro** — **`crud.create` / `crud.update` refuse a `.serverOnly()` column in their INPUT (SEC-14).** `.serverOnly()` is the WIRE-exposure axis — the column never crosses the boundary. Redaction only ever enforced the outbound half (`effectiveRedact` strips it from every returned row), while the create path inserted the raw input, so a descriptor whose input schema happened to include a serverOnly column let a client SET a column it is not allowed to READ. That is mass assignment, and it is the same violation mirrored. A payload that sets one now fails with the new `ServerOnlyColumnWrite` naming the offending columns, and nothing is written. Refused rather than silently stripped: a stripped field makes an attack indistinguishable from a no-op and leaves an honest caller debugging a value that quietly did not land. A key present with the value `undefined` does not count as sent, so optional schema fields are unaffected. Migration: drop those columns from the descriptor's `input` schema. When the server legitimately needs to write one (a hashed key, an internal flag), do it from the handler with `ctx.store.insert` / `ctx.store.update` — those are unchanged; the refusal is on the generated crud path, which is the one fed straight from client input. **`voltro update` carries you across this** — codemod `0.34.0/02_keyed-writes-are-tenant-scoped`. - **@voltro/plugin-governance, @voltro/database, @voltro/cli** — **A GDPR erasure is only as complete as the list of tables it walks, and that list was hand-written.** `subjectScopes: [{ table, subjectField }]` is wrong the day after someone adds a table, and nothing checked it — which is the whole compliance claim, unverified. The framework already knows the answer: `relations()` says which table belongs to which, and `reference()` columns carry the same fact at the column level. ```ts governancePlugin({ deriveSubjectScopes: { subjectTable: 'users' } }) ``` The scope is now DERIVED by walking that graph outward, so a DSAR finds rows two and three hops away (`users → posts → comments`) that a flat `{ table, subjectField }` entry cannot even express — and a table added tomorrow is in the DSAR tomorrow. Explicit `subjectScopes` are still first-class and are UNIONED on top, never replaced: a subject id in a plain column, a polymorphic `(type, id)` pair or an id inside JSON can only be declared. **Only CHILD edges are followed** — a table holding a reference to the subject's row. Never a parent or lookup edge, and a `manyToMany` follows the JUNCTION only. Getting that backwards is not an over-broad export, it is an erasure that walks from one member into their organisation and deletes everybody else's rows. **`GovernanceService.subjectGraph()` and `GET /_voltro/inspect/plugins/governance/subject-graph` report what the derivation CANNOT see**, in the same payload as the paths — every table nothing links to the subject, everything cut by the depth ceiling, everything excluded. A reachable-table list on its own reads as a completeness claim, and "found no rows" is otherwise indistinguishable from "never looked". **`voltro privacy`** ships with it: `scope` derives and prints the graph plus its blind spots OFFLINE (schema only — it runs in CI and in a PR review), and `export` / `erase` run against the RUNNING app's admin-gated governance endpoint rather than opening their own connection, so the configured anonymize fields and the erasure log still apply. `erase` refuses without `--confirm`, without `--url`, and without an inspect credential. **Scale.** The walk no longer does `store.all(table)` per scope. Every read is `WHERE IN ()` on an indexed column, chunked at 500 keys, memoised per shared path prefix, capped at 50 000 rows per table — and a cap that is HIT is reported as `truncated` on the erasure-log entry (and exits non-zero from the CLI), because a short erasure presented as complete is the failure this exists to prevent. Erasure now runs DEEPEST-FIRST so a real foreign key neither refuses the delete nor cascades through rows the log never counted. **Crypto-shredding is deliberately NOT implemented, and must not be faked.** The shipped cipher is ONE app-wide passphrase-derived key (`runtime/fieldCipher.ts`), so there is nothing subject-shaped to destroy — deleting it would make every subject's `.encrypted()` columns unreadable, which is an outage, not an erasure. Per-subject shredding needs envelope encryption (a DEK per subject, wrapped by a KEK, with every existing ciphertext re-wrapped), which is a re-architecture of the cipher rather than a mode of `eraseSubject`. What makes its absence affordable: `.encrypted()` columns are decrypted on read, so `delete` removes the ciphertext and `anonymize` overwrites it — both erase the data rather than the key guarding it. **BREAKING** — `exportSubject` / `eraseSubject` take `ReadonlyArray` where they took `ReadonlyArray`. `codemod: none` because no user-authored code calls them: both are reached through `GovernanceService`, the `governance.*` rpc routes or the dashboard, all of which are unchanged. A direct caller converts with the exported `scopeToPath(scope, subjectTable)`. - **@voltro/cli** — **`voltro create-project` now creates the workspace root when there is none, and `voltro init` means what its name says.** The documented first run — `pnpx voltro create-project acme` then `pnpm install && pnpm dev` — failed at command two for anyone not already inside a prepared monorepo. `create-project` wrote only `apps//…`: no `pnpm-workspace.yaml`, no root `package.json`, no `.gitignore`, no `git init`. It then printed `pnpm install` (and, with a baseline, `pnpm db:up` / `pnpm dev:docker`) into a directory that had no manifest for any of them to live in. Five separate defects fed one broken first contact, and all five are fixed: - **No workspace root.** `create-project` (and the new `init`) write `pnpm-workspace.yaml` (`apps/*/*`, `packages/*`, `packages/*/*`), a root `package.json` with `dev`/`build`/`test`/`typecheck`, a `.gitignore` that covers `.env.local` (where `voltro dev` mints per-project secrets), and run `git init` unless something above is already a repo. Everything is additive: an existing workspace is left alone, and only root scripts you do not already define are filled in. - **`voltro init` was `create-project` under another name.** It is now the workspace-root command: it initialises the CURRENT directory, takes no arguments, scaffolds no apps, and is idempotent. `voltro init --api …` exits 2 and prints `voltro create-project --api …` instead. **Breaking** — see the codemod note. - **The root `dev` script named a tool nothing installed.** All four baselines wrote `turbo run dev` / `turbo run build` / … while no baseline shipped a `turbo.json` or a turbo devDependency, so `pnpm dev` failed even in a correctly prepared workspace. The scripts are plain pnpm now — `pnpm -r --parallel dev`, `pnpm -r build`, `pnpm -r test`, `pnpm -r typecheck` — identical in the scaffolder and in every baseline, so applying a baseline cannot change what `pnpm dev` means. `pnpm -r` selects by "has this script", so an Expo app or a serverless bundle opts out of `dev` by construction rather than by config. - **`pnpm install` still exited 1 — on a question about packages you never chose.** pnpm 11 does not warn about an undecided postinstall script, it fails the install: `ERR_PNPM_IGNORED_BUILDS`. A greenfield scaffold pulls exactly three, all transitive (`esbuild` via vite, `@parcel/watcher`, `msgpackr-extract` via `@effect/rpc`), so the first command after the scaffolder printed it came back red asking about `@parcel/watcher`. The scaffolded `pnpm-workspace.yaml` now ANSWERS all three, each with its reason on the line: `esbuild: true` (vite's compiler binary — the web app does not build without it), the two optional native accelerators `false` (both have pure-JS fallbacks, so a first install needs no C++ toolchain). pnpm 10 ignores the key and is unaffected. Anything new pnpm finds still stops and asks — this decides the framework's own tree, not yours. - **A baseline could drop all its scripts in silence.** `patchPackageJson` returned quietly when the root `package.json` was absent, so a compose baseline reported success having written none of its 18 scripts — including the ones the CLI printed as next steps. It refuses now, before writing or removing any file, and names `voltro init` as the fix. `findWorkspaceRoot` no longer falls back to the current directory when the walk up finds nothing; `add-app` and `voltro cloud project link` say so instead of operating on an invented root. - **@voltro/plugin-webhooks, @voltro/runtime, @voltro/voltro, @voltro/plugin-billing** — **An incoming webhook must declare how it authenticates its caller (SEC-17).** Incoming-webhook routes were mounted raw and signature checking was delegated entirely to whatever the descriptor happened to declare. A hand-written `*.webhook.tsx` with no `signature` and no `provider` shipped as an **unauthenticated public POST that runs application code** — no HMAC, no replay window, no warning. Two first-party plugins carry their own verification (atlassian, billing), which is exactly what made the gap invisible: every example was safe. `mountIncomingWebhook` now THROWS at mount — i.e. at boot, on both boot paths — for a descriptor with no effective signature scheme and no explicit `verification`. The new field takes `'signature'` (the default when a `signature` / `provider` is present), `'provider'` (your handler verifies with the provider's own SDK), or `'none'` (deliberately public because a gateway + IP allow-list owns the trust boundary, logged as a warning on every boot). Declaring `'signature'` with no scheme to verify against is the same open endpoint and lands on the same refusal. Fail-closed rather than a boot warning, for the same reason a missing session secret refuses to boot: a warning about an endpoint that already works is read once, and this one only matters in production, where nobody is reading the boot log. **Second half of the same defect, and the one that can bite a webhook you believed was verified:** a webhook that DECLARED a signature scheme but whose secret did not resolve set `signatureOk = 'skipped'` and ran the handler anyway. One missing env var silently converted a verified webhook into an open one. It now answers 503 naming `VOLTRO_WEBHOOK_SECRET_` — 5xx, not 401, because the fault is ours and most providers retry a 5xx. The framework mints no value for it: the sender holds the other half, so a generated secret would authenticate nobody. `@voltro/plugin-billing`'s webhook inherits this — a deployment with no `webhookSecret` now 503s instead of applying anonymous POSTs to subscription state. `startRpcServer` carries the transport half of the gate: it refuses to mount a `webhookRoutes` entry whose handler carries no verification declaration at all, which covers an embedder wiring routes by hand rather than through the mounter. `mountIncomingWebhook`'s return type is now `MountedIncomingWebhook` (the same callable, plus the stamped declaration). **`voltro doctor` reports it before a deploy does.** A new `incoming webhook verification` section counts the verified endpoints, NAMES every `verification: 'none'` one (a deliberately public URL belongs in a review, not only in a boot log), and fails non-zero on any that declares nothing — the same verdict the boot reaches, from the same resolver (`incomingWebhookVerification`, now exported), so a green doctor is the claim that the app starts. It is in `--json` as `webhookVerification` too: a finding that exists only in the human view cannot be acted on by CI. Migration: add one of `provider:` / `signature:` / `verification:` to every `defineIncomingWebhook`, and set `VOLTRO_WEBHOOK_SECRET_` for the signature-verified ones. The codemod prints the four options and the env-var naming rule; it does not rewrite, because choosing between "verify this" and "this is deliberately public" is precisely the decision that was not being made. - **@voltro/cli** — **The web process's postgres ISR cache and CDC invalidator understood `PG_*` only, and every template teaches `DB_URL` (PROD-5).** `start.ts` gated the postgres ISR cache on `SSR_CACHE === 'postgres' && process.env.PG_HOST`, and `isrCdcInvalidator.ts` gated its `LISTEN` client on `PG_HOST || PG_DATABASE`. The real resolver prefers `DB_URL` / `DB_PRIMARY_URL` and only then `DB_HOST ?? PG_HOST` — and `DB_URL` is what every `voltro-templates` app and the deployment docs configure. So an app configured the documented way, explicitly asking for `SSR_CACHE=postgres`, silently got the **per-process memory cache**, announced by `isr cache backend: memory (per-process)` — an `info` line that reads like the default rather than a refusal. And every route declaring `cacheInvalidatesOn` got **no live invalidation at all**, announced by `log.debug('skipped — no PG_* env vars set')`, which is invisible at the default level and reads as an unconfigured deployment rather than a misread one. Both now go through `resolvePgClientConfig()` / `databaseConfiguredInEnv()` in `connectionConfig.ts` — the same resolver every other connection uses, which also means `PG_SSL`, `DB_SCHEMA` and the acquire bounds arrive with them. **The fallbacks are LOUD now, and one of them is a refusal:** - `SSR_CACHE=postgres` with no database named anywhere **aborts the boot** on a deploy environment (`NODE_ENV=production` / `staging`), and warns loudly otherwise. Memory is not shared between instances and does not survive a restart; serving it under an `info` line is how two replicas came to disagree about a page with nothing to indicate it. Same reasoning as `plugin-search`'s memory-backend refusal. - The CDC invalidator **warns**, naming the routes, when pages declare `cacheInvalidatesOn` and no database is configured. "No page asked for this" stays at `debug` — a non-event. "A page asked for this and it is not happening" is the case that was also `debug`, and that was the defect. `connectionConfigResolver.test.ts` grew the rule that would have caught it: the discrete host/credential variables (`PG_HOST`, `DB_HOST`, `PG_USER`, …) are read in exactly ONE file. Its existing rules asked whether each builder honours `PG_SSL`, which both of these did — they called `sslFromEnv()` and then looked at the wrong database. **`voltro update` carries you across this** — codemod `0.34.0/17_isr-postgres-refuses-without-a-database`. - **@voltro/runtime, @voltro/voltro, @voltro/plugin-multitenancy** — **Keyed-by-primary-key writes are now confined to the caller's tenant (SEC-5).** `ctx.store.update(table, id, patch)`, `delete(table, id)`, `hardDelete(table, id)` and `patchJson(table, id, …)` on a `tenant()`-scoped table resolve the target row INSIDE `subject.tenantId` before writing. They previously addressed the row by primary key alone — every other path was already enforced (reads AND-merge `eq('tenantId', …)`, inserts auto-stamp and default-deny, `updateMany`/`deleteMany` go through `scopeManyWhere`), so a mutation that took a row id from request input was the one way left to write across tenants, silently and with nothing in the code to review. `assertOwnTenant` only ever compared a *claimed* `input.tenantId`, so a mutation with no tenantId in its input never reached it. Migration: the call now fails with the new `TenantRowNotFound` instead of returning `null` / `false`. A handler that read that return as "not found" needs to decide what a refusal should do — catch `_tag === 'TenantRowNotFound'` (or `Effect.catchTag`), and declare it in the mutation's `error:` union to surface it typed. The error is raised IDENTICALLY whether the row is missing or foreign and carries nothing that separates them: reporting forbidden-vs-not-found would make every keyed write a cross-tenant existence oracle. Unaffected: non-`tenant()` tables, subjects with no tenant (schedules, resumed workflows, `*.subscribe.ts` — they still span tenants by design), reads, inserts, `updateMany`/`deleteMany` and the fluent `update(t).where(…)` / `delete(t).where(…)` builders, which were already scoped and are NOT scoped a second time. `@voltro/runtime`'s `StoreError` union gains `TenantRowNotFound` (and `ServerOnlyColumnWrite`, below), so an exhaustive `switch` over it needs the new arms. **`voltro update` carries you across this** — codemod `0.34.0/02_keyed-writes-are-tenant-scoped`. - **@voltro/logger, @voltro/protocol** — **Log redaction is ON by default (SEC-10).** It was opt-in with an EMPTY default: `resolveRedactor` returned `undefined` unless an app passed `redactKeys`, so a handler that logged a request body or a header bag shipped `password`, `authorization` and `set-cookie` verbatim to stdout AND to every registered sink (the CLI buffer, logship, datadog). The justification on the old code — "a logger that faithfully echoes its input is the right default" — is wrong in one specific way: what is being faithfully echoed is whatever the CALLER put in the bag, and the commonest bag is a request. A default that is safe only for the users who already knew the option existed is not a default. Every logger surface (`createLogger`, `makeLogger`, `LoggerLayer`) now installs `makeDefaultRedactor()`: - `DEFAULT_REDACT_KEYS` — exact key matches, normalised (case-insensitive, `_` / `-` / spaces ignored, so `api_key` = `API-KEY` = `apiKey`): credentials, bearer/API tokens, `authorization` / `cookie` / `set-cookie` / `x-api-key`, session + second-factor values, and the payment/government identifiers (`creditCard`, `cvv`, `iban`, `ssn`, …) that must never reach a log index. - `DEFAULT_REDACT_KEY_PARTS` — substring matches for the compound names real code writes: `newPassword`, `oldPassword`, `stripeApiKey`, `userAccessToken`. - A value-SHAPE scan that masks a credential regardless of its key: `Bearer …`, `Basic …`, a JWT, `sk_`/`pk_`/`whsec_`-prefixed keys, GitHub / Slack / AWS key ids, a PEM private key. Deliberately NOT an entropy heuristic — a trace id, a content hash, a git sha and a base64 thumbnail are all long and high-entropy, and a redactor that eats the fields an incident is read through gets switched off wholesale. `redactKeys` now ADDS to that list instead of being the whole of it, and there is **no way to subtract**. The only reason to un-mask `password` is to read it while debugging, and the answer to that is to log a non-secret projection; a subtraction knob would also apply to every dependency logging under that key, which is a blast radius an app cannot assess. The `redact` transform still exists as the deliberate escape hatch and runs AFTER the built-in redactor, so it can mask more and structurally cannot unmask. `codemod: none`: no user-authored code changes. Existing `redactKeys` config keeps working (it just adds), and the only observable difference is that fields which used to print a secret now print `[redacted]`. If a log line you relied on went quiet, rename the field — `traceId`, `requestId`, `cookieName` are all untouched, and `@voltro/protocol`'s own session diagnostic was renamed from `cookie` to `cookieName` for exactly that reason. - **@voltro/testing, @voltro/plugin-mail** — **`ctx.email` / `MockEmail` are deleted; `invoke` provides plugin service layers instead (TEST-1).** The framework shipped a mail-assertion API with **zero producers**: `MockEmail` existed, `makeTestContext` created one and hung it on `ctx.email`, the shipped docs taught `ctx.email.sent` / `ctx.email.lastTo(...)` as THE way to assert mail — and the only callers of `MockEmail.send` in all eight repos were the testing package's own tests. Nothing routed a handler's send into it, and nothing could: mail is not a `ctx` field, it is an Effect **service** a handler resolves with `yield* MailService`, and `invoke` provided only the `EffectStore` layer and `SubjectService`. So a mail-sending handler under test did not go un-asserted — it could not RUN. It died with `Service not found`. Which makes every existing assertion against it one of two things, and this is why the codemod is `manual`: vacuous (`sent` was always empty, so `toHaveLength(0)` passed and meant nothing) or already failing. A transform could rewrite the expressions and every file would compile, having changed a green vacuous test into a green vacuous test under a new name. **The fix is the general one, not a mail special case.** `invoke` now provides every registered plugin's `services:` layer plus the app's own `app.config.ts` `layers:`, merged in the serve pipeline's order (user layers last, so an app layer overrides a plugin layer declaring the same Tag). So the assertion surface for mail is the mail plugin's own memory provider: ```ts const ctx = makeTestContext({ subject: user('u1'), plugins: [mailPlugin({ provider: 'memory', from: 'app@acme.com' })], }) await invoke(sendWelcome, sendWelcomeHandler, { to: 'ada@acme.com' }, ctx) expect(readMailBuffer()[0].to).toEqual(['ada@acme.com']) ``` That is strictly more than the mock could ever have been: the whole send path runs — the default `from`, the dev allowlist, suppression, per-send idempotency, the template render — so "the allowlist dropped this message" is now a testable outcome. A double living in `@voltro/testing` would have had to model a weaker message than `MailService` accepts (`SentEmail` had `to`/`template`/`props` and no `subject`, `html`, `cc`, `bcc` or attachments), and a test asserting against it asserts against the double. The plugin owns the message shape, so the plugin owns the assertion surface. `makeTestContext` gains `layers?:`, and `MakeTestContextOptions.plugins` now does two jobs (interceptors, as before, and services). A Tag nobody provided still fails with `Service not found` — deliberately: that is what the handler does at runtime, and stubbing it would be asserting against the stub. `Cache`, `Kv`, analytics, the outbound `HttpClient` and the aggregate registry stay unprovided for the same reason plus a structural one: the CLI builds them at boot from an app's config, and `@voltro/testing` does not depend on the CLI. `ProcedureExecutor` gains a fourth type parameter `R = never` (the services the handler resolves) — additive, existing three-argument uses are unchanged. Covered by `testing/src/invokeServiceLayers.test.ts` (the layer mechanism, both directions of the override, and the no-silent-stub refusal) and `plugin-mail/src/mailUnderTest.test.ts` (the end-to-end send, the allowlist refusal, and mail-survives-a-rolled-back-mutation). The mail test lives in the plugin because `@voltro/plugin-mail` carries react/react-dom for react-email, so devDepping it from `@voltro/testing` resolves a second copy of React into that package's tree and breaks every `client.test.tsx` case — the trap `testing/src/storeForTenant.test.ts` already documents. - **@voltro/sql-mysql, @voltro/sql-mssql** — **A mysql/mariadb or mssql connection that asks for TLS now gets TLS — or refuses to boot. It no longer connects in plaintext.** `DB_URL=mysql://…?ssl=true` used to connect **unencrypted, with no warning and no error**. `MysqlConnection` had no `ssl` field, `connectionFromConfig` read neither `ConnectionConfig.ssl` nor the URL query, and the layer passed the driver host/port/user/password/database and nothing else. The request was not rejected; it was dropped. mssql had the same hole with an extra twist: a hard-coded `trustServer: true` made the config LOOK TLS-aware while `@effect/sql-mssql` defaults `encrypt` to `false` (it overrides tedious' own `true`), so every mssql session was plaintext too. Both dialects now follow the posture postgres has had since F6: - `?sslmode=require` / `?ssl=true` / `?ssl=1` (mssql also `?encrypt=1`) → TLS, certificate not verified. mysql2 gets `{ rejectUnauthorized: false }` explicitly rather than `{}`, which would silently mean *verify* — a different, stricter mode than the flag names. mssql gets `encrypt: true` + `trustServer: true`. - `?sslmode=disable` / `?ssl=false` → plaintext, explicitly. - Anything else — `prefer`, `allow`, `verify-ca`, `verify-full`, `?ssl=yes`, a mysql2 CA-profile name — **throws at boot**. The cross-dialect `ConnectionConfig.ssl` is a boolean and cannot carry a verification mode, and answering a request for `verify-full` with something weaker is the same defect in a politer form. - `ConnectionConfig.ssl` wins over the URL query, in both directions. **Why the break is correct.** Three groups of users are affected and all three are better off. An app whose URL said `?ssl=true` was being lied to — it now gets what it asked for, or a boot failure if the server cannot provide it. An app that wrote `?sslmode=verify-full` was getting plaintext — the weakest possible answer to the strictest possible request — and now finds out. An app with no TLS in its URL is unaffected. A boot failure is loud, immediate and happens on a deploy; a plaintext connection to a database you believed was encrypted is none of those things. No user-authored SOURCE changes — the affected input is a connection URL / env var, and there is nothing in a repo for a transform to rewrite. That is the case FOR a `manual` codemod rather than against one: a transform cannot look at a value it cannot see, and the failure mode of not reading this is a container that stops booting on a deploy. `voltro update` prints the operator step — *check whether your `DB_URL` carries `?ssl=` / `?sslmode=` / `?encrypt=`, and whether your server actually accepts TLS* — with the two queries that answer it from the database rather than from the config (`SHOW STATUS LIKE 'Ssl_cipher'`, `sys.dm_exec_connections.encrypt_option`). Proven on the wire, not just in config: the live suites assert MySQL's `Ssl_cipher` is empty for a plaintext session and names a cipher under `ssl: true`, and SQL Server's `sys.dm_exec_connections.encrypt_option` reports `FALSE` / `TRUE` respectively. - **@voltro/cli** — **One place decides what environment a `voltro` process is in, and the migration commands stopped guessing (PROD-2).** `if (!process.env.NODE_ENV) process.env.NODE_ENV = 'production'` existed in exactly three files — `serveCommand.ts`, `start.ts`, `webDev.ts` — each with a comment saying an unset `NODE_ENV` in a serving container means production. Nothing else agreed, in three separate ways: - **The launcher decided first.** `bin/voltro.mjs` read `NODE_ENV` in the `serve` / `start` fast paths, which run BEFORE the command's own default. So a `NODE_ENV`-less production deploy with a missing or unloadable serve bundle skipped the "production requires a precompiled serve bundle" guard, fell through to the tsx path, and — in a `--prod --no-optional` image, which has no tsx — died as `Cannot find package 'tsx'`, naming a package the user never asked for instead of the real cause. - **`voltro db apply` / `voltro migrate` ran the DEV branch of every gate.** In a pre-deploy job in the same image with `NODE_ENV` unset, the "auto-apply on prod is not allowed, go through `db plan` + `db apply --plan`" refusal did not fire, `db rollback-file`'s prod refusal did not fire, and the plan ledger recorded `environment: 'dev'` for a production apply. - **The framework TABLE SET disagreed with the process that serves it.** `traceTableEnabled()` and `undoCaptureEnabled()` are "on unless production", so a `NODE_ENV`-less `voltro db apply` declared `_voltro_traces` + `_voltro_undo_log` and `voltro serve` did not. The declared set is what the schema FINGERPRINT hashes — so the apply recorded a fingerprint the serving container could not reproduce, and serve's boot gate refused with `prod-mismatch`, telling the operator to run `voltro db apply`. Which they had just run. The loop has no exit. `bin/nodeEnvironment.mjs` is the one decider (plain ESM, because the launcher runs before the tsx loader and cannot import TypeScript; `src/nodeEnvironment.ts` is its typed face). **An undeclared `NODE_ENV` resolves to `production` for `serve`, `start`, `db` and `migrate`, and to `development` for `dev`.** Every other command is left undeclared on purpose. The polarity is argued per gate rather than flipped once: - for a **refusal** (`db apply` auto-apply, `db rollback-file`), the cost of a false positive is one environment variable and the cost of a false negative is an un-reviewed DDL applied to a production database — so it fails closed; - for a **table-creation** decision, the safe direction is not "production", it is *the same answer the serving process will compute*. Serve resolves an undeclared environment to production, so every migration command must too, or the two declare different schemas; - `voltro dev` declares `development` so the ambiguity never reaches the boot auto-migrate at all — dev's table set becomes a stated fact rather than the absence of one. **What changes for you:** `voltro db apply` and `voltro migrate` on a machine with no `NODE_ENV` now refuse, with a message that names `NODE_ENV` as the reason. Set `NODE_ENV=development` for a local database (`voltro dev` itself is unaffected — it declares its own). Read-only `db` subcommands (`plan`, `status`, `drift`) are unaffected except that they now compute the same declared schema the deploy will. The `dev | staging | prod` ledger name is one reader now (`deployEnvironmentName`). It said "one reader" and there were five in `dbCommand.ts`, two of which mapped the same input differently — they agreed only because the prod refusal made the divergent branch unreachable. The launcher deliberately does NOT write `process.env.NODE_ENV`: it runs before `.env` / `.env.local` are loaded, and a value written there would silently outrank the app's own dotenv file. It reads. That also means a `NODE_ENV` set only in `.env` cannot influence the launcher's bundle guard — set it in the process environment for a non-production `voltro serve`. **`voltro update` carries you across this** — codemod `0.34.0/16_declare-node-env-for-migration-commands`. - **@voltro/runtime, @voltro/protocol, @voltro/voltro, @voltro/plugin-sso-saml, @voltro/plugin-storage, @voltro/plugin-billing, @voltro/plugin-scim** — **The origin guard covers EVERY state-changing surface, not `POST /rpc` and the WS upgrade.** SEC-6/SEC-7 landed the check against two path literals, which read as complete because `/rpc` is where mutations live. It is not the only place they live. A `publicApi:` annotation projects the SAME mutation to `POST /v1/`; `apiConfig.restRoutes` mounts hand-authored ones; `POST /v1/api-keys` mints credentials. All three reach the listener as plugin HTTP routes, and all three resolve their subject through the same auth chain — the built-in session-cookie strategy included. So the framework shipped a guarded `/rpc` and an UNGUARDED REST projection of the same writes: `evil.example` could POST a victim's `voltro:session` cookie at `/v1/orders` and the guarded twin next door would refuse the identical call. **The polarity is inverted.** Every request whose method can change state (anything but GET/HEAD/OPTIONS) is origin-checked, and a route that genuinely cannot be CSRF'd declares itself exempt. A list of guarded paths has to be extended every time a surface is added, and the one that gets forgotten is the one nobody remembered was reachable; forgetting to declare an exemption produces a 403 someone reports, while forgetting to add a guard produced nothing at all. The check still lives in `wrapHttpApp`, the single point `voltro dev` and `voltro serve` share, so neither boot path can have a different answer. **Cookie-auth versus bearer-auth is NOT distinguished per request, on purpose.** The check runs before routing and before the auth chain, so "would this request have been authenticated by a cookie" is not knowable there — and a route that accepts BOTH a bearer token and the cookie has to be guarded regardless. The distinction is made once, by declaration, where someone can reason about it: - `PluginHttpRoute.originGuard: 'exempt'` — the route's authority is something a browser will not attach cross-site. Four first-party routes qualify and now say so: `@voltro/plugin-sso-saml`'s `/saml` (the IdP delivers a signed assertion by making the browser form-POST it — a legitimately cross-site POST), `@voltro/plugin-storage`'s `/_voltro/storage/upload` and `…/upload/resumable` (a signed upload ticket, with the plugin's own CORS allowlist, because a cross-origin upload is the point), `@voltro/plugin-billing`'s `/billing/webhook` (HMAC-verified) and `@voltro/plugin-scim`'s `/scim/v2` (bearer-only, refuses to mount untokened). - The inspect surface and incoming `*.webhook.tsx` mounts are exempt STRUCTURALLY: inspect is token-gated and designed to be read cross-origin by both dashboards, and a webhook route cannot boot without declaring how it verifies its caller. A path shared by several routes is exempt only when EVERY route on it declares it — the pre-routing check cannot know which member will own the method. **SSR still works, and it is asserted on the REST surface too.** The `no-browser-origin` terminal case is unchanged: a request with neither `Origin` nor `Sec-Fetch-Site` did not come from a browsing context. That is the in-process SSR loader, every mobile SDK, curl, and every service-to-service caller — including every webhook sender, which is why the blast radius of guarding by default is close to nil. Only a BROWSER sends `Origin`. Migration: the same one SEC-6 already asks for, now reaching further. **A split web/api deployment must declare `security: { allowedOrigins: [...] }`** — if you already did so for `/rpc`, your REST routes are covered by the same list and there is nothing to do. A cross-origin browser client calling a `publicApi:` route with a bearer token needs its origin in that list. `originGuard: 'off'` still disables the whole check. **`voltro update` carries you across this** — codemod `0.34.0/06_origin-guard-and-trusted-proxies`. - **@voltro/runtime, @voltro/voltro, @voltro/cli** — **Cross-site protection on `POST /rpc` and the WebSocket upgrade (SEC-6, SEC-7).** Neither surface had any check. `@voltro/plugin-auth` ships a real signed double-submit CSRF token, but it is wired only onto plugin-auth's OWN routes — so framework-wide CSRF protection for the general mutation surface rested entirely on the `SameSite=Lax` session-cookie default. Lax still permits top-level navigation POST, is caller-overridable, and does nothing at all for a bearer/JWT flow. Any page on the internet could open a live socket to a logged-in user's app, or drive a mutation from a form. Both are now one decision, made in `wrapHttpApp` — the single point `voltro dev` and `voltro serve` share, so the two boot paths cannot diverge on it. A browser request is accepted when its `Origin` matches the `Host` it was addressed to, or appears in the configured allowlist; `Origin: null` (sandboxed iframe, `data:` document) is refused rather than treated as absent; and when `Origin` is missing but `Sec-Fetch-Site` says `cross-site`, that alone refuses. Everything else on the listener is deliberately unguarded: an incoming webhook is called by a third party and is authenticated by signature, and the inspect surface carries its own host + token guard. **The exemption that keeps SSR working, stated because it is load-bearing:** a request carrying NEITHER `Origin` NOR `Sec-Fetch-Site` is not from a browsing context and is allowed (`reason: 'no-browser-origin'`). That is the in-process SSR loader — `voltro dev` / `voltro start` render pages server-side and their loaders `fetch('/rpc')` from node, which attaches no origin and no fetch metadata — plus every mobile SDK, curl and service-to-service caller. A CSRF attack needs the victim's ambient credentials, which only a browser attaches, and a browser cannot be made to omit `Origin` on a cross-origin POST or a WS handshake. An attacker's own server can POST without one, but it carries no session to ride: that is simply an unauthenticated request, and auth + guards still apply. **Both sides on loopback is accepted**, and that rule is measured rather than convenient: `voltro dev` proxies the api through the web dev server with `changeOrigin: true` (`webDev.ts`), so the api receives `Host: localhost:4000` while the browser correctly reports `Origin: http://localhost:5190`. Compared strictly those are different origins and every dev session would lose its websocket — and a security control that breaks the default dev loop gets turned off rather than configured around. It is narrow in the direction that matters: BOTH sides must be loopback, so a production api on a public host still refuses `Origin: http://localhost:…`, and `localhost.evil.example` is not loopback. **One dev case is refused and it is a decision, not an oversight:** reaching a dev server from a phone on the same wifi makes the page `http://192.168.1.5:5190`, which is not loopback — add that origin to `allowedOrigins` while you test. Widening the carve-out to "both sides are private addresses" would read as the same argument one step out and is not: the loopback case says the attacker already runs code on this machine, a LAN case says some other host on the network does, and that shape is also a self-hosted internal deployment, where it would weaken production. Comparison is otherwise by AUTHORITY (host + port), not scheme. Behind a TLS-terminating ingress the app sees plain http while the browser reports `https://…`, and there is no unforgeable way to learn the external scheme — requiring a scheme match would reject every correctly-configured production deployment, which is how a security control ends up switched off. Both knobs are `app.config.ts` fields — `security: { originGuard, allowedOrigins }` — read by `voltro dev` and `voltro serve` through one shared resolver, with `VOLTRO_ORIGIN_GUARD` / `VOLTRO_ALLOWED_ORIGINS` as env OVERRIDES for a deployment you cannot rebuild. An embedder passes the same object as `RpcServerOptions.security`. Migration: **a split web/api deployment must declare its origins** or every mutation and socket from that page 403s — `security: { allowedOrigins: ['https://app.example.com'] }`. Same-origin apps need no change. `originGuard: 'off'` disables it; an unrecognised value falls back to ENFORCING, never to off. **`voltro update` carries you across this** — codemod `0.34.0/06_origin-guard-and-trusted-proxies`. - **@voltro/runtime, @voltro/protocol, @voltro/voltro, @voltro/plugin-auth, @voltro/plugin-auth-social** — **A plugin HTTP route gets the RESOLVED client address — and the auth routes stop writing the raw header into your audit trail.** SEC-8 inverted the `x-forwarded-for` default for the rate limiter, the geo-block and the pre-routing interceptor, and stopped there. Three first-party routes that record WHO signed in were left reading `req.headers['x-forwarded-for']` verbatim: `@voltro/plugin-auth`'s `/auth/sign-in` and `/auth/mfa/verify`, and `@voltro/plugin-auth-social`'s OAuth callback. So `sessions.ipAddress` — the one column a breach investigation leans on — recorded whatever the caller typed, in a framework that had just built the machinery to prevent exactly that. `PluginHttpRouteRequest` carries `remoteAddr` now: the listener resolves it once per request through `resolveClientAddress` and the app's `security.trustedProxies`, so a plugin route reads the same address the limiter acts on. With no trusted proxy declared the forwarded chain is ignored entirely and the socket peer wins; with one declared, the immediate peer must itself be trusted and the chain is walked right-to-left past every declared hop. **If you wrote a plugin HTTP route that reads `headers['x-forwarded-for']`, read `req.remoteAddr` instead.** The header is still there — it is a request header and we do not strip it — but it is not evidence of anything until you say whose proxy you believe. Migration: **if you run behind a load balancer and rely on `sessions.ipAddress`, set `security: { trustedProxies: ['private'] }`** (or the CIDRs / hop count your ingress needs). Without it the column records your proxy's address rather than the caller's — the same configuration SEC-8 already asks for, now with one more consumer. Apps with no proxy need no change; the column already held the socket peer's address in everything but name. **`voltro update` carries you across this** — codemod `0.34.0/06_origin-guard-and-trusted-proxies`. - **@voltro/plugin-presence, @voltro/ui** — Presence has no table, and its roster now pushes only when it actually moves. **`_voltro_presence` is deleted**, along with the read model that outlived the data: `presenceTable`, `PresenceStore`, `PresenceEntry`, `memoryPresenceStore`, `isOnline`, `filterOnline`, `staleKeys`. Counted across every repo here before removing — each reference was the plugin's own barrel or that module's own test file; nothing called `filterOnline`, including the file that imported it. The table was declared and never written to, purely to own a name; `presence.list` now declares a `reactivityChannel('presence')` as its `source:` instead, and the plugin drops the `store:write` permission it only ever held to authorise a table. **An existing `_voltro_presence` is NOT dropped for you** — the differ never plans a drop for a framework table no app declares — so remove the empty table by hand when convenient. **A roster member is `{ key, meta }` — `lastSeen` is gone from the wire.** It was the OWNING replica's clock ("compared only against other timestamps from THAT owner"), so rendering it as a time was already wrong by the skew between two pods on any multi-replica deployment, with nothing to say so. Nothing in `@voltro/ui` rendered it. **Two defects, and they were one.** The heartbeat pushed unconditionally, and a REMOTE change pushed nothing at all: a member who joined on replica A reached replica B's screens only because one of B's own clients heartbeated within 15 seconds and pushed regardless. So the waste was hiding the gap — making the heartbeat conditional alone would have turned a bounded 15-second delay into a permanent one. `tracker.track()`/`.untrack()` now return `{ delta, changed }`, `.apply()` returns whether the roster moved, and `attachPresenceBus` takes an `onRosterChanged` fired on a peer's delta and a peer's death. The asymmetry is deliberate and load-bearing: a heartbeat is ALWAYS broadcast (a peer's sweep drops a member it has not heard from) and pushed only on a change. Measured on the fixed code (`packages/plugin-presence/scripts/rosterFanoutBody.ts`): 2.7 µs per subscriber per publish, so an unconditional push cost a steady room of N clients N² × that per heartbeat interval — ~107 ms of CPU per 15 s at N=200, and a per-node ceiling around 750 subscribers that nothing in the app could influence. That term is now gone; what remains is linear in real roster churn. **`voltro update` carries you across this** — codemod `0.34.0/25_presence-has-no-table`. - **@voltro/protocol, @voltro/cli, @voltro/voltro** — **A wire-exposed procedure must declare an access decision, and the default is now DENY (SEC-1).** `guards:` defaulted to `undefined` and the scope evaluator returns "allowed" for an empty guard list, so a discovered `*.query.ts` / `*.mutation.ts` / `*.action.ts` / `*.stream.ts` with no `guards:` was callable by **any authenticated session** — default-ALLOW at the procedure level. The framework's only structural answer was `voltro doctor`'s authz scan, which is a report a human runs, not a gate a deploy passes. Two halves shipped together, because either alone is worse than neither: - **The marker.** `defineQuery` & co. take `openAccess: ''` — a declared decision that this procedure needs no authorization check, with the reason in the source. Without it, the only way to satisfy a default-deny gate is to add a guard, so every genuinely open endpoint (health check, public price list, signup precheck) grows a scope every caller already holds. That rubber stamp reads as protection and enforces nothing, which is a worse state than the hole it replaces. `openAccess` is mutually exclusive with `guards:`, is refused empty, and is refused on an `internal: true` procedure (no wire surface to decide about). It normalises INTO the descriptor's `guards` array, so every enforcement path — which is handed that array and nothing else — sees the decision; it does not widen the wire error union, since an open procedure can never produce a `ScopeError`. - **The gate.** `assertProcedureAccessDecisions` (`cli/src/procedureAccessGate.ts`) refuses the boot, naming EVERY offending procedure with its file — never a head and a count, because the fix is one pass over the whole list. ONE function, called by `voltro dev`, by `voltro serve` (in `serveApi`, before anything is bound) and by `voltro doctor` (non-zero exit, `accessDecisions` in `--json`), so a green preflight means the app boots. **`security.defaultDeny` in `app.config.ts` defaults to `true`.** The audit that produced this proposed default-false-for-now; the argument against is in the same document — the default nobody turns on IS the shipped posture, and the shipped posture is what a security review reads. Pre-1.0 the cost of a break is not a factor, and satisfying the gate is a one-line, honest edit per procedure. An app that wants the old behaviour declares it once, where a reviewer can see it: `security: { defaultDeny: false }`. There is deliberately **no env override** — the only direction anyone reaches for is off, and an env var is how that becomes permanent in one CI job with no diff to review. Enforcement is at BOOT and covers the app's OWN discovered procedures, not the dispatch spine and not plugin routes. That is a measurement, not an oversight: the first-party plugins declare 47 procedures through the same definers with zero `guards:`, and nothing in the dispatch spine can tell an app's procedure from a plugin's — a process-global default-deny there would refuse every plugin route in every app, and a security default whose first act is to break the framework's own surface gets switched off. `@voltro/protocol`'s `checkGuards` / `checkGuardsEffect` gain an explicit `GuardCheckOptions` (`defaultDeny`, `procedure`) for a caller that already knows it holds an app procedure; the plugin surface declaring its own decisions is the follow-up that lets it move into the spine. Migration: run `voltro doctor`, which lists every undecided procedure with its tag and file, and give each one `guards:` or `openAccess:`. The codemod is `manual` on purpose — a transform could stamp `openAccess` onto every guardless descriptor and every app would boot, having declared its whole surface open in one commit nobody reads, with a reason the tool invented. That is the failure the marker exists to prevent, performed at scale. - **@voltro/mcp** — `routeHttp` (@voltro/mcp) returns a `Promise`. Two MCP methods now reach the app — `tools/list` folds in the app's agent tools and `tools/call` executes one — so the pure router has to await. Everything else still resolves without touching anything, and the function is still pure in the sense that matters: it binds no socket, and a test supplies a `live` double. Migration: `await routeHttp(...)`, and make the enclosing function async if it is not. Nothing to do if you use the shipped `serveHttp` transport — it already awaits. **`voltro update` carries you across this** — codemod `0.34.0/26_route-http-is-async`. - **@voltro/plugin-sso-saml, @voltro/cli** — **SAML assertion replay was a live gap on the default configuration, and the defence was already built, tested against both backends, and switched off.** `replayProtection` defaulted to absent, which left node-saml at `validateInResponseTo: 'never'` — a captured `SAMLResponse` could be POSTed to the ACS again for as long as its assertion was valid. The one-time request-id cache, its in-process and DataStore backends, the `_voltro_saml_replay` table and the `store:write` declaration all existed. The default is now `{ store: true }`. **Store-backed, not the in-process cache, and that choice is the interesting one.** `replayProtection: true` is not a milder version of the same protection — it is a different failure. Under more than one replica a login lands on process A and its ACS on process B, B has never seen the request id, and NOBODY can log in. Defaulting to it would have traded a replay window for an outage, so the default is the mode that is correct at every replica count. `true` stays available for a single process that would rather not have the table. **What it costs, stated plainly because it is not optional: IdP-initiated SSO stops working.** `validateInResponseTo: 'always'` refuses a response with no `InResponseTo`, and that is exactly the Okta / Azure dashboard app tile. There is no configuration that keeps both, and the reason is structural rather than a missing feature — the protection IS the requirement that the response answer a request this SP issued, and an unsolicited response answers none. node-saml's `'ifPresent'` looks like the compromise and is not one: an attacker replaying a captured response deletes the attribute and the check declines to run. So `replayProtection: false` stays reachable as the deliberate opt-out for the app-tile flow, boot now warns when it is set (naming both what it bought and what it cost), and the A/B control asserting that a capture IS replayable at `false` is kept — it is what an operator choosing that is actually buying. **Two things fixed on the way, both consequences of the default moving:** - The two defaults interact, so it is asserted rather than assumed: with `wantAuthnResponseSigned` now `false` the response-level `InResponseTo` is attacker-editable, and the replay check does not rest on it — node-saml cross-checks it against `SubjectConfirmationData/@InResponseTo` inside the SIGNED assertion and refuses a mismatch. - `ensureSaml` wrapped its whole construction in one `catch` that reported everything as `SAML SSO requires the optional dependency @node-saml/node-saml`. Store-backed replay is the default now, which makes "the DataStore is not bound yet" reachable — and that message would have sent an operator to install a package they already have. Only the dynamic import reports the install hint; a construction failure reports itself, carries its cause, and is NOT sticky (unlike a missing dependency it can resolve on its own, and pinning it would let one early request take the plugin down for the life of the process). **`voltro update` carries you across this** — codemod `0.34.0/23_saml-signature-and-replay-defaults`. - **@voltro/plugin-sso-saml, @voltro/cli** — **An Okta deployment on the default application could not log in, and there was no option to say otherwise.** `buildSamlOptions` set `wantAssertionsSigned: true` and passed nothing for `wantAuthnResponseSigned` — so node-saml's own default of `true` applied and the ACS required BOTH the response envelope and the assertion to be signed. Okta's default application signs the assertion and leaves the envelope unsigned; so does Azure AD's. Those responses were refused with `401 SAML assertion rejected: Invalid document signature`, and because the option was never surfaced there was nothing an operator could set. **The default is now `false`, and the option exists.** The reasoning, since the direction is a relaxation: - The floor did not move. The ASSERTION signature is still required unconditionally and is still not configurable. It is the one that matters: node-saml reads only signature-covered XML (`getVerifiedXml`), and the assertion is what carries the NameID, the attributes, the audience restriction, the validity window and the `SubjectConfirmationData`. - What an envelope signature adds is coverage of the response-level `Status`, `Destination` and `InResponseTo` — real, and smaller than the name suggests. - A refusal an operator cannot configure their way out of is not a stronger posture. It is a wall people climb by forking the plugin or dropping it, and both of those are worse than the checkbox they could not tick. - `wantAuthnResponseSigned: true` is one line for any deployment whose IdP does sign responses, and the docs now say so in both languages. **One edge, measured and pinned rather than glossed:** at the default, an envelope signature that does NOT verify is treated the same as no envelope signature — discarded, with the assertion signature deciding. That is not an auth bypass, and the test says why: an attacker holding a validly signed assertion would simply send no envelope signature, and an attacker-signed *assertion* is refused at every setting. What is genuinely lost is a diagnostic — an IdP misconfigured to sign responses with the wrong key stops being visible — and `wantAuthnResponseSigned: true` gets it back. `samlSignature.test.ts` drives all of this through real RSA-signed fixtures and the real node-saml: the Okta shape is accepted, the same bytes are refused with `wantAuthnResponseSigned: true`, and a fully signed response is still accepted under it (so the option is not a blanket refusal). The boot log reports the two signature requirements separately, because they are separate. **`voltro update` carries you across this** — codemod `0.34.0/23_saml-signature-and-replay-defaults`. - **@voltro/plugin-search** — **`plugin-search` REFUSES to boot in production on the in-memory backend (PLUG-2).** The zero-config backend is an in-process `Map`, and it was wrong in production in two independent ways, both silent: - **per-process** — N replicas hold N divergent indexes, so which results you get depends on which replica served the request, including "no hits" for a document that demonstrably exists; - **non-durable** — the index lives in the heap, so every restart and every deploy starts EMPTY and nothing re-seeds it (`backfillIndex` is a function an app calls, not a boot step). This half is why the refusal is not conditional on detecting a cluster: one replica does not make memory correct, it only removes one of the two ways it is wrong. Migration — pick the one that matches your deployment: ```ts // app.config.ts — a durable engine (the normal answer) searchPlugin({ backend: { engine: 'meilisearch', url: process.env.MEILI_URL!, apiKey: … }, indexes }) // …or assert the ONLY shape in which memory is correct outside dev: // exactly one process, re-seeding every index at startup via backfillIndex(). searchPlugin({ singleProcessMemoryIndex: true, indexes }) ``` `singleProcessMemoryIndex` is a claim, not a mute switch: when the instance membership registry reports a peer replica, the plugin logs that the claim has been contradicted — in any environment, because that is an observation rather than a guess about `NODE_ENV`. The same observation-based warning covers the box where several replicas run with `NODE_ENV` unset, which the production check alone would miss. `voltro dev` is untouched and completely silent: memory is exactly right there, and a warning that fires on every dev boot is a warning nobody reads. Also: `memoryBackend()` now returns a tagged `MemoryBackend`, so `backend: memoryBackend()` is recognised as the same deployment as `backend: 'memory'` (it used to read as an opaque custom backend and would have walked straight past the refusal), and `GET /_voltro/inspect/plugins/search/ indexes` reports `durable` + `singleProcessMemoryIndex` alongside the backend name. **Not shipped here: a postgres/SQL-backed durable floor.** It is the better product and it stays open. It needs seams this package does not have — the plugin reaches its store through descriptor `query`/`insertIgnore`/`update`/ `deleteMany` only, which cannot express doc-attribute predicates over a JSON column, facet `GROUP BY`s, or the per-dialect highlight functions (`ts_headline` / `snippet()` / …) that `SearchQuery` promises. Degrading those silently would replace one lie with another. **`voltro update` carries you across this** — codemod `0.34.0/14_search-memory-backend-refuses-production`. - **@voltro/plugin-search** — `plugin-search` no longer loses a row's index update to a single engine failure, and its `/indexes` counters no longer multiply by the replica count. **The loss.** The post-commit tap was one bare `Effect.tryPromise(applyChange)`. One engine 500 — the DB commit having already happened — left that row missing from (or stale in) the index **forever**, unless an operator noticed a `log.warn` and hit the manual `/reindex` backfill. Every vendor adapter had been setting `SearchBackendError.transient` for exactly this decision, and nothing read it. **Stage 1 — retry, driven by that flag.** The tap now retries a `transient` failure with capped exponential backoff inside its own Effect (which is where the tap contract puts durability). A permanent failure — an unsupported query shape, a `map(row)` that throws on one row — is NOT retried: repeating it cannot succeed. New tunables under `searchPlugin({ sync })`, all with defaults: `retries` (5), `retryBaseDelayMs` (200), `retryMaxDelayMs` (10 000), `resyncIntervalMs` (60 000, `0` disables the sweep), `resyncBatchSize` (200). **Stage 2 — a change that outlives the retry is written down, not logged.** It goes into the new `_voltro_search_drift` ledger, one row per `(index, sourceRow)` under a UNIQUE pair, so N replicas failing on one change collapse to ONE repair unit. A cluster-coordinated sweep (`search.resync`) repairs entries by **re-reading the row from the database and re-deriving the doc** — never by replaying the stored event — so a row updated three times during an outage converges in one pass, a row deleted since converges to a removal, and repair is order-free and idempotent. `POST /_voltro/inspect/plugins/search/resync` runs a pass on demand; `GET …/drift` lists the entries. Unlike a leader-gated *enqueue*, a missed sweep tick cannot lose anything: the ledger row is written by whichever replica saw the failure and stays until somebody repairs it. The one remaining loss case — the engine failed AND the ledger write failed — now fails the tap loudly instead of reporting success. **Drift is observable without reading logs.** `GET …/indexes` reports per index `dropped`, `pendingDrift`, `lastDriftAt`, `drifted`, a fleet-wide `pendingDrift` total, and the retry policy actually in force. The framework tables (`_voltro_search_drift`, plus the new `dropped` / `scope` columns on `_voltro_search_stats`) are reconciled by the declarative differ on `voltro db apply` and on a `voltro dev` boot, on every dialect — no codemod. **The counters (REL-22).** `stats.bump` ran on every replica per change, so the panel whose stated purpose is being truthful multi-instance inflated ~N×. Index WRITES and stats COUNTS are now treated differently on purpose: the write still runs on every replica (`upsert`/`remove` are idempotent, so a duplicate costs write amplification while suppressing it costs a lost update whenever the one elected replica dies — and electing one would import a leadership gap), while the count is corrected without any leader at all. Under `changeScope: 'fleet'` every replica counts and the read takes the MAX (each replica's row is already a fleet-wide count); under `'local'` only the replica that made the write counts (`origin !== 'injected'`) and the read SUMs. Note an `origin` guard alone cannot carry the fleet case: under postgres CDC the NOTIFY echo is the sole delivery, so the writer's own event comes back stamped `injected` too and such a guard would count zero. **Breaking, and why `codemod: none`.** `StatsStore.bump` takes a third `scope` argument and a `'dropped'` kind; `IndexStats` carries `dropped`; `StatsStore.recordReindex` no longer takes a scope. These exports exist for the plugin's own internals and its tests — there is no option through which an app supplies a stats store, and no documented use of them — so no user-authored code is rewritten. Nothing in `searchPlugin({ … })` changes for an existing app: the new `sync` block is optional and every value defaults. - **@voltro/plugin-search** — `search.query` no longer trusts the caller's strings. Three ways a wire caller could reach past the tenant filter are closed as ONE change, because they were one defect: the action's input carries strings that become the search engine's CONTROL PLANE, and a Schema cannot say "this string is safe to splice into a query language" — so the server decides it now. **1. `engineParams` was spread LAST into the engine params object** (all three vendor adapters), so `run('posts', { engineParams: { filter_by: '' } })` replaced the `eq(tenantField, tenantId)` clause the plugin injects — a cross-tenant read from the browser. It is an **allowlist** now, per engine: paging, ordering, typo tolerance and highlight shaping reach the engine; everything that could select a different document set (`filter_by`, `filter`, `facetFilters`, `query_by`, `restrictSearchableAttributes`, `preset`, `pinned_hits`, `enableRules`, …) is dropped and logged with the key name. Merging it *first* would have been the obvious fix and is not one — it stops the overwrite and leaves every other filter-by-another-name intact. An app that genuinely needs one more key opts in server-side: `searchPlugin({ allowedEngineParams: ['query_by'] })`. Document-selecting keys stay refused even then. **2. An unknown index name queried with NO tenant filter.** A miss in the registry yielded `tenantField === undefined`, so the filters passed through unchanged and the query ran unscoped against that collection — on a shared Typesense / Meili / Algolia instance, every collection outside `searchPlugin({ indexes })` was readable by any authenticated caller. It fails with a typed **`SearchIndexNotFound`** now, before the backend is called. **3. `filters[].field` was interpolated raw into each engine's filter DSL.** On Typesense — one flat `filter_by` string supporting `||` — a crafted field name re-groups the boolean tree around the tenant clause appended after it. Caller field names (in `filters[].field`, `facets[]` and `highlight.fields[]`) must now be plain field paths (`^[A-Za-z_][A-Za-z0-9_.]*$`), or be listed in the new optional `IndexSpec.queryableFields` allowlist; otherwise the call fails with a typed **`SearchFieldRejected`**. Algolia's filter *values* are escaped too (a value of `-open` used to invert `status:open` into "not open"), and its range operands are coerced to numbers instead of interpolated. Migration — **`codemod: none`, and here is why no user-authored code needs rewriting**: nothing in the new refusals is reachable from code a codemod could find. `queryableFields` and `allowedEngineParams` are additive options. What changes is what the SERVER answers at runtime, in three cases that were all bugs: querying an index you never declared, naming a field that is not a field, and passing an `engineParams` key that overrode a filter. If your app depended on one of them, the fix is a declaration, not an edit to a call site — declare the index in `searchPlugin({ indexes })`, or add the key to `allowedEngineParams`. `search.query` also carries a wire error union now (`SearchIndexNotFound | SearchFieldRejected`), which existing callers decode as a rejected promise exactly as they already do for any other typed error. The vendor backend factories take an optional second argument (`typesenseBackend(cfg, hooks)`) carrying the app's allowlist widening and the warn sink; the plugin wires it from `app.config.ts`, so a hand-constructed backend keeps working unchanged with the defaults. - **@voltro/runtime, @voltro/voltro** — **Security response headers ship by default (SEC-9).** The framework sent exactly one, and only on served storage blobs (`X-Content-Type-Options: nosniff`, `@voltro/plugin-storage`). No HSTS, no CSP, no `X-Frame-Options`, no `Referrer-Policy` anywhere on the general serve path — while `plans/product/08-security-and-compliance.md` claimed all four as day-one defaults. Every response from the api listener now carries: content-security-policy: default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none' x-frame-options: DENY referrer-policy: no-referrer x-content-type-options: nosniff strict-transport-security: max-age=15552000; includeSubDomains (https only) **Why `default-src 'none'` is safe here, and what the exception is.** `startRpcServer` is the API surface: `POST /rpc`, the `/ws` upgrade, the inspect JSON + SSE routes, incoming webhooks and plugin HTTP routes. It does NOT serve the web app's HTML — that is a different listener — so the strict policy never meets the web client's inline styles or its module graph. The one thing on this listener that IS a document is `@voltro/plugin-openapi`'s `/docs` page (CDN viewer with SRI + two inline scripts), which `default-src 'none'` would blank. So a `text/html` response gets a relaxed policy instead — `frame-ancestors 'none'; base-uri 'none'; object-src 'none'`, which closes clickjacking, base-tag injection and plugin embedding without constraining the page — and `mode: 'strict'` (opt-in) applies the API policy to HTML too, with that consequence documented rather than discovered. HSTS is emitted only over https (a TLS socket, or `x-forwarded-proto: https` from a trusted proxy — see the `x-forwarded-for` entry), and never carries `preload`: preload is effectively irreversible for a domain, so it must be a deployment decision, not a framework default. `Cross-Origin-Opener-Policy` and `Cross-Origin-Resource-Policy` are deliberately NOT defaulted — guessing either breaks a legitimate cross-origin dashboard — and are available through `extra`. A route that sets a header itself always wins; the framework only fills gaps. That is what keeps plugin-storage's `nosniff` + `content-disposition` pairing and the inspect routes' CORS bag intact. Configured in `app.config.ts` as `security: { headers: { mode, csp, cspHtml, hsts, extra, … } }` — one field, read by both boot paths — with the env overrides `VOLTRO_SECURITY_HEADERS` (`off|default|strict`), `VOLTRO_CSP`, `VOLTRO_CSP_HTML`, `VOLTRO_HSTS` for a deployment you cannot rebuild; each accepts `off` to drop just that one. An embedder passes the same object as `RpcServerOptions.security.headers`. Migration: if you serve HTML of your own through a plugin HTTP route on the api listener and it relies on framing or a `` tag, set `cspHtml` for it or send your own `content-security-policy` from the route. **`voltro update` carries you across this** — codemod `0.34.0/06_origin-guard-and-trusted-proxies`. - **@voltro/cli** — **`voltro serve` refuses to boot with pending `*.migration.ts`, instead of saying nothing (PROD-7).** Serve's schema guard is a DECLARATIVE fingerprint diff: it compares the declared schema against the last applied plan and refuses on a mismatch. A file-based migration exists precisely for the changes a state diff cannot infer — a data move, a backfill, a cross-table rewrite — and the commonest of those move **no fingerprint at all**. So the guard passed and production ran un-migrated with nothing said. `voltro dev` applies pending migrations at boot; `voltro db migrate` and `voltro db files` apply them; `voltro serve` did neither and did not mention them. That is exactly the gap `bootLifecycle.ts` closed for boot seeds — not doing it was the right call, and the difference being SILENT was the defect — and the reasoning had not been carried across. **Serve still does not APPLY them, and that stays deliberate:** a rolling deploy starts N replicas, each would try, and the migration lock turns that into N-1 processes blocked on boot. It refuses instead, under the same conditions and with the same bypass as the fingerprint check it sits beside — a real deploy environment (`production` / `staging`), a SQL store, and `VOLTRO_AUTO_MIGRATE=0` to opt out of every boot schema check. The cause is identical in both cases: the pre-deploy migrate step did not run. The refusal names the pending ids and the two commands that run them. A local `voltro serve` is untouched: `voltro dev` applies migrations there, so a preview serve has nothing to report. **`voltro update` carries you across this** — codemod `0.34.0/18_serve-refuses-pending-file-migrations`. - **@voltro/protocol, @voltro/plugin-auth, @voltro/cli** — **A session cookie carries IDENTITY; authority is resolved per request (REL-5).** The cookie embedded the whole `Subject`, `scopes` included, signed at login. Verification was an HMAC check plus `exp` and nothing else — nothing re-resolved authority from anywhere — the default lifetime is 7 days, and the sliding-window renewal re-signed the **old payload** while sliding the revocation row forward. So a user whose role was narrowed kept the old authority in a cryptographically perfect cookie, for a week, and indefinitely as long as they stayed active. Full-session revocation worked; revoking one permission did not take effect at all. The escape hatch did not escape. `resolveScopes` ran on every request and could only UNION onto the cookie's scopes — "a resolver cannot silently remove a scope either" — so even an app that wired it could not narrow. There was no supported way to revoke a single permission short of killing the whole session, which undercut the mid-stream re-authorization machinery the subscription path already had. Three changes, and none of them works alone: - **The payload cannot hold authority.** `SubjectIdentity` (`@voltro/protocol`) is the `Subject` union with `scopes` omitted at the SCHEMA level, and it is what the payload's `subject` field is typed as. `signSession` **throws** on a subject carrying scopes rather than stripping them: silently dropping a scope is an authorization change with no error, no log line and no diff, discovered later as "permissions randomly stopped working". `verifySession` / `verifySessionKeyed` return `SubjectIdentity`, so the guarantee is a type fact and not a convention — nothing downstream can read authority out of a cookie, because the value it gets back has no field for it. - **The resolver says WHICH claim it is making.** `resolveScopes` may now return `{ kind: 'authoritative', scopes }` (this resolver is the complete answer — narrowing works), `{ kind: 'unavailable', reason }` (the source could not be reached: the request fails closed with `Unauthenticated` and the reason reaches `onStrategyFailed`), or a bare array, which still means `{ kind: 'grant' }` and is unioned exactly as before — an already-written resolver keeps its exact meaning, with no compiler error to warn it otherwise. The empty array is what forced the split: under the old shape it had to mean "no extra scopes", under a replace shape it would mean "no scopes at all", and a failed lookup produces it under both. Three meanings, one value, and the union-only rule was really guarding against the third. Narrowing is auditable: `onScopesNarrowed` reports what was removed, once per resolution rather than once per request. - **The framework caches the resolution, with a seam that drives staleness to zero.** `makeScopeCache` / `scopeCacheKey` (`@voltro/protocol`), wired by default in `composeAuthStrategies`. The window is `DEFAULT_SCOPE_CACHE_TTL_MS` = 30s — deliberately the same window the session revocation check already used, so the two per-request store reads miss together and an operator reasons about ONE number instead of discovering later that the second one was 7 days. The honest cost: the revocation check was already a per-request DB hit through a cache of exactly this shape, so this adds one miss per subject per window. An app makes the window zero either with `VOLTRO_AUTH_SCOPE_CACHE_TTL_MS=0` / `auth: { scopeCache: { ttlMs: 0 } }` (resolve every request) or by holding its own `makeScopeCache()`, passing it as `auth: { scopeCache }`, and invalidating inline from the mutation that changes a role — instant on that process, `ttlMs` on other replicas, the same wording the revocation checker already ships. The cache key includes `tenantId`, because a user keeps their id across a tenant switch and their authority does not. **The whole seam is one `app.config.ts` type, not three fields.** `auth.resolveScopes`, `auth.scopeCache` and `auth.onScopesNarrowed` are `AuthorityResolution`, and both boot paths forward `apiConfig.auth` WHOLE. That is not tidiness: the first cut of this change plumbed `resolveScopes` alone with its OLD `=> ReadonlyArray` return type, so `{ kind: 'authoritative' }` did not typecheck in a user's config and the cache and the audit hook had no config surface at all — every protocol test passed over a feature no app could reach. Forwarding an object rather than fields is what makes that half-application unrepresentable. **In-flight sessions are invalidated, by construction.** The payload carries `v: SESSION_PAYLOAD_VERSION` and a payload without it fails to decode. A cookie minted under the old contract asserts authority; reading it leniently as "a subject with no scopes" would authenticate someone under a contract we no longer hold, which is the defect itself in a smaller shape. Every live session ends at deploy and users sign in once more — plan it like a secret rotation. Session rows are untouched. **Not affected:** api-key and JWT strategies already resolved scopes per request from the key record or the token claims. What they gain is a way to be NARROWED — an authoritative resolver overrides a token's own scope claim, which union-only could never do. Migration: `voltro update` prints the manual codemod for any app that touches the session surface. Move the scopes off your mint sites and into `auth.resolveScopes`, pick `authoritative` when that resolver is the complete answer, and return `unavailable` rather than `[]` when the lookup fails. - **@voltro/plugin-auth** — **`UserStore` gained eleven methods, so a HAND-WRITTEN store no longer satisfies the interface.** Email verification, tenant invitations and impersonation all need storage, and this is the one interface the plugin has for it: `markEmailVerified`, `latestToken`, seven `*Invitation*` methods, and three `*ImpersonationGrant*` methods. **If you use `memoryUserStore` or `postgresUserStore`, nothing changes** — both implement everything, and `userStoreContract.test.ts` runs the same contract against both (live postgres included) so the two cannot drift. The alternative was splitting the store into four narrower interfaces so the addition would be invisible, and it was rejected: each feature would then need its own `store:` field on its own config block, an app would pass the same object three times, and the plugin would carry a duck-typed fallback for "the main store happens to satisfy this". One interface for one concept, with a break, is the smaller thing. **Also breaking, smaller:** `SendEmailInput['kind']` gained `'email-verify'` and `'invitation'`. A sender that switches exhaustively over it needs two more arms. The codemod is `manual`, and deliberately so. The missing members are eleven queries against tables only the app knows the shape of, and a transform could only stub them — which is the worst available outcome: `acceptInvitation` returning `null` compiles, ships, and means "every invitation is invalid"; `markEmailVerified` as a no-op means an app on `emailVerification: 'strict'` refuses every login forever. A codemod that makes the build pass while turning a security feature into a permanent refusal is worse than none, because the red build is the only signal that anything is required. The note spells out what each method must do, including the two that must be a SINGLE statement (`acceptInvitation`, `endImpersonationGrant`) and the one rule that is easy to get wrong by copying the neighbours: the read paths in `postgresUserStore` fail OPEN, and an invitation write must not. - **@voltro/plugin-webhooks, @voltro/plugin-billing** — **Outbound webhooks speak Standard Webhooks v1.0.0 by default — verified against the spec's published interop vector, not against ourselves. Three delivery defects fell out on the way.** `plugin-webhooks` already had declared outbound events, durable per-target fan-out, retries, idempotency, rate limits, auto-disable, a management API and Stripe/GitHub/Slack signing. What it did not have was an INTEROPERABLE signature: the house format (`X-Webhook-Signature: t=…,v1=`) is one more thing every receiving team has to implement by hand. **BREAKING — a scheme renders HEADERS, plural.** ```ts signPayload(scheme, body, secret) → signRequest(scheme, { rawBody, secret, messageId }) { headerName, headerValue } { headers } verifySignature(scheme, body, secret, value) → verifyRequest(scheme, { rawBody, secret, headers }) ``` Two things did not fit through the old one-header hole, and both were visible in the code as workarounds: Standard Webhooks needs three headers out and signs over a message id the old signature could not receive, and `slackSignature()` shipped as a **stub whose `verify` returned `false` unconditionally**, usable only via a `"|"` packing convention spliced in by the route mounter. Slack's verifier is real now, and the splice is gone. `codemod: manual` rather than a transform, for one reason: the new signature requires a `messageId`, which is also the consumer's idempotency key, and there is no correct value a transform could invent. `randomUUID()` per call site would compile, pass, and silently make every retry a distinct message to the receiver. **The spec, and how the claim was checked.** A round-trip test passes perfectly for a construction that is entirely wrong — base64 vs hex, the printable secret vs its decoded bytes, `:` vs `.` — because both halves are wrong the same way. So the conformance suite runs the published interop vector (`whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw` / `msg_p5jXN8AQM9LWM0D4loKWxJek` / `1614265330`), independently reproduced with `openssl dgst -sha256 -mac HMAC -macopt hexkey:$(base64 -d)` before the implementation was written. Implemented: the three lowercase `webhook-*` headers, `msg_id.timestamp.payload` signed content with the `.`-delimiter constraint ASSERTED, base64 `v1,` signatures, space-delimited multi-signature rotation, `whsec_` + base64(24..64 bytes) keys HMAC-ing the DECODED bytes, constant-time compare, a 300s tolerance (the spec requires a tolerance and names no number). NOT implemented: the asymmetric half (ed25519 / `v1a` / `whsk_`), which `verifyRequest` refuses by name rather than reporting a generic mismatch. A `whsec_` prefix is REQUIRED and a bare hex secret is refused, at subscribe rather than at the first delivery. Leniency would be worse than useless here: a 64-char hex secret is also valid base64, so a "decode if it looks like base64" rule silently keys the HMAC on 48 bytes of garbage — self-consistently, so our own round-trip passes while every conformant consumer rejects the delivery. **Three delivery defects, found by reading the spec's delivery section against the code:** - **Redirects were FOLLOWED.** `fetch` follows by default. The spec says a 3xx is a failure and must not be followed — and `assertPublicUrl` validates the URL we POST to, so a 302 walked the request past the SSRF guard to wherever the receiver pointed. Now `redirect: 'manual'`. - **There was NO timeout.** A receiver that accepted the connection and never answered held the durable workflow — and its rate-limit slot — indefinitely. Now 30s per attempt (`VOLTRO_WEBHOOK_TIMEOUT_MS` / `timeoutMs`), the top of the spec's 15–30s band. - **`410 Gone` waited for the failure streak.** The receiver has ANSWERED the question; counting to `autoDisableAfter` first (and never, when it is unset) is ignoring the answer. It disables the target immediately now. All three are asserted end-to-end against a real receiver, per dialect. `defaultOutgoingSignature()` returns the spec scheme; the house format is `genericHmacSignature()`, a named choice alongside `stripeSignature()` / `githubSignature()`. Existing target rows are untouched — each stores the scheme it was created with. A signer handed an unrecognised persisted scheme now throws instead of emitting a request header literally named `"undefined"`. - **@voltro/runtime, @voltro/cli** — **A durable workflow re-resolves its caller's authority when it runs; the start-context row carries identity only (REL-24).** `_voltro_workflow_start_contexts.subject` is a `json()` column that held the caller's whole `Subject`, `scopes` included. A cluster runner reads it back — a different process, possibly days later — and ran the workflow with the authority the caller had at START time. Remove a role on Monday and Thursday's resume still asserts it, out of a row nothing re-validates, on a path with no request, no cookie and no expiry. Same class as the session cookie 0.34.0 removed, one layer down and made **durable**. **The guarantee:** > **IDENTITY IS PERSISTED. AUTHORITY IS RE-RESOLVED AT RESUME, OR ABSENT.** - **Identity** — type, id, tenantId, metadata — is written *and read* through `subjectIdentity()`, the same total, lossy function the session cookie mints through. It must survive: `applyTenantScope` reads `tenantId`, the run row is attributed to `id`, and a plugin service resolving a per-user credential reads `metadata`. A workflow started by tenant A still acts on tenant A's rows in three days' time. - **Authority** comes from the app's own `auth.resolveScopes` on every execution attempt — the same seam the request path uses — with `ctx.origin === 'workflow'`. An app that wires no resolver gets runs with no scopes, which is the fail-closed direction and exactly what a cookie-authenticated caller already gets on the request path. - **`{ kind: 'unavailable' }` fails the attempt**, loudly, instead of running with less authority than the caller has. A run that silently skips the branch it was not allowed to take is indistinguishable from one whose business logic said no; cluster retry and `voltro workflows redrive` already exist for the recoverable case. **Why not `SYSTEM_SUBJECT`.** It is the right answer for a run with **no** recorded caller — a bootstrap, an orphan whose row aged out — and the engine still uses it there, unchanged and deliberately *not* put through the app's resolver. It is the wrong answer for a run that HAD one: `SYSTEM_SUBJECT` carries `tenantId: null`, which the tenant scope reads as "no filter", so promoting a tenant-owned workflow to it would trade frozen authority for cross-tenant **visibility**. That is a worse defect wearing the fix's clothes. **`auth.resolveScopes`'s context grew a discriminator and lost a guarantee.** `ctx.origin` is `'request' | 'workflow'`, and `ctx.clientId` is now `number | undefined` — a workflow execution has no connection, and `ctx.headers` is `{}`. Empty rather than fabricated: a resolver that reads headers must be able to branch on `origin` instead of silently receiving a bag that is always empty. That type change is where a resolver reading `clientId` sees the compile error. `scopeCache` applies to the request path only — one resolution per run attempt is not a hot path, and a run that lasts days must not inherit a window sized for a burst of requests. **Both boot paths were already wrong in a second way, and it is fixed in the same change.** `dev.ts` and `serveApi.ts` each carried a hand copy of the persist/load functions, and the copies had drifted: dev `JSON.stringify`s the subject for the raw store path — which applies no `json()` codec, so mysql2 binds a raw object and the statement fails — and parses it back; serve did neither. The durable handoff therefore threw on mysql in production, and every resumed run silently became a bootstrap run. There is one module now (`workflowStartContext.ts`), called by both, with the call sites asserted — a behavioural test cannot see a call site that stopped calling. **No migration to run.** The column is framework-owned, so `voltro db apply` and a `voltro dev` boot carry it on every dialect. Rows written by the previous version still contain scopes and are **stripped on read**: a resumed run cannot re-assert authority an older build persisted. That is data handling, not back-compat — honouring authority we no longer write, because we no longer write it, would be the defect outliving its own fix. **`voltro update` carries you across this** — codemod `0.34.0/20_workflow-authority-resolves-at-resume`. - **@voltro/workflow** — Two workflow APIs were declared and read by nothing. Both are resolved, in opposite directions. **`patches` is now live.** `patch('marker')` (from `@voltro/workflow` / `@voltro/workflow/define`) answers whether a marker declared in `workflow({ patches: [...] })` was in effect **when the current run started** — Temporal-style in-body versioning, so a body can branch and let in-flight runs finish on the old path while new runs take the new one. The answer is read back from `_voltro_workflow_runs.workflowPatches`, which is stamped at start, so it cannot change under a redeploy. Previously `patches` was accepted, stored and rendered as a dashboard tooltip, with no primitive that could read it. **`messages.queries` is REMOVED.** There was never a send path — no `sendWorkflowQuery`, no `awaitQuery`, nothing to receive one — while the codegen projected the channel into the generated rpcGroup and the client's `WorkflowState` carried it, so a declared query was a fully typed record no caller could invoke. Migration: delete the `queries:` block from `workflow({ messages })`. Use `updates` for a synchronous request/response and `signals` for fire-and-forget; a read-only projection of workflow state belongs in a normal `*.query.ts` over `_voltro_workflow_runs` / your own tables. Declaring `queries` no longer produces metadata, so it is silently ignored rather than rejected — the codemod's note is what surfaces it. **A replay nondeterminism tripwire.** Journal entries are keyed by activity name/attempt with no shape check, so editing a workflow body while runs are in flight replays cached results for names that still match and freshly executes the ones that do not, silently; bumping `version` instead terminally fails every in-flight run. Neither branch was safe. A run re-entering its body now compares the steps it REACHES against the steps it recorded on earlier attempts and emits a `nondeterminism-suspected` run event on divergence — set membership (`unreached-step`: a recorded step the current code never reaches) and per-name sequence (`extra-step-occurrence`: a recorded step reached more often than recorded). Never a total order, which would false-positive on concurrent steps. It is an EVENT and never a failure: the checks sit on a best-effort recorder, so a false positive that killed a run would be worse than the divergence it suspects. Covers `voltro workflows redrive`, which re-drives an old journal against current code through the same path. Also fixed on that path: a re-entry used to re-INSERT the run row, which the unique `executionId` rejected, so a resumed run lost its run id and never recorded steps or a terminal status again — it sat at `suspended` forever. - **@voltro/plugin-auth-workos** — **WorkOS hosted login: `state` is mandatory and PKCE (S256) is required, and the callback verifies both (SEC-12).** `workosAuthorizationUrl` appended `state` only `if (o.state)` and generated no `code_verifier` at all — so the DEFAULT flow had no CSRF token, and adding one was an integration's idea rather than the framework's. An attacker who gets a victim's browser to hit the callback with an authorization code they obtained logs the victim into the ATTACKER's account; `state` is the only thing that stops it. - `workosAuthorizationUrl` is **replaced** by `workosBeginLogin`, which returns `{ url, state, codeVerifier }` instead of a string. Both secrets are minted from `randomBytes` on every call; the authorize URL carries `state`, `code_challenge` (S256 of the verifier) and `code_challenge_method`. It no longer accepts a caller-supplied `state` — an application payload mixed into a CSRF nonce is what made the nonce guessable. - `workosAuthenticateWithCode` gains three REQUIRED fields — `state`, `expectedState`, `codeVerifier` — compares the two states in constant time BEFORE any network call, and sends `code_verifier` with the exchange. A mismatch throws the new `WorkosStateMismatchError` (a `WorkosExchangeError`, status 400). The check lives inside the only function that can redeem a code on purpose: a generated `state` that nothing verifies is worse than none, because a code review, a screenshot of the authorize URL and a pen test all then read as "CSRF is handled". Unaffected: `workosStrategy` (the JWKS verify side, the more common integration), Magic Auth (no redirect, no `state` to forge), and the organizations helpers. Nothing to configure in the WorkOS dashboard. **`voltro update` carries you across this** — codemod `0.34.0/04_workos-oauth-state-pkce`. - **@voltro/client, @voltro/cli** — **Every typed-error branch on the write side had been dead since the hooks were written, and it failed silently by construction.** `useMutation.mutate` / `useAction.run` / every `useWorkflow` send / `useUpload.upload` all called `runtime.runPromise(...)` inside a bare `try/catch`. `runPromise` rejects with Effect's `FiberFailure` WRAPPER — an Error subclass that keeps the `Cause` behind a symbol key — so the value a caller catches has `_tag === undefined`, and the branch the docs teach never ran: catch (err) { if (err._tag === 'EntitlementExceeded') showPaywall() } Nothing throws, nothing logs, nothing goes red. The paywall simply never appears. `frontend-saas` shipped with exactly that branch and it could not have worked in any app that scaffolded from it. **The asymmetry is the whole diagnosis.** The READ path already did the right thing, and said why in a comment next to it: `subscriptionCache`'s stream-failure observer reduces the `Cause` with `Cause.squash` "because that value is what `_tag`-style pattern-match consumers expect". Two other places in the framework had learned the same lesson independently — `@voltro/database`'s `settleTransactionExit` (after the same defect shipped in three of four dialect stores) and `@voltro/testing`'s `invoke`. The client's write path was the one side that never got it. `runRpc.ts` is now the single seam all four hooks call. It reads the `Exit` rather than sniffing for a wrapper after the fact, which is what the read path does and is why no second mechanism was invented: `runPromiseExit` + `Cause.squash`, so the wrapper is never minted in the first place. A defect still rejects with the defect, an interrupt still rejects — only the value gets better. Migration: if you never worked around this, your existing `_tag` branches start working and there is nothing to change — but re-read whatever sits in FRONT of a branch that has been dead for its whole life, because a compensating hack there now runs alongside it. If you DID unwrap the wrapper yourself (`Cause.squash` over `Runtime.FiberFailureCauseId`, an `isFiberFailure` test), delete the unwrap — it is a double-unwrap now and stops matching. The codemod is `manual` because a transform cannot tell a workaround from a deliberate `Cause` inspection, and guessing wrong replaces a working error path with a silent one. **Why a green suite let it ship, recorded because the shape recurs.** Every existing test asserted on `onError`'s ARGUMENT or on a mocked hook's `mockRejectedValue({ _tag: 'X' })`. A wrapper is a perfectly good argument, and a mock never produces one — so both styles pass identically in the broken and the fixed framework. The new `writeErrorIsTagged.test.tsx` awaits the REAL hook's REJECTED promise from a real `ManagedRuntime` running a real `Effect.fail`, and carries a control asserting the raw `runPromise` entry point still wraps, so it cannot go quietly green if Effect changes underneath it. `frontend-saas`'s paywall test stopped re-implementing `isEntitlementExceeded` inside its own mock and gained the untagged-failure negative control. - **@voltro/runtime, @voltro/voltro** — **`x-forwarded-for` is no longer trusted by default (SEC-8).** The pre-routing interceptor took the header's first token verbatim as the client address and only fell back to `socket.remoteAddress` when it was absent — `fromXff ?? fromSocket`, with no trusted-proxy configuration anywhere in the framework. `x-forwarded-for` is a request header, so any client can write it: one extra header per request defeated a per-IP rate limit, moved a geo-block, and put an attacker-chosen string into every audit row's `remoteAddr`. The default is INVERTED. With nothing configured, the client address is `socket.remoteAddress` and the forwarded chain is ignored entirely — the only value nobody upstream of the kernel can forge. An operator who genuinely terminates at an ingress declares it in `app.config.ts`, and only then does the chain become evidence: security: { trustedProxies: ['private'] } // RFC1918 + CGNAT + link-local + ULA security: { trustedProxies: ['loopback'] } security: { trustedProxies: ['10.0.0.0/8', 'fc00::/7'] } security: { trustedProxies: ['2'] } // hop count (express's convention) security: { trustedProxies: ['*'] } // any peer — only correct when the // ingress OVERWRITES rather than appends `VOLTRO_TRUSTED_PROXIES` (comma-separated) is the env override for a deployment you cannot rebuild, and an embedder passes `RpcServerOptions.security.trustedProxies`. With a list configured, the immediate peer must itself be trusted (otherwise the header is just something the client typed) and the chain is walked right-to-left past every declared proxy — so a spoofed prefix cannot push the resolved address further left. IPv4-mapped IPv6 (`::ffff:10.0.0.7`, what node hands you for a v4 client on a dual-stack listener) is normalised before matching, because without that every v4 CIDR silently misses and the operator's config appears to do nothing. The same configuration now gates `x-forwarded-proto`, which decides whether a response is treated as https (and therefore whether HSTS is announced). Migration: **if you rate-limit or geo-block per IP behind a load balancer, set `security.trustedProxies`.** Without it every request counts against your proxy's address instead of the caller's — the limiter still works, it just bins everyone together. Apps with no proxy, and apps not using per-IP limits, need no change. **`voltro update` carries you across this** — codemod `0.34.0/06_origin-guard-and-trusted-proxies`. ### Added - **@voltro/workflow, @voltro/ai, @voltro/runtime, @voltro/cli** — **A budget breach can now SUSPEND a durable run instead of destroying it or merely being observed.** The framework had two answers to "this tenant is over budget" and neither is a control: `finops.ts` said flatly that a cost budget "never BLOCKS compute … an observability-grade signal over work that already happened", and `requireAiBudget` hard-fails one call — which does stop the spend, by killing a run that may be nine steps in, losing the work and losing it again on every retry. A ceiling whose only expression is destruction gets set high, or turned off. `aiStep` / `aiObjectStep` take `budget: { limitUsd, estimateUsd?, onExceeded: 'fail' | 'suspend' }`. On `'suspend'` the run parks on a durable `_voltro_budget_holds` row, frees its worker, and resumes when the budget has headroom — then continues from where it stopped. `defineCostBudget` gains the matching `onExceeded: 'observe' | 'suspend'` (default `'observe'`, so nothing changes for an existing budget). **The ordering is the feature.** The gate reads the RESERVATION counter (`requireAiBudget` with `addUsd: 0`) BEFORE the journaled `step()` and before the offload enqueue — not a SUM over `_voltro_ai_usage`, which by definition only knows about money already gone. On the suspend path no provider is contacted and no queue row exists for a dispatcher to pick up. Under the cap, the estimate is RESERVED atomically before the call, which is the difference between a ceiling and a speed bump. **A release wakes a run; it does not authorise a spend.** The hold re-reads the budget on every wake and parks again if it is still over, so an operator lifting the wrong hold, or a window rolling over for a tenant that immediately spends again, cannot spend through the ceiling. Three things can wake it: the hold's own durable recheck clock (15 min, so a tumbling window nobody notifies us about is still noticed), an explicit `releaseBudgetHolds` call from app or operator code (the framework does NOT subscribe a `defineCostBudget` `recovered` signal to it for you — whether a recovered compute budget should wake AI holds is an app decision, and the recheck clock already means no run is stranded either way), and its total timeout (7 days, after which the run fails having spent nothing). The hold key is `//#`, and the generation is load-bearing rather than decorative: a run can be held more than once at one step, and re-parking on the same key would await the deferred the previous release already completed, resolve instantly, and spend straight through — the AI-Flows constant-signal-name collision, one level up, with money on the other side of it. The generation counts holds already recorded, so it is stable under a crash-replay that took no new hold and different under one that did. - **@voltro/local-first** — **`useCrdtText` — a `crdtText()` column bound to a running app, as one hook.** The column type, the Yjs-backed merge, the offline sync queue with bounded retry, durable IndexedDB persistence and the authoritative server-side merge on the write path all already shipped. What every consumer still had to write by hand was the React half, and it is the half with a trap in it. ```tsx const row = useSubscription('app', 'documents.byId', { id }) const save = useMutation('app', 'documents.setBody') const body = useCrdtText({ cell: { table: 'documents', id, column: 'body' }, remote: row.data?.body ?? null, push: (w) => save.mutate({ id: w.id, body: w.update }), })