@volter/twin-upstash 0.1.0

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

@@ -0,0 +1,73 @@
+import { type RedisValue } from './upstash-store.js';
+export type UpstashRedisRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string>;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /**
+     * The token this twin accepts. When set, the request's credential must match it EXACTLY.
+     * When omitted the twin accepts any NON-EMPTY credential and still 401s a missing/blank one —
+     * the honest default for a local twin whose whole point is that you do not hold a real secret.
+     */
+    token?: string;
+};
+export type UpstashRedisResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/** The literal 401 body the real service returns — LIVE-PROBED, byte for byte, including the
+ *  `docs.upstash.com` host (NOT `upstash.com/docs`) and the trailing period. The SAME body and
+ *  status answer a missing header, a blank token and a wrong token: the vendor draws no
+ *  distinction, so neither does this twin. */
+export declare const UPSTASH_UNAUTHORIZED_ERROR = "WRONGPASS invalid or missing auth token. See https://docs.upstash.com/redis/troubleshooting/http_unauthorized for details.";
+/**
+ * Extract the caller's credential. THREE accepted forms, all confirmed against the live service:
+ *   • `Authorization: Bearer <token>`   (documented, what the SDK sends)
+ *   • `Authorization: <token>`          (UNDOCUMENTED but accepted — probed directly)
+ *   • `?_token=<token>`                 (documented)
+ * When both a header and `?_token=` are present, the QUERY PARAM WINS: probing showed a request
+ * with a bogus header and a valid `?_token=` succeeds.
+ */
+export declare function extractUpstashCredential(headers: Record<string, string> | undefined, query: URLSearchParams): string | null;
+/**
+ * Apply `Upstash-Encoding: base64`, exactly as the real service does.
+ *
+ * THE RULE, established by probing rather than from the docs (which only say "all strings … except
+ * for the "OK" response"): every STRING in `result` is base64-encoded with `=` padding, recursively
+ * at any array depth — EXCEPT the simple-status reply whose value is exactly `OK`, which passes
+ * through raw. Integers, `null` and empty arrays are untouched. The `error` field is NEVER encoded.
+ *
+ * The exemption is scoped to the STATUS `OK`, not to the string `"OK"`. Probed evidence:
+ *   SET  → status OK        → `{"result":"OK"}`      (raw)
+ *   GET of a key holding "OK" → bulk string → `{"result":"T0s="}` (encoded)
+ *   PING → status PONG      → `{"result":"UE9ORw=="}` (encoded — so it is not "statuses are raw")
+ * That is why the store carries a `RedisStatus` wrapper at all.
+ */
+export declare function encodeResult(v: RedisValue, base64: boolean): unknown;
+/**
+ * The read-your-writes sync token. LIVE-PROBED behaviour: a base-32 counter (`0-9a-v`) that ADVANCES
+ * on a write and is ECHOED BACK unchanged on a read; an unparseable value degrades to `"0"`; the
+ * header is absent on a 401.
+ *
+ * The twin's counter is derived from the number of WRITE ACTIONS this request appended plus the
+ * caller's own token, so it is monotonic per client without any wall clock or process-global state.
+ * The SDK has a documented off-by-one (it snapshots request headers before storing the new token,
+ * so request N carries response N-2's value) and can send a missing, empty or stale token — this
+ * must therefore be PERMISSIVE and never 4xx on a bad one.
+ */
+export declare function nextSyncToken(incoming: string | undefined, wrote: boolean): string;
+export type UpstashRedisSurface = 'command' | 'pipeline' | 'multi-exec' | 'path-command';
+/** Which endpoint does this path address? Exported so a test can pin the routing table itself. */
+export declare function routeUpstashRedisSurface(path: string): UpstashRedisSurface;
+export declare function handleUpstashRedisTwinRequest(req: UpstashRedisRequest): Promise<UpstashRedisResponse>;
+export declare const UPSTASH_RESOURCE_TYPES: readonly ["key", "script"];
+export type UpstashRedisResourceType = typeof UPSTASH_RESOURCE_TYPES[number];
+export type UpstashRedisTwinSnapshot = {
+    resourceTypes: readonly UpstashRedisResourceType[];
+    implementedEndpoints: readonly string[];
+};
+export declare function upstashTwinSnapshot(): UpstashRedisTwinSnapshot;

package/dist/src/upstash-twin.js

@@ -0,0 +1,437 @@
+// UPSTASH REDIS REST TWIN — THE REQUEST HANDLER. Contract:
+//   handleUpstashRedisTwinRequest({ method, path, body, headers, root, occurredAt, readOnly, token })
+//     -> { status, body, headers }
+//
+// This file is the TRANSPORT half; every Redis semantic lives in `upstash-store.ts` and every
+// Lua semantic in `upstash-lua.ts`. What is modeled here is Upstash's REST protocol itself,
+// which is a real surface with real quirks:
+//
+//   POST /                      body `["SET","k","v","EX",100]`      one command
+//   GET|POST|PUT|HEAD /CMD/a/b  path-style, args percent-decoded     one command
+//   POST /set/k?EX=100          the RAW BODY becomes the last arg    one command
+//   POST /pipeline              body `[["SET","a","1"],["GET","a"]]` N commands, non-atomic
+//   POST /multi-exec            same body shape                      N commands, transaction
+//
+// GROUNDED (2026-08-19) three ways — see spec-sources.json and the store module's header: the REST
+// docs page, the ACTUALLY-INSTALLED `@upstash/redis@1.35.7` compiled source, and LIVE PROBES of a
+// real ephemeral Upstash database. Every status code, error string and header rule below came off
+// that live server, not out of a guess.
+//
+// ── THREE THINGS A NAIVE TWIN GETS WRONG, ALL OF THEM FATAL TO THE REAL SDK ────────────────────
+//
+// 1. `/pipeline` IS NOT OPTIONAL. `@upstash/redis` has `enableAutoPipelining: true` BY DEFAULT
+//    (confirmed in the installed 1.35.7 source), so a plain `await redis.get("k")` arrives as
+//    `POST /pipeline` with body `[["get","k"]]` — NOT as `POST /`. A twin serving only `POST /`
+//    fails against a default-configured client. (A fixed list of commands — `scan keys flushdb
+//    flushall dbsize hscan hgetall hkeys lrange sscan smembers xrange xrevrange zscan zrange exec` —
+//    bypasses auto-pipelining and does arrive at `POST /`.)
+//
+// 2. A COMMAND ERROR IS HTTP 400, NOT 200. The SDK has two error paths: on `!res.ok` it throws
+//    `UpstashError("<error>, command was: <json>")`, and on a 2xx carrying `{error}` it throws the
+//    bare message. Upstash always uses 400, so the suffixed form is what a real integrator sees —
+//    serving 200 silently changes the error text every consumer's tests assert on.
+//
+// 3. `Upstash-Encoding: base64` IS ON BY DEFAULT and its rule is subtler than the docs say. See
+//    `encodeResult` below: every string is base64'd at any array depth EXCEPT the simple-status
+//    reply `OK`. Getting this wrong is invisible in a curl session and catastrophic through the
+//    SDK, whose `base64decode` SWALLOWS failures and returns the raw input — so an unencoded
+//    `"PONG"` (valid base64!) decodes to mojibake rather than erroring.
+import { commandShapeError, execRedisRun, RedisCommandError, RedisStatus, ReadOnlyError, } from "./upstash-store.js";
+import { ownFields, twinResources } from '@volter/world-core';
+import { SERVICE } from "./upstash-store.js";
+/** The literal 401 body the real service returns — LIVE-PROBED, byte for byte, including the
+ *  `docs.upstash.com` host (NOT `upstash.com/docs`) and the trailing period. The SAME body and
+ *  status answer a missing header, a blank token and a wrong token: the vendor draws no
+ *  distinction, so neither does this twin. */
+export const UPSTASH_UNAUTHORIZED_ERROR = 'WRONGPASS invalid or missing auth token. See https://docs.upstash.com/redis/troubleshooting/http_unauthorized for details.';
+/** LIVE-PROBED response headers. `server` carries the real service's own banner shape. */
+const BASE_HEADERS = {
+    'content-type': 'application/json; charset=utf-8',
+    'access-control-allow-credentials': 'true',
+    server: 'Upstash Redis Database (1.17.11)',
+};
+/** LIVE-PROBED: 10 MB, enforced with HTTP 413 (a status the REST docs do not even list). */
+const MAX_REQUEST_BYTES = 10_485_760;
+function lowerHeaders(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h ?? {}))
+        out[k.toLowerCase()] = v;
+    return out;
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// AUTH
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Extract the caller's credential. THREE accepted forms, all confirmed against the live service:
+ *   • `Authorization: Bearer <token>`   (documented, what the SDK sends)
+ *   • `Authorization: <token>`          (UNDOCUMENTED but accepted — probed directly)
+ *   • `?_token=<token>`                 (documented)
+ * When both a header and `?_token=` are present, the QUERY PARAM WINS: probing showed a request
+ * with a bogus header and a valid `?_token=` succeeds.
+ */
+export function extractUpstashCredential(headers, query) {
+    const fromQuery = query.get('_token');
+    if (fromQuery !== null && fromQuery !== '')
+        return fromQuery;
+    const raw = lowerHeaders(headers).authorization;
+    if (raw === undefined)
+        return null;
+    const trimmed = raw.trim();
+    // The optional-group form matters: `Authorization: Bearer ` (the scheme with an EMPTY token)
+    // trims to the bare word "Bearer". A `/^bearer\s+(.*)$/` pattern does not match it, so a naive
+    // implementation falls through and treats the literal string "Bearer" as the credential —
+    // authenticating a request that carries no token at all. Matching the scheme with an optional
+    // remainder is what makes an empty bearer resolve to `null` and get the vendor's 401.
+    const bearer = /^bearer(?:\s+(.*))?$/i.exec(trimmed);
+    const token = bearer ? (bearer[1] ?? '').trim() : trimmed;
+    return token === '' ? null : token;
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// RESPONSE ENCODING
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Apply `Upstash-Encoding: base64`, exactly as the real service does.
+ *
+ * THE RULE, established by probing rather than from the docs (which only say "all strings … except
+ * for the "OK" response"): every STRING in `result` is base64-encoded with `=` padding, recursively
+ * at any array depth — EXCEPT the simple-status reply whose value is exactly `OK`, which passes
+ * through raw. Integers, `null` and empty arrays are untouched. The `error` field is NEVER encoded.
+ *
+ * The exemption is scoped to the STATUS `OK`, not to the string `"OK"`. Probed evidence:
+ *   SET  → status OK        → `{"result":"OK"}`      (raw)
+ *   GET of a key holding "OK" → bulk string → `{"result":"T0s="}` (encoded)
+ *   PING → status PONG      → `{"result":"UE9ORw=="}` (encoded — so it is not "statuses are raw")
+ * That is why the store carries a `RedisStatus` wrapper at all.
+ */
+export function encodeResult(v, base64) {
+    if (v === null || typeof v === 'number')
+        return v;
+    if (v instanceof RedisStatus) {
+        if (!base64)
+            return v.value;
+        return v.value === 'OK' ? 'OK' : Buffer.from(v.value, 'utf8').toString('base64');
+    }
+    if (typeof v === 'string')
+        return base64 ? Buffer.from(v, 'utf8').toString('base64') : v;
+    return v.map((item) => encodeResult(item, base64));
+}
+function itemToJson(item, base64) {
+    return 'error' in item ? { error: item.error } : { result: encodeResult(item.result, base64) };
+}
+/**
+ * The read-your-writes sync token. LIVE-PROBED behaviour: a base-32 counter (`0-9a-v`) that ADVANCES
+ * on a write and is ECHOED BACK unchanged on a read; an unparseable value degrades to `"0"`; the
+ * header is absent on a 401.
+ *
+ * The twin's counter is derived from the number of WRITE ACTIONS this request appended plus the
+ * caller's own token, so it is monotonic per client without any wall clock or process-global state.
+ * The SDK has a documented off-by-one (it snapshots request headers before storing the new token,
+ * so request N carries response N-2's value) and can send a missing, empty or stale token — this
+ * must therefore be PERMISSIVE and never 4xx on a bad one.
+ */
+export function nextSyncToken(incoming, wrote) {
+    const parsed = incoming !== undefined && /^[0-9a-v]+$/.test(incoming) ? Number.parseInt(incoming, 32) : 0;
+    const base = Number.isFinite(parsed) ? parsed : 0;
+    return (wrote ? base + 1 : base).toString(32);
+}
+const fail = (error) => ({ error });
+const isFailure = (v) => typeof v === 'object' && v !== null && 'error' in v;
+/**
+ * Coerce one JSON element to a command argument.
+ *
+ * LIVE-PROBED acceptance: strings, JSON numbers and JSON booleans are all valid args (`["setex",
+ * "k",60,"v"]` works). `null`, objects and nested arrays are REFUSED, each with its own message —
+ * and the object/array message quotes the offending JSON delimiter, which is a Go `json.Delim`
+ * leaking through the real server's decoder. Reproduced verbatim: a consumer matching on the real
+ * text must match here too.
+ */
+function toArg(v) {
+    if (typeof v === 'string')
+        return v;
+    return typeof v === 'number' || typeof v === 'boolean' ? String(v) : argRefusal(v);
+}
+/** An argument that is not a string, number or boolean: null, an array or an object, each with its live-probed text. */
+function argRefusal(v) {
+    if (v === null)
+        return fail('ERR null args are not supported');
+    if (Array.isArray(v))
+        return fail('ERR unsupported arg type: "[": json.Delim');
+    return fail('ERR unsupported arg type: "{": json.Delim');
+}
+function toCommand(raw) {
+    const out = [];
+    for (const item of raw) {
+        const arg = toArg(item);
+        if (isFailure(arg))
+            return arg;
+        out.push(arg);
+    }
+    return out;
+}
+/** Which endpoint does this path address? Exported so a test can pin the routing table itself. */
+export function routeUpstashRedisSurface(path) {
+    const clean = (path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
+    if (clean === '/pipeline')
+        return 'pipeline';
+    if (clean === '/multi-exec')
+        return 'multi-exec';
+    if (clean === '/')
+        return 'command';
+    return 'path-command';
+}
+export async function handleUpstashRedisTwinRequest(req) {
+    const method = req.method.toUpperCase();
+    const [rawPath, rawQuery] = req.path.split('?');
+    const query = new URLSearchParams(rawQuery ?? '');
+    const path = (rawPath ?? '/').replace(/\/+$/, '') || '/';
+    const headers = lowerHeaders(req.headers);
+    const occurredAt = req.occurredAt ?? new Date().toISOString();
+    // CORS preflight: LIVE-PROBED as 200 with an empty body, echoing the request's own origin and
+    // requested headers — NOT a 405, despite the docs listing only HEAD/GET/POST/PUT.
+    if (method === 'OPTIONS')
+        return preflight(headers);
+    // LIVE-PROBED: a disallowed method answers 405 with an EMPTY body and no content-type.
+    if (!['GET', 'POST', 'PUT', 'HEAD'].includes(method))
+        return methodNotAllowed();
+    // ── auth, before anything else. A 401 carries NO sync-token header (probed). ────────────────
+    const credential = extractUpstashCredential(req.headers, query);
+    // a token the Developer API lane issued names its database (issuedDatabase); any other is the World's own database's
+    const issued = credential === null ? undefined : issuedDatabase(req.root, credential);
+    const authorized = issued !== undefined ? issued !== 'refused' : req.token === undefined ? credential !== null : credential === req.token;
+    if (!authorized) {
+        return { status: 401, body: { error: UPSTASH_UNAUTHORIZED_ERROR }, headers: { ...BASE_HEADERS } };
+    }
+    const database = issued === undefined || issued === 'refused' ? undefined : issued;
+    const base64 = headers['upstash-encoding'] !== undefined ? headers['upstash-encoding'] : null;
+    // LIVE-PROBED and CASE-SENSITIVE: `BASE64` and `hex` are both rejected by the real service.
+    if (base64 !== null && base64 !== 'base64')
+        return badEncoding(base64);
+    const encodeBase64 = base64 === 'base64';
+    if ((req.body ?? '').length > MAX_REQUEST_BYTES)
+        return tooLarge((req.body ?? '').length);
+    const surface = routeUpstashRedisSurface(path);
+    const respond = (status, body, wrote) => ({
+        status,
+        body,
+        headers: { ...BASE_HEADERS, ...(status < 400 ? { 'upstash-sync-token': nextSyncToken(headers['upstash-sync-token'], wrote) } : {}) },
+    });
+    const ctx = {
+        occurredAt,
+        ...(req.root !== undefined ? { root: req.root } : {}),
+        ...(req.readOnly !== undefined || database?.readOnly ? { readOnly: req.readOnly === true || database?.readOnly === true } : {}),
+        ...(database !== undefined ? { database: database.id } : {}),
+    };
+    return (async () => {
+        if (surface === 'pipeline' || surface === 'multi-exec') {
+            const isTx = surface === 'multi-exec';
+            const parsed = parseBatch(req.body, isTx);
+            if (isFailure(parsed))
+                return respond(400, { error: parsed.error }, false);
+            // QUEUE-TIME validation, and the ONE place pipeline and multi-exec genuinely diverge.
+            // LIVE-PROBED: an unavailable command or a bad arity discards the WHOLE batch pre-execution
+            // (HTTP 400, a single `{error}` object, nothing applied) — but the two endpoints word it
+            // differently, and a transaction additionally names the index it choked on.
+            for (const [index, cmd] of parsed.entries()) {
+                const shape = commandShapeError(cmd);
+                if (shape !== null)
+                    return respond(400, { error: batchRefusal(isTx, cmd, index, shape) }, false);
+            }
+            const { items, wrote } = await execRedisRun(parsed, ctx);
+            return respond(200, items.map((i) => itemToJson(i, encodeBase64)), wrote);
+        }
+        const command = surface === 'command' ? parseSingleBody(req.body) : parsePathCommand(path, query, req.body, method);
+        if (isFailure(command))
+            return respond(400, { error: command.error }, false);
+        const shape = commandShapeError(command);
+        if (shape !== null)
+            return respond(400, { error: shape }, false);
+        const { items, wrote } = await execRedisRun([command], ctx);
+        const only = items[0];
+        if ('error' in only)
+            return respond(400, { error: only.error }, false);
+        // HEAD answers 200 with no body at all (probed).
+        if (method === 'HEAD')
+            return respond(200, null, wrote);
+        return respond(200, { result: encodeResult(only.result, encodeBase64) }, wrote);
+    })().catch((e) => runFault(e, respond));
+}
+/** A CORS preflight: LIVE-PROBED as 200 with an empty body, echoing the request's own origin and requested headers. */
+function preflight(headers) {
+    return {
+        status: 200,
+        body: null,
+        headers: {
+            'access-control-allow-origin': headers.origin ?? '*',
+            'access-control-allow-methods': 'POST',
+            'access-control-allow-headers': headers['access-control-request-headers'] ?? 'authorization,content-type',
+            'access-control-allow-credentials': 'true',
+        },
+    };
+}
+/** A method the REST API does not take: 405 with an EMPTY body and no content-type (live-probed). */
+function methodNotAllowed() {
+    return { status: 405, body: null };
+}
+/** An `Upstash-Encoding` other than `base64` (live-probed, case-sensitive). */
+function badEncoding(value) {
+    return { status: 400, body: { error: `ERR invalid Upstash-Encoding header: "${value}"` }, headers: { ...BASE_HEADERS } };
+}
+/** A body over the 10 MB request limit: 413 (live-probed; upstash.com/docs/redis/troubleshooting/max_request_size_exceeded). */
+function tooLarge(size) {
+    return {
+        status: 413,
+        body: { error: `ERR max request size exceeded. Limit: ${MAX_REQUEST_BYTES} bytes, Actual: ${size} bytes. See https://upstash.com/docs/redis/troubleshooting/max_request_size_exceeded for details` },
+        headers: { ...BASE_HEADERS },
+    };
+}
+/** A batch with a command refused at queue time (an unavailable command, a bad arity): the whole batch is discarded, a
+ *  pipeline with the command's error, a transaction naming it as Redis's EXECABORT does, or by its index (live-probed). */
+function batchRefusal(isTx, cmd, index, shape) {
+    if (!isTx)
+        return shape;
+    return shape.startsWith('ERR wrong number of arguments')
+        ? `EXECABORT Transaction discarded because of previous errors: ['${String(cmd[0] ?? '').toUpperCase()}': ${shape}]`
+        : `${shape} at index ${index}, discarding transaction`;
+}
+/**
+ * A run that threw: a write on a read-only twin (405), a command error raised outside a command's own item (400), or a
+ * fault inside the twin, answered as a loud, twin-attributed 500 so a caller always gets an answer it can reason about.
+ */
+function runFault(e, respond) {
+    if (e instanceof ReadOnlyError)
+        return { status: 405, body: { error: e.message }, headers: { ...BASE_HEADERS } };
+    if (e instanceof RedisCommandError)
+        return respond(400, { error: e.message }, false);
+    return {
+        status: 500,
+        body: { error: `ERR twin: internal fault handling this command — ${e instanceof Error ? e.message : String(e)}` },
+        headers: { ...BASE_HEADERS },
+    };
+}
+/** A body that does not parse as JSON, refused with `message`. */
+function notJson(message) {
+    return fail(message);
+}
+/** A path segment with a malformed percent escape, passed through as it was sent rather than turned into a 500. */
+function undecodable(segment) {
+    return segment;
+}
+/** `POST /` — the whole command as one JSON array. */
+function parseSingleBody(body) {
+    if (body === undefined || body.trim() === '')
+        return fail('EOF'); // LIVE-PROBED: no `ERR ` prefix
+    let parsed;
+    // LIVE-PROBED: a body that is not JSON answers `expected JSON array`, with no `ERR ` prefix
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return notJson('expected JSON array');
+    }
+    if (!Array.isArray(parsed))
+        return fail('expected JSON array');
+    if (parsed.length === 0)
+        return fail('ERR empty command');
+    return toCommand(parsed);
+}
+/** `POST /pipeline` and `POST /multi-exec` — an array of command arrays. */
+function parseBatch(body, isTx) {
+    const what = isTx ? 'transaction' : 'pipeline';
+    if (body === undefined || body.trim() === '')
+        return fail(`ERR failed to parse ${what} request`);
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return notJson(`ERR failed to parse ${what} request`);
+    }
+    if (!Array.isArray(parsed))
+        return fail(`ERR failed to parse ${what} request`);
+    if (parsed.length === 0)
+        return fail(`ERR empty ${what} request`);
+    const out = [];
+    for (const [index, entry] of parsed.entries()) {
+        // A 1-D array (someone POSTing a single command to /pipeline) is named by INDEX, and the
+        // transaction endpoint uses the generic parse message instead — both probed.
+        if (!Array.isArray(entry))
+            return fail(isTx ? `ERR failed to parse ${what} request` : `ERR failed to parse pipeline command at index ${index}`);
+        const cmd = toCommand(entry);
+        if (isFailure(cmd))
+            return cmd;
+        out.push(cmd);
+    }
+    return out;
+}
+/**
+ * Path-style: `/{COMMAND}/{arg1}/…/{argN}`, args PERCENT-DECODED, command name case-insensitive.
+ *
+ * `POST /set/foo` with a raw body appends that body as the command's LAST argument, and any query
+ * parameters become trailing option tokens (`POST /set/foo?EX=100` ⇒ `SET foo <body> EX 100`) —
+ * both documented and probed. `_token` is stripped: it is the credential, not an argument.
+ */
+function parsePathCommand(path, query, body, method) {
+    const segments = path.replace(/^\/+/, '').split('/');
+    const command = [];
+    for (const seg of segments) {
+        try {
+            command.push(decodeURIComponent(seg));
+        }
+        catch {
+            command.push(undecodable(seg));
+        }
+    }
+    if (command.length === 0 || command[0] === '')
+        return fail('ERR empty command');
+    if ((method === 'POST' || method === 'PUT') && body !== undefined && body !== '')
+        command.push(body);
+    for (const [key, value] of query.entries()) {
+        if (key === '_token')
+            continue;
+        command.push(key);
+        if (value !== '')
+            command.push(value);
+    }
+    return command;
+}
+// ── the self-referential conformance snapshot ──────────────────────────────────────────────────
+// TWO kernel subject types, not one. 'script' was added when the EVAL script cache moved out of
+// the keyspace (§9 self-audit) — and §9 round 1 then caught that this inventory still said 'key'
+// alone, which made the conformance check certify a stale number. The inventory is what the
+// conformance probe is FOR, so it has to name everything the twin actually writes.
+/**
+ * The database a REST token names, when the Developer API lane (../api) issued it: the database's id, and whether it is
+ * the Read Only token ("Read Only token permits access to the read commands only",
+ * upstash.com/docs/redis/features/restapi). A token of a deleted database, or one a password reset revoked, is refused with the vendor's 401, as a wrong
+ * one is. A token no lane database holds is the World's own database's, as every token was before the lane existed: an
+ * application pointed at the World (Dub) carries whatever token its own configuration holds. That rule, and a Read Only
+ * token's write answering the twin's read-only refusal (the grounding database exposed no Read Only token to probe), are
+ * the twin's decisions.
+ */
+function issuedDatabase(root, token) {
+    const row = twinResources(SERVICE, root).filter((r) => r.type === '_database').map((r) => ownFields(r))
+        .find((d) => d.rest_token === token || d.read_only_rest_token === token || (Array.isArray(d._revoked_tokens) && d._revoked_tokens.includes(token)));
+    if (row === undefined)
+        return undefined;
+    // a token its database's password reset revoked ("You can revoke both Standard and Read Only tokens by resetting
+    // password of your database", upstash.com/docs/redis/features/restapi) is refused as a wrong one is
+    if (row.rest_token !== token && row.read_only_rest_token !== token)
+        return 'refused';
+    if (row._deleted_at)
+        return 'refused';
+    return { id: String(row.database_id), readOnly: row.read_only_rest_token === token };
+}
+export const UPSTASH_RESOURCE_TYPES = ['key', 'script'];
+export function upstashTwinSnapshot() {
+    return {
+        resourceTypes: UPSTASH_RESOURCE_TYPES,
+        implementedEndpoints: [
+            'POST / (one command as a JSON array body)',
+            'GET /{COMMAND}/{args...} (path-style, percent-decoded)',
+            'POST /{COMMAND}/{args...} (path-style; the raw body becomes the last argument)',
+            'POST /pipeline (array of command arrays, non-atomic, per-item {result}/{error})',
+            'POST /multi-exec (array of command arrays, transaction, queue-time EXECABORT)',
+            'OPTIONS / (CORS preflight)',
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@volter/twin-upstash",
+  "version": "0.1.0",
+  "description": "Local Upstash Redis (REST API) twin: a real stateful Redis command core (strings/counters/TTL/hashes/sets/sorted-sets/keyspace) served over Upstash's per-database REST protocol — single-command POST /, path-style GET /get/key, POST /pipeline, POST /multi-exec, Bearer-token auth, the {result}/{error} envelope, Upstash-Encoding: base64 — plus an EVAL/EVALSHA Lua-subset interpreter that runs @upstash/ratelimit's real fixed-window/sliding-window/token-bucket scripts. Built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "api/src",
+    "qstash/src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/upstash"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/upstash#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-upstash": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "@volter/world-ui": "0.1.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@upstash/redis": "1.35.7",
+    "@upstash/ratelimit": "2.0.8",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/qstash/src/doors.ts

@@ -0,0 +1,51 @@
+// The World's doors in front of the QStash lane (docs/contributing/architecture.md, "Doors, screens and the gap"). QStash
+// delivers to the customer's own HTTP endpoints, which are outside Upstash: what an endpoint received and how it answers
+// are the World's, read and stated here, as Slack's app deliveries are read (packages/twin/slack/src/slack-interactions.ts,
+// `GET /_twin/deliveries?to=`) and as an outside mail server's answer is stated (packages/twin/resend/src/resend-doors.ts,
+// `POST /_twin/recipients/:domain`).
+//
+// - GET /_twin/deliveries?to=<url> → {to, deliveries}: every request QStash made to that URL, oldest first, each as the
+//   endpoint received it (its method, headers and body) and the status it answered.
+// - POST /_twin/destinations {url, status, body?, headers?, when?} → 204: the World's word on how the endpoints under a URL
+//   answer, and, with `when` (header names and values), how they answer a delivery carrying those headers (a workflow's
+//   route answers its failure call, `Upstash-Workflow-Is-Failure: true`, apart from its steps). The statement that names
+//   headers the delivery carries decides before one that names none, then the longest prefix. A fact about the World, like a person's password: QStash's own
+//   delivery attempt reads it (semantics/delivery.ts), and retries an endpoint that answers an error. A destination the
+//   World states nothing for is asked over HTTP where the World lets the request out.
+// - POST /v2/_twin/drain → the catch-up's report: the World's runner (a served World's drainer) asks the lane to run
+//   what the World clock has made due now. Every request the lane answers runs the same catch-up first; this one asks for
+//   nothing else. It is not QStash's API and answers only here.
+import type { DerivedOperation, SemanticsContext } from '@volter/world-core';
+import { DELIVERY, DESTINATION, type CatchUpReport } from './semantics/delivery.ts';
+
+/** A statement without an http(s) URL and a numeric status: refused, the World unchanged. */
+function malformedStatement(): Response {
+  return Response.json({ error: 'a url (http or https) and a status (a number) are required' }, { status: 400 });
+}
+
+/** The operation a door's context is named by: no spec operation is. */
+export const DOOR: DerivedOperation = { id: 'TwinDoor', method: 'POST', path: '/_twin', class: 'action' };
+
+/** A door's answer, or undefined for a request that is not a door's. `report` is what the catch-up in front did. */
+export async function door(ctx: SemanticsContext, request: Request, report: CatchUpReport): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, '');
+  if (request.method === 'POST' && path === '/v2/_twin/drain') return Response.json(report);
+  if (request.method === 'GET' && path === '/_twin/deliveries') {
+    const to = url.searchParams.get('to') ?? '';
+    if (!to) return Response.json({ error: 'to is required' }, { status: 400 });
+    const deliveries = ctx.rowsRaw(DELIVERY).filter((d) => d.to === to)
+      .sort((a, b) => String(a.at).localeCompare(String(b.at)) || Number(a.n) - Number(b.n))
+      .map((d) => ({ messageId: d.message_id, retried: d.retried, at: d.at, method: d.method, headers: d.headers, body: d.body, status: d.status }));
+    return Response.json({ to, deliveries });
+  }
+  if (request.method === 'POST' && path === '/_twin/destinations') {
+    const b = (ctx.body && typeof ctx.body === 'object' ? ctx.body : {}) as Record<string, unknown>;
+    if (typeof b.url !== 'string' || !/^https?:\/\//.test(b.url) || typeof b.status !== 'number') return malformedStatement();
+    const when = b.when && typeof b.when === 'object' ? (b.when as Record<string, string>) : {};
+    const id = `${b.url} ${Object.entries(when).map(([k, v]) => `${k.toLowerCase()}=${v}`).sort().join('&')}`.trim();
+    await ctx.record(DESTINATION, { url: b.url, status: b.status, body: typeof b.body === 'string' ? b.body : '', headers: b.headers ?? {}, when }, id);
+    return new Response(null, { status: 204 });
+  }
+  return undefined;
+}