@voltro/cli 0.28.0 → 0.29.0

package/templates/agent-docs/data.md

@@ -1024,6 +1024,67 @@ const message = matchError(err, {
 }, () => 'Something went wrong')
 ```
 
+## Cross-table business rules — `.rule()`
+
+A [typed error](#typed-errors) is declared on ONE mutation. A **rule** is declared on a TABLE: an invariant the runtime enforces on EVERY mutation that writes that table, no matter which one did the write. Declare it in the schema with `.rule(name, predicate)`:
+
+```ts
+import { table, id, integer, eq } from '@voltro/database'
+import { database } from '../database/schema'
+
+export const invoices = table('invoices', {
+  id:    id(),
+  total: integer(),
+}).rule(
+  'totalMatchesLineItems',
+  async (row, { store }) => {
+    const items = await store.query(
+      database.lineItems.where(eq('invoiceId', row.id)).descriptor,
+    )
+    const sum = items.reduce((acc, l) => acc + Number(l.amount), 0)
+    return sum === row.total || { params: { computed: sum, declared: row.total } }
+  },
+)
+```
+
+The predicate receives the **post-write row** and a `context` whose `store` is the SAME transactional store the mutation wrote through — so a cross-table read shares the write's MVCC snapshot and cannot race it. It runs INSIDE the mutation transaction, after the write and before commit, and it is dialect-neutral (the same predicate is correct on all four dialects — no per-dialect code). Return `true` (or nothing) when the invariant holds; return `false` or a `RuleViolationDetail` (`{ params?, field?, message? }`) to signal a violation for THIS row.
+
+Unlike [`.check()`](/docs/database/columns#db-level-checks) — a single-row SQL `CHECK` the DATABASE enforces as DDL — a rule is a PREDICATE the runtime evaluates, so it can read OTHER tables. Use `.check()` when the database itself must guarantee a single-row constraint; reach for `.rule()` for a cross-table invariant (an invoice total matching its line items, a booking not exceeding a resource's capacity).
+
+### The violation is a typed error — automatically
+
+A violated `error`-severity rule rolls the whole mutation back and fails with the typed, wire-preserved **`BusinessRuleViolation`**. You do **not** declare it on the mutation's `error:` — the runtime auto-merges it into every mutation's error union at the wire boundary, exactly like `ScopeError`. A rule declared on a SCHEMA table can fail ANY mutation that writes that table, so no single descriptor could know to declare it; the auto-merge is what keeps the violation a typed error the client decodes by `_tag` rather than an untyped defect.
+
+Match it on the client the same way as any [typed error](#matching-typed-errors-on-the-client):
+
+```ts
+import { errorTag } from '@voltro/protocol'
+
+try {
+  await createInvoice(input)
+} catch (err) {
+  if (errorTag(err) === 'BusinessRuleViolation') {
+    // err.rule — the rule name; err.params — the offending values; err.field — the pointer
+  }
+}
+```
+
+`BusinessRuleViolation` carries `rule` (the declared name), optional `params` (i18n params for the offending values), an optional `field` pointer, and `severity` (always `'error'` on the wire — a warning-severity rule never reaches the client as an error).
+
+### `severity: 'warning'` — log without blocking
+
+```ts
+export const invoices = table('invoices', { id: id(), total: integer() }).rule(
+  'totalMatchesLineItems',
+  async (row, { store }) => true,
+  { severity: 'warning' },
+)
+```
+
+A `warning`-severity rule LOGS and audits the violation but lets the write commit — useful while backfilling data that does not yet satisfy a newly-added invariant. The default is `'error'` (roll back).
+
+Rules run on `voltro dev` and `voltro serve` through the same mutation runner, so the two boot paths cannot disagree about whether a rule fires. Inserts and updates on your own tables are re-validated; a delete is not (there is no post-write row to check).
+
 ## `internal: true` — off the wire entirely
 
 Every discovered `*.mutation.ts` / `*.query.ts` / `*.action.ts` / `*.stream.ts` is
@@ -1472,6 +1533,88 @@ A subscription that was live and is then skipped goes idle — it does **not**
 keep serving the snapshot it still holds. Otherwise `skip: !open` would show
 last time's data the moment a dialog reopens.
 
+## SSR preload — first paint with data
+
+By default a `useSubscription` on an SSR page flashes its empty/loading state on
+mount, THEN opens the WebSocket and fetches the first snapshot — even though the
+server could have fetched that value during the render. **`usePreloadedSubscription`**
+closes that gap: it reads its first value from the SSR hydration payload, renders
+real data on the first paint, then upgrades to the live stream the instant its
+first snapshot lands.
+
+Two things wire it up: the hook, and a `preload` export on the page.
+
+```tsx
+import { usePreloadedSubscription } from '@voltro/client'
+
+export const preload = ['notes.list']
+
+export default function NotesPage() {
+  const { data } = usePreloadedSubscription<Note[]>('app', 'notes.list')
+  // `data` is present on the first paint — no loading flash
+  return <NotesTable notes={data} />
+}
+```
+
+`export const preload` lists the subscriptions the page's tree needs at first
+paint. During the SSR render (`voltro dev` and `voltro start`) the framework runs
+each one server-side — the SAME `ctx.query(tag, input)` a loader receives — and
+seeds the result into the hydration payload. The client's
+`usePreloadedSubscription` finds the seed by the SAME cache key `useSubscription`
+uses, so the server markup and the client hydration render read an identical
+value — there is no hydration mismatch. The live subscription still opens and
+takes over; the seed is only the first value, never the source of truth.
+
+### `preload` entries
+
+An entry is either a bare tag or a tag plus an `input` derived from the route
+params:
+
+```tsx
+export const preload = [
+  'teams.list',                                                    // no input
+  { tag: 'project.detail', input: (params) => ({ id: params.id }) },
+]
+```
+
+The `input` you derive here MUST match the `input` you pass the hook — both
+address the same cache entry:
+
+```tsx
+export default function ProjectPage({ params }: { params: { id: string } }) {
+  const { data } = usePreloadedSubscription('app', 'project.detail', { id: params.id })
+  return <ProjectView project={data} />
+}
+```
+
+### Falls back to `useSubscription`
+
+When no seed exists for the key — a client-side SPA navigation the server never
+rendered, or the static prerender (which has no live api origin) —
+`usePreloadedSubscription` behaves EXACTLY like `useSubscription`: it loads until
+the stream answers. So it is always safe to reach for; the preload is a
+first-paint optimization, never a correctness dependency. A failed preload is
+likewise non-fatal — the live subscription still delivers the value on the
+client, the only loss is the first-paint seed.
+
+### Seeding by hand
+
+`export const preload` is sugar over an explicit seed. When a loader ALREADY has
+the value — you fetched it for the `<title>`, a breadcrumb, or the row name — seed
+it directly with `seedPreloadedSubscription` (server-side only) instead of
+fetching it a second time:
+
+```ts
+import { seedPreloadedSubscription } from '@voltro/client'
+
+// inside a loader / layout loader, server-side
+const notes = await ctx.query('notes.list', {})
+seedPreloadedSubscription('app', 'notes.list', {}, notes)
+```
+
+Calling it outside a server render throws — on the client the live subscription
+already provides the value, so a client-side seed would be meaningless.
+
 ## Streams Are Different
 
 For non-database or transient element feeds, use [streams](/docs/data/streams), not subscriptions:
@@ -2697,6 +2840,145 @@ export default defineAggregate({
 
 When no analytics sink is configured the framework provides the no-op sink: the read methods fail with `AnalyticsCapabilityNotSupported({ provider: 'noop' })`, which surfaces as a refresh error (last-good rows are preserved). Provider-specific queries beyond the four-method contract (raw SQL, HyperLogLog) live outside the sink — there is no raw-client escape hatch; query the provider with your own client instance inside the build function where you need them.
 
+## Standing IVM siblings — expectations, cost budgets, experiments
+
+Three more primitives are built on the same engine as `defineAggregate({ incremental })` — they reduce a table to a value maintained incrementally from `store.onChange` CDC deltas (O(1) per write, no re-query). Unlike an aggregate you never `read()` a materialised table; you **observe a live signal** through a framework registry and a `useX(def)` handler-sugar. Each is discovered by its own file convention and wired into both `voltro dev` and `voltro serve`.
+
+| Primitive | File | Reduces a table to | Observe with |
+|---|---|---|---|
+| `defineExpectation` | `*.expectation.ts` | a `holding`/`violated` data-quality signal | `useExpectation` / `ExpectationRegistry` |
+| `defineCostBudget` | `*.budget.ts` | per-tenant compute-cost attribution + `ok`/`warn`/`exceeded` budgets | `useCostBudget` / `CostRegistry` |
+| `defineExperiment` | `*.experiment.ts` | per-variant metric + lift (live A/B / holdout) | `useExperiment` / `ExperimentRegistry` |
+
+They are **soft, observability-grade signals** — none of them ever blocks a write. Rejecting a write is a business rule's job (`table().validate(Schema)`); running an agent/workflow on a change is [`*.reaction.tsx`](/docs/data/reactions). These three only *watch* and *report*.
+
+### Data-quality expectations (`*.expectation.ts`)
+
+A `defineExpectation` is a standing data-quality contract over a table. Where dbt tests / Great Expectations run in BATCH and catch bad data hours later, an expectation re-evaluates on every write and tips `holding`↔`violated` the instant an invariant breaks — tracing the violation to the write that caused it (the CDC event's `traceId` / `subjectId` / `procedure`).
+
+```ts
+// apps/api/expectations/orderFreshness.expectation.ts
+import { defineExpectation } from '@voltro/runtime'
+
+export default defineExpectation({
+  name: 'orders-fresh',
+  on: { table: 'orders' },      // its CDC deltas drive re-evaluation
+  invariant: { kind: 'freshness', column: 'createdAt', maxAgeMs: 10 * 60_000 },
+  severity: 'critical',         // 'info' | 'warn' (default) | 'critical' — alerting priority only
+})
+```
+
+The default export must be the return value of `defineExpectation({...})` — the cli discovers `*.expectation.ts` files by that branded shape.
+
+Four invariant kinds, each reducing the table to one incrementally-maintained metric:
+
+```ts
+{ kind: 'freshness',   column: 'createdAt', maxAgeMs: 600_000 }              // newest row no older than X (re-checked on a clock tick too)
+{ kind: 'nullRate',    column: 'email', maxRate: 0.01 }                      // ≤ 1% of rows null in `column`
+{ kind: 'rowCount',    min: 1, max: 100_000 }                               // COUNT(*) within [min, max]
+{ kind: 'valueBounds', column: 'price', min: 0, max: 1000, maxViolationRate: 0.05 } // ≤ 5% of rows out of [min, max]
+```
+
+An optional `on.where` predicate narrows the population the invariant is asserted over — it runs server-side per row and never leaves the server, so it can be any predicate:
+
+```ts
+on: { table: 'orders', where: (row) => (row['status'] as string) === 'paid' }
+```
+
+Observe one expectation from a handler with `useExpectation`, or read the whole surface off `ExpectationRegistry`:
+
+```ts
+import { Effect } from 'effect'
+import { useExpectation } from '@voltro/runtime'
+import ordersFresh from '../expectations/orderFreshness.expectation'
+
+export default (input, _ctx) =>
+  Effect.gen(function* () {
+    const state = yield* useExpectation(ordersFresh)
+    // state: { status: 'holding' | 'violated' | 'unknown', metric, threshold,
+    //          since, lastEvaluatedAt, lastCause, ... } | null (null = not registered)
+    return { degraded: state?.status === 'violated' }
+  })
+```
+
+`ExpectationRegistry` exposes `snapshot()` (every expectation's state — the inspect feed), `get(name)`, `violations()` (the alerting view), and `subscribe(listener)` for `violated`/`recovered` transitions. A transition carries the causing write's provenance; a `freshness` SLA aging out with no write reports `cause: null` — the honest "no write caused this; the ABSENCE of writes did".
+
+### Cost budgets (`*.budget.ts`)
+
+A `defineCostBudget` is a reactive-FinOps primitive: per-tenant / per-subscription compute-cost attribution plus a budget every tenant is held to independently. It is to reactive compute what AI's `requireAiBudget` is to USD spend — a standing per-tenant ceiling that crosses `ok`→`warn`→`exceeded` and recovers on a window rollover.
+
+```ts
+// apps/api/budgets/tenantCompute.budget.ts
+import { defineCostBudget } from '@voltro/runtime'
+
+export default defineCostBudget({
+  name: 'tenant-compute',
+  limit: 100_000,       // the per-tenant ceiling, in the budget's unit
+  unit: 'recompute',    // which cost unit to meter; omit ⇒ the tenant's TOTAL across every unit
+  warnAt: 0.8,          // fraction of `limit` at which it goes 'warn' (default 0.8; set 1 to disable)
+  window: '24h',        // tumbling window — the counter resets each boundary; omit ⇒ cumulative since boot
+  severity: 'warn',     // 'info' | 'warn' (default) | 'critical'
+})
+```
+
+Observe one budget for one tenant with `useCostBudget(def, tenantId)`:
+
+```ts
+import { Effect } from 'effect'
+import { useCostBudget } from '@voltro/runtime'
+import tenantCompute from '../budgets/tenantCompute.budget'
+
+export default (input, ctx) =>
+  Effect.gen(function* () {
+    const state = yield* useCostBudget(tenantCompute, ctx.tenantId)
+    // state: { status: 'ok' | 'warn' | 'exceeded', spent, limit, warnThreshold, ... } | null
+    return { overBudget: state?.status === 'exceeded' }
+  })
+```
+
+`CostRegistry` exposes `attribution()` (per-tenant chargeback/showback rows — `total` + `byUnit` + `bySubscription`), `tenant(tenantId)`, `budgets()`, `budget(name, tenantId)`, `breaches()` (the alerting view), and `subscribe(listener)` for threshold crossings.
+
+> **Reactive recomputes now feed attribution automatically.** Declaring any `*.budget.ts` wires the dispatcher's `recordCost` tap in both boot paths: every time a source-row change re-runs an affected subscription and pushes it a delta, one `{ unit: 'recompute', amount: 1 }` cost event is attributed to that subscription's tenant (and traceId). So a tenant's `total`/`spent` populates from real reactive work — a `unit: 'recompute'` budget crosses `ok`→`warn`→`exceeded` as deliveries accrue, and recovers on a window rollover. The emission is **per delivered recompute** — one event per subscription the change fanned out to, on both the row-set and computed-query delivery paths. An app that declares NO cost budget wires no tap and allocates nothing on the reactive hot path.
+
+### Online experiments (`*.experiment.ts`)
+
+A `defineExperiment` is a live A/B / holdout experiment expressed as IVM aggregates. Assignment is a deterministic salted hash (subject → variant, no stored assignment table, reproducible on the client); the success metric is maintained PER VARIANT from the watched table's CDC — so lift vs a baseline is real-time, with no batch pipeline. It differs from `plugin-flags` (which GATES a code path) — an experiment MEASURES the outcome.
+
+```ts
+// apps/api/experiments/checkoutColor.experiment.ts
+import { defineExperiment } from '@voltro/runtime'
+
+export default defineExperiment({
+  name: 'checkout-button-color',
+  on: { table: 'orders' },                      // its CDC deltas drive the live recompute
+  subject: 'userId',                            // stable per-subject bucketing (a column name, or a (row) => key fn)
+  variants: [{ name: 'control' }, { name: 'green', weight: 1 }],   // ≥ 2 arms; `weight` skews the split (default 1)
+  holdout: 0.1,                                 // 10% held out entirely, for a clean untouched baseline
+  metric: { kind: 'conversionRate', column: 'completed' },         // per-variant success metric
+  baseline: 'control',                          // which variant lift is measured against (default: the first)
+})
+```
+
+Metric kinds: `{ kind: 'count' }`, `{ kind: 'sum', column }`, `{ kind: 'avg', column }`, and `{ kind: 'conversionRate', column, equals? }` (converted iff `row[column]` is truthy, or `=== equals` when given). `avg` / `conversionRate` are per-subject rates that a lift reads honestly; `count` / `sum` reflect exposure too, so their cross-variant comparison only means "more/less total".
+
+Observe the live result with `useExperiment`, or off `ExperimentRegistry`:
+
+```ts
+import { Effect } from 'effect'
+import { useExperiment } from '@voltro/runtime'
+import checkoutColor from '../experiments/checkoutColor.experiment'
+
+export default (input, _ctx) =>
+  Effect.gen(function* () {
+    const result = yield* useExperiment(checkoutColor)
+    // result: { totalExposure, baseline, variants: [{ variant, isBaseline, isHoldout,
+    //           exposure, metric, lift, diff }, ...], lastUpdatedAt, ... } | null
+    return { arms: result?.variants ?? [] }
+  })
+```
+
+Each variant row carries its `exposure` (sample size), the maintained `metric`, and — for non-baseline arms — `lift` (`(metric − baseMetric) / baseMetric`) and `diff` (absolute). `ExperimentRegistry` exposes `snapshot()`, `get(name)`, and `subscribe(listener)` for the live recompute stream that a results view redraws from. The same-subject-same-variant assignment is a pure function (`assignVariant(def, subject)`) a client can reproduce.
+
 
 
 ---

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

@@ -658,6 +658,53 @@ export const users = table('users', {
 
 The cleanup is a separate PR after the migration has rolled out. Don't mix the rollout PR with the cleanup PR — the markers ARE the migration's audit trail until it's applied everywhere.
 
+## `voltro evolve` — the schema-evolution copilot
+
+Adding the `.renamedFrom()` marker by hand is easy for one column. The hard part of changing an EXISTING schema is the *rest*: which handlers read or write that column, whether a rename is safe or needs a backfill, and getting the annotation onto the entity AND every call site without missing one. `voltro evolve` does that reconnaissance and proposes a reviewable plan.
+
+Given a change, it reads the **observed graph** (`app.graph.observed.generated.json`, recorded by `voltro dev` — see [`voltro check`](/docs/cli/inspect)) plus the declared manifest, enumerates the real blast radius, and prints three things: a proposed **codemod**, a branch-verified **backfill** plan, and a `voltro check` **verify** step.
+
+```bash
+voltro evolve rename-column notes.title --to heading            # dry-run: plan + codemod preview
+voltro evolve rename-column notes.title --to heading --write    # apply the codemod
+voltro evolve retype-column orders.total --to numeric           # reshape → manual codemod + steps
+voltro evolve split-column users.name --into firstName,lastName
+voltro evolve rename-table note --to notes
+voltro evolve drop-column notes.legacy
+voltro evolve rename-column notes.title --to heading --json     # for CI / an agent loop
+```
+
+It is **dry-run by default** (mirrors `voltro generate`); `--write` applies the codemod through the same `runCodemods` toolkit as `voltro update`. `--json` emits the whole plan for CI or an agent.
+
+### The blast radius is observed, not guessed
+
+```text
+change: rename-column notes.title → heading
+
+blast radius (observed + declared):
+  query(notes.list) — observed read
+  mutation(notes.update) — observed update
+  ⚠ 1 declared but NEVER exercised — column use UNKNOWN: notes.archive
+
+codemod:
+  entity: rename 'notes.title' → 'heading' and add .renamedFrom('title') (catalog rename — data preserved)
+  annotate 2 handler site(s) that reference the old field
+
+backfill (dry-runs on branch notes-pr-0):
+  [safe] catalog RENAME — no data movement
+
+verify: voltro check
+```
+
+A handler that a `voltro dev` session or a test actually ran is reported with what it did (`observed read` / `observed update`). A handler that is *declared* to touch the table but was **never exercised** is flagged `UNKNOWN` and listed separately — it is never folded into "safe", because no run proves what it does with the column. That honesty is the point: the tool tells you exactly where it cannot vouch for the change.
+
+### 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.
+- **`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/misc.md

@@ -296,6 +296,63 @@ who may receive the plaintext — a private note you decrypt *for its owner* is
 valid case, so treating "encrypted" as "never to a client" would be wrong. State
 the exposure policy explicitly.
 
+## `.readableBy(...scopes)` — visible only to scoped subjects
+
+The **graded middle of the same wire-exposure axis** as `.serverOnly()` — not a
+fourth axis. A plain column is visible to everyone who can read the row;
+`.serverOnly()` hides it from every client; `.readableBy(...)` sits between them —
+the column reaches a subject only if it holds the scope:
+
+```ts
+import { id, integer, text, table } from '@voltro/database'
+
+export const invoices = table('invoices', {
+  id:          id(),
+  number:      text(),                                        // visible to everyone
+  amountCents: integer().readableBy('billing:read'),          // only billing-scoped subjects
+  taxNote:     text().readableBy('billing:read', 'admin:pii'), // ANY of the two scopes
+})
+```
+
+**What it does:** a column marked `.readableBy(...scopes)` is stripped from the
+wire OUTPUT for any subject holding NONE of the listed scopes, and present for
+one holding **at least one** of them. Like `.serverOnly()` it changes nothing at
+rest and nothing in the DDL — it is a wire concern only, so a server-internal
+read (`ctx.store.query`) still sees the value; the strip applies only on the way
+out to a client.
+
+**Scope semantics:**
+
+- **≥ 1 scope, OR-matched.** A subject sees the column iff it holds at least one
+  of the listed scopes — `.readableBy('a', 'b')` means "a OR b", not both.
+- **Effective scopes.** The check is the framework's `hasEffectiveScope` — the
+  subject's RAW scopes **∪** its rbac role-derived scopes — so a role that grants
+  `billing:read` unlocks the column even when the scope is not listed directly on
+  the subject.
+- **`admin:full` bypasses it.** A subject holding `admin:full` sees every
+  `.readableBy(...)` column, exactly as it satisfies every guard.
+- **At least one scope is required.** `.readableBy()` with no scope would mean
+  "readable by nobody" — that is `.serverOnly()` — so both the empty call and a
+  blank scope string are rejected at declaration.
+
+**`.serverOnly()` wins when both are present.** `.serverOnly()` is the all-hidden
+end of the axis, so a column carrying both is hidden from EVERYONE — `admin:full`
+included. `.readableBy()` only ever *narrows* an otherwise-visible column; it can
+never re-expose a `.serverOnly()` one:
+
+```ts
+amountCents: integer().readableBy('billing:read'),          // scoped subjects see it; admin:full does too
+secretKey:   text().serverOnly().readableBy('billing:read'), // serverOnly wins → hidden from EVERYONE
+```
+
+Enforcement shares the SAME chokepoint as `.serverOnly()` — the Dispatcher's read
+boundary — but resolves **per subject**: it applies to a query's initial snapshot
+AND every reactive subscription delta, and to the one-shot
+[`publicApi`](/docs/data/rest-routes) REST GET, in both boot paths (`voltro dev`,
+`voltro serve`). A table that declares no `.readableBy(...)` column pays nothing —
+the strip collapses to the subject-independent `.serverOnly()` set and the
+dispatcher's read/diff memo is still shared across all subscribers of a change.
+
 ## Worked example
 
 ```ts

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

@@ -280,7 +280,9 @@ Two layers enforce row invariants, and they're complementary:
 
 - **`table().validate(Schema)` (below)** — app-level `effect/Schema` validation, run before the INSERT/UPDATE. Use it for the rich stuff a portable `CHECK` can't express: regex / email / structured strings, length ranges, numeric bounds, cross-field rules with custom typed errors. It's the single validation surface — don't reach for a pile of `.min()` / `.max()` / `.pattern()` column modifiers (there aren't any, by design).
 
-Rule of thumb: **`.check()` when the DATABASE must guarantee it; `validate(Schema)` for everything else.** There is no `.comment()` / `.index()` column modifier — indexes are table-level.
+- **`table().rule(name, predicate)` (cross-table)** — neither of the above can read ANOTHER table. A [business rule](/docs/data/mutations#cross-table-business-rules-rule) is a predicate the runtime evaluates inside the mutation transaction, so it can compare the written row against rows in other tables (an invoice total vs. its line items) and rolls the mutation back with a typed `BusinessRuleViolation` on failure.
+
+Rule of thumb: **`.check()` when the DATABASE must guarantee a single-row constraint; `table().rule()` for a cross-table invariant; `validate(Schema)` for everything else.** There is no `.comment()` / `.index()` column modifier — indexes are table-level.
 
 ## Default with callback
 

package/templates/agent-docs/internationalization.md

@@ -51,7 +51,11 @@ Server-side, the active locale is determined by, in priority order:
 
 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 side mirrors #1 (cookie) and #3 (default) for hydration safety. `Accept-Language` is **server-only** because `navigator.languages` can diverge from what the server saw, which would cause a hydration mismatch.
+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.
+
+> Earlier versions said the client "mirrors cookie and default for hydration safety". That was the opposite of what happened. Dropping the `Accept-Language` signal is not the same as agreeing with the server about it — on a first visit, with no cookie yet, the server negotiated `Accept-Language` while the client fell through to `defaultLocale`. An English browser on a German-default app therefore hydrated `de` over an `en` tree and React discarded the entire server render, which is exactly what SSR was enabled to avoid. It stopped as soon as anything wrote the cookie, so one language switch made it un-reproducible for that developer.
+
+`<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.
 
 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.
 
@@ -697,3 +701,159 @@ For dates, numbers and relative time the hooks are the blessed path; reach for `
 - **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 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.
+
+
+
+---
+
+<!-- source: en/i18n/datetime.md -->
+## Dates & timezones
+
+_"@voltro/datetime — UTC-instant storage, timezone-aware arithmetic/formatting on TC39 Temporal, and the request-scoped timezone-context seam."_
+
+`@voltro/datetime` is the framework's opinion on time: **store UTC instants,
+render in the viewer's timezone, never do zone math by hand.** It is built on the
+[TC39 Temporal](https://tc39.es/proposal-temporal/docs/) standard (via a
+polyfill, so the API is identical on the server and in the browser) and ships
+pure, browser-safe helpers plus a request-scoped timezone seam.
+
+The `.` entry is browser-safe — no `effect`, no `node:*` — so a route or
+component can import it directly. The Effect seam lives in a separate subpath,
+`@voltro/datetime/context`, so the pure surface carries no `effect` dependency.
+
+> **Phase 1.** This is the storage + timezone + formatting layer. Schema-DSL
+> temporal column types, `interval()`, and `rrule()` are later phases; use
+> `timestamp()` columns and these helpers today.
+
+## The storage contract: a `Date` is a UTC instant
+
+`timestamp()` stores `TIMESTAMPTZ`, and the driver hands your app code a plain JS
+`Date`. A `Date` is a bare epoch-millisecond count with no zone of its own, so
+the ONLY correct reading of it is "the UTC instant it points at". These helpers
+make that reading explicit and lossless in both directions:
+
+```ts
+import { toInstant, toUTCString, isValidTimeZone } from '@voltro/datetime'
+
+// A `Date` from a query IS a UTC instant — read it as one, losslessly.
+const when = toInstant(row.createdAt)   // Temporal.Instant
+toUTCString(row.createdAt)              // "2026-08-06T12:00:00Z" — the wire/storage form
+
+isValidTimeZone('Europe/Berlin')        // true
+isValidTimeZone('Mars/Phobos')          // false
+```
+
+`toInstant` accepts a `Temporal.Instant`, a JS `Date`, or an ISO-8601 string —
+but a string MUST carry an explicit offset or `Z`. A naive `2026-01-01T12:00`
+denotes no instant and throws, by design: the whole point is that there is no
+silent zone-guessing. Bridge back with `toDate(instant)` for storage or interop.
+
+## Timezone resolution — the framework convention
+
+Which zone should a given request render in? Resolve it in priority order, each
+candidate validated as an IANA name, falling back to `UTC`:
+
+```ts
+import { resolveTimezone } from '@voltro/datetime'
+
+const tz = resolveTimezone({
+  userTimeZone:    user.timezone,        // 1. the viewing user's profile
+  tenantTimeZone:  tenant.timezone,      // 2. the tenant / org default
+  browserTimeZone: 'Europe/Berlin',      // 3. the browser-reported zone
+})                                        // → a validated IANA name, else 'UTC'
+```
+
+This mirrors `@voltro/i18n`'s `resolveLocale` in spirit — pure, framework-agnostic,
+no Effect or RPC — so it runs in any request pipeline. An invalid or absent
+candidate falls through to the next signal; the result is GUARANTEED valid.
+
+### Carrying it through a request — the context seam
+
+The resolved zone travels through a request via an Effect context tag in
+`@voltro/datetime/context`, so any route, mutation, workflow, or agent can read it:
+
+```ts
+import { currentTimezone, withTimezone } from '@voltro/datetime/context'
+import { Effect } from 'effect'
+
+const program = Effect.gen(function* () {
+  const tz = yield* currentTimezone   // the request's zone, or 'UTC' when none set
+  return tz
+})
+
+// Provide an explicit zone for a sub-computation:
+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. The runtime provides
+the tag per request (via `resolvedTimezoneLayer`); the web layer's `useTimezone()`
+hook is a thin projection over it.
+
+## Arithmetic — the DST split is in the names
+
+Every operation that is ambiguous without a zone REQUIRES an IANA `timeZone`
+argument. There is no implicit "system zone", so a call site cannot silently do
+the wrong thing on a differently-configured box. The DST distinction is
+deliberate and encoded in the method names:
+
+```ts
+import { addDays, addHours, startOfDay, endOfDay } from '@voltro/datetime'
+
+// WALL-CLOCK: same local time, one calendar day later in Berlin.
+// Across a DST boundary the elapsed real time is 23h or 25h. Needs a zone.
+addDays(when, 1, 'Europe/Berlin')
+
+// EXACT elapsed time: 24 × 3600 seconds, DST-oblivious. No zone.
+addHours(when, 24)
+
+// Zone-relative day boundaries.
+startOfDay(when, 'Europe/Berlin')
+endOfDay(when, 'Europe/Berlin')
+```
+
+`addDays` / `addMonths` are wall-clock ("same local time, N days on"); `addHours`
+is exact elapsed time. Comparisons that measure absolute instants (`isAfter`,
+`isBefore`) take no zone; `isSameDay` does, because "same day" is a wall-clock
+question. For a calendar date with no time and no zone — a birthday, a holiday, a
+due date — use `plainDate(year, month, day)` / `parseDate('2026-08-06')`.
+
+## Formatting — locale- and timezone-aware
+
+Formatting is where the viewer's timezone and locale are APPLIED. Both are
+explicit arguments — this layer carries no ambient locale (the web layer resolves
+`useLocale()` and passes it in):
+
+```ts
+import { formatDate, formatDateTime, formatRelativeTime } from '@voltro/datetime'
+
+formatDate(row.createdAt, 'Europe/Berlin', { locale: 'de' })        // "6. Aug. 2026"
+formatDateTime(row.createdAt, 'America/New_York', { locale: 'en' })
+formatRelativeTime(row.createdAt, { locale: 'en' })                 // "3 hours ago"
+```
+
+`FormatOptions` is `{ locale? }` plus any `Intl.DateTimeFormatOptions` override,
+so `formatDate(when, tz, { locale, dateStyle: 'full' })` works. `formatRelativeTime`
+picks the largest unit that fits the signed distance from `now` (default: the
+current instant) and is zone-independent — it measures elapsed real time, not
+wall-clock days.
+
+> These helpers are the STORAGE/TIMEZONE layer. `@voltro/i18n`'s
+> [`useFormatDate` / `useRelativeTime`](/docs/i18n/formatting) hooks are the
+> React binding that read the active locale from the provider; reach for those in
+> components, and for `@voltro/datetime` in server code, loaders, and tests.
+
+## Temporal directly
+
+The exact standard `Temporal` types are re-exported, so you can drop to the full
+API when a helper doesn't cover your case:
+
+```ts
+import { Temporal } from '@voltro/datetime'
+
+const noon = Temporal.PlainTime.from('12:00')
+```
+
+Import `Temporal` from `@voltro/datetime`, never from the polyfill directly — that
+keeps the eventual switch to the native global (once it is universal in browsers)
+a one-line change for the whole codebase.