@volter/twin-upstash 0.1.0

package/dist/qstash/src/manifest.js

@@ -0,0 +1,105 @@
+/** 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 = {
+    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 = {
+    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 = {
+    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 = {
+    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/dist/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/dist/qstash/src/semantics/account.d.ts

@@ -0,0 +1,29 @@
+import type { SemanticsContext } from '@volter/world-core';
+export declare const ACCOUNT = "_qstash_account";
+/** The account a token no person was shown belongs to. */
+export declare const WORLD_ACCOUNT = "world";
+/** An account's token and signing keys as they are now. */
+export declare function accountOf(ctx: SemanticsContext, owner: string): {
+    owner: string;
+    token: string;
+    current: string;
+    next: string;
+};
+/** The console's Reset token: the old token is refused from now on. */
+export declare function resetToken(ctx: SemanticsContext, owner: string): Promise<string>;
+/** Roll the signing keys: the next key becomes the current one, and a new next key is made. */
+export declare function rollKeys(ctx: SemanticsContext, owner: string): Promise<{
+    current: string;
+    next: string;
+}>;
+/** The token a request presents: `Authorization: Bearer <token>` or `?qstash_token=` (bearerAuth, bearerAuthQuery). */
+export declare function tokenOf(request: Request): string | 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 declare function ownerOfToken(ctx: SemanticsContext, token: string): string | 'refused';
+/** The lane's gate: the account a request acts as, or the refusal it answers. */
+export declare function gate(ctx: SemanticsContext, request: Request): {
+    owner: string;
+} | {
+    refused: Response;
+};

package/dist/qstash/src/semantics/account.js

@@ -0,0 +1,91 @@
+// 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';
+export const ACCOUNT = '_qstash_account';
+/** The account a token no person was shown belongs to. */
+export const WORLD_ACCOUNT = 'world';
+const hex = (s) => createHash('sha256').update(s).digest('hex');
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+function tokenAt(owner, generation) {
+    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, n) {
+    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, owner) {
+    const row = ctx.rowsRaw(ACCOUNT).find((a) => a.id === owner);
+    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, owner) {
+    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, owner) {
+    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, owner) {
+    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) {
+    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, token) {
+    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, token) {
+    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, request) {
+    const token = tokenOf(request);
+    const owner = token ? ownerOfToken(ctx, token) : 'refused';
+    if (owner === 'refused')
+        return { refused: Response.json({ error: 'Unauthorized' }, { status: 401 }) };
+    return { owner };
+}

package/dist/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 };
+}

package/dist/qstash/src/semantics/delivery.d.ts

@@ -0,0 +1,17 @@
+import type { SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** The World's word on what a destination answers, stored by `POST /_twin/destinations` (../doors.ts). */
+export declare const DESTINATION = "_qstash_destination";
+/** What a destination received, read at `GET /_twin/deliveries?to=` (../doors.ts). */
+export declare const DELIVERY = "_qstash_delivery";
+/** An `Upstash-Retry-Delay` expression's value in milliseconds: numbers, `retried`, `+ - * /`, parentheses and `pow sqrt
+ *  abs exp floor ceil round min max` (the retry page's Custom Retry Delay); anything else is undefined. */
+export declare function retryDelayMs(expr: string, retried: number): number | undefined;
+/** What a catch-up did: the deliveries it made, by outcome (the drain door answers it). */
+export type CatchUpReport = {
+    delivered: Row[];
+    retried: Row[];
+    failed: Row[];
+};
+/** Run everything due by the World's instant, in order, each at its own moment. */
+export declare function catchUp(ctx: SemanticsContext): Promise<CatchUpReport>;