@capxul/observability 4.20.0-beta.4 → 4.20.0-beta.40

package/README.md

@@ -11,8 +11,101 @@ Activity action events accept the implemented `unresolved` Payment status in
 committed filters and export filters. The event records the selected status;
 it does not infer settlement from an unresolved result.
 
+## Where things live
+
+`src/index.ts` is the package door (`@capxul/observability`) and re-exports the
+folders below. `src/engineering.ts` is the engineering subpath
+(`@capxul/observability/engineering`): it builds the engineering telemetry Layer
+from `engineering/` and `engineering-delivery.ts`.
+
+| Folder         | Owns                                                                                                            |
+| -------------- | --------------------------------------------------------------------------------------------------------------- |
+| `catalog/`     | Event names, journeys, the required envelope, bounded value schemas, every event's schema, CLI vocabularies.    |
+| `events/`      | Event schemas by domain: identity, onboarding, organizations, money, chain, indexing, workflows, activity, CLI. |
+| `operations/`  | Operation names by concept group, composed with the protocol's rows in `operations.ts`.                         |
+| `telemetry/`   | The track handler, redaction before an event leaves the process, and in-process adapters.                       |
+| `browser/`     | Browser PostHog setup, event sanitizing and captured-network masking.                                           |
+| `engineering/` | Engineering logs, metrics and traces: configuration, serialization and the tracer.                              |
+| `delivery/`    | One CLI invocation's engineering delivery: admission, budget, records and export requests.                      |
+
+`packages/tools/src/modules/lint/internal/telemetry-spine/` reads the catalog across `catalog/`,
+`events/`, `telemetry/` and `browser/`, and treats every one of those files as
+naming events rather than producing them.
+
+```text
+src/
+├── devtools.ts
+├── engineering-delivery.ts
+├── engineering.ts
+├── index.ts
+├── operations.ts
+├── telemetry-port.ts
+├── __tests__/
+│   ├── engineering-delivery.test.ts
+│   ├── devtools.test.ts
+│   ├── engineering.test.ts
+│   ├── operations.test.ts
+│   ├── posthog-browser-privacy.test.ts
+│   └── telemetry.test.ts
+├── browser/
+│   ├── analytics.ts
+│   ├── network.ts
+│   └── sanitize.ts
+├── catalog/
+│   ├── cli.ts
+│   ├── envelope.ts
+│   ├── events.ts
+│   ├── journeys.ts
+│   ├── schemas.ts
+│   └── values.ts
+├── delivery/
+│   ├── admission.ts
+│   ├── budget.ts
+│   ├── records.ts
+│   └── requests.ts
+├── engineering/
+│   ├── config.ts
+│   ├── logs.ts
+│   ├── metric-points.ts
+│   ├── minimal.ts
+│   ├── serialization.ts
+│   └── tracer.ts
+├── events/
+│   ├── activity.ts
+│   ├── chain.ts
+│   ├── cli.ts
+│   ├── identity.ts
+│   ├── indexing.ts
+│   ├── money.ts
+│   ├── onboarding.ts
+│   ├── organizations.ts
+│   └── workflows.ts
+├── operations/
+│   ├── money.ts
+│   ├── organizations.ts
+│   ├── people.ts
+│   ├── platform.ts
+│   └── tree.ts
+└── telemetry/
+    ├── adapters.ts
+    ├── redaction.ts
+    └── track.ts
+```
+
 ## 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
@@ -108,3 +201,6 @@ Set `privacy: "minimal"` for hosts that must export only closed operation/error
 codes, timings, environment, and validated correlation. This opt-in removes
 free-form logs, provider messages, URLs, bodies, and source paths, including
 span exception events. Default consumers retain the existing redaction policy.
+`minimalCorrelationId` is that projection's correlation rule: a host that shows
+a correlation id to a person checks it first, so the id it shows is one the
+export carries.

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.d.mts

@@ -1,12 +1,13 @@
-import { Context, Duration, Effect, Layer, Logger, Metric, References, Tracer } from "effect";
-import { HttpClient, HttpClientError } from "effect/unstable/http";
-import { OtlpExporter, OtlpSerialization } from "effect/unstable/observability";
-//#region src/engineering-delivery.d.ts
+import { Context, Duration, Effect, Layer, Logger, Metric, Tracer } from "effect";
+import { HttpClient } from "effect/http";
+import { OtlpExporter } from "effect/observability";
+//#region src/delivery/budget.d.ts
 /** Fixed admission limits for one CLI invocation and its SDK client. */
-declare const CLI_ENGINEERING_LIMITS: Readonly<{
+export declare const CLI_ENGINEERING_LIMITS: Readonly<{
   records: 80;
   ordinaryRecords: 64;
   recordBytes: 16384;
+  recordFields: 48;
   requests: 5;
   ordinaryRequests: 2;
   requestBytes: 1572864;
@@ -28,7 +29,7 @@ interface CliEngineeringStats {
   readonly metricSeries: number;
 }
 /** Shared, closure-owned admission state; no queue or mutable counters are exposed. */
-declare function makeCliEngineeringBudget(): Readonly<{
+export declare function makeCliEngineeringBudget(): Readonly<{
   metricRegistry: Map<string, MetricEntry>;
   emptyMetricRegistry: () => Map<string, MetricEntry>;
   drop: () => void;
@@ -38,9 +39,9 @@ declare function makeCliEngineeringBudget(): Readonly<{
 }>;
 type CliEngineeringBudget = ReturnType<typeof makeCliEngineeringBudget>;
 //#endregion
-//#region src/engineering.d.ts
+//#region src/engineering/config.d.ts
 type EngineeringProducer = "browser" | "server";
-declare const ENGINEERING_CAPXUL_ENVS: readonly ["development", "staging", "production", "local"];
+export declare const ENGINEERING_CAPXUL_ENVS: readonly ["development", "staging", "production", "local"];
 type EngineeringCapxulEnv = (typeof ENGINEERING_CAPXUL_ENVS)[number];
 interface EngineeringTelemetryConfig {
   readonly host: string;
@@ -58,21 +59,35 @@ interface EngineeringTelemetryConfig {
   /** CLI-only shared admission and transport lifetime. Omission preserves host defaults. */
   readonly deliveryBudget?: CliEngineeringBudget;
 }
-declare const traceHeaderFilter: (_name: string) => boolean;
-declare const postHogOtlpEndpoints: (host: string) => {
+export declare const traceHeaderFilter: (_name: string) => boolean;
+export declare const postHogOtlpEndpoints: (host: string) => {
   readonly logs: `${string}/i/v1/logs`;
   readonly traces: `${string}/i/v1/traces`;
   readonly metrics: `${string}/i/v1/metrics`;
 };
-/** Preserve domain exits while preventing the OTLP serializer from seeing raw causes. */
-declare const makeLeakSafeEngineeringTracer: (delegate: Tracer.Tracer, enabled?: () => boolean) => Tracer.Tracer;
+//#endregion
+//#region src/engineering/logs.d.ts
 /** Attempt to drain all engineering signals; completion does not prove ingestion. */
-declare const flushEngineeringTelemetry: Effect.Effect<void, never, OtlpExporter.Flusher>;
+export declare const flushEngineeringTelemetry: Effect.Effect<void, never, OtlpExporter.Flusher>;
 declare const EngineeringLog_base: Context.ServiceClass<EngineeringLog, "capxul/EngineeringLog", Logger.Logger<unknown, void>>;
 declare class EngineeringLog extends EngineeringLog_base {}
 /** Deliver an owned engineering record without changing the caller's console verbosity. */
-declare const logEngineeringInfo: (message: string, attributes: Readonly<Record<string, unknown>>) => Effect.Effect<void, never, EngineeringLog>;
+export declare const logEngineeringInfo: (message: string, attributes: Readonly<Record<string, unknown>>) => Effect.Effect<void, never, never>;
+//#endregion
+//#region src/engineering/tracer.d.ts
+/** Preserve domain exits while preventing the OTLP serializer from seeing raw causes. */
+export declare const makeLeakSafeEngineeringTracer: (delegate: Tracer.Tracer, enabled?: () => boolean) => Tracer.Tracer;
+//#endregion
+//#region src/engineering/minimal.d.ts
+/**
+ * A correlation id the minimal export carries: an identifier with no `/`, not
+ * `0x` hex, and unchanged by the secret mask. The CLI quotes a backend
+ * correlation id as its `ref` only when it passes, so the ref finds a row.
+ */
+export declare const minimalCorrelationId: (value: unknown) => value is string;
+//#endregion
+//#region src/engineering.d.ts
 /** Shared browser/server OTLP layer. OtlpLogger merges with incumbent loggers once. */
-declare const makeEngineeringTelemetryLayer: (config: EngineeringTelemetryConfig) => Layer.Layer<EngineeringLog | OtlpExporter.Flusher, never, never>;
+export declare const makeEngineeringTelemetryLayer: (config: EngineeringTelemetryConfig) => Layer.Layer<EngineeringLog | OtlpExporter.Flusher, never, never>;
 //#endregion
-export { CLI_ENGINEERING_LIMITS, type CliEngineeringBudget, type CliEngineeringStats, ENGINEERING_CAPXUL_ENVS, EngineeringCapxulEnv, EngineeringProducer, EngineeringTelemetryConfig, flushEngineeringTelemetry, logEngineeringInfo, makeCliEngineeringBudget, makeEngineeringTelemetryLayer, makeLeakSafeEngineeringTracer, postHogOtlpEndpoints, traceHeaderFilter };
+export type { CliEngineeringBudget, CliEngineeringStats, EngineeringCapxulEnv, EngineeringProducer, EngineeringTelemetryConfig };