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

package/src/stateful/provider-events.ts

@@ -0,0 +1,462 @@
+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;
+
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+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 class ProviderEventValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ProviderEventValidationError";
+	}
+}
+
+export function buildProviderEvent<
+	TPayload extends Record<string, unknown> = Record<string, unknown>,
+>(input: BuildProviderEventInput<TPayload>): ProviderEvent<TPayload> {
+	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: ProviderEvent<TPayload> = {
+		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<TPayload>(
+	payload: TPayload,
+	extraPatterns: readonly RegExp[] = [],
+): TPayload {
+	const cloned = structuredClone(payload);
+	redactValueInPlace(cloned, [CREDENTIAL_KEY_PATTERN, ...extraPatterns]);
+	return cloned;
+}
+
+export function isStaleProviderEvent(event: ProviderEvent, currentGeneration: number): boolean {
+	return event.session.generation < currentGeneration;
+}
+
+export class InMemoryProviderEventLog implements ProviderEventLog {
+	readonly #events: ProviderEvent[] = [];
+	readonly #eventIds = new Set<string>();
+	readonly #dedupeKeys = new Set<string>();
+
+	async append(event: ProviderEvent): Promise<ProviderEventAppendResult> {
+		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: string): Promise<ProviderEvent | null> {
+		validateRequiredString("eventId", eventId);
+		return this.#events.find((event) => event.eventId === eventId) ?? null;
+	}
+
+	async list(options: ProviderEventListOptions = {}): Promise<ProviderEvent[]> {
+		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 {
+	readonly #log: ProviderEventLog;
+	readonly #defaults: ProviderEventEmitterDefaults;
+
+	constructor(log: ProviderEventLog, defaults: ProviderEventEmitterDefaults) {
+		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<TPayload extends Record<string, unknown> = Record<string, unknown>>(
+		input: ProviderEventEmitterInput<TPayload>,
+	): Promise<ProviderEventAppendResult> {
+		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<TPayload extends Record<string, unknown>>(
+	input: Omit<BuildProviderEventInput<TPayload>, "eventId"> & {
+		observedAt: string;
+	},
+): string {
+	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: readonly string[]): string {
+	return `pevt_${createHash("sha256").update(parts.join("\u001f")).digest("hex")}`;
+}
+
+function validateProviderEvent(
+	event: ProviderEvent,
+	maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES,
+): void {
+	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: ProviderEventSession): void {
+	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: string, value: unknown): void {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new ProviderEventValidationError(`ProviderEvent ${name} must be a non-empty string.`);
+	}
+}
+
+function validateTimestamp(name: string, value: string): void {
+	if (!Number.isFinite(Date.parse(value))) {
+		throw new ProviderEventValidationError(
+			`ProviderEvent ${name} must be a parseable ISO timestamp string.`,
+		);
+	}
+}
+
+function validatePayload(payload: unknown, maxPayloadBytes: number): void {
+	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: unknown,
+	path: string,
+	seen = new WeakSet<object>(),
+): asserts value is JsonValue {
+	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: unknown, patterns: readonly RegExp[]): void {
+	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: unknown): value is Record<string, unknown> {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		!Array.isArray(value) &&
+		Object.getPrototypeOf(value) === Object.prototype
+	);
+}
+
+function buildDedupeTuple(event: ProviderEvent): string {
+	return [
+		event.serviceAccountId ?? "",
+		event.providerId,
+		event.connectionId ?? "",
+		event.dedupeKey,
+	].join("\u001f");
+}
+
+function matchesPattern(pattern: RegExp, value: string): boolean {
+	pattern.lastIndex = 0;
+	const matched = pattern.test(value);
+	pattern.lastIndex = 0;
+	return matched;
+}
+
+function validateListOptions(options: ProviderEventListOptions): void {
+	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(): string {
+	return `pevt_${randomUUID().replaceAll("-", "")}`;
+}

package/src/stateful/session-key.ts

@@ -0,0 +1,111 @@
+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>>;
+}
+
+const PREFIX = "stateful:v1";
+const REQUIRED_DIMENSIONS = ["providerId", "serviceAccountId", "connectionId"] as const;
+const REQUIRED_DIMENSION_SET = new Set<string>(REQUIRED_DIMENSIONS);
+
+export function buildSessionKey(parts: SessionKeyParts): SessionKey {
+	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: Array<readonly [string, string]> = [
+		["providerId", parts.providerId],
+		["serviceAccountId", parts.serviceAccountId],
+		["connectionId", parts.connectionId],
+		...dimensions,
+	];
+	return `${PREFIX}/${segments
+		.map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`)
+		.join("/")}` as SessionKey;
+}
+
+export function parseSessionKey(key: string): SessionKeyParts {
+	const prefix = `${PREFIX}/`;
+	if (!key.startsWith(prefix)) {
+		throw new Error(`Invalid session key: expected canonical prefix "${PREFIX}".`);
+	}
+
+	const parsed = new Map<string, string>();
+	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: Record<string, string> = {};
+	for (const [name, value] of parsed) {
+		if (!REQUIRED_DIMENSION_SET.has(name)) dimensions[name] = value;
+	}
+	return {
+		providerId: parsed.get("providerId") as string,
+		serviceAccountId: parsed.get("serviceAccountId") as string,
+		connectionId: parsed.get("connectionId") as string,
+		dimensions,
+	};
+}
+
+function validateRequiredPart(value: string, name: string): void {
+	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: string, value: string): void {
+	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: string, label: string): string {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		throw new Error(`Invalid session key: ${label} is not valid URI encoding.`);
+	}
+}

package/src/stateful/stateful-provider-adapter-context.ts

@@ -0,0 +1,59 @@
+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 function makeStatefulProviderSessionContext(
+	providerId: string,
+	owner: SessionOwnerRecord,
+	request: StatefulOperationRequest,
+	signal: AbortSignal,
+): StatefulProviderSessionContext {
+	const ctx: StatefulProviderSessionContext = {
+		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<TSession>(
+	providerId: string,
+	session: ManagedSession<TSession>,
+): StatefulProviderSessionContext {
+	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: StatefulProviderSessionContext,
+	request: StatefulOperationRequest,
+): StatefulProviderSessionContext {
+	return {
+		...ctx,
+		...(request.idempotencyKey ? { idempotencyKey: request.idempotencyKey } : {}),
+		...(request.deadlineAt ? { deadlineAt: request.deadlineAt } : {}),
+	};
+}

package/src/stateful/stateful-provider-adapter-metrics.ts

@@ -0,0 +1,48 @@
+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 function observeStatefulSessionOperationDuration(input: {
+	readonly metricEmitter: StatefulProviderMetricEmitter;
+	readonly request: StatefulOperationRequest;
+	readonly owner: SessionOwnerRecord;
+	readonly durationMs: number;
+}): void {
+	input.metricEmitter.observe(
+		"apifuse_stateful_provider_session_operation_duration_ms",
+		statefulSessionMetricLabels(input.request, input.owner),
+		Math.max(0, input.durationMs),
+	);
+}
+
+export function emitStatefulSessionInvalidatedMetric(input: {
+	readonly metricEmitter: StatefulProviderMetricEmitter;
+	readonly request: StatefulOperationRequest;
+	readonly owner: SessionOwnerRecord;
+	readonly reason: string;
+}): void {
+	input.metricEmitter.increment(
+		"apifuse_stateful_provider_session_invalidations_total",
+		statefulSessionMetricLabels(input.request, input.owner, {
+			redactedErrorCode: input.reason,
+		}),
+	);
+}
+
+function statefulSessionMetricLabels(
+	request: StatefulOperationRequest,
+	owner: SessionOwnerRecord,
+	extra: { readonly redactedErrorCode?: string } = {},
+) {
+	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,
+	};
+}