@voltro/cli 0.55.0 → 0.57.0

package/templates/agent-docs/data.md

@@ -2346,6 +2346,38 @@ The contract, in the order it protects you:
 
 **The boundary to keep:** if your own UI needs live data, that is a query + `useSubscription`, never a gateway. A gateway hands you raw frames and none of the subscription protocol's guarantees — reach for it only when the CLIENT dictates the protocol.
 
+## When the api connects — `web.api.connect`
+
+Every declared api opens its WebSocket at mount by default. That is `'eager'`,
+and it is what the framework has always done.
+
+```ts
+// apps/web/app.config.ts
+web: { api: { connect: 'lazy' } }
+```
+
+`'lazy'` defers the connection to the FIRST hook that asks for that api —
+`useSubscription`, `useMutation`, `useAppClient`, any of them. A page that reads
+no data never opens a socket.
+
+Two measurements decide whether you want it. Both are from a real browser
+against a `voltro start`:
+
+- **`interactive: 'full'` is the default, and it connected regardless.** A
+  pre-rendered documentation page that subscribes to nothing opened a socket;
+  pages set to `interactive: 'none'` or `'islands'` opened none. So the pages
+  paying for a connection they never use are exactly the ordinary ones.
+- **An open socket keeps a dormancy-managed instance awake.** `isIdleNow`
+  returns false while `connectedClients() > 0` (see
+  [scale-to-zero](/docs/deployment/scale-to-zero)), so one browser tab left open
+  on a pricing page prevents scale-to-zero for as long as it stays open.
+
+`'eager'` remains the default because `'lazy'` moves WHEN a connection error
+surfaces — from page load to first data use — and an app that opens its socket
+for a side effect (a presence ping, an inspect stream) rather than through a data
+hook would notice the difference. If your app subscribes on every page, the two
+behave identically.
+
 ## See also
 
 - [Subscribers (`*.subscribe.ts`)](/docs/data/subscribers) — server-side, best-effort post-commit reactivity to a table (NOT the client hook on this page).
@@ -3988,7 +4020,7 @@ These helpers give you the secure **handler**, not schema derivation. Deriving t
 
 _Per-table post-commit reactivity via file convention. Default-exported defineSubscriber({ table, on, handler }) — fires AFTER commit, best-effort, fire-and-forget for async handlers._
 
-Use a `*.subscribe.ts` file when you want code to **run after every commit** to a specific table — refresh a search index, emit an external notification, invalidate a cache, push to a worker queue. The file convention is parallel to `*.startup.ts` / `*.cron.tsx` / `*.webhook.tsx`: drop a file matching the suffix anywhere under `apps/<api>/`, default-export a `defineSubscriber({...})`, the framework discovers + binds it at boot.
+Use a `*.subscribe.ts` file when you want code to **run after every commit** to a specific table — refresh a search index, invalidate a cache, push to a worker queue, emit an external notification. The handler runs on **every replica**; when its effect must not repeat, add [`once:`](#how-often-does-it-run-once-per-replica-unless-you-say-otherwise). The file convention is parallel to `*.startup.ts` / `*.cron.tsx` / `*.webhook.tsx`: drop a file matching the suffix anywhere under `apps/<api>/`, default-export a `defineSubscriber({...})`, the framework discovers + binds it at boot.
 
 Subscribers are deliberately **best-effort** + **non-durable**. For crash-safe async work — "a row changed, now run a workflow" — reach for a [reaction](/docs/data/reactions) instead.
 
@@ -4059,6 +4091,90 @@ The `on` filter narrows by operation:
 
 Other-table events get filtered out before your handler sees them. The matcher does this at the dispatcher level so subscribers add zero hot-path overhead to writes that don't match their table.
 
+## How often does it run? Once per replica — unless you say otherwise
+
+A subscriber binds to the change stream on **every api instance**. One `INSERT`
+behind three replicas calls your handler three times.
+
+That is the right default and not a gap. A handler that refreshes a per-process
+cache, warms a local index, or updates in-memory state *has* to run everywhere —
+a fleet-wide gate would leave every other replica stale. The default assumes the
+handler is **idempotent**.
+
+It is the wrong default for an **effect** — a notification, a mail, a webhook, a
+payment — because there is nothing to make idempotent: the effect IS a write, so
+each run produces another one. Three replicas send three mails.
+
+`once: true` is the whole answer for most handlers — the framework derives the
+key:
+
+```ts
+export default defineSubscriber({
+  table: 'absence_requests',
+  on:    ['insert'],
+  once:  true,          // exactly one replica runs the handler per change
+  handler: notifyApprovers,
+})
+```
+
+It names the change by its CONTENT plus its position among content-identical
+repeats. That is not a detail: a fleet change carries no LSN, no commit id and no
+`traceId` (the last one deliberately, so a local trace is never mis-attributed to
+a remote write), so content is the only thing two replicas provably agree on —
+and `A→B`, then `B→A`, then `A→B` again has to count as three changes, not two.
+
+Pass a **function** when you want to be COARSER than one-per-change: two updates
+that differ only in a field you do not care about are two changes to `once: true`
+and can be one to a key you write yourself.
+
+```ts
+// apps/api/subscribers/notifyApprovers.subscribe.ts
+export default defineSubscriber({
+  table: 'absence_requests',
+  on:    ['insert'],
+  // Cluster-wide: exactly one replica runs the handler for each change.
+  once:  (event) => String((event.new as { id?: string } | null)?.id ?? ''),
+  handler: async (event, ctx) => {
+    for (const approver of await approversOf(ctx, event.new)) {
+      await sendNotification(ctx, { toEmployeeId: approver.id })
+    }
+  },
+})
+```
+
+**A key you write must tell two genuine changes apart.** A row id is enough for
+`insert` and `delete`, where a row changes state once. It is not enough for
+`update`: two edits to the same row produce the same id, and the second would be
+dropped as a duplicate of the first — an effect that silently stops happening for
+a row that keeps changing. Put something that moves in the key, or use
+`once: true`:
+
+```ts
+once: (event) => {
+  const row = event.new as { id?: string; updatedAt?: Date } | null
+  return `${row?.id ?? ''}:${row?.updatedAt?.toISOString() ?? ''}`
+},
+```
+
+**`once` is AT MOST once, not exactly once.** The claim is taken before the
+handler runs, so a replica that wins and then dies takes the event with it, and a
+claim that cannot be written at all (database unreachable) is taken by nobody.
+Both are loud in the log and neither is retried — a subscriber is best-effort by
+construction. When the effect must not be lost, the change stream is the wrong
+seam: run it inside the mutation, or start a workflow from a
+[reaction](/docs/data/reactions), where durability is the primitive's job.
+
+The boot log says which one each subscriber got:
+
+```
+subscriber: registered table=absence_requests on=["insert"] once=fleet
+subscriber: registered table=posts on=["insert","update"] once=per-replica
+```
+
+Claims live in `_voltro_change_claims` and are swept after an hour
+(`VOLTRO_CHANGE_CLAIMS_TTL_HOURS`). The key is namespaced per subscriber file, so
+two subscribers watching one table never lock each other out.
+
 ## Semantics — best-effort, fire-and-forget
 
 Subscribers are **non-durable** by design:
@@ -4132,6 +4248,8 @@ export default defineSubscriber({
 export default defineSubscriber({
   table: 'organizations',
   on:    'insert',
+  // The POST is an effect: without `once` every replica sends one.
+  once:  (event) => String((event.new as { id?: string } | null)?.id ?? ''),
   handler: async (event, ctx) => {
     if (!event.new) return
     const slug = event.new.slug as string
@@ -4248,9 +4366,17 @@ into the agent's prompt.
 
 ## Guards (the point)
 
-- **`dedupeKey` (required)** — the same logical change acts exactly once. This is
-  what stops a reaction whose act writes the watched table from self-triggering
+- **`dedupeKey` (required)** — the same logical change acts exactly once, across
+  the whole fleet. The key is claimed in `_voltro_change_claims` before the act
+  runs (INSERT-wins on a UNIQUE — the same arbiter the cron scheduler uses), so
+  two replicas seeing one change start one workflow, not two. This is also what
+  stops a reaction whose act writes the watched table from self-triggering
   forever. `defineReaction` throws at boot if it's missing.
+
+  The claim is taken BEFORE the act, which is what makes it a gate rather than a
+  report — and the cost is stated rather than hidden: an act that THROWS has
+  already consumed its key and is not re-run by a later duplicate. Durability
+  belongs to the workflow the act starts, not to the trigger.
 - **`rateLimit` (optional)** — at most `limit` firings per `windowMs`.
 - **`costBudgetUsd` (optional)** — a per-tenant AI spend ceiling; over budget,
   the reaction refuses (fails closed).
@@ -4271,8 +4397,9 @@ into the agent's prompt.
 - Best-effort + fire-and-forget (like subscribers) — a failing act logs +
   continues; it can't back-pressure the change stream. Durability comes from a
   workflow act (an agent act is best-effort).
-- `dedupeKey` is in-memory per process in v1 (it stops the self-trigger storm
-  within a run); a durable cross-restart dedupe table is a follow-up.
+- `dedupeKey` claims survive a restart but not forever: `_voltro_change_claims`
+  is swept after an hour (`VOLTRO_CHANGE_CLAIMS_TTL_HOURS`). A change whose key
+  reappears after that window acts again.
 
 ## When to use what
 
@@ -4717,6 +4844,19 @@ available without a distributed transaction into the target system, so:
 **Handlers must be idempotent.** A process that dies between "the remote
 accepted it" and "we recorded that" will retry.
 
+**On several replicas, that used to be the smaller reason.** Every replica runs
+the drain, and the drain read every pending row — so an effect was dispatched
+once *per replica*, on the happy path, every time. It is claimed now: a row moves
+`pending → delivering` in one atomic statement stamped with the claiming
+process, so a racing replica loses the row rather than duplicating it, and a
+claim whose holder stops responding is returned to the queue after its lease
+(`claimLeaseMs`, default 5 minutes — raise it above your slowest handler).
+
+That removes the routine duplicate. It does not make delivery exactly-once, and
+nothing can: the process can still die between the remote accepting and the row
+being marked. The idempotency requirement stands — it is now about the failure
+case it was always meant to describe, rather than about every single delivery.
+
 ## Declaring the handler
 
 One `*.outbox.ts` file per effect:

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

@@ -148,6 +148,13 @@ deployments (k8s with `replicas: 3`, multi-pod ECS, etc.) need a
 shared store, otherwise a write on instance A doesn't pin reads on
 instance B.
 
+**The boot says so now.** When replicas are configured and the RYW store falls
+back to memory on a deployment whose environment says several replicas
+(`POD_NAME`, `FLY_ALLOC_ID`, `K_REVISION`, … — or `REPLICA_COUNT`, which is a
+declaration in both directions), the boot warns and names the two ways out. It
+used to log `ryw policy 'fallback'` as though the policy were in force, and the
+first symptom was a user reloading and seeing their own save gone.
+
 Wire Redis:
 
 ```sh
@@ -306,6 +313,31 @@ The bus is **additive** to the inline emit path. Local reactivity must survive a
 
 Because the inline path is never removed, a broker outage degrades **cross-replica** fan-out only — local reactivity keeps working, and the framework logs a warning. The bus reconnects when the broker returns.
 
+## When the connection drops
+
+Every cross-replica mechanism here rides a connection, and a connection that dies quietly is worse than one that fails loudly: the app keeps serving, the clients keep their sockets, and their live queries simply stop updating. So each path is required to notice, recover, and then **say that it lost something**.
+
+**A hole is never patched — it is re-derived.** None of these transports keeps a log. Postgres queues nothing for a listener that is not there; Redis and NATS pub/sub retain nothing at all. So there is nothing to replay, and the only complete recovery is to re-run every live query. That is safe precisely because a live query is idempotent, and it is what the framework does on every one of the events below:
+
+| What happened | How it is noticed | What you see |
+|---|---|---|
+| The postgres `LISTEN` connection died (failover, proxy, `pg_terminate_backend`) | A heartbeat sent through the pool goes unanswered on the LISTEN stream | `cdc: reconnecting` → `cdc: reconnected`, then every live query refreshes |
+| A peer's serial jumped — the broker dropped messages | Per-origin serial accounting; the count is exact | `broadcast: missed N change(s) from …` |
+| This replica could not subscribe at boot (the broker was restarting) | The subscribe is retried in the background | `broadcast: could not subscribe` → `broadcast: subscribed`, then a refresh |
+| The Redis or NATS transport re-dialled underneath us | The driver's connection lifecycle | `broadcast: transport disconnected` → a refresh on reconnect |
+
+Two consequences worth knowing:
+
+- **A broker that is down at boot does not stop the boot.** The replica starts, serves, keeps local reactivity, and joins the bus when the broker returns. A crash loop across the whole fleet is the wrong answer to a broker restart — which is exactly when every replica is dialling at once.
+- **A replica that restarts under a stable name is recognised as a new process.** A StatefulSet pod keeps its `POD_NAME`, and `VOLTRO_REPLICA_ID` is stable by definition, so the name alone cannot tell a restart from a continuation. Each publish carries a per-process epoch so peers reset their watermark instead of quietly ignoring the new process's serials.
+
+The postgres heartbeat is idle-only: any traffic on the channel — including another replica's heartbeat — counts as proof the connection works, so a busy channel never pays for one and a fleet pays roughly one probe per idle window however many replicas it has. Tune it with:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `VOLTRO_CDC_HEARTBEAT_MS` | `20000` | Silence on the channel before a probe is sent |
+| `VOLTRO_CDC_HEARTBEAT_TIMEOUT_MS` | `10000` | How long an unanswered probe may go before the consumer is declared dead |
+
 ## The honest caveat — app-mutation changes only
 
 The bus carries changes that flow through **`ctx.store`** (the framework's mutation path). It does **not** capture **out-of-band DB writes** — a `psql` session, a cron job, or a second service writing the same database directly. Those changes never hit `store.onChange`, so they never reach the bus.
@@ -336,11 +368,27 @@ A changelog table that every replica polls (`SELECT … WHERE seq > :last`) woul
 ```
 
 ```
-[voltro:dev] reactivity: cross-instance fan-out is OFF for dialect 'mssql'. A write on one replica
+[voltro:dev] reactivity: cross-instance fan-out is OFF for dialect 'cockroach'. A write on one replica
 will NOT reach clients on other replicas. Add @voltro/plugin-broadcast (Redis / NATS) to close the gap…
 ```
 
-When BOTH a native path and the broadcast plugin are wired (e.g. postgres + broadcast), both stay active — the own-origin skip dedups, so there's no double-emit. The native path is the primary; the bus is harmless redundancy.
+**The line reports what is RUNNING, not what the dialect could run.** It is derived from the store's resolved change scope, so a dialect that *can* carry changes natively but has capture switched off — `CDC=0`, or an app where every table is `.nonReactive()` — is reported as the gap it is, naming the cause rather than the dialect:
+
+```
+[voltro:dev] reactivity: cross-instance fan-out is OFF. 'mariadb' can carry changes natively
+(binlog CDC) but change capture is not running — CDC=0, or every table is .nonReactive()…
+```
+
+Read that line, not the dialect, when you need to know whether the N² amplification below applies to you: without a native transport there is no second delivery to suppress.
+
+When BOTH a native path and the broadcast plugin are wired (e.g. postgres + broadcast), both stay active — and they carry **different things**. The native path carries table changes to every replica. The bus carries reactivity *channels* (`publishReactivity`), which are not database writes and so have no native transport at all.
+
+```
+[voltro:dev] reactivity: native LISTEN/NOTIFY (postgres) carries table changes;
+@voltro/plugin-broadcast (redis) carries reactivity channels
+```
+
+This page used to say the two paths were harmless redundancy because "the own-origin skip dedups". They were not. The own-origin skip only ever covered a replica's own publish coming back to itself — so a change the native transport had already delivered to every replica was re-published by every replica under *its own* origin, and each peer injected it again. N replicas turned one change into N² deliveries: every subscriber, every live-query wake, every plugin tap. At two replicas a `*.subscribe.ts` handler ran **four** times for one `INSERT`, twice per instance.
 
 ## sqlite and the memory store behind replicas
 

package/templates/agent-docs/deployment.md

@@ -701,6 +701,50 @@ The api stays self-hosted (it must — WebSocket subscriptions + Postgres are
 always-on); only the static bytes move to the edge. `POST /rpc` forwards the
 session cookie exactly as the WS path, so SSR loaders + auth resolve identically.
 
+## Cache headers — `voltro start` sets them, and what they say
+
+Since 0.56.0 the production web server stamps `Cache-Control` on everything it
+serves out of `dist/`. Before that it stamped nothing, and a browser with neither
+`Cache-Control` nor `Last-Modified` has no freshness information at all: it
+revalidated every content-hashed chunk on every visit — for the reference fixture
+that is ten conditional round-trips before the page is interactive, on files whose
+name carries their content hash.
+
+| What | Header | Why |
+|---|---|---|
+| `/assets/index-7N08IhkU.js` (content-hashed) | `public, max-age=31536000, immutable` | The hash IS the version. A new build is a new URL, so there is nothing to invalidate. |
+| `/favicon.svg`, `/robots.txt`, anything from `public/` | `public, max-age=3600` | The URL is stable across deploys, so a long life would pin a stale file. |
+| A pre-rendered page | `public, max-age=0, must-revalidate` | The ETag turns the revalidation into a `304` with no body. |
+| An `isr` page | `public, max-age=0, must-revalidate` | Same, unless you opt into sharing it — below. |
+
+The defaults are deliberately safe for a SHARED cache: nothing is given an
+`s-maxage`, because a CDN holding an HTML page past a deploy serves the previous
+build's asset URLs and the framework has no purge hook to fix that. Two opt-ins,
+for apps that own their CDN and can purge it:
+
+```ts
+// apps/web/app.config.ts
+http: {
+  cache: {
+    // Let a shared cache hold pre-rendered HTML for 60s.
+    htmlSMaxAgeSeconds: 60,
+    // Let a shared cache hold an `isr` page for its OWN `revalidate` window
+    // (plus its stale-while-revalidate). Off by default: `revalidatePath`
+    // purges the framework's cache and a CDN cannot see that purge, so an
+    // on-demand invalidation would take up to `revalidate` seconds to reach a
+    // shared copy.
+    isrShared: true,
+    // Both lifetimes are tunable; `immutableMaxAgeSeconds: 0` turns the
+    // immutable header off entirely.
+    immutableMaxAgeSeconds: 31_536_000,
+    staticMaxAgeSeconds: 3_600,
+  },
+}
+```
+
+When you put the assets on a CDN with `voltro static`, the host's own rules apply
+to them instead — these headers are what the CONTAINER path says.
+
 ## What the framework decides for you
 
 - **Content-Type** per file, from its extension (including the ones generic tools
@@ -863,6 +907,28 @@ readinessProbe:
   failureThreshold: 3
 ```
 
+### Configuring them — `health` in `app.config.ts`
+
+The paths and the answers are declarable, for **both** app types:
+
+```ts
+export default {
+  type: 'web' as const,
+  health: {
+    // Default `/internal`; move it when your app owns a route there.
+    path: '/api/health',
+    liveness:  () => true,
+    readiness: async () => catalogLoaded(),
+  },
+}
+```
+
+**`readiness` is the one worth writing**, because "ready" genuinely differs. For an api it is the dependency ping above. For a screen on a wall it is the opposite — keep showing the last rendered frame while the api wobbles, and count as ready precisely then. Only the app knows.
+
+**`liveness` should stay cheap and dependency-free.** A liveness probe that consults a database restarts pods when the database is slow, which is the one thing that makes an outage worse.
+
+The probes are answered **before routing** on every boot path, so no route and no guard can claim them. That is not a detail: on a web app `voltro dev` used to have no probe surface, and `/internal/*` fell into the page router — an SPA shell answered `200` with HTML, a page whose loader redirects answered `303`, an auth guard answered `303` to `/login`. A kubelet reads all three as PASS, which is the one property a health probe must not have. Worse, one of those pages had a loader that calls the api, so the **web** pod's readiness hung on the **api**'s reachability, once per probe interval.
+
 > **Run `voltro serve` in serving pods — not `voltro dev`.** `voltro dev` is the
 > local-iteration supervisor: file-watch, respawn, codegen, and a boot-time
 > auto-migrate that introspects the whole schema. It does **not** expose the
@@ -1623,7 +1689,7 @@ config format and have **not** been executed against a live account of that
 platform; if one drifts from what the platform ships today, the container is
 still right and the fix is in the wrapper.
 
-Three properties of the image every platform relies on:
+Four properties of the image every platform relies on:
 
 - **`PORT` wins.** The port precedence is `PORT` > `--port` > `app.config.ts` —
   deliberately, because platforms assign through `PORT`. You never configure a
@@ -1635,6 +1701,14 @@ Three properties of the image every platform relies on:
 - **`/internal/readiness` flips to 200 only after the whole boot.** Use it as
   the health check everywhere; routing traffic on process-up instead of
   readiness is how a deploy serves 502s for the first seconds.
+- **The build imports the serve bundle before the image is finished, and a
+  failed import fails the build.** The image-build stage has no database and no
+  secrets, so it cannot require a full boot — but it does not need one: a module
+  `prune-runtime` traced away, a truncated artefact, a wrong entry path or a
+  missing export all fail at *import*, long before anything connects. So the
+  import and a callable `runServe` are required; how far the subsequent start
+  gets is reported, not required. If your build turns red at `load gate:`, the
+  artefact is wrong and no amount of environment will fix it.
 
 ## Fly.io
 

package/templates/agent-docs/internationalization.md

@@ -102,6 +102,38 @@ Locale was already agreed; the zone and the clock were each read from the ambien
 
 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 language picker
+
+`<LocaleSwitcher>` writes the `voltro:locale` cookie and reloads, so the server
+re-renders in the chosen language. It ships from `@voltro/i18n` **unstyled** — a
+native `<select>` you style with your own CSS:
+
+```tsx
+import { useLocale, useT, LocaleSwitcher } from '@voltro/i18n'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+<LocaleSwitcher
+  locales={LOCALES}
+  current={useLocale()}          // server + first paint agree; without it the
+  ariaLabel={useT('lang.label')} // control hydrates from the cookie after mount
+  className="my-lang-select"
+/>
+```
+
+A native `<select>` on purpose: it works everywhere with no portal or
+positioning chrome, is keyboard-accessible by default, and is SSR-safe.
+`onChange` returning `false` suppresses the reload — for an app whose i18n
+runtime swaps catalogs in place.
+
+`@voltro/ui-shadcn` exports the same control pre-styled with the kit's classes.
+Use that one **only in a kit app**: its classes exist only when your CSS entry
+imports `@voltro/ui-shadcn/tokens.css`. Without it the control renders as a bare
+`<select>` with dead `class` attributes — `voltro doctor` reports exactly this.
+
 ## The cookie names are exported
 
 `LOCALE_COOKIE` and `THEME_COOKIE` come from **`@voltro/i18n`** (and from `@voltro/ui-shadcn` if you use the kit):

package/templates/agent-docs/local-first-mobile.md

@@ -399,9 +399,16 @@ Two disciplines it enforces, because both fail silently when hand-rolled:
   when `local` is `true`. Without that every client re-broadcasts what it
   just received: one keystroke, one server write per open tab.
 
-A page mounting an editor needs `renderMode = 'client'`. The default is
+A page mounting an editor needs `renderMode = 'spa'`. The default is
 `'static'`, which pre-renders at build time, and the editor finds no
-`window` there.
+`window` there. `'spa'` is skipped by the prerender and mounts on the
+client; if the route has a layout, that layout still renders server-side
+as an SSR shell.
+
+This page said `'client'`, which is not one of the four render modes and
+fails the build — see [Render modes](/docs/routing/render-modes), which
+names that exact value as invalid. The `frontend-collab` template copied
+the sentence and was unbuildable for as long as it existed.
 
 Carets ride a `delivery: 'latest'` EVENT, deliberately not presence
 metadata: the roster's value-compare push would make every caret move a