@lota-sdk/core 0.4.13 → 0.4.14

package/src/effect/errors.ts

@@ -4,65 +4,186 @@ const ValidationIssueSchema = Schema.Struct({ path: Schema.String, message: Sche
 
 export type ValidationIssue = typeof ValidationIssueSchema.Type
 
-export class DatabaseError extends Schema.TaggedErrorClass<DatabaseError>()('DatabaseError', {
+/**
+ * Single source of truth for every Effect tagged-error `_tag` value in the
+ * SDK. Referenced by:
+ *   - `Schema.TaggedErrorClass<X>()(ERROR_TAGS.X, ...)` at definition time,
+ *   - `Match.tag(ERROR_TAGS.X, ...)` / `Effect.catchTag(ERROR_TAGS.X, ...)` /
+ *     `Effect.catchTags({ [ERROR_TAGS.X]: ... })` at consumer sites,
+ *   - `isBaseServicePersistenceError` / any `_tag === ...` compare.
+ *
+ * Using these constants instead of literal strings prevents typos breaking
+ * catchTag pattern-matching and ensures tag renames stay in lockstep with
+ * consumers.
+ */
+export const ERROR_TAGS = {
+  ActiveThreadRunConflictError: '@lota-sdk/core/ActiveThreadRunConflictError',
+  AgentExecutorError: '@lota-sdk/core/AgentExecutorError',
+  AiGenerationError: '@lota-sdk/core/AiGenerationError',
+  AttachmentParserError: '@lota-sdk/core/AttachmentParserError',
+  AttachmentStorageError: '@lota-sdk/core/AttachmentStorageError',
+  BadRequestError: '@lota-sdk/core/BadRequestError',
+  BaseServicePersistenceError: '@lota-sdk/core/BaseServicePersistenceError',
+  CompactionError: '@lota-sdk/core/CompactionError',
+  CompactionParseError: '@lota-sdk/core/CompactionParseError',
+  ConfigurationError: '@lota-sdk/core/ConfigurationError',
+  ConflictError: '@lota-sdk/core/ConflictError',
+  ContextCompactionRuntimeError: '@lota-sdk/core/ContextCompactionRuntimeError',
+  CursorPaginationError: '@lota-sdk/core/CursorPaginationError',
+  DatabaseError: '@lota-sdk/core/DatabaseError',
+  DelegatedAgentError: '@lota-sdk/core/DelegatedAgentError',
+  EmbeddingCacheError: '@lota-sdk/core/EmbeddingCacheError',
+  EmbeddingProviderError: '@lota-sdk/core/EmbeddingProviderError',
+  ExecutionPlanCacheError: '@lota-sdk/core/ExecutionPlanCacheError',
+  FeedbackLoopServiceError: '@lota-sdk/core/FeedbackLoopServiceError',
+  ForbiddenError: '@lota-sdk/core/ForbiddenError',
+  GeneratedDocumentStorageError: '@lota-sdk/core/GeneratedDocumentStorageError',
+  InvalidAgentNameError: '@lota-sdk/core/InvalidAgentNameError',
+  LearnedSkillNotFoundError: '@lota-sdk/core/LearnedSkillNotFoundError',
+  LearnedSkillServiceError: '@lota-sdk/core/LearnedSkillServiceError',
+  LockAcquisitionError: '@lota-sdk/core/LockAcquisitionError',
+  LockLostError: '@lota-sdk/core/LockLostError',
+  MemoryBlockCompactError: '@lota-sdk/core/MemoryBlockCompactError',
+  MemoryConsolidationError: '@lota-sdk/core/MemoryConsolidationError',
+  MemoryDigestError: '@lota-sdk/core/MemoryDigestError',
+  MemoryRerankError: '@lota-sdk/core/MemoryRerankError',
+  MemoryScopeError: '@lota-sdk/core/MemoryScopeError',
+  MemoryServiceError: '@lota-sdk/core/MemoryServiceError',
+  MemoryStoreError: '@lota-sdk/core/MemoryStoreError',
+  NotFoundError: '@lota-sdk/core/NotFoundError',
+  OrgMemoryLockCallbackError: '@lota-sdk/core/OrgMemoryLockCallbackError',
+  OrganizationMemberServiceError: '@lota-sdk/core/OrganizationMemberServiceError',
+  OrganizationServiceError: '@lota-sdk/core/OrganizationServiceError',
+  PlanAgentHeartbeatError: '@lota-sdk/core/PlanAgentHeartbeatError',
+  PlanAgentQueryError: '@lota-sdk/core/PlanAgentQueryError',
+  PlanCoordinationError: '@lota-sdk/core/PlanCoordinationError',
+  PlanCycleNotFoundError: '@lota-sdk/core/PlanCycleNotFoundError',
+  PlanDeadlineError: '@lota-sdk/core/PlanDeadlineError',
+  PlanEventDeliveryError: '@lota-sdk/core/PlanEventDeliveryError',
+  PlanExecutorGraphError: '@lota-sdk/core/PlanExecutorGraphError',
+  PlanExecutorInternalError: '@lota-sdk/core/PlanExecutorInternalError',
+  PlanRunNotFoundError: '@lota-sdk/core/PlanRunNotFoundError',
+  PlanRunServiceError: '@lota-sdk/core/PlanRunServiceError',
+  PlanScheduleAttachError: '@lota-sdk/core/PlanScheduleAttachError',
+  PlanSchedulerError: '@lota-sdk/core/PlanSchedulerError',
+  PlanSchedulerQueueError: '@lota-sdk/core/PlanSchedulerQueueError',
+  PluginResolutionError: '@lota-sdk/core/PluginResolutionError',
+  PostTurnSideEffectsError: '@lota-sdk/core/PostTurnSideEffectsError',
+  QueueFactoryError: '@lota-sdk/core/QueueFactoryError',
+  QueueWorkerError: '@lota-sdk/core/QueueWorkerError',
+  ReadFilePartsError: '@lota-sdk/core/ReadFilePartsError',
+  RedisError: '@lota-sdk/core/RedisError',
+  RerankServiceError: '@lota-sdk/core/RerankServiceError',
+  RuntimeLifecycleError: '@lota-sdk/core/RuntimeLifecycleError',
+  SandboxedWorkerBootstrapError: '@lota-sdk/core/SandboxedWorkerBootstrapError',
+  SchemaFingerprintError: '@lota-sdk/core/SchemaFingerprintError',
+  ScopedRetrievalError: '@lota-sdk/core/ScopedRetrievalError',
+  SearchWebToolError: '@lota-sdk/core/SearchWebToolError',
+  ServiceError: '@lota-sdk/core/ServiceError',
+  SharedSubscriberCloseError: '@lota-sdk/core/SharedSubscriberCloseError',
+  SocialChatAgentRunnerError: '@lota-sdk/core/SocialChatAgentRunnerError',
+  SocialChatHistoryError: '@lota-sdk/core/SocialChatHistoryError',
+  SocialChatServiceError: '@lota-sdk/core/SocialChatServiceError',
+  SpecialistRunnerError: '@lota-sdk/core/SpecialistRunnerError',
+  StandaloneQueueWorkerError: '@lota-sdk/core/StandaloneQueueWorkerError',
+  SseKeepaliveError: '@lota-sdk/core/SseKeepaliveError',
+  SurrealDBError: '@lota-sdk/core/SurrealDBError',
+  TeamConsultationError: '@lota-sdk/core/TeamConsultationError',
+  TeamThinkAgentFactoryNotConfiguredError: '@lota-sdk/core/TeamThinkAgentFactoryNotConfiguredError',
+  TeamThinkRuntimeError: '@lota-sdk/core/TeamThinkRuntimeError',
+  ThreadListingError: '@lota-sdk/core/ThreadListingError',
+  ThreadMemoryBlockError: '@lota-sdk/core/ThreadMemoryBlockError',
+  ThreadMessageQueryError: '@lota-sdk/core/ThreadMessageQueryError',
+  ThreadTitleError: '@lota-sdk/core/ThreadTitleError',
+  ThreadTurnContextError: '@lota-sdk/core/ThreadTurnContextError',
+  ThreadTurnError: '@lota-sdk/core/ThreadTurnError',
+  ThreadTurnPreparationError: '@lota-sdk/core/ThreadTurnPreparationError',
+  ThreadTurnServiceError: '@lota-sdk/core/ThreadTurnServiceError',
+  ThreadTurnStreamingError: '@lota-sdk/core/ThreadTurnStreamingError',
+  TimedOperationError: '@lota-sdk/core/TimedOperationError',
+  TimeoutError: '@lota-sdk/core/TimeoutError',
+  TurnLifecycleError: '@lota-sdk/core/TurnLifecycleError',
+  UserServiceError: '@lota-sdk/core/UserServiceError',
+  ValidationError: '@lota-sdk/core/ValidationError',
+  WaitForCompactionError: '@lota-sdk/core/WaitForCompactionError',
+} as const
+
+type ErrorTag = (typeof ERROR_TAGS)[keyof typeof ERROR_TAGS]
+
+export class DatabaseError extends Schema.TaggedErrorClass<DatabaseError>()(ERROR_TAGS.DatabaseError, {
   message: Schema.String,
   query: Schema.optional(Schema.String),
   cause: Schema.optional(Schema.Defect),
 }) {}
 
-export class ServiceError extends Schema.TaggedErrorClass<ServiceError>()('ServiceError', {
+export class ServiceError extends Schema.TaggedErrorClass<ServiceError>()(ERROR_TAGS.ServiceError, {
   message: Schema.String,
   cause: Schema.optional(Schema.Defect),
 }) {}
 
 export class BaseServicePersistenceError extends Schema.TaggedErrorClass<BaseServicePersistenceError>()(
-  'BaseServicePersistenceError',
+  ERROR_TAGS.BaseServicePersistenceError,
   { message: Schema.String, cause: Schema.Defect },
 ) {}
 
-export class RedisError extends Schema.TaggedErrorClass<RedisError>()('RedisError', {
+export class RedisError extends Schema.TaggedErrorClass<RedisError>()(ERROR_TAGS.RedisError, {
   message: Schema.String,
   cause: Schema.optional(Schema.Defect),
 }) {}
 
-export class TimeoutError extends Schema.TaggedErrorClass<TimeoutError>()('TimeoutError', {
+export class RuntimeLifecycleError extends Schema.TaggedErrorClass<RuntimeLifecycleError>()(
+  ERROR_TAGS.RuntimeLifecycleError,
+  {
+    operation: Schema.Literals([
+      'connect-plugin-database',
+      'disconnect-plugin-database',
+      'shutdown-social-chat',
+      'disconnect-plugin-databases',
+      'dispose-managed-runtime',
+    ]),
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect),
+  },
+) {}
+
+export class TimeoutError extends Schema.TaggedErrorClass<TimeoutError>()(ERROR_TAGS.TimeoutError, {
   operation: Schema.String,
   ms: Schema.Number,
 }) {}
 
-export class LockAcquisitionError extends Schema.TaggedErrorClass<LockAcquisitionError>()('LockAcquisitionError', {
-  lockKey: Schema.String,
-  maxWaitMs: Schema.Number,
-}) {}
+export class LockAcquisitionError extends Schema.TaggedErrorClass<LockAcquisitionError>()(
+  ERROR_TAGS.LockAcquisitionError,
+  { lockKey: Schema.String, maxWaitMs: Schema.Number },
+) {}
 
-export class LockLostError extends Schema.TaggedErrorClass<LockLostError>()('LockLostError', {
+export class LockLostError extends Schema.TaggedErrorClass<LockLostError>()(ERROR_TAGS.LockLostError, {
   lockKey: Schema.String,
 }) {}
 
-export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()('NotFoundError', {
+export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()(ERROR_TAGS.NotFoundError, {
   resource: Schema.String,
   id: Schema.optional(Schema.String),
   message: Schema.String,
 }) {}
 
-export class BadRequestError extends Schema.TaggedErrorClass<BadRequestError>()('BadRequestError', {
+export class BadRequestError extends Schema.TaggedErrorClass<BadRequestError>()(ERROR_TAGS.BadRequestError, {
   message: Schema.String,
 }) {}
 
-export class ConflictError extends Schema.TaggedErrorClass<ConflictError>()('ConflictError', {
+export class ConflictError extends Schema.TaggedErrorClass<ConflictError>()(ERROR_TAGS.ConflictError, {
   message: Schema.String,
 }) {}
 
-export class ForbiddenError extends Schema.TaggedErrorClass<ForbiddenError>()('ForbiddenError', {
+export class ForbiddenError extends Schema.TaggedErrorClass<ForbiddenError>()(ERROR_TAGS.ForbiddenError, {
   message: Schema.String,
 }) {}
 
-export class ValidationError extends Schema.TaggedErrorClass<ValidationError>()('ValidationError', {
+export class ValidationError extends Schema.TaggedErrorClass<ValidationError>()(ERROR_TAGS.ValidationError, {
   message: Schema.String,
   issues: Schema.optional(Schema.Array(ValidationIssueSchema)),
 }) {}
 
-export class AiGenerationError extends Schema.TaggedErrorClass<AiGenerationError>()('AiGenerationError', {
+export class AiGenerationError extends Schema.TaggedErrorClass<AiGenerationError>()(ERROR_TAGS.AiGenerationError, {
   message: Schema.String,
   source: Schema.String,
   status: Schema.optional(Schema.Number),
@@ -73,17 +194,17 @@ export class AiGenerationError extends Schema.TaggedErrorClass<AiGenerationError
   url: Schema.optional(Schema.String),
 }) {}
 
-export class ThreadTurnError extends Schema.TaggedErrorClass<ThreadTurnError>()('ThreadTurnError', {
+export class ThreadTurnError extends Schema.TaggedErrorClass<ThreadTurnError>()(ERROR_TAGS.ThreadTurnError, {
   message: Schema.String,
   reason: Schema.Literals(['bad-request', 'conflict']),
 }) {}
 
 export class ActiveThreadRunConflictError extends Schema.TaggedErrorClass<ActiveThreadRunConflictError>()(
-  'ActiveThreadRunConflictError',
+  ERROR_TAGS.ActiveThreadRunConflictError,
   { threadId: Schema.String, activeRunId: Schema.String, message: Schema.String },
 ) {}
 
-export class ConfigurationError extends Schema.TaggedErrorClass<ConfigurationError>()('ConfigurationError', {
+export class ConfigurationError extends Schema.TaggedErrorClass<ConfigurationError>()(ERROR_TAGS.ConfigurationError, {
   message: Schema.String,
   key: Schema.optional(Schema.String),
 }) {}
@@ -101,6 +222,7 @@ const EFFECT_ERROR_CLASSES = [
   LockLostError,
   NotFoundError,
   RedisError,
+  RuntimeLifecycleError,
   ServiceError,
   ThreadTurnError,
   TimeoutError,
@@ -109,7 +231,25 @@ const EFFECT_ERROR_CLASSES = [
 
 export type EffectError = InstanceType<(typeof EFFECT_ERROR_CLASSES)[number]>
 
-const EFFECT_ERROR_TAGS = new Set(EFFECT_ERROR_CLASSES.map((cls) => cls.name))
+const EFFECT_ERROR_TAGS = new Set<ErrorTag>([
+  ERROR_TAGS.ActiveThreadRunConflictError,
+  ERROR_TAGS.AiGenerationError,
+  ERROR_TAGS.BadRequestError,
+  ERROR_TAGS.BaseServicePersistenceError,
+  ERROR_TAGS.ConfigurationError,
+  ERROR_TAGS.ConflictError,
+  ERROR_TAGS.DatabaseError,
+  ERROR_TAGS.ForbiddenError,
+  ERROR_TAGS.LockAcquisitionError,
+  ERROR_TAGS.LockLostError,
+  ERROR_TAGS.NotFoundError,
+  ERROR_TAGS.RedisError,
+  ERROR_TAGS.RuntimeLifecycleError,
+  ERROR_TAGS.ServiceError,
+  ERROR_TAGS.ThreadTurnError,
+  ERROR_TAGS.TimeoutError,
+  ERROR_TAGS.ValidationError,
+])
 
 export function isEffectError(error: unknown): error is EffectError {
   if (!error || typeof error !== 'object') {
@@ -117,5 +257,5 @@ export function isEffectError(error: unknown): error is EffectError {
   }
 
   const tag = (error as { _tag?: unknown })._tag
-  return typeof tag === 'string' && EFFECT_ERROR_TAGS.has(tag)
+  return typeof tag === 'string' && EFFECT_ERROR_TAGS.has(tag as ErrorTag)
 }

package/src/effect/index.ts

@@ -1,4 +1,3 @@
-export * from './helpers'
 export * from './layers'
 export * from './services'
 export * from './zod'

package/src/embeddings/provider.ts

@@ -1,7 +1,7 @@
 import { embed, embedMany } from 'ai'
 import { Schema, Effect } from 'effect'
 
-import { ConfigurationError } from '../effect/errors'
+import { ERROR_TAGS, ConfigurationError } from '../effect/errors'
 import { getDirectOpenRouterProvider, normalizeDirectOpenRouterModelId } from '../openrouter/direct-provider'
 
 const SUPPORTED_EMBEDDING_PREFIXES = ['openai/', 'openrouter/'] as const
@@ -17,6 +17,12 @@ type ProviderEmbeddingsOptions = {
   getCache?: () => SharedEmbeddingCache | null
   modelId: string
   openRouterApiKey?: string
+  /**
+   * `runPromise` is required: callers must yield `RuntimeBridgeTag` in their
+   * `Layer.effect` (or accept a `RuntimeBridge` dep) and pass its `runPromise`
+   * through, so this class never reaches for an ambient `Effect.runPromise`.
+   */
+  runPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>
 }
 
 function resolveEmbeddingModel(modelId: string, openRouterApiKey?: string) {
@@ -39,10 +45,10 @@ function normalizeEmbedding(embedding: readonly number[]): number[] {
   return embedding.map((value) => Number(value))
 }
 
-class EmbeddingProviderError extends Schema.TaggedErrorClass<EmbeddingProviderError>()('EmbeddingProviderError', {
-  message: Schema.String,
-  cause: Schema.Defect,
-}) {}
+class EmbeddingProviderError extends Schema.TaggedErrorClass<EmbeddingProviderError>()(
+  ERROR_TAGS.EmbeddingProviderError,
+  { message: Schema.String, cause: Schema.Defect },
+) {}
 
 function tryEmbeddingPromise<A>(
   message: string,
@@ -64,6 +70,7 @@ export class ProviderEmbeddings {
   private readonly inflightEmbeddings = new Map<string, Promise<number[]>>()
 
   private readonly openRouterApiKey: string | undefined
+  private readonly runPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>
 
   constructor(options: ProviderEmbeddingsOptions) {
     this.embedFn = options.embedFn ?? embed
@@ -71,6 +78,7 @@ export class ProviderEmbeddings {
     this.getCache = options.getCache ?? (() => null)
     this.resolvedModelId = options.modelId
     this.openRouterApiKey = options.openRouterApiKey
+    this.runPromise = options.runPromise
   }
 
   private getModelId(): string {
@@ -99,7 +107,7 @@ export class ProviderEmbeddings {
     const pending = this.inflightEmbeddings.get(dedupKey)
     if (pending) return pending
 
-    const promise = Effect.runPromise(this.executeEmbedQueryEffect(input))
+    const promise = this.runPromise(this.executeEmbedQueryEffect(input))
     this.inflightEmbeddings.set(dedupKey, promise)
     void promise.finally(() => this.inflightEmbeddings.delete(dedupKey))
 
@@ -144,7 +152,7 @@ export class ProviderEmbeddings {
     }
 
     const uniqueTexts = [...new Set(nonEmptyEntries.map((entry) => entry.value))]
-    return Effect.runPromise(this.embedDocumentsEffect(normalized, uniqueTexts))
+    return this.runPromise(this.embedDocumentsEffect(normalized, uniqueTexts))
   }
 
   private embedDocumentsEffect(

package/src/queues/autonomous-job.queue.ts

@@ -6,6 +6,7 @@ import type IORedis from 'ioredis'
 
 import { serverLogger } from '../config/logger'
 import { DatabaseServiceTag, RedisServiceTag } from '../effect/services'
+import type { makeAutonomousJobService } from '../services/autonomous-job.service'
 import { QueueJobServiceTag } from '../services/queue-job.service'
 import { buildAutonomousAtJobId } from '../utils/autonomous-job-ids'
 import type { QueueJobService, WorkerHandle } from '../workers/worker-utils'
@@ -13,17 +14,12 @@ import { DEFAULT_JOB_RETENTION } from '../workers/worker-utils'
 import { createQueueFactoryWithDeps, recordEnqueuedJobMetadata } from './queue-factory'
 import { runStandaloneQueueWorker } from './standalone-worker'
 
-// Minimal service shape used by the queue's worker processor. We declare it
-// structurally to avoid importing `AutonomousJobServiceTag` — that would form a
-// dependency cycle since `AutonomousJobServiceLive` now depends on
-// `LotaQueuesServiceTag` (defined in `queues.service.ts` which imports this
-// module).
-interface AutonomousJobWorkerServiceShape {
-  executeQueuedRun(
-    job: Job<AutonomousJobQueuePayload>,
-  ): Effect.Effect<{ status: string; summary?: string }, unknown, unknown>
-  recoverActiveJobs(): Effect.Effect<unknown, unknown, unknown>
-}
+type AutonomousJobWorkerServiceMethods = Pick<
+  ReturnType<typeof makeAutonomousJobService>,
+  'executeQueuedRun' | 'recoverActiveJobs'
+>
+
+type AutonomousJobWorkerServiceShape = AutonomousJobWorkerServiceMethods
 
 class AutonomousJobQueueError extends Schema.TaggedErrorClass<AutonomousJobQueueError>()(
   '@lota-sdk/core/AutonomousJobQueueError',
@@ -53,16 +49,7 @@ function processAutonomousJob(
   deps: AutonomousJobWorkerDeps,
   job: Job<AutonomousJobQueuePayload>,
 ): Promise<{ status: string; summary?: string }> {
-  // `executeQueuedRun` is typed with a wide residual context to account for
-  // the dynamic thread-turn import inside the service; the actual Effect
-  // resolves every tag via the managed runtime that produced this service.
-  return Effect.runPromise(
-    deps.autonomousJobService.executeQueuedRun(job) as Effect.Effect<
-      { status: string; summary?: string },
-      never,
-      never
-    >,
-  )
+  return Effect.runPromise(deps.autonomousJobService.executeQueuedRun(job))
 }
 
 function buildAutonomousSchedulerId(autonomousJobId: string): string {
@@ -193,7 +180,7 @@ export function makeAutonomousJobQueueRuntime(params: MakeAutonomousJobQueueRunt
         Effect.sync(() => {
           serverLogger.error`Autonomous job startup recovery failed: ${error}`
         }),
-      ) as Effect.Effect<unknown, never, never>,
+      ),
     )
 
     return handle
@@ -209,6 +196,7 @@ export function makeAutonomousJobQueueRuntime(params: MakeAutonomousJobQueueRunt
 }
 
 runStandaloneQueueWorker((runtime) => {
+  // @effect-diagnostics-next-line asyncFunction:off -- BullMQ standalone worker bootstrap.
   void (async () => {
     const { AutonomousJobServiceTag } = await import('../services/autonomous-job.service')
     const resolve = <I, T>(tag: Context.Key<I, T>): T => runtime.runSync(Effect.service(tag))

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

@@ -4,21 +4,15 @@ import type { Context } from 'effect'
 import type IORedis from 'ioredis'
 
 import { DatabaseServiceTag, RedisServiceTag } from '../effect/services'
+import type { makePlanExecutorService } from '../services/plan/plan-executor.service'
 import { QueueJobServiceTag } from '../services/queue-job.service'
 import type { QueueJobService, WorkerHandle } from '../workers/worker-utils'
 import { createQueueFactoryWithDeps } from './queue-factory'
 import { runStandaloneQueueWorker } from './standalone-worker'
 
-// Minimal service shape used by the worker processor. Declared structurally to
-// avoid importing the service tag — which would form a dependency cycle since
-// PlanExecutorServiceLive depends on LotaQueuesServiceTag.
-interface DelayedNodePromotionPlanExecutorShape {
-  promoteDelayedNode(params: {
-    runId: string
-    nodeId: string
-    emittedBy: string
-  }): Effect.Effect<unknown, unknown, unknown>
-}
+type DelayedNodePromotionPlanExecutorMethods = Pick<ReturnType<typeof makePlanExecutorService>, 'promoteDelayedNode'>
+
+type DelayedNodePromotionPlanExecutorShape = DelayedNodePromotionPlanExecutorMethods
 
 export interface DelayedNodePromotionJob {
   runId: string
@@ -37,14 +31,13 @@ function processDelayedNodePromotionJob(
   deps: DelayedNodePromotionWorkerDeps,
   job: Job<DelayedNodePromotionJob>,
 ): Promise<void> {
-  const { planExecutorService } = deps
-  return Promise.resolve(
-    planExecutorService.promoteDelayedNode({
+  return Effect.runPromise(
+    deps.planExecutorService.promoteDelayedNode({
       runId: job.data.runId,
       nodeId: job.data.nodeId,
       emittedBy: job.data.emittedBy,
     }),
-  ).then(() => undefined)
+  )
 }
 
 export interface DelayedNodePromotionQueueRuntime {
@@ -82,6 +75,7 @@ export function makeDelayedNodePromotionQueueRuntime(
 }
 
 runStandaloneQueueWorker((runtime) => {
+  // @effect-diagnostics-next-line asyncFunction:off -- BullMQ standalone worker bootstrap.
   void (async () => {
     const { PlanExecutorServiceTag } = await import('../services/plan/plan-executor.service')
     const resolve = <I, T>(tag: Context.Key<I, T>): T => runtime.runSync(Effect.service(tag))

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

@@ -1,12 +1,18 @@
-import { Effect } from 'effect'
+import { Effect, Schema } from 'effect'
 import type IORedis from 'ioredis'
 
 import type { chatLogger } from '../config/logger'
+import { ERROR_TAGS } from '../effect/errors'
 import { sha256Hex } from '../utils/crypto'
 import { DEFAULT_JOB_RETENTION } from '../workers/worker-utils'
 import type { QueueJobService, WorkerHandle } from '../workers/worker-utils'
 import { createQueueFactory } from './queue-factory'
 
+class DocumentProcessorEnqueueError extends Schema.TaggedErrorClass<DocumentProcessorEnqueueError>()(
+  ERROR_TAGS.QueueFactoryError,
+  { message: Schema.String, cause: Schema.Defect },
+) {}
+
 export type DocumentSourceChannel = string
 
 export interface DocumentProcessorAttachmentRef {
@@ -83,9 +89,12 @@ export function createDocumentProcessorQueueRuntime<TJob extends DocumentProcess
     enqueue: (job) => {
       return Effect.runPromise(
         Effect.gen(function* () {
-          const queuedJob = yield* Effect.tryPromise(() =>
-            queueRuntime.getQueue().add('process-document', job, { jobId: buildDocumentProcessorJobId(job) }),
-          )
+          const queuedJob = yield* Effect.tryPromise({
+            try: () =>
+              queueRuntime.getQueue().add('process-document', job, { jobId: buildDocumentProcessorJobId(job) }),
+            catch: (cause) =>
+              new DocumentProcessorEnqueueError({ message: 'Failed to enqueue document processor job.', cause }),
+          })
 
           yield* Effect.catch(
             params.queueJobService.recordEnqueued({

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

@@ -1,8 +1,9 @@
-import { Effect } from 'effect'
+import { Effect, Schema } from 'effect'
 import type { Context } from 'effect'
 import type IORedis from 'ioredis'
 
 import { serverLogger } from '../config/logger'
+import { ERROR_TAGS } from '../effect/errors'
 import { RedisServiceTag } from '../effect/services'
 import { QueueJobServiceTag } from '../services/queue-job.service'
 import type { QueueJobService, WorkerHandle } from '../workers/worker-utils'
@@ -10,6 +11,11 @@ import { getWorkerPath, LONG_JOB_LOCK_DURATION_MS, LOW_JOB_RETENTION } from '../
 import { createQueueFactory } from './queue-factory'
 import { runStandaloneQueueWorker } from './standalone-worker'
 
+class MemoryConsolidationSchedulerError extends Schema.TaggedErrorClass<MemoryConsolidationSchedulerError>()(
+  ERROR_TAGS.QueueFactoryError,
+  { message: Schema.String, cause: Schema.Defect },
+) {}
+
 export interface MemoryConsolidationJob {
   scopeId?: string
 }
@@ -50,19 +56,25 @@ export function makeMemoryConsolidationQueueRuntime(
   const scheduleRecurringConsolidation: MemoryConsolidationQueueRuntime['scheduleRecurringConsolidation'] = () =>
     Effect.runPromise(
       Effect.gen(function* () {
-        const queuedJob = yield* Effect.tryPromise(() =>
-          queue
-            .getQueue()
-            .upsertJobScheduler(
-              MEMORY_CONSOLIDATION_SCHEDULER_ID,
-              { every: MEMORY_CONSOLIDATION_INTERVAL_MS },
-              {
-                name: 'consolidate',
-                data: {},
-                opts: { ...LOW_JOB_RETENTION, attempts: 2, backoff: { type: 'exponential', delay: 5000 } },
-              },
-            ),
-        )
+        const queuedJob = yield* Effect.tryPromise({
+          try: () =>
+            queue
+              .getQueue()
+              .upsertJobScheduler(
+                MEMORY_CONSOLIDATION_SCHEDULER_ID,
+                { every: MEMORY_CONSOLIDATION_INTERVAL_MS },
+                {
+                  name: 'consolidate',
+                  data: {},
+                  opts: { ...LOW_JOB_RETENTION, attempts: 2, backoff: { type: 'exponential', delay: 5000 } },
+                },
+              ),
+          catch: (cause) =>
+            new MemoryConsolidationSchedulerError({
+              message: 'Failed to upsert memory consolidation scheduler.',
+              cause,
+            }),
+        })
 
         yield* Effect.catch(
           queueJobService.recordEnqueued({

package/src/queues/plan-agent-heartbeat.queue.ts

@@ -5,19 +5,19 @@ import type IORedis from 'ioredis'
 
 import { serverLogger } from '../config/logger'
 import { DatabaseServiceTag, RedisServiceTag } from '../effect/services'
+import type { makePlanAgentHeartbeatService } from '../services/plan/plan-agent-heartbeat.service'
 import { QueueJobServiceTag } from '../services/queue-job.service'
 import type { QueueJobService, WorkerHandle } from '../workers/worker-utils'
 import { DEFAULT_JOB_RETENTION, LONG_JOB_LOCK_DURATION_MS } from '../workers/worker-utils'
 import { createQueueFactoryWithDeps } from './queue-factory'
 import { runStandaloneQueueWorker } from './standalone-worker'
 
-// Minimal service shape used by the worker processor. Declared structurally to
-// avoid importing the service tag — which would form a dependency cycle since
-// PlanAgentHeartbeatServiceLive depends on LotaQueuesServiceTag.
-interface PlanAgentHeartbeatWorkerServiceShape {
-  wakeNode(params: PlanAgentHeartbeatWakeJob): Effect.Effect<unknown, unknown, unknown>
-  sweep(params: { organizationId?: string }): Effect.Effect<void, unknown, unknown>
-}
+type PlanAgentHeartbeatWorkerServiceMethods = Pick<
+  ReturnType<typeof makePlanAgentHeartbeatService>,
+  'wakeNode' | 'sweep'
+>
+
+type PlanAgentHeartbeatWorkerServiceShape = PlanAgentHeartbeatWorkerServiceMethods
 
 class PlanAgentHeartbeatQueueError extends Schema.TaggedErrorClass<PlanAgentHeartbeatQueueError>()(
   '@lota-sdk/core/PlanAgentHeartbeatQueueError',
@@ -95,7 +95,7 @@ export function makePlanAgentHeartbeatQueueRuntime(
     return Effect.runPromise(
       Effect.gen(function* () {
         if (job.data.type === 'wake-node') {
-          const wakeJob = job.data
+          const wakeJob: PlanAgentHeartbeatWakeJob = job.data
           yield* service.wakeNode(wakeJob)
           return
         }
@@ -111,7 +111,7 @@ export function makePlanAgentHeartbeatQueueRuntime(
               }),
           })
         }
-      }) as Effect.Effect<void, never, never>,
+      }),
     )
   }
 
@@ -148,6 +148,7 @@ export function makePlanAgentHeartbeatQueueRuntime(
 }
 
 runStandaloneQueueWorker((runtime) => {
+  // @effect-diagnostics-next-line asyncFunction:off -- BullMQ standalone worker bootstrap.
   void (async () => {
     const { PlanAgentHeartbeatServiceTag } = await import('../services/plan/plan-agent-heartbeat.service')
     const resolve = <I, T>(tag: Context.Key<I, T>): T => runtime.runSync(Effect.service(tag))