@ultimat3/jobs 1.0.0

package/src/inspect.ts

@@ -0,0 +1,213 @@
+// Introspection for `/_x`, the CLI and MCP. Every function returns a plain JSON-serialisable
+// object so `x jobs ... --json` and the MCP tool share one shape — an agent debugging a stuck
+// queue reads exactly what the dashboard renders.
+
+import type { JobDriver, JobFilter, JobRecord, QueueStats } from './driver';
+import { JobsNotImplementedError } from './errors';
+import { registeredJobs } from './job';
+import { retrySchedule } from './retry';
+import type { Scheduler } from './scheduler';
+import { registeredTasks } from './scheduler';
+import type { StepRecord } from './steps';
+
+export interface QueueDepthReport {
+  readonly driver: string;
+  readonly queues: readonly QueueStats[];
+  readonly totals: {
+    readonly ready: number;
+    readonly delayed: number;
+    readonly running: number;
+    readonly suspended: number;
+    readonly dead: number;
+  };
+  /** Oldest claimable job across all queues, in ms. The autoscaling signal. */
+  readonly oldestReadyMs: number;
+}
+
+export async function inspectQueues(driver: JobDriver): Promise<QueueDepthReport> {
+  const queues = [...(await driver.stats())];
+  const totals = queues.reduce(
+    (acc, queue) => ({
+      ready: acc.ready + queue.ready,
+      delayed: acc.delayed + queue.delayed,
+      running: acc.running + queue.running,
+      suspended: acc.suspended + queue.suspended,
+      dead: acc.dead + queue.dead,
+    }),
+    { ready: 0, delayed: 0, running: 0, suspended: 0, dead: 0 },
+  );
+  return {
+    driver: driver.name,
+    queues,
+    totals,
+    oldestReadyMs: queues.reduce((max, queue) => Math.max(max, queue.oldestReadyMs), 0),
+  };
+}
+
+export interface StepTrace {
+  readonly name: string;
+  readonly status: StepRecord['status'];
+  readonly startedAt: string;
+  readonly completedAt: string | null;
+  readonly wakeAt: string | null;
+  readonly durationMs: number | null;
+  readonly attempts: number;
+  readonly error: string | null;
+}
+
+export interface JobTrace {
+  readonly id: string;
+  readonly name: string;
+  readonly queue: string;
+  readonly state: JobRecord['state'];
+  readonly attempt: number;
+  readonly maxAttempts: number;
+  readonly idempotencyKey: string;
+  readonly runId: string;
+  readonly runAt: string;
+  readonly lastError: string | null;
+  readonly tenantId: string | null;
+  readonly steps: readonly StepTrace[];
+  /** Remaining retry delays in ms, jitter excluded. */
+  readonly retryDelaysMs: readonly number[];
+}
+
+const iso = (ms: number | undefined): string | null =>
+  ms === undefined ? null : new Date(ms).toISOString();
+
+function requireIntrospection(driver: JobDriver): NonNullable<JobDriver['introspect']> {
+  if (driver.introspect === undefined) {
+    throw new JobsNotImplementedError({
+      feature: `introspection for the "${driver.name}" jobs driver`,
+      fix: "set jobs: { driver: 'postgres' } in app.config.ts, then: x jobs ls --json",
+    });
+  }
+  return driver.introspect;
+}
+
+function toStepTrace(record: StepRecord): StepTrace {
+  return {
+    name: record.name,
+    status: record.status,
+    startedAt: new Date(record.startedAt).toISOString(),
+    completedAt: iso(record.completedAt),
+    wakeAt: iso(record.wakeAt),
+    durationMs: record.completedAt === undefined ? null : record.completedAt - record.startedAt,
+    attempts: record.attempts,
+    error: record.error ?? null,
+  };
+}
+
+export async function inspectJob(driver: JobDriver, jobId: string): Promise<JobTrace | undefined> {
+  const record = await requireIntrospection(driver).job(jobId);
+  if (record === undefined) return undefined;
+  const steps = await driver.steps.list(record.runId);
+  const handle = registeredJobs().find((candidate) => candidate.name === record.name);
+  return {
+    id: record.id,
+    name: record.name,
+    queue: record.queue,
+    state: record.state,
+    attempt: record.attempt,
+    maxAttempts: record.maxAttempts,
+    idempotencyKey: record.idempotencyKey,
+    runId: record.runId,
+    runAt: new Date(record.runAt).toISOString(),
+    lastError: record.lastError ?? null,
+    tenantId: record.tenantId ?? null,
+    steps: steps.map(toStepTrace),
+    retryDelaysMs: handle === undefined ? [] : [...retrySchedule(handle.retry)],
+  };
+}
+
+export function inspectJobList(
+  driver: JobDriver,
+  filter?: JobFilter,
+): Promise<readonly JobRecord[]> {
+  return requireIntrospection(driver).list(filter);
+}
+
+export interface DeadLetterEntry {
+  readonly id: string;
+  readonly name: string;
+  readonly queue: string;
+  readonly attempt: number;
+  readonly lastError: string | null;
+  readonly failedAt: string;
+  readonly retryCommand: string;
+}
+
+export async function inspectDeadLetters(
+  driver: JobDriver,
+  limit = 100,
+): Promise<readonly DeadLetterEntry[]> {
+  const rows = await requireIntrospection(driver).deadLetters(limit);
+  return rows.map((record) => ({
+    id: record.id,
+    name: record.name,
+    queue: record.queue,
+    attempt: record.attempt,
+    lastError: record.lastError ?? null,
+    failedAt: new Date(record.updatedAt).toISOString(),
+    retryCommand: `x jobs retry ${record.id}`,
+  }));
+}
+
+/**
+ * Re-queue a job, optionally dropping one step's persisted result so it re-executes while
+ * everything before it replays from storage. This is why steps are stored, not just logged.
+ */
+export async function retryFromStep(
+  driver: JobDriver,
+  jobId: string,
+  stepName?: string,
+): Promise<JobTrace | undefined> {
+  await requireIntrospection(driver).requeue(
+    jobId,
+    stepName === undefined ? undefined : { fromStep: stepName },
+  );
+  return inspectJob(driver, jobId);
+}
+
+export interface JobsManifest {
+  readonly jobs: readonly {
+    readonly name: string;
+    readonly queue: string;
+    readonly attempts: number;
+    readonly backoff: string;
+    readonly concurrency: number | null;
+    readonly timeoutMs: number | null;
+    readonly retryDelaysMs: readonly number[];
+  }[];
+  readonly tasks: readonly {
+    readonly name: string;
+    readonly cron: string;
+    readonly tz: string;
+    readonly catchUp: string;
+    readonly nextRun: string | null;
+    readonly enqueues: readonly string[];
+  }[];
+}
+
+/** Feeds `x.manifest.json` and the MCP `jobs.list` tool. Generated facts, never prose. */
+export function inspectManifest(scheduler?: Scheduler): JobsManifest {
+  return {
+    jobs: registeredJobs().map((handle) => ({
+      name: handle.name,
+      queue: handle.queue,
+      attempts: handle.retry.attempts,
+      backoff: handle.retry.backoff ?? 'exponential',
+      concurrency: handle.concurrency ?? null,
+      timeoutMs: handle.timeoutMs ?? null,
+      retryDelaysMs: [...retrySchedule(handle.retry)],
+    })),
+    tasks: registeredTasks().map((handle) => ({
+      name: handle.name,
+      cron: handle.cron,
+      tz: handle.tz,
+      catchUp: handle.catchUp,
+      nextRun: scheduler === undefined ? null : scheduler.nextRunFor(handle).toISOString(),
+      enqueues: handle.entries().map(([job]) => job.name),
+    })),
+  };
+}

package/src/job.d.ts

@@ -0,0 +1,71 @@
+import type { Ctx } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { DurationInput } from './clock';
+import type { RetryPolicy } from './retry';
+import { type BackoffStrategy } from './retry';
+import type { StepApi } from './steps';
+export interface JobRunArgs<I> {
+    readonly input: I;
+    readonly step: StepApi;
+    readonly ctx: Ctx;
+    /** 1-based. Assume at-least-once: never branch on `attempt === 1` for correctness. */
+    readonly attempt: number;
+    readonly jobId: string;
+    readonly runId: string;
+}
+export interface JobDefinition<I> {
+    /** Assigned by `x manifest` from the export name; only set by hand in tests. */
+    readonly name?: string;
+    readonly input: StandardSchemaV1<unknown, I>;
+    /** REQUIRED. See the file header — this is the whole point. */
+    readonly idempotencyKey: (input: I) => string;
+    readonly retry: RetryPolicy;
+    readonly queue?: string;
+    /** Max in-flight runs of THIS job across the fleet. Omit for the queue-wide cap. */
+    readonly concurrency?: number;
+    readonly timeout?: DurationInput;
+    run(args: JobRunArgs<I>): Promise<unknown>;
+}
+/**
+ * Methods (not function-typed properties) throughout, so `JobHandle<Specific>` is assignable
+ * to `AnyJobHandle` and heterogeneous handles can share a registry and a task's enqueue list.
+ */
+export interface JobHandle<I = unknown> {
+    readonly kind: 'job';
+    readonly name: string;
+    readonly queue: string;
+    readonly retry: RetryPolicy;
+    readonly concurrency: number | undefined;
+    readonly timeoutMs: number | undefined;
+    readonly input: StandardSchemaV1<unknown, I>;
+    parse(raw: unknown): I;
+    idempotencyKeyFor(input: I): string;
+    run(args: JobRunArgs<I>): Promise<unknown>;
+}
+export type AnyJobHandle = JobHandle<unknown>;
+export declare function job<I>(definition: JobDefinition<I>): JobHandle<I>;
+/**
+ * Called by generated code with `{ onboardOrg, sendDigest }` so queue rows carry the export
+ * name rather than a positional id. Enqueue works either way; the name is for humans.
+ */
+export declare function nameJobs(record: Readonly<Record<string, AnyJobHandle>>): void;
+export declare function getJob(name: string): AnyJobHandle | undefined;
+export declare function registeredJobs(): readonly AnyJobHandle[];
+export declare function resetJobs(): void;
+/**
+ * Registered jobs as the manifest, the `/_x` jobs panel and the MCP dev server need them.
+ * Name-sorted and JSON-safe because `x.manifest.json` is committed and diffed — an
+ * iteration-order-dependent field would show up as a spurious change on every build.
+ * `steps` stays in declaration order: it is a sequence, not a set.
+ */
+export declare function describeJobs(): readonly {
+    readonly name: string;
+    readonly input: unknown;
+    readonly queue: string;
+    readonly retry: {
+        readonly attempts: number;
+        readonly backoff: BackoffStrategy;
+    };
+    readonly steps: readonly string[];
+}[];
+//# sourceMappingURL=job.d.ts.map

package/src/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["job.ts"],"names":[],"mappings":"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"}

package/src/job.js

@@ -0,0 +1,99 @@
+// The `job` primitive: durable background work. The shape is the contract's shape exactly.
+//
+// `idempotencyKey` is NON-OPTIONAL in the type. Queues deliver at least once — network
+// partitions, visibility-timeout expiry and outbox relays all replay — so "did this already
+// run?" is a question every job must answer. Making it optional means the answer is usually
+// "nobody thought about it", and the bug (two charges, two welcome emails, two provisioned
+// orgs) surfaces in production under load, never in a test. Requiring it by construction
+// deletes that class of bug: there is no way to define a job that cannot be deduped.
+import { assert } from '@ultimat3/core';
+import { parse } from '@ultimat3/schema';
+import { toMs } from './clock';
+import { DEFAULT_QUEUE } from './driver';
+import { IdempotencyRequiredError } from './errors';
+import { DEFAULT_RETRY } from './retry';
+const registry = new Map();
+let anonymous = 0;
+export function job(definition) {
+    anonymous += 1;
+    const name = definition.name ?? `anonymous-job-${anonymous}`;
+    // Runtime backstop for generated code and JS callers; TS already forbids omitting it.
+    if (typeof definition.idempotencyKey !== 'function') {
+        throw new IdempotencyRequiredError({ job: name });
+    }
+    assert(definition.retry.attempts >= 1, `job "${name}" needs retry.attempts >= 1, got ${String(definition.retry.attempts)}`, `set retry: { attempts: 1 } or higher on job("${name}") — 0 attempts means the job is never executed at all, not that it never retries`);
+    const handle = {
+        kind: 'job',
+        name,
+        queue: definition.queue ?? DEFAULT_QUEUE,
+        retry: { ...DEFAULT_RETRY, ...definition.retry },
+        concurrency: definition.concurrency,
+        timeoutMs: definition.timeout === undefined ? undefined : toMs(definition.timeout),
+        input: definition.input,
+        parse(raw) {
+            return parse(definition.input, raw);
+        },
+        idempotencyKeyFor(input) {
+            const key = definition.idempotencyKey(input);
+            assert(typeof key === 'string' && key.length > 0, `job "${name}" idempotencyKey returned an empty string`, `return a non-empty stable key from job("${name}").idempotencyKey — an empty key makes every enqueue look like a duplicate of every other`);
+            return key;
+        },
+        run(args) {
+            return definition.run(args);
+        },
+    };
+    registry.set(name, handle);
+    return handle;
+}
+/**
+ * Called by generated code with `{ onboardOrg, sendDigest }` so queue rows carry the export
+ * name rather than a positional id. Enqueue works either way; the name is for humans.
+ */
+export function nameJobs(record) {
+    for (const [exportName, handle] of Object.entries(record)) {
+        if (handle.name === exportName)
+            continue;
+        registry.delete(handle.name);
+        // The caller holds a reference to this exact object, so rebind its name in place.
+        Object.defineProperty(handle, 'name', { value: exportName, configurable: true });
+        registry.set(exportName, handle);
+    }
+}
+export function getJob(name) {
+    return registry.get(name);
+}
+export function registeredJobs() {
+    return [...registry.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function resetJobs() {
+    registry.clear();
+    anonymous = 0;
+}
+/**
+ * Registered jobs as the manifest, the `/_x` jobs panel and the MCP dev server need them.
+ * Name-sorted and JSON-safe because `x.manifest.json` is committed and diffed — an
+ * iteration-order-dependent field would show up as a spurious change on every build.
+ * `steps` stays in declaration order: it is a sequence, not a set.
+ */
+export function describeJobs() {
+    return registeredJobs().map((handle) => ({
+        name: handle.name,
+        input: describeSchema(handle.input),
+        queue: handle.queue,
+        retry: {
+            attempts: handle.retry.attempts,
+            backoff: handle.retry.backoff ?? DEFAULT_RETRY.backoff,
+        },
+        // Empty by design: step names are chosen inside `run()` at execution time, so they are
+        // not statically knowable. `inspect(name)` reports the steps an actual run recorded.
+        steps: [],
+    }));
+}
+/** Best-effort JSON view of a Standard Schema; the vendor decides how much it exposes. */
+function describeSchema(schema) {
+    if (schema === null || typeof schema !== 'object')
+        return null;
+    const vendor = schema['~standard'];
+    return { vendor: vendor?.vendor ?? 'unknown' };
+}
+//# sourceMappingURL=job.js.map

package/src/job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.js","sourceRoot":"","sources":["job.ts"],"names":[],"mappings":"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"}

package/src/job.ts

@@ -0,0 +1,261 @@
+// The `job` primitive: durable background work. The shape is the contract's shape exactly.
+//
+// `idempotencyKey` is NON-OPTIONAL in the type. Queues deliver at least once — network
+// partitions, visibility-timeout expiry and outbox relays all replay — so "did this already
+// run?" is a question every job must answer. Making it optional means the answer is usually
+// "nobody thought about it", and the bug (two charges, two welcome emails, two provisioned
+// orgs) surfaces in production under load, never in a test. Requiring it by construction
+// deletes that class of bug: there is no way to define a job that cannot be deduped.
+
+import type { Ctx } from '@ultimat3/core';
+import { assert } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { parse } from '@ultimat3/schema';
+import type { DurationInput } from './clock';
+import { toMs } from './clock';
+import type { JobDescriptor } from './describe';
+import { describeJob } from './describe';
+import type { EnqueueResult } from './driver';
+import { DEFAULT_QUEUE } from './driver';
+import { IdempotencyRequiredError, JobNameTakenError } from './errors';
+import { NO_TENANT, tenantKeyFrom } from './limits';
+import type { EnqueueOptions } from './outbox';
+import { jobsFacade } from './outbox';
+import type { RetryPolicy } from './retry';
+import { DEFAULT_RETRY } from './retry';
+import type { StepApi } from './steps';
+
+export interface JobRunArgs<I> {
+  readonly input: I;
+  readonly step: StepApi;
+  readonly ctx: Ctx;
+  /** 1-based. Assume at-least-once: never branch on `attempt === 1` for correctness. */
+  readonly attempt: number;
+  readonly jobId: string;
+  readonly runId: string;
+}
+
+export interface JobDefinition<I> {
+  /**
+   * Omit it: `defineApi({ jobs })` assigns the export name. Set it only to pin a queue key the
+   * export name must not decide — a framework job like `mail.send`, or a name rows already carry.
+   */
+  readonly name?: string;
+  readonly input: StandardSchemaV1<unknown, I>;
+  /** REQUIRED. See the file header — this is the whole point. */
+  readonly idempotencyKey: (input: I) => string;
+  readonly retry: RetryPolicy;
+  readonly queue?: string;
+  /** Max in-flight runs of THIS job across the fleet. Omit for the queue-wide cap. */
+  readonly concurrency?: number;
+  readonly timeout?: DurationInput;
+  run(args: JobRunArgs<I>): Promise<unknown>;
+}
+
+/**
+ * Whoever the enqueue is for. Structural, exactly like `tenantKeyFrom` in `limits.ts`: the
+ * queue needs the actor's org and nothing else, so this package never imports the auth types.
+ */
+export interface JobActor {
+  readonly orgId?: string | undefined;
+}
+
+/**
+ * Methods (not function-typed properties) throughout, so `JobHandle<Specific>` is assignable
+ * to `AnyJobHandle` and heterogeneous handles can share a registry and a task's enqueue list.
+ */
+export interface JobHandle<I = unknown> {
+  readonly kind: 'job';
+  readonly name: string;
+  readonly queue: string;
+  readonly retry: RetryPolicy;
+  readonly concurrency: number | undefined;
+  readonly timeoutMs: number | undefined;
+  readonly input: StandardSchemaV1<unknown, I>;
+  parse(raw: unknown): I;
+  idempotencyKeyFor(input: I): string;
+  run(args: JobRunArgs<I>): Promise<unknown>;
+  /**
+   * Put this job on the queue. Joins the caller's transaction when the app installed the
+   * outbox — same call site in a request handler, a job, a script or a test.
+   */
+  enqueue(input: I, options?: EnqueueOptions): Promise<EnqueueResult>;
+  /**
+   * Enqueue on behalf of `actor`: fills `tenantId` from the actor's org so per-tenant limits
+   * apply. It queues rather than running inline because a job's execution surface IS the
+   * queue — an inline run would be a second execution path alongside `executeJob`.
+   */
+  as(actor: JobActor | null, input: I, options?: EnqueueOptions): Promise<EnqueueResult>;
+  describe(): JobDescriptor;
+}
+
+export type AnyJobHandle = JobHandle<unknown>;
+
+const registry = new Map<string, AnyJobHandle>();
+let anonymous = 0;
+
+/**
+ * Proof `job()` built this handle, plus whether its definition named itself and which export
+ * name registration stamped on it. Private, and deliberately not a registry lookup: the registry
+ * is what `registerJob` rewrites, so a guard that read it would reject exactly the handles
+ * registration exists to rename.
+ */
+interface JobOrigin {
+  readonly declaredName: boolean;
+  /** The export name already stamped, once one has been. `undefined` while still provisional. */
+  readonly exportName?: string;
+}
+
+const origin = new WeakMap<object, JobOrigin>();
+
+export function job<I>(definition: JobDefinition<I>): JobHandle<I> {
+  anonymous += 1;
+  const name = definition.name ?? `anonymous-job-${anonymous}`;
+
+  // Runtime backstop for generated code and JS callers; TS already forbids omitting it.
+  if (typeof definition.idempotencyKey !== 'function') {
+    throw new IdempotencyRequiredError({ job: name });
+  }
+  assert(
+    definition.retry.attempts >= 1,
+    `job "${name}" needs retry.attempts >= 1, got ${String(definition.retry.attempts)}`,
+    `set retry: { attempts: 1 } or higher on job("${name}") — 0 attempts means the job is never executed at all, not that it never retries`,
+  );
+
+  const handle: JobHandle<I> = {
+    kind: 'job',
+    name,
+    queue: definition.queue ?? DEFAULT_QUEUE,
+    retry: { ...DEFAULT_RETRY, ...definition.retry },
+    concurrency: definition.concurrency,
+    timeoutMs: definition.timeout === undefined ? undefined : toMs(definition.timeout),
+    input: definition.input,
+    parse(raw: unknown): I {
+      return parse(definition.input, raw) as I;
+    },
+    idempotencyKeyFor(input: I): string {
+      const key = definition.idempotencyKey(input);
+      assert(
+        typeof key === 'string' && key.length > 0,
+        `job "${name}" idempotencyKey returned an empty string`,
+        `return a non-empty stable key from job("${name}").idempotencyKey — an empty key makes every enqueue look like a duplicate of every other`,
+      );
+      return key;
+    },
+    run(args: JobRunArgs<I>): Promise<unknown> {
+      return definition.run(args);
+    },
+    enqueue(input: I, options?: EnqueueOptions): Promise<EnqueueResult> {
+      return jobsFacade().enqueue(handle, input, options);
+    },
+    as(actor: JobActor | null, input: I, options: EnqueueOptions = {}): Promise<EnqueueResult> {
+      const tenantId = options.tenantId ?? tenantFor(actor);
+      // `NO_TENANT` is the limiter's own bucket for an absent tenant, so leaving the column
+      // empty is the same limit and one less fake org id on the row.
+      return handle.enqueue(input, {
+        ...options,
+        ...(tenantId === NO_TENANT ? {} : { tenantId }),
+      });
+    },
+    // Reads `handle`, never the captured `name`: `nameJobs()` rebinds the property in place.
+    describe(): JobDescriptor {
+      return describeJob(handle);
+    },
+  };
+
+  origin.set(handle, { declaredName: definition.name !== undefined });
+  // Refused here, not at `registerJob`: a second `job({ name: 'send-digest' })` would otherwise
+  // overwrite the seated handle and silently take over delivery of every row already queued
+  // under that key. The anonymous names cannot collide — the counter above only ever grows.
+  if (registry.has(name)) throw new JobNameTakenError({ kind: 'job', name });
+  registry.set(name, handle as AnyJobHandle);
+  return handle;
+}
+
+/** `orgId` is optional-with-undefined on an actor and optional-only on `tenantKeyFrom`. */
+function tenantFor(actor: JobActor | null): string {
+  const orgId = actor?.orgId;
+  return tenantKeyFrom(orgId === undefined ? undefined : { orgId });
+}
+
+/**
+ * Structural, not nominal: an object counts as a job handle only if `job()` built it, because
+ * only then does a retry policy, an idempotency key and a queue exist behind it. A look-alike
+ * carrying `kind: 'job'` never reaches the registry, the queue or the manifest.
+ */
+export function isJobHandle(value: unknown): value is AnyJobHandle {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { kind?: unknown }).kind === 'job' &&
+    origin.has(value)
+  );
+}
+
+/**
+ * Register `target` under `name`, stamping the name onto the handle the module exported rather
+ * than seating a differently-named copy: `import { notifySubscribers }` is the handle
+ * `enqueue()` routes through after boot, with nothing to remember.
+ *
+ * A definition that supplied its own `name` keeps it. A job name is the durable queue key that
+ * queued, retrying and dead-lettered rows already carry, so renaming an export must never move
+ * where they are delivered.
+ */
+export function registerJob<H extends AnyJobHandle>(name: string, target: H): H {
+  const source = origin.get(target);
+  const key = source?.declaredName === true ? target.name : name;
+  const seated = registry.get(key);
+  // Re-registering the SAME handle under the SAME name is one registration seen twice, not a
+  // collision: `defineApi` hands over a feature module at boot and the framework's module scan
+  // reaches the same declaration file directly. Only a DIFFERENT job under a taken name is the
+  // ambiguity `X_JOB_DUPLICATE` exists to refuse.
+  if (seated !== undefined) {
+    if (seated !== (target as AnyJobHandle))
+      throw new JobNameTakenError({ kind: 'job', name: key });
+    return target;
+  }
+  // One handle, two export names — `export { notify as first, notify as second }`. The rebind
+  // below is in place, so the second alias would move the durable queue key to whichever name
+  // the module happened to export last, and queued rows would stop being delivered.
+  if (source?.exportName !== undefined && source.exportName !== key)
+    throw new JobNameTakenError({ kind: 'job', name: key });
+  registry.delete(target.name);
+  // The caller holds a reference to this exact object, so rebind its name in place.
+  Object.defineProperty(target, 'name', { value: key, configurable: true });
+  if (source !== undefined) origin.set(target, { ...source, exportName: key });
+  registry.set(key, target as AnyJobHandle);
+  return target;
+}
+
+/**
+ * Called by generated code with `{ onboardOrg, sendDigest }` so queue rows carry the export
+ * name rather than a positional id. `registerJobs(module)` is the call app code makes; this is
+ * the same rules over an explicit record — a declared `name` wins, and a second handle under a
+ * taken name is `X_JOB_DUPLICATE`.
+ */
+export function nameJobs(record: Readonly<Record<string, AnyJobHandle>>): void {
+  for (const [exportName, handle] of Object.entries(record)) registerJob(exportName, handle);
+}
+
+export function getJob(name: string): AnyJobHandle | undefined {
+  return registry.get(name);
+}
+
+export function registeredJobs(): readonly AnyJobHandle[] {
+  return [...registry.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function resetJobs(): void {
+  registry.clear();
+  anonymous = 0;
+}
+
+/**
+ * Registered jobs as the manifest, the `/_x` jobs panel and the MCP dev server need them.
+ * Name-sorted because `x.manifest.json` is committed and diffed — an iteration-order-dependent
+ * list would show up as a spurious change on every build. Each row is the handle's own
+ * `describe()`, so the list and the single job can never disagree.
+ */
+export function describeJobs(): readonly JobDescriptor[] {
+  return registeredJobs().map((handle) => handle.describe());
+}