@apifuse/provider-sdk 2.2.0-beta.61 → 2.2.0-beta.63

package/src/runtime/engine-mode.ts

@@ -0,0 +1,233 @@
+import {
+	createInProcessProviderEngine,
+	PROVIDER_ENGINE_MODE_ENV,
+	type ProviderEngine,
+	type ProviderEngineMode,
+} from "../engine.js";
+import { ProviderError, ValidationError } from "../errors.js";
+
+/**
+ * Engine attachment selection. Internal on purpose: ADR-0011 removes the
+ * in-process lane, so every symbol exported here would become a breaking removal
+ * later. The server surfaces the outcome on the `provider_engine_mode` boot
+ * event instead.
+ */
+
+const KNOWN_PROVIDER_ENGINE_MODES = ["in-process", "remote"] as const;
+
+/** Mode used when neither `engineMode` nor `APIFUSE__ENGINE__MODE` names one. */
+export const DEFAULT_PROVIDER_ENGINE_MODE = "in-process" satisfies ProviderEngineMode;
+
+/** Remote engine client endpoint; engine-owned, so never declarable as a provider secret. */
+export const REMOTE_ENGINE_CLIENT_URL_ENV = "APIFUSE__ENGINE__URL";
+/** Remote engine client credential; registered with the diagnostic redactor by sensitive-values. */
+export const REMOTE_ENGINE_CLIENT_API_KEY_ENV = "APIFUSE__ENGINE__API_KEY";
+
+/** Engine env names that only mean something in remote mode. */
+const REMOTE_ONLY_ENGINE_ENV_NAMES = [
+	REMOTE_ENGINE_CLIENT_URL_ENV,
+	REMOTE_ENGINE_CLIENT_API_KEY_ENV,
+] as const;
+
+/** Where the resolved mode came from, in precedence order. */
+export type ProviderEngineModeSource = "engine" | "env" | "option" | "default";
+
+/**
+ * Non-fatal conditions worth reporting at boot:
+ * - `invalid_env_value`: `APIFUSE__ENGINE__MODE` held an unrecognized value.
+ * - `env_overrode_option`: the manifest and the host code disagreed; the manifest won.
+ * - `engine_object_overrode_requested_mode`: an explicit engine object cannot honour the requested mode.
+ * - `engine_env_ignored`: remote-only engine env is projected but the mode is not
+ *   remote (not reported for a host-supplied engine, which may consume it itself).
+ */
+export type ProviderEngineModeWarning =
+	| "invalid_env_value"
+	| "env_overrode_option"
+	| "engine_object_overrode_requested_mode"
+	| "engine_env_ignored";
+
+export interface ProviderEngineModeResolution {
+	readonly mode: ProviderEngineMode | "custom";
+	readonly source: ProviderEngineModeSource;
+	/** True for every non-remote attachment, whose removal is scheduled by ADR-0011. */
+	readonly deprecated: boolean;
+	readonly warnings: readonly ProviderEngineModeWarning[];
+}
+
+export interface ProviderEngineModeResolutionInput {
+	/** Explicit `engineMode` option passed by the host process. */
+	readonly option?: ProviderEngineMode;
+	/** Explicit engine object passed by the host; used as given when present. */
+	readonly engine?: Pick<ProviderEngine, "kind">;
+	/** Environment to read the engine env from; defaults to `process.env`. */
+	readonly environment?: Readonly<Record<string, string | undefined>>;
+}
+
+function isKnownMode(value: string): value is (typeof KNOWN_PROVIDER_ENGINE_MODES)[number] {
+	return (KNOWN_PROVIDER_ENGINE_MODES as readonly string[]).includes(value);
+}
+
+function normalize(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim().toLowerCase();
+	return trimmed === "" ? undefined : trimmed;
+}
+
+/**
+ * Resolve the engine attachment mode once at boot.
+ *
+ * Precedence: an explicit `engine` object, then `APIFUSE__ENGINE__MODE`, then the
+ * `engineMode` option, then the default. The manifest outranks the option so
+ * provider code cannot silently downgrade what the deployment asked for; every
+ * disagreement is reported in `warnings` with a truthful `source` rather than
+ * being dropped.
+ *
+ * Deployment-authored input is never fatal (an unrecognized env value is warned
+ * about and ignored). A malformed `engineMode` option is a fault in the calling
+ * code, which no manifest can reach, so it throws.
+ */
+export function resolveProviderEngineMode(
+	input: ProviderEngineModeResolutionInput = {},
+): ProviderEngineModeResolution {
+	const environment = input.environment ?? process.env;
+	const warnings: ProviderEngineModeWarning[] = [];
+
+	// Read directly: this is a mode name, not a credential, so it must not be
+	// registered with the diagnostic redactor the way readDiagnosticEnv is.
+	const rawEnv = normalize(environment[PROVIDER_ENGINE_MODE_ENV]);
+	let envMode: ProviderEngineMode | undefined;
+	if (rawEnv !== undefined) {
+		if (isKnownMode(rawEnv)) envMode = rawEnv;
+		else warnings.push("invalid_env_value");
+	}
+
+	const optionMode = normalize(input.option);
+	if (input.option !== undefined && (optionMode === undefined || !isKnownMode(optionMode))) {
+		throw new ValidationError(
+			`Invalid engineMode option "${String(input.option)}"; expected ${KNOWN_PROVIDER_ENGINE_MODES.join(" or ")}`,
+			{ fix: 'Pass engineMode: "in-process" | "remote", or omit it to use the default.' },
+		);
+	}
+	if (optionMode !== undefined && envMode !== undefined && optionMode !== envMode) {
+		warnings.push("env_overrode_option");
+	}
+
+	const requested = envMode ?? optionMode;
+	const requestedSource: ProviderEngineModeSource | undefined =
+		envMode !== undefined ? "env" : optionMode !== undefined ? "option" : undefined;
+
+	// Normalized like every other mode input: an un-normalized host `kind` would
+	// reach the boot event and /readyz verbatim and mis-score the fleet audit.
+	const engineKind =
+		input.engine === undefined ? undefined : (normalize(input.engine.kind) ?? "custom");
+	if (engineKind !== undefined) {
+		if (requested !== undefined && engineKind !== requested) {
+			warnings.push("engine_object_overrode_requested_mode");
+		}
+		return finalize(engineKind, "engine", environment, warnings);
+	}
+
+	return finalize(
+		requested ?? DEFAULT_PROVIDER_ENGINE_MODE,
+		requestedSource ?? "default",
+		environment,
+		warnings,
+	);
+}
+
+function finalize(
+	mode: ProviderEngineMode | "custom",
+	source: ProviderEngineModeSource,
+	environment: Readonly<Record<string, string | undefined>>,
+	warnings: ProviderEngineModeWarning[],
+): ProviderEngineModeResolution {
+	// Presence of the remote engine env never selects a mode (the manifest
+	// generator projects it fleet-wide before the SDK can use it), but staying
+	// silent about it would hide a half-applied cutover. Skipped for a host-supplied
+	// engine: that object may be a remote client that consumes the env itself, so
+	// claiming the env is unused would be a false report.
+	if (
+		mode !== "remote" &&
+		source !== "engine" &&
+		REMOTE_ONLY_ENGINE_ENV_NAMES.some((name) => normalize(environment[name]) !== undefined)
+	) {
+		warnings.push("engine_env_ignored");
+	}
+	// Fail-closed for the ADR-0011 audit: everything that is not the remote lane
+	// still attaches capabilities inside the pod process and is scheduled for
+	// removal, including an opaque host engine that declares no kind.
+	return { mode, source, deprecated: mode !== "remote", warnings };
+}
+
+const UNAVAILABLE_ENGINES = new WeakSet<ProviderEngine>();
+
+/** True when the engine cannot attach, so readiness must report the process as unready. */
+export function isUnavailableProviderEngine(engine: ProviderEngine): boolean {
+	return UNAVAILABLE_ENGINES.has(engine);
+}
+
+/**
+ * Engine that refuses every attachment with `reason`.
+ *
+ * Requesting a mode this release cannot serve must not crash the process: the SDK
+ * answers a structured error per request and reports the process unready, the same
+ * trade-off `provider_secrets_missing` already makes at boot. Non-retryable, so a
+ * caller-side retry loop cannot turn a configuration fault into load.
+ */
+export function createUnavailableProviderEngine(
+	kind: ProviderEngineMode,
+	reason: { message: string; code: string; fix: string },
+): ProviderEngine {
+	const engine: ProviderEngine = {
+		kind,
+		attach: () => {
+			throw new ProviderError(reason.message, {
+				code: reason.code,
+				retryable: false,
+				fix: reason.fix,
+			});
+		},
+	};
+	UNAVAILABLE_ENGINES.add(engine);
+	return engine;
+}
+
+/**
+ * Engine for a resolved mode. `remote` has no client in this release, so it
+ * resolves to an engine that fails every request instead of falling back to
+ * in-process (ADR-0011 Pitfall 2: in-process is never a fallback).
+ */
+export function createEngineForMode(mode: ProviderEngineMode | "custom"): ProviderEngine {
+	// Default-deny on the mode name, not just on "remote": the mode union is open
+	// so a later lane can be named, and falling through to in-process for an
+	// unserved lane is the silent downgrade ADR-0011 Pitfall 2 forbids.
+	if (mode === DEFAULT_PROVIDER_ENGINE_MODE) return createInProcessProviderEngine();
+	return createUnavailableProviderEngine(mode, {
+		message: `Provider engine mode "${mode}" was requested but this @apifuse/provider-sdk release only serves the ${DEFAULT_PROVIDER_ENGINE_MODE} engine`,
+		code: "PROVIDER_ENGINE_MODE_UNSUPPORTED",
+		fix: `Unset ${PROVIDER_ENGINE_MODE_ENV} (or the engineMode option), or upgrade to a release that serves this mode.`,
+	});
+}
+
+/**
+ * Fail fast for the CLIs (`apifuse dev`, `apifuse record`). They are developer
+ * tools, not pods: an unusable mode should stop the command rather than start a
+ * server that refuses every request.
+ */
+export function assertProcessEngineModeSupported(
+	environment: Readonly<Record<string, string | undefined>> = process.env,
+): ProviderEngineModeResolution {
+	const resolution = resolveProviderEngineMode({ environment });
+	if (resolution.mode !== DEFAULT_PROVIDER_ENGINE_MODE) {
+		throw new ProviderError(
+			`Provider engine mode "${resolution.mode}" was requested but this @apifuse/provider-sdk release only serves the ${DEFAULT_PROVIDER_ENGINE_MODE} engine`,
+			{
+				code: "PROVIDER_ENGINE_MODE_UNSUPPORTED",
+				retryable: false,
+				details: { mode: resolution.mode, source: resolution.source },
+				fix: `Unset ${PROVIDER_ENGINE_MODE_ENV}, or upgrade to a release that serves this mode.`,
+			},
+		);
+	}
+	return resolution;
+}

package/src/runtime/handle.ts

@@ -3,7 +3,8 @@
  *
  * Storage layout: one state namespace per kind, `handle.<kind>`, scoped by the
  * kind's access (bound → connection scope via `state.forConnection`, public →
- * provider scope). The state key is the canonical handle string. Records hold
+ * provider scope; both cursors and drafts may be either). The state key is the
+ * canonical handle string. Records hold
  * the validated data plus status/timestamps; the handle string itself carries
  * no payload and no signature.
  */
@@ -26,6 +27,7 @@ import {
 	isDraftKind,
 	type ResultOf,
 } from "../handle.js";
+import { formatHandleIssuers } from "../handle-meta.js";
 import type {
 	ProviderRequestContext,
 	ProviderRuntimeState,
@@ -246,9 +248,8 @@ export function formatNormalizationClasses(classes: readonly string[]): string {
 // ---------------------------------------------------------------------------
 
 function publicCollapsedMessage(kind: HandleKind): string {
-	const again = kind.issuedBy
-		? `Call \`${kind.issuedBy}\` again to get a new one.`
-		: "Request a new one.";
+	const issuers = formatHandleIssuers(kind.issuedBy);
+	const again = issuers ? `Call ${issuers} again to get a new one.` : "Request a new one.";
 	return `\`${kind.fieldName}\` is not valid or has expired. ${again}`;
 }
 
@@ -257,7 +258,7 @@ function normalizationError(kind: HandleKind, failure: NormalizationFailure): Ha
 		return new HandleError(
 			"HANDLE_KIND_MISMATCH",
 			`\`${kind.fieldName}\` must be a \`${kind.name}_...\` handle as returned by ${
-				kind.issuedBy ? `\`${kind.issuedBy}\`` : "the issuing operation"
+				formatHandleIssuers(kind.issuedBy) ?? "the issuing operation"
 			}. ${handleRecoverySentence(kind)}`,
 			{ kind: kind.name, details: { field: kind.fieldName } },
 		);
@@ -352,7 +353,7 @@ function committedError(kind: HandleKind): HandleError {
 function connectionRequiredError(kind: HandleKind, operation: HandleOperation): HandleError {
 	return new HandleError(
 		"HANDLE_CONNECTION_REQUIRED",
-		`Handle kind "${kind.name}" is bound to a connection, but request.connectionId is missing for ${operation}. Bound handles require a connection-scoped request; use access: "public" for connection-less cursors.`,
+		`Handle kind "${kind.name}" is bound to a connection, but request.connectionId is missing for ${operation}. Bound handles require a connection-scoped request; use access: "public" for connection-less kinds.`,
 		{ kind: kind.name },
 	);
 }
@@ -738,8 +739,11 @@ export function createHandleContext(options: CreateHandleContextOptions): Handle
 		};
 	}
 
-	async function create<K extends HandleKind>(kind: K, data: InputOf<K>): Promise<string> {
-		return await instrumented<string>(kind, "create", async (report) => {
+	async function createRecord<K extends HandleKind>(
+		kind: K,
+		data: InputOf<K>,
+	): Promise<HandleRecord<K>> {
+		return await instrumented<HandleRecord<K>>(kind, "create", async (report) => {
 			const validated = validateData(kind, "create", data);
 			const namespace = resolveNamespace(kind, "create");
 			const now = nowMs();
@@ -766,7 +770,9 @@ export function createHandleContext(options: CreateHandleContextOptions): Handle
 				const result = await storage(kind, () =>
 					namespace.compareAndSet(canonical, 0, record, { ttl: msDuration(writeTtlMs) }),
 				);
-				if (result.ok) return { value: canonical, outcome: "success" };
+				if (result.ok) {
+					return { value: toHandleRecord(kind, canonical, record), outcome: "success" };
+				}
 			}
 			throw storageUnavailableError(
 				kind,
@@ -775,6 +781,10 @@ export function createHandleContext(options: CreateHandleContextOptions): Handle
 		});
 	}
 
+	async function create<K extends HandleKind>(kind: K, data: InputOf<K>): Promise<string> {
+		return (await createRecord(kind, data)).handle;
+	}
+
 	async function read<K extends HandleKind>(kind: K, handle: string): Promise<HandleRecord<K>> {
 		return await instrumented<HandleRecord<K>>(kind, "read", async (report) => {
 			const loaded = await load(kind, "read", handle, report);
@@ -1139,7 +1149,7 @@ export function createHandleContext(options: CreateHandleContextOptions): Handle
 		});
 	}
 
-	return { create, read, update, commit, discard };
+	return { create, createRecord, read, update, commit, discard };
 }
 
 /**

package/src/runtime/http-telemetry-binding.ts

@@ -0,0 +1,162 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { HttpClient } from "../types.js";
+import { type HttpTelemetrySink, httpTelemetryErrorCode } from "./http-telemetry.js";
+import { startHttpTelemetry } from "./http-telemetry-guard.js";
+import {
+	proxyTransportRetryErrorCode,
+	proxyTransportRetryErrorStatus,
+} from "./proxy-retry-policy.js";
+
+type HttpTelemetryScope = { sink: HttpTelemetrySink; nativeObserved: boolean };
+const scopes = new AsyncLocalStorage<HttpTelemetryScope>();
+const methods = new Set(["request", "get", "post", "put", "delete", "stream", "sse"]);
+type AdapterState = { sink: HttpTelemetrySink; adapter: HttpClient };
+const adapters = new WeakMap<object, AdapterState>();
+let unsupportedShapeWarned = false;
+
+/** Return whether a host binding has at least one callable declared HTTP method. */
+export function isSupportedHttpBinding(value: unknown): value is HttpClient {
+	if ((typeof value !== "object" && typeof value !== "function") || value === null) return false;
+	for (const method of methods) {
+		try {
+			if (typeof Reflect.get(value, method) === "function") return true;
+		} catch {
+			// A hostile property getter is not a usable binding.
+		}
+	}
+	return false;
+}
+
+/** Emit the unsupported-shape warning once for the process. */
+export function warnUnsupportedHttpBinding(): void {
+	if (unsupportedShapeWarned) return;
+	unsupportedShapeWarned = true;
+	try {
+		console.warn("[apifuse] http telemetry not attached; reason=unsupported_binding_shape");
+	} catch {
+		// Warning output is diagnostic only and must not affect request handling.
+	}
+}
+
+/** Route SDK transports inside a host binding through the same attempt collector. */
+export function scopedHttpTelemetry(
+	existing: HttpTelemetrySink | undefined,
+): HttpTelemetrySink | undefined {
+	const scope = scopes.getStore();
+	if (!scope) return existing;
+	scope.nativeObserved = true;
+	if (!existing || existing === scope.sink) return scope.sink;
+	return {
+		markTelemetryFailed: () => scope.sink.markTelemetryFailed?.(),
+		startRequest(options) {
+			const request = startHttpTelemetry(scope.sink, options.retryPreset);
+			const observer = startHttpTelemetry(
+				{
+					startRequest: (options) => existing.startRequest(options),
+					markTelemetryFailed() {
+						scope.sink.markTelemetryFailed?.();
+						existing.markTelemetryFailed?.();
+					},
+				},
+				options.retryPreset,
+			);
+			return {
+				recordAttempt(event) {
+					request.recordAttempt(event);
+					observer.recordAttempt(event);
+				},
+				finish(ms) {
+					request.finish(ms);
+					observer.finish(ms);
+				},
+				toTenantRetryPayload() {
+					observer.toTenantRetryPayload();
+					return request.toTenantRetryPayload();
+				},
+			};
+		},
+	};
+}
+
+/** Observe opaque host calls without changing their arguments, receiver or returned promise. */
+export function bindHttpTelemetry(client: HttpClient, sink: HttpTelemetrySink): HttpClient {
+	if ((typeof client === "object" && client !== null) || typeof client === "function") {
+		const existing = adapters.get(client as object);
+		if (existing) {
+			existing.sink = sink;
+			return existing.adapter;
+		}
+	}
+	const wrappers = new Map<
+		PropertyKey,
+		{ original: unknown; wrapped: (...args: unknown[]) => unknown }
+	>();
+	// An inheriting target also supports hosts whose own methods are frozen.
+	const adapter = new Proxy(Object.create(client) as HttpClient, {
+		get(_target, property) {
+			const original: unknown = Reflect.get(client, property, client);
+			if (typeof property !== "string" || !methods.has(property) || typeof original !== "function")
+				return original;
+			const cached = wrappers.get(property);
+			if (cached?.original === original) return cached.wrapped;
+			const wrapped = function (this: unknown, ...args: unknown[]) {
+				// Direct calls keep the host receiver; explicit and unbound receivers pass through.
+				const receiver = this === adapter ? client : this;
+				const scope: HttpTelemetryScope = { sink: state.sink, nativeObserved: false };
+				const started = performance.now();
+				const settled = (result: unknown, failed: boolean) => {
+					if (scope.nativeObserved) return;
+					const request = startHttpTelemetry(state.sink, undefined);
+					request.observe(() => {
+						const status = failed
+							? proxyTransportRetryErrorStatus(result)
+							: result &&
+									typeof result === "object" &&
+									"status" in result &&
+									typeof result.status === "number"
+								? result.status
+								: undefined;
+						request.recordAttempt({
+							ms: performance.now() - started,
+							proxyUsed: false,
+							...(status === undefined ? {} : { status }),
+							...(failed
+								? { e: httpTelemetryErrorCode(proxyTransportRetryErrorCode(result)) }
+								: {}),
+						});
+					});
+					request.finish(performance.now() - started);
+				};
+				return scopes.run(scope, () => {
+					let result: unknown;
+					try {
+						result = Reflect.apply(original, receiver, args);
+					} catch (error) {
+						settled(error, true);
+						throw error;
+					}
+					try {
+						if (result instanceof Promise) {
+							void Promise.prototype.then.call(
+								result,
+								(value: unknown) => settled(value, false),
+								(error: unknown) => settled(error, true),
+							);
+						} else settled(result, false);
+					} catch (error) {
+						// Promise subclasses may throw while a telemetry continuation is attached.
+						startHttpTelemetry(state.sink, undefined).observe(() => {
+							throw error;
+						});
+					}
+					return result;
+				});
+			};
+			wrappers.set(property, { original, wrapped });
+			return wrapped;
+		},
+	});
+	const state: AdapterState = { sink, adapter };
+	adapters.set(adapter as object, state);
+	return adapter;
+}

package/src/runtime/http-telemetry-guard.ts

@@ -0,0 +1,208 @@
+import { isPromise } from "node:util/types";
+import type { HttpRetrySummary } from "../types.js";
+import {
+	HttpTelemetryCollector,
+	type HttpTelemetryRequestSink,
+	type HttpTelemetrySink,
+} from "./http-telemetry.js";
+
+const intrinsicPromiseThen = Promise.prototype.then;
+const ignoreObserverResult = () => {};
+
+/** Attach handlers only through the Promise intrinsic; never invoke a host thenable. */
+function absorbObserverPromise(value: object): void {
+	let constructorDescriptor: PropertyDescriptor | undefined;
+	let shadowed = false;
+	try {
+		constructorDescriptor = Object.getOwnPropertyDescriptor(value, "constructor");
+		// Even the intrinsic `then` consults Symbol.species. An undefined constructor
+		// selects its intrinsic Promise without reading a subclass's species getter.
+		Object.defineProperty(value, "constructor", {
+			value: undefined,
+			configurable: constructorDescriptor?.configurable ?? true,
+		});
+		shadowed = true;
+	} catch {
+		// Non-extensible ordinary promises can still accept intrinsic handlers.
+	}
+	try {
+		void intrinsicPromiseThen.call(value, ignoreObserverResult, ignoreObserverResult);
+	} catch {
+		// A non-Promise thenable has no intrinsic rejection to absorb. Do not run it.
+	} finally {
+		if (shadowed) {
+			try {
+				if (constructorDescriptor) {
+					Object.defineProperty(value, "constructor", constructorDescriptor);
+				} else {
+					Reflect.deleteProperty(value, "constructor");
+				}
+			} catch {
+				// Host object traps are also observer failures.
+			}
+		}
+	}
+}
+
+function isAsyncObserverReturn(value: unknown): boolean {
+	if (!value || (typeof value !== "object" && typeof value !== "function")) return false;
+	try {
+		if (!isPromise(value) && (!("then" in value) || typeof value.then !== "function")) return false;
+	} catch {
+		// A rejected Promise can itself have a throwing `then` getter. Still absorb it.
+	}
+	absorbObserverPromise(value);
+	return true;
+}
+
+/** Shared synchronous observer boundary for transport and capability contributors. */
+export function observeTelemetry<T>(callback: () => T, fail: () => void): T | undefined {
+	try {
+		const result = callback();
+		if (isAsyncObserverReturn(result)) {
+			fail();
+			return undefined;
+		}
+		return result;
+	} catch {
+		fail();
+		return undefined;
+	}
+}
+
+/** Isolate synchronous void capability hooks using the same Promise defence. */
+export function createTelemetryObserver(
+	sink: { markTelemetryFailed?(): void } | undefined,
+): (callback: () => unknown) => void {
+	let failed = false;
+	const fail = () => {
+		if (failed) return;
+		failed = true;
+		try {
+			isAsyncObserverReturn(sink?.markTelemetryFailed?.());
+		} catch {
+			// The failure marker is also an observer.
+		}
+	};
+	return (callback) => {
+		try {
+			const result = callback();
+			if (result !== undefined) {
+				isAsyncObserverReturn(result);
+				fail();
+			}
+		} catch {
+			fail();
+		}
+	};
+}
+
+/** Keep all public observers, including property access, outside transport failures. */
+export function startHttpTelemetry(
+	sink: HttpTelemetrySink | undefined,
+	retryPreset: HttpRetrySummary["preset"],
+): HttpTelemetryRequestSink & { observe(callback: () => void): void } {
+	let failed = false;
+	const fail = () => {
+		if (failed) return;
+		failed = true;
+		try {
+			isAsyncObserverReturn(sink?.markTelemetryFailed?.());
+		} catch {
+			// The failure reporter is itself an observer. Never recurse.
+		}
+	};
+	const observe = <T>(callback: () => T): T | undefined => observeTelemetry(callback, fail);
+	const result = observe(() =>
+		(sink ?? new HttpTelemetryCollector()).startRequest({ retryPreset }),
+	);
+	const request = observe(() => {
+		if (
+			!result ||
+			typeof result.recordAttempt !== "function" ||
+			typeof result.finish !== "function" ||
+			typeof result.toTenantRetryPayload !== "function"
+		) {
+			fail();
+			return undefined;
+		}
+		return result;
+	});
+	return {
+		observe,
+		recordAttempt: (event) => {
+			observe(() => request?.recordAttempt(event));
+		},
+		finish: (ms) => {
+			observe(() => request?.finish(ms));
+		},
+		toTenantRetryPayload: () => {
+			if (failed) return undefined;
+			return observe(() => {
+				const value = observe(() => request?.toTenantRetryPayload());
+				if (value === undefined) return undefined;
+				// Copy only validated primitive fields; never pass observer-owned objects on.
+				const { attempts, retries, preset, transport, lastErrorCode, lastStatus } = value;
+				if (
+					!Number.isSafeInteger(attempts) ||
+					attempts < 2 ||
+					!Number.isSafeInteger(retries) ||
+					(retries !== attempts - 1 &&
+						!(attempts === Number.MAX_SAFE_INTEGER && retries === Number.MAX_SAFE_INTEGER)) ||
+					transport !== "native" ||
+					(preset !== undefined &&
+						![
+							"off",
+							"transport_transient",
+							"safe_read",
+							"aggressive_read",
+							"rate_limit_aware",
+						].includes(preset)) ||
+					(lastErrorCode !== undefined &&
+						![
+							"transport_network_error",
+							"transport_timeout",
+							"transport_cancelled",
+							"upstream_http_error",
+							"other",
+						].includes(lastErrorCode)) ||
+					(lastStatus !== undefined && (!Number.isSafeInteger(lastStatus) || lastStatus < 0))
+				) {
+					fail();
+					return undefined;
+				}
+				return {
+					attempts,
+					retries,
+					...(preset === undefined ? {} : { preset }),
+					transport,
+					...(lastErrorCode === undefined ? {} : { lastErrorCode }),
+					...(lastStatus === undefined ? {} : { lastStatus }),
+				};
+			});
+		},
+	};
+}
+
+/** Generic observer guard shared by capability hooks. Returned thenables are absorbed. */
+export function observeTelemetryCallback(
+	sink: { markTelemetryFailed?: () => unknown } | undefined,
+	callback: () => unknown,
+): void {
+	let failed = false;
+	const fail = () => {
+		if (failed) return;
+		failed = true;
+		try {
+			isAsyncObserverReturn(sink?.markTelemetryFailed?.());
+		} catch {
+			// Observer failure is never transport failure.
+		}
+	};
+	try {
+		const result = callback();
+		if (isAsyncObserverReturn(result) || result !== undefined) fail();
+	} catch {
+		fail();
+	}
+}