@ultimat3/jobs 29.3.2 → 30.0.0

package/src/subject-select.ts

@@ -0,0 +1,106 @@
+// How one run finds the subject's rows: through the app's own repositories (a `database()` over
+// the app's driver, so tenancy, the row observer and cache tags hold), a page at a time. A table's
+// rows are those whose key is in a page of its parent's rows — never a statement unbounded by a page.
+
+import { assert } from '@ultimat3/core';
+import type { EntityCore, Table } from '@ultimat3/entity';
+import { database, getEntity } from '@ultimat3/entity';
+import type { Subject } from './subject';
+import type { SubjectPlan, SubjectVia } from './subject-plan';
+
+export type SubjectRow = Readonly<Record<string, unknown>>;
+export type SubjectTable = Table<Record<string, unknown>>;
+
+export interface SubjectReader {
+  readonly plan: SubjectPlan;
+  readonly key: string;
+  readonly size: number;
+  table(entity: string): SubjectTable;
+  core(entity: string): EntityCore;
+  /** The subject's row, read now — never checkpointed, since it is the person's data. */
+  rootRow(): Promise<SubjectRow | null>;
+  /** Every row of `entity` the plan reaches, a page at a time. A row two paths reach comes twice. */
+  pages(entity: string): AsyncGenerator<readonly SubjectRow[]>;
+  /** The values `via` matches on, a page of the parent's rows at a time. */
+  parentKeys(via: SubjectVia): AsyncGenerator<readonly unknown[]>;
+}
+
+/** The primary key of one row as one string: what tells two pages' copies of a row apart. */
+export const rowIdentity = (core: EntityCore, row: SubjectRow): string =>
+  JSON.stringify(core.$primaryKey.map((property) => String(row[property])));
+
+export function subjectReader<I>(
+  subject: Subject<I>,
+  plan: SubjectPlan,
+  key: string,
+): SubjectReader {
+  const cores = new Map<string, EntityCore>();
+  for (const name of [plan.subject, ...plan.steps.map((step) => step.entity)]) {
+    const core = getEntity(name)?.core;
+    assert(
+      core !== undefined,
+      `the subject ${plan.subject} reaches ${name}, which registered no entity core`,
+      `x exercise --json   # lists the subject's reach; declare ${name} with entity() before the subject runs`,
+    );
+    cores.set(name, core as EntityCore);
+  }
+  const db = database(Object.fromEntries(cores), { driver: subject.init.driver });
+  const tables = new Map<string, SubjectTable>(
+    Object.entries(db).map(([name, table]) => [name, table as unknown as SubjectTable]),
+  );
+  const steps = new Map(plan.steps.map((step) => [step.entity, step]));
+  const size = subject.batch;
+
+  const table = (entity: string): SubjectTable => {
+    const found = tables.get(entity);
+    assert(
+      found !== undefined,
+      `the subject ${plan.subject} asked for ${entity}, which its plan does not reach`,
+      `x exercise --json   # prints the subject's plan`,
+    );
+    return found;
+  };
+  const rootRow = (): Promise<SubjectRow | null> =>
+    table(plan.subject)
+      .where({ [plan.key]: key })
+      .one();
+
+  async function* parentKeys(via: SubjectVia): AsyncGenerator<readonly unknown[]> {
+    if (via.parent === plan.subject) {
+      const row = await rootRow();
+      const value = row?.[via.parentKey];
+      if (value !== undefined && value !== null) yield [value];
+      return;
+    }
+    for await (const page of pages(via.parent)) {
+      const values = new Set(page.map((row) => row[via.parentKey]));
+      values.delete(null);
+      values.delete(undefined);
+      if (values.size > 0) yield [...values];
+    }
+  }
+
+  async function* pages(entity: string): AsyncGenerator<readonly SubjectRow[]> {
+    if (entity === plan.subject) {
+      const row = await rootRow();
+      if (row !== null) yield [row];
+      return;
+    }
+    for (const via of steps.get(entity)?.via ?? []) {
+      for await (const values of parentKeys(via)) {
+        yield* table(entity).andWhere(via.property, 'in', values).inBatches(size);
+      }
+    }
+  }
+
+  return {
+    plan,
+    key,
+    size,
+    table,
+    core: (entity) => cores.get(entity) as EntityCore,
+    rootRow,
+    pages,
+    parentKeys,
+  };
+}

package/src/subject.ts

@@ -0,0 +1,119 @@
+// `defineSubject()`: one person's data, declared once — which entity they are, how to find their
+// row, and what happens to every table holding something of theirs. A plain value both factories
+// take (`subjectExport`, `subjectErase`); the reach itself is derived from foreign keys
+// (`subject-plan.ts`), so a table added next month is a build error until it has a treatment.
+
+import { assert } from '@ultimat3/core';
+import type { Driver, EntityCore } from '@ultimat3/entity';
+import type { ExportValue } from './export-format';
+
+/**
+ * What happens to one table's rows of the subject. Nothing defaults (axiom 8): which law applies,
+ * what is kept and for how long are the app's, so every reached table states one of the three.
+ */
+export type SubjectTreatment =
+  | 'delete'
+  /** Overwrite these columns, keep the row. A key set to `null` unlinks it from the subject. */
+  | { readonly anonymize: Readonly<Record<string, unknown>> }
+  /** Keep the row as it is. The reason is required and printed in the export's index. */
+  | { readonly retain: string };
+
+/** The subject as one run sees it: the key it was asked for and its row, read fresh per step. */
+export interface SubjectRef {
+  readonly key: string;
+  readonly row: Readonly<Record<string, unknown>>;
+}
+
+/** One page a target answers for an export: rows over `columns`, and where the next page starts. */
+export interface SubjectTargetPage {
+  readonly rows: readonly Readonly<Record<string, ExportValue>>[];
+  readonly cursor: string | null;
+}
+
+/**
+ * Data the framework holds outside an app's entities — `x_users`, `x_audit`, stored files —
+ * behind the narrowest seam, structural exactly as `PurgeTarget` is: `@ultimat3/auth`,
+ * `@ultimat3/action` and `@ultimat3/storage` each satisfy it without this package importing them.
+ */
+export interface SubjectTarget {
+  /** The step key, the export's object prefix and the report's row. Unique within one subject. */
+  readonly name: string;
+  /** The keys of every row `exportPage` answers, in order: the csv header, the ndjson key order. */
+  readonly columns: readonly string[];
+  exportPage(subject: SubjectRef, cursor: string | null, size: number): Promise<SubjectTargetPage>;
+  /** Remove up to `size` of the subject's records and answer how many went; called until short. */
+  erase(subject: SubjectRef, size: number): Promise<number>;
+}
+
+/** A target the erase leaves alone: still exported, never erased, the reason printed. */
+export interface RetainedTarget {
+  readonly target: SubjectTarget;
+  readonly retain: string;
+}
+
+export type SubjectTargetEntry = SubjectTarget | RetainedTarget;
+
+export interface SubjectInit<I> {
+  /** The driver the app's own `database()` reads through, so tenancy and row observers hold. */
+  readonly driver: Driver;
+  /** The subject's primary key, from the job's input. */
+  readonly key: (input: I) => string;
+  /** By entity name: every table the subject reaches, the subject's own included. */
+  readonly tables: Readonly<Record<string, SubjectTreatment>>;
+  readonly targets?: readonly SubjectTargetEntry[];
+  /**
+   * By entity name: a column holding the subject's key with no foreign key to say so. A table the
+   * reference walk cannot see is invisible until it is listed here, and then it needs a treatment.
+   */
+  readonly columns?: Readonly<Record<string, string>>;
+  /** Rows per statement and per step. Default `DEFAULT_SUBJECT_BATCH`. */
+  readonly batch?: number;
+}
+
+export interface Subject<I> {
+  /** The subject entity's name. */
+  readonly entity: string;
+  readonly init: SubjectInit<I>;
+  readonly batch: number;
+}
+
+/** One statement's worth of one person's rows: small, since a run is one person, never a table. */
+export const DEFAULT_SUBJECT_BATCH = 200;
+
+const declared: Subject<never>[] = [];
+
+export const isRetainedTarget = (entry: SubjectTargetEntry): entry is RetainedTarget =>
+  'retain' in entry && 'target' in entry;
+
+export const targetOf = (entry: SubjectTargetEntry): SubjectTarget =>
+  isRetainedTarget(entry) ? entry.target : entry;
+
+/**
+ * Declare the subject. Checked here only for what needs no other entity — the reach is checked
+ * when a run plans it and by `x exercise`, once every entity module has loaded.
+ */
+export function defineSubject<I>(entity: EntityCore, init: SubjectInit<I>): Subject<I> {
+  const batch = init.batch ?? DEFAULT_SUBJECT_BATCH;
+  assert(
+    Number.isSafeInteger(batch) && batch >= 1,
+    `defineSubject(${entity.$name}) declares batch: ${String(batch)}`,
+    `batch: ${DEFAULT_SUBJECT_BATCH}   # in defineSubject(${entity.$name}, …): rows per statement, at least one`,
+  );
+  const names = (init.targets ?? []).map((entry) => targetOf(entry).name);
+  assert(
+    new Set(names).size === names.length,
+    `defineSubject(${entity.$name}) lists targets with one name twice: ${names.join(', ')}`,
+    `targets: [ … ]   # in defineSubject(${entity.$name}, …): one entry per target name — the name is the step key`,
+  );
+  const subject: Subject<I> = { entity: entity.$name, init, batch };
+  declared.push(subject as Subject<never>);
+  return subject;
+}
+
+/** Every subject declared in this process, in declaration order. Read by `x exercise`. */
+export const registeredSubjects = (): readonly Subject<never>[] => [...declared];
+
+/** Test-only: forget every declared subject. */
+export function resetSubjects(): void {
+  declared.length = 0;
+}

package/src/tenant.ts

@@ -4,8 +4,10 @@
 // by every job is the cross-tenant read this declaration exists to make impossible.
 
 import type { Actor } from '@ultimat3/core';
-import { assert } from '@ultimat3/core';
+import { assert, isUltimateError, renderFixShellArg, tryUseContext } from '@ultimat3/core';
+import { assertRowTenant, ORG_COLUMN } from '@ultimat3/entity';
 import { JobTenantRequiredError } from './errors';
+import { JobTenantMismatchError } from './errors-tenant';
 
 /** The literal a job spells when it belongs to no tenant. */
 export const NO_JOB_TENANT = 'none';
@@ -59,3 +61,69 @@ export function jobRunActor(actor: Actor, orgId: string | undefined): Actor {
   if (actor.orgId === orgId) return actor;
   return Object.freeze({ ...actor, orgId });
 }
+
+/**
+ * The enqueue's half of the rule: a job whose payload names org A is refused when the enqueue says
+ * org B — an explicit `tenantId`, the org `handle.as(actor, …)` stamped, or the AMBIENT actor's
+ * org when one is present. It used to queue, and the run then acted as A for a caller in B.
+ * `tenant: 'none'` declares no org, so there is nothing to disagree with. The ambient half alone
+ * has one escape, entity's: a proven `crossTenant(reason, fn)` (`crossTenantAdmits`).
+ */
+export function refuseEnqueueTenant(
+  job: string,
+  declared: string | undefined,
+  tenantId: string | undefined,
+): void {
+  if (declared === undefined) return;
+  if (tenantId !== undefined && tenantId !== declared) {
+    throw new JobTenantMismatchError({
+      job,
+      reason: `was enqueued for org "${tenantId}" while its payload names org "${declared}", so its run would act for an org the enqueuer is not in`,
+      fix: `${job}.enqueue(input)   # from the org the payload names — an actor of "${declared}" — or with input naming "${tenantId}"`,
+    });
+  }
+  const ambient = tryUseContext()?.actor?.orgId;
+  if (ambient !== undefined && ambient !== declared && !crossTenantAdmits(job, declared)) {
+    throw new JobTenantMismatchError({
+      job,
+      reason: `was enqueued by an actor of org "${ambient}" while its payload names org "${declared}"`,
+      fix: `${job}.enqueue(input)   # from an actor of "${declared}", with input naming "${ambient}", or inside crossTenant('<why>', () => ${job}.enqueue(input)) by an actor holding tenancy:cross`,
+    });
+  }
+}
+
+/**
+ * Whether an enclosing `crossTenant(reason, fn)` admits a payload naming `declared` — asked of
+ * `@ultimat3/entity`'s own write guard, the one place that proof is read: the payload's org is a
+ * tenant value the ambient actor is writing. Inside a proven scope the guard re-proves
+ * `tenancy:cross` and passes (a swapped-in actor without it is `X_TENANCY_CROSS_DENIED`, thrown
+ * through); outside, its mismatch is the answer `false`. Called only once the ambient org is known
+ * to differ, so outside a scope it always disagrees. The explicit `tenantId` half is never admitted:
+ * that row would be queued for one org and refused at its run, which reads no proof.
+ */
+function crossTenantAdmits(job: string, declared: string): boolean {
+  try {
+    assertRowTenant(job, ORG_COLUMN, 'enqueue', { [ORG_COLUMN]: declared });
+    return true;
+  } catch (error) {
+    if (isUltimateError(error) && error.code === 'X_TENANCY_ACTOR_MISMATCH') return false;
+    throw error;
+  }
+}
+
+/**
+ * The run's half, for a row queued before the enqueue refused it: the org the row was queued for
+ * against the org its payload declares. Terminal — the same row disagrees on every attempt.
+ */
+export function refuseRunTenant(
+  job: string,
+  declared: string | undefined,
+  queuedFor: string | undefined,
+): void {
+  if (declared === undefined || queuedFor === undefined || queuedFor === declared) return;
+  throw new JobTenantMismatchError({
+    job,
+    reason: `was queued for org "${queuedFor}" while its payload names org "${declared}"`,
+    fix: `x jobs list --name ${renderFixShellArg(job, '<job>')} --state dead --json   # this row is dead: re-enqueue it from an actor of the org its payload names, never x jobs retry it`,
+  });
+}

package/src/type-pins.ts

@@ -0,0 +1,90 @@
+// Compile-time pins for what a step answers. Source, not a `.test.ts`, on purpose: `tsconfig.json`
+// excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a claim written there can
+// never fail. Nothing here is called — a regression is a build error (axiom 3).
+
+import { t } from '@ultimat3/schema';
+import type { StepApi, StepOutput } from './steps';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+/** Exact, both ways; assignability alone cannot tell a `readonly` or an optional member apart. */
+type Same<A, B> =
+  (<X>() => X extends A ? 1 : 2) extends <X>() => X extends B ? 1 : 2 ? true : false;
+
+type UserId = string & { readonly __brand: 'UserId' };
+
+interface Row {
+  readonly id: UserId;
+  readonly at: Date;
+  readonly maybeAt: Date | null;
+  nick?: string;
+  gone: string | undefined;
+  load(): void;
+}
+
+export type StepOutputPins = [
+  // A `Date` read off a step result is a compile error at the read.
+  Assert<Same<StepOutput<Date>, string>>,
+  Assert<Same<StepOutput<{ toJSON(): { wire: true } }>, { wire: true }>>,
+  // A brand survives: it is a string on the wire and in the type.
+  Assert<Same<StepOutput<UserId>, UserId>>,
+  // `undefined` at the top is the `null` the store holds.
+  Assert<Same<StepOutput<string | undefined>, string | null>>,
+  Assert<Same<StepOutput<undefined>, null>>,
+  // A readonly array stays one, and an element undefined is `null`, as `JSON.stringify` writes it.
+  Assert<Same<StepOutput<readonly Date[]>, readonly string[]>>,
+  Assert<Same<StepOutput<(number | undefined)[]>, (number | null)[]>>,
+  Assert<Same<StepOutput<readonly [Date, number]>, readonly [string, number]>>,
+  // `void` stays `void`: nobody reads it, and an `async () => {}` step must keep compiling.
+  Assert<Same<StepOutput<void>, void>>,
+  // `unknown` promises nothing and stays that way.
+  Assert<Same<StepOutput<unknown>, unknown>>,
+  Assert<Same<StepOutput<{ a: unknown }>, { a: unknown }>>,
+  // Members: readonly and optional kept, a function dropped, a `T | undefined` one may be absent.
+  Assert<
+    Same<
+      StepOutput<Row>,
+      {
+        readonly id: UserId;
+        readonly at: string;
+        readonly maybeAt: string | null;
+        nick?: string;
+        gone?: string;
+      }
+    >
+  >,
+  // A `Map` writes `{}`, and its `size` is not on the wire.
+  Assert<Same<StepOutput<Map<string, number>>, Record<string, never>>>,
+  Assert<Same<StepOutput<RegExp>, Record<string, never>>>,
+  // `message`, `name` and `stack` are not own enumerable; only what a subclass adds is written.
+  Assert<Same<keyof StepOutput<Error>, never>>,
+  Assert<Same<StepOutput<Error & { readonly status: number }>, { readonly status: number }>>,
+  // An object keyed by index, with no `length` on the wire.
+  Assert<Same<StepOutput<Uint8Array>, Record<string, number>>>,
+  // `bigint` never arrives: X_STEP_OUTPUT_UNSERIALIZABLE.
+  Assert<Same<StepOutput<bigint>, never>>,
+];
+
+const Approval = t.object({ amount: t.number });
+
+/** Never called: the point is the types of what it reads. */
+export async function waitForEventPins(step: StepApi): Promise<void> {
+  const answer = await step.waitForEvent('approval', 'invoice.approved', { schema: Approval });
+  const pinned: Assert<Same<typeof answer, { amount: number } | undefined>> = true;
+  void pinned;
+
+  // @ts-expect-error `schema` is required: a waiter's own type would be a cast, not a fact.
+  await step.waitForEvent('approval', 'invoice.approved', { timeout: '1h' });
+  // @ts-expect-error the options are required, because `schema` is.
+  await step.waitForEvent('approval', 'invoice.approved');
+  // @ts-expect-error `<T>` is gone: the schema is what decides the type.
+  await step.waitForEvent<{ amount: number }>('approval', 'invoice.approved', { schema: Approval });
+
+  const stamp = await step.run('stamp', () => new Date(0));
+  // @ts-expect-error a `Date` is a string by the time a step answers it; `new Date(stamp)`.
+  void stamp.getTime();
+  const row = await step.run('load', () => Promise.resolve<{ id: string } | undefined>(undefined));
+  const missed: Assert<Same<typeof row, { id: string } | null>> = true;
+  void missed;
+}

package/src/webhook-errors.ts

@@ -1,5 +1,5 @@
 // The eight `X_WEBHOOK_*` codes an outbound delivery can end on, apart from `errors.ts` for the
-// reason `backfill-errors.ts` is: one file, one job, and `errors.ts` holds the registry. The codes,
+// reason `backfill-errors.ts` is: one file, one job, and `error-codes.ts` holds the registry. The codes,
 // the titles and the single `registerErrorCodes()` call stay there; only the classes live here.
 //
 // THE RULE THIS FILE EXISTS TO KEEP: no secret and no signature reaches a `cause`, a `fix` or a

package/src/webhook-receiver-errors.ts

@@ -0,0 +1,59 @@
+// The two codes an inbound `webhookReceiver()` owns: a declaration that cannot be served, and a
+// verified delivery the queue would not take. Classes only; `error-codes.ts` registers the codes.
+// No body, no header and no secret ever reaches a cause: a refusal is read by the log store.
+
+import { renderThrowable, UltimateError } from '@ultimat3/core';
+
+/** Seconds a vendor is told to wait before redelivering after the queue refused. */
+export const WEBHOOK_RECEIVER_RETRY_AFTER_SECONDS = 30;
+
+/** Refused at declaration, while modules load: no request is ever answered with it. */
+export class WebhookReceiverInvalidError extends UltimateError {
+  constructor(input: { receiver: string; field: string; reason: string; fix: string }) {
+    super({
+      code: 'X_WEBHOOK_RECEIVER_INVALID',
+      cause: `webhookReceiver("${input.receiver}") ${input.field} ${input.reason}`,
+      fix: `webhookReceiver({ name: '${input.receiver}', ${input.fix}, … })`,
+      meta: { receiver: input.receiver, field: input.field },
+    });
+  }
+}
+
+/** What `verify` may answer as an event id: 1-256 printable ASCII characters, no space. */
+export const WEBHOOK_EVENT_ID_PATTERN = /^[\x21-\x7e]{1,256}$/;
+
+/**
+ * `verify` answered an id no job may be keyed by. A 4xx, never a 5xx: a vendor retries a 5xx
+ * forever and the answer would never change. The id itself is never echoed, only its length: an
+ * 8,000-character header is not a value to put in a log line or a response.
+ */
+export class WebhookEventIdInvalidError extends UltimateError {
+  constructor(input: { receiver: string; length: number }) {
+    super({
+      code: 'X_WEBHOOK_EVENT_ID_INVALID',
+      cause: `webhookReceiver("${input.receiver}") verify answered an eventId of ${input.length} characters that is not 1-256 printable ASCII characters`,
+      fix: `webhookReceiver({ name: '${input.receiver}', verify: (inbound) => ({ eventId }) }) — read eventId out of the signed bytes (verifyBodyHmac(...).text), 1-256 printable ASCII characters`,
+      meta: { receiver: input.receiver, length: input.length },
+    });
+  }
+}
+
+/**
+ * The enqueue failed, so the delivery is NOT acknowledged: 503 with `Retry-After` through the error
+ * map (`meta.retryAfterSeconds`), and the vendor redelivers. The inner failure goes through core's
+ * total renderer — it is a caught `unknown`.
+ */
+export class WebhookReceiverUnavailableError extends UltimateError {
+  constructor(input: { receiver: string; eventId: string; error: unknown }) {
+    super({
+      code: 'X_WEBHOOK_RECEIVER_UNAVAILABLE',
+      cause: `webhookReceiver("${input.receiver}") verified event ${input.eventId} and could not queue it: ${renderThrowable(input.error)}`,
+      fix: 'x doctor --json   # then check DATABASE_URL on the web role; the vendor redelivers once the queue answers',
+      meta: {
+        receiver: input.receiver,
+        eventId: input.eventId,
+        retryAfterSeconds: WEBHOOK_RECEIVER_RETRY_AFTER_SECONDS,
+      },
+    });
+  }
+}

package/src/webhook-receiver-route.ts

@@ -0,0 +1,127 @@
+// The door `webhookReceiver()` mounts: read the bytes under `maxBytes`, ask `verify`, enqueue the
+// payload it verified durably, and only then answer 200 `{ ok, eventId, deduped }`. Nothing is
+// parsed before `verify` and no content type is required. An enqueue failure is 503 with
+// `Retry-After`, so the vendor redelivers: an ack never precedes the durable row.
+
+import { readWithinLimit } from '@ultimat3/core';
+import type { Route, RouteHandler, RouteMeta, UltimateRequest } from '@ultimat3/http';
+import { HttpError, jsonResponse } from '@ultimat3/http';
+import type { JsonValue } from '@ultimat3/schema';
+import type { JobHandle } from './job';
+import {
+  WEBHOOK_EVENT_ID_PATTERN,
+  WebhookEventIdInvalidError,
+  WebhookReceiverUnavailableError,
+} from './webhook-receiver-errors';
+import type {
+  WebhookInbound,
+  WebhookReceiverDefinition,
+  WebhookReceiverInput,
+} from './webhook-receiver-types';
+
+interface RouteSpec<P extends JsonValue> {
+  readonly definition: WebhookReceiverDefinition<P>;
+  readonly maxBytes: number;
+  readonly handle: JobHandle<WebhookReceiverInput>;
+}
+
+async function inboundOf(
+  request: UltimateRequest,
+  name: string,
+  maxBytes: number,
+): Promise<WebhookInbound> {
+  // Core's counting reader, NOT `bodyBytes()`: that one caps at `http.bodyLimitBytes`, and a
+  // receiver's own `maxBytes` is the number this route answers to, in either direction.
+  const read =
+    request.method === 'GET'
+      ? { bytes: new Uint8Array(0) }
+      : await readWithinLimit(request.raw.body, maxBytes);
+  if ('over' in read) {
+    throw new HttpError({
+      code: 'X_BODY_INVALID',
+      cause: `${request.pathname} body rejected: body is at least ${read.over} bytes, limit is ${maxBytes}`,
+      fix: `webhookReceiver({ name: '${name}', maxBytes: ${maxBytes * 2}, … }) — raise maxBytes to the largest delivery the vendor sends`,
+      meta: { maxBytes },
+    });
+  }
+  const { bytes } = read;
+  const raw = request.raw;
+  return {
+    bytes,
+    headers: raw.headers,
+    params: request.params,
+    url: request.url,
+    request: () =>
+      new Request(raw.url, {
+        method: raw.method,
+        headers: raw.headers,
+        ...(request.method === 'GET' ? {} : { body: new Uint8Array(bytes) }),
+      }),
+  };
+}
+
+export function receiverRoutes<P extends JsonValue>(spec: RouteSpec<P>): readonly Route[] {
+  const { definition, maxBytes, handle } = spec;
+  const rate = definition.rateLimit;
+  const meta: RouteMeta = {
+    name: `webhook.${definition.name}`,
+    // A vendor carries no session: the credential is the signature `verify` checks.
+    auth: 'public',
+    ...(rate === undefined
+      ? {}
+      : typeof rate === 'string'
+        ? { rateLimit: rate }
+        : { rateLimit: `webhook.${definition.name}`, rateLimitBucket: rate }),
+  };
+
+  const receive: RouteHandler = async (request) => {
+    const inbound = await inboundOf(request, definition.name, maxBytes);
+    const verified = await definition.verify(inbound);
+    if ('answer' in verified) return verified.answer;
+    // Bounded before it is a key, a response field or a cause: `typeof` first, because `verify`
+    // is app code and JS callers return what they like.
+    const eventId: unknown = verified.eventId;
+    if (typeof eventId !== 'string' || !WEBHOOK_EVENT_ID_PATTERN.test(eventId)) {
+      throw new WebhookEventIdInvalidError({
+        receiver: definition.name,
+        length: typeof eventId === 'string' ? eventId.length : 0,
+      });
+    }
+    const row: WebhookReceiverInput = {
+      eventId,
+      ...(verified.orgId === undefined ? {} : { orgId: verified.orgId }),
+      ...(verified.topic === undefined ? {} : { topic: verified.topic }),
+      payload: verified.payload,
+    };
+    // Outside the try: an org receiver whose `verify` named no org is the app's to fix, and a 503
+    // would have the vendor retry it forever.
+    const tenantId = handle.tenantFor(row);
+    let enqueued: Awaited<ReturnType<typeof handle.enqueue>>;
+    try {
+      // `outbox: false`: the row must be durable BEFORE the ack, never staged behind a commit.
+      enqueued = await handle.enqueue(row, {
+        outbox: false,
+        ...(tenantId === undefined ? {} : { tenantId }),
+      });
+    } catch (error) {
+      throw new WebhookReceiverUnavailableError({
+        receiver: definition.name,
+        eventId: row.eventId,
+        error,
+      });
+    }
+    return jsonResponse({ ok: true, eventId: row.eventId, deduped: enqueued.deduped });
+  };
+
+  const routes: Route[] = [{ method: 'POST', path: definition.path, handler: receive, meta }];
+  const handshake = definition.handshake;
+  if (handshake !== undefined) {
+    routes.push({
+      method: 'GET',
+      path: definition.path,
+      meta: { ...meta, name: `webhook.${definition.name}.handshake` },
+      handler: async (request) => handshake(await inboundOf(request, definition.name, maxBytes)),
+    });
+  }
+  return routes;
+}