@gobing-ai/ts-db 0.4.59 → 0.4.60

package/README.md

@@ -233,21 +233,26 @@ const queue = new QueueJobDao(adapter);
 
 // Enqueue — maxRetries is a total attempt budget, not retries after the first:
 // 5 means up to 5 attempts, and `maxRetries: 1` runs the job once with no retry.
-const jobId = await queue.enqueue('send-email', { to: 'user@test.com' }, { maxRetries: 5 });
+// timeoutMs is the per-job execution policy: a positive ms deadline, or explicit
+// `null` = unlimited (omitted = inherit the consumer default).
+const jobId = await queue.enqueue('send-email', { to: 'user@test.com' }, { maxRetries: 5, timeoutMs: 60_000 });
 
-// Consumer: claim ready jobs atomically
-const jobs = await queue.claimReady(10);
+// Consumer: claim ready jobs atomically. claimReady leases each job (mints an
+// attempt token); renew the lease while the handler runs, then ack with the
+// token — fenced acks are ignored if ownership was lost mid-run.
+const jobs = await queue.claimReady(10, { leaseMs: 30_000 });
+await queue.renewLease(jobs[0].id, jobs[0].attemptToken, 30_000);
 
 for (const job of jobs) {
     try {
         await processJob(job);
-        await queue.markCompleted(job.id);
+        await queue.markCompleted(job.id, job.attemptToken);
     } catch (error) {
         if (job.attempts >= job.maxRetries) {
-            await queue.markFailed(job.id, job.attempts + 1, String(error));
+            await queue.markFailed(job.id, job.attempts + 1, String(error), job.attemptToken);
         } else {
             const retryAt = Date.now() + Math.pow(2, job.attempts) * 1000;
-            await queue.markForRetry(job.id, job.attempts + 1, String(error), retryAt);
+            await queue.markForRetry(job.id, job.attempts + 1, String(error), retryAt, job.attemptToken);
         }
     }
 }

package/dist/embedded-migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedded-migrations.d.ts","sourceRoot":"","sources":["../src/embedded-migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,iBAAiB,EA0BjD,CAAC"}
+{"version":3,"file":"embedded-migrations.d.ts","sourceRoot":"","sources":["../src/embedded-migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,iBAAiB,EA+BjD,CAAC"}

package/dist/embedded-migrations.js

@@ -33,4 +33,9 @@ export const embeddedMigrations = [
         sql: 'CREATE INDEX `idx_inbox_messages_to_status` ON `inbox_messages` (`to_id`,`status`);',
         hash: '3c00f1bce4f569e442f3142df31ff478d6c9b3d460824d46575f50a324bfae61',
     },
+    {
+        tag: '0005_queue_attempt_ownership',
+        sql: 'ALTER TABLE `queue_jobs` ADD `timeout_ms` integer;\nALTER TABLE `queue_jobs` ADD `timeout_unlimited` integer DEFAULT 0 NOT NULL;\nALTER TABLE `queue_jobs` ADD `attempt_token` text;\nALTER TABLE `queue_jobs` ADD `lease_expires_at` integer;',
+        hash: 'f6a4eaf11eee838f424515e57eca3a46539260bb2fb5b0b112870ca5ed38d040',
+    },
 ];

package/dist/queue-job-dao.d.ts

@@ -10,6 +10,25 @@ export interface QueueStats {
     completed: number;
     failed: number;
 }
+/** Options for enqueuing a job: retry policy, delay, TTL, and execution policy. */
+export interface QueueEnqueueOptions {
+    /** Total attempts allowed (default 3). */
+    maxRetries?: number;
+    delay?: number;
+    ttlMs?: number;
+    /**
+     * Job execution policy persisted with the row: a positive integer ms
+     * deadline, explicit `null` = unlimited (disables this job's deadline),
+     * omitted = no job-level decision (consumers apply their own default).
+     * Invalid explicit values are rejected before the row is created.
+     */
+    timeoutMs?: number | null;
+}
+/** Options for an atomic claim that takes lease ownership. */
+export interface QueueClaimOptions {
+    /** Ownership lease length in ms; omitted claims keep the legacy recovery path. */
+    leaseMs?: number;
+}
 /**
  * Row type inferred from the queue_jobs Drizzle schema.
  */
@@ -25,22 +44,14 @@ export declare class QueueJobDao extends EntityDao<typeof queueJobs, typeof queu
     /**
      * Enqueue a new job.
      */
-    enqueue(type: string, payload: unknown, options?: {
-        maxRetries?: number;
-        delay?: number;
-        ttlMs?: number;
-    }): Promise<string>;
+    enqueue(type: string, payload: unknown, options?: QueueEnqueueOptions): Promise<string>;
     /**
      * Enqueue multiple jobs in a single batch.
      */
     enqueueBatch(jobs: Array<{
         type: string;
         payload: unknown;
-    } & {
-        maxRetries?: number;
-        delay?: number;
-        ttlMs?: number;
-    }>): Promise<string[]>;
+    } & QueueEnqueueOptions>): Promise<string[]>;
     /**
      * Get a job by ID.
      */
@@ -58,30 +69,56 @@ export declare class QueueJobDao extends EntityDao<typeof queueJobs, typeof queu
      */
     findPending(batchSize: number): Promise<QueueJobRecord[]>;
     /**
-     * Atomically claim ready pending jobs for processing.
+     * Atomically claim ready pending jobs — and recover expired leased
+     * attempts — for processing.
      *
      * The update and selection happen in one SQLite statement so competing
      * consumers only receive rows they actually transitioned to processing.
+     * When `options.leaseMs` is provided the claimed row takes an ownership
+     * lease and a fresh attempt token; the token fences mutations and keeps
+     * rival consumers from re-claiming the live attempt until the lease
+     * expires. Expired leased rows (worker loss) are recovered here with a
+     * fresh token — not by the age-based `resetStuckJobs` sweep, which skips
+     * token-carrying rows. Claims WITHOUT `leaseMs` mint no ownership markers
+     * (and clear any stale ones on reclaim) so the row keeps the legacy
+     * recovery path through the age sweep — a token without a lease would
+     * make the row unrecoverable by both paths.
      */
-    claimReady(batchSize: number): Promise<QueueJobRecord[]>;
+    claimReady(batchSize: number, options?: QueueClaimOptions): Promise<QueueJobRecord[]>;
     /**
      * Mark jobs as processing.
      */
     markProcessing(ids: string[]): Promise<void>;
     /**
      * Mark a job as completed.
+     *
+     * When `attemptToken` is supplied the mutation is fenced: it applies only
+     * if the row is still owned by that attempt. Returns whether it applied.
      */
-    markCompleted(id: string): Promise<void>;
+    markCompleted(id: string, attemptToken?: string): Promise<boolean>;
     /**
-     * Mark a job as failed.
+     * Mark a job as failed, fenced by fresh attempt ownership when supplied.
      */
-    markFailed(id: string, attempts: number, error: string): Promise<void>;
+    markFailed(id: string, attempts: number, error: string, attemptToken?: string): Promise<boolean>;
     /**
-     * Reset a job to pending for retry with backoff.
+     * Reset a job to pending for retry with backoff, fenced by fresh attempt
+     * ownership when supplied.
      */
-    markForRetry(id: string, attempts: number, errorMessage: string, nextRetryAt: number): Promise<void>;
+    markForRetry(id: string, attempts: number, errorMessage: string, nextRetryAt: number, attemptToken?: string): Promise<boolean>;
+    /**
+     * Extend the ownership lease of a claimed attempt.
+     *
+     * Applies only while the row is still owned by `attemptToken`; a `false`
+     * return means ownership was lost (expired and reclaimed by another
+     * consumer) and the caller must abort and fence its acknowledgements.
+     */
+    renewLease(id: string, attemptToken: string, leaseMs: number): Promise<boolean>;
     /**
      * Reset stuck processing jobs (processing beyond visibility timeout).
+     *
+     * Age-based legacy recovery only: rows carrying an attempt token are
+     * lease-owned and recover exclusively through their expired lease in
+     * `claimReady`, never by processing age.
      */
     resetStuckJobs(visibilityTimeout: number): Promise<number>;
     /**

package/dist/queue-job-dao.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue-job-dao.d.ts","sourceRoot":"","sources":["../src/queue-job-dao.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAQ3C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAE3D;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,SAAS,CAAC,OAAO,SAAS,EAAE,OAAO,SAAS,CAAC,EAAE,CAAC;gBACjE,OAAO,EAAE,SAAS;IAI9B;;OAEG;IACG,OAAO,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAClE,OAAO,CAAC,MAAM,CAAC;IAkBlB;;OAEG;IACG,YAAY,CACd,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAC1G,OAAO,CAAC,MAAM,EAAE,CAAC;IA+BpB;;OAEG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAI9D;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAoBrC;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASpD;;OAEG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAe/D;;;;;OAKG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAyB9D;;OAEG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlD;;OAEG;IACG,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9C;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5E;;OAEG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1G;;OAEG;IACG,cAAc,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAahE;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;CAkB3C"}
+{"version":3,"file":"queue-job-dao.d.ts","sourceRoot":"","sources":["../src/queue-job-dao.ts"],"names":[],"mappings":"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"}

package/dist/queue-job-dao.js

@@ -1,6 +1,24 @@
 import { and, eq, inArray, sql } from 'drizzle-orm';
 import { EntityDao } from './entity-dao.js';
 import { queueJobs } from './schema/queue-jobs.js';
+/**
+ * Validate the persisted execution-policy leaf value. The scope-resolution
+ * chain (inherit/unlimited/finite) lives in the consumer packages; the DAO
+ * only stores an already-resolved job option and refuses invalid ones.
+ */
+function assertValidTimeoutMs(value) {
+    if (value === undefined || value === null)
+        return;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        throw new RangeError(`enqueue timeoutMs must be a positive integer or null; received ${String(value)}`);
+    }
+}
+/** Persisted execution-policy columns derived from a validated `timeoutMs` option. */
+function timeoutColumns(timeoutMs) {
+    if (timeoutMs === undefined)
+        return {};
+    return timeoutMs === null ? { timeoutUnlimited: 1 } : { timeoutMs };
+}
 /**
  * DAO for the queue_jobs table.
  *
@@ -15,6 +33,7 @@ export class QueueJobDao extends EntityDao {
      * Enqueue a new job.
      */
     async enqueue(type, payload, options) {
+        assertValidTimeoutMs(options?.timeoutMs);
         const now = this.now();
         const id = crypto.randomUUID();
         await this.create({
@@ -26,6 +45,7 @@ export class QueueJobDao extends EntityDao {
             maxRetries: options?.maxRetries ?? 3,
             nextRetryAt: options?.delay !== undefined ? now + options.delay : now,
             ...(options?.ttlMs !== undefined ? { expiresAt: now + options.ttlMs } : {}),
+            ...timeoutColumns(options?.timeoutMs),
         });
         return id;
     }
@@ -33,6 +53,9 @@ export class QueueJobDao extends EntityDao {
      * Enqueue multiple jobs in a single batch.
      */
     async enqueueBatch(jobs) {
+        for (const job of jobs) {
+            assertValidTimeoutMs(job.timeoutMs);
+        }
         const now = this.now();
         const ids = [];
         const rows = jobs.map((job) => {
@@ -47,6 +70,7 @@ export class QueueJobDao extends EntityDao {
                 maxRetries: job.maxRetries ?? 3,
                 nextRetryAt: job.delay !== undefined ? now + job.delay : now,
                 ...(job.ttlMs !== undefined ? { expiresAt: now + job.ttlMs } : {}),
+                ...timeoutColumns(job.timeoutMs),
             };
         });
         if (rows.length > 0) {
@@ -108,28 +132,55 @@ export class QueueJobDao extends EntityDao {
         return result;
     }
     /**
-     * Atomically claim ready pending jobs for processing.
+     * Atomically claim ready pending jobs — and recover expired leased
+     * attempts — for processing.
      *
      * The update and selection happen in one SQLite statement so competing
      * consumers only receive rows they actually transitioned to processing.
+     * When `options.leaseMs` is provided the claimed row takes an ownership
+     * lease and a fresh attempt token; the token fences mutations and keeps
+     * rival consumers from re-claiming the live attempt until the lease
+     * expires. Expired leased rows (worker loss) are recovered here with a
+     * fresh token — not by the age-based `resetStuckJobs` sweep, which skips
+     * token-carrying rows. Claims WITHOUT `leaseMs` mint no ownership markers
+     * (and clear any stale ones on reclaim) so the row keeps the legacy
+     * recovery path through the age sweep — a token without a lease would
+     * make the row unrecoverable by both paths.
      */
-    async claimReady(batchSize) {
+    async claimReady(batchSize, options) {
         const limit = Math.floor(batchSize);
         if (limit <= 0)
             return [];
         const now = this.now();
+        const leaseMs = options?.leaseMs;
+        const leased = leaseMs !== undefined;
+        const leaseExpiresAt = leased ? now + leaseMs : null;
+        const reclaimable = sql `(
+            ${queueJobs.status} = 'pending'
+            AND (${queueJobs.nextRetryAt} IS NULL OR ${queueJobs.nextRetryAt} <= ${now})
+        ) OR (
+            ${queueJobs.status} = 'processing'
+            AND ${queueJobs.attemptToken} IS NOT NULL
+            AND ${queueJobs.leaseExpiresAt} IS NOT NULL
+            AND ${queueJobs.leaseExpiresAt} <= ${now}
+        )`;
         const result = await this.db
             .update(queueJobs)
-            .set({ status: 'processing', processingAt: now, updatedAt: now })
+            .set({
+            status: 'processing',
+            processingAt: now,
+            updatedAt: now,
+            attemptToken: leased ? sql `lower(hex(randomblob(16)))` : null,
+            leaseExpiresAt,
+        })
             .where(sql `${queueJobs.id} IN (
                     SELECT id
                     FROM ${queueJobs}
-                    WHERE status = 'pending'
-                      AND (next_retry_at IS NULL OR next_retry_at <= ${now})
+                    WHERE ${reclaimable}
                     ORDER BY created_at
                     LIMIT ${limit}
                 )
-                AND ${queueJobs.status} = 'pending'`)
+                AND ${reclaimable}`)
             .returning();
         return result;
     }
@@ -147,45 +198,99 @@ export class QueueJobDao extends EntityDao {
     }
     /**
      * Mark a job as completed.
+     *
+     * When `attemptToken` is supplied the mutation is fenced: it applies only
+     * if the row is still owned by that attempt. Returns whether it applied.
      */
-    async markCompleted(id) {
-        await this.update(id, {
+    async markCompleted(id, attemptToken) {
+        const where = attemptToken === undefined
+            ? eq(queueJobs.id, id)
+            : and(eq(queueJobs.id, id), eq(queueJobs.attemptToken, attemptToken));
+        const result = await this.db
+            .update(queueJobs)
+            .set({
             status: 'completed',
             processingAt: null,
-        });
+            attemptToken: null,
+            leaseExpiresAt: null,
+            updatedAt: this.now(),
+        })
+            .where(where);
+        return result.changes === 1;
     }
     /**
-     * Mark a job as failed.
+     * Mark a job as failed, fenced by fresh attempt ownership when supplied.
      */
-    async markFailed(id, attempts, error) {
-        await this.update(id, {
+    async markFailed(id, attempts, error, attemptToken) {
+        const where = attemptToken === undefined
+            ? eq(queueJobs.id, id)
+            : and(eq(queueJobs.id, id), eq(queueJobs.attemptToken, attemptToken));
+        const result = await this.db
+            .update(queueJobs)
+            .set({
             status: 'failed',
             attempts,
             lastError: error,
             processingAt: null,
-        });
+            attemptToken: null,
+            leaseExpiresAt: null,
+            updatedAt: this.now(),
+        })
+            .where(where);
+        return result.changes === 1;
     }
     /**
-     * Reset a job to pending for retry with backoff.
+     * Reset a job to pending for retry with backoff, fenced by fresh attempt
+     * ownership when supplied.
      */
-    async markForRetry(id, attempts, errorMessage, nextRetryAt) {
-        await this.update(id, {
+    async markForRetry(id, attempts, errorMessage, nextRetryAt, attemptToken) {
+        const where = attemptToken === undefined
+            ? eq(queueJobs.id, id)
+            : and(eq(queueJobs.id, id), eq(queueJobs.attemptToken, attemptToken));
+        const result = await this.db
+            .update(queueJobs)
+            .set({
             status: 'pending',
             attempts,
             lastError: errorMessage,
             nextRetryAt,
             processingAt: null,
-        });
+            attemptToken: null,
+            leaseExpiresAt: null,
+            updatedAt: this.now(),
+        })
+            .where(where);
+        return result.changes === 1;
+    }
+    /**
+     * Extend the ownership lease of a claimed attempt.
+     *
+     * Applies only while the row is still owned by `attemptToken`; a `false`
+     * return means ownership was lost (expired and reclaimed by another
+     * consumer) and the caller must abort and fence its acknowledgements.
+     */
+    async renewLease(id, attemptToken, leaseMs) {
+        const now = this.now();
+        const result = await this.db
+            .update(queueJobs)
+            .set({ leaseExpiresAt: now + leaseMs, updatedAt: now })
+            .where(and(eq(queueJobs.id, id), eq(queueJobs.attemptToken, attemptToken), eq(queueJobs.status, 'processing')));
+        return result.changes === 1;
     }
     /**
      * Reset stuck processing jobs (processing beyond visibility timeout).
+     *
+     * Age-based legacy recovery only: rows carrying an attempt token are
+     * lease-owned and recover exclusively through their expired lease in
+     * `claimReady`, never by processing age.
      */
     async resetStuckJobs(visibilityTimeout) {
         const cutoff = this.now() - visibilityTimeout;
         const result = await this.db
             .update(queueJobs)
             .set({ status: 'pending', processingAt: null, updatedAt: this.now() })
-            .where(sql `${queueJobs.status} = 'processing' AND ${queueJobs.processingAt} IS NOT NULL AND ${queueJobs.processingAt} <= ${cutoff}`);
+            .where(sql `${queueJobs.status} = 'processing' AND ${queueJobs.processingAt} IS NOT NULL AND ${queueJobs.processingAt} <= ${cutoff}
+                AND ${queueJobs.attemptToken} IS NULL`);
         return result.changes;
     }
     /**

package/dist/schema/queue-jobs.d.ts

@@ -75,6 +75,76 @@ export declare const queueJobs: import("drizzle-orm/sqlite-core").SQLiteTableWit
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        timeoutMs: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "timeout_ms";
+            tableName: "queue_jobs";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timeoutUnlimited: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "timeout_unlimited";
+            tableName: "queue_jobs";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        attemptToken: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "attempt_token";
+            tableName: "queue_jobs";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        leaseExpiresAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "lease_expires_at";
+            tableName: "queue_jobs";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
             name: "created_at";
             tableName: "queue_jobs";

package/dist/schema/queue-jobs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue-jobs.d.ts","sourceRoot":"","sources":["../../src/schema/queue-jobs.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBrB,CAAC"}
+{"version":3,"file":"queue-jobs.d.ts","sourceRoot":"","sources":["../../src/schema/queue-jobs.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwBrB,CAAC"}

package/dist/schema/queue-jobs.js

@@ -15,4 +15,12 @@ export const queueJobs = sqliteTable('queue_jobs', {
     lastError: text('last_error'),
     processingAt: integer('processing_at'),
     expiresAt: integer('expires_at'),
+    /** Persisted job execution deadline (ms). `null` = not finite; see timeoutUnlimited. */
+    timeoutMs: integer('timeout_ms'),
+    /** Explicit unlimited mode: 1 = producer disabled this job's execution deadline. */
+    timeoutUnlimited: integer('timeout_unlimited').notNull().default(0),
+    /** Fresh per-claim ownership token; `null` marks legacy (unfenced) claims. */
+    attemptToken: text('attempt_token'),
+    /** Ownership lease expiry — independent of execution duration; renewed while live. */
+    leaseExpiresAt: integer('lease_expires_at'),
 }, (table) => [index('queue_jobs_ready_idx').on(table.status, table.nextRetryAt, table.createdAt)]);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-db",
-    "version": "0.4.59",
+    "version": "0.4.60",
     "description": "@gobing-ai/ts-db — a drizzle-free database facade: typed DAOs over Bun SQLite / Cloudflare D1, a small predicate query spec, single-source-of-truth tables, and migrations. Drizzle stays an internal detail.",
     "keywords": [
         "typescript",
@@ -66,8 +66,8 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-db-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-runtime": "^0.4.59",
-        "@gobing-ai/ts-utils": "^0.4.59"
+        "@gobing-ai/ts-runtime": "^0.4.60",
+        "@gobing-ai/ts-utils": "^0.4.60"
     },
     "peerDependencies": {
         "drizzle-orm": ">=0.38.0",

package/src/embedded-migrations.ts

@@ -41,4 +41,9 @@ export const embeddedMigrations: EmbeddedMigration[] = [
         sql: 'CREATE INDEX `idx_inbox_messages_to_status` ON `inbox_messages` (`to_id`,`status`);',
         hash: '3c00f1bce4f569e442f3142df31ff478d6c9b3d460824d46575f50a324bfae61',
     },
+    {
+        tag: '0005_queue_attempt_ownership',
+        sql: 'ALTER TABLE `queue_jobs` ADD `timeout_ms` integer;\nALTER TABLE `queue_jobs` ADD `timeout_unlimited` integer DEFAULT 0 NOT NULL;\nALTER TABLE `queue_jobs` ADD `attempt_token` text;\nALTER TABLE `queue_jobs` ADD `lease_expires_at` integer;',
+        hash: 'f6a4eaf11eee838f424515e57eca3a46539260bb2fb5b0b112870ca5ed38d040',
+    },
 ];

package/src/queue-job-dao.ts

@@ -20,6 +20,45 @@ export interface QueueStats {
     failed: number;
 }
 
+/** Options for enqueuing a job: retry policy, delay, TTL, and execution policy. */
+export interface QueueEnqueueOptions {
+    /** Total attempts allowed (default 3). */
+    maxRetries?: number;
+    delay?: number;
+    ttlMs?: number;
+    /**
+     * Job execution policy persisted with the row: a positive integer ms
+     * deadline, explicit `null` = unlimited (disables this job's deadline),
+     * omitted = no job-level decision (consumers apply their own default).
+     * Invalid explicit values are rejected before the row is created.
+     */
+    timeoutMs?: number | null;
+}
+
+/** Options for an atomic claim that takes lease ownership. */
+export interface QueueClaimOptions {
+    /** Ownership lease length in ms; omitted claims keep the legacy recovery path. */
+    leaseMs?: number;
+}
+
+/**
+ * Validate the persisted execution-policy leaf value. The scope-resolution
+ * chain (inherit/unlimited/finite) lives in the consumer packages; the DAO
+ * only stores an already-resolved job option and refuses invalid ones.
+ */
+function assertValidTimeoutMs(value: number | null | undefined): void {
+    if (value === undefined || value === null) return;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        throw new RangeError(`enqueue timeoutMs must be a positive integer or null; received ${String(value)}`);
+    }
+}
+
+/** Persisted execution-policy columns derived from a validated `timeoutMs` option. */
+function timeoutColumns(timeoutMs: number | null | undefined): { timeoutMs?: number; timeoutUnlimited?: number } {
+    if (timeoutMs === undefined) return {};
+    return timeoutMs === null ? { timeoutUnlimited: 1 } : { timeoutMs };
+}
+
 /**
  * Row type inferred from the queue_jobs Drizzle schema.
  */
@@ -39,11 +78,8 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
     /**
      * Enqueue a new job.
      */
-    async enqueue(
-        type: string,
-        payload: unknown,
-        options?: { maxRetries?: number; delay?: number; ttlMs?: number },
-    ): Promise<string> {
+    async enqueue(type: string, payload: unknown, options?: QueueEnqueueOptions): Promise<string> {
+        assertValidTimeoutMs(options?.timeoutMs);
         const now = this.now();
         const id = crypto.randomUUID();
 
@@ -56,6 +92,7 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
             maxRetries: options?.maxRetries ?? 3,
             nextRetryAt: options?.delay !== undefined ? now + options.delay : now,
             ...(options?.ttlMs !== undefined ? { expiresAt: now + options.ttlMs } : {}),
+            ...timeoutColumns(options?.timeoutMs),
         });
 
         return id;
@@ -64,9 +101,10 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
     /**
      * Enqueue multiple jobs in a single batch.
      */
-    async enqueueBatch(
-        jobs: Array<{ type: string; payload: unknown } & { maxRetries?: number; delay?: number; ttlMs?: number }>,
-    ): Promise<string[]> {
+    async enqueueBatch(jobs: Array<{ type: string; payload: unknown } & QueueEnqueueOptions>): Promise<string[]> {
+        for (const job of jobs) {
+            assertValidTimeoutMs(job.timeoutMs);
+        }
         const now = this.now();
         const ids: string[] = [];
 
@@ -83,6 +121,7 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
                 maxRetries: job.maxRetries ?? 3,
                 nextRetryAt: job.delay !== undefined ? now + job.delay : now,
                 ...(job.ttlMs !== undefined ? { expiresAt: now + job.ttlMs } : {}),
+                ...timeoutColumns(job.timeoutMs),
             };
         });
 
@@ -158,30 +197,57 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
     }
 
     /**
-     * Atomically claim ready pending jobs for processing.
+     * Atomically claim ready pending jobs — and recover expired leased
+     * attempts — for processing.
      *
      * The update and selection happen in one SQLite statement so competing
      * consumers only receive rows they actually transitioned to processing.
+     * When `options.leaseMs` is provided the claimed row takes an ownership
+     * lease and a fresh attempt token; the token fences mutations and keeps
+     * rival consumers from re-claiming the live attempt until the lease
+     * expires. Expired leased rows (worker loss) are recovered here with a
+     * fresh token — not by the age-based `resetStuckJobs` sweep, which skips
+     * token-carrying rows. Claims WITHOUT `leaseMs` mint no ownership markers
+     * (and clear any stale ones on reclaim) so the row keeps the legacy
+     * recovery path through the age sweep — a token without a lease would
+     * make the row unrecoverable by both paths.
      */
-    async claimReady(batchSize: number): Promise<QueueJobRecord[]> {
+    async claimReady(batchSize: number, options?: QueueClaimOptions): Promise<QueueJobRecord[]> {
         const limit = Math.floor(batchSize);
         if (limit <= 0) return [];
 
         const now = this.now();
+        const leaseMs = options?.leaseMs;
+        const leased = leaseMs !== undefined;
+        const leaseExpiresAt = leased ? now + leaseMs : null;
+        const reclaimable = sql`(
+            ${queueJobs.status} = 'pending'
+            AND (${queueJobs.nextRetryAt} IS NULL OR ${queueJobs.nextRetryAt} <= ${now})
+        ) OR (
+            ${queueJobs.status} = 'processing'
+            AND ${queueJobs.attemptToken} IS NOT NULL
+            AND ${queueJobs.leaseExpiresAt} IS NOT NULL
+            AND ${queueJobs.leaseExpiresAt} <= ${now}
+        )`;
 
         const result = await (this.db as UpdateReturningDb)
             .update(queueJobs)
-            .set({ status: 'processing', processingAt: now, updatedAt: now })
+            .set({
+                status: 'processing',
+                processingAt: now,
+                updatedAt: now,
+                attemptToken: leased ? sql`lower(hex(randomblob(16)))` : null,
+                leaseExpiresAt,
+            })
             .where(
                 sql`${queueJobs.id} IN (
                     SELECT id
                     FROM ${queueJobs}
-                    WHERE status = 'pending'
-                      AND (next_retry_at IS NULL OR next_retry_at <= ${now})
+                    WHERE ${reclaimable}
                     ORDER BY created_at
                     LIMIT ${limit}
                 )
-                AND ${queueJobs.status} = 'pending'`,
+                AND ${reclaimable}`,
             )
             .returning();
 
@@ -204,41 +270,106 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
 
     /**
      * Mark a job as completed.
+     *
+     * When `attemptToken` is supplied the mutation is fenced: it applies only
+     * if the row is still owned by that attempt. Returns whether it applied.
      */
-    async markCompleted(id: string): Promise<void> {
-        await this.update(id, {
-            status: 'completed',
-            processingAt: null,
-        });
+    async markCompleted(id: string, attemptToken?: string): Promise<boolean> {
+        const where =
+            attemptToken === undefined
+                ? eq(queueJobs.id, id)
+                : and(eq(queueJobs.id, id), eq(queueJobs.attemptToken, attemptToken));
+        const result = await (this.db as UpdateChangesDb)
+            .update(queueJobs)
+            .set({
+                status: 'completed',
+                processingAt: null,
+                attemptToken: null,
+                leaseExpiresAt: null,
+                updatedAt: this.now(),
+            })
+            .where(where);
+        return (result as { changes: number }).changes === 1;
     }
 
     /**
-     * Mark a job as failed.
+     * Mark a job as failed, fenced by fresh attempt ownership when supplied.
      */
-    async markFailed(id: string, attempts: number, error: string): Promise<void> {
-        await this.update(id, {
-            status: 'failed',
-            attempts,
-            lastError: error,
-            processingAt: null,
-        });
+    async markFailed(id: string, attempts: number, error: string, attemptToken?: string): Promise<boolean> {
+        const where =
+            attemptToken === undefined
+                ? eq(queueJobs.id, id)
+                : and(eq(queueJobs.id, id), eq(queueJobs.attemptToken, attemptToken));
+        const result = await (this.db as UpdateChangesDb)
+            .update(queueJobs)
+            .set({
+                status: 'failed',
+                attempts,
+                lastError: error,
+                processingAt: null,
+                attemptToken: null,
+                leaseExpiresAt: null,
+                updatedAt: this.now(),
+            })
+            .where(where);
+        return (result as { changes: number }).changes === 1;
     }
 
     /**
-     * Reset a job to pending for retry with backoff.
+     * Reset a job to pending for retry with backoff, fenced by fresh attempt
+     * ownership when supplied.
      */
-    async markForRetry(id: string, attempts: number, errorMessage: string, nextRetryAt: number): Promise<void> {
-        await this.update(id, {
-            status: 'pending',
-            attempts,
-            lastError: errorMessage,
-            nextRetryAt,
-            processingAt: null,
-        });
+    async markForRetry(
+        id: string,
+        attempts: number,
+        errorMessage: string,
+        nextRetryAt: number,
+        attemptToken?: string,
+    ): Promise<boolean> {
+        const where =
+            attemptToken === undefined
+                ? eq(queueJobs.id, id)
+                : and(eq(queueJobs.id, id), eq(queueJobs.attemptToken, attemptToken));
+        const result = await (this.db as UpdateChangesDb)
+            .update(queueJobs)
+            .set({
+                status: 'pending',
+                attempts,
+                lastError: errorMessage,
+                nextRetryAt,
+                processingAt: null,
+                attemptToken: null,
+                leaseExpiresAt: null,
+                updatedAt: this.now(),
+            })
+            .where(where);
+        return (result as { changes: number }).changes === 1;
+    }
+
+    /**
+     * Extend the ownership lease of a claimed attempt.
+     *
+     * Applies only while the row is still owned by `attemptToken`; a `false`
+     * return means ownership was lost (expired and reclaimed by another
+     * consumer) and the caller must abort and fence its acknowledgements.
+     */
+    async renewLease(id: string, attemptToken: string, leaseMs: number): Promise<boolean> {
+        const now = this.now();
+        const result = await (this.db as UpdateChangesDb)
+            .update(queueJobs)
+            .set({ leaseExpiresAt: now + leaseMs, updatedAt: now })
+            .where(
+                and(eq(queueJobs.id, id), eq(queueJobs.attemptToken, attemptToken), eq(queueJobs.status, 'processing')),
+            );
+        return (result as { changes: number }).changes === 1;
     }
 
     /**
      * Reset stuck processing jobs (processing beyond visibility timeout).
+     *
+     * Age-based legacy recovery only: rows carrying an attempt token are
+     * lease-owned and recover exclusively through their expired lease in
+     * `claimReady`, never by processing age.
      */
     async resetStuckJobs(visibilityTimeout: number): Promise<number> {
         const cutoff = this.now() - visibilityTimeout;
@@ -247,7 +378,8 @@ export class QueueJobDao extends EntityDao<typeof queueJobs, typeof queueJobs.id
             .update(queueJobs)
             .set({ status: 'pending', processingAt: null, updatedAt: this.now() })
             .where(
-                sql`${queueJobs.status} = 'processing' AND ${queueJobs.processingAt} IS NOT NULL AND ${queueJobs.processingAt} <= ${cutoff}`,
+                sql`${queueJobs.status} = 'processing' AND ${queueJobs.processingAt} IS NOT NULL AND ${queueJobs.processingAt} <= ${cutoff}
+                AND ${queueJobs.attemptToken} IS NULL`,
             );
 
         return (result as { changes: number }).changes;

package/src/schema/queue-jobs.ts

@@ -18,6 +18,14 @@ export const queueJobs = sqliteTable(
         lastError: text('last_error'),
         processingAt: integer('processing_at'),
         expiresAt: integer('expires_at'),
+        /** Persisted job execution deadline (ms). `null` = not finite; see timeoutUnlimited. */
+        timeoutMs: integer('timeout_ms'),
+        /** Explicit unlimited mode: 1 = producer disabled this job's execution deadline. */
+        timeoutUnlimited: integer('timeout_unlimited').notNull().default(0),
+        /** Fresh per-claim ownership token; `null` marks legacy (unfenced) claims. */
+        attemptToken: text('attempt_token'),
+        /** Ownership lease expiry — independent of execution duration; renewed while live. */
+        leaseExpiresAt: integer('lease_expires_at'),
     },
     (table) => [index('queue_jobs_ready_idx').on(table.status, table.nextRetryAt, table.createdAt)],
 );