@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/runtime/state.js

@@ -1,21 +1,96 @@
+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
+	-- Preserve the original createdAt by patching the encoded envelope in place.
+	-- The envelope puts its metadata before "value", so the first match is the
+	-- envelope's own key, never a provider value; re-encoding with cjson would
+	-- silently turn [] inside the value into {}.
+	local preserved = string.gsub(current_decoded.createdAt, "%%", "%%%%")
+	envelope = (string.gsub(envelope, '"createdAt":"[^"]*"', '"createdAt":"' .. preserved .. '"', 1))
+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 +111,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 +149,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,83 +184,134 @@ 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 };
+    // Metadata precedes `value` on purpose: the compare-and-set Lua script patches
+    // `createdAt` in the encoded string (first occurrence) instead of decoding and
+    // re-encoding with cjson, which would turn empty arrays inside `value` into
+    // objects. Keep the key order stable.
+    return { version, expiresAt, createdAt, updatedAt, value };
 }
 class RedisProviderStateNamespace {
     backend;
     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");
         if (bytes > this.options.maxValueBytes) {
-            throw new UnsupportedProviderStateError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`);
+            throw stateViolationError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`, "size");
         }
     }
-    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 stateViolationError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`, "quota");
+    }
+    writeTiming(ttl) {
+        const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+        const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+        if (ttlMs > maxTtlMs) {
+            throw stateViolationError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`, "ttl");
         }
+        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 recordStateRedisNoop([]);
+        const keys = await this.indexedKeys(this.options.maxEntries);
+        if (keys.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 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 +324,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) };
         }
-        return { ok: true, value: await this.set(key, value, options) };
+        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: 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,20 +357,46 @@ 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 {
     constructor(message = "Provider runtime state is not available in this runtime") {
         super(message, { code: "PROVIDER_STATE_UNSUPPORTED" });
         this.name = "UnsupportedProviderStateError";
+        stateViolationKinds.set(this, "unsupported");
     }
 }
+// Keep the exact no-command result out of band, without inspecting caller options twice.
+const stateRedisNoopResults = new WeakSet();
+function recordStateRedisNoop(result) {
+    stateRedisNoopResults.add(result);
+    return result;
+}
+export function isStateRedisNoop(result) {
+    return result !== null && typeof result === "object" && stateRedisNoopResults.has(result);
+}
+const stateViolationKinds = new WeakMap();
+function stateViolationError(message, kind) {
+    const error = new UnsupportedProviderStateError(message);
+    stateViolationKinds.set(error, kind);
+    return error;
+}
+export function getStateViolation(error) {
+    return error !== null && typeof error === "object" ? stateViolationKinds.get(error) : undefined;
+}
 class UnsupportedProviderStateNamespace {
     async list(_options) {
         throw new UnsupportedProviderStateError();
@@ -236,18 +421,40 @@ class UnsupportedProviderStateNamespace {
     }
 }
 class UnsupportedProviderRuntimeState {
+    forConnection(_connectionId) {
+        return new UnsupportedProviderRuntimeState();
+    }
     namespace(_name, _options) {
         return new UnsupportedProviderStateNamespace();
     }
 }
 class MemoryProviderStateNamespace {
     options;
+    now;
     // biome-ignore lint/suspicious/noExplicitAny: in-memory state stores heterogeneous generic values by key.
     values = new Map();
-    constructor(options) {
+    constructor(options, now = Date.now) {
         this.options = options;
+        this.now = now;
     }
-    pruneExpired(nowMs = Date.now()) {
+    enforceValueSize(value) {
+        const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
+        if (bytes > this.options.maxValueBytes) {
+            throw stateViolationError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`, "size");
+        }
+    }
+    enforceWritePolicy(key, value, ttl) {
+        this.enforceValueSize(value);
+        const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+        const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+        if (ttlMs > maxTtlMs) {
+            throw stateViolationError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`, "ttl");
+        }
+        if (!this.values.has(key) && this.values.size >= this.options.maxEntries) {
+            throw stateViolationError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`, "quota");
+        }
+    }
+    pruneExpired(nowMs = this.now()) {
         for (const [key, row] of this.values.entries()) {
             if (row.expiresAt && Date.parse(row.expiresAt) <= nowMs) {
                 this.values.delete(key);
@@ -265,9 +472,10 @@ class MemoryProviderStateNamespace {
     }
     async set(key, value, options) {
         this.pruneExpired();
-        const now = new Date().toISOString();
+        this.enforceWritePolicy(key, value, options?.ttl);
+        const now = new Date(this.now()).toISOString();
         const current = this.values.get(key);
-        const expiresAt = resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl);
+        const expiresAt = resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl, this.now());
         const row = {
             key,
             value,
@@ -282,8 +490,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(this.now()).toISOString();
+        const stored = {
+            key,
+            value,
+            version: expectedVersion + 1,
+            expiresAt: resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl, this.now()),
+            createdAt: current?.createdAt ?? now,
+            updatedAt: now,
+        };
+        this.values.set(key, stored);
+        return { ok: true, value: stored };
     }
     async delete(key) {
         this.values.delete(key);
@@ -293,20 +517,33 @@ class MemoryProviderStateNamespace {
     }
 }
 class MemoryProviderRuntimeState {
-    namespaces = new Map();
-    namespace(name, _options) {
-        const existing = this.namespaces.get(name);
+    backend;
+    scopeDiscriminator;
+    constructor(backend = {
+        namespaces: new Map(),
+        now: Date.now,
+    }, 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.now);
+        this.backend.namespaces.set(namespaceIdentity, created);
         return created;
     }
 }
-function resolveMemoryStateExpiresAt(ttl) {
+function resolveMemoryStateExpiresAt(ttl, nowMs = Date.now()) {
     const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl ?? "1h");
     if (!match)
-        return new Date(Date.now() + 3_600_000).toISOString();
+        return new Date(nowMs + 3_600_000).toISOString();
     const amount = Number(match[1]);
     const unit = match[2];
     const multiplier = unit === "ms"
@@ -318,7 +555,7 @@ function resolveMemoryStateExpiresAt(ttl) {
                 : unit === "h"
                     ? 3_600_000
                     : 86_400_000;
-    return new Date(Date.now() + amount * multiplier).toISOString();
+    return new Date(nowMs + amount * multiplier).toISOString();
 }
 export function createRedisProviderRuntimeState(options) {
     return new RedisProviderRuntimeState(options);
@@ -336,8 +573,11 @@ export function createProviderRuntimeStateFromEnv(options = {}) {
     }
     return createUnsupportedProviderRuntimeState();
 }
-export function createMemoryProviderRuntimeState() {
-    return new MemoryProviderRuntimeState();
+export function createMemoryProviderRuntimeState(options) {
+    return new MemoryProviderRuntimeState({
+        namespaces: new Map(),
+        now: options?.now ?? Date.now,
+    });
 }
 export function createUnsupportedProviderRuntimeState() {
     return new UnsupportedProviderRuntimeState();

package/dist/runtime/stealth-akamai-sbsd.d.ts

@@ -0,0 +1,54 @@
+import type { ChallengeSolution, ProviderChallenge, StealthResponse } from "../types.js";
+import type { ResolverVendorTransport } from "./resolver-vendors/types.js";
+import type { StealthCookieJar } from "./stealth-cookies.js";
+export type AkamaiSbsdChallenge = Extract<ProviderChallenge, {
+    readonly kind: "akamai_sbsd";
+}>;
+/**
+ * SDK-owned response detection and solve wiring derived from the provider declaration.
+ * The server attaches it to the stealth client options it builds; it is deliberately not
+ * part of the public `StealthClientOptions` type.
+ */
+export type StealthChallengeRuntime = {
+    readonly akamaiSbsd?: {
+        readonly allowedHosts: readonly string[];
+        /** Resolver-declared client profile; must name the initiating session's browser family. */
+        readonly clientProfile?: string;
+        readonly solve?: (challenge: AkamaiSbsdChallenge, transport: ResolverVendorTransport, signal: AbortSignal) => Promise<ChallengeSolution>;
+    };
+};
+export type AkamaiSbsdSessionState = {
+    /**
+     * Latest v-only script for this session; Phase 2 deliberately has no wall-clock TTL.
+     * Challenge-state expiry belongs to the Phase 3 ceremony/solve lease handle
+     * (ADR-0010 v1.1), not to the stealth session.
+     */
+    rememberedScript?: URL;
+    /** In-flight solves keyed by akamaiSbsdChallengeKey; an entry leaves only when it settles. */
+    readonly transactions: Map<string, {
+        readonly result: Promise<{
+            readonly solved: true;
+        } | {
+            readonly solved: false;
+            error: unknown;
+        }>;
+    }>;
+    /**
+     * Key of the last automatic (safe-method) solve whose refetch was not challenged again.
+     * An explicit replay for the same key reuses the solved cookies once instead of solving
+     * again; any newer solve or lease expiry clears it.
+     */
+    completedSuccessKey?: string;
+};
+export declare function findAkamaiSbsdScript(body: string, page: URL): URL | undefined;
+export declare function detectAkamaiSbsdChallenge(response: Pick<StealthResponse, "url" | "body">, pageUrl: string, jar: Pick<StealthCookieJar, "has">, allowedHosts: readonly string[], state: AkamaiSbsdSessionState): AkamaiSbsdChallenge | undefined;
+/**
+ * One in-flight solve per session, challenge, and bound identity: requests on one session
+ * may still pick a different wreq browser/OS or proxy, and a solve is only valid for the
+ * identity that ran it.
+ */
+export declare function akamaiSbsdChallengeKey(challenge: AkamaiSbsdChallenge, identity: {
+    readonly wreqBrowser: string;
+    readonly wreqOs: string;
+    readonly proxyUrl: string | undefined;
+}): string;