@homeflare/alchemy 0.38.0 → 0.40.0

package/src/telemetry/http-client-sealing.test.ts

@@ -0,0 +1,82 @@
+/**
+ * The leak `layer.ts`'s own ★ describes: caddy's `admin-transport-scope.test.ts` measured that a
+ * provider Layer merging its own `HttpClient.HttpClient` straight into its output can shadow a
+ * sibling fetch-based provider's ambient client once both sit in the same `Layer.mergeAll`. This
+ * file is that same test shape, for `telemetryLayer`'s own (real, `fetch`-backed) `FetchHttpClient`.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientResponse from 'effect/unstable/http/HttpClientResponse';
+import { engineOver } from '../verify/fake-engine.ts';
+import { type FakeCollector, fakeCollector } from './fake-collector.ts';
+import { telemetryLayer } from './layer.ts';
+
+interface Probe extends Resource<'Test.TelemetrySealingProbe', { name: string }, { via: string }> {}
+const Probe = Resource<Probe>('Test.TelemetrySealingProbe');
+
+/** A sibling fetch-based provider (Forgejo, LiteLLM in the estate) — it just needs SOME
+ * `HttpClient.HttpClient` in scope, and reports which one it got. */
+const ProbeProvider = (vias: string[]) => {
+  const hit = Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const response = yield* client.get('http://sibling.invalid/probe');
+    vias.push(yield* response.text);
+  });
+  return Provider.succeed(Probe, {
+    read: () => Effect.as(hit, undefined),
+    reconcile: () => Effect.as(hit, { via: 'ambient' }),
+    delete: () => Effect.void,
+  });
+};
+
+/** Answers instantly and records that IT (not telemetry's own client) was the one asked. */
+const labeledClient = (label: string, seen: string[]): Layer.Layer<HttpClient.HttpClient> =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) => {
+      seen.push(label);
+      return Effect.succeed(HttpClientResponse.fromWeb(request, new Response(label)));
+    }),
+  );
+
+let otlp: FakeCollector | undefined;
+afterEach(() => {
+  otlp?.stop();
+  otlp = undefined;
+});
+
+describe('telemetryLayer HttpClient sealing', () => {
+  test("a sibling provider merged alongside it gets the AMBIENT client, never telemetry's own", async () => {
+    otlp = fakeCollector();
+    const vias: string[] = [];
+    const ambient = labeledClient('ambient', vias);
+    const engine = engineOver(
+      Layer.mergeAll(
+        ProbeProvider(vias),
+        telemetryLayer({ endpoints: { traces: `${otlp.url}/v1/traces` }, serviceName: 'test' }),
+      ).pipe(Layer.provideMerge(ambient)),
+    );
+    await engine.deploy(Probe('p', { name: 'sibling' }));
+    expect(vias.length).toBeGreaterThan(0);
+    expect(new Set(vias)).toEqual(new Set(['ambient']));
+  });
+
+  test("with no ambient client at all, the sibling fails rather than silently reaching telemetry's own", async () => {
+    otlp = fakeCollector();
+    const vias: string[] = [];
+    // ★ No `ambient` layer this time. If `telemetryLayer`'s `FetchHttpClient` ever leaked into its
+    //   own output, the sibling below would resolve it and this would succeed instead of throwing —
+    //   exactly the failure mode docs/telemetry-spike.md's first run hit by accident before `ambient` was added.
+    const engine = engineOver(
+      Layer.mergeAll(
+        ProbeProvider(vias),
+        telemetryLayer({ endpoints: { traces: `${otlp.url}/v1/traces` }, serviceName: 'test' }),
+      ),
+    );
+    await expect(engine.deploy(Probe('p', { name: 'sibling' }))).rejects.toThrow();
+  });
+});

package/src/telemetry/index.ts

@@ -0,0 +1,10 @@
+/**
+ * `@homeflare/alchemy/telemetry` — an OTLP tracing/logging/metrics Layer for a stack's own
+ * `providers`, off unless a consumer gives it real endpoints. See docs/telemetry.md for how a site
+ * file wires it up and docs/telemetry-spike.md for what a stack's `providers` Layer can and cannot
+ * capture (measured against alchemy 2.0.0-beta.79's own engine).
+ */
+export { telemetryLayer } from './layer.ts';
+export type { TelemetryEndpoints, TelemetryOptions } from './layer.ts';
+export { DROP, REDACTED, redactAttribute, wrapTracer } from './redact.ts';
+export type { RedactionPolicy } from './redact.ts';

package/src/telemetry/layer.test.ts

@@ -0,0 +1,204 @@
+/**
+ * `telemetryLayer` end to end, over the REAL engine (`verify/fake-engine.ts`'s `engineOver` — real
+ * `Alchemy.Stack` + `Plan.make` + `apply`, an in-memory state store, no network beyond the fake
+ * OTLP collector below) — not a hand-built stand-in. docs/telemetry-spike.md is the exploratory run this distills
+ * into permanent coverage; see it for what a stack's `providers` Layer can and cannot capture.
+ *
+ * ★ A REAL `FetchHttpClient` IS MERGED IN AS `ambient`, standing in for the platform layer a real
+ *   `alchemy.run.ts`'s `Stack.ts` provides underneath the merged `providers` — exactly the shape
+ *   admin-transport-scope.test.ts documents for caddy. Without it the fake provider's own
+ *   `HttpClient.HttpClient` requirement has nothing to resolve to, proving on its own (a thrown
+ *   "Service not found") that `telemetryLayer`'s SEALED internal client never leaks out —
+ *   http-client-sealing.test.ts makes that assertion explicit instead of relying on a crash.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+import { engineOver } from '../verify/fake-engine.ts';
+import { type FakeCollector, fakeCollector } from './fake-collector.ts';
+import { telemetryLayer } from './layer.ts';
+
+interface Thing extends Resource<'Test.TelemetryThing', { name: string }, { name: string }> {}
+const Thing = Resource<Thing>('Test.TelemetryThing');
+
+/** Calls `target` (`GET <target>/probe?token=…`, an `authorization` header set) inside its own
+ * span — a stand-in for a real provider's own `Effect.withSpan` around an SDK call. */
+const probingProvider = (target: string) =>
+  Provider.succeed(Thing, {
+    read: () => Effect.succeed(undefined),
+    reconcile: () =>
+      Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient;
+        const request = HttpClientRequest.get(`${target}/probe?token=SECRET123`).pipe(
+          HttpClientRequest.setHeader('authorization', 'Bearer sekrit'),
+        );
+        const response = yield* client.execute(request);
+        yield* response.text;
+        return { name: 'x' };
+      }).pipe(Effect.withSpan('probe.custom-span')),
+    delete: () => Effect.void,
+  });
+
+let collectors: FakeCollector[] = [];
+const collector = (): FakeCollector => {
+  const c = fakeCollector();
+  collectors.push(c);
+  return c;
+};
+/** A plain HTTP server for the redteam repros below — a real "target" a provider calls, not an OTLP
+ * collector, so it doesn't belong in `collectors`/`FakeCollector`. */
+let servers: Array<{ stop: () => void }> = [];
+afterEach(() => {
+  for (const c of collectors) c.stop();
+  collectors = [];
+  for (const s of servers) s.stop();
+  servers = [];
+});
+
+/** A target that answers every request 404 — a provider call that fails. */
+const notFound = (): string => {
+  const server = Bun.serve({
+    fetch: () => new Response('nope', { status: 404 }),
+    hostname: '127.0.0.1',
+    port: 0,
+  });
+  servers.push({ stop: () => void server.stop(true) });
+  return `http://127.0.0.1:${String(server.port)}`;
+};
+
+describe('telemetryLayer', () => {
+  test('sends nothing to any signal when every endpoint is left unconfigured', async () => {
+    const otlp = collector();
+    const target = collector();
+    const providers = Layer.mergeAll(
+      probingProvider(target.url),
+      telemetryLayer({ endpoints: {}, serviceName: 'test' }),
+    ).pipe(Layer.provideMerge(FetchHttpClient.layer));
+    await engineOver(providers).deploy(Thing('t', { name: 'x' }));
+    expect(otlp.requests.length).toBe(0);
+  });
+
+  test("provider spans, HttpClient client spans and alchemy's own engine spans all arrive", async () => {
+    const otlp = collector();
+    const target = collector();
+    const providers = Layer.mergeAll(
+      probingProvider(target.url),
+      telemetryLayer({ endpoints: { traces: `${otlp.url}/v1/traces` }, serviceName: 'test' }),
+    ).pipe(Layer.provideMerge(FetchHttpClient.layer));
+    await engineOver(providers).deploy(Thing('t', { name: 'x' }));
+    // The provider's own span, the HttpClient client span it made, and alchemy's OWN engine
+    // instrumentation (Apply.ts `instrumentLifecycle`/`apply`/`apply.resource`, Plan.ts
+    // `plan.make`) — measured together in docs/telemetry-spike.md's run against beta.79.
+    for (const name of [
+      'probe.custom-span',
+      'http.client GET',
+      'provider.create',
+      'apply',
+      'apply.resource',
+      'plan.make',
+    ]) {
+      expect(otlp.sawText(name)).toBe(true);
+    }
+  });
+
+  test('redteam PR 302 item 1: OTLP bodies are protobuf, not JSON', async () => {
+    const otlp = collector();
+    const target = collector();
+    const providers = Layer.mergeAll(
+      probingProvider(target.url),
+      telemetryLayer({ endpoints: { traces: `${otlp.url}/v1/traces` }, serviceName: 'test' }),
+    ).pipe(Layer.provideMerge(FetchHttpClient.layer));
+    await engineOver(providers).deploy(Thing('t', { name: 'x' }));
+    const request = otlp.at('/v1/traces')[0];
+    // VictoriaLogs/Metrics answer OTLP JSON with 400 "json encoding isn't supported" — only
+    // protobuf's `content-type` ingests on all three (docs/telemetry-spike.md's follow-up measurement).
+    expect(request?.headers.get('content-type')).toBe('application/x-protobuf');
+  });
+
+  test('redaction holds for a real HttpClient call: no query string, no headers, denylisted host blanked', async () => {
+    const otlp = collector();
+    const target = collector();
+    const targetHost = new URL(target.url).hostname;
+    const providers = Layer.mergeAll(
+      probingProvider(target.url),
+      telemetryLayer({
+        endpoints: { traces: `${otlp.url}/v1/traces` },
+        redaction: { denylist: [targetHost] },
+        serviceName: 'test',
+      }),
+    ).pipe(Layer.provideMerge(FetchHttpClient.layer));
+    await engineOver(providers).deploy(Thing('t', { name: 'x' }));
+    expect(otlp.sawText('SECRET123')).toBe(false);
+    expect(otlp.sawText('sekrit')).toBe(false);
+    expect(otlp.sawText('http.request.header')).toBe(false);
+    expect(otlp.sawText(targetHost)).toBe(false);
+    expect(otlp.sawText('<redacted>')).toBe(true);
+  });
+
+  test('redteam PR 302 items 2+3: a FAILED provider call no longer leaks the query secret or denylisted segments via exception/status', async () => {
+    const otlp = collector();
+    const targetUrl = notFound();
+    const host = new URL(targetUrl).hostname;
+    const secretUrl = `${targetUrl}/secret-site-abc123/probe?token=SECRET123`;
+    const failingProvider = Provider.succeed(Thing, {
+      read: () => Effect.succeed(undefined),
+      reconcile: () =>
+        Effect.gen(function* () {
+          const client = HttpClient.filterStatusOk(yield* HttpClient.HttpClient);
+          const response = yield* client.execute(HttpClientRequest.get(secretUrl));
+          yield* response.text;
+          return { name: 'x' };
+        }).pipe(Effect.withSpan('rt.provider-call')),
+      delete: () => Effect.void,
+    });
+    const providers = Layer.mergeAll(
+      failingProvider,
+      telemetryLayer({
+        endpoints: { traces: `${otlp.url}/v1/traces` },
+        redaction: { denylist: [host, 'secret-site-abc123'] },
+        serviceName: 'rt',
+      }),
+    ).pipe(Layer.provideMerge(FetchHttpClient.layer));
+    await engineOver(providers)
+      .deploy(Thing('t', { name: 'x' }))
+      .catch(() => undefined);
+    // Redteam measured this leaking via `exception.message`/`status.message`, computed from the exit's
+    // Cause at export time — after `wrapTracer`'s own hooks already ran. `redactedSerialization`
+    // (redact-serialization.ts) is the fix: it scrubs the wire-format `TraceData` one level deeper.
+    expect(otlp.sawText('SECRET123')).toBe(false);
+    expect(otlp.sawText('secret-site-abc123')).toBe(false);
+    expect(otlp.sawText(`${host}:`)).toBe(false);
+  });
+
+  test('redteam PR 302 items 2+3: a log line inside a span no longer leaks via the span event name', async () => {
+    const otlp = collector();
+    const secretUrl = 'http://private.example.test/secret-site-abc123/x?token=SECRET123';
+    const loggingProvider = Provider.succeed(Thing, {
+      read: () => Effect.succeed(undefined),
+      reconcile: () =>
+        Effect.logWarning(`calling ${secretUrl}`).pipe(
+          Effect.as({ name: 'x' }),
+          Effect.withSpan('rt.logging'),
+        ),
+      delete: () => Effect.void,
+    });
+    const providers = Layer.mergeAll(
+      loggingProvider,
+      telemetryLayer({
+        endpoints: { traces: `${otlp.url}/v1/traces` },
+        redaction: { denylist: ['private.example.test', 'secret-site-abc123'] },
+        serviceName: 'rt',
+      }),
+    );
+    await engineOver(providers).deploy(Thing('t', { name: 'x' }));
+    // effect's default `tracerLogger` turns this into a span EVENT whose NAME is the log message —
+    // `wrapTracer.event()` redacts the attributes but passed the name straight through before this fix.
+    expect(otlp.sawText('SECRET123')).toBe(false);
+    expect(otlp.sawText('secret-site-abc123')).toBe(false);
+  });
+});

package/src/telemetry/layer.ts

@@ -0,0 +1,152 @@
+/**
+ * A Layer factory for OTLP tracing/logging/metrics, built for a stack's own `providers` Layer
+ * rather than the CLI-wide install alchemy's own `Telemetry/Layer.ts` does (`src/Telemetry/
+ * Layer.ts:13-15`, hard-coded to `otel.alchemy.run` with no override). Nothing here calls that
+ * endpoint or knows it exists.
+ *
+ * ⛔ NO DEFAULTS THAT POINT ANYWHERE. `endpoints` is `{}` by default and `telemetryLayer` resolves
+ *   to `Layer.empty` when every entry is `undefined` — see layer.test.ts's own "nothing sent
+ *   when unconfigured". A consumer wires actual hosts from ITS OWN site config; see docs/telemetry.md.
+ * ★ SEALED TRANSPORT — the caddy lesson (kit PR 293, admin.ts's own ⛔): merging a layer that still
+ *   requires `HttpClient.HttpClient` into a stack's `providers` would let this module's own
+ *   `FetchHttpClient` shadow a sibling fetch-based provider's client once both are merged into the
+ *   same `Layer.mergeAll`. `Layer.provide` (not `Layer.provideMerge`) twice below feeds
+ *   `FetchHttpClient`/`OtlpSerialization` to the OTLP layers and returns ONLY their own output —
+ *   `HttpClient.HttpClient` never appears in what `telemetryLayer` hands back. See
+ *   http-client-sealing.test.ts.
+ * ★ PER-SIGNAL URLS, NOT ONE BASE URL. effect's own `Otlp.layer`/`layerJson` take a single
+ *   `baseUrl` and post to `<baseUrl>/v1/{traces,metrics,logs}` — fine when one collector serves all
+ *   three, wrong for Victoria's split binaries (VictoriaTraces/Logs/Metrics on three different
+ *   ports/paths — docs/telemetry.md has the exact paths). `OtlpTracer`/`OtlpLogger`/`OtlpMetrics`
+ *   each take their own `url` and post to it verbatim (OtlpExporter.ts `make`: `HttpClientRequest.
+ *   post(options.url, …)`, no suffix appended) — exactly the shape three independent endpoints need.
+ * ⛔ PROTOBUF, NOT JSON (redteam PR 302 CRITICAL item 1, 2026-09-26, measured against the pinned
+ *   binaries in homeflare-mini's `src/obs`): VictoriaLogs 1.52.0 and VictoriaMetrics 1.151.0 both
+ *   answer OTLP/HTTP JSON with `400 "json encoding isn't supported for opentelemetry format"` —
+ *   effect's exporter treats a 400 as non-transient, drops the batch silently and disables itself for
+ *   60s at debug-only log level, so a JSON-encoded consumer sees traces (VictoriaTraces alone
+ *   tolerates JSON) but never logs or metrics, with no visible error. `redactedSerialization` below
+ *   provides `OtlpSerialization.layerProtobuf`, which all three ingested in the same measurement.
+ */
+import type * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Logger from 'effect/Logger';
+import * as LogLevel from 'effect/LogLevel';
+import * as Tracer from 'effect/Tracer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { OtlpExporter, OtlpLogger, OtlpMetrics, OtlpTracer } from 'effect/unstable/observability';
+import { redactedSerialization } from './redact-serialization.ts';
+import { type RedactionPolicy, wrapTracer } from './redact.ts';
+
+/** Full OTLP/HTTP endpoint per signal — e.g. `http://victoria.example.test:10428/insert/opentelemetry/v1/traces`. Any entry left `undefined` sends nothing for that signal. */
+export interface TelemetryEndpoints {
+  readonly traces?: string;
+  readonly logs?: string;
+  readonly metrics?: string;
+}
+
+export interface TelemetryOptions {
+  readonly endpoints: TelemetryEndpoints;
+  /** OTLP `service.name` — required, since an unnamed service in a shared Victoria instance is unusable. */
+  readonly serviceName: string;
+  readonly serviceVersion?: string;
+  /** Extra OTLP resource attributes (e.g. `{ "deployment.environment": "prod" }`). */
+  readonly resourceAttributes?: Record<string, unknown>;
+  readonly redaction?: RedactionPolicy;
+  /**
+   * How often a signal flushes its buffer.
+   * @default '1 second' — short on purpose: alchemy invocations are CLI runs, often shorter than a
+   * typical OTLP batch interval, so the export must fire well before the process could exit. The
+   * scope's own shutdown flush (`Exporter.layerFlusher`) is the backstop for whatever this interval
+   * misses; docs/telemetry-spike.md measured both paths.
+   */
+  readonly exportInterval?: Duration.Input;
+  /**
+   * Floor below which a log record never reaches the OTLP logger.
+   * @default 'Info' — redteam PR 302 IMPORTANT item 4: the `alchemy` CLI sets the GLOBAL minimum
+   * log level to Debug (`GlobalLog.ts`), and `OtlpLogger` has no floor of its own, so without one
+   * every Debug-level record (a provider's own connection-string/config dump, annotation noise)
+   * would ship — once `redactedSerialization` fixed item 1's silent-JSON-failure, they would
+   * actually start arriving. This floor applies ONLY to what THIS layer exports; a consumer's
+   * console/file loggers keep whatever level the CLI's own global setting gives them, since
+   * `logsMinimumLevel` filters after `Logger.layer`'s `mergeWithExisting: true` has already added
+   * this logger alongside them, not by lowering that global setting.
+   */
+  readonly logsMinimumLevel?: LogLevel.LogLevel;
+}
+
+// ⚠️ `exactOptionalPropertyTypes` — omit a key entirely rather than set it `undefined`, or the
+//   OTLP layers' own `{ readonly attributes?: X }` (no `| undefined` in their own signatures)
+//   rejects the object.
+const resourceOf = (options: TelemetryOptions) => ({
+  serviceName: options.serviceName,
+  ...(options.serviceVersion !== undefined ? { serviceVersion: options.serviceVersion } : {}),
+  ...(options.resourceAttributes !== undefined ? { attributes: options.resourceAttributes } : {}),
+});
+
+/**
+ * `OtlpTracer.layer`'s own composition (OtlpTracer.ts: `flow(make, Layer.effect(Tracer.Tracer),
+ * Layer.provideMerge(Exporter.layerFlusher))`), with `wrapTracer` inserted between `make` and
+ * `Layer.effect` so every span this tracer creates is redacted before anything else can see it.
+ */
+const tracerLayer = (url: string, options: TelemetryOptions, exportInterval: Duration.Input) =>
+  Layer.effect(
+    Tracer.Tracer,
+    Effect.map(OtlpTracer.make({ exportInterval, resource: resourceOf(options), url }), (inner) =>
+      wrapTracer(inner, options.redaction ?? {}),
+    ),
+  ).pipe(Layer.provideMerge(OtlpExporter.layerFlusher));
+
+/**
+ * `OtlpLogger.layer`'s own composition (`Logger.layer([make(options)], { mergeWithExisting: true })
+ * .pipe(Layer.provideMerge(Exporter.layerFlusher))`), with a level floor inserted between `make` and
+ * `Logger.layer` — see `TelemetryOptions.logsMinimumLevel`'s own doc for why.
+ */
+const loggerLayer = (url: string, options: TelemetryOptions, exportInterval: Duration.Input) => {
+  const floor = options.logsMinimumLevel ?? 'Info';
+  return Logger.layer(
+    [
+      Effect.map(OtlpLogger.make({ exportInterval, resource: resourceOf(options), url }), (inner) =>
+        Logger.make((record) =>
+          LogLevel.isGreaterThanOrEqualTo(record.logLevel, floor) ? inner.log(record) : undefined,
+        ),
+      ),
+    ],
+    { mergeWithExisting: true },
+  ).pipe(Layer.provideMerge(OtlpExporter.layerFlusher));
+};
+
+/**
+ * The Layer a consumer stack merges into its own `providers` — see docs/telemetry.md for how a
+ * site file wires real hosts in, and docs/telemetry-spike.md for what a stack's `providers` Layer does and does
+ * not carry a span for.
+ *
+ * ⚠️ FIXED THREE-ARG `Layer.mergeAll`, NOT AN ARRAY `.reduce`. Every signal slot is filled — with
+ *   the real per-signal layer when its endpoint is set, `Layer.empty` when it is not — instead of
+ *   building a variable-length array and folding it with `Layer.merge`. `Layer<in ROut, …>`
+ *   declares its success channel CONTRAVARIANT, and once a fold's accumulator needs an explicit
+ *   annotation to type-check under this repo's `exactOptionalPropertyTypes`, TS's overload
+ *   resolution for `Layer.provide`/`Layer.merge` starts inferring `unknown` for that channel and
+ *   then fails `unknown` against `never` (measured 2026-09-26, TS2769). `Layer.mergeAll`'s own
+ *   fixed-arity overload — the exact shape alchemy's own `Telemetry/Layer.ts` uses for its three
+ *   signals — infers cleanly with no annotation at all.
+ */
+export const telemetryLayer = (options: TelemetryOptions): Layer.Layer<never> => {
+  const { traces, logs, metrics } = options.endpoints;
+  if (traces === undefined && logs === undefined && metrics === undefined) return Layer.empty;
+  // Default declared here, not in the options' type, so every call site above stays a concrete
+  // `Duration.Input` — `exactOptionalPropertyTypes` rejects passing `undefined` through to the
+  // OTLP layers' own `exportInterval?: Duration.Input` (no `| undefined` in their signatures).
+  const exportInterval: Duration.Input = options.exportInterval ?? '1 second';
+  const tracer = traces === undefined ? Layer.empty : tracerLayer(traces, options, exportInterval);
+  const logger = logs === undefined ? Layer.empty : loggerLayer(logs, options, exportInterval);
+  const meter =
+    metrics === undefined
+      ? Layer.empty
+      : OtlpMetrics.layer({ exportInterval, resource: resourceOf(options), url: metrics });
+  return Layer.mergeAll(tracer, logger, meter).pipe(
+    Layer.provide(redactedSerialization(options.redaction ?? {})),
+    Layer.provide(FetchHttpClient.layer),
+  );
+};

package/src/telemetry/redact-serialization.ts

@@ -0,0 +1,178 @@
+/**
+ * Free-text OTLP redaction applied at `OtlpSerialization` — the ONE place every span/log field
+ * reaches the wire, right before HTTP body encoding. `redact.ts`'s `wrapTracer` only sees what a
+ * caller passes to `Span.attribute()`/`Span.event()`; two real fields never go through either hook:
+ *
+ * - `status.message` and the `exception.*` event attributes `OtlpTracer`'s own `makeOtlpSpan` builds
+ *   from `Cause.prettyErrors(exit.cause)` — computed at export time, inside effect's tracer, AFTER
+ *   `wrapTracer.end()` has already handed the exit straight to `real.end()`.
+ * - a log line inside a span, turned into a span event by effect's default `tracerLogger` — the log
+ *   message becomes the event NAME (not an attribute `wrapTracer.event()` redacts), and its
+ *   `effect.cause` attribute is free text `redactAttribute`'s key-based rules never recognize.
+ *
+ * Redteam finding (PR 302, 2026-09-26): a provider GET that 404'd exported `exception.message =
+ * "... 404 GET http://host/secret-site-abc123/probe?token=SECRET123"` unredacted — the query, the
+ * denylisted path segment and the denylisted host all went out. A `logWarning` inside a span leaked
+ * the same way through the event name.
+ *
+ * ⚠️ SUBSTRING MATCH, NOT SEGMENT MATCH. `redactAttribute` compares a denylist entry against a whole
+ *   `/`-bounded URL segment on purpose (`redact.ts`'s own ⚠️: `"db"` must not blank `"db1.example.
+ *   test"`). Free text has no segment boundaries — a log message or a formatted `Cause` embeds a
+ *   token in prose — so `scrubText` matches a denylist entry as a literal substring ANYWHERE in the
+ *   string. This is strictly broader than the structured rules, so it also closes the `server.
+ *   address` bare-hostname and legacy `http.url` gaps (redteam MINOR item 5) as a side effect: a
+ *   denylisted hostname is a substring match wherever it appears, URL-shaped or not. The tradeoff a
+ *   caller accepts by naming a short, common word in `denylist` is over-redaction, never a leak.
+ */
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { OtlpSerialization } from 'effect/unstable/observability';
+import type { OtlpLogger, OtlpResource, OtlpTracer } from 'effect/unstable/observability';
+import { REDACTED, type RedactionPolicy } from './redact.ts';
+
+const URL_PATTERN = /https?:\/\/[^\s"'<>)]+/g;
+
+/** Strips an embedded URL's query/hash and blanks its denylisted host/path segments — `redact.ts`'s
+ * `url.full` case, reused here because a URL can appear inside prose, not just as its own attribute. */
+const scrubUrl = (raw: string, denylist: ReadonlySet<string>): string => {
+  try {
+    const url = new URL(raw);
+    const host = denylist.has(url.hostname) ? REDACTED : url.host;
+    const path = url.pathname
+      .split('/')
+      .map((segment) => (denylist.has(segment) ? REDACTED : segment))
+      .join('/');
+    return `${url.protocol}//${host}${path}`;
+  } catch {
+    return raw; // Matched the URL_PATTERN regex but `URL` still rejects it — leave verbatim.
+  }
+};
+
+/** Redacts one piece of free text: every embedded URL loses its query string and denylisted
+ * segments, then every denylist entry is blanked as a substring anywhere else in the text. */
+export const scrubText = (text: string, policy: RedactionPolicy): string => {
+  const denylist = policy.denylist ?? [];
+  const denylistSet = new Set(denylist);
+  let out = text.replace(URL_PATTERN, (match) => scrubUrl(match, denylistSet));
+  for (const token of denylist) {
+    if (token.length === 0) continue; // an empty entry would blank every character boundary
+    out = out.split(token).join(REDACTED);
+  }
+  return out;
+};
+
+/** Walks one OTLP `AnyValue`'s string leaves (`stringValue`, and recursively through `arrayValue`/
+ * `kvlistValue`) — the union effect's OTLP encoders use for every attribute and log body value. */
+const scrubValue = (
+  value: OtlpResource.AnyValue,
+  policy: RedactionPolicy,
+): OtlpResource.AnyValue => {
+  if (typeof value.stringValue === 'string')
+    return { ...value, stringValue: scrubText(value.stringValue, policy) };
+  if (value.arrayValue !== undefined) {
+    return {
+      ...value,
+      arrayValue: { values: value.arrayValue.values.map((v) => scrubValue(v, policy)) },
+    };
+  }
+  if (value.kvlistValue !== undefined) {
+    return {
+      ...value,
+      kvlistValue: {
+        values: value.kvlistValue.values.map((kv) => ({
+          key: kv.key,
+          value: scrubValue(kv.value, policy),
+        })),
+      },
+    };
+  }
+  return value; // boolValue / intValue / doubleValue / bytesValue — never free text.
+};
+
+const scrubKeyValues = (
+  attributes: ReadonlyArray<OtlpResource.KeyValue>,
+  policy: RedactionPolicy,
+): Array<OtlpResource.KeyValue> =>
+  attributes.map((kv) => ({ key: kv.key, value: scrubValue(kv.value, policy) }));
+
+/** `TraceData` after every span's name, attributes, events (including the `exception.*` ones
+ * `makeOtlpSpan` builds from the exit), status message and link attributes have been scrubbed. */
+export const redactTraceData = (
+  data: OtlpTracer.TraceData,
+  policy: RedactionPolicy,
+): OtlpTracer.TraceData => ({
+  resourceSpans: data.resourceSpans.map((resourceSpan) => ({
+    ...resourceSpan,
+    scopeSpans: resourceSpan.scopeSpans.map((scopeSpan) => ({
+      ...scopeSpan,
+      spans: scopeSpan.spans.map((span) => ({
+        ...span,
+        attributes: scrubKeyValues(span.attributes, policy),
+        events: span.events.map((event) => ({
+          ...event,
+          attributes: scrubKeyValues(event.attributes, policy),
+          name: scrubText(event.name, policy),
+        })),
+        links: span.links.map((link) => ({
+          ...link,
+          attributes: scrubKeyValues(link.attributes, policy),
+        })),
+        name: scrubText(span.name, policy),
+        status:
+          span.status.message === undefined
+            ? span.status
+            : { ...span.status, message: scrubText(span.status.message, policy) },
+      })),
+    })),
+  })),
+});
+
+type LogRecord = NonNullable<
+  OtlpLogger.LogsData['resourceLogs'][number]['scopeLogs'][number]['logRecords']
+>[number];
+
+// ⚠️ `exactOptionalPropertyTypes` — `body` is `AnyValue?` with no `| undefined` in its own
+//   signature (matches `layer.ts`'s own `resourceOf` note), so an absent one is OMITTED, not set to
+//   `undefined`, or this object-literal return fails to type-check against `ILogRecord`.
+const scrubLogRecord = (record: LogRecord, policy: RedactionPolicy): LogRecord => ({
+  ...record,
+  attributes: scrubKeyValues(record.attributes, policy),
+  ...(record.body !== undefined ? { body: scrubValue(record.body, policy) } : {}),
+});
+
+/** `LogsData` after every log record's attributes and body have been scrubbed — the fix for redteam
+ * item 4's "logs ship unredacted": `log.error` (`Cause.pretty`) and the message body are free text. */
+export const redactLogsData = (
+  data: OtlpLogger.LogsData,
+  policy: RedactionPolicy,
+): OtlpLogger.LogsData => ({
+  resourceLogs: data.resourceLogs.map((resourceLog) => ({
+    ...resourceLog,
+    scopeLogs: resourceLog.scopeLogs.map((scopeLog) => ({
+      ...scopeLog,
+      // Same `exactOptionalPropertyTypes` reasoning as `scrubLogRecord` — omit `logRecords`
+      // entirely rather than assign it `undefined` when the source had none.
+      ...(scopeLog.logRecords !== undefined
+        ? { logRecords: scopeLog.logRecords.map((record) => scrubLogRecord(record, policy)) }
+        : {}),
+    })),
+  })),
+});
+
+/**
+ * Wraps the real `OtlpSerialization` so `telemetryLayer` gets this free-text pass on every signal
+ * with no separate wiring at each call site — `layer.ts` provides this in place of a bare
+ * `OtlpSerialization.layerProtobuf`. Metrics pass through untouched: they carry numeric data points
+ * keyed by `Metric.Metric.AttributeSet`, not provider-supplied free text.
+ */
+export const redactedSerialization = (
+  policy: RedactionPolicy,
+): Layer.Layer<OtlpSerialization.OtlpSerialization> =>
+  Layer.effect(
+    OtlpSerialization.OtlpSerialization,
+    Effect.map(OtlpSerialization.OtlpSerialization, (inner) => ({
+      logs: (data: OtlpLogger.LogsData) => inner.logs(redactLogsData(data, policy)),
+      metrics: inner.metrics,
+      traces: (data: OtlpTracer.TraceData) => inner.traces(redactTraceData(data, policy)),
+    })),
+  ).pipe(Layer.provide(OtlpSerialization.layerProtobuf));