@volter/twin-upstash 0.1.0 → 0.1.2

package/dist/src/upstash-twin.js

@@ -37,7 +37,7 @@
 //    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 { ownFields, twinResources, worldNow } 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
@@ -185,7 +185,7 @@ export async function handleUpstashRedisTwinRequest(req) {
     const query = new URLSearchParams(rawQuery ?? '');
     const path = (rawPath ?? '/').replace(/\/+$/, '') || '/';
     const headers = lowerHeaders(req.headers);
-    const occurredAt = req.occurredAt ?? new Date().toISOString();
+    const occurredAt = req.occurredAt ?? worldNow();
     // 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')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-upstash",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -37,17 +37,17 @@
     "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
   },
   "dependencies": {
-    "@volter/world-ui": "0.1.0",
+    "@volter/world-ui": "0.1.2",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.0"
+    "@volter/world-core": "2.0.2"
   },
   "devDependencies": {
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",
-    "@volter/world-core": "2.0.0",
+    "@volter/world-core": "2.0.2",
     "@volter/world-tooling": "0.1.0",
     "@upstash/redis": "1.35.7",
     "@upstash/ratelimit": "2.0.8",

package/qstash/src/doors.ts

@@ -5,7 +5,7 @@
 // `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.
+//   endpoint received it (its method, headers and body), when it fell due (`at`) and was sent (`sentAt`), 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
@@ -36,7 +36,7 @@ export async function door(ctx: SemanticsContext, request: Request, report: Catc
     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 }));
+      .map((d) => ({ messageId: d.message_id, retried: d.retried, at: d.at, ...(d.sent_at !== undefined ? { sentAt: d.sent_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') {

package/qstash/src/fetch.ts

@@ -2,7 +2,7 @@
 // World's doors and the lane's gate in front, and the catch-up before all of them. The upstash pack's fetch
 // (../../src/upstash-server.ts) sends it every request for a QStash host, every `/v2/` path (an application reaches QStash
 // at its QSTASH_URL, the pack's own address) and the lane's doors.
-import { bindSemantics, coreFor, createDerivedFetch, crossCutting, semanticsContext, type DerivedFetch, type DerivedSurface } from '@volter/world-core';
+import { bindSemantics, coreFor, worldNow, createDerivedFetch, crossCutting, semanticsContext, type DerivedFetch, type DerivedSurface } from '@volter/world-core';
 import surface from './generated/surface.gen.json' with { type: 'json' };
 import { manifest, spanning } from './manifest.ts';
 import { door, DOOR } from './doors.ts';
@@ -36,7 +36,7 @@ export function createQstashLaneFetch(options: QstashLaneOptions = {}): DerivedF
     let report: CatchUpReport = { delivered: [], retried: [], failed: [] };
     if (!options.readOnly && !catchingUp.has(key)) {
       catchingUp.add(key);
-      try { report = await catchUp(ctx); } finally { catchingUp.delete(key); }
+      try { report = await catchUp(ctx, () => Date.parse((options.clock ?? worldNow)())); } finally { catchingUp.delete(key); }
     }
     const own = await door(ctx, request, report);
     if (own) return own;

package/qstash/src/semantics/delivery.ts

@@ -125,7 +125,7 @@ export type CatchUpReport = { delivered: Row[]; retried: Row[]; failed: Row[] };
 
 type Due = { when: number; order: number; act: (at: SemanticsContext, report: CatchUpReport) => Promise<void> };
 
-function nextDue(ctx: SemanticsContext, until: number): Due | undefined {
+function nextDue(ctx: SemanticsContext, until: number, live: () => number): Due | undefined {
   const due: Due[] = [];
   for (const s of ctx.rowsRaw('Schedule')) {
     if (typeof s.nextScheduleTime === 'number' && s.nextScheduleTime <= until) due.push({ when: s.nextScheduleTime, order: 0, act: (at) => fire(at, s) });
@@ -139,7 +139,7 @@ function nextDue(ctx: SemanticsContext, until: number): Due | undefined {
     const when = Number(m._due);
     if (when > until) continue;
     if (m.state === 'CANCEL_REQUESTED') due.push({ when, order: 2 + Number(m._ordinal) / 1e9, act: (at) => cancelled(at, m) });
-    else if (eligible(ctx, m, all)) due.push({ when, order: 3 + Number(m._ordinal) / 1e9, act: (at, report) => attempt(at, m, report) });
+    else if (eligible(ctx, m, all)) due.push({ when, order: 3 + Number(m._ordinal) / 1e9, act: (at, report) => attempt(at, m, report, live) });
   }
   for (const resource of ['DLQMessage', 'WorkflowDLQMessage']) {
     for (const e of ctx.rowsRaw(resource)) {
@@ -151,14 +151,14 @@ function nextDue(ctx: SemanticsContext, until: number): Due | undefined {
 }
 
 /** Run everything due by the World's instant, in order, each at its own moment. */
-export async function catchUp(ctx: SemanticsContext): Promise<CatchUpReport> {
+export async function catchUp(ctx: SemanticsContext, live: () => number = () => nowMs(ctx)): Promise<CatchUpReport> {
   const until = nowMs(ctx);
   const report: CatchUpReport = { delivered: [], retried: [], failed: [] };
   // a message held behind another (the one before it in its queue or its run) goes once that one has left, so the World
   // clock never runs back: each move happens at its own due time or at the last move's, whichever is later
   let last = 0;
   for (let n = 0; n < 5000; n += 1) {
-    const next = nextDue(ctx, until);
+    const next = nextDue(ctx, until, live);
     if (!next) break;
     last = Math.max(last, next.when);
     await next.act(await ctx.at(iso(last)), report);
@@ -197,9 +197,14 @@ async function move(ctx: SemanticsContext, m: Row, to: string, actor: 'time' | '
   m.state = to;
 }
 
-/** One delivery attempt of a message, at the moment it is due. */
-async function attempt(ctx: SemanticsContext, m: Row, report: CatchUpReport): Promise<void> {
+/** One delivery attempt of a message, at the moment it is due. Its signature is issued when it is sent — the World
+ *  clock as the post leaves (`live`), never before the due time: QStash signs a request when it sends it, and a
+ *  delivery the World makes late (its clock moved past the due time) reaches an application already living at that
+ *  instant, which refuses a token that expired while it waited (dub walk 4: every workflow step after a clock shift
+ *  answered "signature verification failed"). A long catch-up on a running clock signs each post at its own instant. */
+async function attempt(ctx: SemanticsContext, m: Row, report: CatchUpReport, live: () => number): Promise<void> {
   const when = nowMs(ctx);
+  const sentAt = Math.max(when, live());
   const tried = Number(m._attempts ?? 0);
   await move(ctx, m, 'ACTIVE', 'time', { _attempts: tried });
   const published = (m._published ?? {}) as Record<string, string>;
@@ -213,11 +218,11 @@ async function attempt(ctx: SemanticsContext, m: Row, report: CatchUpReport): Pr
   const key = accountOf(ctx, String(m._owner ?? 'world')).current;
   const headers: Record<string, string> = {
     ...base, 'upstash-message-id': String(m.messageId), 'upstash-retried': String(tried),
-    'upstash-signature': sign(body, url, Math.floor(when / 1000), `jwt_${String(m.messageId)}_${tried}`, key),
+    'upstash-signature': sign(body, url, Math.floor(sentAt / 1000), `jwt_${String(m.messageId)}_${tried}`, key),
   };
   const method = String(m.method ?? 'POST');
   const outcome = stated(ctx, url, headers) ?? await post(url, method, headers, body);
-  await ctx.record(DELIVERY, { to: url, message_id: m.messageId, retried: tried, at: ctx.occurredAt, n: ctx.rowsRaw(DELIVERY).length, method, headers, body, status: outcome.status }, `delivery:${String(m.messageId)}:${tried}`);
+  await ctx.record(DELIVERY, { to: url, message_id: m.messageId, retried: tried, at: ctx.occurredAt, sent_at: iso(sentAt), n: ctx.rowsRaw(DELIVERY).length, method, headers, body, status: outcome.status }, `delivery:${String(m.messageId)}:${tried}`);
   const n = tried + 1;
   const response = { _response_status: outcome.status, _response_body: outcome.body, _response_headers: outcome.headers };
   if (outcome.status >= 200 && outcome.status < 300) {

package/src/manifest.ts

@@ -1,6 +1,7 @@
 // Upstash Redis's manifest: the vendor facts Redis's command table does not carry (docs/contributing/architecture.md,
 // "Protocol 3"). The surface is generated (./generated/surface.gen.json, from ../spec/commands by scripts/derive-pack.ts):
-// Redis's command table, one entry per command id with its arity, dispatched by upstash-store.ts. The wire is
+// Redis's command table, one entry per command id with its arity, dispatched by the kernel's Redis command core
+// (@volter/world-core/redis) under this pack's dialect (upstash-store.ts). The wire is
 // Upstash's REST envelope (upstash.com/docs/redis/features/restapi), served by the pack's own fetch
 // (upstash-server.ts over upstash-twin.ts), each form it serves cited to that page there.
 //
@@ -10,7 +11,7 @@
 // kernel would enforce a declared `auth`, so none is declared, as psdb's manifest declares none.
 //
 // THE STATE. Keys and their values are the World's state: each key one world-store subject `key:<name>` (its kind,
-// value, deadline and a write ordinal), each cached script one subject `script:<sha1>` (upstash-store.ts, the
+// value, deadline and a write ordinal), each cached script one subject `script:<sha1>` (the kernel's engine.ts, the
 // KeySpace). No command moves a declared state: a key's TTL is a deadline its reads compare with the World clock, and a
 // key's kind is fixed by the command that creates it (a command against another kind answers WRONGTYPE). So no state
 // machine is declared.