@lota-sdk/core 0.1.14 → 0.1.16

package/src/db/surreal-mutation.ts

@@ -0,0 +1,43 @@
+export type SurrealSetClause = { bindingEntries: Record<string, unknown>; statement: string }
+
+export function buildRequiredSurrealSetClause(field: string, bindingName: string, value: unknown): SurrealSetClause {
+  return { statement: `${field} = $${bindingName}`, bindingEntries: { [bindingName]: value } }
+}
+
+export function buildOptionalSurrealSetClause(field: string, value: unknown): SurrealSetClause
+export function buildOptionalSurrealSetClause(field: string, bindingName: string, value: unknown): SurrealSetClause
+export function buildOptionalSurrealSetClause(
+  field: string,
+  bindingNameOrValue: unknown,
+  value?: unknown,
+): SurrealSetClause {
+  const hasExplicitBinding = arguments.length === 3
+  const resolvedValue = hasExplicitBinding ? value : bindingNameOrValue
+  const resolvedBindingName = hasExplicitBinding
+    ? (bindingNameOrValue as string)
+    : `resource_${field.replace(/[^a-zA-Z0-9]+/g, '_')}`
+
+  if (resolvedValue === null || resolvedValue === undefined) {
+    return { statement: `${field} = NONE`, bindingEntries: {} }
+  }
+
+  return buildRequiredSurrealSetClause(field, resolvedBindingName, resolvedValue)
+}
+
+export function combineSurrealSetClauses(...clauses: SurrealSetClause[]): {
+  bindings: Record<string, unknown>
+  statement: string
+} {
+  const bindings: Record<string, unknown> = {}
+  for (const clause of clauses) {
+    for (const [key, value] of Object.entries(clause.bindingEntries)) {
+      bindings[key] = value
+    }
+  }
+
+  return { bindings, statement: clauses.map((clause) => clause.statement).join(', ') }
+}
+
+export function compactDefinedRecord<T extends Record<string, unknown>>(value: T): Partial<T> {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as Partial<T>
+}

package/src/db/tables.ts

@@ -17,11 +17,18 @@ export const TABLES = {
   PLAN_CHECKPOINT: 'planCheckpoint',
   PLAN_VALIDATION_ISSUE: 'planValidationIssue',
   PLAN_EVENT: 'planEvent',
+  PLAN_SCHEDULE: 'planSchedule',
+  PLAN_TEMPLATE: 'planTemplate',
+  PLAN_CYCLE: 'planCycle',
   ORGANIZATION: 'organization',
   ORGANIZATION_MEMBER: 'organizationMember',
   USER: 'user',
   RECENT_ACTIVITY_EVENT: 'recentActivityEvent',
   RECENT_ACTIVITY: 'recentActivity',
+  PLAYBOOK: 'playbook',
+  PLAYBOOK_VERSION: 'playbookVersion',
+  INSTITUTIONAL_MEMORY: 'institutionalMemory',
+  QUALITY_METRIC: 'qualityMetric',
 } as const
 
 export type DatabaseTable = (typeof TABLES)[keyof typeof TABLES] | (string & {})

package/src/db/workstream-message-row.ts

@@ -0,0 +1,15 @@
+import { recordIdSchema } from '@lota-sdk/shared'
+import { z } from 'zod'
+
+export const WorkstreamMessageRowSchema = z.object({
+  id: recordIdSchema,
+  workstreamId: recordIdSchema,
+  messageId: z.string(),
+  role: z.enum(['system', 'user', 'assistant']),
+  parts: z.array(z.record(z.string(), z.unknown())).optional(),
+  metadata: z.record(z.string(), z.unknown()).nullish(),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date().optional(),
+})
+
+export type WorkstreamMessageRow = z.infer<typeof WorkstreamMessageRowSchema>

package/src/embeddings/provider.ts

@@ -71,7 +71,7 @@ export class ProviderEmbeddings {
     const redisCache = this.getCache()
     if (!redisCache) return null
 
-    return await redisCache.get(this.getModelId(), text)
+    return redisCache.get(this.getModelId(), text)
   }
 
   async embedQuery(text: string): Promise<number[]> {

package/src/index.ts

@@ -1,4 +1,4 @@
-export * from './runtime'
+export * from './create-runtime'
 export * from './ai'
 export * from './bifrost'
 export * from './config'

package/src/queues/context-compaction.queue.ts

@@ -1,20 +1,11 @@
-import { Queue, Worker } from 'bullmq'
 import type { Job } from 'bullmq'
 
-import { serverLogger } from '../config/logger'
 import { ensureRecordId } from '../db/record-id'
 import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
-import { getRedisConnectionForBullMQ } from '../redis'
 import { contextCompactionService } from '../services/context-compaction.service'
 import { workstreamService } from '../services/workstream.service'
-import {
-  attachWorkerEvents,
-  createTracedWorkerProcessor,
-  createWorkerShutdown,
-  registerShutdownSignals,
-} from '../workers/worker-utils'
-import type { WorkerHandle } from '../workers/worker-utils'
+import { createQueueFactory } from './queue-factory'
 
 interface ContextCompactionJob {
   domain: 'workstream'
@@ -22,61 +13,35 @@ interface ContextCompactionJob {
   contextSize?: number
 }
 
-const CONTEXT_COMPACTION_QUEUE = 'context-compaction'
-
-let _contextCompactionQueue: Queue<ContextCompactionJob> | null = null
-function getContextCompactionQueue(): Queue<ContextCompactionJob> {
-  if (!_contextCompactionQueue) {
-    _contextCompactionQueue = new Queue<ContextCompactionJob>(CONTEXT_COMPACTION_QUEUE, {
-      connection: getRedisConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 200,
-        removeOnFail: 200,
-        attempts: 2,
-        backoff: { type: 'exponential', delay: 3_000 },
-      },
-    })
-  }
-  return _contextCompactionQueue
-}
-
-export async function enqueueContextCompaction(job: ContextCompactionJob) {
-  return await getContextCompactionQueue().add('compact', job, {
-    deduplication: { id: `compact:${job.domain}:${job.entityId}` },
-  })
-}
-
 async function processContextCompactionJob(job: Job<ContextCompactionJob>): Promise<void> {
   await databaseService.connect()
 
   const { entityId, contextSize } = job.data
   const workstreamRef = ensureRecordId(entityId, TABLES.WORKSTREAM)
-  await workstreamService.setCompacting(workstreamRef, true)
+  await workstreamService.markCompacting(workstreamRef)
   try {
     await contextCompactionService.compactWorkstreamHistory({ workstreamId: workstreamRef, contextSize })
   } finally {
-    await workstreamService.setCompacting(workstreamRef, false)
+    await workstreamService.clearCompacting(workstreamRef)
   }
 }
 
-export function startContextCompactionWorker(options: { registerSignals?: boolean } = {}): WorkerHandle {
-  const { registerSignals = import.meta.main } = options
-  const worker = new Worker(
-    CONTEXT_COMPACTION_QUEUE,
-    createTracedWorkerProcessor(CONTEXT_COMPACTION_QUEUE, processContextCompactionJob),
-    { connection: getRedisConnectionForBullMQ(), concurrency: 2, lockDuration: 300_000 },
-  )
-
-  attachWorkerEvents(worker, 'Context compaction', serverLogger)
-  const shutdown = createWorkerShutdown(worker, 'Context compaction', serverLogger)
-
-  if (registerSignals) {
-    registerShutdownSignals({ name: 'Context compaction', shutdown, logger: serverLogger })
-  }
-
-  return { worker, shutdown }
+const contextCompaction = createQueueFactory<ContextCompactionJob>({
+  name: 'context-compaction',
+  displayName: 'Context compaction',
+  jobName: 'compact',
+  concurrency: 2,
+  lockDuration: 300_000,
+  defaultJobOptions: { attempts: 2, backoff: { type: 'exponential', delay: 3_000 } },
+  processor: processContextCompactionJob,
+})
+
+export function enqueueContextCompaction(job: ContextCompactionJob) {
+  return contextCompaction.enqueue(job, { deduplication: { id: `compact:${job.domain}:${job.entityId}` } })
 }
 
+export const startContextCompactionWorker = contextCompaction.startWorker
+
 if (import.meta.main) {
   startContextCompactionWorker()
 }

package/src/queues/delayed-node-promotion.queue.ts

@@ -0,0 +1,41 @@
+import type { Job } from 'bullmq'
+
+import { databaseService } from '../db/service'
+import { planExecutorService } from '../services/plan-executor.service'
+import { createQueueFactory } from './queue-factory'
+
+export interface DelayedNodePromotionJob {
+  runId: string
+  nodeId: string
+  emittedBy: string
+}
+
+export const DELAYED_NODE_PROMOTION_QUEUE = 'delayed-node-promotion'
+
+async function processDelayedNodePromotionJob(job: Job<DelayedNodePromotionJob>): Promise<void> {
+  await databaseService.connect()
+  await planExecutorService.promoteDelayedNode({
+    runId: job.data.runId,
+    nodeId: job.data.nodeId,
+    emittedBy: job.data.emittedBy,
+  })
+}
+
+const delayedNodePromotion = createQueueFactory<DelayedNodePromotionJob>({
+  name: DELAYED_NODE_PROMOTION_QUEUE,
+  displayName: 'Delayed node promotion',
+  jobName: 'promote-node',
+  concurrency: 1,
+  defaultJobOptions: { attempts: 3, backoff: { type: 'exponential', delay: 5000 } },
+  processor: processDelayedNodePromotionJob,
+})
+
+export async function enqueueDelayedNodePromotion(job: DelayedNodePromotionJob, delayMs: number) {
+  await delayedNodePromotion.enqueue(job, { delay: delayMs, jobId: `promote:${job.runId}:${job.nodeId}` })
+}
+
+export const startDelayedNodePromotionWorker = delayedNodePromotion.startWorker
+
+if (import.meta.main) {
+  startDelayedNodePromotionWorker()
+}

package/src/queues/document-processor.queue.ts

@@ -4,7 +4,12 @@ import { Queue, Worker } from 'bullmq'
 import type IORedis from 'ioredis'
 
 import type { chatLogger } from '../config/logger'
-import { attachWorkerEvents, createWorkerShutdown, registerShutdownSignals } from '../workers/worker-utils'
+import {
+  attachWorkerEvents,
+  createWorkerShutdown,
+  DEFAULT_JOB_RETENTION,
+  registerShutdownSignals,
+} from '../workers/worker-utils'
 import type { WorkerHandle } from '../workers/worker-utils'
 
 export type DocumentSourceChannel = string
@@ -82,12 +87,7 @@ export function createDocumentProcessorQueueRuntime<TJob extends DocumentProcess
 
     queue = new Queue<TJob, unknown, string>(queueName, {
       connection: params.getConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 200,
-        removeOnFail: 200,
-        attempts: 3,
-        backoff: { type: 'exponential', delay: 1000 },
-      },
+      defaultJobOptions: { ...DEFAULT_JOB_RETENTION, attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
     })
 
     return queue

package/src/queues/index.ts

@@ -1,6 +1,9 @@
+export * from './queue-factory'
 export * from './context-compaction.queue'
+export * from './delayed-node-promotion.queue'
 export * from './document-processor.queue'
 export * from './memory-consolidation.queue'
+export * from './plan-scheduler.queue'
 export * from './post-chat-memory.queue'
 export * from './recent-activity-title-refinement.queue'
 export * from './regular-chat-memory-digest.config'

package/src/queues/memory-consolidation.queue.ts

@@ -1,70 +1,34 @@
-import { Queue, Worker } from 'bullmq'
-
-import { serverLogger } from '../config/logger'
-import { getRedisConnectionForBullMQ } from '../redis'
-import {
-  attachWorkerEvents,
-  getWorkerPath,
-  createWorkerShutdown,
-  registerShutdownSignals,
-} from '../workers/worker-utils'
-import type { WorkerHandle } from '../workers/worker-utils'
+import { getWorkerPath, LONG_JOB_LOCK_DURATION_MS, LOW_JOB_RETENTION } from '../workers/worker-utils'
+import { createQueueFactory } from './queue-factory'
 
 export interface MemoryConsolidationJob {
   scopeId?: string
 }
 
-const MEMORY_CONSOLIDATION_QUEUE = 'memory-consolidation'
+const MEMORY_CONSOLIDATION_INTERVAL_MS = 24 * 60 * 60 * 1000
+const MEMORY_CONSOLIDATION_JOB_ID = 'memory-consolidation-recurring'
 
-let _memoryConsolidationQueue: Queue<MemoryConsolidationJob> | null = null
-function getMemoryConsolidationQueue(): Queue<MemoryConsolidationJob> {
-  if (!_memoryConsolidationQueue) {
-    _memoryConsolidationQueue = new Queue<MemoryConsolidationJob>(MEMORY_CONSOLIDATION_QUEUE, {
-      connection: getRedisConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 50,
-        removeOnFail: 50,
-        attempts: 2,
-        backoff: { type: 'exponential', delay: 5000 },
-      },
-    })
-  }
-  return _memoryConsolidationQueue
-}
+const memoryConsolidation = createQueueFactory<MemoryConsolidationJob>({
+  name: 'memory-consolidation',
+  displayName: 'Memory consolidation',
+  jobName: 'consolidate-turn',
+  concurrency: 1,
+  lockDuration: LONG_JOB_LOCK_DURATION_MS,
+  defaultJobOptions: { ...LOW_JOB_RETENTION, attempts: 2, backoff: { type: 'exponential', delay: 5000 } },
+  processorPath: getWorkerPath('memory-consolidation.worker.ts'),
+})
 
 export async function enqueueMemoryConsolidation(job: MemoryConsolidationJob = {}) {
-  await getMemoryConsolidationQueue().add('consolidate-turn', job, {
-    jobId: job.scopeId ? `consolidate-turn:${job.scopeId}` : undefined,
-  })
+  await memoryConsolidation.enqueue(job, { jobId: job.scopeId ? `consolidate-turn:${job.scopeId}` : undefined })
 }
 
 export async function scheduleRecurringConsolidation() {
-  await getMemoryConsolidationQueue().add(
-    'consolidate',
-    {},
-    { repeat: { every: 24 * 60 * 60 * 1000 }, jobId: 'memory-consolidation-recurring' },
-  )
+  await memoryConsolidation
+    .getQueue()
+    .add('consolidate', {}, { repeat: { every: MEMORY_CONSOLIDATION_INTERVAL_MS }, jobId: MEMORY_CONSOLIDATION_JOB_ID })
 }
 
-export function startMemoryConsolidationWorker(options: { registerSignals?: boolean } = {}): WorkerHandle {
-  const { registerSignals = import.meta.main } = options
-  const processorPath = getWorkerPath('memory-consolidation.worker.ts')
-  const worker = new Worker(MEMORY_CONSOLIDATION_QUEUE, processorPath, {
-    connection: getRedisConnectionForBullMQ(),
-    lockDuration: 600_000,
-    concurrency: 1,
-  })
-
-  attachWorkerEvents(worker, 'Memory consolidation', serverLogger)
-
-  const shutdown = createWorkerShutdown(worker, 'Memory consolidation', serverLogger)
-
-  if (registerSignals) {
-    registerShutdownSignals({ name: 'Memory consolidation', shutdown, logger: serverLogger })
-  }
-
-  return { worker, shutdown }
-}
+export const startMemoryConsolidationWorker = memoryConsolidation.startWorker
 
 if (import.meta.main) {
   startMemoryConsolidationWorker()

package/src/queues/plan-scheduler.queue.ts

@@ -0,0 +1,97 @@
+import type { Job } from 'bullmq'
+
+import { serverLogger } from '../config/logger'
+import { databaseService } from '../db/service'
+import { planDeadlineService } from '../services/plan-deadline.service'
+import { planSchedulerService } from '../services/plan-scheduler.service'
+import type { WorkerHandle } from '../workers/worker-utils'
+import { createQueueFactory } from './queue-factory'
+
+export interface PlanSchedulerFireJob {
+  type: 'fire-schedule'
+  scheduleId: string
+}
+
+export interface PlanSchedulerDeadlineJob {
+  type: 'check-deadlines'
+  scheduledFor?: string
+}
+
+export type PlanSchedulerJob = PlanSchedulerFireJob | PlanSchedulerDeadlineJob
+
+export const PLAN_SCHEDULER_QUEUE = 'plan-scheduler'
+
+async function processPlanSchedulerJob(job: Job<PlanSchedulerJob>): Promise<void> {
+  await databaseService.connect()
+
+  switch (job.data.type) {
+    case 'fire-schedule':
+      await planSchedulerService.fireScheduleById(job.data.scheduleId)
+      break
+    case 'check-deadlines':
+      await planDeadlineService.checkDeadlines()
+      break
+  }
+}
+
+const planScheduler = createQueueFactory<PlanSchedulerJob>({
+  name: PLAN_SCHEDULER_QUEUE,
+  displayName: 'Plan scheduler',
+  jobName: 'plan-scheduler-job',
+  concurrency: 1,
+  defaultJobOptions: { attempts: 3, backoff: { type: 'exponential', delay: 5000 } },
+  processor: processPlanSchedulerJob,
+})
+
+/** Enqueue a delayed job that fires a specific schedule at its nextFireAt time. */
+export async function enqueueScheduleFire(scheduleId: string, delayMs: number): Promise<void> {
+  await planScheduler.enqueue(
+    { type: 'fire-schedule', scheduleId },
+    { delay: Math.max(0, delayMs), jobId: `schedule:${scheduleId}`, removeOnComplete: true, removeOnFail: 50 },
+  )
+}
+
+/** Remove a pending fire job for a schedule (on cancel/pause/complete). */
+export async function removeScheduleFireJob(scheduleId: string): Promise<void> {
+  try {
+    await planScheduler.getQueue().remove(`schedule:${scheduleId}`)
+  } catch {
+    // Job may not exist (already fired or never enqueued) — safe to ignore
+  }
+}
+
+const DEADLINE_CHECK_JOB_PREFIX = 'deadline-check'
+
+export async function enqueueDeadlineCheck(scheduledFor: Date): Promise<void> {
+  const delay = Math.max(0, scheduledFor.getTime() - Date.now())
+  await planScheduler.enqueue(
+    { type: 'check-deadlines', scheduledFor: scheduledFor.toISOString() },
+    {
+      delay,
+      jobId: `${DEADLINE_CHECK_JOB_PREFIX}:${scheduledFor.getTime()}`,
+      removeOnComplete: true,
+      removeOnFail: 50,
+    },
+  )
+}
+
+export function startPlanSchedulerWorker(options: { registerSignals?: boolean } = {}): WorkerHandle {
+  const handle = planScheduler.startWorker(options)
+
+  // Recover active schedules on startup
+  planSchedulerService.recoverActiveSchedules().catch((err: unknown) => {
+    serverLogger.error`Plan scheduler startup recovery failed: ${err}`
+  })
+
+  // Seed deadline checks from current runtime state. Subsequent checks are
+  // re-seeded by the queue job after each sweep and by schedule fire events.
+  planDeadlineService.recoverDeadlineChecks().catch((err: unknown) => {
+    serverLogger.error`Plan deadline recovery failed: ${err}`
+  })
+
+  return handle
+}
+
+if (import.meta.main) {
+  startPlanSchedulerWorker()
+}

package/src/queues/post-chat-memory.queue.ts

@@ -1,18 +1,9 @@
 type OrganizationOnboardStatus = string
-import { Queue, Worker } from 'bullmq'
 import type { Job } from 'bullmq'
 
-import { serverLogger } from '../config/logger'
 import { databaseService } from '../db/service'
-import { getRedisConnectionForBullMQ } from '../redis'
 import { memoryService } from '../services/memory.service'
-import {
-  attachWorkerEvents,
-  createTracedWorkerProcessor,
-  createWorkerShutdown,
-  registerShutdownSignals,
-} from '../workers/worker-utils'
-import type { WorkerHandle } from '../workers/worker-utils'
+import { createQueueFactory } from './queue-factory'
 
 interface PostChatMemoryMessage {
   role: 'user' | 'agent'
@@ -32,32 +23,6 @@ interface PostChatMemoryExtractionJob {
   attachmentContext?: string
 }
 
-const POST_CHAT_MEMORY_QUEUE = 'post-chat-memory'
-const POST_CHAT_MEMORY_CONCURRENCY = 3
-const POST_CHAT_MEMORY_LOCK_DURATION_MS = 900_000
-const POST_CHAT_MEMORY_MAX_STALLED_COUNT = 10
-const POST_CHAT_MEMORY_STALLED_INTERVAL_MS = 120_000
-
-let _postChatMemoryQueue: Queue<PostChatMemoryExtractionJob> | null = null
-function getPostChatMemoryQueue(): Queue<PostChatMemoryExtractionJob> {
-  if (!_postChatMemoryQueue) {
-    _postChatMemoryQueue = new Queue<PostChatMemoryExtractionJob>(POST_CHAT_MEMORY_QUEUE, {
-      connection: getRedisConnectionForBullMQ(),
-      defaultJobOptions: {
-        removeOnComplete: 200,
-        removeOnFail: 200,
-        attempts: 3,
-        backoff: { type: 'exponential', delay: 2_000 },
-      },
-    })
-  }
-  return _postChatMemoryQueue
-}
-
-export async function enqueuePostChatMemory(job: PostChatMemoryExtractionJob) {
-  return await getPostChatMemoryQueue().add('extract-memory', job)
-}
-
 async function processPostChatMemoryJob(job: Job<PostChatMemoryExtractionJob>): Promise<void> {
   await databaseService.connect()
 
@@ -98,30 +63,20 @@ async function processPostChatMemoryJob(job: Job<PostChatMemoryExtractionJob>):
   })
 }
 
-export function startPostChatMemoryWorker(options: { registerSignals?: boolean } = {}): WorkerHandle {
-  const { registerSignals = import.meta.main } = options
-  const worker = new Worker(
-    POST_CHAT_MEMORY_QUEUE,
-    createTracedWorkerProcessor(POST_CHAT_MEMORY_QUEUE, processPostChatMemoryJob),
-    {
-      connection: getRedisConnectionForBullMQ(),
-      concurrency: POST_CHAT_MEMORY_CONCURRENCY,
-      lockDuration: POST_CHAT_MEMORY_LOCK_DURATION_MS,
-      maxStalledCount: POST_CHAT_MEMORY_MAX_STALLED_COUNT,
-      stalledInterval: POST_CHAT_MEMORY_STALLED_INTERVAL_MS,
-    },
-  )
-
-  attachWorkerEvents(worker, 'Post-chat memory', serverLogger)
-
-  const shutdown = createWorkerShutdown(worker, 'Post-chat memory', serverLogger)
-
-  if (registerSignals) {
-    registerShutdownSignals({ name: 'Post-chat memory', shutdown, logger: serverLogger })
-  }
-
-  return { worker, shutdown }
-}
+const postChatMemory = createQueueFactory<PostChatMemoryExtractionJob>({
+  name: 'post-chat-memory',
+  displayName: 'Post-chat memory',
+  jobName: 'extract-memory',
+  concurrency: 3,
+  lockDuration: 900_000,
+  maxStalledCount: 10,
+  stalledInterval: 120_000,
+  defaultJobOptions: { attempts: 3, backoff: { type: 'exponential', delay: 2_000 } },
+  processor: processPostChatMemoryJob,
+})
+
+export const enqueuePostChatMemory = postChatMemory.enqueue
+export const startPostChatMemoryWorker = postChatMemory.startWorker
 
 if (import.meta.main) {
   startPostChatMemoryWorker()

package/src/queues/queue-factory.ts

@@ -0,0 +1,100 @@
+import { Queue, Worker } from 'bullmq'
+import type { Job, JobsOptions, WorkerOptions } from 'bullmq'
+import type IORedis from 'ioredis'
+
+import { serverLogger } from '../config/logger'
+import { getRedisConnectionForBullMQ } from '../redis'
+import {
+  attachWorkerEvents,
+  createTracedWorkerProcessor,
+  createWorkerShutdown,
+  DEFAULT_JOB_RETENTION,
+  registerShutdownSignals,
+} from '../workers/worker-utils'
+import type { WorkerHandle } from '../workers/worker-utils'
+
+interface QueueFactoryConfigBase {
+  name: string
+  displayName: string
+  jobName: string
+  concurrency: number
+  lockDuration?: number
+  stalledInterval?: number
+  maxStalledCount?: number
+  defaultJobOptions?: JobsOptions
+  connectionProvider?: () => IORedis
+}
+
+interface QueueFactoryConfigInline<TJob> extends QueueFactoryConfigBase {
+  processor: (job: Job<TJob>) => Promise<void>
+  processorPath?: never
+}
+
+interface QueueFactoryConfigFile extends QueueFactoryConfigBase {
+  processor?: never
+  processorPath: string
+}
+
+export type QueueFactoryConfig<TJob> = QueueFactoryConfigInline<TJob> | QueueFactoryConfigFile
+
+export interface QueueFactory<TJob> {
+  getQueue: () => Queue<TJob, unknown, string>
+  enqueue: (job: TJob, options?: JobsOptions) => Promise<void>
+  startWorker: (options?: { registerSignals?: boolean }) => WorkerHandle
+}
+
+export function createQueueFactory<TJob>(config: QueueFactoryConfig<TJob>): QueueFactory<TJob> {
+  let _queue: Queue<TJob, unknown, string> | null = null
+
+  const getConnection = () => config.connectionProvider?.() ?? getRedisConnectionForBullMQ()
+
+  const getQueue = (): Queue<TJob, unknown, string> => {
+    if (!_queue) {
+      _queue = new Queue<TJob, unknown, string>(config.name, {
+        connection: getConnection(),
+        defaultJobOptions: { ...DEFAULT_JOB_RETENTION, ...config.defaultJobOptions },
+      })
+    }
+    return _queue
+  }
+
+  type QueueAdd = Queue<TJob, unknown, string>['add']
+  const jobName = config.jobName as Parameters<QueueAdd>[0]
+  const toData = (job: TJob) => job as Parameters<QueueAdd>[1]
+
+  const enqueue = async (job: TJob, options?: JobsOptions): Promise<void> => {
+    await getQueue().add(jobName, toData(job), options)
+  }
+
+  const startWorker = (options: { registerSignals?: boolean } = {}): WorkerHandle => {
+    const { registerSignals = import.meta.main } = options
+
+    const workerOptions: WorkerOptions = {
+      connection: getConnection(),
+      concurrency: config.concurrency,
+      ...(config.lockDuration !== undefined ? { lockDuration: config.lockDuration } : {}),
+      ...(config.stalledInterval !== undefined ? { stalledInterval: config.stalledInterval } : {}),
+      ...(config.maxStalledCount !== undefined ? { maxStalledCount: config.maxStalledCount } : {}),
+    }
+
+    const worker = config.processorPath
+      ? new Worker(config.name, config.processorPath, workerOptions)
+      : new Worker(
+          config.name,
+          createTracedWorkerProcessor(config.name, (config as QueueFactoryConfigInline<TJob>).processor),
+          workerOptions,
+        )
+
+    attachWorkerEvents(worker, config.displayName, serverLogger)
+
+    const shutdown = createWorkerShutdown(worker, config.displayName, serverLogger)
+
+    if (registerSignals) {
+      registerShutdownSignals({ name: config.displayName, shutdown, logger: serverLogger })
+    }
+
+    return { worker, shutdown }
+  }
+
+  return { getQueue, enqueue, startWorker }
+}