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

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

@@ -3,13 +3,15 @@
  *
  * Storage layout: one state namespace per kind, `handle.<kind>`, scoped by the
  * kind's access (bound → connection scope via `state.forConnection`, public →
- * provider scope). The state key is the canonical handle string. Records hold
+ * provider scope; both cursors and drafts may be either). The state key is the
+ * canonical handle string. Records hold
  * the validated data plus status/timestamps; the handle string itself carries
  * no payload and no signature.
  */
 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 { 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;
@@ -151,14 +153,13 @@ export function formatNormalizationClasses(classes) {
 // Errors (spec §5)
 // ---------------------------------------------------------------------------
 function publicCollapsedMessage(kind) {
-    const again = kind.issuedBy
-        ? `Call \`${kind.issuedBy}\` again to get a new one.`
-        : "Request a new one.";
+    const issuers = formatHandleIssuers(kind.issuedBy);
+    const again = issuers ? `Call ${issuers} again to get a new one.` : "Request a new one.";
     return `\`${kind.fieldName}\` is not valid or has expired. ${again}`;
 }
 function normalizationError(kind, failure) {
     if (failure.reason === "kind_mismatch") {
-        return new HandleError("HANDLE_KIND_MISMATCH", `\`${kind.fieldName}\` must be a \`${kind.name}_...\` handle as returned by ${kind.issuedBy ? `\`${kind.issuedBy}\`` : "the issuing operation"}. ${handleRecoverySentence(kind)}`, { kind: kind.name, details: { field: kind.fieldName } });
+        return new HandleError("HANDLE_KIND_MISMATCH", `\`${kind.fieldName}\` must be a \`${kind.name}_...\` handle as returned by ${formatHandleIssuers(kind.issuedBy) ?? "the issuing operation"}. ${handleRecoverySentence(kind)}`, { kind: kind.name, details: { field: kind.fieldName } });
     }
     if (kind.access === "public") {
         return new HandleError("HANDLE_INVALID", publicCollapsedMessage(kind), {
@@ -217,7 +218,7 @@ function committedError(kind) {
     return new HandleError("HANDLE_COMMITTED", `\`${kind.fieldName}\` has already been committed and can no longer be changed. ${handleRecoverySentence(kind)}`, { kind: kind.name, details: { field: kind.fieldName } });
 }
 function connectionRequiredError(kind, operation) {
-    return new HandleError("HANDLE_CONNECTION_REQUIRED", `Handle kind "${kind.name}" is bound to a connection, but request.connectionId is missing for ${operation}. Bound handles require a connection-scoped request; use access: "public" for connection-less cursors.`, { kind: kind.name });
+    return new HandleError("HANDLE_CONNECTION_REQUIRED", `Handle kind "${kind.name}" is bound to a connection, but request.connectionId is missing for ${operation}. Bound handles require a connection-scoped request; use access: "public" for connection-less kinds.`, { kind: kind.name });
 }
 function storageUnavailableError(kind, reason, cause) {
     return new HandleError("HANDLE_STORAGE_UNAVAILABLE", `Handle storage for kind "${kind.name}" is not available: ${reason}.`, { kind: kind.name, cause, details: { reason } });
@@ -526,7 +527,7 @@ export function createHandleContext(options) {
             record: value,
         };
     }
-    async function create(kind, data) {
+    async function createRecord(kind, data) {
         return await instrumented(kind, "create", async (report) => {
             const validated = validateData(kind, "create", data);
             const namespace = resolveNamespace(kind, "create");
@@ -551,12 +552,16 @@ export function createHandleContext(options) {
             for (let attempt = 0; attempt < CREATE_ATTEMPTS; attempt += 1) {
                 const canonical = `${kind.name}_${generateWords(kind.wordCount).join("-")}`;
                 const result = await storage(kind, () => namespace.compareAndSet(canonical, 0, record, { ttl: msDuration(writeTtlMs) }));
-                if (result.ok)
-                    return { value: canonical, outcome: "success" };
+                if (result.ok) {
+                    return { value: toHandleRecord(kind, canonical, record), outcome: "success" };
+                }
             }
             throw storageUnavailableError(kind, `could not allocate a unique handle after ${CREATE_ATTEMPTS} attempts`);
         });
     }
+    async function create(kind, data) {
+        return (await createRecord(kind, data)).handle;
+    }
     async function read(kind, handle) {
         return await instrumented(kind, "read", async (report) => {
             const loaded = await load(kind, "read", handle, report);
@@ -876,7 +881,7 @@ export function createHandleContext(options) {
             throw busyError(kind);
         });
     }
-    return { create, read, update, commit, discard };
+    return { create, createRecord, read, update, commit, discard };
 }
 /**
  * Handle context for unit tests: memory state, a fixed connection, and an

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

@@ -0,0 +1,10 @@
+import type { HttpClient } from "../types.js";
+import { type HttpTelemetrySink } from "./http-telemetry.js";
+/** Return whether a host binding has at least one callable declared HTTP method. */
+export declare function isSupportedHttpBinding(value: unknown): value is HttpClient;
+/** Emit the unsupported-shape warning once for the process. */
+export declare function warnUnsupportedHttpBinding(): void;
+/** Route SDK transports inside a host binding through the same attempt collector. */
+export declare function scopedHttpTelemetry(existing: HttpTelemetrySink | undefined): HttpTelemetrySink | undefined;
+/** Observe opaque host calls without changing their arguments, receiver or returned promise. */
+export declare function bindHttpTelemetry(client: HttpClient, sink: HttpTelemetrySink): HttpClient;

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

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

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

@@ -0,0 +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

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