@voltro/plugin-postgis 0.53.0 → 0.55.0

package/CHANGELOG.md

@@ -39,6 +39,341 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.55.0] — 2026-08-27
+
+### ⚠ BREAKING
+
+- **@voltro/protocol, @voltro/client, @voltro/runtime, @voltro/cli** — **A multi-reference field now flips as instantly as a scalar one.** A mutation target's declared `relations:` reconciled the junction inside the server's transaction and nothing else: the client learned about the link change only when the delta came back. On the same submit, the renamed title flipped immediately and the assigned stores did not — the half of the promise that was never stated.
+
+  The declaration now drives BOTH. `useMutation`'s auto-optimistic stages a patch on every subscription sourced on the junction table, reconciling that anchor's links against `input[field]` — surplus links removed, new ones staged, surviving links left untouched with their real ids (a diff, mirroring `store.relationLinks(...).set`, not a drop-and-restage that would blink every unchanged row).
+
+  The patches ride the ordinary optimistic lane, staged under the mutation id, so the rollback rule holds by construction: reverted on failure, kept on success until the base actually moves. Nothing here is on a timer.
+
+  **Migration — `relations:` values are objects now:**
+
+  ```ts
+  // before
+  target: { table: 'employees', op: 'update',
+    relations: { assignedStores: 'employee_assigned_stores' } }
+  
+  // after
+  target: { table: 'employees', op: 'update',
+    relations: { assignedStores: {
+      junction: 'employee_assigned_stores',
+      anchorColumn: 'employeeId',   // the junction reference() pointing at `employees`
+      targetColumn: 'storeId',      // the junction's other reference()
+    } } }
+  ```
+
+  The columns are declaration data because the optimistic patch runs in the BROWSER, which has no table registry to derive them from — `@voltro/database` is server-only by construction, and guessing a column from a table name is exactly what `store.relationLinks` refuses to do. They are not taken on trust: before it writes, the server compares the declaration against the junction's real reference columns and refuses, naming the correct pair, if they disagree. A wrong declaration is a loud error carrying its own fix, never a client that patches one column while the server writes another.
+
+  Semantics unchanged and now shared by both sides: an absent input field touches nothing (absent ≠ empty), an empty array is the explicit clear. The client uses `input.id` for an update and, for an insert, the same optimistic id it stamped on the new row — the server's `output.id` is not knowable before the response.
+
+  **`voltro update` carries you across this** — codemod `0.55.0/01_target-relations-declare-columns`. 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.55.0).
+- **@voltro/client, @voltro/ui, @voltro/ui-shadcn, @voltro/web, @voltro/cli** — **A rich-text field, and the sanitizing contract is the point of it.** `RichTextDocument` (`@voltro/client`) is the value; `widget: 'rich-text'` renders it; `<RichTextView>` (`@voltro/ui`, re-exported by `@voltro/web`) displays it.
+
+  The contract, stated plainly because the alternatives all look reasonable until you name who the attacker is:
+
+  - **The value is a closed document tree, not an HTML string.** There is no `html` node, no raw-markup escape hatch, no attribute bag. Anything that is not one of the declared node types fails to decode. - **The boundary is the `Schema` decode**, which is the server's existing, non-bypassable input boundary — the same one every mutation input already passes through. So the guarantee is not "somebody remembered to sanitize this"; it is that a document which reached the database is one of these shapes. - **A link's `href` is the one field that points outward, and it is allowlisted** — `http(s)`, `mailto:`, a `#fragment`, a `/path`; nothing else. Control characters and whitespace are stripped before the check, because `java\tscript:` navigates exactly like `javascript:` and a check on the raw string passes it. - **Client-side is not a boundary and is not treated as one.** The widget's parser runs in the browser for the editing experience; every property it maintains is re-established by the decode on the server. - **Rendering never uses `dangerouslySetInnerHTML`.** Nodes become React elements, text becomes React children — so markup typed into the box is markup the reader SEES. `<RichTextView>` also drops an href that would not survive a decode, for the value that never went through one.
+
+  Rejected, for the record: sanitizing an HTML string on write (ships an HTML parser and the mXSS surface that comes with it), escaping at render (makes safety a property of every read site), and declaring an unenforced boundary (a convention, not a guarantee).
+
+  The built-in widget is a `<textarea>` over a small, CLOSED markdown subset — headings, `**bold**`, `*italic*`, `` `code` ``, `[text](href)`, lists, blockquote, fenced code — with everything unrecognised left as literal text. That also closes the no-JS loop: the textarea posts source, `/form/*` parses it, and the same decode validates it. A WYSIWYG belongs at rung 2 (register a `rich-text` widget); the stored value shape does not change.
+
+  **Not** the collaborative case: `crdtDoc()` + `useCrdtEditor` remains the multi-writer path (a CRDT bytes column, a sync lane, Tiptap). This is one column, one writer, ordinary JSON the server can validate and diff, and no new dependency in the default kit.
+
+  **Migration:** `WidgetKind` gained `'rich-text'`. Only a registry typed as a TOTAL map (`Record<WidgetKind, Widget>`) notices — add one entry pointing at the exported `RichTextWidget`. Partial registries need nothing.
+
+  Also fixed alongside: the capability manifest's `MANIFEST_WIDGET_KINDS` is a hand copy of `WidgetKind` (a CLI module cannot import `@voltro/client`) and had silently drifted by two kinds since 0.53.0, telling coding agents a smaller set than the renderer accepts. It is complete again and pinned by a test that reads the union out of the client's source.
+
+  **`voltro update` carries you across this** — codemod `0.55.0/02_widget-kind-gained-rich-text`. 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.55.0).
+
+### Added
+
+- **@voltro/database, @voltro/data-transfer, @voltro/cli, @voltro/voltro** — A staged `--mode replace` now RECORDS the scratch tables it creates, and a boot collects the ones nobody is coming back for.
+
+  Staging tables are `_voltro_staging_`-prefixed, so the differ correctly ignores them — and nothing else mentioned them either. A run that died between the load and the swap left a full copy of a bundle that only a hand-written introspection could find, on a database whose boot said nothing. The marker row now names the set, carries a heartbeat the run refreshes while rows land, and records whether the run was started `--no-atomic`. That is what lets a boot tell the three cases apart: silent past the threshold and not resumable → the tables are dropped; still beating → an import is loading into them, here or on another replica; resumable → its staging IS the resume point and is left alone however stale. `VOLTRO_STAGING_STALE_MINUTES` moves the threshold (default 30). A staging record is reported, never a refusal — a staged replace destroys nothing until one short server-side swap, so refusing a boot over it would be an alarm on a healthy database. `voltro data clear-staging` reads the same records and labels each table with what its own run says, instead of listing them flat under a warning that it could not tell a leftover from an import in flight.
+
+  Two smaller things came with it. The raw-SQL seam the staged swap runs on (`DataStore.run`) is a DECLARED optional capability now, in the shape `emptyTables` established, with a parity assertion across the four dialect stores — it was duck-typed against an interface that never mentioned it, so a store that dropped it would have fallen out of the feature detection and taken the slower path forever, on that one dialect, in silence. And a registered staging clone can no longer reach the differ's DECLARED side: `--mode replace` registers each staging table as a clone of its target for the length of the load (a typed write resolves its columns by name), and a plan computed while an import was in flight proposed `create-table _voltro_staging_notes`.
+
+  Also measured rather than assumed: the staging table `createStagingSql` builds on **sqlite** (`CREATE TABLE … AS SELECT * FROM t WHERE 0`) and on **SQL Server** (`SELECT * INTO … WHERE 1 = 0`) carries the target's columns and ZERO foreign keys, which is what the load needs. Those were the two dialects the postgres and mysql-family measurements had not covered.
+- **@voltro/client, @voltro/ui, @voltro/web** — **`useFormField(path)` finds its binding.** `<FormBindingProvider binding={form}>` (mounted for you by `<AutoForm>`) makes the narrow per-field subscription reachable without threading the binding down to every field component as a prop. That thread was blocking incremental adoption: a codebase moving a hundred-plus forms one at a time keeps its own field context and swaps engines per form, and being asked to prop-drill to ~30 field components at once meant taking the binding and declining the optimisation they had the most to gain from.
+
+  **Message ids a real catalogue needed**, each because the generic answer is worse at the point of use:
+
+  - `betweenLength {min,max}` when a field carries BOTH bounds — "at least 2" is a half-truth for a rule that is "between 2 and 50" — and `exactLength {amount}` when they are equal. Read from the schema, not the failing issue: piping nests the later refinement outermost, so the sibling bound is not reachable from the issue that failed. - `invalidEmail` / `invalidUrl` / `invalidUuid` when the refinement declares a JSON-Schema `format`. A bare regex cannot name its own rule, and "Invalid format" beside an email box tells nobody anything. - `minDate` / `maxDate`, because a date bound rendered as a number bound reads "must be at least 2026-01-01". - `invalidFileType` / `fileTooLarge` — not produced by any refinement, carried so an app's own `ctx.validation.fail('doc', 'validation.fileTooLarge')` renders a sentence rather than an id.
+
+  `apiSurface: compatible` — `useFormField` goes from a const arrow to an overloaded function so it can take `(path)` as well as `(binding, path)`. The golden line for the old signature is replaced rather than removed: every existing `useFormField(form, path)` call compiles unchanged, because that overload is still declared first-class. Only code capturing the function's exact TYPE (rather than calling it) sees a difference.
+
+  **Counting rules pass `count`.** `minItems` / `maxItems` carry `{ count }` beside `{min}`/`{max}`: i18next selects a plural form on a parameter named exactly `count`, so ids passing only `{min}` could not be pluralised at all.
+- **@voltro/runtime, @voltro/cli** — **The resume census — `/_voltro/inspect/subscriptions` now carries `resume`.** Per query label: how many subscriptions recorded a delta-resume ring, and how many were excluded, counted per reason (`computed`, `row-filter`, `eager-load`, `uncanonical-input`, `not-offered`). `voltro dev` also logs each verdict once per label under the `voltro:resume` scope — debug is the default level outside production, so it is already on where the tuning happens and off where it is served.
+
+  It exists because the two failure shapes are indistinguishable from outside. A subscription excluded by a row filter and one whose executor returns a **value** rather than a descriptor both reconnect with a fresh snapshot and rows on the screen, so an app measuring its own reconnects cannot tell which of its queries a `tables:` declaration is even capable of helping. The answer is which of the two bind paths the executor took, and nothing on the wire carries it.
+
+  The reasons are the load-bearing part, not the counts: `computed` means no declaration can ever change this query, `row-filter` means the filter narrows its source and the exclusion is the point, and `eager-load` is reported ONLY when the base table is not itself narrowed — so that verdict always means "drop the `.with(...)` and this one resumes". Counts rather than one verdict per label, because resumability is not purely a property of the label: an input that does not canonicalise is a property of the value, so one query can be resumable for one subscriber and excluded for the next. A label nobody has subscribed to is ABSENT rather than reported as zero — "nothing has subscribed yet" and "every query is excluded" must not read the same.
+
+  **And a correction to what `tables:` was documented to buy.** The 0.54.0 notes, the `tables:` doc comment and the row-level-security page all said one registration cost delta-resume on every query descriptor in an app, with a count beside it. The count was real; the sentence around it claimed those descriptors would have HAD the feature, and that was never measured. A query only has a delta chain when its executor returns a descriptor — one that maps its rows or wraps them in a page envelope re-runs an opaque handler and emits snapshots, filter or no filter. So the number a declaration gives back is the number of descriptor-returning subscriptions, not the number of queries. The docs now say that where the decision is made, and the census is how you find out which shape each of yours took.
+
+### Changed
+
+- `dataTransfer.stagingStaleMinutes` in `app.config.ts` — how long a staged import's silence has to last before a boot treats its scratch tables as abandoned. Previously `VOLTRO_STAGING_STALE_MINUTES` only; the env var still overrides the declaration, on the rule every other tunable here follows.
+
+  The reason this was not already a field was recorded as "the boot check runs off the store alone, before the app config is threaded to it". That described the function's signature, not the boot: both paths already held the config three lines above the call. Resolution lives inside `stagingLeftoversAtBoot` rather than at either call site, so the two cannot disagree about what a declared value means, and a source-reading assertion fails if either path stops handing the config over.
+
+### Fixed
+
+- **@voltro/protocol, @voltro/cli, @voltro/client, @voltro/plugin-notifications, @voltro/plugin-comments, @voltro/plugin-presence, @voltro/plugin-search, @voltro/plugin-flags** — **Installing a plugin under an `alias` now moves its client too.** `alias` exists for one problem — your app already publishes `notifications.*` and cannot install a plugin that wants the same namespace — and it has to move four surfaces or it is worse than not existing. It moved three.
+
+  The two that did not:
+
+  - **The generated client sent the tag the PLUGIN authored.** Every lifter is `Rpc.make(descriptor.name, …)`, so the wire tag comes from the descriptor, not from the tag the codegen computed. Under `alias: 'inbox'` the exported identifier became `inboxInboxRpc`, the `appDescriptors` key became `inbox.inbox`, the type key became `inbox.inbox` — and the browser still asked a server that had stopped serving it for `notifications.inbox`. The codegen now lifts every plugin descriptor through `withRpcTag(…)`, unconditionally, so the aliased and un-aliased cases are one code path rather than a branch nothing exercises. - **The plugin's own hooks spelled their namespace as a literal.** `useInbox()`, `useUpload()`, `useComments()`, `usePresence()`, `useFlag()`, `useSearch()` all carried strings like `'notifications.inbox'`, which no alias could reach. `voltro dev` now writes a `registerPluginAliases({ … })` declaration into `rpcGroup.generated.ts` — the module the web client already loads value-level — and every plugin hook resolves its tag through `pluginTag(baseName, route)` from `@voltro/protocol` at call time, not at module load. Aliasing a plugin needs no change at any call site.
+
+  Two installs of one plugin (`name: 'ops'`) with no un-suffixed primary make `pluginTag` **refuse** rather than pick: a hook has no way to name an install, and guessing would address the wrong one silently. The error names both candidates and points at the full-tag call that says which you mean.
+
+  `pluginAlias` / `pluginSlug` moved from the CLI into `@voltro/protocol` (and are re-exported from their old path) because the browser has to derive the same namespace the server registered, and a second copy on the client would be a second definition of the rule with nothing comparing them.
+
+  Also corrected, in the same seam: the list of plugins that deliberately do NOT accept `tables: false` read as exhaustive and omitted `_voltro_storage_grants`, which decides who may read an object. It is named now — along with the reason the option would not have reached it anyway (storage's tables are framework tables, not `extendSchema` contributions).
+- `voltro build` could not produce an api serve bundle on 0.53.0 or 0.54.0.
+
+  `@voltro/content`'s `get.ts` reaches its render pipeline through a dynamic `import('./serverLoad')`. That is deliberate — an unresolvable-at-build-time specifier is what keeps marked and the shiki grammars out of a consumer's client chunk graph. But `serverLoad` was not in the package's entry map, so nothing emitted `dist/serverLoad.js`, and `dist/index.js` shipped an import of a file beside it that was not there.
+
+  It resolved in this repo every time, because the workspace `exports` point at `src/` and `serverLoad.ts` sits next to `get.ts`. A consumer resolves `publishConfig.exports` to `dist/index.js`, and the same line cannot resolve. esbuild does not honour `@vite-ignore` — that is a vite directive — so the serve bundle refused to ship. The refusal was right; nothing had ever triggered it.
+
+  Two things worth knowing, both measured rather than reasoned:
+
+  - **The build was stopped by a dependency that contributes nothing to it.** An api serve bundle reaches `@voltro/content` through `serveCommand → dev → webDev → contentWiring`, and esbuild resolves before it tree-shakes. After shaking, the content pipeline is **0 bytes** of a 14.42 MB bundle. So an api app with no markdown anywhere was blocked by a markdown loader whose code it would never have carried. - **Shipping the file does not bloat anything.** Same measurement with the fixed package resolved as a consumer resolves it: 14.42 MB, content still 0 bytes. The dynamic import stays shaken away.
+
+  `scripts/check-dist-internal-specifiers.mjs` now bundles every emitted file of every publishable package — from `.publish/`, the tree users receive — with bare specifiers external, and fails if any relative specifier does not resolve. GATE-2 (`publint`) answers "does a declared subpath resolve"; this is one level below it, where `./serverLoad` lives.
+- **@voltro/client** — Three places still taught the pre-fix contract for a cold-start failure.
+
+  `SubscriptionFailed` gives it its own state — `loading: false`, `failed: true`, `error` non-optional — precisely so a component branching on `loading` alone cannot render a skeleton forever. But `SubscriptionMeta.error`'s doc comment and two docs pages still said the opposite ("leaves `loading` TRUE … check `error` to break out of it"), which is the sentence a deployment quoted back at us as evidence for the defect that had already been fixed.
+
+  A comment that predicts a trap the code no longer has is worse than no comment: it teaches the defensive shape as if it were still required, and it invites the reading that `loading` is unreliable. All four now describe the state that exists, with the old behaviour kept only as the history that explains why the field is there.
+- **@voltro/client, @voltro/web, @voltro/cli, @voltro/ui** — Four defects a real migration found, all of which passed `tsc` and a full test suite and only showed up against a running system.
+
+  **A server render derived a different form than the browser.** Nothing mounts a runtimes provider during SSR, so `useFormBinding` resolved its input schema from an EMPTY descriptor map: no fields, `required: false`. The browser then rendered the real ones and React discarded the subtree — "Hydration failed" on every server-rendered page carrying a bound form, with the diff pointing at a `Mui-required` class. `@voltro/client` keeps a process-global SSR descriptor registry now, and both boot paths fill it before rendering (`voltro dev` and `voltro start`, pinned as a parity test — a CLI module cannot import `@voltro/client`, so the call goes through `@voltro/web/ssr`, which both already load).
+
+  **A rejected `submit()` had nowhere to go.** A form calls it from an `onSubmit` handler that cannot await it, so the rejection surfaced as `Uncaught (in promise)` while the form sat there looking saved. `submit()` resolves `undefined` now and the failure is state: `state.submitError`, plus an optional `onError`. That covers a composed `onSubmit` whose follow-up write fails on its OWN mutation handle — a failure the binding never saw, and the common shape (create the row, then its first child).
+
+  **Undeclared fields went on the wire.** The binding validated the mapped input and then sent the object unchanged; the client decode ignores excess properties while the server has refused them since 0.37, so a form carrying anything beyond the mutation's input passed validation and was rejected on the wire with a message pointing at no field. The payload is restricted to the declared keys now — the rule the no-JS path already followed, so the two submits agree — with a dev warning naming what was dropped.
+
+  **`setValue` with an unchanged value produced a new `values`.** Every React state source is expected to no-op on that; this one did not, so an effect depending on `values` that re-set a field to the value it already held never settled ("Maximum update depth exceeded" on a form mirroring toggles out of a multi-select).
+- A plugin's dashboard panel no longer disappears when the app aliases the plugin.
+
+  `alias` moves `plugin.name`, and the inspect mount is derived from it, so `alias: 'inbox'` on notifications moved its panel to `/_voltro/inspect/plugins/inbox/...` while both dashboards ask for `/plugins/notifications/...` with the path compiled in. They live in other repositories and cannot follow. The field's own doc comment stated this as a cost you accept — in nine plugins, the protocol helper and the docs.
+
+  `makePluginInspectRegistry` now mounts each plugin's `inspectEndpoints` under its CANONICAL slug as well, in a second pass so an effective mount always wins the path. Added only where unambiguous: a base name carried by more than one installed plugin gets no shared mount, because showing either install under it would hand a dashboard the other one's rows under a name that looks right — the hazard `pluginTag` refuses rather than guesses. `/_voltro/inspect/plugins` now reports `baseName` and `inspectSlug` per plugin, which is how a caller reaches a specific install.
+- **@voltro/cli, @voltro/data-transfer** — **`voltro data restore --drill` failed every healthy backup of a real app.** It compared the restored schema's fingerprint against the backup stamp's `schemaFingerprint`, which records the SOURCE database's whole live schema — and the artifact never carries that schema. `pg_dump` / `mariadb-dump` exclude `_voltro_replace_in_progress` and `_voltro_data_transfers` on purpose, and the backup command opens a run row in the second one before it dumps, so on any database the framework has run against, the artifact is two tables short of the value it was being measured against. The drill answered:
+
+  FAIL — restored N table(s), but the schema fingerprint (…) does NOT match the backup's stamp (…). The restore did not reproduce the schema that was backed up — the artifact is inconsistent.
+
+  about an artifact that was exactly right. A drill exists to be wired to a CI cron, and one that is red on every healthy input gets switched off — taking its two real failures with it.
+
+  The stamp now carries a second value, `dumpFingerprint`: the same snapshot minus `dumpExcludedTables(dialect)` — what a faithful restore must reproduce. The drill compares against that. A stamp written before this field degrades to a PARTIAL pass that says so, rather than falling back to the value that produces the false failure. `dumpExcludedTables` is per-dialect because only two of the five backup paths carry an exclusion flag at all: the sqlite/turso copy and the mssql export carry everything, and subtracting a set from those would invent the same bug in the other direction.
+
+  **The drill also checks the one boot-fatal condition a schema comparison cannot see.** `voltro serve`'s boot gate reads the newest `_voltro_migration_plans` row and refuses with `prod-mismatch` when there is none — so a ledger table that restores with exactly the right columns and zero rows is a database no source tree can boot, and its fingerprint is identical to a healthy one's. That is now a FAIL with the reason named. A restored database with no ledger table at all is not a voltro-managed schema and is reported as such, not failed.
+
+  There is deliberately no app boot in the drill. The boot gate is a comparison, not a startup sequence, so the part that generalises is reachable with a SELECT; booting a fixture app instead would prove something about our fixture rather than about your backup.
+
+---
+
+## [0.54.0] — 2026-08-27
+
+### ⚠ BREAKING
+
+- **@voltro/local-first** — **`CrdtDocHandle.onUpdate` now tells its handler whether the update was LOCAL.** The signature gains a second argument: `onUpdate((update, { local }) => …)`. `local: false` means the blob came from folding somebody else's state through `applyState`.
+
+  Without it, an echo guard could not be written correctly on the public surface. Applying a peer's update fires the same handler a local edit does, so an app pushing from `onUpdate` re-broadcasts what it just received — measured with three tabs open, one keystroke produced three server writes instead of one. It converges (the merge is idempotent), but the amplification scales with the session.
+
+  The only app-level workaround was an `applying` boolean around `applyState`, and that is correct **only** while the backend emits synchronously — a property `CrdtBackend` deliberately does not promise ("the backend decision lives behind our abstraction so it can change"). So the flag had to come from the backend: the yjs one tags its own folds with a symbol origin and reports anything else as local.
+
+  `codemod: none` — the parameter is ADDITIVE. An existing single-argument handler keeps compiling and keeps behaving exactly as before; there is nothing to rewrite. Read the flag when you push from `onUpdate`, which is what `useCrdtDoc` does for you.
+- **@voltro/local-first** — **`RUNTIME_SEAMS` lists ONE seam now, not three** — `['sync-transport-app-tags']`. `RuntimeSeam` narrows with it. The two removed entries left in opposite directions, and `seams.ts` was asserting both halves of the contradiction at once: its `DONE` prose said the presence broker binding shipped while the array beside it still named `presence-broker-binding` as open.
+
+  - `presence-broker-binding` is BUILT. `usePresenceChannel` (`@voltro/plugin-presence/web`) rides the framework's own presence lane, so cross-replica fan-out belongs to the broadcast plugin and there is one presence wire rather than two; the shape is pinned by `presence/channelParity.test-d.ts`. - `wasm-sqlite-durable-adapter` was REJECTED, with the reasoning recorded in `mirror/queryMirror.ts`: the client's query surface is `(tag, input)` and predicates never exist client-side, so a browser SQL engine would evaluate a language the client never sees. A decision is not a gap, and listing it as one invites somebody to close it. A SQLite BACKING beneath `KvStore` remains available and is a different door.
+
+  `codemod: none` because nothing in the framework reads this constant and nothing asks a user to: it is a documentation manifest that happens to be typed. There is no mechanical rewrite for a removed member of one — the correction is the sentence above.
+
+  The docs site's "what's shipped vs. a runtime seam" table carried the same two rows in both languages and now carries one, with both departures stated rather than silently dropped: "we have not built it" and "we decided against it" are different answers and a reader is entitled to know which one applies.
+
+### Added
+
+- **@voltro/content, @voltro/cli** — **Relative images inside markdown content are copied into the build, and their `src` rewritten to the copy.** `![cover](./cover.png)` now lands in `dist/assets/content-media/<hash>.<ext>` and the rendered HTML points there. `voltro dev` serves the same URL shape on demand from the source file, so a page's HTML does not change between development and a build.
+
+  Nothing moved those files before: the artifact emit wrote JSON and the renderer emitted the relative src verbatim, so a built blog asked the browser for a path that exists only in the source tree — while `routing/assets.md` said, in both languages, that the content pipeline copied and hashed them.
+
+  A reference to a file that does not exist now FAILS the build and names the path. The alternative — emit the src and continue — is the defect itself: the page renders, the browser 404s, and the build says nothing.
+
+  Absolute (`/…`) and remote sources are untouched; they are not the build's to move. Copy and content-hash only — build-time transformation (resize / format) remains a named non-goal for markdown content, because a markdown reference carries no width and no `sizes` to derive one from. The `?image` pipeline stays the answer where that matters.
+
+  Renderers outside the framework's build are unaffected: `@voltro/content` exposes this as a registered resolver (`setContentAssetResolver`), and with none registered a relative src is left exactly as written rather than rewritten to a path nothing serves.
+- **@voltro/cli, @voltro/runtime** — **The server-side CRDT compaction threshold is an `app.config.ts` field now, not an environment variable only.** `crdt.compactMaxBytes` (default 512 KiB, `0` disables) decides when a merged `crdtText()` / `crdtDoc()` blob is soft-compacted — re-encoded through a live doc, same lineage, so every outstanding client update still merges. `VOLTRO_CRDT_COMPACT_MAX_BYTES` still wins over it: an operator acting on a running deployment outranks what the project declared.
+
+  This is the standing rule ("every number the framework picks on your behalf is a config field with a default, plus an env override"), applied to the one knob that had only the environment half. A threshold sized for a document shape is a property of the project, so it belongs in a file a reviewer reads and a deploy carries — not in whatever `env:` block somebody remembered to set.
+
+  Resolved by ONE builder both boot paths call (`wireCrdtTunables`), registered into the process slot the merge path reads — the `wireReactiveSocketTunables` shape, for the reason that shape exists: two paths resolving a value separately is how they come to disagree. `setCrdtCompactMaxBytes` was exported and called by nothing before this; the runtime kept a lazy env read for a process that never runs a boot path (a unit test), and that remains the fallback rather than a second answer.
+
+  Note `0` is a value here, not an absence — it means "do not compact" — so the resolver's floor is `>= 0` on both the config and the env side. The `> 0` floor the other tunables use would have silently dropped a declared zero.
+- **@voltro/cli** — **The gRPC surface's shutdown drain budget is configurable — `grpc.drainMs` (default 5000, `0` forces immediately, env `VOLTRO_GRPC_DRAIN_MS`).** It was a `5_000` literal in the `stop()` closure.
+
+  It is a knob rather than a measured constant, and the distinction is worth stating because the framework deliberately refuses knobs elsewhere on the same page (compression levels are fixed — "a knob nobody can pick correctly is worse than a measured default"). A compression level has no input outside the process. A drain budget has two, and neither is ours: the orchestrator's termination grace, past which SIGKILL arrives and a longer budget is decorative; and the app's longest legitimately in-flight call, below which every rolling deploy force-closes work that would have finished. The default fits the 30 s grace both kubernetes and `docker stop` default to.
+
+  The `grpc:` config shape was also declared THREE times — `ApiAppConfig`, `ServeApiOptions` and the shared builder's options — which is how a field lands on two of them. It is one exported `GrpcSurfaceConfig` now, referenced by all three, so the shared builder both boot paths already call is the only thing that reads it.
+
+  The boot line and the budget-exceeded warning both name the resolved value, so what a process will wait is visible before the shutdown rather than after it.
+- **@voltro/cli** — **Partial prerendering's counters are now real metrics — they were incremented by both boot paths and read by nothing, while the observability docs listed them among the exportable ones.** A reader who went looking for them at the OTLP or Prometheus endpoint found nothing there: `pprMetrics()` was a `globalThis` counter slot with no registry bridge, no inspect endpoint and no log line.
+
+  Five series, all labelled `page` — the DECLARED route pattern (`/blog/[slug]`), never a resolved URL: `voltro_ppr_shell_serves_total`, `voltro_ppr_hole_passes_total`, `voltro_ppr_hole_settles_total`, `voltro_ppr_hole_errors_total`, and the `voltro_ppr_hole_pass_seconds` histogram. They land in Effect's global `MetricRegistry`, so `@voltro/plugin-prometheus`' `GET /metrics` and `GET /_voltro/inspect/metrics` both see them with nothing to register — the same placement `@voltro/database` uses for `voltro_db_*`.
+
+  `voltro_ppr_hole_errors_total` is the one to alert on, and it is a separate series rather than a `status` label for a reason: a failed hole pass is invisible from outside. The shell is already on the wire with a `200`, so the page renders and every `<Await>` boundary silently stays on its fallback forever.
+
+  Two things changed beyond the bridge. The last/max latency PAIR is gone in favour of the histogram — a last value plus a monotonic max answers strictly less, and the max never comes back down. And `voltro dev` now counts shell serves too; the counter previously existed only on the `voltro start` path, which for a metric is the silent kind of drift (the series simply reads zero).
+
+  The `globalThis` slot is deleted rather than kept beside the registry: two counters for one fact is how a dashboard and a scrape target come to disagree.
+- **@voltro/plugin-presence** — `resolveMember` now receives the app's `store`, and `identityFields:` closes the hole in the obvious resolver.
+
+  Both from a deployment that adopted the hook and reported what it cost them.
+
+  **The store.** The resolver's whole job is a by-id read, and `app.config.ts` — where it is declared — is evaluated long before a migrated `DataStore` exists. The workaround is a module cell filled from a `*.startup.ts`; the plugin already receives the store through `bindDataStore`, so it hands it to the resolver instead: `resolveMember: ({ subject, store }) => …`.
+
+  **The hole.** Resolved fields merge OVER the caller's `meta`, so a key the resolver does not return keeps whatever the client sent. A resolver returning only what it found — `{ userName }` for a user with no avatar — therefore leaves a caller-supplied `avatarUrl`, or a `userName` the resolver has never heard of, standing in the roster every other member reads. That is the exact substitution the hook exists to prevent, and the doc comment's promise ("a caller cannot override what the server says about them") was broader than the behaviour: it holds only for the keys returned on that call.
+
+  `identityFields: ['userName', 'avatarUrl']` names the keys the SERVER owns. They are stripped from the caller's `meta` BEFORE the merge, so the answer is the same on every call whether or not the resolver produced a value. Ignored without a `resolveMember` — with no server identity to protect, stripping a client field would only delete data the app put there deliberately. Returning every identity key (`null` where you have no value) remains the alternative, and is what the reporting deployment did.
+- **@voltro/plugin-queue** — **Queue consumers now export Prometheus series and open one tracing span per message, continuing the producer's trace.** Both were specified and neither was built: `voltro_queue_consumed_total` had zero occurrences anywhere in the repo, and `traceparent` was copied out of the message headers onto `ctx.traceparent` — a value a handler can forward by hand, not a trace. A Kafka hop was where every distributed trace ended.
+
+  Four series, all in Effect's global `MetricRegistry` (so `GET /metrics` and `GET /_voltro/inspect/metrics` both see them): `voltro_queue_consumed_total{topic,outcome}`, `voltro_queue_retries_total{topic}`, `voltro_queue_produced_total{topic}` and the `voltro_queue_lag_messages{topic,partition}` gauge.
+
+  `outcome` is a closed two-value union — `ok` and `dead-lettered` together are every message the runner finished with, so the dead-letter rate is a division with no second series to join. A message abandoned by a REBALANCE is deliberately in neither: it was not consumed here, its new owner redelivers and counts it there, and counting it twice would make that ratio wrong in the direction of looking healthy.
+
+  Lag costs no extra round trip — `highWatermark` already rides along in the fetch response, so it is arithmetic on data the provider was handed. It is recorded in the provider rather than the runner because that is the only layer holding the watermark; the runner could only get it by asking the broker. Offsets are parsed as `BigInt` so a long-lived topic cannot lose precision, and an unparseable pair records nothing rather than a zero: "no lag" and "we could not tell" must not read the same.
+
+  The per-topic inspect counters stay, and each fact is now moved by exactly ONE recorder that writes both the slot and the series, so the dashboard and the scrape target cannot drift.
+
+  Each message is processed inside a `queue.consume` span whose parent is the incoming `traceparent`, parsed by the same `externalSpanFromTraceparent` the inbound-webhook path uses — so a malformed or all-zero header means "no parent" (a fresh root span), never a failed message. The span covers the whole message including retries and the dead-letter publish, and carries the OTel `messaging.*` attributes plus `voltro.queue.outcome`. The topic is an attribute, not part of the span name.
+
+  Known limit, measured rather than assumed: a span opened from DETACHED work does not reach an OTLP exporter, because the framework's tracer is a `Layer` provided only inside the rpc server's scope. This is framework-wide (`cdcOut.deliver` and `plugin.<name>.schedule-fire` are the same shape) and is stated in the queue docs rather than implied away. The metrics are unaffected — the metric registry is a process global.
+- **@voltro/runtime, @voltro/voltro** — `setRowFilter({ …, tables: ['documents', 'comments'] })` — declare which tables your filter may narrow, and delta-resume survives everywhere else.
+
+  Delta-resume is excluded for a subscription whose row set is re-resolved per delivery: replaying deltas could serve rows the subject has since lost. But the question the runtime could ask was only "is a filter registered in this process?", so ONE registration disabled cheap reconnects for every subscription in the app, including every one whose source the filter could never narrow.
+
+  It does not reach every query. A subscription only has a delta chain when its executor returns a DESCRIPTOR; one that returns a mapped value or a page envelope re-runs an opaque handler and emits snapshots, with or without a filter. `tables:` costs nothing and applies the moment such a query returns a builder — but the count it gives back is the count of descriptor-returning subscriptions, not of queries. The resume census on `/_voltro/inspect/subscriptions` reports which shape each of your queries took.
+
+  The exclusion is per table now. A declared filter keeps resume for every subscription whose source is not in its set; an undeclared filter keeps today's conservative behaviour (the runtime cannot know which tables the predicate may reach, and "unknown" must read as "yes").
+
+  **Declared, not probed** — and the difference is soundness, not taste. Resolving the scope at subscribe and treating `predicate(ctx, source) === undefined` as safe is the cheaper version: it is wrong, because the predicate is a function of freshly loaded context, so a table it does not narrow now may be narrowed on the next delivery — which is the entire reason the filter is re-resolved per delivery. A static list is a promise about every future resolution, and the runtime holds the app to it: a predicate returned for an undeclared table raises the new `RowFilterDeclarationViolated` at the read that did it (the request fails, a subscription is revoked) rather than serving rows under a resume grant the declaration no longer earns.
+
+  Eager loads (`.with(...)`) stay excluded wholesale — a relation resolves below the seam that narrows (see the sibling entry).
+
+  `apiSurface: compatible` — the golden also picks up `subscribeDescriptor` gaining its `reauthorize`/`refilter` parameters, which landed in the SSE/gRPC row-filter fix without a regeneration. That member is a framework-internal transport binding: the only implementors are the two boot paths (`serveApi.ts`, `dev.ts`), both already passing the new arguments. No user code implements or calls it, so no code that compiled stops compiling.
+- **@voltro/local-first** — **`useCrdtDoc` — the transport half `useCrdtEditor` had no partner for.** `useCrdtEditor({ doc })` takes a `CrdtDocHandle` and owns the editor lifecycle; getting that handle wired to a server was app-level glue until now. Import it from `@voltro/local-first/react`:
+
+  ```tsx
+  const shared = useCrdtDoc({
+    cell: { table: 'documents', id, column: 'body' },
+    remote: row.data?.body ?? null,          // the reactive query streaming the row
+    push: (w) => save.mutate({ id: w.id, update: w.update }),
+  })
+  // in a CHILD component, so useCrdtEditor is never a conditional hook call:
+  const editor = useCrdtEditor({ doc })
+  ```
+
+  It returns `{ doc, loaded, outstanding, synced, setOnline }`. `doc` is `null` until the mount effect has run — the document is built in an effect, never during render, which is what a rich-text binding gets wrong first (constructing during render crashes a prerender and leaves a second instance alive under StrictMode).
+
+  **It is `createSyncClient`-backed, not new glue.** The four-line hand-rolled version loses the offline queue, the bounded retry, `outstanding`/`synced`, the per-cell coalescence that drains 1000 offline keystrokes as O(1) pushes, durable persistence, and the discipline that a `null` row means NOT LOADED rather than an empty document — fold an empty document over a loading row and the first keystroke can push a state that erases what was stored.
+
+  **The echo guard is the part that could not be written outside the package until now.** A `crdtDoc()` handle is mutated by the EDITOR, so local edits arrive as `onUpdate` callbacks — and folding a peer's state through `applyState` fires the same callback. The hook pushes only when `local` is true. Without that, every client re-broadcasts what it just received.
+
+  `useCrdtText` and `useCrdtDoc` now build their sync client through one shared internal seam rather than two copies of the same transport wiring.
+
+### Fixed
+
+- **@voltro/runtime** — A row filter was bypassed for any table reached through `.with(...)`.
+
+  The filter is AND-merged onto a read's BASE table by the store middleware; an eager load is resolved BELOW that seam — the memory store recurses through its own raw read, the SQL stores fold the relation into one join — so the relation's rows never passed the code that would narrow them. Measured on one data set: a filter restricting `readers` to the caller returned exactly the caller's row on a direct read and BOTH rows through `.with({ readers: true })`.
+
+  Applying the filter inside eager compilation is the real fix and it is a per-dialect change. Until then the read REFUSES rather than serves, naming the table and both ways out (read it as its own query, or drop it from the `.with(...)`). Only relations reaching a table the filter actually narrows are affected; every other eager load is untouched, and an app with no filter pays nothing.
+
+  Silent exposure is the one outcome that must not survive the gap — the same reasoning that makes this module refuse to fail open when `load` fails.
+- **@voltro/cli** — **The AGENTS.md seeder executed every app's `app.config.ts`, so seeding one app could stop another from booting.** It walked `apps/<proj>/<app>` for the whole workspace and `import()`ed each config to read its `plugins:` list. An `app.config.ts` is not inert: it imports the app's schema, which calls `databaseHandle(...)`, which REGISTERS every table. Two apps that each declare an `actors` table therefore collided —
+
+  ```
+  duplicate table 'actors' registration: two different table descriptors claim the same name.
+  ```
+
+  — and the app being booted was the one that failed. A reference project could not start at all.
+
+  The seeder parses the config now instead of importing it, resolving each plugin's package by pairing the identifiers called inside the `plugins: [...]` block with the import that introduced them (so a renamed import still lands on the right package), and reading the `{ name: '…' }` form directly. A plugin it cannot attribute is dropped rather than guessed: the index is a filter, and a wrong row is worse than a missing one.
+
+  The rule this encodes: **a step that writes documentation must not execute application modules.** Nothing about composing an index needs a config's runtime value, and the sibling app-discovery pass was already reading the same file as text for its `type:` check.
+
+  Worth knowing for the next diagnosis: two different descriptors for one name reads like one module evaluated twice, so the investigation went looking for split module identity (pnpm symlink vs real path, ESM cache keying). It was two DIFFERENT apps, pulled in by a documentation step — found by tracing what actually resolved, not by reasoning about what could.
+- **@voltro/cli** — **`voltro build` read the PREVIOUS build's config, so every `app.config.ts` change landed one build late.** `loadConfig` prefers the precompiled `.framework/dist/server/appConfig.js` when it exists — correct for `serve` / `start`, which cannot read TypeScript, and exactly wrong for the command that WRITES that file. Anything consumed before the config is recompiled took the stale value: `fonts`, `images`, `seo`, `theme`, `locales`.
+
+  Silent in the worst way: the second build is always right, so the symptom is "my change did nothing" followed by "…and now it works", with no error either time. Measured by setting `title` to a probe value, building, and finding the old title in the generated shell.
+
+  `voltro dev` already carried this fix, with the reasoning written on the option itself. The build path is the one that makes the artefact, so it is the last place that should trust it.
+- **@voltro/local-first** — **`useCrdtEditor` built its editor during RENDER, so a default page could not mount it and StrictMode leaked one.** The Tiptap instance was constructed inside a `useMemo`, which runs while rendering. Two consequences, both real:
+
+  - **Server render threw.** Tiptap needs `window`; a page mounting this hook failed prerender with `there is no window object available`. `renderMode` defaults to `'static'`, so that is the ordinary page, not an exotic one. - **React's double-invoked render built TWO editors** and the cleanup destroyed only the last, leaving the first alive holding its Yjs binding. `useCrdtText`'s own comment documents exactly this shape as a bug; the editor had it anyway.
+
+  Construction moved into an effect, and the cleanup destroys THAT instance rather than whatever the ref currently holds — reading the ref destroys the new editor on a rebuild and leaves the old one running.
+
+  `extensions` is no longer a dependency. Callers pass an inline array literal, which is a fresh identity every render, so listing it rebuilt the whole editor per keystroke; it is read at construction from a ref instead. The trade is stated rather than hidden: changing `extensions` after mount does not rebuild the editor — remount with a `key` if you need that.
+
+  **`CrdtDocHandle` is exported now.** It is the parameter type of `useCrdtEditor`, and it was declared, used across the package, and exported from nowhere — visible in the built `.d.ts` only as a bare `declare interface`, which no import can reach. An app binding an editor could not type its own variable.
+- **@voltro/cli** — `middleware.ts`'s `cspNonce` now reaches the scripts in a STREAMED response's `<head>`. Both boot paths handed the nonce to React — which stamps only the scripts React itself emits — and not to the driver that composes the head, so on the arm a plain `renderMode: 'ssr'` page takes, `renderDeferredRegistryScript()` (executable inline JS) and the `__voltro_state__` payload went out bare under the very `script-src 'nonce-…'` policy the same response set. A deferring page's registry was therefore the one script the browser refused to run. The `renderMode: 'spa'` layout-shell arms were unstamped end to end for the same reason and are fixed with them.
+
+  `stampScriptNonce` also stops mistaking `data-nonce="…"` or a `?nonce=` query parameter for a nonce attribute, which left exactly the tags a policy then blocked unstamped.
+
+  Still open, and now documented rather than implied: the settle `<script>` an `<Await>` boundary emits inside the streamed body is part of the rendered tree, so neither stamper reaches it — `defer()` and `cspNonce` do not compose yet.
+- **@voltro/runtime, @voltro/cli, @voltro/plugin-queue, @voltro/plugin-cdc-out** — **A span opened by detached work reached no exporter.** The tracer is a `Layer` provided at `startRpcServer`'s outermost scope, so `Effect.withSpan` inside a handler resolves the configured OpenTelemetry tracer. Work that runs OUTSIDE a request fiber — a broker callback, a schedule firing, a CDC delivery — reaches Effect through its own `runPromise`, which resolves the DEFAULT tracer: it creates spans and hands them to nobody. Measured against a live tracing layer: **0 finished spans**, for three framework span sites that all read as instrumented (`queue.consume`, `cdcOut.deliver`, `plugin.<name>.schedule-fire`).
+
+  The server now publishes its tracer instance into a process cell (`globalThis` + `Symbol.for`, for the same duplicate-instance reason `coreTablesRegistry` and the row filter are there), and detached work runs under it via `withServerTracer`. That is exactly the correction the LOGGER already had one line over in `rpcServer.ts` — detached fibers "start from the default runtime and carry their own", and were given one; the tracer never was.
+
+  Not a second provider: a per-plugin tracer means a second `NodeTracerProvider` with an exporter nothing flushes at shutdown, and global OTel registration is refused on purpose. There is one tracer, built where it always was.
+
+  `withServerTracer` is a no-op when nothing is published — a unit test, an embedder, a process with no rpc server — never a throw and never a second tracer. Pinned by `serverTracer.test.ts`, whose second case drives the defect directly: without the wrapper, the same span never reaches the tracer under test.
+- **@voltro/local-first** — **`useCrdtEditor` was unreachable from a published install.** `@voltro/local-first`'s source `exports` map carried `./editor`, its `publishConfig.exports` — the map an npm install actually resolves — carried only `.` and `./react`, and the build emitted no editor bundle. So the rich-text editor binding worked inside this monorepo (where `workspace:*` resolves the source map) and gave every user `ERR_PACKAGE_PATH_NOT_EXPORTED`, while the docs taught it.
+
+  `editor` is a build entry now, `./editor` is in the published exports, and it has its own api-extractor report so the surface is checked like the other two. An entry point that is documented and not built is a feature that exists for nobody outside this repo, and the two maps diverging is the shape that hides it: the one you read is not the one users resolve.
+- **@voltro/web** — `responseHeaders` and `cspNonce` are on the type users actually write against.
+
+  The CSP-nonce and response-header feature shipped with its fields declared in the CLI's internal `MiddlewareResult` and NOT in the one `@voltro/web/middleware` publishes — the type `defineMiddleware` checks a user's `run` against. The runtime honoured both fields; the compiler refused them. So the documented way to set a `Content-Security-Policy` from middleware produced TS2322, and the only way to use a working feature was to cast around its own type.
+
+  Two definitions of one shape is what allowed it: the half that gained the feature is not the half a user writes against. The published type carries both fields now, with the same documented limits (a prerendered `static` file is served without a render, so no middleware runs; `cspNonce` is `ssr` only, because an isr render is cached and a cached nonce is a lie the browser enforces).
+
+  Caught by the `web-layout-loader` fixture, which is the only place that writes this type the way a user does.
+- **@voltro/cli** — `voltro mobile <dir>` read its directory with a predicate that treats every flag as valued.
+
+  The command found its root with a hand-rolled scan — first argument that does not start with `-` and is not preceded by a `--flag`. Two things go wrong with that shape, and `cliPositionalFlagSafety.test.ts` exists because they have gone wrong before:
+
+  - it treats a BOOLEAN flag as consuming the next argument, so `voltro mobile links --help ./app` decided `./app` was `--help`'s value and silently fell back to `process.cwd()`; - it matched with `indexOf`, the FIRST occurrence, so an argument whose text appears twice was judged by the wrong position.
+
+  It uses `firstPositional(args, VALUED_FLAGS)` now, with the three flags that actually take a value declared rather than inferred.
+- **@voltro/database** — Adding a `.default(…)` to an EXISTING `text()` column no longer kills the migration on MySQL. MySQL refuses a DEFAULT on a TEXT/BLOB column outright (`BLOB, TEXT, GEOMETRY or JSON column 'x' can't have a default value`), where MariaDB allows it — so the same declaration applied on one engine and failed mid-migration on the other. `CREATE TABLE` has always answered this by widening such a column to `VARCHAR(255)` (`NVARCHAR(450)` on SQL Server, where the reason is indexability); the ALTER path now applies that same answer, reshaping the column to the declared shape instead of setting a default on whatever the column happened to be. A column therefore ends up with the same type whether the default was declared before or after the table existed. Postgres (TEXT takes a DEFAULT) and SQLite (rebuilds to the declared shape) are unchanged. Note the narrowing: on mysql/mariadb the column becomes `VARCHAR(255)`, so the ALTER fails loudly if an existing row is longer — use `text().maxLength(n)` to choose the width. The same widening rule also reached `ADD COLUMN`, which on SQL Server had emitted `NVARCHAR(MAX)` for a column `CREATE TABLE` renders as `NVARCHAR(450)`.
+- **@voltro/cli** — **Validation errors on the no-JavaScript form path rendered in English on every locale.** `validateFields` resolves message ids through a locale whose default is `documentLocale()` — it reads `<html lang>`, and outside a browser that is always `'en'`. The `/form/*` handler runs on the server, so a German page's 422 came back with English field errors while the same form with JavaScript rendered German; the flash carries the resolved strings, so hydration kept them.
+
+  The handler now resolves the locale from THIS request through the same resolver the surrounding page render and the ISR cache key already use (cookie › `Accept-Language` › the app's default). It is a required option on `makeFormPostHandler` rather than an optional one: both boot paths mount that handler separately, and an option nobody has to pass is one a new mount silently omits — landing straight back on the browser default. An app with no `locales` configured answers `'en'` explicitly.
+
+  **Under URL-prefix i18n the referring path outranks that chain.** There the language IS the URL (`/de/todos`) and the cookie may say something else entirely, so a cookie-only answer renders errors for a page the user is not on. The handler passes the referer's path to the resolver and both boot paths check it against the app's declared `locales` first, through one shared `localeFromPathPrefix` — a first segment that is not a declared locale (`/design/…`) falls through to the cookie chain rather than being mistaken for one. This is the "referer path vs. locale cookie" question the no-JS form work left open; the answer is both, in that order.
+- **@voltro/client** — `useOutbox`'s `resolveConflict(id, input)` now actually replays the entry it resolved. It replayed against the pre-resolution queue — `replay` reads the queue through a ref, and the `setQueue` beside it had not landed yet — so the entry it was handed was still `conflict`, `replayable()` stopped at it, and nothing was sent. The resolution then sat in the queue as `pending` with no further replay scheduled, and every write queued behind it stayed blocked with it: a conflict that could be resolved in the UI and never left the device.
+- **@voltro/runtime, @voltro/cli** — **A subscription opened over SSE or gRPC ignored the registered row filter — every read, not just the first.** `dispatcher.subscribe` resolves row visibility itself and treats a missing `refilter` as "this app has no row filter", so it read the descriptor unnarrowed. The WebSocket path always supplied one (`bindSubscription`'s `defaultRefilter`); the SSE and gRPC projections go through `makeQuerySubscriber`, whose `subscribeDescriptor` callback passed three arguments and dropped the trailing pair. Both boot paths were affected identically, so nothing a dev/serve parity check looks at could see it.
+
+  The same omission dropped the per-delivery guard re-check, which `data/grpc.md` and the 0.53.0 notes stated as a property: a revoked scope did not end a descriptor-query stream on those two transports. Computed queries were never affected (they re-run their handler, guards included), and neither was any app without a registered row filter.
+
+  Three things changed. `makeDefaultRefilter` moved to `@voltro/runtime`'s `rowFilter` module — it was private to the WebSocket entrypoint, and the transports that could not reach it are exactly the ones that went unfiltered. `QuerySubscriberDeps.subscribeDescriptor` takes the reauthorizer and the refilter as REQUIRED parameters, so a future transport cannot omit them by writing a shorter callback. And `dispatcher.subscribe` now THROWS, by name, when no refilter is passed while a filter is registered: reading unfiltered on purpose is available, but has to be said out loud with `NO_ROW_FILTER`. That is the same correction `ctx.rowFilter` already carries one layer up — `undefined` may mean "this app has none", never "the caller forgot".
+
+  Pinned by `subscriberTransportRefilter.test.ts`, which drives a real dispatcher through a store that evaluates predicates and asserts the foreign row never crosses the wire in ANY frame, with a positive control so an empty stream cannot pass.
+- **@voltro/cli** — **A template could not ship a font or an image — the scaffolder corrupted every binary file.** `scaffoldFromTemplate` read each file with `readFile(src, 'utf8')` and wrote the string back. That call does not throw on binary input: it substitutes U+FFFD for every undecodable sequence and returns a string, so a woff2 went in at 15 344 bytes and came out at 27 572, silently, in every scaffolded project.
+
+  Substitution is now gated on a text-extension allowlist and everything else is copied byte-for-byte. Extension-less files and dotfiles (`Dockerfile`, `.gitignore`, `LICENSE`) count as text — they carry tokens, and treating them as binary would ship a literal `{{appName}}`.
+
+  The comment above that line already claimed "we hard-fail if a template author adds one so the failure is visible at boot". There was no such check, and there could not be one on that call. There is now: a file whose extension says text but whose bytes are not valid UTF-8 is REFUSED by name rather than written corrupt, so an allowlist that is wrong about a file fails loudly instead of quietly.
+
+  Nothing could see this. `voltro-templates`' own harness classifies files itself and copies non-text ones byte-for-byte, so `pnpm test:templates` was green over a rendering the scaffolder does not perform — it validated the harness, not the scaffold a user receives.
+
+---
+
 ## [0.53.0] — 2026-08-26
 
 ### ⚠ BREAKING

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-postgis",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "description": "PostGIS plugin — postgres-native geometry/geography columns and spatial predicates (ST_DWithin, ST_Contains, ST_Intersects) for location-aware apps; declare GiST indexes via .expressionIndex(..., { kind: 'gist' }). Postgres-only; other dialects fail loud at schema emission.",
   "keywords": [
     "voltro",
@@ -33,7 +33,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.53.0"
+    "@voltro/database": "0.55.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"