@voltro/cli 0.59.0 → 0.61.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
 import { t as e } from "./loadEnv-D9nEOClM.js";
-import { t } from "./start-DNtIlBcn.js";
+import { t } from "./start-bqT4GRH0.js";
 export { e as loadDotEnv, t as runStartCommand };

package/dist/{updateCommand-Bw3mCUDT.js → updateCommand-B18ZQNFg.js}

@@ -1,4 +1,4 @@
-import { n as e, r as t, t as n } from "./codemodRunner-kNnh1I7_.js";
+import { n as e, r as t, t as n } from "./codemodRunner-Drb-H-jr.js";
 import { basename as r, dirname as i, join as a, relative as o, resolve as s } from "node:path";
 import { existsSync as c, readFileSync as l, readdirSync as u, statSync as d, writeFileSync as f } from "node:fs";
 import { totalmem as p } from "node:os";

package/dist/updateCommand-B4EgDD-m.js

@@ -0,0 +1,2 @@
+import { m as e, p as t } from "./updateCommand-B18ZQNFg.js";
+export { t as runApplyCodemods, e as runUpdateCommand };

package/dist/{webDev-CBN9KkyQ.js → webDev-CYjhmOTZ.js}

@@ -2556,7 +2556,7 @@ The wrapper is what carries \`match\`, and what lets \`voltro doctor\` report wh
 	return [
 		"",
 		"// Browser-side Sentry (frontend half of the deep integration). Errors +",
-		"// browser rpc spans flow to Sentry, sharing the server transactions' trace.",
+		"// page-owned rpc spans linked to their server traces flow to Sentry.",
 		n === void 0 ? `await initSentryBrowser(${JSON.stringify(r)})` : `await initSentryBrowser({ ...${JSON.stringify(r)}, ...(await __sentryOptions()) })`
 	];
 }, Fo = (e) => e.env ? ["import './env.public'"] : [], Io = (e) => {

package/dist/{webDev-Bzb8ZFus.js → webDev-CuG3Ged-.js}

@@ -1,2 +1,2 @@
-import { C as e, T as t, m as n } from "./webDev-CBN9KkyQ.js";
+import { C as e, T as t, m as n } from "./webDev-CYjhmOTZ.js";
 export { n as loadConfig, e as tryRunWebServe, t as walkPagesTree };

package/dist/{webhooksCommand-BPJQOGTe.js → webhooksCommand-Bs-HZ4wY.js}

@@ -222,7 +222,7 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev-Dff_pdik.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-kn9-7RXZ.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -892,6 +892,24 @@
         "title": "UiStrings gained a required `connectAccount` section",
         "kind": "manual"
       },
+      {
+        "version": "0.60.0",
+        "id": "0.60.0/01_declared_failures_are_not_incidents",
+        "title": "Sentry no longer reports declared failures by default",
+        "kind": "manual"
+      },
+      {
+        "version": "0.61.0",
+        "id": "0.61.0/01_rpc_errors_have_kinds",
+        "title": "`RpcError` now carries an explicit failure kind",
+        "kind": "manual"
+      },
+      {
+        "version": "0.61.0",
+        "id": "0.61.0/02_sentry_rpc_spans_join_page",
+        "title": "Sentry rpc spans now join the active browser transaction",
+        "kind": "manual"
+      },
       {
         "version": "0.7.0",
         "id": "0.7.0/01_row-filter-load-failure",
@@ -938,24 +956,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.59.0",
-    "@voltro/cache": "0.59.0",
-    "@voltro/client": "0.59.0",
-    "@voltro/content": "0.59.0",
-    "@voltro/data-transfer": "0.59.0",
-    "@voltro/database": "0.59.0",
-    "@voltro/env": "0.59.0",
-    "@voltro/kv": "0.59.0",
-    "@voltro/logger": "0.59.0",
-    "@voltro/plugin-auth": "0.59.0",
-    "@voltro/plugin-broadcast": "0.59.0",
-    "@voltro/plugin-mail": "0.59.0",
-    "@voltro/plugin-storage": "0.59.0",
-    "@voltro/plugin-webhooks": "0.59.0",
-    "@voltro/protocol": "0.59.0",
-    "@voltro/runtime": "0.59.0",
-    "@voltro/serverless": "0.59.0",
-    "@voltro/workflow": "0.59.0",
+    "@voltro/ai": "0.61.0",
+    "@voltro/cache": "0.61.0",
+    "@voltro/client": "0.61.0",
+    "@voltro/content": "0.61.0",
+    "@voltro/data-transfer": "0.61.0",
+    "@voltro/database": "0.61.0",
+    "@voltro/env": "0.61.0",
+    "@voltro/kv": "0.61.0",
+    "@voltro/logger": "0.61.0",
+    "@voltro/plugin-auth": "0.61.0",
+    "@voltro/plugin-broadcast": "0.61.0",
+    "@voltro/plugin-mail": "0.61.0",
+    "@voltro/plugin-storage": "0.61.0",
+    "@voltro/plugin-webhooks": "0.61.0",
+    "@voltro/protocol": "0.61.0",
+    "@voltro/runtime": "0.61.0",
+    "@voltro/serverless": "0.61.0",
+    "@voltro/workflow": "0.61.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.59.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.61.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. |
@@ -832,7 +832,7 @@ each plugin's own README.
 | row-history | `node_modules/@voltro/cli/templates/agent-docs/plugins/row-history.md` (or `node_modules/@voltro/plugin-row-history/README.md`) | Full row history + time-travel. audit() records who/when; row-history records what-changed-to-what — a value snapshot of every row on every write, with as-of queries. |
 | scim | `node_modules/@voltro/cli/templates/agent-docs/plugins/scim.md` (or `node_modules/@voltro/plugin-scim/README.md`) | SCIM 2.0 provisioning — Users + Groups REST endpoints so an enterprise IdP (Okta, Entra, OneLogin) can create / update / deactivate users in your app. |
 | search | `node_modules/@voltro/cli/templates/agent-docs/plugins/search.md` (or `node_modules/@voltro/plugin-search/README.md`) | Keep an external search index (Typesense / Meilisearch / Algolia) in sync with your tables via the ChangeEvent tap, query it tenant-scoped through a typed action + hook. |
-| sentry | `node_modules/@voltro/cli/templates/agent-docs/plugins/sentry.md` (or `node_modules/@voltro/plugin-sentry/README.md`) | Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces. |
+| sentry | `node_modules/@voltro/cli/templates/agent-docs/plugins/sentry.md` (or `node_modules/@voltro/plugin-sentry/README.md`) | Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and controlled performance traces. |
 | soft-delete | `node_modules/@voltro/cli/templates/agent-docs/plugins/soft-delete.md` (or `node_modules/@voltro/plugin-soft-delete/README.md`) | The softDelete() schema mixin — deletedAt / deletedBy columns, delete() redirected to an UPDATE, default reads filtered, hardDelete() bypass. |
 | sso-saml | `node_modules/@voltro/cli/templates/agent-docs/plugins/sso-saml.md` (or `node_modules/@voltro/plugin-sso-saml/README.md`) | Enterprise SAML 2.0 SSO — SP-initiated login, ACS assertion consumer, SP metadata. Signature verification via @node-saml/node-saml; framework session minting built in. |
 | storage | `node_modules/@voltro/cli/templates/agent-docs/plugins/storage.md` (or `node_modules/@voltro/plugin-storage/README.md`) | File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.59.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.61.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. |
@@ -92,7 +92,7 @@ each plugin's own README.
 | row-history | `node_modules/@voltro/cli/templates/agent-docs/plugins/row-history.md` (or `node_modules/@voltro/plugin-row-history/README.md`) | Full row history + time-travel. audit() records who/when; row-history records what-changed-to-what — a value snapshot of every row on every write, with as-of queries. |
 | scim | `node_modules/@voltro/cli/templates/agent-docs/plugins/scim.md` (or `node_modules/@voltro/plugin-scim/README.md`) | SCIM 2.0 provisioning — Users + Groups REST endpoints so an enterprise IdP (Okta, Entra, OneLogin) can create / update / deactivate users in your app. |
 | search | `node_modules/@voltro/cli/templates/agent-docs/plugins/search.md` (or `node_modules/@voltro/plugin-search/README.md`) | Keep an external search index (Typesense / Meilisearch / Algolia) in sync with your tables via the ChangeEvent tap, query it tenant-scoped through a typed action + hook. |
-| sentry | `node_modules/@voltro/cli/templates/agent-docs/plugins/sentry.md` (or `node_modules/@voltro/plugin-sentry/README.md`) | Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces. |
+| sentry | `node_modules/@voltro/cli/templates/agent-docs/plugins/sentry.md` (or `node_modules/@voltro/plugin-sentry/README.md`) | Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and controlled performance traces. |
 | soft-delete | `node_modules/@voltro/cli/templates/agent-docs/plugins/soft-delete.md` (or `node_modules/@voltro/plugin-soft-delete/README.md`) | The softDelete() schema mixin — deletedAt / deletedBy columns, delete() redirected to an UPDATE, default reads filtered, hardDelete() bypass. |
 | sso-saml | `node_modules/@voltro/cli/templates/agent-docs/plugins/sso-saml.md` (or `node_modules/@voltro/plugin-sso-saml/README.md`) | Enterprise SAML 2.0 SSO — SP-initiated login, ACS assertion consumer, SP metadata. Signature verification via @node-saml/node-saml; framework session minting built in. |
 | storage | `node_modules/@voltro/cli/templates/agent-docs/plugins/storage.md` (or `node_modules/@voltro/plugin-storage/README.md`) | File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser. |

package/templates/agent-docs/_manifest.json

@@ -660,7 +660,7 @@
     {
       "slug": "sentry",
       "title": "Sentry",
-      "description": "Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces.",
+      "description": "Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and controlled performance traces.",
       "pkg": "@voltro/plugin-sentry",
       "doc": "plugins/sentry.md",
       "module": "agent-docs/plugins/sentry.md"

package/templates/agent-docs/data.md

@@ -1220,13 +1220,21 @@ try {
 }
 ```
 
-**Trace id for debugging.** An error caught from `useMutation` / `useAction` carries a **non-enumerable `__voltroTraceId`** — the bridge to the server logs for that exact call:
+**Trace id for debugging.** An error caught from `useMutation` / `useAction`
+carries the **non-enumerable client-span id `__voltroTraceId`**:
 
 ```ts
 const traceId = (err as { __voltroTraceId?: string }).__voltroTraceId
-// → `voltro logs --trace <traceId>` to see the server-side span
+// If the server accepted the call: `voltro logs --trace <traceId>`
 ```
 
+For a declared handler error, the server necessarily accepted the call and the
+id joins to its span. For a transport error it may not: the connection can fail
+before the request arrived or after the handler ran but before its response
+returned. Use `kind` from
+[`useOnRpcError`](/docs/ui/client-utilities/use-on-rpc-error) for that distinction;
+the presence of the id alone proves only that the client span existed.
+
 `errorTag` lives in `@voltro/protocol` rather than in the client for a reason
 worth knowing before you decide where your own error handling goes: **`_tag` is a
 wire concept, and protocol owns the wire.** So a shared error handler in a package

package/templates/agent-docs/observability.md

@@ -213,6 +213,12 @@ Trace continuity is **automatic and on by default** in `voltro dev` — a buffer
 - **api → api is automatic over HTTP.** An action or handler that calls another api via the framework `HttpClient` sends a W3C `traceparent` header; an inbound `*.webhook.tsx` route (an incoming HTTP handler) **continues** the caller's trace. So frontend → api Y → api Z (via webhook / HTTP) is **one** trace.
 - **Every log line carries it.** Handlers stamp `fields.traceId` onto each log line they emit, so [`voltro logs --trace <id>`](/docs/observability/cli) returns the whole chain across hops, in order.
 
+The client span exists before the transport proves delivery. If a connection
+fails, its `traceId` can therefore have no matching server span — or the server
+may have completed the handler and lost only the response. In rpc-error policy,
+use [`RpcError.kind`](/docs/ui/client-utilities/use-on-rpc-error), never the mere
+presence of `traceId`, to distinguish transport failures from handler failures.
+
 ```
 client.mutation.placeOrder        traceId=4bf92f35…
 └─ mutation.placeOrder            traceId=4bf92f35…   (api Y, ctx.request.traceId)
@@ -259,7 +265,7 @@ This is the fastest way to answer "where did this error come from?" — far fast
 
 The same trace continuity flows to a vendor APM when you install a deep-observability plugin — no `OTEL_*` env. Each contributes an OTel span-processor to the framework's tracer via `contributeObservability`, so the vendor runs as a **consumer** of the existing tracer (the in-app Traces panel keeps working) and receives the identical spans:
 
-- [`@voltro/plugin-sentry`](/docs/plugins/sentry) — every mutation/query/action error becomes a Sentry issue correlated to its `trace_id` + `span_id`, with the request's log lines as breadcrumbs; opt-in performance traces (`traces: true`).
+- [`@voltro/plugin-sentry`](/docs/plugins/sentry) — every mutation/query/action error becomes a Sentry issue correlated to its `trace_id` + `span_id`, with the request's log lines as breadcrumbs; server performance traces are on by default (`traces: false` disables them). The browser integration keeps rpc markers inside the sampled page/navigation transaction and links each marker to its Effect/server trace.
 - [`@voltro/plugin-datadog`](/docs/plugins/datadog) — framework spans → the Datadog Agent's OTLP receiver (`traces: true`), plus log forwarding with `dd.trace_id` correlation.
 
 See [Observability › Routing traces to a vendor](/docs/observability/overview#routing-traces-to-a-vendor) for the contribution surface + the sampler caveat.

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

@@ -1,6 +1,6 @@
 # Sentry
 
-> Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces.
+> Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and controlled performance traces.
 
 
 
@@ -9,9 +9,9 @@
 <!-- source: en/plugins/sentry.md -->
 ## Sentry
 
-_Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces._
+_Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and controlled performance traces._
 
-`@voltro/plugin-sentry` is the deep Sentry integration: every mutation/query/action failure becomes a Sentry issue **correlated to the active distributed trace** (trace_id + span_id) and carrying the request's recent log lines as breadcrumbs. Opt into performance traces and the framework's spans flow to Sentry as transactions.
+`@voltro/plugin-sentry` is the deep Sentry integration: every mutation/query/action failure becomes a Sentry issue **correlated to the active distributed trace** (trace_id + span_id) and carrying the request's recent log lines as breadcrumbs. The framework's spans flow to Sentry as transactions by default.
 
 Uses the official `@sentry/node` SDK in **OpenTelemetry-consumer mode** — it consumes the framework's existing tracer (it never becomes the global provider), so the in-app [Traces dashboard](/docs/observability/distributed-tracing) stays intact.
 
@@ -29,7 +29,7 @@ export default {
       // dsn defaults to SENTRY_DSN; without a valid DSN the plugin is a no-op.
       environment: 'production',   // or SENTRY_ENVIRONMENT
       release: '1.4.2',            // or SENTRY_RELEASE
-      traces: true,                // route the framework's spans → Sentry (default off)
+      traces: true,                // route the framework's spans → Sentry (default on)
       tracesSampleRate: 1.0,
       profiling: true,             // continuous CPU profiler via @sentry/profiling-node
     }),
@@ -46,7 +46,7 @@ export default {
 | `dsn` | `string` | `SENTRY_DSN` env | No valid DSN → the plugin is inert (no interceptors registered). |
 | `environment` | `string` | `SENTRY_ENVIRONMENT` env | Sentry `environment` tag + `deployment.environment` resource attribute. |
 | `release` | `string` | `SENTRY_RELEASE` env | Release-health + source-map matching; also `service.version`. |
-| `traces` | `boolean` | `false` | Route the framework's OTel spans to Sentry as transactions. Off → errors + breadcrumbs only. |
+| `traces` | `boolean` | `true` | Route the framework's OTel spans to Sentry as transactions. Off → errors + breadcrumbs only. |
 | `tracesSampleRate` | `number` | `1.0` | Applied by the Sentry client (not a tracer sampler). Only relevant with `traces`. |
 | `profiling` | `boolean` | `false` | Continuous CPU profiler via `@sentry/profiling-node` (lazy; warns if not installed). |
 | `profilesSampleRate` | `number` | `1.0` | Only relevant with `profiling`. |
@@ -73,15 +73,15 @@ This guarantees the error links to its trace in Sentry **regardless** of the Eff
 
 The framework log sink feeds a bounded **per-trace** ring (capped per-trace + LRU + TTL), keyed on each log line's `traceId`. On an error the trace's breadcrumbs are attached to the event; traces that never error are reaped by the TTL. So a Sentry issue shows the exact log lines leading up to it — for that request only.
 
-## Traces (opt-in `traces:true`)
+## Server traces
 
 The plugin contributes a `SentrySpanProcessor` to the framework's tracer (via the plugin observability surface — see [Observability › Routing traces to a vendor](/docs/observability/overview#routing-traces-to-a-vendor)). Every framework span becomes a Sentry transaction, sharing the same trace id the errors carry — so in Sentry you land on an error inside its full distributed trace.
 
 We deliberately do **not** install a `SentrySampler` as the tracer's sampler: that would gate recording for the WHOLE tracer and blind the framework's own in-app Traces buffer. The framework keeps its always-on sampler; `tracesSampleRate` is applied by the Sentry client.
 
-## Full-stack — browser → backend in ONE Sentry trace
+## Correlating the browser page with server traces
 
-The plugin ships a browser half at `@voltro/plugin-sentry/web` so a click in the UI and the server work it triggers appear as **one trace** in Sentry. Turn it on in the web app's `app.config.ts`:
+The plugin ships a browser half at `@voltro/plugin-sentry/web`. It records one page-load or navigation transaction with rpc child spans, while each rpc child links to the Effect trace continued by the server. This avoids a transaction and network envelope per rpc call without losing the connection between browser and server work. Turn it on in the web app's `app.config.ts`:
 
 ```ts
 // apps/web/app.config.ts
@@ -94,6 +94,8 @@ export default {
     environment: 'production',
     release: '1.4.2',          // MUST match the api's `release` for unified release health
     tracesSampleRate: 1.0,
+    browserTracing: true,
+    rpcSpans: true,
   },
 }
 ```
@@ -102,7 +104,22 @@ The framework's generated entry calls `initSentryBrowser()` before mount (no cod
 
 What it does:
 - **Inits `@sentry/react`** with `browserTracingIntegration` — page loads + client navigations become Sentry transactions, and unhandled errors / promise rejections are captured by the SDK's default global handlers.
-- **Unifies the trace.** Every framework rpc call (`useMutation`/`useSubscription`/`useAction`) already wraps itself in an Effect client span and propagates that span's W3C `traceId`+`spanId` to the api (the api's `sentryPlugin({ traces:true })` turns the server spans into Sentry transactions under that same trace id). The browser half subscribes to the framework's client-trace bus and emits a browser-side Sentry span into the **same** trace, parented at the client span — so Sentry's trace view shows the browser hop and the server transactions in one tree.
+- **Keeps rpc spans page-owned.** Every framework rpc call (`useMutation`/`useSubscription`/`useAction`) already wraps itself in an Effect client span and propagates that span's W3C `traceId`+`spanId` to the api. The browser half adds a child to the currently active page/navigation transaction and attaches the Effect/server trace as a span link. If no browser transaction is active, it emits no rpc root transaction.
+- **Honours sampling.** `tracesSampleRate` decides whether the page/navigation root is recorded; its rpc children inherit that decision. The bridge does not inject a sampled parent decision.
+
+Browser trace controls:
+
+| Option | Default | Effect |
+|---|---|---|
+| `tracesSampleRate` | `1.0` | Samples page-load/navigation transactions and therefore their rpc children. Error reporting is independent. |
+| `browserTracing` | `true` | Installs page-load/navigation instrumentation. `false` also defaults `rpcSpans` to off. |
+| `rpcSpans` | same as `browserTracing` | Adds rpc children to an active browser transaction. `false` keeps browser errors and page traces but removes the rpc bridge. Set it to `true` with `browserTracing:false` only if your app creates active Sentry transactions itself. |
+
+At browser boot the plugin prints the effective values, including the mode:
+
+```text
+[@voltro/plugin-sentry] browser active { tracesSampleRate: 1, browserTracing: true, rpcSpans: true, rpcSpanMode: 'page-child-with-server-link' }
+```
 
 > **Manual wiring** (no app.config field, e.g. an app that builds its own entry): call it yourself once at boot —
 > ```ts
@@ -157,9 +174,9 @@ 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`.
+The two halves are independent: the api plugin alone gives you server traces + errors; add the web half for page performance, browser errors, rpc markers, and links back to the server traces. Both tracing halves 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 server transactions plus one sampled browser transaction per page/navigation 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.
+**Traces default to on, at `tracesSampleRate: 1.0`.** That is explicit, not a production recommendation. Lower the rate independently on api and web to fit the trace budget. Set api `traces:false` to keep server errors and breadcrumbs only; set web `browserTracing:false` to keep browser error capture without automatic performance transactions; or use web `rpcSpans:false` to keep page performance while omitting rpc child spans.
 
 ## Source maps (every bundle, browser and server)
 
@@ -243,11 +260,97 @@ Two details worth knowing before the first upload:
   store, and it fails with `SSL peer certificate … unable to get local issuer
   certificate`. Add `ca-certificates` to the build stage.
 
-**What we have not measured:** how a given Sentry project resolves the uploaded
-artifacts end to end. `sentry-cli sourcemaps upload` matches on debug IDs it
-injects into the emitted JS, and the URL prefix is the older release-artifact
-fallback — which is why the prefix is set correctly per directory rather than
-left to one default, and why this paragraph is here instead of a claim.
+**Debug ids are what make a server frame resolve, and they need their own
+step.** `sentry-cli sourcemaps upload` does **not** write them — `inject` is a
+separate subcommand, and `upload` only uses ids that are already there, falling
+back to matching on the artifact NAME when they are not.
+
+That fallback cannot work for a server bundle: the artifact is named from
+`--url-prefix` (`~/chunk-ABC.js`) while the frame carries the absolute path the
+node process loaded (`/workspace/…/serveBundle/chunk-ABC.js`), and nothing
+rewrites either side. Measured downstream before this was fixed: 4300 artifacts
+uploaded, the release finalised, every frame still minified — nothing red, which
+is the failure this page's own warning describes.
+
+`voltro build` runs `inject` first now, so the ids are in both the shipped JS and
+the map before anything is uploaded. The URL prefix stays as the fallback for the
+browser bundle, whose frames really are URLs under `~/assets`.
+
+## The web server is a SECOND process — and it needs the DSN too
+
+A framework app runs two server processes. `voltro serve` is the api, where
+`sentryPlugin()` initialises the SDK through the plugin lifecycle. `voltro start`
+is the **web server** — SSR, loaders, ISR, the revalidation legs — and it has no
+plugin lifecycle at all.
+
+It now initialises Sentry itself when `SENTRY_DSN` is set:
+
+```sh
+SENTRY_DSN=… SENTRY_ENVIRONMENT=production SENTRY_RELEASE=1.4.2 voltro start
+```
+
+```
+{"level":"info","msg":"sentry active","environment":"production","release":"1.4.2","traces":false,"profiling":false,"process":"web"}
+```
+
+Same line and same field names as the api half, from the same function — one
+vocabulary across both pods, plus `process` so a collector can tell them apart.
+
+**Why this was a hole rather than a missing log line.** An SSR shell throw is
+caught, logged, and answered with a 500. No browser ever renders it, so the
+client-side ErrorBoundary bridge below cannot see it either: the error existed
+only in the pod's stdout. Both ends of the integration worked and the middle was
+dark.
+
+Three things to know:
+
+- **`@voltro/plugin-sentry` must be installed in the WEB app**, not only the api
+  — the web server resolves the shared init from it. With a DSN set and the
+  package missing, the boot says so and names the command; it does not fail.
+- **`traces` is `false` here, deliberately.** The api half contributes a span
+  processor to the framework's tracer. The web server has no tracer, so
+  initialising with tracing on would put `traces: true` in a boot line while
+  nothing produces a span.
+- **No DSN is silent.** On the api side `sentryPlugin()` in your config is a
+  declaration, so an inert one is worth a warning. Here there is no declaration
+  to contradict, and a line about an integration you did not ask for is noise.
+
+**Re-run `voltro build` after upgrading.** Production `voltro start` loads the
+app's precompiled start bundle, so the web half picks this up when that bundle
+is rebuilt — not from the framework version alone.
+
+## What reaches Sentry — a declared failure does not
+
+A procedure's `error:` union is a **contract**. Somebody wrote the outcome down,
+the client gets it typed and branches on it, and it describes a state of the
+world: `AccessDeniedError` on a team you are not a member of is the system
+working. A **defect** is the opposite — nobody foresaw it. Sentry is built for
+the second.
+
+So a cause that carries only declared failures is **not** reported:
+
+```ts
+sentryPlugin()                              // captureFailures: false — the default
+sentryPlugin({ captureFailures: true })     // report them again
+sentryPlugin({ captureFailures: (e) => (e as { _tag?: string })._tag === 'PaymentDeclined' })
+```
+
+- **Defects are always reported**, including a defect that arrived beside a
+  failure — the rule is failures-*only*, so one cannot hide the other.
+- **Both halves take the option.** A rejected call is an rpc error on the client
+  too, so `initSentryBrowser({ captureFailures })` applies the same rule to
+  `rpc.*` events that carry a `_tag`. Set them together, or the api goes quiet
+  while the browser keeps filing the same rejection.
+- **Route render failures and `reportClientError` are never filtered.** Nobody
+  declared those, which is the whole distinction.
+- **The boot line names it** — `sentry active … captureFailures=false` — because
+  a default the framework picks for you is one nobody finds again.
+
+Why the default is off: an issue list that fills with the expected is one nobody
+reads. Every invalid form value, every click on a resource without access and
+every call on a deleted row was a `level: error` issue. If Sentry is where you
+see errors at all, `captureFailures: true` is the one-line answer and it is a
+reasonable choice.
 
 ## Catching errors — what's automatic, what's manual
 
@@ -257,7 +360,8 @@ Once the two halves are wired, most errors are captured **with no per-call code*
 |---|---|---|
 | rpc handler throw (mutation/query/action) | ✅ auto | server interceptor → Sentry, trace-correlated + breadcrumbs |
 | Unhandled browser error / promise rejection | ✅ auto | `@sentry/react` global handlers (after `initSentryBrowser`) |
-| **React render error** (any page, incl. catch-all `[...slug]`, `error.tsx` boundary) | ✅ auto | the framework's route ErrorBoundary publishes to a client-error bus → the Sentry web bridge captures it. React swallows boundary-caught errors before `window.onerror`, so this bridge is what makes them reach Sentry — tagged with the route + component stack. |
+| **React render error, in the BROWSER** (any page, incl. catch-all `[...slug]`, `error.tsx` boundary) | ✅ auto | the framework's route ErrorBoundary publishes to a client-error bus → the Sentry web bridge captures it. React swallows boundary-caught errors before `window.onerror`, so this bridge is what makes them reach Sentry — tagged with the route + component stack. |
+| **React render error, during SSR** — six sites: `ssr-shell`, `spa-layout-shell`, `render` (incl. a loader throw), `not-found-render`, `ppr-holes`, `swr-refresh` | ✅ auto, from the WEB server | a different process and a different path: the render never reaches a browser, so the row above cannot cover it. Captured by the web server's own Sentry (see the section above), tagged `voltro.process=web` and `voltro.stage`. The last three are `warn`-level — the request still serves something — and are reported anyway: quieter is not less real, and nothing else can see them. Needs `SENTRY_DSN` on the **web** deployment. |
 | **Loader failure** (page/layout `loader` reject) | ✅ auto | same route bus path |
 | Manual try/catch (event handler, async effect, anywhere) | ✋ one call | `reportClientError(error, context?)` |
 | **Every other server primitive** — REST route (`defineRestRoute`), aggregate, subscriber, schedule, workflow, webhook, startup | ✅ auto | each primitive's error path publishes to the framework's server-error bus → the plugin captures it, tagged `voltro.errorSource` + `voltro.name` (+ traceId for workflows) |

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

@@ -1194,10 +1194,20 @@ const { status, reportSuccess } = useConnectionStatus('app')
 `status` is `'connected' | 'degraded' | 'offline'`. `offline` is browser-reported
 (`navigator.onLine` plus its `online` / `offline` events) — reliable for "the
 network is gone", and it wins over `degraded`. `degraded` means an rpc on that
-api failed and nothing has succeeded since; it is real evidence, not a guess.
-Coming back online clears the failure count, since failures counted during an
-offline window *are* that window. `reportSuccess()` clears it eagerly from a
-place that knows a call went through.
+api failed with `kind: 'transport'` and no later call has proved the server
+reachable. Declared handler errors do **not** colour the connection; if already
+degraded, a handler reply clears it because the server demonstrably answered.
+Local client and unknown failures leave the connection state unchanged. Any rpc
+success also clears the failure count automatically. Coming back online clears
+it too, since failures counted during an offline window *are* that window.
+`reportSuccess()` remains the explicit escape hatch for another signal that
+proves a round trip succeeded.
+
+Use this hook to **render aggregate connection state**. To classify the failure
+that is firing right now — for example, to avoid a data-error toast in the same
+tick the socket drops — branch on `event.kind` inside
+[`useOnRpcError`](/docs/ui/client-utilities/use-on-rpc-error). React state updates
+after the event and therefore cannot classify that event retroactively.
 
 Also returned: `online`, `failureCount`, `lastFailureAt`. There is deliberately
 no polling ping — the framework does not call the server just to colour an
@@ -1578,16 +1588,34 @@ import { useOnRpcError } from '@voltro/client'
 import { errorTag } from '@voltro/protocol'
 
 useOnRpcError('app', useCallback((e) => {
+  if (e.kind === 'transport') {
+    showConnectionLost()
+    return
+  }
   if (errorTag(e.error) === 'Unauthenticated') redirectToSignIn()
 }, []))
 ```
 
-The event is `{ source, tag, error, traceId? }`. `source` is
+The event is `{ source, tag, error, kind, traceId? }`. `source` is
 `'mutation' | 'action' | 'subscription'`, so both unary calls and stream
 failures arrive here. `error` is the raw value — a `Schema.TaggedError`, a plain
 `Error`, or anything else that was thrown; `errorTag(err)` reads `_tag` off
-tagged errors and returns `undefined` otherwise. `traceId` is the same id the
-server logged, so a handler can point at `voltro logs --trace <id>`.
+tagged errors and returns `undefined` otherwise.
+
+`kind` is `'transport' | 'handler' | 'client' | 'unknown'`:
+
+- `transport` — @effect/rpc could not complete the exchange. Use this branch for
+  connection banners and to suppress misleading data-error toasts.
+- `handler` — the rpc returned a declared failure, such as `Unauthenticated`.
+- `client` — framework work around the call failed locally.
+- `unknown` — a combined or opaque operation could not be classified honestly.
+
+`traceId` identifies the **client call span**. When the server accepted the
+request, it propagates the same id and `voltro logs --trace <id>` can join the
+call to server logs. A transport error can happen before the server saw the
+request, or after it handled the request but before the response returned, so a
+`traceId` on `kind: 'transport'` is not proof that server logs exist. For the
+same reason the event deliberately has no `reachedServer` boolean.
 
 Two things to know. The hook re-subscribes whenever the listener **reference**
 changes, so define it with `useCallback` or at module scope unless you want that.
@@ -1598,9 +1626,9 @@ per api name.
 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.
+tag, `rpcErrorKind`, and optional `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

package/templates/agent-docs/whats-new.md

@@ -1,4 +1,4 @@
-# What's new in 0.59.0
+# What's new in 0.61.0
 
 Read this FIRST when a task touches an area you have not worked in recently.
 It is the cheapest way to notice that the framework grew the thing you were
@@ -9,51 +9,21 @@ BREAKING entries name a codemod; run `voltro update` to apply it.
 
 ### ⚠ BREAKING
 
-- **@voltro/cli** — **`web.sourcemaps` moved to the top level of `app.config.ts`, and now covers every bundle the build minifies.**
+- **@voltro/client, @voltro/web, @voltro/cli** — `RpcError.kind` now distinguishes transport, handler, client, and unknown failures; manually emitted events must add the field, while `useConnectionStatus` now degrades only for transport failures and clears on the next rpc success.
 
-  It reached exactly one of them before: the vite CLIENT build. `voltro build` minifies four — the browser bundle, the SSR bundle, the `voltro start` bundle, and for an api app the precompiled entry plus the serve bundle that `voltro serve` actually runs — and none of the other three had a `sourcemap` option or a config path that could ask for one. `keepNames` rescues the identifiers that are read as strings and nothing else, so a frame out of the artefact production runs read `at Qo (serveEntry.js:236:76405)`.
+  **`voltro update` carries you across this** — codemod `0.61.0/01_rpc_errors_have_kinds`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.61.0).
+- **@voltro/plugin-sentry, @voltro/cli** — Browser RPC spans now join the active page/navigation transaction and link to the Effect/server trace instead of creating one root transaction per call; `tracesSampleRate`, `browserTracing`, and the new `rpcSpans` switch control the resulting browser trace volume.
 
-  The docs closed that hole with a sentence instead of a field: *server stack traces are un-minified already*. The built file says otherwise, and the server half is where it costs most — a schedule, a workflow step, a subscriber or a REST route has no browser caller whose frame could stand in for it.
+  **`voltro update` carries you across this** — codemod `0.61.0/02_sentry_rpc_spans_join_page`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.61.0).
 
-  A second field (`api.sourcemaps`) would have made the same mistake twice. "Do I want resolvable frames from this app" has one answer; how many bundles the build happens to emit is not the caller's business.
-
-  Three details that come with it:
-
-  - **The old spelling is REFUSED, not ignored.** A moved option that is silently dropped goes green, stops emitting maps, and is found by someone reading an unresolvable frame months later. - **Each output directory uploads under the prefix that matches how its files are named** — `~/assets` for the browser bundle, `~/` for the bundles a node process loaded. One prefix across both is wrong for one of them. - **The upload and sweep run at every exit of the build**, not after the client bundle. Sweeping there would have deleted the client maps before the server ones existed, leaving those neither uploaded nor deleted.
-
-  `minifiedBundlesCarryMaps.test.ts` asserts the property over the SET: every bundler options object in the CLI that turns minification on must also decide `sourcemap`. That is what was missing — not one option, three, because nothing was watching the class.
-
-  **`voltro update` carries you across this** — codemod `0.59.0/01_sourcemaps_moved_to_the_top_level`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.59.0).
-- **@voltro/ai** — **Speech has a cost path, and a built-in provider name can be taken over.**
-
-  Three changes, one thread: the speech seam existed and nothing could reach it.
-
-  **`registerSpeechProvider(name, provider, { replaceBuiltin: true })`.** Refusing `mock` / `openai` / `gateway` / `anthropic` outright was wrong, and the case that shows it is one the refusal could not see: a provider name is not always an alias the app chooses. `openai` is the segment the gateway puts in its model ids, so it is what a stored catalog's rows carry and what a picker submits — an app told to pick another name cannot, without rewriting persisted rows and live sessions. It keeps its own dispatch instead, for every provider rather than the colliding one. What the refusal protected is kept by putting the intent in the call.
-
-  **Registered providers resolve BEFORE built-ins.** The dispatch decided from a hard-coded list of built-in names, so without this the flag would let you register `openai` and never route to it — declared, documented, wired at zero call sites.
-
-  **`MeteredUsage` — a tally in characters or seconds.** Every speech vendor meters one of those; none meters tokens. A ledger that only knew tokens could not hold a speech call at all, so speech spend was not un-priced, it was *absent*. The token shape is untouched (it is what the AI SDK returns); the new shape is separate rather than a unit tacked onto `AiUsage`, because writing a character count into a field called `inputTokens` puts a lie in a row someone reads later.
-
-  `_voltro_ai_usage` gains a `unit` column, and `costSource` gains `'unpriced'`: a non-token unit with no supplied price is written with the real count and a zero cost rather than a fabricated one, since a per-1M-token rate applied to a character count produces a number indistinguishable from a real one. Sum the count columns grouped by `unit`, never across it.
-
-  BREAKING for a caller that had narrowed `CostBreakdown['costSource']` to two values or reads `estimateCostUsd`'s return positionally. No call site changes SHAPE — the token path takes the same arguments and returns the same numbers — but a narrowing is user-authored code, so this carries a `manual` codemod rather than `none`: nothing here can be transformed (whether the third member belongs in your union is your decision), and the reader who needs it is exactly the one a "touches no user-authored code" line would have sent away. It also names the query that does not fail but answers wrongly: summing `_voltro_ai_usage` counts ACROSS units now adds characters to tokens.
-
-  **`voltro update` carries you across this** — codemod `0.59.0/02_costsource_gained_unpriced`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.59.0).
-
-### Added
-
-- **@voltro/ai** — **`GatewayModelInfo.raw`** — the `/v1/models` entry exactly as it came over the wire, beside the normalised fields.
-
-  Normalising is the right default: the union of `tags`, `supported_parameters` and `modalities` is framework knowledge, and every app on the gateway was writing those forty lines differently. But normalising is lossy by construction, and the fields it drops are not decoration — a picker built on the vendor's own capability tags, a pricing display that shows a structure we have not normalised, `zdr` and `no_training` kept apart instead of folded into `dataPolicy`.
-
-  Without `raw`, such an app fetches the endpoint a second time and maintains a second parser of the same response. One field rather than three more normalised ones, because the alternative asks the same question again at every field the gateway adds.
+### Fixed
 
-  Absent on the injected-provider path, for the same reason `capabilities` is: that seam never saw a response, and an empty object would turn "no wire data" into the claim that the wire carried nothing.
+- **@voltro/cli** — **Six SSR failure sites report to Sentry, not three.**
 
-### Fixed
+  0.60.0 gave the web server its own Sentry and wired the three loud sites: the SSR shell throw, the SPA layout shell throw, and the general render error (which covers a loader throw). The docs said "shell throw, loader throw, PPR/SWR refresh" — and an enumeration in a claim is read as exhaustive.
 
-- **@voltro/cli** — **`@sentry/cli` 3.x loads.** The loader read one export spelling — `module.exports = SentryCli`, which is 2.x. 3.x ships `exports.SentryCli = SentryCli`, so `mod.default` is a namespace object rather than the class, and a build with a source-map upload configured stopped with *could not be loaded*.
+  The other three were `warn`-level and reported to nobody: a failed PPR hole pass, a failed background SWR refresh, and a `not-found.tsx` that throws while rendering. They are quieter because the request still serves something — stale HTML, an unfilled hole, a plain 404 — which says something about the REQUEST and nothing about who else could find out. The answer to that is nobody: none of them reaches a browser boundary, so the pod's stdout was the only record.
 
-  The framework cannot pin its way out of this: `@sentry/cli` is FSL-1.1-MIT, so it is not ours to depend on and the app installs it — which means `pnpm add -D @sentry/cli`, the command we ourselves print, resolves the latest. Reading one spelling turned our own documented instruction into a failing build.
+  They carry their own `voltro.stage` (`not-found-render`, `ppr-holes`, `swr-refresh`), so a quota-conscious project can drop them by stage without losing the three that fail the request.
 
-  All four positions are accepted now (both spellings, each of which `import()` presents twice), and the two failures are told apart: a package that resolved but had no readable constructor no longer says *install it*. That reading is what cost a pipeline — locally `require()` resolves and the binary is there, so nothing about the install looks wrong.
+  `webSentry.test.ts` now fails if a render-path `log.error`/`log.warn` gains no reporter beside it — the property, rather than the six call sites.