@volter/twin-upstash 0.1.0

package/dist/src/upstash-conformance.d.ts

@@ -0,0 +1,7 @@
+export type UpstashRedisConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    resourceTypesChecked: number;
+    violations: string[];
+};
+export declare function checkUpstashRedisConformance(): Promise<UpstashRedisConformanceReport>;

package/dist/src/upstash-conformance.js

@@ -0,0 +1,119 @@
+// upstash conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+//
+// This is NOT the static self-referential snapshot check most packs ship. §9 refuted that pattern
+// elsewhere in this repo on the grounds that comparing one constant to another cannot detect a dead
+// handler — so this check ISSUES REAL REQUESTS (the azureformrecognizer `conformance.endpoint_probe`
+// pattern): it drives every endpoint the snapshot claims through `handleUpstashRedisTwinRequest`
+// against a throwaway root and requires each to be genuinely routed and to answer with the right
+// envelope. A twin whose handler returned `{}` fails this, which is the whole point.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleUpstashRedisTwinRequest, upstashTwinSnapshot, UPSTASH_RESOURCE_TYPES } from "./upstash-twin.js";
+const AT = '2026-01-01T00:00:00.000Z';
+export async function checkUpstashRedisConformance() {
+    const snapshot = upstashTwinSnapshot();
+    const violations = [];
+    const root = mkdtempSync(join(tmpdir(), 'upstash-conf-'));
+    const auth = { authorization: 'Bearer twin-conformance-token' };
+    const result = (r) => r.body.result;
+    const probes = [
+        {
+            label: 'POST / (one command as a JSON array body)',
+            method: 'POST', path: '/', body: JSON.stringify(['SET', 'conf:a', 'one']),
+            expect: (r) => r.status === 200 && result(r) === 'OK',
+        },
+        {
+            label: 'GET /{COMMAND}/{args...} (path-style, percent-decoded)',
+            method: 'GET', path: '/get/conf:a',
+            expect: (r) => r.status === 200 && result(r) === 'one',
+        },
+        {
+            label: 'POST /{COMMAND}/{args...} (path-style; the raw body becomes the last argument)',
+            method: 'POST', path: '/set/conf:b?EX=100', body: 'two',
+            expect: (r) => r.status === 200 && result(r) === 'OK',
+        },
+        {
+            label: 'POST /pipeline (array of command arrays, non-atomic, per-item {result}/{error})',
+            method: 'POST', path: '/pipeline', body: JSON.stringify([['GET', 'conf:b'], ['TTL', 'conf:b']]),
+            expect: (r) => {
+                const items = r.body;
+                return r.status === 200 && Array.isArray(items) && items.length === 2 && items[0].result === 'two' && items[1].result === 100;
+            },
+        },
+        {
+            label: 'POST /multi-exec (array of command arrays, transaction, queue-time EXECABORT)',
+            method: 'POST', path: '/multi-exec', body: JSON.stringify([['INCR', 'conf:n'], ['INCR', 'conf:n']]),
+            expect: (r) => {
+                const items = r.body;
+                return r.status === 200 && Array.isArray(items) && items[0].result === 1 && items[1].result === 2;
+            },
+        },
+        {
+            label: 'OPTIONS / (CORS preflight)',
+            method: 'OPTIONS', path: '/',
+            expect: (r) => r.status === 200,
+        },
+    ];
+    try {
+        for (const probe of probes) {
+            if (!snapshot.implementedEndpoints.includes(probe.label)) {
+                violations.push(`probe '${probe.label}' has no matching entry in implementedEndpoints`);
+                continue;
+            }
+            const response = await handleUpstashRedisTwinRequest({
+                method: probe.method,
+                path: probe.path,
+                headers: auth,
+                root,
+                occurredAt: AT,
+                ...(probe.body !== undefined ? { body: probe.body } : {}),
+            });
+            if (!probe.expect(response)) {
+                violations.push(`endpoint '${probe.label}' did not answer as declared (status ${response.status}, body ${JSON.stringify(response.body)})`);
+            }
+        }
+        // Every claimed endpoint must have a probe — otherwise the inventory could grow entries nothing
+        // exercises, which is exactly the drift a self-referential snapshot cannot see.
+        for (const endpoint of snapshot.implementedEndpoints) {
+            if (!probes.some((p) => p.label === endpoint))
+                violations.push(`declared endpoint '${endpoint}' has no conformance probe`);
+        }
+        // The inventory must match what the handler WRITES, in BOTH directions.
+        //
+        // §9 round 2: the first version only rejected an EXTRA bogus type, so reverting the inventory
+        // to the round-one bug (`['key']` alone, omitting 'script') left this loop vacuous and the
+        // check still returned ok — it could not fail in the direction of the very drift its comment
+        // claimed to catch. Both directions are now asserted, so a missing type is a violation too.
+        const written = ['key', 'script'];
+        for (const type of UPSTASH_RESOURCE_TYPES) {
+            if (!written.includes(type))
+                violations.push(`declared resource type '${type}' is not written by any handler path`);
+        }
+        for (const type of written) {
+            if (!UPSTASH_RESOURCE_TYPES.includes(type)) {
+                violations.push(`the handler writes subject type '${type}' but UPSTASH_RESOURCE_TYPES does not declare it`);
+            }
+        }
+        // …and 'script' must be genuinely reachable, not merely declared.
+        const loaded = await handleUpstashRedisTwinRequest({ method: 'POST', path: '/', headers: auth, root, occurredAt: AT, body: JSON.stringify(['SCRIPT', 'LOAD', 'return 1']) });
+        const sha = loaded.body.result;
+        const ran = await handleUpstashRedisTwinRequest({ method: 'POST', path: '/', headers: auth, root, occurredAt: AT, body: JSON.stringify(['EVALSHA', String(sha), '0']) });
+        if (typeof sha !== 'string' || ran.body.result !== 1) {
+            violations.push(`resource type 'script' is declared but the script cache did not round-trip (load=${JSON.stringify(loaded.body)} run=${JSON.stringify(ran.body)})`);
+        }
+        const alive = await handleUpstashRedisTwinRequest({ method: 'POST', path: '/', headers: auth, root, occurredAt: AT, body: JSON.stringify(['DBSIZE']) });
+        if (typeof alive.body.result !== 'number' || alive.body.result < 3) {
+            violations.push(`the 'key' resource type is declared but the probes' writes did not project into the keyspace (DBSIZE=${JSON.stringify(alive.body)})`);
+        }
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+    return {
+        ok: violations.length === 0,
+        endpointsChecked: snapshot.implementedEndpoints.length,
+        resourceTypesChecked: snapshot.resourceTypes.length,
+        violations,
+    };
+}

package/dist/src/upstash-connector.d.ts

@@ -0,0 +1,115 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { type UpstashRedisBudgetedOptions } from './upstash-budget.js';
+export type { UpstashRedisBudgetedOptions };
+/** A key the caller wants pulled. `type` may be supplied when already known, to save a round trip. */
+export type UpstashRedisKeyHandle = {
+    key: string;
+    type?: string;
+};
+/**
+ * The subset of a real Redis client this connector calls. A `@upstash/redis` `Redis` instance
+ * satisfies it structurally. Every member is OPTIONAL: a client that cannot do one of these makes
+ * the corresponding pull observe nothing, which is the honest outcome — inventing a value would
+ * turn "cannot see" into "saw an empty key", and a subsequent push would then delete real data.
+ */
+export interface UpstashRedisLikeClient {
+    get?: (key: string) => Promise<unknown>;
+    type?: (key: string) => Promise<string>;
+    ttl?: (key: string) => Promise<number>;
+    hgetall?: (key: string) => Promise<Record<string, unknown> | null>;
+    smembers?: (key: string) => Promise<string[]>;
+    lrange?: (key: string, start: number, stop: number) => Promise<string[]>;
+    zrange?: (key: string, start: number, stop: number, opts?: {
+        withScores?: boolean;
+    }) => Promise<unknown[]>;
+    scan?: (cursor: number, opts?: {
+        match?: string;
+        count?: number;
+    }) => Promise<[string, string[]]>;
+}
+/** The twin-side shape of one pulled key, before it becomes a kernel resource. */
+export type UpstashRedisRealKey = {
+    key: string;
+    type: string;
+    /** Already in this twin's storage encoding: string | string[] | [f,v][] | [member,score][]. */
+    value: unknown;
+    /** Seconds remaining, Redis-style: -1 = no TTL, -2 = missing. */
+    ttl?: number;
+};
+/**
+ * Pure mapper (a real key → a kernel `SyncResource`). Never touches a client, so the mutation
+ * harness's connector-seam sweep (which sabotages exports matching sync/push/pull/fullSync) leaves
+ * it real — the pack convention, mirroring qstash's `mapMessage`.
+ *
+ * The field names deliberately avoid the kernel's reserved META keys (`type`/`id`/`updatedAt`,
+ * which `projectResources` SILENTLY DROPS): the Redis type is stored as `kind`, and the key name
+ * as `name`. This is the same layout `upstash-store.ts` writes, so a pulled key and a locally
+ * written one are indistinguishable to every read path.
+ *
+ * `occurredAtMs` is required rather than defaulted: a TTL in SECONDS has to be turned into an
+ * absolute deadline against SOME instant, and silently choosing `Date.now()` here would make a
+ * pulled key's expiry unreproducible.
+ */
+export declare function mapKey(real: UpstashRedisRealKey, occurredAtMs: number): SyncResource;
+/**
+ * Read the CURRENT real state of every NAMED key. A key the vendor does not have is SKIPPED — never
+ * emitted as an empty one, which would let a later push wipe it.
+ */
+export declare function pullUpstashRedisKeys(rawClient: UpstashRedisLikeClient, handles: UpstashRedisKeyHandle[], opts?: {
+    occurredAt?: string;
+} & UpstashRedisBudgetedOptions): Promise<SyncResource[]>;
+/**
+ * Walk the real keyspace with `SCAN`, bounded by `limit`.
+ *
+ * The bound is the point: an unbounded walk of a production Redis is precisely the burst the rate
+ * budget exists to stop, and a connector that offered one would be inviting the caller to spend a
+ * whole allowance in a loop. Returns the discovered handles; feed them to `pullUpstashRedisKeys`.
+ */
+export declare function pullUpstashRedisScan(rawClient: UpstashRedisLikeClient, opts?: {
+    match?: string;
+    limit?: number;
+    pageSize?: number;
+} & UpstashRedisBudgetedOptions): Promise<UpstashRedisKeyHandle[]>;
+/**
+ * D7 entry point: pull the current real state of every named key and fold it into the twin via ONE
+ * one observation. Returns `{observed, deltasAppended}` — a re-pull of identical
+ * state appends ZERO deltas, which is what makes the pull idempotent.
+ */
+export declare function syncUpstashRedisFromReal(rawClient: UpstashRedisLikeClient, opts?: {
+    root?: string;
+    occurredAt?: string;
+    keys?: UpstashRedisKeyHandle[];
+} & UpstashRedisBudgetedOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * An `UpstashRedisLikeClient` over the kernel's executor. At a REAL boundary the kernel sets the
+ * sealed credential over these headers (executor.ts); at the twin's own wire any credential is one.
+ *
+ * Every call is `POST /` with the command as a JSON array — the REST protocol's canonical form, and
+ * what `@upstash/redis` sends. The reply is `{result: …}` and the SDK hands the caller the INNER
+ * value, so this does too: returning the envelope would present a shape the parsers below have
+ * never seen, and they would find nothing rather than fail. (The sibling upstashvector pack lost a
+ * whole refresh to exactly that, 2026-09-08.)
+ */
+export declare function upstashRedisClientOver(execute: RemoteExecute): UpstashRedisLikeClient;
+/** The refresh adapter: Redis enumerates (`SCAN` walks the keyspace), so the whole database comes
+ *  back without the world having to say which keys it holds. */
+export declare function syncUpstashRedisFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+    limit?: number;
+    match?: string;
+} & UpstashRedisBudgetedOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * The perform adapter. A key a world wrote crosses as the command that would recreate it, typed by
+ * what it is: a string is a SET (with its TTL when it has one), a hash an HSET, a set an SADD, a
+ * list an RPUSH, a sorted set a ZADD. A delete is a DEL. Anything else this world recorded about
+ * the database is a read at Upstash and has nothing to write.
+ */
+export declare function performUpstashRedisAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome>;

package/dist/src/upstash-connector.js

@@ -0,0 +1,309 @@
+// upstash CONNECTOR — the live-vendor pull path that gives this twin the "git for SaaS"
+// lifecycle over an INJECTED client (the auth boundary). The pack imports NO SDK and holds NO
+// token; a consumer injects something structurally satisfying `UpstashRedisLikeClient` (a real
+// `@upstash/redis` client is assignable as-is, since its `get`/`type`/`ttl`/... methods have
+// exactly these shapes).
+//
+// ── PULL IS HANDLE-DRIVEN, AND THAT IS A DELIBERATE SAFETY PROPERTY, NOT A GAP ─────────────────
+// Redis has no cheap "give me everything" endpoint. `KEYS *` is O(N) and Upstash's own docs warn
+// against it on a production database; `SCAN` is the supported walk but is unbounded in cost. So
+// this connector pulls the CURRENT real value of keys the caller NAMES, and `syncUpstashRedisFromReal`
+// folds them through one observation (the kernel dedupes, so a re-pull of identical state appends
+// ZERO deltas). `pullUpstashRedisScan` exists for callers who genuinely want a walk, and it takes a
+// hard `limit` for the same reason.
+//
+// ── THE RATE BUDGET IS NOT OPTIONAL HERE ──────────────────────────────────────────────────────
+// Upstash BILLS AND LIMITS PER COMMAND, and publishes the number (10,000 commands/sec — see
+// upstash-budget.ts). A key-by-key pull is exactly the shape that turns one careless loop into
+// tens of thousands of billable commands, so every entrypoint below GUARDS the injected client
+// before touching it (`guardUpstashRedisClient`, which is idempotent). There is deliberately no
+// option that turns the guard off.
+import { observeResources } from '@volter/world-core';
+import { upstashBudgetOf, guardUpstashRedisClient } from "./upstash-budget.js";
+const SERVICE = 'upstash';
+function kid(id) {
+    return `key:${id}`;
+}
+/**
+ * Pure mapper (a real key → a kernel `SyncResource`). Never touches a client, so the mutation
+ * harness's connector-seam sweep (which sabotages exports matching sync/push/pull/fullSync) leaves
+ * it real — the pack convention, mirroring qstash's `mapMessage`.
+ *
+ * The field names deliberately avoid the kernel's reserved META keys (`type`/`id`/`updatedAt`,
+ * which `projectResources` SILENTLY DROPS): the Redis type is stored as `kind`, and the key name
+ * as `name`. This is the same layout `upstash-store.ts` writes, so a pulled key and a locally
+ * written one are indistinguishable to every read path.
+ *
+ * `occurredAtMs` is required rather than defaulted: a TTL in SECONDS has to be turned into an
+ * absolute deadline against SOME instant, and silently choosing `Date.now()` here would make a
+ * pulled key's expiry unreproducible.
+ */
+export function mapKey(real, occurredAtMs) {
+    const ttl = real.ttl;
+    const pexpireAt = ttl !== undefined && ttl > 0 ? occurredAtMs + ttl * 1000 : null;
+    return {
+        type: 'key',
+        id: kid(real.key),
+        // Gotcha (kernel field MERGE, never a deep merge or an omission-clear): every field a later
+        // local write could overwrite is written explicitly here, so a pulled key can never inherit a
+        // stale `last_id` or a dead `gone` flag from a previous incarnation of the same subject.
+        fields: {
+            name: real.key,
+            kind: real.type,
+            v: real.value,
+            pexpire_at: pexpireAt,
+            last_id: '',
+            gone: false,
+        },
+    };
+}
+/** Normalize whatever the injected client returned into this twin's storage encoding. */
+function encodeValue(type, raw) {
+    if (type === 'hash') {
+        const obj = (raw ?? {});
+        return Object.entries(obj).map(([f, v]) => [f, typeof v === 'string' ? v : JSON.stringify(v)]);
+    }
+    if (type === 'zset') {
+        // `zrange(..., {withScores:true})` returns a flat [member, score, member, score, …] array.
+        const flat = (raw ?? []);
+        // Scores are stored as STRINGS, matching upstash-store.ts's StoredZSet: a JSON number
+        // cannot represent ±inf, and a pulled +inf score would otherwise persist as null.
+        const out = [];
+        for (let i = 0; i + 1 < flat.length; i += 2)
+            out.push([String(flat[i]), String(flat[i + 1])]);
+        return out;
+    }
+    if (type === 'set' || type === 'list')
+        return (raw ?? []).map((v) => (typeof v === 'string' ? v : JSON.stringify(v)));
+    if (type === 'string')
+        return typeof raw === 'string' ? raw : JSON.stringify(raw ?? null);
+    // A type this connector cannot faithfully encode is REFUSED BY NAME, never coerced.
+    //
+    // §9 round 2 found the old `return JSON.stringify(...)` fallback storing a pulled STREAM as a
+    // JSON string while still labelling it `kind:'stream'` — after which every stream read threw a
+    // raw TypeError out of the request handler. Silently mis-encoding a type is worse than not
+    // pulling it: the twin then holds state that looks real and cannot be read.
+    throw new Error(`upstash connector: cannot pull key of type '${type}' — this connector encodes string/hash/set/list/zset only (upstash.connector.pull_streams is the filed todo for streams)`);
+}
+/**
+ * Read the CURRENT real state of every NAMED key. A key the vendor does not have is SKIPPED — never
+ * emitted as an empty one, which would let a later push wipe it.
+ */
+export async function pullUpstashRedisKeys(rawClient, handles, opts = {}) {
+    const client = guardUpstashRedisClient(rawClient, upstashBudgetOf(opts));
+    if (handles.length === 0)
+        return [];
+    const at = Date.parse(opts.occurredAt ?? new Date().toISOString());
+    const out = [];
+    for (const handle of handles) {
+        const type = handle.type ?? (client.type ? await client.type(handle.key) : 'string');
+        if (type === 'none')
+            continue; // the key does not exist on the vendor
+        let value;
+        if (type === 'hash')
+            value = client.hgetall ? await client.hgetall(handle.key) : null;
+        else if (type === 'set')
+            value = client.smembers ? await client.smembers(handle.key) : [];
+        else if (type === 'list')
+            value = client.lrange ? await client.lrange(handle.key, 0, -1) : [];
+        else if (type === 'zset')
+            value = client.zrange ? await client.zrange(handle.key, 0, -1, { withScores: true }) : [];
+        else
+            value = client.get ? await client.get(handle.key) : null;
+        if (value === null || value === undefined)
+            continue;
+        const ttl = client.ttl ? await client.ttl(handle.key) : -1;
+        out.push(mapKey({ key: handle.key, type, value: encodeValue(type, value), ttl }, at));
+    }
+    return out;
+}
+/**
+ * Walk the real keyspace with `SCAN`, bounded by `limit`.
+ *
+ * The bound is the point: an unbounded walk of a production Redis is precisely the burst the rate
+ * budget exists to stop, and a connector that offered one would be inviting the caller to spend a
+ * whole allowance in a loop. Returns the discovered handles; feed them to `pullUpstashRedisKeys`.
+ */
+export async function pullUpstashRedisScan(rawClient, opts = {}) {
+    const client = guardUpstashRedisClient(rawClient, upstashBudgetOf(opts));
+    if (!client.scan)
+        return [];
+    const limit = opts.limit ?? 100;
+    const pageSize = opts.pageSize ?? 50;
+    const found = [];
+    let cursor = 0;
+    // A bounded loop, not a `while (cursor !== 0)`: a vendor that never returns cursor 0 must not be
+    // able to spin this forever, and the budget must not be the only thing that stops it.
+    for (let page = 0; page < 100 && found.length < limit; page++) {
+        const [next, keys] = await client.scan(cursor, { count: pageSize, ...(opts.match !== undefined ? { match: opts.match } : {}) });
+        found.push(...keys);
+        cursor = Number(next);
+        if (cursor === 0)
+            break;
+    }
+    return found.slice(0, limit).map((key) => ({ key }));
+}
+/**
+ * D7 entry point: pull the current real state of every named key and fold it into the twin via ONE
+ * one observation. Returns `{observed, deltasAppended}` — a re-pull of identical
+ * state appends ZERO deltas, which is what makes the pull idempotent.
+ */
+export async function syncUpstashRedisFromReal(rawClient, opts = {}) {
+    // Guard ONCE here and hand the guarded client down: the per-handle loop is unbounded in handle
+    // count, so this is the entrypoint that must be unable to run unbudgeted.
+    const client = guardUpstashRedisClient(rawClient, upstashBudgetOf(opts));
+    const occurredAt = opts.occurredAt ?? new Date().toISOString();
+    const resources = await pullUpstashRedisKeys(client, opts.keys ?? [], { occurredAt });
+    const result = ((__at) => observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt);
+    return { observed: resources.length, deltasAppended: result.appended };
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/**
+ * An `UpstashRedisLikeClient` over the kernel's executor. At a REAL boundary the kernel sets the
+ * sealed credential over these headers (executor.ts); at the twin's own wire any credential is one.
+ *
+ * Every call is `POST /` with the command as a JSON array — the REST protocol's canonical form, and
+ * what `@upstash/redis` sends. The reply is `{result: …}` and the SDK hands the caller the INNER
+ * value, so this does too: returning the envelope would present a shape the parsers below have
+ * never seen, and they would find nothing rather than fail. (The sibling upstashvector pack lost a
+ * whole refresh to exactly that, 2026-09-08.)
+ */
+export function upstashRedisClientOver(execute) {
+    const command = async (...args) => {
+        const res = await execute({
+            method: 'POST', path: '/',
+            headers: { accept: 'application/json', 'content-type': 'application/json', authorization: 'Bearer twin' },
+            body: JSON.stringify(args.map((a) => (typeof a === 'string' ? a : String(a)))),
+        });
+        let parsed = {};
+        try {
+            parsed = JSON.parse(res.body || '{}');
+        }
+        catch {
+            parsed = {};
+        }
+        if (res.status < 200 || res.status >= 300 || parsed?.error !== undefined) {
+            throw new Error(`upstash redis ${String(args[0])} refused: HTTP ${res.status} ${JSON.stringify(parsed).slice(0, 200)}`);
+        }
+        return parsed?.result !== undefined ? parsed.result : parsed;
+    };
+    return {
+        get: (key) => command('GET', key),
+        type: (key) => command('TYPE', key),
+        ttl: (key) => command('TTL', key),
+        hgetall: async (key) => {
+            // HGETALL over REST answers a FLAT array (field, value, field, value…), which is what the
+            // wire says; the SDK object-ifies it and this connector reads an object.
+            const flat = await command('HGETALL', key);
+            if (!Array.isArray(flat))
+                return (flat ?? null);
+            const out = {};
+            for (let i = 0; i + 1 < flat.length; i += 2)
+                out[String(flat[i])] = flat[i + 1];
+            return out;
+        },
+        smembers: async (key) => ((await command('SMEMBERS', key)) ?? []).map((m) => String(m)),
+        lrange: async (key, start, stop) => ((await command('LRANGE', key, start, stop)) ?? []).map((m) => String(m)),
+        zrange: async (key, start, stop, opts) => (await command('ZRANGE', key, start, stop, ...(opts?.withScores ? ['WITHSCORES'] : []))) ?? [],
+        scan: async (cursor, opts) => {
+            const args = ['SCAN', cursor];
+            if (opts?.match !== undefined)
+                args.push('MATCH', opts.match);
+            if (opts?.count !== undefined)
+                args.push('COUNT', opts.count);
+            const answered = await command(...args);
+            const next = Array.isArray(answered) ? String(answered[0] ?? '0') : '0';
+            const keys = Array.isArray(answered) && Array.isArray(answered[1]) ? answered[1].map((k) => String(k)) : [];
+            return [next, keys];
+        },
+    };
+}
+/** The refresh adapter: Redis enumerates (`SCAN` walks the keyspace), so the whole database comes
+ *  back without the world having to say which keys it holds. */
+export async function syncUpstashRedisFromRemote(execute, opts = {}) {
+    // Guarded here as well as inside the sync: the guard is idempotent, and stating it at every
+    // entrypoint is what this pack's source tooth holds the connector to.
+    const client = guardUpstashRedisClient(upstashRedisClientOver(execute), upstashBudgetOf(opts));
+    // `syncUpstashRedisFromReal` takes the keys as an argument, which is right for a caller who knows
+    // what it wants and wrong for "refresh this world", which means the database. Redis has an
+    // enumeration, so this uses it: SCAN discovers the keyspace (bounded — an unbounded walk of a
+    // production Redis is the burst the rate budget exists to stop) and the handles it finds are what
+    // gets pulled. Without this the refresh named no key and reported an empty database.
+    const keys = await pullUpstashRedisScan(client, {
+        ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+        ...(opts.match !== undefined ? { match: opts.match } : {}),
+    });
+    return syncUpstashRedisFromReal(client, {
+        keys,
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        occurredAt: opts.occurredAt ?? new Date().toISOString(),
+    });
+}
+/**
+ * The perform adapter. A key a world wrote crosses as the command that would recreate it, typed by
+ * what it is: a string is a SET (with its TTL when it has one), a hash an HSET, a set an SADD, a
+ * list an RPUSH, a sorted set a ZADD. A delete is a DEL. Anything else this world recorded about
+ * the database is a read at Upstash and has nothing to write.
+ */
+export async function performUpstashRedisAction(execute, action, _ctx) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const fields = (action.fields ?? {});
+    // THE STORE'S OWN FIELD NAMES. An entry is
+    //   { name, kind, v, pexpire_at, last_id, gone }
+    // and the operations are `string.set` / `hash.set` / `set.add` / `list.push` / `zset.add` /
+    // `key.del`. The first version of this adapter read `key`, `type`, `value`, `ttl` and `deleted` —
+    // none of which exist — so it sent `SET '' ''` and the vendor answered 200. A wrong write that
+    // succeeds is the worst outcome available here, and no gate exercises a perform, so it passed
+    // every one of them. (Audit, 2026-09-08.)
+    const key = typeof fields.name === 'string' && fields.name ? fields.name : action.subject.id.replace(/^key:/, '');
+    const kind = String(fields.kind ?? 'string');
+    const value = fields.v;
+    const send = async (...args) => {
+        const res = await execute({
+            method: 'POST', path: '/',
+            headers: { accept: 'application/json', 'content-type': 'application/json', authorization: 'Bearer twin' },
+            body: JSON.stringify(args.map((a) => (typeof a === 'string' ? a : String(a)))),
+        });
+        if (res.status < 200 || res.status >= 300)
+            throw new Error(`upstash redis ${String(args[0])} refused: HTTP ${res.status} ${res.body.slice(0, 200)}`);
+        try {
+            return JSON.parse(res.body || '{}');
+        }
+        catch {
+            return {};
+        }
+    };
+    if (op === 'key.del' || fields.gone === true) {
+        return { externalId: key, data: await send('DEL', key) };
+    }
+    // `pexpire_at` is an ABSOLUTE epoch-ms instant, not a TTL in seconds — so it converges with
+    // PEXPIREAT, which takes exactly that. Sending it as an `EX` argument would have set an expiry
+    // fifty-six thousand years out.
+    const expireAt = typeof fields.pexpire_at === 'number' && fields.pexpire_at > 0 ? fields.pexpire_at : null;
+    const withExpiry = async (answered) => {
+        if (expireAt !== null)
+            await send('PEXPIREAT', key, expireAt);
+        return { externalId: key, data: answered };
+    };
+    if (kind === 'string')
+        return withExpiry(await send('SET', key, String(value ?? '')));
+    if (kind === 'hash') {
+        // `v` is an array of [field, value] PAIRS, which HSET wants flattened.
+        const flat = (Array.isArray(value) ? value : []).flatMap((pair) => (Array.isArray(pair) ? [String(pair[0]), String(pair[1])] : []));
+        return flat.length === 0 ? { externalId: key, data: {} } : withExpiry(await send('HSET', key, ...flat));
+    }
+    if (kind === 'set') {
+        const members = (Array.isArray(value) ? value : []).map(String);
+        return members.length === 0 ? { externalId: key, data: {} } : withExpiry(await send('SADD', key, ...members));
+    }
+    if (kind === 'list') {
+        const items = (Array.isArray(value) ? value : []).map(String);
+        return items.length === 0 ? { externalId: key, data: {} } : withExpiry(await send('RPUSH', key, ...items));
+    }
+    if (kind === 'zset') {
+        // `v` is [[member, score], …]; ZADD takes them the other way round.
+        const pairs = (Array.isArray(value) ? value : []).flatMap((pair) => (Array.isArray(pair) ? [String(pair[1]), String(pair[0])] : []));
+        return pairs.length === 0 ? { externalId: key, data: {} } : withExpiry(await send('ZADD', key, ...pairs));
+    }
+    return { externalId: key, data: { performed: false, reason: `a ${kind} key has no command in this adapter that recreates it — this stays this world's own record` } };
+}