@apifuse/provider-sdk 2.2.0-beta.55 → 2.2.0-beta.56

package/src/runtime/proxy-telemetry.ts

@@ -9,8 +9,19 @@ import type {
 	ProxyVendorName,
 	SmartproxyAllocatorBodyClass,
 } from "../config/loader.js";
+import {
+	closedEnum,
+	RequestTelemetry,
+	type ClosedEnum,
+	type TelemetryContributor,
+} from "./request-telemetry.js";
+import { createTraceContext } from "./trace.js";
 
-export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+export { PROVIDER_TELEMETRY_HEADER } from "./request-telemetry.js";
+
+declare const PROXY_HASH: unique symbol;
+/** Bounded hexadecimal host hash used in proxy attempt samples. */
+export type ProxyHash = ClosedEnum<string> & { readonly [PROXY_HASH]: true };
 
 export type ProxyTelemetryResolvedPayload = {
 	kind: "resolved";
@@ -94,14 +105,51 @@ export type ProxyTelemetryLogPayload =
 	| ProxyTelemetryResolvedPayload
 	| ProxyTelemetryUnresolvedPayload;
 
-type ProviderTelemetryHeader = {
-	v: 1;
-	proxy?: ProxyTelemetryLogPayload;
+/** Concrete gateway-safe projection of the unchanged proxy sibling. */
+export type ProxyTelemetryHeaderPayload = {
+	kind: ClosedEnum<"resolved" | "unresolved">;
+	provider?: ClosedEnum<ProxyVendorName>;
+	userAgentSource?: ClosedEnum<ProxyUserAgentSource>;
+	protocol?: ClosedEnum<ProxyProtocol>;
+	cacheStatus?: ClosedEnum<ProxyCacheStatus>;
+	cacheHit?: boolean;
+	resolutionMs?: number;
+	allocatorMs?: number;
+	allocatorStatus?: number;
+	allocatorBodyClass?: ClosedEnum<SmartproxyAllocatorBodyClass>;
+	allocatorAttempts?: number;
+	lockWaitMs?: number;
+	redisReadMs?: number;
+	redisWriteMs?: number;
+	poolAgeMs?: number;
+	poolExpiresInMs?: number;
+	attempts?: number;
+	refreshes?: number;
+	attemptSamples?: {
+		n: number;
+		a: number;
+		i?: number;
+		h?: ProxyHash;
+		o: ClosedEnum<ProxyAttemptTelemetryEvent["outcome"]>;
+		c?: ClosedEnum<string>;
+		s?: number;
+		d?: number;
+	}[];
+	vendors?: ClosedEnum<ProxyVendorName>[];
+	failovers?: {
+		v: ClosedEnum<ProxyVendorName>;
+		nx?: ClosedEnum<ProxyVendorName>;
+		p: ClosedEnum<ProxyVendorFailoverTelemetryEvent["phase"]>;
+		r: ClosedEnum<ProxyVendorFailoverTelemetryEvent["reason"]>;
+		a?: number;
+	}[];
 };
 
-const MAX_HEADER_BYTES = 4_096;
 const MAX_PROXY_ATTEMPT_SAMPLES = 24;
 const MAX_PROXY_FAILOVER_SAMPLES = 12;
+const MAX_RETAINED_PROXY_RESOLUTIONS = 64;
+const PROXY_HEADER_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
+const PROXY_HEADER_HASH = /^[0-9a-f]{1,16}$/;
 
 const CACHE_STATUS_SEVERITY: Record<ProxyCacheStatus, number> = {
 	disabled: 0,
@@ -128,19 +176,48 @@ function worseStatus(left: ProxyCacheStatus, right: ProxyCacheStatus): ProxyCach
 	return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left] ? right : left;
 }
 
-function encodeBase64Url(value: string): string {
-	return Buffer.from(value, "utf8").toString("base64url");
+function aggregateResolution(
+	acc: ProxyResolutionTelemetryEvent,
+	event: ProxyResolutionTelemetryEvent,
+): ProxyResolutionTelemetryEvent {
+	return {
+		provider: event.provider,
+		userAgentSource: event.userAgentSource ?? acc.userAgentSource,
+		cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
+		cacheHit: acc.cacheHit && event.cacheHit,
+		resolutionMs: acc.resolutionMs + event.resolutionMs,
+		allocatorMs: sumOptional(acc.allocatorMs, event.allocatorMs),
+		allocatorStatus: event.allocatorStatus ?? acc.allocatorStatus,
+		allocatorBodyClass: event.allocatorBodyClass ?? acc.allocatorBodyClass,
+		allocatorAttempts: sumOptional(acc.allocatorAttempts, event.allocatorAttempts),
+		lockWaitMs: sumOptional(acc.lockWaitMs, event.lockWaitMs),
+		redisReadMs: sumOptional(acc.redisReadMs, event.redisReadMs),
+		redisWriteMs: sumOptional(acc.redisWriteMs, event.redisWriteMs),
+		poolAgeMs: maxOptional(acc.poolAgeMs, event.poolAgeMs),
+		poolExpiresInMs: maxOptional(acc.poolExpiresInMs, event.poolExpiresInMs),
+		attempts: acc.attempts + event.attempts,
+		refreshes: sumOptional(acc.refreshes, event.refreshes),
+	};
 }
 
-export class ProxyTelemetryCollector implements ProxyTelemetrySink {
+export class ProxyTelemetryCollector
+	implements
+		ProxyTelemetrySink,
+		TelemetryContributor<ProxyTelemetryLogPayload, ProxyTelemetryHeaderPayload>
+{
+	readonly key = "proxy" as const;
 	#events: ProxyResolutionTelemetryEvent[] = [];
+	#resolutionCount = 0;
+	#aggregateResolution: ProxyResolutionTelemetryEvent | undefined;
+	#lastSuccessfulResolution: ProxyResolutionTelemetryEvent | undefined;
+	#vendors: ProxyVendorName[] = [];
 	#attempts: ProxyAttemptTelemetryEvent[] = [];
 	#failovers: ProxyVendorFailoverTelemetryEvent[] = [];
 	#unresolvedVendors: ProxyVendorName[] = [];
 
 	recordProxyResolution(event: ProxyResolutionTelemetryEvent): void {
 		const outcome = event.outcome === "error" ? "error" : "ok";
-		this.#events.push({
+		const normalized: ProxyResolutionTelemetryEvent = {
 			provider: event.provider,
 			outcome,
 			...(event.userAgentSource ? { userAgentSource: event.userAgentSource } : {}),
@@ -174,12 +251,29 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			attempts: Math.max(1, Math.floor(event.attempts || 1)),
 			refreshes:
 				event.refreshes === undefined ? undefined : Math.max(0, Math.floor(event.refreshes)),
-		});
+		};
+		this.#resolutionCount += 1;
+		if (this.#events.length < MAX_RETAINED_PROXY_RESOLUTIONS) this.#events.push(normalized);
+		this.#aggregateResolution = this.#aggregateResolution
+			? aggregateResolution(this.#aggregateResolution, normalized)
+			: normalized;
+		if (outcome === "ok") this.#lastSuccessfulResolution = normalized;
+		if (!this.#vendors.includes(event.provider)) this.#vendors.push(event.provider);
 		if (outcome === "error" && !this.#unresolvedVendors.includes(event.provider)) {
 			this.#unresolvedVendors.push(event.provider);
 		}
 	}
 
+	/** Number of raw resolution events retained for bounded-history verification. */
+	get retainedResolutionEventCount(): number {
+		return this.#events.length;
+	}
+
+	/** Total resolutions included in the incremental aggregate. */
+	get resolutionEventCount(): number {
+		return this.#resolutionCount;
+	}
+
 	recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void {
 		if (this.#failovers.length >= MAX_PROXY_FAILOVER_SAMPLES) return;
 		this.#failovers.push({
@@ -213,8 +307,7 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 	}
 
 	toLogPayload(): ProxyTelemetryLogPayload | undefined {
-		const [first, ...rest] = this.#events;
-		const okEvents = this.#events.filter((event) => event.outcome !== "error");
+		const aggregate = this.#aggregateResolution;
 		const attemptSamples = this.#attempts.map((attempt, index) => ({
 			n: index + 1,
 			a: attempt.attempt,
@@ -233,33 +326,8 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			...(failover.attempt === undefined ? {} : { a: failover.attempt }),
 		}));
 
-		if (okEvents.length === 0) {
-			if (!first && failovers.length === 0) return undefined;
-			const failureEvents = this.#events.filter((event) => event.outcome === "error");
-			const [firstFailure, ...remainingFailures] = failureEvents;
-			const aggregate = firstFailure
-				? remainingFailures.reduce<ProxyResolutionTelemetryEvent>(
-						(acc, event) => ({
-							provider: event.provider,
-							outcome: "error",
-							cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
-							cacheHit: acc.cacheHit && event.cacheHit,
-							resolutionMs: acc.resolutionMs + event.resolutionMs,
-							allocatorMs: sumOptional(acc.allocatorMs, event.allocatorMs),
-							allocatorStatus: event.allocatorStatus ?? acc.allocatorStatus,
-							allocatorBodyClass: event.allocatorBodyClass ?? acc.allocatorBodyClass,
-							allocatorAttempts: sumOptional(acc.allocatorAttempts, event.allocatorAttempts),
-							lockWaitMs: sumOptional(acc.lockWaitMs, event.lockWaitMs),
-							redisReadMs: sumOptional(acc.redisReadMs, event.redisReadMs),
-							redisWriteMs: sumOptional(acc.redisWriteMs, event.redisWriteMs),
-							poolAgeMs: maxOptional(acc.poolAgeMs, event.poolAgeMs),
-							poolExpiresInMs: maxOptional(acc.poolExpiresInMs, event.poolExpiresInMs),
-							attempts: acc.attempts + event.attempts,
-							refreshes: sumOptional(acc.refreshes, event.refreshes),
-						}),
-						firstFailure,
-					)
-				: undefined;
+		if (!this.#lastSuccessfulResolution) {
+			if (!aggregate && failovers.length === 0) return undefined;
 			return {
 				kind: "unresolved",
 				vendors: [...this.#unresolvedVendors],
@@ -301,33 +369,8 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		}
 
 		// The serving vendor/protocol is the last successful resolution.
-		const serving = okEvents[okEvents.length - 1] ?? first;
-		const vendors: ProxyVendorName[] = [];
-		for (const event of this.#events) {
-			if (!vendors.includes(event.provider)) vendors.push(event.provider);
-		}
-
-		const aggregate = rest.reduce<ProxyResolutionTelemetryEvent>(
-			(acc, event) => ({
-				provider: event.provider,
-				userAgentSource: event.userAgentSource ?? acc.userAgentSource,
-				cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
-				cacheHit: acc.cacheHit && event.cacheHit,
-				resolutionMs: acc.resolutionMs + event.resolutionMs,
-				allocatorMs: sumOptional(acc.allocatorMs, event.allocatorMs),
-				allocatorStatus: event.allocatorStatus ?? acc.allocatorStatus,
-				allocatorBodyClass: event.allocatorBodyClass ?? acc.allocatorBodyClass,
-				allocatorAttempts: sumOptional(acc.allocatorAttempts, event.allocatorAttempts),
-				lockWaitMs: sumOptional(acc.lockWaitMs, event.lockWaitMs),
-				redisReadMs: sumOptional(acc.redisReadMs, event.redisReadMs),
-				redisWriteMs: sumOptional(acc.redisWriteMs, event.redisWriteMs),
-				poolAgeMs: maxOptional(acc.poolAgeMs, event.poolAgeMs),
-				poolExpiresInMs: maxOptional(acc.poolExpiresInMs, event.poolExpiresInMs),
-				attempts: acc.attempts + event.attempts,
-				refreshes: sumOptional(acc.refreshes, event.refreshes),
-			}),
-			first,
-		);
+		if (!aggregate) return undefined;
+		const serving = this.#lastSuccessfulResolution;
 		return {
 			kind: "resolved",
 			provider: serving.provider,
@@ -356,18 +399,61 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			attempts: aggregate.attempts,
 			...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
 			...(attemptSamples.length > 0 ? { attemptSamples } : {}),
-			...(vendors.length > 1 ? { vendors } : {}),
+			...(this.#vendors.length > 1 ? { vendors: [...this.#vendors] } : {}),
 			...(failovers.length > 0 ? { failovers } : {}),
 		};
 	}
 
-	toHeaderValue(): string | undefined {
-		const proxy = this.toLogPayload();
-		if (!proxy) return undefined;
-		const payload: ProviderTelemetryHeader = { v: 1, proxy };
+	toHeaderPayload(log: ProxyTelemetryLogPayload): ProxyTelemetryHeaderPayload {
+		const attemptSamples = log.attemptSamples?.map((sample) => ({
+			n: sample.n,
+			a: sample.a,
+			...(sample.i === undefined ? {} : { i: sample.i }),
+			...(sample.h && PROXY_HEADER_HASH.test(sample.h)
+				? { h: closedEnum(sample.h) as ProxyHash }
+				: {}),
+			o: closedEnum(sample.o),
+			...(sample.c && PROXY_HEADER_TOKEN.test(sample.c) ? { c: closedEnum(sample.c) } : {}),
+			...(sample.s === undefined ? {} : { s: sample.s }),
+			...(sample.d === undefined ? {} : { d: sample.d }),
+		}));
+		const failovers = log.failovers?.map((failover) => ({
+			...failover,
+			v: closedEnum(failover.v),
+			...(failover.nx ? { nx: closedEnum(failover.nx) } : {}),
+			p: closedEnum(failover.p),
+			r: closedEnum(failover.r),
+		}));
+		if (log.kind === "resolved") {
+			return {
+				...log,
+				kind: closedEnum(log.kind),
+				provider: closedEnum(log.provider),
+				...(log.userAgentSource ? { userAgentSource: closedEnum(log.userAgentSource) } : {}),
+				...(log.protocol ? { protocol: closedEnum(log.protocol) } : {}),
+				cacheStatus: closedEnum(log.cacheStatus),
+				...(log.allocatorBodyClass
+					? { allocatorBodyClass: closedEnum(log.allocatorBodyClass) }
+					: {}),
+				...(attemptSamples ? { attemptSamples } : {}),
+				...(log.vendors ? { vendors: log.vendors.map((vendor) => closedEnum(vendor)) } : {}),
+				...(failovers ? { failovers } : {}),
+			} as ProxyTelemetryHeaderPayload;
+		}
+		return {
+			...log,
+			kind: closedEnum(log.kind),
+			vendors: log.vendors.map((vendor) => closedEnum(vendor)),
+			...(log.cacheStatus ? { cacheStatus: closedEnum(log.cacheStatus) } : {}),
+			...(log.allocatorBodyClass ? { allocatorBodyClass: closedEnum(log.allocatorBodyClass) } : {}),
+			...(failovers ? { failovers } : {}),
+			...(attemptSamples ? { attemptSamples } : {}),
+		} as ProxyTelemetryHeaderPayload;
+	}
 
-		const encoded = encodeBase64Url(JSON.stringify(payload));
-		if (encoded.length > MAX_HEADER_BYTES) return undefined;
-		return encoded;
+	toHeaderValue(): string | undefined {
+		const telemetry = new RequestTelemetry(createTraceContext());
+		telemetry.register(this);
+		return telemetry.toHeaderValue();
 	}
 }

package/src/runtime/request-telemetry.ts

@@ -0,0 +1,376 @@
+import { PROVIDER_OBSERVABILITY_TAXONOMY_VERSION } from "../observability.js";
+import type { ProxyTelemetrySink } from "../config/loader.js";
+import type { ProxyTelemetryLogPayload } from "./proxy-telemetry.js";
+import type { Span, TraceContext } from "./trace.js";
+
+export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+
+export type TelemetryKey =
+	| "proxy"
+	| "resolver"
+	| "http"
+	| "stealth"
+	| "native"
+	| "browser"
+	| "ocr"
+	| "stt"
+	| "cache"
+	| "state"
+	| "events";
+
+declare const CLOSED_ENUM: unique symbol;
+
+/** A string from an SDK-declared, closed observability taxonomy. */
+export type ClosedEnum<T extends string> = T & { readonly [CLOSED_ENUM]: true };
+
+/** Brands a value from an SDK-declared closed string union without changing it. */
+export function closedEnum<T extends string>(value: T): ClosedEnum<T> {
+	return value as ClosedEnum<T>;
+}
+
+/** Explicit exemption for the existing implementation-shaped cache key list. */
+export type TenantOpaqueKeys = string[] & { readonly __tenantOpaqueCacheKeys: true };
+
+/** Names the deliberate tenant cache-key exemption without changing its wire value. */
+export function tenantOpaqueKeys(value: string[]): TenantOpaqueKeys {
+	return value as TenantOpaqueKeys;
+}
+
+/**
+ * Compile-time projection for the gateway ingestion contract. Plain strings,
+ * URLs, hostnames, free text, unknown values, and escape-hatch properties reduce to `never`.
+ */
+export type GatewayIngestible<T> = 0 extends 1 & T
+	? never
+	: T extends object
+		? keyof T extends never
+			? never
+			: {
+					[K in keyof T]: 0 extends 1 & T[K]
+						? never
+						: unknown extends T[K]
+							? never
+							: [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>]
+								? T[K]
+								: [NonNullable<T[K]>] extends [readonly (infer U)[]]
+									? 0 extends 1 & U
+										? never
+										: unknown extends U
+											? never
+											: [U] extends [
+													number | boolean | ClosedEnum<string> | GatewayIngestible<U>,
+												]
+												? T[K]
+												: never
+									: [NonNullable<T[K]>] extends [object]
+										? [NonNullable<T[K]>] extends [GatewayIngestible<NonNullable<T[K]>>]
+											? T[K]
+											: never
+										: never;
+				}
+		: never;
+
+/** Compile-time projection for tenant-visible, identity-neutral metadata. */
+export type TenantNeutral<T> = 0 extends 1 & T
+	? never
+	: T extends object
+		? {
+				[K in keyof T]: K extends
+					| `vendor${string}`
+					| "provider"
+					| "engine"
+					| "model"
+					| `${string}Host`
+					? never
+					: 0 extends 1 & T[K]
+						? never
+						: unknown extends T[K]
+							? never
+							: [NonNullable<T[K]>] extends [
+									string[] & { readonly __tenantOpaqueCacheKeys: true },
+								]
+								? K extends "keys"
+									? T[K]
+									: never
+								: [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>]
+									? T[K]
+									: [NonNullable<T[K]>] extends [object]
+										? [NonNullable<T[K]>] extends [TenantNeutral<NonNullable<T[K]>>]
+											? T[K]
+											: never
+										: never;
+			}
+		: never;
+
+export interface SpanIndex {
+	readonly spans: readonly Span[];
+	readonly byName: ReadonlyMap<string, readonly Span[]>;
+	count(name: string): number;
+	durationMs(name: string): number;
+}
+
+export interface TelemetryContributor<Log extends object, Header extends object> {
+	readonly key: TelemetryKey;
+	toLogPayload(spans: SpanIndex): Log | undefined;
+	toHeaderPayload(
+		log: Log,
+	): 0 extends 1 & Header
+		? never
+		: [Header] extends [GatewayIngestible<Header>]
+			? Header | undefined
+			: never;
+}
+
+export type RequestTelemetryLogPayload = {
+	proxy?: ProxyTelemetryLogPayload;
+} & Partial<Record<Exclude<TelemetryKey, "proxy">, object>>;
+
+type RegisteredTelemetryContributor = {
+	readonly key: TelemetryKey;
+	toLogPayload(spans: SpanIndex): object | undefined;
+	toHeaderPayload(log: object): object | undefined;
+};
+
+type ProviderTelemetryEnvelope = {
+	v: 1;
+	taxonomy: typeof PROVIDER_OBSERVABILITY_TAXONOMY_VERSION;
+	truncated?: true;
+} & Partial<Record<Exclude<TelemetryKey, "events">, object>>;
+
+const MAX_HEADER_BYTES = 4_096;
+const MAX_INGESTIBLE_ARRAY_LENGTH = 64;
+const MAX_INGESTIBLE_OBJECT_KEYS = 32;
+const MAX_INGESTIBLE_DEPTH = 4;
+const INGESTIBLE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
+const HEADER_PRIORITY = [
+	"proxy",
+	"resolver",
+	"native",
+	"http",
+	"stealth",
+	"browser",
+	"ocr",
+	"stt",
+	"cache",
+	"state",
+] as const satisfies readonly Exclude<TelemetryKey, "events">[];
+const warnedInvalidKeys = new Set<TelemetryKey>();
+
+function createSpanIndex(trace: TraceContext): SpanIndex {
+	const spans = trace.getSpans().slice();
+	const mutableByName = new Map<string, Span[]>();
+	for (const span of spans) {
+		const named = mutableByName.get(span.name);
+		if (named) named.push(span);
+		else mutableByName.set(span.name, [span]);
+	}
+	const byName = new Map<string, readonly Span[]>(mutableByName);
+	return {
+		spans,
+		byName,
+		count(name): number {
+			return byName.get(name)?.length ?? 0;
+		},
+		durationMs(name): number {
+			return (byName.get(name) ?? []).reduce((total, span) => total + span.duration_ms, 0);
+		},
+	};
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * Bounded structural defence in depth against casts and accidental free text.
+ * Closed-enum brands are erased at runtime; the type-level guard is the contract,
+ * while this check only enforces safe token shapes and collection bounds.
+ */
+export function isGatewayIngestible(value: unknown): boolean {
+	const ancestors = new Set<object>();
+	const visit = (candidate: unknown, depth: number): boolean => {
+		if (typeof candidate === "number") return Number.isFinite(candidate);
+		if (typeof candidate === "boolean") return true;
+		if (typeof candidate === "string") return INGESTIBLE_TOKEN.test(candidate);
+		if (candidate === null || typeof candidate !== "object") return false;
+		if (depth >= MAX_INGESTIBLE_DEPTH || ancestors.has(candidate)) return false;
+
+		if (Array.isArray(candidate)) {
+			if (candidate.length > MAX_INGESTIBLE_ARRAY_LENGTH) return false;
+			ancestors.add(candidate);
+			const valid = candidate.every(
+				(item, index) => Object.hasOwn(candidate, index) && visit(item, depth + 1),
+			);
+			ancestors.delete(candidate);
+			return valid;
+		}
+
+		if (!isPlainRecord(candidate)) return false;
+		const keys = Object.keys(candidate);
+		if (keys.length > MAX_INGESTIBLE_OBJECT_KEYS) return false;
+		ancestors.add(candidate);
+		const valid = keys.every((key) => visit(candidate[key], depth + 1));
+		ancestors.delete(candidate);
+		return valid;
+	};
+	try {
+		return visit(value, 0);
+	} catch {
+		return false;
+	}
+}
+
+function encodeEnvelope(envelope: ProviderTelemetryEnvelope): string {
+	return Buffer.from(JSON.stringify(envelope), "utf8").toString("base64url");
+}
+
+function warnInvalidSibling(key: TelemetryKey): void {
+	if (warnedInvalidKeys.has(key)) return;
+	warnedInvalidKeys.add(key);
+	try {
+		console.warn(
+			`[provider-sdk] Dropped invalid telemetry sibling "${key}"; contributors must return serializable log objects and bounded gateway-safe header values.`,
+		);
+	} catch {
+		// A host-provided console must not let telemetry fail the request path.
+	}
+}
+
+function isProxySink(value: unknown): value is ProxyTelemetrySink {
+	if (value === null || typeof value !== "object") return false;
+	try {
+		return typeof Reflect.get(value, "recordProxyResolution") === "function";
+	} catch {
+		return false;
+	}
+}
+
+/** One finalisation owner for every request-scoped telemetry contributor. */
+export class RequestTelemetry {
+	readonly trace: TraceContext;
+	readonly contributors: Readonly<
+		Partial<
+			Record<
+				TelemetryKey,
+				{
+					readonly key: TelemetryKey;
+					toLogPayload(spans: SpanIndex): object | undefined;
+				}
+			>
+		>
+	>;
+	readonly #registered: Partial<Record<TelemetryKey, RegisteredTelemetryContributor>> = {};
+	readonly #exposed: Partial<
+		Record<
+			TelemetryKey,
+			{
+				readonly key: TelemetryKey;
+				toLogPayload(spans: SpanIndex): object | undefined;
+			}
+		>
+	> = {};
+	#proxy: ProxyTelemetrySink | undefined;
+
+	constructor(trace: TraceContext) {
+		this.trace = trace;
+		this.contributors = this.#exposed;
+	}
+
+	register<Log extends object, Header extends object>(
+		contributor: TelemetryContributor<Log, Header> &
+			(0 extends 1 & Log
+				? never
+				: 0 extends 1 & Header
+					? never
+					: [Header] extends [GatewayIngestible<Header>]
+						? unknown
+						: never),
+	): void {
+		if (this.#registered[contributor.key]) {
+			throw new TypeError(`Telemetry contributor "${contributor.key}" is already registered.`);
+		}
+		const registered: RegisteredTelemetryContributor = {
+			key: contributor.key,
+			toLogPayload: (spans) => contributor.toLogPayload(spans),
+			toHeaderPayload: (log) => contributor.toHeaderPayload(log as Log),
+		};
+		this.#registered[contributor.key] = registered;
+		this.#exposed[contributor.key] = contributor;
+		if (contributor.key === "proxy" && isProxySink(contributor)) this.#proxy = contributor;
+	}
+
+	get proxy(): ProxyTelemetrySink | undefined {
+		return this.#proxy;
+	}
+
+	toLogPayload(): RequestTelemetryLogPayload | undefined {
+		const spans = createSpanIndex(this.trace);
+		const payload: Partial<Record<TelemetryKey, object>> = {};
+		for (const key of Object.keys(this.#registered) as TelemetryKey[]) {
+			const contributor = this.#registered[key];
+			if (!contributor) continue;
+			try {
+				const sibling = contributor.toLogPayload(spans);
+				if (sibling === undefined) continue;
+				JSON.stringify(sibling);
+				payload[key] = sibling;
+			} catch {
+				warnInvalidSibling(key);
+			}
+		}
+		return Object.keys(payload).length > 0 ? (payload as RequestTelemetryLogPayload) : undefined;
+	}
+
+	toHeaderValue(): string | undefined {
+		const spans = createSpanIndex(this.trace);
+		const siblings: Partial<Record<Exclude<TelemetryKey, "events">, object>> = {};
+		for (const key of HEADER_PRIORITY) {
+			const contributor = this.#registered[key];
+			if (!contributor) continue;
+			try {
+				const log = contributor.toLogPayload(spans);
+				if (log === undefined) continue;
+				const projected = contributor.toHeaderPayload(log);
+				if (projected === undefined) continue;
+				if (!isGatewayIngestible(projected)) {
+					warnInvalidSibling(key);
+					continue;
+				}
+				const serialized = JSON.stringify(projected);
+				const decoded: unknown = JSON.parse(serialized);
+				if (!isGatewayIngestible(decoded) || !isPlainRecord(decoded)) {
+					warnInvalidSibling(key);
+					continue;
+				}
+				siblings[key] = decoded;
+			} catch {
+				warnInvalidSibling(key);
+			}
+		}
+
+		if (Object.keys(siblings).length === 0) return undefined;
+
+		// Gateway uses permissive json.Unmarshal (unknown keys are ignored) but
+		// requires v === 1. The observability taxonomy is additive and independent.
+		const envelope: ProviderTelemetryEnvelope = {
+			v: 1,
+			taxonomy: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			...siblings,
+		};
+		let encoded = encodeEnvelope(envelope);
+		if (encoded.length <= MAX_HEADER_BYTES) return encoded;
+
+		for (let index = HEADER_PRIORITY.length - 1; index >= 0; index -= 1) {
+			const key = HEADER_PRIORITY[index];
+			if (!key || !(key in envelope)) continue;
+			delete envelope[key];
+			if (!HEADER_PRIORITY.some((candidate) => candidate in envelope)) return undefined;
+			envelope.truncated = true;
+			encoded = encodeEnvelope(envelope);
+			if (encoded.length <= MAX_HEADER_BYTES) return encoded;
+		}
+		return undefined;
+	}
+}