@dudousxd/nestjs-durable-transport-db 0.2.1 → 0.2.2

package/dist/index.d.cts

@@ -74,10 +74,27 @@ interface DbTransportOptions {
     prefix?: string;
     /** Poll interval in ms when a queue is empty. Default 500. */
     pollMs?: number;
-    /** How long a claimed row is owned before it's reclaimable (crash recovery), in ms. Default 30_000. */
+    /**
+     * How long a claimed row is owned before it's reclaimable (crash recovery), in ms. Default 30_000.
+     * Every claim this instance holds is renewed every `leaseMs / 3` while it is waiting or running, so
+     * a step may run longer than `leaseMs`; only a crashed (or event-loop-blocked) instance loses it.
+     */
     leaseMs?: number;
-    /** Max rows claimed per poll. Default 10. */
+    /**
+     * Max rows claimed per poll. Default 10. The task loop claims only as many rows as it has free
+     * {@link concurrency} slots (capped by this); the results loop claims up to this many.
+     */
     batchSize?: number;
+    /**
+     * How many tasks this instance runs at once (worker side). Default 1. A row is claimed only when a
+     * slot is free to run it, so rows never wait claimed behind a slow task while a sibling sits idle.
+     */
+    concurrency?: number;
+    /**
+     * Where a transport failure is reported: a failing poll, a throwing result handler (the result is
+     * re-delivered after the lease), a lost claim. Default `console.error`.
+     */
+    onError?: (err: unknown) => void;
     /** Create the two tables on first use if missing. Default true. */
     autoCreate?: boolean;
     /** Identifies this instance in `claimed_by` (for debugging). Defaults to a random id. */
@@ -104,6 +121,8 @@ declare class DbTransport implements Transport {
     private readonly pollMs;
     private readonly leaseMs;
     private readonly batchSize;
+    private readonly concurrency;
+    private readonly onError;
     private readonly autoCreate;
     private readonly instanceId;
     private readonly isPg;
@@ -112,12 +131,24 @@ declare class DbTransport implements Transport {
     private schemaReady?;
     private taskLoop?;
     private resultLoop?;
+    /** Tasks running on this instance (at most `concurrency`). */
+    private readonly runningTasks;
+    /** Claim tokens this instance holds, by table — every one is renewed on `renewTimer`. */
+    private readonly held;
+    private renewTimer?;
+    private renewal?;
     constructor(options: DbTransportOptions);
     /** Positional placeholder for param `i` (1-based): `$i` on Postgres, `?` elsewhere. */
     private ph;
     private q;
     private now;
     private ensureSchema;
+    /**
+     * Run one `CREATE … IF NOT EXISTS`. Two instances booting on a fresh database race it, and Postgres
+     * can reject the loser with a unique violation on its catalog even with `IF NOT EXISTS`; the
+     * statement is simply re-run, by which point the table exists and it is a no-op.
+     */
+    private createIfMissing;
     private createTables;
     dispatch(task: RemoteTask): Promise<void>;
     handle(name: string, fn: StepHandler): void;
@@ -125,16 +156,47 @@ declare class DbTransport implements Transport {
     onHeartbeat(_handler: (beat: Heartbeat) => Promise<void>): void;
     /** Run `tick` repeatedly; sleep `pollMs` when it reports an empty queue. Stops on `close()`. */
     private loop;
-    /** Claim a batch of tasks (FOR UPDATE SKIP LOCKED), then run each outside the lock. */
+    /**
+     * One task-loop round: claim as many rows as there are free slots (never more — a claimed row that
+     * isn't running is one an idle sibling can't run), and start each. With every slot busy, wait for
+     * one to free instead of polling.
+     */
     private drainTasks;
-    /** Claim a batch of results, deliver each to the engine, then delete it. */
+    /**
+     * Run one claimed task and settle it — only while this instance still holds the claim: the claim is
+     * re-checked before running, and the task row is deleted and its result written in ONE transaction,
+     * conditional on the claim token, so an instance whose claim was taken over neither deletes the new
+     * holder's row nor publishes a second result.
+     */
+    private runTask;
+    /** Whether the claim on `stepId` is still `token`'s (re-stamping it if so). */
+    private stillHolds;
+    /** Delete the task row and publish its result in ONE transaction, only while `token` holds it. */
+    private settleTask;
+    /**
+     * Claim a batch of results, deliver each to the engine, and delete it — only after its handler ran
+     * (at-least-once), and only while this round still holds the claim (a newer result for the same
+     * step that replaced the row resets the claim, so it is delivered next instead of deleted). The
+     * batch's claim is renewed until it is done. A throwing handler is reported and its row left for
+     * re-delivery after the lease; the rest of the batch continues.
+     */
     private drainResults;
     /**
-     * Atomically claim up to `batchSize` un-leased rows matching `where` and stamp them with this
-     * instance's lease. `SELECT … FOR UPDATE SKIP LOCKED` inside the txn means concurrent instances
-     * skip each other's locked rows instead of blocking, so no row is claimed twice.
+     * Atomically claim up to `limit` un-leased rows matching `where` and stamp them with a claim token
+     * unique to this round (`<instanceId>:<uuid>`). `SELECT … FOR UPDATE SKIP LOCKED` inside the txn
+     * means concurrent instances skip each other's locked rows instead of blocking, so no row is
+     * claimed twice; the token is what every later delete/settle is conditional on.
      */
     private claim;
+    private hold;
+    private release;
+    /** Re-stamp `claimed_at` on every row still claimed under a token this instance holds. */
+    private renewHeld;
+    /**
+     * Write a result row. A result already waiting for the same step (an earlier attempt's, not yet
+     * deleted by the engine) is REPLACED and its claim reset, never kept: `step_id` is stable across
+     * attempts, so keeping the old row would silently drop a retry's result.
+     */
     private insertResult;
     private sleep;
     /** Stop the pollers and wait for the current ticks to settle. Does not close the shared DataSource. */

package/dist/index.d.ts

@@ -74,10 +74,27 @@ interface DbTransportOptions {
     prefix?: string;
     /** Poll interval in ms when a queue is empty. Default 500. */
     pollMs?: number;
-    /** How long a claimed row is owned before it's reclaimable (crash recovery), in ms. Default 30_000. */
+    /**
+     * How long a claimed row is owned before it's reclaimable (crash recovery), in ms. Default 30_000.
+     * Every claim this instance holds is renewed every `leaseMs / 3` while it is waiting or running, so
+     * a step may run longer than `leaseMs`; only a crashed (or event-loop-blocked) instance loses it.
+     */
     leaseMs?: number;
-    /** Max rows claimed per poll. Default 10. */
+    /**
+     * Max rows claimed per poll. Default 10. The task loop claims only as many rows as it has free
+     * {@link concurrency} slots (capped by this); the results loop claims up to this many.
+     */
     batchSize?: number;
+    /**
+     * How many tasks this instance runs at once (worker side). Default 1. A row is claimed only when a
+     * slot is free to run it, so rows never wait claimed behind a slow task while a sibling sits idle.
+     */
+    concurrency?: number;
+    /**
+     * Where a transport failure is reported: a failing poll, a throwing result handler (the result is
+     * re-delivered after the lease), a lost claim. Default `console.error`.
+     */
+    onError?: (err: unknown) => void;
     /** Create the two tables on first use if missing. Default true. */
     autoCreate?: boolean;
     /** Identifies this instance in `claimed_by` (for debugging). Defaults to a random id. */
@@ -104,6 +121,8 @@ declare class DbTransport implements Transport {
     private readonly pollMs;
     private readonly leaseMs;
     private readonly batchSize;
+    private readonly concurrency;
+    private readonly onError;
     private readonly autoCreate;
     private readonly instanceId;
     private readonly isPg;
@@ -112,12 +131,24 @@ declare class DbTransport implements Transport {
     private schemaReady?;
     private taskLoop?;
     private resultLoop?;
+    /** Tasks running on this instance (at most `concurrency`). */
+    private readonly runningTasks;
+    /** Claim tokens this instance holds, by table — every one is renewed on `renewTimer`. */
+    private readonly held;
+    private renewTimer?;
+    private renewal?;
     constructor(options: DbTransportOptions);
     /** Positional placeholder for param `i` (1-based): `$i` on Postgres, `?` elsewhere. */
     private ph;
     private q;
     private now;
     private ensureSchema;
+    /**
+     * Run one `CREATE … IF NOT EXISTS`. Two instances booting on a fresh database race it, and Postgres
+     * can reject the loser with a unique violation on its catalog even with `IF NOT EXISTS`; the
+     * statement is simply re-run, by which point the table exists and it is a no-op.
+     */
+    private createIfMissing;
     private createTables;
     dispatch(task: RemoteTask): Promise<void>;
     handle(name: string, fn: StepHandler): void;
@@ -125,16 +156,47 @@ declare class DbTransport implements Transport {
     onHeartbeat(_handler: (beat: Heartbeat) => Promise<void>): void;
     /** Run `tick` repeatedly; sleep `pollMs` when it reports an empty queue. Stops on `close()`. */
     private loop;
-    /** Claim a batch of tasks (FOR UPDATE SKIP LOCKED), then run each outside the lock. */
+    /**
+     * One task-loop round: claim as many rows as there are free slots (never more — a claimed row that
+     * isn't running is one an idle sibling can't run), and start each. With every slot busy, wait for
+     * one to free instead of polling.
+     */
     private drainTasks;
-    /** Claim a batch of results, deliver each to the engine, then delete it. */
+    /**
+     * Run one claimed task and settle it — only while this instance still holds the claim: the claim is
+     * re-checked before running, and the task row is deleted and its result written in ONE transaction,
+     * conditional on the claim token, so an instance whose claim was taken over neither deletes the new
+     * holder's row nor publishes a second result.
+     */
+    private runTask;
+    /** Whether the claim on `stepId` is still `token`'s (re-stamping it if so). */
+    private stillHolds;
+    /** Delete the task row and publish its result in ONE transaction, only while `token` holds it. */
+    private settleTask;
+    /**
+     * Claim a batch of results, deliver each to the engine, and delete it — only after its handler ran
+     * (at-least-once), and only while this round still holds the claim (a newer result for the same
+     * step that replaced the row resets the claim, so it is delivered next instead of deleted). The
+     * batch's claim is renewed until it is done. A throwing handler is reported and its row left for
+     * re-delivery after the lease; the rest of the batch continues.
+     */
     private drainResults;
     /**
-     * Atomically claim up to `batchSize` un-leased rows matching `where` and stamp them with this
-     * instance's lease. `SELECT … FOR UPDATE SKIP LOCKED` inside the txn means concurrent instances
-     * skip each other's locked rows instead of blocking, so no row is claimed twice.
+     * Atomically claim up to `limit` un-leased rows matching `where` and stamp them with a claim token
+     * unique to this round (`<instanceId>:<uuid>`). `SELECT … FOR UPDATE SKIP LOCKED` inside the txn
+     * means concurrent instances skip each other's locked rows instead of blocking, so no row is
+     * claimed twice; the token is what every later delete/settle is conditional on.
      */
     private claim;
+    private hold;
+    private release;
+    /** Re-stamp `claimed_at` on every row still claimed under a token this instance holds. */
+    private renewHeld;
+    /**
+     * Write a result row. A result already waiting for the same step (an earlier attempt's, not yet
+     * deleted by the engine) is REPLACED and its claim reset, never kept: `step_id` is stable across
+     * attempts, so keeping the old row would silently drop a retry's result.
+     */
     private insertResult;
     private sleep;
     /** Stop the pollers and wait for the current ticks to settle. Does not close the shared DataSource. */

package/dist/index.js

@@ -2,6 +2,7 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/db-transport.ts
+import { randomUUID } from "node:crypto";
 import { runStepHandler } from "@dudousxd/nestjs-durable-core";
 
 // src/executors.ts
@@ -44,6 +45,10 @@ function mikroOrmExecutor(em) {
 __name(mikroOrmExecutor, "mikroOrmExecutor");
 
 // src/db-transport.ts
+function numberOption(value, fallback, min) {
+  return value !== void 0 && Number.isFinite(value) && value >= min ? value : fallback;
+}
+__name(numberOption, "numberOption");
 var DbTransport = class {
   static {
     __name(this, "DbTransport");
@@ -55,6 +60,8 @@ var DbTransport = class {
   pollMs;
   leaseMs;
   batchSize;
+  concurrency;
+  onError;
   autoCreate;
   instanceId;
   isPg;
@@ -63,17 +70,25 @@ var DbTransport = class {
   schemaReady;
   taskLoop;
   resultLoop;
+  /** Tasks running on this instance (at most `concurrency`). */
+  runningTasks = /* @__PURE__ */ new Set();
+  /** Claim tokens this instance holds, by table — every one is renewed on `renewTimer`. */
+  held = /* @__PURE__ */ new Map();
+  renewTimer;
+  renewal;
   constructor(options) {
     this.exec = options.executor;
     this.group = options.group;
     const prefix = options.prefix ?? "durable";
     this.tasksTable = `${prefix}_transport_tasks`;
     this.resultsTable = `${prefix}_transport_results`;
-    this.pollMs = options.pollMs ?? 500;
-    this.leaseMs = options.leaseMs ?? 3e4;
-    this.batchSize = options.batchSize ?? 10;
+    this.pollMs = numberOption(options.pollMs, 500, 0);
+    this.leaseMs = numberOption(options.leaseMs, 3e4, 1);
+    this.batchSize = Math.floor(numberOption(options.batchSize, 10, 1));
+    this.concurrency = Math.floor(numberOption(options.concurrency, 1, 1));
+    this.onError = options.onError ?? ((err) => console.error("[DbTransport]", err));
     this.autoCreate = options.autoCreate ?? true;
-    this.instanceId = options.instanceId ?? `db-${Math.floor(Date.now()).toString(36)}`;
+    this.instanceId = options.instanceId ?? `db-${randomUUID()}`;
     this.isPg = this.exec.dialect === "postgres";
   }
   // ── dialect helpers ──────────────────────────────────────────────────────────────────────────
@@ -89,16 +104,33 @@ var DbTransport = class {
   }
   // ── schema ───────────────────────────────────────────────────────────────────────────────────
   ensureSchema() {
-    if (!this.schemaReady) this.schemaReady = this.createTables();
+    if (!this.schemaReady) {
+      this.schemaReady = this.createTables().catch((err) => {
+        this.schemaReady = void 0;
+        throw err;
+      });
+    }
     return this.schemaReady;
   }
+  /**
+  * Run one `CREATE … IF NOT EXISTS`. Two instances booting on a fresh database race it, and Postgres
+  * can reject the loser with a unique violation on its catalog even with `IF NOT EXISTS`; the
+  * statement is simply re-run, by which point the table exists and it is a no-op.
+  */
+  async createIfMissing(sql) {
+    try {
+      await this.exec.query(sql);
+    } catch {
+      await this.exec.query(sql);
+    }
+  }
   async createTables() {
     if (!this.autoCreate) return;
     const str = "varchar(191)";
     const txt = this.isPg ? "text" : "longtext";
     const tasks = this.q(this.tasksTable);
     const results = this.q(this.resultsTable);
-    await this.exec.query(`CREATE TABLE IF NOT EXISTS ${tasks} (
+    await this.createIfMissing(`CREATE TABLE IF NOT EXISTS ${tasks} (
         ${this.q("step_id")} ${str} PRIMARY KEY,
         ${this.q("run_id")} ${str} NOT NULL,
         ${this.q("seq")} integer NOT NULL,
@@ -111,7 +143,7 @@ var DbTransport = class {
         ${this.q("claimed_at")} bigint,
         ${this.q("created_at")} bigint NOT NULL
       )`);
-    await this.exec.query(`CREATE TABLE IF NOT EXISTS ${results} (
+    await this.createIfMissing(`CREATE TABLE IF NOT EXISTS ${results} (
         ${this.q("step_id")} ${str} PRIMARY KEY,
         ${this.q("run_id")} ${str} NOT NULL,
         ${this.q("seq")} integer NOT NULL,
@@ -169,23 +201,56 @@ var DbTransport = class {
   // ── polling ──────────────────────────────────────────────────────────────────────────────────
   /** Run `tick` repeatedly; sleep `pollMs` when it reports an empty queue. Stops on `close()`. */
   async loop(tick) {
-    await this.ensureSchema();
     while (this.running) {
       let processed = 0;
       try {
+        await this.ensureSchema();
         processed = await tick();
       } catch (err) {
-        if (this.running) console.error("[DbTransport] poll failed", err);
+        if (this.running) this.onError(err);
       }
-      if (processed === 0) await this.sleep(this.pollMs);
+      if (processed === 0 && this.running) await this.sleep(this.pollMs);
     }
   }
-  /** Claim a batch of tasks (FOR UPDATE SKIP LOCKED), then run each outside the lock. */
+  /**
+  * One task-loop round: claim as many rows as there are free slots (never more — a claimed row that
+  * isn't running is one an idle sibling can't run), and start each. With every slot busy, wait for
+  * one to free instead of polling.
+  */
   async drainTasks(group) {
-    const claimed = await this.claim(this.tasksTable, `${this.q("grp")} = ${this.ph(1)}`, [
+    const free = this.concurrency - this.runningTasks.size;
+    if (free <= 0) {
+      await Promise.race(this.runningTasks);
+      return 1;
+    }
+    const { rows, token } = await this.claim(this.tasksTable, Math.min(free, this.batchSize), `${this.q("grp")} = ${this.ph(1)}`, [
       group
     ]);
-    for (const row of claimed) {
+    if (rows.length === 0) return 0;
+    this.hold(this.tasksTable, token);
+    let left = rows.length;
+    for (const row of rows) {
+      const run = this.runTask(row, group, token).finally(() => {
+        this.runningTasks.delete(run);
+        left -= 1;
+        if (left === 0) this.release(this.tasksTable, token);
+      });
+      this.runningTasks.add(run);
+    }
+    return rows.length;
+  }
+  /**
+  * Run one claimed task and settle it — only while this instance still holds the claim: the claim is
+  * re-checked before running, and the task row is deleted and its result written in ONE transaction,
+  * conditional on the claim token, so an instance whose claim was taken over neither deletes the new
+  * holder's row nor publishes a second result.
+  */
+  async runTask(row, group, token) {
+    try {
+      if (!await this.stillHolds(row.step_id, token)) {
+        this.onError(new Error(`[DbTransport] lost the claim on task ${row.step_id} before running it \u2014 another instance took it over; not running it here`));
+        return;
+      }
       const task = {
         runId: row.run_id,
         seq: Number(row.seq),
@@ -196,62 +261,169 @@ var DbTransport = class {
         attempt: Number(row.attempt)
       };
       const result = await runStepHandler(task, this.handlers.get(task.name));
-      await this.insertResult(result);
-      await this.exec.query(`DELETE FROM ${this.q(this.tasksTable)} WHERE ${this.q("step_id")} = ${this.ph(1)}`, [
-        task.stepId
-      ]);
+      if (!await this.settleTask(task.stepId, token, result)) {
+        this.onError(new Error(`[DbTransport] lost the claim on task ${task.stepId} while running it (this instance went silent past leaseMs) \u2014 another instance took it over and may run it too; this run's result was dropped. Raise leaseMs if steps block the event loop`));
+      }
+    } catch (err) {
+      this.onError(err);
     }
-    return claimed.length;
   }
-  /** Claim a batch of results, deliver each to the engine, then delete it. */
-  async drainResults(handler) {
-    const claimed = await this.claim(this.resultsTable, "1 = 1", []);
-    for (const row of claimed) {
-      const result = {
-        runId: row.run_id,
-        seq: Number(row.seq),
-        stepId: row.step_id,
-        status: row.status,
-        output: row.output == null ? void 0 : JSON.parse(row.output),
-        error: row.error == null ? void 0 : JSON.parse(row.error),
-        startedAt: row.started_at == null ? void 0 : Number(row.started_at)
-      };
-      await handler(result);
-      await this.exec.query(`DELETE FROM ${this.q(this.resultsTable)} WHERE ${this.q("step_id")} = ${this.ph(1)}`, [
-        result.stepId
+  /** Whether the claim on `stepId` is still `token`'s (re-stamping it if so). */
+  async stillHolds(stepId, token) {
+    const t = this.q(this.tasksTable);
+    const rows = await this.exec.transaction(async (tx) => {
+      const held = await tx.query(`SELECT ${this.q("step_id")} FROM ${t} WHERE ${this.q("step_id")} = ${this.ph(1)} AND ${this.q("claimed_by")} = ${this.ph(2)} FOR UPDATE`, [
+        stepId,
+        token
+      ]);
+      if (held.length > 0) {
+        await tx.query(`UPDATE ${t} SET ${this.q("claimed_at")} = ${this.ph(1)} WHERE ${this.q("step_id")} = ${this.ph(2)} AND ${this.q("claimed_by")} = ${this.ph(3)}`, [
+          this.now(),
+          stepId,
+          token
+        ]);
+      }
+      return held;
+    });
+    return rows.length > 0;
+  }
+  /** Delete the task row and publish its result in ONE transaction, only while `token` holds it. */
+  async settleTask(stepId, token, result) {
+    const t = this.q(this.tasksTable);
+    return this.exec.transaction(async (tx) => {
+      const held = await tx.query(`SELECT ${this.q("step_id")} FROM ${t} WHERE ${this.q("step_id")} = ${this.ph(1)} AND ${this.q("claimed_by")} = ${this.ph(2)} FOR UPDATE`, [
+        stepId,
+        token
       ]);
+      if (held.length === 0) return false;
+      await tx.query(`DELETE FROM ${t} WHERE ${this.q("step_id")} = ${this.ph(1)} AND ${this.q("claimed_by")} = ${this.ph(2)}`, [
+        stepId,
+        token
+      ]);
+      await this.insertResult(result, tx);
+      return true;
+    });
+  }
+  /**
+  * Claim a batch of results, deliver each to the engine, and delete it — only after its handler ran
+  * (at-least-once), and only while this round still holds the claim (a newer result for the same
+  * step that replaced the row resets the claim, so it is delivered next instead of deleted). The
+  * batch's claim is renewed until it is done. A throwing handler is reported and its row left for
+  * re-delivery after the lease; the rest of the batch continues.
+  */
+  async drainResults(handler) {
+    const { rows, token } = await this.claim(this.resultsTable, this.batchSize, "1 = 1", []);
+    if (rows.length === 0) return 0;
+    this.hold(this.resultsTable, token);
+    try {
+      for (const row of rows) {
+        if (!this.running) break;
+        try {
+          const result = {
+            runId: row.run_id,
+            seq: Number(row.seq),
+            stepId: row.step_id,
+            status: row.status,
+            output: row.output == null ? void 0 : JSON.parse(row.output),
+            error: row.error == null ? void 0 : JSON.parse(row.error),
+            startedAt: row.started_at == null ? void 0 : Number(row.started_at)
+          };
+          await handler(result);
+          await this.exec.query(`DELETE FROM ${this.q(this.resultsTable)} WHERE ${this.q("step_id")} = ${this.ph(1)} AND ${this.q("claimed_by")} = ${this.ph(2)}`, [
+            row.step_id,
+            token
+          ]);
+        } catch (err) {
+          this.onError(err);
+        }
+      }
+    } finally {
+      this.release(this.resultsTable, token);
     }
-    return claimed.length;
+    return rows.length;
   }
   /**
-  * Atomically claim up to `batchSize` un-leased rows matching `where` and stamp them with this
-  * instance's lease. `SELECT … FOR UPDATE SKIP LOCKED` inside the txn means concurrent instances
-  * skip each other's locked rows instead of blocking, so no row is claimed twice.
+  * Atomically claim up to `limit` un-leased rows matching `where` and stamp them with a claim token
+  * unique to this round (`<instanceId>:<uuid>`). `SELECT … FOR UPDATE SKIP LOCKED` inside the txn
+  * means concurrent instances skip each other's locked rows instead of blocking, so no row is
+  * claimed twice; the token is what every later delete/settle is conditional on.
   */
-  async claim(table, where, whereParams) {
+  async claim(table, limit, where, whereParams) {
     const t = this.q(table);
     const staleBefore = this.now() - this.leaseMs;
-    return this.exec.transaction(async (tx) => {
+    const token = `${this.instanceId}:${randomUUID()}`;
+    const rows = await this.exec.transaction(async (tx) => {
       const leaseClause = `(${this.q("claimed_at")} IS NULL OR ${this.q("claimed_at")} < ${this.ph(whereParams.length + 1)})`;
-      const rows = await tx.query(`SELECT * FROM ${t} WHERE ${where} AND ${leaseClause}
-         ORDER BY ${this.q("created_at")} ASC LIMIT ${this.batchSize} FOR UPDATE SKIP LOCKED`, [
+      const found = await tx.query(`SELECT * FROM ${t} WHERE ${where} AND ${leaseClause}
+         ORDER BY ${this.q("created_at")} ASC LIMIT ${Math.max(1, Math.floor(limit))} FOR UPDATE SKIP LOCKED`, [
         ...whereParams,
         staleBefore
       ]);
-      if (rows.length > 0) {
-        const ids = rows.map((r) => r.step_id);
+      if (found.length > 0) {
+        const ids = found.map((r) => r.step_id);
         const placeholders = ids.map((_, i) => this.ph(i + 3)).join(", ");
         await tx.query(`UPDATE ${t} SET ${this.q("claimed_by")} = ${this.ph(1)}, ${this.q("claimed_at")} = ${this.ph(2)}
            WHERE ${this.q("step_id")} IN (${placeholders})`, [
-          this.instanceId,
+          token,
           this.now(),
           ...ids
         ]);
       }
-      return rows;
+      return found;
     });
+    return {
+      rows,
+      token
+    };
+  }
+  // ── claim renewal: every claim held, not only the row being run ─────────────────────────────
+  hold(table, token) {
+    let tokens = this.held.get(table);
+    if (!tokens) {
+      tokens = /* @__PURE__ */ new Set();
+      this.held.set(table, tokens);
+    }
+    tokens.add(token);
+    if (this.renewTimer) return;
+    const intervalMs = Math.max(10, Math.floor(this.leaseMs / 3));
+    this.renewTimer = setInterval(() => {
+      if (this.renewal) return;
+      const round = this.renewHeld().catch((err) => this.onError(err)).finally(() => {
+        if (this.renewal === round) this.renewal = void 0;
+      });
+      this.renewal = round;
+    }, intervalMs);
+    this.renewTimer.unref?.();
+  }
+  release(table, token) {
+    const tokens = this.held.get(table);
+    tokens?.delete(token);
+    if (tokens?.size === 0) this.held.delete(table);
+    if (this.held.size === 0 && this.renewTimer) {
+      clearInterval(this.renewTimer);
+      this.renewTimer = void 0;
+    }
+  }
+  /** Re-stamp `claimed_at` on every row still claimed under a token this instance holds. */
+  async renewHeld() {
+    for (const [table, tokens] of this.held) {
+      if (tokens.size === 0) continue;
+      const list = [
+        ...tokens
+      ];
+      const placeholders = list.map((_, i) => this.ph(i + 2)).join(", ");
+      await this.exec.query(`UPDATE ${this.q(table)} SET ${this.q("claimed_at")} = ${this.ph(1)} WHERE ${this.q("claimed_by")} IN (${placeholders})`, [
+        this.now(),
+        ...list
+      ]);
+    }
   }
-  async insertResult(result) {
+  /**
+  * Write a result row. A result already waiting for the same step (an earlier attempt's, not yet
+  * deleted by the engine) is REPLACED and its claim reset, never kept: `step_id` is stable across
+  * attempts, so keeping the old row would silently drop a retry's result.
+  */
+  async insertResult(result, tx = this.exec) {
     const t = this.q(this.resultsTable);
     const cols = [
       "step_id",
@@ -263,9 +435,26 @@ var DbTransport = class {
       "started_at",
       "created_at"
     ];
-    const head = this.isPg ? `INSERT INTO ${t} (...) ON CONFLICT (${this.q("step_id")}) DO NOTHING` : `INSERT IGNORE INTO ${t} (...)`;
-    const sql = head.replace("(...)", `(${cols.map((c) => this.q(c)).join(", ")}) VALUES (${cols.map((_, i) => this.ph(i + 1)).join(", ")})`);
-    await this.exec.query(sql, [
+    const replace = [
+      "run_id",
+      "seq",
+      "status",
+      "output",
+      "error",
+      "started_at",
+      "created_at"
+    ];
+    const values = `(${cols.map((c) => this.q(c)).join(", ")}) VALUES (${cols.map((_, i) => this.ph(i + 1)).join(", ")})`;
+    const sql = this.isPg ? `INSERT INTO ${t} ${values} ON CONFLICT (${this.q("step_id")}) DO UPDATE SET ${[
+      ...replace.map((c) => `${this.q(c)} = EXCLUDED.${this.q(c)}`),
+      `${this.q("claimed_by")} = NULL`,
+      `${this.q("claimed_at")} = NULL`
+    ].join(", ")}` : `INSERT INTO ${t} ${values} ON DUPLICATE KEY UPDATE ${[
+      ...replace.map((c) => `${this.q(c)} = VALUES(${this.q(c)})`),
+      `${this.q("claimed_by")} = NULL`,
+      `${this.q("claimed_at")} = NULL`
+    ].join(", ")}`;
+    await tx.query(sql, [
       result.stepId,
       result.runId,
       result.seq,
@@ -286,6 +475,12 @@ var DbTransport = class {
       this.taskLoop,
       this.resultLoop
     ]);
+    await Promise.allSettled([
+      ...this.runningTasks
+    ]);
+    if (this.renewTimer) clearInterval(this.renewTimer);
+    this.renewTimer = void 0;
+    await this.renewal;
   }
 };
 export {