@volter/twin-upstash 0.1.0

package/src/upstash-conformance.ts

@@ -0,0 +1,131 @@
+// 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.ts';
+
+export type UpstashRedisConformanceReport = {
+  ok: boolean;
+  endpointsChecked: number;
+  resourceTypesChecked: number;
+  violations: string[];
+};
+
+const AT = '2026-01-01T00:00:00.000Z';
+
+/** One probe per claimed endpoint: the request to make, and what a LIVE handler must answer. */
+type Probe = { label: string; method: string; path: string; body?: string; expect: (r: { status: number; body: unknown }) => boolean };
+
+export async function checkUpstashRedisConformance(): Promise<UpstashRedisConformanceReport> {
+  const snapshot = upstashTwinSnapshot();
+  const violations: string[] = [];
+  const root = mkdtempSync(join(tmpdir(), 'upstash-conf-'));
+  const auth = { authorization: 'Bearer twin-conformance-token' };
+  const result = (r: { body: unknown }) => (r.body as { result?: unknown }).result;
+
+  const probes: Probe[] = [
+    {
+      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 as Array<{ result?: unknown }>;
+        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 as Array<{ result?: unknown }>;
+        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 as readonly string[]).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 as { result?: unknown }).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 as { result?: unknown }).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 as { result?: unknown }).result !== 'number' || (alive.body as { result: number }).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/src/upstash-connector.ts

@@ -0,0 +1,340 @@
+// 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 type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { upstashBudgetOf, guardUpstashRedisClient, type UpstashRedisBudgetedOptions } from './upstash-budget.ts';
+
+const SERVICE = 'upstash';
+
+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;
+};
+
+function kid(id: string): string {
+  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: UpstashRedisRealKey, occurredAtMs: number): SyncResource {
+  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 as never,
+      pexpire_at: pexpireAt,
+      last_id: '',
+      gone: false,
+    },
+  };
+}
+
+/** Normalize whatever the injected client returned into this twin's storage encoding. */
+function encodeValue(type: string, raw: unknown): unknown {
+  if (type === 'hash') {
+    const obj = (raw ?? {}) as Record<string, unknown>;
+    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 ?? []) as unknown[];
+    // 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: Array<[string, string]> = [];
+    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 ?? []) as unknown[]).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: UpstashRedisLikeClient,
+  handles: UpstashRedisKeyHandle[],
+  opts: { occurredAt?: string } & UpstashRedisBudgetedOptions = {},
+): Promise<SyncResource[]> {
+  const client = guardUpstashRedisClient(rawClient, upstashBudgetOf(opts));
+  if (handles.length === 0) return [];
+  const at = Date.parse(opts.occurredAt ?? new Date().toISOString());
+  const out: SyncResource[] = [];
+  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: unknown;
+    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: UpstashRedisLikeClient,
+  opts: { match?: string; limit?: number; pageSize?: number } & UpstashRedisBudgetedOptions = {},
+): Promise<UpstashRedisKeyHandle[]> {
+  const client = guardUpstashRedisClient(rawClient, upstashBudgetOf(opts));
+  if (!client.scan) return [];
+  const limit = opts.limit ?? 100;
+  const pageSize = opts.pageSize ?? 50;
+  const found: string[] = [];
+  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: UpstashRedisLikeClient,
+  opts: { root?: string; occurredAt?: string; keys?: UpstashRedisKeyHandle[] } & UpstashRedisBudgetedOptions = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  // 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: RemoteExecute): UpstashRedisLikeClient {
+  const command = async (...args: unknown[]): Promise<any> => {
+    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: any = {};
+    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) as Record<string, unknown> | null;
+      const out: Record<string, unknown> = {};
+      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: unknown) => String(m)),
+    lrange: async (key, start, stop) => ((await command('LRANGE', key, start, stop)) ?? []).map((m: unknown) => String(m)),
+    zrange: async (key, start, stop, opts) => (await command('ZRANGE', key, start, stop, ...(opts?.withScores ? ['WITHSCORES'] : []))) ?? [],
+    scan: async (cursor, opts) => {
+      const args: unknown[] = ['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: unknown) => 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: RemoteExecute,
+  opts: { root?: string; origin?: string; occurredAt?: string; limit?: number; match?: string } & UpstashRedisBudgetedOptions = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  // 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: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  const fields = (action.fields ?? {}) as Record<string, any>;
+
+  // 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: unknown[]): Promise<Record<string, unknown>> => {
+    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 || '{}') as Record<string, unknown>; } 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: Record<string, unknown>): Promise<PushOutcome> => {
+    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: unknown) => (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: unknown) => (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` } };
+}