@voltro/cli 0.60.0 → 0.61.0

package/dist/startEntry.js

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

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

@@ -1,4 +1,4 @@
-import { n as e, r as t, t as n } from "./codemodRunner-ClUqkhvR.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.60.0",
+  "version": "0.61.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -898,6 +898,18 @@
         "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",
@@ -944,24 +956,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.60.0",
-    "@voltro/cache": "0.60.0",
-    "@voltro/client": "0.60.0",
-    "@voltro/content": "0.60.0",
-    "@voltro/data-transfer": "0.60.0",
-    "@voltro/database": "0.60.0",
-    "@voltro/env": "0.60.0",
-    "@voltro/kv": "0.60.0",
-    "@voltro/logger": "0.60.0",
-    "@voltro/plugin-auth": "0.60.0",
-    "@voltro/plugin-broadcast": "0.60.0",
-    "@voltro/plugin-mail": "0.60.0",
-    "@voltro/plugin-storage": "0.60.0",
-    "@voltro/plugin-webhooks": "0.60.0",
-    "@voltro/protocol": "0.60.0",
-    "@voltro/runtime": "0.60.0",
-    "@voltro/serverless": "0.60.0",
-    "@voltro/workflow": "0.60.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.60.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.60.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)
 
@@ -344,7 +361,7 @@ 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, 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** (shell throw, loader throw, PPR/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`. Needs `SENTRY_DSN` on the **web** deployment. |
+| **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.60.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,54 +9,21 @@ BREAKING entries name a codemod; run `voltro update` to apply it.
 
 ### ⚠ BREAKING
 
-- **@voltro/plugin-sentry** — **A declared failure no longer reaches Sentry by default, and the source-map upload now injects debug ids.** Two separate defects, both found by the same deployment on its first day of real server-side events.
+- **@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.
 
-  **1. The contract was being reported as an incident.** The rpc interceptor skipped only clean interrupts; everything else went to `captureException`. So a failure declared in a procedure's `error:` union — the thing the client gets typed and branches on — arrived as `level: error`, `handled: yes`. The first server-side issue a deployment ever received was a person clicking a team they are not a member of.
+  **`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.
 
-  Effect separates a failure from a defect, this framework leans on that split deliberately (a store refusal was made typed so an app could branch on it; an unlookupable conflict key was deliberately left a defect, because it is a broken call rather than a condition in the data), and a descriptor carries it in `error:`. Reporting both as an incident discarded that one layer up.
-
-  `shouldCapture` now skips a cause that is failures-ONLY. A defect is reported as before, including a defect that travelled beside a failure — the rule is failures-only rather than "any failure present" precisely so one cannot hide the other. `captureFailures: true` restores the old behaviour; a predicate keeps the ones that are signal.
-
-  **The browser half moved with it**, or the option would have been half-wired: a rejected call is an rpc error on the client too, published to the client error bus and captured by the browser bridge. `initSentryBrowser` takes the same option and applies it to `rpc.*` events carrying a `_tag`. Route render failures and `reportClientError` calls are never filtered — nobody declared those.
-
-  **2. `sentry-cli sourcemaps upload` does NOT write debug ids.** `inject` is a separate subcommand; `upload` only uses ids that are already present, and falls 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, and nothing rewrites either side.
-
-  Measured downstream: 4300 artifacts uploaded, release finalised, every frame still minified. Nothing was red — the exact shape this code's own header warns about, an upload that matched nothing looking like one that worked. The comment above the uploader asserted the injection happened, which made it a description standing where a check belonged.
-
-  `inject` now runs first, over the same directories, and `sourcemapDebugIds.test.ts` drives the real binary to assert an id lands in both the JS and the map. `--url-prefix` stays as the fallback for the browser bundle, whose frames really are URLs.
-
-  The boot line names the new setting (`sentry active … captureFailures=false`), because a default the framework picks for you is one nobody finds again.
-
-  **`voltro update` carries you across this** — codemod `0.60.0/01_declared_failures_are_not_incidents`. 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.60.0).
-
-### Added
-
-- **@voltro/cli, @voltro/plugin-sentry** — **The web server process now initialises Sentry and reports its own errors.**
-
-  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, so it had none.
-
-  That was not a cosmetic difference in boot output. A web pod legitimately logs less than an api pod, because it has no store, no rpc, no scheduler, no workflows and no plugins. What it also had was **no error reporting**: an SSR shell throw is caught, logged and answered with a 500, so no browser ever renders it and the client-side ErrorBoundary bridge cannot see it either. Both ends of the integration worked and the middle was dark — while the docs' "React render error ✅ auto" row, true of the client path, read as covering all of them.
-
-  Set `SENTRY_DSN` on the web deployment and the boot says `sentry active` with the same message and the same field names as the api half, from the same function — `initSentryServer` in `@voltro/plugin-sentry/server`, which the api plugin now calls too. One init, because a copy of `skipOpenTelemetrySetup`, the traces default, the overrides-first spread and the degrade-on-missing-SDK path would have drifted the moment either half gained a case.
-
-  Three deliberate asymmetries, each because the two processes are not the same thing:
-
-  - **`traces: false` on the web side.** The api contributes a span processor to the framework's tracer; the web server has no tracer at all, so tracing on would put `traces: true` in a boot line while nothing produces a span. - **No DSN is SILENT here.** On the api side `sentryPlugin()` is a declaration and an inert one contradicts it. There is no declaration here. - **`@voltro/plugin-sentry` must be installed in the WEB app.** With a DSN set and the package missing, the boot names the command rather than failing — monitoring must never be what stops a deploy.
-
-  Measured against a real production `voltro start`, both branches. Note that production `voltro start` loads the app's precompiled start bundle, so a web deployment picks this up when that bundle is rebuilt — the framework version alone is not enough.
+  **`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).
 
 ### Fixed
 
-- **@voltro/workflow, @voltro/runtime, @voltro/database, @voltro/cli, @voltro/plugin-sentry** — **Six raw writes removed from production log streams — and the guard that was supposed to catch them rewritten, because it was green for two independent reasons.**
-
-  A pod tail showed `[voltro:workflow] shard-lock coordination: row-based (dialect=mariadb, mode=row)` sitting between JSON records. `@voltro/logger` is what makes a line JSON in a pod and pretty on a TTY; a `process.stderr.write` bypasses that decision at exactly the place nobody looks, because a dev terminal renders both the same.
-
-  Fixed at the source: the workflow cluster layer (2), `rpcServer`'s computed-cache warning, the subscription outbox's and the RYW store's `warn`/`onError` defaults — those two are not fallbacks, the callers pass nothing, so the default IS the production path — and the migration file discovery's skip notice, which lands in the migrate job's stream.
+- **@voltro/cli** — **Six SSR failure sites report to Sentry, not three.**
 
-  **The guard is the part worth reading.** `prodLogDiscipline.test.ts` existed for this exact class and reported clean, for two reasons that had to be fixed separately:
+  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.
 
-  - Its file set was a hand-written list of five. A guard that opts files IN says nothing about any file added after it was written. - Its matcher was LINE-LOCAL, so `process.stderr.write(` on one line and the `` `[tag] `` on the next never matched — 4 of the 9 call sites in the repo are written that way, including one in a file that WAS on the list. The guard had been pointed straight at an offender and called it clean.
+  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.
 
-  It is opt-OUT now: every server-side package's source is scanned, exceptions carry a reason, and a second test fails if an exception's call site disappears — an allowlist entry for code that is gone reads as a rule with a hole in it.
+  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.
 
-  Verified against a real `voltro serve` under `NODE_ENV=production`: 35 records, zero framework lines that are not JSON.
+  `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.

package/templates/apps/api-ai/package.json

@@ -12,12 +12,12 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/ai": "0.60.0",
-    "@voltro/cli": "0.60.0",
-    "@voltro/database": "0.60.0",
-    "@voltro/env": "0.60.0",
-    "@voltro/protocol": "0.60.0",
-    "@voltro/runtime": "0.60.0",
+    "@voltro/ai": "0.61.0",
+    "@voltro/cli": "0.61.0",
+    "@voltro/database": "0.61.0",
+    "@voltro/env": "0.61.0",
+    "@voltro/protocol": "0.61.0",
+    "@voltro/runtime": "0.61.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {

package/templates/apps/api-auth/package.json

@@ -13,17 +13,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.60.0",
-    "@voltro/database": "0.60.0",
-    "@voltro/env": "0.60.0",
-    "@voltro/plugin-auth": "0.60.0",
-    "@voltro/protocol": "0.60.0",
-    "@voltro/runtime": "0.60.0",
-    "@voltro/sql-postgres": "0.60.0",
+    "@voltro/cli": "0.61.0",
+    "@voltro/database": "0.61.0",
+    "@voltro/env": "0.61.0",
+    "@voltro/plugin-auth": "0.61.0",
+    "@voltro/protocol": "0.61.0",
+    "@voltro/runtime": "0.61.0",
+    "@voltro/sql-postgres": "0.61.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.60.0",
+    "@voltro/testing": "0.61.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

package/templates/apps/api-backend/package.json

@@ -16,16 +16,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.60.0",
-    "@voltro/database": "0.60.0",
-    "@voltro/env": "0.60.0",
-    "@voltro/plugin-multitenancy": "0.60.0",
-    "@voltro/protocol": "0.60.0",
-    "@voltro/runtime": "0.60.0",
+    "@voltro/cli": "0.61.0",
+    "@voltro/database": "0.61.0",
+    "@voltro/env": "0.61.0",
+    "@voltro/plugin-multitenancy": "0.61.0",
+    "@voltro/protocol": "0.61.0",
+    "@voltro/runtime": "0.61.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.60.0",
+    "@voltro/testing": "0.61.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"

package/templates/apps/api-backend-deactivation/package.json

@@ -13,16 +13,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.60.0",
-    "@voltro/database": "0.60.0",
-    "@voltro/env": "0.60.0",
-    "@voltro/plugin-deactivation": "0.60.0",
-    "@voltro/protocol": "0.60.0",
-    "@voltro/runtime": "0.60.0",
+    "@voltro/cli": "0.61.0",
+    "@voltro/database": "0.61.0",
+    "@voltro/env": "0.61.0",
+    "@voltro/plugin-deactivation": "0.61.0",
+    "@voltro/protocol": "0.61.0",
+    "@voltro/runtime": "0.61.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.60.0",
+    "@voltro/testing": "0.61.0",
     "typescript": "^6.0.3",
     "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"