@apifuse/provider-sdk 2.2.0-beta.23 → 2.2.0-beta.24

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,9 +17,10 @@ import {
 } from "./redis.js";
 
 const DEFAULT_REDIS_TIMEOUT_MS = 250;
-const REDIS_STATE_PREFIX = "apifuse:provider-state:v1";
-const LEGACY_INDEX_SCAN_COUNT = 256;
-const LEGACY_INDEX_SCAN_MAX_PAGES = 8;
+const REDIS_STATE_PREFIX = "apifuse:provider-state:v2";
+const LEGACY_REDIS_STATE_PREFIX = "apifuse:provider-state:v1";
+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])
@@ -27,87 +29,164 @@ local index_ttl = tonumber(ARGV[4])
 local envelope = ARGV[5]
 
 redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
-local exists = redis.call("EXISTS", KEYS[1])
+redis.call("ZREM", KEYS[2], KEYS[3])
 local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
-if exists == 0 and not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+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)
+if ARGV[6] == "1" then
+	redis.call("SET", KEYS[3], ARGV[7], "PX", index_ttl)
+end
 return {1, envelope}
 `;
 
 const COMPARE_AND_SET_WITH_QUOTA_SCRIPT = `
 local current = redis.call("GET", KEYS[1])
+local scoped_present = current and true or false
+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 allow_legacy_claim = ARGV[7] == "1"
+local legacy_tombstone = ARGV[8]
+
+if not scoped_present then
+	local legacy = redis.call("GET", KEYS[3])
+	if legacy then
+		local ok, decoded = pcall(cjson.decode, legacy)
+		if ok and type(decoded) == "table" and decoded.deleted == true then
+			legacy = false
+		end
+	end
+	if legacy and not allow_legacy_claim then
+		return {-1, false}
+	end
+	if legacy then
+		local legacy_ttl = redis.call("PTTL", KEYS[3])
+		if legacy_ttl == -1 then
+			legacy_ttl = index_ttl
+		elseif legacy_ttl < 1 then
+			legacy_ttl = 1
+		end
+		if legacy_ttl > 0 then
+			redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+			redis.call("ZREM", KEYS[2], KEYS[3])
+			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], legacy, "PX", legacy_ttl)
+			redis.call("ZADD", KEYS[2], now + legacy_ttl, KEYS[1])
+			redis.call("PEXPIRE", KEYS[2], index_ttl)
+			redis.call("SET", KEYS[3], legacy_tombstone, "PX", index_ttl)
+			current = legacy
+		end
+	end
+end
+
 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
 
-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]
 redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
-local exists = current and 1 or 0
+redis.call("ZREM", KEYS[2], KEYS[3])
 local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
-if exists == 0 and not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+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)
+if allow_legacy_claim then
+	redis.call("SET", KEYS[3], legacy_tombstone, "PX", index_ttl)
+end
 return {1, envelope}
 `;
 
 const DELETE_WITH_INDEX_SCRIPT = `
-redis.call("DEL", KEYS[1])
-redis.call("ZREM", KEYS[2], KEYS[1])
+redis.call("SET", KEYS[1], ARGV[1], "PX", ARGV[2])
+if ARGV[3] == "1" then
+	redis.call("SET", KEYS[3], ARGV[1], "PX", ARGV[2])
+end
+redis.call("ZREM", KEYS[2], KEYS[1], KEYS[3])
 return 1
 `;
 
-// Older SDKs wrote only the value key. Every operation that depends on the
-// namespace index advances a bounded SCAN cursor and lazily imports active
-// legacy envelopes into the new ZSET. The cursor is
-// deliberately cyclic rather than permanently "complete": an old pod may
-// still write an unindexed key during a rolling deploy. Each list/write call
-// does a fixed amount of migration work; Redis KEYS and unbounded scans remain
-// forbidden.
-const BACKFILL_LEGACY_INDEX_SCRIPT = `
-local now = tonumber(ARGV[1])
-local index_ttl = tonumber(ARGV[2])
-local next_cursor = ARGV[3]
-
-redis.call("ZREMRANGEBYSCORE", KEYS[1], "-inf", now)
-for i = 4, #ARGV, 3 do
-	local key = ARGV[i]
-	local expected = ARGV[i + 1]
-	local expires_at = tonumber(ARGV[i + 2])
-	if redis.call("GET", key) == expected then
-		redis.call("ZADD", KEYS[1], "NX", expires_at, key)
-	end
+// A v1 key has no connection discriminator, so it cannot safely be exposed to
+// every v2 scope. The first concrete connection (or explicit provider scope) to
+// request a key atomically adopts that value and tombstones v1. The missing-
+// connection sentinel never claims legacy state.
+const CLAIM_LEGACY_SCRIPT = `
+local scoped = redis.call("GET", KEYS[1])
+if scoped then
+	return {1, scoped}
+end
+
+local legacy = redis.call("GET", KEYS[3])
+if not legacy then
+	return {1, false}
+end
+local ok, decoded = pcall(cjson.decode, legacy)
+if ok and type(decoded) == "table" and decoded.deleted == true then
+	return {1, false}
 end
-if redis.call("EXISTS", KEYS[1]) == 1 then
-	redis.call("PEXPIRE", KEYS[1], index_ttl)
+local legacy_ttl = redis.call("PTTL", KEYS[3])
+if legacy_ttl == -1 then
+	legacy_ttl = tonumber(ARGV[3])
+elseif legacy_ttl < 1 then
+	legacy_ttl = 1
+end
+
+local now = tonumber(ARGV[1])
+local max_entries = tonumber(ARGV[2])
+local index_ttl = tonumber(ARGV[3])
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+redis.call("ZREM", KEYS[2], KEYS[3])
+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[2], next_cursor, "PX", index_ttl)
-return redis.call("ZCARD", KEYS[1])
+
+redis.call("SET", KEYS[1], legacy, "PX", legacy_ttl)
+redis.call("ZADD", KEYS[2], now + legacy_ttl, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+redis.call("SET", KEYS[3], ARGV[4], "PX", index_ttl)
+return {1, legacy}
 `;
 
 type RedisProviderRuntimeStateOptions = {
 	readonly redisUrl: string;
 	readonly providerId?: string;
+	/** Test seam; production callers use redisUrl-backed client sharing. */
+	readonly __redisClient?: ProviderRedisClient;
 };
 
 type RedisStateEnvelope = {
@@ -118,23 +197,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;
@@ -157,25 +245,49 @@ 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 {
+	return `${providerStatePrefix(providerId, namespace, scopeDiscriminator)}:${key}`;
+}
+
+function legacyProviderStatePrefix(providerId: string | undefined, namespace: string): string {
+	return `${LEGACY_REDIS_STATE_PREFIX}:${providerId ?? "default"}:${namespace}`;
+}
+
+function legacyProviderStateKey(
+	providerId: string | undefined,
+	namespace: string,
+	key: string,
 ): string {
-	const prefix = `${providerStatePrefix(providerId, namespace)}:`;
-	return redisKey.startsWith(prefix) ? redisKey.slice(prefix.length) : redisKey;
+	return `${legacyProviderStatePrefix(providerId, namespace)}:${key}`;
 }
 
-function redisGlobLiteral(value: string): string {
-	return value.replace(/[\\*?\[\]]/g, "\\$&");
+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 {
@@ -196,10 +308,6 @@ 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,
@@ -240,6 +348,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,
@@ -256,10 +379,28 @@ 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 legacyRedisKey(key: string): string {
+		return legacyProviderStateKey(this.providerId, this.namespaceName, key);
+	}
+
+	private statePrefix(): string {
+		return providerStatePrefix(
+			this.providerId,
+			this.namespaceName,
+			this.scopeDiscriminator,
+		);
 	}
 
 	private indexKey(): string {
@@ -267,70 +408,18 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		// 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),
+			providerStatePrefix(
+				this.providerId,
+				this.namespaceName,
+				this.scopeDiscriminator,
+			),
 			"utf8",
 		).toString("base64url");
 		return `${REDIS_STATE_PREFIX}:index:${namespaceIdentity}`;
 	}
 
-	private legacyScanCursorKey(): string {
-		return `${this.indexKey()}:legacy-scan-cursor`;
-	}
-
-	private legacyPrefix(): string {
-		return `${providerStatePrefix(this.providerId, this.namespaceName)}:`;
-	}
-
-	private async backfillLegacyIndex(): Promise<void> {
-		await requireRedisReady(this.backend.redis);
-		const cursorKey = this.legacyScanCursorKey();
-		let cursor =
-			(await withRequiredRedis(() => this.backend.redis.get(cursorKey))) ?? "0";
-		const pattern = `${redisGlobLiteral(this.legacyPrefix())}*`;
-		const indexTtlMs = parseStateDurationMs(this.options.maxTtl);
-
-		for (let page = 0; page < LEGACY_INDEX_SCAN_MAX_PAGES; page += 1) {
-			const [nextCursor, keys] = await withRequiredRedis(() =>
-				this.backend.redis.scan(
-					cursor,
-					"MATCH",
-					pattern,
-					"COUNT",
-					LEGACY_INDEX_SCAN_COUNT,
-				),
-			);
-			const rawValues =
-				keys.length > 0
-					? await withRequiredRedis(() => this.backend.redis.mget(keys))
-					: [];
-			const now = Date.now();
-			const activeLegacyArgs: string[] = [];
-			for (const [index, raw] of rawValues.entries()) {
-				const key = keys[index];
-				if (!key || !raw) continue;
-				const envelope = envelopeFromJson(
-					publicStateKey(this.providerId, this.namespaceName, key),
-					raw,
-				);
-				const expiresAtMs = envelope ? Date.parse(envelope.expiresAt) : Number.NaN;
-				if (!Number.isFinite(expiresAtMs) || expiresAtMs <= now) continue;
-				activeLegacyArgs.push(key, raw, String(expiresAtMs));
-			}
-			await withRequiredRedis(() =>
-				this.backend.redis.eval(
-					BACKFILL_LEGACY_INDEX_SCRIPT,
-					2,
-					this.indexKey(),
-					cursorKey,
-					String(now),
-					String(indexTtlMs),
-					nextCursor,
-					...activeLegacyArgs,
-				),
-			);
-			cursor = nextCursor;
-			if (cursor === "0") break;
-		}
+	private canClaimLegacy(): boolean {
+		return this.scopeDiscriminator !== MISSING_CONNECTION_SCOPE_DISCRIMINATOR;
 	}
 
 	private async indexedKeys(limit: number): Promise<string[]> {
@@ -349,6 +438,31 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		});
 	}
 
+	private async readRaw(key: string): Promise<string | null> {
+		await requireRedisReady(this.backend.redis);
+		if (!this.canClaimLegacy()) {
+			return await withRequiredRedis(() => this.backend.redis.get(this.redisKey(key)));
+		}
+		const tombstone = JSON.stringify({ deleted: true } satisfies RedisStateTombstone);
+		const result = await withRequiredRedis(() =>
+			this.backend.redis.eval(
+				CLAIM_LEGACY_SCRIPT,
+				3,
+				this.redisKey(key),
+				this.indexKey(),
+				this.legacyRedisKey(key),
+				String(Date.now()),
+				String(this.options.maxEntries),
+				String(parseStateDurationMs(this.options.maxTtl)),
+				tombstone,
+			),
+		);
+		if (Array.isArray(result) && Number(result[0]) === 0) {
+			throw this.quotaExceeded();
+		}
+		return Array.isArray(result) && typeof result[1] === "string" ? result[1] : null;
+	}
+
 	private enforceValueSize(value: unknown): void {
 		const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
 		if (bytes > this.options.maxValueBytes) {
@@ -387,31 +501,30 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 	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 [];
-		await this.backfillLegacyIndex();
-		const keys = (await this.indexedKeys(this.options.maxEntries)).filter((key) => {
-			const publicKey = publicStateKey(this.providerId, this.namespaceName, key);
-			return options?.prefix ? publicKey.startsWith(options.prefix) : true;
-		});
-		const limited = keys.slice(0, requestedLimit);
-		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 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.backfillLegacyIndex();
 		const current = await this.get<T>(key);
 		const createdAt = current?.createdAt ?? new Date().toISOString();
 		const version = (current?.version ?? 0) + 1;
@@ -421,14 +534,17 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		const result = await withRequiredRedis(() =>
 			this.backend.redis.eval(
 				SET_WITH_QUOTA_SCRIPT,
-				2,
+				3,
 				this.redisKey(key),
 				this.indexKey(),
+				this.legacyRedisKey(key),
 				String(Date.now()),
 				String(this.options.maxEntries),
 				String(timing.expiresAtMs),
 				String(timing.indexTtlMs),
 				JSON.stringify(envelope),
+				this.canClaimLegacy() ? "1" : "0",
+				JSON.stringify({ deleted: true } satisfies RedisStateTombstone),
 			),
 		);
 		if (!Array.isArray(result) || Number(result[0]) !== 1) {
@@ -462,12 +578,7 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		options?: StateWriteOptions,
 	): Promise<StateCasResult<T>> {
 		this.enforceValueSize(value);
-		await this.backfillLegacyIndex();
-		const current = await this.get<T>(key);
-		if ((current?.version ?? 0) !== expectedVersion) {
-			return { ok: false, current };
-		}
-		const createdAt = current?.createdAt ?? new Date().toISOString();
+		const createdAt = new Date().toISOString();
 		const timing = this.writeTiming(options?.ttl);
 		const envelope = redisEnvelope(
 			value,
@@ -479,15 +590,18 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		const result = await withRequiredRedis(() =>
 			this.backend.redis.eval(
 				COMPARE_AND_SET_WITH_QUOTA_SCRIPT,
-				2,
+				3,
 				this.redisKey(key),
 				this.indexKey(),
+				this.legacyRedisKey(key),
 				String(expectedVersion),
 				String(Date.now()),
 				String(this.options.maxEntries),
 				String(timing.expiresAtMs),
 				String(timing.indexTtlMs),
 				JSON.stringify(envelope),
+				this.canClaimLegacy() ? "1" : "0",
+				JSON.stringify({ deleted: true } satisfies RedisStateTombstone),
 			),
 		);
 		if (Array.isArray(result) && Number(result[0]) === 0) {
@@ -497,27 +611,29 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 			const rawCurrent = Array.isArray(result) && typeof result[1] === "string" ? result[1] : null;
 			return { ok: false, current: envelopeFromJson(key, rawCurrent) };
 		}
-		return {
-			ok: true,
-			value: {
-				key,
-				value,
-				version: envelope.version,
-				expiresAt: timing.expiresAt,
-				createdAt,
-				updatedAt: envelope.updatedAt,
-			},
-		};
+		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);
+		const tombstone = JSON.stringify({ deleted: true } satisfies RedisStateTombstone);
 		await withRequiredRedis(() =>
 			this.backend.redis.eval(
 				DELETE_WITH_INDEX_SCRIPT,
-				2,
+				3,
 				this.redisKey(key),
 				this.indexKey(),
+				this.legacyRedisKey(key),
+				tombstone,
+				String(parseStateDurationMs(this.options.maxTtl)),
+				this.canClaimLegacy() ? "1" : "0",
 			),
 		);
 	}
@@ -537,14 +653,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,
+		);
 	}
 }
 
@@ -594,6 +730,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();
 	}
@@ -722,14 +862,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;
 	}
 }