@voltro/plugin-auth-oidc 0.51.0 → 0.53.0

package/CHANGELOG.md

@@ -39,6 +39,362 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [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
+
+- **@voltro/protocol, @voltro/runtime, @voltro/cli, @voltro/web, @voltro/plugin-storage, @voltro/plugin-ratelimit** — The HTTP surface is complete — seven gaps closed, each proven against the real listener.
+
+  **Binary byte streams.** REST handlers return `bytes(stream, { contentType, contentLength?, contentDisposition? })` (lazy thunk form defers opening the source); plugin routes return `byteStream`. Piped, never buffered (a 256 MiB export streams with bounded heap), never compressed. Idempotency × stream is DECIDED: `streaming: true` on an idempotent method with an idempotency binding is a mount error (a stream cannot cache a replayable body — retries would 409 until the TTL); an undeclared stream releases its claim at return. Storage's full-object download rides the generic path now.
+
+  **Negotiated compression + conditional GET.** brotli/gzip negotiated with a compressible-type allowlist, 1 KiB threshold, `Vary: Accept-Encoding` always on compressible types — on the api's buffered responses AND `voltro start`'s HTML (`http.compression.{enabled,minBytes}`). The BREACH position is structural: `POST /rpc` responses are NEVER compressed. ISR keeps ONE uncompressed entry and compresses per hit. `voltro start` answers `If-None-Match` with 304 (weak md5 tags over the uncompressed body); REST routes can declare `etag: true` (GET, weak SHA-1 content tag).
+
+  **Raw WebSocket gateways.** `defineWebSocket({ path, auth, onConnection })` in a `*.ws.ts` file — for FOREIGN protocols (a Yjs provider, a device fleet); app realtime stays the subscription protocol. `auth` is required with no default: `'subject'` runs the same chain as rpc/SSR BEFORE the upgrade (401 while it is still http) and binds the connection to the credential's expiry (close code 4001); `'public'` is a written-down decision. Every gateway path joins the upgrade origin guard (cross-site WebSocket hijacking → 403). Teardown at construction; plain GET → 426; duplicate paths refuse the boot.
+
+  **Body caps everywhere.** The 8 MiB cap used to guard only `/rpc`; plugin routes read uncapped and webhooks read uncapped AND UTF-8-round-tripped (corrupting binary bodies — fixed, proven byte-for-byte). `http.maxBodyBytes` (env `VOLTRO_MAX_BODY_BYTES`), per-route overrides on `defineRestRoute` and webhook handlers; a shared path takes its group's widest override. 413 for both request shapes.
+
+  **Full method unions.** PATCH/HEAD/OPTIONS are first-class on plugin and REST routes; HEAD is admitted wherever GET is (RFC 9110) with the transport dropping the body.
+
+  **BREAKING — the interceptor chain is fail-closed.** A throwing `onHttpRequest` interceptor is a 500 + a log line now; it used to be swallowed, which let a crashed security gate silently stop guarding. The manual codemod tells interceptor authors where the decision lives: propagate (a gate) or catch-and-degrade-loudly (protection with a dependency) — plugin-ratelimit's httpShield now does the latter, so a Redis outage cannot become a self-inflicted API outage. No app-authored call sites change shape, hence `apiSurface: compatible` — the break is the error POLARITY of one plugin-author hook, carried by the manual note.
+
+  **Middleware response headers + CSP nonce.** `middleware.ts` can return `responseHeaders` (applied on every render response shape, both boot paths; prerendered static files are the documented proxy-side limit) and `cspNonce` — the framework stamps every script tag of that render (React's own included) while the policy header stays the middleware's. `isr` + `cspNonce` is refused loudly: a cached nonce is a lie the browser enforces.
+
+  Deliberate limits: no multipart parser on REST/webhook routes (the storage upload routes are the sanctioned file path); static-file response headers belong at the proxy.
+- **@voltro/plugin-row-history, @voltro/cli** — `@voltro/plugin-versioning` is renamed to `@voltro/plugin-row-history` — the name now says what it does.
+
+  The old name collided head-on with API versioning (versioned REST routes, `/v1` → `/v2`, sunset flow), which `defineRestRoute` now supports as a first-class `version:` field. What this plugin does is row history + time travel (`rowHistory` / `rowAsOf` / `restoreAsOf` / `diffVersions` over `_voltro_row_history`); every comparison table that filed it under API versioning was reading the name, not the feature.
+
+  Renamed with it: the factory (`versioningPlugin` → `rowHistoryPlugin`), the options type (`VersioningPluginOptions` → `RowHistoryPluginOptions`), and the default instance alias (`versioning` → `row-history` — the inspect endpoint path and boot-log lines; an explicit `alias:` you passed is untouched). The table name (`_voltro_row_history`) and `VOLTRO_ROW_HISTORY_TTL_HOURS` already carried the new name: no data movement, no env change, no migration.
+
+  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.
+
+  Scoped to `@voltro/*` deliberately (third-party packages have too many legitimate no-import shapes), and three states are distinguished and printed: exempt by name with a reason (`@voltro/cli` is the binary, `@voltro/devtools` is mounted by `voltro dev`, `@voltro/sql-*` drivers are loaded from config); not-measurable-yet for `@voltro/client`/`@voltro/web` on a tree where codegen has never run (a missing measurement, not a dead dependency); and unimported — advisory, never fatal. A mention in a comment or an error string does not count as an import, and a commented-out import counts least of all: it is the artefact the rule exists to see past. Also in `voltro doctor --json` under `unimportedDeps`, `null` when no `package.json` could be read.
+- **@voltro/web, @voltro/cli** — Islands now save real bytes — every `interactive: 'islands'` page gets its OWN browser entry.
+
+  Measured on the reference fixture (pinned in `bundle-budget.json`, 2026-08-25): an islands page's first load is **59.6 KB gz** against **181.9 KB gz** for a fully hydrated page — react + the island runtime + that page's islands, no router, no Effect runtime, no subscription cache. The bundle-budget gate pins a hard <70 KB bound AND the ratio (<50 % of a full page), so a regression that re-couples the entries fails loudly.
+
+  - **`@voltro/web/islands`** is the new react-only subpath — `island()` and the hydration runtime import only react + react-dom/client. Importing the `@voltro/web` BARREL (or `@voltro/i18n`) anywhere in an island's import graph is now a BUILD error naming file and specifier: an island hydrates provider-less, router hooks and `useT()` throw there anyway, and the barrel would pull the Effect runtime into the slim entry. - **The build finds each page's islands** through its relative import graph (transitively, through components in between) and emits one shell + entry per islands page. `interactive` must be a source LITERAL to select the slim entry — a computed value ships the full entry as before, and the build says so. - **All three paths**: `voltro build` (SSG renders into the per-page shell, main-shell stylesheets folded in), `voltro start` (ssr/isr islands routes serve their shell), `voltro dev` (same mechanism on demand — violations fire in dev, not first in CI). Fixed on the way: a STATIC islands page fell through dev's render gate to the SPA fallback and loaded the full app entry — dev now server-renders it like production. - **Framework islands**: an island importing `@voltro/client` (`useSubscription`, …) is detected — that page's entry boots the rpc client and wraps each island root in `VoltroRuntimeProvider`, so the island receives live data. Presentational pages never pay for the client core. - **`hydrate: 'only'`** (Astro's `client:only`): the server renders an empty placeholder — a browser-only lib touching `window` in render no longer crashes the SSR pass — and the client mounts fresh with `createRoot`. - **Island props are declared lossy where they are**: props cross an HTML attribute as JSON, so a `Date` arrives as an ISO string and `Map`/`Set`/ functions do not arrive at all — dev warns naming the island and prop. - The per-island `manualChunks` rule is gone: with per-page entries as additional rollup inputs it MERGED the shared react modules into the island group (a second-React-instance shape); per-island chunks were also redundant — the entry already scopes to the page's islands, and they were statically preloaded anyway.
+
+  Limits: an islands page reached via SPA navigation from a full page runs in the already-loaded app bundle (the saving applies to hard loads of the islands page); a page's islands share one entry (hydrate strategies control WHEN each hydrates, not when it downloads).
+
+  Why the golden churn is compatible: `hydrate: 'only'` widens a union, `hydrateIslandsOnPage` gains an optional options argument, and the subpath is a new export.
+- **@voltro/ui, @voltro/client, @voltro/web, @voltro/cli** — Forms without JavaScript — `<AutoForm>` on a server-rendered page now works with JS disabled, end to end.
+
+  The form always renders `action="/form/<mutationTag>"` + `method="post"`; with JS alive, `onSubmit` intercepts exactly as before (optimistic rpc path unchanged). The `/form/*` endpoint is mounted by the WEB listener on BOTH boot paths (`voltro dev` and `voltro start`, one shared builder):
+
+  - **Origin-checked at the door** with the same `classifyRequestOrigin` the api's rpc listener runs — a cross-origin form POST is a 403 before a byte of the body is parsed. (The server-side forward reaches the api as a no-browser-origin request, so the web listener's check is the one that guards this surface.) - **One validation path.** The urlencoded body maps through the schema-driven `formDataToInput` (checkbox present/absent → true/false, `''` on number/date omits the field — never a silent 0 —, repeated keys → arrays, non-numeric strings pass through RAW so the decode fails honestly instead of minting NaN, unknown keys dropped) and validates with the SAME `validateFields` the client-side submit runs — byte-identical field errors. - **PRG on success**: 303 back to the submitting page, or to `<AutoForm redirectTo>` (same-origin relative paths only — anything else is refused, a hidden field must not become an open redirect). Reloading the redirected-to page cannot resubmit. - **422 re-render on validation failure**: the referring page renders in the same response with field errors + submitted values in the SAME error UI (`role="alert"`, aria unchanged), `cache-control: no-store`, bypassing the ISR cache in both directions. An rpc refusal after valid input (guard, server error) renders as a form-level error. The flash also embeds as a JSON script, so a page whose bundle arrives late hydrates to the identical state. - **Valid submits forward server-side over `POST /rpc`** with the request's cookie — auth middleware, guards and the rpc interceptor chain run identically to every other mutation.
+
+  New `<AutoForm>` props: `formKey` (several forms per page — the 422 re-render re-fills only the submitted one), `redirectTo`, and `action={false}` for purely static deploys where `/form/*` does not exist. Headless: `useFormBinding` gains `flash` + `formError`, `@voltro/web` gains `useFormFlash(formKey)`.
+
+  Also fixed on the way: a required `Schema.Boolean` field with no default used to block the JS submit as "missing" while its checkbox rendered visibly unchecked — boolean fields now seed `false`, agreeing with what the user sees (and with the no-JS mapping).
+
+  Deliberate limits: the no-JS error re-render needs an `ssr`/`isr` page (a static page cannot be re-rendered with request state; a minimal error page is the fallback); a purely static deploy has no `/form/*` endpoint (use `action={false}`); file uploads stay JS-only (multipart → 415). On an ssr page pass `schema` explicitly — descriptor resolution is a client-runtime feature and the SSR render would otherwise show no fields.
+
+  Bundle note: the `serverContext` chunk group is renamed `serverRequest` by the context's move to @voltro/client — identical 190 B gz, re-pinned in `bundle-budget.json` (fresh full measurement 2026-08-25: firstLoad 185,494 B gz, was 185,309 — +185 B from the form-flash read in the request context).
+
+  Why the golden churn is compatible: every addition is a new export or an optional prop; `FormBinding.formError` is a new member of the hook's RETURN type (nothing in the public API accepts a caller-built `FormBinding`), and `ServerRequestContextValue.formFlash` is optional.
+- **@voltro/runtime, @voltro/cli, @voltro/cms, @voltro/plugin-broadcast** — On-demand ISR revalidation — the third invalidation axis next to time (`revalidate`) and CDC (`cacheInvalidatesOn`). Server code in the api process calls `revalidatePath('/blog/[slug]')` / `revalidateTable('posts')` / `revalidateTag('pricing')` (exported from `@voltro/runtime`; callable from mutations, actions, webhook receivers and REST routes) and the matching ISR cache entries fall on EVERY `voltro start` replica — including on dialects with no CDC at all, which is the case this exists for.
+
+  Transport is dialect-shaped, either or both: on postgres a `pg_notify` rides the SAME LISTEN connection the CDC invalidator already holds (no broker needed); everywhere else the broadcast broker carries it (`BROADCAST_URL` on both deployments; channel namespaced by `VOLTRO_BROADCAST_NAMESPACE` — deliberately env-derived, because this channel pairs an api with its WEB app and no shared name is derivable). A web process with isr routes and neither transport warns loudly at boot; under `voltro dev` the calls are documented debug-logged no-ops. Tags share ONE mechanism with tables — `cacheInvalidatesOn` accepts free strings, so `revalidateTag` is the same sink under another name.
+
+  Correctness edges built in: `revalidatePath` against a `static` route is a NAMED error on the web process (never a silent no-op); a purge landing while an SWR refresh or miss fill renders is guarded by a per-key generation counter on BOTH cache backends — the pre-purge page cannot be written back with a full TTL, and a refused write also suppresses the postgres backend's fire-and-forget upsert so no replica resurrects a deleted row. A content type declares `revalidate: { paths, tags }` and `publish()`/`unpublish()` fire them after commit.
+
+  Proven end-to-end (`scripts/revalidate-e2e.mjs`): 1 api + 2 `voltro start` replicas behind Redis (warm → purge → both fresh, with a negative control), the sqlite dialect leg, and a broker-less postgres leg where the NOTIFY line alone carries the purge to a LISTEN-only replica.
+
+  `apiSurface: compatible` — additive only: the new `@voltro/runtime` revalidation exports, an optional `revalidate` on `ContentTypeSpec`, the optional `onRevalidate`/`revalidateChannel` on the CDC invalidator options, a widened `BroadcastChannelKind`, and `IsrCache.set`'s new optional generation guard (plus `generation()`).
+- **@voltro/protocol, @voltro/plugin-openapi** — `defineRestRoute` takes an opt-in `version:` — versioned REST APIs with a sunset flow.
+
+  `version: 'v2'` + `path: '/customers'` mounts the route at `/v2/customers`, the same `/vN/` convention the `publicApi:` projection and the built-in `/v1/api-keys` surface already use. The path is normalised ONCE at definition time, so every consumer — the mount, path-param matching, the idempotency scope, tracing spans, the OpenAPI generator — sees the mounted path and none can disagree.
+
+  Deliberate edges:
+
+  - **Opt-in, no auto-prefix.** A route without `version:` keeps its literal path untouched — an automatic prefix would silently move every deployed route. A path that already starts with `/vN/` AND declares `version:` is refused loudly at definition (both spellings at once is never what the author meant). - **Two versions are two descriptors.** The old version is ordinary code — visible, testable, deletable — carrying `deprecated:` (the replacement pointer) and `sunset:` (the date it starts answering `410 Gone`; the 410 body now also names which `version` died). - **One OpenAPI document for every version.** The `/vN/` prefix already separates the paths; each versioned operation is grouped under a version tag and carries `x-voltro-api-version` for tooling. No `?version=` filtered spec — a second document shape for information the paths already state. - The rpc socket stays outside URL versioning on purpose: the generated client is versioned with the server it was generated from. A stale browser tab runs the previous client until reload — that skew window exists and is documented, not solved by URLs.
+- **@voltro/web, @voltro/cli** — Opt-in View Transitions for SPA navigations. `router.viewTransitions: true` in a web `app.config.ts` runs every route swap — `<Link>` clicks, `navigate(...)`, back/forward — through `document.startViewTransition`; individual navigations override the default in either direction with `navigate(to, { transition })` / `<Link transition>`.
+
+  The visual swap is the router's deferred-navigation commit, flushed synchronously inside the transition callback — by that point the target's lazy chunk and loaders have settled, so the flushed tree renders with data in hand. Three deliberate behaviors: `defer()` fields (and an explicit `Pending` skeleton's settled content) resolve AFTER the transition as ordinary updates, never a second animation; navigating while a transition is animating skips the running one (last navigation wins, nothing queues); overlay/dialog state changes never trigger one — a root snapshot would cross-fade the whole viewport for a one-layer change.
+
+  Fallback is exact: a browser without the API, and any user with `prefers-reduced-motion: reduce`, gets today's untransitioned swap — same timing, nothing to feature-detect. Styling is plain `::view-transition-*` CSS (no animation DSL); cross-document transitions for static/MPA pages are a one-line `@view-transition` CSS opt-in with no framework involvement.
+
+  Proven in a real chromium (`scripts/browser-view-transitions.mjs`): called on navigation, silent under reduced-motion, harmless with the API deleted, one transition across a `defer()` commit, rapid double-navigation lands on the last target — plus the jsdom wiring suite and the generated-entry flag check shared by all three web boot paths.
+
+  `apiSurface: compatible` — additive only: a new optional `viewTransitions` on `RouterProps`, optional `transition` on `NavigateOptions`/`LinkProps`, and the optional `router` block on the web app config.
+- **@voltro/web, @voltro/cli** — Schema-typed search params — the query-string half of the URL is now part of the type graph.
+
+  A page declares its contract once:
+
+  ```ts
+  export const searchParams = Schema.Struct({
+    q:    Schema.optionalWith(Schema.String, { default: () => '' }),
+    page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }),
+  })
+  ```
+
+  and gets, end to end:
+
+  - **Typed reads** — `useSearchParams(searchParams)` returns the decoded, defaulted shape, SSR-aware; the zero-arg call keeps returning the raw `URLSearchParams`. Decoding is TOTAL: an invalid query falls back to the schema's defaults instead of crashing a render; only a schema that cannot even decode `{}` (a required field with no default) throws, naming the fix. - **Typed links** — the generated `routes` builder brands the route's URL with the schema's shape through a TYPE-ONLY page import (zero value edges: code-splitting is untouched, pinned by test), and `withQuery` type-checks against it — a misspelt key or wrong value type is a compile error. The link-side encode is canonical and schema-free (strings/numbers/booleans, arrays as repeated keys); a roundtrip test pins that it produces exactly what the schema's decode accepts. Deliberately ONE generic signature rather than overloads: with overloads, a wrong key would silently fall through to the permissive untyped form and the compile error would never fire. - **Typed writes** — `useSetSearchParams(searchParams)` returns the typed setter: its object form replaces the query (same semantics as the untyped form), and its updater form receives the CURRENT decoded params, so keeping `?filter` across a page flip is one explicit spread — `setParams((p) => ({ ...p, page: p.page + 1 }))` — instead of a hand-rolled merge. - **A fail-closed isr gate** — `renderMode: 'isr'` plus a `searchParams` export is refused at boot: the isr cache is keyed by path (+tenant+locale), not query, so the first variant would be cached for every query — and the gate catches the re-exported spelling (`export { searchParams } from …`, the mirror-route pattern) too, not only the local declaration. - **A doctor rule** — a page that exports the schema but keeps reading the query with zero-arg `useSearchParams()` is flagged with the typed spelling.
+
+  Deliberate limits: array fields decode a single occurrence as a one-element array (link shape stays stable); `siblingApps` routes stay untyped (their schemas live in a foreign compile graph); `static` pages see the defaults at build time and decode live on the client.
+
+  Why the golden churn is compatible: `VoltroRouteUrl` gains a type parameter with a DEFAULT (`<TSearch = unknown>`), so every existing bare `VoltroRouteUrl` spelling still compiles, and the new brand member is an OPTIONAL phantom property of type `unknown` — assignability in both directions is unchanged. `withQuery`'s parameter for the untyped case is strictly WIDER than before (adds `boolean` and array values); no call that compiled stops compiling.
+
+### Fixed
+
+- **@voltro/cli** — `voltro agents-md`'s copied `agent-docs/` mirror no longer keeps orphaned modules across a re-seed.
+
+  The copy fallback (projects where `@voltro/cli` isn't resolvable) merged into an existing `agent-docs/` directory: when a module was renamed upstream (`plugins/versioning.md` → `plugins/row-history.md`), a `--force` re-seed brought the new file and left the old one sitting beside it — a stale generated doc teaching a package name that no longer exists, which is exactly the claim≠code drift the guide exists to prevent. The mirror is wholly framework-owned, so a re-seed now replaces it (the generator prunes its own output dir the same way).
+- **@voltro/cli** — `voltro check`'s observed-diff footer now accounts for every declared procedure, and no result line states a verdict without the count it is a verdict about.
+
+  Two defects, both found by readers doing arithmetic on the output:
+
+  - The diff computes TWO kinds of blindness — a procedure that never ran, and one that ran with no table access recorded — and the printer named only the first. The printed counts came out short of the total, with no way to tell an unshown category from a defect in `check` itself. The buckets are now derived from the result type, so a third one cannot be added without the label map failing to compile, and a partition that does not close prints as such instead of quietly under-counting. - `no declared/observed mismatches` was a bare verdict sitting under its denominator, and was quotable — and quoted — without it, as a clean bill of health for a surface where almost nothing had been exercised. Every result line now carries its scope (`no declared/observed mismatch among the 12 that ran`), and at zero coverage the section reports the ABSENCE of a comparison (`nothing was compared — a declaration is only checked against a procedure that RAN`) rather than the absence of findings. The two are different facts and only one of them is evidence.
+- **@voltro/cli** — An `isr` render no longer sees the requesting visitor's credentials — in `voltro dev` and `voltro start` alike.
+
+  An isr page's HTML is cached under tenant+locale and served to every visitor inside the revalidate window, but the render itself ran with the FULL request: loaders received the session cookie, and `ctx.query` was bound to it. A loader that read subject-scoped data on an isr page therefore cached the first visitor's data and served it to everyone — cache poisoning by construction.
+
+  The render boundary is fail-closed now: before an isr render runs, the cookie jar (except `voltro:locale`), the `authorization` header and every `x-voltro-*` header are stripped, for the loaders, `ctx.query` AND the `useServerRequest()` snapshot. What survives is exactly what the cache key and locale resolution read: `x-tenant`, `accept-language`, and the locale cookie — so a `de` visitor's fill still lands under the `de` key. One shared helper (`isrCredentialStrip.ts`), called by both boot paths, so dev renders isr anonymously exactly as production does — a page can no longer look personalised in dev and silently serve shared HTML in production.
+
+  Behavioural consequence, on purpose: a subject-reading loader on an isr page now gets the anonymous answer. A page whose loader needs the signed-in subject belongs on `renderMode: 'ssr'`.
+- **@voltro/cli, @voltro/runtime** — **`voltro serve` registers plugin rpc routes again — every plugin-contributed procedure answered `Unknown request tag` in production while `voltro dev` registered all of them.** The serve path mirrored dev's plugin-route block by hand and mirrored exactly half of it: the collision check ran (so nothing warned) and the returned routes were discarded as a bare expression statement, never reaching the buckets the rpc registry is built from. Every plugin route was indistinguishable from a tag that never existed — `useUpload`'s storage tags, presence, every inspect-less plugin rpc — while the app's own procedures answered normally, so the registry looked alive.
+
+  Three changes, each aimed at the way this stayed invisible:
+
+  - Both boot paths now call ONE shared builder (`mergePluginRoutesInto`) whose buckets are required parameters — a returned list can be discarded by a statement that typechecks; a function you cannot call without handing it the sinks cannot have its effect dropped. A reachability test drives a real socket with a plugin tag and an invented-tag control, and a source pin keeps the helper pair from being reassembled by hand in either path. - The boot line `plugin routes registered` prints WHENEVER plugins are installed, count included — zero is a finding, and silence is how this shipped. `voltro check` against a running server now also diffs source-declared tags against the live registry (`declared vs live:`), and its offline manifest includes plugin routes, which it previously did not. - Every `Defect` frame the server sends is now also a server log line (`rpc defect sent to client`, ws and http rpc). The defect string used to exist only inside the WebSocket frame — visible in whoever's browser console, invisible to the operator whose server produced it.
+
+---
+
 ## [0.51.0] — 2026-08-24
 
 ### ⚠ BREAKING

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-auth-oidc",
-  "version": "0.51.0",
+  "version": "0.53.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.51.0"
+    "@voltro/protocol": "0.53.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"