@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.30

package/src/runtime/state.ts

@@ -1,5 +1,6 @@
-import { providerStateRedisUrlFromEnv } from "../config/loader";
-import { ProviderError } from "../errors";
+import { createHash } from "node:crypto";
+import { providerStateRedisUrlFromEnv } from "../config/loader.js";
+import { ProviderError } from "../errors.js";
 import type {
 	ProviderRuntimeState,
 	ProviderStateNamespace,
@@ -7,20 +8,94 @@ import type {
 	StateNamespaceOptions,
 	StateValue,
 	StateWriteOptions,
-} from "../types";
+} from "../types.js";
 import {
 	createProviderRedisClient,
 	ensureRedisReady,
 	type ProviderRedisClient,
 	withRedisTimeout,
-} from "./redis";
+} 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;
@@ -57,47 +141,50 @@ async function withRequiredRedis<T>(operation: () => Promise<T>): Promise<T> {
 	return await withRedisTimeout(operation, {
 		timeoutMs: DEFAULT_REDIS_TIMEOUT_MS,
 		onTimeout: () => {
-			throw new UnsupportedProviderStateError(
-				"Provider runtime state Redis timed out",
-			);
+			throw new UnsupportedProviderStateError("Provider runtime state Redis timed out");
 		},
 		onError: () => {
-			throw new UnsupportedProviderStateError(
-				"Provider runtime state Redis is unavailable",
-			);
+			throw new UnsupportedProviderStateError("Provider runtime state Redis is unavailable");
 		},
 	});
 }
 
 async function requireRedisReady(redis: ProviderRedisClient): Promise<void> {
 	if (await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS)) return;
-	throw new UnsupportedProviderStateError(
-		"Provider runtime state Redis is unavailable",
-	);
+	throw new UnsupportedProviderStateError("Provider runtime state Redis is unavailable");
+}
+
+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 providerStatePrefix(
 	providerId: string | undefined,
 	namespace: string,
+	scopeDiscriminator: string,
 ): string {
-	return `${REDIS_STATE_PREFIX}:${providerId ?? "default"}:${namespace}`;
+	return `${REDIS_STATE_PREFIX}:${providerId ?? "default"}:${namespace}:${scopeDiscriminator}`;
 }
 
 function providerStateKey(
 	providerId: string | undefined,
 	namespace: string,
+	scopeDiscriminator: string,
 	key: string,
 ): string {
-	return `${providerStatePrefix(providerId, namespace)}:${key}`;
+	return `${providerStatePrefix(providerId, namespace, scopeDiscriminator)}:${key}`;
 }
 
-function publicStateKey(
-	providerId: string | undefined,
-	namespace: string,
-	redisKey: string,
-): string {
-	const prefix = `${providerStatePrefix(providerId, namespace)}:`;
-	return redisKey.startsWith(prefix) ? redisKey.slice(prefix.length) : redisKey;
+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 {
@@ -118,23 +205,27 @@ 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;
 	}
-	const record: Record<string, unknown> = Object.fromEntries(
-		Object.entries(parsed),
-	);
+	const record: Record<string, unknown> = Object.fromEntries(Object.entries(parsed));
 	if (
 		typeof record.version !== "number" ||
 		typeof record.expiresAt !== "string" ||
@@ -154,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,
@@ -170,21 +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 prefix(): string {
-		return `${providerStatePrefix(this.providerId, this.namespaceName)}:`;
+	private statePrefix(): string {
+		return providerStatePrefix(
+			this.providerId,
+			this.namespaceName,
+			this.scopeDiscriminator,
+		);
 	}
 
-	private async activeKeys(): Promise<string[]> {
+	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 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 {
@@ -196,80 +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] : [];
-		});
+	async list<T>(options?: { limit?: number; prefix?: string }): Promise<StateValue<T>[]> {
+		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>> {
+	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(
+		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),
-				"PX",
-				ttlMs,
 			),
 		);
+		if (!Array.isArray(result) || Number(result[0]) !== 1) {
+			throw this.quotaExceeded();
+		}
 		return {
 			key,
 			value,
 			version,
-			expiresAt,
+			expiresAt: timing.expiresAt,
 			createdAt,
 			updatedAt: envelope.updatedAt,
 		};
@@ -293,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();
 		}
-		return { ok: true, value: await this.set(key, value, options) };
+		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: 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(
@@ -313,60 +507,59 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 	): Promise<StateValue<Record<string, unknown>>> {
 		const current = (await this.get<Record<string, unknown>>(key))?.value ?? {};
 		const previous = typeof current[field] === "number" ? current[field] : 0;
-		return await this.set(
-			key,
-			{ ...current, [field]: previous + delta },
-			options,
-		);
+		return await this.set(key, { ...current, [field]: previous + delta }, options);
 	}
 }
 
 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;
 	}
 
-	namespace(
-		name: string,
-		options: StateNamespaceOptions,
-	): ProviderStateNamespace {
+	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,
+			options.scope === "provider" ? PROVIDER_SCOPE_DISCRIMINATOR : this.scopeDiscriminator,
 		);
 	}
 }
 
 export class UnsupportedProviderStateError extends ProviderError {
-	constructor(
-		message = "Provider runtime state is not available in this runtime",
-	) {
+	constructor(message = "Provider runtime state is not available in this runtime") {
 		super(message, { code: "PROVIDER_STATE_UNSUPPORTED" });
 		this.name = "UnsupportedProviderStateError";
 	}
 }
 
 class UnsupportedProviderStateNamespace implements ProviderStateNamespace {
-	async list<T>(_options?: {
-		limit?: number;
-		prefix?: string;
-	}): Promise<StateValue<T>[]> {
+	async list<T>(_options?: { limit?: number; prefix?: string }): Promise<StateValue<T>[]> {
 		throw new UnsupportedProviderStateError();
 	}
 	async get<T>(_key: string): Promise<StateValue<T> | null> {
 		throw new UnsupportedProviderStateError();
 	}
-	async set<T>(
-		_key: string,
-		_value: T,
-		_options?: StateWriteOptions,
-	): Promise<StateValue<T>> {
+	async set<T>(_key: string, _value: T, _options?: StateWriteOptions): Promise<StateValue<T>> {
 		throw new UnsupportedProviderStateError();
 	}
 	async patch<T extends Record<string, unknown>>(
@@ -398,10 +591,11 @@ class UnsupportedProviderStateNamespace implements ProviderStateNamespace {
 }
 
 class UnsupportedProviderRuntimeState implements ProviderRuntimeState {
-	namespace(
-		_name: string,
-		_options: StateNamespaceOptions,
-	): ProviderStateNamespace {
+	forConnection(_connectionId: string | undefined): ProviderRuntimeState {
+		return new UnsupportedProviderRuntimeState();
+	}
+
+	namespace(_name: string, _options: StateNamespaceOptions): ProviderStateNamespace {
 		return new UnsupportedProviderStateNamespace();
 	}
 }
@@ -412,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) {
@@ -420,10 +639,7 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 		}
 	}
 
-	async list<T>(_options?: {
-		limit?: number;
-		prefix?: string;
-	}): Promise<StateValue<T>[]> {
+	async list<T>(_options?: { limit?: number; prefix?: string }): Promise<StateValue<T>[]> {
 		this.pruneExpired();
 		const rows = Array.from(this.values.values()).filter((value) =>
 			_options?.prefix ? value.key.startsWith(_options.prefix) : true,
@@ -436,17 +652,12 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 		return this.values.get(key) ?? null;
 	}
 
-	async set<T>(
-		key: string,
-		value: T,
-		options?: StateWriteOptions,
-	): Promise<StateValue<T>> {
+	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,
-		);
+		const expiresAt = resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl);
 		const row = {
 			key,
 			value,
@@ -470,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> {
@@ -496,17 +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,
+	) {}
+
+	forConnection(connectionId: string | undefined): ProviderRuntimeState {
+		return new MemoryProviderRuntimeState(
+			this.backend,
+			connectionScopeDiscriminator(connectionId),
+		);
+	}
 
-	namespace(
-		name: string,
-		_options: StateNamespaceOptions,
-	): ProviderStateNamespace {
-		const existing = this.namespaces.get(name);
+	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;
 	}
 }
@@ -536,10 +777,7 @@ export function createRedisProviderRuntimeState(
 }
 
 export function createProviderRuntimeStateFromEnv(
-	options: {
-		readonly providerId?: string;
-		readonly allowMemoryFallback?: boolean;
-	} = {},
+	options: { readonly providerId?: string; readonly allowMemoryFallback?: boolean } = {},
 ): ProviderRuntimeState {
 	const redisUrl = providerStateRedisUrlFromEnv();
 	if (redisUrl) {