@ultimat3/jobs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @ultimat3/jobs ⚙️
+
+Durable background work. Steps that replay, a transactional outbox that is on by default,
+and one driver interface so Postgres → Redis → NATS is a config line.
+
+```ts
+import { job, t } from '@ultimat3/jobs';
+
+export const onboardOrg = job({
+  input: t.object({ orgId: t.uuid }),
+  idempotencyKey: ({ orgId }) => `onboard:${orgId}`,   // REQUIRED by the type
+  retry: { attempts: 5, backoff: 'exponential' },
+  async run({ input, step, ctx }) {
+    const org = await step.run('provision', () => ctx.orgs.provision(input.orgId));
+    await step.run('welcome-email', () => ctx.mail.send(welcomeEmail, org));
+    await step.sleep('3d');
+    await step.run('nudge', () => ctx.mail.send(nudgeEmail, org));
+  },
+});
+```
+
+`welcome-email` fails? Attempt 2 replays `provision` **from storage** and re-sends only the
+email. The 3-day sleep does not hold a process: the run suspends and the queue redelivers it.
+
+## The handle is the surface
+
+```ts
+await onboardOrg.enqueue({ orgId });              // joins the ambient transaction
+await onboardOrg.as(ctx.actor, { orgId });        // same, tenantId stamped from the actor
+onboardOrg.describe();                            // the manifest row for this job
+await nightlyDigest.enqueue();                    // fire a task's entries now
+nightlyDigest.describe();                         // { kind: 'task', cron, tz, jobs, … }
+```
+
+| Member | On | Behaviour |
+|---|---|---|
+| `enqueue(input, options?)` | `JobHandle` | queues through `jobsFacade()`; joins the caller's `tx` when the outbox is installed |
+| `as(actor, input, options?)` | `JobHandle` | enqueue on behalf of an actor — fills `tenantId` from `actor.orgId` so per-tenant limits apply |
+| `describe()` | `JobHandle` | the `JobDescriptor` the manifest, `/_x` and MCP read |
+| `entries()` | `TaskHandle` | the declared `[job, input]` pairs |
+| `enqueue(options?)` | `TaskHandle` | fires every declared entry now, one result per entry |
+| `describe()` | `TaskHandle` | `TaskDescriptor` — cron, tz, catch-up, jobs in declaration order |
+
+## The export name is the job's name
+
+```ts
+export const api = defineApi({
+  jobs: [postJobs, orgJobs],     // module namespaces, never a list of name strings
+  tasks: [scheduledTasks],
+});
+```
+
+`defineApi` hands each module to `registerJobs`/`registerTasks`, which stamp the export name
+onto **the handle the module exported** and re-key the registry — `import { onboardOrg }` is the
+object `enqueue()` routes through after boot, not a renamed copy of it. Hand nothing over and a
+job keeps the positional name `job()` gave it: `anonymous-job-2` on the queue row, in
+`x.manifest.json` and in every dead-letter trace, appearing in no source file.
+
+A definition that sets `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 — `@ultimat3/mail`'s `mail.send` relies on exactly that.
+
+Registering the same handle twice is one registration seen twice, because `defineApi` and the
+framework's module scan both reach the same declaration file. Everything else that puts two
+things on one durable name is `X_JOB_DUPLICATE`, refused at the earliest point it is decidable:
+
+| Collision | Refused at |
+|---|---|
+| two definitions setting the same `name:` | `job()` / `task()`, before either can seat the other out |
+| two different handles under one export name | `defineApi` |
+| one handle exported twice (`export { notify as a, notify as b }`) | `defineApi` — the second alias would move the queue key |
+
+`registerJobs`/`registerTasks` are internal: `defineApi` reaches them through core's registrar
+table, and they are not part of this package's public API. There is one way to register.
+
+`.as()` **queues**; it never runs the handler inline. A job's execution surface is the queue,
+so an inline run would be a second execution path next to the worker's — with no retry, no
+dedupe and no dead letter. Its idempotency key is the job's own, so a manual `task.enqueue()`
+and the scheduler's occurrence-scoped fire stay distinct rows on purpose.
+
+With no facade installed, `enqueue` publishes straight to `jobDriver()`; with none of those
+either, it is `X_DRIVER_UNAVAILABLE` at the call, not a silently dropped job.
+
+## `idempotencyKey` is required by the type
+
+Not a convention, not a lint rule — a non-optional field on `JobDefinition`. Queues deliver
+at least once (partition, lease expiry, outbox replay), so every job is asked "have you
+already run?" whether or not its author thought about it. Optional means the answer is
+usually "nobody thought about it", and the bug — two charges, two welcome emails, two
+provisioned orgs — shows up in production under load and never in a test. There is no way
+to define a job in Ultimate that cannot be deduped.
+
+## Durable steps
+
+| Call | Behaviour |
+|---|---|
+| `step.run(name, fn)` | runs once ever; result persisted before the next step starts |
+| `step.sleep(name, '3d')` | suspends the run, requeues it for the wake time |
+| `step.sleep('3d')` | same, step name derived from the duration |
+| `step.waitForEvent(name, event, { match, timeout })` | suspends until `publishEvent()` matches |
+
+Step names are the replay key, so they must be deterministic and unique in a run — a
+duplicate is `X_STEP_DUPLICATE`, not a silent overwrite. Suspension is control flow
+(`StepSuspension`), never a failure: it does not burn a retry attempt.
+
+## The transactional outbox (on by default)
+
+```ts
+await ctx.tx(async (tx) => {
+  const post = await ctx.posts.publish(input.postId, tx);
+  await notifySubscribers.enqueue({ postId: post.id }); // joins `tx`
+});
+```
+
+The job row is written in the **same transaction** as the business rows; a relay publishes
+it after commit. The bug class this removes:
+
+| Without an outbox | Result |
+|---|---|
+| enqueue, then the transaction rolls back | the job runs against rows that never existed |
+| commit, then the process dies before enqueue | the job is lost, silently, forever |
+
+Both are load-dependent, both pass every test you would write, and both produce "the email
+went out but the order isn't in the database". Joining the transaction closes the window.
+The relay publishes *then* marks published, so a crash re-publishes — collapsed by the
+idempotency key. Set `mode: 'required'` to make an enqueue outside a transaction an
+`X_OUTBOX_NO_TX` error instead of a direct publish.
+
+## Drivers
+
+One interface: `enqueue`, `claim` (visibility timeout), `ack`, `nack` (backoff),
+`heartbeat`, `stats`. Zero job-code change between them.
+
+| Driver | Status | Backing | Use |
+|---|---|---|---|
+| `pg` | **default** | `SELECT ... FOR UPDATE SKIP LOCKED`, partial unique index, advisory-lock leader | zero-infra start, most apps |
+| `memory` | complete | in-process maps | `x dev`, tests |
+| `redis` | interface-complete, `X_NOT_IMPLEMENTED` | Streams + consumer groups | planned |
+| `nats` | interface-complete, `X_NOT_IMPLEMENTED` | JetStream work queue | planned |
+
+The pg SQL is exported verbatim (`SQL_CLAIM`, `SQL_ENQUEUE`, `SQL_NACK`, …) so an agent
+debugging a stuck queue can read and run the exact statement.
+
+## Roles
+
+| Role | Entry | Behaviour |
+|---|---|---|
+| `worker` | `createWorker({ driver, queues, concurrency })` | per-queue pools, heartbeat, SIGTERM drain: stop claiming → finish in-flight → close |
+| `scheduler` | `createScheduler({ driver, leader })` | advisory-lock leader, one dispatcher per tick, catch-up policy |
+
+```ts
+export const nightlyDigest = task({
+  cron: '0 3 * * *',
+  tz: 'UTC',                      // REQUIRED — a cron without a timezone is a bug
+  enqueue: () => [[sendDigest, {}]],
+});
+```
+
+`tz` is required by the type *and* validated against the runtime's IANA database, because a
+non-empty string is not a timezone: `tz: 'Bogota'` would resolve every occurrence in UTC and
+run five hours off, silently, forever. `0 3 * * *` in a DST zone runs twice or zero times on
+the switch day. Catch-up after downtime is explicit: `skip` (default), `run-once`, `run-all`.
+
+## Retries
+
+`{ attempts, backoff: 'exponential' | 'linear' | 'fixed', delay, maxDelay, jitter }`.
+Equal jitter is on by default so a burst of failures does not retry in lockstep.
+Exhausted jobs are dead-lettered, never dropped: `x jobs retry <id>`.
+
+```
+retrySchedule({ attempts: 5, backoff: 'exponential', delay: 1000 })
+// => [1000, 2000, 4000, 8000]
+```
+
+## Limits
+
+Per-tenant concurrency (`tenantId` = the actor's `orgId`, carried on the queue row), a
+per-queue cap and a global cap. Over a cap, the claim is handed straight back without
+burning an attempt — one org's 50k-row import cannot starve the fleet.
+
+## Introspection
+
+`inspectQueues`, `inspectJob` (per-step trace), `inspectDeadLetters`, `retryFromStep`,
+`inspectManifest` — all `--json`-shaped, shared by `/_x`, the CLI and the MCP tools.
+
+## Errors
+
+| Code | Cause |
+|---|---|
+| `X_IDEMPOTENCY_REQUIRED` | job defined without an idempotency key (JS callers) |
+| `X_STEP_DUPLICATE` | two steps share a name in one run |
+| `X_JOB_DUPLICATE` | enqueue collided with a live key under `onConflict: 'error'`; or two different job/task handles registered under one name |
+| `X_JOB_TIMEOUT` | job or required `waitForEvent` exceeded its timeout |
+| `X_JOB_MAX_ATTEMPTS` | retries exhausted, job dead-lettered |
+| `X_OUTBOX_NO_TX` | enqueue outside a transaction with `mode: 'required'` |
+| `X_DRIVER_UNAVAILABLE` | no `DATABASE_URL` / executor for the pg driver |
+| `X_NOT_IMPLEMENTED` | redis / nats driver |
+
+## Boundary
+
+Tier 3. Imports `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/entity`,
+`@ultimat3/policy`, `@ultimat3/cache`, `@ultimat3/time`. Never HTTP, render or UI.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ultimat3/jobs",
+  "version": "1.0.0",
+  "description": "Durable background work: steps, transactional outbox, cron tasks, one driver interface",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/jobs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/entity": "1.0.0",
+    "@ultimat3/schema": "1.0.0",
+    "@ultimat3/time": "1.0.0"
+  }
+}

package/src/clock.d.ts

@@ -0,0 +1,7 @@
+import type { Clock } from '@ultimat3/core';
+export type DurationInput = string | number;
+/** A Clock may hand back a `Date` or epoch ms; scheduling needs one comparable number. */
+export declare function nowMs(clock?: Clock): number;
+/** `'3d'` | `'30s'` | `1500` -> ms. Numbers pass through so callers may stay explicit. */
+export declare function toMs(duration: DurationInput): number;
+//# sourceMappingURL=clock.d.ts.map

package/src/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["clock.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAI5C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,0FAA0F;AAC1F,wBAAgB,KAAK,CAAC,KAAK,GAAE,KAAmB,GAAG,MAAM,CAIxD;AAED,0FAA0F;AAC1F,wBAAgB,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAKpD"}

package/src/clock.js

@@ -0,0 +1,21 @@
+// Internal: every scheduling decision in this package is made in epoch ms against an
+// injected Clock, so tests never sleep and a frozen clock cannot be bypassed.
+import { systemClock } from '@ultimat3/core';
+import { parseDuration } from '@ultimat3/time';
+/** A Clock may hand back a `Date` or epoch ms; scheduling needs one comparable number. */
+export function nowMs(clock = systemClock) {
+    const reading = clock.now();
+    if (reading instanceof Date)
+        return reading.getTime();
+    return Number(reading);
+}
+/** `'3d'` | `'30s'` | `1500` -> ms. Numbers pass through so callers may stay explicit. */
+export function toMs(duration) {
+    if (typeof duration === 'number')
+        return duration;
+    const parsed = parseDuration(duration);
+    if (parsed instanceof Date)
+        return parsed.getTime();
+    return Number(parsed);
+}
+//# sourceMappingURL=clock.js.map

package/src/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["clock.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,8EAA8E;AAG9E,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/C,0FAA0F;AAC1F,MAAM,UAAU,KAAK,CAAC,KAAK,GAAU,WAAW;IAC9C,MAAM,OAAO,GAAY,KAAK,CAAC,GAAG,EAAE,CAAC;IACrC,IAAI,OAAO,YAAY,IAAI;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IACtD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,IAAI,CAAC,QAAuB;IAC1C,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAClD,MAAM,MAAM,GAAY,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,MAAM,YAAY,IAAI;QAAE,OAAO,MAAM,CAAC,OAAO,EAAE,CAAC;IACpD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC"}

package/src/clock.ts

@@ -0,0 +1,23 @@
+// Internal: every scheduling decision in this package is made in epoch ms against an
+// injected Clock, so tests never sleep and a frozen clock cannot be bypassed.
+
+import type { Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+import { parseDuration } from '@ultimat3/time';
+
+export type DurationInput = string | number;
+
+/** A Clock may hand back a `Date` or epoch ms; scheduling needs one comparable number. */
+export function nowMs(clock: Clock = systemClock): number {
+  const reading: unknown = clock.now();
+  if (reading instanceof Date) return reading.getTime();
+  return Number(reading);
+}
+
+/** `'3d'` | `'30s'` | `1500` -> ms. Numbers pass through so callers may stay explicit. */
+export function toMs(duration: DurationInput): number {
+  if (typeof duration === 'number') return duration;
+  const parsed: unknown = parseDuration(duration);
+  if (parsed instanceof Date) return parsed.getTime();
+  return Number(parsed);
+}

package/src/describe.ts

@@ -0,0 +1,61 @@
+// The JSON projection of one job handle, shared by `handle.describe()` and `describeJobs()`.
+// Byte-stability is the whole point: `x.manifest.json` is committed and diffed, so anything
+// clock- or iteration-order-dependent in this shape is a spurious change on every build.
+
+import { toJsonSchema } from '@ultimat3/schema';
+import type { BackoffStrategy, RetryPolicy } from './retry';
+import { DEFAULT_RETRY } from './retry';
+
+/** A registered job as the manifest, the `/_x` jobs panel and the MCP dev server read it. */
+export interface JobDescriptor {
+  readonly name: string;
+  /** JSON Schema, exactly as an action's descriptor publishes one — never the schema object. */
+  readonly input: Record<string, unknown>;
+  readonly queue: string;
+  readonly retry: { readonly attempts: number; readonly backoff: BackoffStrategy };
+  readonly steps: readonly string[];
+}
+
+/**
+ * Narrower than `JobHandle` on purpose: the projection reads four declared fields, so keeping
+ * it structural means it never has to carry — or vary with — the handle's input generic.
+ */
+export interface DescribableJob {
+  readonly name: string;
+  readonly queue: string;
+  readonly retry: RetryPolicy;
+  readonly input: unknown;
+}
+
+export function describeJob(handle: DescribableJob): JobDescriptor {
+  return {
+    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: [],
+  };
+}
+
+/**
+ * The job's input as JSON Schema. Naming the vendor — which is all this used to publish — told a
+ * reader of `x.manifest.json` who validated the payload and nothing about its shape, so the one
+ * fact the manifest exists to carry was missing. Never throws: a schema the active provider cannot
+ * introspect degrades to a permissive object node, because a missing manifest detail must not
+ * break a build.
+ */
+function describeSchema(schema: unknown): Record<string, unknown> {
+  try {
+    const converted: unknown = toJsonSchema(schema);
+    if (typeof converted === 'object' && converted !== null && !Array.isArray(converted))
+      return converted as Record<string, unknown>;
+  } catch {
+    // fall through to the permissive node
+  }
+  return { type: 'object', additionalProperties: true };
+}

package/src/driver-memory.d.ts

@@ -0,0 +1,9 @@
+import type { Clock } from '@ultimat3/core';
+import type { JobDriver } from './driver';
+import type { StepStore } from './steps';
+export interface MemoryDriverOptions {
+    readonly clock?: Clock;
+    readonly steps?: StepStore;
+}
+export declare function createMemoryDriver(options?: MemoryDriverOptions): JobDriver;
+//# sourceMappingURL=driver-memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"driver-memory.d.ts","sourceRoot":"","sources":["driver-memory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAG5C,OAAO,KAAK,EAKV,SAAS,EAMV,MAAM,UAAU,CAAC;AAGlB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGzC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAID,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,SAAS,CAwL/E"}

package/src/driver-memory.js

@@ -0,0 +1,189 @@
+// In-process driver for `x dev` and tests: same semantics as pg (visibility timeout,
+// idempotency dedupe, dead-letter) with zero infrastructure, so a test suite exercises the
+// real claim/ack/nack paths rather than a mock that always succeeds.
+import { assert, systemClock, uuid } from '@ultimat3/core';
+import { nowMs } from './clock';
+import { DEFAULT_QUEUE } from './driver';
+import { JobDuplicateError } from './errors';
+import { createMemoryStepStore } from './steps';
+const LIVE_STATES = new Set(['ready', 'delayed', 'running', 'suspended']);
+export function createMemoryDriver(options = {}) {
+    const clock = options.clock ?? systemClock;
+    const steps = options.steps ?? createMemoryStepStore();
+    const jobs = new Map();
+    const liveByKey = (key) => {
+        for (const record of jobs.values()) {
+            if (record.idempotencyKey === key && LIVE_STATES.has(record.state))
+                return record;
+        }
+        return undefined;
+    };
+    const update = (id, patch) => {
+        const existing = jobs.get(id);
+        if (existing === undefined)
+            return;
+        jobs.set(id, { ...existing, ...patch, updatedAt: nowMs(clock) });
+    };
+    const introspect = {
+        job(jobId) {
+            return Promise.resolve(jobs.get(jobId));
+        },
+        list(filter = {}) {
+            const rows = [...jobs.values()]
+                .filter((record) => filter.queue === undefined || record.queue === filter.queue)
+                .filter((record) => filter.name === undefined || record.name === filter.name)
+                .filter((record) => filter.state === undefined || record.state === filter.state)
+                .sort((a, b) => a.createdAt - b.createdAt)
+                .slice(0, filter.limit ?? 100);
+            return Promise.resolve(rows);
+        },
+        deadLetters(limit = 100) {
+            const rows = [...jobs.values()]
+                .filter((record) => record.state === 'dead')
+                .sort((a, b) => b.updatedAt - a.updatedAt)
+                .slice(0, limit);
+            return Promise.resolve(rows);
+        },
+        async requeue(jobId, requeueOptions) {
+            const existing = jobs.get(jobId);
+            assert(existing !== undefined, `no job ${jobId} in the memory driver`, 'requeue a job id returned by enqueue() or stats() — the memory driver holds no state across processes, so an id from another run will not resolve');
+            const record = existing;
+            if (requeueOptions?.fromStep !== undefined) {
+                // Drop the target step so it re-executes; earlier steps stay memoized.
+                await steps.del(record.runId, requeueOptions.fromStep);
+            }
+            update(jobId, { state: 'ready', attempt: 0, runAt: nowMs(clock) });
+            const next = jobs.get(jobId);
+            return next ?? record;
+        },
+    };
+    return {
+        name: 'memory',
+        steps,
+        introspect,
+        enqueue(request) {
+            const existing = liveByKey(request.idempotencyKey);
+            if (existing !== undefined) {
+                if (request.onConflict === 'error') {
+                    throw new JobDuplicateError({
+                        job: request.name,
+                        idempotencyKey: request.idempotencyKey,
+                        existingId: existing.id,
+                    });
+                }
+                return Promise.resolve({ id: existing.id, runId: existing.runId, deduped: true });
+            }
+            const at = nowMs(clock);
+            const runAt = request.runAt ?? at;
+            const record = {
+                id: uuid(),
+                name: request.name,
+                queue: request.queue || DEFAULT_QUEUE,
+                input: request.input,
+                idempotencyKey: request.idempotencyKey,
+                runId: request.runId ?? uuid(),
+                attempt: 0,
+                maxAttempts: request.maxAttempts,
+                state: runAt > at ? 'delayed' : 'ready',
+                runAt,
+                createdAt: at,
+                updatedAt: at,
+                ...(request.tenantId === undefined ? {} : { tenantId: request.tenantId }),
+            };
+            jobs.set(record.id, record);
+            return Promise.resolve({ id: record.id, runId: record.runId, deduped: false });
+        },
+        claim(claimOptions) {
+            const at = nowMs(clock);
+            const wanted = new Set(claimOptions.queues);
+            const claimable = [...jobs.values()]
+                .filter((record) => wanted.size === 0 || wanted.has(record.queue))
+                .filter((record) => {
+                if (record.runAt > at)
+                    return false;
+                if (record.state === 'ready' || record.state === 'delayed')
+                    return true;
+                if (record.state === 'suspended')
+                    return true;
+                // Lease expiry: a worker that died without ack releases its job here.
+                return record.state === 'running' && (record.visibleAt ?? 0) <= at;
+            })
+                .sort((a, b) => a.runAt - b.runAt)
+                .slice(0, claimOptions.limit);
+            const out = [];
+            for (const record of claimable) {
+                const claimed = {
+                    ...record,
+                    state: 'running',
+                    attempt: record.attempt + 1,
+                    claimedBy: claimOptions.workerId,
+                    claimedAt: at,
+                    visibleAt: at + claimOptions.visibilityTimeoutMs,
+                    updatedAt: at,
+                };
+                jobs.set(record.id, claimed);
+                out.push(claimed);
+            }
+            return Promise.resolve(out);
+        },
+        ack(jobId) {
+            update(jobId, { state: 'done' });
+            return Promise.resolve();
+        },
+        nack(jobId, nackOptions) {
+            const record = jobs.get(jobId);
+            if (record === undefined)
+                return Promise.resolve();
+            const at = nowMs(clock);
+            const counts = nackOptions.countsAsAttempt !== false;
+            const patch = {
+                state: nackOptions.deadLetter === true ? 'dead' : counts ? 'ready' : 'suspended',
+                runAt: at + nackOptions.delayMs,
+                // A suspension must not burn an attempt, or a 3-day sleep dead-letters the run.
+                attempt: counts ? record.attempt : record.attempt - 1,
+                ...(nackOptions.error === undefined ? {} : { lastError: nackOptions.error }),
+            };
+            update(jobId, patch);
+            return Promise.resolve();
+        },
+        heartbeat(jobId, heartbeatOptions) {
+            update(jobId, { visibleAt: nowMs(clock) + heartbeatOptions.visibilityTimeoutMs });
+            return Promise.resolve();
+        },
+        stats() {
+            const at = nowMs(clock);
+            const byQueue = new Map();
+            for (const record of jobs.values()) {
+                const current = byQueue.get(record.queue) ?? {
+                    queue: record.queue,
+                    ready: 0,
+                    delayed: 0,
+                    running: 0,
+                    suspended: 0,
+                    dead: 0,
+                    oldestReadyMs: 0,
+                };
+                const next = { ...current };
+                if (record.state === 'ready' && record.runAt <= at) {
+                    next.ready += 1;
+                    next.oldestReadyMs = Math.max(next.oldestReadyMs, at - record.runAt);
+                }
+                else if (record.state === 'ready' || record.state === 'delayed')
+                    next.delayed += 1;
+                else if (record.state === 'running')
+                    next.running += 1;
+                else if (record.state === 'suspended')
+                    next.suspended += 1;
+                else if (record.state === 'dead')
+                    next.dead += 1;
+                byQueue.set(record.queue, next);
+            }
+            return Promise.resolve([...byQueue.values()].sort((a, b) => a.queue.localeCompare(b.queue)));
+        },
+        close() {
+            jobs.clear();
+            return Promise.resolve();
+        },
+    };
+}
+//# sourceMappingURL=driver-memory.js.map

package/src/driver-memory.js.map

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