@volter/twin-upstash 0.1.0

package/dist/qstash/src/semantics/schedules.ts

@@ -0,0 +1,132 @@
+// Schedules: "you can create a schedule, and we will publish the message in the given period. To create a schedule, you
+// simply need to add the `Upstash-Cron` header to your `publish` request." "By default, we evaluate cron expressions in
+// `UTC`." (https://upstash.com/docs/qstash/features/schedules). The catch-up publishes a schedule's message each time
+// its cron fires (delivery.ts); a paused schedule's trigger "will simply be ignored" (the spec's pause).
+//
+// "If you want to run your schedule in a specific timezone, see the section on Timezones": a `CRON_TZ=<IANA zone>` prefix
+// evaluates the expression in that zone ("CRON_TZ=America/New_York 0 4 * * *", the same page). `Upstash-Queue-Name` enqueues
+// each message the schedule publishes into that queue (the page's "Scheduling to a Queue").
+// Where the documentation stops and the lane decides: the cron is the five standard fields (minute, hour, day of month,
+// month, day of week) with `*`, lists, ranges and steps; a zone the runtime does not know answers 400; a
+// schedule is first due at its cron's first minute after it is made ("It can take up to 60 seconds for the schedule to be
+// loaded on an active node and triggered for the first time": the lane loads it at once).
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { ownerFor, labelsOf, sentHeader } from './messages.ts';
+import { durationSeconds, everHeld, headersOf, mintId, nowMs, refuse, type Row } from './shared.ts';
+
+type Field = Set<number>;
+
+function field(spec: string, min: number, max: number): Field | undefined {
+  const out = new Set<number>();
+  for (const part of spec.split(',')) {
+    const m = /^(\*|\d+(?:-\d+)?)(?:\/(\d+))?$/.exec(part);
+    if (!m) return undefined;
+    const [lo, hi] = m[1] === '*' ? [min, max] : m[1]!.includes('-') ? m[1]!.split('-').map(Number) as [number, number] : [Number(m[1]), m[2] ? max : Number(m[1])];
+    const step = m[2] ? Number(m[2]) : 1;
+    if (lo < min || hi > max || lo > hi || step < 1) return undefined;
+    for (let v = lo; v <= hi; v += step) out.add(v);
+  }
+  return out;
+}
+
+type Cron = { minute: Field; hour: Field; dom: Field; month: Field; dow: Field; domAny: boolean; dowAny: boolean; zone: string };
+
+/** A cron expression's fields and zone, or undefined when it is not one the lane reads. */
+export function parseCron(expr: string): Cron | undefined {
+  const tz = /^CRON_TZ=(\S+)\s+/.exec(expr.trim());
+  const zone = tz?.[1] ?? 'UTC';
+  try { new Intl.DateTimeFormat('en-US', { timeZone: zone }); } catch { return undefined; }
+  const parts = expr.trim().replace(/^CRON_TZ=\S+\s+/, '').split(/\s+/);
+  if (parts.length !== 5) return undefined;
+  const [mi, h, dom, mo, dow] = parts as [string, string, string, string, string];
+  const f = { minute: field(mi, 0, 59), hour: field(h, 0, 23), dom: field(dom, 1, 31), month: field(mo, 1, 12), dow: field(dow.replace(/\b7\b/g, '0'), 0, 6) };
+  if (!f.minute || !f.hour || !f.dom || !f.month || !f.dow) return undefined;
+  return { minute: f.minute, hour: f.hour, dom: f.dom, month: f.month, dow: f.dow, domAny: dom === '*', dowAny: dow === '*', zone };
+}
+
+/** The wall clock in a zone at an instant: month, day of month, day of week, hour, minute. */
+function wall(ms: number, zone: string): { month: number; dom: number; dow: number; hour: number; minute: number } {
+  const parts = Object.fromEntries(new Intl.DateTimeFormat('en-US', { timeZone: zone, hourCycle: 'h23', month: 'numeric', day: 'numeric', weekday: 'short', hour: 'numeric', minute: 'numeric' })
+    .formatToParts(new Date(ms)).map((x) => [x.type, x.value]));
+  const dow = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].indexOf(String(parts.weekday));
+  return { month: Number(parts.month), dom: Number(parts.day), dow, hour: Number(parts.hour) % 24, minute: Number(parts.minute) };
+}
+
+/** The first minute after `afterMs` the cron fires at, its fields read on the wall clock of its zone. Day of month and day
+ *  of week, both restricted, fire on either (the classic cron rule). A day or hour that cannot match is skipped whole. */
+export function nextFire(expr: string, afterMs: number): number | undefined {
+  const c = parseCron(expr);
+  if (!c) return undefined;
+  let t = Math.floor(afterMs / 60_000) * 60_000 + 60_000;
+  const end = t + 366 * 86_400_000;
+  for (let skip = skipFrom(c, t); skip > 0 && t < end; skip = skipFrom(c, t)) t += skip;
+  return t < end ? t : neverFires();
+}
+
+/** How far past the minute `t` the cron's next candidate is: 0 when it fires at `t`, the rest of the day when the day
+ *  cannot match, the rest of the hour when the hour cannot, else a minute. */
+function skipFrom(c: Cron, t: number): number {
+  const w = wall(t, c.zone);
+  const dayOk = c.domAny && c.dowAny ? true : c.domAny ? c.dow.has(w.dow) : c.dowAny ? c.dom.has(w.dom) : c.dom.has(w.dom) || c.dow.has(w.dow);
+  if (!c.month.has(w.month) || !dayOk) return (60 - w.minute) * 60_000 + (23 - w.hour) * 3_600_000;
+  if (!c.hour.has(w.hour)) return (60 - w.minute) * 60_000;
+  return c.minute.has(w.minute) ? 0 : 60_000;
+}
+
+/** A cron no minute of the coming year meets (`0 0 30 2 *`, the 30th of February): it has no next time. */
+function neverFires(): undefined {
+  return undefined;
+}
+
+/** POST /v2/schedules/{destination}: a schedule of the message the request describes (its body, its `Upstash-*` headers),
+ *  answered `{scheduleId}`. `Upstash-Schedule-Id` names a schedule to create or overwrite (the spec's parameter). */
+const createSchedule: Semantics = async (ctx) => {
+  const destination = String(ctx.call.params.destination ?? '');
+  const h = headersOf(ctx);
+  const cron = h['upstash-cron'];
+  if (!cron) return refuse(ctx, 400, 'Upstash-Cron header is required');
+  const owner = ownerFor(ctx);
+  if (!/^https?:\/\//.test(destination) && !ctx.rowsRaw('URLGroup').some((g) => g.name === destination && g._owner === owner)) return refuse(ctx, 404, `URL Group ${destination} not found`);
+  const next = nextFire(cron, nowMs(ctx));
+  if (next === undefined) return refuse(ctx, 400, `invalid cron expression: ${cron}`);
+  const id = h['upstash-schedule-id'] ?? mintId(ctx, 'scd_', 'schedule', everHeld(ctx, 'Schedule'));
+  const retries = h['upstash-retries'] !== undefined && /^\d+$/.test(h['upstash-retries']) ? Number(h['upstash-retries']) : 3;
+  const fields: Row = {
+    scheduleId: id, cron, destination, createdAt: nowMs(ctx), method: h['upstash-method'] ?? 'POST', header: sentHeader(h), body: ctx.text ?? '',
+    retries, ...(durationSeconds(h['upstash-delay']) ? { delay: durationSeconds(h['upstash-delay']) } : {}),
+    ...(h['upstash-callback'] ? { callback: h['upstash-callback'] } : {}), ...(h['upstash-failure-callback'] ? { failureCallback: h['upstash-failure-callback'] } : {}),
+    isPaused: false, nextScheduleTime: next, ...labelsOf(h),
+    ...(h['upstash-queue-name'] ? { _queue: h['upstash-queue-name'] } : {}),
+    _owner: owner, _published: h,
+  };
+  await ctx.write('Schedule', id, fields, 'schedule.create');
+  return ctx.reply({ scheduleId: id });
+};
+
+const scheduleOf = (ctx: SemanticsContext): Row | undefined => ctx.rowsRaw('Schedule').find((s) => s.scheduleId === String(ctx.call.params.scheduleId));
+
+/** POST /v2/schedules/{scheduleId}/pause, and the PATCH the vendor's clients send (the spec patch): its cron is ignored from
+ *  now on. Answered 200 with no body. */
+const pause: Semantics = async (ctx) => {
+  const s = scheduleOf(ctx);
+  if (!s) return refuse(ctx, 404, 'Schedule not found.');
+  const refused = ctx.legal('Schedule', 'isPaused', ctx.call.operation.id, s.isPaused === true);
+  if (refused) return ctx.refuse(refused);
+  if (s.isPaused !== true) await ctx.write('Schedule', String(s.id), { isPaused: true }, 'schedule.pause');
+  return new Response(null, { status: 200 });
+};
+
+/** DELETE /v2/schedules/{scheduleId}: it fires no more. Answered 200 with no body. */
+const remove: Semantics = async (ctx) => {
+  const s = scheduleOf(ctx);
+  if (!s) return refuse(ctx, 404, 'Schedule not found.');
+  await ctx.write('Schedule', String(s.id), { deleted: true }, 'schedule.delete');
+  return new Response(null, { status: 200 });
+};
+
+export const scheduleSemantics: Record<string, Semantics> = {
+  post_v2_schedules_destination: createSchedule,
+  post_v2_schedules_scheduleid_pause: pause,
+  patch_v2_schedules_scheduleid_pause: pause,
+  delete_v2_schedules_scheduleid: remove,
+};

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

@@ -0,0 +1,45 @@
+import type { SemanticsContext } from '@volter/world-core';
+export type Row = Record<string, unknown>;
+/** A refusal in the documents' `Error` schema, `{"error": "<message>"}`. */
+export declare const refuse: (ctx: SemanticsContext, status: number, message: string) => Response;
+/** The request's headers, lower-cased. */
+export declare function headersOf(ctx: SemanticsContext): Record<string, string>;
+export declare function lowerKeys(h: Record<string, unknown> | undefined): Record<string, string>;
+/** A header map as the documents answer one: each name to its list of values. */
+export declare function multiValue(h: Record<string, string> | undefined): Record<string, string[]>;
+/** A multi-valued map to single values (the first of each). */
+export declare function singleValue(h: Record<string, unknown> | undefined): Record<string, string>;
+/** A duration as the delay page writes it: "The format for the duration is `<number><unit>`" (10s, 3m, 2h, 7d;
+ *  https://upstash.com/docs/qstash/features/delay), in seconds. A bare number is taken as seconds (the lane's decision:
+ *  the client's `delay` option is a number of seconds, which it writes as `<n>s`). Anything else is undefined. */
+export declare function durationSeconds(raw: unknown): number | undefined;
+/** The World's instant as Unix milliseconds. */
+export declare const nowMs: (ctx: SemanticsContext) => number;
+export declare const iso: (ms: number) => string;
+/** An id of QStash's form (`msg_…`, `scd_…`, `wfr_…`) derived from the World's instant, the kind and how many of it
+ *  the World already holds, so a World mints the same ids every run. The characters are the twin's. */
+export declare function mintId(ctx: SemanticsContext, prefix: string, kind: string, count: number): string;
+/** Every subject of a stored type, the tombstoned ones too (an id is never minted twice). */
+export declare const everHeld: (ctx: SemanticsContext, resource: string) => number;
+/** A stored subject's vendor fields: none of the kernel's, none of the lane's bookkeeping (`_`), and `state` only
+ *  where the document's schema carries it. */
+export declare function vendorFields(ctx: SemanticsContext, row: Row, keep: readonly string[]): Row;
+/** The `Message` schema's fields (the qstash document). */
+export declare const MESSAGE_FIELDS: readonly ["messageId", "url", "topicName", "endpointName", "method", "header", "body", "bodyBase64", "maxRetries", "notBefore", "createdAt", "callback", "failureCallback", "queueName", "scheduleId", "callerIP", "label", "labels", "flowControlKey", "rate", "period", "parallelism"];
+/** A queue name: "Queue names can only contain alphanumeric characters, hyphens, periods, and underscores." (the spec's
+ *  pause and resume 400). */
+export declare const QUEUE_NAME: RegExp;
+/** The body of a request as the text it was sent. */
+export declare const textOf: (ctx: SemanticsContext) => string;
+/** Base64 of a text, as QStash carries bodies and step results. */
+export declare const b64: (s: string) => string;
+/** A query parameter's values, repeated or comma-separated ("Multiple values can be passed either by repeating the query
+ *  parameter (`label=label_1&label=label_2`) or as a single comma-separated value (`label=label_1,label_2`)", the spec's bulk
+ *  cancel). */
+export declare function queryValues(ctx: SemanticsContext, name: string): string[];
+/** A bulk request's filter over stored subjects: each filter the request names, by the field it reads (a date range reads
+ *  `dateField`), "a workflow run matches if its value equals any of the given values (OR logic), and multiple filters are
+ *  combined with AND logic" (the spec's bulk cancel). `prefix` names the fields matched by prefix (a workflow URL without
+ *  `workflowUrlExactMatch`). Where the documentation stops and the lane decides: a filter whose field a subject lacks
+ *  excludes it. */
+export declare function matchesFilters(ctx: SemanticsContext, row: Row, fields: Record<string, string>, dateField: string, prefix?: string[]): boolean;

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

@@ -0,0 +1,115 @@
+// What the QStash lane's handlers share: the refusals, the request's headers, durations, ids and the views of stored
+// subjects in the documents' shapes. Where the documents stop and the lane decides, the comment beside the rule says so.
+import { createHash } from 'node:crypto';
+/** A refusal in the documents' `Error` schema, `{"error": "<message>"}`. */
+export const refuse = (ctx, status, message) => ctx.refuse({ status, message });
+/** The request's headers, lower-cased. */
+export function headersOf(ctx) {
+    const out = {};
+    ctx.call.request.headers.forEach((v, k) => { out[k.toLowerCase()] = v; });
+    return out;
+}
+export function lowerKeys(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h ?? {}))
+        if (v !== undefined && v !== null)
+            out[k.toLowerCase()] = String(v);
+    return out;
+}
+/** A header map as the documents answer one: each name to its list of values. */
+export function multiValue(h) {
+    return Object.fromEntries(Object.entries(h ?? {}).map(([k, v]) => [k, [v]]));
+}
+/** A multi-valued map to single values (the first of each). */
+export function singleValue(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h ?? {})) {
+        const first = Array.isArray(v) ? v[0] : v;
+        if (first !== undefined && first !== null)
+            out[k.toLowerCase()] = String(first);
+    }
+    return out;
+}
+/** A duration as the delay page writes it: "The format for the duration is `<number><unit>`" (10s, 3m, 2h, 7d;
+ *  https://upstash.com/docs/qstash/features/delay), in seconds. A bare number is taken as seconds (the lane's decision:
+ *  the client's `delay` option is a number of seconds, which it writes as `<n>s`). Anything else is undefined. */
+export function durationSeconds(raw) {
+    if (typeof raw === 'number' && Number.isFinite(raw) && raw >= 0)
+        return raw;
+    if (typeof raw !== 'string')
+        return undefined;
+    const s = raw.trim();
+    if (/^\d+$/.test(s))
+        return Number(s);
+    const m = /^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/.exec(s);
+    if (!m || s === '')
+        return undefined;
+    return Number(m[1] ?? 0) * 86_400 + Number(m[2] ?? 0) * 3600 + Number(m[3] ?? 0) * 60 + Number(m[4] ?? 0);
+}
+/** The World's instant as Unix milliseconds. */
+export const nowMs = (ctx) => Date.parse(ctx.occurredAt);
+export const iso = (ms) => new Date(ms).toISOString();
+const hex = (s) => createHash('sha256').update(s).digest('hex');
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/** An id of QStash's form (`msg_…`, `scd_…`, `wfr_…`) derived from the World's instant, the kind and how many of it
+ *  the World already holds, so a World mints the same ids every run. The characters are the twin's. */
+export function mintId(ctx, prefix, kind, count) {
+    const h = hex(`qstash:${kind}:${ctx.occurredAt}:${count}`);
+    let out = '';
+    for (let i = 0; out.length < 26; i += 1)
+        out += ALPHABET[parseInt(h.slice((i * 2) % 60, (i * 2) % 60 + 2), 16) % ALPHABET.length];
+    return `${prefix}${out}`;
+}
+/** Every subject of a stored type, the tombstoned ones too (an id is never minted twice). */
+export const everHeld = (ctx, resource) => ctx.rowsRaw(resource, { withDeleted: true }).length;
+/** A stored subject's vendor fields: none of the kernel's, none of the lane's bookkeeping (`_`), and `state` only
+ *  where the document's schema carries it. */
+export function vendorFields(ctx, row, keep) {
+    const own = ctx.own(row);
+    const out = {};
+    for (const k of keep)
+        if (own[k] !== undefined && own[k] !== null)
+            out[k] = own[k];
+    return out;
+}
+/** The `Message` schema's fields (the qstash document). */
+export const MESSAGE_FIELDS = ['messageId', 'url', 'topicName', 'endpointName', 'method', 'header', 'body', 'bodyBase64', 'maxRetries', 'notBefore', 'createdAt',
+    'callback', 'failureCallback', 'queueName', 'scheduleId', 'callerIP', 'label', 'labels', 'flowControlKey', 'rate', 'period', 'parallelism'];
+/** A queue name: "Queue names can only contain alphanumeric characters, hyphens, periods, and underscores." (the spec's
+ *  pause and resume 400). */
+export const QUEUE_NAME = /^[A-Za-z0-9._-]+$/;
+/** The body of a request as the text it was sent. */
+export const textOf = (ctx) => ctx.text ?? '';
+/** Base64 of a text, as QStash carries bodies and step results. */
+export const b64 = (s) => Buffer.from(s, 'utf8').toString('base64');
+/** A query parameter's values, repeated or comma-separated ("Multiple values can be passed either by repeating the query
+ *  parameter (`label=label_1&label=label_2`) or as a single comma-separated value (`label=label_1,label_2`)", the spec's bulk
+ *  cancel). */
+export function queryValues(ctx, name) {
+    return new URL(ctx.call.request.url).searchParams.getAll(name).flatMap((v) => v.split(',')).map((s) => s.trim()).filter(Boolean);
+}
+/** A bulk request's filter over stored subjects: each filter the request names, by the field it reads (a date range reads
+ *  `dateField`), "a workflow run matches if its value equals any of the given values (OR logic), and multiple filters are
+ *  combined with AND logic" (the spec's bulk cancel). `prefix` names the fields matched by prefix (a workflow URL without
+ *  `workflowUrlExactMatch`). Where the documentation stops and the lane decides: a filter whose field a subject lacks
+ *  excludes it. */
+export function matchesFilters(ctx, row, fields, dateField, prefix = []) {
+    const q = new URL(ctx.call.request.url).searchParams;
+    for (const [param, field] of Object.entries(fields)) {
+        const wanted = queryValues(ctx, param);
+        if (!wanted.length)
+            continue;
+        const have = Array.isArray(row[field]) ? row[field].map(String) : row[field] === undefined || row[field] === null ? [] : [String(row[field])];
+        const hit = prefix.includes(param) ? have.some((h) => wanted.some((w) => h.startsWith(w))) : have.some((h) => wanted.includes(h));
+        if (!hit)
+            return false;
+    }
+    const at = Number(row[dateField]);
+    const from = q.get('fromDate');
+    const to = q.get('toDate');
+    if (from !== null && !(at >= Number(from)))
+        return false;
+    if (to !== null && !(at <= Number(to)))
+        return false;
+    return true;
+}

package/dist/qstash/src/semantics/shared.ts

@@ -0,0 +1,121 @@
+// What the QStash lane's handlers share: the refusals, the request's headers, durations, ids and the views of stored
+// subjects in the documents' shapes. Where the documents stop and the lane decides, the comment beside the rule says so.
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+
+export type Row = Record<string, unknown>;
+
+/** A refusal in the documents' `Error` schema, `{"error": "<message>"}`. */
+export const refuse = (ctx: SemanticsContext, status: number, message: string): Response => ctx.refuse({ status, message });
+
+/** The request's headers, lower-cased. */
+export function headersOf(ctx: SemanticsContext): Record<string, string> {
+  const out: Record<string, string> = {};
+  ctx.call.request.headers.forEach((v, k) => { out[k.toLowerCase()] = v; });
+  return out;
+}
+
+export function lowerKeys(h: Record<string, unknown> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(h ?? {})) if (v !== undefined && v !== null) out[k.toLowerCase()] = String(v);
+  return out;
+}
+
+/** A header map as the documents answer one: each name to its list of values. */
+export function multiValue(h: Record<string, string> | undefined): Record<string, string[]> {
+  return Object.fromEntries(Object.entries(h ?? {}).map(([k, v]) => [k, [v]]));
+}
+
+/** A multi-valued map to single values (the first of each). */
+export function singleValue(h: Record<string, unknown> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(h ?? {})) {
+    const first = Array.isArray(v) ? v[0] : v;
+    if (first !== undefined && first !== null) out[k.toLowerCase()] = String(first);
+  }
+  return out;
+}
+
+/** A duration as the delay page writes it: "The format for the duration is `<number><unit>`" (10s, 3m, 2h, 7d;
+ *  https://upstash.com/docs/qstash/features/delay), in seconds. A bare number is taken as seconds (the lane's decision:
+ *  the client's `delay` option is a number of seconds, which it writes as `<n>s`). Anything else is undefined. */
+export function durationSeconds(raw: unknown): number | undefined {
+  if (typeof raw === 'number' && Number.isFinite(raw) && raw >= 0) return raw;
+  if (typeof raw !== 'string') return undefined;
+  const s = raw.trim();
+  if (/^\d+$/.test(s)) return Number(s);
+  const m = /^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/.exec(s);
+  if (!m || s === '') return undefined;
+  return Number(m[1] ?? 0) * 86_400 + Number(m[2] ?? 0) * 3600 + Number(m[3] ?? 0) * 60 + Number(m[4] ?? 0);
+}
+
+/** The World's instant as Unix milliseconds. */
+export const nowMs = (ctx: SemanticsContext): number => Date.parse(ctx.occurredAt);
+export const iso = (ms: number): string => new Date(ms).toISOString();
+
+const hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+/** An id of QStash's form (`msg_…`, `scd_…`, `wfr_…`) derived from the World's instant, the kind and how many of it
+ *  the World already holds, so a World mints the same ids every run. The characters are the twin's. */
+export function mintId(ctx: SemanticsContext, prefix: string, kind: string, count: number): string {
+  const h = hex(`qstash:${kind}:${ctx.occurredAt}:${count}`);
+  let out = '';
+  for (let i = 0; out.length < 26; i += 1) out += ALPHABET[parseInt(h.slice((i * 2) % 60, (i * 2) % 60 + 2), 16) % ALPHABET.length];
+  return `${prefix}${out}`;
+}
+
+/** Every subject of a stored type, the tombstoned ones too (an id is never minted twice). */
+export const everHeld = (ctx: SemanticsContext, resource: string): number => ctx.rowsRaw(resource, { withDeleted: true }).length;
+
+/** A stored subject's vendor fields: none of the kernel's, none of the lane's bookkeeping (`_`), and `state` only
+ *  where the document's schema carries it. */
+export function vendorFields(ctx: SemanticsContext, row: Row, keep: readonly string[]): Row {
+  const own = ctx.own(row);
+  const out: Row = {};
+  for (const k of keep) if (own[k] !== undefined && own[k] !== null) out[k] = own[k];
+  return out;
+}
+
+/** The `Message` schema's fields (the qstash document). */
+export const MESSAGE_FIELDS = ['messageId', 'url', 'topicName', 'endpointName', 'method', 'header', 'body', 'bodyBase64', 'maxRetries', 'notBefore', 'createdAt',
+  'callback', 'failureCallback', 'queueName', 'scheduleId', 'callerIP', 'label', 'labels', 'flowControlKey', 'rate', 'period', 'parallelism'] as const;
+
+/** A queue name: "Queue names can only contain alphanumeric characters, hyphens, periods, and underscores." (the spec's
+ *  pause and resume 400). */
+export const QUEUE_NAME = /^[A-Za-z0-9._-]+$/;
+
+/** The body of a request as the text it was sent. */
+export const textOf = (ctx: SemanticsContext): string => ctx.text ?? '';
+
+/** Base64 of a text, as QStash carries bodies and step results. */
+export const b64 = (s: string): string => Buffer.from(s, 'utf8').toString('base64');
+
+/** A query parameter's values, repeated or comma-separated ("Multiple values can be passed either by repeating the query
+ *  parameter (`label=label_1&label=label_2`) or as a single comma-separated value (`label=label_1,label_2`)", the spec's bulk
+ *  cancel). */
+export function queryValues(ctx: SemanticsContext, name: string): string[] {
+  return new URL(ctx.call.request.url).searchParams.getAll(name).flatMap((v) => v.split(',')).map((s) => s.trim()).filter(Boolean);
+}
+
+/** A bulk request's filter over stored subjects: each filter the request names, by the field it reads (a date range reads
+ *  `dateField`), "a workflow run matches if its value equals any of the given values (OR logic), and multiple filters are
+ *  combined with AND logic" (the spec's bulk cancel). `prefix` names the fields matched by prefix (a workflow URL without
+ *  `workflowUrlExactMatch`). Where the documentation stops and the lane decides: a filter whose field a subject lacks
+ *  excludes it. */
+export function matchesFilters(ctx: SemanticsContext, row: Row, fields: Record<string, string>, dateField: string, prefix: string[] = []): boolean {
+  const q = new URL(ctx.call.request.url).searchParams;
+  for (const [param, field] of Object.entries(fields)) {
+    const wanted = queryValues(ctx, param);
+    if (!wanted.length) continue;
+    const have = Array.isArray(row[field]) ? (row[field] as unknown[]).map(String) : row[field] === undefined || row[field] === null ? [] : [String(row[field])];
+    const hit = prefix.includes(param) ? have.some((h) => wanted.some((w) => h.startsWith(w))) : have.some((h) => wanted.includes(h));
+    if (!hit) return false;
+  }
+  const at = Number(row[dateField]);
+  const from = q.get('fromDate'); const to = q.get('toDate');
+  if (from !== null && !(at >= Number(from))) return false;
+  if (to !== null && !(at <= Number(to))) return false;
+  return true;
+}
+

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

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const urlGroupSemantics: Record<string, Semantics>;

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

@@ -0,0 +1,58 @@
+import { ownerFor } from "./messages.js";
+import { nowMs, refuse } from "./shared.js";
+const groupOf = (ctx, name, owner) => ctx.rowsRaw('URLGroup').find((g) => g.name === name && g._owner === owner);
+function view(ctx, g) {
+    const own = ctx.own(g);
+    return { name: own.name, createdAt: own.createdAt, updatedAt: own.updatedAt, endpoints: own.endpoints ?? [] };
+}
+function endpointsOf(ctx) {
+    const list = ctx.body?.endpoints;
+    if (!Array.isArray(list))
+        return undefined;
+    return list.map((e) => e).filter((e) => typeof e.url === 'string' || typeof e.name === 'string')
+        .map((e) => ({ ...(typeof e.url === 'string' ? { url: e.url } : { url: '' }), ...(typeof e.name === 'string' ? { name: e.name } : {}) }));
+}
+/** POST /v2/topics/{urlGroupName}/endpoints: "Add one or multiple endpoints to a URL Group. If the URL Group does not
+ *  exist, it will be created." (the spec). An endpoint the
+ *  group already has (the same URL) is replaced by the one sent. Answered 200 with no body. */
+const upsert = async (ctx) => {
+    const name = String(ctx.call.params.urlGroupName);
+    const sent = endpointsOf(ctx);
+    if (!sent || !sent.length || sent.some((e) => !/^https?:\/\//.test(e.url)))
+        return refuse(ctx, 400, 'endpoints must be a non-empty list of {url, name?} with an http or https url');
+    const owner = ownerFor(ctx);
+    const g = groupOf(ctx, name, owner);
+    const kept = (g?.endpoints ?? []).filter((e) => !sent.some((s) => s.url === e.url));
+    const at = nowMs(ctx);
+    await ctx.write('URLGroup', g ? String(g.id) : `${owner}:${name}`, { name, createdAt: g?.createdAt ?? at, updatedAt: at, endpoints: [...kept, ...sent], _owner: owner }, g ? 'url_group.update' : 'url_group.create');
+    return new Response(null, { status: 200 });
+};
+/** DELETE /v2/topics/{urlGroupName}/endpoints: the endpoints named (by URL or by name) leave the group. Answered 200. */
+const removeEndpoints = async (ctx) => {
+    const g = groupOf(ctx, String(ctx.call.params.urlGroupName), ownerFor(ctx));
+    if (!g)
+        return refuse(ctx, 404, `URL Group ${String(ctx.call.params.urlGroupName)} not found`);
+    const sent = endpointsOf(ctx) ?? [];
+    const endpoints = (g.endpoints ?? []).filter((e) => !sent.some((s) => (s.url && s.url === e.url) || (s.name !== undefined && s.name === e.name)));
+    await ctx.write('URLGroup', String(g.id), { endpoints, updatedAt: nowMs(ctx) }, 'url_group.update');
+    return new Response(null, { status: 200 });
+};
+export const urlGroupSemantics = {
+    post_v2_topics_urlgroupname_endpoints: upsert,
+    delete_v2_topics_urlgroupname_endpoints: removeEndpoints,
+    get_v2_topics_urlgroupname: async (ctx) => {
+        const g = groupOf(ctx, String(ctx.call.params.urlGroupName), ownerFor(ctx));
+        return g ? ctx.reply(view(ctx, g)) : refuse(ctx, 404, `URL Group ${String(ctx.call.params.urlGroupName)} not found`);
+    },
+    get_v2_topics: async (ctx) => {
+        const owner = ownerFor(ctx);
+        return ctx.reply(ctx.rowsRaw('URLGroup').filter((g) => g._owner === owner).sort((a, b) => String(a.name).localeCompare(String(b.name))).map((g) => view(ctx, g)));
+    },
+    delete_v2_topics_urlgroupname: async (ctx) => {
+        const g = groupOf(ctx, String(ctx.call.params.urlGroupName), ownerFor(ctx));
+        if (!g)
+            return refuse(ctx, 404, `URL Group ${String(ctx.call.params.urlGroupName)} not found`);
+        await ctx.write('URLGroup', String(g.id), { deleted: true }, 'url_group.delete');
+        return new Response(null, { status: 200 });
+    },
+};

package/dist/qstash/src/semantics/urlgroups.ts

@@ -0,0 +1,69 @@
+// URL groups (the API calls them topics): "a URL Group is just a namespace where you can publish messages to, the same way
+// as publishing a message to an endpoint directly" and "When you publish a message to a URL Group, it will be fanned out and
+// sent to all the subscribed endpoints." (https://upstash.com/docs/qstash/features/url-groups). A message published to a group
+// is one message per endpoint (messages.ts); the lane serves the group's upsert of endpoints, its read, its list, the
+// removal of endpoints and the group's deletion.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { ownerFor } from './messages.ts';
+import { nowMs, refuse, type Row } from './shared.ts';
+
+type Endpoint = { url: string; name?: string };
+
+const groupOf = (ctx: SemanticsContext, name: string, owner: string): Row | undefined =>
+  ctx.rowsRaw('URLGroup').find((g) => g.name === name && g._owner === owner);
+
+function view(ctx: SemanticsContext, g: Row): Row {
+  const own = ctx.own(g);
+  return { name: own.name, createdAt: own.createdAt, updatedAt: own.updatedAt, endpoints: own.endpoints ?? [] };
+}
+
+function endpointsOf(ctx: SemanticsContext): Endpoint[] | undefined {
+  const list = (ctx.body as { endpoints?: unknown } | undefined)?.endpoints;
+  if (!Array.isArray(list)) return undefined;
+  return list.map((e) => e as Row).filter((e) => typeof e.url === 'string' || typeof e.name === 'string')
+    .map((e) => ({ ...(typeof e.url === 'string' ? { url: e.url } : { url: '' }), ...(typeof e.name === 'string' ? { name: e.name } : {}) }));
+}
+
+/** POST /v2/topics/{urlGroupName}/endpoints: "Add one or multiple endpoints to a URL Group. If the URL Group does not
+ *  exist, it will be created." (the spec). An endpoint the
+ *  group already has (the same URL) is replaced by the one sent. Answered 200 with no body. */
+const upsert: Semantics = async (ctx) => {
+  const name = String(ctx.call.params.urlGroupName);
+  const sent = endpointsOf(ctx);
+  if (!sent || !sent.length || sent.some((e) => !/^https?:\/\//.test(e.url))) return refuse(ctx, 400, 'endpoints must be a non-empty list of {url, name?} with an http or https url');
+  const owner = ownerFor(ctx);
+  const g = groupOf(ctx, name, owner);
+  const kept = ((g?.endpoints ?? []) as Endpoint[]).filter((e) => !sent.some((s) => s.url === e.url));
+  const at = nowMs(ctx);
+  await ctx.write('URLGroup', g ? String(g.id) : `${owner}:${name}`, { name, createdAt: g?.createdAt ?? at, updatedAt: at, endpoints: [...kept, ...sent], _owner: owner }, g ? 'url_group.update' : 'url_group.create');
+  return new Response(null, { status: 200 });
+};
+
+/** DELETE /v2/topics/{urlGroupName}/endpoints: the endpoints named (by URL or by name) leave the group. Answered 200. */
+const removeEndpoints: Semantics = async (ctx) => {
+  const g = groupOf(ctx, String(ctx.call.params.urlGroupName), ownerFor(ctx));
+  if (!g) return refuse(ctx, 404, `URL Group ${String(ctx.call.params.urlGroupName)} not found`);
+  const sent = endpointsOf(ctx) ?? [];
+  const endpoints = ((g.endpoints ?? []) as Endpoint[]).filter((e) => !sent.some((s) => (s.url && s.url === e.url) || (s.name !== undefined && s.name === e.name)));
+  await ctx.write('URLGroup', String(g.id), { endpoints, updatedAt: nowMs(ctx) }, 'url_group.update');
+  return new Response(null, { status: 200 });
+};
+
+export const urlGroupSemantics: Record<string, Semantics> = {
+  post_v2_topics_urlgroupname_endpoints: upsert,
+  delete_v2_topics_urlgroupname_endpoints: removeEndpoints,
+  get_v2_topics_urlgroupname: async (ctx) => {
+    const g = groupOf(ctx, String(ctx.call.params.urlGroupName), ownerFor(ctx));
+    return g ? ctx.reply(view(ctx, g)) : refuse(ctx, 404, `URL Group ${String(ctx.call.params.urlGroupName)} not found`);
+  },
+  get_v2_topics: async (ctx) => {
+    const owner = ownerFor(ctx);
+    return ctx.reply(ctx.rowsRaw('URLGroup').filter((g) => g._owner === owner).sort((a, b) => String(a.name).localeCompare(String(b.name))).map((g) => view(ctx, g)));
+  },
+  delete_v2_topics_urlgroupname: async (ctx) => {
+    const g = groupOf(ctx, String(ctx.call.params.urlGroupName), ownerFor(ctx));
+    if (!g) return refuse(ctx, 404, `URL Group ${String(ctx.call.params.urlGroupName)} not found`);
+    await ctx.write('URLGroup', String(g.id), { deleted: true }, 'url_group.delete');
+    return new Response(null, { status: 200 });
+  },
+};

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

@@ -0,0 +1,44 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Accepted, type Publication } from './messages.js';
+import { type Row } from './shared.js';
+export declare const isWorkflowMessage: (h: Record<string, string>) => boolean;
+/** A run's messages, in the order the run made them. */
+export declare function runMessages(ctx: SemanticsContext, runId: string): Row[];
+/** The steps a delivery of the run's message `seq` carries: the steps a resumed run kept, then the run's own messages up
+ *  to `seq`, each as `{messageId, body: <base64 of what was published>, callType}` (`processRawSteps`). */
+export declare function rawSteps(ctx: SemanticsContext, runId: string, seq: number): Row[];
+/** What a workflow's delivery carries in its headers: every `Upstash-Forward-*` header with the prefix stripped (the
+ *  run's `Upstash-Workflow-Sdk-Version` among them, which is how `serve()` tells a delivery from its own first
+ *  invocation), and the run's own workflow headers as published. */
+export declare function workflowHeaders(published: Record<string, string>): Record<string, string>;
+/** One batch or publish entry of a workflow: the first of a run starts it, a later one is a step of an active run. A run
+ *  id the World already holds is not started twice: the client reads `deduplicated` and warns "Workflow run … already
+ *  exists" (`triggerFirstInvocation`). A step for a run no longer active is refused 400, which the client reads as "Tried
+ *  to append to a cancelled workflow" (`triggerRouteFunction`). */
+export declare function acceptWorkflowMessage(ctx: SemanticsContext, p: Publication, owner: string): Promise<Accepted>;
+/** A wait whose timeout has come: the step comes back to its timeout URL timed out, with the headers the run gave for it
+ *  (the catch-up, delivery.ts). */
+export declare function timeOut(ctx: SemanticsContext, w: Row): Promise<void>;
+/** The ids a query names, whether repeated or comma-separated ("Multiple values can be passed either by repeating the
+ *  query parameter ... or as a single comma-separated value", the spec's bulk cancel). */
+export declare function idsOf(ctx: SemanticsContext, name: string): string[];
+export declare function workflowDlqView(ctx: SemanticsContext, e: Row): Row;
+/** A step's message has failed after its retries: "When a workflow step fails and exhausts all configured retries,
+ *  Upstash Workflow automatically moves the failed run to the DLQ." (https://upstash.com/docs/workflow/features/dlq); the
+ *  run is RUN_FAILED, and its failure function is called ("a failure function ... executes custom logic when a workflow
+ *  run fails after exhausting all retry attempts", https://upstash.com/docs/workflow/features/failure-callback) as a
+ *  QStash failure callback to the failure URL, with the callback body plus the run's id and creation time, which the
+ *  client's `serve()` reads, and the `Upstash-Failure-Callback-*` headers the run was started with (their prefix made
+ *  `Upstash-`). */
+export declare function failRun(ctx: SemanticsContext, m: Row, outcome: {
+    status: number;
+    body: string;
+    headers: Record<string, string>;
+}): Promise<void>;
+/** The failure call's outcome on its DLQ entry: CALLBACK_SUCCESS once it is answered, CALLBACK_FAIL once its retries are
+ *  spent (the workflow document's `failureFunctionState` filter lists CALLBACK_INPROGRESS, CALLBACK_SUCCESS, CALLBACK_FAIL). */
+export declare function failureCallSettled(ctx: SemanticsContext, callbackOf: string, delivered: boolean): Promise<void>;
+/** The Workflow DLQ, newest first, as `{messages}`: "If no cursor is returned, you have reached the end". Answers
+ *  `GET /v2/workflows/dlq` and the client's `GET /v2/dlq?source=workflow` (the spec patch). */
+export declare function workflowDlq(ctx: SemanticsContext): Response;
+export declare const workflowSemantics: Record<string, Semantics>;