@voltro/cli 0.56.0 → 0.58.0

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

@@ -263,6 +263,54 @@ await ctx.store.upsert('orgSlugs', {
 Requires a composite UNIQUE constraint on the table — declare it via
 `.unique([cols])` in the schema (see [Indexes](/docs/database/indexes#composite-unique-constraints)).
 
+### The row you get back is the row that was there
+
+When an upsert on a non-`id` key MATCHES, it updates the existing row — and that
+row keeps its own `id`. The `id` you passed is the one that would have been used
+had it inserted, so a fresh id on every call is the normal shape:
+
+```ts
+await ctx.store.upsert('projectHours', {
+  teamId: 't-1', year: 2026, hours: 111,
+}, {
+  conflictColumns: ['teamId', 'year'],
+  update: ['hours'],
+})
+```
+
+The returned row carries the id of whichever row now holds those values. Compare
+values, not ids, if you need to know whether you inserted or updated.
+
+On MySQL and MariaDB this costs one extra guarantee, because the dialect cannot
+express the question. Postgres names its target — `ON CONFLICT (teamId, year)`
+fires on that index and nothing else — while `ON DUPLICATE KEY UPDATE` fires on
+whichever unique key the incoming row violates, which may not be the one you
+named. The store therefore checks afterwards that the row it reached carries your
+conflict values, and refuses the write if it does not: that row would have
+absorbed your values while your row was never written. The refusal names the
+differing column; the values go to the server log rather than into a sentence
+that may reach a user.
+
+A conflict column the database GENERATES cannot be checked this way — its value
+is never in the row you sent. The remaining columns are still compared; if a
+conflict key consists ENTIRELY of generated columns there is nothing to compare,
+and the upsert refuses rather than guessing.
+
+### Generated columns in a conflict key
+
+A partial-unique index on MySQL/MariaDB is usually a STORED generated column plus
+NULL-distinct semantics — the key constrains only the rows the expression marks.
+An upsert can conflict on such a key, but only on the path where the DATABASE
+evaluates the expression: the single-statement form, reached on MariaDB when the
+row is a complete INSERT row and `update` is a column list.
+
+The other path looks the row up by value first — it has to, because a function
+`update` needs the existing row to compute its patch — and the value of a
+generated column is not in the row you passed. There is no substitute for it, so
+that combination refuses and names the column rather than guessing at one.
+Postgres has no such split: `ON CONFLICT` names its index and the server
+evaluates the column.
+
 ## `insertIgnore` — keep existing on conflict
 
 For idempotent write patterns where you want to ensure a row exists

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/observability.md

@@ -513,7 +513,7 @@ others. The answer is `fleet`-scoped and says what it is missing:
 }
 ```
 
-Three properties are deliberate:
+Four properties are deliberate:
 
 - **A replica that has written nothing is `missing`, not absent.** Dropping it
   would make a partial answer look complete — the same unlabelled sample, one
@@ -521,9 +521,20 @@ Three properties are deliberate:
 - **A stale row is reported with its `ageMs`, not filtered out.** Removing it
   hides that the answer is partial; keeping it unmarked presents fiction as
   current.
+- **A row from a replica that is GONE is `departed`, not stale.** These are
+  different facts with different next steps: a stale row belongs to a replica
+  membership still lists, so it is running and has stopped refreshing — a fault,
+  and a reason for `complete: false`. A departed row belongs to a process that
+  exited; that is what a scale-down looks like, and it is not a reason for
+  anything. Conflating them made `complete` unreachable after any replica had
+  ever exited. They are still listed, with their age, because a reader who
+  cannot see them cannot tell a fleet that scaled down from a table being
+  written by something nobody is tracking.
 - **Mixed versions are named** in `completeness.versions` when the responders
   disagree. A rolling deploy spans two shapes, and averaging them silently is
-  wrong in a way nothing downstream can detect.
+  wrong in a way nothing downstream can detect. Departed replicas are excluded
+  from the tally — a process that has been dead for hours reporting a "version
+  split" is a line somebody acts on.
 
 **If there is no shared store, the request is refused with `501`** and a reason
 — never answered with this replica's own numbers. Handing back a sample to

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/auth-supabase.md

@@ -87,6 +87,27 @@ const resolve = composeAuthStrategies([
 | `defaultTenantId` | (none) | Fallback for single-tenant deployments. |
 | `scopesFromClaims` | (none) | Map claims (Supabase `role`, or an `app_metadata` permissions array) → `Subject.scopes`. |
 
+### `jwtSecret` may be a function — and should be, if you build an image
+
+`voltro build` imports `app.config.ts`, so anything the config CONSTRUCTS runs at
+build time. `jwtSecret: process.env.SUPABASE_JWT_SECRET` therefore makes an image
+build need a production credential for a bundle that will not contain one, and a
+placeholder is not an option — the framework ships no secret values, and an
+`ARG SUPABASE_JWT_SECRET` in a Dockerfile is exactly that.
+
+Pass a function instead:
+
+```ts
+supabaseStrategy({ jwtSecret: () => process.env.SUPABASE_JWT_SECRET })
+```
+
+The build never calls it. The BOOT does, once, through the strategy pass both
+`voltro dev` and `voltro serve` share — so an unset variable still refuses to
+start, with the strategy's id in the message. Deferring the read does not defer
+the failure to the first request: an auth strategy that cannot verify a token
+accepts nobody, and a process that started anyway serves a login that can never
+succeed.
+
 Algorithms follow the mode — JWKS pins `['RS256', 'ES256']`, `jwtSecret` pins `['HS256']`; the two are mutually exclusive, so there is no alg-confusion downgrade surface (an RS256 setup can't be tricked into accepting an HS256-forged token). `none` is never accepted.
 
 ## Environment variables

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/plugins/sentry.md

@@ -111,21 +111,104 @@ What it does:
 > ```
 > It's a no-op on the server (SSR) and without a DSN.
 
-The two halves are independent: the api plugin alone gives you server traces + errors; add the web half for the browser hop. For the FULL frontend→backend waterfall in Sentry, run **both** (`sentryPlugin({ traces:true })` on the api + `sentry: { dsn }` on the web app), with matching `release`.
+### Values the bundle cannot know
+
+Everything in that `sentry:` block is a literal frozen into the bundle. That is
+right for a DSN and a release, and wrong for `environment` as soon as one image
+serves more than one environment — one build job and several environment-bound
+deploy jobs is an ordinary pipeline, and a baked `environment` is then true for
+at most one of them. Leaving it out does not help: Sentry defaults a missing
+environment to `production`, so a wrong tag is what you get either way, and a
+wrong tag is worse than none because somebody acts on it.
+
+There is no runtime channel to read instead — public values are baked at build
+time by construction — so the value has to be computed where it is known. The
+entry is generated anyway, so it can call something:
+
+```ts
+// app.config.ts
+sentry: { dsn: '…', optionsFrom: 'src/sentryOptions.ts' }
+```
+
+```ts
+// src/sentryOptions.ts
+export default () => ({
+  environment: location.hostname.startsWith('stage-') ? 'staging' : 'production',
+})
+```
+
+The module's default export is called by the generated entry before
+`initSentryBrowser`, may be async, and its result is spread LAST — so it
+overrides the literals above it, which is the whole reason to reach for it.
+
+### Or from the public env
+
+Without an explicit option, the browser half reads
+`VOLTRO_PUBLIC_SENTRY_DSN`, `VOLTRO_PUBLIC_SENTRY_ENVIRONMENT` and
+`VOLTRO_PUBLIC_SENTRY_RELEASE` — the same shape the api half already has, where
+`sentryPlugin()` takes no arguments and resolves `SENTRY_*` from the environment.
+Declare them in your `defineEnv` contract and an app is finished without touching
+`app.config.ts`.
+
+**A public value must exist when the bundle is BUILT.** `voltro build` freezes the
+declared public subset into the bundle — that is what makes it readable in a
+browser — so these belong in the build (a Docker build-arg, a CI build step), not
+in deployment env. Setting one as a deployment variable deploys cleanly and does
+nothing; `voltro start` warns when it finds one, naming whether the bundle
+carries that key at all.
+
+The two halves are independent: the api plugin alone gives you server traces + errors; add the web half for the browser hop. For the full frontend→backend waterfall, run **both** — and both are on by default, so an app with the plugin on the api and `@voltro/plugin-sentry` as a dependency of the web app gets the whole trace from one `SENTRY_DSN` plus one `VOLTRO_PUBLIC_SENTRY_DSN`. Give both halves the same `release`.
+
+**Traces default to on, at `tracesSampleRate: 1.0`.** That is the coherent default rather than a generous one: the browser half already sampled every page load, navigation and rpc call at 1.0, so with the api half off each of those spans was emitted, paid for, and belonged to a trace with no server side — a browser hop hanging off nothing. The rate is named on the boot line (`sentry active traces=true tracesSampleRate=1`) so a first boot shows what it is about to send; lower it with `tracesSampleRate`, or set `traces: false` to keep errors and breadcrumbs only.
 
 ## Source maps (browser stack traces)
 
-The web bundle is minified, so browser errors arrive in Sentry with **minified** stack traces unless you upload source maps. The plugin does **not** upload them for you — it captures + correlates errors, but wiring the build to publish maps is a per-app build step (it needs your build output plus a Sentry auth token, neither of which the runtime plugin owns). Wire it once with Sentry's official tooling, keyed to the **same `release`** the plugin uses so the maps match the uploaded events:
+The web bundle is minified, so browser errors arrive in Sentry with **minified** stack traces unless the maps are uploaded. `voltro build` does it:
+
+```ts
+// app.config.ts
+web: {
+  sourcemaps: {
+    mode: 'hidden',
+    upload: { org: 'acme', project: 'web' },
+  },
+}
+```
 
 ```sh
-# after the web build, from the web app dir — uploads maps for one release
-pnpm add -D @sentry/cli
-SENTRY_AUTH_TOKEN=… npx sentry-cli sourcemaps upload \
-  --org <org> --project <project> \
-  --release "$SENTRY_RELEASE" ./dist
+# the build needs both; the deployment needs neither
+SENTRY_AUTH_TOKEN=sntrys_… SENTRY_RELEASE=1.4.2 voltro build
 ```
 
-Or add `@sentry/vite-plugin` to the web app's Vite config so the upload runs automatically on every production build. Either way, set `release` to the same value (e.g. the git SHA) on BOTH the api `sentryPlugin({ release })` and the web `sentry` field — the upload's `--release` must match or Sentry won't resolve the frames. Server stack traces are un-minified already (the api ships readable JS), so this is a browser-only concern.
+That emits the maps, uploads them through `@sentry/cli`, and then **removes them from the output**. Three things in that sentence are the reason it lives in the build rather than in your deploy script:
+
+- **The moment.** There is no seam in a Dockerfile between "the bundle exists" and "the image is built". There is one here.
+- **The release.** Sentry matches an artifact to an event by release, and the event's comes from `SENTRY_RELEASE` via `sentryPlugin`. Upload under a different value and no frame resolves — silently, because an upload that matched nothing looks exactly like one that worked. A build with an upload configured and no release **refuses** rather than uploading under nothing.
+- **The deletion.** A `.map` left in `dist` is your source, downloadable by anyone. "We delete it in the deploy step" is a promise a failing build breaks, so the removal is a `finally`: the maps go even when the upload fails, and a configured upload that did not happen fails the build.
+
+### Turning it on selectively
+
+`app.config.ts` is TypeScript, so the ordinary branch is the answer:
+
+```ts
+web: {
+  sourcemaps: process.env.CI
+    ? { mode: 'hidden', upload: { org: 'acme', project: 'web' } }
+    : 'hidden',
+}
+```
+
+`'hidden'` alone emits the maps and **keeps** them — right for reading a stack trace locally, and a leak in an image. Omit the field entirely and nothing is emitted, which is the default.
+
+`keep` defaults to "keep them only if nothing consumed them": `false` when `upload` is set, `true` when it is not. Set `keep: true` beside an upload when you want both.
+
+### The auth token is not a config field
+
+It is read from `SENTRY_AUTH_TOKEN` and there is deliberately no `authToken` option: `app.config.ts` is a committed file, and a token with `project:releases` scope can write to every project in the org. Give it to the **build** (a CI secret, a Docker build secret) — not to the deployment, since the upload happens while the bundle is being built.
+
+**Install `@sentry/cli` yourself: `pnpm add -D @sentry/cli` in the web app.** The framework depends on it nowhere, and that is a licence decision rather than a packaging one — it is FSL-1.1-MIT, which restricts competing commercial use, so it must not sit in the dependency graph of a package we publish. A build with an upload configured and the package missing **refuses and names the command**, rather than skipping the upload and leaving you to find out months later that no frame resolves.
+
+Server stack traces are un-minified already (the api ships readable JS), so this is a browser-only concern.
 
 ## Catching errors — what's automatic, what's manual
 

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
@@ -813,6 +843,23 @@ chat.regenerate()                            // re-run the last user prompt
 | `regenerate()` | Re-sends the last user prompt as a fresh turn; `undefined` if there is none. |
 | `sending` | `true` while a `send` is in flight. |
 
+**You do not need `@ai-sdk/react`.** `useAgentChat` covers the three things it is
+usually kept for:
+
+- **Tool calls** — each message carries `parts`, and a `tool` part has
+  `toolName`, `state`, `input` and `output`. Render from `parts` rather than
+  `content` and a tool call looks the same live and after a reload.
+- **Persistence** — the thread is a DB-backed reactive query, not client state.
+  Nothing is lost when the tab closes.
+- **Resumption** — for the same reason. Reopen the tab mid-turn and the
+  in-flight assistant message re-renders from the row that is still being
+  written; there is no transport to reconnect and no replay to arrange.
+
+So an app can drop `@ai-sdk/react` and `DefaultChatTransport` entirely. What
+`useAgentChat` deliberately does not do is manage a transport of its own — it
+composes the agent's synthesized `messages` subscription and `send` action, which
+is what makes the reload behaviour free rather than implemented.
+
 `threadId` is required — mint one per chat (a `useRef`'d uuid) and keep it stable
 across renders, since it is the subscription key for the whole thread. Render
 from `message.parts` (text / reasoning / tool / source / file) rather than
@@ -1547,6 +1594,18 @@ changes, so define it with `useCallback` or at module scope unless you want that
 And the bus is per api runtime — an app talking to several apis subscribes once
 per api name.
 
+**You do not need this hook to REPORT rpc failures.** Every event this bus emits
+is also published on the client error bus, so a reporter — the Sentry browser
+integration, or anything wired with `subscribeClientErrors` — already sees it,
+under `source: 'rpc.mutation' | 'rpc.action' | 'rpc.subscription'` with the rpc
+tag and `traceId` in `context`. This hook is for cross-cutting *policy* (redirect
+on `Unauthenticated`, toast on a network failure), not for telemetry; bridging
+the two by hand now reports twice.
+
+Everything is published, including a reconnect storm. If that is too loud for
+your reporter, gate it in the subscriber — which failures are worth an event is
+your policy, and the bus cannot hold one for every subscriber.
+
 This is the read side of failures that already happened on the wire. To push a
 client-side error the server never saw, call `reportClientError(error, context)`
 instead. Note also that a subscription failure *after* data arrived reaches only
@@ -1597,6 +1656,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 -->