@voltro/plugin-auth-oidc 0.52.0 → 0.54.0

package/CHANGELOG.md

@@ -39,6 +39,422 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.54.0] — 2026-08-27
+
+### ⚠ BREAKING
+
+- **@voltro/local-first** — **`CrdtDocHandle.onUpdate` now tells its handler whether the update was LOCAL.** The signature gains a second argument: `onUpdate((update, { local }) => …)`. `local: false` means the blob came from folding somebody else's state through `applyState`.
+
+  Without it, an echo guard could not be written correctly on the public surface. Applying a peer's update fires the same handler a local edit does, so an app pushing from `onUpdate` re-broadcasts what it just received — measured with three tabs open, one keystroke produced three server writes instead of one. It converges (the merge is idempotent), but the amplification scales with the session.
+
+  The only app-level workaround was an `applying` boolean around `applyState`, and that is correct **only** while the backend emits synchronously — a property `CrdtBackend` deliberately does not promise ("the backend decision lives behind our abstraction so it can change"). So the flag had to come from the backend: the yjs one tags its own folds with a symbol origin and reports anything else as local.
+
+  `codemod: none` — the parameter is ADDITIVE. An existing single-argument handler keeps compiling and keeps behaving exactly as before; there is nothing to rewrite. Read the flag when you push from `onUpdate`, which is what `useCrdtDoc` does for you.
+- **@voltro/local-first** — **`RUNTIME_SEAMS` lists ONE seam now, not three** — `['sync-transport-app-tags']`. `RuntimeSeam` narrows with it. The two removed entries left in opposite directions, and `seams.ts` was asserting both halves of the contradiction at once: its `DONE` prose said the presence broker binding shipped while the array beside it still named `presence-broker-binding` as open.
+
+  - `presence-broker-binding` is BUILT. `usePresenceChannel` (`@voltro/plugin-presence/web`) rides the framework's own presence lane, so cross-replica fan-out belongs to the broadcast plugin and there is one presence wire rather than two; the shape is pinned by `presence/channelParity.test-d.ts`. - `wasm-sqlite-durable-adapter` was REJECTED, with the reasoning recorded in `mirror/queryMirror.ts`: the client's query surface is `(tag, input)` and predicates never exist client-side, so a browser SQL engine would evaluate a language the client never sees. A decision is not a gap, and listing it as one invites somebody to close it. A SQLite BACKING beneath `KvStore` remains available and is a different door.
+
+  `codemod: none` because nothing in the framework reads this constant and nothing asks a user to: it is a documentation manifest that happens to be typed. There is no mechanical rewrite for a removed member of one — the correction is the sentence above.
+
+  The docs site's "what's shipped vs. a runtime seam" table carried the same two rows in both languages and now carries one, with both departures stated rather than silently dropped: "we have not built it" and "we decided against it" are different answers and a reader is entitled to know which one applies.
+
+### Added
+
+- **@voltro/content, @voltro/cli** — **Relative images inside markdown content are copied into the build, and their `src` rewritten to the copy.** `![cover](./cover.png)` now lands in `dist/assets/content-media/<hash>.<ext>` and the rendered HTML points there. `voltro dev` serves the same URL shape on demand from the source file, so a page's HTML does not change between development and a build.
+
+  Nothing moved those files before: the artifact emit wrote JSON and the renderer emitted the relative src verbatim, so a built blog asked the browser for a path that exists only in the source tree — while `routing/assets.md` said, in both languages, that the content pipeline copied and hashed them.
+
+  A reference to a file that does not exist now FAILS the build and names the path. The alternative — emit the src and continue — is the defect itself: the page renders, the browser 404s, and the build says nothing.
+
+  Absolute (`/…`) and remote sources are untouched; they are not the build's to move. Copy and content-hash only — build-time transformation (resize / format) remains a named non-goal for markdown content, because a markdown reference carries no width and no `sizes` to derive one from. The `?image` pipeline stays the answer where that matters.
+
+  Renderers outside the framework's build are unaffected: `@voltro/content` exposes this as a registered resolver (`setContentAssetResolver`), and with none registered a relative src is left exactly as written rather than rewritten to a path nothing serves.
+- **@voltro/cli, @voltro/runtime** — **The server-side CRDT compaction threshold is an `app.config.ts` field now, not an environment variable only.** `crdt.compactMaxBytes` (default 512 KiB, `0` disables) decides when a merged `crdtText()` / `crdtDoc()` blob is soft-compacted — re-encoded through a live doc, same lineage, so every outstanding client update still merges. `VOLTRO_CRDT_COMPACT_MAX_BYTES` still wins over it: an operator acting on a running deployment outranks what the project declared.
+
+  This is the standing rule ("every number the framework picks on your behalf is a config field with a default, plus an env override"), applied to the one knob that had only the environment half. A threshold sized for a document shape is a property of the project, so it belongs in a file a reviewer reads and a deploy carries — not in whatever `env:` block somebody remembered to set.
+
+  Resolved by ONE builder both boot paths call (`wireCrdtTunables`), registered into the process slot the merge path reads — the `wireReactiveSocketTunables` shape, for the reason that shape exists: two paths resolving a value separately is how they come to disagree. `setCrdtCompactMaxBytes` was exported and called by nothing before this; the runtime kept a lazy env read for a process that never runs a boot path (a unit test), and that remains the fallback rather than a second answer.
+
+  Note `0` is a value here, not an absence — it means "do not compact" — so the resolver's floor is `>= 0` on both the config and the env side. The `> 0` floor the other tunables use would have silently dropped a declared zero.
+- **@voltro/cli** — **The gRPC surface's shutdown drain budget is configurable — `grpc.drainMs` (default 5000, `0` forces immediately, env `VOLTRO_GRPC_DRAIN_MS`).** It was a `5_000` literal in the `stop()` closure.
+
+  It is a knob rather than a measured constant, and the distinction is worth stating because the framework deliberately refuses knobs elsewhere on the same page (compression levels are fixed — "a knob nobody can pick correctly is worse than a measured default"). A compression level has no input outside the process. A drain budget has two, and neither is ours: the orchestrator's termination grace, past which SIGKILL arrives and a longer budget is decorative; and the app's longest legitimately in-flight call, below which every rolling deploy force-closes work that would have finished. The default fits the 30 s grace both kubernetes and `docker stop` default to.
+
+  The `grpc:` config shape was also declared THREE times — `ApiAppConfig`, `ServeApiOptions` and the shared builder's options — which is how a field lands on two of them. It is one exported `GrpcSurfaceConfig` now, referenced by all three, so the shared builder both boot paths already call is the only thing that reads it.
+
+  The boot line and the budget-exceeded warning both name the resolved value, so what a process will wait is visible before the shutdown rather than after it.
+- **@voltro/cli** — **Partial prerendering's counters are now real metrics — they were incremented by both boot paths and read by nothing, while the observability docs listed them among the exportable ones.** A reader who went looking for them at the OTLP or Prometheus endpoint found nothing there: `pprMetrics()` was a `globalThis` counter slot with no registry bridge, no inspect endpoint and no log line.
+
+  Five series, all labelled `page` — the DECLARED route pattern (`/blog/[slug]`), never a resolved URL: `voltro_ppr_shell_serves_total`, `voltro_ppr_hole_passes_total`, `voltro_ppr_hole_settles_total`, `voltro_ppr_hole_errors_total`, and the `voltro_ppr_hole_pass_seconds` histogram. They land in Effect's global `MetricRegistry`, so `@voltro/plugin-prometheus`' `GET /metrics` and `GET /_voltro/inspect/metrics` both see them with nothing to register — the same placement `@voltro/database` uses for `voltro_db_*`.
+
+  `voltro_ppr_hole_errors_total` is the one to alert on, and it is a separate series rather than a `status` label for a reason: a failed hole pass is invisible from outside. The shell is already on the wire with a `200`, so the page renders and every `<Await>` boundary silently stays on its fallback forever.
+
+  Two things changed beyond the bridge. The last/max latency PAIR is gone in favour of the histogram — a last value plus a monotonic max answers strictly less, and the max never comes back down. And `voltro dev` now counts shell serves too; the counter previously existed only on the `voltro start` path, which for a metric is the silent kind of drift (the series simply reads zero).
+
+  The `globalThis` slot is deleted rather than kept beside the registry: two counters for one fact is how a dashboard and a scrape target come to disagree.
+- **@voltro/plugin-presence** — `resolveMember` now receives the app's `store`, and `identityFields:` closes the hole in the obvious resolver.
+
+  Both from a deployment that adopted the hook and reported what it cost them.
+
+  **The store.** The resolver's whole job is a by-id read, and `app.config.ts` — where it is declared — is evaluated long before a migrated `DataStore` exists. The workaround is a module cell filled from a `*.startup.ts`; the plugin already receives the store through `bindDataStore`, so it hands it to the resolver instead: `resolveMember: ({ subject, store }) => …`.
+
+  **The hole.** Resolved fields merge OVER the caller's `meta`, so a key the resolver does not return keeps whatever the client sent. A resolver returning only what it found — `{ userName }` for a user with no avatar — therefore leaves a caller-supplied `avatarUrl`, or a `userName` the resolver has never heard of, standing in the roster every other member reads. That is the exact substitution the hook exists to prevent, and the doc comment's promise ("a caller cannot override what the server says about them") was broader than the behaviour: it holds only for the keys returned on that call.
+
+  `identityFields: ['userName', 'avatarUrl']` names the keys the SERVER owns. They are stripped from the caller's `meta` BEFORE the merge, so the answer is the same on every call whether or not the resolver produced a value. Ignored without a `resolveMember` — with no server identity to protect, stripping a client field would only delete data the app put there deliberately. Returning every identity key (`null` where you have no value) remains the alternative, and is what the reporting deployment did.
+- **@voltro/plugin-queue** — **Queue consumers now export Prometheus series and open one tracing span per message, continuing the producer's trace.** Both were specified and neither was built: `voltro_queue_consumed_total` had zero occurrences anywhere in the repo, and `traceparent` was copied out of the message headers onto `ctx.traceparent` — a value a handler can forward by hand, not a trace. A Kafka hop was where every distributed trace ended.
+
+  Four series, all in Effect's global `MetricRegistry` (so `GET /metrics` and `GET /_voltro/inspect/metrics` both see them): `voltro_queue_consumed_total{topic,outcome}`, `voltro_queue_retries_total{topic}`, `voltro_queue_produced_total{topic}` and the `voltro_queue_lag_messages{topic,partition}` gauge.
+
+  `outcome` is a closed two-value union — `ok` and `dead-lettered` together are every message the runner finished with, so the dead-letter rate is a division with no second series to join. A message abandoned by a REBALANCE is deliberately in neither: it was not consumed here, its new owner redelivers and counts it there, and counting it twice would make that ratio wrong in the direction of looking healthy.
+
+  Lag costs no extra round trip — `highWatermark` already rides along in the fetch response, so it is arithmetic on data the provider was handed. It is recorded in the provider rather than the runner because that is the only layer holding the watermark; the runner could only get it by asking the broker. Offsets are parsed as `BigInt` so a long-lived topic cannot lose precision, and an unparseable pair records nothing rather than a zero: "no lag" and "we could not tell" must not read the same.
+
+  The per-topic inspect counters stay, and each fact is now moved by exactly ONE recorder that writes both the slot and the series, so the dashboard and the scrape target cannot drift.
+
+  Each message is processed inside a `queue.consume` span whose parent is the incoming `traceparent`, parsed by the same `externalSpanFromTraceparent` the inbound-webhook path uses — so a malformed or all-zero header means "no parent" (a fresh root span), never a failed message. The span covers the whole message including retries and the dead-letter publish, and carries the OTel `messaging.*` attributes plus `voltro.queue.outcome`. The topic is an attribute, not part of the span name.
+
+  Known limit, measured rather than assumed: a span opened from DETACHED work does not reach an OTLP exporter, because the framework's tracer is a `Layer` provided only inside the rpc server's scope. This is framework-wide (`cdcOut.deliver` and `plugin.<name>.schedule-fire` are the same shape) and is stated in the queue docs rather than implied away. The metrics are unaffected — the metric registry is a process global.
+- **@voltro/runtime, @voltro/voltro** — `setRowFilter({ …, tables: ['bookmarks', 'recentSearches'] })` — declare which tables your filter may narrow, and delta-resume survives everywhere else.
+
+  Delta-resume is excluded for a subscription whose row set is re-resolved per delivery: replaying deltas could serve rows the subject has since lost. But the question the runtime could ask was only "is a filter registered in this process?", so ONE registration disabled cheap reconnects for every subscription in the app — a deployment measured a filter narrowing 4 tables costing the feature on all 173 of their query descriptors, 55 of whose source tables the filter never touches.
+
+  The exclusion is per table now. A declared filter keeps resume for every subscription whose source is not in its set; an undeclared filter keeps today's conservative behaviour (the runtime cannot know which tables the predicate may reach, and "unknown" must read as "yes").
+
+  **Declared, not probed** — and the difference is soundness, not taste. Resolving the scope at subscribe and treating `predicate(ctx, source) === undefined` as safe is the cheaper version: it is wrong, because the predicate is a function of freshly loaded context, so a table it does not narrow now may be narrowed on the next delivery — which is the entire reason the filter is re-resolved per delivery. A static list is a promise about every future resolution, and the runtime holds the app to it: a predicate returned for an undeclared table raises the new `RowFilterDeclarationViolated` at the read that did it (the request fails, a subscription is revoked) rather than serving rows under a resume grant the declaration no longer earns.
+
+  Eager loads (`.with(...)`) stay excluded wholesale — a relation resolves below the seam that narrows (see the sibling entry).
+
+  `apiSurface: compatible` — the golden also picks up `subscribeDescriptor` gaining its `reauthorize`/`refilter` parameters, which landed in the SSE/gRPC row-filter fix without a regeneration. That member is a framework-internal transport binding: the only implementors are the two boot paths (`serveApi.ts`, `dev.ts`), both already passing the new arguments. No user code implements or calls it, so no code that compiled stops compiling.
+- **@voltro/local-first** — **`useCrdtDoc` — the transport half `useCrdtEditor` had no partner for.** `useCrdtEditor({ doc })` takes a `CrdtDocHandle` and owns the editor lifecycle; getting that handle wired to a server was app-level glue until now. Import it from `@voltro/local-first/react`:
+
+  ```tsx
+  const shared = useCrdtDoc({
+    cell: { table: 'documents', id, column: 'body' },
+    remote: row.data?.body ?? null,          // the reactive query streaming the row
+    push: (w) => save.mutate({ id: w.id, update: w.update }),
+  })
+  // in a CHILD component, so useCrdtEditor is never a conditional hook call:
+  const editor = useCrdtEditor({ doc })
+  ```
+
+  It returns `{ doc, loaded, outstanding, synced, setOnline }`. `doc` is `null` until the mount effect has run — the document is built in an effect, never during render, which is what a rich-text binding gets wrong first (constructing during render crashes a prerender and leaves a second instance alive under StrictMode).
+
+  **It is `createSyncClient`-backed, not new glue.** The four-line hand-rolled version loses the offline queue, the bounded retry, `outstanding`/`synced`, the per-cell coalescence that drains 1000 offline keystrokes as O(1) pushes, durable persistence, and the discipline that a `null` row means NOT LOADED rather than an empty document — fold an empty document over a loading row and the first keystroke can push a state that erases what was stored.
+
+  **The echo guard is the part that could not be written outside the package until now.** A `crdtDoc()` handle is mutated by the EDITOR, so local edits arrive as `onUpdate` callbacks — and folding a peer's state through `applyState` fires the same callback. The hook pushes only when `local` is true. Without that, every client re-broadcasts what it just received.
+
+  `useCrdtText` and `useCrdtDoc` now build their sync client through one shared internal seam rather than two copies of the same transport wiring.
+
+### Fixed
+
+- **@voltro/runtime** — A row filter was bypassed for any table reached through `.with(...)`.
+
+  The filter is AND-merged onto a read's BASE table by the store middleware; an eager load is resolved BELOW that seam — the memory store recurses through its own raw read, the SQL stores fold the relation into one join — so the relation's rows never passed the code that would narrow them. Measured on one data set: a filter restricting `readers` to the caller returned exactly the caller's row on a direct read and BOTH rows through `.with({ readers: true })`.
+
+  Applying the filter inside eager compilation is the real fix and it is a per-dialect change. Until then the read REFUSES rather than serves, naming the table and both ways out (read it as its own query, or drop it from the `.with(...)`). Only relations reaching a table the filter actually narrows are affected; every other eager load is untouched, and an app with no filter pays nothing.
+
+  Silent exposure is the one outcome that must not survive the gap — the same reasoning that makes this module refuse to fail open when `load` fails.
+- **@voltro/cli** — **The AGENTS.md seeder executed every app's `app.config.ts`, so seeding one app could stop another from booting.** It walked `apps/<proj>/<app>` for the whole workspace and `import()`ed each config to read its `plugins:` list. An `app.config.ts` is not inert: it imports the app's schema, which calls `databaseHandle(...)`, which REGISTERS every table. Two apps that each declare an `actors` table therefore collided —
+
+  ```
+  duplicate table 'actors' registration: two different table descriptors claim the same name.
+  ```
+
+  — and the app being booted was the one that failed. A reference project could not start at all.
+
+  The seeder parses the config now instead of importing it, resolving each plugin's package by pairing the identifiers called inside the `plugins: [...]` block with the import that introduced them (so a renamed import still lands on the right package), and reading the `{ name: '…' }` form directly. A plugin it cannot attribute is dropped rather than guessed: the index is a filter, and a wrong row is worse than a missing one.
+
+  The rule this encodes: **a step that writes documentation must not execute application modules.** Nothing about composing an index needs a config's runtime value, and the sibling app-discovery pass was already reading the same file as text for its `type:` check.
+
+  Worth knowing for the next diagnosis: two different descriptors for one name reads like one module evaluated twice, so the investigation went looking for split module identity (pnpm symlink vs real path, ESM cache keying). It was two DIFFERENT apps, pulled in by a documentation step — found by tracing what actually resolved, not by reasoning about what could.
+- **@voltro/cli** — **`voltro build` read the PREVIOUS build's config, so every `app.config.ts` change landed one build late.** `loadConfig` prefers the precompiled `.framework/dist/server/appConfig.js` when it exists — correct for `serve` / `start`, which cannot read TypeScript, and exactly wrong for the command that WRITES that file. Anything consumed before the config is recompiled took the stale value: `fonts`, `images`, `seo`, `theme`, `locales`.
+
+  Silent in the worst way: the second build is always right, so the symptom is "my change did nothing" followed by "…and now it works", with no error either time. Measured by setting `title` to a probe value, building, and finding the old title in the generated shell.
+
+  `voltro dev` already carried this fix, with the reasoning written on the option itself. The build path is the one that makes the artefact, so it is the last place that should trust it.
+- **@voltro/local-first** — **`useCrdtEditor` built its editor during RENDER, so a default page could not mount it and StrictMode leaked one.** The Tiptap instance was constructed inside a `useMemo`, which runs while rendering. Two consequences, both real:
+
+  - **Server render threw.** Tiptap needs `window`; a page mounting this hook failed prerender with `there is no window object available`. `renderMode` defaults to `'static'`, so that is the ordinary page, not an exotic one. - **React's double-invoked render built TWO editors** and the cleanup destroyed only the last, leaving the first alive holding its Yjs binding. `useCrdtText`'s own comment documents exactly this shape as a bug; the editor had it anyway.
+
+  Construction moved into an effect, and the cleanup destroys THAT instance rather than whatever the ref currently holds — reading the ref destroys the new editor on a rebuild and leaves the old one running.
+
+  `extensions` is no longer a dependency. Callers pass an inline array literal, which is a fresh identity every render, so listing it rebuilt the whole editor per keystroke; it is read at construction from a ref instead. The trade is stated rather than hidden: changing `extensions` after mount does not rebuild the editor — remount with a `key` if you need that.
+
+  **`CrdtDocHandle` is exported now.** It is the parameter type of `useCrdtEditor`, and it was declared, used across the package, and exported from nowhere — visible in the built `.d.ts` only as a bare `declare interface`, which no import can reach. An app binding an editor could not type its own variable.
+- **@voltro/cli** — `middleware.ts`'s `cspNonce` now reaches the scripts in a STREAMED response's `<head>`. Both boot paths handed the nonce to React — which stamps only the scripts React itself emits — and not to the driver that composes the head, so on the arm a plain `renderMode: 'ssr'` page takes, `renderDeferredRegistryScript()` (executable inline JS) and the `__voltro_state__` payload went out bare under the very `script-src 'nonce-…'` policy the same response set. A deferring page's registry was therefore the one script the browser refused to run. The `renderMode: 'spa'` layout-shell arms were unstamped end to end for the same reason and are fixed with them.
+
+  `stampScriptNonce` also stops mistaking `data-nonce="…"` or a `?nonce=` query parameter for a nonce attribute, which left exactly the tags a policy then blocked unstamped.
+
+  Still open, and now documented rather than implied: the settle `<script>` an `<Await>` boundary emits inside the streamed body is part of the rendered tree, so neither stamper reaches it — `defer()` and `cspNonce` do not compose yet.
+- **@voltro/runtime, @voltro/cli, @voltro/plugin-queue, @voltro/plugin-cdc-out** — **A span opened by detached work reached no exporter.** The tracer is a `Layer` provided at `startRpcServer`'s outermost scope, so `Effect.withSpan` inside a handler resolves the configured OpenTelemetry tracer. Work that runs OUTSIDE a request fiber — a broker callback, a schedule firing, a CDC delivery — reaches Effect through its own `runPromise`, which resolves the DEFAULT tracer: it creates spans and hands them to nobody. Measured against a live tracing layer: **0 finished spans**, for three framework span sites that all read as instrumented (`queue.consume`, `cdcOut.deliver`, `plugin.<name>.schedule-fire`).
+
+  The server now publishes its tracer instance into a process cell (`globalThis` + `Symbol.for`, for the same duplicate-instance reason `coreTablesRegistry` and the row filter are there), and detached work runs under it via `withServerTracer`. That is exactly the correction the LOGGER already had one line over in `rpcServer.ts` — detached fibers "start from the default runtime and carry their own", and were given one; the tracer never was.
+
+  Not a second provider: a per-plugin tracer means a second `NodeTracerProvider` with an exporter nothing flushes at shutdown, and global OTel registration is refused on purpose. There is one tracer, built where it always was.
+
+  `withServerTracer` is a no-op when nothing is published — a unit test, an embedder, a process with no rpc server — never a throw and never a second tracer. Pinned by `serverTracer.test.ts`, whose second case drives the defect directly: without the wrapper, the same span never reaches the tracer under test.
+- **@voltro/local-first** — **`useCrdtEditor` was unreachable from a published install.** `@voltro/local-first`'s source `exports` map carried `./editor`, its `publishConfig.exports` — the map an npm install actually resolves — carried only `.` and `./react`, and the build emitted no editor bundle. So the rich-text editor binding worked inside this monorepo (where `workspace:*` resolves the source map) and gave every user `ERR_PACKAGE_PATH_NOT_EXPORTED`, while the docs taught it.
+
+  `editor` is a build entry now, `./editor` is in the published exports, and it has its own api-extractor report so the surface is checked like the other two. An entry point that is documented and not built is a feature that exists for nobody outside this repo, and the two maps diverging is the shape that hides it: the one you read is not the one users resolve.
+- **@voltro/web** — `responseHeaders` and `cspNonce` are on the type users actually write against.
+
+  The CSP-nonce and response-header feature shipped with its fields declared in the CLI's internal `MiddlewareResult` and NOT in the one `@voltro/web/middleware` publishes — the type `defineMiddleware` checks a user's `run` against. The runtime honoured both fields; the compiler refused them. So the documented way to set a `Content-Security-Policy` from middleware produced TS2322, and the only way to use a working feature was to cast around its own type.
+
+  Two definitions of one shape is what allowed it: the half that gained the feature is not the half a user writes against. The published type carries both fields now, with the same documented limits (a prerendered `static` file is served without a render, so no middleware runs; `cspNonce` is `ssr` only, because an isr render is cached and a cached nonce is a lie the browser enforces).
+
+  Caught by the `web-layout-loader` fixture, which is the only place that writes this type the way a user does.
+- **@voltro/cli** — `voltro mobile <dir>` read its directory with a predicate that treats every flag as valued.
+
+  The command found its root with a hand-rolled scan — first argument that does not start with `-` and is not preceded by a `--flag`. Two things go wrong with that shape, and `cliPositionalFlagSafety.test.ts` exists because they have gone wrong before:
+
+  - it treats a BOOLEAN flag as consuming the next argument, so `voltro mobile links --help ./app` decided `./app` was `--help`'s value and silently fell back to `process.cwd()`; - it matched with `indexOf`, the FIRST occurrence, so an argument whose text appears twice was judged by the wrong position.
+
+  It uses `firstPositional(args, VALUED_FLAGS)` now, with the three flags that actually take a value declared rather than inferred.
+- **@voltro/database** — Adding a `.default(…)` to an EXISTING `text()` column no longer kills the migration on MySQL. MySQL refuses a DEFAULT on a TEXT/BLOB column outright (`BLOB, TEXT, GEOMETRY or JSON column 'x' can't have a default value`), where MariaDB allows it — so the same declaration applied on one engine and failed mid-migration on the other. `CREATE TABLE` has always answered this by widening such a column to `VARCHAR(255)` (`NVARCHAR(450)` on SQL Server, where the reason is indexability); the ALTER path now applies that same answer, reshaping the column to the declared shape instead of setting a default on whatever the column happened to be. A column therefore ends up with the same type whether the default was declared before or after the table existed. Postgres (TEXT takes a DEFAULT) and SQLite (rebuilds to the declared shape) are unchanged. Note the narrowing: on mysql/mariadb the column becomes `VARCHAR(255)`, so the ALTER fails loudly if an existing row is longer — use `text().maxLength(n)` to choose the width. The same widening rule also reached `ADD COLUMN`, which on SQL Server had emitted `NVARCHAR(MAX)` for a column `CREATE TABLE` renders as `NVARCHAR(450)`.
+- **@voltro/cli** — **Validation errors on the no-JavaScript form path rendered in English on every locale.** `validateFields` resolves message ids through a locale whose default is `documentLocale()` — it reads `<html lang>`, and outside a browser that is always `'en'`. The `/form/*` handler runs on the server, so a German page's 422 came back with English field errors while the same form with JavaScript rendered German; the flash carries the resolved strings, so hydration kept them.
+
+  The handler now resolves the locale from THIS request through the same resolver the surrounding page render and the ISR cache key already use (cookie › `Accept-Language` › the app's default). It is a required option on `makeFormPostHandler` rather than an optional one: both boot paths mount that handler separately, and an option nobody has to pass is one a new mount silently omits — landing straight back on the browser default. An app with no `locales` configured answers `'en'` explicitly.
+
+  **Under URL-prefix i18n the referring path outranks that chain.** There the language IS the URL (`/de/todos`) and the cookie may say something else entirely, so a cookie-only answer renders errors for a page the user is not on. The handler passes the referer's path to the resolver and both boot paths check it against the app's declared `locales` first, through one shared `localeFromPathPrefix` — a first segment that is not a declared locale (`/design/…`) falls through to the cookie chain rather than being mistaken for one. This is the "referer path vs. locale cookie" question the no-JS form work left open; the answer is both, in that order.
+- **@voltro/client** — `useOutbox`'s `resolveConflict(id, input)` now actually replays the entry it resolved. It replayed against the pre-resolution queue — `replay` reads the queue through a ref, and the `setQueue` beside it had not landed yet — so the entry it was handed was still `conflict`, `replayable()` stopped at it, and nothing was sent. The resolution then sat in the queue as `pending` with no further replay scheduled, and every write queued behind it stayed blocked with it: a conflict that could be resolved in the UI and never left the device.
+- **@voltro/runtime, @voltro/cli** — **A subscription opened over SSE or gRPC ignored the registered row filter — every read, not just the first.** `dispatcher.subscribe` resolves row visibility itself and treats a missing `refilter` as "this app has no row filter", so it read the descriptor unnarrowed. The WebSocket path always supplied one (`bindSubscription`'s `defaultRefilter`); the SSE and gRPC projections go through `makeQuerySubscriber`, whose `subscribeDescriptor` callback passed three arguments and dropped the trailing pair. Both boot paths were affected identically, so nothing a dev/serve parity check looks at could see it.
+
+  The same omission dropped the per-delivery guard re-check, which `data/grpc.md` and the 0.53.0 notes stated as a property: a revoked scope did not end a descriptor-query stream on those two transports. Computed queries were never affected (they re-run their handler, guards included), and neither was any app without a registered row filter.
+
+  Three things changed. `makeDefaultRefilter` moved to `@voltro/runtime`'s `rowFilter` module — it was private to the WebSocket entrypoint, and the transports that could not reach it are exactly the ones that went unfiltered. `QuerySubscriberDeps.subscribeDescriptor` takes the reauthorizer and the refilter as REQUIRED parameters, so a future transport cannot omit them by writing a shorter callback. And `dispatcher.subscribe` now THROWS, by name, when no refilter is passed while a filter is registered: reading unfiltered on purpose is available, but has to be said out loud with `NO_ROW_FILTER`. That is the same correction `ctx.rowFilter` already carries one layer up — `undefined` may mean "this app has none", never "the caller forgot".
+
+  Pinned by `subscriberTransportRefilter.test.ts`, which drives a real dispatcher through a store that evaluates predicates and asserts the foreign row never crosses the wire in ANY frame, with a positive control so an empty stream cannot pass.
+- **@voltro/cli** — **A template could not ship a font or an image — the scaffolder corrupted every binary file.** `scaffoldFromTemplate` read each file with `readFile(src, 'utf8')` and wrote the string back. That call does not throw on binary input: it substitutes U+FFFD for every undecodable sequence and returns a string, so a woff2 went in at 15 344 bytes and came out at 27 572, silently, in every scaffolded project.
+
+  Substitution is now gated on a text-extension allowlist and everything else is copied byte-for-byte. Extension-less files and dotfiles (`Dockerfile`, `.gitignore`, `LICENSE`) count as text — they carry tokens, and treating them as binary would ship a literal `{{appName}}`.
+
+  The comment above that line already claimed "we hard-fail if a template author adds one so the failure is visible at boot". There was no such check, and there could not be one on that call. There is now: a file whose extension says text but whose bytes are not valid UTF-8 is REFUSED by name rather than written corrupt, so an allowlist that is wrong about a file fails loudly instead of quietly.
+
+  Nothing could see this. `voltro-templates`' own harness classifies files itself and copies non-text ones byte-for-byte, so `pnpm test:templates` was green over a rendering the scaffolder does not perform — it validated the harness, not the scaffold a user receives.
+
+---
+
+## [0.53.0] — 2026-08-26
+
+### ⚠ BREAKING
+
+- **@voltro/database, @voltro/runtime, @voltro/voltro** — `missingConflictColumns` takes the table — `(table, conflictColumns, row)` — and returns `{ column, reason: 'absent' | 'null' }` entries instead of bare names. The old signature structurally could not know which columns are DB-generated, so the upsert/insertIgnore guard built on it refused every write keyed on a stored generated column: a condition nobody can satisfy, since the database rejects an explicit value for a generated column and the framework's own stamping strips one. Such keys exist precisely to make a NULL-folding composite unique enforceable (`CASE WHEN ref IS NULL THEN 1 END` folding manual rows onto one value), so the guard refused exactly the schema shape it should protect — and the neighbouring `missingRequiredColumns` had carried the skip, with the reason written beside it, all along.
+
+  The guard's message now also separates the two bugs the flat list merged: an ABSENT key (`'x' is absent`) and a NULL one (`'x' is NULL — NULL never matches a unique conflict target, so this write would always INSERT; use a plain insert for NULL-keyed rows, or make the column NOT NULL`). They have different fixes, and the shared word "missing" sent a reader hunting for an absent field that was present-but-NULL.
+
+  Migration: pass the table definition (the value `missingRequiredColumns` already takes) and read `.column`/`.reason` off the results; `undefined` as the table means nothing can be recognised as generated.
+
+  **`voltro update` carries you across this** — codemod `0.53.0/01_conflict-columns-take-the-table`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.53.0).
+- **@voltro/client, @voltro/ui, @voltro/cli, @voltro/web** — `useFormBinding` carries a WHOLE form now, on a per-field engine behind the facade — the engine is an implementation detail (no engine type in the public API, pinned by a contract test; production builds stub its devtools channel). The old surface is unchanged; everything new is additive:
+
+  - **Nested values + sections.** A nested struct flattens into dotted fields (`address.city`) grouped under `section('address')` — no more `custom` placeholder. The no-JS POST rebuilds the nested object from dotted input names, so both submit paths agree. - **Field arrays.** `array('entries')` — push / insert / remove / move / swap + per-item field handles; arrays of structs carry item descriptors. - **Bound field handles.** `field('address.city')` returns value, setValue, onBlur, the display-gated error, touched/blurred/dirty, required, label, widget, options, and a11y props (`aria-invalid`, `aria-required`, `aria-describedby`) ready to spread onto any widget kit. - **Error timing a form can trust.** A form never opens with errors: a field reveals its error after ITS blur or after the first submit attempt, then live (`validate: { onChange: 'afterTouched' | 'always' | 'never' }`). `isValid`/`canSubmit` always tell the truth underneath. This changes VISIBLE behavior — errors used to appear only after submit; now blur reveals them earlier. - **`toInput` / `onSubmit` — values ≠ mutation input.** Map form values to the wire input before validation, route input-schema issues back to form fields via `errorPath` (same-name automatic), or own the composed save with the mutation handle in hand — optimistic + server-error routing kept. - **One `form.state`**: isDirty (interaction-based), canSubmit, isSubmitting, isSubmitted, isSubmitSuccessful, submissionAttempts, errorCount, firstInvalidPath, pending, isLoading, submitError, data. - **`reset(nextDefaults)`** switches the edited record without a remount; `focusFirstInvalid()` moves focus to the first visible error. - **Per-field rendering.** `subscribe: 'fields'` + `useFormField(form, path)` — a keystroke re-renders one field, not the page. - **Schema-declared structure.** `formField({ section, order, label, widget })` annotation, `description` → help text, `Schema.Date` / `Schema.DateTimeUtc` → date/datetime widgets.
+
+  The one compile-visible break: `WidgetKind` gained `'array'`, so an app registry typed as a TOTAL `Record<WidgetKind, Widget>` needs one new entry (the codemod note finds the shape). `reset` and `validateFields` only gained optional parameters.
+- **@voltro/client** — Client-side validation messages are STRUCTURED now — stable ids with params (`validation.required`, `validation.minLength {min}`), read from the ParseIssue tree (schema ids + annotations), not effect's English developer text ("Expected string, actual undefined"). The binding renders them through a built-in en/de catalog (locale from `<html lang>`, override via `locale:`), and `messages: (id, params) => t(id, params)` wires an app's own i18n catalog in one line — the regexes apps laid over the developer texts can go. A `message` annotation may BE an id (`'validation.between|{"min":2,"max":50}'`), and a struct-level `filter` returning `[{ path, message }]` lands each issue at ITS field.
+
+  Two observable changes: `errors` keys are now the FULL dotted path (`'address.city'`, `'entries.0.startsAt'`) instead of collapsing to the top-level segment, and the display strings differ from the old developer text. `validateFields` additionally returns the raw `issues` array for widget kits that translate themselves.
+
+  **`voltro update` carries you across this** — codemod `0.53.0/03_validation-messages-are-ids`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.53.0).
+
+### Added
+
+- **@voltro/plugin-comments, @voltro/ui, @voltro/devtools-ui** — `@voltro/plugin-comments` — comment threads anchored to anything the app can name (an order, a document, a section anchor), live over the existing reactive engine: `comments.list` declares a `reactivityChannel` as its `source:`, every write publishes it, and a second client sees a new comment without a reload. No second push mechanism.
+
+  Access FOLLOWS THE ANCHOR, fail-closed: the app declares `access.viaEntity` (guard delegation — receives anchor, subject and the bound store, so the rule reads the entity's own row) or `access.scope`; with neither declared, every read and write refuses by name — a comments surface nobody opened serves nobody rather than everybody. A soft-deleted anchor is the same door: the guard cannot approve what it cannot read, so a stale mention notification finds "no longer available", not a leak.
+
+  Mentions are tenant-safe BY CONSTRUCTION, twice: the `resolveMentions` seam requires the calling subject in its signature and the plugin re-filters the result to the caller's tenant (opt-out `crossTenant`), and every mention is RE-validated at create time against the same resolver — a hand-crafted mention on a foreign tenant is dropped, never delivered. A validated mention sends through plugin-notifications when configured (preferences, quiet hours and digests apply — ten mentions in one window roll into ONE delivery, tested); without it, a log note and nothing else.
+
+  Also in the box: replies (anchor-pinned — a reply cannot smuggle into a thread on a different anchor than the access check ran for), resolve/reopen, author-only edit, delete with a `comments:moderate` scope override cascading reactions, per-emoji reactions aggregated with `count` + `mine`, per-subject thread unread (`markRead`; your own comments are never unread for you), `useComments`/`useThread`/`useMentionSearch` hooks, the ejectable unstyled `<CommentsThread>` in `@voltro/ui`, and a Comments panel in both dashboards. Moderation is honestly opt-in (one plugin-moderation rule, documented — no "automatic" claim).
+
+  Proven over the real wire (`scripts/comments-e2e.mjs`, real `voltro serve` + postgres + signed session subjects): A comments → B's ALREADY-OPEN subscription receives the new snapshot live; B's mention lands in the inbox (no self-notification); resolve at A arrives live at B; soft-deleted and missing anchors refuse; a cross-tenant mention delivers nothing. The docs site carries a LIVE demo (the real plugin against the docs demo backend). The declared limits are documented: attachments = storage-grant + URL, and the channel-wide reactivity granularity with the read-set work as the named narrowing.
+- **@voltro/content, @voltro/cli, @voltro/changelog** — Content collections (plan 03): `@voltro/content` — file-based, schema-typed markdown content without installing a markdown dependency.
+
+  `defineCollection` declares a folder (`content/<name>/**/*.md`) with an `effect/Schema` frontmatter schema in a `*.collection.ts` file. The isomorphic `getCollection`/`getEntry`: at build/SSR time the server reads the filesystem, decodes frontmatter (a violation FAILS the build naming the file), and renders markdown with dual-theme shiki; the build emits JSON artifacts under `dist/assets/content/…` that the CLIENT branch fetches on SPA navigations — no markdown engine, no highlighter, no content bodies in the browser bundle (proven by the fixture e2e's budget checks: 402 chunks → 9 after the split). Slugs come from the relative path; duplicates are build errors. Locale trees (`i18n: { locales, defaultLocale, missing }`) serve `de/` mirrors with per-collection fallback-or-404 policy. Rendered entries carry `headings[]` (depth/slug/text — the SAME ids stamped on the HTML, via one shared `extractHeadings`). `kind: 'data'` decodes `.json` files (authors.json). `reference('<collection>')` fields are validated by the build — a dangling reference names collection, entry, field and target. `config.feeds` builds RSS from a collection next to sitemap.xml and serves the same XML as a live dev route. `voltro dev` serves artifact shapes on demand and invalidates on `content/**` edits.
+
+  `@voltro/changelog` now CONSUMES the seam (frontmatter + render via `@voltro/content/markdown`, `renderReleaseRss` via the generic `buildFeed`); unlabelled fences render plain instead of guessing `ts`. An unexpected static-loader throw at build time now FAILS the build instead of shipping an empty page (it shipped a whole docs site as 646 empty pages under exit 0). The blog/docs/changelog templates run on collections; the docs site migrated with a script-proven equivalence over all 646 pages × both locales.
+- **@voltro/local-first, @voltro/database, @voltro/runtime, @voltro/protocol, @voltro/client, @voltro/cli, @voltro/plugin-row-history, @voltro/voltro** — CRDT beyond text: `crdtDoc()` stores a whole collaborative document as a column (same storage and doc-agnostic authoritative server merge as `crdtText()`, which stays as the plain-text specialisation), and `@voltro/local-first/editor` ships `useCrdtEditor` — a Tiptap binding (StarterKit + Collaboration + CollaborationCaret, all MIT, fully self-hosted; the paid Tiptap Cloud features are deliberately unused) over the new `CrdtDocHandle` (`createDoc`: the raw Y.Doc for the binding, `stateVector`/`encodeUpdateSince`, `onUpdate`, and `encodeAnchor`/`resolveAnchor` — the stable-position primitive inline comments pin threads with).
+
+  Wire amplification is fixed in BOTH directions. Upstream, offline edits coalesce per cell in the durable queue (1000 keystrokes drain as O(1) pushes) and a client push is an incremental update. Downstream, the new `mergeCells` patch op carries per-column incremental updates: the dispatcher diffs CRDT cells against the subscriber's previous state vector and the client folds them through `crdtMergeCell` — a one-character edit against a 100 KB document measured under 1 KB on the subscription wire, no op in the delta carrying the full blob.
+
+  Fold atomicity is pinned in layers in the one store wrapper: a per-row in-process mutex serialises concurrent folds completely on a single node, a verify-and-refold pass heals cross-replica interleaves, and the residual multi-replica window is a stated limit (descriptor-level `FOR UPDATE` is the named next step). Storage stays bounded: a fold's result soft-compacts past `VOLTRO_CRDT_COMPACT_MAX_BYTES` (default 512 KiB) without breaking the merge lineage; `rebaseText` is the explicit hard reset — a new epoch subscribers receive as a fresh snapshot.
+
+  The capture paths know CRDT columns now: undo capture strips them from update images and skips crdt-only updates entirely (client-side doc undo is the editor's Y.UndoManager), row history excludes them the same way (document version history is named snapshots taken BEFORE compaction), and both exclusions keep whole images on DELETE. Exposure rules are declaration rules: `.serverOnly()` on a CRDT column throws (a doc clients write but never read cannot be collaborated on); `.encrypted()` is the documented online-only decision. Carets ride a `delivery: 'latest'` event via `attachAwarenessBridge` — one member's state per envelope, measured far inside the event cap, never the aggregated room — deliberately NOT presence metadata, whose value-compare push would make every caret move a "real" change.
+- **@voltro/protocol, @voltro/runtime** — A write target declares its many-to-many relations now — and the framework writes the junction in the SAME transaction:
+
+  ```ts
+  target: {
+    table: 'employees', op: 'update',
+    relations: { assignedStores: 'employee_assigned_stores' },
+  }
+  ```
+
+  After the executor succeeds, `input.assignedStores` is reconciled against the junction through the diff-based link writer — inserted, deleted, and unchanged rows are exactly the diff, so reactive subscriptions on the junction see one change per changed row. The link writes go through `ctx.store`: undo capture and cross-table rules see them, and a failure rolls the whole mutation back. Semantics pinned by test: an ABSENT input field touches nothing (absent ≠ empty), `[]` is the explicit clear, a non-array refuses by field name, the row id is `output.id` else `input.id`.
+
+  Underneath sits the new `store.relationLinks(junction, table, id)` — the existing `links()` with its anchor COLUMN derived from the junction's `reference()` targets; a self-junction is refused by name, never guessed.
+- **@voltro/runtime, @voltro/protocol, @voltro/client, @voltro/cli, @voltro/voltro** — Delta-resume for subscriptions: a client that reconnects inside the resume window no longer pays for a full snapshot per query. The re-subscribe presents the last materialised revision in the per-call `voltro-resume-from` header (the same surface the idempotency key rides, read by the ONE shared auth-middleware builder so both boot paths agree), and the server — which keeps a resumable subscription alive server-side for the window after a disconnect, its emits recorded into a bounded per-identity delta ring — replays only the missed deltas and re-attaches the stream on the SAME revision line. The wire signal is the first event's tag: `delta` means resumed, `snapshot` means reset — no schema change.
+
+  The failure direction is fixed everywhere: a wrong snapshot costs bytes, a wrong replay would leak rows, so every doubtful case answers with a fresh snapshot. Concretely: the ring is keyed by query + canonical input + subject + tenant (a login/logout/tenant-switch between disconnect and resume simply never finds it); the per-delivery guard re-check keeps running on the detached subscription and a revocation while offline drops the retained history (plus one more re-check at the adoption boundary); row-filtered apps and computed queries are excluded from resume entirely; a non-chaining or out-of-window revision falls back to snapshot. Replayed deltas may coalesce exactly as slow-consumer updates do.
+
+  `@voltro/client` participates automatically: the reconnect-seeded cache keeps its rows AND revision, sends the header on the re-subscribe, applies a resumed delta onto the held base with no snapshot round-trip, and treats a snapshot-first stream as the reset it already knew. Tunables ride the shared resolver both boot paths call: `reactive.resume.windowMs` (default 60 s, env `VOLTRO_REACTIVE_RESUME_WINDOW_MS`) and `reactive.resume.maxDeltas` (default 256, env `VOLTRO_REACTIVE_RESUME_MAX_DELTAS`). Proven end-to-end against a real `voltro serve`: kill a live subscriber mid-stream, write while it is gone, resume — first event is a delta past the held revision, a post-resume write reaches the adopted stream live, a headerless control gets a snapshot, and past the window the same header gets a snapshot again.
+- **@voltro/cli, @voltro/web** — Font pipeline (plan 12). Declare local font files once (`fonts:` in the web `app.config.ts`) and get content-hashed self-hosting, `@font-face` with `font-display`, a SIZE-ADJUSTED fallback face (real metrics read via fontkit, capsize formula against Arial/Times — the swap moves nothing, CLS ≈ 0), a `<link rel="preload">` in the shell head, and opt-in unicode-range subsetting (`subsets: ['latin', 'latin-ext']` via subset-font, declared with matching `unicode-range`). Multiple weights/styles per family and variable ranges (`weight: '100 900'`) are first-class. `localFont('Inter')` in `@voltro/web` maps the declared family to its CSS variable/stack.
+
+  ONE memoized build feeds every surface: `writeEntryFiles` bakes CSS + preloads into the generated shell (served identically by dev, static prerender, SSR streaming and `voltro start`), the dev server answers the hashed files from the same memo, `voltro build` writes them into `dist/assets/fonts` — the shell's URLs and the files cannot disagree.
+
+  No font CDN request ever leaves a visitor's browser — the GDPR argument the docs carry (LG München), proven by e2e: a real chromium loads the page with ZERO foreign-host requests. Full e2e (`scripts/font-pipeline-e2e.mjs`): hashed woff2 in dist, subset measurably smaller than the source, @font-face + fallback face + preload in the built HTML, dev parity, browser network assertion. Deliberately NOT built: a Google-Fonts download helper (license terms are per-family — the manual path is documented).
+
+  fontkit + subset-font ship as optional dependencies of @voltro/cli (script-free, verified — the plan-11 decision inherited); without them fonts still self-host and the metrics/subset halves degrade with one named warning each, plus a `voltro doctor` rule naming which half is missing.
+- **@voltro/client, @voltro/ui** — The form contract, made seamless where it still had seams:
+
+  - **App-wide message wiring.** `<ValidationMessagesProvider messages={(id, params) => t(id, params)}>` once at the root resolves every form's schema ids AND server ids (`ctx.validation.fail`) through the app's i18n catalog — the per-form `messages:` option still wins, `undefined` falls through per id. - **`toInput` is compiler-checked.** The typed `useFormBinding` has two shapes now: without `toInput`, form values ARE the mutation input; with it, the form gets its own `Values` shape and the mapper's return is checked against the mutation's input — a mapping that stops producing the wire shape is a type error. - **`<AutoForm>` renders the structure the schema declares.** Nested structs become real `<fieldset>` sections with legends; widget props come from the FIELD HANDLE, which fixes a real defect the audit found — a dotted field's value was read as a flat property, so nested inputs rendered permanently empty. Widgets receive `onBlur` (all built-ins forward it), so the reveal-on-blur timing works in AutoForm exactly as in the headless binding; `reference` reaches registry widgets for query-bound pickers. - **Proven over the real wire** (`scripts/forms-e2e.mjs`, real `voltro serve` boot): a `ctx.validation.fail` refusal arrives as a TYPED `ValidationError` with its field and message id, and a target's declared `relations:` reconciles the junction end to end — set, diff, absent ≠ empty, explicit clear — with an executor that never touches the junction.
+- **@voltro/cli, @voltro/runtime** — The opt-in gRPC surface — an external client generated from the framework-emitted `.proto` calls a named Voltro procedure: unary for mutations/actions, server-streaming (live current-snapshot frames) for queries. Nothing re-implements the wire semantics: a gRPC call runs the SAME bound runner every other surface uses, so guards, the plugin interceptor chain (order proven side-by-side against a socket call in the e2e) and typed errors behave identically.
+
+  `app.config.ts` `grpc: { port, procedures: [tags], tls? }` — nothing exposed by default, every tag named, a phantom tag refuses the boot. The `.proto` comes from the procedures' own `effect/Schema` via a checked-in `grpc.manifest.json` whose FIELD NUMBERS are append-only: an inserted field never renumbers its neighbours, a deleted field's number goes `reserved` (emitted into the proto), and reusing a reserved number is a codegen error — the one gRPC trap that silently corrupts old clients. proto3 presence maps `Schema.optional` AND `NullOr` to the `optional` keyword (absent and null are one wire state, documented); the unmappable (shape unions, tuples, recursion, free-form objects) is a loud per-procedure error naming the schema path.
+
+  The status table is COMPLETE against the wire error union, with the two non-failures distinguishable in trailers: `ScopeError` → `PERMISSION_DENIED` (or `UNAUTHENTICATED` for a credential-less caller), schema-invalid input → `INVALID_ARGUMENT` (the bridge decodes the proto-deserialized request against the descriptor's input schema — proto3 suppresses defaults, so skipping that decode fails much later as a DB constraint), `BusinessRuleViolation` → `FAILED_PRECONDITION` + `voltro-error: rule`, and a PENDING `requiresApproval` — a flow outcome, not a failure — `FAILED_PRECONDITION` + `voltro-pending: approval` + `voltro-approval-id`.
+
+  Deadlines INTERRUPT the work: `grpc-timeout` aborts the executor's fiber through the new `ServeRequestContext.signal` (honoured at the one place the executor effect runs to a promise), pinned by an e2e where a 300ms deadline on a 2s action answers `DEADLINE_EXCEEDED` and the post-sleep write never lands. Streaming rides the dispatcher subscription binding (per-delivery guard re-check included) with grpc-js write backpressure — frames coalesce to the latest snapshot instead of buffering unboundedly. `grpc.health.v1` + server reflection mount automatically; the gRPC packages are script-free optional dependencies (Apache-2.0), and a configured block with them missing refuses the boot by name. Also fixed on the way: the query subscriber's error events now keep a tagged error's `_tag` (it was collapsed to `{ message }`, blinding SSE consumers and the gRPC mapper alike).
+
+  Declared v1 limits, with alternatives: no client/bidi streaming, no gRPC-Web (browsers use the framework's subscription protocol), no Connect protocol (REST/OpenAPI projection is the answer there), and `*.stream.ts` procedures are not exposable.
+- **@voltro/cli, @voltro/web** — Build-time image pipeline (plan 11). `import hero from './hero.jpg?image'` turns a static asset into an `OptimizedImageAsset`: every ladder width up to the intrinsic width encoded as AVIF + WebP plus a same-family fallback, hashed into `dist/assets/`, with intrinsic width/height and a 16px blur data URI. `<Image src={hero}>` renders a `<picture>` with per-format sources — dimensions and blur inferred, `placeholder="blur"` the default. The suffix is an explicit opt-in: bare image imports keep Vite's URL semantics untouched.
+
+  Transforms run through a persistent cache (`.framework/image-cache/`, bounded concurrency) — the second build re-encodes nothing (proven: `scripts/image-pipeline-e2e.mjs` asserts zero cache-file rewrites on build two, plus `<picture>`/srcSet/blur/dimensions in the prerendered HTML and a real chromium decoding a transformed WebP from the dev endpoint). In dev, `/_voltro/image/<assetId>` transforms on demand and answers ONLY for manifest-registered assets; `voltro start` serves build artifacts with no transform endpoint at all (deliberate — no production transform-DoS surface).
+
+  sharp ships as an optional dependency of @voltro/cli — auto-available, install-failure-tolerant, and script-free since 0.33 (prebuilds ride `@img/*` platform packages, so pnpm 10's build-approval gate does not apply; measured, correcting the plan's assumption). Without a working sharp the pipeline serves originals with ONE loud warning naming the fix, and `voltro doctor` distinguishes "not installed" from "installed but platform binary missing" (the omit-optional install). Tunables: `images.{formats,quality}` in the web `app.config.ts`; per-`<Image>` `quality` flows into the CDN loader seam, which stays the answer for dynamic/remote `src`.
+
+  `apiSurface: compatible` — additive: `OptimizedImageAsset` + `ImageLoader.quality` + the `quality` prop on `@voltro/web`, the `images` config block, and the new CLI modules.
+- **@voltro/web** — Intercepting routes (plan 22): the modal-with-URL pattern. A page exporting `intercept: { from: '/photos' }` renders as an OVERLAY above the still-mounted origin page on a soft navigation from a `from` route, standalone on a hard load (and on soft navigation from anywhere else), and closes on Back — with the background's mounted state, scroll and subscriptions untouched.
+
+  The architecture is the surgical variant of the dual-tree model: the router's single committed chain becomes the BACKGROUND tree (its render pathname held on the bottom of a background stack persisted in `history.state.__vwebBg`), and each overlay level is a second, narrow render path — own match, own page-loader state (through the SAME LoaderCache key a standalone visit and prefetch warm), own RouterContext provider. Nested modals stack; a replace inside a modal (a `useSetSearchParams` tweak) carries the stack forward instead of wiping it; a hard load IGNORES a surviving stack, because the server rendered standalone and hydration must match.
+
+  Behaviour changes that ship with it: `useBlocker` now guards POPSTATE — the Back gesture is a modal's primary close, and it previously bypassed every blocker (the router reverts the moved URL via an entry-index delta and offers retry/reset; ESC in the overlay routes through the same path). `useSearchParams`/`useSetSearchParams` read and write the CALLING TREE's query — a background component can no longer decode the modal's query against its own schema or write onto the modal's URL. Navigation scrolling moved to the visual commit, so an overlay open never scrolls the background. The overlay slot is ALWAYS rendered (null when closed) through the shared provider tree, keeping server/client fiber arity identical (the useId class). The overlay chrome is a native `<dialog>` via `showModal()` — platform focus trap, backdrop and focus restoration; body scroll locked while open; deliberately unstyled (`dialog[data-vweb-overlay]`).
+
+  Declared non-goal: Next's parallel `@slot` routes — split panes are components in a layout, not a routing concept. Islands/zero-JS pages don't intercept (no client router). Proven by 6 jsdom router tests plus `scripts/intercept-e2e.mjs` on an ssr fixture: standalone SSR HTML with per-photo title and zero hydration warnings, overlay over a mounted background (typed input + mount counter survive open AND close), per-tree search params, nested modals with topmost-only Back, popstate blocking with discard, reload-renders-standalone, and a dev-parity smoke.
+
+  Measured price: the router group grew 1.5 KB gz (10.5 -> 12.0 KB, the whole first-load delta of this change) -- the overlay stack, popstate blocking and per-tree search params; every other bundle group moved by noise only. The bundle budget is re-pinned to that number.
+- **@voltro/local-first, @voltro/client, @voltro/cli, @voltro/plugin-presence** — The local-first sync engine. A `localFirst()` table's data is now offline readable, editable and convergently resynchronised — through the primitives apps already use, not a second data API.
+
+  READS: the subscription cache accepts a mirror; every base movement of every subscribed query persists (rows + revision) into a subject+tenant-PARTITIONED IndexedDB store, a cold start seeds `useSubscription` from it (offline reload renders the last materialised rows), and the next connect presents the mirrored revision as `voltro-resume-from` — composing with delta-resume. Deliberately NOT a browser SQL engine: the client's query surface is `(tag, input)`, predicates never exist client-side, so the mirror stores materialised results per query behind a `KvStore` seam (a SQLite backing stays possible without touching a consumer). Soundness is structural: partitioning lives in the KEY (a new subject never finds the predecessor's rows; `purge()` on logout/revocation), `.encrypted()` columns are stripped before every save via codegen-emitted metadata (`voltro dev` writes a zero-import `.framework/localFirst.generated.ts`), a snapshot save REPLACES the row set (revoked/deleted rows evict by construction), and entries gate on a build `schemaFingerprint` — a new build's load is a visible cold start, never a mixed-shape render.
+
+  WRITES: `useOutbox` gains durability (`persistence:` seam; the one real implementation is `outboxPersistence()` over the same `PersistenceAdapter` the sync queue drains — one durable queue per device) and conflict resolution: `resolveConflict(id, input)` returns a conflicted entry to pending with the resolved input, typically computed by `resolveWithPolicy()` — `crdtText()` columns MERGE, scalars follow the declared `conflictPolicy()`, convergence proven side-symmetric. Multi-tab safety via `withDrainLock` (an exclusive per-partition Web Lock; a host without the API drains unlocked and reports it). Presence rides ONE wire: `usePresenceChannel` in plugin-presence/web adapts the local-first `PresenceChannel` onto the framework's existing presence lane instead of a second transport.
+
+  Proven end-to-end in a REAL chromium against a real `voltro serve` (`scripts/browser-local-first.mjs`): online seed → 5 offline edits → page RELOAD (queue survives in real IndexedDB, order preserved, mirrored rows render) → drain under the real Web Lock → server and a second browser context converge on all 6 rows; two tabs race the lock and exactly one drains; a foreign subject's binding reads nothing and purge empties exactly one partition.
+- **@voltro/cli** — OG-image generation (plan 13). A page declares its `og:image` as a satori JSX template (`export const ogImage = ({ params, loaderData, locale }) => …`); `static` pages bake the PNG at build time — hashed into `dist/assets/og/`, `og:image`/`twitter:image`/`twitter:card` injected with the absolute `seo.siteUrl`, the page's own `og:image` meta winning over the generated tag — and `ssr` pages serve it on demand over `/_voltro/og`, ONE builder mounted by `voltro dev` AND `voltro start` (head injection lives in the SHARED head builder, so the streamed arm a plain ssr page takes cannot drift from the buffered one — it did, for one commit, and the parity e2e is what caught it).
+
+  The on-demand URL is signed: HMAC-SHA256 (timing-safe compare) over route + params + tenant + locale — tampering answers 403, tenant/locale ride the signature AND the cache key, and the PNG caches in the same IsrCache backend as the page cache. Secret handling is conditional by design: a single process mints a per-boot secret (sign and verify happen in the same process); a DEPLOY boot with ssr `ogImage` pages and no `VOLTRO_OG_SECRET` refuses loudly — behind a load balancer the signing and the fetching replica differ, and a per-boot secret would 403 every cross-replica fetch. Never a default value.
+
+  Preconditions are decided, not improvised: a declared `fonts:` family is REQUIRED (the renderer reads the ORIGINAL un-subsetted files; no bundled default font — that would ship a license artifact) with a named error naming the fix; emoji are a declared limit (satori's emoji path is a per-glyph CDN fetch — use an image/data-URI in the template). satori (pinned to an aged release — the workspace's minimumReleaseAge gate is policy) and @resvg/resvg-js ship as script-free optionalDependencies.
+
+  Proven: renderer core 4/4 (real PNG, size flow-through, distinct-template proof, font refusal), signed route 4/4 (cache HIT, 403, tenant variants render DIFFERENT images, signature-is-not-access), and the `font-pipeline-e2e` extension — build §1b (PNG in dist + absolute tags), dev §2b and `voltro start` §5 (signed URL in the ssr head, PNG, HIT, 403) all green.
+- **@voltro/web, @voltro/cli** — Partial prerendering (plan 20): an isr page that exports `ppr = true` combines a cached, ANONYMOUS shell with per-request dynamic holes on the same response.
+
+  The design decision, made against React's actual capabilities: a cached stream prefix cannot be RESUMED in stable React (postponed state is experimental), so ppr is client composition on the existing `defer()` seam. The shell is the normal buffered isr render — eager fields in the HTML, each hole as its `<Await>` fallback, cached as a plain IsrCacheEntry (no cache shape change, same revalidate/CDC/on-demand invalidation). On every serve (hit, stale, miss) the response stays open after the shell bytes: the page loader runs again with the FULL request context and each deferred field is appended as a registry settle script the moment it resolves. The client reveals holes through hydration.
+
+  The shell render is fail-closed, not merely stripped: its loader context and `useServerRequest()` snapshot THROW by name on credential access (cookie, authorization, x-voltro-*; any cookie but voltro:locale) — the first request answers with an error naming the read and the fix ("move it into a deferred hole"), instead of baking silently-empty subject data into an artefact served to everyone. Holes are async functions; their credential reads happen inside the promise and see the real request only on the hole pass.
+
+  Static + ppr stays refused (a static file host cannot append anything — isr with a long revalidate is that page); ppr requires `interactive: 'full'`; layout loaders cannot defer on a ppr page (v1); csp nonces are refused as on isr. `voltro dev` mirrors the whole behaviour through the shared `pprRender.ts`. Proven end-to-end by `scripts/ppr-e2e.mjs` with a FILE-GATED hole (deterministic, no timing waits): shell chunk received while the hole is provably open, settle script after the gate opens, per-subject hole content with a byte-identical subject-free shell prefix across subjects, cache HIT on the second request, the named 500 for an eager credential read, dev parity, and a browser client-navigation rendering the hole via the client defer path.
+- **@voltro/plugin-presence** — `presencePlugin({ resolveMember })` — resolve the fields other channel members see about a caller (display name, avatar URL) server-side, from the authenticated subject. `meta` is client-supplied and handed to every channel member verbatim, which is the right contract for a cursor and the wrong one for identity: any member could present any name and any `<img src>` to everyone else. The resolver runs on every heartbeat and its result merges OVER the caller's `meta`, so a client cannot override what the server says about them; returning `undefined` declines and leaves `meta` untouched. The docs and the package description now say plainly that `meta` is unvalidated and relayed verbatim — identity does not belong in it.
+- **@voltro/plugin-queue, @voltro/cli, @voltro/devtools-ui, @voltro/plugin-cdc-out, @voltro/sql-postgres, @voltro/sql-mysql, @voltro/sql-mssql, @voltro/sql-sqlite** — `@voltro/plugin-queue` — interop with a Kafka an adopter already runs, as the door to foreign queues (the outbox stays the path for your OWN durable side-effects, workflows for your own orchestration). Kafka first; the `QueueProvider` contract is cut so SQS/RabbitMQ can be later implementations.
+
+  Consuming is a file convention: `*.consumer.ts` exports a `defineQueueConsumer({ topic, schema, handler })`, discovered on BOTH boot paths and started at plugin activation. The semantics are deliberate and documented: at-least-once with per-message commit (a process killed mid-batch redelivers exactly the unhandled tail), serial per partition (parallelism only ACROSS partitions; retry backoff blocks the partition on purpose), decode failures dead-letter immediately to `<topic>.dlq` with `x-voltro-dlq-*` reason headers (a deterministic failure retried forever is an infinite loop with extra steps), handler failures retry with backoff then dead-letter after `maxAttempts`, and a rebalance is never counted as a failure. Handlers get `ctx.store` but are NOT transaction-wrapped (the HTTP-handler boundary) and must be idempotent. Replica coordination is Kafka's own consumer group — no advisory lock, unlike schedules, which have no broker to do it for them.
+
+  Producing: transactional-with-a-write goes through the existing outbox (`ctx.outbox.enqueue('queue.produce', …)` + a `queueOutboxHandler()` bridge file — one durability path, not a second), fire-and-forget through `QueueService.produce`. Topic creation is EXPLICIT (`ensureTopics`) — whether a client may create topics on foreign infrastructure is the adopter's policy; a consumer on a not-yet-existing topic warns and retries in the background, never aborting the boot. `kafkaSink` plugs cdc-out table mirroring into the same provider (key = row id, `x-voltro-delivery-key` dedupe header).
+
+  Observability: `GET /_voltro/inspect/plugins/queue/consumers` + a Queue panel in both dashboards; `traceparent` flows from message headers to `ctx.traceparent`.
+
+  Found by the e2e (mutation → outbox → real broker → second process's consumer → row; kill a fleet member mid-flow → the survivor takes over with no duplicate row): the INSERT branch of `upsert` never stamped a generated `id`, so an upsert into an auto-id table failed on the NOT NULL constraint — in all four dialect stores. Fixed in all four (`stampGeneratedId` at the top of `executeUpsert`, as `insert` already did), pinned by a source-parity test; the default DO-UPDATE column set already excludes `id`, so a conflicting row keeps its identity.
+- **@voltro/client, @voltro/ui, @voltro/testing** — Three more pieces of the form contract:
+
+  - **Reference fields.** `formField({ reference: 'stores' })` marks a schema field as a table reference — `widget: 'reference'` carrying its target table, the value stays the id (or id list, feeding a target's declared `relations:`). The default registry renders the render-prop note (a live picker needs a query binding only the app can name); `WidgetKind` grew accordingly (covered by the 0.53.0/04 note). - **`formSections(fields)`** groups an ordered field list into contiguous sections, and `<FormSkeleton>` renders them — title rows included, so the placeholder has the SHAPE of the real form. - **`renderFormBinding`** in `@voltro/testing/client` drives the REAL binding against the fake api: fill / blur / submit / visible errors / state, with server field errors injected by simply throwing `ValidationError({ field })` from the mutation handler — the same routing path a production refusal takes. Needs jsdom; react-dom loads lazily so the non-form harness stays React-DOM-free.
+- **@voltro/web, @voltro/cli** — `<Script>` — third-party scripts with a declared loading strategy (plan 23). `afterInteractive` (default, injected after hydration, never render-blocking) and `lazyOnload` (browser idle via requestIdleCallback with the setTimeout fallback). Inline variant with a REQUIRED `id` as its dedupe key. Deliberately absent: `beforeInteractive` (the honest answer for a must-run-first script is a literal tag in the shell head — a preload link fetches but never executes) and `worker` (Partytown-class, its own decision).
+
+  Dedupe rides a PROCESS-GLOBAL registry (globalThis + Symbol.for — not React context, not module scope: islands entries are separate bundles and every island is its own hydrateRoot). A script is never unloaded; a re-mount of the same src/id injects nothing and re-fetches nothing, but `onLoad` fires again from the registry cache — the next/script remount bug class, pinned by e2e. Cache callbacks are cancelable microtasks so StrictMode's dev double-effect cannot double-fire a visible mount's onLoad.
+
+  Behavior per `interactive` mode is DECIDED: on `'none'` the bundle never ships so a `<Script>` can never fire — the build warns by name; on `'islands'` the page's static part never mounts — the build warns and the answer is moving the script into an `*.island.tsx` (it then loads when that island hydrates). CSP: an explicit `nonce` prop wins; otherwise the injector propagates the document's own nonce (SSR pages under the middleware's `cspNonce` get it automatically); static pages have no per-request nonce path — `'strict-dynamic'` or a hash policy is the documented answer.
+
+  Proven: 7 jsdom unit tests (dedupe, cached callbacks, id refusal, stubbed rIC + Safari fallback, nonce propagation) + a real-chromium e2e (`scripts/browser-script-component.mjs`, 11 checks: hydration-before-script ordering without sleeps, one request for two tags, remount onLoad without a second request, both build warnings asserted against a real `voltro build`).
+- **@voltro/protocol, @voltro/runtime, @voltro/client** — Server-side FIELD validation, end to end. `@voltro/protocol` gains the browser-safe `ValidationError({ field, message, params? })` and `ValidationErrors({ issues })` — the constructors the docs promised for several versions while no package exported them — auto-merged into every mutation's and action's wire error union (exactly like `ScopeError` and `BusinessRuleViolation`), so no descriptor ever declares them. Executors raise them through the new, always-present `ctx.validation`:
+
+  ```ts
+  if (await emailTaken(input.email)) {
+    return yield* ctx.validation.fail('email', 'validation.emailTaken')
+  }
+  yield* ctx.validation.require(input.startsAt < input.endsAt, 'endsAt', 'validation.beforeStart')
+  ```
+
+  `useFormBinding` now ROUTES them: the error lands in `errors[field]` (translated through the message catalog), the form stays editable, and `submitError` only ever carries what no field can — a banner listening there stops double-reporting every field refusal. A `BusinessRuleViolation` whose rule pinpointed a `field` routes through the same path; the one reader for all three shapes is `fieldIssuesOf` in `@voltro/protocol`, so a custom widget kit cannot disagree with `<AutoForm>` about which errors belong on a field. Store-opaque failures (unique violations without a rule) still surface as `submitError` — mapping them to a column is the declared next step, not silently half-done.
+- **@voltro/client** — `useFormBinding` closes two gaps between the docs' promise and the hook. `asyncFields` puts `useAsyncValidation` INTO the submit path: in-flight checks are awaited (bounded, default 5s, fail-closed to `validation.checking`), an `invalid` verdict blocks the submit with the message on ITS field — the uniqueness probe no longer runs beside the form while `submit` ignores it. And `createHooks` now types the binding: `useFormBinding('employees.update', …)` takes the tag as a literal, `values`/`defaults` and the submit output infer from the generated descriptor — same treatment `useSubscription`/`useMutation`/`useAction` already had.
+- **@voltro/runtime, @voltro/cli, @voltro/voltro** — Subscription socket backpressure (plan 01 phase 1). Measured first: a consumer that stopped reading retained EVERY event — 300 changes, 300 retained events, the producer never slowed — so one dead dashboard tab grew the process without bound.
+
+  Now a per-subscription outbox sits between the dispatcher's synchronous emit and the socket stream. A pump fiber awaits each event's acceptance; while the consumer is blocked, updates COALESCE onto the newest state and the next accepted event is ONE patch computed against the state of the last event actually handed over — patch continuity holds across any number of collapsed intermediates (proven by materializing the received events client-style and comparing against the final server state). Revisions jump forward under coalescing; wire-protocol.md documents the jump as normal, never a gap. Memory per blocked subscription is bounded by construction: one pending state, however far behind the consumer is.
+
+  The terminal policy is loud: a consumer persistently over `reactive.socket.maxBufferedBytes` (default 1 MiB) for `reactive.socket.overrunAfterMs` (default 10 s) receives a typed `SubscriptionOverrun` error event — carrying `bufferedBytes` and `maxBufferedBytes` — and the stream ends; the client re-subscribes for a fresh snapshot. Never a silent drop. Oversized events are telemetry, not a cap: over `reactive.socket.oversizedEventBytes` (default 256 KiB) the event is delivered normally, counted and WARN-logged with the query tag.
+
+  All three knobs live in `app.config.ts` under `reactive.socket` with env overrides (`VOLTRO_REACTIVE_MAX_BUFFERED_BYTES` / `VOLTRO_REACTIVE_OVERRUN_AFTER_MS` / `VOLTRO_REACTIVE_OVERSIZED_EVENT_BYTES`), resolved by ONE resolver both boot paths wire. Four metrics ride the shared snapshot the Prometheus exporter and the inspect Metrics panel read: `voltro_subscription_buffered_bytes`, `voltro_subscription_coalesced_total`, `voltro_subscription_overrun_total`, `voltro_subscription_oversized_total`.
+
+  `apiSurface: compatible` — additive: the outbox/tunables/metrics exports on `@voltro/runtime`, an optional `socket` block on `ReactiveConfigInput`, and an optional trailing parameter on `bindSubscriptionUntyped`.
+- **@voltro/plugin-notifications, @voltro/cli, @voltro/env, @voltro/protocol, @voltro/devtools-ui** — Web Push (VAPID) as a notification channel — `webPushChannel()` in `@voltro/plugin-notifications`: a browser subscribes once (`useWebPush()` + the shipped `sw.js`) and receives notifications with the tab closed.
+
+  The protocol layer is an own ~250-line implementation over `node:crypto` (RFC 8291 aes128gcm encryption + RFC 8292 VAPID ES256), pinned byte-for-byte against RFC 8291 Appendix A — no dependency tree for what is one HKDF chain, one AES-GCM call and one JWT. ONE secret, `VOLTRO_VAPID_PRIVATE_KEY` (a base64url P-256 scalar): the browser-facing public key is DERIVED from it, so a public/private pair can never desync. `voltro dev` mints it per project into the gitignored `.env.local` (the new `p256` mint encoding, and plugins can now declare their own mintables via `PluginEnvVar.generate`); a production boot with the channel configured and no key refuses by name.
+
+  Subscriptions live per subject AND per endpoint (`_voltro_notification_push_subscriptions`, unique on a sha256 endpoint hash — endpoint URLs can exceed the unique-index byte ceiling on mssql/mysql). Delivery is per endpoint and ISOLATED, and this fix reached the existing mobile `pushChannel` too: its old loop threw at the FIRST rejected token, aborting every remaining device's send and collapsing the outcome into one per-channel `failed` row. Both channels now implement `deliverDetailed`; the delivery log records one row PER ENDPOINT (`endpoint` column), the channel counts delivered when at least one endpoint was reached, and `pushChannel` gained `onTokenRejected(token, reason)` as the app-side prune hook. Web push prunes itself: a push service answering 404/410 deletes exactly that endpoint's row — the subject's other browsers keep receiving.
+
+  Also in the box: payload cap handling (over ~4 KB the payload SHRINKS — `data` first, then the body truncates — never dropped), click tracking (a per-delivery token rides the payload; the service worker's `notificationclick` reports it and the record gains `clickedAt` — the token itself never reaches a dashboard reader), quiet hours / digests / preferences applying unchanged (preference key `webPush`), subject-bound subscribe/unsubscribe RPC mutations, and the dashboards' delivery panel showing per-endpoint rows + a clicked badge.
+
+  Proven twice, per the plan's split: a mock-push-endpoint suite asserts the VAPID JWT verifies against the derived public key, the body decrypts with the subscriber's keys, TTL rides the request, the oversize payload shrinks, and the 2-endpoints-1-dead case delivers one and prunes one; a real-chromium e2e (`scripts/webpush-e2e.mjs`) registers the SHIPPED service worker, delivers a simulated push over CDP, and asserts the event fires with the payload intact — and not at all after unregistering.
+
+### Changed
+
+- **@voltro/runtime** — Matcher authority for subscription wakes: a subscription whose query is a plain predicate read is now woken by the predicate index ALONE. The IndexedMatcher has always routed change events precisely (column, range and composite-tuple buckets, parity-pinned against a linear scan) — and its selectivity was then discarded, because every subscription was also registered as a dependent of its own table and the dispatcher unioned the two sets. Measured before: 200 of 200 subscribers whose predicate matched NOTHING were woken (and re-queried) by one write on their table. After: 0.
+
+  The soundness argument for authority: any change that can move a pure descriptor read's result involves a row whose OLD or NEW image matches the predicate — ordered limit/offset windows included, since a row shifting the window matches it itself. A per-delivery row filter does not break it either: the filter only ever ANDs onto the base predicate the matcher indexes, so a base-predicate wake is conservative (pinned by its own test). Everything the matcher cannot soundly judge keeps the conservative table-wide wake: queries with an eager spec, a setOp or a CTE (a self-referential eager collapses to "own table only" while reading rows the root predicate does not describe — the classification is structural, not set-based), `dependsOn` raw reads, computed and `reactivityChannel` queries, and OVERSIZED change events (`tombstone`/`unrecovered` images the matcher cannot see wake the whole table for that one event; `rehydrated` is judged normally — previously the `oversized` marker was read by nothing, hidden behind the same wildcard).
+
+  Measured consequence (fanout-ceiling.mjs, three runs): the distinct per-user shape (`where userId = me`) now pays a bucket lookup plus ONE delivery per write regardless of resident subscriber count — flat, no longer ~22–29 µs per subscriber per write — so a selective `where` buys real headroom, and the ceiling is set by the shared all-match shape (0.37–0.41 µs/subscriber, ≈25–27k subscribers per node at 10 writes/s against 10% of one core). The ceiling script now FAILS if a never-matching subscriber is woken, so the wildcard cannot quietly return. Also new: a chaos test pinning that one stalled consumer among 500 healthy ones neither delays the healthy population nor grows the server (its backlog coalesces onto the newest state, bounded).
+
+### Fixed
+
+- **@voltro/data-transfer, @voltro/runtime** — The five framework tables the last two plugins added are classified for transfer.
+
+  `voltro data export --scope all` refuses to run until every framework table is either portable or environment-local, and the four comment tables plus web push's subscription table were neither. They are now:
+
+  - the comments, threads, reactions and read-markers are **portable** — they are what the app's users wrote, and moving them is the reason a transfer exists. - `_voltro_notification_push_subscriptions` is **environment-local**. A browser push endpoint is bound to the deployment that minted it: the `applicationServerKey` the browser subscribed with is derived from `VOLTRO_VAPID_PRIVATE_KEY`, so a push service refuses a delivery signed by any other one. Importing a foreign row makes the target attempt a delivery that must fail — and the auto-prune then deletes a subscription that was valid where it came from.
+
+  Also: one composite map key carried a raw NUL character instead of the `\u0000` escape, which made its file BINARY to every text tool. The runtime value is identical; what changes is that `grep` can read the file again.
+- **@voltro/runtime, @voltro/workflow, @voltro/plugin-ratelimit, @voltro/cli** — Two more ways a production stream got bare text between its JSON records, both now closed:
+
+  - **`Effect.log*` rendered through Effect's DEFAULT logger** — a multi-line `timestamp=… level=WARN fiber=#…` logfmt block — anywhere the framework runs an Effect runtime without the framework logger installed: the workflow/cluster engine, the plugin SQL runtime, the kv facade, the rpc server's own fibers, and every detached handler fiber (`Effect.runFork` starts from the default runtime, so a handler's `Effect.logInfo` never saw the server's logger). Every production runtime now carries `LoggerLayer` — once per runtime root, because a second replace in one fiber stack prints every line twice — so `Effect.log*` in user handlers, workflow executors and cluster internals renders as the framework's JSON in a pod and pretty on a TTY. - **Bare `console.*` in server-side packages**: the row-filter load failure (request and subscription paths) and the rate-limit shield's degrade-to-unlimited warning now log through scoped framework loggers. `awaitSignal`'s suspend hint routes through `Effect.logWarning` inside the workflow runtime instead of a console fallback.
+
+  The production-stream source guard now also pins both classes: no `console.*` in the server packages it watches, and no `ManagedRuntime.make` in a production command without `LoggerLayer`.
+- **@voltro/cli** — `voltro serve`'s `/_voltro/inspect/data/tables` now serves the MERGED table set (app entities + framework-assembled tables + analytics), as `voltro dev` always has. It served the app's entities alone, so `voltro check --url` — which reads that endpoint as its idea of which tables exist — reported a query whose `source:` names a framework table (`_voltro_agent_messages`, say) as a dangling-source ERROR against a live server, exit 1, while `--offline` said OK about the same declaration: the offline manifest assembles the framework tables itself, and the two modes contradicted each other. The full set was already computed a few lines above (the stale-`source:` audit refuses to run without it, for this exact reason) — the inspect surface just never received it. The masked data browser gains the same tables.
+- **@voltro/client** — Auto-optimistic `op: 'update'` now merges into a SINGLE-OBJECT cache entry — a `*.getById` read — exactly as it merges a list row, and `op: 'delete'` empties one to `null`. The reducer's list handling fell through `Array.isArray(current) ? current : []` for a single object, so a two-field PATCH replaced the whole row until the server snapshot arrived: for ~400ms a detail page rendered only the patched fields — no assignee, a `createdAt` of "Invalid Date", nothing the input did not carry. The doc sentence "update merges by id" now holds for both shapes it covers; a patch whose id does not match the cached object leaves it untouched, and the same rule applies to a single object at a nested target path.
+- **@voltro/runtime, @voltro/cli, @voltro/voltro** — Two optional-parameter declarations that were not optional enough.
+
+  **`MutationLike.descriptor.target.relations`** was declared `relations?: Readonly<Record<string, string>>` while every sibling field in that interface carries `| undefined`. With `exactOptionalPropertyTypes` on, `relations?: X` REFUSES an explicit `undefined` — and `InsertTarget` types it exactly that way, so a concrete `DiscoveredMutation` stopped being assignable to `MutationLike`. One missing union member, 153 compile errors across `dev.ts` and `serveApi.ts`, and the CLI's whole boot path did not typecheck.
+
+  **`wrapCaptureStore`'s CRDT resolver** now defaults, like the one on `makeUndoCapture` that passes straight into it. Required there and optional here was the same information decided two ways inside one change, and the required form turned a two-argument call that compiled into one that does not — for a `@public` export the umbrella re-exports as `voltro/server`. Omitted means "no CRDT columns", which is what a caller written before the feature meant. The deliberate parity guard is unaffected: `undoCaptureDep` still REQUIRES its resolver, by design and with the reason written at the declaration.
+
+  Also here: `voltro serve` read a bare `schemaRegistry` at two sites where the registry lives on `opts` — the dev/serve copy, loud this time because it does not compile.
+- **@voltro/plugin-presence** — `usePresence` / `useTyping` no longer fire their join/heartbeat into the client-boot window of an SSR page. The mount effect called `mutate` against the not-yet-resolved api; the stub throws, the error escaped the effect as an uncaught pageerror (no boundary catches an effect), and the first join was simply lost — the member appeared only at the next interval beat. The hooks' own roster subscription is the resolution signal (it stays idle until the client is real), so the join is sent on the first snapshot — an empty roster counts — and the unmount leave is gated the same way.
+- **@voltro/logger, @voltro/cli** — In a `json`-format log stream (the default off a TTY, so every pod), EVERY line the framework emits is now a parseable record. Previously a production tail mixed JSON records with bare text from three sources: five subsystems whose serve-path wiring handed them hand-rolled `process.stdout.write('[tag] …')` adapters instead of the logger (schedule, broadcast, workflow ×2, flow-control — dev handed the real logger through, so every dev terminal looked right); the boot banner and app surface, which stripped their colours off a TTY and printed the multi-line layout anyway; and `voltro db apply`'s plan summary and refusal detail, rendered as terminal tables into a migrate job's stream.
+
+  `@voltro/logger` now exports `logFormat()` — the same pretty/json resolution the loggers use — and every report renderer consults it: on a TTY the banners and tables render exactly as before; in `json` mode each becomes one structured record carrying the same numbers as fields (the plan summary includes the per-op lines, the fingerprints and the rolling-deploy advisory). Refusals on the apply path carry their detail and fix as fields of the SAME record as their headline instead of raw lines under it. A source guard pins the `[tag]`-adapter idiom out of the production boot-path files so a sixth subsystem cannot reintroduce it.
+- **@voltro/cli** — **An unmatched path is a server-rendered 404 now, in both boot paths.** The best-matching `not-found.tsx` (deepest owning directory, group segments excluded — the same pick the client router makes) renders through the ssr arm with status 404 and `x-voltro-rendered-by: ssr-not-found`; an app without one gets a plain-text 404. Previously `voltro dev` served a 200 client shell for any unknown path — so crawlers indexed error pages, link checkers needed a browser to see failures, monitoring read "fine", and the user saw a shell and then the client-side not-found jump — and `voltro start` answered a bare text 404 without the app's page. One shared predicate (`bestNotFoundDir`), so dev and start cannot disagree about which file answers a miss.
+
+  **`voltro probe access` can judge procedures with required input.** It sent `{}` for every probe, so any guarded procedure whose input has required fields died in the decoder before the guard ran and probed `inconclusive` — measured at 704 of 914 on one deployment, 77% of the surface unjudgeable by the tool that exists to judge it. The probe now synthesizes a minimal payload from the SAME input schema the server enforces (read from the local checkout's descriptors; required scalars/enums/literals filled, optionals omitted). The old reasoning survives in the failure direction: when synthesis is impossible or wrong, the call dies in the decoder exactly as `{}` did and the verdict degrades to `inconclusive` — never to a false refused/admitted.
+
+  Also pinned: a NEW column and its FOREIGN KEY in the same plan land in ONE `db apply` (integration-tested against a real postgres — plan carries add-column + add-foreign-key + add-index, the re-plan is empty, the constraint is live). Reported long ago against an early planner and never re-measured; the round-trip test keeps the ordering from regressing into needing a second run.
+- **@voltro/cli** — `voltro update` can cross a package rename. The pin sweep bumped the OLD package name to the target version — a version never published under that name — so the install failed with `NO_MATCHING_VERSION`, and the codemod that performs exactly this rename sat inside the target version the failed install never put on disk. "Fix the install" was the rename; the user did the circle by hand.
+
+  Renames are now data (`packageRenames.ts`), and they ride the same published manifest the codemod preview already reads (`voltro.renames` beside `voltro.codemods`), so the OLD cli running the update learns the target's renames through the registry query it already makes — before anything is installed. The sweep then moves the dependency KEY and bumps the version in one write; a `workspace:`-pinned dep stays skipped rather than half-renamed. When the manifest cannot be fetched, the running cli's own rename registry is the fallback, and the install-failure message now names the rename circle so a user who still hits it knows the three manual steps.
+- **@voltro/cli** — `restRoutes` declared on a `type:'web'` app now REFUSES the boot (`voltro dev` and `voltro start`, one shared predicate) instead of being silently ignored. The silent form was the worst available behaviour: a readiness probe hitting a declared `/api/health` got the SPA shell with a 200 — green probe, handler never reached — a POST got 404, and call sites ran against a dead same-origin path with nothing anywhere saying the config was inert. The refusal names the fix: REST routes mount on the API process; same-origin paths belong to the ingress/proxy.
+
+  Also: `voltro secret generate inspect-write` mints the mutating-inspect second factor (`VOLTRO_INSPECT_WRITE_TOKEN`), and the 401 that demands it now names that command — the message named the header and the variable and left "where does the value come from" to guesswork. And a re-issued codemod note (`0.53.0/02`) reaches everyone who crossed 0.37.0 with `input: Schema.Struct({})` procedures: that shape flipped from accept-everything to reject-everything, which the original note never named — and a published note cannot be amended for anyone already past it.
+
+### Internal (no consumer-facing effect)
+
+- **@voltro/cli, @voltro/web** — Release-gate findings, all in guards or infrastructure — no runtime behavior changes: the OG-route signing separator is written as the `\u0000` escape instead of a literal NUL byte (a NUL makes the file binary to grep, so every text-based audit silently skipped it); the cookie-jar boot-path guard follows the ppr shell branch (`pprShellCookies` over the shared-render allowlist); the native-leaf rationale recognises prebuilt-platform-package natives (`sharp`/`@resvg/resvg-js` carry their `.node` in platform-triple optionalDependencies) and records `fontkit`/`subset-font`/`satori` as documented dynamic-import leaves (optional at build time, interop proven by the font/OG e2e); the `voltro data` e2e suites give their spawned CLIs an isolated HOME so `guardLive`'s machine-registry fan-out cannot see an unrelated live `voltro dev` the operator runs; and the CI/gate test stack starts `kafka-test` (with a broker-answering healthcheck), so the plugin-queue integration suite runs non-vacuously instead of loudly skipping.
+
+---
+
 ## [0.52.0] — 2026-08-25
 
 ### ⚠ BREAKING
@@ -68,6 +484,14 @@ _Changes staged for the next release accumulate here (rolled up from
 
   The codemod rewrites imports, the factory call sites and the options-type references, and prints the one step it cannot do — swapping the dependency in package.json.
 
+  **Upgrading FROM ≤0.51: swap the dependency BEFORE running `voltro update`.** Measured against the published packages: the 0.51 CLI's pin sweep bumps the OLD name to 0.52.0 — a version that was never published under that name — so the install fails with `NO_MATCHING_VERSION`, the codemod (which ships inside the target) never lands on disk, and the printed `--codemods-only` recovery fails on the same unresolvable pin (even `pnpm exec` is wedged until package.json is fixed by hand). Do this first, then update:
+
+  1. In every `package.json`: `"@voltro/plugin-versioning"` → `"@voltro/plugin-row-history"` (same range).
+  2. `pnpm install` (or your package manager's equivalent).
+  3. `voltro update` — the source codemod now runs normally and rewrites the imports/call sites.
+
+  From 0.52.0 on this cannot recur: package renames are DATA the update path applies before the install (`voltro.renames` in the published manifest, with the CLI's own registry as fallback).
+
 ### Added
 
 - **@voltro/cli** — `voltro doctor` now reports every declared `@voltro/*` dependency with no import site — the residue a migration off a framework package leaves in `package.json`, where it keeps getting installed, walked by `voltro update`, and read as evidence the package is in use, its breaking-change notes included.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-auth-oidc",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "Generic OIDC AuthStrategy for the Voltro framework. Discovers JWKS via the well-known endpoint or accepts an explicit URL. Covers Okta, Keycloak, Cognito, Azure AD, Google Workspace, and any other OIDC-compliant IdP that doesn't ship a first-party plugin.",
   "keywords": [
     "voltro",
@@ -33,7 +33,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/protocol": "0.52.0"
+    "@voltro/protocol": "0.54.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"