@voltro/cli 0.53.0 → 0.55.0

package/templates/agent-docs/data.md

@@ -431,6 +431,15 @@ between acting on it and learning to skim it:
   recorder resolves it through the relation registry instead, target and (for a
   many-to-many) junction alike. A write to the junction changes membership,
   which is exactly the change a user makes.
+- **A `crud.*` executor is watched exactly like a hand-written one** — and it is
+  the case that needs it most. `crud.list('tasks', { include: { subTasks: true } })`
+  reads a table your own file never names, so there is nothing in front of you to
+  check `source:` against. The descriptor stays yours either way: `crud.*` supplies
+  only the executor, you write the `source:` beside it. `crud.count` counts as a
+  read too — it returns a number rather than rows, but an insert changes that
+  number, so the counted table belongs in `source:` or "page 3 of 12" stops moving.
+  `crud.create` / `update` / `remove` issue no read at all and never produce a
+  finding.
 - **A table read only to NARROW a result is not counted** — a parent reached
   through `inSubquery(...)`, or a read the framework made to resolve your row
   filter. Those decide which rows come back rather than contributing rows, and
@@ -733,9 +742,12 @@ is always present (the fallback stands in until the first snapshot) and `loading
 is a plain boolean reporting the true state. There is nothing to narrow.
 
 **Errors.** `loading` means **no data has arrived yet** — it is not a claim that
-the subscription is healthy. A **cold-start** failure (nothing ever arrived)
-leaves `loading` true *and* sets `error`, so a component that branches on
-`loading` alone renders a skeleton forever; check `error` to break out of it. A
+the subscription is healthy. A **cold-start** failure (nothing ever arrived) is
+its own state: `loading` is `false`, `failed` is `true`, and `error` is
+non-optional there, so branching on `loading` alone can no longer render a
+skeleton forever. (It used to leave `loading` true, and the type's own comment
+predicted the consequence — the fix was to stop making `loading` mean two
+things rather than to keep warning about it.) A
 failure AFTER data arrived deliberately does NOT replace good data with an error
 banner (a transient websocket hiccup would blank a working screen); those reach
 the api's error bus instead — subscribe with `useOnRpcError` for
@@ -1119,7 +1131,13 @@ export const employeesUpdate = defineMutation({
   target: {
     table: 'employees',
     op: 'update',
-    relations: { assignedStores: 'employee_assigned_stores' },
+    relations: {
+      assignedStores: {
+        junction: 'employee_assigned_stores',
+        anchorColumn: 'employeeId',   // the junction reference() pointing at `employees`
+        targetColumn: 'storeId',      // the junction's other reference()
+      },
+    },
   },
 })
 ```
@@ -1127,9 +1145,7 @@ export const employeesUpdate = defineMutation({
 After the executor succeeds, `input.assignedStores` is reconciled against the
 junction via the diff-based link writer (`store.relationLinks`): missing rows
 inserted, surplus rows deleted, unchanged rows untouched — so reactive
-subscriptions on the junction see one change per changed row. The anchor
-column is derived from the junction's `reference()` targets; a self-junction
-(both columns referencing one table) is refused by name, never guessed.
+subscriptions on the junction see one change per changed row.
 
 The semantics worth knowing: an ABSENT input field leaves the links
 untouched — absent is not empty; an empty array is the explicit "clear them
@@ -1137,6 +1153,34 @@ all". The row id comes from the executor's `output.id`, falling back to
 `input.id`. The link writes go through `ctx.store`, so undo capture and
 cross-table rules see them like any other write.
 
+### The same declaration drives the optimistic update
+
+A junction change used to reach the browser only with the server delta — so on
+one submit the renamed title flipped immediately and the assigned stores sat on
+their old value until the roundtrip landed. It does not any more: `useMutation`
+reconciles the junction rows of every subscription sourced on `junction` the
+moment the mutation is sent, against the same `input[field]` the server will
+write.
+
+It is a diff, not a redraw: a surviving link keeps its own row (and its real
+id), a surplus link disappears, and only a genuinely new link is a staged
+optimistic row. The patches ride the ordinary optimistic lane — reverted if the
+mutation fails, kept after it succeeds until the server data actually moves.
+Nothing is on a timer.
+
+Client-side the anchor id is `input.id`; for an `insert` it is the same
+optimistic id the new row was stamped with, since the server's `output.id` is
+not knowable before the response arrives.
+
+**Why you state the two columns.** The optimistic patch runs in the BROWSER, and
+the browser cannot import your `db/` schema — `@voltro/database` is server-only
+by construction — so the junction's two `reference()` columns cannot be derived
+there. `anchorColumn` is the one pointing at the target's own table;
+`targetColumn` is the other. They are not taken on trust: before it writes, the
+server compares your declaration against the junction's real reference columns
+and refuses, naming the correct pair, if they disagree. A self-junction (both
+columns referencing one table) is still refused by name, never guessed.
+
 ## Typed Errors
 
 ```ts
@@ -1717,7 +1761,7 @@ created by every migration and diffed on every boot.
 
 The other tempting option is to point `source:` at a name that resolves to
 nothing. That is worse than the empty table: the [stale-`source` boot
-warning](#fan-out--how-many-subscribers-may-one-change-wake) is the only signal
+warning](#fan-out-how-many-subscribers-may-one-change-wake) is the only signal
 for a subscription that has gone permanently quiet, and an exemption for a name
 you invented disables it for the one case it was built for.
 
@@ -1847,7 +1891,7 @@ Two consequences worth knowing:
 - **Not free per subscriber.** A publish wakes every subscriber of that channel
   and re-runs each one's executor; the channel is one routing key, so
   subscribers looking at different slices of the state are woken too. Publish on
-  a real change, not on a timer — see [Fan-out](#fan-out--how-many-subscribers-may-one-change-wake).
+  a real change, not on a timer — see [Fan-out](#fan-out-how-many-subscribers-may-one-change-wake).
 
 ## Query Executor
 
@@ -2065,9 +2109,10 @@ the resume window (`reactive.resume.windowMs`, default 60 s) the server replays
 **only the deltas the client missed** — the re-subscribe presents the last
 materialised revision and the stream continues on the same revision line, so a
 short offline gap costs a handful of patches instead of every row. Outside the
-window, for computed queries, for row-filtered apps, or whenever anything is in
+window, for computed queries, for a subscription whose source table a
+registered row filter may narrow, or whenever anything is in
 doubt, the query answers with a fresh snapshot — the delta-resume wire contract
-lives in [the wire protocol](/docs/data/wire-protocol#reconnect--delta-resume).
+lives in [the wire protocol](/docs/data/wire-protocol#reconnect-delta-resume).
 
 **What is on screen while that happens is your last-known-good data, not a
 skeleton.** The replacement cache is seeded from the one it retires, so `data`
@@ -2172,6 +2217,15 @@ subscriber on every delivery, on purpose — a role revoked or a share withdrawn
 to end the stream on the very NEXT delivery, not whenever a cache happens to
 expire — and each of them can be a database round-trip.
 
+**On every transport.** A live query can leave the server three ways — the
+WebSocket the browser client uses, an [SSE
+stream](/docs/data/rest-routes#live-updates-over-http-stream-sse), and a
+[gRPC](/docs/data/grpc) server-streaming rpc — and all three resolve per
+delivery through the same code: guards re-checked before each frame, row
+visibility re-derived from the unfiltered base descriptor for each frame, and a
+revoked scope ending the stream. The transport decides how the frame is
+framed, never what the subject may see.
+
 So deliveries run **concurrently, up to a bound**. The default is 8 in flight.
 Measured with 50 subscribers behind a 5 ms guard: 517 ms to serve all of them
 serially, 72 ms at 8 lanes.
@@ -3205,7 +3259,9 @@ es.addEventListener('delta',    (e) => applyDelta(JSON.parse(e.data)))
 
 Each event's `_tag` becomes the SSE `event:` name, so a client listens per kind instead of switching on a payload field. The framing handles the details that bite otherwise: embedded newlines are split across `data:` lines (a raw `\n` would truncate the event), a `retry:` hint is sent, and a keep-alive comment goes out every 15s so proxies don't drop an idle stream.
 
-Same guarantees as the WebSocket path, because it is the same code: the declarative `guards:`, the row filter and tenant scoping all run before anything is emitted, and the client's disconnect tears the subscription down (including a disconnect *during* setup). A guard denial arrives as one `error` event rather than an HTTP status — by then the response headers are already sent.
+Same guarantees as the WebSocket path, because it is the same code: the declarative `guards:`, the [row filter](/docs/authentication/row-level-security) and tenant scoping all run before anything is emitted, and the client's disconnect tears the subscription down (including a disconnect *during* setup). A guard denial arrives as one `error` event rather than an HTTP status — by then the response headers are already sent.
+
+And they run before **every** event, not only before the first one: the guards are re-checked and the subject's row visibility is re-resolved from the unfiltered base descriptor per delivery, so a scope revoked while the `EventSource` is open ends the stream on the next event, and a membership that ends stops carrying those rows in the next `delta`. An open SSE stream is not a cheaper read path than a fresh `GET`.
 
 `stream: 'sse'` on a mutation or action is ignored: there is nothing to subscribe to.
 
@@ -4999,11 +5055,29 @@ A resume is declined — always with a fresh snapshot — when:
 - the resuming caller is a different subject or tenant (a login, logout or
   tenant switch between disconnect and resume) — the retained history is keyed
   by subject AND tenant, so a changed identity simply never finds it;
-- the app registers a row filter (`setRowFilter`), or the query is a
-  **computed** query — both are excluded from resume by design: a row-filtered
-  subscription's visible row set exists only per delivery, and a computed query
-  re-runs a handler with no delta chain to replay. They reconnect with a fresh
-  snapshot, exactly as before.
+- the query is a **computed** query — it re-runs a handler, so there is no
+  delta chain to replay;
+- a registered row filter (`setRowFilter`) can narrow THIS subscription's
+  source table, or the query declares an eager `.with(...)`. A row-filtered
+  subscription's visible row set exists only per delivery, so replaying it
+  could serve rows the subject has since lost.
+
+  **This is per table, not per app.** A filter that declares
+  `tables: [...]` (see [row-level security](/docs/authentication/row-level-security))
+  keeps delta-resume on every subscription whose source is not in that set —
+  the common case, since most filters narrow a handful of tables. Without the
+  declaration the framework cannot know which tables the predicate may reach
+  and excludes them all. Eager loads are excluded wholesale because a relation
+  resolves below the seam that narrows. They reconnect with a fresh snapshot,
+  exactly as before.
+
+**Which of your queries actually got a ring** is recorded per label, since the
+excluded and the never-eligible look identical on the wire:
+`/_voltro/inspect/subscriptions` returns a `resume` array of
+`{ label, resumable, excluded }`, and `voltro dev` logs each verdict once under
+the `voltro:resume` scope. A `computed` verdict is the one worth reading first:
+it means the executor returns a value rather than a descriptor, so no row-filter
+declaration can ever change it.
 
 **Author a live-subscribed getter to return, not throw.** A subscription is a
 long-lived stream, so a getter that throws on every re-evaluation is a broken
@@ -6101,6 +6175,8 @@ export default {
     port: 50051,
     procedures: ['orders.get', 'orders.list', 'orders.create'],
     // tls: { certPath, keyPath, caPath? } — plaintext without it (dev / mesh).
+    // drainMs: 5000,        // shutdown drain budget — see below
+    // maxMessageBytes, maxMetadataBytes — grpc-js frame limits
   },
 }
 ```
@@ -6112,6 +6188,21 @@ works out of the box). The gRPC packages ship as script-free optional
 dependencies of `@voltro/cli`; a configured `grpc:` block with them missing
 refuses the boot by name.
 
+## Shutdown drains, then forces — `drainMs`
+
+On SIGTERM the surface flips its health status to `NOT_SERVING` (so a load
+balancer stops sending it work) and gives open calls **`drainMs`** to finish
+before force-closing them. Default `5000`; `0` forces immediately; the env
+override is `VOLTRO_GRPC_DRAIN_MS`.
+
+Pick it from two numbers only you have. Keep it **below** your orchestrator's
+termination grace (`terminationGracePeriodSeconds`, `docker stop -t`) — past
+that point SIGKILL arrives and the drain never completes, so a larger budget
+buys nothing. Keep it **above** your longest legitimately in-flight unary
+call, or every rolling deploy force-closes work that would have finished. When
+the budget is exceeded the surface says so in a warning naming the budget,
+rather than leaking the port into the next boot.
+
 ## Field numbers are managed — `grpc.manifest.json`
 
 Field numbers are the proto wire identity, so they may never depend on
@@ -6169,10 +6260,19 @@ sleeping action whose post-sleep write never lands).
 A `query` becomes a **server-streaming** rpc: each frame is the CURRENT full
 snapshot, re-pushed live when the query's `source:` changes — subscribe,
 mutate from anywhere, and the open stream receives the new frame with no
-re-request. The per-delivery guard re-check applies (a revoked scope ends
-the stream with the mapped status), and slow consumers are handled through
-grpc-js write backpressure — frames coalesce to the latest snapshot rather
-than buffering unboundedly.
+re-request.
+
+**Authorization is re-derived per FRAME, not frozen at open.** Before every
+delivery the framework re-runs the query's `guards:` and re-resolves the
+subject's [row-level visibility](/docs/authentication/row-level-security)
+from the unfiltered base descriptor. A revoked scope ends the stream with the
+mapped status; a membership that ends mid-stream stops carrying those rows in
+the next frame, with the stream itself untouched. This is the same code the
+WebSocket and SSE transports run — an open gRPC stream is not a cheaper read
+path than a fresh call.
+
+Slow consumers are handled through grpc-js write backpressure — frames
+coalesce to the latest snapshot rather than buffering unboundedly.
 
 ## Declared limits (v1)
 

package/templates/agent-docs/database/advancedqueries.md

@@ -627,7 +627,7 @@ await ctx.store.update('notes', id, {
 
 Two layers of validation apply:
 
-1. **JSON validity** — that the stored bytes are well-formed JSON — is enforced automatically by the database on every dialect (see [Storage + validation per dialect](#storage--validation-per-dialect)). You don't declare anything.
+1. **JSON validity** — that the stored bytes are well-formed JSON — is enforced automatically by the database on every dialect (see [Storage + validation per dialect](#storage-validation-per-dialect)). You don't declare anything.
 2. **JSON *shape*** — that the value matches your expected structure — is up to you: enforce it at the table level with `table().validate(Schema)`:
 
 ```ts

package/templates/agent-docs/database/migrations.md

@@ -700,7 +700,7 @@ A handler that a `voltro dev` session or a test actually ran is reported with wh
 
 ### What the codemod does per kind
 
-- **`rename-column`** gets a real `transform`: it renames the field in the `*.entity.ts` AND chains **`.renamedFrom('old')`** (so the differ plans a catalog RENAME, not the lossy drop+create described [above](#renamedfromoldname)), then annotates the handler sites the blast radius found.
+- **`rename-column`** gets a real `transform`: it renames the field in the `*.entity.ts` AND chains **`.renamedFrom('old')`** (so the differ plans a catalog RENAME, not the lossy drop+create described [above](#renamedfrom-oldname)), then annotates the handler sites the blast radius found.
 - **`retype-column` / `split-column` / `drop-column` / `rename-table`** are reshaping changes with no single mechanical rewrite, so they get a **`manual`** codemod: a generated, numbered checklist of the edits + the annotation to add, printed for you to apply.
 
 `voltro evolve` produces the plan; it does not apply the schema change. **`voltro check` is the gate on the result**, and `voltro db apply` lands it — after `--write`, review the annotated handlers, then run those two.

package/templates/agent-docs/database/seedsdialects.md

@@ -391,7 +391,7 @@ What the framework hides for you vs what's worth knowing. Per-dialect pages dril
 | `RETURNING *` on DELETE                   | yes             | no              | yes (10.0+)     | OUTPUT DELETED.* | yes | yes |
 | Parameterized `LIMIT ?`                   | yes             | no — integer-literal inlined | yes | no — integer-literal inlined | yes | yes |
 | `LIMIT N OFFSET N` syntax                 | yes             | yes             | yes             | no — `OFFSET … ROWS FETCH NEXT … ROWS ONLY` | yes | yes |
-| DEFAULT on TEXT columns                   | yes             | **NO** — auto-uses VARCHAR(255) | yes | yes (NVARCHAR(MAX)) | yes | yes |
+| DEFAULT on TEXT columns                   | yes             | **NO** — framework emits VARCHAR(255) | yes — framework still emits VARCHAR(255) (engine parity) | yes — framework emits NVARCHAR(450) (indexable) | yes | yes |
 | Native JSON column type                   | JSONB           | JSON            | JSON            | NVARCHAR(MAX)    | TEXT                | TEXT               |
 | JSON columns returned as objects          | yes             | yes             | yes             | **no — strings** — framework auto-parses | **no — strings** — framework auto-parses | **no — strings** — framework auto-parses |
 | Booleans                                  | proper booleans | 0/1 (TINYINT)   | 0/1             | BIT (proper bool) | 0/1 (INTEGER)     | 0/1 (INTEGER)      |
@@ -796,11 +796,48 @@ The framework's DDL emitter detects the case and switches to `VARCHAR(255)`:
 ```typescript
 text().default('json')                     // → VARCHAR(255) DEFAULT 'json'
 text().oneOf(['a', 'b', 'c']).default('a') // → VARCHAR(255) DEFAULT 'a' CHECK (col IN ('a','b','c'))
-text().nullable()                          // → TEXT (unchanged — no default to trip up)
+text().nullable()                          // → LONGTEXT (unchanged — no default to trip up)
 ```
 
 VARCHAR(255) is the framework's heuristic — enough for typical enum-like values, short status strings, format identifiers. If you need longer defaulted text, declare the column as `text().nullable()` + handle the missing-default case in application code, OR drop down to `unsafe()`.
 
+### Adding a default to an existing column
+
+The rule holds for a migration too, not only for `CREATE TABLE`. Adding
+`.default(…)` to a `text()` column that already exists **reshapes** the column
+rather than setting a default on it:
+
+```sql
+ALTER TABLE tickets MODIFY COLUMN `status` VARCHAR(255) NOT NULL DEFAULT 'active'
+```
+
+That is deliberate, and it is what makes the change appliable at all: a plain
+`ALTER TABLE … ALTER COLUMN status SET DEFAULT 'active'` is answered by MySQL
+with `BLOB, TEXT, GEOMETRY or JSON column 'status' can't have a default value`,
+so the migration would stop half-applied. Reshaping means the column has the same
+type whether the default was declared before or after the table existed.
+
+Two consequences worth knowing before you run it:
+
+- **It is a narrowing.** If a row already holds more than 255 characters, the
+  ALTER fails (`Data too long for column 'status'`) and the migration stops
+  before it. Check first, and pick the width yourself with
+  `text().maxLength(n).default(…)` if 255 is too small:
+
+  ```sql
+  SELECT COUNT(*) FROM tickets WHERE CHAR_LENGTH(status) > 255
+  ```
+
+- **Removing a default does not reshape back.** `DROP DEFAULT` is legal on any
+  mysql type, and widening a `VARCHAR(255)` back to `LONGTEXT` would fail for an
+  indexed column — so the column keeps its bounded type. Declare
+  `text().maxLength(255)` if you want that to be visible in the schema.
+
+SQL Server does the same thing for its own reason (an `NVARCHAR(MAX)` column
+cannot be indexed, so a defaulted text column is `NVARCHAR(450)`). On postgres a
+`TEXT` column takes a `DEFAULT` directly, and SQLite rebuilds the table to the
+declared shape — neither reshapes anything.
+
 ## JSON columns
 
 `json()` columns emit `JSON` (mysql's native binary JSON type since 5.7+). The driver auto-parses on read; same shape as postgres. No coercion overhead.
@@ -1187,6 +1224,31 @@ When the caller didn't supply an `orderBy` but did set `skip` (uncommon but lega
 
 The compiler inlines integer literals for TOP/OFFSET/FETCH NEXT values rather than parameter binding. Same rationale as MySQL — tedious has bind-as-INT issues with large or unexpected-typed numeric params.
 
+## Text columns with a DEFAULT — NVARCHAR(450)
+
+A plain `text()` column is `NVARCHAR(MAX)`, which SQL Server cannot index. A text
+column that carries a literal default or a closed value set is therefore emitted
+bounded, at `NVARCHAR(450)` — under the 900-byte single-column key limit, so it
+stays indexable:
+
+```typescript
+text().default('open')                 // → NVARCHAR(450) + a DEFAULT constraint
+text().oneOf(['open', 'closed'])       // → NVARCHAR(450) + a CHECK constraint
+text().nullable()                      // → NVARCHAR(MAX)
+```
+
+This holds for migrations as well as for `CREATE TABLE`: adding `.default(…)` to
+an existing text column retypes it to `NVARCHAR(450)` and then adds the default
+constraint, so the column has the same type whether the default was declared
+before or after the table existed. It is a narrowing — if a row already holds
+more than 450 characters, the `ALTER COLUMN` fails ("String or binary data would
+be truncated") and the migration stops there. Check first, and use
+`text().maxLength(n).default(…)` to choose a different width:
+
+```sql
+SELECT COUNT(*) FROM tickets WHERE LEN(status) > 450
+```
+
 ## JSON columns — NVARCHAR(MAX) + auto-parse
 
 `json()` columns emit `NVARCHAR(MAX)` in DDL — mssql has no native JSON type pre-2025. Validation goes through `ISJSON(col) = 1` CHECK constraints; serialization is application-side.

package/templates/agent-docs/internationalization.md

@@ -78,6 +78,8 @@ Server-side, the active locale is determined by, in priority order:
 2. **`Accept-Language` header** — the browser/OS preference, q-weighted and sorted per RFC 4647.
 3. **`defaultLocale`** — last-resort fallback.
 
+**One resolver decides, and everything the server renders for that request reads its answer** — the page render and its `<I18nProvider>`, the `<html lang>` attribute, the ISR cache key (so a language switch cannot re-serve the previous locale's cached HTML), and the validation errors an [`<AutoForm>` renders on the no-JavaScript form-POST path](/docs/ui/forms-and-tables#forms-without-javascript). That last one is worth naming because a server has no `<html lang>` to read yet at the time it validates; deriving the locale a second way there would answer `en` for every request.
+
 The resolved locale is **guaranteed** to be one of the codes in `locales`. Any unsupported value (a cookie pointing at a code you no longer ship, a browser asking for `xx-YY`) falls through to the next signal. RFC 4647 lookup strips subtags one segment at a time — `de-CH-1996` → `de-CH` → `de` — so a `de` catalog serves a `de-CH` browser.
 
 The client **adopts what the server resolved**, reading it from the `<html lang>` attribute the server render sets, then falling back to the cookie and the default. `Accept-Language` is never read in the browser: `navigator.languages` can diverge from what the server saw.

package/templates/agent-docs/introduction.md

@@ -544,6 +544,16 @@ export const searchParams = Schema.Struct({
 
 - `searchParams` (an `effect/Schema` struct — every field optional or with a default) types the page's query string: `useSearchParams(searchParams)` returns the decoded shape, and links built with `withQuery` type-check against it. Details: [Pages → Query strings](/docs/routing/pages#query-strings).
 
+Two more page exports change what the framework produces for a route:
+
+```tsx
+export const ogImage = ({ params, loaderData, locale }) => ({ type: 'div', props: { /* satori JSX */ } })
+export const intercept = { from: '/photos' }
+```
+
+- `ogImage` declares the page's `og:image` as a satori JSX template. `static` pages render the PNG at BUILD time into `dist/assets/og/`; `ssr` pages render it on demand over a signed route. The `og:image` / `twitter:image` / `twitter:card` tags are injected automatically unless your own `meta` already sets them. A declared font is REQUIRED (there is no bundled default), and an `ssr` route exporting it needs `VOLTRO_OG_SECRET` — `voltro start` refuses the boot otherwise. Details: [Loaders and meta → OG images](/docs/routing/loaders-and-meta#og-images-from-a-template-ogimage).
+- `intercept` makes the page an **intercepting route**: `from` names one or more ROUTE PATTERNS (`'/photos'`, `['/photos', '/albums/[id]']`), and a soft navigation arriving from one of them renders this page as an overlay above the still-mounted origin. Every hard load — and a soft navigation from anywhere else — renders it standalone. Details: [Intercepting routes](/docs/routing/intercepting-routes).
+
 ## Discovery in practice
 
 ```text
@@ -605,11 +615,26 @@ If yes, the promise belongs in the name — you cannot see a contract before you
 | `*.store.ts` | exactly one `defineStore`, no server state | `store/one-per-file`, `store/mirrors-server-state` |
 | `*.collection.ts` | declares content collections (`defineCollection`); frontmatter schema violations fail the build naming the file | the build's collection decode + reference validation |
 | `*.consumer.ts` | declares queue consumers (`defineQueueConsumer`, @voltro/plugin-queue); loading registers, the plugin's activation starts them | the queue runner (decode→DLQ, retry→DLQ, commit-per-message) |
+| `*.ws.ts` | default-exports one raw WebSocket gateway (`defineWebSocket`), mounting its own upgrade path beside the rpc socket | boot discovery on BOTH paths (`voltro dev` and `voltro serve`); two gateways on one path refuse the boot |
 
 A `*.component.tsx` promises exactly ONE component. It does not promise to export nothing else: types, and plain module-local values a `const COLUMNS = […]` beside the table that renders them, are fine and always were. What the rule counts is components — a declaration that renders — so an object, an array, a string or a `new` beside your component is not a second one, and neither is `export default Card` next to `export const Card`.
 
 The BOUNDARY rules (`internal/foreign-import`, `fixture/production-import`, `ui/unlinked`) are assertions about your import graph, so it is worth knowing which edges they follow: relative specifiers, your tsconfig `paths` aliases (read from the nearest `tsconfig.json`, so a per-app `@/*` works when you run `voltro doctor` at the repo root), `export … from` re-exports, and dynamic `import()`. A package import is a leaf — the walk stops at the edge of your app.
 
+## Contracts that are not suffixes
+
+The admission test above is about the PROMISE, not about the spelling — and three of the framework's conventions carry one without being a suffix on a filename. They are listed here because a reader looking for "what does the framework read out of my tree" would otherwise stop at the table:
+
+| Convention | Promise | Read by |
+|---|---|---|
+| `searchParams` page export | the page's query string decodes through this `effect/Schema` struct — every field optional or with a default | `useSearchParams(searchParams)`, `withQuery` link typing, and the render-mode scan (a page declaring BOTH `renderMode: 'isr'` and `searchParams` is refused) |
+| `ogImage` page export | this route's `og:image` is a satori JSX template, not a file you ship | the build (`static` → a hashed PNG in `dist/assets/og/`) and `voltro start` (`ssr` → a signed on-demand route, which needs `VOLTRO_OG_SECRET`) |
+| `intercept` page export | `from` names the routes a soft navigation may arrive from for this page to render as an overlay above them | the client router; a hard load renders the page standalone regardless |
+| `grpc.manifest.json` (app root) | field numbers are checked in and append-only — a deleted field goes `reserved`, never re-used | `voltro grpc proto` and the gRPC surface wiring, which derive wire identity from it rather than from declaration order |
+| `content/<name>/**` | the files a `*.collection.ts` declares — markdown with frontmatter, or `.json` for a data collection | `getCollection` / `getEntry`, the build's collection artifacts, and the dev server's watcher |
+
+The page exports are per-ROUTE and the last two are per-APP, which is the only reason they cannot be spellings: there is nothing to rename.
+
 ## `*.component.ui.tsx` — reads, never writes
 
 ```tsx