@voltro/cli 0.56.0 → 0.57.0

package/dist/{webhooksCommand-uuPu8qQX.js → webhooksCommand-CYXTNvXq.js}

@@ -222,8 +222,8 @@ 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-B9Gz0k85.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
-	return r((await n(await t(e))).events.map((e) => ({
+	let { walk: t, loadDiscovered: n } = await import("./dev-Bl9HqtV7.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	return r((await n(await t(e), { root: e })).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor
 	}))).map((e) => x(e.descriptor));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -884,24 +884,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.56.0",
-    "@voltro/cache": "0.56.0",
-    "@voltro/client": "0.56.0",
-    "@voltro/content": "0.56.0",
-    "@voltro/data-transfer": "0.56.0",
-    "@voltro/database": "0.56.0",
-    "@voltro/env": "0.56.0",
-    "@voltro/kv": "0.56.0",
-    "@voltro/logger": "0.56.0",
-    "@voltro/plugin-auth": "0.56.0",
-    "@voltro/plugin-broadcast": "0.56.0",
-    "@voltro/plugin-mail": "0.56.0",
-    "@voltro/plugin-storage": "0.56.0",
-    "@voltro/plugin-webhooks": "0.56.0",
-    "@voltro/protocol": "0.56.0",
-    "@voltro/runtime": "0.56.0",
-    "@voltro/serverless": "0.56.0",
-    "@voltro/workflow": "0.56.0",
+    "@voltro/ai": "0.57.0",
+    "@voltro/cache": "0.57.0",
+    "@voltro/client": "0.57.0",
+    "@voltro/content": "0.57.0",
+    "@voltro/data-transfer": "0.57.0",
+    "@voltro/database": "0.57.0",
+    "@voltro/env": "0.57.0",
+    "@voltro/kv": "0.57.0",
+    "@voltro/logger": "0.57.0",
+    "@voltro/plugin-auth": "0.57.0",
+    "@voltro/plugin-broadcast": "0.57.0",
+    "@voltro/plugin-mail": "0.57.0",
+    "@voltro/plugin-storage": "0.57.0",
+    "@voltro/plugin-webhooks": "0.57.0",
+    "@voltro/protocol": "0.57.0",
+    "@voltro/runtime": "0.57.0",
+    "@voltro/serverless": "0.57.0",
+    "@voltro/workflow": "0.57.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -749,7 +749,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.56.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.57.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.56.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.57.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/_manifest.json

@@ -260,7 +260,7 @@
       "group": null,
       "description": "Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue.",
       "path": "agent-docs/schema-driven-ui.md",
-      "files": 23
+      "files": 24
     },
     {
       "id": "security",

package/templates/agent-docs/ai.md

@@ -1326,7 +1326,7 @@ defaults to treating an `AgentEvent`-shaped `{ _tag: 'done' | 'error' }` as the
 end of the run. Override `isTerminal` when your element type signals completion
 some other way, or the hook will keep trying to resume a finished stream.
 
-For multi-node deployments use `dataStoreResumableStreamStore(ctx.store)` — it persists to the framework's own database (`streamEventsTable` + `streamStateTable`, register them in your `database/index.ts`) and elects exactly ONE producer per `streamId` via an atomic claim, so only one node runs the model while every node's consumers tail the shared log. Sweep finished streams with `gcResumableStreams(store, { olderThan })`.
+For multi-node deployments use `dataStoreResumableStreamStore(ctx.store)` — it persists to the framework's own database (`_voltro_stream_events` + `_voltro_stream_state`, created for you: the table assembly adds both for any app that depends on `@voltro/ai`, so `voltro dev` / `voltro db apply` / `voltro migrate` all plan them) and elects exactly ONE producer per `streamId` via an atomic claim, so only one node runs the model while every node's consumers tail the shared log. Sweep finished streams with `gcResumableStreams(store, { olderThan })`.
 
 For the fastest path, `redisResumableStreamStore(redis, { ttlSeconds })` backs the log with a Redis LIST (`RPUSH`/`LRANGE`) plus a `SET … NX` producer claim — TTL evicts finished/abandoned streams without a sweep. `@voltro/ai` takes no Redis dependency; you inject a tiny `ResumableRedis` client (five methods: `setNx` / `rpush` / `lrange` / `set` / `exists`) adapting ioredis / node-redis. All three backends satisfy the same `ResumableStreamStore` interface, so they swap without touching the producer/consumer code.
 

package/templates/agent-docs/authentication.md

@@ -2691,31 +2691,46 @@ comment, and this one is load-bearing: the resume grant is issued on its
 strength. Omit `tables:` entirely and nothing is verified and nothing resumes —
 the conservative default.
 
-## Eager loads are refused, not silently unfiltered
+## Eager loads are narrowed too
 
 A relation pulled in with `.with(...)` is resolved **below** the seam that
-applies the filter: the stores expand the eager tree themselves (the memory
-store recurses through its own raw read; the SQL stores fold the relation into
-one join). So a filtered table reached through a relation would come back
-unfiltered.
+AND-merges the filter onto a read's base table: the stores expand the eager tree
+themselves (the memory store recurses through its own raw read; the SQL stores
+fold the relation into one join or JSON aggregate). So for a while a filtered
+table reached through a relation came back unfiltered, and then — once that was
+found — the read refused rather than serve those rows.
 
-Rather than serve those rows, the read **refuses**, naming the table and both
-ways out:
+Neither is the case now. The middleware writes your filter's predicate into each
+narrowed branch's `where`, which is where a caller could have put it themselves,
+so every resolver on every dialect applies it without knowing a row filter
+exists:
 
+```ts
+// what you wrote
+notes.with({ readers: true })
+
+// what the store resolves, when your filter narrows `readers`
+notes.with({ readers: { where: /* your filter's predicate for `readers` */ } })
 ```
-row filter: 'readers' is reached through an eager load on 'notes', and an eager
-relation is resolved BELOW the row filter — its rows would come back
-unfiltered. Refusing the read rather than serving it.
-  → read 'readers' as its own query (it is filtered there), or
-  → drop 'readers' from this .with(...) if the relation does not need
-    row-level narrowing.
-```
 
-Only relations reaching a table your filter actually narrows are affected —
-every other eager load is untouched. Applying the filter inside eager
-compilation is the real fix and it is a per-dialect change; until then this is
-a refusal rather than a leak, for the same reason the module refuses to
-fail open.
+Your own `where` is kept and the filter goes **under** it, so a branch you
+narrowed stays narrower and nothing a caller writes can widen the filter.
+Nested `.with(...)` is narrowed at every level. A relation reaching a table your
+filter does not narrow is untouched.
+
+**One case still refuses: a filtered `manyToMany` JUNCTION.** A branch `where`
+is a predicate on the relation's TARGET, and a filter narrowing the junction has
+nowhere to be expressed — so that read raises rather than joining junction rows
+the filter would have removed:
+
+```
+row filter: the junction table 'noteTags' behind relation 'tags' on 'notes' is
+row-filtered, and a many-to-many junction is read below the seam that could
+narrow it — its rows would be joined unfiltered. Refusing the read rather than
+serving it.
+  → read 'noteTags' as its own query (it is filtered there), or
+  → drop 'tags' from this .with(...).
+```
 
 ## Row filters vs. guards
 

package/templates/agent-docs/cli.md

@@ -1856,6 +1856,8 @@ It covers both halves of the stack:
 | server | a `token` / `secret` / `password` column with no encryption | `.encrypted()` |
 | server | a notify / webhook helper called at a mutation's tail | `defineSubscriber` / `defineReaction` |
 | server | a `*.subscribe.ts` handler that writes or publishes, with no `once:` | `once: true` on `defineSubscriber` |
+| server | an executor builds a field its descriptor's `output` does not declare | add it to `output` — the struct IS the serializer |
+| server | a mutation writes a NULLABLE column through an input field that cannot be `null` | `Schema.optional(Schema.NullOr(...))` |
 | server | `hasMore` + `limit + 1` | `paginateById` |
 | server | `.getTime()` / `.toISOString()` mapping a row on the way out | `timestampMs` / `timestampMsOrNull` from `@voltro/database/wire` in the descriptor's `output` struct |
 | client | per-field `useState` + a submit flag | `useFormBinding` |
@@ -1900,6 +1902,25 @@ decision was made, not which way. It reads the handler through the AST, so
 like an inline arrow; a handler IMPORTED from another module is not judged at
 all, since its body is not in the file being read.
 
+**Two rules read a DECLARATION against a DECLARATION, and are therefore exact.**
+`executor-builds-an-undeclared-field` compares the object literal an executor
+returns with its descriptor's `output` struct: since the struct IS the
+serializer, a key it does not declare is stripped on the way out, so every
+reader downstream gets `undefined` and renders a blank with nothing logged
+anywhere. `nullable-column-a-mutation-cannot-clear` compares a mutation's target
+table's nullable columns with its input schema — a nullable column written
+through a field that cannot be `null` can be set once and never emptied.
+
+Both REFUSE rather than guess, and the refusals are the interesting part. A
+spread on either side of the output comparison (`{ ...row, extra }`, or a
+`...Base` inside the declared struct) means the key set is not knowable from the
+source; reporting the visible half would name the field the author can already
+see and miss the ones they cannot. An output that is a named schema rather than
+a literal struct is unjudgeable, not empty — the second reading would make every
+field a finding. And a table declaration the scan cannot find produces no
+finding at all, because "this table has no nullable columns" and "I could not
+look" lead to opposite conclusions.
+
 It stays quiet on a reader on purpose. `once:` on a cache-warming subscriber
 would silence it on every replica but one, which is worse than the repetition it
 removes — only the handler's author knows which of the two they wrote.
@@ -2368,6 +2389,33 @@ voltro check             --url https://api.example.com
 
 `--token` (or `VOLTRO_INSPECT_TOKEN`) supplies the bearer; `VOLTRO_INSPECT_URL` sets a default target so you can drop the flag. Works for `inspect`, `logs`, `traces`, `workflows`, `cluster` and `check`.
 
+### `logs` and `traces` need a ring on the target — off by default
+
+A deployed app runs `voltro serve`, and `voltro serve` keeps **no** in-process log ring or span buffer unless you ask for one. Without it both commands answer:
+
+```
+voltro logs: NOTHING WAS SEARCHED — the target could not be read: HTTP 404
+endpoint not enabled on this instance — This instance keeps no in-process logs ring…
+```
+
+That headline is the point: *"no records matched the given filters"* would have sent you off widening `--tail` forever. Turn a ring on per app:
+
+```ts
+// app.config.ts
+export default defineAppConfig({
+  inspect: {
+    logs:   true,              // default size
+    traces: { size: 2_000 },   // or name it
+  },
+})
+```
+
+or per deployment, without a rebuild: `VOLTRO_INSPECT_LOGS=2000`, `VOLTRO_INSPECT_TRACES=on`, `=off` to override a config that declared one.
+
+**Why off by default.** A ring is memory on every replica, forever, for data most deployments already collect from stdout through their platform's pipeline. That pipeline stays the main road; the ring answers the different question — *what has THIS instance been doing in the last few minutes* — and it answers it for a hosted app, where reading a pod's stdout is not an option.
+
+**What a ring does not do.** It holds a bounded number of records on ONE replica. Against a fleet you are reading 1/N, and it is not retention: a restart empties it. `voltro dev` keeps both rings unconditionally — this switch is about what production does.
+
 ## `voltro probe access` — is a declared guard actually enforced?
 
 `voltro check` reads an app's manifest and reports a procedure with **no access

package/templates/agent-docs/configuration.md

@@ -202,10 +202,35 @@ is accepted but only reachable from server-side render code, and the boot
 ## Plugins declare their env
 
 A plugin that reads environment variables declares them via `declaredEnv` on its
-`VoltroPlugin` (metadata only — the plugin still reads its own values). This
-makes a plugin's env needs visible in the manifest, `.env.example`, and the
-dashboard. The first-party plugins already declare theirs, so the manifest is
-complete out of the box.
+`VoltroPlugin`. The plugin still reads its own values; declaring them makes its
+env needs visible in the manifest, `.env.example`, and the dashboard. The
+first-party plugins already declare theirs, so the manifest is complete out of
+the box.
+
+**`required: true` is a boot CONTRACT, not documentation.** Every required entry
+is resolved before any plugin activates, and one that does not resolve **aborts
+the boot** with the plugin named:
+
+```
+plugin environment validation failed (1 variable):
+  • STRIPE_SECRET_KEY — required by @voltro/plugin-billing, and nothing set it
+      Stripe API secret key.
+  → set the variable, or pass the value as a plugin option if the plugin takes one, or
+    declare it yourself in app.config.ts's `env` (an app declaration overrides a plugin's).
+```
+
+That is the point of failing at the boot: a deployment variable which silently
+stops being set — a rotated secret, a typo in a values file, a CI variable nobody
+created — is routine, and the alternative is finding out from the first customer.
+
+A `secret: true` variable resolves through the configured **secrets backend**,
+not just `process.env`. A backend that cannot answer fails the boot too, reported
+as *unreadable* rather than as an absent variable — those are different facts and
+need different next steps.
+
+Your own `defineEnv` declaration of the same variable **overrides the plugin's**:
+declare it there to give it a default, or to mark it optional because you pass
+the value as a plugin option instead.
 
 ## Anti-pattern
 

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

@@ -368,10 +368,19 @@ 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…
 ```
 
+**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.
 
 ```

package/templates/agent-docs/deployment.md

@@ -907,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

package/templates/agent-docs/plugins/audit.md

@@ -356,7 +356,7 @@ What it discloses, and what it never does:
 
 | | |
 | --- | --- |
-| a string | its LENGTH — `string(113)`. Never a prefix, never a hash |
+| a string | its LENGTH — `string(113)`. Never a prefix, never a hash. Below a floor, a bucket: `string(<16)` |
 | a number, a boolean, a date | its TYPE only. A number can BE the secret |
 | a declared field name | survives — `jiraToken` |
 | a key that is not an identifier | described, not reproduced — `<key:string(36)>` |
@@ -369,10 +369,26 @@ Two of those are worth a sentence each.
 it looks like a declared field: a plain short identifier. A legitimate key that
 is not one (`content-type`) loses its name and keeps its shape.
 
-**A string's length is a real disclosure, and a small one.** For a fixed-format
-credential it carries nothing — every token of a given kind is the same length.
-For a human-chosen password it is a weak hint. If that matters in your threat
-model, `'all'` is the default and stays available.
+**A string's length is a real disclosure, and a small one — above a floor.** For
+a fixed-format credential it carries nothing — every token of a given kind is the
+same length. For a human-chosen password it is a weak hint.
+
+Below a floor it stops being small: a six-digit TOTP reported as `string(6)`, or
+a four-digit PIN as `string(4)`, tells a reader with log access exactly what
+shape to try. Nothing this mode is FOR lives under 16 characters — the case that
+motivated it is 113 against an expected 44 — so a string shorter than that
+reports `string(<16)`: shorter than the floor, not how much shorter.
+
+```ts
+auditPlugin({ redactOutcome: 'shape', redactionLengthFloor: 0 })
+```
+
+`0` turns the floor off, for a deployment whose audited payloads are ids and
+tokens and every character of length is worth having; raise it for one holding
+short human-entered secrets. An EMPTY string stays exact (`string(0)`) — "the
+field arrived empty" is a real diagnosis and an empty string is not a secret. The
+floor applies to described keys too, for the reason above them: a key that is not
+a declared field is a key carrying data.
 
 `redactSubject` spells its variant `'metadata-shape'`, because its default
 (`'metadata'`) already names the field it acts on.

package/templates/agent-docs/plugins/billing.md

@@ -40,6 +40,8 @@ export default {
 
 `plans` is the single source of tier→limit truth — it lives in code, not the DB, so limits change by redeploy, not migration. Entitlement values are `number | 'unlimited'`. With no provider configured (and no `STRIPE_SECRET_KEY`), the plugin uses an in-memory **mock provider** — zero-config for dev and tests.
 
+> **Under `NODE_ENV=production`, a mock chosen by ABSENCE warns.** `STRIPE_SECRET_KEY` is a deployment variable, and one that silently stops being set — a rotated secret, a typo in a values file, a CI variable nobody created — is routine. Without the line, an app that had been charging customers keeps answering every billing call successfully, reaches nobody, and leaves nothing to find afterwards. Set the key, or write `provider: 'mock'` so the mock is a decision on the page rather than an absence. An explicitly declared mock stays silent.
+
 What it provides:
 
 - The `_voltro_billing_*` tables (customers, subscriptions, invoices, usage, flush_claims, dunning_notices) via `extendSchema.tables`.

package/templates/agent-docs/reference.md

@@ -89,6 +89,7 @@ these before hand-rolling a form, a table, or a picker** — full guide in
 | [`usePreview`](/docs/ui/client-utilities/use-preview) | Mutation dry-run — run the real handler in a rolled-back transaction. |
 | [`useProvenance`](/docs/ui/client-utilities/use-provenance) | "Why is this value here?" — lineage lookup for a field. |
 | [`useOnRpcError`](/docs/ui/client-utilities/use-on-rpc-error) / `reportClientError` | Subscribe to the rpc error bus; report a client error to the server. |
+| [`useSubscriptionHealth`](/docs/ui/client-utilities/use-subscription-health) | Which of an api's calls are currently REFUSED — a refused subscription never retries and reads as `loading`. |
 | [`useTracking`](/docs/ui/client-utilities/use-tracking) | Fire mount/unmount + interaction tracking events. |
 | [`useCapabilityManifest`](/docs/ui/client-utilities/use-capability-manifest) | The api's capability manifest (procedures + tables + schemas), fetched once. |
 | [`useRefreshSubscriptions`](/docs/ui/client-utilities/use-refresh-subscriptions) | Force-refresh live subscriptions (e.g. after an out-of-band change). |

package/templates/agent-docs/scheduling.md

@@ -539,6 +539,29 @@ defineSchedule({
 
 > The watchdog stops *waiting* and records the timeout; it cannot truly abort a Promise's in-flight side effects (JavaScript has no thread-kill). Make long handlers cooperative — check a deadline, or do the heavy lifting in a [workflow](/docs/workflows/overview) with its own step-level durability.
 
+## Across replicas — the heartbeat
+
+`onOverlap: 'skip'` is a **cluster-wide** rule, not a per-process one: a firing is suppressed when an occurrence of the same schedule is running on *any* replica. That check reads `_voltro_schedule_runs`, so it needs a way to tell a run that is still working from one whose process died mid-run and left its row on `running` forever.
+
+That is `heartbeatAt`: a run in flight bumps it every **30 seconds**, and a row silent for three beats is read as dead rather than as a live occurrence. Without it the only evidence a row carried was `firedAt`, and a window generous enough never to cut off a long run is also long enough to suppress a half-hourly cron for hours after one restart.
+
+```ts
+// app.config.ts
+export default defineAppConfig({
+  scheduling: {
+    scheduleHeartbeatMs: 30_000,   // default; VOLTRO_SCHEDULE_HEARTBEAT_MS overrides it
+  },
+})
+```
+
+Raise it in a deployment with many long-running schedules where the writes matter more than the detection latency; a run shorter than one interval writes no beat at all and costs nothing either way. It is **not a lease** — a stale beat only stops a corpse from holding the schedule shut; nothing takes ownership of the run.
+
+The skip is logged with what it measured, so the two cases are legible from the log alone:
+
+```
+schedule: overlap skip  name=reindex scope=cluster heldBy=pod-7f4c lastSeenMs=1840
+```
+
 ## Backfill — `backfill`
 
 When the process was down across one or more firing instants, what should happen on boot? Computed from the last `_voltro_schedule_runs` row for the schedule.

package/templates/agent-docs/schema-driven-ui.md

@@ -370,6 +370,36 @@ widget })` rides an annotation, `description` becomes help text, and
 underneath is an implementation detail — no engine type appears in the public
 API, and production builds stub its devtools channel automatically.
 
+### When the FORM decides which mutation it is
+
+Some forms only learn their target from what the user does: a calendar entry
+becomes a recurring **series** the moment "repeats" is ticked, and the series
+mutation takes eleven more fields than the single one.
+
+Pass a function of the current values instead of a tag:
+
+```tsx
+const form = useFormBinding<CalendarInput>(
+  'app',
+  (v) => (v.repeats ? 'calendarRecurringEvent.create' : 'calendarEntries.create'),
+  { defaults: { title: '', repeats: false } },
+)
+```
+
+The schema in force follows the tag, so `form.fields` grows and shrinks with it
+and validation always matches what will actually be submitted. **The values do
+not reset** — the engine is constructed once and never rebuilt, so everything
+typed before the switch survives it. That is the whole reason this exists:
+deriving the tag outside the binding is not available (the values belong to the
+binding and do not exist before it), and re-mounting with a different tag throws
+the user's input away.
+
+Two details worth knowing. On the first render there are no values yet, so the
+function is called with your `defaults`. And the accessibility ids are pinned to
+the first tag and stay there — they are DOM ids, and letting them move on the
+keystroke that flips the branch would remount every field, taking the focus and
+the caret with it.
+
 ### Reference fields, uploads, and testing the form
 
 **Reference fields.** Mark a schema field as a table reference and it renders
@@ -1597,6 +1627,57 @@ identity* changed underneath them.
 
 
 
+---
+
+<!-- source: en/ui/client-utilities/use-subscription-health.md -->
+## useSubscriptionHealth
+
+_Which of an api's calls are currently refused — the state a screen cannot derive from its own hook._
+
+A refused subscription is **terminal for its transport**. It does not retry, so
+there is no second error event to react to — and `SubscriptionFailed` presents
+`data: undefined`, which is the value most reading layers derive `loading` from.
+A component that branches on `data === undefined` therefore shows a spinner from
+then on, indefinitely. The state union models this correctly (`failed: true`,
+`loading: false`); what loses it is the wrapper hook in between, and a wrapper
+that passes `{ data, loading }` through is the natural shape to write.
+
+`useSubscriptionHealth` answers the question no single hook can: **is anything on
+this api currently refused, and what.**
+
+```tsx
+import { useSubscriptionHealth } from '@voltro/client'
+
+const SessionBar = () => {
+  const { healthy, failed } = useSubscriptionHealth('app')
+  if (healthy) return null
+  return <Banner>Not loading: {failed.map((f) => f.tag).join(', ')}</Banner>
+}
+```
+
+A tag enters `failed` when a call for it fails and leaves when a call for the
+**same tag** succeeds. It is keyed by tag rather than counted, because the
+question a screen asks is "is this working now" and two failures of one call are
+one broken thing. `healthy` is the positive form of the same fact, so a component
+reads `if (!healthy)` instead of `if (failed.length > 0)`.
+
+Each entry is `{ tag, source, error, at }` — `at` is the timestamp of the
+failure, so a bar can say *since 12:04* rather than only *broken*.
+
+## What it does not do
+
+It is not a retry mechanism and not an error boundary. Recovery is the
+transport's job: an `Unauthenticated` failure makes the framework re-resolve the
+credential and rebuild the connection, and a rebuilt client re-subscribes on its
+own — a failed entry is never carried across the swap, so it is re-attempted
+rather than restored as broken. Nothing in your app wires that.
+
+The register is scoped to one api's runtime and is reset when that runtime is
+rebuilt, deliberately: carrying a failure across a transport swap would report a
+call as broken that has not been tried since.
+
+
+
 ---
 
 <!-- source: en/ui/client-utilities/use-tracking.md -->