@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.11

package/dist/stateful/session-key.js

@@ -0,0 +1,86 @@
+const PREFIX = "stateful:v1";
+const REQUIRED_DIMENSIONS = ["providerId", "serviceAccountId", "connectionId"];
+const REQUIRED_DIMENSION_SET = new Set(REQUIRED_DIMENSIONS);
+export function buildSessionKey(parts) {
+    validateRequiredPart(parts.providerId, "providerId");
+    validateRequiredPart(parts.serviceAccountId, "serviceAccountId");
+    validateRequiredPart(parts.connectionId, "connectionId");
+    const dimensions = Object.entries(parts.dimensions ?? {}).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+    for (const [name, value] of dimensions) {
+        validateDimension(name, value);
+    }
+    const segments = [
+        ["providerId", parts.providerId],
+        ["serviceAccountId", parts.serviceAccountId],
+        ["connectionId", parts.connectionId],
+        ...dimensions,
+    ];
+    return `${PREFIX}/${segments
+        .map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`)
+        .join("/")}`;
+}
+export function parseSessionKey(key) {
+    const prefix = `${PREFIX}/`;
+    if (!key.startsWith(prefix)) {
+        throw new Error(`Invalid session key: expected canonical prefix "${PREFIX}".`);
+    }
+    const parsed = new Map();
+    for (const segment of key.slice(prefix.length).split("/")) {
+        const separator = segment.indexOf("=");
+        if (separator <= 0) {
+            throw new Error(`Invalid session key segment "${segment}"; expected name=value.`);
+        }
+        const name = decodeSegment(segment.slice(0, separator), "dimension name");
+        const value = decodeSegment(segment.slice(separator + 1), `dimension "${name}"`);
+        if (parsed.has(name)) {
+            throw new Error(`Invalid session key: duplicate dimension "${name}".`);
+        }
+        if (name.trim().length === 0) {
+            throw new Error("Invalid session key: dimension name must not be empty.");
+        }
+        if (value.trim().length === 0) {
+            throw new Error(`Invalid session key: dimension "${name}" must not be empty.`);
+        }
+        parsed.set(name, value);
+    }
+    for (const required of REQUIRED_DIMENSIONS) {
+        if (!parsed.has(required)) {
+            throw new Error(`Invalid session key: missing required dimension "${required}".`);
+        }
+    }
+    const dimensions = {};
+    for (const [name, value] of parsed) {
+        if (!REQUIRED_DIMENSION_SET.has(name))
+            dimensions[name] = value;
+    }
+    return {
+        providerId: parsed.get("providerId"),
+        serviceAccountId: parsed.get("serviceAccountId"),
+        connectionId: parsed.get("connectionId"),
+        dimensions,
+    };
+}
+function validateRequiredPart(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Cannot build session key: required dimension "${name}" is missing or empty.`);
+    }
+}
+function validateDimension(name, value) {
+    if (name.trim().length === 0) {
+        throw new Error("Cannot build session key: extra dimension name must not be empty.");
+    }
+    if (REQUIRED_DIMENSION_SET.has(name)) {
+        throw new Error(`Cannot build session key: extra dimension "${name}" duplicates a required dimension.`);
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Cannot build session key: extra dimension "${name}" is missing or empty.`);
+    }
+}
+function decodeSegment(value, label) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw new Error(`Invalid session key: ${label} is not valid URI encoding.`);
+    }
+}

package/dist/stateful/stateful-provider-adapter-context.d.ts

@@ -0,0 +1,5 @@
+import type { StatefulProviderSessionContext } from "./stateful-provider-adapter.js";
+import type { StatefulOperationRequest } from "./stateful-provider-session-routing.js";
+import type { ManagedSession, SessionOwnerRecord } from "./stateful-provider-session-runtime.js";
+export declare function makeStatefulProviderSessionContext(providerId: string, owner: SessionOwnerRecord, request: StatefulOperationRequest, signal: AbortSignal): StatefulProviderSessionContext;
+export declare function makeStatefulProviderCloseContext<TSession>(providerId: string, session: ManagedSession<TSession>): StatefulProviderSessionContext;

package/dist/stateful/stateful-provider-adapter-context.js

@@ -0,0 +1,42 @@
+export function makeStatefulProviderSessionContext(providerId, owner, request, signal) {
+    const ctx = {
+        sessionKey: owner.sessionKey,
+        providerId,
+        connectionId: request.connectionId,
+        serviceAccountId: request.serviceAccountId,
+        ownerPodId: owner.ownerPodId,
+        ownerEndpoint: owner.ownerEndpoint,
+        ownerStatus: owner.status,
+        generation: owner.generation,
+        signal,
+        requestId: request.requestId,
+        operationId: request.operationId,
+        ...(request.runtimeContext !== undefined ? { runtimeContext: request.runtimeContext } : {}),
+    };
+    return withOptionalRequestMetadata(ctx, request);
+}
+export function makeStatefulProviderCloseContext(providerId, session) {
+    const identity = session.identity;
+    return {
+        sessionKey: session.sessionKey,
+        providerId,
+        ...(identity
+            ? {
+                connectionId: identity.connectionId,
+                serviceAccountId: identity.serviceAccountId,
+                ownerPodId: identity.ownerPodId,
+                ownerEndpoint: identity.ownerEndpoint,
+                ownerStatus: identity.ownerStatus,
+            }
+            : {}),
+        generation: session.generation,
+        signal: new AbortController().signal,
+    };
+}
+function withOptionalRequestMetadata(ctx, request) {
+    return {
+        ...ctx,
+        ...(request.idempotencyKey ? { idempotencyKey: request.idempotencyKey } : {}),
+        ...(request.deadlineAt ? { deadlineAt: request.deadlineAt } : {}),
+    };
+}

package/dist/stateful/stateful-provider-adapter-metrics.d.ts

@@ -0,0 +1,15 @@
+import type { StatefulProviderMetricEmitter } from "./stateful-provider-observability.js";
+import type { StatefulOperationRequest } from "./stateful-provider-session-routing.js";
+import type { SessionOwnerRecord } from "./stateful-provider-session-runtime.js";
+export declare function observeStatefulSessionOperationDuration(input: {
+    readonly metricEmitter: StatefulProviderMetricEmitter;
+    readonly request: StatefulOperationRequest;
+    readonly owner: SessionOwnerRecord;
+    readonly durationMs: number;
+}): void;
+export declare function emitStatefulSessionInvalidatedMetric(input: {
+    readonly metricEmitter: StatefulProviderMetricEmitter;
+    readonly request: StatefulOperationRequest;
+    readonly owner: SessionOwnerRecord;
+    readonly reason: string;
+}): void;

package/dist/stateful/stateful-provider-adapter-metrics.js

@@ -0,0 +1,21 @@
+export function observeStatefulSessionOperationDuration(input) {
+    input.metricEmitter.observe("apifuse_stateful_provider_session_operation_duration_ms", statefulSessionMetricLabels(input.request, input.owner), Math.max(0, input.durationMs));
+}
+export function emitStatefulSessionInvalidatedMetric(input) {
+    input.metricEmitter.increment("apifuse_stateful_provider_session_invalidations_total", statefulSessionMetricLabels(input.request, input.owner, {
+        redactedErrorCode: input.reason,
+    }));
+}
+function statefulSessionMetricLabels(request, owner, extra = {}) {
+    return {
+        requestId: request.requestId,
+        providerId: request.providerId,
+        connectionId: request.connectionId,
+        serviceAccountId: request.serviceAccountId,
+        operationId: request.operationId,
+        sessionKey: request.sessionKey,
+        ownerPodId: owner.ownerPodId,
+        generation: owner.generation,
+        ...extra,
+    };
+}

package/dist/stateful/stateful-provider-adapter.d.ts

@@ -0,0 +1,98 @@
+import type { ProviderEventPublishOptions } from "./provider-event-pipeline.js";
+import { type StatefulProviderMetricEmitter } from "./stateful-provider-observability.js";
+import type { StatefulOperationExecutor, StatefulOperationRequest, StatefulOperationResult, StatefulOwnershipValidator } from "./stateful-provider-session-routing.js";
+import type { SessionOwnerRecord, SessionPoolPolicy } from "./stateful-provider-session-runtime.js";
+export type StatefulProviderConcurrencyPolicy = {
+    readonly mode: "serialize";
+} | {
+    readonly mode: "parallel";
+    readonly maxInFlight?: number;
+};
+export type StatefulProviderReconnectPolicy = "resume" | "recreate" | "unsupported";
+export type StatefulProviderAdapterPolicy = {
+    readonly concurrency: StatefulProviderConcurrencyPolicy;
+    readonly reconnect: StatefulProviderReconnectPolicy;
+};
+export type StatefulSessionHealth = {
+    readonly status: "ready" | "connecting" | "reconnecting" | "degraded" | "closed";
+    readonly reason?: string;
+    readonly lastError?: string;
+};
+export declare class StatefulSessionInvalidatedError extends Error {
+    readonly name = "StatefulSessionInvalidatedError";
+    readonly reason: string;
+    readonly retryable: boolean;
+    constructor(message: string, options: {
+        readonly reason: string;
+        readonly retryable?: boolean;
+    });
+}
+export interface StatefulProviderSessionContext {
+    readonly sessionKey: string;
+    readonly providerId: string;
+    /** Present for operation-created sessions; optional for direct pool users. */
+    readonly connectionId?: string;
+    /** Present for operation-created sessions; optional for direct pool users. */
+    readonly serviceAccountId?: string;
+    readonly ownerPodId?: string;
+    readonly ownerEndpoint?: string;
+    readonly ownerStatus?: string;
+    readonly generation: number;
+    readonly signal: AbortSignal;
+    readonly requestId?: string;
+    readonly operationId?: string;
+    readonly idempotencyKey?: string;
+    readonly deadlineAt?: string;
+    readonly runtimeContext?: unknown;
+}
+export type StatefulProviderEventPublish<TEvent = unknown> = (event: TEvent) => void | Promise<void>;
+export type StatefulProviderEventDisposer = () => void | Promise<void>;
+export interface StatefulProviderEventPublisher<TEvent = unknown> {
+    publish(event: TEvent, options: ProviderEventPublishOptions): unknown;
+}
+export type StatefulWriteReconciliationResult<TSharedState = unknown> = {
+    readonly result: StatefulOperationResult;
+    readonly sharedState?: TSharedState;
+};
+export interface StatefulProviderAdapter<TSession, TSharedState = unknown, TEvent = unknown> {
+    readonly providerId: string;
+    readonly policy: StatefulProviderAdapterPolicy;
+    /** Optional until durable cursor/checkpoint state exists for a provider. */
+    restore?(ctx: StatefulProviderSessionContext): Promise<TSharedState | undefined>;
+    connect(ctx: StatefulProviderSessionContext, sharedState: TSharedState | undefined): Promise<TSession>;
+    invoke(ctx: StatefulProviderSessionContext, session: TSession, request: StatefulOperationRequest): Promise<StatefulOperationResult>;
+    /** Requires a matching session-manager checkpointStore. */
+    snapshot?(ctx: StatefulProviderSessionContext, session: TSession): Promise<TSharedState | undefined>;
+    /** Caller-driven through StatefulProviderSessionManager.health(). */
+    health?(ctx: StatefulProviderSessionContext, session: TSession): Promise<StatefulSessionHealth>;
+    close(ctx: StatefulProviderSessionContext, session: TSession, reason: string): Promise<void>;
+    /** Caller-driven through StatefulProviderSessionManager.reconcileWrite(). */
+    reconcileWrite?(ctx: StatefulProviderSessionContext, ledgerEntry: unknown, sharedState: TSharedState | undefined): Promise<StatefulWriteReconciliationResult<TSharedState>>;
+    /** Registers a connection-owned event source. Its disposer runs before checkpoint and close. */
+    subscribe?(ctx: StatefulProviderSessionContext, session: TSession, publish: StatefulProviderEventPublish<TEvent>): StatefulProviderEventDisposer | Promise<StatefulProviderEventDisposer>;
+}
+export type StatefulProviderSessionManagerOptions<TSession, TSharedState, TEvent = unknown> = {
+    readonly adapter: StatefulProviderAdapter<TSession, TSharedState, TEvent>;
+    readonly poolPolicy: SessionPoolPolicy;
+    readonly checkpointStore?: (ctx: StatefulProviderSessionContext, state: TSharedState) => Promise<void>;
+    readonly eventPublisher?: StatefulProviderEventPublisher<TEvent>;
+    readonly clock?: () => Date;
+    readonly metricEmitter?: StatefulProviderMetricEmitter;
+};
+export declare class StatefulProviderSessionManager<TSession, TSharedState = unknown, TEvent = unknown> implements StatefulOperationExecutor<TSession> {
+    #private;
+    constructor(options: StatefulProviderSessionManagerOptions<TSession, TSharedState, TEvent>);
+    invoke(owner: SessionOwnerRecord, request: StatefulOperationRequest, signal: AbortSignal, validateOwnership?: StatefulOwnershipValidator): Promise<StatefulOperationResult>;
+    executeLocal(request: StatefulOperationRequest, owner: SessionOwnerRecord, signal: AbortSignal, validateOwnership?: StatefulOwnershipValidator): Promise<StatefulOperationResult>;
+    health(owner: SessionOwnerRecord, request: StatefulOperationRequest, signal: AbortSignal, validateOwnership?: StatefulOwnershipValidator): Promise<StatefulSessionHealth>;
+    reconcileWrite(owner: SessionOwnerRecord, request: StatefulOperationRequest, ledgerEntry: unknown, signal: AbortSignal, validateOwnership?: StatefulOwnershipValidator): Promise<StatefulWriteReconciliationResult<TSharedState>>;
+    closeAll(reason: string): Promise<void>;
+    private getOrCreate;
+    private connect;
+    private validatePooledOwnership;
+    private refreshEventOwnerFence;
+    private closeManagedSession;
+    private observeDuration;
+    private runLimited;
+    private schedule;
+}

package/dist/stateful/stateful-provider-adapter.js

@@ -0,0 +1,287 @@
+import { makeStatefulProviderCloseContext, makeStatefulProviderSessionContext, } from "./stateful-provider-adapter-context.js";
+import { emitStatefulSessionInvalidatedMetric, observeStatefulSessionOperationDuration, } from "./stateful-provider-adapter-metrics.js";
+import { NOOP_STATEFUL_PROVIDER_METRIC_EMITTER, } from "./stateful-provider-observability.js";
+import { PodLocalSessionPool } from "./stateful-provider-session-runtime.js";
+export class StatefulSessionInvalidatedError extends Error {
+    name = "StatefulSessionInvalidatedError";
+    reason;
+    retryable;
+    constructor(message, options) {
+        super(message);
+        this.reason = options.reason;
+        this.retryable = options.retryable ?? false;
+    }
+}
+const STATEFUL_SESSION_ESTABLISHMENT_FAILURE = Symbol.for("@apifuse/provider-sdk/stateful/session-establishment-failure@1");
+function markStatefulSessionEstablishmentFailure(error) {
+    if ((typeof error === "object" && error !== null) || typeof error === "function") {
+        try {
+            Object.defineProperty(error, STATEFUL_SESSION_ESTABLISHMENT_FAILURE, {
+                value: true,
+                enumerable: false,
+            });
+            return error;
+        }
+        catch { }
+    }
+    const wrapped = new Error("Stateful session establishment failed.", { cause: error });
+    Object.defineProperty(wrapped, STATEFUL_SESSION_ESTABLISHMENT_FAILURE, { value: true });
+    return wrapped;
+}
+export class StatefulProviderSessionManager {
+    #adapter;
+    #pool;
+    #checkpointStore;
+    #eventPublisher;
+    #clock;
+    #metricEmitter;
+    #eventDisposers = new Map();
+    #eventOwnerFences = new Map();
+    #parallelLimiters = new Map();
+    constructor(options) {
+        validateAdapterConfiguration(options);
+        this.#adapter = options.adapter;
+        this.#checkpointStore = options.checkpointStore;
+        this.#eventPublisher = options.eventPublisher;
+        this.#clock = options.clock ?? (() => new Date());
+        this.#metricEmitter = options.metricEmitter ?? NOOP_STATEFUL_PROVIDER_METRIC_EMITTER;
+        this.#pool = new PodLocalSessionPool(options.poolPolicy, (session, reason) => this.closeManagedSession(session, reason));
+    }
+    async invoke(owner, request, signal, validateOwnership) {
+        const startedAt = this.#clock().getTime();
+        const run = async () => {
+            const managedSession = await this.getOrCreate(owner, request, signal, validateOwnership);
+            const validatedOwner = await this.validatePooledOwnership(owner, request.sessionKey, signal, validateOwnership);
+            const ctx = makeStatefulProviderSessionContext(this.#adapter.providerId, validatedOwner, request, signal);
+            try {
+                const result = await this.#adapter.invoke(ctx, managedSession.value, request);
+                this.observeDuration(request, owner, startedAt);
+                return result;
+            }
+            catch (error) {
+                if (!(error instanceof StatefulSessionInvalidatedError))
+                    throw error;
+                emitStatefulSessionInvalidatedMetric({
+                    metricEmitter: this.#metricEmitter,
+                    request,
+                    owner,
+                    reason: error.reason,
+                });
+                await this.#pool.invalidate(owner.sessionKey, error.reason);
+                if (!error.retryable || this.#adapter.policy.reconnect === "unsupported")
+                    throw error;
+                const reconnected = await this.getOrCreate(owner, request, signal, validateOwnership);
+                const revalidatedOwner = await this.validatePooledOwnership(owner, request.sessionKey, signal, validateOwnership);
+                const reconnectedCtx = makeStatefulProviderSessionContext(this.#adapter.providerId, revalidatedOwner, request, signal);
+                const result = await this.#adapter.invoke(reconnectedCtx, reconnected.value, request);
+                this.observeDuration(request, owner, startedAt);
+                return result;
+            }
+        };
+        return this.schedule(owner.sessionKey, run);
+    }
+    executeLocal(request, owner, signal, validateOwnership) {
+        return this.invoke(owner, request, signal, validateOwnership);
+    }
+    async health(owner, request, signal, validateOwnership) {
+        if (!this.#adapter.health) {
+            throw new Error(`Stateful provider adapter "${this.#adapter.providerId}" has no health hook.`);
+        }
+        return this.schedule(owner.sessionKey, async () => {
+            const session = await this.getOrCreate(owner, request, signal, validateOwnership);
+            const validatedOwner = await this.validatePooledOwnership(owner, request.sessionKey, signal, validateOwnership);
+            return this.#adapter.health?.(makeStatefulProviderSessionContext(this.#adapter.providerId, validatedOwner, request, signal), session.value);
+        });
+    }
+    async reconcileWrite(owner, request, ledgerEntry, signal, validateOwnership) {
+        if (!this.#adapter.reconcileWrite) {
+            throw new Error(`Stateful provider adapter "${this.#adapter.providerId}" does not support write reconciliation.`);
+        }
+        return this.schedule(owner.sessionKey, async () => {
+            const restoreCtx = makeStatefulProviderSessionContext(this.#adapter.providerId, owner, request, signal);
+            const sharedState = this.#adapter.restore
+                ? await this.#adapter.restore(restoreCtx)
+                : undefined;
+            const validatedOwner = validateOwnership ? await validateOwnership(owner, signal) : owner;
+            const ctx = makeStatefulProviderSessionContext(this.#adapter.providerId, validatedOwner, request, signal);
+            return this.#adapter.reconcileWrite?.(ctx, ledgerEntry, sharedState);
+        });
+    }
+    closeAll(reason) {
+        return this.#pool.closeAll(reason);
+    }
+    async getOrCreate(owner, request, signal, validateOwnership) {
+        return this.#pool.getOrCreate(owner.sessionKey, owner.generation, () => this.connect(owner, request, signal, validateOwnership), this.#clock(), managedSessionIdentity(owner, request));
+    }
+    async connect(owner, request, signal, validateOwnership) {
+        const ctx = makeStatefulProviderSessionContext(this.#adapter.providerId, owner, request, signal);
+        let session;
+        let connected = false;
+        try {
+            const sharedState = this.#adapter.restore ? await this.#adapter.restore(ctx) : undefined;
+            session = await this.#adapter.connect(ctx, sharedState);
+            connected = true;
+            const validatedOwner = validateOwnership ? await validateOwnership(owner, signal) : owner;
+            const validatedCtx = makeStatefulProviderSessionContext(this.#adapter.providerId, validatedOwner, request, signal);
+            this.refreshEventOwnerFence(validatedOwner, request.sessionKey);
+            if (!this.#adapter.subscribe || !this.#eventPublisher)
+                return session;
+            const identityKey = sessionIdentityKey(owner.sessionKey, owner.generation);
+            const disposer = await this.#adapter.subscribe(validatedCtx, session, (event) => {
+                const ownerFence = this.#eventOwnerFences.get(identityKey);
+                if (!ownerFence)
+                    return;
+                this.#eventPublisher?.publish(event, { ownerFence });
+            });
+            if (typeof disposer !== "function") {
+                throw new Error(`Stateful provider adapter "${this.#adapter.providerId}" subscribe hook must return a disposer.`);
+            }
+            this.#eventDisposers.set(identityKey, disposer);
+            return session;
+        }
+        catch (error) {
+            this.#eventOwnerFences.delete(sessionIdentityKey(owner.sessionKey, owner.generation));
+            let establishmentError = error;
+            if (connected) {
+                try {
+                    await this.#adapter.close(ctx, session, "session-establishment-failed");
+                }
+                catch (closeError) {
+                    establishmentError = new AggregateError([error, closeError], "Stateful session establishment and cleanup both failed.");
+                }
+            }
+            throw markStatefulSessionEstablishmentFailure(establishmentError);
+        }
+    }
+    async validatePooledOwnership(owner, sessionKey, signal, validateOwnership) {
+        try {
+            const validatedOwner = validateOwnership ? await validateOwnership(owner, signal) : owner;
+            this.refreshEventOwnerFence(validatedOwner, sessionKey);
+            return validatedOwner;
+        }
+        catch (error) {
+            await this.#pool
+                .invalidate(owner.sessionKey, "ownership-validation-failed")
+                .catch(() => undefined);
+            throw markStatefulSessionEstablishmentFailure(error);
+        }
+    }
+    refreshEventOwnerFence(owner, sessionKey) {
+        this.#eventOwnerFences.set(sessionIdentityKey(owner.sessionKey, owner.generation), {
+            sessionKey,
+            generation: owner.generation,
+            ownerPodId: owner.ownerPodId,
+            ownerEndpoint: owner.ownerEndpoint,
+        });
+    }
+    async closeManagedSession(session, reason) {
+        const ctx = makeStatefulProviderCloseContext(this.#adapter.providerId, session);
+        const errors = [];
+        const disposerKey = sessionIdentityKey(session.sessionKey, session.generation);
+        const disposer = this.#eventDisposers.get(disposerKey);
+        this.#eventDisposers.delete(disposerKey);
+        this.#eventOwnerFences.delete(disposerKey);
+        if (disposer) {
+            try {
+                await disposer();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (this.#adapter.snapshot && this.#checkpointStore) {
+            try {
+                const state = await this.#adapter.snapshot(ctx, session.value);
+                if (state !== undefined)
+                    await this.#checkpointStore(ctx, state);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        try {
+            await this.#adapter.close(ctx, session.value, reason);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, "Stateful session cleanup failed in multiple hooks.");
+        }
+    }
+    observeDuration(request, owner, startedAt) {
+        observeStatefulSessionOperationDuration({
+            metricEmitter: this.#metricEmitter,
+            request,
+            owner,
+            durationMs: this.#clock().getTime() - startedAt,
+        });
+    }
+    async runLimited(sessionKey, maxInFlight, run) {
+        const limiter = this.#parallelLimiters.get(sessionKey) ?? { active: 0, waiting: [] };
+        this.#parallelLimiters.set(sessionKey, limiter);
+        if (limiter.active >= maxInFlight) {
+            await new Promise((resolve) => limiter.waiting.push(resolve));
+        }
+        limiter.active += 1;
+        try {
+            return await run();
+        }
+        finally {
+            limiter.active -= 1;
+            limiter.waiting.shift()?.();
+            if (limiter.active === 0 && limiter.waiting.length === 0) {
+                this.#parallelLimiters.delete(sessionKey);
+            }
+        }
+    }
+    schedule(sessionKey, run) {
+        const concurrency = this.#adapter.policy.concurrency;
+        if (concurrency.mode === "serialize")
+            return this.#pool.runExclusive(sessionKey, run);
+        if (concurrency.maxInFlight === undefined)
+            return run();
+        return this.runLimited(sessionKey, concurrency.maxInFlight, run);
+    }
+}
+function validateAdapterConfiguration(options) {
+    const adapter = options.adapter;
+    if (!adapter.policy?.concurrency || !adapter.policy.reconnect) {
+        throw new Error(`Stateful provider adapter "${adapter.providerId}" requires concurrency and reconnect policies.`);
+    }
+    const concurrency = adapter.policy.concurrency;
+    if (concurrency.mode !== "serialize" && concurrency.mode !== "parallel") {
+        throw new Error('Stateful concurrency policy mode must be "serialize" or "parallel".');
+    }
+    if (concurrency.mode === "serialize" && "maxInFlight" in concurrency) {
+        throw new Error("Stateful serialize concurrency must not declare maxInFlight.");
+    }
+    if (concurrency.mode === "parallel" &&
+        concurrency.maxInFlight !== undefined &&
+        (!Number.isInteger(concurrency.maxInFlight) || concurrency.maxInFlight <= 0)) {
+        throw new Error("Stateful parallel concurrency maxInFlight must be a positive integer.");
+    }
+    if (!["resume", "recreate", "unsupported"].includes(adapter.policy.reconnect)) {
+        throw new Error('Stateful reconnect policy must be "resume", "recreate", or "unsupported".');
+    }
+    if (Boolean(adapter.snapshot) !== Boolean(options.checkpointStore)) {
+        throw new Error(`Stateful provider adapter "${adapter.providerId}" snapshot and session-manager checkpointStore must be configured together.`);
+    }
+    if (Boolean(adapter.subscribe) !== Boolean(options.eventPublisher)) {
+        throw new Error(`Stateful provider adapter "${adapter.providerId}" subscribe and session-manager eventPublisher must be configured together.`);
+    }
+}
+function managedSessionIdentity(owner, request) {
+    return {
+        connectionId: request.connectionId,
+        serviceAccountId: request.serviceAccountId,
+        ownerPodId: owner.ownerPodId,
+        ownerEndpoint: owner.ownerEndpoint,
+        ownerStatus: owner.status,
+    };
+}
+function sessionIdentityKey(sessionKey, generation) {
+    return `${sessionKey}\u001f${generation}`;
+}

package/dist/stateful/stateful-provider-observability.d.ts

@@ -0,0 +1,62 @@
+export declare const STATEFUL_PROVIDER_METRIC_NAMES: readonly ["apifuse_stateful_provider_session_owner_acquire_total", "apifuse_stateful_provider_session_owner_renew_total", "apifuse_stateful_provider_session_owner_release_total", "apifuse_stateful_provider_session_owner_conflict_total", "apifuse_stateful_provider_session_owner_fencing_stale_total", "apifuse_stateful_provider_active_sessions", "apifuse_stateful_provider_lru_evictions_total", "apifuse_stateful_provider_session_invalidations_total", "apifuse_stateful_provider_session_operation_queue_depth", "apifuse_stateful_provider_session_operation_queue_wait_ms", "apifuse_stateful_provider_session_operation_duration_ms", "apifuse_stateful_provider_routing_forward_total", "apifuse_stateful_provider_routing_local_total", "apifuse_stateful_provider_routing_reacquire_total", "apifuse_stateful_provider_routing_deadline_expired_total", "apifuse_stateful_provider_event_append_total", "apifuse_stateful_provider_event_dedupe_total", "apifuse_stateful_provider_event_drop_total", "apifuse_stateful_provider_event_lag_ms", "apifuse_stateful_provider_webhook_enqueue_total", "apifuse_stateful_provider_webhook_fanout_recovered_total", "apifuse_stateful_provider_webhook_delivered_total", "apifuse_stateful_provider_webhook_retry_total", "apifuse_stateful_provider_webhook_dead_letter_total", "apifuse_stateful_provider_webhook_canceled_total", "apifuse_stateful_provider_webhook_replay_total", "apifuse_stateful_provider_webhook_latency_ms", "apifuse_stateful_provider_write_ledger_ambiguous_total", "apifuse_stateful_provider_write_ledger_reconciled_total", "apifuse_stateful_provider_write_ledger_failed_total"];
+export type StatefulProviderMetricName = (typeof STATEFUL_PROVIDER_METRIC_NAMES)[number];
+export declare const STATEFUL_PROVIDER_LOG_FIELDS: readonly ["requestId", "eventId", "deliveryId", "providerId", "connectionId", "serviceAccountId", "operationId", "sessionKeyHash", "ownerPodId", "generation", "leaseExpiresAt", "capacityClass", "queueDepth", "eventType", "subjectKind", "subjectId", "retryCount", "ledgerState", "healthStatus", "redactedErrorCode"];
+export type StatefulProviderLogField = (typeof STATEFUL_PROVIDER_LOG_FIELDS)[number];
+export declare const STATEFUL_PROVIDER_AUTOSCALING_SIGNALS: readonly ["active_sessions", "session_queue_depth", "session_queue_wait_ms", "reconnect_rate", "provider_event_lag_ms", "webhook_outbox_depth", "webhook_due_retry_depth", "memory_pressure", "file_descriptor_pressure", "socket_pressure"];
+export type StatefulProviderAutoscalingSignal = (typeof STATEFUL_PROVIDER_AUTOSCALING_SIGNALS)[number];
+export declare const STATEFUL_PROVIDER_HEALTH_DIMENSIONS: readonly ["registry_connectivity", "owner_lease_freshness", "pool_capacity", "upstream_auth_validity", "push_loop_lag", "event_append_lag", "webhook_backlog"];
+export type StatefulProviderHealthDimension = (typeof STATEFUL_PROVIDER_HEALTH_DIMENSIONS)[number];
+export declare const STATEFUL_PROVIDER_ROLLOUT_STATES: readonly ["disabled", "tenant_allowlist", "connection_allowlist", "shadow", "canary", "production", "rollback"];
+export type StatefulProviderRolloutState = (typeof STATEFUL_PROVIDER_ROLLOUT_STATES)[number];
+export interface StatefulProviderMetricLabelInput {
+    readonly requestId?: string;
+    readonly eventId?: string;
+    readonly deliveryId?: string;
+    readonly providerId?: string;
+    readonly connectionId?: string;
+    readonly serviceAccountId?: string;
+    readonly operationId?: string;
+    readonly sessionKey?: string;
+    readonly sessionKeyHash?: string;
+    readonly ownerPodId?: string;
+    readonly generation?: number | string;
+    readonly leaseExpiresAt?: string;
+    readonly capacityClass?: string;
+    readonly queueDepth?: number | string;
+    readonly eventType?: string;
+    readonly subjectKind?: string;
+    readonly subjectId?: string;
+    readonly retryCount?: number | string;
+    readonly ledgerState?: string;
+    readonly healthStatus?: string;
+    readonly redactedErrorCode?: string;
+}
+export type StatefulProviderMetricLabels = Partial<Record<StatefulProviderLogField, string>>;
+export interface StatefulProviderMetricEmitter {
+    increment(name: StatefulProviderMetricName, labels?: StatefulProviderMetricLabelInput, value?: number): void;
+    gauge(name: StatefulProviderMetricName, labels: StatefulProviderMetricLabelInput, value: number): void;
+    observe(name: StatefulProviderMetricName, labels: StatefulProviderMetricLabelInput, value: number): void;
+}
+export type StatefulProviderRecordedMetric = {
+    readonly kind: "increment" | "gauge" | "observe";
+    readonly name: StatefulProviderMetricName;
+    readonly labels: StatefulProviderMetricLabels;
+    readonly value: number;
+};
+export declare const NOOP_STATEFUL_PROVIDER_METRIC_EMITTER: {
+    increment(): void;
+    gauge(): void;
+    observe(): void;
+};
+export declare class RecordingStatefulProviderMetricEmitter implements StatefulProviderMetricEmitter {
+    readonly metrics: StatefulProviderRecordedMetric[];
+    increment(name: StatefulProviderMetricName, labels?: StatefulProviderMetricLabelInput, value?: number): void;
+    gauge(name: StatefulProviderMetricName, labels: StatefulProviderMetricLabelInput, value: number): void;
+    observe(name: StatefulProviderMetricName, labels: StatefulProviderMetricLabelInput, value: number): void;
+}
+export declare function isStatefulProviderMetricName(value: unknown): value is StatefulProviderMetricName;
+export declare function isStatefulProviderLogField(value: unknown): value is StatefulProviderLogField;
+export declare function isStatefulProviderAutoscalingSignal(value: unknown): value is StatefulProviderAutoscalingSignal;
+export declare function sanitizeSessionKeyForLog(sessionKey: string): string;
+export declare function statefulProviderMetricLabels(input: StatefulProviderMetricLabelInput): StatefulProviderMetricLabels;
+export declare function assertNoRawSessionKeyInLabels(labels: Record<string, string | number | boolean | null | undefined>, rawSessionKey: string): void;