@pithy-sh/core 0.12.0 → 0.14.0

package/src/presence/ticket.ts

@@ -0,0 +1,145 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { base64UrlDecode, base64UrlEncode } from "../controlPlane/token/base64url";
+import { PresenceTicketInvalidError } from "../error/pithyError";
+import { PRESENCE_TICKET_TTL_SECONDS } from "./declaration";
+import { PresenceOrigin, PresenceParticipantName, PresenceParticipantRef } from "./frames";
+import { PresenceRecordId, PresenceRoomKindName } from "./names";
+
+/**
+ * **A presence ticket: single use, 60 seconds, one room, one participant.**
+ *
+ * `<claims>.<signature>`, both unpadded base64url, the signature an HMAC-SHA256 over the claims segment with
+ * the Worker's `presence-ticket-key` secret. The alphabet and the dot are all token characters, so a
+ * ticket rides in `Sec-WebSocket-Protocol` as `pithy.ticket.<ticket>` untouched.
+ *
+ * What a ticket proves is that **this Worker** minted it, behind a gate, for these claims. Verifying it
+ * here checks the signature, the expiry and the room; spending it is the room's job, because only the room
+ * the ticket names can redeem it, which is what makes "single use" decidable without a write anywhere.
+ *
+ * Every failure is the one {@link PresenceTicketInvalidError}, with the step in `detail` for the log: a caller
+ * holding someone else's ticket learns that it does not work, never why.
+ */
+
+/** The subprotocol prefix a ticket travels under, beside `pithy.presence.v1`. */
+export const PRESENCE_TICKET_PROTOCOL_PREFIX = "pithy.ticket.";
+
+/** What a ticket says, signed. */
+export const PresenceTicketClaims = z
+  .object({
+    v: z.literal(1).describe("The ticket format. A different one is refused."),
+    id: z.string().uuid().describe("The ticket's own id — what the room records as spent."),
+    kind: PresenceRoomKindName.describe("The room kind the ticket admits to."),
+    recordId: PresenceRecordId.describe("The record the room is about."),
+    ref: PresenceParticipantRef.describe(
+      "Who the participant is: the client's opaque ref, or the signed-in user's id.",
+    ),
+    name: PresenceParticipantName.describe("How other participants see them."),
+    origin: PresenceOrigin.describe("Which door the ticket was minted at."),
+    exp: z.number().int().positive().describe("When the ticket stops being honored, in seconds since the epoch."),
+  })
+  .describe("The claims a presence ticket carries, signed by the Worker that minted it.");
+export type PresenceTicketClaims = z.infer<typeof PresenceTicketClaims>;
+
+/** What a caller asks a ticket for: everything but the id and the expiry, which the minter decides. */
+export type PresenceTicketRequest = Omit<PresenceTicketClaims, "v" | "id" | "exp">;
+
+const encoder = new TextEncoder();
+
+async function hmacKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify",
+  ]);
+}
+
+/** Mint a ticket. `keys[0]` signs. */
+export async function mintPresenceTicket(
+  request: PresenceTicketRequest,
+  keys: readonly string[],
+  now: Date = new Date(),
+): Promise<{ ticket: string; claims: PresenceTicketClaims }> {
+  const [signing] = keys;
+  if (signing === undefined) throw new PresenceTicketInvalidError({ detail: "no signing key" });
+  const claims = PresenceTicketClaims.parse({
+    v: 1,
+    id: crypto.randomUUID(),
+    ...request,
+    exp: Math.floor(now.getTime() / 1000) + PRESENCE_TICKET_TTL_SECONDS,
+  });
+  const body = base64UrlEncode(encoder.encode(JSON.stringify(claims)));
+  const signature = new Uint8Array(await crypto.subtle.sign("HMAC", await hmacKey(signing), encoder.encode(body)));
+  return { ticket: `${body}.${base64UrlEncode(signature)}`, claims };
+}
+
+/** Decode a segment, mapping the control-plane decoder's refusal onto this one. */
+function decode(segment: string, what: string): Uint8Array {
+  try {
+    return base64UrlDecode(segment);
+  } catch (cause) {
+    throw new PresenceTicketInvalidError({ detail: `${what} is not base64url` }, { cause });
+  }
+}
+
+/**
+ * Verify a ticket for one room: the signature under any honored key, the expiry, and that it names this
+ * kind and this record. Returns the claims; spending them is the room's.
+ */
+export async function verifyPresenceTicket(
+  ticket: string,
+  room: { kind: string; recordId: string },
+  keys: readonly string[],
+  now: Date = new Date(),
+): Promise<PresenceTicketClaims> {
+  const parts = ticket.split(".");
+  const [body, signature] = parts;
+  if (parts.length !== 2 || !body || !signature) throw new PresenceTicketInvalidError({ detail: "not two segments" });
+  const signed = decode(signature, "signature");
+  let authentic = false;
+  for (const key of keys) {
+    if (await crypto.subtle.verify("HMAC", await hmacKey(key), signed, encoder.encode(body))) {
+      authentic = true;
+      break;
+    }
+  }
+  if (!authentic) throw new PresenceTicketInvalidError({ detail: "signature does not verify under any honored key" });
+
+  let json: unknown;
+  try {
+    json = JSON.parse(new TextDecoder().decode(decode(body, "claims")));
+  } catch (cause) {
+    if (cause instanceof PresenceTicketInvalidError) throw cause;
+    throw new PresenceTicketInvalidError({ detail: "claims are not JSON" }, { cause });
+  }
+  const parsed = PresenceTicketClaims.safeParse(json);
+  if (!parsed.success) throw new PresenceTicketInvalidError({ detail: "claims do not parse" });
+  const claims = parsed.data;
+
+  const seconds = Math.floor(now.getTime() / 1000);
+  if (claims.exp <= seconds) throw new PresenceTicketInvalidError({ detail: `expired at ${claims.exp}` });
+  // A ticket living past its stated life was not minted here, whatever signed it.
+  if (claims.exp > seconds + PRESENCE_TICKET_TTL_SECONDS) {
+    throw new PresenceTicketInvalidError({ detail: `expiry ${claims.exp} is beyond the ticket lifetime` });
+  }
+  if (claims.kind !== room.kind || claims.recordId !== room.recordId) {
+    throw new PresenceTicketInvalidError({
+      detail: `minted for ${claims.kind}/${claims.recordId}, presented at ${room.kind}/${room.recordId}`,
+    });
+  }
+  return claims;
+}
+
+/**
+ * The ticket from a subprotocol offer, or `undefined` when none rides in it. More than one is refused as
+ * none: an offer is one client's, and two tickets in it is not something a client means.
+ */
+export function ticketFromOffer(offered: string | null | undefined): string | undefined {
+  const tickets = (offered ?? "")
+    .split(",")
+    .map((protocol) => protocol.trim())
+    .filter((protocol) => protocol.startsWith(PRESENCE_TICKET_PROTOCOL_PREFIX))
+    .map((protocol) => protocol.slice(PRESENCE_TICKET_PROTOCOL_PREFIX.length));
+  return tickets.length === 1 ? tickets[0] : undefined;
+}

package/src/processing/activity.ts

@@ -0,0 +1,289 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ConsentPurposeId } from "../consent/purpose";
+import { fromZodError, ValidationError } from "../error/pithyError";
+import { PrivacyClassName } from "../privacy/classes";
+import { type BasisSource, LegalBasis } from "./vocabulary";
+
+/**
+ * Processing activities: what a Worker does with personal data, why, and on what legal basis — the declarations the
+ * GDPR Article 30 record is derived from.
+ *
+ * ## Declared where the processing is
+ *
+ * A capability states the activities it performs, under its own `name` (`auth.account`), the rule consent purposes,
+ * tables and error codes follow. The adopter adds their own in the `processing` block of a Worker's
+ * `pithy.config.ts`, and may replace a capability's legal basis there.
+ *
+ * ## A missing basis is a gap, never a guess
+ *
+ * `legalBasis` is optional. An activity without one is reported as a gap in the record, and nothing fills it in.
+ */
+
+/** An activity id: `<domain>.<name>`, lowercase, the domain being the declaring capability's name. */
+export const ProcessingActivityId = z
+  .string()
+  .regex(
+    /^[a-z][a-z0-9-]*\.[a-z][a-z0-9_.-]*$/,
+    "A processing activity id is `<domain>.<name>`: lowercase, the domain being the declaring capability's name.",
+  )
+  .max(128)
+  .describe(
+    "A processing activity id, `<domain>.<name>` — `auth.account`. The domain is the declaring capability's name, or the adopter's own domain for an activity declared in `pithy.config.ts`.",
+  );
+export type ProcessingActivityId = z.infer<typeof ProcessingActivityId>;
+
+/** Someone outside the Worker's own code who receives personal data for an activity. */
+export const ProcessingRecipient = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .max(120)
+      .describe("Who receives it, as an auditor would name them — `Stripe`, `Cloudflare Email Service`."),
+    receives: z
+      .string()
+      .min(1)
+      .max(500)
+      .describe("What they receive, in one sentence — `The buyer's email address and what they bought.`"),
+    classes: z
+      .array(PrivacyClassName)
+      .default([])
+      .describe("The data classes in what they receive — `pii`, `phi`, or an adopter's own."),
+  })
+  .describe("One recipient of personal data: who it is, what it receives, and the classes in it.");
+export type ProcessingRecipient = z.output<typeof ProcessingRecipient>;
+export type ProcessingRecipientInput = z.input<typeof ProcessingRecipient>;
+
+/** A consent purpose belongs with a consent basis and nowhere else. */
+function consentPurposeNeedsConsent(
+  value: { legalBasis?: LegalBasis | undefined; consentPurpose?: string | undefined },
+  ctx: z.RefinementCtx,
+): void {
+  if (value.consentPurpose !== undefined && value.legalBasis !== "consent") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["consentPurpose"],
+      message:
+        "`consentPurpose` names the purpose a `consent` basis rests on. Set `legalBasis` to `consent`, or drop it.",
+    });
+  }
+}
+
+/** One processing activity, as a capability or the adopter declares it. */
+export const ProcessingActivity = z
+  .object({
+    id: ProcessingActivityId,
+    purpose: z
+      .string()
+      .min(1)
+      .max(500)
+      .describe(
+        "Why the data is processed, in one sentence an auditor reads — `Keep an account and sign its holder in.`",
+      ),
+    classes: z
+      .array(PrivacyClassName)
+      .default([])
+      .describe(
+        "The data classes the activity uses — `pii`, `phi`, or an adopter's own. Cross-checked against the classes the Worker's schemas store.",
+      ),
+    legalBasis: LegalBasis.optional().describe(
+      "The lawful basis it rests on. Absent is reported as a gap in the processing record, never filled in.",
+    ),
+    consentPurpose: ConsentPurposeId.optional().describe(
+      "For a `consent` basis, the consent purpose the activity rests on — `email.marketing`. The record cites its grant counts.",
+    ),
+    recipients: z
+      .array(ProcessingRecipient)
+      .default([])
+      .describe(
+        "Who receives the data beyond Cloudflare, which the record always lists — a payment rail, a mail provider. Built from the resolved config, so a rail that is off is not named.",
+      ),
+  })
+  .superRefine(consentPurposeNeedsConsent)
+  .describe("One processing activity: its purpose, the data classes it uses, its legal basis and its recipients.");
+export type ProcessingActivity = z.output<typeof ProcessingActivity>;
+export type ProcessingActivityInput = z.input<typeof ProcessingActivity>;
+
+/** The adopter's replacement for a capability's legal basis. */
+export const ProcessingOverride = z
+  .object({
+    legalBasis: LegalBasis.describe("The basis that replaces the capability's own."),
+    consentPurpose: ConsentPurposeId.optional().describe(
+      "For a `consent` basis, the consent purpose it rests on. Left out, a capability's own purpose is kept.",
+    ),
+  })
+  .strict()
+  .superRefine(consentPurposeNeedsConsent)
+  .describe("A legal basis the adopter states for a capability's activity, replacing the one it declares.");
+export type ProcessingOverride = z.infer<typeof ProcessingOverride>;
+
+/** The `processing` block, as a Worker's `pithy.config.ts` writes it. */
+export const ProcessingPolicy = z
+  .object({
+    activities: z
+      .array(ProcessingActivity)
+      .optional()
+      .describe(
+        "Your own processing activities, beside the ones composed capabilities declare. Each under your own domain.",
+      ),
+    overrides: z
+      .record(ProcessingActivityId, ProcessingOverride)
+      .optional()
+      .describe(
+        'A legal basis per capability activity, replacing the one it declares: `{ "auth.account": { legalBasis: "legitimate-interests" } }`.',
+      ),
+  })
+  .strict()
+  .describe("What this Worker does with personal data beyond what its capabilities declare, and the bases you state.");
+export type ProcessingPolicy = z.output<typeof ProcessingPolicy>;
+export type ProcessingPolicyInput = z.input<typeof ProcessingPolicy>;
+
+/** The domain half of an activity id: `auth` for `auth.account`. */
+export function activityDomain(id: string): string {
+  const dot = id.indexOf(".");
+  return dot === -1 ? id : id.slice(0, dot);
+}
+
+/**
+ * Parse one declarer's activities and refuse what the record could not attribute: an invalid activity, one under a
+ * domain that is not the declarer's, or two with one id. `domain` is the declaring capability's name, or `null` for
+ * the adopter's own, which may use any domain but a reserved one.
+ */
+export function parseProcessingActivities(
+  declarer: string,
+  activities: readonly ProcessingActivityInput[],
+  domain: string | null,
+  reserved: ReadonlySet<string> = new Set(),
+): ProcessingActivity[] {
+  const seen = new Set<string>();
+  return activities.map((input) => {
+    const parsed = ProcessingActivity.safeParse(input);
+    if (!parsed.success) {
+      throw new ValidationError({
+        message: `${declarer} declares a processing activity that is not valid: ${parsed.error.issues[0]?.message ?? "invalid"}.`,
+        action:
+          "Give it an id of the form `<domain>.<name>` and a purpose; name a consent purpose only under a consent basis.",
+      });
+    }
+    const activity = parsed.data;
+    const own = activityDomain(activity.id);
+    if (domain !== null && own !== domain) {
+      throw new ValidationError({
+        message: `The ${declarer} capability declares the processing activity "${activity.id}" outside its own domain.`,
+        action: `Name it under ${domain}. — a capability declares activities only under its own name.`,
+      });
+    }
+    if (domain === null && reserved.has(own)) {
+      throw new ValidationError({
+        message: `The processing activity "${activity.id}" is under ${own}., which a composed capability owns.`,
+        action: "Name your own activities under your own domain, such as your app's name.",
+      });
+    }
+    if (seen.has(activity.id)) {
+      throw new ValidationError({
+        message: `${declarer} declares the processing activity "${activity.id}" twice.`,
+        action: "Declare each activity once.",
+      });
+    }
+    seen.add(activity.id);
+    return activity;
+  });
+}
+
+/** Parse a `processing` block, or refuse it naming what is wrong. `undefined` is the empty policy. */
+export function parseProcessingPolicy(input: unknown): ProcessingPolicy {
+  if (input === undefined) return {};
+  const parsed = ProcessingPolicy.safeParse(input);
+  if (!parsed.success) {
+    throw fromZodError(parsed.error, {
+      message: "The processing block in pithy.config.ts does not parse.",
+      action: "Fix the field named, then deploy again.",
+    });
+  }
+  return parsed.data;
+}
+
+/** One activity as it takes effect: who declared it, its basis after any override, and where that came from. */
+export interface ResolvedActivity {
+  readonly id: string;
+  readonly purpose: string;
+  readonly classes: readonly string[];
+  readonly legalBasis: LegalBasis | null;
+  readonly basisSource: BasisSource | null;
+  readonly consentPurpose: string | null;
+  readonly recipients: readonly ProcessingRecipient[];
+  /** The capability that declared it, or `config` for the adopter's own. */
+  readonly declaredBy: string;
+}
+
+/** What resolving reads off a composed capability. */
+interface ActivityDeclarer {
+  readonly name: string;
+  readonly processing?: readonly ProcessingActivity[];
+}
+
+/** One declared activity, before any override. */
+function resolved(activity: ProcessingActivity, declaredBy: string, source: BasisSource): ResolvedActivity {
+  return {
+    id: activity.id,
+    purpose: activity.purpose,
+    classes: [...activity.classes],
+    legalBasis: activity.legalBasis ?? null,
+    basisSource: activity.legalBasis === undefined ? null : source,
+    consentPurpose: activity.consentPurpose ?? null,
+    recipients: activity.recipients.map((recipient) => ({ ...recipient, classes: [...recipient.classes] })),
+    declaredBy,
+  };
+}
+
+/**
+ * Every activity as it takes effect over a composition: each capability's, in composition order, then the adopter's,
+ * with the block's overrides applied. Refuses an adopter activity under a composed capability's domain, an id declared
+ * twice, and an override naming an activity no composed capability declares. Called when a Worker assembles.
+ */
+export function resolveProcessing(
+  policy: ProcessingPolicy,
+  capabilities: readonly ActivityDeclarer[],
+): ResolvedActivity[] {
+  const reserved = new Set(capabilities.map((capability) => capability.name));
+  const own = parseProcessingActivities("pithy.config.ts", policy.activities ?? [], null, reserved);
+  const declared = capabilities.flatMap((capability) =>
+    (capability.processing ?? []).map((activity) => resolved(activity, capability.name, "capability")),
+  );
+  const ids = new Set<string>();
+  for (const activity of declared) {
+    if (ids.has(activity.id)) {
+      throw new ValidationError({
+        message: `The processing activity "${activity.id}" is declared twice.`,
+        action: "Declare each activity once.",
+      });
+    }
+    ids.add(activity.id);
+  }
+  const overrides = policy.overrides ?? {};
+  for (const id of Object.keys(overrides)) {
+    if (own.some((activity) => activity.id === id)) {
+      throw new ValidationError({
+        message: `The processing block overrides "${id}", which is declared in the same block.`,
+        action: `State its legal basis on the activity itself.`,
+      });
+    }
+    if (!ids.has(id)) {
+      throw new ValidationError({
+        message: `The processing block overrides "${id}", which no composed capability declares.`,
+        action: "Name an activity a composed capability declares. `GET /control-plane/processing` lists them.",
+      });
+    }
+  }
+  const overridden = declared.map((activity): ResolvedActivity => {
+    const override = overrides[activity.id];
+    if (override === undefined) return activity;
+    const consentPurpose =
+      override.legalBasis === "consent" ? (override.consentPurpose ?? activity.consentPurpose) : null;
+    return { ...activity, legalBasis: override.legalBasis, basisSource: "config", consentPurpose };
+  });
+  return [...overridden, ...own.map((activity) => resolved(activity, "config", "config"))];
+}

package/src/processing/composed.ts

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import { parseProcessingPolicy, type ResolvedActivity, resolveProcessing } from "./activity";
+
+/**
+ * The processing activities as this Worker resolved them at assembly, reachable from module scope, so the control
+ * plane reads the same record `createBackend` refused or accepted. One Worker assembles one backend; a second assembly
+ * in one isolate replaces the first wholesale, as `../retention/composed.ts` does for the retention policy.
+ */
+
+/** Parse and resolve a Worker's `processing` block over what it composes, or refuse it. */
+export function effectiveProcessing(block: unknown, capabilities: readonly Capability[]): ResolvedActivity[] {
+  return resolveProcessing(parseProcessingPolicy(block), capabilities);
+}
+
+let recorded: readonly ResolvedActivity[] | null = null;
+
+/** Record the resolved activities. Called once by `createBackend`. */
+export function recordProcessing(activities: readonly ResolvedActivity[]): void {
+  recorded = activities;
+}
+
+/** Forget them. For a test that needs the un-assembled state back. */
+export function forgetProcessing(): void {
+  recorded = null;
+}
+
+/** The resolved activities, or `null` before any backend has been assembled in this isolate. */
+export function composedProcessing(): readonly ResolvedActivity[] | null {
+  return recorded;
+}

package/src/processing/vocabulary.ts

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/** The processing record's closed vocabularies, apart from the walk that fills them, so a browser may import them. */
+
+/** What kind of gap the record names. */
+export const PROCESSING_GAP_KINDS = [
+  "no-legal-basis",
+  "no-consent-purpose",
+  "class-not-stored",
+  "class-unclaimed",
+  "phi-not-covered",
+  "no-standing-grant",
+] as const;
+export type ProcessingGapKindId = (typeof PROCESSING_GAP_KINDS)[number];
+
+/** Where a recipient came from. */
+export const RECIPIENT_SOURCES = ["platform", "binding", "declared"] as const;
+export type RecipientSource = (typeof RECIPIENT_SOURCES)[number];
+
+/** Where a legal basis came from: the declaring capability, or the `processing` block. */
+export const BASIS_SOURCES = ["capability", "config"] as const;
+export type BasisSource = (typeof BASIS_SOURCES)[number];
+
+/** The six lawful bases of GDPR Article 6(1), (a) to (f), in that order. */
+export const LEGAL_BASES = [
+  "consent",
+  "contract",
+  "legal-obligation",
+  "vital-interests",
+  "public-task",
+  "legitimate-interests",
+] as const;
+
+/** One lawful basis for processing. */
+export const LegalBasis = z
+  .enum(LEGAL_BASES)
+  .describe(
+    "The lawful basis of GDPR Article 6(1): `consent` (a), `contract` (b), `legal-obligation` (c), `vital-interests` (d), `public-task` (e) or `legitimate-interests` (f). A `consent` basis names the consent purpose it rests on.",
+  );
+export type LegalBasis = z.infer<typeof LegalBasis>;

package/src/queue/consumer.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ExecutionContext } from "@cloudflare/workers-types";
+import type { Logger } from "../logger/logger";
+
+/**
+ * **A capability's queue consumer, and how one Worker's `queue` export finds it (#824).**
+ *
+ * A Worker has one `queue` handler for every queue it consumes, the way it has one `email` and one `scheduled`.
+ * Which capability a message belongs to cannot be read off the batch: `batch.queue` is the provisioned name,
+ * `<project>-<env>-<thing>`, which no capability knows at runtime and which a long name truncates. So the message
+ * says it: every body a capability sends carries its own name under {@link QUEUE_CAPABILITY_FIELD}, built with
+ * {@link queueBody}, and the dispatcher hands each capability exactly the messages that name it.
+ *
+ * **A message no composed capability claims is acknowledged and logged**, never retried. Retrying cannot make a
+ * capability appear, so a retry would only walk the message to its dead-letter queue and count it as a delivery
+ * failure it never was.
+ *
+ * **A handler that throws costs its own messages, and nothing else.** Every other capability's messages are still
+ * handed over; the first failure is rethrown after the pass, so the invocation is recorded as failed and the runtime
+ * retries what was neither acknowledged nor retried.
+ */
+
+/**
+ * One delivered message, as much of the runtime's as a consumer touches. Stated here rather than imported, so the
+ * Workers types' `Message` — a word half the kit uses for other things — never becomes a name the kit reaches for.
+ */
+export interface QueueMessage {
+  /** The runtime's id for this delivery. */
+  readonly id: string;
+  /** The body as sent. */
+  readonly body: unknown;
+  /** How many times this message has been delivered, this one included. Starts at 1. */
+  readonly attempts: number;
+  /** Settle it: delivered, never to be seen again. */
+  ack(): void;
+  /** Settle it: deliver it again after the delay, or to the dead-letter queue once retries are spent. */
+  retry(options?: { delaySeconds?: number }): void;
+}
+
+/** One batch the runtime hands a Worker's `queue` export. */
+export interface QueueBatch {
+  /** The provisioned queue's name. */
+  readonly queue: string;
+  /** Its messages. */
+  readonly messages: readonly QueueMessage[];
+}
+
+/** The body field that names the capability a queue message belongs to. */
+export const QUEUE_CAPABILITY_FIELD = "capability";
+
+/** A capability's queue handler: the messages that name it, from one batch. */
+export type CapabilityQueueHandler = (
+  messages: readonly QueueMessage[],
+  env: Record<string, unknown>,
+  ctx: ExecutionContext,
+) => Promise<void>;
+
+/** A message body, stamped with the capability it belongs to so the Worker's one `queue` export can route it. */
+export function queueBody<const Capability extends string, const Body extends Record<string, unknown>>(
+  capability: Capability,
+  body: Body,
+): Body & { capability: Capability } {
+  return { ...body, capability };
+}
+
+/** The capability a message body names, or null when it names none. */
+export function queueMessageCapability(body: unknown): string | null {
+  if (typeof body !== "object" || body === null) return null;
+  const value = (body as Record<string, unknown>)[QUEUE_CAPABILITY_FIELD];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/** Hand each composed capability the messages of one batch that name it. */
+export async function dispatchQueueBatch(
+  batch: QueueBatch,
+  handlers: ReadonlyMap<string, CapabilityQueueHandler>,
+  env: Record<string, unknown>,
+  ctx: ExecutionContext,
+  log?: Pick<Logger, "warn">,
+): Promise<void> {
+  const claimed = new Map<string, QueueMessage[]>();
+  for (const message of batch.messages) {
+    const capability = queueMessageCapability(message.body);
+    if (capability === null || !handlers.has(capability)) {
+      log?.warn("queue message unclaimed", { queue: batch.queue, messageId: message.id, capability });
+      message.ack();
+      continue;
+    }
+    const list = claimed.get(capability) ?? [];
+    list.push(message);
+    claimed.set(capability, list);
+  }
+  const failures: unknown[] = [];
+  for (const [capability, messages] of claimed) {
+    try {
+      await handlers.get(capability)?.(messages, env, ctx);
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  if (failures[0] !== undefined) throw failures[0];
+}