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

package/src/runtime/cache-telemetry.ts

@@ -0,0 +1,247 @@
+import { Buffer } from "node:buffer";
+import type { ProviderCacheLookupMeta } from "../types.js";
+import {
+	closedEnum,
+	type ClosedEnum,
+	type SpanIndex,
+	type TelemetryContributor,
+} from "./request-telemetry.js";
+import { createTelemetryObserver } from "./http-telemetry-guard.js";
+
+export type CacheTelemetrySource = "memory" | "redis" | "loader";
+
+export type CacheTelemetrySample = {
+	key: string;
+	hit: boolean;
+	stale: boolean;
+	ageMs?: number;
+	source: CacheTelemetrySource;
+};
+
+export type CacheTelemetryLogPayload = {
+	telemetryFailed?: true;
+	lookups: number;
+	hits: number;
+	stale: number;
+	misses: number;
+	writes: number;
+	loaderErrors: number;
+	writeErrors: number;
+	source: { memory: number; redis: number; loader: number };
+	redisFallbacks: number;
+	redisMode: ClosedEnum<"not_configured" | "configured" | "degraded">;
+	/** Successful Redis commands, including reads, writes, and deletes; memory-only work counts zero. */
+	redisRoundTrips: number;
+	ageMs?: { p50: number; max: number };
+	samples: CacheTelemetrySample[];
+	dropped: number;
+};
+
+export type CacheTelemetryHeaderPayload = Omit<
+	CacheTelemetryLogPayload,
+	"samples" | "ageMs" | "telemetryFailed"
+> & {
+	ageP50?: number;
+	ageMax?: number;
+};
+
+export interface CacheTelemetrySink {
+	markTelemetryFailed?(): void;
+	setRedisConfigured?(configured: boolean): void;
+	recordLookup(meta: ProviderCacheLookupMeta): void;
+	recordWrite(): void;
+	recordLoaderError?(): void;
+	recordWriteError?(): void;
+	recordRedisFallback(): void;
+	recordRedisRoundTrip?(): void;
+}
+
+const cacheTelemetryBindings = new WeakMap<object, CacheTelemetrySink>();
+
+/** Internal construction binding; keeps sink plumbing off ProviderCacheOptions. */
+export function bindCacheTelemetry<T extends object>(
+	options: T,
+	sink: CacheTelemetrySink | undefined,
+): T {
+	if (sink) cacheTelemetryBindings.set(options, sink);
+	return options;
+}
+
+/** Internal lookup used only by the cache factory. */
+export function cacheTelemetryFor(options: object): CacheTelemetrySink | undefined {
+	return cacheTelemetryBindings.get(options);
+}
+
+export function guardCacheTelemetry(sink: CacheTelemetrySink | undefined): CacheTelemetrySink {
+	const observe = createTelemetryObserver(sink);
+	return {
+		setRedisConfigured: (configured) => observe(() => sink?.setRedisConfigured?.(configured)),
+		recordLookup: (meta) => observe(() => sink?.recordLookup(meta)),
+		recordWrite: () => observe(() => sink?.recordWrite()),
+		recordLoaderError: () => observe(() => sink?.recordLoaderError?.()),
+		recordWriteError: () => observe(() => sink?.recordWriteError?.()),
+		recordRedisFallback: () => observe(() => sink?.recordRedisFallback()),
+		recordRedisRoundTrip: () => observe(() => sink?.recordRedisRoundTrip?.()),
+	};
+}
+
+const MAX_SAMPLES = 24;
+const MAX_TEXT = 300;
+
+function integer(value: number): number {
+	return Number.isFinite(value)
+		? Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value)))
+		: Number.MAX_SAFE_INTEGER;
+}
+
+function add(a: number, b: number): number {
+	return Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+}
+
+function boundedText(value: string, redact?: (text: string) => string): string {
+	let result: string;
+	try {
+		result = redact?.(value) ?? value;
+	} catch {
+		result = "[REDACTION_FAILED]";
+	}
+	const length = Math.min(result.length, MAX_TEXT);
+	const units = Buffer.alloc(length * 2);
+	for (let index = 0; index < length; index += 1)
+		units.writeUInt16LE(result.charCodeAt(index), index * 2);
+	return units.toString("utf16le");
+}
+
+export class CacheTelemetryCollector
+	implements
+		TelemetryContributor<CacheTelemetryLogPayload, CacheTelemetryHeaderPayload>,
+		CacheTelemetrySink
+{
+	readonly key = "cache" as const;
+	readonly #redact?: (text: string) => string;
+	#telemetryFailed = false;
+	#lookups = 0;
+	#hits = 0;
+	#stale = 0;
+	#misses = 0;
+	#writes = 0;
+	#loaderErrors = 0;
+	#writeErrors = 0;
+	#source = { memory: 0, redis: 0, loader: 0 };
+	#redisFallbacks = 0;
+	#configured: "not_configured" | "configured" | "degraded";
+	#redisRoundTrips = 0;
+	#ages: number[] = [];
+	#maxAge = 0;
+	#samples: CacheTelemetrySample[] = [];
+	#dropped = 0;
+
+	constructor(options: { redact?: (text: string) => string } = {}) {
+		this.#redact = options.redact;
+		this.#configured = "not_configured";
+	}
+	setRedisConfigured(configured: boolean): void {
+		if (configured && this.#configured === "not_configured") this.#configured = "configured";
+	}
+	markTelemetryFailed(): void {
+		this.#telemetryFailed = true;
+	}
+
+	recordLookup(meta: ProviderCacheLookupMeta): void {
+		if (!["memory", "redis", "loader"].includes(meta.source)) {
+			this.#telemetryFailed = true;
+			return;
+		}
+		this.#lookups = add(this.#lookups, 1);
+		if (meta.hit) this.#hits = add(this.#hits, 1);
+		else this.#misses = add(this.#misses, 1);
+		if (meta.stale) this.#stale = add(this.#stale, 1);
+		this.#source[meta.source] = add(this.#source[meta.source], 1);
+		if (meta.source === "redis" && this.#configured === "not_configured")
+			this.#configured = "configured";
+		if (meta.ageMs !== undefined) {
+			const age = integer(meta.ageMs);
+			if (this.#ages.length < MAX_SAMPLES) this.#ages.push(age);
+			this.#maxAge = Math.max(this.#maxAge, age);
+		}
+		if (this.#samples.length < MAX_SAMPLES) {
+			this.#samples.push({
+				key: boundedText(meta.key, this.#redact),
+				hit: meta.hit,
+				stale: meta.stale,
+				...(meta.ageMs === undefined ? {} : { ageMs: integer(meta.ageMs) }),
+				source: meta.source,
+			});
+		} else this.#dropped = add(this.#dropped, 1);
+	}
+
+	recordWrite(): void {
+		this.#writes = add(this.#writes, 1);
+	}
+	recordLoaderError(): void {
+		this.#loaderErrors = add(this.#loaderErrors, 1);
+	}
+	recordWriteError(): void {
+		this.#writeErrors = add(this.#writeErrors, 1);
+	}
+
+	recordRedisFallback(): void {
+		this.#redisFallbacks = add(this.#redisFallbacks, 1);
+		this.#configured = "degraded";
+	}
+
+	recordRedisRoundTrip(): void {
+		this.#redisRoundTrips = add(this.#redisRoundTrips, 1);
+	}
+
+	toLogPayload(_spans: SpanIndex): CacheTelemetryLogPayload | undefined {
+		if (
+			this.#lookups === 0 &&
+			this.#writes === 0 &&
+			this.#redisFallbacks === 0 &&
+			!this.#telemetryFailed
+		)
+			return undefined;
+		const sorted = [...this.#ages].sort((a, b) => a - b);
+		const p50 = sorted.length ? sorted[Math.floor((sorted.length - 1) / 2)]! : undefined;
+		return {
+			...(this.#telemetryFailed ? { telemetryFailed: true as const } : {}),
+			lookups: this.#lookups,
+			hits: this.#hits,
+			stale: this.#stale,
+			misses: this.#misses,
+			writes: this.#writes,
+			loaderErrors: this.#loaderErrors,
+			writeErrors: this.#writeErrors,
+			source: { ...this.#source },
+			redisFallbacks: this.#redisFallbacks,
+			redisMode: closedEnum(this.#configured),
+			redisRoundTrips: this.#redisRoundTrips,
+			...(p50 === undefined ? {} : { ageMs: { p50, max: this.#maxAge } }),
+			samples: this.#samples.map((sample) => ({ ...sample })),
+			dropped: this.#dropped,
+		};
+	}
+
+	toHeaderPayload(log: CacheTelemetryLogPayload): CacheTelemetryHeaderPayload {
+		return {
+			lookups: log.lookups,
+			hits: log.hits,
+			stale: log.stale,
+			misses: log.misses,
+			writes: log.writes,
+			loaderErrors: log.loaderErrors,
+			writeErrors: log.writeErrors,
+			source: {
+				memory: log.source.memory,
+				redis: log.source.redis,
+				loader: log.source.loader,
+			},
+			redisFallbacks: log.redisFallbacks,
+			redisMode: log.redisMode,
+			redisRoundTrips: log.redisRoundTrips,
+			...(log.ageMs ? { ageP50: log.ageMs.p50, ageMax: log.ageMs.max } : {}),
+			dropped: log.dropped,
+		};
+	}
+}

package/src/runtime/cache.ts

@@ -11,6 +11,7 @@ import type {
 	ProviderCacheResponseMeta,
 	ProviderCacheResult,
 } from "../types.js";
+import { cacheTelemetryFor, guardCacheTelemetry } from "./cache-telemetry.js";
 import {
 	createProviderRedisClient,
 	ensureRedisReady,
@@ -135,15 +136,13 @@ function assertJsonSafeSecretValue(
 	if (typeof value === "number") {
 		if (!Number.isFinite(value))
 			unsupportedSecretValue(reportedPath, "non-finite numbers are unsupported");
-		if (Object.is(value, -0))
-			unsupportedSecretValue(reportedPath, "negative zero is unsupported");
+		if (Object.is(value, -0)) unsupportedSecretValue(reportedPath, "negative zero is unsupported");
 		return;
 	}
 	if (typeof value !== "object") {
 		unsupportedSecretValue(reportedPath, `${typeof value} values are unsupported`);
 	}
-	if (ancestors.has(value))
-		unsupportedSecretValue(reportedPath, "cyclic values are unsupported");
+	if (ancestors.has(value)) unsupportedSecretValue(reportedPath, "cyclic values are unsupported");
 
 	ancestors.add(value);
 	try {
@@ -156,8 +155,7 @@ function assertJsonSafeSecretValue(
 				const key = String(index);
 				expectedNames.add(key);
 				const descriptor = Object.getOwnPropertyDescriptor(value, key);
-				if (!descriptor)
-					unsupportedSecretValue(reportedPath, "sparse arrays are unsupported");
+				if (!descriptor) unsupportedSecretValue(reportedPath, "sparse arrays are unsupported");
 				if (!descriptor.enumerable || !("value" in descriptor)) {
 					unsupportedSecretValue(reportedPath, "array accessors are unsupported");
 				}
@@ -275,10 +273,7 @@ function hashSecretValue(
 	return { value: `hmac-sha256:${digest}`, secretScoped: true };
 }
 
-function metadataKeys(
-	events: ProviderCacheLookupMeta[],
-	secretScopedKeys: Set<string>,
-): string[] {
+function metadataKeys(events: ProviderCacheLookupMeta[], secretScopedKeys: Set<string>): string[] {
 	let secretScopedIndex = 0;
 	return Array.from(new Set(events.map((event) => event.key))).map((key) => {
 		if (!secretScopedKeys.has(key)) return key;
@@ -369,10 +364,14 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 	const memoryMaxEntries = Math.max(1, options.memoryMaxEntries ?? DEFAULT_MEMORY_MAX_ENTRIES);
 	const now = options.now ?? Date.now;
 	const events: ProviderCacheLookupMeta[] = [];
+	const telemetry = guardCacheTelemetry(cacheTelemetryFor(options));
+	telemetry.setRedisConfigured?.(!!redisUrl);
+	let redisUnavailable = false;
 	const secretScopedKeys = new Set<string>();
 
 	function record(meta: ProviderCacheLookupMeta): void {
 		events.push(meta);
+		telemetry?.recordLookup(meta);
 	}
 
 	function sweepMemory(currentTime: number): void {
@@ -416,13 +415,22 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 	} | null> {
 		const redis = backend.redis;
 		if (!redis || !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
+			if (redis) {
+				redisUnavailable = true;
+				telemetry?.recordRedisFallback();
+			}
 			return null;
 		}
 
 		const raw = await withRedisFallback(async () => {
 			return await redis.get(key);
 		});
-		if (typeof raw !== "string" && raw !== null) return null;
+		if (typeof raw !== "string" && raw !== null) {
+			redisUnavailable = true;
+			telemetry.recordRedisFallback();
+			return null;
+		}
+		telemetry?.recordRedisRoundTrip?.();
 
 		const envelope = safeParseEnvelope(raw);
 		if (!envelope) return null;
@@ -473,6 +481,7 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 		value: T,
 		cacheOptions: ProviderCacheGetOrSetOptions,
 	): Promise<void> {
+		telemetry?.recordWrite();
 		const currentTime = now();
 		const freshTtlMs = jitteredTtlMs(cacheOptions.ttlMs, cacheOptions.jitterPct);
 		const staleIfErrorMs = cacheOptions.staleIfErrorMs ?? 0;
@@ -487,9 +496,21 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 
 		const redis = backend.redis;
 		if (!redis || !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
+			if (redis) {
+				redisUnavailable = true;
+				telemetry?.recordRedisFallback();
+				telemetry?.recordWriteError?.();
+			}
 			return;
 		}
-		await withRedisFallback(() => redis.set(key, JSON.stringify(envelope), "PX", staleTtlMs));
+		const written = await withRedisFallback(() =>
+			redis.set(key, JSON.stringify(envelope), "PX", staleTtlMs),
+		);
+		if (written === undefined) {
+			redisUnavailable = true;
+			telemetry?.recordRedisFallback();
+			telemetry?.recordWriteError?.();
+		} else telemetry?.recordRedisRoundTrip?.();
 	}
 
 	async function loadAndStore<T>(
@@ -514,6 +535,13 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 			if (staleCandidate?.meta.stale) {
 				return staleCandidate;
 			}
+			telemetry?.recordLookup({
+				key,
+				hit: false,
+				stale: false,
+				source: "loader",
+			});
+			telemetry?.recordLoaderError?.();
 			throw error;
 		}
 	}
@@ -530,18 +558,29 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 		async get<T = unknown>(key: string): Promise<ProviderCacheResult<T> | null> {
 			const result = await read<T>(key);
 			if (result) record(result.meta);
+			else
+				telemetry.recordLookup({
+					key,
+					hit: false,
+					stale: false,
+					source: backend.redis && !redisUnavailable ? "redis" : "memory",
+				});
 			return result;
 		},
 
 		set: write,
 
 		async delete(key: string): Promise<void> {
+			telemetry?.recordWrite();
 			backend.memory.delete(key);
 			const redis = backend.redis;
 			if (!redis || !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
+				if (redis) telemetry?.recordRedisFallback();
 				return;
 			}
-			await withRedisFallback(() => redis.del(key));
+			const deleted = await withRedisFallback(() => redis.del(key));
+			if (deleted === undefined) telemetry?.recordRedisFallback();
+			else telemetry?.recordRedisRoundTrip?.();
 		},
 
 		async getOrSet<T = unknown>(
@@ -557,10 +596,22 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 
 			const existingInflight = backend.inflight.get(key);
 			if (existingInflight) {
-				const inflightResult = await existingInflight;
-				const result = resultWithValue<T>(inflightResult.value, inflightResult.meta);
-				record(result.meta);
-				return result;
+				try {
+					const inflightResult = await existingInflight;
+					const result = resultWithValue<T>(inflightResult.value, inflightResult.meta);
+					record(result.meta);
+					return result;
+				} catch (error) {
+					const meta: ProviderCacheLookupMeta = {
+						key,
+						hit: false,
+						stale: false,
+						source: "loader",
+					};
+					telemetry.recordLookup(meta);
+					telemetry?.recordLoaderError?.();
+					throw error;
+				}
 			}
 
 			const promise: Promise<ProviderCacheResult<unknown>> = loadAndStore(

package/src/runtime/capability-response.ts

@@ -0,0 +1,53 @@
+export const CAPABILITY_BODY_UNAVAILABLE = "<body unavailable>";
+
+/** Read optional diagnostic response text without letting a body stall the request failure. */
+export async function readCapabilityErrorBody(
+	response: Response,
+	signal: AbortSignal,
+): Promise<string> {
+	if (signal.aborted) return CAPABILITY_BODY_UNAVAILABLE;
+
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let onAbort: (() => void) | undefined;
+	let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+	let unavailableWon = false;
+	const cancelBody = (reason: unknown) => {
+		const cancellation = reader ? reader.cancel(reason) : response.body?.cancel(reason);
+		if (cancellation) void cancellation.catch(() => {});
+	};
+	const unavailable = new Promise<string>((resolve) => {
+		onAbort = () => {
+			unavailableWon = true;
+			resolve(CAPABILITY_BODY_UNAVAILABLE);
+			cancelBody(signal.reason);
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		timer = setTimeout(() => {
+			unavailableWon = true;
+			resolve(CAPABILITY_BODY_UNAVAILABLE);
+			cancelBody(new Error("capability error body read timeout"));
+		}, 250);
+	});
+	const body = Promise.resolve()
+		.then(async () => {
+			if (unavailableWon) return CAPABILITY_BODY_UNAVAILABLE;
+			if (!response.body) return response.text();
+			reader = response.body.getReader();
+			const decoder = new TextDecoder();
+			let text = "";
+			while (true) {
+				if (unavailableWon) return CAPABILITY_BODY_UNAVAILABLE;
+				const chunk = await reader.read();
+				if (chunk.done) return text + decoder.decode();
+				text += decoder.decode(chunk.value, { stream: true });
+			}
+		})
+		.catch(() => CAPABILITY_BODY_UNAVAILABLE);
+
+	try {
+		return await Promise.race([body, unavailable]);
+	} finally {
+		if (timer !== undefined) clearTimeout(timer);
+		if (onAbort) signal.removeEventListener("abort", onAbort);
+	}
+}

package/src/runtime/capability-telemetry.ts

@@ -0,0 +1,101 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Buffer } from "node:buffer";
+import { registerDiagnosticValue } from "./diagnostic-env.js";
+import { redactDiagnosticText } from "./diagnostic-redactor.js";
+import { observeTelemetry } from "./http-telemetry-guard.js";
+import { boundedText } from "./resolver-telemetry.js";
+
+/** Internal capture facts, isolated across concurrent calls and never attached to caller results. */
+export type CapabilityFacts = { status?: number; finishReason?: string; diagnostics?: string };
+export const capabilityFacts = new AsyncLocalStorage<CapabilityFacts>();
+const metadata = new WeakMap<object, { backend: string; engine: string; model?: string }>();
+export function tagCapability<T extends object>(
+	context: T,
+	facts: { backend: string; engine: string; model?: string },
+): T {
+	metadata.set(context, facts);
+	return context;
+}
+export function capabilityMetadata(context: object) {
+	return metadata.get(context);
+}
+export function captureCapability(facts: CapabilityFacts): void {
+	const current = capabilityFacts.getStore();
+	if (current) Object.assign(current, facts);
+}
+export function registerCapabilityInput(input: {
+	kind: string;
+	data?: string;
+	url?: string;
+}): void {
+	// Payloads are measurements, never redaction needles. Only bounded URLs belong
+	// in the request inventory; structural stripping covers oversized URL echoes.
+	if (input.kind === "url" && input.url && Buffer.byteLength(input.url) <= 2048)
+		registerDiagnosticValue(input.url.trim());
+}
+/**
+ * Formats capability diagnostics after credential redaction.
+ * When `stripPayload` is enabled, long base64-shaped runs are replaced as a
+ * defence in depth; this may replace an unregistered long identifier, while
+ * protecting against the more likely case of payload data in an upstream body.
+ */
+export function capabilityText(
+	value: string,
+	redact?: (text: string) => string,
+	stripPayload = false,
+): string {
+	const stripped = value
+		.replace(
+			/(?:authorization|proxy-authorization|cookie|set-cookie)\s*["']?\s*[:=]\s*[^\r\n]+/gi,
+			"[REDACTED]",
+		)
+		.replace(/Bearer\s+[^\r\n]+/gi, "[REDACTED]")
+		.replace(/https?:\/\/[^\s"'<>]+/gi, "[REDACTED]")
+		.replace(/data:[^\s"']+/gi, "[BASE64_STRIPPED]");
+	return boundedText(
+		stripPayload ? stripped.replace(/[A-Za-z0-9+/=]{64,}/g, "[BASE64_STRIPPED]") : stripped,
+		(text) => redactDiagnosticText(text, redact),
+	);
+}
+export function capabilityErrorText(error: unknown): string {
+	if (!(error instanceof Error)) return String(error);
+	const details = "details" in error ? error.details : undefined;
+	const body =
+		details && typeof details === "object" && "body" in details ? details.body : undefined;
+	return `${error.message}${typeof body === "string" ? ` ${body}` : ""}`;
+}
+export const integer = (n: number | undefined) =>
+	Math.min(
+		Number.MAX_SAFE_INTEGER,
+		Math.max(0, Math.floor(Number.isFinite(n ?? 0) ? (n ?? 0) : 0)),
+	);
+export const add = (a: number, b: number) =>
+	Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+export function inputBytes(input: { kind: string; data?: string }): number | undefined {
+	if (input.kind !== "base64" || input.data === undefined) return undefined;
+	return Buffer.byteLength(input.data.trim(), "base64");
+}
+/** All capability hooks use the HTTP observer guard, including failure reporting. */
+export function observeCapability(
+	sink: { markTelemetryFailed?(): void },
+	callback: () => unknown,
+): void {
+	observeTelemetry(callback, () => {
+		observeTelemetry(
+			() => sink.markTelemetryFailed?.(),
+			() => {},
+		);
+	});
+}
+
+// Only server-enrolled capability spans use the request root; standalone instrumentation
+// continues to use its caller's active span. No existing namespace changes parentage.
+type RootRunner = <T>(callback: () => Promise<T>) => Promise<T>;
+const roots = new WeakMap<object, RootRunner>();
+export function bindCapabilityRoot<T extends object>(context: T, run: RootRunner): T {
+	roots.set(context, run);
+	return context;
+}
+export function runCapabilitySpan<T>(context: object, callback: () => Promise<T>): Promise<T> {
+	return roots.get(context)?.(callback) ?? callback();
+}

package/src/runtime/diagnostic-env.ts

@@ -1,9 +1,9 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 
 import {
+	otlpHeaderCredentialValues,
 	resolvedStringVariants,
 	urlCredentialComponents,
-	otlpHeaderCredentialValues,
 } from "./diagnostic-env-values.js";
 import {
 	type CompiledDiagnosticSensitiveValues,
@@ -17,6 +17,7 @@ export interface DiagnosticEnvScope {
 	observe: EnvObserver;
 	finished: boolean;
 	staticValues?: CompiledDiagnosticSensitiveValues;
+	register?: (values: readonly string[]) => void;
 }
 const observers = new AsyncLocalStorage<DiagnosticEnvScope>();
 
@@ -48,6 +49,15 @@ export function readDiagnosticEnv(
 	return value;
 }
 
+/** Register a runtime-discovered sensitive value in the active request inventory. */
+export function registerDiagnosticValue(value: string): void {
+	if (value.length < 4) return;
+	const scope = observers.getStore();
+	if (scope && !scope.finished && scope.register) {
+		scope.register([value]);
+	}
+}
+
 export function withDiagnosticEnv<T>(observer: EnvObserver | DiagnosticEnvScope, fn: () => T): T {
 	const scope = typeof observer === "function" ? { observe: observer, finished: false } : observer;
 	const run = () => observers.run(scope, fn);