@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.40

package/src/runtime/state.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { providerStateRedisUrlFromEnv } from "../config/loader.js";
 import { ProviderError } from "../errors.js";
 import type {
@@ -16,11 +17,85 @@ import {
 } from "./redis.js";
 
 const DEFAULT_REDIS_TIMEOUT_MS = 250;
-const REDIS_STATE_PREFIX = "apifuse:provider-state:v1";
+const REDIS_STATE_PREFIX = "apifuse:provider-state:v2";
+const PROVIDER_SCOPE_DISCRIMINATOR = "scope:provider";
+const MISSING_CONNECTION_SCOPE_DISCRIMINATOR = "scope:connection:missing";
+const SET_WITH_QUOTA_SCRIPT = `
+local now = tonumber(ARGV[1])
+local max_entries = tonumber(ARGV[2])
+local expires_at = tonumber(ARGV[3])
+local index_ttl = tonumber(ARGV[4])
+local envelope = ARGV[5]
+
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
+if not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+	return {0, false}
+end
+
+redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
+redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+return {1, envelope}
+`;
+
+const COMPARE_AND_SET_WITH_QUOTA_SCRIPT = `
+local current = redis.call("GET", KEYS[1])
+if current then
+	local ok, decoded = pcall(cjson.decode, current)
+	if ok and type(decoded) == "table" and decoded.deleted == true then
+		current = false
+	end
+end
+
+local now = tonumber(ARGV[2])
+local max_entries = tonumber(ARGV[3])
+local expires_at = tonumber(ARGV[4])
+local index_ttl = tonumber(ARGV[5])
+local envelope = ARGV[6]
+
+local current_version = 0
+local current_decoded = false
+if current then
+	local ok, decoded = pcall(cjson.decode, current)
+	if not ok or type(decoded) ~= "table" or type(decoded.version) ~= "number" then
+		return {-2, current}
+	end
+	current_version = decoded.version
+	current_decoded = decoded
+end
+if current_version ~= tonumber(ARGV[1]) then
+	return {-1, current or false}
+end
+
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
+if not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+	return {0, false}
+end
+
+if current_decoded and type(current_decoded.createdAt) == "string" then
+	local next_decoded = cjson.decode(envelope)
+	next_decoded.createdAt = current_decoded.createdAt
+	envelope = cjson.encode(next_decoded)
+end
+redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
+redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+return {1, envelope}
+`;
+
+const DELETE_WITH_INDEX_SCRIPT = `
+redis.call("SET", KEYS[1], ARGV[1], "PX", ARGV[2])
+redis.call("ZREM", KEYS[2], KEYS[1])
+return 1
+`;
 
 type RedisProviderRuntimeStateOptions = {
 	readonly redisUrl: string;
 	readonly providerId?: string;
+	/** Test seam; production callers use redisUrl-backed client sharing. */
+	readonly __redisClient?: ProviderRedisClient;
 };
 
 type RedisStateEnvelope = {
@@ -31,23 +106,32 @@ type RedisStateEnvelope = {
 	readonly updatedAt: string;
 };
 
+type RedisStateTombstone = {
+	readonly deleted: true;
+};
+
 type RedisBackend = {
 	readonly redis: ProviderRedisClient;
 };
 
 const redisBackends = new Map<string, RedisBackend>();
 
-function getRedisBackend(redisUrl: string): RedisBackend {
+function getRedisBackend(
+	redisUrl: string,
+	injectedRedis?: ProviderRedisClient,
+): RedisBackend {
 	const existing = redisBackends.get(redisUrl);
 	if (existing) return existing;
-	const redis = createProviderRedisClient({
-		redisUrl,
-		timeoutMs: DEFAULT_REDIS_TIMEOUT_MS,
-		onError: () => {
-			// Runtime state operations fail closed at their call sites. Avoid noisy
-			// unhandled Redis errors from background reconnect attempts.
-		},
-	});
+	const redis =
+		injectedRedis ??
+		createProviderRedisClient({
+			redisUrl,
+			timeoutMs: DEFAULT_REDIS_TIMEOUT_MS,
+			onError: () => {
+				// Runtime state operations fail closed at their call sites. Avoid noisy
+				// unhandled Redis errors from background reconnect attempts.
+			},
+		});
 	const backend = { redis };
 	redisBackends.set(redisUrl, backend);
 	return backend;
@@ -70,21 +154,37 @@ async function requireRedisReady(redis: ProviderRedisClient): Promise<void> {
 	throw new UnsupportedProviderStateError("Provider runtime state Redis is unavailable");
 }
 
-function providerStatePrefix(providerId: string | undefined, namespace: string): string {
-	return `${REDIS_STATE_PREFIX}:${providerId ?? "default"}:${namespace}`;
+function connectionScopeDiscriminator(connectionId: string | undefined): string {
+	if (connectionId === undefined) return MISSING_CONNECTION_SCOPE_DISCRIMINATOR;
+	const digest = createHash("sha256").update(connectionId, "utf8").digest("hex");
+	return `scope:connection:sha256:${digest}`;
 }
 
-function providerStateKey(providerId: string | undefined, namespace: string, key: string): string {
-	return `${providerStatePrefix(providerId, namespace)}:${key}`;
+function providerStatePrefix(
+	providerId: string | undefined,
+	namespace: string,
+	scopeDiscriminator: string,
+): string {
+	return `${REDIS_STATE_PREFIX}:${providerId ?? "default"}:${namespace}:${scopeDiscriminator}`;
 }
 
-function publicStateKey(
+function providerStateKey(
 	providerId: string | undefined,
 	namespace: string,
-	redisKey: string,
+	scopeDiscriminator: string,
+	key: string,
 ): string {
-	const prefix = `${providerStatePrefix(providerId, namespace)}:`;
-	return redisKey.startsWith(prefix) ? redisKey.slice(prefix.length) : redisKey;
+	return `${providerStatePrefix(providerId, namespace, scopeDiscriminator)}:${key}`;
+}
+
+function publicStateKey(redisKey: string, prefixes: readonly string[]): string {
+	for (const prefix of prefixes) {
+		const prefixWithSeparator = `${prefix}:`;
+		if (redisKey.startsWith(prefixWithSeparator)) {
+			return redisKey.slice(prefixWithSeparator.length);
+		}
+	}
+	return redisKey;
 }
 
 function parseStateDurationMs(ttl: StateWriteOptions["ttl"]): number {
@@ -105,17 +205,23 @@ function parseStateDurationMs(ttl: StateWriteOptions["ttl"]): number {
 	return Math.max(1, amount * multiplier);
 }
 
-function resolveExpiresAt(ttl: StateWriteOptions["ttl"]): string {
-	return new Date(Date.now() + parseStateDurationMs(ttl)).toISOString();
-}
-
 function envelopeFromJson(
 	key: string,
 	raw: string | null,
 	// biome-ignore lint/suspicious/noExplicitAny: state envelopes deserialize caller-owned generic values.
 ): StateValue<any> | null {
 	if (!raw) return null;
-	const parsed: unknown = JSON.parse(raw);
+	// A corrupt/undecodable persisted envelope must be treated as absent rather
+	// than throwing a raw JSON.parse SyntaxError: an uncaught SyntaxError escapes
+	// the provider error taxonomy, is masked as internal_error 500, and is then
+	// retried by the hub (2026-07-22 catchtable reserve RCA, candidate A). Returning
+	// null also keeps list() from aborting the whole scan on a single bad entry.
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
 	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
 		return null;
 	}
@@ -139,6 +245,21 @@ function envelopeFromJson(
 	};
 }
 
+function isStateTombstone(raw: string | null): boolean {
+	if (!raw) return false;
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		return (
+			parsed !== null &&
+			typeof parsed === "object" &&
+			!Array.isArray(parsed) &&
+			(parsed as { deleted?: unknown }).deleted === true
+		);
+	} catch {
+		return false;
+	}
+}
+
 function redisEnvelope(
 	value: unknown,
 	version: number,
@@ -155,19 +276,60 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		private readonly providerId: string | undefined,
 		private readonly namespaceName: string,
 		private readonly options: StateNamespaceOptions,
+		private readonly scopeDiscriminator: string,
 	) {}
 
 	private redisKey(key: string): string {
-		return providerStateKey(this.providerId, this.namespaceName, key);
+		return providerStateKey(
+			this.providerId,
+			this.namespaceName,
+			this.scopeDiscriminator,
+			key,
+		);
+	}
+
+	private statePrefix(): string {
+		return providerStatePrefix(
+			this.providerId,
+			this.namespaceName,
+			this.scopeDiscriminator,
+		);
 	}
 
-	private prefix(): string {
-		return `${providerStatePrefix(this.providerId, this.namespaceName)}:`;
+	private indexKey(): string {
+		// Keep bookkeeping outside the caller-owned keyspace. A provider may use
+		// any state key (including "__index"), so a suffix inside the namespace
+		// could turn the ZSET into a string and break every subsequent write.
+		const namespaceIdentity = Buffer.from(
+			providerStatePrefix(
+				this.providerId,
+				this.namespaceName,
+				this.scopeDiscriminator,
+			),
+			"utf8",
+		).toString("base64url");
+		return `${REDIS_STATE_PREFIX}:index:${namespaceIdentity}`;
 	}
 
-	private async activeKeys(): Promise<string[]> {
+	private async indexedKeys(limit: number): Promise<string[]> {
 		await requireRedisReady(this.backend.redis);
-		return await withRequiredRedis(() => this.backend.redis.keys(`${this.prefix()}*`));
+		const now = Date.now();
+		return await withRequiredRedis(async () => {
+			await this.backend.redis.zremrangebyscore(this.indexKey(), "-inf", now);
+			return await this.backend.redis.zrangebyscore(
+				this.indexKey(),
+				now + 1,
+				"+inf",
+				"LIMIT",
+				0,
+				limit,
+			);
+		});
+	}
+
+	private async readRaw(key: string): Promise<string | null> {
+		await requireRedisReady(this.backend.redis);
+		return await withRequiredRedis(() => this.backend.redis.get(this.redisKey(key)));
 	}
 
 	private enforceValueSize(value: unknown): void {
@@ -179,57 +341,86 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		}
 	}
 
-	private async enforceMaxEntries(key: string): Promise<void> {
-		const keys = await this.activeKeys();
-		const redisKey = this.redisKey(key);
-		const otherKeys = keys.filter((candidate) => candidate !== redisKey);
-		if (otherKeys.length >= this.options.maxEntries) {
+	private quotaExceeded(): UnsupportedProviderStateError {
+		return new UnsupportedProviderStateError(
+			`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`,
+		);
+	}
+
+	private writeTiming(ttl: StateWriteOptions["ttl"]): {
+		expiresAt: string;
+		expiresAtMs: number;
+		indexTtlMs: number;
+	} {
+		const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+		const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+		if (ttlMs > maxTtlMs) {
 			throw new UnsupportedProviderStateError(
-				`Provider runtime state namespace quota exceeded (${otherKeys.length + 1} > ${this.options.maxEntries})`,
+				`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`,
 			);
 		}
+		const expiresAtMs = Date.now() + ttlMs;
+		return {
+			expiresAt: new Date(expiresAtMs).toISOString(),
+			expiresAtMs,
+			indexTtlMs: maxTtlMs,
+		};
 	}
 
 	async list<T>(options?: { limit?: number; prefix?: string }): Promise<StateValue<T>[]> {
-		const keys = (await this.activeKeys()).filter((key) => {
-			const publicKey = publicStateKey(this.providerId, this.namespaceName, key);
-			return options?.prefix ? publicKey.startsWith(options.prefix) : true;
-		});
-		const limited = keys.slice(0, Math.max(0, options?.limit ?? keys.length));
-		if (limited.length === 0) return [];
-		const values = await withRequiredRedis(() => this.backend.redis.mget(limited));
-		return values.flatMap((raw, index) => {
-			const key = limited[index];
-			if (!key) return [];
-			const value = envelopeFromJson(publicStateKey(this.providerId, this.namespaceName, key), raw);
-			return value ? [value] : [];
-		});
+		const requestedLimit = Math.max(0, options?.limit ?? this.options.maxEntries);
+		if (requestedLimit === 0) return [];
+		const keys = await this.indexedKeys(this.options.maxEntries);
+		if (keys.length === 0) return [];
+		const values = await withRequiredRedis(() => this.backend.redis.mget(keys));
+		const rows: StateValue<T>[] = [];
+		for (const [index, raw] of values.entries()) {
+			const redisKey = keys[index];
+			if (!redisKey) continue;
+			const publicKey = publicStateKey(redisKey, [this.statePrefix()]);
+			if (options?.prefix && !publicKey.startsWith(options.prefix)) continue;
+			const value = envelopeFromJson(publicKey, raw);
+			if (!value) continue;
+			rows.push(value);
+		}
+		return rows.slice(0, requestedLimit);
 	}
 
 	async get<T>(key: string): Promise<StateValue<T> | null> {
-		await requireRedisReady(this.backend.redis);
-		const raw = await withRequiredRedis(() => this.backend.redis.get(this.redisKey(key)));
+		const raw = await this.readRaw(key);
+		if (isStateTombstone(raw)) return null;
 		return envelopeFromJson(key, raw);
 	}
 
 	async set<T>(key: string, value: T, options?: StateWriteOptions): Promise<StateValue<T>> {
 		this.enforceValueSize(value);
-		await this.enforceMaxEntries(key);
 		const current = await this.get<T>(key);
 		const createdAt = current?.createdAt ?? new Date().toISOString();
 		const version = (current?.version ?? 0) + 1;
-		const ttl = options?.ttl ?? this.options.defaultTtl;
-		const ttlMs = parseStateDurationMs(ttl);
-		const expiresAt = resolveExpiresAt(ttl);
-		const envelope = redisEnvelope(value, version, createdAt, expiresAt);
-		await withRequiredRedis(() =>
-			this.backend.redis.set(this.redisKey(key), JSON.stringify(envelope), "PX", ttlMs),
+		const timing = this.writeTiming(options?.ttl);
+		const envelope = redisEnvelope(value, version, createdAt, timing.expiresAt);
+		await requireRedisReady(this.backend.redis);
+		const result = await withRequiredRedis(() =>
+			this.backend.redis.eval(
+				SET_WITH_QUOTA_SCRIPT,
+				2,
+				this.redisKey(key),
+				this.indexKey(),
+				String(Date.now()),
+				String(this.options.maxEntries),
+				String(timing.expiresAtMs),
+				String(timing.indexTtlMs),
+				JSON.stringify(envelope),
+			),
 		);
+		if (!Array.isArray(result) || Number(result[0]) !== 1) {
+			throw this.quotaExceeded();
+		}
 		return {
 			key,
 			value,
 			version,
-			expiresAt,
+			expiresAt: timing.expiresAt,
 			createdAt,
 			updatedAt: envelope.updatedAt,
 		};
@@ -253,16 +444,59 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		options?: StateWriteOptions,
 	): Promise<StateCasResult<T>> {
 		this.enforceValueSize(value);
-		const current = await this.get<T>(key);
-		if ((current?.version ?? 0) !== expectedVersion) {
-			return { ok: false, current };
+		const createdAt = new Date().toISOString();
+		const timing = this.writeTiming(options?.ttl);
+		const envelope = redisEnvelope(
+			value,
+			expectedVersion + 1,
+			createdAt,
+			timing.expiresAt,
+		);
+		await requireRedisReady(this.backend.redis);
+		const result = await withRequiredRedis(() =>
+			this.backend.redis.eval(
+				COMPARE_AND_SET_WITH_QUOTA_SCRIPT,
+				2,
+				this.redisKey(key),
+				this.indexKey(),
+				String(expectedVersion),
+				String(Date.now()),
+				String(this.options.maxEntries),
+				String(timing.expiresAtMs),
+				String(timing.indexTtlMs),
+				JSON.stringify(envelope),
+			),
+		);
+		if (Array.isArray(result) && Number(result[0]) === 0) {
+			throw this.quotaExceeded();
+		}
+		if (!Array.isArray(result) || Number(result[0]) !== 1) {
+			const rawCurrent = Array.isArray(result) && typeof result[1] === "string" ? result[1] : null;
+			return { ok: false, current: envelopeFromJson(key, rawCurrent) };
+		}
+		const rawWritten = typeof result[1] === "string" ? result[1] : null;
+		const written = envelopeFromJson(key, rawWritten) as StateValue<T> | null;
+		if (!written) {
+			throw new UnsupportedProviderStateError(
+				"Provider runtime state CAS returned an invalid value",
+			);
 		}
-		return { ok: true, value: await this.set(key, value, options) };
+		return { ok: true, value: written };
 	}
 
 	async delete(key: string): Promise<void> {
 		await requireRedisReady(this.backend.redis);
-		await withRequiredRedis(() => this.backend.redis.del(this.redisKey(key)));
+		const tombstone = JSON.stringify({ deleted: true } satisfies RedisStateTombstone);
+		await withRequiredRedis(() =>
+			this.backend.redis.eval(
+				DELETE_WITH_INDEX_SCRIPT,
+				2,
+				this.redisKey(key),
+				this.indexKey(),
+				tombstone,
+				String(parseStateDurationMs(this.options.maxTtl)),
+			),
+		);
 	}
 
 	async increment(
@@ -280,14 +514,34 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 class RedisProviderRuntimeState implements ProviderRuntimeState {
 	readonly backend: RedisBackend;
 	readonly providerId?: string;
+	readonly redisUrl: string;
+	readonly scopeDiscriminator: string;
 
-	constructor(options: RedisProviderRuntimeStateOptions) {
-		this.backend = getRedisBackend(options.redisUrl);
+	constructor(
+		options: RedisProviderRuntimeStateOptions,
+		scopeDiscriminator = MISSING_CONNECTION_SCOPE_DISCRIMINATOR,
+	) {
+		this.backend = getRedisBackend(options.redisUrl, options.__redisClient);
 		this.providerId = options.providerId;
+		this.redisUrl = options.redisUrl;
+		this.scopeDiscriminator = scopeDiscriminator;
+	}
+
+	forConnection(connectionId: string | undefined): ProviderRuntimeState {
+		return new RedisProviderRuntimeState(
+			{ redisUrl: this.redisUrl, providerId: this.providerId },
+			connectionScopeDiscriminator(connectionId),
+		);
 	}
 
 	namespace(name: string, options: StateNamespaceOptions): ProviderStateNamespace {
-		return new RedisProviderStateNamespace(this.backend, this.providerId, name, options);
+		return new RedisProviderStateNamespace(
+			this.backend,
+			this.providerId,
+			name,
+			options,
+			options.scope === "provider" ? PROVIDER_SCOPE_DISCRIMINATOR : this.scopeDiscriminator,
+		);
 	}
 }
 
@@ -337,6 +591,10 @@ class UnsupportedProviderStateNamespace implements ProviderStateNamespace {
 }
 
 class UnsupportedProviderRuntimeState implements ProviderRuntimeState {
+	forConnection(_connectionId: string | undefined): ProviderRuntimeState {
+		return new UnsupportedProviderRuntimeState();
+	}
+
 	namespace(_name: string, _options: StateNamespaceOptions): ProviderStateNamespace {
 		return new UnsupportedProviderStateNamespace();
 	}
@@ -348,6 +606,31 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 
 	constructor(private readonly options: StateNamespaceOptions) {}
 
+	private enforceValueSize(value: unknown): void {
+		const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
+		if (bytes > this.options.maxValueBytes) {
+			throw new UnsupportedProviderStateError(
+				`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`,
+			);
+		}
+	}
+
+	private enforceWritePolicy(key: string, value: unknown, ttl: StateWriteOptions["ttl"]): void {
+		this.enforceValueSize(value);
+		const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+		const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+		if (ttlMs > maxTtlMs) {
+			throw new UnsupportedProviderStateError(
+				`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`,
+			);
+		}
+		if (!this.values.has(key) && this.values.size >= this.options.maxEntries) {
+			throw new UnsupportedProviderStateError(
+				`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`,
+			);
+		}
+	}
+
 	private pruneExpired(nowMs = Date.now()): void {
 		for (const [key, row] of this.values.entries()) {
 			if (row.expiresAt && Date.parse(row.expiresAt) <= nowMs) {
@@ -371,6 +654,7 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 
 	async set<T>(key: string, value: T, options?: StateWriteOptions): Promise<StateValue<T>> {
 		this.pruneExpired();
+		this.enforceWritePolicy(key, value, options?.ttl);
 		const now = new Date().toISOString();
 		const current = this.values.get(key);
 		const expiresAt = resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl);
@@ -397,14 +681,30 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 	}
 
 	async compareAndSet<T>(
-		_key: string,
-		_expectedVersion: number,
-		_value: T,
-		_options?: StateWriteOptions,
+		key: string,
+		expectedVersion: number,
+		value: T,
+		options?: StateWriteOptions,
 	): Promise<StateCasResult<T>> {
-		throw new UnsupportedProviderStateError(
-			"In-memory provider runtime state does not support compareAndSet",
-		);
+		this.pruneExpired();
+		const current = this.values.get(key) as StateValue<T> | undefined;
+		if ((current?.version ?? 0) !== expectedVersion) {
+			return { ok: false, current: current ?? null };
+		}
+		this.enforceWritePolicy(key, value, options?.ttl);
+		const now = new Date().toISOString();
+		const stored = {
+			key,
+			value,
+			version: expectedVersion + 1,
+			expiresAt: resolveMemoryStateExpiresAt(
+				options?.ttl ?? this.options.defaultTtl,
+			),
+			createdAt: current?.createdAt ?? now,
+			updatedAt: now,
+		} satisfies StateValue<T>;
+		this.values.set(key, stored);
+		return { ok: true, value: stored };
 	}
 
 	async delete(key: string): Promise<void> {
@@ -423,14 +723,31 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 	}
 }
 
+type MemoryProviderStateBackend = {
+	readonly namespaces: Map<string, MemoryProviderStateNamespace>;
+};
+
 class MemoryProviderRuntimeState implements ProviderRuntimeState {
-	readonly namespaces = new Map<string, MemoryProviderStateNamespace>();
+	constructor(
+		private readonly backend: MemoryProviderStateBackend = { namespaces: new Map() },
+		private readonly scopeDiscriminator = MISSING_CONNECTION_SCOPE_DISCRIMINATOR,
+	) {}
 
-	namespace(name: string, _options: StateNamespaceOptions): ProviderStateNamespace {
-		const existing = this.namespaces.get(name);
+	forConnection(connectionId: string | undefined): ProviderRuntimeState {
+		return new MemoryProviderRuntimeState(
+			this.backend,
+			connectionScopeDiscriminator(connectionId),
+		);
+	}
+
+	namespace(name: string, options: StateNamespaceOptions): ProviderStateNamespace {
+		const scopeDiscriminator =
+			options.scope === "provider" ? PROVIDER_SCOPE_DISCRIMINATOR : this.scopeDiscriminator;
+		const namespaceIdentity = `${scopeDiscriminator}\0${name}`;
+		const existing = this.backend.namespaces.get(namespaceIdentity);
 		if (existing) return existing;
-		const created = new MemoryProviderStateNamespace(_options);
-		this.namespaces.set(name, created);
+		const created = new MemoryProviderStateNamespace(options);
+		this.backend.namespaces.set(namespaceIdentity, created);
 		return created;
 	}
 }