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

package/dist/server/state-backend-report.d.ts

@@ -0,0 +1,70 @@
+/**
+ * What a provider store resolved to at boot.
+ *
+ * `endpoint` is deliberately host and port only: the URL can carry a password
+ * (`redis://:secret@host:6379`), and the diagnostic inventory already treats
+ * those credential components — and only those — as sensitive
+ * (`collectDiagnosticSensitiveValues`, `urlCredentialComponents(url, {
+ * includePathAndQuery: false })`). A URL that does not parse contributes no
+ * endpoint at all rather than a redacted-looking fragment of itself.
+ */
+export type ProviderStoreBackendReport = {
+    /**
+     * `redis` when a URL resolved, `memory` for the in-process fallback,
+     * `unsupported` when state has no backend and every call fails closed,
+     * `injected` when the host handed the server a store object.
+     */
+    readonly backend: "redis" | "memory" | "unsupported" | "injected";
+    /** Env name that supplied the Redis URL. Present only for `redis`. */
+    readonly envName?: string;
+    /**
+     * `host:port` of the resolved Redis. Never includes credentials, path or
+     * query. Absent when the URL does not parse, or when its query carries an
+     * ioredis option that moves the endpoint (`path`, `port`, `host`, `family`)
+     * so the authority is not where the client connects — see
+     * `state_redis_url_ambiguous_endpoint`.
+     */
+    readonly endpoint?: string;
+    /** URL scheme, e.g. `redis` or `rediss`. Present only for `redis`. */
+    readonly scheme?: string;
+    /** True when the URL came from a shared fallback env rather than the store's own. */
+    readonly fallback?: boolean;
+};
+/**
+ * One line per process boot naming the stores the provider resolved. Without
+ * it, a provider silently riding the cache Redis for its state is
+ * indistinguishable from one on a durable instance, from outside the pod and
+ * from the pod's own logs (apifuse#2302, the reason apifuse#2144 could only be
+ * verified by inference from the Deployment spec).
+ */
+export type ProviderStateBackendLogEvent = {
+    /** `warn` when a warning was raised, otherwise `info`. */
+    readonly level: "info" | "warn";
+    readonly event: "provider_state_backend";
+    readonly providerId: string;
+    readonly state: ProviderStoreBackendReport;
+    readonly cache: ProviderStoreBackendReport;
+    readonly sdkVersion: string;
+    /**
+     * Non-fatal findings, e.g. `state_redis_url_fallback` (the state store is
+     * sharing an instance provisioned for something else),
+     * `state_redis_url_unparsed`, or `state_redis_url_ambiguous_endpoint` (the
+     * URL's query carries an ioredis option that moves the endpoint, so the
+     * authority is not reported as the endpoint). Absent when the resolution
+     * was unambiguous.
+     */
+    readonly warnings?: readonly string[];
+};
+/**
+ * Build the boot event from the same env precedence the stores themselves use
+ * (`providerStateRedisResolutionFromEnv` / `providerCacheRedisResolutionFromEnv`),
+ * so the line can never describe a backend other than the one in use.
+ */
+export declare function providerStateBackendLogEvent(input: {
+    readonly providerId: string;
+    readonly sdkVersion: string;
+    /** The host passed an explicit state store, so no env resolution happened. */
+    readonly injectedState: boolean;
+    /** Mirrors `createProviderRuntimeStateFromEnv({ allowMemoryFallback })`. */
+    readonly allowMemoryFallback: boolean;
+}): ProviderStateBackendLogEvent;

package/dist/server/state-backend-report.js

@@ -0,0 +1,113 @@
+import { providerCacheRedisResolutionFromEnv, providerStateRedisResolutionFromEnv, } from "../config/loader.js";
+/**
+ * Whether ioredis' own URL parsing would move the endpoint away from the
+ * authority this function can see. `createProviderRedisClient` hands the raw
+ * URL to `new Redis(url, …)`, and `parseURL` ends with
+ * `defaults(result, queryOptions)` — lodash `defaults`, so a query key only
+ * applies where the authority supplied nothing:
+ *
+ * - `path` is never derived from the authority of a `redis://` URL (that
+ *   pathname is the db index), so `?path=` always applies — and
+ *   `StandaloneConnector` connects to `options.path` INSTEAD of host/port.
+ *   The client is then on a Unix socket the authority says nothing about.
+ * - `port` applies only when the URL carries no explicit port.
+ * - `host` never applies here: we return early unless `parsed.hostname` is
+ *   set, so `result.host` is always already populated.
+ * - `family` selects an address family; it does not move `host:port`.
+ *
+ * Verified against the pinned ioredis 5.11.1. In those cases the endpoint is
+ * WITHHELD and the ambiguity named, rather than reported as the authority — a
+ * diagnostic whose whole job is to answer "which Redis is this provider on"
+ * must not answer it wrongly. The query is never echoed: it can carry a
+ * password, which is why `endpoint` is host-and-port only to begin with.
+ */
+function queryMovesEndpoint(parsed) {
+    if (parsed.searchParams.has("path"))
+        return true;
+    return parsed.searchParams.has("port") && parsed.port === "";
+}
+function redisEndpoint(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return {};
+    }
+    // No authority means this is not the `redis://host:port` shape at all (e.g.
+    // a bare `host:port`, which parses as a scheme). Report nothing rather than
+    // a fragment of a string whose parts we have not identified.
+    if (!parsed.hostname)
+        return {};
+    const scheme = parsed.protocol.replace(/:$/, "");
+    if (queryMovesEndpoint(parsed))
+        return { scheme, ambiguous: true };
+    return {
+        scheme,
+        endpoint: parsed.port ? `${parsed.hostname}:${parsed.port}` : parsed.hostname,
+    };
+}
+function redisReport(resolution) {
+    const { endpoint, scheme, ambiguous } = redisEndpoint(resolution.url);
+    return {
+        parsed: endpoint !== undefined || ambiguous === true,
+        ambiguous: ambiguous === true,
+        report: {
+            backend: "redis",
+            envName: resolution.envName,
+            ...(endpoint === undefined ? {} : { endpoint }),
+            ...(scheme === undefined ? {} : { scheme }),
+            ...(resolution.fallback ? { fallback: true } : {}),
+        },
+    };
+}
+/**
+ * Build the boot event from the same env precedence the stores themselves use
+ * (`providerStateRedisResolutionFromEnv` / `providerCacheRedisResolutionFromEnv`),
+ * so the line can never describe a backend other than the one in use.
+ */
+export function providerStateBackendLogEvent(input) {
+    const warnings = [];
+    let state;
+    if (input.injectedState) {
+        state = { backend: "injected" };
+    }
+    else {
+        const resolution = providerStateRedisResolutionFromEnv();
+        if (resolution) {
+            const { report, parsed, ambiguous } = redisReport(resolution);
+            state = report;
+            if (!parsed)
+                warnings.push("state_redis_url_unparsed");
+            if (ambiguous)
+                warnings.push("state_redis_url_ambiguous_endpoint");
+            if (resolution.fallback)
+                warnings.push("state_redis_url_fallback");
+        }
+        else {
+            state = { backend: input.allowMemoryFallback ? "memory" : "unsupported" };
+        }
+    }
+    const cacheResolution = providerCacheRedisResolutionFromEnv();
+    let cache;
+    if (cacheResolution) {
+        const { report, parsed, ambiguous } = redisReport(cacheResolution);
+        cache = report;
+        if (!parsed)
+            warnings.push("cache_redis_url_unparsed");
+        if (ambiguous)
+            warnings.push("cache_redis_url_ambiguous_endpoint");
+    }
+    else {
+        cache = { backend: "memory" };
+    }
+    return {
+        level: warnings.length > 0 ? "warn" : "info",
+        event: "provider_state_backend",
+        providerId: input.providerId,
+        state,
+        cache,
+        sdkVersion: input.sdkVersion,
+        ...(warnings.length === 0 ? {} : { warnings }),
+    };
+}

package/dist/server/trace-output.d.ts

@@ -0,0 +1,7 @@
+import { type DiagnosticRedactor } from "../runtime/diagnostic-redactor.js";
+import { type CreateTraceContextOptions } from "../runtime/trace.js";
+import type { TraceConfig } from "../types.js";
+type EnvLike = Record<string, string | undefined>;
+/** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
+export declare function resolveServerTraceContextOptions(config: TraceConfig, resourceAttributes: Record<string, string>, env?: EnvLike, redact?: DiagnosticRedactor): CreateTraceContextOptions;
+export {};

package/dist/server/trace-output.js

@@ -0,0 +1,111 @@
+import { isSensitiveFixtureKey, REDACTED_FIXTURE_VALUE } from "../fixture-sanitization.js";
+import { redactedKeyAllocator, isRedactedKey, REDACTION_FAILED, redactDiagnosticText, } from "../runtime/diagnostic-redactor.js";
+import { OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, resolveOTLPExportOptions, resolveOTLPResourceAttributes, } from "../runtime/otlp.js";
+import { resolveTraceContextOptions, } from "../runtime/trace.js";
+import { sanitizeSpanForOutput, sanitizeSpanNameForOutput, sanitizeTraceAttributes, } from "../trace-sanitization.js";
+const TRACE_RESOURCE_ATTRIBUTE_SANITIZER = Symbol.for("@apifuse/provider-sdk/runtime/trace-resource-attribute-sanitizer");
+// Warn once per environment object: process.env in production, each injected env in tests.
+const warnedEnvironments = new WeakSet();
+const warnedResourceEnvironments = new WeakSet();
+function warnDiscardedResourceAttributes(env, resolution) {
+    if (resolution.discarded.length === 0 || warnedResourceEnvironments.has(env))
+        return;
+    warnedResourceEnvironments.add(env);
+    console.warn(`[apifuse] ${resolution.discarded.join(", ")} could not be parsed as an OTel key=value list and was ignored.`);
+}
+function warnExportDisabled(env, resolution) {
+    if (warnedEnvironments.has(env))
+        return;
+    warnedEnvironments.add(env);
+    console.warn(resolution.status === "unconfigured"
+        ? `[apifuse] OTLP trace export is enabled but no endpoint is configured; set ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT} or ${OTEL_EXPORTER_OTLP_ENDPOINT}. Trace export is disabled.`
+        : `[apifuse] OTLP trace export is enabled but ${resolution.source} ${resolution.reason}. Trace export is disabled.`);
+}
+function resolveServerOTLPExportOptions(config, env) {
+    const resolution = resolveOTLPExportOptions({
+        endpoint: config.otlp?.endpoint ?? config.endpoint,
+        headers: config.otlp?.headers,
+        timeout: config.otlp?.timeout,
+    }, env);
+    if (resolution.status === "resolved")
+        return resolution.options;
+    warnExportDisabled(env, resolution);
+    return undefined;
+}
+/**
+ * Per-request attributes carry client-supplied values (request_id) and get the full attribute
+ * sanitizer, exactly as on the console path. Operator-configured attributes from the process
+ * environment are identifiers rather than request data: their values are kept, with control
+ * characters neutralized, length bounded, and secret-named keys redacted.
+ */
+function resolveExportResourceAttributes(requestAttributes, env, redact) {
+    const resolution = resolveOTLPResourceAttributes({}, env);
+    warnDiscardedResourceAttributes(env, resolution);
+    const operatorAttributes = resolution.attributes;
+    const requestKeys = new Set(Object.keys(requestAttributes));
+    return {
+        // Keep the raw snapshot private until export. A credential registered after
+        // trace creation must be matched before any key or value is bounded.
+        attributes: { ...operatorAttributes, ...requestAttributes },
+        sanitize(attributes) {
+            const nextKey = redactedKeyAllocator(Object.keys(attributes));
+            const sanitizedOperatorAttributes = {};
+            const rawRequestAttributes = {};
+            for (const [key, value] of Object.entries(attributes)) {
+                const unchangedOperatorValue = !requestKeys.has(key) && operatorAttributes[key] === value;
+                if (unchangedOperatorValue) {
+                    const redactedKey = isRedactedKey(key) ? key : redactDiagnosticText(key, redact);
+                    const keyChanged = redactedKey !== key;
+                    const sanitizedKey = keyChanged ? nextKey() : sanitizeSpanNameForOutput(key);
+                    sanitizedOperatorAttributes[sanitizedKey] = keyChanged
+                        ? redactedKey === REDACTION_FAILED
+                            ? REDACTION_FAILED
+                            : REDACTED_FIXTURE_VALUE
+                        : isSensitiveFixtureKey(key)
+                            ? REDACTED_FIXTURE_VALUE
+                            : sanitizeSpanNameForOutput(value, redact);
+                }
+                else {
+                    rawRequestAttributes[key] = value;
+                }
+            }
+            const sanitizedRequestAttributes = Object.fromEntries(Object.entries(sanitizeTraceAttributes(rawRequestAttributes, redact, Object.keys(sanitizedOperatorAttributes))).map(([key, value]) => [key, String(value)]));
+            return { ...sanitizedOperatorAttributes, ...sanitizedRequestAttributes };
+        },
+    };
+}
+/** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
+export function resolveServerTraceContextOptions(config, resourceAttributes, env = process.env, redact) {
+    const resolved = resolveTraceContextOptions(config);
+    const outputEnabled = config.enabled !== false && config.exporter !== "none";
+    const consoleHook = outputEnabled && (config.exporter === "console" || config.exporter === "json")
+        ? (span) => console.log(JSON.stringify(sanitizeSpanForOutput(span, resourceAttributes, redact)))
+        : undefined;
+    const onSpan = consoleHook && resolved.onSpan
+        ? (span) => {
+            consoleHook(span);
+            resolved.onSpan?.(span);
+        }
+        : (consoleHook ?? resolved.onSpan);
+    const exportOptions = outputEnabled && config.exporter === "otlp"
+        ? resolveServerOTLPExportOptions(config, env)
+        : undefined;
+    const exportResources = exportOptions
+        ? resolveExportResourceAttributes(resourceAttributes, env, redact)
+        : undefined;
+    if (exportResources) {
+        Object.defineProperty(exportResources.attributes, TRACE_RESOURCE_ATTRIBUTE_SANITIZER, { value: exportResources.sanitize });
+    }
+    return {
+        maxSpans: resolved.maxSpans,
+        onSpan,
+        ...(redact ? { redact } : {}),
+        ...(exportOptions
+            ? {
+                exportOptions,
+                resourceAttributes: exportResources?.attributes,
+                sanitizeSpanForExport: (span) => sanitizeSpanForOutput(span, undefined, redact),
+            }
+            : {}),
+    };
+}

package/dist/server/types.d.ts

@@ -4,6 +4,7 @@ export declare const ConnectionModeSchema: z.ZodEnum<{
     none: "none";
     oauth2: "oauth2";
     "platform-managed": "platform-managed";
+    oauth2_proxied: "oauth2_proxied";
 }>;
 export declare const OperationConnectionSchema: z.ZodObject<{
     id: z.ZodString;
@@ -12,6 +13,7 @@ export declare const OperationConnectionSchema: z.ZodObject<{
         none: "none";
         oauth2: "oauth2";
         "platform-managed": "platform-managed";
+        oauth2_proxied: "oauth2_proxied";
     }>;
     secrets: z.ZodRecord<z.ZodString, z.ZodString>;
     scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -29,12 +31,14 @@ export declare const OperationRequestSchema: z.ZodObject<{
             none: "none";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
+            oauth2_proxied: "oauth2_proxied";
         }>;
         secrets: z.ZodRecord<z.ZodString, z.ZodString>;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         externalRef: z.ZodString;
     }, z.core.$strip>>;
+    tenantId: z.ZodOptional<z.ZodString>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     trace: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
@@ -42,6 +46,13 @@ export declare const ErrorEnvelopeSchema: z.ZodObject<{
     code: z.ZodString;
     message: z.ZodString;
     requestId: z.ZodOptional<z.ZodString>;
+    retryable: z.ZodBoolean;
+    source: z.ZodOptional<z.ZodEnum<{
+        client: "client";
+        upstream_rule: "upstream_rule";
+        upstream_failure: "upstream_failure";
+        apifuse: "apifuse";
+    }>>;
     fix: z.ZodOptional<z.ZodString>;
     details: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
@@ -55,21 +66,21 @@ export declare const OperationSuccessResponseSchema: z.ZodObject<{
             stale: z.ZodBoolean;
             keys: z.ZodArray<z.ZodString>;
             source: z.ZodOptional<z.ZodEnum<{
-                loader: "loader";
-                memory: "memory";
                 mixed: "mixed";
                 redis: "redis";
+                memory: "memory";
+                loader: "loader";
             }>>;
         }, z.core.$strip>>;
         retry: z.ZodOptional<z.ZodObject<{
             attempts: z.ZodNumber;
             retries: z.ZodNumber;
             preset: z.ZodOptional<z.ZodEnum<{
-                aggressive_read: "aggressive_read";
                 off: "off";
-                rate_limit_aware: "rate_limit_aware";
-                safe_read: "safe_read";
                 transport_transient: "transport_transient";
+                safe_read: "safe_read";
+                aggressive_read: "aggressive_read";
+                rate_limit_aware: "rate_limit_aware";
             }>>;
             transport: z.ZodEnum<{
                 native: "native";
@@ -84,6 +95,13 @@ export declare const OperationErrorResponseSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
+        source: z.ZodOptional<z.ZodEnum<{
+            client: "client";
+            upstream_rule: "upstream_rule";
+            upstream_failure: "upstream_failure";
+            apifuse: "apifuse";
+        }>>;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;
@@ -98,6 +116,9 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    engine: z.ZodOptional<z.ZodObject<{
+        egressLease: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
@@ -105,6 +126,7 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
             none: "none";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
+            oauth2_proxied: "oauth2_proxied";
         }>;
         secrets: z.ZodRecord<z.ZodString, z.ZodString>;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -115,12 +137,22 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
 export declare const AuthFlowSuccessResponseSchema: z.ZodObject<{
     data: z.ZodUnknown;
     contextPatch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodUnknown>>>;
+    engine: z.ZodOptional<z.ZodObject<{
+        egressLease: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const AuthFlowErrorResponseSchema: z.ZodObject<{
     error: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
+        source: z.ZodOptional<z.ZodEnum<{
+            client: "client";
+            upstream_rule: "upstream_rule";
+            upstream_failure: "upstream_failure";
+            apifuse: "apifuse";
+        }>>;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;

package/dist/server/types.js

@@ -1,6 +1,13 @@
 import { z } from "zod";
+import { PROVIDER_ERROR_SOURCES } from "../observability.js";
 import { HttpRetryPreset } from "../types.js";
-export const ConnectionModeSchema = z.enum(["oauth2", "credentials", "platform-managed", "none"]);
+export const ConnectionModeSchema = z.enum([
+    "oauth2",
+    "oauth2_proxied",
+    "credentials",
+    "platform-managed",
+    "none",
+]);
 export const OperationConnectionSchema = z.object({
     id: z.string(),
     mode: ConnectionModeSchema,
@@ -14,6 +21,13 @@ export const OperationRequestSchema = z.object({
     input: z.record(z.string(), z.unknown()),
     connectionId: z.string().optional(),
     connection: OperationConnectionSchema.optional(),
+    /**
+     * Gateway-asserted principal scope: the organization id for customer
+     * subjects, the service-account id for platform service accounts. Absent
+     * on direct calls and self-test. Trusted exactly like `connectionId`; it is
+     * never derived from caller headers or `input`.
+     */
+    tenantId: z.string().optional(),
     headers: z.record(z.string(), z.string()).optional(),
     trace: z.record(z.string(), z.string()).optional(),
 });
@@ -21,6 +35,11 @@ export const ErrorEnvelopeSchema = z.object({
     code: z.string(),
     message: z.string(),
     requestId: z.string().optional(),
+    retryable: z.boolean(),
+    // Who stopped the request (honest-provider-error-contract); optional so
+    // older peers (stateful forwarding owners) remain parseable. Derived from
+    // the PROVIDER_ERROR_SOURCES registry so the enum cannot drift.
+    source: z.enum(PROVIDER_ERROR_SOURCES).optional(),
     fix: z.string().optional(),
     details: z.unknown().optional(),
 });
@@ -73,10 +92,24 @@ export const AuthFlowRequestSchema = z.object({
     headers: z.record(z.string(), z.string()).optional(),
     input: z.record(z.string(), z.unknown()).optional(),
     context: z.record(z.string(), z.unknown()).optional(),
+    /** Opaque engine state. This is never projected into FlowContext or provider contextPatch. */
+    engine: z
+        .object({
+        egressLease: z.string().min(1).max(16_384).optional(),
+    })
+        .strict()
+        .optional(),
     connection: OperationConnectionSchema.optional(),
 });
 export const AuthFlowSuccessResponseSchema = z.object({
     data: z.unknown(),
     contextPatch: z.record(z.string(), z.unknown().nullable()).optional(),
+    /** Opaque engine state to carry verbatim to the next auth turn. */
+    engine: z
+        .object({
+        egressLease: z.string().min(1).max(16_384).optional(),
+    })
+        .strict()
+        .optional(),
 });
 export const AuthFlowErrorResponseSchema = OperationErrorResponseSchema;

package/dist/stateful/errors.d.ts

@@ -0,0 +1,19 @@
+export type StatefulControlPlaneOperation = "resolve" | "acquire" | "renew" | "release";
+export declare class StatefulRoutingDeadlineError extends Error {
+    readonly requestId: string;
+    readonly deadlineAt: string;
+    constructor(requestId: string, deadlineAt: string);
+}
+export declare class StatefulControlPlaneError extends Error {
+    readonly code: string;
+    readonly operation: StatefulControlPlaneOperation;
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(input: {
+        readonly code: string;
+        readonly message: string;
+        readonly operation: StatefulControlPlaneOperation;
+        readonly status?: number;
+        readonly cause?: unknown;
+    });
+}

package/dist/stateful/errors.js

@@ -0,0 +1,24 @@
+export class StatefulRoutingDeadlineError extends Error {
+    requestId;
+    deadlineAt;
+    constructor(requestId, deadlineAt) {
+        super(`Stateful operation request ${requestId} deadline has expired.`);
+        this.name = "StatefulRoutingDeadlineError";
+        this.requestId = requestId;
+        this.deadlineAt = deadlineAt;
+    }
+}
+export class StatefulControlPlaneError extends Error {
+    code;
+    operation;
+    status;
+    cause;
+    constructor(input) {
+        super(input.message);
+        this.name = "StatefulControlPlaneError";
+        this.code = input.code;
+        this.operation = input.operation;
+        this.status = input.status;
+        this.cause = input.cause;
+    }
+}

package/dist/stateful/http-provider-event-emitter.d.ts

@@ -0,0 +1,40 @@
+import type { ProviderEventDeliveryFailureRecorder } from "./provider-event-delivery-failures.js";
+import type { ProviderEventPublisher, ProviderEventPublishOptions, PublishAck } from "./provider-event-pipeline.js";
+import { type ProviderEventMetricEmitter } from "./provider-event-pipeline-metrics.js";
+import type { ProviderEvent } from "./provider-events.js";
+type FetchTransport = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type HttpProviderEventEmitterOptions = {
+    readonly baseUrl: string;
+    readonly secret: string;
+    readonly fetch?: FetchTransport;
+    readonly clock?: () => Date;
+    readonly random?: () => number;
+    readonly metricEmitter?: ProviderEventMetricEmitter;
+    readonly failureRecorder?: ProviderEventDeliveryFailureRecorder;
+    readonly maxBufferedEvents?: number;
+    readonly retryBaseMs?: number;
+    readonly retryMaxMs?: number;
+    readonly maxAttempts?: number;
+    readonly jitterRatio?: number;
+};
+export type ProviderEventFlushReport = {
+    /** Events delivered during this emitter's lifetime. */
+    readonly delivered: number;
+    /** Events permanently dropped during this emitter's lifetime. */
+    readonly failed: number;
+    /** Events still buffered when flush returned. */
+    readonly pending: number;
+};
+/**
+ * Provider-pod HTTP publication with a bounded best-effort delivery guarantee and at-least-once
+ * transport retries. This is not durable at-least-once delivery: buffered events can be lost if
+ * the process is killed. Graceful shutdown should drain the in-memory buffer with flush().
+ */
+export declare class HttpProviderEventEmitter implements ProviderEventPublisher {
+    #private;
+    constructor(options: HttpProviderEventEmitterOptions);
+    publish(event: ProviderEvent, options: ProviderEventPublishOptions): PublishAck;
+    pendingCount(): number;
+    flush(timeoutMs?: number): Promise<ProviderEventFlushReport>;
+}
+export {};