@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.50

package/dist/stateful/provider-events.js

@@ -0,0 +1,289 @@
+import { createHash, randomUUID } from "node:crypto";
+const DEFAULT_MAX_PAYLOAD_BYTES = 256 * 1024;
+const REDACTED_VALUE = "[REDACTED]";
+const CREDENTIAL_KEY_PATTERN = /(?:token|password|secret|credential|cookie|authorization)/i;
+export class ProviderEventValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProviderEventValidationError";
+    }
+}
+export function buildProviderEvent(input) {
+    validatePayload(input.payload, input.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES);
+    const observedAt = input.observedAt ?? input.clock?.().toISOString() ?? new Date().toISOString();
+    const payload = input.shouldRedactPayload === false
+        ? input.payload
+        : redactProviderEventPayload(input.payload, input.redactionPatterns);
+    const event = {
+        eventId: input.eventId ?? buildEventId({ ...input, observedAt }),
+        providerId: input.providerId,
+        eventType: input.eventType,
+        observedAt,
+        payload,
+        session: input.session,
+        ...(input.connectionId ? { connectionId: input.connectionId } : {}),
+        ...(input.serviceAccountId ? { serviceAccountId: input.serviceAccountId } : {}),
+        ...(input.subject ? { subject: input.subject } : {}),
+        ...(input.occurredAt ? { occurredAt: input.occurredAt } : {}),
+        ...(input.providerCursor ? { providerCursor: input.providerCursor } : {}),
+        ...(input.dedupeKey ? { dedupeKey: input.dedupeKey } : {}),
+        ...(input.rawRef ? { rawRef: input.rawRef } : {}),
+    };
+    validateProviderEvent(event, input.maxPayloadBytes);
+    return event;
+}
+export function redactProviderEventPayload(payload, extraPatterns = []) {
+    const cloned = structuredClone(payload);
+    redactValueInPlace(cloned, [CREDENTIAL_KEY_PATTERN, ...extraPatterns]);
+    return cloned;
+}
+export function isStaleProviderEvent(event, currentGeneration) {
+    return event.session.generation < currentGeneration;
+}
+export class InMemoryProviderEventLog {
+    #events = [];
+    #eventIds = new Set();
+    #dedupeKeys = new Set();
+    async append(event) {
+        validateProviderEvent(event);
+        if (this.#eventIds.has(event.eventId)) {
+            return { event, appended: false };
+        }
+        const dedupeTuple = event.dedupeKey ? buildDedupeTuple(event) : undefined;
+        if (dedupeTuple && this.#dedupeKeys.has(dedupeTuple)) {
+            return { event, appended: false };
+        }
+        this.#events.push(event);
+        this.#eventIds.add(event.eventId);
+        if (dedupeTuple)
+            this.#dedupeKeys.add(dedupeTuple);
+        return { event, appended: true };
+    }
+    async get(eventId) {
+        validateRequiredString("eventId", eventId);
+        return this.#events.find((event) => event.eventId === eventId) ?? null;
+    }
+    async list(options = {}) {
+        validateListOptions(options);
+        let events = this.#events;
+        if (options.providerId) {
+            events = events.filter((event) => event.providerId === options.providerId);
+        }
+        if (options.connectionId) {
+            events = events.filter((event) => event.connectionId === options.connectionId);
+        }
+        if (options.eventType) {
+            events = events.filter((event) => event.eventType === options.eventType);
+        }
+        if (options.subjectKind) {
+            events = events.filter((event) => event.subject?.kind === options.subjectKind);
+        }
+        if (options.subjectId) {
+            events = events.filter((event) => event.subject?.id === options.subjectId);
+        }
+        if (options.afterObservedAt) {
+            const afterMs = Date.parse(options.afterObservedAt);
+            events = events.filter((event) => Date.parse(event.observedAt) > afterMs);
+        }
+        return typeof options.limit === "number" ? events.slice(0, options.limit) : [...events];
+    }
+}
+export class ProviderEventEmitter {
+    #log;
+    #defaults;
+    constructor(log, defaults) {
+        validateRequiredString("providerId", defaults.providerId);
+        if (defaults.connectionId !== undefined) {
+            validateRequiredString("connectionId", defaults.connectionId);
+        }
+        if (defaults.serviceAccountId !== undefined) {
+            validateRequiredString("serviceAccountId", defaults.serviceAccountId);
+        }
+        validateSession(defaults.session);
+        this.#log = log;
+        this.#defaults = defaults;
+    }
+    emit(input) {
+        const event = buildProviderEvent({
+            ...input,
+            providerId: input.providerId ?? this.#defaults.providerId,
+            connectionId: input.connectionId ?? this.#defaults.connectionId,
+            serviceAccountId: input.serviceAccountId ?? this.#defaults.serviceAccountId,
+            session: input.session ?? this.#defaults.session,
+            clock: input.clock ?? this.#defaults.clock,
+            idFactory: input.idFactory ?? this.#defaults.idFactory,
+            maxPayloadBytes: input.maxPayloadBytes ?? this.#defaults.maxPayloadBytes,
+            shouldRedactPayload: input.shouldRedactPayload ?? this.#defaults.shouldRedactPayload,
+            redactionPatterns: input.redactionPatterns ?? this.#defaults.redactionPatterns,
+        });
+        return this.#log.append(event);
+    }
+}
+function buildEventId(input) {
+    if (input.dedupeKey) {
+        return deterministicProviderEventId([
+            input.providerId,
+            input.connectionId ?? "",
+            input.eventType,
+            input.dedupeKey,
+        ]);
+    }
+    return (input.idFactory?.() ??
+        deterministicProviderEventId([
+            input.providerId,
+            input.connectionId ?? "",
+            input.eventType,
+            input.subject?.kind ?? "",
+            input.subject?.id ?? "",
+            input.observedAt,
+        ]));
+}
+function deterministicProviderEventId(parts) {
+    return `pevt_${createHash("sha256").update(parts.join("\u001f")).digest("hex")}`;
+}
+function validateProviderEvent(event, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES) {
+    validateRequiredString("eventId", event.eventId);
+    validateRequiredString("providerId", event.providerId);
+    if (event.connectionId !== undefined)
+        validateRequiredString("connectionId", event.connectionId);
+    if (event.serviceAccountId !== undefined) {
+        validateRequiredString("serviceAccountId", event.serviceAccountId);
+    }
+    validateRequiredString("eventType", event.eventType);
+    if (event.subject) {
+        validateRequiredString("subject.kind", event.subject.kind);
+        validateRequiredString("subject.id", event.subject.id);
+    }
+    if (event.occurredAt !== undefined) {
+        validateRequiredString("occurredAt", event.occurredAt);
+        validateTimestamp("occurredAt", event.occurredAt);
+    }
+    validateRequiredString("observedAt", event.observedAt);
+    validateTimestamp("observedAt", event.observedAt);
+    validateSession(event.session);
+    if (event.providerCursor !== undefined) {
+        validateRequiredString("providerCursor", event.providerCursor);
+    }
+    if (event.dedupeKey !== undefined) {
+        validateRequiredString("dedupeKey", event.dedupeKey);
+    }
+    if (event.rawRef !== undefined) {
+        validateRequiredString("rawRef", event.rawRef);
+    }
+    validatePayload(event.payload, maxPayloadBytes);
+}
+function validateSession(session) {
+    validateRequiredString("session.sessionKey", session?.sessionKey);
+    if (!Number.isInteger(session?.generation) || session.generation < 0) {
+        throw new ProviderEventValidationError("ProviderEvent session.generation must be a non-negative integer.");
+    }
+}
+function validateRequiredString(name, value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new ProviderEventValidationError(`ProviderEvent ${name} must be a non-empty string.`);
+    }
+}
+function validateTimestamp(name, value) {
+    if (!Number.isFinite(Date.parse(value))) {
+        throw new ProviderEventValidationError(`ProviderEvent ${name} must be a parseable ISO timestamp string.`);
+    }
+}
+function validatePayload(payload, maxPayloadBytes) {
+    if (typeof maxPayloadBytes !== "number" ||
+        !Number.isFinite(maxPayloadBytes) ||
+        maxPayloadBytes <= 0) {
+        throw new ProviderEventValidationError("ProviderEvent maxPayloadBytes must be a positive finite number.");
+    }
+    if (!isPlainRecord(payload)) {
+        throw new ProviderEventValidationError("ProviderEvent payload must be a JSON-serializable object.");
+    }
+    assertJsonValue(payload, "payload");
+    const encoded = JSON.stringify(payload);
+    if (encoded === undefined) {
+        throw new ProviderEventValidationError("ProviderEvent payload must be JSON-serializable.");
+    }
+    const payloadBytes = Buffer.byteLength(encoded, "utf8");
+    if (payloadBytes > maxPayloadBytes) {
+        throw new ProviderEventValidationError(`ProviderEvent payload exceeds max size of ${maxPayloadBytes} bytes.`);
+    }
+}
+function assertJsonValue(value, path, seen = new WeakSet()) {
+    if (value === null)
+        return;
+    if (typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return;
+        throw new ProviderEventValidationError(`ProviderEvent ${path} must not contain non-finite numbers.`);
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            throw new ProviderEventValidationError(`ProviderEvent ${path} must not contain circular references.`);
+        }
+        seen.add(value);
+        for (const [index, entry] of value.entries()) {
+            assertJsonValue(entry, `${path}[${index}]`, seen);
+        }
+        seen.delete(value);
+        return;
+    }
+    if (isPlainRecord(value)) {
+        if (seen.has(value)) {
+            throw new ProviderEventValidationError(`ProviderEvent ${path} must not contain circular references.`);
+        }
+        seen.add(value);
+        for (const [key, entry] of Object.entries(value)) {
+            assertJsonValue(entry, `${path}.${key}`, seen);
+        }
+        seen.delete(value);
+        return;
+    }
+    throw new ProviderEventValidationError(`ProviderEvent ${path} must be JSON-serializable.`);
+}
+function redactValueInPlace(value, patterns) {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            redactValueInPlace(entry, patterns);
+        return;
+    }
+    if (!isPlainRecord(value))
+        return;
+    for (const [key, entry] of Object.entries(value)) {
+        if (patterns.some((pattern) => matchesPattern(pattern, key)))
+            value[key] = REDACTED_VALUE;
+        else
+            redactValueInPlace(entry, patterns);
+    }
+}
+function isPlainRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+function buildDedupeTuple(event) {
+    return [
+        event.serviceAccountId ?? "",
+        event.providerId,
+        event.connectionId ?? "",
+        event.dedupeKey,
+    ].join("\u001f");
+}
+function matchesPattern(pattern, value) {
+    pattern.lastIndex = 0;
+    const matched = pattern.test(value);
+    pattern.lastIndex = 0;
+    return matched;
+}
+function validateListOptions(options) {
+    if (options.afterObservedAt) {
+        validateTimestamp("afterObservedAt", options.afterObservedAt);
+    }
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit <= 0)) {
+        throw new ProviderEventValidationError("ProviderEvent list limit must be a positive integer.");
+    }
+}
+export function randomProviderEventId() {
+    return `pevt_${randomUUID().replaceAll("-", "")}`;
+}

package/dist/stateful/session-key.d.ts

@@ -0,0 +1,15 @@
+declare const SESSION_KEY_BRAND: unique symbol;
+/** Canonical, opaque identity for a stateful provider session. */
+export type SessionKey = string & {
+    readonly [SESSION_KEY_BRAND]: "SessionKey";
+};
+export interface SessionKeyParts {
+    readonly providerId: string;
+    readonly serviceAccountId: string;
+    readonly connectionId: string;
+    /** Optional extra session axes (e.g. device, mailbox, persona). Defaults to none. */
+    readonly dimensions?: Readonly<Record<string, string>>;
+}
+export declare function buildSessionKey(parts: SessionKeyParts): SessionKey;
+export declare function parseSessionKey(key: string): SessionKeyParts;
+export {};

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;
+}