@capxul/observability 4.20.0-beta.31 → 4.20.0-beta.32

package/README.md

@@ -34,6 +34,7 @@ naming events rather than producing them.
 
 ```text
 src/
+├── devtools.ts
 ├── engineering-delivery.ts
 ├── engineering.ts
 ├── index.ts
@@ -41,6 +42,7 @@ src/
 ├── telemetry-port.ts
 ├── __tests__/
 │   ├── engineering-delivery.test.ts
+│   ├── devtools.test.ts
 │   ├── engineering.test.ts
 │   ├── operations.test.ts
 │   ├── posthog-browser-privacy.test.ts
@@ -92,6 +94,18 @@ src/
 
 ## The required envelope (ADR-0020 A1 amendment)
 
+The `@capxul/observability/devtools` subpath exports `withDevTools(layer, url)` and
+`validateDevToolsUrl(url)` for local Effect inspection. An omitted URL keeps the
+original layer. An explicit local WebSocket URL adds the native Effect 4
+DevTools connection after the host's services and metric registry are built.
+The connection closes with the host scope. Local spans retain their original
+detail; existing remote exporters keep their own privacy policy. The local
+tracer does not mutate the remote exporter's span methods. Its optional protocol
+loads only when enabled. The separate entry stays out of Convex's static runtime graph.
+
+See [the development workflow](../../docs/canon/development-and-verification.md#local-effect-devtools)
+for the editor and agent collector commands.
+
 One PostHog project holds every environment, so `capxul_env` — not project
 isolation — is what keeps a production surface from reading dev traffic. It is
 REQUIRED on every catalog event, together with `producer`. Call sites do not

package/dist/devtools.d.mts

@@ -0,0 +1,7 @@
+import { Layer } from "effect";
+//#region src/devtools.d.ts
+/** Local inspection is an explicit host choice, independent of remote telemetry. */
+export declare function validateDevToolsUrl(value: string): string;
+/** Acquire after the host layer so traces and metrics use the same context. */
+export declare function withDevTools<R, E, I>(layer: Layer.Layer<R, E, I>, url: string | undefined): Layer.Layer<R, E, I>;
+//#endregion

package/dist/devtools.mjs

@@ -0,0 +1,72 @@
+import { Effect, Layer, Tracer } from "effect";
+//#region src/devtools.ts
+/** Local inspection is an explicit host choice, independent of remote telemetry. */
+function validateDevToolsUrl(value) {
+	const url = new URL(value);
+	if (!["ws:", "wss:"].includes(url.protocol) || ![
+		"localhost",
+		"127.0.0.1",
+		"[::1]",
+		"host.docker.internal"
+	].includes(url.hostname) || url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") throw new TypeError("devToolsUrl must be a local WebSocket URL without credentials");
+	return url.href;
+}
+function localSpan(delegate) {
+	const attributes = new Map(delegate.attributes);
+	let status = delegate.status;
+	return {
+		_tag: "Span",
+		name: delegate.name,
+		spanId: delegate.spanId,
+		traceId: delegate.traceId,
+		parent: delegate.parent,
+		annotations: delegate.annotations,
+		sampled: delegate.sampled,
+		kind: delegate.kind,
+		attributes,
+		get status() {
+			return status;
+		},
+		get links() {
+			return delegate.links;
+		},
+		attribute(key, value) {
+			attributes.set(key, value);
+			delegate.attribute(key, value);
+		},
+		event(name, time, values) {
+			delegate.event(name, time, values);
+		},
+		addLinks(links) {
+			delegate.addLinks(links);
+		},
+		end(endTime, exit) {
+			delegate.end(endTime, exit);
+			status = {
+				_tag: "Ended",
+				startTime: status.startTime,
+				endTime,
+				exit
+			};
+		}
+	};
+}
+/** Acquire after the host layer so traces and metrics use the same context. */
+function withDevTools(layer, url) {
+	if (url === void 0) return layer;
+	const endpoint = validateDevToolsUrl(url);
+	return Layer.unwrap(Effect.promise(async () => {
+		const [{ DevToolsClient }, { Socket }] = await Promise.all([import("effect/devtools"), import("effect/socket")]);
+		const client = DevToolsClient.layer.pipe(Layer.provide(Socket.layerWebSocket(endpoint)), Layer.provide(Socket.layerWebSocketConstructorGlobal));
+		return Layer.effect(Tracer.Tracer, Effect.gen(function* () {
+			const delegate = yield* Effect.tracer;
+			const mirror = Tracer.make({
+				span: (options) => localSpan(delegate.span(options)),
+				...delegate.context === void 0 ? {} : { context: delegate.context.bind(delegate) }
+			});
+			return yield* DevToolsClient.makeTracer.pipe(Effect.provideService(Tracer.Tracer, mirror));
+		})).pipe(Layer.provide(client), Layer.provideMerge(layer));
+	}));
+}
+//#endregion
+export { validateDevToolsUrl, withDevTools };

package/dist/engineering.mjs

@@ -1,4 +1,4 @@
-import { I as CLI_CAPABILITIES, L as CLI_COMMAND_NAMES, R as CLI_INVOCATION_KINDS, an as isCapxulOperation, cn as ORGANIZATION_SETUP_STATUSES, dn as isCredentialField, fn as CAPXUL_ERROR_CODES, ln as redactSecrets, pn as FAILURE_MODES, sn as ORGANIZATION_SETUP_REASONS, un as redactUrlSecrets } from "./src-L9SjUzWV.mjs";
+import { G as CLI_COMMAND_NAMES, K as CLI_INVOCATION_KINDS, W as CLI_CAPABILITIES, _n as redactSecrets, bn as CAPXUL_ERROR_CODES, gn as ORGANIZATION_SETUP_STATUSES, hn as ORGANIZATION_SETUP_REASONS, pn as isCapxulOperation, vn as redactUrlSecrets, xn as FAILURE_MODES, yn as isCredentialField } from "./src-BPQVVRCG.mjs";
 import { Cause, Clock, Context, Deferred, Duration, Effect, Exit, FiberSet, Layer, LogLevel, Logger, Metric, Option, References, Schedule, Stream, Tracer } from "effect";
 import { FetchHttpClient, Headers, HttpBody, HttpClient, HttpClientError, HttpClientResponse } from "effect/http";
 import { OtlpExporter, OtlpLogger, OtlpMetrics, OtlpSerialization, OtlpTracer } from "effect/observability";
@@ -75,6 +75,123 @@ const attributes = (input, limit = 32) => {
 };
 const terminalName = (name) => name === "cli.command.completed" || name === "cli.wallet.step" || CLI_COMMAND_NAMES.some((command) => name === `cli.command.${command}`);
 //#endregion
+//#region src/engineering/tracer.ts
+const failureText = (failure, key, limit, source) => {
+	if (failure === null || typeof failure !== "object") return void 0;
+	try {
+		let owner = failure;
+		let descriptor;
+		for (let depth = 0; owner !== null && depth < 4; depth += 1) {
+			descriptor = Object.getOwnPropertyDescriptor(owner, key);
+			if (descriptor !== void 0 || key !== "name") break;
+			owner = Object.getPrototypeOf(owner);
+		}
+		const value = descriptor?.value;
+		return typeof value === "string" || key === "code" && typeof value === "number" ? redactSecrets(String(value), source).slice(0, limit) : void 0;
+	} catch {
+		return;
+	}
+};
+const exportFailure = (failure, source) => {
+	const message = failureText(failure, "message", 2048, source) ?? (typeof failure === "string" ? redactSecrets(failure, source).slice(0, 2048) : "Engineering operation failed");
+	const code = failureText(failure, "code", 128);
+	const error = new Error((code === void 0 ? message : `${message} [code=${code}]`).slice(0, 2048));
+	error.name = failureText(failure, "_tag", 128) ?? failureText(failure, "name", 128) ?? "Error";
+	error.stack = failureText(failure, "stack", 8192, source) ?? `${error.name}: ${error.message}`;
+	return error;
+};
+const exportFailureExit = (cause, source) => Exit.failCause(Cause.fromReasons(cause.reasons.filter((reason) => !Cause.isInterruptReason(reason)).slice(0, 8).map((reason) => Cause.isFailReason(reason) ? Cause.makeFailReason(exportFailure(reason.error, source)) : Cause.makeDieReason(exportFailure(reason.defect, source)))));
+const BROWSER_KEEPALIVE_BYTES = 65536;
+let unfinishedBrowserExportBytes = 0;
+const hasBrowserDocument = () => typeof window !== "undefined" && typeof document !== "undefined";
+const browserExportClient = (client) => HttpClient.transform(client, (response, request) => Effect.acquireUseRelease(Effect.sync(() => {
+	const bytes = "contentLength" in request.body ? request.body.contentLength : void 0;
+	if (request.body._tag === "Stream" || request.body._tag === "FormData" || bytes === void 0 || !Number.isSafeInteger(bytes) || bytes < 0 || unfinishedBrowserExportBytes + bytes > BROWSER_KEEPALIVE_BYTES) return;
+	unfinishedBrowserExportBytes += bytes;
+	return bytes;
+}), (bytes) => response.pipe(Effect.provideService(FetchHttpClient.RequestInit, { keepalive: bytes !== void 0 }), Effect.tap((result) => bytes === void 0 ? Effect.void : Stream.runDrain(result.stream).pipe(Effect.catchIf((error) => error.reason._tag === "EmptyBodyError", () => Effect.void)))), (bytes) => Effect.sync(() => {
+	if (bytes !== void 0) unfinishedBrowserExportBytes -= bytes;
+})));
+const spanUpstream = (span) => {
+	let current = span;
+	while (current?._tag === "Span") {
+		const upstream = current.attributes.get("chain.upstream");
+		if (upstream === "alchemy" || upstream === "infura" || upstream === "gateway") return upstream;
+		current = current.parent._tag === "Some" ? current.parent.value : void 0;
+	}
+};
+function redactHttpPath(path, fullUrl, source) {
+	let origin = "https://redaction.invalid";
+	try {
+		const url = new URL(String(fullUrl));
+		if (url.protocol === "https:" || url.protocol === "http:") origin = url.origin;
+	} catch {}
+	const prefix = path.startsWith("/") ? origin : "";
+	return redactUrlSecrets(`${prefix}${path}`, source).slice(prefix.length, prefix.length + 2048);
+}
+/** A span whose prototype is `span`: it answers every Span member until an own property overrides it. */
+function inheritSpan(span) {
+	const wrapped = Object.create(span);
+	Object.defineProperties(wrapped, {
+		traceId: { get: () => span.traceId },
+		spanId: { get: () => span.spanId },
+		attributes: { get: () => span.attributes },
+		event: {
+			value: span.event.bind(span),
+			configurable: true
+		},
+		addLinks: {
+			value: span.addLinks.bind(span),
+			configurable: true
+		}
+	});
+	return wrapped;
+}
+/** Preserve domain exits while preventing the OTLP serializer from seeing raw causes. */
+const makeLeakSafeEngineeringTracer = (delegate, enabled = () => true) => Tracer.make({
+	span(options) {
+		const span = enabled() ? delegate.span(options) : new Tracer.NativeSpan(options);
+		const wrapped = inheritSpan(span);
+		Object.defineProperty(wrapped, "attribute", { value: (name, value) => {
+			const source = spanUpstream(span);
+			const header = /^http\.(?:request|response)\.header\.(.+)$/u.exec(name)?.[1];
+			if (header !== void 0 && isCredentialField(header, "header")) span.attribute(name, "[REDACTED]");
+			else if (typeof value === "string" && name === "url.query") span.attribute(name, redactUrlSecrets(`?${value}`).slice(1, 2049));
+			else if (typeof value === "string" && (name === "url.path" || name === "http.target")) {
+				const fullUrl = span.attributes.get("url.full") ?? span.attributes.get("http.url");
+				const path = name === "url.path" && typeof fullUrl === "string" ? /^https?:\/\/[^/]+([^?#]*)/u.exec(fullUrl)?.[1] ?? value : value;
+				span.attribute(name, redactHttpPath(path, fullUrl, source));
+			} else if (typeof value === "string" && (name === "url.full" || name === "http.url" || header === "location" || header === "referer" || header === "referrer")) span.attribute(name, redactUrlSecrets(value, source).slice(0, 2048));
+			else if (header !== void 0 && typeof value === "string") span.attribute(name, redactSecrets(value, source).slice(0, 2048));
+			else span.attribute(name, value);
+		} });
+		Object.defineProperty(wrapped, "end", {
+			configurable: false,
+			enumerable: false,
+			value: (endTime, exit) => {
+				if (!enabled()) {
+					Object.defineProperty(wrapped, "status", { value: {
+						_tag: "Ended",
+						startTime: span.status.startTime,
+						endTime,
+						exit
+					} });
+					return;
+				}
+				if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)) {
+					const first = exit.cause.reasons.find((reason) => !Cause.isInterruptReason(reason));
+					const code = failureText(first === void 0 ? void 0 : Cause.isFailReason(first) ? first.error : first.defect, "code", 128);
+					if (code !== void 0) span.attribute("error.code", code);
+					span.end(endTime, exportFailureExit(exit.cause, spanUpstream(span)));
+				} else span.end(endTime, exit);
+			},
+			writable: false
+		});
+		return wrapped;
+	},
+	...delegate.context === void 0 ? {} : { context: delegate.context.bind(delegate) }
+});
+//#endregion
 //#region src/delivery/records.ts
 function admittedLogger(state, delegate) {
 	return Logger.make((options) => {
@@ -130,7 +247,7 @@ function admittedTracer(state, delegate) {
 /** The span as a producer sees it: at most 32 fields and 2000 attribute bytes, 2 events, 2 links. */
 function boundedSpan(state, span) {
 	const { budget } = state;
-	const wrapped = Object.create(span);
+	const wrapped = inheritSpan(span);
 	let fields = 0, events = 0, links = 0, attributeBytes = 0;
 	let ended = false;
 	Object.defineProperties(wrapped, {
@@ -466,109 +583,6 @@ const validateEngineeringTelemetryConfig = (config) => {
 	};
 };
 //#endregion
-//#region src/engineering/tracer.ts
-const failureText = (failure, key, limit, source) => {
-	if (failure === null || typeof failure !== "object") return void 0;
-	try {
-		let owner = failure;
-		let descriptor;
-		for (let depth = 0; owner !== null && depth < 4; depth += 1) {
-			descriptor = Object.getOwnPropertyDescriptor(owner, key);
-			if (descriptor !== void 0 || key !== "name") break;
-			owner = Object.getPrototypeOf(owner);
-		}
-		const value = descriptor?.value;
-		return typeof value === "string" || key === "code" && typeof value === "number" ? redactSecrets(String(value), source).slice(0, limit) : void 0;
-	} catch {
-		return;
-	}
-};
-const exportFailure = (failure, source) => {
-	const message = failureText(failure, "message", 2048, source) ?? (typeof failure === "string" ? redactSecrets(failure, source).slice(0, 2048) : "Engineering operation failed");
-	const code = failureText(failure, "code", 128);
-	const error = new Error((code === void 0 ? message : `${message} [code=${code}]`).slice(0, 2048));
-	error.name = failureText(failure, "_tag", 128) ?? failureText(failure, "name", 128) ?? "Error";
-	error.stack = failureText(failure, "stack", 8192, source) ?? `${error.name}: ${error.message}`;
-	return error;
-};
-const exportFailureExit = (cause, source) => Exit.failCause(Cause.fromReasons(cause.reasons.filter((reason) => !Cause.isInterruptReason(reason)).slice(0, 8).map((reason) => Cause.isFailReason(reason) ? Cause.makeFailReason(exportFailure(reason.error, source)) : Cause.makeDieReason(exportFailure(reason.defect, source)))));
-const BROWSER_KEEPALIVE_BYTES = 65536;
-let unfinishedBrowserExportBytes = 0;
-const hasBrowserDocument = () => typeof window !== "undefined" && typeof document !== "undefined";
-const browserExportClient = (client) => HttpClient.transform(client, (response, request) => Effect.acquireUseRelease(Effect.sync(() => {
-	const bytes = "contentLength" in request.body ? request.body.contentLength : void 0;
-	if (request.body._tag === "Stream" || request.body._tag === "FormData" || bytes === void 0 || !Number.isSafeInteger(bytes) || bytes < 0 || unfinishedBrowserExportBytes + bytes > BROWSER_KEEPALIVE_BYTES) return;
-	unfinishedBrowserExportBytes += bytes;
-	return bytes;
-}), (bytes) => response.pipe(Effect.provideService(FetchHttpClient.RequestInit, { keepalive: bytes !== void 0 }), Effect.tap((result) => bytes === void 0 ? Effect.void : Stream.runDrain(result.stream).pipe(Effect.catchIf((error) => error.reason._tag === "EmptyBodyError", () => Effect.void)))), (bytes) => Effect.sync(() => {
-	if (bytes !== void 0) unfinishedBrowserExportBytes -= bytes;
-})));
-const spanUpstream = (span) => {
-	let current = span;
-	while (current?._tag === "Span") {
-		const upstream = current.attributes.get("chain.upstream");
-		if (upstream === "alchemy" || upstream === "infura" || upstream === "gateway") return upstream;
-		current = current.parent._tag === "Some" ? current.parent.value : void 0;
-	}
-};
-function redactHttpPath(path, fullUrl, source) {
-	let origin = "https://redaction.invalid";
-	try {
-		const url = new URL(String(fullUrl));
-		if (url.protocol === "https:" || url.protocol === "http:") origin = url.origin;
-	} catch {}
-	const prefix = path.startsWith("/") ? origin : "";
-	return redactUrlSecrets(`${prefix}${path}`, source).slice(prefix.length, prefix.length + 2048);
-}
-/** A span whose prototype is `span`: it answers every Span member until an own property overrides it. */
-function inheritSpan(span) {
-	return Object.create(span);
-}
-/** Preserve domain exits while preventing the OTLP serializer from seeing raw causes. */
-const makeLeakSafeEngineeringTracer = (delegate, enabled = () => true) => Tracer.make({
-	span(options) {
-		const span = enabled() ? delegate.span(options) : new Tracer.NativeSpan(options);
-		const wrapped = inheritSpan(span);
-		Object.defineProperty(wrapped, "attribute", { value: (name, value) => {
-			const source = spanUpstream(span);
-			const header = /^http\.(?:request|response)\.header\.(.+)$/u.exec(name)?.[1];
-			if (header !== void 0 && isCredentialField(header, "header")) span.attribute(name, "[REDACTED]");
-			else if (typeof value === "string" && name === "url.query") span.attribute(name, redactUrlSecrets(`?${value}`).slice(1, 2049));
-			else if (typeof value === "string" && (name === "url.path" || name === "http.target")) {
-				const fullUrl = span.attributes.get("url.full") ?? span.attributes.get("http.url");
-				const path = name === "url.path" && typeof fullUrl === "string" ? /^https?:\/\/[^/]+([^?#]*)/u.exec(fullUrl)?.[1] ?? value : value;
-				span.attribute(name, redactHttpPath(path, fullUrl, source));
-			} else if (typeof value === "string" && (name === "url.full" || name === "http.url" || header === "location" || header === "referer" || header === "referrer")) span.attribute(name, redactUrlSecrets(value, source).slice(0, 2048));
-			else if (header !== void 0 && typeof value === "string") span.attribute(name, redactSecrets(value, source).slice(0, 2048));
-			else span.attribute(name, value);
-		} });
-		Object.defineProperty(wrapped, "end", {
-			configurable: false,
-			enumerable: false,
-			value: (endTime, exit) => {
-				if (!enabled()) {
-					Object.defineProperty(wrapped, "status", { value: {
-						_tag: "Ended",
-						startTime: span.status.startTime,
-						endTime,
-						exit
-					} });
-					return;
-				}
-				if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)) {
-					const first = exit.cause.reasons.find((reason) => !Cause.isInterruptReason(reason));
-					const code = failureText(first === void 0 ? void 0 : Cause.isFailReason(first) ? first.error : first.defect, "code", 128);
-					if (code !== void 0) span.attribute("error.code", code);
-					span.end(endTime, exportFailureExit(exit.cause, spanUpstream(span)));
-				} else span.end(endTime, exit);
-			},
-			writable: false
-		});
-		return wrapped;
-	},
-	...delegate.context === void 0 ? {} : { context: delegate.context.bind(delegate) }
-});
-//#endregion
 //#region src/engineering/minimal.ts
 const MINIMAL_LOG_NAMES = /* @__PURE__ */ new Set([
 	"capxul_sdk_operation",