@volter/twin-upstash 0.1.0

package/qstash/src/egress.ts

@@ -0,0 +1,58 @@
+// The QStash lane's one outbound request: a delivery to the publisher's own destination (usually the application inside
+// the World). The catch-up (semantics/delivery.ts) decides what is delivered and when; this performs one request and
+// reports the destination's answer. The colocated twin host runs without the World's injector, so the kernel applies
+// the World's rules before any socket opens: a destination on one of the application's own hostnames (its production
+// URL, which an app in production mode publishes to) reaches the application where it listens (`appDestination`);
+// otherwise `worldEgressRefusal` decides (internal addresses pass; a sealed World refuses the rest), and a refusal is a
+// failed attempt, as an unreachable host is: QStash reports no answer as status -1.
+import { appDestination, deliverToApp } from '@volter/world-core/app-route';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+
+export type Outcome = { status: number; body: string; headers: Record<string, string>; error?: string };
+
+export async function post(url: string, method: string, headers: Record<string, string>, body: string): Promise<Outcome> {
+  if (appDestination(url)) return toApp(url, method, headers, body);
+  const refusal = worldEgressRefusal(url);
+  return refusal !== null ? { status: -1, body: '', headers: {}, error: refusal } : send(url, method, headers, body);
+}
+
+/** The request itself, to a destination the World lets the request out to. */
+async function send(url: string, method: string, headers: Record<string, string>, body: string): Promise<Outcome> {
+  try {
+    const res = await fetch(url, { method, headers, ...(method !== 'GET' && method !== 'HEAD' ? { body } : {}) });
+    const out: Record<string, string> = {};
+    res.headers.forEach((v, k) => { out[k.toLowerCase()] = v; });
+    return { status: res.status, body: await res.text(), headers: out };
+  } catch (error) {
+    return { status: -1, body: '', headers: {}, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** A delivery to the application, answered as the lane's other deliveries are (fetch's defaults: a redirect followed,
+ *  at most 20, a 303, or a 301/302 after a POST, becoming a GET without its body), each hop routed again. */
+async function toApp(url: string, method: string, headers: Record<string, string>, body: string): Promise<Outcome> {
+  let at = url; let m = method; let b: string | undefined = body; const h = { ...headers };
+  for (let hops = 0; ; hops++) {
+    const app = appDestination(at);
+    // leaving the application drops what fetch drops crossing origins
+    if (!app) {
+      for (const k of Object.keys(h)) if (['authorization', 'cookie', 'proxy-authorization'].includes(k.toLowerCase())) delete h[k];
+      return post(at, m, h, b ?? '');
+    }
+    let answer;
+    try {
+      answer = await deliverToApp(app, at, { method: m, headers: h, body: b });
+    } catch (error) {
+      return { status: -1, body: '', headers: {}, error: error instanceof Error ? error.message : String(error) };
+    }
+    const location = answer.headers.location;
+    if (![301, 302, 303, 307, 308].includes(answer.status) || !location) return answer;
+    if (hops >= 20) return { status: -1, body: '', headers: {}, error: 'redirect count exceeded' };
+    at = new URL(location, at).toString();
+    if (answer.status === 303 || ((answer.status === 301 || answer.status === 302) && m === 'POST')) {
+      if (m !== 'HEAD') m = 'GET';
+      b = undefined;
+      for (const k of Object.keys(h)) if (/^content-/i.test(k)) delete h[k];
+    }
+  }
+}

package/qstash/src/fetch.ts

@@ -0,0 +1,46 @@
+// The QStash lane's fetch: QStash's and Workflow's API through the derived dispatch over the two documents' union, with the
+// 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 surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest, spanning } from './manifest.ts';
+import { door, DOOR } from './doors.ts';
+import { gate } from './semantics/account.ts';
+import { catchUp, type CatchUpReport } from './semantics/delivery.ts';
+import { qstashSemantics } from './semantics/index.ts';
+
+export type QstashLaneOptions = { root?: string; readOnly?: boolean; clock?: () => string };
+
+// A catch-up delivers to the application, which may call QStash back while it answers (a workflow's route sends its next
+// step): that request is answered without a catch-up of its own, and the one already running takes up what it publishes.
+const catchingUp = new Set<string>();
+
+export function createQstashLaneFetch(options: QstashLaneOptions = {}): DerivedFetch {
+  const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+  const derived = createDerivedFetch({
+    surface: { ...(surface as unknown as DerivedSurface), spanning },
+    handlers: bindSemantics(manifest, qstashSemantics, scope),
+    core: coreFor(manifest, scope),
+    around: crossCutting(manifest, { readOnly: options.readOnly ?? false, ...scope }),
+    // an operation the lane does not serve, and a path neither document has. Where the documents stop and the lane
+    // decides: QStash's answer to an unknown request is not documented; the lane answers 404 in the Error schema.
+    gap: () => Response.json({ error: 'Not Found' }, { status: 404 }),
+  });
+  return Object.assign(async (request: Request): Promise<Response> => {
+    // a body labelled JSON that does not parse is QStash's 400 (the derived dispatch answers it, `malformedBody`); the
+    // catch-up and the doors in front read no body of it
+    const ctx = await semanticsContext(manifest, request.clone(), DOOR, scope)
+      .catch(() => semanticsContext(manifest, new Request(request.url, { method: request.method, headers: request.headers }), DOOR, scope));
+    const key = options.root ?? '';
+    let report: CatchUpReport = { delivered: [], retried: [], failed: [] };
+    if (!options.readOnly && !catchingUp.has(key)) {
+      catchingUp.add(key);
+      try { report = await catchUp(ctx); } finally { catchingUp.delete(key); }
+    }
+    const own = await door(ctx, request, report);
+    if (own) return own;
+    const admitted = gate(ctx, request);
+    return 'refused' in admitted ? admitted.refused : derived(request);
+  }, { owners: () => derived.owners() });
+}

package/qstash/src/generated/surface.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"openapi","format":"openapi","version":"2.0.0","resources":[{"name":"BulkAction","schema":"BulkAction","fields":[{"name":"actionId","type":"string","nullable":false},{"name":"completedAt","type":"integer","nullable":false},{"name":"createdAt","type":"integer","nullable":false},{"name":"filter","type":"object","nullable":false},{"name":"kind","type":"string","nullable":false,"enum":["cancel"]},{"name":"processed","type":"integer","nullable":false},{"name":"state","type":"string","nullable":false,"enum":["IN_PROGRESS","FINISHED"]},{"name":"total","type":"integer","nullable":false}],"stateCandidates":[{"field":"state","values":["FINISHED","IN_PROGRESS"]}],"expandable":[]},{"name":"Endpoint","schema":"Endpoint","fields":[{"name":"name","type":"string","nullable":false},{"name":"url","type":"string","nullable":false}],"stateCandidates":[],"expandable":[]},{"name":"FlowControlKey","schema":"FlowControlKey","fields":[{"name":"flowControlKey","type":"string","nullable":false},{"name":"isPaused","type":"boolean","nullable":false},{"name":"isPinnedParallelism","type":"boolean","nullable":false},{"name":"isPinnedRate","type":"boolean","nullable":false},{"name":"parallelismCount","type":"integer","nullable":false},{"name":"parallelismMax","type":"integer","nullable":false},{"name":"rateCount","type":"integer","nullable":false},{"name":"rateMax","type":"integer","nullable":false},{"name":"ratePeriod","type":"integer","nullable":false},{"name":"ratePeriodStart","type":"integer","nullable":false},{"name":"waitListSize","type":"integer","nullable":false}],"stateCandidates":[],"expandable":[]},{"name":"LogEntry","schema":"LogEntry","fields":[{"name":"body","type":"string","nullable":false},{"name":"callback","type":"string","nullable":false},{"name":"callbackHeaders","type":"object","nullable":false},{"name":"endpointName","type":"string","nullable":false},{"name":"error","type":"string","nullable":false},{"name":"failureCallback","type":"string","nullable":false},{"name":"failureCallbackHeaders","type":"object","nullable":false},{"name":"header","type":"object","nullable":false},{"name":"label","type":"string","nullable":false},{"name":"labels","type":"array","nullable":false},{"name":"maxRetries","type":"integer","nullable":false},{"name":"messageId","type":"string","nullable":false},{"name":"method","type":"string","nullable":false},{"name":"nextDeliveryTime","type":"integer","nullable":false},{"name":"queueName","type":"string","nullable":false},{"name":"responseBody","type":"string","nullable":false},{"name":"responseHeaders","type":"object","nullable":false},{"name":"responseStatus","type":"integer","nullable":false},{"name":"retryDelayExpression","type":"string","nullable":false},{"name":"scheduleId","type":"string","nullable":false},{"name":"state","type":"string","nullable":false,"enum":["CREATED","ACTIVE","RETRY","ERROR","DELIVERED","FAILED","CANCEL_REQUESTED","CANCELLED"]},{"name":"time","type":"integer","nullable":false},{"name":"timeout","type":"integer","nullable":false},{"name":"topicName","type":"string","nullable":false},{"name":"url","type":"string","nullable":false}],"stateCandidates":[{"field":"state","values":["ACTIVE","CANCELLED","CANCEL_REQUESTED","CREATED","DELIVERED","ERROR","FAILED","RETRY"]}],"expandable":[]},{"name":"Queue","schema":"Queue","fields":[{"name":"createdAt","type":"integer","nullable":false},{"name":"lag","type":"integer","nullable":false},{"name":"name","type":"string","nullable":false},{"name":"parallelism","type":"integer","nullable":false},{"name":"paused","type":"boolean","nullable":false},{"name":"updatedAt","type":"integer","nullable":false}],"stateCandidates":[],"expandable":[]},{"name":"Schedule","schema":"Schedule","fields":[{"name":"body","type":"string","nullable":false},{"name":"callback","type":"string","nullable":false},{"name":"callerIp","type":"string","nullable":false},{"name":"createdAt","type":"integer","nullable":false,"required":true},{"name":"cron","type":"string","nullable":false,"required":true},{"name":"delay","type":"integer","nullable":false},{"name":"destination","type":"string","nullable":false,"required":true},{"name":"failureCallback","type":"string","nullable":false},{"name":"flowControlKey","type":"string","nullable":false},{"name":"header","type":"object","nullable":false},{"name":"isPaused","type":"boolean","nullable":false,"required":true},{"name":"label","type":"string","nullable":false},{"name":"labels","type":"array","nullable":false},{"name":"lastScheduleStates","type":"object","nullable":false},{"name":"lastScheduleTime","type":"integer","nullable":false},{"name":"method","type":"string","nullable":false,"required":true},{"name":"nextScheduleTime","type":"integer","nullable":false},{"name":"parallelism","type":"integer","nullable":false},{"name":"period","type":"integer","nullable":false},{"name":"rate","type":"integer","nullable":false},{"name":"retries","type":"integer","nullable":false},{"name":"retryDelayExpression","type":"string","nullable":false},{"name":"scheduleId","type":"string","nullable":false,"required":true}],"stateCandidates":[],"expandable":[]},{"name":"URLGroup","schema":"URLGroup","fields":[{"name":"createdAt","type":"integer","nullable":false},{"name":"endpoints","type":"array","nullable":false},{"name":"name","type":"string","nullable":false},{"name":"updatedAt","type":"integer","nullable":false}],"stateCandidates":[],"expandable":[]},{"name":"Waiter","schema":"Waiter","fields":[{"name":"deadline","type":"integer","nullable":false},{"name":"headers","type":"object","nullable":false},{"name":"timeoutBody","type":"string","nullable":false},{"name":"timeoutHeaders","type":"object","nullable":false},{"name":"timeoutUrl","type":"string","nullable":false},{"name":"url","type":"string","nullable":false}],"stateCandidates":[],"expandable":[]},{"name":"WorkflowDLQMessage","schema":"WorkflowDLQMessage","fields":[{"name":"body","type":"string","nullable":false},{"name":"bodyBase64","type":"string","nullable":false},{"name":"callerIP","type":"string","nullable":false},{"name":"createdAt","type":"integer","nullable":false},{"name":"dlqId","type":"string","nullable":false},{"name":"failureCallback","type":"string","nullable":false},{"name":"failureFunctionState","type":"string","nullable":false},{"name":"flowControlKey","type":"string","nullable":false},{"name":"header","type":"object","nullable":false},{"name":"label","type":"string","nullable":false},{"name":"labels","type":"array","nullable":false},{"name":"maxRetries","type":"integer","nullable":false},{"name":"method","type":"string","nullable":false},{"name":"responseBody","type":"string","nullable":false},{"name":"responseBodyBase64","type":"string","nullable":false},{"name":"responseHeader","type":"object","nullable":false},{"name":"responseStatus","type":"integer","nullable":false},{"name":"url","type":"string","nullable":false},{"name":"workflowCreatedAt","type":"integer","nullable":false},{"name":"workflowRunId","type":"string","nullable":false},{"name":"workflowUrl","type":"string","nullable":false}],"stateCandidates":[],"expandable":[]},{"name":"WorkflowRun","schema":"WorkflowRun","fields":[{"name":"dlqId","type":"string","nullable":false},{"name":"failureFunction","type":"FailureFunction","nullable":false},{"name":"flowControlKey","type":"string","nullable":false},{"name":"invoker","type":"InvokerContext","nullable":false},{"name":"label","type":"string","nullable":false},{"name":"labels","type":"array","nullable":false},{"name":"steps","type":"array","nullable":false},{"name":"workflowRunCallerIp","type":"string","nullable":false},{"name":"workflowRunCompletedAt","type":"integer","nullable":false},{"name":"workflowRunCreatedAt","type":"integer","nullable":false},{"name":"workflowRunId","type":"string","nullable":false},{"name":"workflowRunResponse","type":"string","nullable":false},{"name":"workflowState","type":"string","nullable":false},{"name":"workflowUrl","type":"string","nullable":false}],"stateCandidates":[],"expandable":[]}],"operations":[{"id":"post_v2_batch","method":"post","path":"/v2/batch","pathParams":[],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"post_v2_batch_trigger","method":"post","path":"/v2/batch/trigger","pathParams":[],"query":[],"body":[],"bodyEncoding":"json","successStatus":201,"class":"non-resource"},{"id":"get_v2_bulkactions","method":"get","path":"/v2/bulkActions","pathParams":[],"query":[{"name":"count","type":"integer","required":false},{"name":"cursor","type":"string","required":false},{"name":"state","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"BulkAction","list":true,"key":"bulkActions"},"class":"list","resource":"BulkAction"},{"id":"get_v2_bulkactions_actionid","method":"get","path":"/v2/bulkActions/{actionId}","pathParams":["actionId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"BulkAction","list":false},"class":"retrieve","resource":"BulkAction"},{"id":"get_v2_dlq","method":"get","path":"/v2/dlq","pathParams":[],"query":[{"name":"callerIp","type":"array","required":false},{"name":"count","type":"integer","required":false},{"name":"cursor","type":"string","required":false},{"name":"fromDate","type":"integer","required":false},{"name":"label","type":"array","required":false},{"name":"messageId","type":"string","required":false},{"name":"queueName","type":"array","required":false},{"name":"responseStatus","type":"array","required":false},{"name":"scheduleId","type":"array","required":false},{"name":"source","type":"string","required":false},{"name":"toDate","type":"integer","required":false},{"name":"topicName","type":"array","required":false},{"name":"url","type":"array","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"delete_v2_dlq","method":"delete","path":"/v2/dlq","pathParams":[],"query":[{"name":"callerIp","type":"array","required":false},{"name":"count","type":"integer","required":false},{"name":"cursor","type":"string","required":false},{"name":"dlqIds","type":"array","required":false},{"name":"flowControlKey","type":"array","required":false},{"name":"fromDate","type":"integer","required":false},{"name":"label","type":"array","required":false},{"name":"messageId","type":"string","required":false},{"name":"queueName","type":"array","required":false},{"name":"responseStatus","type":"array","required":false},{"name":"scheduleId","type":"array","required":false},{"name":"toDate","type":"integer","required":false},{"name":"topicName","type":"array","required":false},{"name":"url","type":"array","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action"},{"id":"get_v2_dlq_dlqid","method":"get","path":"/v2/dlq/{dlqId}","pathParams":["dlqId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"delete_v2_dlq_dlqid","method":"delete","path":"/v2/dlq/{dlqId}","pathParams":["dlqId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete"},{"id":"post_v2_dlq_retry","method":"post","path":"/v2/dlq/retry","pathParams":[],"query":[{"name":"callerIp","type":"array","required":false},{"name":"dlqIds","type":"array","required":false},{"name":"flowControlKey","type":"array","required":false},{"name":"fromDate","type":"integer","required":false},{"name":"label","type":"array","required":false},{"name":"messageId","type":"string","required":false},{"name":"queueName","type":"array","required":false},{"name":"responseStatus","type":"array","required":false},{"name":"scheduleId","type":"array","required":false},{"name":"toDate","type":"integer","required":false},{"name":"topicName","type":"array","required":false},{"name":"url","type":"array","required":false}],"body":[],"bodyEncoding":"none","successStatus":201,"class":"non-resource"},{"id":"post_v2_dlq_retry_dlqid","method":"post","path":"/v2/dlq/retry/{dlqId}","pathParams":["dlqId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":201,"class":"non-resource"},{"id":"post_v2_enqueue_queuename_destination","method":"post","path":"/v2/enqueue/{queueName}/{destination}","pathParams":["queueName","destination","queueName"],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"get_v2_flowcontrol","method":"get","path":"/v2/flowControl","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"FlowControlKey","list":true},"class":"list","resource":"FlowControlKey"},{"id":"get_v2_flowcontrol_flowcontrolkey","method":"get","path":"/v2/flowControl/{flowControlKey}","pathParams":["flowControlKey"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"FlowControlKey","list":false},"class":"retrieve","resource":"FlowControlKey"},{"id":"post_v2_flowcontrol_flowcontrolkey_pause","method":"post","path":"/v2/flowControl/{flowControlKey}/pause","pathParams":["flowControlKey"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"FlowControlKey"},{"id":"post_v2_flowcontrol_flowcontrolkey_pin","method":"post","path":"/v2/flowControl/{flowControlKey}/pin","pathParams":["flowControlKey"],"query":[{"name":"parallelism","type":"integer","required":false},{"name":"period","type":"integer","required":false},{"name":"rate","type":"integer","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"FlowControlKey"},{"id":"post_v2_flowcontrol_flowcontrolkey_resetrate","method":"post","path":"/v2/flowControl/{flowControlKey}/resetRate","pathParams":["flowControlKey"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"FlowControlKey"},{"id":"post_v2_flowcontrol_flowcontrolkey_resume","method":"post","path":"/v2/flowControl/{flowControlKey}/resume","pathParams":["flowControlKey"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"FlowControlKey"},{"id":"post_v2_flowcontrol_flowcontrolkey_unpin","method":"post","path":"/v2/flowControl/{flowControlKey}/unpin","pathParams":["flowControlKey"],"query":[{"name":"parallelism","type":"boolean","required":false},{"name":"rate","type":"boolean","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"FlowControlKey"},{"id":"get_v2_globalparallelism","method":"get","path":"/v2/globalParallelism","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"get_v2_keys","method":"get","path":"/v2/keys","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"get_v2_keys_rotate","method":"get","path":"/v2/keys/rotate","pathParams":["flowControlKey"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"FlowControlKey","list":false},"class":"retrieve","resource":"FlowControlKey"},{"id":"post_v2_keys_rotate","method":"post","path":"/v2/keys/rotate","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"get_v2_logs","method":"get","path":"/v2/logs","pathParams":[],"query":[{"name":"count","type":"integer","required":false},{"name":"cursor","type":"string","required":false},{"name":"fromDate","type":"integer","required":false},{"name":"label","type":"array","required":false},{"name":"messageId","type":"string","required":false},{"name":"queueName","type":"string","required":false},{"name":"scheduleId","type":"string","required":false},{"name":"state","type":"string","required":false},{"name":"toDate","type":"integer","required":false},{"name":"topicName","type":"string","required":false},{"name":"url","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"LogEntry","list":true,"key":"logs"},"class":"list","resource":"LogEntry"},{"id":"delete_v2_messages","method":"delete","path":"/v2/messages","pathParams":[],"query":[{"name":"async","type":"boolean","required":false},{"name":"callerIp","type":"array","required":false},{"name":"callerIP","type":"array","required":false},{"name":"count","type":"integer","required":false},{"name":"flowControlKey","type":"array","required":false},{"name":"fromDate","type":"integer","required":false},{"name":"host","type":"array","required":false},{"name":"label","type":"array","required":false},{"name":"messageIds","type":"array","required":false},{"name":"path","type":"array","required":false},{"name":"queueName","type":"array","required":false},{"name":"scheduleId","type":"array","required":false},{"name":"toDate","type":"integer","required":false},{"name":"topicName","type":"array","required":false},{"name":"url","type":"array","required":false}],"body":[],"bodyEncoding":"none","successStatus":202,"class":"action"},{"id":"get_v2_messages_messageid","method":"get","path":"/v2/messages/{messageId}","pathParams":["messageId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"delete_v2_messages_messageid","method":"delete","path":"/v2/messages/{messageId}","pathParams":["messageId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":202,"class":"delete"},{"id":"post_v2_messages_messageid_retry","method":"post","path":"/v2/messages/{messageId}/retry","pathParams":["messageId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"post_v2_notify_eventid","method":"post","path":"/v2/notify/{eventId}","pathParams":["eventId"],"query":[],"body":[],"bodyEncoding":"json","successStatus":201,"class":"non-resource"},{"id":"post_v2_notify_workflowrunid_eventid","method":"post","path":"/v2/notify/{workflowRunId}/{eventId}","pathParams":["workflowRunId","eventId"],"query":[],"body":[],"bodyEncoding":"json","successStatus":201,"answers":{"resource":"Waiter","list":false,"key":"waiter"},"class":"action","resource":"Waiter"},{"id":"post_v2_publish_destination","method":"post","path":"/v2/publish/{destination}","pathParams":["destination"],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"get_v2_queues","method":"get","path":"/v2/queues","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Queue","list":true},"class":"list","resource":"Queue"},{"id":"post_v2_queues","method":"post","path":"/v2/queues","pathParams":[],"query":[],"body":[{"name":"parallelism","type":"integer","required":true},{"name":"queueName","type":"string","required":true}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"get_v2_queues_queuename","method":"get","path":"/v2/queues/{queueName}","pathParams":["queueName"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Queue","list":false},"class":"retrieve","resource":"Queue"},{"id":"delete_v2_queues_queuename","method":"delete","path":"/v2/queues/{queueName}","pathParams":["queueName"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete","resource":"Queue"},{"id":"post_v2_queues_queuename_pause","method":"post","path":"/v2/queues/{queueName}/pause","pathParams":["queueName"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"Queue"},{"id":"post_v2_queues_queuename_resume","method":"post","path":"/v2/queues/{queueName}/resume","pathParams":["queueName"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"Queue"},{"id":"get_v2_schedules","method":"get","path":"/v2/schedules","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Schedule","list":true},"class":"list","resource":"Schedule"},{"id":"post_v2_schedules_destination","method":"post","path":"/v2/schedules/{destination}","pathParams":["destination"],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"get_v2_schedules_scheduleid","method":"get","path":"/v2/schedules/{scheduleId}","pathParams":["scheduleId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Schedule","list":false},"class":"retrieve","resource":"Schedule"},{"id":"delete_v2_schedules_scheduleid","method":"delete","path":"/v2/schedules/{scheduleId}","pathParams":["scheduleId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete","resource":"Schedule"},{"id":"post_v2_schedules_scheduleid_pause","method":"post","path":"/v2/schedules/{scheduleId}/pause","pathParams":["scheduleId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"Schedule"},{"id":"patch_v2_schedules_scheduleid_pause","method":"patch","path":"/v2/schedules/{scheduleId}/pause","pathParams":["scheduleId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"Schedule"},{"id":"post_v2_schedules_scheduleid_resume","method":"post","path":"/v2/schedules/{scheduleId}/resume","pathParams":["scheduleId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"Schedule"},{"id":"patch_v2_schedules_scheduleid_resume","method":"patch","path":"/v2/schedules/{scheduleId}/resume","pathParams":["scheduleId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action","resource":"Schedule"},{"id":"get_v2_topics","method":"get","path":"/v2/topics","pathParams":[],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"URLGroup","list":true},"class":"list","resource":"URLGroup"},{"id":"get_v2_topics_urlgroupname","method":"get","path":"/v2/topics/{urlGroupName}","pathParams":["urlGroupName"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"URLGroup","list":false},"class":"retrieve","resource":"URLGroup"},{"id":"delete_v2_topics_urlgroupname","method":"delete","path":"/v2/topics/{urlGroupName}","pathParams":["urlGroupName"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete","resource":"URLGroup"},{"id":"post_v2_topics_urlgroupname_endpoints","method":"post","path":"/v2/topics/{urlGroupName}/endpoints","pathParams":["urlGroupName"],"query":[],"body":[{"name":"endpoints","type":"array","required":true}],"bodyEncoding":"json","successStatus":200,"class":"action","resource":"URLGroup"},{"id":"delete_v2_topics_urlgroupname_endpoints","method":"delete","path":"/v2/topics/{urlGroupName}/endpoints","pathParams":["urlGroupName"],"query":[],"body":[{"name":"endpoints","type":"array","required":true}],"bodyEncoding":"json","successStatus":200,"class":"action","resource":"URLGroup"},{"id":"post_v2_trigger_workflowurl","method":"post","path":"/v2/trigger/{workflowUrl}","pathParams":["workflowUrl"],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"post_v2_wait_eventid","method":"post","path":"/v2/wait/{eventId}","pathParams":["eventId"],"query":[],"body":[{"name":"step","type":"object","required":false},{"name":"timeout","type":"string","required":false},{"name":"timeoutBody","type":"string","required":false},{"name":"timeoutHeaders","type":"object","required":false},{"name":"timeoutUrl","type":"string","required":false},{"name":"url","type":"string","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"get_v2_waiters_eventid","method":"get","path":"/v2/waiters/{eventId}","pathParams":["eventId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"Waiter","list":true},"class":"list","resource":"Waiter"},{"id":"get_v2_workflows_bulkactions","method":"get","path":"/v2/workflows/bulkActions","pathParams":[],"query":[{"name":"count","type":"integer","required":false},{"name":"cursor","type":"string","required":false},{"name":"state","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"BulkAction","list":true,"key":"bulkActions"},"class":"list","resource":"BulkAction"},{"id":"get_v2_workflows_bulkactions_actionid","method":"get","path":"/v2/workflows/bulkActions/{actionId}","pathParams":["actionId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"BulkAction","list":false},"class":"retrieve","resource":"BulkAction"},{"id":"get_v2_workflows_dlq","method":"get","path":"/v2/workflows/dlq","pathParams":[],"query":[{"name":"callerIp","type":"array","required":false},{"name":"count","type":"integer","required":false},{"name":"cursor","type":"string","required":false},{"name":"failureFunctionState","type":"array","required":false},{"name":"flowControlKey","type":"array","required":false},{"name":"fromDate","type":"integer","required":false},{"name":"label","type":"array","required":false},{"name":"toDate","type":"integer","required":false},{"name":"workflowCreatedAt","type":"integer","required":false},{"name":"workflowRunId","type":"string","required":false},{"name":"workflowUrl","type":"array","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"WorkflowDLQMessage","list":true,"key":"messages"},"class":"list","resource":"WorkflowDLQMessage"},{"id":"delete_v2_workflows_dlq","method":"delete","path":"/v2/workflows/dlq","pathParams":[],"query":[{"name":"callerIp","type":"array","required":false},{"name":"count","type":"integer","required":false},{"name":"cursor","type":"string","required":false},{"name":"dlqIds","type":"array","required":false},{"name":"failureFunctionState","type":"array","required":false},{"name":"flowControlKey","type":"array","required":false},{"name":"fromDate","type":"integer","required":false},{"name":"label","type":"array","required":false},{"name":"toDate","type":"integer","required":false},{"name":"workflowCreatedAt","type":"integer","required":false},{"name":"workflowRunId","type":"string","required":false},{"name":"workflowUrl","type":"array","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action"},{"id":"get_v2_workflows_dlq_dlqid","method":"get","path":"/v2/workflows/dlq/{dlqId}","pathParams":["dlqId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"WorkflowDLQMessage","list":false},"class":"retrieve","resource":"WorkflowDLQMessage"},{"id":"delete_v2_workflows_dlq_dlqid","method":"delete","path":"/v2/workflows/dlq/{dlqId}","pathParams":["dlqId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete","resource":"WorkflowDLQMessage"},{"id":"post_v2_workflows_dlq_callback_dlqid","method":"post","path":"/v2/workflows/dlq/callback/{dlqId}","pathParams":["dlqId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"delete_v2_workflows_dlq_callback_dlqid","method":"delete","path":"/v2/workflows/dlq/callback/{dlqId}","pathParams":["dlqId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete"},{"id":"post_v2_workflows_dlq_restart","method":"post","path":"/v2/workflows/dlq/restart","pathParams":[],"query":[{"name":"callerIp","type":"array","required":false},{"name":"count","type":"integer","required":false},{"name":"cursor","type":"string","required":false},{"name":"dlqIds","type":"array","required":false},{"name":"failureFunctionState","type":"array","required":false},{"name":"flowControlKey","type":"array","required":false},{"name":"fromDate","type":"integer","required":false},{"name":"label","type":"array","required":false},{"name":"toDate","type":"integer","required":false},{"name":"workflowCreatedAt","type":"integer","required":false},{"name":"workflowRunId","type":"string","required":false},{"name":"workflowUrl","type":"array","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"post_v2_workflows_dlq_restart_dlqid","method":"post","path":"/v2/workflows/dlq/restart/{dlqId}","pathParams":["dlqId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"post_v2_workflows_dlq_resume","method":"post","path":"/v2/workflows/dlq/resume","pathParams":[],"query":[{"name":"callerIp","type":"array","required":false},{"name":"count","type":"integer","required":false},{"name":"cursor","type":"string","required":false},{"name":"dlqIds","type":"array","required":false},{"name":"failureFunctionState","type":"array","required":false},{"name":"flowControlKey","type":"array","required":false},{"name":"fromDate","type":"integer","required":false},{"name":"label","type":"array","required":false},{"name":"toDate","type":"integer","required":false},{"name":"workflowCreatedAt","type":"integer","required":false},{"name":"workflowRunId","type":"string","required":false},{"name":"workflowUrl","type":"array","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"post_v2_workflows_dlq_resume_dlqid","method":"post","path":"/v2/workflows/dlq/resume/{dlqId}","pathParams":["dlqId"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"class":"non-resource"},{"id":"get_v2_workflows_logs","method":"get","path":"/v2/workflows/logs","pathParams":[],"query":[{"name":"callerIp","type":"string","required":false},{"name":"count","type":"integer","required":false},{"name":"cursor","type":"string","required":false},{"name":"flowControlKey","type":"string","required":false},{"name":"fromDate","type":"integer","required":false},{"name":"label","type":"array","required":false},{"name":"state","type":"string","required":false},{"name":"toDate","type":"integer","required":false},{"name":"trimBody","type":"integer","required":false},{"name":"workflowCreatedAt","type":"integer","required":false},{"name":"workflowRunId","type":"string","required":false},{"name":"workflowRuns","type":"string","required":false},{"name":"workflowUrl","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"answers":{"resource":"WorkflowRun","list":true,"key":"runs"},"class":"list","resource":"WorkflowRun"},{"id":"delete_v2_workflows_runs","method":"delete","path":"/v2/workflows/runs","pathParams":[],"query":[{"name":"async","type":"boolean","required":false},{"name":"callerIp","type":"array","required":false},{"name":"count","type":"integer","required":false},{"name":"flowControlKey","type":"array","required":false},{"name":"fromDate","type":"number","required":false},{"name":"host","type":"array","required":false},{"name":"label","type":"array","required":false},{"name":"path","type":"array","required":false},{"name":"toDate","type":"number","required":false},{"name":"workflowRunIds","type":"array","required":false},{"name":"workflowUrl","type":"array","required":false},{"name":"workflowUrlExactMatch","type":"boolean","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"action"},{"id":"delete_v2_workflows_runs_workflowrunid","method":"delete","path":"/v2/workflows/runs/{workflowRunId}","pathParams":["workflowRunId"],"query":[{"name":"cancel","type":"boolean","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"delete"}]}

package/qstash/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"Message":{"actions":[],"states":{"state":["ACTIVE","CANCELLED","CANCEL_REQUESTED","CREATED","DELIVERED","FAILED","RETRY"]},"embeds":{}},"Queue":{"retrieve":"/v2/queues/{queueName}","actions":[],"states":{},"embeds":{}},"Schedule":{"actions":[{"operation":"post_v2_schedules_scheduleid_pause","method":"POST","path":"/v2/schedules/{scheduleId}/pause","field":"isPaused","from":["true"]},{"operation":"post_v2_schedules_scheduleid_pause","method":"POST","path":"/v2/schedules/{scheduleId}/pause","field":"isPaused","from":["false"],"to":"true"},{"operation":"patch_v2_schedules_scheduleid_pause","method":"PATCH","path":"/v2/schedules/{scheduleId}/pause","field":"isPaused","from":["true"]},{"operation":"patch_v2_schedules_scheduleid_pause","method":"PATCH","path":"/v2/schedules/{scheduleId}/pause","field":"isPaused","from":["false"],"to":"true"}],"states":{"isPaused":["false","true"]},"embeds":{}},"URLGroup":{"list":"/v2/topics","retrieve":"/v2/topics/{urlGroupName}","actions":[],"states":{},"embeds":{}},"DLQMessage":{"actions":[],"states":{},"embeds":{}},"WorkflowRun":{"actions":[],"states":{"workflowState":["RUN_CANCELED","RUN_FAILED","RUN_STARTED","RUN_SUCCESS"]},"embeds":{}},"WorkflowDLQMessage":{"list":"/v2/workflows/dlq","actions":[],"states":{},"embeds":{}},"Waiter":{"actions":[],"states":{},"embeds":{}}}}

package/qstash/src/index.ts

@@ -0,0 +1,35 @@
+// The QStash lane of the upstash pack (QStash and Upstash Workflow, one API in two documents), as a plain fetch: the
+// whole pack's fetch (the Redis REST wire, the Developer API and console at api.upstash.com and console.upstash.com, and
+// QStash), whose owners are the operations this lane serves. Its life walks through them: a customer signs in to the
+// console for its QStash token and keys, and publishes, schedules, queues and runs workflows through QStash's API
+// (journeys/customer-life.outline.md).
+import type { DerivedFetch } from '@volter/world-core';
+import { createUpstashRedisTwinFetch } from '../../src/upstash-server.ts';
+import { createQstashLaneFetch, type QstashLaneOptions } from './fetch.ts';
+
+export { manifest } from './manifest.ts';
+export { createQstashLaneFetch } from './fetch.ts';
+
+export function createQstashTwinFetch(options: QstashLaneOptions = {}): DerivedFetch {
+  const lane = createQstashLaneFetch(options);
+  const pack = createUpstashRedisTwinFetch({ ...(options.root !== undefined ? { root: options.root } : {}), ...(options.readOnly !== undefined ? { readOnly: options.readOnly } : {}), qstash: lane });
+  return Object.assign((request: Request) => pack(request), { owners: () => lane.owners() });
+}
+
+/** The pack's views of the lane's answers, for a journey step's `view` (scripts/journey-kit.ts). `steps`: the deliveries
+ *  door's answer with each workflow delivery's body read as `serve()` reads it: its steps, each step's published body
+ *  decoded from base64 (and parsed, where it is JSON). */
+export const answerViews: Record<string, (body: unknown) => unknown> = {
+  steps: (body) => {
+    const b = body as { deliveries?: Array<Record<string, unknown>> };
+    const decode = (s: string): unknown => { const t = Buffer.from(s, 'base64').toString('utf8'); try { return JSON.parse(t); } catch { return t; } };
+    return {
+      ...b,
+      deliveries: (b.deliveries ?? []).map((d) => {
+        let raw: unknown;
+        try { raw = JSON.parse(String(d.body)); } catch { return d; }
+        return Array.isArray(raw) ? { ...d, steps: raw.map((r: Record<string, unknown>) => ({ ...r, body: decode(String(r.body ?? '')) })) } : d;
+      }),
+    };
+  },
+};

package/qstash/src/manifest.ts

@@ -0,0 +1,134 @@
+// Upstash QStash and Upstash Workflow, the `qstash` lane of the upstash pack: one API published as two OpenAPI documents
+// (docs/contributing/architecture.md, "Other wires"). Upstash publishes qstash/openapi.yaml and workflow/openapi.yaml, both
+// served at https://qstash-{region}.upstash.io with one key set and sharing endpoints; the lane vendors both as published
+// (../spec/openapi/) and its surface is their union (./generated/surface.gen.json, by `bun scripts/derive-pack.ts
+// upstash/qstash`). This manifest holds the vendor facts neither document carries, and the machines of the states the lane
+// moves. The lane writes the pack's one store (`upstash`), beside the Redis keys and the console's records.
+//
+// A WORKFLOW IS QSTASH MESSAGES. "Upstash Workflow is built on top of Upstash QStash" and "Each step is executed in its
+// own HTTP call to your application" (https://upstash.com/docs/workflow/basics/how): @upstash/workflow starts a run and
+// sends each step through the QStash batch endpoint with its `Upstash-Workflow-*` headers, and QStash delivers each step
+// to the app's workflow route as it delivers any message. So a run's steps are messages, moved by the message machine
+// below, and the run has its own machine over them.
+//
+// NO `auth`: QStash reads its token as `Authorization: Bearer <QSTASH_TOKEN>` or as the `qstash_token` query parameter
+// (both documents' `securitySchemes`: bearerAuth and bearerAuthQuery), and a token belongs to the account the console
+// shows it to, which the kernel's gate cannot read; the lane's gate (semantics/account.ts) reads both.
+//
+// ERRORS: every refusal both documents give is the `Error` schema, `{"error": "<message>"}`; the documents name a
+// refusal's status and cause ("Message not found") and never its message text. Where the documentation stops: each
+// message below states the rule in the documents' words, not a text Upstash was seen to send.
+import type { DerivedManifest, StateField } from '@volter/world-core';
+
+/** The path parameters whose values hold slashes: a destination is a whole URL (`/v2/publish/https://example.com/x`). */
+export const spanning = ['destination', 'workflowUrl'];
+
+/** The hosts the lane serves: "https://qstash-{region}.upstash.io" with the regions us-east-1 and eu-central-1 (both
+ *  documents' `servers`), and qstash.upstash.io, the host Upstash's pages send their examples to. An application pointed at
+ *  the World through QSTASH_URL reaches the lane at the pack's own address instead. SHAPE judges the lane's life on these. */
+export const hosts = [{ host: 'qstash-us-east-1.upstash.io' }, { host: 'qstash-eu-central-1.upstash.io' }, { host: 'qstash.upstash.io' }];
+
+const LIFECYCLE = 'https://upstash.com/docs/qstash/howto/debug-logs';
+const RETRY = 'https://upstash.com/docs/qstash/features/retry';
+const CANCEL = 'spec:/documents/qstash/paths/~1v2~1messages~1{messageId}/delete "Cancel a pending message"';
+
+/** A message's `state`: the state its log answers (the message's own view has no state field). "When a message is ready
+ *  for execution, it will be become ACTIVE and a delivery to your API is attempted. If you API responds with a status code
+ *  between 200 - 299, the task is considered successful and will be marked as DELIVERED. Otherwise the message is being
+ *  retried if there are any retries left and moves to RETRY. If all retries are exhausted, the task has FAILED and the
+ *  message will be moved to the DLQ." (debug-logs). A cancel logs CANCEL_REQUESTED, and "If retries are not exhausted
+ *  yet, in the next deliver time, the message will be marked as CANCELLED" (the same page). A retry falls due on the World
+ *  clock (`min(86400, e^(2.5n))` seconds, the retry page). ERROR is the log's record of a failed attempt, written beside
+ *  the move to RETRY or FAILED: not a state the message rests in. Not made by the lane: a delivery in flight when a cancel
+ *  arrives (ACTIVE → CANCEL_REQUESTED): the lane's attempt is over before any request is answered. */
+const messageState: StateField = {
+  initial: 'CREATED',
+  transitions: [
+    { actor: 'time', from: ['CREATED'], to: 'ACTIVE', source: LIFECYCLE },
+    { actor: 'vendor', from: ['ACTIVE'], to: 'DELIVERED', source: LIFECYCLE },
+    { actor: 'vendor', from: ['ACTIVE'], to: 'RETRY', source: RETRY },
+    { actor: 'vendor', from: ['ACTIVE'], to: 'FAILED', source: LIFECYCLE },
+    { actor: 'time', from: ['RETRY'], to: 'ACTIVE', source: RETRY },
+    { operation: 'delete_v2_messages_messageid', from: ['CREATED', 'RETRY'], to: 'CANCEL_REQUESTED', refusal: { status: 404, message: 'Message not found.' }, source: CANCEL },
+    // a run canceled cancels the steps it still owes
+    { operation: 'delete_v2_workflows_runs', from: ['CREATED', 'RETRY'], to: 'CANCEL_REQUESTED', source: 'spec:/documents/workflow/paths/~1v2~1workflows~1runs/delete "Cancel all matching workflow runs."' },
+    { actor: 'time', from: ['CANCEL_REQUESTED'], to: 'CANCELLED', source: LIFECYCLE },
+  ],
+};
+
+const RUN_STATES = 'https://upstash.com/docs/workflow/basics/client/logs';
+const RUN_CANCEL = 'spec:/documents/workflow/paths/~1v2~1workflows~1runs~1{workflowRunId}/delete "Cancel an ongoing workflow run."';
+const RUNS_CANCEL = 'spec:/documents/workflow/paths/~1v2~1workflows~1runs/delete "Cancel all matching workflow runs."';
+
+/** A workflow run's `workflowState`: "RUN_STARTED The workflow run is in progress. RUN_SUCCESS The workflow run completed
+ *  successfully. RUN_FAILED The run failed after all retries. RUN_CANCELED The run was manually canceled." (the client's
+ *  logs page). A run succeeds when its route function returns: `serve()` then reports it finished with
+ *  `DELETE /v2/workflows/runs/{workflowRunId}?cancel=false` (the spec patch's `cancel`, from @upstash/workflow's source);
+ *  `client.cancel` cancels through the bulk `DELETE /v2/workflows/runs?workflowRunIds=`. A run fails when a step's message
+ *  is FAILED. A run in the DLQ is resumed as a new run with a new id ("A new workflow run ID is generated",
+ *  https://upstash.com/docs/workflow/api-reference/dlq/resume-workflow-from-dlq), so the failed run never moves again. */
+const runState: StateField = {
+  initial: 'RUN_STARTED',
+  transitions: [
+    { operation: 'delete_v2_workflows_runs_workflowrunid', from: ['RUN_STARTED'], to: 'RUN_SUCCESS', refusal: { status: 404, message: 'A workflow run is not found with the given id.' }, source: RUN_STATES },
+    { operation: 'delete_v2_workflows_runs_workflowrunid', from: ['RUN_STARTED'], to: 'RUN_CANCELED', refusal: { status: 404, message: 'A workflow run is not found with the given id.' }, source: RUN_CANCEL },
+    { operation: 'delete_v2_workflows_runs', from: ['RUN_STARTED'], to: 'RUN_CANCELED', source: RUNS_CANCEL },
+    { actor: 'vendor', from: ['RUN_STARTED'], to: 'RUN_FAILED', source: RUN_STATES },
+  ],
+};
+
+/** A schedule's `isPaused`: "When a schedule is paused, the cron trigger will simply be ignored. If the schedule is
+ *  already paused, this action has no effect." (the spec's pause). The stay is declared first: an ask naming no target
+ *  takes the first transition that allows it. Not made by the lane: resume (no customer of the life resumes a schedule;
+ *  its operation is the gap). */
+const SCHEDULE_PAUSE = 'spec:/documents/qstash/paths/~1v2~1schedules~1{scheduleId}~1pause/post "If the schedule is already paused, this action has no effect."';
+const schedulePaused: StateField = {
+  initial: false,
+  transitions: [
+    { operation: 'post_v2_schedules_scheduleid_pause', from: ['true'], source: SCHEDULE_PAUSE },
+    { operation: 'post_v2_schedules_scheduleid_pause', from: ['false'], to: 'true', source: SCHEDULE_PAUSE },
+    // the clients' PATCH form of the same operation (the spec patch)
+    { operation: 'patch_v2_schedules_scheduleid_pause', from: ['true'], source: SCHEDULE_PAUSE },
+    { operation: 'patch_v2_schedules_scheduleid_pause', from: ['false'], to: 'true', source: SCHEDULE_PAUSE },
+  ],
+};
+
+export const manifest: DerivedManifest = {
+  vendor: 'upstash',
+  service: 'upstash',
+  body: {},
+  // QStash mints a message id `msg_…`, a schedule id `scd_…` and a workflow run id `wfr_…` (the pages' examples:
+  // msg_xxx, scd_xxx, wfr_abc123); the lane's handlers mint them, and a trigger may name its own run id
+  // (`workflowRunId`, https://upstash.com/docs/workflow/basics/client/trigger)
+  ids: { template: '{prefix}{n}', acceptProvided: true },
+  // createdAt, notBefore and a waiter's deadline are Unix times
+  time: 'unix',
+  error: { error: '{message}' },
+  readOnly: { status: 405, message: 'This twin is read-only: omit readOnly to accept writes.' },
+  malformedBody: { status: 400, message: 'The request body is not valid JSON.' },
+  notFound: { status: 404, message: 'Not found.' },
+  // every list is a handler's (the DLQ's `{messages, cursor}`, a bare array of queues); required by the type, nothing
+  // reads it
+  list: { style: 'envelope', envelope: { messages: '{data}', cursor: '{next_cursor}' }, limit: { param: 'count', default: 100, max: 100 }, cursor: { param: 'cursor', encoding: 'base64-offset' } },
+  deleted: {},
+  // the operations of a declared resource the lane does not serve: the gap
+  unmodeled: [
+    'get_v2_dlq_dlqid', 'delete_v2_dlq_dlqid', 'get_v2_queues', 'get_v2_schedules', 'get_v2_schedules_scheduleid',
+    'get_v2_waiters_eventid', 'get_v2_workflows_dlq_dlqid', 'delete_v2_workflows_dlq_dlqid', 'get_v2_workflows_logs',
+  ],
+  resources: {
+    // the message is not a resource of either document (GET /v2/messages/{messageId} answers `Message`, a view): its
+    // state is what its log answers
+    Message: { storedAs: 'qstash_message', idPrefix: 'msg_', state: { state: messageState } },
+    // a queue is made by its first enqueue or its upsert and holds its messages in order, paused or not
+    Queue: { storedAs: 'qstash_queue', idPrefix: '' },
+    Schedule: { storedAs: 'qstash_schedule', idPrefix: 'scd_', state: { isPaused: schedulePaused } },
+    // a URL group (a topic): its endpoints, keyed by its account and name
+    URLGroup: { storedAs: 'qstash_url_group', idPrefix: '' },
+    DLQMessage: { storedAs: 'qstash_dlq', idPrefix: '' },
+    WorkflowRun: { storedAs: 'workflow_run', idPrefix: 'wfr_', state: { workflowState: runState } },
+    WorkflowDLQMessage: { storedAs: 'workflow_dlq', idPrefix: '' },
+    // a waiter is present while a run waits on its event id, and gone when notified, timed out or canceled
+    Waiter: { storedAs: 'workflow_waiter', idPrefix: '' },
+  },
+};

package/qstash/src/semantics/account.ts

@@ -0,0 +1,98 @@
+// A QStash account: its token and its two signing keys. Every Upstash account has QStash; the console's QStash page
+// shows its `QSTASH_TOKEN` and its `QSTASH_CURRENT_SIGNING_KEY` and `QSTASH_NEXT_SIGNING_KEY` ("copy the `QSTASH_TOKEN`
+// from the **Quickstart** section", https://upstash.com/docs/qstash/overall/getstarted) and resets the token ("Resetting
+// your token will invalidate your current token and all future requests with the old token will be rejected",
+// https://upstash.com/docs/qstash/howto/reset-token). Rolling the keys makes the next key the current one and a new next
+// ("currentKey = nextKey / nextKey = generateNewKey()", https://upstash.com/docs/qstash/howto/roll-signing-keys).
+//
+// A person's account is their console email (the api lane's sign-in, ../../../api/src/screens/session.tsx). A token the
+// console never showed is the World's own account's, as every token is for the pack root's Redis: an application pointed
+// at the World (Dub) carries whatever token its configuration holds, and the World starts the twin with the signing keys
+// it gave the application (QSTASH_CURRENT_SIGNING_KEY, QSTASH_NEXT_SIGNING_KEY).
+//
+// Where the documentation stops and the twin decides: a token has the form the local development page prints
+// (base64 of `{"UserID":…,"Password":…}`) and a key the form it prints (`sig_` and 28 characters); both are derived from the
+// account and how many times it was reset or rolled, so a World shows the same values every run. A request with no token
+// answers 401 {"error": "Unauthorized"} (the documents' 401 is "Unauthorized"); a reset token answers the same.
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+import type { Row } from './shared.ts';
+
+export const ACCOUNT = '_qstash_account';
+/** The account a token no person was shown belongs to. */
+export const WORLD_ACCOUNT = 'world';
+
+const hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+function tokenAt(owner: string, generation: number): string {
+  const h = hex(`qstash-token:${owner}:${generation}`);
+  const userId = `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
+  return Buffer.from(JSON.stringify({ UserID: userId, Password: h.slice(32, 64) }), 'utf8').toString('base64');
+}
+
+function keyAt(owner: string, n: number): string {
+  if (owner === WORLD_ACCOUNT && n === 0 && process.env.QSTASH_CURRENT_SIGNING_KEY) return process.env.QSTASH_CURRENT_SIGNING_KEY;
+  if (owner === WORLD_ACCOUNT && n === 1 && process.env.QSTASH_NEXT_SIGNING_KEY) return process.env.QSTASH_NEXT_SIGNING_KEY;
+  const h = hex(`qstash-signing-key:${owner}:${n}`);
+  let out = '';
+  for (let i = 0; out.length < 28; i += 1) out += ALPHABET[parseInt(h.slice((i * 2) % 62, (i * 2) % 62 + 2), 16) % ALPHABET.length];
+  return `sig_${out}`;
+}
+
+/** How many times an account's token was reset and its keys rolled. */
+function countsOf(ctx: SemanticsContext, owner: string): { resets: number; rolls: number } {
+  const row = ctx.rowsRaw(ACCOUNT).find((a) => a.id === owner) as Row | undefined;
+  return { resets: Number(row?.resets ?? 0), rolls: Number(row?.rolls ?? 0) };
+}
+
+/** An account's token and signing keys as they are now. */
+export function accountOf(ctx: SemanticsContext, owner: string): { owner: string; token: string; current: string; next: string } {
+  const { resets, rolls } = countsOf(ctx, owner);
+  return { owner, token: tokenAt(owner, resets), current: keyAt(owner, rolls), next: keyAt(owner, rolls + 1) };
+}
+
+/** The console's Reset token: the old token is refused from now on. */
+export async function resetToken(ctx: SemanticsContext, owner: string): Promise<string> {
+  const { resets, rolls } = countsOf(ctx, owner);
+  await ctx.record(ACCOUNT, { resets: resets + 1, rolls }, owner);
+  return tokenAt(owner, resets + 1);
+}
+
+/** Roll the signing keys: the next key becomes the current one, and a new next key is made. */
+export async function rollKeys(ctx: SemanticsContext, owner: string): Promise<{ current: string; next: string }> {
+  const { resets, rolls } = countsOf(ctx, owner);
+  await ctx.record(ACCOUNT, { resets, rolls: rolls + 1 }, owner);
+  return { current: keyAt(owner, rolls + 1), next: keyAt(owner, rolls + 2) };
+}
+
+/** The token a request presents: `Authorization: Bearer <token>` or `?qstash_token=` (bearerAuth, bearerAuthQuery). */
+export function tokenOf(request: Request): string | undefined {
+  const bearer = /^bearer\s+(\S+)\s*$/i.exec(request.headers.get('authorization') ?? '');
+  const query = new URL(request.url).searchParams.get('qstash_token');
+  return bearer?.[1] ?? (query && query.trim() !== '' ? query.trim() : undefined);
+}
+
+/** The account a token names: a person's current token names their account; a token a person was shown before a reset
+ *  is refused; any other is the World's own account's. */
+export function ownerOfToken(ctx: SemanticsContext, token: string): string | 'refused' {
+  const people = ctx.rowsRaw('_person').map((p) => ({ email: String(p.email), resets: countsOf(ctx, String(p.email)).resets }));
+  const current = people.find((p) => token === tokenAt(p.email, p.resets));
+  if (current) return current.email;
+  return people.some((p) => resetAway(p, token)) ? 'refused' : WORLD_ACCOUNT;
+}
+
+/** Whether a token is one a person held before they reset it: "Resetting your token will invalidate your current token and
+ *  all future requests with the old token will be rejected." (https://upstash.com/docs/qstash/howto/reset-token) */
+function resetAway(p: { email: string; resets: number }, token: string): boolean {
+  for (let g = 0; g < p.resets; g += 1) if (token === tokenAt(p.email, g)) return true;
+  return false;
+}
+
+/** The lane's gate: the account a request acts as, or the refusal it answers. */
+export function gate(ctx: SemanticsContext, request: Request): { owner: string } | { refused: Response } {
+  const token = tokenOf(request);
+  const owner = token ? ownerOfToken(ctx, token) : 'refused';
+  if (owner === 'refused') return { refused: Response.json({ error: 'Unauthorized' }, { status: 401 }) };
+  return { owner };
+}