@ultimat3/jobs 1.0.0

package/src/outbox.ts

@@ -0,0 +1,336 @@
+// The transactional outbox — ON BY DEFAULT, because the alternative is a bug you cannot see
+// in review. `ctx.jobs.enqueue()` inside a request writes the job row in the SAME `tx` as the
+// business rows and a relay publishes it after commit. Without it, every enqueue is a
+// distributed-transaction coin flip:
+//
+//   enqueue then rollback  -> the job runs against rows that never existed
+//   commit then enqueue    -> the process dies in between and the job is lost forever
+//
+// Both are load-dependent, both pass every test, and both are the top source of "the email
+// went out but the order isn't in the database" tickets. Joining the transaction removes the
+// window entirely; the relay's at-least-once delivery is deduped by the job's idempotencyKey.
+
+import type { Clock } from '@ultimat3/core';
+import { logger, uuid } from '@ultimat3/core';
+import type { Tx } from '@ultimat3/entity';
+import { nowMs } from './clock';
+import type { EnqueueResult, JobDriver } from './driver';
+import { DEFAULT_QUEUE, jobDriver } from './driver';
+import { DriverUnavailableError, OutboxNoTxError } from './errors';
+import type { JobHandle } from './job';
+
+export interface OutboxRecord {
+  readonly id: string;
+  readonly job: string;
+  readonly queue: string;
+  readonly input: unknown;
+  readonly idempotencyKey: string;
+  readonly maxAttempts: number;
+  readonly runAt: number;
+  readonly stagedAt: number;
+  readonly tenantId?: string;
+  readonly publishedAt?: number;
+}
+
+export interface OutboxStore {
+  /** Write inside `tx`. Nothing is visible to the relay until that tx commits. */
+  stage(tx: Tx, record: OutboxRecord): Promise<void>;
+  /** Called by the tx runner after COMMIT. */
+  commit(tx: Tx): Promise<readonly OutboxRecord[]>;
+  /** Called by the tx runner after ROLLBACK. Staged rows vanish with the transaction. */
+  rollback(tx: Tx): Promise<void>;
+  /** Unpublished, committed rows — the relay's work queue. */
+  claim(limit: number): Promise<readonly OutboxRecord[]>;
+  markPublished(id: string, at: number): Promise<void>;
+  pendingCount(): Promise<number>;
+}
+
+/**
+ * Default store. Staged rows hang off the `Tx` object itself in a WeakMap, so the "same
+ * transaction" guarantee needs no cooperation from the DB layer and rollback is a delete.
+ * The pg store swaps this for a real `x_outbox` table written by the same connection.
+ */
+export function createMemoryOutboxStore(): OutboxStore {
+  const staged = new WeakMap<object, OutboxRecord[]>();
+  const committed = new Map<string, OutboxRecord>();
+
+  const key = (tx: Tx): object => tx as unknown as object;
+
+  return {
+    stage(tx, record) {
+      const bucket = staged.get(key(tx)) ?? [];
+      bucket.push(record);
+      staged.set(key(tx), bucket);
+      return Promise.resolve();
+    },
+    commit(tx) {
+      const bucket = staged.get(key(tx)) ?? [];
+      staged.delete(key(tx));
+      for (const record of bucket) committed.set(record.id, record);
+      return Promise.resolve(bucket);
+    },
+    rollback(tx) {
+      staged.delete(key(tx));
+      return Promise.resolve();
+    },
+    claim(limit) {
+      const ready = [...committed.values()]
+        .filter((record) => record.publishedAt === undefined)
+        .sort((a, b) => a.stagedAt - b.stagedAt)
+        .slice(0, limit);
+      return Promise.resolve(ready);
+    },
+    markPublished(id, at) {
+      const record = committed.get(id);
+      if (record !== undefined) committed.set(id, { ...record, publishedAt: at });
+      return Promise.resolve();
+    },
+    pendingCount() {
+      let count = 0;
+      for (const record of committed.values()) {
+        if (record.publishedAt === undefined) count += 1;
+      }
+      return Promise.resolve(count);
+    },
+  };
+}
+
+export interface EnqueueOptions {
+  /** Epoch ms, or a delay via `runAt: nowMs() + toMs('5m')`. */
+  readonly runAt?: number;
+  readonly tenantId?: string;
+  readonly queue?: string;
+  /** Escape hatch for enqueues that must fire regardless of the caller's transaction. */
+  readonly outbox?: boolean;
+}
+
+export interface OutboxDeps {
+  readonly store: OutboxStore;
+  readonly driver: JobDriver;
+  readonly clock?: Clock;
+  /** `'required'` fails an out-of-transaction enqueue instead of publishing it directly. */
+  readonly mode?: 'default' | 'required';
+}
+
+/** Stage a job inside `tx`. Returns the row that the relay will publish after commit. */
+export function enqueueInTx<I>(
+  deps: OutboxDeps,
+  tx: Tx,
+  handle: JobHandle<I>,
+  input: I,
+  options: EnqueueOptions = {},
+): Promise<OutboxRecord> {
+  const at = nowMs(deps.clock);
+  const record: OutboxRecord = {
+    id: uuid(),
+    job: handle.name,
+    queue: options.queue ?? handle.queue ?? DEFAULT_QUEUE,
+    input,
+    idempotencyKey: handle.idempotencyKeyFor(input),
+    maxAttempts: handle.retry.attempts,
+    runAt: options.runAt ?? at,
+    stagedAt: at,
+    ...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
+  };
+  return deps.store.stage(tx, record).then(() => record);
+}
+
+export interface JobsFacade {
+  /**
+   * Joins the ambient transaction when there is one. Same call site in a request handler,
+   * a job, or a script — the transactional behaviour is the framework's problem, not yours.
+   */
+  enqueue<I>(handle: JobHandle<I>, input: I, options?: EnqueueOptions): Promise<EnqueueResult>;
+}
+
+const STAGED_RESULT: EnqueueResult = { id: '', runId: '', deduped: false };
+
+export function createJobsFacade(deps: OutboxDeps, currentTx: () => Tx | undefined): JobsFacade {
+  return {
+    async enqueue<I>(
+      handle: JobHandle<I>,
+      input: I,
+      options: EnqueueOptions = {},
+    ): Promise<EnqueueResult> {
+      const tx = options.outbox === false ? undefined : currentTx();
+
+      if (tx === undefined) {
+        if (deps.mode === 'required' && options.outbox !== false) {
+          throw new OutboxNoTxError({ job: handle.name });
+        }
+        return deps.driver.enqueue({
+          name: handle.name,
+          queue: options.queue ?? handle.queue,
+          input,
+          idempotencyKey: handle.idempotencyKeyFor(input),
+          maxAttempts: handle.retry.attempts,
+          runAt: options.runAt ?? nowMs(deps.clock),
+          ...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
+        });
+      }
+
+      const record = await enqueueInTx(deps, tx, handle, input, options);
+      // No queue id yet by design: the row does not exist until COMMIT.
+      return { ...STAGED_RESULT, id: record.id };
+    },
+  };
+}
+
+let ambient: JobsFacade | undefined;
+let fallback: JobsFacade | undefined;
+
+/**
+ * Installed once at boot, next to `setJobDriver`, with the app's outbox store and its
+ * transaction accessor. `handle.enqueue()` then joins the caller's transaction wherever it is
+ * called from — which is the only reason the outbox protects anything.
+ */
+export function setJobsFacade(facade: JobsFacade | null): void {
+  ambient = facade ?? undefined;
+}
+
+/**
+ * The one enqueue path. With no facade installed the fallback publishes straight to the
+ * ambient driver, so a script, a test or `x dev` enqueues without wiring anything — an app
+ * that installed the outbox gets the outbox, at the same call site.
+ */
+export function jobsFacade(): JobsFacade {
+  if (ambient !== undefined) return ambient;
+  fallback ??= createJobsFacade(
+    {
+      // A getter, not a snapshot: `setJobDriver()` after the first enqueue is honoured, and a
+      // missing driver is an error at the call rather than at import time.
+      get driver(): JobDriver {
+        const installed = jobDriver();
+        if (installed === undefined) {
+          throw new DriverUnavailableError({
+            driver: 'none',
+            cause: 'no queue driver is installed in this process',
+            fix: 'call setJobDriver(createMemoryDriver()) before enqueuing — or set jobs.driver in app.config.ts and run `x dev`',
+          });
+        }
+        return installed;
+      },
+      // Unreachable while `currentTx` is `() => undefined`; present because `OutboxDeps`
+      // requires a store, and a real one is cheaper than an assertion that cannot fire.
+      store: createMemoryOutboxStore(),
+    },
+    () => undefined,
+  );
+  return fallback;
+}
+
+/** Test/CLI seam, the counterpart to `resetJobDriver()`: forget the installed facade. */
+export function resetJobsFacade(): void {
+  ambient = undefined;
+}
+
+export interface RelayOptions extends OutboxDeps {
+  readonly batchSize?: number;
+  readonly intervalMs?: number;
+}
+
+export interface OutboxRelay {
+  /** One pass. Returns how many rows were published. Call it directly in tests. */
+  tick(): Promise<number>;
+  start(): void;
+  stop(): void;
+  pending(): Promise<number>;
+}
+
+/**
+ * At-least-once by construction: publish, THEN mark published. A crash between the two
+ * re-publishes, which the idempotency key collapses — the opposite order would lose jobs.
+ */
+export function createOutboxRelay(options: RelayOptions): OutboxRelay {
+  const batchSize = options.batchSize ?? 100;
+  const intervalMs = options.intervalMs ?? 200;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let running = false;
+
+  const tick = async (): Promise<number> => {
+    const batch = await options.store.claim(batchSize);
+    let published = 0;
+    for (const record of batch) {
+      try {
+        await options.driver.enqueue({
+          name: record.job,
+          queue: record.queue,
+          input: record.input,
+          idempotencyKey: record.idempotencyKey,
+          maxAttempts: record.maxAttempts,
+          runAt: record.runAt,
+          ...(record.tenantId === undefined ? {} : { tenantId: record.tenantId }),
+        });
+        await options.store.markPublished(record.id, nowMs(options.clock));
+        published += 1;
+      } catch (error) {
+        // Leave the row unpublished; the next tick retries it. Order is preserved per queue.
+        logger.warn('jobs.outbox.publish-failed', {
+          job: record.job,
+          id: record.id,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    return published;
+  };
+
+  return {
+    tick,
+    start() {
+      if (timer !== undefined) return;
+      timer = setInterval(() => {
+        if (running) return;
+        running = true;
+        void tick().finally(() => {
+          running = false;
+        });
+      }, intervalMs);
+    },
+    stop() {
+      if (timer !== undefined) clearInterval(timer);
+      timer = undefined;
+    },
+    pending: () => options.store.pendingCount(),
+  };
+}
+
+/** SQL for the pg-backed outbox. The relay publishes rows this INSERT created. */
+export const SQL_OUTBOX_TABLE = `
+create table if not exists x_outbox (
+  id              uuid primary key,
+  job             text        not null,
+  queue           text        not null default 'default',
+  input           jsonb       not null,
+  idempotency_key text        not null,
+  max_attempts    int         not null default 3,
+  run_at          timestamptz not null default now(),
+  staged_at       timestamptz not null default now(),
+  tenant_id       text,
+  published_at    timestamptz
+);
+create index if not exists x_outbox_unpublished_idx
+  on x_outbox (staged_at) where published_at is null;
+`.trim();
+
+export const SQL_OUTBOX_STAGE = `
+insert into x_outbox
+  (id, job, queue, input, idempotency_key, max_attempts, run_at, staged_at, tenant_id)
+values ($1, $2, $3, $4::jsonb, $5, $6, to_timestamp($7 / 1000.0), to_timestamp($8 / 1000.0), $9)
+`.trim();
+
+export const SQL_OUTBOX_CLAIM = `
+select id, job, queue, input, idempotency_key, max_attempts,
+       (extract(epoch from run_at) * 1000)::bigint    as run_at,
+       (extract(epoch from staged_at) * 1000)::bigint as staged_at,
+       tenant_id
+  from x_outbox
+ where published_at is null
+ order by staged_at
+ limit $1
+   for update skip locked
+`.trim();
+
+export const SQL_OUTBOX_MARK_PUBLISHED = `
+update x_outbox set published_at = to_timestamp($2 / 1000.0) where id = $1
+`.trim();

package/src/register.ts

@@ -0,0 +1,40 @@
+/**
+ * Export names become job and task names. `registerJobs(await import('./jobs'))` is how a module
+ * namespace becomes registered handles the queue, the scheduler and the manifest all address by
+ * the identifier the source file uses — never a positional `anonymous-job-2`.
+ */
+
+import { type RegisteredPrimitive, registerPrimitiveRegistrar } from '@ultimat3/core';
+import { isJobHandle, registerJob } from './job';
+import { isTaskHandle, registerTask } from './scheduler';
+
+/** `registerJobs(await import('./jobs'))` — export names become job names. */
+export function registerJobs(
+  module: Readonly<Record<string, unknown>>,
+): readonly RegisteredPrimitive[] {
+  const registered: RegisteredPrimitive[] = [];
+  for (const name of Object.keys(module).sort()) {
+    const value = module[name];
+    if (isJobHandle(value)) registered.push(registerJob(name, value));
+  }
+  return registered;
+}
+
+/** `registerTasks(await import('./tasks'))` — export names become task names. */
+export function registerTasks(
+  module: Readonly<Record<string, unknown>>,
+): readonly RegisteredPrimitive[] {
+  const registered: RegisteredPrimitive[] = [];
+  for (const name of Object.keys(module).sort()) {
+    const value = module[name];
+    if (isTaskHandle(value)) registered.push(registerTask(name, value));
+  }
+  return registered;
+}
+
+// `defineApi` lives in `@ultimat3/action`, which sits on this tier and so cannot import this
+// file. Announcing the registrars in core's table is what lets one `defineApi({ jobs, tasks })`
+// call name durable work without a sideways import — importing the module you pass is what
+// loads this.
+registerPrimitiveRegistrar('job', registerJobs);
+registerPrimitiveRegistrar('task', registerTasks);

package/src/retry.d.ts

@@ -0,0 +1,40 @@
+import type { DurationInput } from './clock';
+export type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+export interface RetryPolicy {
+    /** Total attempts including the first. `attempts: 1` means no retry. */
+    readonly attempts: number;
+    readonly backoff?: BackoffStrategy;
+    /** Base delay. Default 1s. */
+    readonly delay?: DurationInput;
+    /** Ceiling for any single delay. Default 1h. */
+    readonly maxDelay?: DurationInput;
+    /**
+     * Equal jitter (half fixed, half random) by default. Without it, a burst of failures
+     * retries in lockstep and re-creates the thundering herd that killed the dependency.
+     */
+    readonly jitter?: boolean;
+    /** Default true: an exhausted job is parked, never dropped. */
+    readonly deadLetter?: boolean;
+}
+export declare const DEFAULT_RETRY: {
+    attempts: number;
+    backoff: "exponential";
+    delay: number;
+    maxDelay: number;
+    jitter: true;
+    deadLetter: true;
+};
+export type Random = () => number;
+/** Delay before `attempt` (1-based: the delay after attempt 1 failed is `attempt: 1`). */
+export declare function backoffDelayMs(policy: RetryPolicy, attempt: number, random?: Random): number;
+export interface RetryDecision {
+    readonly retry: boolean;
+    readonly delayMs: number;
+    readonly deadLetter: boolean;
+    readonly nextAttempt: number;
+}
+/** The one place that decides retry vs dead-letter. Drivers never re-derive this. */
+export declare function nextRetry(policy: RetryPolicy, attempt: number, random?: Random): RetryDecision;
+/** Every delay in the policy, jitter off, for docs and `--json` output. */
+export declare function retrySchedule(policy: RetryPolicy): readonly number[];
+//# sourceMappingURL=retry.d.ts.map

package/src/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["retry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEjE,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;IACnC,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,eAAO,MAAM,aAAa;;;;;;;CAOH,CAAC;AAExB,MAAM,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC;AAElC,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAe5F;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAgB9F;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,MAAM,EAAE,CAOpE"}

package/src/retry.js

@@ -0,0 +1,59 @@
+// Retry arithmetic, kept pure so the schedule is testable and printable. `x jobs schedule`
+// renders `retrySchedule()` verbatim — an agent should be able to see when attempt 5 lands
+// without running the queue.
+import { toMs } from './clock';
+export const DEFAULT_RETRY = {
+    attempts: 3,
+    backoff: 'exponential',
+    delay: 1_000,
+    maxDelay: 3_600_000,
+    jitter: true,
+    deadLetter: true,
+};
+/** Delay before `attempt` (1-based: the delay after attempt 1 failed is `attempt: 1`). */
+export function backoffDelayMs(policy, attempt, random) {
+    const base = toMs(policy.delay ?? DEFAULT_RETRY.delay ?? 1_000);
+    const cap = toMs(policy.maxDelay ?? DEFAULT_RETRY.maxDelay ?? 3_600_000);
+    const strategy = policy.backoff ?? 'exponential';
+    const step = Math.max(1, attempt);
+    let raw;
+    if (strategy === 'fixed')
+        raw = base;
+    else if (strategy === 'linear')
+        raw = base * step;
+    else
+        raw = base * 2 ** (step - 1);
+    const capped = Math.min(raw, cap);
+    if (policy.jitter !== true)
+        return Math.round(capped);
+    const roll = (random ?? Math.random)();
+    return Math.round(capped / 2 + (capped / 2) * roll);
+}
+/** The one place that decides retry vs dead-letter. Drivers never re-derive this. */
+export function nextRetry(policy, attempt, random) {
+    const exhausted = attempt >= policy.attempts;
+    if (exhausted) {
+        return {
+            retry: false,
+            delayMs: 0,
+            deadLetter: policy.deadLetter ?? true,
+            nextAttempt: attempt,
+        };
+    }
+    return {
+        retry: true,
+        delayMs: backoffDelayMs(policy, attempt, random),
+        deadLetter: false,
+        nextAttempt: attempt + 1,
+    };
+}
+/** Every delay in the policy, jitter off, for docs and `--json` output. */
+export function retrySchedule(policy) {
+    const deterministic = { ...policy, jitter: false };
+    const out = [];
+    for (let attempt = 1; attempt < policy.attempts; attempt += 1) {
+        out.push(backoffDelayMs(deterministic, attempt));
+    }
+    return out;
+}
+//# sourceMappingURL=retry.js.map

package/src/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["retry.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,2FAA2F;AAC3F,6BAA6B;AAG7B,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAqB/B,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,aAAa;IACtB,KAAK,EAAE,KAAK;IACZ,QAAQ,EAAE,SAAS;IACnB,MAAM,EAAE,IAAI;IACZ,UAAU,EAAE,IAAI;CACK,CAAC;AAIxB,0FAA0F;AAC1F,MAAM,UAAU,cAAc,CAAC,MAAmB,EAAE,OAAe,EAAE,MAAe;IAClF,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC;IAChE,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,aAAa,CAAC,QAAQ,IAAI,SAAS,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,IAAI,aAAa,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAElC,IAAI,GAAW,CAAC;IAChB,IAAI,QAAQ,KAAK,OAAO;QAAE,GAAG,GAAG,IAAI,CAAC;SAChC,IAAI,QAAQ,KAAK,QAAQ;QAAE,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;;QAC7C,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAElC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACtD,CAAC;AASD,qFAAqF;AACrF,MAAM,UAAU,SAAS,CAAC,MAAmB,EAAE,OAAe,EAAE,MAAe;IAC7E,MAAM,SAAS,GAAG,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC;IAC7C,IAAI,SAAS,EAAE,CAAC;QACd,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,CAAC;YACV,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI;YACrC,WAAW,EAAE,OAAO;SACrB,CAAC;IACJ,CAAC;IACD,OAAO;QACL,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC;QAChD,UAAU,EAAE,KAAK;QACjB,WAAW,EAAE,OAAO,GAAG,CAAC;KACzB,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,MAAmB;IAC/C,MAAM,aAAa,GAAgB,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAChE,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,QAAQ,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QAC9D,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/src/retry.ts

@@ -0,0 +1,90 @@
+// Retry arithmetic, kept pure so the schedule is testable and printable. `x jobs schedule`
+// renders `retrySchedule()` verbatim — an agent should be able to see when attempt 5 lands
+// without running the queue.
+
+import type { DurationInput } from './clock';
+import { toMs } from './clock';
+
+export type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+
+export interface RetryPolicy {
+  /** Total attempts including the first. `attempts: 1` means no retry. */
+  readonly attempts: number;
+  readonly backoff?: BackoffStrategy;
+  /** Base delay. Default 1s. */
+  readonly delay?: DurationInput;
+  /** Ceiling for any single delay. Default 1h. */
+  readonly maxDelay?: DurationInput;
+  /**
+   * Equal jitter (half fixed, half random) by default. Without it, a burst of failures
+   * retries in lockstep and re-creates the thundering herd that killed the dependency.
+   */
+  readonly jitter?: boolean;
+  /** Default true: an exhausted job is parked, never dropped. */
+  readonly deadLetter?: boolean;
+}
+
+export const DEFAULT_RETRY = {
+  attempts: 3,
+  backoff: 'exponential',
+  delay: 1_000,
+  maxDelay: 3_600_000,
+  jitter: true,
+  deadLetter: true,
+} satisfies RetryPolicy;
+
+export type Random = () => number;
+
+/** Delay before `attempt` (1-based: the delay after attempt 1 failed is `attempt: 1`). */
+export function backoffDelayMs(policy: RetryPolicy, attempt: number, random?: Random): number {
+  const base = toMs(policy.delay ?? DEFAULT_RETRY.delay ?? 1_000);
+  const cap = toMs(policy.maxDelay ?? DEFAULT_RETRY.maxDelay ?? 3_600_000);
+  const strategy = policy.backoff ?? 'exponential';
+  const step = Math.max(1, attempt);
+
+  let raw: number;
+  if (strategy === 'fixed') raw = base;
+  else if (strategy === 'linear') raw = base * step;
+  else raw = base * 2 ** (step - 1);
+
+  const capped = Math.min(raw, cap);
+  if (policy.jitter !== true) return Math.round(capped);
+  const roll = (random ?? Math.random)();
+  return Math.round(capped / 2 + (capped / 2) * roll);
+}
+
+export interface RetryDecision {
+  readonly retry: boolean;
+  readonly delayMs: number;
+  readonly deadLetter: boolean;
+  readonly nextAttempt: number;
+}
+
+/** The one place that decides retry vs dead-letter. Drivers never re-derive this. */
+export function nextRetry(policy: RetryPolicy, attempt: number, random?: Random): RetryDecision {
+  const exhausted = attempt >= policy.attempts;
+  if (exhausted) {
+    return {
+      retry: false,
+      delayMs: 0,
+      deadLetter: policy.deadLetter ?? true,
+      nextAttempt: attempt,
+    };
+  }
+  return {
+    retry: true,
+    delayMs: backoffDelayMs(policy, attempt, random),
+    deadLetter: false,
+    nextAttempt: attempt + 1,
+  };
+}
+
+/** Every delay in the policy, jitter off, for docs and `--json` output. */
+export function retrySchedule(policy: RetryPolicy): readonly number[] {
+  const deterministic: RetryPolicy = { ...policy, jitter: false };
+  const out: number[] = [];
+  for (let attempt = 1; attempt < policy.attempts; attempt += 1) {
+    out.push(backoffDelayMs(deterministic, attempt));
+  }
+  return out;
+}

package/src/scheduler.d.ts

@@ -0,0 +1,79 @@
+import type { Clock } from '@ultimat3/core';
+import type { EnqueueResult, JobDriver } from './driver';
+import type { AnyJobHandle } from './job';
+/** `[[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) waits for the next one; `run-once` fires a single catch-up; `run-all`
+ * fires one per missed occurrence, bounded by `maxCatchUp`.
+ */
+export type CatchUpPolicy = 'skip' | 'run-once' | 'run-all';
+export interface TaskDefinition {
+    readonly name?: string;
+    readonly cron: string;
+    /** REQUIRED IANA zone, e.g. `'UTC'`, `'America/New_York'`. */
+    readonly tz: string;
+    enqueue: () => readonly TaskEnqueueEntry[];
+    readonly catchUp?: CatchUpPolicy;
+    readonly maxCatchUp?: number;
+}
+export interface TaskHandle {
+    readonly kind: 'task';
+    readonly name: string;
+    readonly cron: string;
+    readonly tz: string;
+    readonly catchUp: CatchUpPolicy;
+    readonly maxCatchUp: number;
+    entries(): readonly TaskEnqueueEntry[];
+}
+/** Resolves the next fire time. Injected so scheduling logic is testable without a cron impl. */
+export type CronResolver = (cron: string, options: {
+    tz: string;
+    from: Date;
+}) => Date;
+export declare function task(definition: TaskDefinition): TaskHandle;
+export declare function nameTasks(record: Readonly<Record<string, TaskHandle>>): void;
+export declare function registeredTasks(): readonly TaskHandle[];
+export declare function getTask(name: string): TaskHandle | undefined;
+export declare function resetTasks(): void;
+export interface LeaderElection {
+    acquire(): Promise<boolean>;
+    release(): Promise<void>;
+}
+/** Single-node default: always the leader. Multi-node uses `createPgLeader()`. */
+export declare function soleLeader(): LeaderElection;
+export interface SchedulerState {
+    /** Epoch ms of the last occurrence this task was dispatched for. */
+    lastFiredAt(taskName: string): Promise<number | undefined>;
+    markFired(taskName: string, occurrenceMs: number): Promise<void>;
+}
+export declare function createMemorySchedulerState(): SchedulerState;
+export interface SchedulerOptions {
+    readonly driver: JobDriver;
+    readonly clock?: Clock;
+    readonly leader?: LeaderElection;
+    readonly state?: SchedulerState;
+    readonly cron?: CronResolver;
+    readonly tickIntervalMs?: number;
+    /** Defaults to every registered task. */
+    readonly tasks?: readonly TaskHandle[];
+}
+export interface DispatchedOccurrence {
+    readonly task: string;
+    readonly occurrenceMs: number;
+    readonly jobs: readonly {
+        readonly job: string;
+        readonly result: EnqueueResult;
+    }[];
+    readonly catchUp: boolean;
+}
+export interface Scheduler {
+    start(): void;
+    stop(): Promise<void>;
+    /** One dispatch round. Returns what it enqueued — tests call this, not the timer. */
+    tick(): Promise<readonly DispatchedOccurrence[]>;
+    nextRunFor(handle: TaskHandle, from?: Date): Date;
+}
+export declare function createScheduler(options: SchedulerOptions): Scheduler;
+//# sourceMappingURL=scheduler.d.ts.map

package/src/scheduler.d.ts.map

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