@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/runtime/request-options.js

@@ -1,3 +1,26 @@
+import { isProviderError } from "../errors.js";
+export const REDACTED_QUERY_VALUE = "[REDACTED]";
+/** Internal heuristic shared by diagnostic and fixture structural redaction. */
+export function isSensitiveKey(key) {
+    return /authorization|token|api[-_]?key|(^|[-_])(code|key|secret|signature|session|state)($|[-_])/i.test(key);
+}
+const HTTP_REQUEST_METHOD_CONFIG = {
+    request: { optionsIndex: 1 },
+    get: { optionsIndex: 1 },
+    post: { optionsIndex: 2 },
+    put: { optionsIndex: 2 },
+    delete: { optionsIndex: 1 },
+    stream: { optionsIndex: 1 },
+    sse: { optionsIndex: 1 },
+};
+export const HTTP_REQUEST_METHOD_NAMES = Object.keys(HTTP_REQUEST_METHOD_CONFIG);
+const HTTP_REQUEST_METHOD_SET = new Set(HTTP_REQUEST_METHOD_NAMES);
+export function isHttpRequestMethod(method) {
+    return typeof method === "string" && HTTP_REQUEST_METHOD_SET.has(method);
+}
+export function normalizeSensitiveParams(sensitiveParams) {
+    return sensitiveParams && Object.keys(sensitiveParams).length > 0 ? sensitiveParams : undefined;
+}
 function isParamArray(value) {
     return Array.isArray(value);
 }
@@ -22,6 +45,571 @@ export function appendQueryParams(url, params) {
     }
     return parsed.toString();
 }
+function decodeQueryComponent(value) {
+    try {
+        return decodeURIComponent(value.replaceAll("+", " "));
+    }
+    catch {
+        return value;
+    }
+}
+/** Redacts matching query keys without reserializing any other URL bytes. */
+export function redactUrlQueryParams(url, sensitiveParamNames) {
+    if (sensitiveParamNames.length === 0)
+        return { redactedUrl: url, sensitiveValues: [] };
+    const names = new Set(sensitiveParamNames);
+    const queryStart = url.indexOf("?");
+    if (queryStart === -1)
+        return { redactedUrl: url, sensitiveValues: [] };
+    const fragmentStart = url.indexOf("#", queryStart);
+    const queryEnd = fragmentStart === -1 ? url.length : fragmentStart;
+    const query = url.slice(queryStart + 1, queryEnd);
+    const sensitiveValues = [];
+    const redactedQuery = query
+        .split("&")
+        .map((part) => {
+        const assignment = part.indexOf("=");
+        const encodedKey = assignment === -1 ? part : part.slice(0, assignment);
+        if (!names.has(decodeQueryComponent(encodedKey)))
+            return part;
+        const encodedValue = assignment === -1 ? "" : part.slice(assignment + 1);
+        sensitiveValues.push(decodeQueryComponent(encodedValue));
+        return `${encodedKey}=${REDACTED_QUERY_VALUE}`;
+    })
+        .join("&");
+    return {
+        redactedUrl: `${url.slice(0, queryStart + 1)}${redactedQuery}${url.slice(queryEnd)}`,
+        sensitiveValues,
+    };
+}
+/**
+ * Serializes public and secret query parameters together while constructing a
+ * separate, structurally redacted URL for diagnostics and observability.
+ */
+export function serializeRequestUrl(url, params, sensitiveParams) {
+    const urlWithParams = appendQueryParams(url, params);
+    const normalizedSensitiveParams = normalizeSensitiveParams(sensitiveParams);
+    if (!normalizedSensitiveParams) {
+        return { requestUrl: urlWithParams, redactedUrl: urlWithParams, sensitiveValues: [] };
+    }
+    const sensitiveParamNames = Object.keys(normalizedSensitiveParams);
+    const existing = redactUrlQueryParams(urlWithParams, sensitiveParamNames);
+    const sensitiveValues = new Set(existing.sensitiveValues);
+    let requestUrl = urlWithParams;
+    for (const [key, value] of Object.entries(normalizedSensitiveParams)) {
+        const serializedValue = String(value);
+        requestUrl = appendQueryParams(requestUrl, { [key]: serializedValue });
+        sensitiveValues.add(serializedValue);
+    }
+    const redacted = redactUrlQueryParams(requestUrl, sensitiveParamNames);
+    return {
+        requestUrl,
+        redactedUrl: redacted.redactedUrl,
+        sensitiveValues: [...sensitiveValues],
+    };
+}
+const MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH = 8;
+export function normalizePercentEscapes(value) {
+    return value.replace(/%[\da-f]{2}/gi, (percentEscape) => percentEscape.toUpperCase());
+}
+function sensitiveValueVariants(value) {
+    if (!value || value === REDACTED_QUERY_VALUE)
+        return [];
+    // Owner-visible policy: short credentials are literal, case-sensitive tokens only.
+    // Encoded short needles collide with benign cursors and ordinary diagnostic text.
+    if (value.length < 8)
+        return [value];
+    // These ASCII characters are identical under NFC, JSON, URI-component and
+    // form encoding. Avoid constructing those identical variants for common tokens.
+    if (/^[A-Za-z0-9._*-]+$/.test(value)) {
+        const base64 = Buffer.from(value, "utf8").toString("base64");
+        const base64Url = base64.replaceAll("+", "-").replaceAll("/", "_");
+        return [
+            ...new Set([
+                value,
+                base64,
+                base64.replace(/=+$/, ""),
+                base64Url,
+                base64Url.replace(/=+$/, ""),
+            ]),
+        ];
+    }
+    const normalized = value.normalize("NFC");
+    const formEncoded = new URLSearchParams({ value }).toString().slice("value=".length);
+    let componentEncoded;
+    try {
+        componentEncoded = encodeURIComponent(value);
+    }
+    catch {
+        // encodeURIComponent rejects lone UTF-16 surrogates. The raw value is
+        // still safe to scrub, and URLSearchParams supplies its well-formed form.
+        componentEncoded = value;
+    }
+    const base64 = Buffer.from(value, "utf8").toString("base64");
+    const base64Url = base64.replaceAll("+", "-").replaceAll("/", "_");
+    const jsonEscaped = JSON.stringify(value).slice(1, -1);
+    return [
+        ...new Set([
+            value,
+            normalized,
+            componentEncoded,
+            formEncoded,
+            jsonEscaped,
+            base64,
+            base64.replace(/=+$/, ""),
+            base64Url,
+            base64Url.replace(/=+$/, ""),
+        ].map(normalizePercentEscapes)),
+    ];
+}
+export function allSensitiveValueVariants(sensitiveValues) {
+    const variants = new Map();
+    for (const sensitiveValue of sensitiveValues) {
+        const requiresTokenBoundary = sensitiveValue.length < MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH;
+        // Long values are unlikely to be ordinary prose, so case folding is worth
+        // the extra over-redaction protection. Values of 4-7 characters remain
+        // case-sensitive because they commonly occur as words and identifiers.
+        const caseInsensitive = sensitiveValue.length >= 8;
+        for (const value of sensitiveValueVariants(sensitiveValue)) {
+            const existing = variants.get(value);
+            variants.set(value, {
+                value,
+                requiresTokenBoundary: existing
+                    ? existing.requiresTokenBoundary && requiresTokenBoundary
+                    : requiresTokenBoundary,
+                caseInsensitive: existing ? existing.caseInsensitive || caseInsensitive : caseInsensitive,
+            });
+        }
+    }
+    return [...variants.values()].sort((left, right) => right.value.length - left.value.length || left.value.localeCompare(right.value));
+}
+function isTokenCharacter(value) {
+    return value !== undefined && /[\p{L}\p{N}]/u.test(value);
+}
+function replaceSensitiveVariant(text, variant) {
+    const normalized = normalizePercentEscapes(text);
+    const comparable = variant.caseInsensitive ? normalized.toLowerCase() : text;
+    const needle = variant.caseInsensitive ? variant.value.toLowerCase() : variant.value;
+    let cursor = 0;
+    let output = "";
+    for (let index = comparable.indexOf(needle); index !== -1; index = comparable.indexOf(needle, index + 1)) {
+        const end = index + needle.length;
+        if (variant.requiresTokenBoundary &&
+            (isTokenCharacter(comparable[index - 1]) || isTokenCharacter(comparable[end])))
+            continue;
+        // Unicode folding can change offsets; suppress the field instead of slicing a secret.
+        if (comparable.length !== text.length)
+            return REDACTED_QUERY_VALUE;
+        output += text.slice(cursor, index) + REDACTED_QUERY_VALUE;
+        cursor = end;
+        index = end - 1;
+    }
+    return cursor ? output + text.slice(cursor) : text;
+}
+/** Scrubs raw and URL-encoded secret values from diagnostic text. */
+export function redactSensitiveText(text, sensitiveValues, requestUrl, redactedUrl) {
+    let redacted = requestUrl && redactedUrl ? text.replaceAll(requestUrl, redactedUrl) : text;
+    for (const variant of allSensitiveValueVariants(sensitiveValues)) {
+        // Low-entropy values are still redacted, but only as complete tokens. This
+        // covers query values and diagnostic phrases such as "credential api rejected"
+        // without corrupting timestamps or words such as "rapid".
+        redacted = replaceSensitiveVariant(redacted, variant);
+    }
+    return redacted;
+}
+function isSdkErrorBrand(key) {
+    return (typeof key === "symbol" &&
+        Symbol.keyFor(key)?.startsWith("@apifuse/provider-sdk/error-") === true);
+}
+function redactDiagnosticString(value, context) {
+    return redactSensitiveText(value, context.sensitiveValues, context.requestUrl, context.redactedUrl);
+}
+function redactClassificationString(value, context) {
+    let redacted = context.requestUrl && context.redactedUrl
+        ? value.replaceAll(context.requestUrl, context.redactedUrl)
+        : value;
+    for (const variant of allSensitiveValueVariants(context.sensitiveValues)) {
+        redacted = replaceSensitiveVariant(redacted, {
+            ...variant,
+            requiresTokenBoundary: false,
+        });
+    }
+    return redacted;
+}
+function cloneForRedaction(source) {
+    let clone;
+    try {
+        clone = Array.isArray(source)
+            ? []
+            : source instanceof DOMException
+                ? new DOMException(source.message, source.name)
+                : Object.create(Object.getPrototypeOf(source));
+        if (Array.isArray(source) && Object.getPrototypeOf(source) !== Array.prototype) {
+            Object.setPrototypeOf(clone, Object.getPrototypeOf(source));
+        }
+    }
+    catch {
+        clone = source instanceof Error ? new Error() : {};
+    }
+    for (const key of Reflect.ownKeys(source)) {
+        const descriptor = Object.getOwnPropertyDescriptor(source, key);
+        if (!descriptor)
+            continue;
+        if (Array.isArray(source) && key === "length")
+            continue;
+        try {
+            const preserveSdkBrand = isSdkErrorBrand(key);
+            Object.defineProperty(clone, key, preserveSdkBrand
+                ? descriptor
+                : {
+                    ...descriptor,
+                    configurable: true,
+                    ...(Object.hasOwn(descriptor, "value") ? { writable: true } : {}),
+                });
+        }
+        catch {
+            // A hostile or exotic diagnostic property must not make redaction fail.
+        }
+    }
+    if (source instanceof Error) {
+        // DOMException exposes name/message through internal-slot getters. An
+        // Object.create clone does not carry those slots, so materialize the
+        // classification fields as safe own properties on the replacement.
+        for (const key of ["name", "message", "stack"]) {
+            if (Object.hasOwn(clone, key))
+                continue;
+            const property = readDiagnosticProperty(source, key);
+            if (!property.ok)
+                continue;
+            const propertyValue = key === "stack" && typeof property.value !== "string" ? new Error().stack : property.value;
+            try {
+                Object.defineProperty(clone, key, {
+                    value: propertyValue,
+                    configurable: true,
+                    enumerable: false,
+                    writable: true,
+                });
+            }
+            catch {
+                // The generic Error fallback remains classifiable even if an exotic
+                // prototype rejects an own diagnostic property.
+            }
+        }
+    }
+    return clone;
+}
+function setDiagnosticProperty(target, key, value) {
+    try {
+        return Reflect.set(target, key, value, target);
+    }
+    catch {
+        return false;
+    }
+}
+function diagnosticPropertyKeys(value) {
+    const keys = new Set(Reflect.ownKeys(value));
+    if (value instanceof Error) {
+        // Built-in error text and AggregateError.errors are commonly
+        // non-enumerable, while SDK options carry serializable details.
+        for (const key of ["name", "message", "stack", "cause", "errors", "options"]) {
+            if (key in value)
+                keys.add(key);
+        }
+    }
+    if (!(value instanceof Error) && "toJSON" in value)
+        keys.add("toJSON");
+    return [...keys];
+}
+function requiresCloneBeforeRedaction(value, keys) {
+    for (const key of keys) {
+        if (isSdkErrorBrand(key))
+            continue;
+        let owner = value;
+        while (owner) {
+            const descriptor = Object.getOwnPropertyDescriptor(owner, key);
+            if (descriptor) {
+                if (Object.hasOwn(descriptor, "value")) {
+                    if (owner === value && descriptor.writable === false)
+                        return true;
+                }
+                else if (descriptor.set === undefined) {
+                    return true;
+                }
+                break;
+            }
+            owner = Object.getPrototypeOf(owner);
+        }
+    }
+    return false;
+}
+function readDiagnosticProperty(value, key) {
+    try {
+        return { ok: true, value: Reflect.get(value, key, value) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+// These fields control error identity/classification downstream. Their values
+// are exempt from whole-value replacement, but strings are still scrubbed when
+// they contain an actual declared credential or request URL.
+const DIAGNOSTIC_CLASSIFICATION_FIELDS = new Set([
+    "name",
+    "code",
+    "status",
+    "upstreamStatus",
+    "category",
+    "retryable",
+]);
+// Underscore-delimited error codes are semantic identities, not diagnostic
+// payload. Preserve the shared SDK/provider code convention without maintaining
+// a second, inevitably partial list of codes declared by individual transports.
+function isSemanticErrorCode(value) {
+    return /^(?:[A-Za-z][A-Za-z0-9]*_)+[A-Za-z0-9]+$/.test(value);
+}
+function isClassificationField(context, propertyName, parent) {
+    return Boolean(propertyName &&
+        parent &&
+        context.classificationObjects.has(parent) &&
+        DIAGNOSTIC_CLASSIFICATION_FIELDS.has(propertyName));
+}
+function redactedDiagnosticKey(key, context) {
+    return redactClassificationString(key, context);
+}
+function hasRedactedOwnKey(value, context) {
+    return Object.getOwnPropertyNames(value).some((key) => redactedDiagnosticKey(key, context) !== key);
+}
+function collisionSafeDiagnosticKey(target, preferredKey) {
+    if (!Object.hasOwn(target, preferredKey))
+        return preferredKey;
+    let suffix = 2;
+    while (Object.hasOwn(target, `${preferredKey}#${suffix}`))
+        suffix += 1;
+    return `${preferredKey}#${suffix}`;
+}
+function redactDiagnosticValue(value, context, propertyName, parent) {
+    const classificationField = isClassificationField(context, propertyName, parent);
+    if (classificationField && typeof value !== "string")
+        return value;
+    if (typeof value === "string") {
+        if (!classificationField)
+            return redactDiagnosticString(value, context);
+        const redacted = redactClassificationString(value, context);
+        if (propertyName === "code" && redacted === value && isSemanticErrorCode(value))
+            return value;
+        return redacted;
+    }
+    if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
+        return context.sensitiveValues.includes(String(value)) ? REDACTED_QUERY_VALUE : value;
+    }
+    if ((typeof value !== "object" && typeof value !== "function") || value === null)
+        return value;
+    if (value instanceof URL) {
+        const redactedUrl = redactDiagnosticString(value.toString(), context);
+        if (redactedUrl === value.toString())
+            return value;
+        try {
+            return new URL(redactedUrl);
+        }
+        catch {
+            return redactedUrl;
+        }
+    }
+    if (value instanceof Headers) {
+        const redactedHeaders = new Headers();
+        for (const [key, headerValue] of value.entries()) {
+            redactedHeaders.append(key, redactDiagnosticString(headerValue, context));
+        }
+        return redactedHeaders;
+    }
+    if (value instanceof Request) {
+        const redactedUrl = redactDiagnosticString(value.url, context);
+        const redactedHeaders = redactDiagnosticValue(value.headers, context);
+        if (redactedUrl === value.url &&
+            [...value.headers].every(([key, headerValue]) => {
+                return redactedHeaders.get(key) === headerValue;
+            })) {
+            return value;
+        }
+        try {
+            const redactedRequest = new Request(redactedUrl, value);
+            for (const key of [...redactedRequest.headers.keys()])
+                redactedRequest.headers.delete(key);
+            for (const [key, headerValue] of redactedHeaders) {
+                redactedRequest.headers.append(key, headerValue);
+            }
+            return redactedRequest;
+        }
+        catch {
+            const redactedRequest = Object.create(Object.getPrototypeOf(value));
+            Object.defineProperties(redactedRequest, {
+                headers: { value: redactedHeaders, enumerable: true },
+                url: { value: redactedUrl, enumerable: true },
+            });
+            return redactedRequest;
+        }
+    }
+    if (value instanceof Response) {
+        const redactedUrl = redactDiagnosticString(value.url, context);
+        const redactedHeaders = redactDiagnosticValue(value.headers, context);
+        if (redactedUrl === value.url &&
+            [...value.headers].every(([key, headerValue]) => {
+                return redactedHeaders.get(key) === headerValue;
+            })) {
+            return value;
+        }
+        const redactedResponse = Object.create(Object.getPrototypeOf(value));
+        Object.defineProperties(redactedResponse, {
+            headers: { value: redactedHeaders, enumerable: true },
+            ok: { value: value.ok, enumerable: true },
+            redirected: { value: value.redirected, enumerable: true },
+            status: { value: value.status, enumerable: true },
+            statusText: {
+                value: redactDiagnosticString(value.statusText, context),
+                enumerable: true,
+            },
+            type: { value: value.type, enumerable: true },
+            url: { value: redactedUrl, enumerable: true },
+        });
+        return redactedResponse;
+    }
+    const previouslySeen = context.seen.get(value);
+    if (previouslySeen !== undefined)
+        return previouslySeen;
+    if (value instanceof Map) {
+        const redactedMap = new Map();
+        context.seen.set(value, redactedMap);
+        for (const [key, entryValue] of value) {
+            redactedMap.set(redactDiagnosticValue(key, context), redactDiagnosticValue(entryValue, context));
+        }
+        return redactedMap;
+    }
+    // Clone non-extensible graphs before descending so cycles encountered before
+    // a secret-bearing readonly field already point at the eventual replacement.
+    // Without this, a frozen `error.cause = error` graph could retain the original
+    // secret through the cloned node's earlier self-reference.
+    const keys = diagnosticPropertyKeys(value);
+    let target = Object.isExtensible(value) &&
+        !requiresCloneBeforeRedaction(value, keys) &&
+        !hasRedactedOwnKey(value, context)
+        ? value
+        : cloneForRedaction(value);
+    context.seen.set(value, target);
+    for (const key of keys) {
+        const current = readDiagnosticProperty(value, key);
+        if (!current.ok)
+            continue;
+        const propertyName = typeof key === "string" ? key : undefined;
+        const redacted = key === "toJSON" && typeof current.value === "function"
+            ? (...args) => redactDiagnosticValue(Reflect.apply(current.value, value, args), context)
+            : redactDiagnosticValue(current.value, context, propertyName, value);
+        const ownKey = Object.hasOwn(value, key);
+        const preferredKey = ownKey && typeof key === "string" ? redactedDiagnosticKey(key, context) : key;
+        let targetKey = key;
+        if (preferredKey !== key) {
+            try {
+                Reflect.deleteProperty(target, key);
+            }
+            catch {
+                // A clone is selected before traversal whenever an own key changes,
+                // so this is only a defensive fallback for exotic proxies.
+            }
+            targetKey = collisionSafeDiagnosticKey(target, preferredKey);
+        }
+        if (targetKey === key && Object.is(redacted, current.value))
+            continue;
+        if (!setDiagnosticProperty(target, targetKey, redacted)) {
+            if (target === value) {
+                target = cloneForRedaction(value);
+                context.seen.set(value, target);
+            }
+            if (!setDiagnosticProperty(target, targetKey, redacted)) {
+                // cloneForRedaction deliberately makes string-keyed own properties
+                // configurable. This is a last-resort path for inherited readonly
+                // accessors such as DOMException.message.
+                try {
+                    Object.defineProperty(target, targetKey, {
+                        value: redacted,
+                        configurable: true,
+                        enumerable: targetKey !== "message" && targetKey !== "stack" && targetKey !== "cause",
+                        writable: true,
+                    });
+                }
+                catch {
+                    // Redaction is best-effort for inaccessible exotic properties, but
+                    // it must never mask the original transport failure.
+                }
+            }
+        }
+    }
+    return target;
+}
+/**
+ * Redacts error text and recursively serializable diagnostic metadata.
+ * Mutable errors retain identity; readonly/frozen errors may be replaced, so
+ * callers must use the returned value.
+ */
+export function redactSensitiveError(error, sensitiveValues, requestUrl, redactedUrl) {
+    if (sensitiveValues.length === 0 && (!requestUrl || !redactedUrl || requestUrl === redactedUrl)) {
+        return error;
+    }
+    const classificationObjects = new Set();
+    if ((typeof error === "object" || typeof error === "function") && error !== null) {
+        classificationObjects.add(error);
+        if (isProviderError(error)) {
+            const options = readDiagnosticProperty(error, "options");
+            if (options.ok && typeof options.value === "object" && options.value !== null) {
+                classificationObjects.add(options.value);
+            }
+        }
+    }
+    return redactDiagnosticValue(error, {
+        classificationObjects,
+        sensitiveValues,
+        requestUrl,
+        redactedUrl,
+        seen: new Map(),
+    });
+}
+/** Redacts failures that occur before a request URL can be fully serialized. */
+export function redactSensitiveRequestError(error, url, sensitiveParams) {
+    const normalizedSensitiveParams = normalizeSensitiveParams(sensitiveParams);
+    const structural = redactUrlQueryParams(url, Object.keys(normalizedSensitiveParams ?? {}));
+    return redactSensitiveError(error, [
+        ...new Set([
+            ...Object.values(normalizedSensitiveParams ?? {}).map(String),
+            ...structural.sensitiveValues,
+        ]),
+    ], url, structural.redactedUrl);
+}
+function isRequestOptions(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Validates an untyped proxy invocation before narrowing it to the HttpClient contract. */
+export function parseHttpRequestInvocation(method, args) {
+    if (!isHttpRequestMethod(method) || typeof args[0] !== "string")
+        return undefined;
+    const optionsIndex = HTTP_REQUEST_METHOD_CONFIG[method].optionsIndex;
+    const options = args[optionsIndex];
+    if (options !== undefined && !isRequestOptions(options))
+        return undefined;
+    if (method === "post" || method === "put") {
+        if (args.length < 2 || args.length > 3)
+            return undefined;
+        return { method, args: args };
+    }
+    if (args.length > 2)
+        return undefined;
+    return { method, args: args };
+}
+/** Internal typed registry for the request-options position of HttpClient calls. */
+export function requestOptionsFromHttpInvocation(invocation) {
+    const candidate = invocation.args[HTTP_REQUEST_METHOD_CONFIG[invocation.method].optionsIndex];
+    return isRequestOptions(candidate) ? candidate : undefined;
+}
+export function replaceRequestOptionsInHttpInvocation(invocation, options) {
+    invocation.args[HTTP_REQUEST_METHOD_CONFIG[invocation.method].optionsIndex] = options;
+}
 export function normalizeHttpRequestBody(body) {
     if (body === undefined) {
         return undefined;

package/dist/runtime/request-telemetry.d.ts

@@ -0,0 +1,70 @@
+import type { ProxyTelemetrySink } from "../config/loader.js";
+import type { ProxyTelemetryLogPayload } from "./proxy-telemetry.js";
+import type { ResolverTelemetryLogPayload } from "./resolver-telemetry.js";
+import type { Span, TraceContext } from "./trace.js";
+export declare 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 declare function closedEnum<T extends string>(value: T): 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 declare function tenantOpaqueKeys(value: string[]): 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;
+    resolver?: ResolverTelemetryLogPayload;
+} & Partial<Record<Exclude<TelemetryKey, "proxy" | "resolver">, object>>;
+/** @internal */
+export declare const HEADER_PRIORITY: readonly ["proxy", "resolver", "native", "http", "stealth", "browser", "ocr", "stt", "cache", "state"];
+/**
+ * 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 declare function isGatewayIngestible(value: unknown): boolean;
+/** One finalisation owner for every request-scoped telemetry contributor. */
+export declare class RequestTelemetry {
+    #private;
+    readonly trace: TraceContext;
+    readonly contributors: Readonly<Partial<Record<TelemetryKey, {
+        readonly key: TelemetryKey;
+        toLogPayload(spans: SpanIndex): object | undefined;
+    }>>>;
+    constructor(trace: TraceContext);
+    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;
+    get proxy(): ProxyTelemetrySink | undefined;
+    toLogPayload(): RequestTelemetryLogPayload | undefined;
+    toHeaderValue(): string | undefined;
+}
+export {};