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

package/dist/runtime/secrets.d.ts

@@ -0,0 +1,27 @@
+import type { EnvContext, ProviderDefinition } from "../types.js";
+/**
+ * Canonical error code for a declared-but-unprovisioned provider secret.
+ *
+ * The SDK is the single source of truth for env/secret presence validation:
+ * providers declare secrets in `defineProvider({ secrets: [...] })` and the
+ * runtime enforces presence before any handler or auth-flow code runs.
+ * Provider-local presence guards (requireServiceKey/requireApiKey style) are a
+ * deprecated antipattern — see the `sdk-owned-secret-presence` submit-check
+ * rule.
+ */
+export declare const MISSING_SECRET_CODE = "MISSING_SECRET";
+/**
+ * Names of declared `required: true` secrets whose env values are unset or
+ * whitespace-only. Whitespace-only values count as missing for parity with the
+ * `.trim()` guards well-built providers used before the SDK owned this check —
+ * a blank value provisioned by a broken secret pipeline must not pass the gate.
+ */
+export declare function listMissingRequiredSecrets(provider: ProviderDefinition, env: EnvContext): string[];
+/**
+ * Throws the canonical structured missing-secret error when any declared
+ * `required: true` secret is absent. All missing names are reported in a
+ * single error so operators can provision the full set in one pass instead of
+ * discovering them one deploy at a time (the 2026-07-22 unprovisioned-secret
+ * incident failure mode).
+ */
+export declare function assertRequiredSecretsPresent(provider: ProviderDefinition, env: EnvContext): void;

package/dist/runtime/secrets.js

@@ -0,0 +1,51 @@
+import { ProviderSecretError } from "../errors.js";
+/**
+ * Canonical error code for a declared-but-unprovisioned provider secret.
+ *
+ * The SDK is the single source of truth for env/secret presence validation:
+ * providers declare secrets in `defineProvider({ secrets: [...] })` and the
+ * runtime enforces presence before any handler or auth-flow code runs.
+ * Provider-local presence guards (requireServiceKey/requireApiKey style) are a
+ * deprecated antipattern — see the `sdk-owned-secret-presence` submit-check
+ * rule.
+ */
+export const MISSING_SECRET_CODE = "MISSING_SECRET";
+/**
+ * Names of declared `required: true` secrets whose env values are unset or
+ * whitespace-only. Whitespace-only values count as missing for parity with the
+ * `.trim()` guards well-built providers used before the SDK owned this check —
+ * a blank value provisioned by a broken secret pipeline must not pass the gate.
+ */
+export function listMissingRequiredSecrets(provider, env) {
+    const missing = [];
+    for (const secret of provider.secrets ?? []) {
+        if (secret.required !== true) {
+            continue;
+        }
+        const value = env.get(secret.name);
+        if (value === undefined || value.trim() === "") {
+            missing.push(secret.name);
+        }
+    }
+    return missing;
+}
+/**
+ * Throws the canonical structured missing-secret error when any declared
+ * `required: true` secret is absent. All missing names are reported in a
+ * single error so operators can provision the full set in one pass instead of
+ * discovering them one deploy at a time (the 2026-07-22 unprovisioned-secret
+ * incident failure mode).
+ */
+export function assertRequiredSecretsPresent(provider, env) {
+    const missing = listMissingRequiredSecrets(provider, env);
+    if (missing.length === 0) {
+        return;
+    }
+    const names = missing.join(", ");
+    throw new ProviderSecretError(`Missing required provider secret${missing.length > 1 ? "s" : ""}: ${names}`, {
+        code: MISSING_SECRET_CODE,
+        category: "credential_unavailable",
+        retryable: false,
+        fix: `Provision ${names} in the provider environment (e.g. Doppler). Declared in defineProvider({ secrets: [...] }).`,
+    });
+}

package/dist/runtime/state.d.ts

@@ -1,8 +1,11 @@
 import { ProviderError } from "../errors.js";
 import type { ProviderRuntimeState } from "../types.js";
+import { type ProviderRedisClient } from "./redis.js";
 type RedisProviderRuntimeStateOptions = {
     readonly redisUrl: string;
     readonly providerId?: string;
+    /** Test seam; production callers use redisUrl-backed client sharing. */
+    readonly __redisClient?: ProviderRedisClient;
 };
 export declare class UnsupportedProviderStateError extends ProviderError {
     constructor(message?: string);

package/dist/runtime/state.js

@@ -1,21 +1,93 @@
+import { createHash } from "node:crypto";
 import { providerStateRedisUrlFromEnv } from "../config/loader.js";
 import { ProviderError } from "../errors.js";
 import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } 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
+`;
 const redisBackends = new Map();
-function getRedisBackend(redisUrl) {
+function getRedisBackend(redisUrl, injectedRedis) {
     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;
@@ -36,15 +108,26 @@ async function requireRedisReady(redis) {
         return;
     throw new UnsupportedProviderStateError("Provider runtime state Redis is unavailable");
 }
-function providerStatePrefix(providerId, namespace) {
-    return `${REDIS_STATE_PREFIX}:${providerId ?? "default"}:${namespace}`;
+function connectionScopeDiscriminator(connectionId) {
+    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, namespace, scopeDiscriminator) {
+    return `${REDIS_STATE_PREFIX}:${providerId ?? "default"}:${namespace}:${scopeDiscriminator}`;
 }
-function providerStateKey(providerId, namespace, key) {
-    return `${providerStatePrefix(providerId, namespace)}:${key}`;
+function providerStateKey(providerId, namespace, scopeDiscriminator, key) {
+    return `${providerStatePrefix(providerId, namespace, scopeDiscriminator)}:${key}`;
 }
-function publicStateKey(providerId, namespace, redisKey) {
-    const prefix = `${providerStatePrefix(providerId, namespace)}:`;
-    return redisKey.startsWith(prefix) ? redisKey.slice(prefix.length) : redisKey;
+function publicStateKey(redisKey, prefixes) {
+    for (const prefix of prefixes) {
+        const prefixWithSeparator = `${prefix}:`;
+        if (redisKey.startsWith(prefixWithSeparator)) {
+            return redisKey.slice(prefixWithSeparator.length);
+        }
+    }
+    return redisKey;
 }
 function parseStateDurationMs(ttl) {
     const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl ?? "1h");
@@ -63,13 +146,21 @@ function parseStateDurationMs(ttl) {
                     : 86_400_000;
     return Math.max(1, amount * multiplier);
 }
-function resolveExpiresAt(ttl) {
-    return new Date(Date.now() + parseStateDurationMs(ttl)).toISOString();
-}
 function envelopeFromJson(key, raw) {
     if (!raw)
         return null;
-    const parsed = 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;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
         return null;
     }
@@ -90,6 +181,20 @@ function envelopeFromJson(key, raw) {
         updatedAt: record.updatedAt,
     };
 }
+function isStateTombstone(raw) {
+    if (!raw)
+        return false;
+    try {
+        const parsed = JSON.parse(raw);
+        return (parsed !== null &&
+            typeof parsed === "object" &&
+            !Array.isArray(parsed) &&
+            parsed.deleted === true);
+    }
+    catch {
+        return false;
+    }
+}
 function redisEnvelope(value, version, createdAt, expiresAt) {
     const updatedAt = new Date().toISOString();
     return { value, version, expiresAt, createdAt, updatedAt };
@@ -99,21 +204,38 @@ class RedisProviderStateNamespace {
     providerId;
     namespaceName;
     options;
-    constructor(backend, providerId, namespaceName, options) {
+    scopeDiscriminator;
+    constructor(backend, providerId, namespaceName, options, scopeDiscriminator) {
         this.backend = backend;
         this.providerId = providerId;
         this.namespaceName = namespaceName;
         this.options = options;
+        this.scopeDiscriminator = scopeDiscriminator;
     }
     redisKey(key) {
-        return providerStateKey(this.providerId, this.namespaceName, key);
+        return providerStateKey(this.providerId, this.namespaceName, this.scopeDiscriminator, key);
+    }
+    statePrefix() {
+        return providerStatePrefix(this.providerId, this.namespaceName, this.scopeDiscriminator);
     }
-    prefix() {
-        return `${providerStatePrefix(this.providerId, this.namespaceName)}:`;
+    indexKey() {
+        // 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}`;
     }
-    async activeKeys() {
+    async indexedKeys(limit) {
         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);
+        });
+    }
+    async readRaw(key) {
+        await requireRedisReady(this.backend.redis);
+        return await withRequiredRedis(() => this.backend.redis.get(this.redisKey(key)));
     }
     enforceValueSize(value) {
         const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
@@ -121,52 +243,68 @@ class RedisProviderStateNamespace {
             throw new UnsupportedProviderStateError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`);
         }
     }
-    async enforceMaxEntries(key) {
-        const keys = await this.activeKeys();
-        const redisKey = this.redisKey(key);
-        const otherKeys = keys.filter((candidate) => candidate !== redisKey);
-        if (otherKeys.length >= this.options.maxEntries) {
-            throw new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${otherKeys.length + 1} > ${this.options.maxEntries})`);
+    quotaExceeded() {
+        return new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`);
+    }
+    writeTiming(ttl) {
+        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})`);
         }
+        const expiresAtMs = Date.now() + ttlMs;
+        return {
+            expiresAt: new Date(expiresAtMs).toISOString(),
+            expiresAtMs,
+            indexTtlMs: maxTtlMs,
+        };
     }
     async list(options) {
-        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)
+        const requestedLimit = Math.max(0, options?.limit ?? this.options.maxEntries);
+        if (requestedLimit === 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 = [];
+        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(key) {
-        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(key, value, options) {
         this.enforceValueSize(value);
-        await this.enforceMaxEntries(key);
         const current = await this.get(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,
         };
@@ -179,15 +317,29 @@ class RedisProviderStateNamespace {
     }
     async compareAndSet(key, expectedVersion, value, options) {
         this.enforceValueSize(value);
-        const current = await this.get(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);
+        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) {
         await requireRedisReady(this.backend.redis);
-        await withRequiredRedis(() => this.backend.redis.del(this.redisKey(key)));
+        const tombstone = JSON.stringify({ deleted: true });
+        await withRequiredRedis(() => this.backend.redis.eval(DELETE_WITH_INDEX_SCRIPT, 2, this.redisKey(key), this.indexKey(), tombstone, String(parseStateDurationMs(this.options.maxTtl))));
     }
     async increment(key, field, delta = 1, options) {
         const current = (await this.get(key))?.value ?? {};
@@ -198,12 +350,19 @@ class RedisProviderStateNamespace {
 class RedisProviderRuntimeState {
     backend;
     providerId;
-    constructor(options) {
-        this.backend = getRedisBackend(options.redisUrl);
+    redisUrl;
+    scopeDiscriminator;
+    constructor(options, 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) {
+        return new RedisProviderRuntimeState({ redisUrl: this.redisUrl, providerId: this.providerId }, connectionScopeDiscriminator(connectionId));
     }
     namespace(name, options) {
-        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);
     }
 }
 export class UnsupportedProviderStateError extends ProviderError {
@@ -236,6 +395,9 @@ class UnsupportedProviderStateNamespace {
     }
 }
 class UnsupportedProviderRuntimeState {
+    forConnection(_connectionId) {
+        return new UnsupportedProviderRuntimeState();
+    }
     namespace(_name, _options) {
         return new UnsupportedProviderStateNamespace();
     }
@@ -247,6 +409,23 @@ class MemoryProviderStateNamespace {
     constructor(options) {
         this.options = options;
     }
+    enforceValueSize(value) {
+        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})`);
+        }
+    }
+    enforceWritePolicy(key, value, ttl) {
+        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})`);
+        }
+    }
     pruneExpired(nowMs = Date.now()) {
         for (const [key, row] of this.values.entries()) {
             if (row.expiresAt && Date.parse(row.expiresAt) <= nowMs) {
@@ -265,6 +444,7 @@ class MemoryProviderStateNamespace {
     }
     async set(key, value, options) {
         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);
@@ -282,8 +462,24 @@ class MemoryProviderStateNamespace {
     async patch(_key, _partial, _options) {
         throw new UnsupportedProviderStateError("In-memory provider runtime state does not support patch");
     }
-    async compareAndSet(_key, _expectedVersion, _value, _options) {
-        throw new UnsupportedProviderStateError("In-memory provider runtime state does not support compareAndSet");
+    async compareAndSet(key, expectedVersion, value, options) {
+        this.pruneExpired();
+        const current = this.values.get(key);
+        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,
+        };
+        this.values.set(key, stored);
+        return { ok: true, value: stored };
     }
     async delete(key) {
         this.values.delete(key);
@@ -293,13 +489,23 @@ class MemoryProviderStateNamespace {
     }
 }
 class MemoryProviderRuntimeState {
-    namespaces = new Map();
-    namespace(name, _options) {
-        const existing = this.namespaces.get(name);
+    backend;
+    scopeDiscriminator;
+    constructor(backend = { namespaces: new Map() }, scopeDiscriminator = MISSING_CONNECTION_SCOPE_DISCRIMINATOR) {
+        this.backend = backend;
+        this.scopeDiscriminator = scopeDiscriminator;
+    }
+    forConnection(connectionId) {
+        return new MemoryProviderRuntimeState(this.backend, connectionScopeDiscriminator(connectionId));
+    }
+    namespace(name, options) {
+        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;
     }
 }

package/dist/runtime/stealth-cookies.d.ts

@@ -0,0 +1,20 @@
+import type { CookieJar, StealthCookieStore, StealthCookieStoreV1, StealthSessionCookies } from "../types.js";
+export declare class StealthCookieJar implements CookieJar, StealthSessionCookies {
+    private cookies;
+    private readonly defaultUrl;
+    constructor(cookieStrings: readonly string[], defaultUrl?: string);
+    setFromCookieStrings(cookieStrings: readonly string[], url?: string): void;
+    get(name: string, url?: string): string | undefined;
+    getAll(url?: string): Record<string, string>;
+    has(name: string, url?: string): boolean;
+    toString(url?: string): string;
+    toHeader(url?: string): string;
+    snapshot(): Record<string, string>;
+    restore(cookies: Record<string, string>): void;
+    serialize(): StealthCookieStoreV1;
+    deserialize(state: StealthCookieStore): void;
+    clear(): void;
+    find(predicate: (cookie: string) => boolean, url?: string): string | undefined;
+    private normalizeUrl;
+    private getUniqueCookies;
+}