@smthrs/observability 0.35.0 → 1.0.0-rc.4

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# @smthrs/observability
+
+## [Unreleased]
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Added
+
+- Effect-native OTLP export, structured logger layers, validated OpenTelemetry
+  resource metadata, provider-neutral SDK bridges, and explicit Node and
+  browser SDK subpaths.
+- A bounded, asynchronous journal logger with versioned cause payloads,
+  durable journal-owned identities, synchronous detached snapshots, and the
+  shared credential-redaction rules.
+- Package-owned generated README and API documentation.
+- Producer-wired run throughput, active seat, and quota park metrics.
+- A `droppedLogRecords` counter for every operational log record lost to queue
+  overflow, journal delivery failure, or a journal defect.
+- An `Endpoint` module that decodes and normalizes the collector endpoint every
+  OTLP builder posts to.
+
+### Changed
+
+- Removed duplicate cache hit, miss, and hit-rate handles; the authoritative
+  cache series remain in `@smthrs/step-cache`.
+
+### Fixed
+
+- Recreated or concurrent journal logger layers no longer reuse `sourceSeq`
+  identities and silently lose records.
+- Queued records no longer observe later caller mutation or discard Effect
+  failure, defect, and interruption causes.
+- All resource builders now reject the same malformed identities, Unicode,
+  attribute keys, values, and resource sizes with one typed error.
+- Logger capacity, identifier, snapshot, overflow, and shutdown behavior is
+  explicit and covered at its exact boundaries.
+- A logged value large enough to spend the snapshot budget no longer turns
+  `annotations` into a scalar, and a projection that still fails `TelemetryLog`
+  degrades to a decodable total record instead of an undecodable journal row.
+- Journal delivery failures and journal defects are reported as warnings and
+  counted instead of vanishing, and a defect no longer ends the forwarding
+  worker for the rest of the run. Interruption still ends it.
+- Snapshot truncation runs in one pass instead of about twenty re-encodes and
+  never cuts a surrogate pair.
+- An unusable collector endpoint fails layer acquisition instead of producing a
+  layer that exports nothing, and repeated trailing separators no longer
+  produce a double slash in a signal URL.
+- The logger layers no longer pin the application's `MinimumLogLevel` when the
+  caller named no level.
+
+### Documentation
+
+- Corrected the reason `NodeOtel` cannot be re-exported from the root barrel:
+  it resolves Node-only host modules, including a bare `async_hooks` specifier,
+  rather than a `node:` built-in.
+- Removed the internal review markers from every published JSDoc block.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 William Cory
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,84 @@
+# @smthrs/observability
+
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://observability.smithers.sh
+
+# `@smthrs/observability`
+
+Send an Effect program's logs, metrics, and traces to an OpenTelemetry collector with one layer.
+
+`Otlp` composes only what `effect` itself ships, so it allocates no OpenTelemetry SDK, never resolves a `node:` built-in, and runs unchanged in Node, Bun, and a browser. Around it the package ships the pieces a host installs beside an exporter: Effect logger layers, a validated `Resource` describing the service, a `JournalLogger` that mirrors a run's log records into a durable journal, the runtime `Metric` handles that cross package boundaries, and `Otel`, which bridges OpenTelemetry providers an application already built.
+
+`NodeOtel` and `BrowserOtel` are deliberately not re-exported from the root. Each binds a host-specific OpenTelemetry SDK: `NodeOtel` reaches `@effect/opentelemetry/NodeSdk` and `@opentelemetry/sdk-trace-node`, which pulls the bare `async_hooks` specifier through `@opentelemetry/context-async-hooks`. Re-exporting it would put a module a browser bundler cannot resolve in the root entry point. Import them by subpath instead: `@smthrs/observability/NodeOtel`.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+Node.js 26.4.0 or later. Effect services are identified by module identity, so install the same `effect` release this package is built against.
+
+The default install supports the root, `Otlp`, `Otel`, and `Resource`, with
+required `@effect/opentelemetry@4.0.0-rc.115` and `@opentelemetry/api@1.9.1`
+peers. It includes no HTTP exporters or trace SDK. Select the optional peers
+for the host subpath you import:
+
+```sh
+# @smthrs/observability/NodeOtel
+pnpm add @opentelemetry/exporter-logs-otlp-http@0.222.0 @opentelemetry/exporter-metrics-otlp-http@0.222.0 @opentelemetry/exporter-trace-otlp-http@0.222.0 @opentelemetry/sdk-trace-base@2.11.0 @opentelemetry/sdk-trace-node@2.11.0
+# @smthrs/observability/BrowserOtel
+pnpm add @opentelemetry/sdk-trace-base@2.11.0 @opentelemetry/sdk-trace-web@2.11.0
+```
+
+## Use
+
+```ts
+import * as Otlp from "@smthrs/observability/Otlp"
+
+const Telemetry = Otlp.layerFetch({
+  baseUrl: "http://localhost:4318",
+  serviceName: "my-service"
+})
+```
+
+Provide the layer, give it a scope, and every span, log record, and metric series the program already produces posts to the collector. Deleting the provide removes telemetry and changes nothing else.
+
+Resource identity fields and attribute keys are limited to 1,024 UTF-16 code
+units, strings to 65,536 code units, and attributes to 256 entries.
+Resources are refused during layer acquisition with `InvalidResourceConfiguration`
+if arrays exceed 256 elements or the whole OTLP JSON resource exceeds 128 KiB.
+The byte budget counts keys, values, wrappers, JSON escaping, and UTF-8, including
+service identity and SDK-added `telemetry.sdk.name` and `telemetry.sdk.language`.
+These SDK fields are reserved even for the default Effect exporter. Resource
+metadata is explicit; both default OTLP and Node SDK layers isolate ambient
+resource configuration so it cannot enlarge a resource after validation.
+The 1 MiB transport reserves 8 KiB for the request envelope
+and 888 KiB (`Otlp.reservedBatchBytes`) for signal batches: about 909 bytes per
+record in the upstream 1,000-record log or span batch. Large application records
+can still exceed the transport cap.
+
+Discarded batches increment `flows_observability_otlp_dropped` and emit a
+`Warn` diagnostic with code `otlp_export_discarded` at most once per minute per
+transport through the loggers installed before exporter acquisition. Install
+an ambient logger that writes outside OTLP to observe loss independently; an
+empty logger set or a minimum level above `Warn` suppresses that diagnostic.
+The warning never enters this exporter and includes only the discard reason,
+request bytes, byte limit, and running drop count.
+
+## Documentation
+
+Full documentation is at [observability.smithers.sh](https://observability.smithers.sh):
+
+- [Quickstart](https://observability.smithers.sh/quickstart/): export a trace, a log record, and a metric series to a collector you can watch.
+- [Installation](https://observability.smithers.sh/installation/): requirements, import forms, and the rule that keeps the root entry point bundling for a browser.
+- [The layer map](https://observability.smithers.sh/concepts/layer-map/): which builder to reach for, and what each one costs.
+- [API reference](https://observability.smithers.sh/reference/api/): every public export, with validation, backpressure, shutdown, retry, and platform contracts.
+- [Troubleshooting](https://observability.smithers.sh/troubleshooting/): the typed refusals this package reports, and the silent cases that are not refusals at all.
+
+## License
+
+MIT

package/dist/cjs/BrowserOtel.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Browser OpenTelemetry setup with explicitly injected providers/readers.
+ *
+ * @since 0.1.0
+ */
+import type { LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import type { MetricReader } from "@opentelemetry/sdk-metrics";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import * as Layer from "effect/Layer";
+import * as Resource from "./Resource.ts";
+import type { Configuration as ResourceConfiguration } from "./Resource.ts";
+/**
+ * Browser OTEL layer options. Processors and readers are created by the
+ * caller's factories, which keeps this module free of Node imports and browser
+ * exporter policy. Every factory is owned: it runs once during layer
+ * acquisition, after resource validation, and the layer scope shuts down
+ * everything it returned. An empty array installs nothing for that signal.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+    readonly resource: ResourceConfiguration;
+    readonly spanProcessor?: (() => SpanProcessor | ReadonlyArray<SpanProcessor>) | undefined;
+    readonly logRecordProcessor?: (() => LogRecordProcessor | ReadonlyArray<LogRecordProcessor>) | undefined;
+    readonly metricReader?: (() => MetricReader | ReadonlyArray<MetricReader>) | undefined;
+    readonly loggerMergeWithExisting?: boolean | undefined;
+}
+/**
+ * Builds a scoped browser OpenTelemetry layer. The web SDK owns every
+ * processor and reader the factories return and shuts them down on release.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerOtel: (options: Options) => Layer.Layer<never, Resource.InvalidResourceConfiguration>;
+//# sourceMappingURL=BrowserOtel.d.ts.map

package/dist/cjs/BrowserOtel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserOtel.d.ts","sourceRoot":"","sources":["../../src/BrowserOtel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAElE,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,IAAI,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAE3E;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAA;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC,GAAG,SAAS,CAAA;IACzF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC,kBAAkB,CAAC,CAAC,GAAG,SAAS,CAAA;IACxG,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC,GAAG,SAAS,CAAA;IACtF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CACvD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,OAAO,KAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,4BAA4B,CAUlG,CAAA"}

package/dist/cjs/BrowserOtel.js

@@ -0,0 +1,47 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var BrowserOtel_exports = {};
+__export(BrowserOtel_exports, {
+  layerOtel: () => layerOtel
+});
+module.exports = __toCommonJS(BrowserOtel_exports);
+var WebSdk = __toESM(require("@effect/opentelemetry/WebSdk"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Layer = __toESM(require("effect/Layer"), 1);
+var Resource = __toESM(require("./Resource.js"), 1);
+const layerOtel = (options) => Layer.unwrap(
+  Effect.map(Resource.decode(options.resource), (decoded) => WebSdk.layer(() => ({
+    resource: Resource.toOpenTelemetryConfiguration(decoded),
+    spanProcessor: options.spanProcessor?.(),
+    logRecordProcessor: options.logRecordProcessor?.(),
+    metricReader: options.metricReader?.(),
+    loggerMergeWithExisting: options.loggerMergeWithExisting
+  })))
+);
+//# sourceMappingURL=BrowserOtel.js.map

package/dist/cjs/BrowserOtel.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/BrowserOtel.ts"],
+  "sourcesContent": ["/**\n * Browser OpenTelemetry setup with explicitly injected providers/readers.\n *\n * @since 0.1.0\n */\n\nimport * as WebSdk from \"@effect/opentelemetry/WebSdk\"\nimport type { LogRecordProcessor } from \"@opentelemetry/sdk-logs\"\nimport type { MetricReader } from \"@opentelemetry/sdk-metrics\"\nimport type { SpanProcessor } from \"@opentelemetry/sdk-trace-base\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Resource from \"./Resource.ts\"\nimport type { Configuration as ResourceConfiguration } from \"./Resource.ts\"\n\n/**\n * Browser OTEL layer options. Processors and readers are created by the\n * caller's factories, which keeps this module free of Node imports and browser\n * exporter policy. Every factory is owned: it runs once during layer\n * acquisition, after resource validation, and the layer scope shuts down\n * everything it returned. An empty array installs nothing for that signal.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Options {\n  readonly resource: ResourceConfiguration\n  readonly spanProcessor?: (() => SpanProcessor | ReadonlyArray<SpanProcessor>) | undefined\n  readonly logRecordProcessor?: (() => LogRecordProcessor | ReadonlyArray<LogRecordProcessor>) | undefined\n  readonly metricReader?: (() => MetricReader | ReadonlyArray<MetricReader>) | undefined\n  readonly loggerMergeWithExisting?: boolean | undefined\n}\n\n/**\n * Builds a scoped browser OpenTelemetry layer. The web SDK owns every\n * processor and reader the factories return and shuts them down on release.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerOtel = (options: Options): Layer.Layer<never, Resource.InvalidResourceConfiguration> =>\n  Layer.unwrap(\n    Effect.map(Resource.decode(options.resource), (decoded) =>\n      WebSdk.layer(() => ({\n        resource: Resource.toOpenTelemetryConfiguration(decoded),\n        spanProcessor: options.spanProcessor?.(),\n        logRecordProcessor: options.logRecordProcessor?.(),\n        metricReader: options.metricReader?.(),\n        loggerMergeWithExisting: options.loggerMergeWithExisting\n      })))\n  )\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,aAAwB;AAIxB,aAAwB;AACxB,YAAuB;AACvB,eAA0B;AA4BnB,MAAM,YAAY,CAAC,YACxB,MAAM;AAAA,EACJ,OAAO,IAAI,SAAS,OAAO,QAAQ,QAAQ,GAAG,CAAC,YAC7C,OAAO,MAAM,OAAO;AAAA,IAClB,UAAU,SAAS,6BAA6B,OAAO;AAAA,IACvD,eAAe,QAAQ,gBAAgB;AAAA,IACvC,oBAAoB,QAAQ,qBAAqB;AAAA,IACjD,cAAc,QAAQ,eAAe;AAAA,IACrC,yBAAyB,QAAQ;AAAA,EACnC,EAAE,CAAC;AACP;",
+  "names": []
+}

package/dist/cjs/Endpoint.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Validated collector endpoints for the OTLP exporters.
+ *
+ * The endpoint is the field an operator most often gets wrong, and a wrong one
+ * is invisible: Effect's exporter absorbs export failure by design, so a layer
+ * built against `""` or `"localhost:4318"` looks identical to a working one and
+ * simply never delivers. Every builder therefore decodes its endpoint during
+ * layer acquisition, the same posture `Resource` already takes.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/**
+ * Largest collector endpoint accepted by a builder.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumEndpointLength = 2048;
+/**
+ * Runtime schema for an absolute `http:` or `https:` collector endpoint that
+ * carries no credentials, query, fragment, backslashes, spaces, or controls.
+ * A base path is allowed; authentication belongs in exporter headers.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const Endpoint: Schema.String;
+declare const InvalidExporterEndpoint_base: Schema.Class<InvalidExporterEndpoint, Schema.TaggedStruct<"@smthrs/observability/InvalidExporterEndpoint", {
+    readonly code: Schema.Literal<"invalid_exporter_endpoint">;
+    readonly path: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Stable exporter-endpoint refusal shared by every OTLP builder.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export declare class InvalidExporterEndpoint extends InvalidExporterEndpoint_base {
+}
+/**
+ * Removes the repeated trailing separators that would otherwise produce a
+ * double slash in a signal URL.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export declare const normalize: (endpoint: string) => string;
+/**
+ * Decodes one collector endpoint into its normalized form without retaining
+ * the rejected value.
+ *
+ * `path` names the option the endpoint arrived on, so the refusal points at the
+ * caller's own field rather than at a shared internal name.
+ *
+ * @category decoding
+ * @since 1.0.0-rc.0
+ */
+export declare const decode: (endpoint: unknown, path: string) => Effect.Effect<string, InvalidExporterEndpoint>;
+/**
+ * Builds the OTLP/HTTP URL one signal is posted to below a decoded endpoint.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export declare const signalUrl: (endpoint: string, signal: "traces" | "metrics" | "logs") => string;
+export {};
+//# sourceMappingURL=Endpoint.d.ts.map

package/dist/cjs/Endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Endpoint.d.ts","sourceRoot":"","sources":["../../src/Endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAA;AAuC1C;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,eAGpB,CAAA;;;;;;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,4BAO5C;CAAG;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,MAAM,KAAG,MAAsC,CAAA;AAEnF;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM,GACjB,UAAU,OAAO,EACjB,MAAM,MAAM,KACX,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAW7C,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,UAAU,MAAM,EAAE,QAAQ,QAAQ,GAAG,SAAS,GAAG,MAAM,KAAG,MAC7C,CAAA"}

package/dist/cjs/Endpoint.js

@@ -0,0 +1,85 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Endpoint_exports = {};
+__export(Endpoint_exports, {
+  Endpoint: () => Endpoint,
+  InvalidExporterEndpoint: () => InvalidExporterEndpoint,
+  decode: () => decode,
+  maximumEndpointLength: () => maximumEndpointLength,
+  normalize: () => normalize,
+  signalUrl: () => signalUrl
+});
+module.exports = __toCommonJS(Endpoint_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+const maximumEndpointLength = 2048;
+const largestRepairedCodeUnit = 32;
+const repairedByUrlParser = (value) => {
+  for (let index = 0; index < value.length; index++) {
+    if (value.charCodeAt(index) <= largestRepairedCodeUnit) return true;
+  }
+  return false;
+};
+const isAbsoluteHttpUrl = (value) => {
+  if (repairedByUrlParser(value)) return false;
+  if (!/^https?:\/\/[^/]/i.test(value) || /[?#\\]/.test(value)) return false;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  return url.username === "" && url.password === "";
+};
+const Endpoint = Schema.String.check(
+  Schema.isMaxLength(maximumEndpointLength),
+  Schema.makeFilter((value) => isAbsoluteHttpUrl(value), { title: "absoluteCollectorEndpoint" })
+);
+class InvalidExporterEndpoint extends Schema.TaggedError()(
+  "@smthrs/observability/InvalidExporterEndpoint",
+  {
+    code: Schema.Literal("invalid_exporter_endpoint"),
+    path: Schema.String,
+    message: Schema.String
+  }
+) {
+}
+const normalize = (endpoint) => endpoint.replace(/\/+$/, "");
+const decode = (endpoint, path) => Schema.decodeUnknownEffect(Endpoint)(endpoint).pipe(
+  Effect.map(normalize),
+  Effect.mapError(
+    () => new InvalidExporterEndpoint({
+      code: "invalid_exporter_endpoint",
+      path,
+      message: `OTLP collector ${path} must be an absolute http:// or https:// base URL without credentials, query, fragment, backslashes, spaces, or control characters`
+    })
+  )
+);
+const signalUrl = (endpoint, signal) => `${normalize(endpoint)}/v1/${signal}`;
+//# sourceMappingURL=Endpoint.js.map

package/dist/cjs/Endpoint.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Endpoint.ts"],
+  "sourcesContent": ["/**\n * Validated collector endpoints for the OTLP exporters.\n *\n * The endpoint is the field an operator most often gets wrong, and a wrong one\n * is invisible: Effect's exporter absorbs export failure by design, so a layer\n * built against `\"\"` or `\"localhost:4318\"` looks identical to a working one and\n * simply never delivers. Every builder therefore decodes its endpoint during\n * layer acquisition, the same posture `Resource` already takes.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Largest collector endpoint accepted by a builder.\n *\n * @category constants\n * @since 1.0.0-rc.0\n */\nexport const maximumEndpointLength = 2_048\n\n/** The largest code unit the WHATWG URL parser repairs away: the space. */\nconst largestRepairedCodeUnit = 0x20\n\n/**\n * Reports whether the URL parser would repair the value rather than parse it\n * as written. It strips leading and trailing C0 controls and spaces and\n * removes tab, newline, and carriage return from anywhere in its input, and\n * every one of those sits at or below {@link largestRepairedCodeUnit}.\n */\nconst repairedByUrlParser = (value: string): boolean => {\n  for (let index = 0; index < value.length; index++) {\n    if (value.charCodeAt(index) <= largestRepairedCodeUnit) return true\n  }\n  return false\n}\n\nconst isAbsoluteHttpUrl = (value: string): boolean => {\n  // `new URL` alone is not a validator here. It strips padding and inline\n  // control characters before parsing, so it reports a copy-pasted\n  // `\"http://collector:4318\\n\"` as well formed while the untrimmed original is\n  // what a builder would hand its exporter: either an unusable URL or a\n  // request to a host nobody typed. No legal collector endpoint carries one of\n  // these, so refusing them costs nothing and closes the silent case.\n  if (repairedByUrlParser(value)) return false\n  // Exporters append /v1/<signal> to this base. A query or fragment would\n  // swallow that suffix instead of changing the request path. Also refuse\n  // missing authority separators and backslashes that WHATWG silently repairs.\n  if (!/^https?:\\/\\/[^/]/i.test(value) || /[?#\\\\]/.test(value)) return false\n  let url: URL\n  try {\n    url = new URL(value)\n  } catch {\n    return false\n  }\n  return url.username === \"\" && url.password === \"\"\n}\n\n/**\n * Runtime schema for an absolute `http:` or `https:` collector endpoint that\n * carries no credentials, query, fragment, backslashes, spaces, or controls.\n * A base path is allowed; authentication belongs in exporter headers.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const Endpoint = Schema.String.check(\n  Schema.isMaxLength(maximumEndpointLength),\n  Schema.makeFilter((value: string) => isAbsoluteHttpUrl(value), { title: \"absoluteCollectorEndpoint\" })\n)\n\n/**\n * Stable exporter-endpoint refusal shared by every OTLP builder.\n *\n * @category errors\n * @since 1.0.0-rc.0\n */\nexport class InvalidExporterEndpoint extends Schema.TaggedError<InvalidExporterEndpoint>()(\n  \"@smthrs/observability/InvalidExporterEndpoint\",\n  {\n    code: Schema.Literal(\"invalid_exporter_endpoint\"),\n    path: Schema.String,\n    message: Schema.String\n  }\n) {}\n\n/**\n * Removes the repeated trailing separators that would otherwise produce a\n * double slash in a signal URL.\n *\n * @category conversions\n * @since 1.0.0-rc.0\n */\nexport const normalize = (endpoint: string): string => endpoint.replace(/\\/+$/, \"\")\n\n/**\n * Decodes one collector endpoint into its normalized form without retaining\n * the rejected value.\n *\n * `path` names the option the endpoint arrived on, so the refusal points at the\n * caller's own field rather than at a shared internal name.\n *\n * @category decoding\n * @since 1.0.0-rc.0\n */\nexport const decode = (\n  endpoint: unknown,\n  path: string\n): Effect.Effect<string, InvalidExporterEndpoint> =>\n  Schema.decodeUnknownEffect(Endpoint)(endpoint).pipe(\n    Effect.map(normalize),\n    Effect.mapError(() =>\n      new InvalidExporterEndpoint({\n        code: \"invalid_exporter_endpoint\",\n        path,\n        message:\n          `OTLP collector ${path} must be an absolute http:// or https:// base URL without credentials, query, fragment, backslashes, spaces, or control characters`\n      })\n    )\n  )\n\n/**\n * Builds the OTLP/HTTP URL one signal is posted to below a decoded endpoint.\n *\n * @category conversions\n * @since 1.0.0-rc.0\n */\nexport const signalUrl = (endpoint: string, signal: \"traces\" | \"metrics\" | \"logs\"): string =>\n  `${normalize(endpoint)}/v1/${signal}`\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAYA,aAAwB;AACxB,aAAwB;AAQjB,MAAM,wBAAwB;AAGrC,MAAM,0BAA0B;AAQhC,MAAM,sBAAsB,CAAC,UAA2B;AACtD,WAAS,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS;AACjD,QAAI,MAAM,WAAW,KAAK,KAAK,wBAAyB,QAAO;AAAA,EACjE;AACA,SAAO;AACT;AAEA,MAAM,oBAAoB,CAAC,UAA2B;AAOpD,MAAI,oBAAoB,KAAK,EAAG,QAAO;AAIvC,MAAI,CAAC,oBAAoB,KAAK,KAAK,KAAK,SAAS,KAAK,KAAK,EAAG,QAAO;AACrE,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,IAAI,KAAK;AAAA,EACrB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,SAAO,IAAI,aAAa,MAAM,IAAI,aAAa;AACjD;AAUO,MAAM,WAAW,OAAO,OAAO;AAAA,EACpC,OAAO,YAAY,qBAAqB;AAAA,EACxC,OAAO,WAAW,CAAC,UAAkB,kBAAkB,KAAK,GAAG,EAAE,OAAO,4BAA4B,CAAC;AACvG;AAQO,MAAM,gCAAgC,OAAO,YAAqC;AAAA,EACvF;AAAA,EACA;AAAA,IACE,MAAM,OAAO,QAAQ,2BAA2B;AAAA,IAChD,MAAM,OAAO;AAAA,IACb,SAAS,OAAO;AAAA,EAClB;AACF,EAAE;AAAC;AASI,MAAM,YAAY,CAAC,aAA6B,SAAS,QAAQ,QAAQ,EAAE;AAY3E,MAAM,SAAS,CACpB,UACA,SAEA,OAAO,oBAAoB,QAAQ,EAAE,QAAQ,EAAE;AAAA,EAC7C,OAAO,IAAI,SAAS;AAAA,EACpB,OAAO;AAAA,IAAS,MACd,IAAI,wBAAwB;AAAA,MAC1B,MAAM;AAAA,MACN;AAAA,MACA,SACE,kBAAkB,IAAI;AAAA,IAC1B,CAAC;AAAA,EACH;AACF;AAQK,MAAM,YAAY,CAAC,UAAkB,WAC1C,GAAG,UAAU,QAAQ,CAAC,OAAO,MAAM;",
+  "names": []
+}

package/dist/cjs/JournalLogger.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Non-blocking forwarding of bounded operational logs to the durable journal.
+ *
+ * @since 0.1.0
+ */
+import * as Journal from "@smthrs/journal/Journal";
+import * as JournalEvent from "@smthrs/journal/JournalEvent";
+import * as Cause from "effect/Cause";
+import * as Layer from "effect/Layer";
+import type * as LogLevel from "effect/LogLevel";
+import * as Schema from "effect/Schema";
+/**
+ * Largest queue accepted by the forwarding logger.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumCapacity = 65536;
+/**
+ * Largest detached log payload admitted to the asynchronous queue.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumSnapshotBytes: number;
+/**
+ * Largest number of container members copied into one detached log payload.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumSnapshotMembers = 4096;
+/**
+ * Deepest container path copied into one detached log payload.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumSnapshotDepth = 64;
+/**
+ * What a hostile or unreadable logged value becomes.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const unrenderableMarker = "[Unrenderable]";
+/**
+ * What a value beyond a logger resource ceiling becomes.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const truncatedMarker = "[Truncated]";
+/**
+ * Options for the journal forwarding logger.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Options {
+    /** The run every forwarded record is attributed to. */
+    readonly runId: JournalEvent.RunId;
+    /** Queue depth, 1 through {@link maximumCapacity}. Defaults to 256. */
+    readonly capacity?: number | undefined;
+    /**
+     * Pins `References.MinimumLogLevel` for the whole application. Omitted, the
+     * layer leaves that reference alone and Effect's own `Info` default applies.
+     */
+    readonly minimumLogLevel?: LogLevel.LogLevel | undefined;
+    /**
+     * Keeps the ambient loggers alongside the forwarder. Defaults to `false`,
+     * which replaces the ambient logger set.
+     */
+    readonly mergeWithExisting?: boolean | undefined;
+}
+declare const InvalidJournalLoggerOptions_base: Schema.Class<InvalidJournalLoggerOptions, Schema.TaggedStruct<"@smthrs/observability/InvalidJournalLoggerOptions", {
+    readonly code: Schema.Literal<"invalid_journal_logger_options">;
+    readonly path: Schema.String;
+    readonly message: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * A stable logger configuration refusal.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export declare class InvalidJournalLoggerOptions extends InvalidJournalLoggerOptions_base {
+}
+/**
+ * One typed failure retained from an Effect cause.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const TelemetryFail: Schema.Struct<{
+    readonly _tag: Schema.Literal<"Fail">;
+    readonly error: Schema.Unknown;
+}>;
+/**
+ * One unexpected defect retained from an Effect cause.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const TelemetryDie: Schema.Struct<{
+    readonly _tag: Schema.Literal<"Die">;
+    readonly defect: Schema.Unknown;
+}>;
+/**
+ * One interruption retained from an Effect cause.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const TelemetryInterrupt: Schema.Struct<{
+    readonly _tag: Schema.Literal<"Interrupt">;
+    readonly fiberId: Schema.NullOr<Schema.Int>;
+}>;
+/**
+ * One reason in a persisted telemetry cause.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const TelemetryCauseReason: Schema.Union<readonly [Schema.Struct<{
+    readonly _tag: Schema.Literal<"Fail">;
+    readonly error: Schema.Unknown;
+}>, Schema.Struct<{
+    readonly _tag: Schema.Literal<"Die">;
+    readonly defect: Schema.Unknown;
+}>, Schema.Struct<{
+    readonly _tag: Schema.Literal<"Interrupt">;
+    readonly fiberId: Schema.NullOr<Schema.Int>;
+}>]>;
+/**
+ * One reason in a persisted telemetry cause.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type TelemetryCauseReason = typeof TelemetryCauseReason.Type;
+/**
+ * A versioned structural Effect cause.
+ *
+ * Effect 4 stores composed failures as an ordered reason list. The projection
+ * preserves that order and each fail, defect, or interrupt discriminator.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const TelemetryCause: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly reasons: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly _tag: Schema.Literal<"Fail">;
+        readonly error: Schema.Unknown;
+    }>, Schema.Struct<{
+        readonly _tag: Schema.Literal<"Die">;
+        readonly defect: Schema.Unknown;
+    }>, Schema.Struct<{
+        readonly _tag: Schema.Literal<"Interrupt">;
+        readonly fiberId: Schema.NullOr<Schema.Int>;
+    }>]>>;
+}>;
+/**
+ * A versioned structural Effect cause.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type TelemetryCause = typeof TelemetryCause.Type;
+/**
+ * Runtime schema for the operational log payload written to the journal.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const TelemetryLog: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly level: Schema.Literals<readonly ["All", "Fatal", "Error", "Warn", "Info", "Debug", "Trace", "None"]>;
+    readonly message: Schema.Unknown;
+    readonly annotations: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly cause: Schema.Struct<{
+        readonly version: Schema.Literal<1>;
+        readonly reasons: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+            readonly _tag: Schema.Literal<"Fail">;
+            readonly error: Schema.Unknown;
+        }>, Schema.Struct<{
+            readonly _tag: Schema.Literal<"Die">;
+            readonly defect: Schema.Unknown;
+        }>, Schema.Struct<{
+            readonly _tag: Schema.Literal<"Interrupt">;
+            readonly fiberId: Schema.NullOr<Schema.Int>;
+        }>]>>;
+    }>;
+    readonly fiberId: Schema.Int;
+    readonly traceId: Schema.optionalKey<Schema.String>;
+    readonly spanId: Schema.optionalKey<Schema.String>;
+    readonly timestamp: Schema.String;
+}>;
+/**
+ * Versioned operational log payload written to the journal.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type TelemetryLog = typeof TelemetryLog.Type;
+/**
+ * Installs a bounded, drop-on-overflow logger forwarder for one explicit run.
+ *
+ * Configuration is decoded before a worker starts. The callback reads the
+ * queue's remaining room first, snapshots and redacts a bounded DTO
+ * synchronously only when a slot is free, then performs only non-blocking
+ * queue admission. A record a saturated queue cannot take is counted and
+ * discarded without being snapshotted. Queue overflow, journal `Dropped` receipts, delivery failures,
+ * and journal defects each advance `Metric.droppedLogRecords`. The two failure
+ * paths also warn through the ambient loggers with a fixed code and run id,
+ * and the worker keeps draining. `Accepted` and `Duplicate` do not advance the
+ * counter. Admission receipts cannot identify later drop-oldest evictions of
+ * these records or report asynchronous persistence failures or shutdown losses.
+ * Closing the scope interrupts the worker and may drop records still queued
+ * behind an in-flight write without advancing the counter.
+ *
+ * The layer replaces the ambient logger set unless `mergeWithExisting` is
+ * `true`, and provides `MinimumLogLevel` only when `minimumLogLevel` is given,
+ * so an application that set that reference elsewhere keeps it.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerJournalForwarding: (options: Options) => Layer.Layer<never, InvalidJournalLoggerOptions, Journal.Journal>;
+export {};
+//# sourceMappingURL=JournalLogger.d.ts.map