effect-cf 0.42.1 → 0.44.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # effect-cf
 
+## 0.44.0
+
+### Minor Changes
+
+- [#178](https://github.com/danieljvdm/effect-cf/pull/178) [`9551619`](https://github.com/danieljvdm/effect-cf/commit/95516194672b7245ce3db77d3ee3aa0359901ebc) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Preserve more Effect telemetry in Cloudflare's native spans: bounded JSON strings for structured attributes, searchable Effect and parent IDs, span kind, up to eight link ID pairs, and safe failure/defect/interruption classification. The `effect.*` attribute namespace is now reserved for adapter metadata; move application annotations using that prefix to an application namespace for native export.
+
+  Add `CloudflareTracer.layerWith({ formatError, spanEvents })` while retaining `CloudflareTracer.layer`. Error details require a caller-supplied sanitizing formatter. Event forwarding is off by default; opting in emits bounded structured logs in the owning span's async context and adds log volume. Unsupported or oversized metadata and formatter/logging failures cannot fail application operations. Correlation does not change Cloudflare trace IDs, parentage, native status, or graph links.
+
+## 0.43.0
+
+### Minor Changes
+
+- [#174](https://github.com/danieljvdm/effect-cf/pull/174) [`10cd4a9`](https://github.com/danieljvdm/effect-cf/commit/10cd4a9cd162ef38599a53c772cdb19f8e241605) Thanks [@danieljvdm](https://github.com/danieljvdm)! - ## effect-cf
+
+  Require Effect `^4.0.0-rc.115` and matching `@effect/sql-d1`, `@effect/sql-pg`, and
+  `@effect/sql-sqlite-do` peers. Upgrade the Effect family together.
+
+  Preserve Cloudflare span context with Effect's new fiber representation and close
+  request scopes when HEAD or status 204, 205, or 304 omits an Effect streaming body.
+  Omitted streams are not started, and request resources and telemetry are finalized.
+
+  HyperdrivePg now uses Effect's native PostgreSQL driver. Consumers must account for
+  its new result codecs (`int8` becomes `bigint`, dates become strings, and timestamps
+  become epoch milliseconds), wrap JSON parameters with `sql.json`, and submit one
+  statement per query. The driver enables named prepared statements by default;
+  pass `prepare: false` for poolers that cannot preserve them.
+
+  ## effect-webtransport
+
+  Require Effect `^4.0.0-rc.115` and migrate the Socket adapter to scoped readers and
+  writers. Replace `socket.run(handler)` with a scoped acquisition of `socket.reader`
+  and a loop over `reader.pull`. Use `writer.write` and `writer.writeAll` after
+  acquiring `socket.writer`.
+
+  Reads now follow consumer demand without dispatching a fiber per chunk. Reader
+  scope cleanup still releases stream locks, sends FIN on success, and aborts writes
+  on failure. Releasing a writer scope half-closes the write side. Interrupting a
+  batch stops unsent frames while leaving the socket available for later writes.
+
+  Every close, including peer FIN, fails with a `SocketError` containing
+  `SocketCloseError`. Remove `closeCodeIsError`, `FromBidirectionalStreamOptions`,
+  and `defaultCloseCodeIsError`; handle close reasons in the read loop and use
+  `Effect.retry` around the scoped loop to reconnect. WebSocket fallback options now
+  accept `highWaterMark`.
+
+  MessagePack serialization was removed upstream. Use `RpcSerialization.layerNdjson`
+  or `RpcSerialization.layerSchemaBinary()` for the byte-stream transport.
+
 ## 0.42.1
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 Cloudflare entrypoints and bindings as Effect services.
 
 ```sh
-npm install effect-cf "effect@^4.0.0-rc.112"
+npm install effect-cf "effect@^4.0.0-rc.115"
 ```
 
 The repository tests against workerd `1.20260825.1` and `@cloudflare/workers-types@5.20260825.1`. Use `compatibility_date: "2026-08-25"` in Wrangler.
@@ -120,12 +120,82 @@ Nested spans, concurrent fibers, and resumed work restore the appropriate span
 context. Cloudflare handles sampling and export; no exporter endpoint or flush
 is needed.
 
-String, number, and boolean attributes are forwarded. Other attributes, span
-events, and links remain Effect-local. Completion is recorded as `effect.exit`
-with `success`, `failure`, or `interrupted`; Cloudflare does not expose a setter
-for native outcome status. Effect IDs remain separate from Cloudflare's opaque
-trace/span IDs. Explicit external parents cannot join a Cloudflare trace by ID,
-and `root: true` starts under the invocation's captured context.
+Strings, finite numbers, and booleans are forwarded as native scalars. Null,
+plain objects (including null-prototype objects), and dense arrays are encoded
+as JSON strings under the original attribute key. For example,
+`{ routes: ["email", "sms"], retry: false }` becomes the string
+`'{"routes":["email","sms"],"retry":false}'`, not native object/array metadata.
+There is no flattening or generated attribute key per nested field.
+
+Each encoded value is limited to **4096 UTF-8 bytes, four container levels, and
+64 values including the root**. Keys and JSON punctuation count toward bytes.
+The entire value is dropped if it exceeds a limit or contains unsupported input:
+cycles, accessors, undefined, non-finite numbers, bigint, symbols, functions,
+class instances (including errors and Effect `Redacted`), or sparse arrays.
+Only own enumerable string keys and array elements are included; getters and
+`toJSON` are never called. Serialization/host errors are ignored. Dropped updates
+leave any previous native attribute value intact. Original Effect-local values
+remain available. These are adapter limits; Cloudflare can apply further limits.
+Existing scalar strings are forwarded unchanged.
+
+The adapter reserves **`effect.*`**; caller attributes in that namespace remain
+Effect-local and cannot overwrite its metadata. Existing annotations using that
+prefix should move to an application namespace if they need native export.
+
+| Native attribute                                  | Representation                                                                                               |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `effect.trace_id`, `effect.span_id`               | Effect IDs, distinct from Cloudflare's opaque IDs                                                            |
+| `effect.parent.trace_id`, `effect.parent.span_id` | Effect parent IDs, when present                                                                              |
+| `effect.span.kind`                                | Effect's internal/server/client/producer/consumer kind                                                       |
+| `effect.span.links`                               | JSON array of `{ traceId, spanId }` for the first eight links at span end, including `addLinks` updates      |
+| `effect.span.links_dropped`                       | Omitted link count; the candidate array is dropped whole if it exceeds the JSON limits                       |
+| `effect.exit`                                     | `success`, `failure`, or `interrupted`                                                                       |
+| `effect.error.kind`                               | On failure: `failure`, `defect`, `mixed` (typed failures and defects), or `interrupted` (interruptions only) |
+
+Link attributes remain local. Correlation and error metadata add no spans or
+logs. No Cause, error payload, message, stack, schema input, or request body is
+automatically serialized for errors. Optional diagnostics require an explicit
+sanitizing formatter:
+
+```ts
+const tracing = CloudflareTracer.layerWith({
+  formatError: () => ({
+    type: "OperationFailed",
+    message: "The operation could not complete",
+  }),
+  spanEvents: true,
+});
+
+export default Worker.make(Layer.empty, {
+  eventLayer: tracing,
+  fetch: Effect.sync(() => new Response("Hello")).pipe(Effect.withSpan("greet")),
+});
+```
+
+`formatError` receives the failed span's Cause, including interruption, and may
+return `undefined` or sanitized `type`/`message` strings. These become
+`effect.error.type` and `effect.error.message`; each is dropped above 4096 UTF-8
+bytes. Extra returned fields are ignored. The formatter runs once at end only
+for sampled failed spans; formatter exceptions cannot change the application exit.
+Do not pass through raw errors or use a full Cause formatter here.
+
+`spanEvents` defaults to `false`. Opting in forwards at most the first **16 event
+attempts per span** through `console.log` in that span's captured async context.
+Each structured log contains `effect.event` (the original name),
+`effect.event.time_unix_nano` (the original bigint timestamp as a decimal string),
+`effect.trace_id`, `effect.span_id`, and nested `attributes`. The complete log
+uses the same JSON limits, including its envelope; an unsupported/oversized log
+is dropped whole and still consumes one attempt. Unsampled and ended spans emit
+no event logs. Reentrant forwarding and console failures are suppressed. This
+adds log volume and may increase Observability costs; log retention/export also
+depends on your Cloudflare logging configuration.
+
+This is searchable correlation and optional **log forwarding**. Cloudflare's
+custom span API does not expose native IDs, manual parent wiring, an outcome
+setter, `addLink`, or `addEvent`. It does not create native graph edges, clickable
+links, native OTel span events, or cross-system propagation. Explicit external
+parents cannot join a Cloudflare trace by ID, and `root: true` starts under the
+invocation's captured context.
 
 This layer replaces the active Effect tracer. When combining it with
 `CloudflareOtlp`, select only `logs` and/or `metrics` in the OTLP layer. See

package/dist/AnalyticsEngine.mjs

@@ -235,9 +235,9 @@ const makeClient = (definition, defaults) => (dataset) => {
 	};
 };
 const queryConfig = (options) => Config.all({
-	accountId: options?.accountId ?? Config.string("CLOUDFLARE_ACCOUNT_ID"),
-	apiToken: options?.apiToken ?? Config.redacted("CLOUDFLARE_API_TOKEN"),
-	apiBaseUrl: options?.apiBaseUrl ?? Config.string("CLOUDFLARE_API_BASE_URL").pipe(Config.withDefault(defaultQueryApiBaseUrl))
+	accountId: options?.accountId ?? Config.String("CLOUDFLARE_ACCOUNT_ID"),
+	apiToken: options?.apiToken ?? Config.Redacted("CLOUDFLARE_API_TOKEN"),
+	apiBaseUrl: options?.apiBaseUrl ?? Config.String("CLOUDFLARE_API_BASE_URL").pipe(Config.withDefault(defaultQueryApiBaseUrl))
 });
 const queryLayer = (tag, definition) => Layer.effect(tag, makeQueryClient(definition));
 const layerFetch = (tag, definition) => queryLayer(tag, definition).pipe(Layer.provide(FetchHttpClient.layer));

package/dist/CloudflareTracer.d.mts

@@ -1,20 +1,65 @@
 import * as Layer from "effect/Layer";
+import * as Cause from "effect/Cause";
 declare namespace CloudflareTracer_d_exports {
-  export { layer };
+  export { ErrorDetails, LayerOptions, layer, layerWith };
 }
+/** Explicitly sanitized diagnostics. No error payload or Cause is serialized automatically. */
+interface ErrorDetails {
+  readonly type?: string;
+  readonly message?: string;
+}
+interface LayerOptions {
+  /**
+   * Called once for a sampled failed span, including interruption. Return only
+   * safe diagnostic strings; each is dropped if over 4096 UTF-8 bytes. Throws
+   * are ignored. Defaults to classification only, without messages or stacks.
+   */
+  readonly formatError?: (cause: Cause.Cause<unknown>) => ErrorDetails | undefined;
+  /**
+   * Forward the first 16 event attempts per sampled span as structured console
+   * logs in its captured context. Defaults to false. Each complete log must fit
+   * the JSON limits documented on `layer`. This adds billable log volume.
+   */
+  readonly spanEvents?: boolean;
+}
+/**
+ * Configures the per-invocation native tracer. See `layer` for representations
+ * and limits. Options do not change Cloudflare sampling or native trace IDs.
+ */
+declare const layerWith: (options?: LayerOptions) => Layer.Layer<never>;
 /**
- * Sends Effect spans to Cloudflare Workers Observability using the runtime's
- * custom span API. Build this layer inside each invocation, for example with
- * `Worker.make(Services, { eventLayer: CloudflareTracer.layer, fetch })`.
- * It captures the invocation's async context and must not be cached across requests.
+ * Sends Effect spans to Cloudflare Workers Observability. Build inside each
+ * invocation, e.g. `Worker.make(Services, { eventLayer: CloudflareTracer.layer, fetch })`.
+ * Captures async context; never cache the built layer across requests.
+ *
+ * Strings, finite numbers and booleans remain native scalars. Null, plain
+ * objects and arrays become JSON strings under their original keys, limited to
+ * 4096 UTF-8 bytes, 4 container levels and 64 values including the root. Values
+ * exceeding any limit are dropped whole, as are cycles, accessors, unsupported
+ * values (including undefined, bigint, functions, class instances and Redacted)
+ * or serialization failures. No getters or toJSON methods are invoked. Only
+ * own enumerable string keys / dense array elements are encoded. No flattening.
+ *
+ * `effect.*` is reserved for this adapter; caller attributes in that namespace
+ * remain local. `effect.trace_id`, `effect.span_id`, `effect.parent.trace_id`,
+ * `effect.parent.span_id` and `effect.span.kind` describe Effect identities.
+ * At end, `effect.span.links` contains JSON for the first 8 linked Effect ID
+ * pairs (including addLinks updates), bounded by the same JSON limits, with
+ * omitted count in `effect.span.links_dropped`. Link attributes stay local.
+ *
+ * `effect.exit` is success/failure/interrupted. Failed spans also have
+ * `effect.error.kind`: failure, defect, mixed (failures + defects), or interrupted.
+ * No error payloads, messages or stacks are exported unless formatError opts in.
+ * Events remain local unless `layerWith({ spanEvents: true })` opts into logs.
+ * Local NativeSpan storage retains original attributes, links and events.
  *
- * Enable `observability.traces.enabled` in Wrangler. Cloudflare owns sampling
- * and export; no OTLP exporter or flush is required. Scalar attributes are
- * forwarded; other attributes, events, and links remain Effect-local. Completion
- * is recorded as `effect.exit`, since Cloudflare has no outcome-setting API.
- * Effect trace/span IDs remain independent of Cloudflare's opaque IDs. External
- * parents and `root: true` cannot override the invocation's Cloudflare trace.
+ * Enable observability.traces.enabled in Wrangler. Cloudflare owns sampling
+ * and export; no OTLP exporter or flush is required. Metadata creates no extra
+ * spans. Cloudflare IDs remain opaque and distinct: this provides lookup, not
+ * native graph links or cross-system propagation. There is no native outcome
+ * setter or addEvent API. External parents and root: true cannot override the
+ * invocation's Cloudflare trace. See Cloudflare's custom spans documentation.
  */
 declare const layer: Layer.Layer<never>;
 //#endregion
-export { CloudflareTracer_d_exports, layer };
+export { CloudflareTracer_d_exports, ErrorDetails, LayerOptions, layer, layerWith };

package/dist/CloudflareTracer.mjs

@@ -9,44 +9,163 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { tracing } from "cloudflare:workers";
 import * as Tracer from "effect/Tracer";
 //#region src/CloudflareTracer.ts
-var CloudflareTracer_exports = /* @__PURE__ */ __exportAll({ layer: () => layer });
+var CloudflareTracer_exports = /* @__PURE__ */ __exportAll({
+	layer: () => layer,
+	layerWith: () => layerWith
+});
+const maxBytes = 4096;
+const maxLinks = 8;
+const maxEvents = 16;
+const textEncoder = new TextEncoder();
+const bestEffort = (f) => {
+	try {
+		f();
+	} catch {}
+};
+const encodeJson = (value) => {
+	let bytes = 0;
+	let values = 0;
+	const parts = [];
+	const ancestors = /* @__PURE__ */ new Set();
+	const append = (part) => {
+		bytes += textEncoder.encode(part).byteLength;
+		if (bytes > maxBytes) return false;
+		parts.push(part);
+		return true;
+	};
+	const string = (text) => text.length <= maxBytes && append(JSON.stringify(text));
+	const visit = (current, depth) => {
+		if (++values > 64) return false;
+		if (Predicate.isString(current)) return string(current);
+		if (current === null || Predicate.isBoolean(current)) return append(String(current));
+		if (Predicate.isNumber(current)) return Number.isFinite(current) && append(String(current));
+		if (!Predicate.isObjectOrArray(current) || depth === 4 || ancestors.has(current)) return false;
+		const array = Array.isArray(current);
+		const prototype = Object.getPrototypeOf(current);
+		if (!array && prototype !== Object.prototype && prototype !== null) return false;
+		if (array && current.length > 64 - values) return false;
+		ancestors.add(current);
+		if (!append(array ? "[" : "{")) return false;
+		let count = 0;
+		const member = (key) => {
+			const descriptor = Object.getOwnPropertyDescriptor(current, key);
+			if (!descriptor || !Object.hasOwn(descriptor, "value")) return false;
+			if (count++ > 0 && !append(",")) return false;
+			if (!array && (!string(key) || !append(":"))) return false;
+			return visit(descriptor.value, depth + 1);
+		};
+		if (array) {
+			for (let i = 0; i < current.length; i++) if (!member(String(i))) return false;
+		} else for (const key in current) if (Object.hasOwn(current, key) && !member(key)) return false;
+		ancestors.delete(current);
+		return append(array ? "]" : "}");
+	};
+	try {
+		return visit(value, 0) ? parts.join("") : void 0;
+	} catch {
+		return;
+	}
+};
 var Span = class extends Tracer.NativeSpan {
 	runInContext;
+	config;
+	forwardEvent;
 	cloudflareSpan;
-	constructor(options, runInContext, cloudflareSpan) {
+	eventAttempts = 0;
+	constructor(options, runInContext, config, forwardEvent, cloudflareSpan) {
 		super({
 			...options,
 			sampled: options.sampled && (cloudflareSpan?.isTraced ?? false)
 		});
 		this.runInContext = runInContext;
+		this.config = config;
+		this.forwardEvent = forwardEvent;
 		this.cloudflareSpan = cloudflareSpan;
+		if (!this.sampled) return;
+		bestEffort(() => {
+			this.setAttribute("effect.trace_id", this.traceId);
+			this.setAttribute("effect.span_id", this.spanId);
+			this.setAttribute("effect.span.kind", this.kind);
+			if (Option.isSome(this.parent)) {
+				this.setAttribute("effect.parent.trace_id", this.parent.value.traceId);
+				this.setAttribute("effect.parent.span_id", this.parent.value.spanId);
+			}
+		});
+	}
+	setAttribute(key, value) {
+		bestEffort(() => this.cloudflareSpan?.setAttribute(key, value));
 	}
 	attribute(key, value) {
 		super.attribute(key, value);
-		if (Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value)) this.cloudflareSpan?.setAttribute(key, value);
+		if (!this.sampled || this.status._tag === "Ended" || key.startsWith("effect.")) return;
+		if (Predicate.isString(value) || Predicate.isBoolean(value)) this.setAttribute(key, value);
+		else if (Predicate.isNumber(value)) {
+			if (Number.isFinite(value)) this.setAttribute(key, value);
+		} else {
+			const json = encodeJson(value);
+			if (json !== void 0) this.setAttribute(key, json);
+		}
+	}
+	event(name, startTime, attributes) {
+		super.event(name, startTime, attributes);
+		if (!this.config.spanEvents || !this.sampled || this.status._tag === "Ended" || this.eventAttempts >= maxEvents) return;
+		this.eventAttempts++;
+		bestEffort(() => {
+			const json = encodeJson({
+				"effect.event": name,
+				"effect.event.time_unix_nano": String(startTime),
+				"effect.trace_id": this.traceId,
+				"effect.span_id": this.spanId,
+				attributes: attributes ?? {}
+			});
+			if (json !== void 0) this.forwardEvent(this.runInContext, json);
+		});
 	}
 	end(endTime, exit) {
 		if (this.status._tag === "Ended") return;
 		super.end(endTime, exit);
-		this.cloudflareSpan?.setAttribute("effect.exit", Exit.isSuccess(exit) ? "success" : Cause.hasInterruptsOnly(exit.cause) ? "interrupted" : "failure");
-		this.cloudflareSpan?.end();
+		if (!this.sampled) return;
+		this.setAttribute("effect.exit", Exit.isSuccess(exit) ? "success" : Cause.hasInterruptsOnly(exit.cause) ? "interrupted" : "failure");
+		bestEffort(() => {
+			if (this.links.length > 0) {
+				const links = this.links.slice(0, maxLinks).map(({ span }) => ({
+					traceId: span.traceId,
+					spanId: span.spanId
+				}));
+				const json = encodeJson(links);
+				if (json !== void 0) this.setAttribute("effect.span.links", json);
+				this.setAttribute("effect.span.links_dropped", this.links.length - (json ? links.length : 0));
+			}
+		});
+		if (Exit.isFailure(exit)) {
+			this.setAttribute("effect.error.kind", Cause.hasDies(exit.cause) ? Cause.hasFails(exit.cause) ? "mixed" : "defect" : Cause.hasInterruptsOnly(exit.cause) ? "interrupted" : "failure");
+			bestEffort(() => {
+				const details = this.config.formatError?.(exit.cause);
+				for (const key of ["type", "message"]) {
+					const value = details?.[key];
+					if (Predicate.isString(value) && value.length <= maxBytes && textEncoder.encode(value).byteLength <= maxBytes) this.setAttribute(`effect.error.${key}`, value);
+				}
+			});
+		}
+		bestEffort(() => this.cloudflareSpan?.end());
 	}
 };
 /**
-* Sends Effect spans to Cloudflare Workers Observability using the runtime's
-* custom span API. Build this layer inside each invocation, for example with
-* `Worker.make(Services, { eventLayer: CloudflareTracer.layer, fetch })`.
-* It captures the invocation's async context and must not be cached across requests.
-*
-* Enable `observability.traces.enabled` in Wrangler. Cloudflare owns sampling
-* and export; no OTLP exporter or flush is required. Scalar attributes are
-* forwarded; other attributes, events, and links remain Effect-local. Completion
-* is recorded as `effect.exit`, since Cloudflare has no outcome-setting API.
-* Effect trace/span IDs remain independent of Cloudflare's opaque IDs. External
-* parents and `root: true` cannot override the invocation's Cloudflare trace.
+* Configures the per-invocation native tracer. See `layer` for representations
+* and limits. Options do not change Cloudflare sampling or native trace IDs.
 */
-const layer = Layer.effect(Tracer.Tracer, Effect.sync(() => {
+const layerWith = (options = {}) => Layer.effect(Tracer.Tracer, Effect.sync(() => {
 	const invocationContext = AsyncLocalStorage.snapshot();
+	let forwarding = false;
+	const forwardEvent = (context, json) => {
+		if (forwarding) return;
+		forwarding = true;
+		try {
+			context(() => console.log(JSON.parse(json)));
+		} finally {
+			forwarding = false;
+		}
+	};
 	const contextFor = (span) => {
 		while (span?._tag === "Span") {
 			if (span instanceof Span) return span.runInContext;
@@ -55,15 +174,49 @@ const layer = Layer.effect(Tracer.Tracer, Effect.sync(() => {
 		return invocationContext;
 	};
 	return Tracer.make({
-		span(options) {
-			const parentContext = options.root ? invocationContext : contextFor(Option.getOrUndefined(options.parent));
-			if (!options.sampled) return new Span(options, parentContext);
-			return parentContext(() => tracing.startActiveSpan(options.name, (span) => new Span(options, AsyncLocalStorage.snapshot(), span)));
+		span(spanOptions) {
+			const parentContext = spanOptions.root ? invocationContext : contextFor(Option.getOrUndefined(spanOptions.parent));
+			if (!spanOptions.sampled) return new Span(spanOptions, parentContext, options, forwardEvent);
+			return parentContext(() => tracing.startActiveSpan(spanOptions.name, (span) => new Span(spanOptions, AsyncLocalStorage.snapshot(), options, forwardEvent, span)));
 		},
 		context(primitive, fiber) {
-			return contextFor(fiber.currentSpan)(() => primitive["~effect/Effect/evaluate"](fiber));
+			return contextFor(fiber.cache.span)(() => primitive["~effect/Effect/evaluate"](fiber));
 		}
 	});
 }));
+/**
+* Sends Effect spans to Cloudflare Workers Observability. Build inside each
+* invocation, e.g. `Worker.make(Services, { eventLayer: CloudflareTracer.layer, fetch })`.
+* Captures async context; never cache the built layer across requests.
+*
+* Strings, finite numbers and booleans remain native scalars. Null, plain
+* objects and arrays become JSON strings under their original keys, limited to
+* 4096 UTF-8 bytes, 4 container levels and 64 values including the root. Values
+* exceeding any limit are dropped whole, as are cycles, accessors, unsupported
+* values (including undefined, bigint, functions, class instances and Redacted)
+* or serialization failures. No getters or toJSON methods are invoked. Only
+* own enumerable string keys / dense array elements are encoded. No flattening.
+*
+* `effect.*` is reserved for this adapter; caller attributes in that namespace
+* remain local. `effect.trace_id`, `effect.span_id`, `effect.parent.trace_id`,
+* `effect.parent.span_id` and `effect.span.kind` describe Effect identities.
+* At end, `effect.span.links` contains JSON for the first 8 linked Effect ID
+* pairs (including addLinks updates), bounded by the same JSON limits, with
+* omitted count in `effect.span.links_dropped`. Link attributes stay local.
+*
+* `effect.exit` is success/failure/interrupted. Failed spans also have
+* `effect.error.kind`: failure, defect, mixed (failures + defects), or interrupted.
+* No error payloads, messages or stacks are exported unless formatError opts in.
+* Events remain local unless `layerWith({ spanEvents: true })` opts into logs.
+* Local NativeSpan storage retains original attributes, links and events.
+*
+* Enable observability.traces.enabled in Wrangler. Cloudflare owns sampling
+* and export; no OTLP exporter or flush is required. Metadata creates no extra
+* spans. Cloudflare IDs remain opaque and distinct: this provides lookup, not
+* native graph links or cross-system propagation. There is no native outcome
+* setter or addEvent API. External parents and root: true cannot override the
+* invocation's Cloudflare trace. See Cloudflare's custom spans documentation.
+*/
+const layer = layerWith();
 //#endregion
-export { CloudflareTracer_exports, layer };
+export { CloudflareTracer_exports, layer, layerWith };

package/dist/Environment.mjs

@@ -15,11 +15,11 @@ var Environment_exports = /* @__PURE__ */ __exportAll({
 var WorkerEnvironment = class extends Context.Service()("effect-cf/WorkerEnvironment") {};
 let WorkerConfig;
 (function(_WorkerConfig) {
-	_WorkerConfig.string = (name) => Config.string(name);
-	_WorkerConfig.redacted = (name) => Config.redacted(name);
-	_WorkerConfig.number = (name) => Config.number(name);
-	_WorkerConfig.integer = (name) => Config.int(name);
-	_WorkerConfig.boolean = (name) => Config.boolean(name);
+	_WorkerConfig.string = (name) => Config.String(name);
+	_WorkerConfig.redacted = (name) => Config.Redacted(name);
+	_WorkerConfig.number = (name) => Config.Number(name);
+	_WorkerConfig.integer = (name) => Config.Int(name);
+	_WorkerConfig.boolean = (name) => Config.Boolean(name);
 	const providerFromEnv = _WorkerConfig.providerFromEnv = (env, options) => {
 		const record = {};
 		for (const [key, value] of Object.entries(env)) if (Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value)) record[key] = String(value);

package/dist/Worker.mjs

@@ -58,8 +58,9 @@ const renderFetchSuccess = (effect, eventLayer) => Effect.suspend(() => {
 		return Effect.succeed(response);
 	});
 	const handleResponse = (request, response) => nativeResponse !== void 0 ? Effect.void : Effect.map(Effect.context(), (context) => {
-		webResponse = HttpServerResponse.toWeb(HttpEffect.scopeTransferToStream(response), {
-			withoutBody: request.method === "HEAD",
+		const withoutBody = request.method === "HEAD";
+		webResponse = HttpServerResponse.toWeb(HttpServerResponse.omitsBody(response, withoutBody) ? response : HttpEffect.scopeTransferToStream(response), {
+			withoutBody,
 			context
 		});
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-cf",
-  "version": "0.42.1",
+  "version": "0.44.0",
   "description": "Effect-native primitives for Cloudflare Workers and bindings.",
   "license": "MIT",
   "repository": {
@@ -94,11 +94,11 @@
     "@cloudflare/sandbox": "^0.13.0-next.738.2",
     "@cloudflare/vitest-plugin": "^1.0.0",
     "@cloudflare/workers-types": "^5.20260825.1",
-    "@effect/sql-d1": "^4.0.0-rc.112",
-    "@effect/sql-pg": "^4.0.0-rc.112",
-    "@effect/sql-sqlite-do": "^4.0.0-rc.112",
+    "@effect/sql-d1": "^4.0.0-rc.115",
+    "@effect/sql-pg": "^4.0.0-rc.115",
+    "@effect/sql-sqlite-do": "^4.0.0-rc.115",
     "@modelcontextprotocol/server": "^2.0.0",
-    "effect": "^4.0.0-rc.112"
+    "effect": "^4.0.0-rc.115"
   },
   "peerDependenciesMeta": {
     "@cloudflare/computer": {

package/src/AnalyticsEngine.ts

@@ -729,11 +729,11 @@ export const makeClient =
 
 export const queryConfig = (options?: QueryConfigOptions) =>
   Config.all({
-    accountId: options?.accountId ?? Config.string("CLOUDFLARE_ACCOUNT_ID"),
-    apiToken: options?.apiToken ?? Config.redacted("CLOUDFLARE_API_TOKEN"),
+    accountId: options?.accountId ?? Config.String("CLOUDFLARE_ACCOUNT_ID"),
+    apiToken: options?.apiToken ?? Config.Redacted("CLOUDFLARE_API_TOKEN"),
     apiBaseUrl:
       options?.apiBaseUrl ??
-      Config.string("CLOUDFLARE_API_BASE_URL").pipe(Config.withDefault(defaultQueryApiBaseUrl)),
+      Config.String("CLOUDFLARE_API_BASE_URL").pipe(Config.withDefault(defaultQueryApiBaseUrl)),
   });
 
 export const queryLayer = <Self>(

package/src/CloudflareTracer.ts

@@ -11,31 +11,185 @@ import * as Tracer from "effect/Tracer";
 type SpanOptions = Parameters<Tracer.Tracer["span"]>[0];
 type RunInContext = ReturnType<typeof AsyncLocalStorage.snapshot>;
 type CloudflareSpan = Parameters<Parameters<typeof tracing.startActiveSpan>[1]>[0];
+type ForwardEvent = (context: RunInContext, json: string) => void;
+
+/** Explicitly sanitized diagnostics. No error payload or Cause is serialized automatically. */
+export interface ErrorDetails {
+  readonly type?: string;
+  readonly message?: string;
+}
+
+export interface LayerOptions {
+  /**
+   * Called once for a sampled failed span, including interruption. Return only
+   * safe diagnostic strings; each is dropped if over 4096 UTF-8 bytes. Throws
+   * are ignored. Defaults to classification only, without messages or stacks.
+   */
+  readonly formatError?: (cause: Cause.Cause<unknown>) => ErrorDetails | undefined;
+  /**
+   * Forward the first 16 event attempts per sampled span as structured console
+   * logs in its captured context. Defaults to false. Each complete log must fit
+   * the JSON limits documented on `layer`. This adds billable log volume.
+   */
+  readonly spanEvents?: boolean;
+}
+
+const maxBytes = 4096;
+const maxLinks = 8;
+const maxEvents = 16;
+const textEncoder = new TextEncoder();
+
+const bestEffort = (f: () => void): void => {
+  try {
+    f();
+  } catch {
+    // Telemetry must not change the application's exit, including formatter/host failures.
+  }
+};
+
+// This bounded JSON writer deliberately avoids coercion, getters and toJSON.
+// Schema decoding / JSON.stringify on arbitrary input would traverse it before
+// enforcing our work/depth limits, and could invoke application code.
+// oxlint-disable-next-line anti-slop/no-unknown-parameters
+const encodeJson = (value: unknown): string | undefined => {
+  let bytes = 0;
+  let values = 0;
+  const parts: Array<string> = [];
+  const ancestors = new Set<object>();
+  const append = (part: string): boolean => {
+    bytes += textEncoder.encode(part).byteLength;
+    if (bytes > maxBytes) return false;
+    parts.push(part);
+
+    return true;
+  };
+  const string = (text: string): boolean => text.length <= maxBytes && append(JSON.stringify(text));
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters
+  const visit = (current: unknown, depth: number): boolean => {
+    if (++values > 64) return false;
+    if (Predicate.isString(current)) return string(current);
+    if (current === null || Predicate.isBoolean(current)) return append(String(current));
+    if (Predicate.isNumber(current)) return Number.isFinite(current) && append(String(current));
+    if (!Predicate.isObjectOrArray(current) || depth === 4 || ancestors.has(current)) return false;
+
+    const array = Array.isArray(current);
+    const prototype = Object.getPrototypeOf(current);
+
+    if (!array && prototype !== Object.prototype && prototype !== null) return false;
+    if (array && current.length > 64 - values) return false;
+    ancestors.add(current);
+    if (!append(array ? "[" : "{")) return false;
+
+    let count = 0;
+    const member = (key: string): boolean => {
+      const descriptor = Object.getOwnPropertyDescriptor(current, key);
+
+      if (!descriptor || !Object.hasOwn(descriptor, "value")) return false;
+      if (count++ > 0 && !append(",")) return false;
+      if (!array && (!string(key) || !append(":"))) return false;
+
+      return visit(descriptor.value, depth + 1);
+    };
+
+    if (array) {
+      for (let i = 0; i < current.length; i++) {
+        if (!member(String(i))) return false;
+      }
+    } else {
+      for (const key in current) {
+        if (Object.hasOwn(current, key) && !member(key)) return false;
+      }
+    }
+    ancestors.delete(current);
+
+    return append(array ? "]" : "}");
+  };
+
+  try {
+    return visit(value, 0) ? parts.join("") : undefined;
+  } catch {
+    return undefined;
+  }
+};
 
 class Span extends Tracer.NativeSpan {
+  private eventAttempts = 0;
+
   constructor(
     options: SpanOptions,
     readonly runInContext: RunInContext,
+    readonly config: LayerOptions,
+    readonly forwardEvent: ForwardEvent,
     readonly cloudflareSpan?: CloudflareSpan,
   ) {
     super({ ...options, sampled: options.sampled && (cloudflareSpan?.isTraced ?? false) });
+    if (!this.sampled) return;
+
+    bestEffort(() => {
+      this.setAttribute("effect.trace_id", this.traceId);
+      this.setAttribute("effect.span_id", this.spanId);
+      this.setAttribute("effect.span.kind", this.kind);
+      if (Option.isSome(this.parent)) {
+        this.setAttribute("effect.parent.trace_id", this.parent.value.traceId);
+        this.setAttribute("effect.parent.span_id", this.parent.value.spanId);
+      }
+    });
+  }
+
+  private setAttribute(key: string, value: string | number | boolean): void {
+    bestEffort(() => this.cloudflareSpan?.setAttribute(key, value));
   }
 
-  // Effect's tracer contract accepts arbitrary attributes; only CF-supported scalars cross the boundary.
+  // Effect's tracer contract accepts arbitrary attributes.
   // oxlint-disable-next-line anti-slop/no-unknown-parameters
   override attribute(key: string, value: unknown): void {
     super.attribute(key, value);
+    if (!this.sampled || this.status._tag === "Ended" || key.startsWith("effect.")) return;
+
+    if (Predicate.isString(value) || Predicate.isBoolean(value)) {
+      this.setAttribute(key, value);
+    } else if (Predicate.isNumber(value)) {
+      if (Number.isFinite(value)) this.setAttribute(key, value);
+    } else {
+      const json = encodeJson(value);
 
-    if (Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value)) {
-      this.cloudflareSpan?.setAttribute(key, value);
+      if (json !== undefined) this.setAttribute(key, json);
     }
   }
 
+  override event(
+    name: string,
+    startTime: bigint,
+    attributes?: Parameters<Tracer.Span["event"]>[2],
+  ): void {
+    super.event(name, startTime, attributes);
+    if (
+      !this.config.spanEvents ||
+      !this.sampled ||
+      this.status._tag === "Ended" ||
+      this.eventAttempts >= maxEvents
+    )
+      return;
+    this.eventAttempts++;
+    bestEffort(() => {
+      const json = encodeJson({
+        "effect.event": name,
+        "effect.event.time_unix_nano": String(startTime),
+        "effect.trace_id": this.traceId,
+        "effect.span_id": this.spanId,
+        attributes: attributes ?? {},
+      });
+
+      if (json !== undefined) this.forwardEvent(this.runInContext, json);
+    });
+  }
+
   override end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): void {
     if (this.status._tag === "Ended") return;
-
     super.end(endTime, exit);
-    this.cloudflareSpan?.setAttribute(
+    if (!this.sampled) return;
+
+    this.setAttribute(
       "effect.exit",
       Exit.isSuccess(exit)
         ? "success"
@@ -43,56 +197,138 @@ class Span extends Tracer.NativeSpan {
           ? "interrupted"
           : "failure",
     );
-    this.cloudflareSpan?.end();
+    bestEffort(() => {
+      if (this.links.length > 0) {
+        const links = this.links.slice(0, maxLinks).map(({ span }) => ({
+          traceId: span.traceId,
+          spanId: span.spanId,
+        }));
+        const json = encodeJson(links);
+
+        if (json !== undefined) this.setAttribute("effect.span.links", json);
+        this.setAttribute(
+          "effect.span.links_dropped",
+          this.links.length - (json ? links.length : 0),
+        );
+      }
+    });
+    if (Exit.isFailure(exit)) {
+      this.setAttribute(
+        "effect.error.kind",
+        Cause.hasDies(exit.cause)
+          ? Cause.hasFails(exit.cause)
+            ? "mixed"
+            : "defect"
+          : Cause.hasInterruptsOnly(exit.cause)
+            ? "interrupted"
+            : "failure",
+      );
+      bestEffort(() => {
+        const details = this.config.formatError?.(exit.cause);
+
+        for (const key of ["type", "message"] as const) {
+          const value = details?.[key];
+
+          if (
+            Predicate.isString(value) &&
+            value.length <= maxBytes &&
+            textEncoder.encode(value).byteLength <= maxBytes
+          ) {
+            this.setAttribute(`effect.error.${key}`, value);
+          }
+        }
+      });
+    }
+    bestEffort(() => this.cloudflareSpan?.end());
   }
 }
 
 /**
- * Sends Effect spans to Cloudflare Workers Observability using the runtime's
- * custom span API. Build this layer inside each invocation, for example with
- * `Worker.make(Services, { eventLayer: CloudflareTracer.layer, fetch })`.
- * It captures the invocation's async context and must not be cached across requests.
- *
- * Enable `observability.traces.enabled` in Wrangler. Cloudflare owns sampling
- * and export; no OTLP exporter or flush is required. Scalar attributes are
- * forwarded; other attributes, events, and links remain Effect-local. Completion
- * is recorded as `effect.exit`, since Cloudflare has no outcome-setting API.
- * Effect trace/span IDs remain independent of Cloudflare's opaque IDs. External
- * parents and `root: true` cannot override the invocation's Cloudflare trace.
+ * Configures the per-invocation native tracer. See `layer` for representations
+ * and limits. Options do not change Cloudflare sampling or native trace IDs.
  */
-export const layer: Layer.Layer<never> = Layer.effect(
-  Tracer.Tracer,
-  Effect.sync(() => {
-    const invocationContext = AsyncLocalStorage.snapshot();
-    const contextFor = (span: Tracer.AnySpan | undefined): RunInContext => {
-      while (span?._tag === "Span") {
-        if (span instanceof Span) return span.runInContext;
-
-        // Effect can install a no-op span while tracing is locally disabled.
-        span = Option.getOrUndefined(span.parent);
-      }
+export const layerWith = (options: LayerOptions = {}): Layer.Layer<never> =>
+  Layer.effect(
+    Tracer.Tracer,
+    Effect.sync(() => {
+      const invocationContext = AsyncLocalStorage.snapshot();
+      let forwarding = false;
+      const forwardEvent: ForwardEvent = (context, json) => {
+        if (forwarding) return;
+        forwarding = true;
+        try {
+          // Parse only our own bounded JSON to give console a structured object.
+          context(() => console.log(JSON.parse(json)));
+        } finally {
+          forwarding = false;
+        }
+      };
+      const contextFor = (span: Tracer.AnySpan | undefined): RunInContext => {
+        while (span?._tag === "Span") {
+          if (span instanceof Span) return span.runInContext;
 
-      return invocationContext;
-    };
+          // Effect can install a no-op span while tracing is locally disabled.
+          span = Option.getOrUndefined(span.parent);
+        }
 
-    return Tracer.make({
-      span(options) {
-        const parentContext = options.root
-          ? invocationContext
-          : contextFor(Option.getOrUndefined(options.parent));
+        return invocationContext;
+      };
 
-        if (!options.sampled) return new Span(options, parentContext);
+      return Tracer.make({
+        span(spanOptions) {
+          const parentContext = spanOptions.root
+            ? invocationContext
+            : contextFor(Option.getOrUndefined(spanOptions.parent));
 
-        return parentContext(() =>
-          tracing.startActiveSpan(
-            options.name,
-            (span) => new Span(options, AsyncLocalStorage.snapshot(), span),
-          ),
-        );
-      },
-      context(primitive, fiber) {
-        return contextFor(fiber.currentSpan)(() => primitive["~effect/Effect/evaluate"](fiber));
-      },
-    });
-  }),
-);
+          if (!spanOptions.sampled)
+            return new Span(spanOptions, parentContext, options, forwardEvent);
+
+          return parentContext(() =>
+            tracing.startActiveSpan(
+              spanOptions.name,
+              (span) =>
+                new Span(spanOptions, AsyncLocalStorage.snapshot(), options, forwardEvent, span),
+            ),
+          );
+        },
+        context(primitive, fiber) {
+          return contextFor(fiber.cache.span)(() => primitive["~effect/Effect/evaluate"](fiber));
+        },
+      });
+    }),
+  );
+
+/**
+ * Sends Effect spans to Cloudflare Workers Observability. Build inside each
+ * invocation, e.g. `Worker.make(Services, { eventLayer: CloudflareTracer.layer, fetch })`.
+ * Captures async context; never cache the built layer across requests.
+ *
+ * Strings, finite numbers and booleans remain native scalars. Null, plain
+ * objects and arrays become JSON strings under their original keys, limited to
+ * 4096 UTF-8 bytes, 4 container levels and 64 values including the root. Values
+ * exceeding any limit are dropped whole, as are cycles, accessors, unsupported
+ * values (including undefined, bigint, functions, class instances and Redacted)
+ * or serialization failures. No getters or toJSON methods are invoked. Only
+ * own enumerable string keys / dense array elements are encoded. No flattening.
+ *
+ * `effect.*` is reserved for this adapter; caller attributes in that namespace
+ * remain local. `effect.trace_id`, `effect.span_id`, `effect.parent.trace_id`,
+ * `effect.parent.span_id` and `effect.span.kind` describe Effect identities.
+ * At end, `effect.span.links` contains JSON for the first 8 linked Effect ID
+ * pairs (including addLinks updates), bounded by the same JSON limits, with
+ * omitted count in `effect.span.links_dropped`. Link attributes stay local.
+ *
+ * `effect.exit` is success/failure/interrupted. Failed spans also have
+ * `effect.error.kind`: failure, defect, mixed (failures + defects), or interrupted.
+ * No error payloads, messages or stacks are exported unless formatError opts in.
+ * Events remain local unless `layerWith({ spanEvents: true })` opts into logs.
+ * Local NativeSpan storage retains original attributes, links and events.
+ *
+ * Enable observability.traces.enabled in Wrangler. Cloudflare owns sampling
+ * and export; no OTLP exporter or flush is required. Metadata creates no extra
+ * spans. Cloudflare IDs remain opaque and distinct: this provides lookup, not
+ * native graph links or cross-system propagation. There is no native outcome
+ * setter or addEvent API. External parents and root: true cannot override the
+ * invocation's Cloudflare trace. See Cloudflare's custom spans documentation.
+ */
+export const layer: Layer.Layer<never> = layerWith();

package/src/Environment.ts

@@ -33,19 +33,19 @@ export namespace WorkerConfig {
   export type Key = ScalarConfigKey;
 
   /** Read a scalar Cloudflare var or secret as a string. */
-  export const string = <const Name extends Key>(name: Name) => Config.string(name);
+  export const string = <const Name extends Key>(name: Name) => Config.String(name);
 
   /** Read a scalar Cloudflare secret as a redacted string. */
-  export const redacted = <const Name extends Key>(name: Name) => Config.redacted(name);
+  export const redacted = <const Name extends Key>(name: Name) => Config.Redacted(name);
 
   /** Read a scalar Cloudflare var or secret as a number. */
-  export const number = <const Name extends Key>(name: Name) => Config.number(name);
+  export const number = <const Name extends Key>(name: Name) => Config.Number(name);
 
   /** Read a scalar Cloudflare var or secret as an integer. */
-  export const integer = <const Name extends Key>(name: Name) => Config.int(name);
+  export const integer = <const Name extends Key>(name: Name) => Config.Int(name);
 
   /** Read a scalar Cloudflare var or secret as a boolean. */
-  export const boolean = <const Name extends Key>(name: Name) => Config.boolean(name);
+  export const boolean = <const Name extends Key>(name: Name) => Config.Boolean(name);
 
   export interface ProviderOptions {
     /**

package/src/Worker.ts

@@ -277,10 +277,17 @@ const renderFetchSuccess = <E, R, REvent, EventLayerError, EventLayerRequirement
       nativeResponse !== undefined
         ? Effect.void
         : Effect.map(Effect.context<never>(), (context) => {
-            webResponse = HttpServerResponse.toWeb(HttpEffect.scopeTransferToStream(response), {
-              withoutBody: request.method === "HEAD",
-              context,
-            });
+            const withoutBody = request.method === "HEAD";
+
+            webResponse = HttpServerResponse.toWeb(
+              HttpServerResponse.omitsBody(response, withoutBody)
+                ? response
+                : HttpEffect.scopeTransferToStream(response),
+              {
+                withoutBody,
+                context,
+              },
+            );
           });
     const telemetryMiddleware = HttpMiddleware.make((self) =>
       RpcTargets.withScope(