@ultimat3/jobs 1.2.0 → 2.0.0

package/src/steps.ts

@@ -10,7 +10,7 @@ import type { Clock } from '@ultimat3/core';
 import { logger } from '@ultimat3/core';
 import type { DurationInput } from './clock';
 import { nowMs, toMs } from './clock';
-import { JobTimeoutError, StepDuplicateError } from './errors';
+import { JobAbortedError, JobTimeoutError, StepDuplicateError } from './errors';
 
 export type StepStatus = 'completed' | 'sleeping' | 'waiting' | 'failed';
 
@@ -57,8 +57,14 @@ export interface WaitForEventOptions {
 }
 
 export interface StepApi {
-  /** Run once, ever. On replay the persisted output is returned and `fn` is not called. */
-  run<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+  /**
+   * Run once, ever. On replay the persisted output is returned and `fn` is not called.
+   *
+   * `fn` receives the step's `AbortSignal` — the run's cancellation and this step's own ceiling,
+   * whichever fires first. Hand it to `fetch`, or read `.aborted` in a loop: past it, this step
+   * may no longer write, because the attempt that replaced this one owns the run.
+   */
+  run<T>(name: string, fn: (signal: AbortSignal) => Promise<T> | T): Promise<T>;
   /** Suspend the run. `sleep(duration)` derives the step name from the duration. */
   sleep(name: string, duration: DurationInput): Promise<void>;
   sleep(duration: DurationInput): Promise<void>;
@@ -136,49 +142,148 @@ export interface StepRunnerOptions {
   readonly eventPollMs?: number;
   /** Per-step ceiling; the job-level timeout is enforced by the worker. */
   readonly stepTimeoutMs?: number;
+  /**
+   * The run's cancellation — `executeJob` aborts it at the job's deadline. Once aborted this
+   * runner writes nothing: the nack that follows a deadline makes the job claimable, so the
+   * store belongs to whichever attempt has it now.
+   */
+  readonly signal?: AbortSignal;
 }
 
 export interface StepRunner {
   readonly step: StepApi;
-  /** Names used in THIS attempt, in order — the trace shown by `x jobs show`. */
+  /**
+   * Names used in THIS attempt, in order — the trace shown by `x jobs show`. Bounded at
+   * `MAX_TRACE_NAMES`, oldest dropped: duplicate detection reads its own set, so this is a
+   * window on a long run and never the run's record.
+   */
   usedNames(): readonly string[];
-  /** Names that were served from storage instead of executed. */
+  /** Names that were served from storage instead of executed. Bounded the same way. */
   replayedNames(): readonly string[];
 }
 
+/** Stands in for an absent run signal, so the fence has one shape and no `undefined` branch. */
+const NEVER_ABORTED = new AbortController().signal;
+
+/**
+ * What one attempt's trace keeps. The trace is a diagnostic `x jobs show` renders, never the
+ * run's record — `driver.steps.list(runId)` is that — and a `backfill()` over a million rows
+ * claims 20,000 names in a single attempt, all of them carried to the end of the run.
+ */
+export const MAX_TRACE_NAMES = 200;
+
+/** Most recent first out: the tail of a long run is the half an operator is reading. */
+function trace(into: string[], name: string): void {
+  into.push(name);
+  if (into.length > MAX_TRACE_NAMES) into.shift();
+}
+
 export function createStepRunner(options: StepRunnerOptions): StepRunner {
   const { runId, jobName, store } = options;
+  /** Every name this attempt has claimed. Membership only — the trace is `used`. */
+  const claimed = new Set<string>();
   const used: string[] = [];
   const replayed: string[] = [];
   const clock = options.clock;
   const pollMs = options.eventPollMs ?? 30_000;
+  const runSignal = options.signal ?? NEVER_ABORTED;
+
+  /**
+   * This attempt's view of the run's persisted steps, hydrated from ONE `store.list(runId)` the
+   * first time a step asks. Replay used to cost one `SQL_STEP_GET` per completed step: a
+   * `backfill()` over 5M rows at `batch: 1000` is 5,000 steps, so an attempt killed at 4,800
+   * issued 4,800 sequential round trips before reading a single new row — and re-paid them on
+   * every retry, often outrunning its own visibility timeout while the heartbeat was still
+   * renewing.
+   *
+   * Sound because the fence in `put()` is: only the attempt that owns the run may write to it, so
+   * within one attempt an absent name stays absent unless this runner writes it. Writes go into
+   * the map as they go into the store, never the other way round — the store is still the record.
+   */
+  let hydrated: Map<string, StepRecord> | undefined;
+
+  const load = async (name: string): Promise<StepRecord | undefined> => {
+    if (hydrated === undefined) {
+      hydrated = new Map();
+      for (const record of await store.list(runId)) hydrated.set(record.name, record);
+    }
+    return hydrated.get(name);
+  };
+
+  /** Keep the hydrated view in step with what was just persisted. */
+  const remember = (record: StepRecord): void => {
+    hydrated?.set(record.name, record);
+  };
 
   const claimName = (name: string): void => {
-    if (used.includes(name)) throw new StepDuplicateError({ job: jobName, step: name });
-    used.push(name);
+    // The Set decides, the array only reports. `Array.includes` made a long run quadratic —
+    // `backfill({ batch: 50 })` over a million rows is 20,000 steps and ~200M string compares.
+    if (claimed.has(name)) throw new StepDuplicateError({ job: jobName, step: name });
+    claimed.add(name);
+    trace(used, name);
+  };
+
+  /**
+   * The one-argument `sleep('1h')` derives its step name from the duration, so a poll loop —
+   * `for (…) { await step.sleep('1h') }`, the form the docs show — minted `sleep:1h` twice and
+   * died with `X_STEP_DUPLICATE` on iteration 2. The occurrence ORDINAL disambiguates them, the
+   * way `backfill()`'s `batch:<index>` does: the body re-runs from the top on every replay, so
+   * the same sequence of calls mints the same sequence of names.
+   *
+   * The FIRST occurrence keeps the bare `sleep:1h`, so a run already suspended on one resumes
+   * across this change instead of re-sleeping under a new key.
+   */
+  const sleepOrdinals = new Map<string, number>();
+  const derivedSleepName = (duration: string): string => {
+    const base = `sleep:${duration}`;
+    const occurrence = (sleepOrdinals.get(base) ?? 0) + 1;
+    sleepOrdinals.set(base, occurrence);
+    return occurrence === 1 ? base : `${base}#${occurrence}`;
+  };
+
+  const cancelled = (): boolean => runSignal.aborted;
+
+  /**
+   * EVERY write this runner makes, and the one place the cancellation is enforced. A step result
+   * from a cancelled attempt is a write onto the attempt that replaced it: the deadline nacked
+   * this job, another worker claimed the same `runId`, and a late `put` would hand it a step it
+   * never ran — or overwrite one it did. The write is refused, and refusing it unwinds the body.
+   */
+  const put = async (record: StepRecord): Promise<void> => {
+    if (cancelled()) throw new JobAbortedError({ job: jobName, step: record.name });
+    await store.put(record);
+    remember(record);
   };
 
   const now = (): number => nowMs(clock);
 
-  async function run<T>(name: string, fn: () => Promise<T> | T): Promise<T> {
+  async function run<T>(name: string, fn: (signal: AbortSignal) => Promise<T> | T): Promise<T> {
     claimName(name);
-    const existing = await store.get(runId, name);
+    const existing = await load(name);
     if (existing?.status === 'completed') {
-      replayed.push(name);
+      trace(replayed, name);
       return existing.output as T;
     }
 
     const startedAt = existing?.startedAt ?? now();
     const attempts = (existing?.attempts ?? 0) + 1;
+    // The step's own ceiling, folded into the run's cancellation so the body reads ONE signal and
+    // sees whichever deadline lands first. Composed only when there is a second one to compose.
+    const deadline = new AbortController();
+    const signal =
+      options.stepTimeoutMs === undefined
+        ? runSignal
+        : AbortSignal.any([runSignal, deadline.signal]);
     try {
       const output = await withStepTimeout(
-        fn(),
+        fn(signal),
         options.stepTimeoutMs,
+        deadline,
         () =>
           new JobTimeoutError({ job: jobName, step: name, timeoutMs: options.stepTimeoutMs ?? 0 }),
       );
       // Persist BEFORE returning: a crash one line later must not re-run this step.
-      await store.put({
+      await put({
         runId,
         name,
         status: 'completed',
@@ -190,41 +295,50 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
       return output;
     } catch (error) {
       if (isStepSuspension(error)) throw error;
-      await store.put({
-        runId,
-        name,
-        status: 'failed',
-        startedAt,
-        attempts,
-        error: error instanceof Error ? error.message : String(error),
-      });
+      // The failure is this run's own history, so it is recorded on the way out — unless the
+      // attempt was cancelled, in which case the history is no longer ours to write. The original
+      // error is what the caller has to see, never one raised by the bookkeeping.
+      if (!cancelled()) {
+        // Deliberately NOT through `put`: the caller has to see the original error, never one
+        // raised by the bookkeeping. The hydrated view is updated by hand for the same reason.
+        const failure: StepRecord = {
+          runId,
+          name,
+          status: 'failed',
+          startedAt,
+          attempts,
+          error: error instanceof Error ? error.message : String(error),
+        };
+        await store.put(failure);
+        remember(failure);
+      }
       throw error;
     }
   }
 
   async function sleep(a: string | DurationInput, b?: DurationInput): Promise<void> {
     // `sleep('3d')` — the duration doubles as the step name, which stays deterministic.
-    const name = b === undefined ? `sleep:${String(a)}` : String(a);
+    const name = b === undefined ? derivedSleepName(String(a)) : String(a);
     const duration = b === undefined ? (a as DurationInput) : b;
     claimName(name);
 
-    const existing = await store.get(runId, name);
+    const existing = await load(name);
     if (existing?.status === 'completed') {
-      replayed.push(name);
+      trace(replayed, name);
       return;
     }
 
     const at = now();
     if (existing?.status === 'sleeping' && existing.wakeAt !== undefined) {
       if (existing.wakeAt <= at) {
-        await store.put({ ...existing, status: 'completed', completedAt: at });
+        await put({ ...existing, status: 'completed', completedAt: at });
         return;
       }
       throw new StepSuspension({ step: name, resumeAt: existing.wakeAt, reason: 'sleep' });
     }
 
     const wakeAt = at + toMs(duration);
-    await store.put({
+    await put({
       runId,
       name,
       status: 'sleeping',
@@ -241,9 +355,9 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
     waitOptions: WaitForEventOptions = {},
   ): Promise<T | undefined> {
     claimName(name);
-    const existing = await store.get(runId, name);
+    const existing = await load(name);
     if (existing?.status === 'completed') {
-      replayed.push(name);
+      trace(replayed, name);
       return existing.output as T | undefined;
     }
 
@@ -254,7 +368,7 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
 
     const hit = await options.events?.find(event, correlationKey, startedAt);
     if (hit !== undefined) {
-      await store.put({
+      await put({
         runId,
         name,
         status: 'completed',
@@ -277,7 +391,7 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
         });
       }
       logger.warn('jobs.step.wait-timeout', { job: jobName, step: name, event });
-      await store.put({
+      await put({
         runId,
         name,
         status: 'completed',
@@ -291,7 +405,7 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
     }
 
     const resumeAt = Math.min(deadline, at + pollMs);
-    await store.put({
+    await put({
       runId,
       name,
       status: 'waiting',
@@ -317,14 +431,24 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
   };
 }
 
+/**
+ * A step's own ceiling. It ABORTS before it rejects, in that order: `run()` fails the step on this
+ * rejection and the job retries, so a body still holding a socket open past the deadline would be
+ * racing the attempt that replaced it. Cancelling first is the only thing that can stop it.
+ */
 function withStepTimeout<T>(
   work: Promise<T> | T,
   timeoutMs: number | undefined,
+  deadline: AbortController,
   error: () => Error,
 ): Promise<T> {
   if (timeoutMs === undefined || timeoutMs <= 0) return Promise.resolve(work);
   return new Promise<T>((resolve, reject) => {
-    const timer = setTimeout(() => reject(error()), timeoutMs);
+    const timer = setTimeout(() => {
+      const failure = error();
+      deadline.abort(failure);
+      reject(failure);
+    }, timeoutMs);
     Promise.resolve(work).then(
       (value) => {
         clearTimeout(timer);

package/src/task.ts

@@ -0,0 +1,229 @@
+// The `task` primitive: a cron declaration and its registry. A task NEVER does work — it
+// enqueues jobs, so retries, idempotency and observability all come from the job machinery
+// instead of being re-invented per cron. `scheduler.ts` is what fires one.
+//
+// `tz` is required by the type. A cron without a timezone is a bug waiting for March: `0 3 *
+// * *` in a DST-observing zone runs twice or zero times on the switch day, and "the nightly
+// digest went out at 2am and again at 3am" is not a mystery anyone should have to debug.
+//
+// **The framework's DST answer, `As of 2026-08`: ONE occurrence per calendar day, at the first
+// valid instant.** Pinned against a real zone in `scheduler-dst.test.ts`, both transitions:
+//
+//   FALL BACK — the repeated wall-clock hour yields ONE occurrence, the first (CEST) instant. It
+//   has to: `scheduler.ts`'s `dispatch` keys the idempotency key on `occurrenceMs`, and the two
+//   instants of a repeated 02:00 genuinely differ, so two occurrences would be two keys and the
+//   nightly digest would go out twice — the exact failure a required `tz` exists to prevent.
+//   Nothing downstream could catch it.
+//   SPRING FORWARD — the missing hour SHIFTS forward (02:00 fires at 03:00), never skips. A
+//   skipped day is a billing run that silently never happened, which is worse than one an hour
+//   late, and `catchUp` cannot recover an occurrence that was never an occurrence.
+
+import { assert } from '@ultimat3/core';
+import { isValidTimeZone } from '@ultimat3/time';
+import { nowMs } from './clock';
+import type { EnqueueResult } from './driver';
+import { JobNameTakenError } from './errors';
+import type { AnyJobHandle } from './job';
+import type { EnqueueOptions } from './outbox';
+
+/** `[[sendDigest, {}]]` — a job handle plus its input. */
+export type TaskEnqueueEntry = readonly [AnyJobHandle, unknown];
+
+/**
+ * What to do when the scheduler was down across one or more occurrences.
+ * `skip` (default) collapses them into ONE dispatch for the LATEST missed occurrence — the
+ * older ones are dropped, never replayed; `run-once` fires a single catch-up, the EARLIEST
+ * missed one; `run-all` fires one per missed occurrence, bounded by `maxCatchUp`.
+ */
+export type CatchUpPolicy = 'skip' | 'run-once' | 'run-all';
+
+export interface TaskDefinition {
+  /** Omit it: `defineApi({ tasks })` assigns the export name. Set it only to pin the name the
+   * scheduler's `lastFiredAt` and occurrence lock are already keyed by. */
+  readonly name?: string;
+  readonly cron: string;
+  /** REQUIRED IANA zone, e.g. `'UTC'`, `'America/New_York'`. */
+  readonly tz: string;
+  /**
+   * Builds the entries for ONE occurrence, given that occurrence's instant in epoch ms.
+   *
+   * The argument exists because catch-up does: a tick dispatched late, or replayed for a
+   * missed occurrence, has a wall clock that no longer matches the occurrence being fired.
+   * A payload derived from `Date.now()` there is silently for the wrong day — and the
+   * scheduler's own key is occurrence-scoped, so nothing downstream catches it.
+   */
+  enqueue: (occurrenceMs: number) => readonly TaskEnqueueEntry[];
+  readonly catchUp?: CatchUpPolicy;
+  readonly maxCatchUp?: number;
+}
+
+/** One entry's outcome, from a scheduled dispatch or a manual `task.enqueue()` alike. */
+export interface TaskJobResult {
+  readonly job: string;
+  readonly result: EnqueueResult;
+}
+
+/** JSON-safe view of a task for the manifest, `/_x` and the MCP dev server. */
+export interface TaskDescriptor {
+  readonly kind: 'task';
+  readonly name: string;
+  readonly cron: string;
+  readonly tz: string;
+  readonly catchUp: CatchUpPolicy;
+  readonly maxCatchUp: number;
+  readonly jobs: readonly string[];
+}
+
+export interface TaskHandle {
+  readonly kind: 'task';
+  readonly name: string;
+  readonly cron: string;
+  readonly tz: string;
+  readonly catchUp: CatchUpPolicy;
+  readonly maxCatchUp: number;
+  /**
+   * Entries for `occurrenceMs`. Defaults to now, which is the honest answer for the two
+   * callers that have no occurrence: a manual `task.enqueue()` and `describe()`, which only
+   * wants the job names.
+   */
+  entries(occurrenceMs?: number): readonly TaskEnqueueEntry[];
+  /**
+   * Fire this task's declared entries now, through the same facade `JobHandle.enqueue` uses —
+   * the backfill and "run it again" path, with no scheduler and no leader involved.
+   */
+  enqueue(options?: EnqueueOptions): Promise<readonly TaskJobResult[]>;
+  describe(): TaskDescriptor;
+}
+
+const registry = new Map<string, TaskHandle>();
+let anonymous = 0;
+
+/** Job's store, for tasks: proof `task()` built the handle, plus whether it named itself. */
+interface TaskOrigin {
+  readonly declaredName: boolean;
+  /** The export name already stamped, once one has been. `undefined` while still provisional. */
+  readonly exportName?: string;
+}
+
+const origin = new WeakMap<object, TaskOrigin>();
+
+export function task(definition: TaskDefinition): TaskHandle {
+  anonymous += 1;
+  const name = definition.name ?? `anonymous-task-${anonymous}`;
+  // Runtime backstop; the type already makes an omitted tz a build error.
+  assert(
+    typeof definition.tz === 'string' && definition.tz.length > 0,
+    `task "${name}" needs an explicit IANA tz — a cron without a timezone is a bug`,
+    `add tz to task("${name}"), e.g. tz: 'UTC' — an unzoned cron silently drifts by an hour at every DST transition`,
+  );
+  // A non-empty string is not a timezone. `tz: 'Bogota'` would otherwise resolve every
+  // occurrence in UTC and the cron would run five hours off, silently, forever. `time`'s
+  // validator and not a local `Intl` probe: ES2024 `Intl` ACCEPTS `'+02:00'`, and a fixed offset
+  // carries no DST rules — the one thing a cron's timezone exists to supply. One validator means
+  // a zone `task()` accepts is a zone `@ultimat3/time` can then do arithmetic in.
+  assert(
+    isValidTimeZone(definition.tz),
+    `task "${name}" has tz "${definition.tz}", which is not a zone in the IANA tz database`,
+    `use the full zone id on task("${name}"), e.g. tz: 'America/Bogota' — list the valid ones with: bun -e "console.log(Intl.supportedValuesOf('timeZone').join('\\n'))"`,
+  );
+
+  const handle: TaskHandle = {
+    kind: 'task',
+    name,
+    cron: definition.cron,
+    tz: definition.tz,
+    catchUp: definition.catchUp ?? 'skip',
+    maxCatchUp: definition.maxCatchUp ?? 10,
+    // `nowMs()` and not `Date.now()`: every reading of time in this package goes through a
+    // Clock so a frozen one cannot be bypassed.
+    entries: (occurrenceMs: number = nowMs()) => definition.enqueue(occurrenceMs),
+    async enqueue(options?: EnqueueOptions): Promise<readonly TaskJobResult[]> {
+      const fired: TaskJobResult[] = [];
+      for (const [handleForJob, input] of handle.entries()) {
+        // The job's PLAIN key, deliberately not `dispatch()`'s `task:occurrence:key`: that one
+        // is occurrence-scoped so two schedulers cannot double-fire the same tick, and reusing
+        // it here would make a manual run dedupe against whichever occurrence it landed in.
+        fired.push({ job: handleForJob.name, result: await handleForJob.enqueue(input, options) });
+      }
+      return fired;
+    },
+    // Reads `handle`, never the captured `name`: `nameTasks()` rebinds the property in place.
+    describe(): TaskDescriptor {
+      return {
+        kind: 'task',
+        name: handle.name,
+        cron: handle.cron,
+        tz: handle.tz,
+        catchUp: handle.catchUp,
+        maxCatchUp: handle.maxCatchUp,
+        // Declaration order: a task's entries are a sequence, not a set.
+        jobs: handle.entries().map(([entry]) => entry.name),
+      };
+    },
+  };
+  origin.set(handle, { declaredName: definition.name !== undefined });
+  // Refused here, not at `registerTask`: a second `task({ name: 'nightly' })` would otherwise
+  // replace the seated handle, and the scheduler's persisted `lastFiredAt` — keyed by that name —
+  // would silently start driving a different cron. The anonymous names cannot collide.
+  if (registry.has(name)) throw new JobNameTakenError({ kind: 'task', name });
+  registry.set(name, handle);
+  return handle;
+}
+
+/** Structural, exactly as `isJobHandle` is: only a handle `task()` built has a cron behind it. */
+export function isTaskHandle(value: unknown): value is TaskHandle {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { kind?: unknown }).kind === 'task' &&
+    origin.has(value)
+  );
+}
+
+/**
+ * Register `target` under `name`, stamped onto the handle the module exported — the scheduler's
+ * occurrence key is `task:occurrenceMs:jobKey`, so the task's name is what stops two nodes
+ * double-firing a tick, and a copy under a second name would defeat it.
+ *
+ * A definition that supplied its own `name` keeps it, for the same reason a job's does: the
+ * scheduler's persisted `lastFiredAt` is keyed by that name.
+ */
+export function registerTask(name: string, target: TaskHandle): TaskHandle {
+  const source = origin.get(target);
+  const key = source?.declaredName === true ? target.name : name;
+  const seated = registry.get(key);
+  // The same handle under the same name is one registration seen twice — `defineApi` and the
+  // framework's module scan both reach the same declaration file. A DIFFERENT task under a taken
+  // name is the ambiguity to refuse.
+  if (seated !== undefined) {
+    if (seated !== target) throw new JobNameTakenError({ kind: 'task', name: key });
+    return target;
+  }
+  // One handle exported under two names: the rebind below is in place, so the second alias would
+  // move the occurrence key the scheduler dedupes ticks on.
+  if (source?.exportName !== undefined && source.exportName !== key)
+    throw new JobNameTakenError({ kind: 'task', name: key });
+  registry.delete(target.name);
+  Object.defineProperty(target, 'name', { value: key, configurable: true });
+  if (source !== undefined) origin.set(target, { ...source, exportName: key });
+  registry.set(key, target);
+  return target;
+}
+
+/** `registerTasks(module)` is the call app code makes; this is the same rules over a record. */
+export function nameTasks(record: Readonly<Record<string, TaskHandle>>): void {
+  for (const [exportName, handle] of Object.entries(record)) registerTask(exportName, handle);
+}
+
+export function registeredTasks(): readonly TaskHandle[] {
+  return [...registry.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function getTask(name: string): TaskHandle | undefined {
+  return registry.get(name);
+}
+
+export function resetTasks(): void {
+  registry.clear();
+  anonymous = 0;
+}

package/src/tenant.ts

@@ -0,0 +1,61 @@
+// What tenant a job's body runs as. A job is server-authoritative work with no request behind it,
+// so the org cannot be read off a caller — it is DECLARED, per job, and derived from that job's
+// OWN input. A boot-supplied service actor was the alternative and is rejected: one identity shared
+// 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 { JobTenantRequiredError } from './errors';
+
+/** The literal a job spells when it belongs to no tenant. */
+export const NO_JOB_TENANT = 'none';
+
+/**
+ * Either the org this job's input names, or the explicit statement that it names none. There is no
+ * third spelling and no default: a job that declared neither used to run with whatever ambient
+ * context the worker happened to have, which was none — so `@ultimat3/entity`'s tenant guard read
+ * no actor, derived no predicate and accepted a caller-named tenant unchecked.
+ */
+export type JobTenant<I> = ((input: I) => string) | typeof NO_JOB_TENANT;
+
+/**
+ * Runtime backstop for generated code and JS callers; TS already forbids omitting it. The mirror of
+ * `idempotencyKey`'s backstop, and refused at `job()` for the same reason — the earliest point at
+ * which the mistake is decidable is the declaration, not the first claim.
+ */
+export function assertJobTenant(job: string, tenant: unknown): void {
+  if (typeof tenant === 'function' || tenant === NO_JOB_TENANT) return;
+  throw new JobTenantRequiredError({ job });
+}
+
+/**
+ * The org one run acts under: `undefined` for `'none'`, which is what makes a tenant-scoped read
+ * inside such a job fail closed with `X_TENANCY_ACTOR_ORG_REQUIRED` rather than read somebody's
+ * rows by accident.
+ *
+ * An empty answer is refused here rather than carried: `''` is not a tenant, and an actor holding
+ * one would satisfy the guard's `orgId !== undefined` check while matching no row's `org_id`.
+ * `assert` and not a code of its own, exactly as `idempotencyKeyFor`'s empty-key refusal is — the
+ * declaration is wrong in both cases and the repair is the same edit.
+ */
+export function jobTenantFor<I>(job: string, tenant: JobTenant<I>, input: I): string | undefined {
+  if (tenant === NO_JOB_TENANT) return undefined;
+  const orgId = tenant(input);
+  assert(
+    typeof orgId === 'string' && orgId.length > 0,
+    `job "${job}" tenant() returned an empty tenant, so the run would carry an org no row can match`,
+    `return the org id from job("${job}").tenant — tenant: (input) => input.orgId — or declare tenant: 'none' if this job touches no tenant-scoped table`,
+  );
+  return orgId;
+}
+
+/**
+ * The actor the run's ambient context carries. The identity itself is whoever the app wired into
+ * `WorkerOptions.context()` — this changes only the ORG, because the tenant is a fact about the
+ * WORK and not about which process claimed it. `'none'` strips the org rather than leaving one
+ * behind: a job that declared no tenant must not inherit the worker's.
+ */
+export function jobRunActor(actor: Actor, orgId: string | undefined): Actor {
+  if (actor.orgId === orgId) return actor;
+  return Object.freeze({ ...actor, orgId });
+}