@strav/queue 0.4.30 → 1.0.0-alpha.3

package/README.md

@@ -0,0 +1,243 @@
+# @strav/queue
+
+Background-job primitives for Strav 1.0 — the `Job` base class, the `JobRegistry`, the `Queue` contract, and a synchronous in-process driver. Postgres-backed `DatabaseQueue` + `Worker` + `Scheduler` land in follow-up M3 slices.
+
+> **Status: 1.0.0-alpha — queue package functionally complete.** Contract layer + `SyncQueue` + `DatabaseQueue` (queue-until-commit) + `Worker` (SKIP LOCKED + backoff + atomic-move-to-failed) + `Scheduler` (cron + `onOneServer`) + `failedJobsSchema` all shipped. Only the `queue:retry` / `queue:flush` console commands remain — they wait on `@strav/cli` (M4).
+
+## Install
+
+```bash
+bun add @strav/queue
+```
+
+Peer dep: `@strav/kernel` (already in the workspace).
+
+## Defining a Job
+
+Subclass `Job<TPayload>`, declare a stable `static jobName`, implement `handle(ctx)`:
+
+```ts
+import { Job, type JobContext } from '@strav/queue'
+import { inject } from '@strav/kernel'
+
+@inject()
+export class SendWelcomeEmail extends Job<{ userId: string }> {
+  static override readonly jobName = 'mail.welcome'
+
+  constructor(
+    private readonly users: UserRepository,
+    private readonly mail: MailManager,
+  ) {
+    super()
+  }
+
+  async handle(ctx: JobContext<{ userId: string }>): Promise<void> {
+    const user = await this.users.findOrFail(ctx.payload.userId)
+    await this.mail.send(new WelcomeEmail(user))
+  }
+}
+```
+
+The Worker constructs the Job via the container — so `@inject()`-marked subclasses get their dependencies the same way Repositories + controllers do. The payload arrives on `JobContext.payload` (after JSON round-trip through the queue backend).
+
+### Configuration
+
+Optional static overrides — the Worker reads these per-attempt:
+
+```ts
+class SendWelcomeEmail extends Job<...> {
+  static override readonly jobName = 'mail.welcome'
+  static override readonly maxAttempts = 5
+  static override readonly timeout = 30          // seconds
+  static override readonly queue = 'mail'        // named queue
+  static override backoff(attempt: number): number {
+    return Math.min(60, 2 ** attempt)            // seconds before next retry
+  }
+}
+```
+
+Omitted fields fall back to driver defaults.
+
+### `failed(ctx)` hook
+
+Fires when a `handle()` attempt throws — both on intermediate retryable failures AND on the final failure. Useful for routing to a dead-letter, posting to Slack, etc.:
+
+```ts
+async failed(ctx: JobFailedContext<{ userId: string }>): Promise<void> {
+  await slack.post(`Welcome email failed for ${ctx.payload.userId}: ${(ctx.error as Error).message}`)
+}
+```
+
+A throw from `failed()` is logged but doesn't change the retry decision.
+
+## Registering jobs
+
+`JobRegistry` maps `jobName` strings back to Job classes — the Worker uses it to deserialize the queue row's `type` column into a class to instantiate.
+
+### Explicit
+
+```ts
+import { JobRegistry } from '@strav/queue'
+import { SendWelcomeEmail } from '../app/Jobs/send_welcome_email.ts'
+
+const registry = new JobRegistry().registerAll([SendWelcomeEmail, /* ... */])
+```
+
+### Auto-discovery
+
+`discover(pattern)` uses `Bun.Glob` to scan files, dynamically imports each, and registers every export that satisfies `isJobClass()`. Same shape as `SchemaRegistry.discover` in `@strav/database`.
+
+```ts
+await registry.discover('app/Jobs/**/*.ts')
+```
+
+Re-exports of the same class (barrel patterns) dedupe by identity; two DIFFERENT classes sharing a `jobName` throw `ConfigError`.
+
+## Dispatching
+
+`Queue` is an interface with three methods:
+
+```ts
+queue.dispatch(JobClass, payload, opts?)       // returns jobId (ULID)
+queue.dispatchLater(at, JobClass, payload, opts?)
+queue.dispatchSync(JobClass, payload)          // run in-process, no persistence
+```
+
+`dispatchLater`'s `at` is either a `Date` (absolute) or a positive number of seconds from now. Past dates / zero clamp to "now". Negative numbers throw.
+
+`opts.queue` and `opts.attempts` override the JobClass defaults.
+
+## SyncQueue — in-process driver
+
+The V1 driver for tests and single-process dev. Instantiates the Job via the container, builds a `JobContext`, calls `handle()` synchronously. No persistence, no retries — if `handle()` throws, the throw propagates.
+
+```ts
+import { Application } from '@strav/kernel'
+import { SyncQueue } from '@strav/queue'
+
+const app = new Application()
+const queue = new SyncQueue({ container: app, logger: app.resolve(Logger) })
+
+await queue.dispatch(SendWelcomeEmail, { userId: 'u-1' })   // runs immediately
+```
+
+`dispatchLater` under `SyncQueue` ignores the delay (still runs immediately) but validates the delay shape — so callers can't pass `-5` here and have it silently work, only to fail on `DatabaseQueue` later.
+
+## DatabaseQueue — Postgres-backed driver
+
+The production driver. `dispatch` writes a `strav_jobs` row; the Worker (next M3 slice) picks it up via `SELECT FOR UPDATE SKIP LOCKED`. Apps register `jobSchema` with their `SchemaRegistry` and migrate the table.
+
+```ts
+import { Application, EventBus } from '@strav/kernel'
+import { DatabaseProvider, PostgresDatabase, SchemaRegistry } from '@strav/database'
+import { DatabaseQueue, jobSchema } from '@strav/queue'
+
+// In SchemasProvider (or wherever you register schemas):
+registry.registerAll([jobSchema, /* … */])
+
+// In QueueProvider:
+new DatabaseQueue({
+  db: app.resolve(PostgresDatabase),
+  container: app,
+  logger: app.resolve(Logger),
+})
+```
+
+### Queue-until-commit
+
+When `dispatch` is called inside `UnitOfWork.run(...)` or `TenantManager.withTenant(...)`, the INSERT routes through the ambient transaction. Atomic with the surrounding work:
+
+```ts
+await uow.run(async () => {
+  await userRepo.create({ email })
+  await queue.dispatch(SendWelcomeEmail, { userId: '...' })
+  // If the transaction commits, both the user row AND the queue row
+  // are visible. If it rolls back, neither exists.
+})
+```
+
+This is the M3 spike from the spec — Postgres's transactional atomicity gives us the semantic for free. See [`docs/queue/api.md`](../../docs/queue/api.md#queue-until-commit-semantics) for the full mechanics.
+
+### Delay mechanics
+
+`dispatchLater` computes delays in Postgres (`now() + interval 'N seconds'`) so the Worker reads `available_at` from the same DB clock the dispatcher wrote against — no clock-skew bugs.
+
+## Worker — the consumer side
+
+Polls `strav_jobs`, claims via `SELECT FOR UPDATE SKIP LOCKED`, runs `handle()` with a per-attempt timeout, deletes on success, retries with backoff on failure.
+
+```ts
+import { Worker } from '@strav/queue'
+
+const worker = new Worker({
+  db: app.resolve(PostgresDatabase),
+  registry: app.resolve(JobRegistry),
+  container: app,
+  logger: app.resolve(Logger),
+  queues: ['default'],
+  pollInterval: 1000,      // ms between empty polls
+  timeoutSeconds: 60,      // per-attempt timeout
+})
+
+const controller = new AbortController()
+process.on('SIGTERM', () => controller.abort())
+process.on('SIGINT',  () => controller.abort())
+
+await worker.run(controller.signal)
+```
+
+`SKIP LOCKED` is the load-bearing primitive — multiple Worker processes can poll the same queue concurrently without picking the same row. Scale horizontally by running more processes.
+
+Default backoff: exponential with ±25% jitter, capped at 300 seconds. Per-job override via `static backoff(attempt: number)`, per-Worker via `defaultBackoff`. Jitter prevents thundering-herd retries when many jobs fail simultaneously.
+
+`processOne()` (single-shot) is also exposed — useful for tests + one-off CLI invocations.
+
+## Scheduler — cron-driven dispatch
+
+```ts
+import { Scheduler, dailyAt, everyMinutes, hourly } from '@strav/queue'
+
+const scheduler = new Scheduler({
+  queue: app.resolve(Queue),
+  tenants: app.resolve(TenantManager),
+})
+
+scheduler
+  .schedule({ job: CleanupOldSessions, cron: hourly() })
+  .schedule({ job: GenerateNightlyReports, cron: dailyAt('02:00'), oneServer: true })
+  .schedule({ job: SyncStripe, cron: everyMinutes(15), oneServer: true })
+
+const controller = new AbortController()
+process.on('SIGTERM', () => controller.abort())
+process.on('SIGINT',  () => controller.abort())
+await scheduler.run(controller.signal)
+```
+
+`oneServer: true` uses `TenantManager.withLock` to acquire a fleet-wide advisory lock + `strav_scheduler_runs.last_run_at` to track which tick boundary already dispatched. Only one server in the fleet dispatches per tick — exactly-once across however many scheduler processes you run.
+
+Register `schedulerRunsSchema` alongside `jobSchema` in your `SchemaRegistry` so `generateMigration` picks up the table.
+
+Cron matching is UTC-based for predictability. Helper builders cover the common cases (`everyMinute`, `everyMinutes`, `hourly`, `daily`, `dailyAt`) — reach for `cron(expression)` directly when you need weekly / monthly / arbitrary expressions.
+
+## Failed jobs — `strav_failed_jobs` dead-letter
+
+When `Worker.processOne()` exhausts a job's `max_attempts`, the row moves from `strav_jobs` to `strav_failed_jobs` atomically (INSERT + DELETE in one transaction). Apps inspect this table to triage what blew up:
+
+```sql
+SELECT job_name, exception, attempts, failed_at
+FROM strav_failed_jobs
+WHERE job_name = 'mail.welcome'
+ORDER BY failed_at DESC;
+```
+
+Register `failedJobsSchema` alongside `jobSchema` + `schedulerRunsSchema` so `generateMigration` picks up the table:
+
+```ts
+registry.registerAll([userSchema, jobSchema, schedulerRunsSchema, failedJobsSchema])
+```
+
+The `queue:retry` / `queue:flush` console commands (bulk re-enqueue / drop) ship with `@strav/cli` in M4. Until then, retry by hand: SELECT the failed row, INSERT into `strav_jobs` with the same payload, DELETE from `strav_failed_jobs`.
+
+## What's NOT here yet
+
+- **`queue:retry` / `queue:flush` console commands** — bulk operations on the `strav_failed_jobs` table. Waits on `@strav/cli` in M4.

package/package.json

@@ -1,38 +1,29 @@
 {
   "name": "@strav/queue",
-  "version": "0.4.30",
+  "version": "1.0.0-alpha.3",
+  "description": "Strav queue layer — Job + JobRegistry + dispatch contract; backends ship as drivers",
   "type": "module",
-  "description": "Background job processing and task scheduling for the Strav framework",
-  "license": "MIT",
-  "keywords": [
-    "bun",
-    "framework",
-    "typescript",
-    "strav",
-    "queue",
-    "scheduler"
-  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
   "files": [
-    "src/",
-    "package.json",
-    "tsconfig.json",
-    "CHANGELOG.md"
+    "src",
+    "README.md"
   ],
-  "exports": {
-    ".": "./src/index.ts",
-    "./queue": "./src/queue/index.ts",
-    "./queue/*": "./src/queue/*.ts",
-    "./scheduler": "./src/scheduler/index.ts",
-    "./scheduler/*": "./src/scheduler/*.ts",
-    "./providers": "./src/providers/index.ts",
-    "./providers/*": "./src/providers/*.ts"
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/database": "1.0.0-alpha.3",
+    "@strav/kernel": "1.0.0-alpha.3"
   },
   "peerDependencies": {
-    "@strav/kernel": "0.4.30",
-    "@strav/database": "0.4.30"
+    "@types/bun": ">=1.3.14"
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
-  }
+  "devDependencies": null
 }

package/src/cron.ts

@@ -0,0 +1,194 @@
+/**
+ * `CronExpression` — parses a 5-field cron string + matches it against
+ * a `Date`.
+ *
+ * Fields, in order:
+ *   1. minute        (0–59)
+ *   2. hour          (0–23)
+ *   3. day-of-month  (1–31)
+ *   4. month         (1–12)
+ *   5. day-of-week   (0–6, Sunday = 0)
+ *
+ * Per-field syntax:
+ *   - `*`         — any value
+ *   - `N`         — exactly N
+ *   - `A-B`       — every value in `[A, B]` inclusive
+ *   - `A,B,C`     — list of values (each item is itself one of the
+ *                   above forms)
+ *   - `*\/N`      — every Nth value across the full range
+ *   - `A-B/N`     — every Nth value across `[A, B]`
+ *
+ * Time zone: matches against the UTC components of the `Date` —
+ * `.getUTCMinutes()` / `.getUTCHours()` / etc. Predictable across
+ * machines; apps that need wall-clock scheduling translate by hand at
+ * the call site (or supply a `Date` already shifted to local).
+ *
+ * Name aliases (`jan` / `mon` / etc.) are not supported in V1; use
+ * numbers.
+ */
+
+const FIELDS = [
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour', min: 0, max: 23 },
+  { name: 'day-of-month', min: 1, max: 31 },
+  { name: 'month', min: 1, max: 12 },
+  { name: 'day-of-week', min: 0, max: 6 },
+] as const
+
+export class CronExpression {
+  /** The expanded set of acceptable values per field — `Set<number>` × 5. */
+  private readonly fields: ReadonlyArray<ReadonlySet<number>>
+
+  constructor(public readonly expression: string) {
+    const parts = expression.trim().split(/\s+/)
+    if (parts.length !== 5) {
+      throw new Error(
+        `CronExpression: expected 5 space-separated fields, got ${parts.length}: "${expression}"`,
+      )
+    }
+    this.fields = parts.map((part, i) => {
+      const spec = FIELDS[i] as (typeof FIELDS)[number]
+      return parseField(part, spec.min, spec.max, spec.name)
+    })
+  }
+
+  /** True iff `date`'s UTC components fall within every field's accepted set. */
+  matches(date: Date): boolean {
+    const minute = date.getUTCMinutes()
+    const hour = date.getUTCHours()
+    const dayOfMonth = date.getUTCDate()
+    // JS months are 0–11; cron is 1–12.
+    const month = date.getUTCMonth() + 1
+    const dayOfWeek = date.getUTCDay()
+
+    return (
+      (this.fields[0] as ReadonlySet<number>).has(minute) &&
+      (this.fields[1] as ReadonlySet<number>).has(hour) &&
+      (this.fields[2] as ReadonlySet<number>).has(dayOfMonth) &&
+      (this.fields[3] as ReadonlySet<number>).has(month) &&
+      (this.fields[4] as ReadonlySet<number>).has(dayOfWeek)
+    )
+  }
+}
+
+/** Parse one field. Handles `,` lists by recursing on each segment. */
+function parseField(part: string, min: number, max: number, label: string): ReadonlySet<number> {
+  if (part === '') {
+    throw new Error(`CronExpression: empty ${label} field.`)
+  }
+  const out = new Set<number>()
+  for (const segment of part.split(',')) {
+    parseSegment(segment, min, max, label, out)
+  }
+  return out
+}
+
+/** Parse a single segment: `*`, `N`, `A-B`, `*\/N`, `A-B/N`. */
+function parseSegment(segment: string, min: number, max: number, label: string, into: Set<number>) {
+  // Step syntax: split off `/N` if present.
+  let baseSegment = segment
+  let step = 1
+  const slashIdx = segment.indexOf('/')
+  if (slashIdx !== -1) {
+    baseSegment = segment.slice(0, slashIdx)
+    const stepText = segment.slice(slashIdx + 1)
+    const parsed = Number.parseInt(stepText, 10)
+    if (!Number.isInteger(parsed) || parsed <= 0 || String(parsed) !== stepText) {
+      throw new Error(`CronExpression: bad step in ${label} "${segment}".`)
+    }
+    step = parsed
+  }
+
+  let start: number
+  let end: number
+  if (baseSegment === '*') {
+    start = min
+    end = max
+  } else if (baseSegment.includes('-')) {
+    const [aText, bText] = baseSegment.split('-')
+    if (aText === undefined || bText === undefined) {
+      throw new Error(`CronExpression: bad range in ${label} "${segment}".`)
+    }
+    const a = Number.parseInt(aText, 10)
+    const b = Number.parseInt(bText, 10)
+    if (
+      !Number.isInteger(a) ||
+      !Number.isInteger(b) ||
+      String(a) !== aText ||
+      String(b) !== bText
+    ) {
+      throw new Error(`CronExpression: bad range in ${label} "${segment}".`)
+    }
+    start = a
+    end = b
+  } else {
+    const n = Number.parseInt(baseSegment, 10)
+    if (!Number.isInteger(n) || String(n) !== baseSegment) {
+      throw new Error(`CronExpression: bad value in ${label} "${segment}".`)
+    }
+    start = n
+    end = n
+  }
+
+  if (start < min || end > max) {
+    throw new Error(`CronExpression: ${label} value out of range [${min}, ${max}]: "${segment}".`)
+  }
+  if (start > end) {
+    throw new Error(`CronExpression: ${label} range start > end: "${segment}".`)
+  }
+
+  for (let v = start; v <= end; v += step) {
+    into.add(v)
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public helpers — convenience constructors for the common cadences.
+// Apps reaching beyond these use `cron(expression)` directly.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Every minute — `* * * * *`. */
+export function everyMinute(): CronExpression {
+  return new CronExpression('* * * * *')
+}
+
+/** Every N minutes — emits a cron expression with `*\/N` in the minute field. Throws on non-positive N. */
+export function everyMinutes(n: number): CronExpression {
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`everyMinutes: expected a positive integer, got ${n}.`)
+  }
+  return new CronExpression(`*/${n} * * * *`)
+}
+
+/** Top of every hour — `0 * * * *`. */
+export function hourly(): CronExpression {
+  return new CronExpression('0 * * * *')
+}
+
+/** Midnight UTC daily — `0 0 * * *`. */
+export function daily(): CronExpression {
+  return new CronExpression('0 0 * * *')
+}
+
+/** Daily at a specific UTC time — `dailyAt('14:30')` → `30 14 * * *`. */
+export function dailyAt(time: string): CronExpression {
+  const match = time.match(/^(\d{1,2}):(\d{2})$/)
+  if (!match) {
+    throw new Error(`dailyAt: expected HH:MM (24-hour), got "${time}".`)
+  }
+  const hour = Number.parseInt(match[1] as string, 10)
+  const minute = Number.parseInt(match[2] as string, 10)
+  if (hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+    throw new Error(`dailyAt: time out of range "${time}".`)
+  }
+  return new CronExpression(`${minute} ${hour} * * *`)
+}
+
+/**
+ * Escape hatch for non-trivial schedules — accepts any valid 5-field cron
+ * expression. Apps that want weekly / monthly / "Mondays at 9" etc. use
+ * this directly.
+ */
+export function cron(expression: string): CronExpression {
+  return new CronExpression(expression)
+}

package/src/database_queue.ts

@@ -0,0 +1,177 @@
+/**
+ * `DatabaseQueue` — Postgres-backed `Queue` driver.
+ *
+ * Persists each `dispatch` / `dispatchLater` as a `_strav_jobs` row;
+ * Workers (next M3 slice) `SELECT FOR UPDATE SKIP LOCKED` to claim
+ * available rows and run `handle()`.
+ *
+ * **Queue-until-commit semantics.** When `dispatch()` is called inside
+ * a `UnitOfWork.run(...)` or `TenantManager.withTenant(...)` scope, the
+ * driver routes the INSERT through the ambient transaction's executor
+ * (read from `transactionalStorage`). The new row commits + rolls back
+ * atomically with the surrounding transaction:
+ *
+ *   - If the transaction COMMITs, the queue row is visible to Workers.
+ *     The dispatched job runs.
+ *   - If the transaction ROLLBACKs, the row never existed. The job is
+ *     dropped.
+ *
+ * This is exactly the spec's M3 spike ("flush queue on commit; drop
+ * on rollback") — Postgres's transactional atomicity gives us the
+ * semantic for free; no deferred-callback machinery needed.
+ *
+ * Outside a transactional scope, `dispatch` writes against
+ * `this.db` directly (auto-commit).
+ *
+ * `dispatchSync` bypasses persistence entirely — instantiates the Job
+ * via the container and runs `handle()` in-process, just like
+ * `SyncQueue.dispatchSync`. The caller's session continues without a
+ * Worker ever seeing the work.
+ */
+
+import {
+  currentTransactionalContext,
+  type Database,
+  type DatabaseExecutor,
+  type PostgresDatabase,
+} from '@strav/database'
+import { type Container, type Logger, ulid } from '@strav/kernel'
+import type { JobClass, JobContext, PayloadOf } from './job.ts'
+import { jobSchema } from './job_schema.ts'
+import type { DispatchLaterOptions, DispatchOptions, Queue } from './queue.ts'
+
+export interface DatabaseQueueOptions {
+  /** Postgres pool used for INSERTs outside an ambient transaction. */
+  db: PostgresDatabase | Database
+  /**
+   * Container used to construct Job instances for `dispatchSync`. The
+   * Worker (separate slice) also goes through the container, so the
+   * same `@inject()`-driven wiring resolves consistently.
+   */
+  container: Container
+  /** Optional Logger attached to `dispatchSync` `JobContext.log`. Default: no-op. */
+  logger?: Logger
+  /** Default `max_attempts` when neither the JobClass nor `DispatchOptions` specifies one. Default `3`. */
+  defaultAttempts?: number
+  /** Default queue name when neither the JobClass nor `DispatchOptions` specifies one. Default `'default'`. */
+  defaultQueue?: string
+}
+
+export class DatabaseQueue implements Queue {
+  private readonly db: Database
+  private readonly container: Container
+  private readonly logger: Logger
+  private readonly defaultAttempts: number
+  private readonly defaultQueue: string
+
+  constructor(opts: DatabaseQueueOptions) {
+    this.db = opts.db
+    this.container = opts.container
+    this.logger = opts.logger ?? createNoopLogger()
+    this.defaultAttempts = opts.defaultAttempts ?? 3
+    this.defaultQueue = opts.defaultQueue ?? 'default'
+  }
+
+  async dispatch<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    opts?: DispatchOptions,
+  ): Promise<string> {
+    return this.insertJob(jobClass, payload, /* delaySeconds */ 0, opts)
+  }
+
+  async dispatchLater<TJob extends JobClass>(
+    at: Date | number,
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    opts?: DispatchLaterOptions,
+  ): Promise<string> {
+    const delaySeconds = computeDelaySeconds(at)
+    return this.insertJob(jobClass, payload, delaySeconds, opts)
+  }
+
+  async dispatchSync<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+  ): Promise<void> {
+    const jobId = ulid()
+    const job = this.container.make(jobClass)
+    const ctx: JobContext = {
+      jobId,
+      attempt: 1,
+      payload,
+      // SyncQueue parity — dispatchSync runs to completion in one tick;
+      // a never-aborted signal keeps handlers written against the
+      // production contract working unchanged.
+      signal: new AbortController().signal,
+      log: this.logger,
+    }
+    await job.handle(ctx)
+  }
+
+  /**
+   * Single INSERT path shared by `dispatch` + `dispatchLater`. Reads
+   * the ambient transactional context — when present, the INSERT
+   * routes through `ctx.tx` so the row is part of the surrounding
+   * transaction's atomicity guarantee.
+   */
+  private async insertJob<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    delaySeconds: number,
+    opts: DispatchOptions | undefined,
+  ): Promise<string> {
+    const jobId = ulid()
+    const queue = opts?.queue ?? jobClass.queue ?? this.defaultQueue
+    const maxAttempts = opts?.attempts ?? jobClass.maxAttempts ?? this.defaultAttempts
+
+    const executor: DatabaseExecutor = currentTransactionalContext()?.tx ?? this.db
+    // `available_at` is computed in Postgres so the queue's notion of
+    // "now" is the DB clock — the only clock the Worker reads.
+    // Mixing wall-clock from the dispatcher with DB-clock from the
+    // Worker invites skew bugs.
+    const availableAtFragment =
+      delaySeconds > 0 ? `now() + interval '${delaySeconds} seconds'` : 'now()'
+    await executor.execute(
+      `INSERT INTO ${quoteIdent(jobSchema.name)} (
+        "id", "queue", "job_name", "payload", "attempts", "max_attempts", "available_at", "created_at", "updated_at"
+      ) VALUES (
+        $1, $2, $3, $4::jsonb, 0, $5, ${availableAtFragment}, now(), now()
+      )`,
+      [jobId, queue, jobClass.jobName, JSON.stringify(payload), maxAttempts],
+    )
+    return jobId
+  }
+}
+
+/** Normalize `at` (Date | seconds-from-now) → seconds-from-now ≥ 0. */
+function computeDelaySeconds(at: Date | number): number {
+  if (typeof at === 'number') {
+    if (at < 0) {
+      throw new Error(`DatabaseQueue.dispatchLater: delay must be non-negative, got ${at}.`)
+    }
+    return at
+  }
+  // `at` is a Date — past values clamp to 0 (immediately available).
+  const deltaMs = at.getTime() - Date.now()
+  return Math.max(0, Math.ceil(deltaMs / 1000))
+}
+
+/** Single-quote-aware identifier quoter for the schema table name. */
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`
+}
+
+/** Bare Logger that drops every call — same shape as SyncQueue's. */
+function createNoopLogger(): Logger {
+  const noop = () => undefined
+  return {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    fatal: noop,
+    trace: noop,
+    child: () => createNoopLogger(),
+  } as unknown as Logger
+}