@volter/twin-upstash 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,18 @@
+export { handleUpstashRedisTwinRequest, routeUpstashRedisSurface, upstashTwinSnapshot, extractUpstashCredential, encodeResult, nextSyncToken, UPSTASH_RESOURCE_TYPES, UPSTASH_UNAUTHORIZED_ERROR, } from './upstash-twin.js';
+export type { UpstashRedisRequest, UpstashRedisResponse, UpstashRedisResourceType, UpstashRedisSurface, UpstashRedisTwinSnapshot, } from './upstash-twin.js';
+export { execRedisRun, commandShapeError, globMatch, isWriteCommand, unavailableCommand, restRestricted, wrongArity, RedisCommandError, RedisStatus, ReadOnlyError, SERVED_COMMANDS, commandId, upstashRedisOwners, KEY_TYPES, REST_RESTRICTED_COMMANDS, SERVICE, } from './upstash-store.js';
+export type { RedisContext, RedisValue, RunItem, KeyType } from './upstash-store.js';
+export { runLua, parseLua, tokenize, luaScriptSha1, luaTruthy, luaTypeName, luaToNumber, luaEquals, numberToLuaString, LuaError, LuaTable } from './upstash-lua.js';
+export type { LuaHost, LuaValue, LuaFunction } from './upstash-lua.js';
+export { createUpstashRedisTwinFetch, createUpstashRedisTwinServer } from './upstash-server.js';
+export type { UpstashRedisServerOptions, UpstashRedisTwinFetchOptions } from './upstash-server.js';
+export { mapKey, pullUpstashRedisKeys, pullUpstashRedisScan, syncUpstashRedisFromReal, } from './upstash-connector.js';
+export type { UpstashRedisLikeClient, UpstashRedisKeyHandle, UpstashRedisRealKey, UpstashRedisBudgetedOptions, } from './upstash-connector.js';
+export { UPSTASH_BUDGETED_METHODS, UPSTASH_BUDGET_CEILING, UPSTASH_BUDGET_MAX_RETRY_AFTER_S, UPSTASH_BUDGET_WINDOW_MS, UPSTASH_CALL_WEIGHTS, UPSTASH_RATE_BUDGET, UpstashRedisBudget, UpstashRedisBudgetError, upstashBudgetPath, upstashCallWeight, upstashClientBudget, guardUpstashRedisClient, } from './upstash-budget.js';
+export type { UpstashRedisBudgetErrorKind, UpstashRedisBudgetOptions, UpstashRedisBudgetReservation, UpstashRedisBudgetSnapshot, } from './upstash-budget.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;
+/** The pack's views of its answers, for a journey step's `view` (scripts/journey-kit.ts). `decoded`: an answer to a
+ *  request sent with `Upstash-Encoding: base64`, as @upstash/redis reads it: each `result` decoded, each `error` as it is,
+ *  for a single command's `{result}` or `{error}` and for a pipeline's or transaction's list of them. */
+export declare const answerViews: Record<string, (body: unknown) => unknown>;

package/dist/src/index.js

@@ -0,0 +1,124 @@
+// @volter/twin-upstash — the Upstash Redis REST API twin, built on the shared @volter/world-core
+// kernel. Per-database host transport (`https://<slug>.upstash.io`), five request forms
+// (`POST /`, path-style `GET|POST /CMD/args`, raw-body `POST /set/k`, `POST /pipeline`,
+// `POST /multi-exec`), Bearer-token auth with the vendor's literal `WRONGPASS` 401, the
+// `{result}`/`{error}` envelope, and `Upstash-Encoding: base64`.
+//
+// Behind that protocol is a REAL Redis: a stateful keyspace (strings, counters, hashes, sets,
+// sorted sets, lists, streams) with real type errors (`WRONGTYPE`), real integer semantics
+// (`ERR value is not an integer or out of range`), real lazy TTL expiry — and a Lua-subset
+// INTERPRETER behind `EVAL`/`EVALSHA`, which is what lets `@upstash/ratelimit` run its own
+// unmodified fixed-window / sliding-window / token-bucket scripts against this twin and actually
+// enforce a limit. Nothing about those scripts is special-cased: they run because the interpreter
+// runs Lua, and their SHA1s are only ever used the way real Redis uses them (the script cache and
+// the `NOSCRIPT` fallback contract).
+//
+// TIME IS INJECTED: TTL expiry, rate-limit windows and stream ids are all measured against an
+// INJECTED clock — the request's own `occurredAt`, or `createUpstashRedisTwinServer({ now })` — so
+// every time-dependent behaviour is reproducible rather than raced. See README ## Coverage.
+//
+// State lives ENTIRELY in the kernel action log (no side-store): every Redis key is one kernel
+// subject, so a restart against the same root answers the same `GET`.
+export { handleUpstashRedisTwinRequest, routeUpstashRedisSurface, upstashTwinSnapshot, extractUpstashCredential, encodeResult, nextSyncToken, UPSTASH_RESOURCE_TYPES, UPSTASH_UNAUTHORIZED_ERROR, } from "./upstash-twin.js";
+// The command core — exported so a caller can drive Redis semantics in-process, without HTTP.
+export { execRedisRun, commandShapeError, globMatch, isWriteCommand, unavailableCommand, restRestricted, wrongArity, RedisCommandError, RedisStatus, ReadOnlyError, SERVED_COMMANDS, commandId, upstashRedisOwners, KEY_TYPES, REST_RESTRICTED_COMMANDS, SERVICE, } from "./upstash-store.js";
+// The Lua-subset interpreter. Exported because `EVAL` fidelity is a headline claim of this pack and
+// a consumer (or a reviewer) must be able to run a script against it directly.
+export { runLua, parseLua, tokenize, luaScriptSha1, luaTruthy, luaTypeName, luaToNumber, luaEquals, numberToLuaString, LuaError, LuaTable } from "./upstash-lua.js";
+export { createUpstashRedisTwinFetch, createUpstashRedisTwinServer } from "./upstash-server.js";
+export { mapKey, pullUpstashRedisKeys, pullUpstashRedisScan, syncUpstashRedisFromReal, } from "./upstash-connector.js";
+// The client-side rate budget — the fail-closed backstop every live call goes through. The
+// MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives here is this vendor's
+// DECLARATION (window/ceiling/per-method weights) plus `guardUpstashRedisClient`, the choke point
+// the connector entrypoints apply unconditionally. Exported so an operator can inspect spend
+// (`snapshot`) and a caller can catch `UpstashRedisBudgetError` by type; there is deliberately no
+// export that disables the guard.
+export { UPSTASH_BUDGETED_METHODS, UPSTASH_BUDGET_CEILING, UPSTASH_BUDGET_MAX_RETRY_AFTER_S, UPSTASH_BUDGET_WINDOW_MS, UPSTASH_CALL_WEIGHTS, UPSTASH_RATE_BUDGET, UpstashRedisBudget, UpstashRedisBudgetError, upstashBudgetPath, upstashCallWeight, upstashClientBudget, guardUpstashRedisClient, } from "./upstash-budget.js";
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack } from '@volter/world-core';
+import { performUpstashRedisAction, syncUpstashRedisFromRemote } from "./upstash-connector.js";
+import { UPSTASH_RATE_BUDGET as RATE_BUDGET } from "./upstash-budget.js";
+export const pack = {
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+    // the real state system. Moved 2026-09-08.
+    protocol: '2',
+    // A cache moves constantly and a full SCAN of a real keyspace is expensive, so the poll is coarse
+    // and the on-demand path is what a world uses when it needs to know now.
+    refresh: { every: '15m', webhook: false, onDemand: { atMost: '30s' } },
+    stateSystem: { perform: performUpstashRedisAction, refresh: syncUpstashRedisFromRemote },
+    // The round trip is a SET — Redis's own write, idempotent by nature, so a second send on a branch
+    // sets the key again rather than being refused.
+    roundTrip: { method: 'POST', path: '/', body: ['SET', 'round-trip', 'round-trip'], headers: { authorization: 'Bearer round-trip' } },
+    parityOrigin: 'http://twin',
+    shapeParity: 'held',
+    // The SAME object upstash-budget.ts declares at module load — one source of truth, so
+    // registering the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    vendor: 'upstash',
+    // INTERCEPTION — this pack's hosts as DATA (packRegistry HostRule), moved from the injector's
+    // hand table with its reasoning verbatim:
+    // (TOMBSTONE) `azureformrecognizer` used to live here as a bare
+    // `h.endsWith('.cognitiveservices.azure.com')` suffix matcher, with a note that a second Azure
+    // AI twin on that shared domain would need path-prefix disambiguation. That second twin is here
+    // — the `azure` pack's service area 2 serves Azure OpenAI on `/openai/*` — so BOTH claims moved
+    // onto their pack descriptors WITH `pathPattern`s and this hand entry was deleted in the same
+    // change (one home per fact; keeping it would throw at require time). See
+    // packages/twin/azureformrecognizer/src/index.ts and packages/twin/azure/src/index.ts.
+    // Upstash Redis. Every database gets its OWN host under one shared apex —
+    // https://<slug>.upstash.io, where the slug is per-database (both naming generations exist in
+    // the wild: the legacy regional `us1-merry-cat-32748` form and the current
+    // `striking-osprey-20681` form) — so there is no fixed host to match and this needs a SUFFIX
+    // matcher, exactly like azureformrecognizer's per-resource Azure hosts above. Confirmed against
+    // the pack's own connector/README and the vendor's REST docs; global databases use ONE hostname
+    // and Upstash routes internally, so there is no region-suffixed variant to add.
+    //
+    // QStash and Upstash Workflow share the apex too (qstash.upstash.io, qstash-<region>.upstash.io): they are this pack's
+    // `qstash` lane (../qstash/src/), so the suffix takes their hosts and the pack's fetch sends them to the lane. The one
+    // exclusion is Upstash VECTOR (`*-vector.upstash.io`, packages/twin/upstashvector), claimed by that pack's own entry: a
+    // bare suffix would swallow it into this twin. Upstash Search (`*-search.upstash.io`) also lives here and has no twin
+    // yet; when one lands it needs the same treatment, and this comment is the note that says so.
+    hosts: [
+        { suffix: '.upstash.io' },
+        { suffix: '-vector.upstash.io', exclude: true },
+        // the Developer API and the console's pages, the pack's `api` lane (../api/src/index.ts)
+        { host: 'api.upstash.com', pathPattern: '^/v2/(redis|team|teams)(/|$)' },
+        { host: 'console.upstash.com', pathPattern: '^/(login|account/(api|teams)|qstash|invite)(/|$)' },
+    ],
+    // QStash's clients read their base URL from QSTASH_URL (@upstash/qstash's documented override; @upstash/workflow's
+    // Client is a QStash client and reads the same), so the World points it at this twin as well as redirecting the hosts.
+    endpointEnv: {
+        name: 'UPSTASH_TWIN_URL',
+        templates: { QSTASH_URL: '${url}' },
+        note: '@upstash/qstash and @upstash/workflow read QSTASH_URL; the injector also redirects *.upstash.io (Redis databases, QStash) to this twin.',
+    },
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-upstash',
+    resources: ['key'],
+    specSource: 'upstash.com/docs/redis/features/restapi + the installed @upstash/redis@1.35.7 compiled source + LIVE PROBES of a real ephemeral Upstash database (every error string, HTTP status and base64 rule); see spec-sources.json.',
+    description: 'Upstash Redis REST twin — a real stateful Redis keyspace (strings/counters/TTL/hashes/sets/sorted-sets/lists/streams, WRONGTYPE and integer errors, lazy expiry) served over Upstash\'s REST protocol: POST /, path-style GET /get/key, POST /pipeline, POST /multi-exec, Bearer auth with the vendor\'s WRONGPASS 401, and Upstash-Encoding: base64. EVAL/EVALSHA run a Lua-subset INTERPRETER over that same command core, so @upstash/ratelimit\'s own unmodified scripts execute and a limiter genuinely enforces. Clock is injected (no wall-clock reads). Kernel-backed. Its lanes: the Developer API and console (api.upstash.com, console.upstash.com: sign-in, API keys, the QStash page), and QStash with Upstash Workflow (qstash.upstash.io and QSTASH_URL: publish, enqueue, batch, schedules, queues, the DLQs, signing keys, and workflow runs delivered step by step to the app, with waits, notify, cancel and resume).',
+    // Adoption, all in the pack's one home. The `scopes` entries are exact PACKAGE names, not an apex: the `@upstash/` scope
+    // spans several Upstash products, and Vector has its own pack, so it is claimed package by package: the Redis client and
+    // the ratelimiter built on it, and QStash's and Workflow's clients (the qstash lane). Stems: UPSTASH_REDIS_* and KV_REST_*
+    // (the env names Vercel KV, this vendor's Redis under another label, writes into a project), and QSTASH_*.
+    adoption: {
+        pypi: ['upstash-redis', 'upstash-ratelimit', 'qstash', 'upstash-workflow'],
+        sdks: ['@upstash/redis', '@upstash/ratelimit', '@upstash/qstash', '@upstash/workflow'],
+        scopes: ['@upstash/redis', '@upstash/ratelimit', '@upstash/qstash', '@upstash/workflow'],
+        envStems: ['UPSTASHREDIS', 'KVREST', 'QSTASH'],
+    },
+    browserRouting: { apiPathPrefix: '/', loaderHost: 'https://twin.upstash.io' },
+};
+registerPack(pack);
+/** A string of a `Upstash-Encoding: base64` answer as @upstash/redis decodes it: base64 to UTF-8, the bare status `OK`
+ *  excepted, which Upstash leaves raw (upstash-twin.ts, `encodeResult`). */
+const decodeResult = (v) => typeof v === 'string' ? (v === 'OK' ? v : Buffer.from(v, 'base64').toString('utf8')) : Array.isArray(v) ? v.map(decodeResult) : v;
+/** The pack's views of its answers, for a journey step's `view` (scripts/journey-kit.ts). `decoded`: an answer to a
+ *  request sent with `Upstash-Encoding: base64`, as @upstash/redis reads it: each `result` decoded, each `error` as it is,
+ *  for a single command's `{result}` or `{error}` and for a pipeline's or transaction's list of them. */
+export const answerViews = {
+    decoded: (body) => {
+        const one = (item) => (item !== null && typeof item === 'object' && 'result' in item ? { ...item, result: decodeResult(item.result) } : item);
+        return Array.isArray(body) ? body.map(one) : one(body);
+    },
+};

package/dist/src/manifest.d.ts

@@ -0,0 +1,14 @@
+export declare const manifest: {
+    vendor: string;
+    service: string;
+    resources: {
+        Key: {
+            storedAs: string;
+            idPrefix: string;
+        };
+        Script: {
+            storedAs: string;
+            idPrefix: string;
+        };
+    };
+};

package/dist/src/manifest.js

@@ -0,0 +1,8 @@
+export const manifest = {
+    vendor: 'upstash',
+    service: 'upstash',
+    resources: {
+        Key: { storedAs: 'key', idPrefix: 'key' },
+        Script: { storedAs: 'script', idPrefix: 'script' },
+    },
+};

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

@@ -0,0 +1,85 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+import type { UpstashRedisLikeClient } from './upstash-connector.js';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export declare const UPSTASH_BUDGET_WINDOW_MS = 60000;
+/** Weighted units allowed inside one window. See the header for where this number comes from. */
+export declare const UPSTASH_BUDGET_CEILING = 600;
+/** Seconds. A `Retry-After` above this means the credential is throttled hard — fail loudly. */
+export declare const UPSTASH_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by the client method the guard is about to invoke. See the header. */
+export declare const UPSTASH_CALL_WEIGHTS: {
+    /** `scan` — a keyspace WALK, whose cost scales with the customer's database, not the request. */
+    readonly scan: 8;
+    /** Every other modeled call (get/type/ttl/hgetall/smembers/lrange/zrange, and anything unclassified). */
+    readonly other: 2;
+};
+/**
+ * The client methods this pack PRICES BY NAME, as dotted paths into the injected client.
+ *
+ * Two kinds of entry: (a) every method this connector actually calls, and (b) an endpoint the
+ * VENDOR documents in a distinct tier which a consumer can reach through the guarded client even
+ * though this connector never calls it (see the weights section of the header). Used to build the
+ * guarded surface — and, in the pack's own suite, the counting fake.
+ *
+ * NOT a closed list, and not a claim about the injected client's shape. A path the real client does
+ * not have is SKIPPED (this connector's members are optional; inventing one would turn "observe
+ * nothing" into "call something that isn't there"), and a method absent from this list is still
+ * PRICED at `defaultWeight` when a caller reaches for it — an unmodeled endpoint must never be
+ * free, and dropping one would be worse than free because it would be invisible.
+ */
+export declare const UPSTASH_BUDGETED_METHODS: readonly ["get", "type", "ttl", "hgetall", "smembers", "lrange", "zrange", "scan"];
+/** THE PACK'S DECLARATION — pure data, the only Upstash-specific thing in the whole budget. */
+export declare const UPSTASH_RATE_BUDGET: RateBudgetDeclaration;
+/** Price one Upstash Redis call by its client method name (e.g. `get`, `scan`). */
+export declare function upstashCallWeight(method: string): number;
+/** Where UpstashRedis's ledger lives. Token-keyed and cwd-independent by default (the vendor limits per
+ *  credential, so a cwd-scoped ledger would hand the same credential a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
+export declare function upstashBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options for UpstashRedis's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type UpstashRedisBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * UpstashRedis's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof UpstashRedisBudget` means "a budget that accounts against this
+ * vendor's ledger under this vendor's ceiling": another vendor's `RateBudget` (with its own,
+ * possibly larger, ceiling) is NOT assignable where one of these is required.
+ */
+export declare class UpstashRedisBudget extends RateBudget {
+    constructor(opts?: UpstashRedisBudgetOptions);
+}
+export type { RateBudgetErrorKind as UpstashRedisBudgetErrorKind } from '@volter/world-core';
+export { RateBudgetError as UpstashRedisBudgetError } from '@volter/world-core';
+export type UpstashRedisBudgetReservation = RateBudgetReservation;
+export type UpstashRedisBudgetSnapshot = RateBudgetSnapshot;
+/** What every budgeted connector entrypoint accepts. There is deliberately no option that turns the
+ *  guard OFF — only ones that say WHICH ledger and clock to account against. */
+export type UpstashRedisBudgetedOptions = {
+    /** An existing budget to share across calls. Omit and one is constructed. Cannot be null. */
+    budget?: UpstashRedisBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: UpstashRedisBudgetOptions;
+};
+/** Pull the budget wiring out of a caller's opts bag, so an entrypoint can forward it verbatim. */
+export declare function upstashBudgetOf(opts: UpstashRedisBudgetedOptions): UpstashRedisBudgetedOptions;
+/** Is this client already behind a budget? Returns the budget it is behind, if so. */
+export declare function upstashClientBudget(client: unknown): RateBudget | undefined;
+/**
+ * Wrap an INJECTED UpstashRedis client so EVERY call it makes is charged against the shared budget
+ * BEFORE the request goes out. This pack's connector never constructs the transport itself (the
+ * consumer injects a client that satisfies `UpstashRedisLikeClient` structurally), so the guard is a
+ * DECORATOR rather than a factory — which is exactly why every connector entrypoint applies it
+ * UNCONDITIONALLY instead of trusting the caller to have done it.
+ *
+ * IDEMPOTENT: wrapping an already-guarded client returns it unchanged, so a caller who forgot is
+ * protected and a caller who wrapped deliberately is not double-charged.
+ *
+ * A method that THROWS is still inspected: an SDK typically RAISES on a 429 rather than returning
+ * it, and that error's back-off is exactly the signal that must become a persisted cooldown. Losing
+ * it would leave the ledger cheerfully spending into a throttled credential. The original error is
+ * always re-raised afterwards — the budget never swallows a vendor failure — EXCEPT when the
+ * back-off is beyond the cap, where the budget's own louder "stop calling" error takes precedence.
+ */
+export declare function guardUpstashRedisClient(client: UpstashRedisLikeClient, opts?: UpstashRedisBudgetedOptions): UpstashRedisLikeClient;