@fullstackhouse/open-mercato-durable-work 0.1.0

package/dist/transport/pgboss.js

@@ -0,0 +1,176 @@
+import { deliveryId } from "../core/ids.js";
+let cached = null;
+async function pgboss() {
+  if (cached) return cached;
+  try {
+    cached = await import("pg-boss");
+    return cached;
+  } catch (error) {
+    throw new Error(
+      "The pgboss transport requires the optional peer dependency `pg-boss`. Install it, or use DURABLE_WORK_TRANSPORT=bullmq.",
+      { cause: error }
+    );
+  }
+}
+function asDb(tx) {
+  return {
+    async executeSql(text, values) {
+      const result = await tx.query(text, values);
+      return { rows: result.rows, rowCount: result.rowCount };
+    }
+  };
+}
+const tickDelivery = (id) => ({ jobId: id, seq: 0, redrives: 0 });
+class PgBossTransport {
+  constructor(options) {
+    this.options = options;
+    this.name = "pgboss";
+    this.supportsTransactionalEnqueue = true;
+    this.boss = null;
+    this.starting = null;
+    this.ensuredQueues = /* @__PURE__ */ new Set();
+    this.workerIds = [];
+    this.ticks = [];
+    this.shutdown = new AbortController();
+    this.boss = options.instance ?? null;
+    this.ownsInstance = !options.instance;
+  }
+  async ready() {
+    if (this.boss) return this.boss;
+    if (!this.starting) {
+      this.starting = (async () => {
+        const { PgBoss } = await pgboss();
+        const instance = new PgBoss({ connectionString: this.options.connectionString, schema: this.options.schema ?? "durable_work_boss" });
+        await instance.start();
+        this.boss = instance;
+        return instance;
+      })();
+    }
+    return this.starting;
+  }
+  /** pg-boss 10+ requires a queue to exist before anything is sent to it. `expireInSeconds`
+   *  belongs to the queue, not to the worker: it is how long a delivery may stay active before
+   *  pg-boss reclaims it, so it must exceed a whole slice or work that is still running gets
+   *  handed to a second worker — which the lease then refuses, wasting the slice. */
+  async ensureQueue(name, expireInSeconds) {
+    const boss = await this.ready();
+    if (this.ensuredQueues.has(name)) return boss;
+    await boss.createQueue(name, expireInSeconds ? { expireInSeconds } : void 0);
+    this.ensuredQueues.add(name);
+    return boss;
+  }
+  async enqueue(queue, delivery, opts) {
+    const boss = await this.ensureQueue(queue);
+    const key = deliveryId(delivery);
+    const sent = await boss.send(queue, delivery, {
+      // pg-boss job ids are uuids, so the delivery identity travels as the singleton key —
+      // which is also what makes a re-enqueue of the same delivery a no-op.
+      singletonKey: key,
+      startAfter: opts.delayMs && opts.delayMs > 0 ? Math.ceil(opts.delayMs / 1e3) : void 0,
+      retryLimit: opts.retry.attempts,
+      retryDelay: Math.max(1, Math.round(opts.retry.backoff.delayMs / 1e3)),
+      // pg-boss rejects a max delay unless backoff is on, so the cap travels only with it.
+      ...opts.retry.backoff.type === "exponential" ? { retryBackoff: true, retryDelayMax: Math.max(1, Math.round(opts.retry.backoff.maxDelayMs / 1e3)) } : { retryBackoff: false },
+      ...opts.tx ? { db: asDb(opts.tx) } : {}
+    });
+    return { transportJobId: sent ?? key };
+  }
+  async remove(queue, transportJobId) {
+    const boss = await this.ready();
+    await boss.deleteJob(queue, transportJobId).catch(() => void 0);
+  }
+  async getState(queue, transportJobId) {
+    const boss = await this.ready();
+    const job = await boss.getJobById(queue, transportJobId).catch(() => null);
+    if (!job) return "unknown";
+    switch (job.state) {
+      case "created":
+      case "retry":
+        return "waiting";
+      case "active":
+        return "active";
+      case "completed":
+        return "completed";
+      case "cancelled":
+      case "failed":
+        return "failed";
+      default:
+        return "unknown";
+    }
+  }
+  async upsertTick(opts) {
+    await this.ensureQueue(opts.queue);
+    const everySeconds = Math.max(1, Math.round(opts.everyMs / 1e3));
+    const fire = async () => {
+      if (this.shutdown.signal.aborted) return;
+      const boss = await this.ready();
+      await boss.send(opts.queue, tickDelivery(opts.id), { singletonKey: opts.id, singletonSeconds: everySeconds }).catch(() => void 0);
+    };
+    void fire();
+    const timer = setInterval(() => void fire(), opts.everyMs);
+    timer.unref?.();
+    this.ticks.push(timer);
+  }
+  async bind(queue, handler, opts) {
+    const boss = await this.ensureQueue(queue, Math.ceil(opts.activeTimeoutMs / 1e3));
+    const workerId = await boss.work(
+      queue,
+      { batchSize: opts.concurrency },
+      async (jobs) => {
+        for (const job of jobs) {
+          const delivery = job.data;
+          const combined = new AbortController();
+          const relay = () => combined.abort();
+          job.signal?.addEventListener("abort", relay, { once: true });
+          this.shutdown.signal.addEventListener("abort", relay, { once: true });
+          try {
+            await handler(delivery, {
+              transportJobId: job.id,
+              // pg-boss does not expose the attempt on the job, so the adapter reports the
+              // first attempt and lets its own retry policy carry the rest. The consequence is
+              // narrow: the delay written to `next_run_at` is the base rather than a backed-off
+              // one, and pg-boss's own `retryBackoff` still spaces the real deliveries.
+              attempt: 1,
+              maxAttempts: 1,
+              signal: combined.signal,
+              handBack: async (next, handBackOpts) => {
+                await this.enqueue(queue, next, {
+                  delayMs: handBackOpts?.delayMs,
+                  retry: { attempts: 1, backoff: { type: "fixed", delayMs: 0, maxDelayMs: 0 } }
+                });
+              }
+            });
+          } catch (error) {
+            if (error?.name === "NoFurtherAttempts") continue;
+            throw error;
+          } finally {
+            job.signal?.removeEventListener("abort", relay);
+            this.shutdown.signal.removeEventListener("abort", relay);
+          }
+        }
+      }
+    );
+    this.workerIds.push({ queue, id: workerId });
+    return {
+      queue,
+      close: async () => {
+        const instance = await this.ready();
+        await instance.offWork(queue, { id: workerId }).catch(() => void 0);
+      }
+    };
+  }
+  async close(opts = {}) {
+    this.shutdown.abort();
+    for (const timer of this.ticks) clearInterval(timer);
+    this.ticks.length = 0;
+    if (!this.boss) return;
+    if (!this.ownsInstance) return;
+    await this.boss.stop({ graceful: true, close: true, timeout: opts.timeoutMs ?? 3e4 }).catch(() => void 0);
+    this.boss = null;
+    this.starting = null;
+  }
+}
+export {
+  PgBossTransport
+};
+//# sourceMappingURL=pgboss.js.map

package/dist/transport/pgboss.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/transport/pgboss.ts"],
+  "sourcesContent": ["// The pg-boss adapter: production without Redis, and the only adapter that can enqueue a\n// delivery inside the caller's transaction.\n//\n// That one capability is why it exists. `send(..., { db })` composes its statements on a\n// client the caller supplies, so a domain row, its job row and its delivery all commit or all\n// roll back. With any other transport there is a window between commit and enqueue where a\n// crash leaves a job nobody will ever deliver \u2014 the reconciler closes it, but closing it after\n// fifteen minutes is not the same as never opening it.\n//\n// pg-boss is a peer dependency and is imported lazily.\n\nimport { deliveryId } from '../core/ids'\nimport type { Delivery, SqlExecutor } from '../core/types'\nimport type {\n  BindOptions,\n  BoundWorker,\n  DeliveryHandler,\n  DeliveryState,\n  EnqueueOptions,\n  TransportAdapter,\n} from './types'\n\ntype PgBossModule = typeof import('pg-boss')\n// pg-boss 12 exports the class by name, not as a default.\ntype PgBossInstance = InstanceType<PgBossModule['PgBoss']>\ntype PgBossJob = import('pg-boss').Job<Delivery> & { signal?: AbortSignal }\n\nexport type PgBossTransportOptions = {\n  connectionString: string\n  /** Keeps pg-boss's own tables out of `public`, so they are obviously not the app's. */\n  schema?: string\n  /** Reuse an already-started instance instead of owning its lifecycle. */\n  instance?: PgBossInstance\n}\n\nlet cached: PgBossModule | null = null\nasync function pgboss(): Promise<PgBossModule> {\n  if (cached) return cached\n  try {\n    cached = await import('pg-boss')\n    return cached\n  } catch (error) {\n    throw new Error(\n      'The pgboss transport requires the optional peer dependency `pg-boss`. Install it, or use DURABLE_WORK_TRANSPORT=bullmq.',\n      { cause: error },\n    )\n  }\n}\n\n/**\n * Adapts a `SqlExecutor` to the shape pg-boss expects from a caller-supplied client.\n *\n * pg-boss only ever calls `executeSql`, so the whole surface is one method. Passing our own\n * executor through \u2014 rather than requiring a raw `pg` client \u2014 is what lets the caller's\n * transaction be a MikroORM one, a node-postgres one, or the harness's, without any of them\n * knowing about the others.\n */\nfunction asDb(tx: SqlExecutor) {\n  return {\n    async executeSql(text: string, values: unknown[]) {\n      const result = await tx.query(text, values)\n      return { rows: result.rows as Record<string, unknown>[], rowCount: result.rowCount }\n    },\n  }\n}\n\n/** A tick, in the same shape as any other delivery. */\nconst tickDelivery = (id: string): Delivery => ({ jobId: id, seq: 0, redrives: 0 })\n\nexport class PgBossTransport implements TransportAdapter {\n  readonly name = 'pgboss' as const\n  readonly supportsTransactionalEnqueue = true\n\n  private boss: PgBossInstance | null = null\n  private starting: Promise<PgBossInstance> | null = null\n  private readonly ownsInstance: boolean\n  private readonly ensuredQueues = new Set<string>()\n  private readonly workerIds: Array<{ queue: string; id: string }> = []\n  private readonly ticks: NodeJS.Timeout[] = []\n  private readonly shutdown = new AbortController()\n\n  constructor(private readonly options: PgBossTransportOptions) {\n    this.boss = options.instance ?? null\n    this.ownsInstance = !options.instance\n  }\n\n  private async ready(): Promise<PgBossInstance> {\n    if (this.boss) return this.boss\n    if (!this.starting) {\n      this.starting = (async () => {\n        const { PgBoss } = await pgboss()\n        const instance = new PgBoss({ connectionString: this.options.connectionString, schema: this.options.schema ?? 'durable_work_boss' })\n        await instance.start()\n        this.boss = instance\n        return instance\n      })()\n    }\n    return this.starting\n  }\n\n  /** pg-boss 10+ requires a queue to exist before anything is sent to it. `expireInSeconds`\n   *  belongs to the queue, not to the worker: it is how long a delivery may stay active before\n   *  pg-boss reclaims it, so it must exceed a whole slice or work that is still running gets\n   *  handed to a second worker \u2014 which the lease then refuses, wasting the slice. */\n  private async ensureQueue(name: string, expireInSeconds?: number): Promise<PgBossInstance> {\n    const boss = await this.ready()\n    if (this.ensuredQueues.has(name)) return boss\n    await boss.createQueue(name, expireInSeconds ? { expireInSeconds } : undefined)\n    this.ensuredQueues.add(name)\n    return boss\n  }\n\n  async enqueue(queue: string, delivery: Delivery, opts: EnqueueOptions): Promise<{ transportJobId: string }> {\n    const boss = await this.ensureQueue(queue)\n    const key = deliveryId(delivery)\n    const sent = await boss.send(queue, delivery as unknown as object, {\n      // pg-boss job ids are uuids, so the delivery identity travels as the singleton key \u2014\n      // which is also what makes a re-enqueue of the same delivery a no-op.\n      singletonKey: key,\n      startAfter: opts.delayMs && opts.delayMs > 0 ? Math.ceil(opts.delayMs / 1000) : undefined,\n      retryLimit: opts.retry.attempts,\n      retryDelay: Math.max(1, Math.round(opts.retry.backoff.delayMs / 1000)),\n      // pg-boss rejects a max delay unless backoff is on, so the cap travels only with it.\n      ...(opts.retry.backoff.type === 'exponential'\n        ? { retryBackoff: true, retryDelayMax: Math.max(1, Math.round(opts.retry.backoff.maxDelayMs / 1000)) }\n        : { retryBackoff: false }),\n      ...(opts.tx ? { db: asDb(opts.tx) } : {}),\n    })\n    // `send` returns null when the singleton key collapsed this into an existing job. That is\n    // the intended outcome, not a failure: the delivery is already scheduled.\n    return { transportJobId: sent ?? key }\n  }\n\n  async remove(queue: string, transportJobId: string): Promise<void> {\n    const boss = await this.ready()\n    await boss.deleteJob(queue, transportJobId).catch(() => undefined)\n  }\n\n  async getState(queue: string, transportJobId: string): Promise<DeliveryState> {\n    const boss = await this.ready()\n    const job = await boss.getJobById(queue, transportJobId).catch(() => null)\n    if (!job) return 'unknown'\n    switch (job.state) {\n      case 'created':\n      case 'retry':\n        return 'waiting'\n      case 'active':\n        return 'active'\n      case 'completed':\n        return 'completed'\n      case 'cancelled':\n      case 'failed':\n        return 'failed'\n      default:\n        return 'unknown'\n    }\n  }\n\n  async upsertTick(opts: { id: string; queue: string; everyMs: number }): Promise<void> {\n    await this.ensureQueue(opts.queue)\n    // pg-boss's own scheduler is cron-based, so its finest granularity is a minute \u2014 too\n    // coarse for a repair loop. A per-process timer with a singleton key gives the cadence we\n    // need and still collapses the fleet's ticks into one job per window. The trade-off is\n    // stated rather than hidden: with zero workers up there is no tick, exactly as with a\n    // broker-owned schedule that nobody polls.\n    const everySeconds = Math.max(1, Math.round(opts.everyMs / 1000))\n    const fire = async () => {\n      if (this.shutdown.signal.aborted) return\n      const boss = await this.ready()\n      // Delivery-shaped, like every other payload on every adapter: a tick is a delivery\n      // whose handler happens to ignore it, not a second kind of message.\n      await boss\n        .send(opts.queue, tickDelivery(opts.id), { singletonKey: opts.id, singletonSeconds: everySeconds })\n        .catch(() => undefined)\n    }\n    void fire()\n    const timer = setInterval(() => void fire(), opts.everyMs)\n    timer.unref?.()\n    this.ticks.push(timer)\n  }\n\n  async bind(queue: string, handler: DeliveryHandler, opts: BindOptions): Promise<BoundWorker> {\n    const boss = await this.ensureQueue(queue, Math.ceil(opts.activeTimeoutMs / 1000))\n\n    const workerId = await boss.work<Delivery>(\n      queue,\n      { batchSize: opts.concurrency },\n      async (jobs: PgBossJob[]) => {\n        for (const job of jobs) {\n          // Whatever arrived is handed on unexamined. An adapter that inspects payloads\n          // decides what counts as a real delivery, and this one used to skip anything\n          // without a `jobId` \u2014 which silently swallowed every reconciler tick.\n          const delivery = job.data\n\n          const combined = new AbortController()\n          const relay = () => combined.abort()\n          job.signal?.addEventListener('abort', relay, { once: true })\n          this.shutdown.signal.addEventListener('abort', relay, { once: true })\n\n          try {\n            await handler(delivery, {\n              transportJobId: job.id,\n              // pg-boss does not expose the attempt on the job, so the adapter reports the\n              // first attempt and lets its own retry policy carry the rest. The consequence is\n              // narrow: the delay written to `next_run_at` is the base rather than a backed-off\n              // one, and pg-boss's own `retryBackoff` still spaces the real deliveries.\n              attempt: 1,\n              maxAttempts: 1,\n              signal: combined.signal,\n              handBack: async (next, handBackOpts) => {\n                // No native hand-back: send the next delivery and let this one complete. The\n                // row is already at `seq + 1`, so the new key cannot collide with this job.\n                await this.enqueue(queue, next, {\n                  delayMs: handBackOpts?.delayMs,\n                  retry: { attempts: 1, backoff: { type: 'fixed', delayMs: 0, maxDelayMs: 0 } },\n                })\n              },\n            })\n          } catch (error) {\n            if ((error as { name?: string })?.name === 'NoFurtherAttempts') continue // settled; no retry wanted\n            throw error\n          } finally {\n            job.signal?.removeEventListener('abort', relay)\n            this.shutdown.signal.removeEventListener('abort', relay)\n          }\n        }\n      },\n    )\n\n    this.workerIds.push({ queue, id: workerId })\n    return {\n      queue,\n      close: async () => {\n        const instance = await this.ready()\n        await instance.offWork(queue, { id: workerId }).catch(() => undefined)\n      },\n    }\n  }\n\n  async close(opts: { timeoutMs?: number } = {}): Promise<void> {\n    this.shutdown.abort()\n    for (const timer of this.ticks) clearInterval(timer)\n    this.ticks.length = 0\n    if (!this.boss) return\n    if (!this.ownsInstance) return\n    await this.boss.stop({ graceful: true, close: true, timeout: opts.timeoutMs ?? 30_000 }).catch(() => undefined)\n    this.boss = null\n    this.starting = null\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/transport/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/transport/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/generated/entities/durable_work_job/index.ts

@@ -0,0 +1,42 @@
+export const id = "id";
+export const tenant_id = "tenant_id";
+export const organization_id = "organization_id";
+export const kind = "kind";
+export const status = "status";
+export const created_by = "created_by";
+export const created_at = "created_at";
+export const updated_at = "updated_at";
+export const input = "input";
+export const checkpoint = "checkpoint";
+export const meta = "meta";
+export const idempotency_key = "idempotency_key";
+export const lock_key = "lock_key";
+export const subject_type = "subject_type";
+export const subject_id = "subject_id";
+export const progress_job_id = "progress_job_id";
+export const lease_owner = "lease_owner";
+export const lease_epoch = "lease_epoch";
+export const lease_expires_at = "lease_expires_at";
+export const heartbeat_at = "heartbeat_at";
+export const queue_name = "queue_name";
+export const queue_job_id = "queue_job_id";
+export const continuation_seq = "continuation_seq";
+export const redrives = "redrives";
+export const next_run_at = "next_run_at";
+export const pending_since = "pending_since";
+export const redrives_since_commit = "redrives_since_commit";
+export const consecutive_failures = "consecutive_failures";
+export const interruptions = "interruptions";
+export const mirror_attempts = "mirror_attempts";
+export const last_committed_at = "last_committed_at";
+export const started_at = "started_at";
+export const finished_at = "finished_at";
+export const parked_at = "parked_at";
+export const cancel_requested_at = "cancel_requested_at";
+export const cancelled_by = "cancelled_by";
+export const error_class = "error_class";
+export const error_code = "error_code";
+export const error_message = "error_message";
+export const domain_mirrored_at = "domain_mirrored_at";
+export const processed_count = "processed_count";
+export const total_count = "total_count";

package/generated/entities.ids.generated.ts

@@ -0,0 +1,9 @@
+// GENERATED by scripts/gen-entity-ids.mjs from core/schema.ts. Do not edit.
+export const M = {
+  "durable_work": "durable_work"
+} as const
+export const E = {
+  "durable_work": {
+    "durable_work_job": "durable_work:durable_work_job"
+  }
+} as const

package/package.json

@@ -0,0 +1,145 @@
+{
+  "name": "@fullstackhouse/open-mercato-durable-work",
+  "version": "0.1.0",
+  "description": "Durable at-least-once background work for Open Mercato apps: a leased job record in Postgres with epoch fencing, bounded resumable slices, a server-side reconciler, fenced cancel and an operator API. Pluggable transport (BullMQ or pg-boss).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "license": "MIT",
+  "author": "Full Stack House",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fullstackhouse/open-mercato-durable.git",
+    "directory": "packages/durable-work"
+  },
+  "keywords": [
+    "open-mercato",
+    "background-jobs",
+    "durable",
+    "at-least-once",
+    "queue",
+    "bullmq",
+    "pg-boss"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist",
+    "src",
+    "generated",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node build.mjs && node scripts/gen-entity-ids.mjs",
+    "prepack": "yarn build",
+    "watch": "node watch.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "gen:entity-ids": "node scripts/gen-entity-ids.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.tsx": {
+      "types": "./src/*.tsx",
+      "default": "./dist/*.js"
+    },
+    "./*.json": "./src/*.json",
+    "./*": {
+      "types": [
+        "./src/*.ts",
+        "./src/*.tsx"
+      ],
+      "default": "./dist/*.js"
+    },
+    "./*/*.json": "./src/*/*.json",
+    "./*/*": {
+      "types": [
+        "./src/*/*.ts",
+        "./src/*/*.tsx"
+      ],
+      "default": "./dist/*/*.js"
+    },
+    "./*/*/*.json": "./src/*/*/*.json",
+    "./*/*/*": {
+      "types": [
+        "./src/*/*/*.ts",
+        "./src/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*.js"
+    },
+    "./*/*/*/*.json": "./src/*/*/*/*.json",
+    "./*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*.ts",
+        "./src/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*.js"
+    },
+    "./*/*/*/*/*.json": "./src/*/*/*/*/*.json",
+    "./*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*.js"
+    }
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": ">=7.0.0",
+    "@mikro-orm/migrations": ">=7.0.0",
+    "@mikro-orm/postgresql": ">=7.0.0",
+    "@open-mercato/core": ">=0.7.0 <0.8.0",
+    "@open-mercato/shared": ">=0.7.0 <0.8.0",
+    "bullmq": "^5.0.0 || ^6.0.0",
+    "ioredis": ">=5.0.0",
+    "next": ">=15.0.0",
+    "pg": ">=8.0.0",
+    "pg-boss": ">=12.0.0 <13.0.0",
+    "zod": ">=3.25.0"
+  },
+  "peerDependenciesMeta": {
+    "bullmq": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "pg-boss": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@mikro-orm/core": "^7.1.8",
+    "@mikro-orm/migrations": "^7.1.8",
+    "@mikro-orm/postgresql": "^7.1.8",
+    "@open-mercato/core": "0.7.0",
+    "@open-mercato/shared": "0.7.0",
+    "@types/node": "^24.10.1",
+    "@types/pg": "^8.20.0",
+    "awilix": "^13.0.5",
+    "bullmq": "^6.3.4",
+    "esbuild": "^0.25.0",
+    "eslint": "^9.0.0",
+    "glob": "^13.0.6",
+    "globals": "^16.0.0",
+    "ioredis": "^5.11.1",
+    "next": "16.3.0",
+    "pg": "^8.23.0",
+    "pg-boss": "^12.30.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0",
+    "zod": "^4.4.3"
+  }
+}

package/src/core/__tests__/registry.test.ts

@@ -0,0 +1,43 @@
+import { KindRegistry } from '../registry'
+
+import type { SliceOutcome } from '../types'
+
+const kind = (id: string, step: () => Promise<SliceOutcome> = async () => 'drained') => ({ kind: id, queue: 'durable-work.test', step })
+
+describe('KindRegistry', () => {
+  it('accepts the same handler registered twice', () => {
+    // `register` runs on every container build, which in a web process is every request. A
+    // registry that treated re-registration as a conflict would crash the second request.
+    const registry = new KindRegistry()
+    const definition = kind('test.a')
+    registry.register(definition)
+    expect(() => registry.register(definition)).not.toThrow()
+    expect(registry.list()).toHaveLength(1)
+  })
+
+  it('refuses two different handlers under one id', () => {
+    // Accepting the second silently would make "which code runs this job?" depend on the order
+    // containers happened to be built in.
+    const registry = new KindRegistry()
+    registry.register(kind('test.b'))
+    expect(() => registry.register(kind('test.b', async () => 'budget'))).toThrow(/Duplicate durable job kind/)
+  })
+
+  it('refuses a domain mirror with no way back', () => {
+    // An operator could otherwise re-drive the job while the domain row stayed terminal.
+    const registry = new KindRegistry()
+    expect(() => registry.register({ ...kind('test.c'), onTransition: async () => ({ matched: 1 }) })).toThrow(
+      /onTransition without onRedrive/,
+    )
+  })
+
+  it('applies defaults, including parking rather than re-driving an orphan', () => {
+    const registry = new KindRegistry()
+    registry.register(kind('test.d'))
+    const resolved = registry.require('test.d')
+    // A job nobody declared idempotent is not re-run automatically just because its worker died.
+    expect(resolved.orphanPolicy).toBe('park')
+    expect(resolved.lease.ttlMs).toBeGreaterThan(0)
+    expect(resolved.budget.maxConsecutiveFailures).toBeGreaterThan(0)
+  })
+})

package/src/core/errors.ts

@@ -0,0 +1,104 @@
+// The error taxonomy. Anything a step throws that is not one of these is `transient`: an
+// unrecognised failure is far more often a blip than a dead end, and the cost of guessing
+// wrong is one retry rather than a multi-day run thrown away.
+
+import type { ErrorClass } from './types'
+
+/** Retry this delivery. The default class for anything unrecognised. */
+export class TransientError extends Error {
+  readonly durableErrorClass: ErrorClass = 'transient'
+  constructor(message: string, options?: { cause?: unknown; code?: string }) {
+    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined)
+    this.name = 'TransientError'
+    this.code = options?.code
+  }
+  readonly code?: string
+}
+
+/** Fail the job now, without further transport attempts. Still re-drivable by an operator. */
+export class TerminalError extends Error {
+  readonly durableErrorClass: ErrorClass = 'terminal'
+  constructor(message: string, options?: { cause?: unknown; code?: string }) {
+    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined)
+    this.name = 'TerminalError'
+    this.code = options?.code
+  }
+  readonly code?: string
+}
+
+/** Fail the job now and refuse a plain re-drive: an operator must pass `{ force: true }`.
+ *  For failures where running the work again is known to be wrong, not merely useless. */
+export class UnrecoverableError extends Error {
+  readonly durableErrorClass: ErrorClass = 'unrecoverable'
+  constructor(message: string, options?: { cause?: unknown; code?: string }) {
+    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined)
+    this.name = 'UnrecoverableError'
+    this.code = options?.code
+  }
+  readonly code?: string
+}
+
+/** Thrown by `fencedWrite` when the lease was lost or taken while the slice was running. The
+ *  transaction it guards has already rolled back, so nothing the slice believed it wrote is
+ *  in the database. Never retried inside the slice: the job now belongs to someone else. */
+export class LeaseLostError extends Error {
+  readonly durableErrorClass: ErrorClass = 'transient'
+  constructor(readonly lease: { jobId: string; owner: string; epoch: number }) {
+    super(`Lease lost for job ${lease.jobId} (owner ${lease.owner}, epoch ${lease.epoch})`)
+    this.name = 'LeaseLostError'
+  }
+}
+
+/** Another live job already holds this `lockKey` in this scope. The single-runner guarantee,
+ *  surfaced as a 409 rather than a duplicate run. */
+export class LockKeyHeldError extends Error {
+  readonly durableErrorClass: ErrorClass = 'terminal'
+  constructor(
+    readonly lockKey: string,
+    readonly heldBy?: string,
+  ) {
+    super(`Lock key ${JSON.stringify(lockKey)} is held by a live job${heldBy ? ` (${heldBy})` : ''}`)
+    this.name = 'LockKeyHeldError'
+  }
+}
+
+/** Signals the transport to end this delivery without scheduling another attempt. The job's
+ *  own state already says what happened; a further attempt would claim a row that refuses it. */
+export class NoFurtherAttempts extends Error {
+  constructor(readonly reason: string) {
+    super(`No further transport attempts: ${reason}`)
+    this.name = 'NoFurtherAttempts'
+  }
+}
+
+/** A registry lookup for a kind no process registered. */
+export class UnknownKindError extends Error {
+  constructor(readonly kind: string) {
+    super(`No handler registered for durable job kind ${JSON.stringify(kind)}`)
+    this.name = 'UnknownKindError'
+  }
+}
+
+const CLASSES: ReadonlySet<string> = new Set<ErrorClass>(['transient', 'terminal', 'unrecoverable'])
+
+/** Reads the class off an error, defaulting to `transient`.
+ *
+ *  Matches on a `durableErrorClass` property rather than `instanceof`, so an error that
+ *  crossed a package boundary — two copies of this package in one install, a re-thrown cause,
+ *  a structured-clone — is still classified correctly. Getting this wrong the other way would
+ *  silently downgrade an `unrecoverable` to a retry loop. */
+export function classifyError(error: unknown): ErrorClass {
+  const candidate = (error as { durableErrorClass?: unknown } | null | undefined)?.durableErrorClass
+  return typeof candidate === 'string' && CLASSES.has(candidate) ? (candidate as ErrorClass) : 'transient'
+}
+
+/** The `error_code` to persist, if the error carries one. */
+export function errorCodeOf(error: unknown): string | null {
+  const code = (error as { code?: unknown } | null | undefined)?.code
+  return typeof code === 'string' && code.length > 0 ? code : null
+}
+
+export function errorMessageOf(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return typeof error === 'string' ? error : 'Unknown error'
+}

package/src/core/ids.ts

@@ -0,0 +1,58 @@
+// Delivery identity and queue naming.
+
+import type { Delivery } from './types'
+
+/** The id a transport carries for one delivery of one job.
+ *
+ *  Colon-free on purpose: BullMQ 6 rejects `:` in a job id (it is the separator in its own
+ *  Redis keys), and the id has to be usable unchanged as a pg-boss `singletonKey` too.
+ *
+ *  It encodes `(jobId, seq, redrives)` because that triple IS the fence: a delivery whose seq
+ *  or redrives no longer match the row is a straggler from a previous slice or re-drive, and
+ *  `claim` refuses it. Making the id carry the triple means a duplicate delivery is refused by
+ *  the database rather than deduplicated by the broker, which is the only version of that
+ *  guarantee that survives a broker restart. */
+export function deliveryId(delivery: Delivery): string {
+  return `dw-${delivery.jobId}-${delivery.seq}-${delivery.redrives}`
+}
+
+const DELIVERY_ID = /^dw-(.+)-(\d+)-(\d+)$/
+
+export function parseDeliveryId(id: string): Delivery | null {
+  const match = DELIVERY_ID.exec(id)
+  if (!match) return null
+  return { jobId: match[1]!, seq: Number(match[2]), redrives: Number(match[3]) }
+}
+
+/**
+ * Queues are named per kind group so one worker process can bind a subset of kinds.
+ *
+ * A period, not a colon. pg-boss validates queue names against
+ * `[alphanumeric, _, -, ., /]` and rejects a colon outright, and BullMQ gives `:` special
+ * meaning inside its own Redis keys. One name has to work on every adapter — a per-adapter
+ * rewrite would mean the queue an operator sees in the code is not the queue they can find
+ * in the broker.
+ */
+export function queueNameFor(group: string): string {
+  return `durable-work.${group}`
+}
+
+/** The characters every supported broker accepts in a queue name. */
+export const PORTABLE_QUEUE_NAME = /^[A-Za-z0-9_\-./]+$/
+
+/** The idempotency key handed to a slice, and the one it should forward to any external
+ *  side effect. Stable across retries of the same slice, different for the next slice. */
+export function sliceIdempotencyKey(jobId: string, seq: number): string {
+  return `${jobId}:${seq}`
+}
+
+/** Identifies one worker process for the lifetime of that process.
+ *
+ *  The random suffix is what makes "is this lease mine?" answerable after a crash: a restarted
+ *  process on the same host must not match the lease its predecessor held, or a stalled
+ *  redelivery to the new process would be accepted while the old row still looks alive. */
+export function makeOwnerId(prefix = 'dw'): string {
+  const random = Math.random().toString(36).slice(2, 10)
+  const pid = typeof process !== 'undefined' && process.pid ? process.pid : 0
+  return `${prefix}-${pid}-${Date.now().toString(36)}-${random}`
+}