@nicnocquee/dataqueue 1.22.0 → 1.25.0

package/src/queue.ts

@@ -1,3 +1,12 @@
+/**
+ * Backward-compatible re-exports.
+ * All SQL logic has moved to backends/postgres.ts (PostgresBackend class).
+ * These functions delegate to a temporary PostgresBackend instance so that
+ * any existing internal callers continue to work.
+ *
+ * Wait-related functions (waitJob, updateStepData, createWaitpoint, etc.)
+ * are PostgreSQL-only and use direct SQL queries.
+ */
 import { Pool } from 'pg';
 import {
   JobOptions,
@@ -6,142 +15,35 @@ import {
   JobEvent,
   JobEventType,
   TagQueryMode,
+  WaitpointRecord,
 } from './types.js';
+import { PostgresBackend } from './backends/postgres.js';
+import { randomUUID } from 'crypto';
 import { log } from './log-context.js';
 
-/**
- * Record a job event in the job_events table
- */
+/* Thin wrappers — every function creates a lightweight backend wrapper
+   around the given pool and forwards the call.  The class itself holds
+   no mutable state so this is safe and cheap. */
+
 export const recordJobEvent = async (
   pool: Pool,
   jobId: number,
   eventType: JobEventType,
   metadata?: any,
-): Promise<void> => {
-  const client = await pool.connect();
-  try {
-    await client.query(
-      `INSERT INTO job_events (job_id, event_type, metadata) VALUES ($1, $2, $3)`,
-      [jobId, eventType, metadata ? JSON.stringify(metadata) : null],
-    );
-  } catch (error) {
-    log(`Error recording job event for job ${jobId}: ${error}`);
-    // Do not throw, to avoid interfering with main job logic
-  } finally {
-    client.release();
-  }
-};
+): Promise<void> =>
+  new PostgresBackend(pool).recordJobEvent(jobId, eventType, metadata);
 
-/**
- * Add a job to the queue
- */
 export const addJob = async <PayloadMap, T extends keyof PayloadMap & string>(
   pool: Pool,
-  {
-    jobType,
-    payload,
-    maxAttempts = 3,
-    priority = 0,
-    runAt = null,
-    timeoutMs = undefined,
-    tags = undefined,
-  }: JobOptions<PayloadMap, T>,
-): Promise<number> => {
-  const client = await pool.connect();
-  try {
-    let result;
-    if (runAt) {
-      result = await client.query(
-        `INSERT INTO job_queue 
-          (job_type, payload, max_attempts, priority, run_at, timeout_ms, tags) 
-         VALUES ($1, $2, $3, $4, $5, $6, $7) 
-         RETURNING id`,
-        [
-          jobType,
-          payload,
-          maxAttempts,
-          priority,
-          runAt,
-          timeoutMs ?? null,
-          tags ?? null,
-        ],
-      );
-      log(
-        `Added job ${result.rows[0].id}: payload ${JSON.stringify(payload)}, runAt ${runAt.toISOString()}, priority ${priority}, maxAttempts ${maxAttempts} jobType ${jobType}, tags ${JSON.stringify(tags)}`,
-      );
-    } else {
-      result = await client.query(
-        `INSERT INTO job_queue 
-          (job_type, payload, max_attempts, priority, timeout_ms, tags) 
-         VALUES ($1, $2, $3, $4, $5, $6) 
-         RETURNING id`,
-        [
-          jobType,
-          payload,
-          maxAttempts,
-          priority,
-          timeoutMs ?? null,
-          tags ?? null,
-        ],
-      );
-      log(
-        `Added job ${result.rows[0].id}: payload ${JSON.stringify(payload)}, priority ${priority}, maxAttempts ${maxAttempts} jobType ${jobType}, tags ${JSON.stringify(tags)}`,
-      );
-    }
-    await recordJobEvent(pool, result.rows[0].id, JobEventType.Added, {
-      jobType,
-      payload,
-      tags,
-    });
-    return result.rows[0].id;
-  } catch (error) {
-    log(`Error adding job: ${error}`);
-    throw error;
-  } finally {
-    client.release();
-  }
-};
+  job: JobOptions<PayloadMap, T>,
+): Promise<number> => new PostgresBackend(pool).addJob(job);
 
-/**
- * Get a job by ID
- */
 export const getJob = async <PayloadMap, T extends keyof PayloadMap & string>(
   pool: Pool,
   id: number,
-): Promise<JobRecord<PayloadMap, T> | null> => {
-  const client = await pool.connect();
-  try {
-    const result = await client.query(
-      `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason" FROM job_queue WHERE id = $1`,
-      [id],
-    );
-
-    if (result.rows.length === 0) {
-      log(`Job ${id} not found`);
-      return null;
-    }
+): Promise<JobRecord<PayloadMap, T> | null> =>
+  new PostgresBackend(pool).getJob<PayloadMap, T>(id);
 
-    log(`Found job ${id}`);
-
-    const job = result.rows[0] as JobRecord<PayloadMap, T>;
-
-    return {
-      ...job,
-      payload: job.payload,
-      timeoutMs: job.timeoutMs,
-      failureReason: job.failureReason,
-    };
-  } catch (error) {
-    log(`Error getting job ${id}: ${error}`);
-    throw error;
-  } finally {
-    client.release();
-  }
-};
-
-/**
- * Get jobs by status
- */
 export const getJobsByStatus = async <
   PayloadMap,
   T extends keyof PayloadMap & string,
@@ -150,37 +52,13 @@ export const getJobsByStatus = async <
   status: string,
   limit = 100,
   offset = 0,
-): Promise<JobRecord<PayloadMap, T>[]> => {
-  const client = await pool.connect();
-  try {
-    const result = await client.query(
-      `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason" FROM job_queue WHERE status = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`,
-      [status, limit, offset],
-    );
-
-    log(`Found ${result.rows.length} jobs by status ${status}`);
-
-    return result.rows.map((job) => ({
-      ...job,
-      payload: job.payload,
-      timeoutMs: job.timeoutMs,
-      failureReason: job.failureReason,
-    }));
-  } catch (error) {
-    log(`Error getting jobs by status ${status}: ${error}`);
-    throw error;
-  } finally {
-    client.release();
-  }
-};
+): Promise<JobRecord<PayloadMap, T>[]> =>
+  new PostgresBackend(pool).getJobsByStatus<PayloadMap, T>(
+    status,
+    limit,
+    offset,
+  );
 
-/**
- * Get the next batch of jobs to process
- * @param pool - The database pool
- * @param workerId - The worker ID
- * @param batchSize - The batch size
- * @param jobType - Only fetch jobs with this job type (string or array of strings)
- */
 export const getNextBatch = async <
   PayloadMap,
   T extends keyof PayloadMap & string,
@@ -189,354 +67,307 @@ export const getNextBatch = async <
   workerId: string,
   batchSize = 10,
   jobType?: string | string[],
-): Promise<JobRecord<PayloadMap, T>[]> => {
-  const client = await pool.connect();
-  try {
-    // Begin transaction
-    await client.query('BEGIN');
+): Promise<JobRecord<PayloadMap, T>[]> =>
+  new PostgresBackend(pool).getNextBatch<PayloadMap, T>(
+    workerId,
+    batchSize,
+    jobType,
+  );
+
+export const completeJob = async (pool: Pool, jobId: number): Promise<void> =>
+  new PostgresBackend(pool).completeJob(jobId);
+
+export const prolongJob = async (pool: Pool, jobId: number): Promise<void> =>
+  new PostgresBackend(pool).prolongJob(jobId);
 
-    // Build job type filter
-    let jobTypeFilter = '';
-    let params: any[] = [workerId, batchSize];
-    if (jobType) {
-      if (Array.isArray(jobType)) {
-        jobTypeFilter = ` AND job_type = ANY($3)`;
-        params.push(jobType);
-      } else {
-        jobTypeFilter = ` AND job_type = $3`;
-        params.push(jobType);
+export const failJob = async (
+  pool: Pool,
+  jobId: number,
+  error: Error,
+  failureReason?: FailureReason,
+): Promise<void> =>
+  new PostgresBackend(pool).failJob(jobId, error, failureReason);
+
+export const retryJob = async (pool: Pool, jobId: number): Promise<void> =>
+  new PostgresBackend(pool).retryJob(jobId);
+
+export const cleanupOldJobs = async (
+  pool: Pool,
+  daysToKeep = 30,
+): Promise<number> => new PostgresBackend(pool).cleanupOldJobs(daysToKeep);
+
+export const cancelJob = async (pool: Pool, jobId: number): Promise<void> =>
+  new PostgresBackend(pool).cancelJob(jobId);
+
+export const editJob = async <PayloadMap, T extends keyof PayloadMap & string>(
+  pool: Pool,
+  jobId: number,
+  updates: {
+    payload?: PayloadMap[T];
+    maxAttempts?: number;
+    priority?: number;
+    runAt?: Date | null;
+    timeoutMs?: number | null;
+    tags?: string[] | null;
+  },
+): Promise<void> => new PostgresBackend(pool).editJob(jobId, updates);
+
+export const editAllPendingJobs = async <
+  PayloadMap,
+  T extends keyof PayloadMap & string,
+>(
+  pool: Pool,
+  filters:
+    | {
+        jobType?: string;
+        priority?: number;
+        runAt?:
+          | Date
+          | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
+        tags?: { values: string[]; mode?: TagQueryMode };
       }
-    }
+    | undefined,
+  updates: {
+    payload?: PayloadMap[T];
+    maxAttempts?: number;
+    priority?: number;
+    runAt?: Date | null;
+    timeoutMs?: number;
+    tags?: string[];
+  },
+): Promise<number> =>
+  new PostgresBackend(pool).editAllPendingJobs(filters, updates);
 
-    // Get and lock a batch of jobs
-    const result = await client.query(
-      `
-      UPDATE job_queue
-      SET status = 'processing', 
-          locked_at = NOW(), 
-          locked_by = $1,
-          attempts = attempts + 1,
-          updated_at = NOW(),
-          pending_reason = NULL,
-          started_at = COALESCE(started_at, NOW()),
-          last_retried_at = CASE WHEN attempts > 0 THEN NOW() ELSE last_retried_at END
-      WHERE id IN (
-        SELECT id FROM job_queue
-        WHERE (status = 'pending' OR (status = 'failed' AND next_attempt_at <= NOW()))
-        AND (attempts < max_attempts)
-        AND run_at <= NOW()
-        ${jobTypeFilter}
-        ORDER BY priority DESC, created_at ASC
-        LIMIT $2
-        FOR UPDATE SKIP LOCKED
-      )
-      RETURNING id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason"
-    `,
-      params,
-    );
+export const cancelAllUpcomingJobs = async (
+  pool: Pool,
+  filters?: {
+    jobType?: string;
+    priority?: number;
+    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
+    tags?: { values: string[]; mode?: TagQueryMode };
+  },
+): Promise<number> => new PostgresBackend(pool).cancelAllUpcomingJobs(filters);
 
-    log(`Found ${result.rows.length} jobs to process`);
+export const getAllJobs = async <
+  PayloadMap,
+  T extends keyof PayloadMap & string,
+>(
+  pool: Pool,
+  limit = 100,
+  offset = 0,
+): Promise<JobRecord<PayloadMap, T>[]> =>
+  new PostgresBackend(pool).getAllJobs<PayloadMap, T>(limit, offset);
 
-    // Commit transaction
-    await client.query('COMMIT');
+export const setPendingReasonForUnpickedJobs = async (
+  pool: Pool,
+  reason: string,
+  jobType?: string | string[],
+): Promise<void> =>
+  new PostgresBackend(pool).setPendingReasonForUnpickedJobs(reason, jobType);
 
-    // Record processing event for each job
-    for (const row of result.rows) {
-      await recordJobEvent(pool, row.id, JobEventType.Processing);
-    }
+export const reclaimStuckJobs = async (
+  pool: Pool,
+  maxProcessingTimeMinutes = 10,
+): Promise<number> =>
+  new PostgresBackend(pool).reclaimStuckJobs(maxProcessingTimeMinutes);
 
-    return result.rows.map((job) => ({
-      ...job,
-      payload: job.payload,
-      timeoutMs: job.timeoutMs,
-    }));
-  } catch (error) {
-    log(`Error getting next batch: ${error}`);
-    await client.query('ROLLBACK');
-    throw error;
-  } finally {
-    client.release();
-  }
-};
+export const getJobEvents = async (
+  pool: Pool,
+  jobId: number,
+): Promise<JobEvent[]> => new PostgresBackend(pool).getJobEvents(jobId);
 
-/**
- * Mark a job as completed
- */
-export const completeJob = async (pool: Pool, jobId: number): Promise<void> => {
-  const client = await pool.connect();
-  try {
-    await client.query(
-      `
-      UPDATE job_queue
-      SET status = 'completed', updated_at = NOW(), completed_at = NOW()
-      WHERE id = $1
-    `,
-      [jobId],
-    );
-    await recordJobEvent(pool, jobId, JobEventType.Completed);
-  } catch (error) {
-    log(`Error completing job ${jobId}: ${error}`);
-    throw error;
-  } finally {
-    log(`Completed job ${jobId}`);
-    client.release();
-  }
-};
+export const getJobsByTags = async <
+  PayloadMap,
+  T extends keyof PayloadMap & string,
+>(
+  pool: Pool,
+  tags: string[],
+  mode: TagQueryMode = 'all',
+  limit = 100,
+  offset = 0,
+): Promise<JobRecord<PayloadMap, T>[]> =>
+  new PostgresBackend(pool).getJobsByTags<PayloadMap, T>(
+    tags,
+    mode,
+    limit,
+    offset,
+  );
+
+export const getJobs = async <PayloadMap, T extends keyof PayloadMap & string>(
+  pool: Pool,
+  filters?: {
+    jobType?: string;
+    priority?: number;
+    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
+    tags?: { values: string[]; mode?: TagQueryMode };
+  },
+  limit = 100,
+  offset = 0,
+): Promise<JobRecord<PayloadMap, T>[]> =>
+  new PostgresBackend(pool).getJobs<PayloadMap, T>(filters, limit, offset);
+
+// ── Progress ──────────────────────────────────────────────────────────────────
+
+export const updateProgress = async (
+  pool: Pool,
+  jobId: number,
+  progress: number,
+): Promise<void> => new PostgresBackend(pool).updateProgress(jobId, progress);
+
+// ── Wait support functions (PostgreSQL-only) ─────────────────────────────────
 
 /**
- * Mark a job as failed
+ * Transition a job to 'waiting' status with wait_until and/or wait_token_id.
+ * Saves step_data so the handler can resume from where it left off.
  */
-export const failJob = async (
+export const waitJob = async (
   pool: Pool,
   jobId: number,
-  error: Error,
-  failureReason?: FailureReason,
+  options: {
+    waitUntil?: Date;
+    waitTokenId?: string;
+    stepData: Record<string, any>;
+  },
 ): Promise<void> => {
   const client = await pool.connect();
   try {
-    /**
-     * The next attempt will be scheduled after `2^attempts * 1 minute` from the last attempt.
-     */
-    await client.query(
+    const result = await client.query(
       `
       UPDATE job_queue
-      SET status = 'failed', 
-          updated_at = NOW(),
-          next_attempt_at = CASE 
-            WHEN attempts < max_attempts THEN NOW() + (POWER(2, attempts) * INTERVAL '1 minute')
-            ELSE NULL
-          END,
-          error_history = COALESCE(error_history, '[]'::jsonb) || $2::jsonb,
-          failure_reason = $3,
-          last_failed_at = NOW()
-      WHERE id = $1
+      SET status = 'waiting',
+          wait_until = $2,
+          wait_token_id = $3,
+          step_data = $4,
+          locked_at = NULL,
+          locked_by = NULL,
+          updated_at = NOW()
+      WHERE id = $1 AND status = 'processing'
     `,
       [
         jobId,
-        JSON.stringify([
-          {
-            message: error.message || String(error),
-            timestamp: new Date().toISOString(),
-          },
-        ]),
-        failureReason ?? null,
+        options.waitUntil ?? null,
+        options.waitTokenId ?? null,
+        JSON.stringify(options.stepData),
       ],
     );
-    await recordJobEvent(pool, jobId, JobEventType.Failed, {
-      message: error.message || String(error),
-      failureReason,
+    if (result.rowCount === 0) {
+      log(
+        `Job ${jobId} could not be set to waiting (may have been reclaimed or is no longer processing)`,
+      );
+      return;
+    }
+    await recordJobEvent(pool, jobId, JobEventType.Waiting, {
+      waitUntil: options.waitUntil?.toISOString() ?? null,
+      waitTokenId: options.waitTokenId ?? null,
     });
+    log(`Job ${jobId} set to waiting`);
   } catch (error) {
-    log(`Error failing job ${jobId}: ${error}`);
+    log(`Error setting job ${jobId} to waiting: ${error}`);
     throw error;
   } finally {
-    log(`Failed job ${jobId}`);
     client.release();
   }
 };
 
 /**
- * Retry a failed job immediately
+ * Update step_data for a job. Called after each ctx.run() step completes
+ * to persist intermediate progress.
  */
-export const retryJob = async (pool: Pool, jobId: number): Promise<void> => {
+export const updateStepData = async (
+  pool: Pool,
+  jobId: number,
+  stepData: Record<string, any>,
+): Promise<void> => {
   const client = await pool.connect();
   try {
     await client.query(
-      `
-      UPDATE job_queue
-      SET status = 'pending', 
-          updated_at = NOW(),
-          locked_at = NULL,
-          locked_by = NULL,
-          next_attempt_at = NOW(),
-          last_retried_at = NOW()
-      WHERE id = $1
-    `,
-      [jobId],
+      `UPDATE job_queue SET step_data = $2, updated_at = NOW() WHERE id = $1`,
+      [jobId, JSON.stringify(stepData)],
     );
-    await recordJobEvent(pool, jobId, JobEventType.Retried);
   } catch (error) {
-    log(`Error retrying job ${jobId}: ${error}`);
-    throw error;
+    log(`Error updating step_data for job ${jobId}: ${error}`);
+    // Best-effort: do not throw to avoid killing the running handler
   } finally {
-    log(`Retried job ${jobId}`);
     client.release();
   }
 };
 
 /**
- * Delete old completed jobs
+ * Parse a timeout string like '10m', '1h', '24h', '7d' into milliseconds.
  */
-export const cleanupOldJobs = async (
-  pool: Pool,
-  daysToKeep = 30,
-): Promise<number> => {
-  const client = await pool.connect();
-  try {
-    const result = await client.query(`
-      DELETE FROM job_queue
-      WHERE status = 'completed'
-      AND updated_at < NOW() - INTERVAL '${daysToKeep} days'
-      RETURNING id
-    `);
-    log(`Deleted ${result.rowCount} old jobs`);
-    return result.rowCount || 0;
-  } catch (error) {
-    log(`Error cleaning up old jobs: ${error}`);
-    throw error;
-  } finally {
-    client.release();
-  }
-};
-
 /**
- * Cancel a scheduled job (only if still pending)
+ * Maximum allowed timeout in milliseconds (~365 days).
+ * Prevents overflow to Infinity when computing Date offsets.
  */
-export const cancelJob = async (pool: Pool, jobId: number): Promise<void> => {
-  const client = await pool.connect();
-  try {
-    await client.query(
-      `
-      UPDATE job_queue
-      SET status = 'cancelled', updated_at = NOW(), last_cancelled_at = NOW()
-      WHERE id = $1 AND status = 'pending'
-    `,
-      [jobId],
+const MAX_TIMEOUT_MS = 365 * 24 * 60 * 60 * 1000;
+
+function parseTimeoutString(timeout: string): number {
+  const match = timeout.match(/^(\d+)(s|m|h|d)$/);
+  if (!match) {
+    throw new Error(
+      `Invalid timeout format: "${timeout}". Expected format like "10m", "1h", "24h", "7d".`,
     );
-    await recordJobEvent(pool, jobId, JobEventType.Cancelled);
-  } catch (error) {
-    log(`Error cancelling job ${jobId}: ${error}`);
-    throw error;
-  } finally {
-    log(`Cancelled job ${jobId}`);
-    client.release();
   }
-};
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  let ms: number;
+  switch (unit) {
+    case 's':
+      ms = value * 1000;
+      break;
+    case 'm':
+      ms = value * 60 * 1000;
+      break;
+    case 'h':
+      ms = value * 60 * 60 * 1000;
+      break;
+    case 'd':
+      ms = value * 24 * 60 * 60 * 1000;
+      break;
+    default:
+      throw new Error(`Unknown timeout unit: "${unit}"`);
+  }
+  if (!Number.isFinite(ms) || ms > MAX_TIMEOUT_MS) {
+    throw new Error(
+      `Timeout value "${timeout}" is too large. Maximum allowed is 365 days.`,
+    );
+  }
+  return ms;
+}
 
 /**
- * Cancel all upcoming jobs (pending and scheduled in the future) with optional filters
+ * Create a waitpoint token in the database.
+ * The token can be used to pause a job until an external signal completes it.
+ *
+ * @param pool - The database pool
+ * @param jobId - The job ID to associate with the token (null if created outside a handler)
+ * @param options - Optional timeout and tags
+ * @returns The created waitpoint token
  */
-export const cancelAllUpcomingJobs = async (
+export const createWaitpoint = async (
   pool: Pool,
-  filters?: {
-    jobType?: string;
-    priority?: number;
-    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
-    tags?: { values: string[]; mode?: TagQueryMode };
-  },
-): Promise<number> => {
+  jobId: number | null,
+  options?: { timeout?: string; tags?: string[] },
+): Promise<{ id: string }> => {
   const client = await pool.connect();
   try {
-    let query = `
-      UPDATE job_queue
-      SET status = 'cancelled', updated_at = NOW()
-      WHERE status = 'pending'`;
-    const params: any[] = [];
-    let paramIdx = 1;
-    if (filters) {
-      if (filters.jobType) {
-        query += ` AND job_type = $${paramIdx++}`;
-        params.push(filters.jobType);
-      }
-      if (filters.priority !== undefined) {
-        query += ` AND priority = $${paramIdx++}`;
-        params.push(filters.priority);
-      }
-      if (filters.runAt) {
-        if (filters.runAt instanceof Date) {
-          query += ` AND run_at = $${paramIdx++}`;
-          params.push(filters.runAt);
-        } else if (typeof filters.runAt === 'object') {
-          const ops = filters.runAt;
-          if (ops.gt) {
-            query += ` AND run_at > $${paramIdx++}`;
-            params.push(ops.gt);
-          }
-          if (ops.gte) {
-            query += ` AND run_at >= $${paramIdx++}`;
-            params.push(ops.gte);
-          }
-          if (ops.lt) {
-            query += ` AND run_at < $${paramIdx++}`;
-            params.push(ops.lt);
-          }
-          if (ops.lte) {
-            query += ` AND run_at <= $${paramIdx++}`;
-            params.push(ops.lte);
-          }
-          if (ops.eq) {
-            query += ` AND run_at = $${paramIdx++}`;
-            params.push(ops.eq);
-          }
-        }
-      }
-      if (
-        filters.tags &&
-        filters.tags.values &&
-        filters.tags.values.length > 0
-      ) {
-        const mode = filters.tags.mode || 'all';
-        const tagValues = filters.tags.values;
-        switch (mode) {
-          case 'exact':
-            query += ` AND tags = $${paramIdx++}`;
-            params.push(tagValues);
-            break;
-          case 'all':
-            query += ` AND tags @> $${paramIdx++}`;
-            params.push(tagValues);
-            break;
-          case 'any':
-            query += ` AND tags && $${paramIdx++}`;
-            params.push(tagValues);
-            break;
-          case 'none':
-            query += ` AND NOT (tags && $${paramIdx++})`;
-            params.push(tagValues);
-            break;
-          default:
-            query += ` AND tags @> $${paramIdx++}`;
-            params.push(tagValues);
-        }
-      }
+    const id = `wp_${randomUUID()}`;
+    let timeoutAt: Date | null = null;
+
+    if (options?.timeout) {
+      const ms = parseTimeoutString(options.timeout);
+      timeoutAt = new Date(Date.now() + ms);
     }
-    query += '\nRETURNING id';
-    const result = await client.query(query, params);
-    log(`Cancelled ${result.rowCount} jobs`);
-    return result.rowCount || 0;
-  } catch (error) {
-    log(`Error cancelling upcoming jobs: ${error}`);
-    throw error;
-  } finally {
-    client.release();
-  }
-};
 
-/**
- * Get all jobs with optional pagination
- */
-export const getAllJobs = async <
-  PayloadMap,
-  T extends keyof PayloadMap & string,
->(
-  pool: Pool,
-  limit = 100,
-  offset = 0,
-): Promise<JobRecord<PayloadMap, T>[]> => {
-  const client = await pool.connect();
-  try {
-    const result = await client.query(
-      `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason" FROM job_queue ORDER BY created_at DESC LIMIT $1 OFFSET $2`,
-      [limit, offset],
+    await client.query(
+      `INSERT INTO waitpoints (id, job_id, status, timeout_at, tags) VALUES ($1, $2, 'waiting', $3, $4)`,
+      [id, jobId, timeoutAt, options?.tags ?? null],
     );
-    log(`Found ${result.rows.length} jobs (all)`);
-    return result.rows.map((job) => ({
-      ...job,
-      payload: job.payload,
-      timeoutMs: job.timeoutMs,
-    }));
+
+    log(`Created waitpoint ${id} for job ${jobId}`);
+    return { id };
   } catch (error) {
-    log(`Error getting all jobs: ${error}`);
+    log(`Error creating waitpoint: ${error}`);
     throw error;
   } finally {
     client.release();
@@ -544,62 +375,73 @@ export const getAllJobs = async <
 };
 
 /**
- * Set a pending reason for unpicked jobs
+ * Complete a waitpoint token, optionally providing output data.
+ * This also moves the associated job from 'waiting' back to 'pending' so
+ * it gets picked up by the polling loop.
  */
-export const setPendingReasonForUnpickedJobs = async (
+export const completeWaitpoint = async (
   pool: Pool,
-  reason: string,
-  jobType?: string | string[],
-) => {
+  tokenId: string,
+  data?: any,
+): Promise<void> => {
   const client = await pool.connect();
   try {
-    let jobTypeFilter = '';
-    let params: any[] = [reason];
-    if (jobType) {
-      if (Array.isArray(jobType)) {
-        jobTypeFilter = ` AND job_type = ANY($2)`;
-        params.push(jobType);
-      } else {
-        jobTypeFilter = ` AND job_type = $2`;
-        params.push(jobType);
-      }
-    }
-    await client.query(
-      `UPDATE job_queue SET pending_reason = $1 WHERE status = 'pending'${jobTypeFilter}`,
-      params,
+    await client.query('BEGIN');
+
+    // Update the waitpoint
+    const wpResult = await client.query(
+      `UPDATE waitpoints SET status = 'completed', output = $2, completed_at = NOW()
+       WHERE id = $1 AND status = 'waiting'
+       RETURNING job_id`,
+      [tokenId, data != null ? JSON.stringify(data) : null],
     );
+
+    if (wpResult.rows.length === 0) {
+      await client.query('ROLLBACK');
+      log(`Waitpoint ${tokenId} not found or already completed`);
+      return;
+    }
+
+    const jobId = wpResult.rows[0].job_id;
+
+    // Move the associated job back to 'pending' so it gets picked up
+    if (jobId != null) {
+      await client.query(
+        `UPDATE job_queue
+         SET status = 'pending', wait_token_id = NULL, wait_until = NULL, updated_at = NOW()
+         WHERE id = $1 AND status = 'waiting'`,
+        [jobId],
+      );
+    }
+
+    await client.query('COMMIT');
+    log(`Completed waitpoint ${tokenId} for job ${jobId}`);
+  } catch (error) {
+    await client.query('ROLLBACK');
+    log(`Error completing waitpoint ${tokenId}: ${error}`);
+    throw error;
   } finally {
     client.release();
   }
 };
 
 /**
- * Reclaim jobs stuck in 'processing' for too long.
- *
- * If a process (e.g., API route or worker) crashes after marking a job as 'processing' but before completing it, the job can remain stuck in the 'processing' state indefinitely. This can happen if the process is killed or encounters an unhandled error after updating the job status but before marking it as 'completed' or 'failed'.
- * @param pool - The database pool
- * @param maxProcessingTimeMinutes - Max allowed processing time in minutes (default: 10)
- * @returns Number of jobs reclaimed
+ * Retrieve a waitpoint token by its ID.
  */
-export const reclaimStuckJobs = async (
+export const getWaitpoint = async (
   pool: Pool,
-  maxProcessingTimeMinutes = 10,
-): Promise<number> => {
+  tokenId: string,
+): Promise<WaitpointRecord | null> => {
   const client = await pool.connect();
   try {
     const result = await client.query(
-      `
-      UPDATE job_queue
-      SET status = 'pending', locked_at = NULL, locked_by = NULL, updated_at = NOW()
-      WHERE status = 'processing'
-        AND locked_at < NOW() - INTERVAL '${maxProcessingTimeMinutes} minutes'
-      RETURNING id
-      `,
+      `SELECT id, job_id AS "jobId", status, output, timeout_at AS "timeoutAt", created_at AS "createdAt", completed_at AS "completedAt", tags FROM waitpoints WHERE id = $1`,
+      [tokenId],
     );
-    log(`Reclaimed ${result.rowCount} stuck jobs`);
-    return result.rowCount || 0;
+    if (result.rows.length === 0) return null;
+    return result.rows[0] as WaitpointRecord;
   } catch (error) {
-    log(`Error reclaiming stuck jobs: ${error}`);
+    log(`Error getting waitpoint ${tokenId}: ${error}`);
     throw error;
   } finally {
     client.release();
@@ -607,199 +449,43 @@ export const reclaimStuckJobs = async (
 };
 
 /**
- * Get all events for a job, ordered by createdAt ascending
+ * Expire timed-out waitpoint tokens and move their associated jobs back to 'pending'.
+ * Should be called periodically (e.g., alongside reclaimStuckJobs).
  */
-export const getJobEvents = async (
-  pool: Pool,
-  jobId: number,
-): Promise<JobEvent[]> => {
+export const expireTimedOutWaitpoints = async (pool: Pool): Promise<number> => {
   const client = await pool.connect();
   try {
-    const res = await client.query(
-      `SELECT id, job_id AS "jobId", event_type AS "eventType", metadata, created_at AS "createdAt" FROM job_events WHERE job_id = $1 ORDER BY created_at ASC`,
-      [jobId],
-    );
-    return res.rows as JobEvent[];
-  } finally {
-    client.release();
-  }
-};
+    await client.query('BEGIN');
 
-/**
- * Get jobs by tags (matches all specified tags)
- */
-export const getJobsByTags = async <
-  PayloadMap,
-  T extends keyof PayloadMap & string,
->(
-  pool: Pool,
-  tags: string[],
-  mode: TagQueryMode = 'all',
-  limit = 100,
-  offset = 0,
-): Promise<JobRecord<PayloadMap, T>[]> => {
-  const client = await pool.connect();
-  try {
-    let query = `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags
-       FROM job_queue`;
-    let params: any[] = [];
-    switch (mode) {
-      case 'exact':
-        query += ' WHERE tags = $1';
-        params = [tags];
-        break;
-      case 'all':
-        query += ' WHERE tags @> $1';
-        params = [tags];
-        break;
-      case 'any':
-        query += ' WHERE tags && $1';
-        params = [tags];
-        break;
-      case 'none':
-        query += ' WHERE NOT (tags && $1)';
-        params = [tags];
-        break;
-      default:
-        query += ' WHERE tags @> $1';
-        params = [tags];
-    }
-    query += ' ORDER BY created_at DESC LIMIT $2 OFFSET $3';
-    params.push(limit, offset);
-    const result = await client.query(query, params);
-    log(
-      `Found ${result.rows.length} jobs by tags ${JSON.stringify(tags)} (mode: ${mode})`,
-    );
-    return result.rows.map((job) => ({
-      ...job,
-      payload: job.payload,
-      timeoutMs: job.timeoutMs,
-      failureReason: job.failureReason,
-    }));
-  } catch (error) {
-    log(
-      `Error getting jobs by tags ${JSON.stringify(tags)} (mode: ${mode}): ${error}`,
+    // Find and expire timed-out waitpoints
+    const result = await client.query(
+      `UPDATE waitpoints
+       SET status = 'timed_out'
+       WHERE status = 'waiting' AND timeout_at IS NOT NULL AND timeout_at <= NOW()
+       RETURNING id, job_id`,
     );
-    throw error;
-  } finally {
-    client.release();
-  }
-};
 
-export const getJobs = async <PayloadMap, T extends keyof PayloadMap & string>(
-  pool: Pool,
-  filters?: {
-    jobType?: string;
-    priority?: number;
-    runAt?: Date | { gt?: Date; gte?: Date; lt?: Date; lte?: Date; eq?: Date };
-    tags?: { values: string[]; mode?: TagQueryMode };
-  },
-  limit = 100,
-  offset = 0,
-): Promise<JobRecord<PayloadMap, T>[]> => {
-  const client = await pool.connect();
-  try {
-    let query = `SELECT id, job_type AS "jobType", payload, status, max_attempts AS "maxAttempts", attempts, priority, run_at AS "runAt", timeout_ms AS "timeoutMs", created_at AS "createdAt", updated_at AS "updatedAt", started_at AS "startedAt", completed_at AS "completedAt", last_failed_at AS "lastFailedAt", locked_at AS "lockedAt", locked_by AS "lockedBy", error_history AS "errorHistory", failure_reason AS "failureReason", next_attempt_at AS "nextAttemptAt", last_failed_at AS "lastFailedAt", last_retried_at AS "lastRetriedAt", last_cancelled_at AS "lastCancelledAt", pending_reason AS "pendingReason", tags FROM job_queue`;
-    const params: any[] = [];
-    let where: string[] = [];
-    let paramIdx = 1;
-    if (filters) {
-      if (filters.jobType) {
-        where.push(`job_type = $${paramIdx++}`);
-        params.push(filters.jobType);
-      }
-      if (filters.priority !== undefined) {
-        where.push(`priority = $${paramIdx++}`);
-        params.push(filters.priority);
-      }
-      if (filters.runAt) {
-        if (filters.runAt instanceof Date) {
-          where.push(`run_at = $${paramIdx++}`);
-          params.push(filters.runAt);
-        } else if (
-          typeof filters.runAt === 'object' &&
-          (filters.runAt.gt !== undefined ||
-            filters.runAt.gte !== undefined ||
-            filters.runAt.lt !== undefined ||
-            filters.runAt.lte !== undefined ||
-            filters.runAt.eq !== undefined)
-        ) {
-          const ops = filters.runAt as {
-            gt?: Date;
-            gte?: Date;
-            lt?: Date;
-            lte?: Date;
-            eq?: Date;
-          };
-          if (ops.gt) {
-            where.push(`run_at > $${paramIdx++}`);
-            params.push(ops.gt);
-          }
-          if (ops.gte) {
-            where.push(`run_at >= $${paramIdx++}`);
-            params.push(ops.gte);
-          }
-          if (ops.lt) {
-            where.push(`run_at < $${paramIdx++}`);
-            params.push(ops.lt);
-          }
-          if (ops.lte) {
-            where.push(`run_at <= $${paramIdx++}`);
-            params.push(ops.lte);
-          }
-          if (ops.eq) {
-            where.push(`run_at = $${paramIdx++}`);
-            params.push(ops.eq);
-          }
-        }
-      }
-      if (
-        filters.tags &&
-        filters.tags.values &&
-        filters.tags.values.length > 0
-      ) {
-        const mode = filters.tags.mode || 'all';
-        const tagValues = filters.tags.values;
-        switch (mode) {
-          case 'exact':
-            where.push(`tags = $${paramIdx++}`);
-            params.push(tagValues);
-            break;
-          case 'all':
-            where.push(`tags @> $${paramIdx++}`);
-            params.push(tagValues);
-            break;
-          case 'any':
-            where.push(`tags && $${paramIdx++}`);
-            params.push(tagValues);
-            break;
-          case 'none':
-            where.push(`NOT (tags && $${paramIdx++})`);
-            params.push(tagValues);
-            break;
-          default:
-            where.push(`tags @> $${paramIdx++}`);
-            params.push(tagValues);
-        }
+    // Move associated jobs back to 'pending'
+    for (const row of result.rows) {
+      if (row.job_id != null) {
+        await client.query(
+          `UPDATE job_queue
+           SET status = 'pending', wait_token_id = NULL, wait_until = NULL, updated_at = NOW()
+           WHERE id = $1 AND status = 'waiting'`,
+          [row.job_id],
+        );
       }
     }
-    if (where.length > 0) {
-      query += ` WHERE ${where.join(' AND ')}`;
+
+    await client.query('COMMIT');
+    const count = result.rowCount || 0;
+    if (count > 0) {
+      log(`Expired ${count} timed-out waitpoints`);
     }
-    // Always add LIMIT and OFFSET as the last parameters
-    paramIdx = params.length + 1;
-    query += ` ORDER BY created_at DESC LIMIT $${paramIdx++} OFFSET $${paramIdx}`;
-    params.push(limit, offset);
-    const result = await client.query(query, params);
-    log(`Found ${result.rows.length} jobs`);
-    return result.rows.map((job) => ({
-      ...job,
-      payload: job.payload,
-      timeoutMs: job.timeoutMs,
-      failureReason: job.failureReason,
-    }));
+    return count;
   } catch (error) {
-    log(`Error getting jobs: ${error}`);
+    await client.query('ROLLBACK');
+    log(`Error expiring timed-out waitpoints: ${error}`);
     throw error;
   } finally {
     client.release();