@ultimat3/jobs 25.0.0 → 25.2.0

package/CLAUDE.md

@@ -227,7 +227,8 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
   reading per pass, duplicate names refused.
 - **`exportRows()`**: one object per PAGE, named by page index; NO cross-tenant escape.
 - **`webhook()`**: ONE event to ONE endpoint, no steps; each attempt but a CANCELLED one recorded
-  before the throw; `ledger.isDisabled` gates the socket. **The wire format is core's.**
+  before the throw; `ledger.isDisabled` gates the socket. **The wire format is core's.** An org
+  tenant reads `orgId` OFF THE INPUT; none, or not the run's org: TERMINAL `X_JOB_TENANT_MISMATCH`.
 - A `-fixture.ts` file does not ship; `backfill-pass-fixture.ts` raises a plain `Error` subclass on
   purpose (it stands in for app code).
 
@@ -301,6 +302,7 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 | `worker-loop.ts` | the claim loop's timer: wake, `again`, the kicks |
 | `driver-pg-outbox-sql.ts` | the `x_outbox` statements |
 | `errors-operator.ts` / `errors-requeue.ts` | the operator verbs' refusals; `requeue`'s |
+| `errors-tenant.ts` | `JobTenantMismatchError` |
 
 Which `-fixture.ts` harness each suite shares, and what each `.job.` suite proves:
 `docs/history/jobs.md`, "Moved 2026-10-01 — test harnesses".

package/README.md

@@ -502,13 +502,17 @@ subscription table, one `enqueue` per endpoint.
 import { memoryWebhookLedger, webhook } from '@ultimat3/jobs';
 
 declare const db: {
-  endpoints: { byId(id: string): Promise<{ id: string; url: string; secret: string } | null> };
+  endpoints: {
+    byId(id: string): Promise<{ id: string; orgId: string; url: string; secret: string } | null>;
+  };
   events: { byId(id: string): Promise<{ topic: string; body: string } | null> };
 };
 
 export const deliver = webhook({
   name: 'partner.webhooks',
-  tenant: 'none',
+  // The org that owns the endpoint, carried on every enqueue — or `tenant: 'none'` for endpoints
+  // no tenant owns. `tenant` is synchronous over the input, so the org rides beside the two ids.
+  tenant: ({ orgId }) => orgId,
   // Read once per ATTEMPT and never checkpointed: the endpoint carries a secret, and a step's
   // output is written to `x_job_steps`.
   endpoint: ({ endpointId }) => db.endpoints.byId(endpointId),
@@ -518,11 +522,11 @@ export const deliver = webhook({
 });
 
 // The fan-out is yours, because the subscription table is yours.
-declare function subscribersOf(topic: string): Promise<readonly { id: string }[]>;
+declare function subscribersOf(topic: string): Promise<readonly { id: string; orgId: string }[]>;
 declare const event: { readonly id: string };
 
 for (const endpoint of await subscribersOf('orders.paid')) {
-  await deliver.enqueue({ endpointId: endpoint.id, eventId: event.id });
+  await deliver.enqueue({ endpointId: endpoint.id, eventId: event.id, orgId: endpoint.orgId });
 }
 ```
 
@@ -558,6 +562,13 @@ re-exports (`X_HELPER_COPY`). Same argument `timing-safe-equal.ts` makes for its
 | the DRAIN never aborts a POST already on the wire; it stops one not yet sent | torn down, the job goes to the next pod, which re-POSTs the same event on every deploy. Finished, it is recorded like any other outcome — a real failure during the drain included |
 | re-enabling is always yours | an endpoint the framework un-disabled on its own is a retry loop with no end |
 | `WebhookLedger` is a seam, not a table | retention is seven years for one business and thirty days for the next, so shipping a schema would ship one of those answers |
+| an org-owned delivery carries `orgId` on its input | `tenant` is a synchronous function of the input, so an org looked up from the endpoint id would be a read before the run has an org to read under. `tenant: ({ orgId }) => orgId` needs it on every enqueue, and both seams are handed it. A tenant that reads no `orgId` (`'none'`, or 25.0.0's `({ endpointId }) => …`) enqueues without one, as before |
+| the payload's org is the run's org, or the delivery dies | a tenant that names no org for the payload, or an `orgId` that is not the org the run is under (with `tenant: 'none'`, any `orgId`), is `X_JOB_TENANT_MISMATCH` before either seam reads — **terminal**, dead-lettered on attempt 1, because the same row is refused on every attempt and by `x jobs retry` |
+
+**Upgrading a webhook to `tenant: ({ orgId }) => orgId`.** Deliveries already queued without an
+`orgId` dead-letter on their next attempt with `X_JOB_TENANT_MISMATCH`, and a retry cannot add the
+field. Drain the queue before deploying the new declaration, or re-enqueue what dead-letters with its
+org: `x jobs ls --state dead --name partner.webhooks --json`, then `deliver.enqueue({ endpointId, eventId, orgId })` for each.
 
 **Set `timeout` below the drain budget.** A webhook has no timeout unless you declare one, and a
 POST on the wire when SIGTERM lands runs until the receiver answers. With a `timeout`, a drained
@@ -867,18 +878,18 @@ hourly task fire 24 catch-ups a second apart.
 
 ### A `PgExecutor`
 
-`PgExecutor` is one method — `query(text, values)` — and the boot supplies it (`@ultimat3/cli`'s
-`pgExecutorFor(client)`). Outside the boot — a test, a script — build it over `@ultimat3/db`'s
-client, which already speaks `(text, values)` and decodes `jsonb`:
+`PgExecutor` is one method — `query(text, values)` — and there is ONE builder for it:
+`@ultimat3/db`'s `dbExecutor()`, which the boot uses too (`dbExecutor(() => client)`). It resolves
+its client per statement — by default the installed one, which inside `withTransaction` is the
+transaction's own connection — and that client already speaks `(text, values)` and decodes `jsonb`.
+Outside the boot — a test, a script — hand it the client to stay on:
 
 ```ts
-import { postgresClient } from '@ultimat3/db';
+import { dbExecutor, postgresClient } from '@ultimat3/db';
 import type { PgExecutor } from '@ultimat3/jobs';
 
 const client = postgresClient({ url: 'postgres://localhost:5432/app_test' });
-export const executor: PgExecutor = {
-  query: <R>(text: string, values: readonly unknown[]) => client.query<R>({ text, values }),
-};
+export const executor: PgExecutor = dbExecutor(() => client);
 ```
 
 | Not this | Because |
@@ -1294,6 +1305,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `JobRowStatusUnknownError` | `X_JOB_ROW_STATUS_UNKNOWN` | `src/errors.ts` |
 | `JobSlotLostError` | `X_JOB_SLOT_LOST` | `src/errors.ts` |
 | `JobTenantRequiredError` | `X_JOB_TENANT_REQUIRED` | `src/errors.ts` |
+| `JobTenantMismatchError` | `X_JOB_TENANT_MISMATCH` | `src/errors-tenant.ts` |
 | `JobTimeoutError` | `X_JOB_TIMEOUT` | `src/errors.ts` |
 | `LeaseLostError` | `X_JOB_LEASE_LOST` | `src/errors.ts` |
 | `OutboxNoTxError` | `X_OUTBOX_NO_TX` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/jobs",
-  "version": "25.0.0",
+  "version": "25.2.0",
   "description": "Durable background work: steps, transactional outbox, cron tasks, one driver interface",
   "license": "MIT",
   "type": "module",
@@ -32,10 +32,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "25.0.0",
-    "@ultimat3/db": "25.0.0",
-    "@ultimat3/entity": "25.0.0",
-    "@ultimat3/schema": "25.0.0",
-    "@ultimat3/time": "25.0.0"
+    "@ultimat3/core": "25.2.0",
+    "@ultimat3/db": "25.2.0",
+    "@ultimat3/entity": "25.2.0",
+    "@ultimat3/schema": "25.2.0",
+    "@ultimat3/time": "25.2.0"
   }
 }

package/src/errors-tenant.ts

@@ -0,0 +1,22 @@
+// The one refusal for a job whose PAYLOAD and declared tenant disagree — a webhook delivery's
+// `orgId` that is not the org the run is under, a tenant that derives no org from the payload, an
+// agent actor resolved in another org. Its code stays declared in `errors.ts`, classified terminal.
+
+import { UltimateError } from '@ultimat3/core';
+
+export class JobTenantMismatchError extends UltimateError {
+  constructor(input: {
+    readonly job: string;
+    /** What disagrees, in words — org ids only; never a secret, never a row. */
+    readonly reason: string;
+    /** The enqueue, or the declaration, that repairs it — specific to the caller. */
+    readonly fix: string;
+  }) {
+    super({
+      code: 'X_JOB_TENANT_MISMATCH',
+      cause: `job "${input.job}" ${input.reason} — the same payload is refused on every attempt, so it is dead-lettered on this one`,
+      fix: input.fix,
+      meta: { job: input.job },
+    });
+  }
+}

package/src/errors.ts

@@ -44,6 +44,7 @@ export const JOB_OWNED_ERROR_CODES = [
   'X_JOB_PAGE_INVALID',
   'X_JOB_ON_SETTLED_FAILED',
   'X_JOB_NOT_FOUND',
+  'X_JOB_TENANT_MISMATCH',
 ] as const;
 
 /**
@@ -102,6 +103,7 @@ export const JOB_ERROR_TITLES: Readonly<Record<JobOwnedErrorCode, string>> = {
   X_JOB_PAGE_INVALID: 'a job list page was asked for outside its bounds',
   X_JOB_ON_SETTLED_FAILED: 'the onSettled hook failed after the run was settled',
   X_JOB_NOT_FOUND: 'the queue holds no job with this id',
+  X_JOB_TENANT_MISMATCH: "a job's payload names an org other than the tenant it runs under",
 };
 
 // One unconditional call, so a second package claiming one of jobs' codes throws
@@ -155,6 +157,9 @@ registerErrorRetry({
   X_EXPORT_PART_TOO_LARGE: 'terminal',
   // The worker settles a busy key itself; listed so a body that RETHROWS one it was handed stops.
   X_JOB_KEY_BUSY: 'terminal',
+  // The payload names the wrong org, or none its tenant can run under — a fact about the ROW, so
+  // every attempt and every `x jobs retry` is refused identically: the repair is a new enqueue.
+  X_JOB_TENANT_MISMATCH: 'terminal',
 });
 
 // No `docs:` on any class below, here or in `backfill-errors.ts`. `UltimateError` fills it from

package/src/index.ts

@@ -153,6 +153,7 @@ export {
   JobPageInvalidError,
 } from './errors-operator';
 export { JobNotFoundError, JobNotRequeueableError } from './errors-requeue';
+export { JobTenantMismatchError } from './errors-tenant';
 export type { EventBus, JobEvent, MemoryEventBusOptions, PublishOptions } from './events';
 export {
   EVENTS_PURGE_TARGET,
@@ -361,6 +362,7 @@ export type {
   WebhookEndpoint,
   WebhookEvent,
   WebhookReport,
+  WebhookTenant,
 } from './webhook';
 export { DEFAULT_WEBHOOK_DISABLE_AFTER, webhook } from './webhook';
 export type { WebhookFetch } from './webhook-attempt';

package/src/webhook.ts

@@ -27,6 +27,7 @@ import {
 import { t } from '@ultimat3/schema';
 import type { DurationInput } from './clock';
 import { nowMs } from './clock';
+import { JobTenantMismatchError } from './errors-tenant';
 import type { JobHandle } from './job';
 import { job } from './job';
 import type { RetryPolicy } from './retry';
@@ -94,8 +95,23 @@ export interface WebhookDeliveryInput {
   readonly endpointId: string;
   /** Also the id the receiver dedupes on — it is signed, so it cannot be moved in transit. */
   readonly eventId: string;
+  /**
+   * The org that owns the endpoint, for a delivery declared `tenant: ({ orgId }) => orgId`. On the
+   * input because `tenant` is a synchronous function of the input alone — derived from the
+   * endpoint id it would be a read before the run has an org to read under. Neither signed nor
+   * sent: the receiver learns nothing it did not already know.
+   */
+  readonly orgId?: string | undefined;
 }
 
+/**
+ * Who a delivery runs as: `'none'`, or the org derived from its payload. May answer `undefined` —
+ * `({ orgId }) => orgId` over a row that carries none — and that answer is refused, TERMINALLY,
+ * before either seam reads (`X_JOB_TENANT_MISMATCH`). One signature for both shapes on purpose: a
+ * 25.0.0 `({ endpointId }) => …` that never reads `orgId` keeps enqueuing without one.
+ */
+export type WebhookTenant = 'none' | ((input: WebhookDeliveryInput) => string | undefined);
+
 /** What one landed delivery reports. Bounded, so `x jobs show` can print it. */
 export interface WebhookReport {
   readonly endpointId: string;
@@ -111,12 +127,13 @@ export interface WebhookDefinition {
    */
   readonly name: string;
   /**
-   * REQUIRED, exactly as on `job()`: `tenant: ({ endpointId }) => …` for a delivery scoped to the
-   * org that owns the endpoint, or the explicit `tenant: 'none'`. A delivery reads the app's own
-   * endpoint and event rows through the seams below, so the org those reads run under is a fact
-   * about the WORK and is declared here rather than inherited from whichever worker claimed it.
+   * REQUIRED, exactly as on `job()`: `tenant: ({ orgId }) => orgId` for a delivery scoped to the
+   * org that owns the endpoint — every enqueue then carries `orgId` — or the explicit
+   * `tenant: 'none'`. A delivery reads the app's own endpoint and event rows
+   * through the seams below, so the org those reads run under is a fact about the WORK and is
+   * declared here rather than inherited from whichever worker claimed it.
    */
-  readonly tenant: JobTenant<WebhookDeliveryInput>;
+  readonly tenant: WebhookTenant;
   /**
    * The endpoint this delivery is for. Read once PER ATTEMPT and never checkpointed: it carries a
    * secret, and a `step.run` output is written to `x_job_steps` — a credential in a durable table
@@ -124,11 +141,18 @@ export interface WebhookDefinition {
    */
   endpoint(args: {
     readonly endpointId: string;
+    /**
+     * The delivery's own `orgId`, off the input — by the time a seam runs, the org the run is
+     * under, or absent. Handed over so a seam names its tenant from the work rather than reading it
+     * back off `ctx.actor`.
+     */
+    readonly orgId: string | undefined;
     readonly ctx: Ctx;
   }): Promise<WebhookEndpoint | null> | WebhookEndpoint | null;
   /** The event's bytes. Read per attempt as well, out of the app's own table. */
   event(args: {
     readonly eventId: string;
+    readonly orgId: string | undefined;
     readonly ctx: Ctx;
   }): Promise<WebhookEvent | null> | WebhookEvent | null;
   /** Where every attempt is recorded, and where the consecutive-failure count comes from. */
@@ -175,11 +199,11 @@ export function webhook(definition: WebhookDefinition): JobHandle<WebhookDeliver
   // Named so `run` can read the deadline `job()` resolved — one parse of `timeout`, never two.
   const handle: JobHandle<WebhookDeliveryInput> = job<WebhookDeliveryInput>({
     name: definition.name,
-    input: t.object({ endpointId: t.string, eventId: t.string }),
+    input: t.object({ endpointId: t.string, eventId: t.string, orgId: t.optional(t.string) }),
     // Endpoint AND event: the same event fans out to every subscribed endpoint, so a key on the
     // event alone would dedupe every one of those deliveries into the first endpoint's row.
     idempotencyKey: ({ endpointId, eventId }) => `${definition.name}:${endpointId}:${eventId}`,
-    tenant: definition.tenant,
+    tenant: tenantOf(definition),
     retry: definition.retry ?? DEFAULT_RETRY,
     ...(definition.queue === undefined ? {} : { queue: definition.queue }),
     ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }),
@@ -194,7 +218,13 @@ export function webhook(definition: WebhookDefinition): JobHandle<WebhookDeliver
               job: definition.name,
               timeoutMs: handle.timeoutMs,
             };
-      const endpoint = await definition.endpoint({ endpointId: input.endpointId, ctx });
+      // Before either seam: the org they are handed must be the org every read runs under.
+      assertInputOrg(definition.name, input.orgId, ctx);
+      const endpoint = await definition.endpoint({
+        endpointId: input.endpointId,
+        orgId: input.orgId,
+        ctx,
+      });
       if (endpoint === null) {
         throw new WebhookEndpointUnknownError({
           webhook: definition.name,
@@ -222,7 +252,7 @@ export function webhook(definition: WebhookDefinition): JobHandle<WebhookDeliver
         resolve: definition.resolve ?? resolveWebhookHost,
       });
 
-      const event = await definition.event({ eventId: input.eventId, ctx });
+      const event = await definition.event({ eventId: input.eventId, orgId: input.orgId, ctx });
       if (event === null) {
         throw new WebhookEventUnknownError({ webhook: definition.name, eventId: input.eventId });
       }
@@ -323,6 +353,44 @@ export function webhook(definition: WebhookDefinition): JobHandle<WebhookDeliver
   return handle;
 }
 
+/**
+ * The declared tenant, asked as declared, with one refusal added: an answer that names NO org. Only
+ * then — a 25.0.0 `tenant: ({ endpointId }) => …` never reads `orgId` and needs none, so requiring
+ * one would refuse every delivery it queued. The usual cause is a row queued before `orgId` existed
+ * under a `({ orgId }) => orgId` declaration. Coded and TERMINAL rather than `jobTenantFor`'s
+ * `assert`: an unclassified refusal spent the whole retry policy, and `x jobs retry`, re-proving it.
+ */
+function tenantOf(definition: WebhookDefinition): JobTenant<WebhookDeliveryInput> {
+  const declared = definition.tenant;
+  if (typeof declared !== 'function') return declared;
+  return (input) => {
+    const orgId = declared(input);
+    if (typeof orgId === 'string' && orgId.length > 0) return orgId;
+    throw new JobTenantMismatchError({
+      job: definition.name,
+      reason: `declares an org tenant, and this delivery's payload names no org for it${input.orgId === undefined ? ' (it carries no orgId)' : ''}`,
+      fix: `${definition.name}.enqueue({ endpointId, eventId, orgId }) — re-enqueue it with the org that owns the endpoint; a queued row cannot be retried into having one`,
+    });
+  };
+}
+
+/**
+ * The org a seam is HANDED is the org the run is UNDER, or the delivery is refused before either
+ * seam reads: a lookup filtered by `orgId` would otherwise read another org's endpoint, secret and
+ * all, inside this org's run. With `tenant: 'none'` nothing would check it at all, so any `orgId`
+ * is refused there. Terminal for `tenantOf`'s reason — the payload is the same on every attempt.
+ */
+function assertInputOrg(name: string, orgId: string | undefined, ctx: Ctx): void {
+  if (orgId === undefined) return;
+  const runOrg = ctx.actor.orgId ?? undefined;
+  if (orgId === runOrg) return;
+  throw new JobTenantMismatchError({
+    job: name,
+    reason: `was handed orgId ${orgId}, but the run is under ${runOrg === undefined ? "tenant 'none'" : `org ${runOrg}`}`,
+    fix: `webhook({ name: '${name}', tenant: ({ orgId }) => orgId, … }) — derive the tenant from the payload's own org, or enqueue ${name} with the orgId its tenant resolves to`,
+  });
+}
+
 /** A URL no delivery may open, or a secret that would make the POST unsigned. The parsed url. */
 function assertDeliverable(name: string, endpoint: WebhookEndpoint): URL {
   if (endpoint.secret.length === 0) {