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

package/dist/runtime/cache-telemetry.js

@@ -0,0 +1,177 @@
+import { Buffer } from "node:buffer";
+import { closedEnum, } from "./request-telemetry.js";
+import { createTelemetryObserver } from "./http-telemetry-guard.js";
+const cacheTelemetryBindings = new WeakMap();
+/** Internal construction binding; keeps sink plumbing off ProviderCacheOptions. */
+export function bindCacheTelemetry(options, sink) {
+    if (sink)
+        cacheTelemetryBindings.set(options, sink);
+    return options;
+}
+/** Internal lookup used only by the cache factory. */
+export function cacheTelemetryFor(options) {
+    return cacheTelemetryBindings.get(options);
+}
+export function guardCacheTelemetry(sink) {
+    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) {
+    return Number.isFinite(value)
+        ? Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value)))
+        : Number.MAX_SAFE_INTEGER;
+}
+function add(a, b) {
+    return Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+}
+function boundedText(value, redact) {
+    let result;
+    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 {
+    key = "cache";
+    #redact;
+    #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;
+    #redisRoundTrips = 0;
+    #ages = [];
+    #maxAge = 0;
+    #samples = [];
+    #dropped = 0;
+    constructor(options = {}) {
+        this.#redact = options.redact;
+        this.#configured = "not_configured";
+    }
+    setRedisConfigured(configured) {
+        if (configured && this.#configured === "not_configured")
+            this.#configured = "configured";
+    }
+    markTelemetryFailed() {
+        this.#telemetryFailed = true;
+    }
+    recordLookup(meta) {
+        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() {
+        this.#writes = add(this.#writes, 1);
+    }
+    recordLoaderError() {
+        this.#loaderErrors = add(this.#loaderErrors, 1);
+    }
+    recordWriteError() {
+        this.#writeErrors = add(this.#writeErrors, 1);
+    }
+    recordRedisFallback() {
+        this.#redisFallbacks = add(this.#redisFallbacks, 1);
+        this.#configured = "degraded";
+    }
+    recordRedisRoundTrip() {
+        this.#redisRoundTrips = add(this.#redisRoundTrips, 1);
+    }
+    toLogPayload(_spans) {
+        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 } : {}),
+            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) {
+        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/dist/runtime/cache.js

@@ -2,6 +2,7 @@ import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { createHash, createHmac } from "node:crypto";
 import { providerCacheRedisUrlFromEnv } from "../config/loader.js";
 import { ProviderError } from "../errors.js";
+import { cacheTelemetryFor, guardCacheTelemetry } from "./cache-telemetry.js";
 import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis.js";
 export const APIFUSE__CACHE__KEY_PEPPER_ENV = "APIFUSE__CACHE__KEY_PEPPER";
 const DEFAULT_PREFIX = "apifuse:provider-cache:v1";
@@ -286,9 +287,13 @@ export function createProviderCache(options) {
     const memoryMaxEntries = Math.max(1, options.memoryMaxEntries ?? DEFAULT_MEMORY_MAX_ENTRIES);
     const now = options.now ?? Date.now;
     const events = [];
+    const telemetry = guardCacheTelemetry(cacheTelemetryFor(options));
+    telemetry.setRedisConfigured?.(!!redisUrl);
+    let redisUnavailable = false;
     const secretScopedKeys = new Set();
     function record(meta) {
         events.push(meta);
+        telemetry?.recordLookup(meta);
     }
     function sweepMemory(currentTime) {
         for (const [entryKey, entry] of backend.memory) {
@@ -322,13 +327,21 @@ export function createProviderCache(options) {
     async function readRedis(key, currentTime) {
         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)
+        if (typeof raw !== "string" && raw !== null) {
+            redisUnavailable = true;
+            telemetry.recordRedisFallback();
             return null;
+        }
+        telemetry?.recordRedisRoundTrip?.();
         const envelope = safeParseEnvelope(raw);
         if (!envelope)
             return null;
@@ -370,6 +383,7 @@ export function createProviderCache(options) {
         return staleMemoryResult;
     }
     async function write(key, value, cacheOptions) {
+        telemetry?.recordWrite();
         const currentTime = now();
         const freshTtlMs = jitteredTtlMs(cacheOptions.ttlMs, cacheOptions.jitterPct);
         const staleIfErrorMs = cacheOptions.staleIfErrorMs ?? 0;
@@ -383,9 +397,21 @@ export function createProviderCache(options) {
         rememberEnvelope(key, envelope, currentTime);
         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(key, loader, cacheOptions, staleCandidate) {
         try {
@@ -405,6 +431,13 @@ export function createProviderCache(options) {
             if (staleCandidate?.meta.stale) {
                 return staleCandidate;
             }
+            telemetry?.recordLookup({
+                key,
+                hit: false,
+                stale: false,
+                source: "loader",
+            });
+            telemetry?.recordLoaderError?.();
             throw error;
         }
     }
@@ -421,16 +454,30 @@ export function createProviderCache(options) {
             const result = await read(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) {
+            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(key, loader, cacheOptions) {
             const existing = await read(key);
@@ -440,10 +487,23 @@ export function createProviderCache(options) {
             }
             const existingInflight = backend.inflight.get(key);
             if (existingInflight) {
-                const inflightResult = await existingInflight;
-                const result = resultWithValue(inflightResult.value, inflightResult.meta);
-                record(result.meta);
-                return result;
+                try {
+                    const inflightResult = await existingInflight;
+                    const result = resultWithValue(inflightResult.value, inflightResult.meta);
+                    record(result.meta);
+                    return result;
+                }
+                catch (error) {
+                    const meta = {
+                        key,
+                        hit: false,
+                        stale: false,
+                        source: "loader",
+                    };
+                    telemetry.recordLookup(meta);
+                    telemetry?.recordLoaderError?.();
+                    throw error;
+                }
             }
             const promise = loadAndStore(key, loader, cacheOptions, existing).finally(() => {
                 backend.inflight.delete(key);

package/dist/runtime/capability-response.d.ts

@@ -0,0 +1,3 @@
+export declare const CAPABILITY_BODY_UNAVAILABLE = "<body unavailable>";
+/** Read optional diagnostic response text without letting a body stall the request failure. */
+export declare function readCapabilityErrorBody(response: Response, signal: AbortSignal): Promise<string>;

package/dist/runtime/capability-response.js

@@ -0,0 +1,56 @@
+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, signal) {
+    if (signal.aborted)
+        return CAPABILITY_BODY_UNAVAILABLE;
+    let timer;
+    let onAbort;
+    let reader;
+    let unavailableWon = false;
+    const cancelBody = (reason) => {
+        const cancellation = reader ? reader.cancel(reason) : response.body?.cancel(reason);
+        if (cancellation)
+            void cancellation.catch(() => { });
+    };
+    const unavailable = new Promise((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/dist/runtime/capability-telemetry.d.ts

@@ -0,0 +1,46 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** Internal capture facts, isolated across concurrent calls and never attached to caller results. */
+export type CapabilityFacts = {
+    status?: number;
+    finishReason?: string;
+    diagnostics?: string;
+};
+export declare const capabilityFacts: AsyncLocalStorage<CapabilityFacts>;
+export declare function tagCapability<T extends object>(context: T, facts: {
+    backend: string;
+    engine: string;
+    model?: string;
+}): T;
+export declare function capabilityMetadata(context: object): {
+    backend: string;
+    engine: string;
+    model?: string;
+} | undefined;
+export declare function captureCapability(facts: CapabilityFacts): void;
+export declare function registerCapabilityInput(input: {
+    kind: string;
+    data?: string;
+    url?: string;
+}): void;
+/**
+ * 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 declare function capabilityText(value: string, redact?: (text: string) => string, stripPayload?: boolean): string;
+export declare function capabilityErrorText(error: unknown): string;
+export declare const integer: (n: number | undefined) => number;
+export declare const add: (a: number, b: number) => number;
+export declare function inputBytes(input: {
+    kind: string;
+    data?: string;
+}): number | undefined;
+/** All capability hooks use the HTTP observer guard, including failure reporting. */
+export declare function observeCapability(sink: {
+    markTelemetryFailed?(): void;
+}, callback: () => unknown): void;
+type RootRunner = <T>(callback: () => Promise<T>) => Promise<T>;
+export declare function bindCapabilityRoot<T extends object>(context: T, run: RootRunner): T;
+export declare function runCapabilitySpan<T>(context: object, callback: () => Promise<T>): Promise<T>;
+export {};

package/dist/runtime/capability-telemetry.js

@@ -0,0 +1,68 @@
+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";
+export const capabilityFacts = new AsyncLocalStorage();
+const metadata = new WeakMap();
+export function tagCapability(context, facts) {
+    metadata.set(context, facts);
+    return context;
+}
+export function capabilityMetadata(context) {
+    return metadata.get(context);
+}
+export function captureCapability(facts) {
+    const current = capabilityFacts.getStore();
+    if (current)
+        Object.assign(current, facts);
+}
+export function registerCapabilityInput(input) {
+    // 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, redact, stripPayload = false) {
+    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) {
+    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) => Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(Number.isFinite(n ?? 0) ? (n ?? 0) : 0)));
+export const add = (a, b) => Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+export function inputBytes(input) {
+    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, callback) {
+    observeTelemetry(callback, () => {
+        observeTelemetry(() => sink.markTelemetryFailed?.(), () => { });
+    });
+}
+const roots = new WeakMap();
+export function bindCapabilityRoot(context, run) {
+    roots.set(context, run);
+    return context;
+}
+export function runCapabilitySpan(context, callback) {
+    return roots.get(context)?.(callback) ?? callback();
+}

package/dist/runtime/diagnostic-env.d.ts

@@ -4,8 +4,11 @@ export interface DiagnosticEnvScope {
     observe: EnvObserver;
     finished: boolean;
     staticValues?: CompiledDiagnosticSensitiveValues;
+    register?: (values: readonly string[]) => void;
 }
 /** Resolve and register atomically, before any consumer can use a live env credential. */
 export declare function readDiagnosticEnv(name: string, env?: Readonly<Record<string, string | undefined>>): string | undefined;
+/** Register a runtime-discovered sensitive value in the active request inventory. */
+export declare function registerDiagnosticValue(value: string): void;
 export declare function withDiagnosticEnv<T>(observer: EnvObserver | DiagnosticEnvScope, fn: () => T): T;
 export {};

package/dist/runtime/diagnostic-env.js

@@ -1,5 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { resolvedStringVariants, urlCredentialComponents, otlpHeaderCredentialValues, } from "./diagnostic-env-values.js";
+import { otlpHeaderCredentialValues, resolvedStringVariants, urlCredentialComponents, } from "./diagnostic-env-values.js";
 import { registerProcessDiagnosticValues, suppressProcessDiagnosticValues, withAppDiagnosticFallback, } from "./diagnostic-redactor.js";
 const observers = new AsyncLocalStorage();
 /** Resolve and register atomically, before any consumer can use a live env credential. */
@@ -28,6 +28,15 @@ export function readDiagnosticEnv(name, env = process.env) {
     }
     return value;
 }
+/** Register a runtime-discovered sensitive value in the active request inventory. */
+export function registerDiagnosticValue(value) {
+    if (value.length < 4)
+        return;
+    const scope = observers.getStore();
+    if (scope && !scope.finished && scope.register) {
+        scope.register([value]);
+    }
+}
 export function withDiagnosticEnv(observer, fn) {
     const scope = typeof observer === "function" ? { observe: observer, finished: false } : observer;
     const run = () => observers.run(scope, fn);

package/dist/runtime/engine-mode.d.ts

@@ -0,0 +1,74 @@
+import { type ProviderEngine, type ProviderEngineMode } from "../engine.js";
+/** Mode used when neither `engineMode` nor `APIFUSE__ENGINE__MODE` names one. */
+export declare const DEFAULT_PROVIDER_ENGINE_MODE = "in-process";
+/** Remote engine client endpoint; engine-owned, so never declarable as a provider secret. */
+export declare const REMOTE_ENGINE_CLIENT_URL_ENV = "APIFUSE__ENGINE__URL";
+/** Remote engine client credential; registered with the diagnostic redactor by sensitive-values. */
+export declare const REMOTE_ENGINE_CLIENT_API_KEY_ENV = "APIFUSE__ENGINE__API_KEY";
+/** 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>>;
+}
+/**
+ * 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 declare function resolveProviderEngineMode(input?: ProviderEngineModeResolutionInput): ProviderEngineModeResolution;
+/** True when the engine cannot attach, so readiness must report the process as unready. */
+export declare function isUnavailableProviderEngine(engine: ProviderEngine): boolean;
+/**
+ * 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 declare function createUnavailableProviderEngine(kind: ProviderEngineMode, reason: {
+    message: string;
+    code: string;
+    fix: string;
+}): ProviderEngine;
+/**
+ * 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 declare function createEngineForMode(mode: ProviderEngineMode | "custom"): ProviderEngine;
+/**
+ * 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 declare function assertProcessEngineModeSupported(environment?: Readonly<Record<string, string | undefined>>): ProviderEngineModeResolution;