@voltro/plugin-sentry 0.59.0 → 0.61.0

package/CHANGELOG.md

@@ -39,6 +39,89 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.61.0] — 2026-08-31
+
+### ⚠ BREAKING
+
+- **@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.
+
+  **`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.
+
+  **`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/cli** — **Six SSR failure sites report to Sentry, not three.**
+
+  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.
+
+  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.
+
+  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.
+
+  `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.
+
+---
+
+## [0.60.0] — 2026-08-31
+
+### ⚠ 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.
+
+  **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.
+
+  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.
+
+### 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.
+
+  **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:
+
+  - 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.
+
+  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.
+
+  Verified against a real `voltro serve` under `NODE_ENV=production`: 35 records, zero framework lines that are not JSON.
+
+---
+
 ## [0.59.0] — 2026-08-30
 
 ### ⚠ BREAKING

package/README.md

@@ -2,7 +2,7 @@
 
 # @voltro/plugin-sentry
 
-**Deep Sentry integration — error tracking correlated to the distributed trace, breadcrumbs from the framework log sink, and (opt-in) performance traces routed from the framework's OTel tracer via @sentry/node in OTel-consumer mode. Errors carry the active trace_id + span_id + the request's recent log lines.**
+**Deep Sentry integration — trace-correlated error tracking, breadcrumbs from the framework log sink, page-owned browser performance spans, and server traces routed from the framework's OTel tracer via @sentry/node in OTel-consumer mode.**
 
 [📖 Documentation](https://docs.voltro.dev/docs/plugins/sentry) · [voltro.dev](https://voltro.dev) · [Voltro Cloud](https://voltro.cloud)
 

package/dist/index.d.ts

@@ -35,7 +35,7 @@ declare interface CaptureContext {
     readonly spanId?: string;
 }
 
-export declare const captureToSentry: (sentry: SentryLike, cause: Cause.Cause<unknown>, ctx: CaptureContext, breadcrumbs: ReadonlyArray<Breadcrumb>) => void;
+export declare const captureToSentry: (sentry: SentryLike, cause: Cause.Cause<unknown>, ctx: CaptureContext, breadcrumbs: ReadonlyArray<Breadcrumb>, captureFailures?: boolean | ((error: unknown) => boolean)) => void;
 
 /** Unwrap an Effect `Cause` to the underlying error value (Error | tagged
  *  error | defect). `Cause.squash` returns the most informative throwable. */
@@ -92,19 +92,37 @@ export declare interface SentryPluginOptions {
     /**
      * Route the framework's OTel spans to Sentry as transactions. Default **true**.
      *
-     * It was `false`, and that made the pair's default the worst of the three
-     * available. The BROWSER half defaults `tracesSampleRate: 1.0` with
-     * `browserTracing` on, so page loads, navigations and every rpc call already
-     * become spans without anybody asking. With the server side off, each of those
-     * spans is emitted and paid for, carries a `traceId` the api also logged, and
-     * belongs to a trace with no server half — a browser hop hanging off nothing.
-     * Both-off would at least be coherent; both-on is what the two halves were
-     * built for.
-     *
-     * `false` turns them off and still leaves errors + breadcrumbs, which is the
-     * whole of the plugin for an app with no trace budget.
+     * The browser half records page/navigation transactions and page-owned rpc
+     * child spans; those children link to the Effect/server trace. `false` turns
+     * server transactions off while leaving errors + breadcrumbs intact.
      */
     readonly traces?: boolean;
+    /**
+     * Whether a DECLARED failure reaches Sentry. **Default `false`.**
+     *
+     * 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 in is the system
+     * working. A DEFECT is the opposite — nobody foresaw it — and that is what
+     * Sentry is built for. Defects are always reported; this option is only about
+     * the other half.
+     *
+     * The default was `true` by omission rather than by decision, and it filled a
+     * deployment's issue list with `level: error` entries for every invalid form
+     * value, every click on a resource without access and every call on a deleted
+     * row. An issue list of expected things is one nobody reads.
+     *
+     * Set `true` to keep the old behaviour — worth it if Sentry is where you see
+     * errors at all. Or pass a predicate when only some of them are signal:
+     *
+     * ```ts
+     * sentryPlugin({ captureFailures: (e) => (e as { _tag?: string })._tag === 'PaymentDeclined' })
+     * ```
+     *
+     * A cause carrying a defect is reported whatever it travelled with, so this
+     * cannot hide one by accident.
+     */
+    readonly captureFailures?: boolean | ((error: unknown) => boolean);
     /** Continuous CPU profiling via @sentry/profiling-node. Default false. */
     readonly profiling?: boolean;
     /** Profile sample rate (0..1) when `profiling`. Default 1.0. */

package/dist/index.js

@@ -1,35 +1,23 @@
-import { Cause as e, Effect as t } from "effect";
-import { pluginEnv as n } from "@voltro/env";
-import { addSink as r } from "@voltro/logger";
-import { definePlugin as i, subscribeServerErrors as a } from "@voltro/protocol";
-//#region src/dsn.ts
-var o = (e) => {
-	if (!e) return null;
-	try {
-		let t = new URL(e), n = t.username, r = t.pathname.split("/").filter(Boolean), i = r[r.length - 1];
-		return !n || !i ? null : {
-			protocol: t.protocol.replace(/:$/, ""),
-			publicKey: n,
-			host: t.host,
-			projectId: i
-		};
-	} catch {
-		return null;
-	}
-}, s = {
+import { n as e, r as t, t as n } from "./server-DQn_uTTk.js";
+import { Cause as r, Effect as i } from "effect";
+import { pluginEnv as a } from "@voltro/env";
+import { addSink as o } from "@voltro/logger";
+import { definePlugin as s, subscribeServerErrors as c } from "@voltro/protocol";
+//#region src/breadcrumbs.ts
+var l = {
 	trace: "debug",
 	debug: "debug",
 	info: "info",
 	warn: "warning",
 	error: "error",
 	fatal: "fatal"
-}, c = (e) => ({
+}, u = (e) => ({
 	timestamp: e.ts.getTime() / 1e3,
-	level: s[e.level] ?? "info",
+	level: l[e.level] ?? "info",
 	...e.scope ? { category: e.scope } : {},
 	message: e.message,
 	...Object.keys(e.fields).length > 0 ? { data: { ...e.fields } } : {}
-}), l = (e = {}, t = () => Date.now()) => {
+}), d = (e = {}, t = () => Date.now()) => {
 	let n = e.maxPerTrace ?? 50, r = e.maxTraces ?? 1e3, i = e.ttlMs ?? 3e5, a = /* @__PURE__ */ new Map(), o = () => {
 		let e = t() - i;
 		for (let [t, n] of a) if (n.at < e) a.delete(t);
@@ -38,11 +26,11 @@ var o = (e) => {
 	return {
 		add(e, i) {
 			o();
-			let s = a.get(e), l = s ?? {
+			let s = a.get(e), c = s ?? {
 				at: t(),
 				crumbs: []
 			};
-			for (s && a.delete(e), l.at = t(), l.crumbs.push(c(i)), l.crumbs.length > n && l.crumbs.shift(), a.set(e, l); a.size > r;) {
+			for (s && a.delete(e), c.at = t(), c.crumbs.push(u(i)), c.crumbs.length > n && c.crumbs.shift(), a.set(e, c); a.size > r;) {
 				let e = a.keys().next().value;
 				if (e === void 0) break;
 				a.delete(e);
@@ -59,24 +47,35 @@ var o = (e) => {
 			return a.size;
 		}
 	};
-}, u = (t) => e.squash(t), d = (e, t, n = []) => {
+}, f = (e) => r.squash(e), p = (e, t, n = []) => {
 	e.withScope((r) => {
 		r.setTag("voltro.errorSource", t.source), t.name !== void 0 && r.setTag("voltro.name", t.name), t.traceId !== void 0 && r.setContext("trace", { trace_id: t.traceId }), t.fields !== void 0 && r.setContext("voltro", t.fields);
 		for (let e of n) r.addBreadcrumb(e);
 		e.captureException(t.error);
 	});
-}, f = (t, n, r, i) => {
-	if (e.isInterruptedOnly(n)) return;
-	let a = u(n);
-	t.withScope((e) => {
-		e.setContext("trace", {
-			trace_id: r.traceId,
-			...r.spanId === void 0 ? {} : { span_id: r.spanId }
-		}), e.setTag("rpc.tag", r.tag), e.setTag("rpc.kind", r.kind), e.setTag("subject.type", r.subject.type), r.subject.tenantId !== void 0 && r.subject.tenantId !== null && e.setTag("tenant.id", r.subject.tenantId);
-		for (let t of i) e.addBreadcrumb(t);
-		t.captureException(a);
+}, m = (e, t) => {
+	if (r.isInterruptedOnly(e)) return !1;
+	if (t === !0) return !0;
+	let n = [...r.failures(e)];
+	return [...r.defects(e)].length > 0 ? !0 : n.length === 0 || t === !1 ? !1 : n.some((e) => {
+		try {
+			return t(e);
+		} catch {
+			return !0;
+		}
+	});
+}, h = (e, t, n, r, i = !1) => {
+	if (!m(t, i)) return;
+	let a = f(t);
+	e.withScope((t) => {
+		t.setContext("trace", {
+			trace_id: n.traceId,
+			...n.spanId === void 0 ? {} : { span_id: n.spanId }
+		}), t.setTag("rpc.tag", n.tag), t.setTag("rpc.kind", n.kind), t.setTag("subject.type", n.subject.type), n.subject.tenantId !== void 0 && n.subject.tenantId !== null && t.setTag("tenant.id", n.subject.tenantId);
+		for (let e of r) t.addBreadcrumb(e);
+		e.captureException(a);
 	});
-}, p = n([
+}, g = a([
 	{
 		name: "SENTRY_DSN",
 		required: !1,
@@ -95,76 +94,61 @@ var o = (e) => {
 		secret: !1,
 		description: "Release identifier for Sentry release health + source maps."
 	}
-]), m = (e = {}) => {
-	let n = p.read("SENTRY_DSN", e.dsn), s = o(n), c = e.name ? `@voltro/plugin-sentry#${e.name}` : "@voltro/plugin-sentry";
-	if (!s) return i({
-		name: c,
+]), _ = (r = {}) => {
+	let a = g.read("SENTRY_DSN", r.dsn), l = t(a), u = r.name ? `@voltro/plugin-sentry#${r.name}` : "@voltro/plugin-sentry";
+	if (!l) return s({
+		name: u,
 		description: "Sentry error tracking (inactive — no valid SENTRY_DSN).",
-		onActivate: (e) => t.sync(() => e.logger.warn("sentry inactive — no valid DSN (set `dsn` or SENTRY_DSN)")),
-		onDeactivate: () => t.void
+		onActivate: (e) => i.sync(() => e.logger.warn("sentry inactive — no valid DSN (set `dsn` or SENTRY_DSN)")),
+		onDeactivate: () => i.void
 	});
-	let u = p.read("SENTRY_ENVIRONMENT", e.environment), m = p.read("SENTRY_RELEASE", e.release), h = e.tracesSampleRate ?? 1, g = e.traces ?? !0, _ = l({ maxPerTrace: e.maxBreadcrumbs ?? 50 }), v, y = (e, t) => {
-		if (v) try {
-			f(v, e, t, _.take(t.traceId));
+	let f = g.read("SENTRY_ENVIRONMENT", r.environment), m = g.read("SENTRY_RELEASE", r.release), _ = r.tracesSampleRate ?? 1, v = r.traces ?? !0, y = r.captureFailures ?? !1, b = d({ maxPerTrace: r.maxBreadcrumbs ?? 50 }), x, S = (e, t) => {
+		if (x) try {
+			h(x, e, t, b.take(t.traceId), y);
 		} catch {}
-	}, b = (e, n) => e.pipe(t.tapErrorCause((e) => t.sync(() => y(e, {
-		tag: n.tag,
-		kind: n.kind,
-		subject: n.subject,
-		traceId: n.traceId,
-		...n.spanId === void 0 ? {} : { spanId: n.spanId }
-	})))), x = [
+	}, C = (e, t) => e.pipe(i.tapErrorCause((e) => i.sync(() => S(e, {
+		tag: t.tag,
+		kind: t.kind,
+		subject: t.subject,
+		traceId: t.traceId,
+		...t.spanId === void 0 ? {} : { spanId: t.spanId }
+	})))), w = [
 		"rpc:intercept:mutation",
 		"rpc:intercept:query",
 		"rpc:intercept:action",
-		`network:outbound:${s.host}`
-	], S, C;
-	return i({
-		name: c,
-		description: "Deep Sentry integration — trace-correlated errors + breadcrumbs + (opt-in) performance traces.",
-		permissions: x,
-		declaredEnv: p.declared,
-		interceptMutation: b,
-		interceptQuery: b,
-		interceptAction: b,
+		`network:outbound:${l.host}`
+	], T, E;
+	return s({
+		name: u,
+		description: "Deep Sentry integration — trace-correlated errors, breadcrumbs, and controlled performance traces.",
+		permissions: w,
+		declaredEnv: g.declared,
+		interceptMutation: C,
+		interceptQuery: C,
+		interceptAction: C,
 		contributeObservability: async (t) => {
-			let r;
-			try {
-				r = await import("@sentry/node");
-			} catch {
-				t.logger.warn("sentry requested but @sentry/node is not installed — inactive");
-				return;
-			}
-			let i = [];
-			if (e.profiling) try {
-				let { nodeProfilingIntegration: e } = await import("@sentry/profiling-node");
-				i.push(e());
-			} catch {
-				t.logger.warn("sentry profiling requested but @sentry/profiling-node is not installed");
-			}
-			let { integrations: a, ...o } = e.init ?? {};
-			if (a && i.push(...a), r.init({
-				...o,
-				dsn: n,
-				skipOpenTelemetrySetup: !0,
-				tracesSampleRate: h,
-				...u ? { environment: u } : {},
-				...m ? { release: m } : {},
-				...e.profiling ? { profilesSampleRate: e.profilesSampleRate ?? 1 } : {},
-				...i.length > 0 ? { integrations: i } : {}
-			}), v = r, t.logger.info("sentry active", {
-				environment: u,
+			let i = {
+				dsn: a,
+				environment: f,
 				release: m,
-				traces: g,
-				profiling: !!e.profiling,
-				...g ? { tracesSampleRate: h } : {}
-			}), g) try {
+				tracesSampleRate: _,
+				traces: v,
+				profiling: r.profiling,
+				profilesSampleRate: r.profilesSampleRate,
+				init: r.init
+			}, o = await n(i, t.logger);
+			if (o === void 0) return;
+			let s = o.sdk;
+			if (o.client, x = s, t.logger.info("sentry active", {
+				...e(o, i),
+				captureFailures: typeof y == "function" ? "predicate" : y
+			}), v) try {
 				let { SentrySpanProcessor: e } = await import("@sentry/opentelemetry");
 				return {
 					spanProcessors: [new e()],
 					resourceAttributes: {
 						...m ? { "service.version": m } : {},
-						...u ? { "deployment.environment": u } : {}
+						...f ? { "deployment.environment": f } : {}
 					}
 				};
 			} catch {
@@ -172,18 +156,18 @@ var o = (e) => {
 				return;
 			}
 		},
-		onActivate: () => t.sync(() => {
-			S = r((e) => {
+		onActivate: () => i.sync(() => {
+			T = o((e) => {
 				let t = e.fields.traceId;
-				typeof t == "string" && t.length > 0 && _.add(t, e);
-			}), C = a((e) => {
-				if (v) try {
-					d(v, e, e.traceId ? _.take(e.traceId) : []);
+				typeof t == "string" && t.length > 0 && b.add(t, e);
+			}), E = c((e) => {
+				if (x) try {
+					p(x, e, e.traceId ? b.take(e.traceId) : []);
 				} catch {}
 			});
 		}),
-		onDeactivate: () => t.promise(async () => {
-			S?.(), S = void 0, C?.(), C = void 0;
+		onDeactivate: () => i.promise(async () => {
+			T?.(), T = void 0, E?.(), E = void 0;
 			try {
 				await (await import("@sentry/node")).close(2e3);
 			} catch {}
@@ -191,4 +175,4 @@ var o = (e) => {
 	});
 };
 //#endregion
-export { f as captureToSentry, u as causeToError, l as makeBreadcrumbRing, o as parseDsn, m as sentryPlugin, c as toBreadcrumb };
+export { h as captureToSentry, f as causeToError, d as makeBreadcrumbRing, t as parseDsn, _ as sentryPlugin, u as toBreadcrumb };

package/dist/server-DQn_uTTk.js

@@ -0,0 +1,57 @@
+//#region src/dsn.ts
+var e = (e) => {
+	if (!e) return null;
+	try {
+		let t = new URL(e), n = t.username, r = t.pathname.split("/").filter(Boolean), i = r[r.length - 1];
+		return !n || !i ? null : {
+			protocol: t.protocol.replace(/:$/, ""),
+			publicKey: n,
+			host: t.host,
+			projectId: i
+		};
+	} catch {
+		return null;
+	}
+}, t = async (t, n) => {
+	if (!e(t.dsn)) return;
+	let r;
+	try {
+		r = await import("@sentry/node");
+	} catch {
+		n.warn("sentry requested but @sentry/node is not installed — inactive");
+		return;
+	}
+	let i = [];
+	if (t.profiling) try {
+		let { nodeProfilingIntegration: e } = await import("@sentry/profiling-node");
+		i.push(e());
+	} catch {
+		n.warn("sentry profiling requested but @sentry/profiling-node is not installed");
+	}
+	let { integrations: a, ...o } = t.init ?? {};
+	Array.isArray(a) && i.push(...a);
+	let s = t.tracesSampleRate ?? 1, c = t.traces ?? !0, l = r.init({
+		...o,
+		dsn: t.dsn,
+		skipOpenTelemetrySetup: !0,
+		tracesSampleRate: s,
+		...t.environment ? { environment: t.environment } : {},
+		...t.release ? { release: t.release } : {},
+		...t.profiling ? { profilesSampleRate: t.profilesSampleRate ?? 1 } : {},
+		...i.length > 0 ? { integrations: i } : {}
+	});
+	return {
+		sdk: r,
+		client: l,
+		tracesEnabled: c,
+		tracesSampleRate: s
+	};
+}, n = (e, t) => ({
+	environment: t.environment,
+	release: t.release,
+	traces: e.tracesEnabled,
+	profiling: !!t.profiling,
+	...e.tracesEnabled ? { tracesSampleRate: e.tracesSampleRate } : {}
+});
+//#endregion
+export { n, e as r, t };

package/dist/server.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Initialise `@sentry/node`, or explain why not.
+ *
+ * Returns `undefined` for the two non-error outcomes — no DSN, or the SDK is
+ * not installed — because neither is a reason to fail a boot. The api half made
+ * that call first (an optional dependency CAN fail to install, and a monitoring
+ * integration must never be the thing that stops a deploy), and the web half
+ * inherits it rather than deciding again.
+ */
+export declare const initSentryServer: (options: SentryServerInitOptions, log: SentryServerLog) => Promise<SentryServer | undefined>;
+
+/**
+ * The fields the `sentry active` line carries.
+ *
+ * Shared so the two processes cannot describe the same state differently — the
+ * whole point of the change is that a reader tailing an api pod and a web pod
+ * sees one vocabulary.
+ */
+export declare const sentryActiveFields: (server: SentryServer, options: SentryServerInitOptions) => Record<string, unknown>;
+
+export declare interface SentryServer {
+    /** The initialised `@sentry/node` namespace. */
+    readonly sdk: {
+        readonly captureException: (error: unknown, hint?: unknown) => string;
+        readonly flush?: (timeout?: number) => Promise<boolean>;
+    };
+    /** Whatever `Sentry.init` returned — the client, on SDK versions that return
+     *  one. Passed through rather than re-fetched via `getClient()`, because the
+     *  two are not the same call on every version and the caller asked for the
+     *  init's answer. */
+    readonly client: unknown;
+    readonly tracesEnabled: boolean;
+    readonly tracesSampleRate: number;
+}
+
+/** What the caller must hand in — resolved from env by the caller, because the
+ *  two processes read their environment through different gates. */
+export declare interface SentryServerInitOptions {
+    readonly dsn: string | undefined;
+    readonly environment?: string | undefined;
+    readonly release?: string | undefined;
+    /** Default 1.0, matching the browser half. */
+    readonly tracesSampleRate?: number | undefined;
+    /** Default ON — see the plugin's `traces` option for why `false` made the
+     *  browser half's spans point at nothing. */
+    readonly traces?: boolean | undefined;
+    readonly profiling?: boolean | undefined;
+    readonly profilesSampleRate?: number | undefined;
+    /** User escape hatch, spread FIRST so plugin-managed keys stay authoritative. */
+    readonly init?: Record<string, unknown> | undefined;
+}
+
+export declare interface SentryServerLog {
+    readonly info: (message: string, fields?: Record<string, unknown>) => void;
+    readonly warn: (message: string, fields?: Record<string, unknown>) => void;
+}
+
+export { }

package/dist/server.js

@@ -0,0 +1,2 @@
+import { n as e, t } from "./server-DQn_uTTk.js";
+export { t as initSentryServer, e as sentryActiveFields };

package/dist/web.d.ts

@@ -20,21 +20,45 @@ export declare const closeSentryBrowser: () => void;
  *  server (SSR) and without a DSN. */
 export declare const initSentryBrowser: (options?: SentryBrowserOptions) => Promise<void>;
 
-/** Emit a browser-side Sentry span into the SAME trace as the server
- *  transaction the call will produce. */
+/**
+ * Is this client-side event a DECLARED failure?
+ *
+ * Two conditions, and both are needed. The source must be an `rpc.*` one — a
+ * route render throw or a manual `reportClientError` is nobody's declared
+ * outcome. And the value must carry a `_tag`: the framework's typed errors are
+ * `Schema.TaggedError` subclasses, so a decoded one has one, while a transport
+ * failure, an aborted socket or a forwarded defect does not.
+ *
+ * The rule is deliberately narrow. Anything it cannot positively identify as
+ * declared is reported, because the cost of the two mistakes is not symmetric:
+ * a noisy issue is read and dismissed, a missing one is never read.
+ */
+export declare const isDeclaredRpcFailure: (event: {
+    source: string;
+    error: unknown;
+}) => boolean;
+
+/** Add an rpc marker to the active page/navigation transaction and link it to
+ *  the Effect trace continued by the server. With no active browser parent,
+ *  `onlyIfParent` deliberately produces no recorded root transaction. */
 export declare const recordClientTraceSpan: (sentry: SentryBrowserLike, event: ClientTraceEvent) => void;
 
 export { reportClientError }
 
 export declare interface SentryBrowserLike {
-    continueTrace<T>(context: {
-        sentryTrace: string;
-        baggage?: string;
-    }, callback: () => T): T;
     startInactiveSpan(options: {
         name: string;
         op?: string;
+        onlyIfParent?: boolean;
         attributes?: Record<string, unknown>;
+        links?: ReadonlyArray<{
+            context: {
+                traceId: string;
+                spanId: string;
+                traceFlags: number;
+            };
+            attributes?: Record<string, string | number | boolean>;
+        }>;
     }): SentrySpanLike;
     withScope(callback: (scope: SentryBrowserScopeLike) => void): unknown;
     captureException(exception: unknown): unknown;
@@ -53,6 +77,25 @@ export declare interface SentryBrowserOptions {
     /** Instrument page loads + client navigations via `browserTracingIntegration`.
      *  Default true. */
     readonly browserTracing?: boolean;
+    /** Record rpc markers under the active page/navigation transaction and link
+     *  them to their server traces. Defaults to `browserTracing`; set `false` to
+     *  disable only this bridge while keeping browser error reporting. Set
+     *  `true` with `browserTracing:false` only when the app creates its own
+     *  active Sentry transactions. */
+    readonly rpcSpans?: boolean;
+    /**
+     * Whether a DECLARED failure that came back from an rpc call reaches Sentry.
+     * **Default `false`**, matching `sentryPlugin({ captureFailures })`.
+     *
+     * Both halves need it or neither works. The api stops reporting
+     * `AccessDeniedError` and the browser keeps filing the same rejection,
+     * because a rejected call is an rpc error on this side too — the option would
+     * be half-wired, and the issue list would look unchanged.
+     *
+     * Route render failures and explicit `reportClientError` calls are NEVER
+     * filtered by this: nobody declared them, which is the whole distinction.
+     */
+    readonly captureFailures?: boolean | ((error: unknown) => boolean);
 }
 
 declare interface SentryBrowserScopeLike {
@@ -66,8 +109,4 @@ declare interface SentrySpanLike {
     end(): void;
 }
 
-/** Build the `sentry-trace` header for a client trace event (sampled=1 — the
- *  framework records always-on; Sentry's client applies its own sample rate). */
-export declare const sentryTraceHeader: (event: ClientTraceEvent) => string;
-
 export { }

package/dist/web.js

@@ -5,44 +5,66 @@ var i = (e, t) => {
 	e.withScope((n) => {
 		n.setTag("voltro.errorSource", t.source), t.pathname && n.setTag("route.pathname", t.pathname), t.componentStack && n.setContext("react", { componentStack: t.componentStack }), t.context && n.setContext("voltro", t.context), e.captureException(t.error);
 	});
-}, a = (e) => `${e.traceId}-${e.spanId}-1`, o = (e, t) => {
-	e.continueTrace({ sentryTrace: a(t) }, () => {
-		e.startInactiveSpan({
-			name: `${t.source}.${t.tag}`,
-			op: `rpc.client.${t.source}`,
-			attributes: {
-				"rpc.tag": t.tag,
-				"voltro.source": t.source
-			}
-		}).end();
-	});
-}, s = (e) => {
+}, a = (e, t) => {
+	e.startInactiveSpan({
+		name: `${t.source}.${t.tag}`,
+		op: `rpc.client.${t.source}`,
+		onlyIfParent: !0,
+		attributes: {
+			"rpc.tag": t.tag,
+			"voltro.source": t.source
+		},
+		links: [{
+			context: {
+				traceId: t.traceId,
+				spanId: t.spanId,
+				traceFlags: 1
+			},
+			attributes: { "voltro.link.type": "rpc.server-trace" }
+		}]
+	}).end();
+}, o = (e) => e.source.startsWith("rpc.") && typeof e.error?._tag == "string", s = (e) => {
 	let t = r()[e];
 	return typeof t == "string" && t !== "" ? t : void 0;
 }, c, l, u = async (e = {}) => {
 	if (typeof window > "u") return;
 	let r = e.dsn ?? s("VOLTRO_PUBLIC_SENTRY_DSN");
 	if (!r) return;
-	let a = e.environment ?? s("VOLTRO_PUBLIC_SENTRY_ENVIRONMENT"), u = e.release ?? s("VOLTRO_PUBLIC_SENTRY_RELEASE"), d = await import("@sentry/react");
-	d.init({
+	let u = e.environment ?? s("VOLTRO_PUBLIC_SENTRY_ENVIRONMENT"), f = e.release ?? s("VOLTRO_PUBLIC_SENTRY_RELEASE"), p = e.tracesSampleRate ?? 1, m = e.browserTracing !== !1, h = e.rpcSpans ?? m, g = await import("@sentry/react");
+	g.init({
 		dsn: r,
-		tracesSampleRate: e.tracesSampleRate ?? 1,
-		...a ? { environment: a } : {},
-		...u ? { release: u } : {},
-		integrations: e.browserTracing === !1 ? [] : [d.browserTracingIntegration()]
+		tracesSampleRate: p,
+		...u ? { environment: u } : {},
+		...f ? { release: f } : {},
+		integrations: m ? [g.browserTracingIntegration()] : []
 	});
-	let f = d;
-	c?.(), c = n((e) => {
+	let _ = g;
+	c?.(), c = void 0, h && (c = n((e) => {
 		try {
-			o(f, e);
+			a(_, e);
 		} catch {}
-	}), l?.(), l = t((e) => {
+	})), l?.();
+	let v = e.captureFailures ?? !1;
+	l = t((e) => {
 		try {
-			i(f, e);
+			if (o(e) && !d(e.error, v)) return;
+			i(_, e);
 		} catch {}
+	}), console.info("[@voltro/plugin-sentry] browser active", {
+		tracesSampleRate: p,
+		browserTracing: m,
+		rpcSpans: h,
+		rpcSpanMode: h ? "page-child-with-server-link" : "off"
 	});
-}, d = () => {
+}, d = (e, t) => {
+	if (typeof t != "function") return t;
+	try {
+		return t(e);
+	} catch {
+		return !0;
+	}
+}, f = () => {
 	c?.(), c = void 0, l?.(), l = void 0;
 };
 //#endregion
-export { i as captureClientError, d as closeSentryBrowser, u as initSentryBrowser, o as recordClientTraceSpan, e as reportClientError, a as sentryTraceHeader };
+export { i as captureClientError, f as closeSentryBrowser, u as initSentryBrowser, o as isDeclaredRpcFailure, a as recordClientTraceSpan, e as reportClientError };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@voltro/plugin-sentry",
-  "version": "0.59.0",
-  "description": "Deep Sentry integration — error tracking correlated to the distributed trace, breadcrumbs from the framework log sink, and (opt-in) performance traces routed from the framework's OTel tracer via @sentry/node in OTel-consumer mode. Errors carry the active trace_id + span_id + the request's recent log lines.",
+  "version": "0.61.0",
+  "description": "Deep Sentry integration — error tracking correlated to distributed traces, breadcrumbs from the framework log sink, controlled browser performance spans, and server traces routed from the framework's OTel tracer via @sentry/node in OTel-consumer mode.",
   "keywords": [
     "voltro",
     "typescript",
@@ -23,6 +23,11 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
     "./web": {
       "types": "./dist/web.d.ts",
       "import": "./dist/web.js",
@@ -38,10 +43,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.59.0",
-    "@voltro/env": "0.59.0",
-    "@voltro/logger": "0.59.0",
-    "@voltro/protocol": "0.59.0"
+    "@voltro/client": "0.61.0",
+    "@voltro/env": "0.61.0",
+    "@voltro/logger": "0.61.0",
+    "@voltro/protocol": "0.61.0"
   },
   "optionalDependencies": {
     "@sentry/node": "^10.70.0",