@apifuse/provider-sdk 2.2.0-beta.10 → 2.2.0-beta.12

package/dist/stateful/provider-event-pipeline-metrics.js

@@ -0,0 +1,48 @@
+export const PROVIDER_EVENT_METRIC_NAMES = [
+    "apifuse_stateful_provider_event_append_total",
+    "apifuse_stateful_provider_event_dedupe_total",
+    "apifuse_stateful_provider_event_drop_total",
+    "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_latency_ms",
+];
+export const NOOP_PROVIDER_EVENT_METRIC_EMITTER = {
+    increment() { },
+    observe() { },
+};
+export function providerEventMetricLabels(event) {
+    return {
+        eventId: event.eventId,
+        providerId: event.providerId,
+        connectionId: event.connectionId,
+        serviceAccountId: event.serviceAccountId,
+        eventType: event.eventType,
+        subjectKind: event.subject?.kind,
+        subjectId: event.subject?.id,
+        sessionKey: event.session.sessionKey,
+        generation: event.session.generation,
+    };
+}
+export function providerWebhookDeliveryMetricLabels(delivery) {
+    return { deliveryId: delivery.deliveryId };
+}
+export function emitProviderWebhookDeliveryFailureMetric(metricEmitter, delivery, status) {
+    if (status === "retrying") {
+        metricEmitter.increment("apifuse_stateful_provider_webhook_retry_total", providerWebhookDeliveryMetricLabels(delivery));
+        return;
+    }
+    if (status === "dead_lettered") {
+        metricEmitter.increment("apifuse_stateful_provider_webhook_dead_letter_total", providerWebhookDeliveryMetricLabels(delivery));
+    }
+}
+export function providerWebhookDeliveryLatencyMs(delivery, now) {
+    const startedAt = Date.parse(delivery.lastAttemptAt ?? delivery.nextAttemptAt);
+    const completedAt = Date.parse(now);
+    if (!Number.isFinite(startedAt) || !Number.isFinite(completedAt))
+        return 0;
+    return Math.max(0, completedAt - startedAt);
+}

package/dist/stateful/provider-event-pipeline.d.ts

@@ -0,0 +1,50 @@
+import type { ProviderEventMetricEmitter } from "./provider-event-pipeline-metrics.js";
+import type { ProviderEvent } from "./provider-events.js";
+import type { SessionKey } from "./session-key.js";
+export type { ProviderEventMetricEmitter } from "./provider-event-pipeline-metrics.js";
+export type ProviderEventOwnerFence = {
+    readonly ownerPodId: string;
+    readonly ownerEndpoint: string;
+    readonly sessionKey: SessionKey;
+    readonly generation: number;
+};
+export type ProviderEventPublishOptions = {
+    /** Required ownership proof forwarded to the durable platform write boundary. */
+    readonly ownerFence: ProviderEventOwnerFence;
+    /** Overrides the transport idempotency key; defaults to the event id. */
+    readonly idempotencyKey?: string;
+};
+export type PublishAck = {
+    /** Whether this event was accepted into the pod-local retry buffer. */
+    readonly accepted: boolean;
+    /** Number of events currently held in the pod-local retry buffer. */
+    readonly queued: number;
+};
+/** Fire-and-forget publication from a provider pod into the platform ingest boundary. */
+export interface ProviderEventPublisher {
+    publish(event: ProviderEvent, options: ProviderEventPublishOptions): PublishAck;
+}
+export type AppendProviderEventAndEnqueueWebhooksResult = {
+    readonly appended: boolean;
+    readonly appendedCount: number;
+    readonly matchedSubscriptionCount: number;
+    readonly enqueuedCount: number;
+    readonly recoveredFanoutCount?: number;
+    readonly fenced?: boolean;
+};
+export type ProviderEventPipelineAppendOptions = {
+    readonly now?: string;
+    readonly idFactory?: () => string;
+    readonly metricEmitter?: ProviderEventMetricEmitter;
+    readonly beforeAppend?: () => Promise<boolean> | boolean;
+    readonly ownerFence?: ProviderEventOwnerFence;
+};
+/**
+ * Durable append-and-fanout contract implemented on the platform side.
+ *
+ * Provider-pod code must depend on ProviderEventPublisher, never ProviderEventPipeline: a pod-local
+ * publisher cannot truthfully report a durable append or downstream webhook fanout.
+ */
+export interface ProviderEventPipeline {
+    appendAndFanout(event: ProviderEvent, options?: ProviderEventPipelineAppendOptions): Promise<AppendProviderEventAndEnqueueWebhooksResult>;
+}

package/dist/stateful/provider-event-pipeline.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,101 @@
+export type ProviderEventSubject = {
+    /** Provider-defined resource category, for example `message`, `mailbox`, or `browser-context`. */
+    kind: string;
+    id: string;
+};
+export type ProviderEventSession = {
+    /** Canonical logical session identity shared by every stateful provider. */
+    sessionKey: string;
+    /** Ownership generation shared by every stateful provider for stale-event fencing. */
+    generation: number;
+};
+export interface ProviderEvent<TPayload = Record<string, unknown>> {
+    /** Universal stable identity used for transport retries and deduplication. */
+    eventId: string;
+    /** Universal provider namespace needed to route and interpret the event. */
+    providerId: string;
+    /** Optional because mailbox/browser protocols may not expose an API connection identity. */
+    connectionId?: string;
+    /** Optional because not every provider session maps to a platform service account. */
+    serviceAccountId?: string;
+    /** Universal provider-defined event classification. */
+    eventType: string;
+    /** Optional for protocol-level events without a single resource subject. */
+    subject?: ProviderEventSubject;
+    /** Optional when the upstream protocol does not provide an occurrence timestamp. */
+    occurredAt?: string;
+    /** Universal SDK observation time used for ordering and lag measurement. */
+    observedAt: string;
+    /** Universal JSON data envelope; protocols without data use an empty object. */
+    payload: TPayload;
+    /** Universal stateful ownership fence for rejecting events from stale sessions. */
+    session: ProviderEventSession;
+    providerCursor?: string;
+    dedupeKey?: string;
+    rawRef?: string;
+}
+export type ProviderEventIdFactory = () => string;
+export type ProviderEventClock = () => Date;
+export type BuildProviderEventInput<TPayload extends Record<string, unknown> = Record<string, unknown>> = Omit<ProviderEvent<TPayload>, "eventId" | "observedAt"> & {
+    eventId?: string;
+    observedAt?: string;
+    clock?: ProviderEventClock;
+    idFactory?: ProviderEventIdFactory;
+    maxPayloadBytes?: number;
+    shouldRedactPayload?: boolean;
+    /** Provider-specific credential key patterns added to the conservative SDK defaults. */
+    redactionPatterns?: readonly RegExp[];
+};
+export type ProviderEventListOptions = {
+    providerId?: string;
+    connectionId?: string;
+    eventType?: string;
+    subjectKind?: string;
+    subjectId?: string;
+    afterObservedAt?: string;
+    limit?: number;
+};
+export type ProviderEventAppendResult = {
+    event: ProviderEvent;
+    appended: boolean;
+};
+export interface ProviderEventLog {
+    append(event: ProviderEvent): Promise<ProviderEventAppendResult>;
+    get(eventId: string): Promise<ProviderEvent | null>;
+    list(options?: ProviderEventListOptions): Promise<ProviderEvent[]>;
+}
+export type ProviderEventEmitterDefaults = {
+    providerId: string;
+    connectionId?: string;
+    serviceAccountId?: string;
+    session: ProviderEventSession;
+    clock?: ProviderEventClock;
+    idFactory?: ProviderEventIdFactory;
+    maxPayloadBytes?: number;
+    shouldRedactPayload?: boolean;
+    redactionPatterns?: readonly RegExp[];
+};
+export type ProviderEventEmitterInput<TPayload extends Record<string, unknown> = Record<string, unknown>> = Omit<BuildProviderEventInput<TPayload>, "providerId" | "connectionId" | "serviceAccountId" | "session"> & {
+    providerId?: string;
+    connectionId?: string;
+    serviceAccountId?: string;
+    session?: ProviderEventSession;
+};
+export declare class ProviderEventValidationError extends Error {
+    constructor(message: string);
+}
+export declare function buildProviderEvent<TPayload extends Record<string, unknown> = Record<string, unknown>>(input: BuildProviderEventInput<TPayload>): ProviderEvent<TPayload>;
+export declare function redactProviderEventPayload<TPayload>(payload: TPayload, extraPatterns?: readonly RegExp[]): TPayload;
+export declare function isStaleProviderEvent(event: ProviderEvent, currentGeneration: number): boolean;
+export declare class InMemoryProviderEventLog implements ProviderEventLog {
+    #private;
+    append(event: ProviderEvent): Promise<ProviderEventAppendResult>;
+    get(eventId: string): Promise<ProviderEvent | null>;
+    list(options?: ProviderEventListOptions): Promise<ProviderEvent[]>;
+}
+export declare class ProviderEventEmitter {
+    #private;
+    constructor(log: ProviderEventLog, defaults: ProviderEventEmitterDefaults);
+    emit<TPayload extends Record<string, unknown> = Record<string, unknown>>(input: ProviderEventEmitterInput<TPayload>): Promise<ProviderEventAppendResult>;
+}
+export declare function randomProviderEventId(): string;

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;