@capxul/observability 4.20.0-beta.23 → 4.20.0-beta.26

package/README.md

@@ -11,6 +11,85 @@ 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/
+├── engineering-delivery.ts
+├── engineering.ts
+├── index.ts
+├── operations.ts
+├── telemetry-port.ts
+├── __tests__/
+│   ├── engineering-delivery.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)
 
 One PostHog project holds every environment, so `capxul_env` — not project

package/dist/engineering.d.mts

@@ -1,9 +1,9 @@
-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;
@@ -28,7 +28,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 +38,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 +58,27 @@ 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, never>;
+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.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 };