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

package/dist/runtime/engine-mode.js

@@ -0,0 +1,152 @@
+import { createInProcessProviderEngine, PROVIDER_ENGINE_MODE_ENV, } 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"];
+/** Mode used when neither `engineMode` nor `APIFUSE__ENGINE__MODE` names one. */
+export const DEFAULT_PROVIDER_ENGINE_MODE = "in-process";
+/** 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,
+];
+function isKnownMode(value) {
+    return KNOWN_PROVIDER_ENGINE_MODES.includes(value);
+}
+function normalize(value) {
+    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 = {}) {
+    const environment = input.environment ?? process.env;
+    const warnings = [];
+    // 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;
+    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 = 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, source, environment, warnings) {
+    // 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();
+/** True when the engine cannot attach, so readiness must report the process as unready. */
+export function isUnavailableProviderEngine(engine) {
+    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, reason) {
+    const engine = {
+        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) {
+    // 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 = process.env) {
+    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/dist/runtime/handle.js

@@ -11,7 +11,7 @@
 import { randomInt, randomUUID } from "node:crypto";
 import { isProviderError } from "../errors.js";
 import { HandleError, handleRecoverySentence, isDraftKind, } from "../handle.js";
-import { formatHandleIssuers } from "../handle-meta.js";
+import { formatHandleIssuers, handleHasDirectionalFieldNames } from "../handle-meta.js";
 import { BOUND_HANDLE_WORD_COUNT, findHandleWordWithinDistance, HIGH_PUBLIC_HANDLE_WORD_COUNT, ISSUABLE_HANDLE_WORDS, PUBLIC_HANDLE_WORD_COUNT, } from "./handle-wordlist.js";
 import { createMemoryProviderRuntimeState } from "./state.js";
 const RECORD_VERSION = 1;
@@ -153,6 +153,14 @@ export function formatNormalizationClasses(classes) {
 // Errors (spec §5)
 // ---------------------------------------------------------------------------
 function publicCollapsedMessage(kind) {
+    // "a new one" is unambiguous only while the kind has one name. When it is
+    // issued under `next_cursor` and accepted under `cursor`, the caller has to
+    // be told which field to read, so use the full recovery sentence — it names
+    // both keys and is identical for invalid / expired / not-found, which is
+    // what keeps the public collapse indistinguishable.
+    if (handleHasDirectionalFieldNames(kind)) {
+        return `\`${kind.fieldName}\` is not valid or has expired. ${handleRecoverySentence(kind)}`;
+    }
     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}`;

package/dist/runtime/http-telemetry-guard.d.ts

@@ -1,6 +1,16 @@
 import type { HttpRetrySummary } from "../types.js";
 import { type HttpTelemetryRequestSink, type HttpTelemetrySink } from "./http-telemetry.js";
+/** Shared synchronous observer boundary for transport and capability contributors. */
+export declare function observeTelemetry<T>(callback: () => T, fail: () => void): T | undefined;
+/** Isolate synchronous void capability hooks using the same Promise defence. */
+export declare function createTelemetryObserver(sink: {
+    markTelemetryFailed?(): void;
+} | undefined): (callback: () => unknown) => void;
 /** Keep all public observers, including property access, outside transport failures. */
 export declare function startHttpTelemetry(sink: HttpTelemetrySink | undefined, retryPreset: HttpRetrySummary["preset"]): HttpTelemetryRequestSink & {
     observe(callback: () => void): void;
 };
+/** Generic observer guard shared by capability hooks. Returned thenables are absorbed. */
+export declare function observeTelemetryCallback(sink: {
+    markTelemetryFailed?: () => unknown;
+} | undefined, callback: () => unknown): void;

package/dist/runtime/http-telemetry-guard.js

@@ -1,3 +1,4 @@
+import { isPromise } from "node:util/types";
 import { HttpTelemetryCollector, } from "./http-telemetry.js";
 const intrinsicPromiseThen = Promise.prototype.then;
 const ignoreObserverResult = () => { };
@@ -44,7 +45,7 @@ function isAsyncObserverReturn(value) {
     if (!value || (typeof value !== "object" && typeof value !== "function"))
         return false;
     try {
-        if (!("then" in value) || typeof value.then !== "function")
+        if (!isPromise(value) && (!("then" in value) || typeof value.then !== "function"))
             return false;
     }
     catch {
@@ -53,8 +54,23 @@ function isAsyncObserverReturn(value) {
     absorbObserverPromise(value);
     return true;
 }
-/** Keep all public observers, including property access, outside transport failures. */
-export function startHttpTelemetry(sink, retryPreset) {
+/** Shared synchronous observer boundary for transport and capability contributors. */
+export function observeTelemetry(callback, fail) {
+    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) {
     let failed = false;
     const fail = () => {
         if (failed)
@@ -64,24 +80,37 @@ export function startHttpTelemetry(sink, retryPreset) {
             isAsyncObserverReturn(sink?.markTelemetryFailed?.());
         }
         catch {
-            // The failure reporter is itself an observer. Never recurse.
+            // The failure marker is also an observer.
         }
     };
-    const observe = (callback) => {
+    return (callback) => {
         try {
             const result = callback();
-            if (isAsyncObserverReturn(result)) {
-                // The observer API is synchronous. Absorb invalid asynchronous returns too.
+            if (result !== undefined) {
+                isAsyncObserverReturn(result);
                 fail();
-                return undefined;
             }
-            return result;
         }
         catch {
             fail();
-            return undefined;
         }
     };
+}
+/** Keep all public observers, including property access, outside transport failures. */
+export function startHttpTelemetry(sink, retryPreset) {
+    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 = (callback) => observeTelemetry(callback, fail);
     const result = observe(() => (sink ?? new HttpTelemetryCollector()).startRequest({ retryPreset }));
     const request = observe(() => {
         if (!result ||
@@ -148,3 +177,26 @@ export function startHttpTelemetry(sink, retryPreset) {
         },
     };
 }
+/** Generic observer guard shared by capability hooks. Returned thenables are absorbed. */
+export function observeTelemetryCallback(sink, callback) {
+    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();
+    }
+}

package/dist/runtime/http.js

@@ -84,19 +84,92 @@ function hasHeader(headers, name) {
     const needle = name.toLowerCase();
     return Object.keys(headers).some((key) => key.toLowerCase() === needle);
 }
-function withClientHeaders(options, clientOptions, body) {
-    const headers = {
+function withClientHeaderDefaults(headers, clientOptions, body) {
+    const merged = {
         ...(clientOptions.userAgent ? { "User-Agent": clientOptions.userAgent } : {}),
-        ...options?.headers,
+        ...headers,
     };
-    if (body !== undefined && !hasHeader(headers, "Content-Type")) {
-        headers["Content-Type"] = "application/json";
+    if (body !== undefined && !hasHeader(merged, "Content-Type")) {
+        merged["Content-Type"] = "application/json";
     }
+    return merged;
+}
+function withClientHeaders(options, clientOptions, body) {
+    // The ambient client signal is merged into the per-request one here so every
+    // downstream read (retry loop, sleep, body consumption) sees a single signal.
+    // The header-factory branch needs it too, otherwise factory-header requests
+    // would lose ambient cancellation entirely.
+    const signal = mergeAbortSignals(clientOptions.signal, options?.signal);
+    // A header factory is resolved per issued attempt (resolveAttemptHeaders);
+    // the client defaults are applied to its output at that point.
+    if (typeof options?.headers === "function")
+        return { ...options, signal };
     return {
         ...options,
-        headers,
+        headers: withClientHeaderDefaults(options?.headers, clientOptions, body),
+        signal,
     };
 }
+function headerFactoryFailure(message, cause) {
+    // A dedicated code keeps a broken proof minter out of the retry predicate:
+    // toHttpTransportError would otherwise brand a plain throw as
+    // transport_network_error, which the default retry policy re-issues.
+    // retryable:false is explicit so the served error envelope does not
+    // advertise a deterministic signing failure as retryable, and
+    // category:provider_error keeps a provider-local minting bug out of the
+    // upstream-failure signal (status 0 would otherwise fall through the
+    // observability ladder to upstream_http / source upstream_failure).
+    return new TransportError(message, {
+        code: "http_header_factory_failed",
+        status: 0,
+        retryable: false,
+        category: "provider_error",
+        ...(cause instanceof Error ? { cause } : {}),
+    });
+}
+function isHeaderRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+// Settle `promise`, or reject with the signal's reason as soon as it aborts, so
+// a pending header factory cannot outlive the request deadline or an ambient
+// cancellation (native fetch has not started yet, so nothing else observes them).
+function settleBeforeAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+        // Always attach handlers: a late rejection after the abort must settle
+        // here (a no-op on the already-rejected promise), never go unhandled.
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}
+async function resolveAttemptHeaders(options, clientOptions, attempt, signal) {
+    const { headers } = options;
+    if (typeof headers !== "function")
+        return headers;
+    // The per-call timeout may have fired during proxy resolution: do not start
+    // the factory at all once the request is already aborted.
+    if (signal?.aborted)
+        throw signal.reason;
+    let minted;
+    try {
+        minted = await settleBeforeAbort(Promise.resolve().then(() => headers(attempt())), signal);
+    }
+    catch (error) {
+        // An abort is classified by toHttpTransportError (cancelled / timed out).
+        if (signal?.aborted)
+            throw error;
+        throw headerFactoryFailure("Request header factory failed", error);
+    }
+    if (!isHeaderRecord(minted)) {
+        throw headerFactoryFailure("Request header factory must return a header record");
+    }
+    return withClientHeaderDefaults(minted, clientOptions, options.body);
+}
 function parseHttpData(body, headers) {
     const contentType = headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
     if (contentType?.includes("application/json")) {
@@ -552,23 +625,29 @@ function serializeHttpRequestUrl(baseUrl, url, options) {
         throw redactSensitiveRequestError(error, url, options.sensitiveParams);
     }
 }
-async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0, dedupe, observeProxy) {
+async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0, dedupe, observeProxy, nextHeaderAttempt = () => 1) {
     const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
     const { requestUrl } = serializedUrl;
     const controller = options.timeout ? new AbortController() : undefined;
-    const signal = mergeAbortSignals(clientOptions.signal, controller?.signal);
-    const timeoutHandle = options.timeout
+    const signal = mergeAbortSignals(options.signal, controller?.signal);
+    let timeoutHandle = options.timeout
         ? setTimeout(() => controller?.abort(), options.timeout)
         : undefined;
+    const disarmTimeout = () => {
+        if (!timeoutHandle)
+            return;
+        clearTimeout(timeoutHandle);
+        timeoutHandle = undefined;
+    };
     let proxy;
     try {
-        throwIfAmbientAborted(clientOptions.signal);
+        throwIfAmbientAborted(options.signal);
         // Resolve inside the try (and after the timeout is armed) so allocator
         // failures are branded as TransportErrors and count against the request
         // deadline, exactly as an inline resolve would.
         proxy = await resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset);
         observeProxy?.(Boolean(proxy));
-        throwIfAmbientAborted(clientOptions.signal);
+        throwIfAmbientAborted(options.signal);
         // For a registry allocator chain, skip an endpoint a prior attempt already
         // tried rather than re-issuing the same request. Returning the sentinel
         // (instead of breaking) lets the loop keep advancing the flat offset until
@@ -579,8 +658,12 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
             }
             dedupe.attempted.add(proxy);
         }
+        // Resolve after the dedupe check so a skipped duplicate offset never burns
+        // a single-use proof, and with the serialized URL so URL-bound proofs
+        // match what is actually issued.
+        const requestHeaders = await resolveAttemptHeaders(options, clientOptions, () => ({ attempt: nextHeaderAttempt(), url: requestUrl, method }), signal);
         const requestInit = {
-            headers: options.headers,
+            headers: requestHeaders,
             method,
             ...(proxy ? { proxy } : {}),
             ...(signal ? { signal } : {}),
@@ -608,36 +691,45 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
                 status: response.status,
             });
         }
-        return toNativeHttpResponse(response);
+        // `timeout` bounds the header phase (types.ts RequestOptions.timeout), so it
+        // is disarmed before the body is read: awaiting the buffered body inside
+        // this try brands a mid-body failure as a transport error, but must not
+        // extend the deadline over the download. Cancellation still applies —
+        // `signal` stays attached to the native response. The discarded non-2xx
+        // bodies drained above stay under the deadline on purpose: nothing else
+        // bounds them, and their content is never returned to the caller.
+        disarmTimeout();
+        return await toNativeHttpResponse(response);
     }
     catch (error) {
         if (error instanceof SyntaxError) {
             throw redactSensitiveError(error, serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
         }
-        const transportError = redactSensitiveError(toHttpTransportError(error, clientOptions.signal, controller?.signal), serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
+        const transportError = redactSensitiveError(toHttpTransportError(error, options.signal, controller?.signal), serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
         transportError.proxyUsed = Boolean(proxy);
         throw transportError;
     }
     finally {
-        if (timeoutHandle)
-            clearTimeout(timeoutHandle);
+        disarmTimeout();
     }
 }
 async function fetchNativeHttpStream(baseUrl, url, method, options, clientOptions, warn, observeProxy) {
     const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
     const { requestUrl } = serializedUrl;
     const controller = options.timeout ? new AbortController() : undefined;
-    const signal = mergeAbortSignals(clientOptions.signal, controller?.signal);
+    const signal = mergeAbortSignals(options.signal, controller?.signal);
     const timeoutHandle = options.timeout
         ? setTimeout(() => controller?.abort(), options.timeout)
         : undefined;
     try {
-        throwIfAmbientAborted(clientOptions.signal);
+        throwIfAmbientAborted(options.signal);
         const proxy = await resolveNativeProxy(options, clientOptions, warn);
         observeProxy?.(Boolean(proxy));
-        throwIfAmbientAborted(clientOptions.signal);
+        throwIfAmbientAborted(options.signal);
+        // Streams never retry: a header factory is resolved once, as attempt 1.
+        const headers = await resolveAttemptHeaders(options, clientOptions, () => ({ attempt: 1, url: requestUrl, method }), signal);
         const requestInit = {
-            headers: options.headers,
+            headers,
             method,
             ...(proxy ? { proxy } : {}),
             ...(signal ? { signal } : {}),
@@ -653,15 +745,15 @@ async function fetchNativeHttpStream(baseUrl, url, method, options, clientOption
                 status: response.status,
             });
         }
-        // Per-call timeout remains header-scoped, while the ambient request signal
-        // stays attached to the response body for its full consumption lifetime.
-        return toNativeHttpStreamResponse(response, serializedUrl, clientOptions.signal);
+        // The stream timeout remains header-scoped; composed ambient and local
+        // cancellation stays attached to native fetch for the body's full lifetime.
+        return toNativeHttpStreamResponse(response, serializedUrl, options.signal);
     }
     catch (error) {
         if (error instanceof SyntaxError) {
             throw redactSensitiveError(error, serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
         }
-        throw redactSensitiveError(toHttpTransportError(error, clientOptions.signal, controller?.signal), serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
+        throw redactSensitiveError(toHttpTransportError(error, options.signal, controller?.signal), serializedUrl.sensitiveValues, serializedUrl.requestUrl, serializedUrl.redactedUrl);
     }
     finally {
         if (timeoutHandle)
@@ -772,6 +864,15 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 method: methodName,
             });
             const dedupeContext = dedupeAllocatorEndpoints ? { attempted: new Set() } : undefined;
+            // Numbers the attempts a header factory sees: only requests that reached
+            // header resolution count, so a failed proxy allocation (which increments
+            // the telemetry `issued` count below) or a dedupe-skipped offset does not
+            // make the first request that is actually built report `attempt: 2`.
+            let headerAttempts = 0;
+            const nextHeaderAttempt = () => {
+                headerAttempts += 1;
+                return headerAttempts;
+            };
             const executeOnce = async (proxyAttemptOffset = 0) => {
                 const started = performance.now();
                 let proxyUsed = false;
@@ -783,7 +884,7 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                     const outcome = await fetchNativeHttp(baseUrl, url, methodName, attemptOptions, clientOptions, warnOnce, statusRetryEnabled ? retryOptions?.statusCodes : undefined, proxyAttemptOffset, dedupeContext, (used, status) => {
                         proxyUsed = used;
                         observedStatus = status;
-                    });
+                    }, nextHeaderAttempt);
                     if (!isDedupeSkipOutcome(outcome))
                         record({
                             status: outcome.status,
@@ -800,7 +901,7 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 }
             };
             if (!retryEnabled || !retryOptions) {
-                throwIfAmbientAborted(clientOptions.signal);
+                throwIfAmbientAborted(headersOptions.signal);
                 const outcome = await executeOnce();
                 if (isDedupeSkipOutcome(outcome)) {
                     // Single-shot path never de-duplicates (dedupeContext is undefined),
@@ -822,7 +923,7 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
             // allocations skip offsets.
             let issued = 0;
             for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
-                throwIfAmbientAborted(clientOptions.signal);
+                throwIfAmbientAborted(headersOptions.signal);
                 // Whether this offset actually issued a request (vs. a skipped duplicate),
                 // so the catch counts a thrown *transport* failure once without
                 // double-counting a status outcome that already incremented before it
@@ -840,7 +941,7 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                     issuedThisAttempt = true;
                     if (isHttpStatusOutcome(outcome)) {
                         if (outcome.retryable && issued < retryOptions.attempts) {
-                            await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers), clientOptions.signal);
+                            await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers), headersOptions.signal);
                             continue;
                         }
                         throw toUpstreamHttpError(outcome.status);
@@ -857,7 +958,7 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                     return response;
                 }
                 catch (error) {
-                    throwIfAmbientAborted(clientOptions.signal);
+                    throwIfAmbientAborted(headersOptions.signal);
                     if (!issuedThisAttempt)
                         issued += 1;
                     lastError = error;
@@ -870,7 +971,7 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                             options: retryOptions,
                             proxyUsed,
                         })) {
-                        await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt), clientOptions.signal);
+                        await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt), headersOptions.signal);
                         continue;
                     }
                     throw error;
@@ -911,7 +1012,7 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
         // Streams never retry. Observe the header fetch without consuming its body.
         const telemetry = startHttpTelemetry(scopedHttpTelemetry(clientOptions.httpTelemetry), "off");
         const started = performance.now();
-        const alreadyAborted = clientOptions.signal?.aborted === true;
+        const alreadyAborted = headersOptions.signal?.aborted === true;
         let proxyUsed = false;
         const record = (event) => {
             if (alreadyAborted)
@@ -941,10 +1042,15 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
         delete: async (url, options) => request(url, "DELETE", options),
         stream: async (url, options = {}) => streamRequest(url, options.method ?? "GET", options),
         sse: async (url, options = {}) => {
-            const headers = {
-                Accept: "text/event-stream",
-                ...options.headers,
-            };
+            const callerHeaders = options.headers;
+            const headers = typeof callerHeaders === "function"
+                ? async (attempt) => {
+                    // Pass a malformed result through unchanged so the factory
+                    // validation rejects it instead of spreading it into `{}`.
+                    const minted = await callerHeaders(attempt);
+                    return isHeaderRecord(minted) ? { Accept: "text/event-stream", ...minted } : minted;
+                }
+                : { Accept: "text/event-stream", ...callerHeaders };
             const response = await streamRequest(url, options.method ?? "GET", {
                 ...options,
                 headers,