@strav/queue 0.4.31 → 1.0.0-alpha.4

package/src/job_registry.ts

@@ -0,0 +1,135 @@
+/**
+ * `JobRegistry` — runtime catalog of every registered `Job` class.
+ *
+ * Apps register jobs explicitly (`register(JobClass)` / `registerAll
+ * ([...])`) or via `discover(pattern)`, which uses `Bun.Glob` to scan
+ * files + dynamically `import()` each, registering every exported
+ * class that satisfies {@link isJobClass}. Same shape as
+ * `SchemaRegistry.discover` in `@strav/database`.
+ *
+ * The registry rejects two different classes claiming the same
+ * `jobName` (a wire-protocol collision — the Worker can't disambiguate
+ * which class to instantiate). Re-imports of the same class via a
+ * barrel are deduped by identity.
+ */
+
+import { ConfigError } from '@strav/kernel'
+import { Job, type JobClass } from './job.ts'
+
+export class JobRegistry {
+  private readonly byName = new Map<string, JobClass>()
+
+  /** Register one Job class. Throws when `jobName` is empty or already taken. */
+  register(jobClass: JobClass): this {
+    if (!jobClass.jobName) {
+      throw new ConfigError(
+        `JobRegistry: ${jobClass.name || 'anonymous job'} must declare a non-empty \`static jobName\` — that's the wire identifier the Worker dispatches against.`,
+      )
+    }
+    const existing = this.byName.get(jobClass.jobName)
+    if (existing === jobClass) return this
+    if (existing) {
+      throw new ConfigError(
+        `JobRegistry: jobName "${jobClass.jobName}" is already registered to a different class (${existing.name} vs ${jobClass.name}). Pick a different jobName — the Worker uses it to route serialized payloads back to a class.`,
+      )
+    }
+    this.byName.set(jobClass.jobName, jobClass)
+    return this
+  }
+
+  /** Register several. Order matters only insofar as register() throws on conflict. */
+  registerAll(jobClasses: readonly JobClass[]): this {
+    for (const cls of jobClasses) this.register(cls)
+    return this
+  }
+
+  /**
+   * Auto-discover Job classes by glob pattern. For each matched file:
+   *   1. dynamically `import()` it,
+   *   2. iterate every exported value,
+   *   3. register every one that satisfies {@link isJobClass}.
+   *
+   * `pattern` is a `Bun.Glob`-compatible string (or array). `cwd`
+   * defaults to `process.cwd()` (typically the repo root). Returns
+   * `this` for chaining.
+   *
+   * Re-exports of the same class via multiple files dedupe by object
+   * identity — typical barrel patterns work. Two DIFFERENT classes
+   * sharing a `jobName` still throw `ConfigError`.
+   *
+   * Files exporting no Job classes (helpers, type-only re-exports) are
+   * silently skipped.
+   */
+  async discover(pattern: string | string[], options: { cwd?: string } = {}): Promise<this> {
+    const patterns = Array.isArray(pattern) ? pattern : [pattern]
+    const cwd = options.cwd ?? process.cwd()
+    const files = new Set<string>()
+    for (const p of patterns) {
+      const glob = new Bun.Glob(p)
+      for await (const file of glob.scan({ cwd, absolute: true })) {
+        files.add(file)
+      }
+    }
+    for (const file of files) {
+      const mod = (await import(file)) as Record<string, unknown>
+      for (const value of Object.values(mod)) {
+        if (!isJobClass(value)) continue
+        this.register(value)
+      }
+    }
+    return this
+  }
+
+  /** Resolve by `jobName`. Returns `undefined` for unknown names. */
+  get(jobName: string): JobClass | undefined {
+    return this.byName.get(jobName)
+  }
+
+  /** Throwing variant — use when "this job must exist" is a hard precondition. */
+  getOrFail(jobName: string): JobClass {
+    const cls = this.byName.get(jobName)
+    if (!cls) {
+      throw new ConfigError(
+        `JobRegistry: no Job is registered under "${jobName}". ` +
+          'Either the dispatcher serialized an unknown class, or the Worker is running against a different registry than the dispatcher used.',
+      )
+    }
+    return cls
+  }
+
+  /** True when a Job with this `jobName` is registered. */
+  has(jobName: string): boolean {
+    return this.byName.has(jobName)
+  }
+
+  /** Every registered class, in insertion order. */
+  all(): readonly JobClass[] {
+    return [...this.byName.values()]
+  }
+
+  /** Test helper: wipe the registry. */
+  clear(): void {
+    this.byName.clear()
+  }
+}
+
+/**
+ * Type-guard: a value looks like a Job class — a function whose
+ * prototype extends `Job` and which declares a non-empty `jobName`.
+ * Used by `discover()` to filter exported values; exported so apps can
+ * hand-roll their own discovery loops.
+ *
+ * The prototype check is conservative — a class that doesn't extend
+ * `Job` (even one that happens to look duck-typed) is rejected. That's
+ * intentional: the `failed?` hook + future Worker extensions key off
+ * `instanceof Job`, so the registry's identity guarantee has to match.
+ */
+export function isJobClass(value: unknown): value is JobClass {
+  if (typeof value !== 'function') return false
+  // The Job constructor itself isn't registerable (it's abstract); only
+  // subclasses are.
+  if (value === Job) return false
+  if (!(value.prototype instanceof Job)) return false
+  const jobName = (value as { jobName?: unknown }).jobName
+  return typeof jobName === 'string' && jobName.length > 0
+}

package/src/job_schema.ts

@@ -0,0 +1,49 @@
+/**
+ * `strav_jobs` schema — the backing table for `DatabaseQueue`.
+ *
+ * Naming convention: framework-managed tables that apps register +
+ * migrate use the `strav_*` prefix (no leading underscore — those are
+ * reserved for raw-DDL tables created by the runner / DDL emitter:
+ * `_strav_migrations`, `_strav_tenant_sequences`). Apps register
+ * `jobSchema` with their SchemaRegistry and `generateMigration` picks
+ * it up like any other schema.
+ *
+ * Columns:
+ *   - `id` (char(26), ULID PK) — globally unique across queues.
+ *   - `queue` (varchar(64)) — named queue. Default `'default'`. Workers
+ *     poll one queue at a time, so this is the routing key.
+ *   - `job_name` (varchar(128)) — `JobRegistry` lookup key. The Worker
+ *     deserializes the row by mapping this back to a `JobClass`.
+ *   - `payload` (jsonb) — the `JSON.stringify`'d job payload.
+ *   - `attempts` (integer, default 0) — count of attempts so far. The
+ *     Worker increments before running `handle()`.
+ *   - `max_attempts` (integer, default 3) — total retries allowed.
+ *     `attempts >= max_attempts` after a failed attempt → terminal
+ *     failure, moves to `failed_jobs` (V1 just leaves it; failed-jobs
+ *     handling is its own slice).
+ *   - `available_at` (timestamptz) — the earliest time a Worker may
+ *     pick this row up. `now()` for immediate dispatch; `dispatchLater`
+ *     pushes this into the future.
+ *   - `reserved_at` (timestamptz, nullable) — when a Worker locked
+ *     the row via `SELECT FOR UPDATE SKIP LOCKED`. NULL means
+ *     unreserved.
+ *   - `created_at` / `updated_at` — provided by `t.timestamps()`.
+ *
+ * Not `tenanted: true` — the queue is system-level. Multi-tenant apps
+ * that want per-tenant queues can clone this schema with a tenant_id
+ * FK + RLS, but that's a follow-up.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const jobSchema = defineSchema('strav_jobs', Archetype.Entity, (t) => {
+  t.id()
+  t.string('queue').max(64).default('default')
+  t.string('job_name').max(128)
+  t.json<unknown>('payload')
+  t.integer('attempts').default(0)
+  t.integer('max_attempts').default(3)
+  t.timestamp('available_at')
+  t.timestamp('reserved_at').nullable()
+  t.timestamps()
+})

package/src/queue.ts

@@ -0,0 +1,69 @@
+/**
+ * `Queue` — the contract every backend implements.
+ *
+ * V1 ships two: `SyncQueue` (in-process, no persistence — for tests +
+ * single-process dev) and `DatabaseQueue` (Postgres-backed, the
+ * production driver). Both implement this interface; apps depend on
+ * the abstract `Queue` symbol via DI.
+ *
+ * Method semantics:
+ *   - `dispatch(JobClass, payload, opts?)` — enqueue for a Worker to
+ *     pick up. Returns the assigned `jobId` (ULID).
+ *   - `dispatchLater(at, JobClass, payload, opts?)` — same as dispatch
+ *     but the row isn't picked up until `at`. `at` is either a `Date`
+ *     (absolute) or a number of seconds from now (relative).
+ *   - `dispatchSync(JobClass, payload)` — instantiate + run `handle()`
+ *     synchronously in the caller's process. No persistence, no
+ *     retries, no Worker required. Useful for tests, for dev mode,
+ *     and for callers that genuinely want the work done inline (rare
+ *     in production — most jobs exist precisely to defer work).
+ */
+
+import type { JobClass, PayloadOf } from './job.ts'
+
+export interface DispatchOptions {
+  /** Named queue to dispatch onto. Default: the JobClass's `static queue` or `'default'`. */
+  queue?: string
+  /**
+   * Override total attempts (including the first). Default: the
+   * JobClass's `static maxAttempts`, or the driver default (typically 3).
+   */
+  attempts?: number
+}
+
+export interface DispatchLaterOptions extends DispatchOptions {
+  // No additional options today; the slot exists so future drivers can
+  // grow it (e.g. `priority` or `deduplicationKey`) without breaking
+  // the call sites.
+}
+
+export interface Queue {
+  /** Enqueue immediately. Returns the assigned job id (ULID). */
+  dispatch<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    opts?: DispatchOptions,
+  ): Promise<string>
+
+  /**
+   * Enqueue with a delay. `at` is either a `Date` (absolute wall-clock
+   * time) or a positive number of seconds from now. Returns the
+   * assigned job id (ULID).
+   *
+   * `Date` values in the past are clamped to "now" — i.e. the job
+   * becomes immediately eligible. Negative numbers throw.
+   */
+  dispatchLater<TJob extends JobClass>(
+    at: Date | number,
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    opts?: DispatchLaterOptions,
+  ): Promise<string>
+
+  /**
+   * Run the job synchronously in the caller's process. No persistence,
+   * no retries — if `handle()` throws, the throw propagates. Returns
+   * when `handle()` resolves.
+   */
+  dispatchSync<TJob extends JobClass>(jobClass: TJob, payload: PayloadOf<TJob>): Promise<void>
+}

package/src/scheduler.ts

@@ -0,0 +1,271 @@
+/**
+ * `Scheduler` — recurring job dispatch on a cron cadence.
+ *
+ * Two surfaces:
+ *   - `.schedule(opts)` registers an entry (`{ job, cron, name?,
+ *     payload?, oneServer? }`). Returns `this` for chaining.
+ *   - `.tick(now)` processes every registered entry whose cron matches
+ *     `now`. Dispatches via the wired `Queue`. Exposed for tests +
+ *     one-shot CLI use.
+ *   - `.run(signal)` is the long-running loop — calls `tick()` at each
+ *     minute boundary, sleeps abort-aware between ticks.
+ *
+ * `oneServer: true` entries use `TenantManager.withLock` to acquire a
+ * fleet-wide advisory lock named after the entry. Inside the lock the
+ * dispatcher checks `strav_scheduler_runs.last_run_at` — if the
+ * current tick boundary already has a run recorded, this server skips
+ * (another server won). Otherwise dispatch + UPSERT atomically.
+ *
+ * `withLock` is built on `UnitOfWork.run`, which means
+ * `DatabaseQueue.dispatch` inside it auto-routes through the same
+ * transaction — the queue row INSERT + the run-tracking UPSERT commit
+ * together. A throw before COMMIT drops both. Exactly the
+ * queue-until-commit semantic from M2.
+ *
+ * Cron matching is UTC-based (see {@link CronExpression}). Apps that
+ * want local-time scheduling shift their schedule expressions; the
+ * Scheduler doesn't take a timezone option.
+ */
+
+import type { TenantManager } from '@strav/database'
+import { type Logger, ulid } from '@strav/kernel'
+import type { CronExpression } from './cron.ts'
+import type { JobClass } from './job.ts'
+import type { Queue } from './queue.ts'
+
+export interface ScheduleOptions {
+  /** Job to dispatch when the cron matches. */
+  job: JobClass
+  /** Payload handed to the Job. Default `undefined` → empty payload. */
+  payload?: unknown
+  /** Cron expression that gates the dispatch. */
+  cron: CronExpression
+  /**
+   * Identifier used for the advisory lock key + the
+   * `strav_scheduler_runs` row. Defaults to `job.jobName`.
+   * Specify when one job class is scheduled multiple times with
+   * different cadences / payloads, so each has its own lock + row.
+   */
+  name?: string
+  /**
+   * When `true`, only one server in the fleet dispatches per tick
+   * (advisory lock + run-tracking row). When `false` (default), every
+   * server dispatches independently — fine for jobs whose work is
+   * itself idempotent or which want fan-out semantics.
+   */
+  oneServer?: boolean
+}
+
+export interface SchedulerOptions {
+  /** Queue used to dispatch each entry's job. */
+  queue: Queue
+  /**
+   * TenantManager — used for its `withLock` + UoW combo on
+   * `oneServer` entries. `Scheduler` doesn't itself do tenancy; this
+   * is the most ergonomic primitive for "advisory lock + transaction
+   * + ambient ALS so dispatch joins the same tx."
+   */
+  tenants: TenantManager
+  /**
+   * Optional fallback executor used when an `oneServer: false` entry's
+   * dispatch raises. Only used to log the failure; the Queue itself
+   * already routes the SQL. Default: no-op logger.
+   */
+  logger?: Logger
+}
+
+interface ScheduledEntry {
+  name: string
+  cron: CronExpression
+  job: JobClass
+  payload: unknown
+  oneServer: boolean
+}
+
+export class Scheduler {
+  private readonly queue: Queue
+  private readonly tenants: TenantManager
+  private readonly logger: Logger
+  private readonly entries: ScheduledEntry[] = []
+
+  constructor(opts: SchedulerOptions) {
+    this.queue = opts.queue
+    this.tenants = opts.tenants
+    this.logger = opts.logger ?? createNoopLogger()
+  }
+
+  /** Register a recurring dispatch. Returns `this` for chaining. */
+  schedule(options: ScheduleOptions): this {
+    this.entries.push({
+      name: options.name ?? options.job.jobName,
+      cron: options.cron,
+      job: options.job,
+      payload: options.payload,
+      oneServer: options.oneServer ?? false,
+    })
+    return this
+  }
+
+  /** Every registered entry — exposed for inspection / tests. */
+  all(): readonly ScheduledEntry[] {
+    return [...this.entries]
+  }
+
+  /**
+   * Force-dispatch one named entry once, regardless of its cron expression.
+   * Useful for `bun strav scheduler:run <name>` — run an entry on demand
+   * without waiting for the next tick boundary.
+   *
+   * Honors `oneServer`: when set, the lock + run-tracking row still apply,
+   * so two `scheduler:run` invocations against the same name from
+   * different machines don't double-dispatch. The "tick boundary" used
+   * for run-tracking is `now` floored to the minute, the same convention
+   * `tick()` uses.
+   *
+   * Throws when `name` doesn't match any registered entry — silent failure
+   * here would be a footgun in a deploy script.
+   */
+  async runEntry(name: string, now: Date = new Date()): Promise<void> {
+    const entry = this.entries.find((e) => e.name === name)
+    if (!entry) {
+      throw new Error(
+        `Scheduler.runEntry("${name}"): no schedule with that name registered. ` +
+          `Known names: ${this.entries.map((e) => e.name).join(', ') || '(none)'}`,
+      )
+    }
+    if (entry.oneServer) {
+      await this.dispatchOneServer(entry, floorToMinute(now))
+    } else {
+      await this.queue.dispatch(entry.job, entry.payload as never)
+    }
+  }
+
+  /**
+   * Process every entry against `now`. The tick boundary is `now`
+   * floored to the start of its minute (seconds + millis cleared) —
+   * cron matches against that, and `oneServer` run-tracking writes
+   * that value into `strav_scheduler_runs.last_run_at`.
+   */
+  async tick(now: Date = new Date()): Promise<void> {
+    const boundary = floorToMinute(now)
+    for (const entry of this.entries) {
+      if (!entry.cron.matches(boundary)) continue
+      try {
+        if (entry.oneServer) {
+          await this.dispatchOneServer(entry, boundary)
+        } else {
+          await this.queue.dispatch(entry.job, entry.payload as never)
+        }
+      } catch (error) {
+        this.logger.error('Scheduler: dispatch failed', {
+          name: entry.name,
+          jobName: entry.job.jobName,
+          error,
+        })
+      }
+    }
+  }
+
+  /**
+   * Run the minute-tick loop until `signal` aborts. Each iteration
+   * sleeps until the next minute boundary, then calls `tick()`. The
+   * sleep is abort-aware — `signal.abort()` returns within one tick
+   * rather than waiting out the minute.
+   *
+   * On the FIRST iteration, sleeps to the next minute boundary
+   * BEFORE the first tick — so callers see one full minute pass
+   * between `run()` start and the first dispatch. (Calling `tick()`
+   * explicitly before `run()` is the way to dispatch immediately.)
+   */
+  async run(signal: AbortSignal): Promise<void> {
+    while (!signal.aborted) {
+      const now = new Date()
+      const nextBoundary = nextMinuteBoundary(now)
+      const sleepMs = Math.max(0, nextBoundary.getTime() - now.getTime())
+      await sleep(sleepMs, signal)
+      if (signal.aborted) return
+      try {
+        await this.tick(nextBoundary)
+      } catch (loopError) {
+        this.logger.error('Scheduler: tick iteration failed', { error: loopError })
+      }
+    }
+  }
+
+  private async dispatchOneServer(entry: ScheduledEntry, tickBoundary: Date): Promise<void> {
+    await this.tenants.withLock(`scheduler:${entry.name}`, async (tx) => {
+      const last = await tx.queryOne<{ last_run_at: Date }>(
+        `SELECT last_run_at FROM "strav_scheduler_runs" WHERE name = $1`,
+        [entry.name],
+      )
+      // The lock serializes the read+write window — if another server
+      // already recorded this tick boundary, skip cleanly.
+      if (last !== null && last.last_run_at.getTime() >= tickBoundary.getTime()) {
+        return
+      }
+      // Inside withLock's UoW, the dispatch routes through the ambient
+      // tx — the queue row INSERT + the run-tracking UPSERT commit
+      // atomically. If anything throws, both roll back.
+      await this.queue.dispatch(entry.job, entry.payload as never)
+      await tx.execute(
+        `INSERT INTO "strav_scheduler_runs" (id, name, last_run_at, created_at, updated_at)
+         VALUES ($1, $2, $3, now(), now())
+         ON CONFLICT (name) DO UPDATE
+           SET last_run_at = EXCLUDED.last_run_at, updated_at = now()`,
+        [ulid(), entry.name, tickBoundary],
+      )
+    })
+  }
+}
+
+/** Floor a Date to the start of its minute (seconds + millis cleared). */
+function floorToMinute(date: Date): Date {
+  return new Date(
+    Date.UTC(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+      date.getUTCHours(),
+      date.getUTCMinutes(),
+      0,
+      0,
+    ),
+  )
+}
+
+/** Next-minute boundary strictly after `date`. */
+function nextMinuteBoundary(date: Date): Date {
+  const floor = floorToMinute(date)
+  return new Date(floor.getTime() + 60_000)
+}
+
+/** Abort-aware sleep. */
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal.aborted) {
+      resolve()
+      return
+    }
+    const timer = setTimeout(resolve, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', onAbort)
+      resolve()
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/** No-op Logger — same shape as the ones in DatabaseQueue / Worker. */
+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
+}

package/src/scheduler_runs_schema.ts

@@ -0,0 +1,33 @@
+/**
+ * `strav_scheduler_runs` schema — tracks the last tick boundary at
+ * which a `Scheduler.onOneServer` entry dispatched.
+ *
+ * Why the table exists: `pg_advisory_xact_lock` releases on COMMIT —
+ * the lock is held only for the duration of the dispatch transaction
+ * (~10ms). Without a run-tracking row, two servers entering the lock
+ * block back-to-back at the start of the same minute would each see
+ * "cron matches now" and dispatch — double work.
+ *
+ * The check inside the lock block:
+ *   1. SELECT last_run_at WHERE name = $name.
+ *   2. If last_run_at >= tick_boundary, another server already won
+ *      this minute. Skip.
+ *   3. Otherwise dispatch + UPSERT last_run_at = tick_boundary.
+ *
+ * The advisory lock serializes the read+write so the check is honest.
+ *
+ * Schema constraints: framework PK kinds are `id`/`uuid`/`bigSerial`/
+ * `tenantedBigSerial`. None are text, so we can't make `name` itself
+ * the PK; instead ULID PK + `name` UNIQUE. The ULID is dead weight on
+ * the application side but keeps the row shape consistent with the
+ * rest of the framework.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const schedulerRunsSchema = defineSchema('strav_scheduler_runs', Archetype.Entity, (t) => {
+  t.id()
+  t.string('name').max(128).unique()
+  t.timestamp('last_run_at')
+  t.timestamps()
+})

package/src/sync_queue.ts

@@ -0,0 +1,126 @@
+/**
+ * `SyncQueue` — in-process synchronous Queue driver.
+ *
+ * Instantiates the Job via the container (so `@inject()` resolves
+ * dependencies the same way the real Worker would), builds a
+ * `JobContext`, runs `handle(ctx)`. No persistence, no retries — if
+ * the handler throws, the throw propagates to the dispatcher.
+ *
+ * Use cases:
+ *   - **Tests** — drive a job end-to-end without standing up a
+ *     `DatabaseQueue` + Worker.
+ *   - **Single-process dev** — flatten the Queue → Worker hop so
+ *     `bun dev` shows job output inline.
+ *   - **Inline-by-design** — rare in production, but callers that
+ *     genuinely want sync execution (e.g. an importer that's already
+ *     in a transaction) call `dispatchSync` directly.
+ *
+ * The non-sync methods (`dispatch` / `dispatchLater`) on this driver
+ * also run the work synchronously — they exist so the same code path
+ * works in both sync-only test setups and async-Worker production
+ * setups. `dispatchLater`'s delay is ignored under SyncQueue; the work
+ * runs immediately.
+ */
+
+import { type Container, type Logger, ulid } from '@strav/kernel'
+import type { JobClass, JobContext, PayloadOf } from './job.ts'
+import type { DispatchLaterOptions, DispatchOptions, Queue } from './queue.ts'
+
+export interface SyncQueueOptions {
+  /**
+   * Container used to construct Job instances. `make(JobClass)` builds
+   * via `@inject()` metadata, so subclasses with constructor deps get
+   * the same wiring the production Worker provides.
+   */
+  container: Container
+  /**
+   * Optional Logger to attach to every `JobContext.log`. When omitted,
+   * a no-op logger is used — useful in tests where log noise is
+   * unwelcome.
+   */
+  logger?: Logger
+}
+
+export class SyncQueue implements Queue {
+  private readonly container: Container
+  private readonly logger: Logger
+
+  constructor(opts: SyncQueueOptions) {
+    this.container = opts.container
+    this.logger = opts.logger ?? createNoopLogger()
+  }
+
+  async dispatch<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    _opts?: DispatchOptions,
+  ): Promise<string> {
+    const jobId = ulid()
+    await this.run(jobId, jobClass, payload)
+    return jobId
+  }
+
+  async dispatchLater<TJob extends JobClass>(
+    at: Date | number,
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+    _opts?: DispatchLaterOptions,
+  ): Promise<string> {
+    // Validate the delay even though we don't honor it — same contract
+    // surface as the production driver, so callers can't accidentally
+    // pass a negative delay that "works" under SyncQueue and fails on
+    // DatabaseQueue.
+    if (typeof at === 'number' && at < 0) {
+      throw new Error(`SyncQueue.dispatchLater: delay must be non-negative, got ${at}.`)
+    }
+    return this.dispatch(jobClass, payload)
+  }
+
+  async dispatchSync<TJob extends JobClass>(
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+  ): Promise<void> {
+    await this.run(ulid(), jobClass, payload)
+  }
+
+  private async run<TJob extends JobClass>(
+    jobId: string,
+    jobClass: TJob,
+    payload: PayloadOf<TJob>,
+  ): Promise<void> {
+    const job = this.container.make(jobClass)
+    const ctx: JobContext = {
+      jobId,
+      attempt: 1,
+      payload,
+      // SyncQueue runs to completion in one tick — abort isn't a thing
+      // here. We hand out a never-aborted signal so handlers written
+      // against the production contract don't need a separate code
+      // path.
+      signal: new AbortController().signal,
+      log: this.logger,
+    }
+    await job.handle(ctx)
+  }
+}
+
+/**
+ * Bare Logger that drops every call. Avoids pulling in the full
+ * LoggerProvider when callers just want SyncQueue in tests.
+ */
+function createNoopLogger(): Logger {
+  const noop = () => undefined
+  // The Logger contract is wider; the few methods downstream code may
+  // call are stubbed. Cast keeps the type signature honest at the
+  // boundary — Logger's full surface includes `child()` etc., which a
+  // future caller could exercise.
+  return {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    fatal: noop,
+    trace: noop,
+    child: () => createNoopLogger(),
+  } as unknown as Logger
+}