@voltro/cli 0.50.0 → 0.51.0

package/dist/webDev-DposiF3j.js

@@ -0,0 +1,2 @@
+import { _ as e, y as t } from "./webDev-B-ubQEMX.js";
+export { e as tryRunWebServe, t as walkPagesTree };

package/dist/{webhooksCommand-B0bdyuQ4.js → webhooksCommand-FLYY9IXh.js}

@@ -222,7 +222,7 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev-BWwE0QjK.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-CK522MV5.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
 	return r((await n(await t(e))).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -694,6 +694,30 @@
         "title": "`InterruptedReplace.tables` is `number | null`",
         "kind": "manual"
       },
+      {
+        "version": "0.51.0",
+        "id": "0.51.0/01_computed-source-keeps-its-names",
+        "title": "A COMPUTED `source:` can keep its typed names — do not widen the whole registry",
+        "kind": "manual"
+      },
+      {
+        "version": "0.51.0",
+        "id": "0.51.0/02_restore-refuses-without-marker",
+        "title": "`voltro data restore` refuses when it cannot write the in-progress marker",
+        "kind": "manual"
+      },
+      {
+        "version": "0.51.0",
+        "id": "0.51.0/03_restore-assets-returns-counts",
+        "title": "`restoreAssetsFromCas` returns `{ count, objects }`, not a number",
+        "kind": "manual"
+      },
+      {
+        "version": "0.51.0",
+        "id": "0.51.0/04_i18n-timezone-prop",
+        "title": "`<I18nProvider>`: `timeZone` is its own prop, not an `intlConfig` member",
+        "kind": "transform"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -769,22 +793,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.50.0",
-    "@voltro/cache": "0.50.0",
-    "@voltro/data-transfer": "0.50.0",
-    "@voltro/database": "0.50.0",
-    "@voltro/env": "0.50.0",
-    "@voltro/kv": "0.50.0",
-    "@voltro/logger": "0.50.0",
-    "@voltro/plugin-auth": "0.50.0",
-    "@voltro/plugin-broadcast": "0.50.0",
-    "@voltro/plugin-mail": "0.50.0",
-    "@voltro/plugin-storage": "0.50.0",
-    "@voltro/plugin-webhooks": "0.50.0",
-    "@voltro/protocol": "0.50.0",
-    "@voltro/runtime": "0.50.0",
-    "@voltro/serverless": "0.50.0",
-    "@voltro/workflow": "0.50.0",
+    "@voltro/ai": "0.51.0",
+    "@voltro/cache": "0.51.0",
+    "@voltro/data-transfer": "0.51.0",
+    "@voltro/database": "0.51.0",
+    "@voltro/env": "0.51.0",
+    "@voltro/kv": "0.51.0",
+    "@voltro/logger": "0.51.0",
+    "@voltro/plugin-auth": "0.51.0",
+    "@voltro/plugin-broadcast": "0.51.0",
+    "@voltro/plugin-mail": "0.51.0",
+    "@voltro/plugin-storage": "0.51.0",
+    "@voltro/plugin-webhooks": "0.51.0",
+    "@voltro/protocol": "0.51.0",
+    "@voltro/runtime": "0.51.0",
+    "@voltro/serverless": "0.51.0",
+    "@voltro/workflow": "0.51.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -404,11 +404,21 @@ Do NOT write `x.page.tsx`, `index.page.tsx` or `[id].page.tsx` — those were th
 **Every suffix above is a CONTRACT, not a label.** Something else depends on each
 promise, and `voltro doctor` enforces all of them:
 
-- `*.component.ui.tsx` may read (`useT`, `useCan`, `usePermissions`) but must
-  never import a write hook (`useMutation`, `useAction`, `useUpload`, …). That is
-  what lets a caller render it ten thousand times in a list, reuse it across
-  features, and prerender it without reading its source. Lift the write into the
-  owning `*.component.tsx` and pass a handler down.
+- `*.component.ui.tsx` may read (`useT`, `useTFn`, `useCan`, `usePermissions`,
+  the `@voltro/i18n` formatters) but must never import a write hook
+  (`useMutation`, `useAction`, `useUpload`, …). That is what lets a caller render
+  it ten thousand times in a list, reuse it across features, and prerender it
+  without reading its source. Lift the write into the owning `*.component.tsx`
+  and pass a handler down.
+
+  **Reading is a recommendation, not a grudging allowance — call the hook, do
+  not take a prop.** Threading `t` / `formatDate` / `useCan` through props is
+  prop-drilling: it grows the prop surface with every formatter, has to be
+  restated in every intermediate signature and every test, and does NOT make the
+  component more reusable — it makes every call site worse. The one argument for
+  the prop, "it renders without a provider", is already paid for the moment any
+  test mounts one. Pick one way per component head: a `t` prop beside a
+  formatter hook is the worst of both.
 - `*.internal.ts` is the promise that refactoring inside that directory breaks
   nobody. An import from another subtree revokes it.
 - `*.types.ts` having no runtime export is what makes importing it free and makes

package/templates/AGENTS.md

@@ -404,11 +404,21 @@ Do NOT write `x.page.tsx`, `index.page.tsx` or `[id].page.tsx` — those were th
 **Every suffix above is a CONTRACT, not a label.** Something else depends on each
 promise, and `voltro doctor` enforces all of them:
 
-- `*.component.ui.tsx` may read (`useT`, `useCan`, `usePermissions`) but must
-  never import a write hook (`useMutation`, `useAction`, `useUpload`, …). That is
-  what lets a caller render it ten thousand times in a list, reuse it across
-  features, and prerender it without reading its source. Lift the write into the
-  owning `*.component.tsx` and pass a handler down.
+- `*.component.ui.tsx` may read (`useT`, `useTFn`, `useCan`, `usePermissions`,
+  the `@voltro/i18n` formatters) but must never import a write hook
+  (`useMutation`, `useAction`, `useUpload`, …). That is what lets a caller render
+  it ten thousand times in a list, reuse it across features, and prerender it
+  without reading its source. Lift the write into the owning `*.component.tsx`
+  and pass a handler down.
+
+  **Reading is a recommendation, not a grudging allowance — call the hook, do
+  not take a prop.** Threading `t` / `formatDate` / `useCan` through props is
+  prop-drilling: it grows the prop surface with every formatter, has to be
+  restated in every intermediate signature and every test, and does NOT make the
+  component more reusable — it makes every call site worse. The one argument for
+  the prop, "it renders without a provider", is already paid for the moment any
+  test mounts one. Pick one way per component head: a `t` prop beside a
+  formatter hook is the worst of both.
 - `*.internal.ts` is the promise that refactoring inside that directory breaks
   nobody. An import from another subtree revokes it.
 - `*.types.ts` having no runtime export is what makes importing it free and makes
@@ -707,7 +717,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.50.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.51.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.50.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.51.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/cli.md

@@ -290,6 +290,19 @@ carries its own guards, or it is a UI-affordance scope that `useCan` reads to
 hide a button and no server check backs on purpose. All three are fine. Not
 knowing which is not.
 
+`rbac/unguarded-mutation` flags a mutation that declares neither a guard nor an
+`openAccess:` reason. It skips **`internal: true`** procedures: those are in no
+rpc group and on no route, so "any caller who can reach the rpc surface" names a
+surface that does not exist — and neither remedy applies either, since a guard
+would protect nothing and `openAccess` is refused outright on an internal
+descriptor. This is the same `isWireReachable` predicate the boot access gate and
+all three rpc-group assemblies use, so `check` and `voltro doctor` cannot answer
+the question differently.
+
+A manifest that does not carry the field at all — an api older than it — is read
+as *reachable*, not as internal. The rule stays loud rather than going quiet on
+the apps least able to notice.
+
 #### Declared vs OBSERVED — reconciled against reality
 
 A query's `source` and a mutation's `targets` are not documentation: the
@@ -323,6 +336,30 @@ Three things about that output are deliberate:
   about the runs that happened, not a proof about the ones that didn't, and
   `check`'s exit code gates CI. They are always warnings.
 
+A fourth thing is not visible in that output and matters more than any of the
+three: **the recorder only knows what ran.** A boot is not a run. An idle dev
+instance that started, served nothing and stopped produces
+
+```
+observed: 0/2755 procedures exercised (0%)
+  2753 unexercised — no recording, so nothing is claimed about them
+```
+
+which is the honest answer and also a useless one — the section says nothing
+about 99.9% of the surface. If you want this as a CI gate, the recording pass has
+to be a run that actually *calls* the procedures. `voltro e2e` is one: it spawns
+`voltro dev` for the api, which turns recording on, and then drives the specs. A
+harness of your own that boots the app in its own process needs
+`VOLTRO_OBSERVE_GRAPH=1` set before anything is imported. Either way, booting the
+app and then running `check` measures nothing, and the report will not pretend
+otherwise.
+
+It is still worth wiring up at low coverage, because the findings are per
+procedure and do not need company. One deployment had exactly one procedure
+observed, and that one produced a real defect: a mutation upserting
+`push_subscriptions` with no declared target while two queries read that table as
+their `source`, so a registered device never appeared in any running subscription.
+
 No file → the section is skipped silently. This is not derived by parsing your
 handlers: a static pass over code that reaches the store through shared helpers,
 behind conditionals, has a long tail of both false positives and false negatives
@@ -3337,10 +3374,17 @@ voltro data restore ./backups/2026-07-01 --assets    # pg_restore / mariadb /
 
 These shell out to the vendor tools resolved from your `DB_DIALECT` + connection env. They produce a dialect-native artifact (`db.dump`, `db.sql`, `db.sqlite`, `db.bacpac`) that is lossless and point-in-time consistent for **same-dialect** restore — the right tool for disaster recovery. Secrets are passed via the tools' environment variables (`PGPASSWORD`, `MYSQL_PWD`), never on the command line, where the tool supports it. The named tool must be installed and on `PATH`.
 
+On **mariadb** the MariaDB-named binaries (`mariadb-dump`, `mariadb`) are preferred and Oracle's (`mysqldump`, `mysql`) are the fallback — with the reason carried into the failure, because the error that fallback produces (`Unknown table 'COLUMN_STATISTICS' in information_schema`, 1109) names a table nobody asked for. Two things worth knowing before you go and install the MariaDB client package:
+
+- Do **not** reach for `--column-statistics=0`. That flag does not exist on `mariadb-dump`, so it patches the wrong client and breaks the right one.
+- A MariaDB **12.x** client requires TLS by default. Running it *by hand* against a server without TLS fails with `TLS/SSL error: SSL is required` (2026) and needs `--skip-ssl`. These commands are not affected — it is the first manual call after installing that trips.
+
 ### `--assets` — the blobs are not in the dump
 
 A vendor dump contains rows. Your blobs are in object storage, and no `pg_dump` has ever seen them. So a rows-only backup restores a database whose rows reference objects that are not there — and the reference and the object are checked at different times, which is why that state is discovered by a user, months later, rather than by the restore.
 
+The backend it reads is the one your app **configured** — `storagePlugin({ provider: s3(…) })` if you installed it, the `STORAGE_*` env otherwise. (The commands used to resolve the env default unconditionally, so an app that configured its provider in code had its export, import and backup reading a different backend than the rest of it.)
+
 `--assets` captures them alongside the dump, through the same content-addressed pipeline `voltro data export --assets` uses: each blob is streamed (never buffered whole), stored under `assets/<sha256>` so identical content is stored once, and listed in `assets/index.ndjson`. `restore --assets` streams them back and **re-hashes on the way**, so a corrupted artifact can never silently overwrite good bytes.
 
 ```
@@ -3353,28 +3397,73 @@ backups/2026-07-01/
 
 Three refusals, each for a belief that is otherwise acted on silently:
 
-- **`backup --assets` with no storage provider configured → refused.** There is nothing to capture, and a flag that is accepted and ignored lets you build a rollback story on an artifact that does not contain what you asked for.
+- **`backup --assets` with no storage provider configured → refused.** There is nothing to capture, and a flag that is accepted and ignored lets you build a rollback story on an artifact that does not contain what you asked for. "Configured" means one of the two things a person actually did: installed `storagePlugin(...)`, or set `STORAGE_PROVIDER`. An in-memory provider nobody asked for is not a decision — and until recently it was what this check saw, which is why the refusal never fired and `--assets` wrote artifacts stamped as carrying blobs that held none.
 - **`restore --assets` on a rows-only backup → refused.** You believe the blobs are in there. Restoring the rows anyway produces exactly the dangling state this exists to prevent.
 - **restore *without* `--assets` on a backup that HAS them → warned, not refused.** Restoring rows without blobs is legitimate (a schema drill, a lower environment), and refusing it would push people at `--force`.
 
+**A reference the provider cannot resolve is reported, not fatal.** A row in `_voltro_storage_refs` can point at an object that was deleted, or that never arrived because an earlier import ran without `--assets`. That is a fact about your data, and no backup can put back bytes that are not there — so the capture records the key, steps over it, and the run says how many:
+
+```
+warn  177 of 178 blob reference(s) point at objects the storage provider does not have;
+      they are NOT in this backup and no restore can bring them back.
+```
+
+Aborting on the first one made `--assets` unusable for exactly the deployment that needed it: 178 references, one resolvable, and the run stopped at the second — leaving an `assets/` directory with a single blob, **no `voltro-backup-stamp.json`** (the writer never got that far), and nothing anywhere saying 177 objects had been skipped. The stamp is now written on every path, including the one where the asset phase fails, because it describes the **dump** and the dump is already on disk and correct. Without it, `restore` greeted an artifact this tool had written minutes earlier with *"an older/handmade backup. Cannot verify dialect or schema version."*
+
+Only a genuine *not found* is treated this way. A 403 from a rotated credential or a 5xx from a backend outage still fails the capture — calling those "the object is gone" would turn a recoverable outage into a backup that quietly contains nothing.
+
+**Three numbers, because they answer three questions.** `_voltro_storage_refs` holds one row per *reference*, several of which legitimately name one *key*, and the content-addressed store keeps one body per distinct *object*:
+
+```
+57 reference(s) → 16 key(s) → 16 object(s), 65476 byte(s) under assets/
+```
+
+The stamp carries all three (`references`, `count`, `objects`, with `totalBytes` and `objectBytes` beside them). It used to carry only the reference count under the name `count`, so a stamp read `57` over a directory holding 16 files — and anyone answering *"are all the blobs there?"* after a restore compared the two and found a 3.5× gap that was not one. A key named by several references is also fetched once now, rather than downloaded and hashed once per row.
+
 Resume is per blob key, so re-running a `--assets` capture that was interrupted transfers only what is missing. The **dump itself has no resume** — a vendor artifact is one opaque file with no offset to restart from. If you need a resumable, chunkable, observable transfer, that is the logical path (`export` / `import`), and it is why the logical path exists.
 
+### The stamp's skew warning compares the backup against the TARGET
+
+`restore` reads `voltro-backup-stamp.json` before touching anything and warns when the backup's schema fingerprint differs from the target's. That warning used to say the difference was against "what this code declares", and it was not — the value it compares against is the target database's *live* schema, read by introspection at restore time. Bringing a target to the backup's shape makes the warning disappear while the declared fingerprint is a third value entirely, which is how the mislabel was caught. The comparison was always the useful one; only the sentence was wrong, and it sent readers looking for a code change where a database differed.
+
+The same distinction shows up in `voltro db plan`, which prints `live … · declared …` rather than `from → to` for the same reason: **a hash of a live database never equals the hash of the declaration it came from.** Introspection cannot recover everything a declaration carries — generated expressions, `maxLength`, sensitivity markers — so the two are not comparable and are not meant to match. The plan's operation list is what says whether they agree; `0 operations` under two different fingerprints means they do.
+
 ### A restore that is interrupted refuses the next boot
 
 `restore` writes one row into `_voltro_replace_in_progress` **before** the first destructive statement and removes it **after** the last write — the blobs included. Its presence at boot is a refusal naming the artifact that was going in.
 
 This is the counterpart to `--allow-live`, and it guards from the other side: `--allow-live` asks you not to restore over a running instance, and this says *this database is mid-restore, do not serve it*. A half-restored database looks exactly like a normal one from the inside — every query answers, nothing errors.
 
-Whether the marker survives the restore depends on the dialect's restore shape, and that is stated rather than implied:
+**The restore artifact can erase the marker, and this table said otherwise.** It read "postgres, mysql, mariadb: drops only the objects the dump names — the marker survives". The reasoning is right and the premise was wrong: a native dump names the *whole* database, `_voltro_replace_in_progress` included, and a mysql-family restore writes `DROP TABLE IF EXISTS` in front of each table. The table sorts early, so the guard was removed near the *start* of the window it covers. Measured downstream: one row before the restore, zero after, twice.
+
+Two changes, covering different dumps:
+
+- **A backup taken by `voltro data backup` excludes the marker table** (`--exclude-table` / `--ignore-table`). It can no longer carry the thing that erases the guard on the way back in.
+- **`restore` writes the marker back after the tool exits**, on the failing path as well as the succeeding one. That covers dumps taken before this version and dumps made by hand. If it was removed and rewritten you get a warning saying so; if it could not be rewritten you get an error, because the guard is then off for that run and nothing will stop the next boot.
+
+**A restore that cannot write the marker at all is refused.** Two things can prevent it — the bookkeeping store will not open (wrong credentials, an unreachable database, a missing env var, no `app.config.ts` from here), or the table is not there yet — and both mean the same thing to you: this restore would run with no guard. The refusal names which one it was:
+
+```
+✗ refusing to restore: the in-progress marker cannot be written.
+    reason: bookkeeping is unavailable: connect ECONNREFUSED 127.0.0.1:5432
+```
+
+This used to be a silent hole rather than a refusal, and worse than silent. The failure to open the store was caught and discarded, and the discarded value guarded *every* branch below it — including the refusal that would have reported the guard missing. So a restore ran on and, over a database with zero marker rows, printed *"the next boot will REFUSE, by design"*. The next boot did not refuse, and `voltro data clear-replace-marker` had nothing to clear. A restore is the operation you run against a target that is already unwell, so the precaution was falling away exactly when it was needed.
+
+**`--no-marker`** restores without the guard, deliberately. It warns every time and names the reason the marker was unavailable. It exists because the accidental way did: if going unguarded is ever right, it should be something you typed.
 
 | dialect | shape | effect |
 |---|---|---|
-| postgres, mysql, mariadb | drops only the objects the dump names | the marker survives, so a killed restore is caught at the next boot |
+| postgres, mysql, mariadb | the dump names the whole database, so the restore drops the marker table too | our backups exclude it; for any other dump the marker is written back after the tool exits |
 | sqlite, turso | whole-file replacement — made **atomic** (temp file + rename) | there is no half-restored state to catch; a killed restore leaves the live file untouched |
 | mssql | `sqlpackage /Action:Import` replaces the database | a *failed* import is the one case not covered here — verify with `--drill` |
 
 Clear a marker deliberately with `voltro data clear-replace-marker --yes` once you have decided the current state is correct.
 
+**`_voltro_data_transfers` is excluded for the same reason, one table over.** The restore opens its own run row there *before* the tool starts; a dump that carried the table dropped it mid-flight, and the update recording the outcome then wrote into a table that no longer held the row. The visible result was that a failed native restore did not appear in `voltro data transfers` at all — only the `backup` row the dump had brought over from the *source* database. The command that answers "did the restore finish" could not see the run asking.
+
+Exactly those two tables are excluded, and the line is deliberate: a native restore into the same deployment *should* bring the migration ledger, the stored plans, the CDC offsets and the schedule claims — they describe the data being restored. These two describe the *restore*, and a record of an operation must not be overwritten by the operation it records.
+
 ### Both directions are in the history
 
 `backup` and `restore` write a row to the same `_voltro_data_transfers` record `import` and `export` use, so `voltro data transfers` answers "did last night's backup finish" from the instance that ran it:

package/templates/agent-docs/data.md

@@ -1700,6 +1700,32 @@ That matters because the failure it replaces is silent. A `source:` is matched b
 
 The file is generated, so **commit it** like the rpc group and let `voltro dev` rewrite it. Before the first run — and in a project that never generates it — `source:` is plain `string` again, which is exactly the previous behaviour; there is no configuration and nothing to opt into.
 
+The error carries a suggestion when the name is close to a real one — `Did you mean '"error_logs"'?` — so a rename usually resolves without leaving the editor.
+
+#### A COMPUTED `source:` can keep its names
+
+A generic reader — the table arrives in `input`, the caller picks it out of a registry — is computed, and yet every name it can produce is known. The obvious derivation is not assignable:
+
+```ts
+source: Object.keys(JUNCTION_REGISTRY),   // string[] — ✗
+```
+
+The tempting exit is a cast, or annotating `ReactivitySourceValue` (the wide `string | ReactivityChannel` shape, exported from `@voltro/protocol`). Both compile at once and take that **entire** set of tables out of the check permanently. Keep the literal's keys instead:
+
+```ts
+const REGISTRY = { … } as const satisfies Readonly<Record<string, JunctionMeta>>
+
+// consumers that index with a plain string still get the wide type
+export const JUNCTION_REGISTRY: Readonly<Record<string, JunctionMeta>> = REGISTRY
+
+// … and the source list keeps its literal names
+export const JUNCTION_TABLE_NAMES = Object.keys(REGISTRY) as ReadonlyArray<keyof typeof REGISTRY>
+```
+
+The part that is easy to get wrong: an **annotation widens the keys back**, even when the literal carries `as const`. A registry written as `export const R: Readonly<Record<string, Meta>> = { … } as const` has `keyof typeof R === string`, and nothing about it looks wrong — the annotation is checked against the literal and then replaces its type. `satisfies` checks without replacing. That is the whole reason for the two-line split above.
+
+Reach for `ReactivitySourceValue` when there genuinely is no key set to keep — a name read from a config file, or assembled at runtime. Not when recovering one takes two lines.
+
 Two things it deliberately does not narrow. A **plugin's** route `source:` stays `string`: a plugin ships against many apps and cannot know any of their tables. And nothing that READS a descriptor's source at runtime narrows either — a reader that refused an unknown name would reject the stale name it exists to report.
 
 **It does not check the other direction — except for relations.** A `source:` that omits a table the query genuinely reads is silent: the name is right, the table exists, and nothing has an opinion. That is the failure that costs a user report — they type, the row lands, and the panel does not move.
@@ -1714,6 +1740,16 @@ Two things it deliberately does not narrow. A **plugin's** route `source:` stays
 
 An eager-loaded relation is composition by definition — its rows are IN the result — and its table comes from the relation registry, so the rule has no heuristic and no exception list. A **many-to-many** wants the junction table too, and says so separately: adding or removing a link writes only the junction row, so declaring the target alone leaves the list stale on exactly the operation a user performs to change it.
 
+Nested relations resolve in the **same** pass: a relation loaded under `.with({ subTasks: { with: { watchers: true } } })` is looked up on `task_sub_tasks`, not on the query's base, so both levels are reported at once rather than one per run.
+
+The one thing it still cannot see is a base table it cannot find — neither declared in `source:` nor written as `database.<name>` / `.select('<name>')`. There is then no table to resolve the relations against, and the query would otherwise report clean while every relation on it is unchecked. So doctor says so:
+
+```
+⚠  1 query could not be fully checked — the base table is neither declared nor readable from the executor:
+   reports.byKind: `blocked` resolved against no table
+   declare the base table in `source:` and re-run — relations under it are unchecked until then.
+```
+
 What doctor deliberately does NOT do is derive every table an executor reads. That needs a judgement — does this read **compose** the result or merely **restrict** it? — and only composing reads belong in `source:`; a restricting one re-running on every unrelated write puts a hundred lists back on the wire. A scan has to infer that from syntax, and a rule that guesses on a correct codebase teaches you to ignore it.
 
 So: when a live view does not update, check the writing table is in the reading query's `source:` before anything else.

package/templates/agent-docs/internationalization.md

@@ -36,6 +36,13 @@ export default {
   // supported one. MUST be in `locales`. Pick your source-of-truth
   // language — typically English.
   defaultLocale: 'en' as const,
+  // The zone every date/time formatter renders in. Omit it and each
+  // runtime uses its own — the pod's on the server, the viewer's in the
+  // browser — which is a hydration mismatch on every SSR timestamp.
+  // An IANA name pins one zone for everyone; 'viewer' resolves it per
+  // request from the `voltro:tz` cookie.
+  timeZone: 'viewer' as const,
+  defaultTimeZone: 'UTC' as const,
 }
 ```
 
@@ -79,6 +86,18 @@ The client **adopts what the server resolved**, reading it from the `<html lang>
 
 `<html lang>` carries the same resolved locale — the value the `<I18nProvider>` renders with, on the same request. That matters on its own: it is what a screen reader pronounces in, what Chrome offers to translate *from*, and what hyphenation uses.
 
+### The same contract carries the render zone and the render clock
+
+`lang` is one of three answers the server decides and publishes so the client does not form its own:
+
+| attribute | what it carries |
+|---|---|
+| `lang` | the resolved locale |
+| `data-voltro-tz` | the IANA zone every date/time formatter renders in — set `timeZone` in `app.config.ts` |
+| `data-voltro-now` | the server's render instant, so `useRelativeTime` produces the same string in the hydration pass |
+
+Locale was already agreed; the zone and the clock were each read from the ambient runtime, which meant a server-rendered timestamp was a hydration mismatch waiting for a wide enough offset or a slow enough connection. See [Plurals & formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr--the-setting-that-is-not-a-preference) — that is the page to read before you migrate hand-rolled `toLocaleString()` calls onto the hooks.
+
 See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the component hooks, [Plurals & formatting](/docs/i18n/formatting) for CLDR plural selection and the `Intl`-backed date / number / relative-time hooks, and [URL strategies](/docs/i18n/url-strategies) for cookie-only vs URL-prefix routing.
 
 ## The cookie names are exported
@@ -675,7 +694,19 @@ formatDate(order.createdAt, { dateStyle: 'medium' })
 formatDate(order.createdAt, { dateStyle: 'medium', timeStyle: 'short', timeZone: 'Europe/Berlin' })
 ```
 
-`(value, options?) => string`, where `value` is a `Date`, a timestamp number, or a date string, and `options` is `Intl.DateTimeFormatOptions`. **Omit `timeZone` and the viewer's own zone is used** — which is what a multi-timezone app wants. Pass one only when the value genuinely belongs to a fixed zone (a store's opening hours, a scheduled broadcast). Pinning a global zone across the whole app is the anti-pattern this replaces.
+`(value, options?) => string`, where `value` is a `Date`, a timestamp number, or a date string, and `options` is `Intl.DateTimeFormatOptions`.
+
+**The zone comes from the provider, which you configure once** — `timeZone` in the web `app.config.ts` (see [Timezones under SSR](#timezones-under-ssr-the-setting-that-is-not-a-preference)). Pass `timeZone` in the options only when the value genuinely belongs to a fixed zone regardless of who is looking (a store's opening hours, a scheduled broadcast); that overrides the provider for one call.
+
+**With `timeZone` unset in `app.config.ts` there is no zone at all, and each runtime falls back to its own.** On a server-rendered page that is the pod's zone for the markup and the viewer's for the hydration render — a mismatch on every timestamp, and a different calendar day across midnight. `useTimeZone()` returns `undefined` in exactly that state, so you can assert on it.
+
+### `useTimeZone`
+
+```tsx
+const timeZone = useTimeZone()   // 'Europe/Berlin' — or undefined when none is pinned
+```
+
+`undefined` is a real answer and worth branching on: it means nobody decided, so the server and the browser are each using their own zone. It is not the same as `'UTC'`.
 
 ### `useRelativeTime`
 
@@ -688,7 +719,9 @@ relativeTime(comment.postedAt, { numeric: 'always' }) // "1 day ago" instead of
 relativeTime(comment.postedAt, { now: renderedAt })   // measure against a fixed base
 ```
 
-`(value, options?) => string`. Options are `Intl.RelativeTimeFormatOptions` plus a `now` override (a `Date`, number, or string) for deterministic rendering and tests; the default base is `Date.now()`.
+`(value, options?) => string`. Options are `Intl.RelativeTimeFormatOptions` plus a `now` override (a `Date`, number, or string) for deterministic rendering and tests.
+
+**Hydration-safe by default.** Without an explicit `now`, the base is the server's render instant for the server render *and* the hydration pass that has to match it — published as `<html data-voltro-now>` — then the live clock once hydration commits. So "3 minutes ago" cannot become "4 minutes ago" between the HTML and the first client render just because the network was slow, which is what a plain `Date.now()` base does whenever a unit boundary falls in the gap.
 
 It picks the **largest unit that fits**, so a 90-minute delta reads "1 hour ago", not "90 minutes ago". Anything under a second renders through the `second` unit at 0 — "now" — which avoids the "0 seconds ago" flicker hand-rolled versions produce. `numeric: 'auto'` is the default, so English gets "yesterday" rather than "1 day ago".
 
@@ -721,7 +754,7 @@ For a component that needs several at once, without stacking five hook calls:
 import { useFormatters } from '@voltro/i18n'
 
 function ActivityRow({ entry }: { readonly entry: Entry }) {
-  const { locale, formatDate, relativeTime, formatNumber, plural } = useFormatters()
+  const { locale, timeZone, formatDate, relativeTime, formatNumber, plural } = useFormatters()
 
   return (
     <li lang={locale}>
@@ -735,7 +768,77 @@ function ActivityRow({ entry }: { readonly entry: Entry }) {
 }
 ```
 
-It returns the active `locale` plus `formatDate`, `relativeTime`, `formatNumber` and `plural` — memoized together. Currency is not in the bundle because it needs its ISO code up front; call `useFormatCurrency(code)` alongside it when you need one.
+It returns the active `locale` and `timeZone` plus `formatDate`, `relativeTime`, `formatNumber` and `plural` — memoized together. Currency is not in the bundle because it needs its ISO code up front; call `useFormatCurrency(code)` alongside it when you need one.
+
+## Timezones under SSR — the setting that is not a preference
+
+A formatter is deterministic given the value, the locale, the zone and the clock. The provider supplies all four, and the two beyond locale are the ones that differ between the server and the browser:
+
+| | Where it came from before | What that means under SSR |
+|---|---|---|
+| **locale** | the provider, both sides | agreed already — the server publishes `<html lang>` and the client reads the attribute rather than `navigator.languages` |
+| **zone** | the runtime | the POD on the server (UTC on a container with no `TZ`), the VIEWER's machine in the browser |
+| **clock** | `Date.now()` | two numbers, differing by the network latency |
+
+So a server-rendered timestamp was a hydration mismatch (React error #418) waiting for a wide enough offset or a slow enough connection, and across midnight it was a different calendar **day**. The fix is the one the locale already used: **the server decides, publishes its answer, and the client reads the answer instead of forming its own.**
+
+### Configure it once
+
+```ts
+// apps/<project>/web/app.config.ts
+export default {
+  type: 'web' as const,
+  name: 'myApp',
+  port: 5191,
+  locales: ['de', 'en'] as const,
+  defaultLocale: 'de' as const,
+
+  timeZone: 'Europe/Berlin' as const,   // one zone for every viewer
+  // …or:
+  // timeZone: 'viewer' as const,       // resolve per request, per user
+  // defaultTimeZone: 'UTC' as const,   // before the viewer's zone is known
+}
+```
+
+Whatever it resolves to is stamped on the document as `<html data-voltro-tz>`, and the generated client entry reads that attribute. Both sides then format against one value — which is the property that removes the mismatch, whether or not the value is the viewer's true zone. Being *wrong together* is repairable after mount; being *different* is not.
+
+`timeZone` requires `locales`, because the zone rides the `<I18nProvider>` the framework generates from it.
+
+### `timeZone: 'viewer'` — how the server learns the zone
+
+Through the `voltro:tz` cookie, which has two writers and wants both:
+
+1. **The framework's script**, injected into `<head>`, seeds it from `Intl.DateTimeFormat().resolvedOptions().timeZone` when the cookie is absent. From the second request onward the server renders in the browser's zone with no login and no app code. It never overwrites an existing value and never reloads the page.
+2. **Your app, at login** — overwriting it with the zone you hold for the signed-in user. That is the authoritative one: a profile field or an identity provider's `timeZone` claim beats the machine a user happens to be sitting at.
+
+Write it from `middleware.ts`, which runs per request and can return cookies:
+
+```ts
+// apps/<project>/web/middleware.ts
+import { defineMiddleware } from '@voltro/web/middleware'
+import { TIMEZONE_COOKIE, isSupportedTimeZone } from '@voltro/i18n'
+
+export const userTimeZone = defineMiddleware({
+  run: async (req) => {
+    const zone = await zoneForSession(req.cookies)   // your session → the user's own zone
+    if (!isSupportedTimeZone(zone) || req.cookies[TIMEZONE_COOKIE] === zone) return undefined
+    return {
+      setCookies: [
+        { name: TIMEZONE_COOKIE, value: zone, path: '/', maxAge: 31_536_000, sameSite: 'lax' as const },
+      ],
+    }
+  },
+})
+```
+
+A cookie set here is applied to the jar the SAME render reads, so the zone takes
+effect on the response that sets it rather than the one after.
+
+Validate before you write. An unusable zone is dropped on the way in (a stale cookie, a typo in the config, a runtime with a trimmed ICU) rather than forwarded — `Intl.DateTimeFormat` throws on an unknown zone, and one bad value would otherwise degrade every timestamp in the app to a raw `Date` string.
+
+### Prerendered pages
+
+A `renderMode: 'static'` page is one artefact for every viewer, so `'viewer'` cannot mean the viewer there — it resolves to `defaultTimeZone`. The build publishes that value and its own build instant, so the markup and the first client render still agree; a relative time in a prerendered page corrects itself in one frame after mount rather than mismatching.
 
 ## Formatters vs. ICU in the catalog
 
@@ -750,7 +853,8 @@ For dates, numbers and relative time the hooks are the blessed path; reach for `
 
 - **Don't write `(s)`, `count === 1 ? 'x' : 'xs'`, or a `+ 's'` suffix.** It is wrong in most languages and cannot be fixed by a translator. Use `plural` / `usePlural` or ICU in the catalog.
 - **Don't hand-roll "X minutes ago".** `useRelativeTime` is one hook, is localized, and handles the sub-second and unit-selection cases that inline versions get wrong.
-- **Don't pin a global `timeZone` / locale for the whole app.** The formatters resolve the active locale from the provider; a pin makes every viewer read the app in one user's settings.
+- **Don't pass `timeZone` at every call site to work around a missing config.** Set `timeZone` in `app.config.ts` once. A per-call convention is a rule every new call has to remember, and the ones that forget are invisible until a viewer in another zone reads a wrong date.
+- **Don't call `Intl.DateTimeFormat().resolvedOptions().timeZone` in a component to "fix" SSR.** It is the viewer's true zone and therefore the wrong value: the server could not know it, so the server did not render with it, and using it on the client guarantees the mismatch. Let the server decide and publish — that is what `timeZone: 'viewer'` does.
 - **Don't pass a locale-formatted string to a machine consumer.** Formatted output is presentation — send ISO strings and raw numbers to APIs, `dateTime` attributes and sort keys.
 - **Don't format inside a `.map()` by constructing `Intl` objects yourself.** The hooks memoize per locale; a fresh `new Intl.NumberFormat(...)` per row is the slow path.
 
@@ -840,14 +944,28 @@ program.pipe(withTimezone('Europe/Berlin'))
 `currentTimezone` never fails — an absent context is the documented `UTC`
 default, so call sites don't handle a missing-service error.
 
-> **What ships today is the SEAM, not the wiring.** `@voltro/datetime/context`
-> exports `currentTimezone`, `withTimezone` and `resolvedTimezoneLayer`, and you
-> provide the layer yourself. The framework does **not** yet install it per
-> request, and there is **no `useTimezone()` hook** in the web layer — both are
-> planned to land in `@voltro/runtime` + `@voltro/web`. Until then: resolve the
-> zone yourself (`resolveTimezone`) and provide `resolvedTimezoneLayer` around
-> the work that needs it, or pass an explicit `timeZone` argument. Without a
-> provided layer every call reads the `UTC` default.
+> **Two zones, and only one of them is wired. Keep them apart.**
+>
+> The **render zone** — what a date LOOKS like in the UI — is wired end to end.
+> Set `timeZone` in the web `app.config.ts`, and the framework resolves it per
+> request, publishes it on the document, and every `@voltro/i18n` formatter on
+> both sides of the hydration boundary uses it. Read it with `useTimeZone()`
+> from `@voltro/i18n`. See
+> [Formatting → Timezones under SSR](/docs/i18n/formatting#timezones-under-ssr--the-setting-that-is-not-a-preference).
+>
+> The **server-side compute zone** — what `startOfDay` or a workflow's "same
+> time tomorrow" resolves against inside a handler — is still the SEAM only.
+> `@voltro/datetime/context` exports `currentTimezone`, `withTimezone` and
+> `resolvedTimezoneLayer`; the framework does **not** install the layer per
+> request, so resolve the zone yourself (`resolveTimezone`) and provide
+> `resolvedTimezoneLayer` around the work that needs it, or pass an explicit
+> `timeZone` argument. Without a provided layer every call reads the `UTC`
+> default.
+>
+> Rendering a date correctly does NOT give a route handler the user's zone, and
+> a handler that has it does NOT change what the browser renders. They are
+> separate values today and a `timeZone` in `app.config.ts` configures the
+> first one only.
 
 ## Arithmetic — the DST split is in the names