@ultimat3/jobs 1.0.0

package/src/driver-pg.ts

@@ -0,0 +1,356 @@
+// The DEFAULT driver: a Postgres queue. Zero infra to start — the database you already have
+// is the queue. `SELECT ... FOR UPDATE SKIP LOCKED` lets N workers claim disjoint batches
+// without a coordinator, and the visibility timeout (`visible_at`) makes a worker crash cost
+// one lease instead of one job. The statements themselves live in `driver-pg-sql.ts`.
+
+import type { Clock } from '@ultimat3/core';
+import { systemClock, uuid } from '@ultimat3/core';
+import { nowMs } from './clock';
+import type {
+  ClaimedJob,
+  ClaimOptions,
+  EnqueueRequest,
+  EnqueueResult,
+  JobDriver,
+  JobFilter,
+  JobIntrospection,
+  JobRecord,
+  NackOptions,
+  QueueStats,
+} from './driver';
+import { DEFAULT_QUEUE } from './driver';
+import {
+  SQL_ACK,
+  SQL_ADVISORY_UNLOCK,
+  SQL_CLAIM,
+  SQL_ENQUEUE,
+  SQL_FIND_LIVE_BY_KEY,
+  SQL_HEARTBEAT,
+  SQL_NACK,
+  SQL_STATS,
+  SQL_STEP_GET,
+  SQL_STEP_PUT,
+  SQL_TRY_ADVISORY_LOCK,
+} from './driver-pg-sql';
+import { DriverUnavailableError, JobDuplicateError } from './errors';
+import type { StepRecord, StepStore } from './steps';
+
+/** The one thing this driver needs from the DB layer. Satisfied by `Bun.sql` and by a Tx. */
+export interface PgExecutor {
+  query<R>(sql: string, params: readonly unknown[]): Promise<readonly R[]>;
+}
+
+export interface PgDriverOptions {
+  readonly executor?: PgExecutor;
+  readonly clock?: Clock;
+}
+
+interface StepRow {
+  readonly run_id: string;
+  readonly name: string;
+  readonly status: string;
+  readonly output: unknown;
+  readonly started_at: number | string;
+  readonly completed_at: number | string | null;
+  readonly wake_at: number | string | null;
+  readonly event: string | null;
+  readonly correlation_key: string | null;
+  readonly attempts: number;
+  readonly error: string | null;
+}
+
+interface JobRow {
+  readonly id: string;
+  readonly name: string;
+  readonly queue: string;
+  readonly input: unknown;
+  readonly idempotency_key: string;
+  readonly run_id: string;
+  readonly attempt: number;
+  readonly max_attempts: number;
+  readonly state: string;
+  readonly tenant_id: string | null;
+  readonly last_error: string | null;
+  readonly claimed_by: string | null;
+  readonly run_at: number | string;
+  readonly visible_at: number | string | null;
+  readonly created_at: number | string;
+  readonly updated_at: number | string;
+}
+
+const num = (value: number | string | null | undefined): number =>
+  value === null || value === undefined ? 0 : Number(value);
+
+const optionalNum = (value: number | string | null | undefined): number | undefined =>
+  value === null || value === undefined ? undefined : Number(value);
+
+function toJobRecord(row: JobRow): JobRecord {
+  const visibleAt = optionalNum(row.visible_at);
+  return {
+    id: row.id,
+    name: row.name,
+    queue: row.queue,
+    input: row.input,
+    idempotencyKey: row.idempotency_key,
+    runId: row.run_id,
+    attempt: row.attempt,
+    maxAttempts: row.max_attempts,
+    state: row.state as JobRecord['state'],
+    runAt: num(row.run_at),
+    createdAt: num(row.created_at),
+    updatedAt: num(row.updated_at),
+    ...(row.tenant_id === null ? {} : { tenantId: row.tenant_id }),
+    ...(row.last_error === null ? {} : { lastError: row.last_error }),
+    ...(row.claimed_by === null ? {} : { claimedBy: row.claimed_by }),
+    ...(visibleAt === undefined ? {} : { visibleAt }),
+  };
+}
+
+function toStepRecord(row: StepRow): StepRecord {
+  const completedAt = optionalNum(row.completed_at);
+  const wakeAt = optionalNum(row.wake_at);
+  return {
+    runId: row.run_id,
+    name: row.name,
+    status: row.status as StepRecord['status'],
+    output: row.output,
+    startedAt: num(row.started_at),
+    attempts: row.attempts,
+    ...(completedAt === undefined ? {} : { completedAt }),
+    ...(wakeAt === undefined ? {} : { wakeAt }),
+    ...(row.event === null ? {} : { event: row.event }),
+    ...(row.correlation_key === null ? {} : { correlationKey: row.correlation_key }),
+    ...(row.error === null ? {} : { error: row.error }),
+  };
+}
+
+function resolveExecutor(injected: PgExecutor | undefined): PgExecutor {
+  if (injected !== undefined) return injected;
+  throw new DriverUnavailableError({
+    driver: 'pg',
+    cause: 'no PgExecutor was provided and Bun.sql is not configured',
+    fix: 'set DATABASE_URL in .env then run `x db up`, or use driver: "memory" in app.config.ts',
+  });
+}
+
+function pgStepStore(exec: () => PgExecutor): StepStore {
+  return {
+    async get(runId, name) {
+      const rows = await exec().query<StepRow>(SQL_STEP_GET, [runId, name]);
+      const row = rows[0];
+      return row === undefined ? undefined : toStepRecord(row);
+    },
+    async put(record) {
+      await exec().query(SQL_STEP_PUT, [
+        record.runId,
+        record.name,
+        record.status,
+        JSON.stringify(record.output ?? null),
+        record.startedAt,
+        record.completedAt ?? null,
+        record.wakeAt ?? null,
+        record.event ?? null,
+        record.correlationKey ?? null,
+        record.attempts,
+        record.error ?? null,
+      ]);
+    },
+    async list(runId) {
+      const rows = await exec().query<StepRow>(
+        `select * from x_job_steps where run_id = $1 order by started_at`,
+        [runId],
+      );
+      return rows.map(toStepRecord);
+    },
+    async del(runId, name) {
+      await exec().query(`delete from x_job_steps where run_id = $1 and name = $2`, [runId, name]);
+    },
+    async clear(runId) {
+      await exec().query(`delete from x_job_steps where run_id = $1`, [runId]);
+    },
+  };
+}
+
+export function createPgDriver(options: PgDriverOptions = {}): JobDriver {
+  const clock = options.clock ?? systemClock;
+  let executor: PgExecutor | undefined;
+  const exec = (): PgExecutor => {
+    executor ??= resolveExecutor(options.executor);
+    return executor;
+  };
+
+  const introspect: JobIntrospection = {
+    async job(jobId) {
+      const rows = await exec().query<JobRow>(`select * from x_jobs where id = $1`, [jobId]);
+      const row = rows[0];
+      return row === undefined ? undefined : toJobRecord(row);
+    },
+    async list(filter: JobFilter = {}) {
+      const rows = await exec().query<JobRow>(
+        `select * from x_jobs
+          where ($1::text is null or queue = $1)
+            and ($2::text is null or name  = $2)
+            and ($3::text is null or state = $3)
+          order by created_at desc
+          limit $4`,
+        [filter.queue ?? null, filter.name ?? null, filter.state ?? null, filter.limit ?? 100],
+      );
+      return rows.map(toJobRecord);
+    },
+    async deadLetters(limit = 100) {
+      const rows = await exec().query<JobRow>(
+        `select * from x_jobs where state = 'dead' order by updated_at desc limit $1`,
+        [limit],
+      );
+      return rows.map(toJobRecord);
+    },
+    async requeue(jobId, requeueOptions) {
+      if (requeueOptions?.fromStep !== undefined) {
+        const current = await this.job(jobId);
+        if (current !== undefined) {
+          await exec().query(`delete from x_job_steps where run_id = $1 and name = $2`, [
+            current.runId,
+            requeueOptions.fromStep,
+          ]);
+        }
+      }
+      const rows = await exec().query<JobRow>(
+        `update x_jobs set state = 'ready', attempt = 0, run_at = now(), updated_at = now()
+          where id = $1 returning *`,
+        [jobId],
+      );
+      const row = rows[0];
+      if (row === undefined) {
+        throw new DriverUnavailableError({
+          driver: 'pg',
+          cause: `job ${jobId} does not exist`,
+          fix: 'x jobs list --state dead --json',
+        });
+      }
+      return toJobRecord(row);
+    },
+  };
+
+  return {
+    name: 'pg',
+    steps: pgStepStore(exec),
+    introspect,
+
+    async enqueue(request: EnqueueRequest): Promise<EnqueueResult> {
+      const runAt = request.runAt ?? nowMs(clock);
+      const rows = await exec().query<{ id: string; run_id: string }>(SQL_ENQUEUE, [
+        uuid(),
+        request.name,
+        request.queue || DEFAULT_QUEUE,
+        JSON.stringify(request.input ?? null),
+        request.idempotencyKey,
+        request.runId ?? uuid(),
+        request.maxAttempts,
+        runAt,
+        request.tenantId ?? null,
+      ]);
+      const inserted = rows[0];
+      if (inserted !== undefined) {
+        return { id: inserted.id, runId: inserted.run_id, deduped: false };
+      }
+
+      // `do nothing` fired: a live job already owns this idempotency key.
+      const existing = await exec().query<{ id: string; run_id: string }>(SQL_FIND_LIVE_BY_KEY, [
+        request.idempotencyKey,
+      ]);
+      const found = existing[0];
+      if (found === undefined) {
+        throw new DriverUnavailableError({
+          driver: 'pg',
+          cause: `enqueue of "${request.name}" was rejected but no live row holds its idempotency key`,
+          fix: 'x db check — the x_jobs_idempotency_live_idx index is missing or stale',
+        });
+      }
+      if (request.onConflict === 'error') {
+        throw new JobDuplicateError({
+          job: request.name,
+          idempotencyKey: request.idempotencyKey,
+          existingId: found.id,
+        });
+      }
+      return { id: found.id, runId: found.run_id, deduped: true };
+    },
+
+    async claim(claimOptions: ClaimOptions): Promise<readonly ClaimedJob[]> {
+      const queues = claimOptions.queues.length > 0 ? claimOptions.queues : [DEFAULT_QUEUE];
+      const rows = await exec().query<JobRow>(SQL_CLAIM, [
+        queues,
+        claimOptions.limit,
+        claimOptions.workerId,
+        claimOptions.visibilityTimeoutMs,
+      ]);
+      const at = nowMs(clock);
+      return rows.map((row) => {
+        const record = toJobRecord(row);
+        return {
+          ...record,
+          claimedAt: at,
+          visibleAt: record.visibleAt ?? at + claimOptions.visibilityTimeoutMs,
+        };
+      });
+    },
+
+    async ack(jobId: string): Promise<void> {
+      await exec().query(SQL_ACK, [jobId]);
+    },
+
+    async nack(jobId: string, nackOptions: NackOptions): Promise<void> {
+      const counts = nackOptions.countsAsAttempt !== false;
+      const state = nackOptions.deadLetter === true ? 'dead' : counts ? 'ready' : 'suspended';
+      await exec().query(SQL_NACK, [
+        jobId,
+        state,
+        counts,
+        nackOptions.delayMs,
+        nackOptions.error ?? null,
+      ]);
+    },
+
+    async heartbeat(jobId: string, heartbeatOptions): Promise<void> {
+      await exec().query(SQL_HEARTBEAT, [jobId, heartbeatOptions.visibilityTimeoutMs]);
+    },
+
+    async stats(): Promise<readonly QueueStats[]> {
+      const rows = await exec().query<{
+        queue: string;
+        ready: number | string;
+        delayed: number | string;
+        running: number | string;
+        suspended: number | string;
+        dead: number | string;
+        oldest_ready_ms: number | string;
+      }>(SQL_STATS, []);
+      return rows.map((row) => ({
+        queue: row.queue,
+        ready: num(row.ready),
+        delayed: num(row.delayed),
+        running: num(row.running),
+        suspended: num(row.suspended),
+        dead: num(row.dead),
+        oldestReadyMs: Math.round(num(row.oldest_ready_ms)),
+      }));
+    },
+  };
+}
+
+/** Advisory-lock leader election, used by the `scheduler` role. */
+export function createPgLeader(
+  lockKey: number,
+  options: PgDriverOptions = {},
+): { acquire(): Promise<boolean>; release(): Promise<void> } {
+  const exec = (): PgExecutor => resolveExecutor(options.executor);
+  return {
+    async acquire() {
+      const rows = await exec().query<{ locked: boolean }>(SQL_TRY_ADVISORY_LOCK, [lockKey]);
+      return rows[0]?.locked === true;
+    },
+    async release() {
+      await exec().query(SQL_ADVISORY_UNLOCK, [lockKey]);
+    },
+  };
+}

package/src/driver-redis.d.ts

@@ -0,0 +1,7 @@
+import type { JobDriver } from './driver';
+export interface RedisDriverOptions {
+    readonly url?: string;
+    readonly consumerGroup?: string;
+}
+export declare function createRedisDriver(_options?: RedisDriverOptions): JobDriver;
+//# sourceMappingURL=driver-redis.d.ts.map

package/src/driver-redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-redis.d.ts","sourceRoot":"","sources":["driver-redis.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAKV,SAAS,EAGV,MAAM,UAAU,CAAC;AA4BlB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,kBAAuB,GAAG,SAAS,CAuB9E"}

package/src/driver-redis.js

@@ -0,0 +1,54 @@
+// Redis driver — interface-complete, not implemented. Honest stub: correct types so an app
+// can be written against it and `x verify` typechecks, with one labelled throw per method so
+// nobody discovers the gap from a silently-dropped job.
+//
+// Design it will implement when written: a per-queue Redis Stream with a consumer group
+// (XADD / XREADGROUP / XACK), `XAUTOCLAIM` for the visibility timeout, a ZSET for delayed
+// and suspended runs, and step records in a hash keyed by run id.
+import { JobsNotImplementedError } from './errors';
+const FIX = 'use driver: "pg" (default) or "memory" — see docs/jobs/drivers.md#redis';
+const unavailable = (method) => {
+    throw new JobsNotImplementedError({ feature: `redis jobs driver (${method})`, fix: FIX });
+};
+const redisStepStore = () => ({
+    get(_runId, _name) {
+        return unavailable('steps.get');
+    },
+    put(_record) {
+        return unavailable('steps.put');
+    },
+    list(_runId) {
+        return unavailable('steps.list');
+    },
+    del(_runId, _name) {
+        return unavailable('steps.del');
+    },
+    clear(_runId) {
+        return unavailable('steps.clear');
+    },
+});
+export function createRedisDriver(_options = {}) {
+    return {
+        name: 'redis',
+        steps: redisStepStore(),
+        enqueue(_request) {
+            return unavailable('enqueue');
+        },
+        claim(_options) {
+            return unavailable('claim');
+        },
+        ack(_jobId) {
+            return unavailable('ack');
+        },
+        nack(_jobId, _options) {
+            return unavailable('nack');
+        },
+        heartbeat(_jobId, _options) {
+            return unavailable('heartbeat');
+        },
+        stats() {
+            return unavailable('stats');
+        },
+    };
+}
+//# sourceMappingURL=driver-redis.js.map

package/src/driver-redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-redis.js","sourceRoot":"","sources":["driver-redis.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,6FAA6F;AAC7F,wDAAwD;AACxD,EAAE;AACF,wFAAwF;AACxF,0FAA0F;AAC1F,kEAAkE;AAWlE,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAGnD,MAAM,GAAG,GAAG,yEAAyE,CAAC;AAEtF,MAAM,WAAW,GAAG,CAAC,MAAc,EAAS,EAAE;IAC5C,MAAM,IAAI,uBAAuB,CAAC,EAAE,OAAO,EAAE,sBAAsB,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;AAC5F,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,GAAc,EAAE,CAAC,CAAC;IACvC,GAAG,CAAC,MAAc,EAAE,KAAa;QAC/B,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC;IAClC,CAAC;IACD,GAAG,CAAC,OAAmB;QACrB,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,MAAc;QACjB,OAAO,WAAW,CAAC,YAAY,CAAC,CAAC;IACnC,CAAC;IACD,GAAG,CAAC,MAAc,EAAE,KAAa;QAC/B,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC;IAClC,CAAC;IACD,KAAK,CAAC,MAAc;QAClB,OAAO,WAAW,CAAC,aAAa,CAAC,CAAC;IACpC,CAAC;CACF,CAAC,CAAC;AAOH,MAAM,UAAU,iBAAiB,CAAC,QAAQ,GAAuB,EAAE;IACjE,OAAO;QACL,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,cAAc,EAAE;QACvB,OAAO,CAAC,QAAwB;YAC9B,OAAO,WAAW,CAAC,SAAS,CAAC,CAAC;QAChC,CAAC;QACD,KAAK,CAAC,QAAsB;YAC1B,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;QACD,GAAG,CAAC,MAAc;YAChB,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,MAAc,EAAE,QAAqB;YACxC,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;QACD,SAAS,CAAC,MAAc,EAAE,QAAkD;YAC1E,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC;QAClC,CAAC;QACD,KAAK;YACH,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/src/driver-redis.ts

@@ -0,0 +1,76 @@
+// Redis driver — interface-complete, not implemented. Honest stub: correct types so an app
+// can be written against it and `x verify` typechecks, with one labelled throw per method so
+// nobody discovers the gap from a silently-dropped job.
+//
+// Design it will implement when written: a per-queue Redis Stream with a consumer group
+// (XADD / XREADGROUP / XACK), `XAUTOCLAIM` for the visibility timeout, a ZSET for delayed
+// and suspended runs, and step records in a hash keyed by run id.
+
+import type {
+  ClaimedJob,
+  ClaimOptions,
+  EnqueueRequest,
+  EnqueueResult,
+  JobDriver,
+  NackOptions,
+  QueueStats,
+} from './driver';
+import { JobsNotImplementedError } from './errors';
+import type { StepRecord, StepStore } from './steps';
+
+// Names the config edit that actually removes the stub, plus the runnable command for whatever
+// is already queued. The redis driver lands in v2; there is no flag that turns this one on.
+const FIX =
+  "set jobs: { driver: 'postgres' } in app.config.ts, then: x jobs drain --to memory --json";
+
+const unavailable = (method: string): never => {
+  throw new JobsNotImplementedError({ feature: `redis jobs driver (${method})`, fix: FIX });
+};
+
+const redisStepStore = (): StepStore => ({
+  get(_runId: string, _name: string): Promise<StepRecord | undefined> {
+    return unavailable('steps.get');
+  },
+  put(_record: StepRecord): Promise<void> {
+    return unavailable('steps.put');
+  },
+  list(_runId: string): Promise<readonly StepRecord[]> {
+    return unavailable('steps.list');
+  },
+  del(_runId: string, _name: string): Promise<void> {
+    return unavailable('steps.del');
+  },
+  clear(_runId: string): Promise<void> {
+    return unavailable('steps.clear');
+  },
+});
+
+export interface RedisDriverOptions {
+  readonly url?: string;
+  readonly consumerGroup?: string;
+}
+
+export function createRedisDriver(_options: RedisDriverOptions = {}): JobDriver {
+  return {
+    name: 'redis',
+    steps: redisStepStore(),
+    enqueue(_request: EnqueueRequest): Promise<EnqueueResult> {
+      return unavailable('enqueue');
+    },
+    claim(_options: ClaimOptions): Promise<readonly ClaimedJob[]> {
+      return unavailable('claim');
+    },
+    ack(_jobId: string): Promise<void> {
+      return unavailable('ack');
+    },
+    nack(_jobId: string, _options: NackOptions): Promise<void> {
+      return unavailable('nack');
+    },
+    heartbeat(_jobId: string, _options: { readonly visibilityTimeoutMs: number }): Promise<void> {
+      return unavailable('heartbeat');
+    },
+    stats(): Promise<readonly QueueStats[]> {
+      return unavailable('stats');
+    },
+  };
+}

package/src/driver.d.ts

@@ -0,0 +1,114 @@
+import type { StepStore } from './steps';
+export type JobState = 'ready' | 'delayed' | 'running' | 'suspended' | 'done' | 'failed' | 'dead';
+export interface JobRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly queue: string;
+    readonly input: unknown;
+    /** Dedupe key from the job definition. At-least-once delivery leans on this. */
+    readonly idempotencyKey: string;
+    /** Stable across retries and suspensions — the key every step record hangs off. */
+    readonly runId: string;
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly state: JobState;
+    /** Epoch ms; the job is invisible until then. */
+    readonly runAt: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    /** Actor's orgId, for per-tenant limits. */
+    readonly tenantId?: string;
+    readonly lastError?: string;
+    readonly claimedBy?: string;
+    readonly visibleAt?: number;
+}
+export type ConflictPolicy = 'dedupe' | 'error';
+export interface EnqueueRequest {
+    readonly name: string;
+    readonly queue: string;
+    readonly input: unknown;
+    readonly idempotencyKey: string;
+    readonly maxAttempts: number;
+    /** Epoch ms. Omit for "now". */
+    readonly runAt?: number;
+    readonly tenantId?: string;
+    /** Reuse an existing run id when resuming, so step history is preserved. */
+    readonly runId?: string;
+    readonly onConflict?: ConflictPolicy;
+}
+export interface EnqueueResult {
+    readonly id: string;
+    readonly runId: string;
+    /** True when an in-flight job already held this idempotency key. */
+    readonly deduped: boolean;
+}
+export interface ClaimOptions {
+    readonly queues: readonly string[];
+    readonly limit: number;
+    /** Lease length. A worker that dies without ack makes the job claimable again after this. */
+    readonly visibilityTimeoutMs: number;
+    readonly workerId: string;
+}
+export interface ClaimedJob extends JobRecord {
+    readonly claimedAt: number;
+    readonly visibleAt: number;
+}
+export interface NackOptions {
+    /** Delay before the job becomes claimable again. */
+    readonly delayMs: number;
+    readonly error?: string;
+    /**
+     * False for a suspension (`step.sleep`): parking a run is not a failure and must not burn
+     * a retry attempt, or a 3-day sleep would dead-letter the job.
+     */
+    readonly countsAsAttempt?: boolean;
+    readonly deadLetter?: boolean;
+}
+export interface QueueStats {
+    readonly queue: string;
+    readonly ready: number;
+    readonly delayed: number;
+    readonly running: number;
+    readonly suspended: number;
+    readonly dead: number;
+    /** Age in ms of the oldest claimable job — the number that decides autoscaling. */
+    readonly oldestReadyMs: number;
+}
+export interface JobFilter {
+    readonly queue?: string;
+    readonly name?: string;
+    readonly state?: JobState;
+    readonly limit?: number;
+}
+/** Optional: powers `/_x` and the MCP tools. A minimal driver may omit it. */
+export interface JobIntrospection {
+    job(jobId: string): Promise<JobRecord | undefined>;
+    list(filter?: JobFilter): Promise<readonly JobRecord[]>;
+    deadLetters(limit?: number): Promise<readonly JobRecord[]>;
+    /** Re-queue a dead/failed job. `fromStep` drops step records from that step onward. */
+    requeue(jobId: string, options?: {
+        readonly fromStep?: string;
+    }): Promise<JobRecord>;
+}
+export interface JobDriver {
+    readonly name: string;
+    /** Step persistence lives with the queue: one store, one transaction boundary. */
+    readonly steps: StepStore;
+    enqueue(request: EnqueueRequest): Promise<EnqueueResult>;
+    claim(options: ClaimOptions): Promise<readonly ClaimedJob[]>;
+    ack(jobId: string): Promise<void>;
+    nack(jobId: string, options: NackOptions): Promise<void>;
+    /** Extends the lease of a long-running job so it is not double-claimed. */
+    heartbeat(jobId: string, options: {
+        readonly visibilityTimeoutMs: number;
+    }): Promise<void>;
+    stats(): Promise<readonly QueueStats[]>;
+    readonly introspect?: JobIntrospection;
+    close?(): Promise<void>;
+}
+export declare const DEFAULT_QUEUE = "default";
+export declare const DEFAULT_VISIBILITY_TIMEOUT_MS = 30000;
+/** Set once at boot from `app.config.ts`. Roles share one driver instance per process. */
+export declare function setJobDriver(driver: JobDriver): void;
+export declare function jobDriver(): JobDriver | undefined;
+//# sourceMappingURL=driver.d.ts.map

package/src/driver.d.ts.map

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

package/src/driver.js

@@ -0,0 +1,14 @@
+// The queue contract. Every driver (pg, memory, redis, nats) implements exactly this, so
+// switching backends is a config line and ZERO job-code change. Six methods and no more:
+// claim/ack/nack with a visibility timeout is the smallest set that survives a worker crash.
+export const DEFAULT_QUEUE = 'default';
+export const DEFAULT_VISIBILITY_TIMEOUT_MS = 30_000;
+let ambient;
+/** Set once at boot from `app.config.ts`. Roles share one driver instance per process. */
+export function setJobDriver(driver) {
+    ambient = driver;
+}
+export function jobDriver() {
+    return ambient;
+}
+//# sourceMappingURL=driver.js.map

package/src/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["driver.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,yFAAyF;AACzF,6FAA6F;AAuH7F,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AACvC,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAC;AAEpD,IAAI,OAA8B,CAAC;AAEnC,0FAA0F;AAC1F,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC5C,OAAO,GAAG,MAAM,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,OAAO,CAAC;AACjB,CAAC"}