@lota-sdk/core 0.4.7 → 0.4.9

package/src/services/plan/plan-scheduler.service.ts

@@ -0,0 +1,385 @@
+import { PlanCycleRecordSchema, PlanScheduleRecordSchema } from '@lota-sdk/shared'
+import type { PlanScheduleRecord, PlanScheduleSpec } from '@lota-sdk/shared'
+import { Context, Cron, Schema, Effect, Layer, Result } from 'effect'
+import { BoundQuery } from 'surrealdb'
+
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId, recordIdToString } from '../../db/record-id'
+import type { SurrealDBService } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { NotFoundError } from '../../effect/errors'
+import { effectTryPromise as effectTryPromiseShared } from '../../effect/helpers'
+import { DatabaseServiceTag } from '../../effect/services'
+import { nowDate, nowEpochMillis, toDatabaseDateTime, unsafeDateFrom } from '../../utils/date-time'
+
+interface PlanSchedulerRuntimeDeps {
+  promoteDelayedNode(params: { runId: string; nodeId: string; emittedBy: string }): Promise<void>
+  advanceCycle(cycleId: RecordIdInput): Promise<void>
+  recoverDeadlineChecks(): Promise<void>
+}
+
+class PlanSchedulerError extends Schema.TaggedErrorClass<PlanSchedulerError>()('PlanSchedulerError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+function effectTryPromise<A>(
+  evaluate: () => PromiseLike<A> | Effect.Effect<A, unknown>,
+  message: string,
+): Effect.Effect<A, PlanSchedulerError> {
+  return effectTryPromiseShared(evaluate, (cause) => new PlanSchedulerError({ message, cause }))
+}
+
+function failPlanScheduler(message: string, cause?: unknown): Effect.Effect<never, PlanSchedulerError> {
+  return Effect.fail(new PlanSchedulerError({ message, ...(cause === undefined ? {} : { cause }) }))
+}
+
+function requireScheduleField<A>(value: A | undefined, message: string): Effect.Effect<A, PlanSchedulerError> {
+  return value === undefined ? failPlanScheduler(message) : Effect.succeed(value)
+}
+
+const computeNextCronDateEffect: (cronExpression: string, baseTime: Date) => Effect.Effect<Date, PlanSchedulerError> =
+  Effect.fn('PlanScheduler.computeNextCronDate')(function* (cronExpression: string, baseTime: Date) {
+    const parsedCron = Cron.parse(cronExpression)
+    const cron = Result.isSuccess(parsedCron)
+      ? parsedCron.success
+      : yield* failPlanScheduler(`Invalid cron expression: "${cronExpression}".`)
+
+    return yield* Effect.try({
+      try: () => Cron.next(cron, baseTime),
+      catch: (cause) =>
+        new PlanSchedulerError({
+          message: `Failed to compute the next fire time for cron expression "${cronExpression}".`,
+          cause,
+        }),
+    })
+  })
+
+const computeNextFireAtEffect: (spec: PlanScheduleSpec, baseTime?: Date) => Effect.Effect<Date, PlanSchedulerError> =
+  Effect.fn('PlanScheduler.computeNextFireAt')(function* (spec: PlanScheduleSpec, baseTime: Date = nowDate()) {
+    switch (spec.type) {
+      case 'immediate':
+        return baseTime
+
+      case 'absolute': {
+        const at = yield* requireScheduleField(spec.at, 'Absolute schedules require an "at" timestamp.')
+        return unsafeDateFrom(at)
+      }
+
+      case 'relative': {
+        const delayMs = yield* requireScheduleField(spec.delayMs, 'Relative schedules require "delayMs".')
+        return unsafeDateFrom(baseTime.getTime() + delayMs)
+      }
+
+      case 'cron': {
+        const cronExpression = yield* requireScheduleField(spec.cron, 'Cron schedules require a "cron" expression.')
+        return yield* computeNextCronDateEffect(cronExpression, baseTime)
+      }
+
+      case 'monitoring': {
+        const intervalMs = yield* requireScheduleField(spec.intervalMs, 'Monitoring schedules require "intervalMs".')
+        return unsafeDateFrom(baseTime.getTime() + intervalMs)
+      }
+
+      default:
+        return yield* failPlanScheduler('Unsupported schedule type in schedule specification.')
+    }
+  })
+
+export function makePlanSchedulerService(db: SurrealDBService) {
+  const loadPlanSchedulerQueue = () =>
+    effectTryPromise(() => import('../../queues/plan-scheduler.queue'), 'Failed to load plan scheduler queue module.')
+
+  const createScheduleEffect = (params: {
+    organizationId: RecordIdInput
+    threadId: RecordIdInput
+    planSpecId?: RecordIdInput
+    runId?: RecordIdInput
+    nodeId?: string
+    scheduleSpec: PlanScheduleSpec
+  }): Effect.Effect<PlanScheduleRecord, PlanSchedulerError> =>
+    Effect.gen(function* () {
+      const nextFireAt = yield* computeNextFireAtEffect(params.scheduleSpec)
+      const now = nowDate()
+      const record = yield* effectTryPromise(
+        () =>
+          db.create(
+            TABLES.PLAN_SCHEDULE,
+            {
+              organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+              threadId: ensureRecordId(params.threadId, TABLES.THREAD),
+              planSpecId: params.planSpecId ? ensureRecordId(params.planSpecId, TABLES.PLAN_SPEC) : undefined,
+              runId: params.runId ? ensureRecordId(params.runId, TABLES.PLAN_RUN) : undefined,
+              nodeId: params.nodeId,
+              scheduleSpec: params.scheduleSpec,
+              status: 'active',
+              fireCount: 0,
+              nextFireAt: toDatabaseDateTime(nextFireAt),
+              createdAt: now,
+            },
+            PlanScheduleRecordSchema,
+          ),
+        'Failed to create plan schedule.',
+      )
+      const { enqueueScheduleFire } = yield* loadPlanSchedulerQueue()
+      yield* effectTryPromise(
+        () =>
+          enqueueScheduleFire(
+            recordIdToString(record.id, TABLES.PLAN_SCHEDULE),
+            Math.max(0, nextFireAt.getTime() - nowEpochMillis()),
+          ),
+        'Failed to enqueue schedule fire job.',
+      )
+      return record
+    })
+
+  const fireScheduleEffect = (
+    schedule: PlanScheduleRecord,
+    runtimeDeps: PlanSchedulerRuntimeDeps,
+  ): Effect.Effect<void, PlanSchedulerError> =>
+    Effect.gen(function* () {
+      const now = nowDate()
+      const newFireCount = schedule.fireCount + 1
+      const isRecurring = schedule.scheduleSpec.type === 'cron' || schedule.scheduleSpec.type === 'monitoring'
+      const maxReached = schedule.scheduleSpec.maxFires !== undefined && newFireCount >= schedule.scheduleSpec.maxFires
+
+      let nextFireAt: Date | null = null
+      let newStatus: 'active' | 'completed' = 'completed'
+
+      if (isRecurring && !maxReached) {
+        nextFireAt = yield* computeNextFireAtEffect(schedule.scheduleSpec, now)
+        newStatus = 'active'
+      }
+
+      yield* effectTryPromise(
+        () =>
+          db.update(
+            TABLES.PLAN_SCHEDULE,
+            schedule.id,
+            {
+              fireCount: newFireCount,
+              lastFiredAt: now,
+              nextFireAt: toDatabaseDateTime(nextFireAt),
+              status: newStatus,
+            },
+            PlanScheduleRecordSchema,
+          ),
+        'Failed to update fired schedule.',
+      )
+
+      let shouldRecoverDeadlineChecks = false
+      if (newStatus === 'active') {
+        if (!nextFireAt) {
+          return yield* new PlanSchedulerError({ message: 'Recurring schedules must resolve a next fire time.' })
+        }
+        const { enqueueScheduleFire } = yield* loadPlanSchedulerQueue()
+        yield* effectTryPromise(
+          () =>
+            enqueueScheduleFire(
+              recordIdToString(schedule.id, TABLES.PLAN_SCHEDULE),
+              Math.max(0, nextFireAt.getTime() - nowEpochMillis()),
+            ),
+          'Failed to enqueue next schedule fire job.',
+        )
+      }
+
+      const runId = schedule.runId
+      const nodeId = schedule.nodeId
+      if (runId && nodeId) {
+        yield* effectTryPromise(
+          () =>
+            runtimeDeps.promoteDelayedNode({
+              runId: recordIdToString(runId, TABLES.PLAN_RUN),
+              nodeId,
+              emittedBy: 'plan-scheduler',
+            }),
+          'Failed to promote delayed plan node.',
+        )
+        shouldRecoverDeadlineChecks = true
+      }
+
+      if (schedule.planSpecId && !schedule.runId) {
+        const cycle = yield* effectTryPromise(
+          () =>
+            db.findOne(
+              TABLES.PLAN_CYCLE,
+              { scheduleId: ensureRecordId(schedule.id, TABLES.PLAN_SCHEDULE) },
+              PlanCycleRecordSchema,
+            ),
+          'Failed to load plan cycle for schedule.',
+        )
+        if (cycle) {
+          yield* effectTryPromise(() => runtimeDeps.advanceCycle(cycle.id), 'Failed to advance plan cycle.')
+          shouldRecoverDeadlineChecks = true
+        }
+      }
+
+      if (shouldRecoverDeadlineChecks) {
+        yield* effectTryPromise(() => runtimeDeps.recoverDeadlineChecks(), 'Failed to recover deadline checks.')
+      }
+    })
+
+  const fireScheduleByIdEffect = (scheduleId: string, runtimeDeps: PlanSchedulerRuntimeDeps) =>
+    Effect.gen(function* () {
+      const schedule = yield* effectTryPromise(
+        () =>
+          db.findOne(
+            TABLES.PLAN_SCHEDULE,
+            { id: ensureRecordId(scheduleId, TABLES.PLAN_SCHEDULE) },
+            PlanScheduleRecordSchema,
+          ),
+        'Failed to load schedule by id.',
+      )
+      if (!schedule || schedule.status !== 'active') return
+
+      yield* fireScheduleEffect(schedule, runtimeDeps)
+    })
+
+  const recoverActiveSchedulesEffect = () =>
+    Effect.gen(function* () {
+      const activeSchedules = yield* effectTryPromise(
+        () =>
+          db.queryMany(
+            new BoundQuery(`SELECT * FROM ${TABLES.PLAN_SCHEDULE} WHERE status = $status ORDER BY nextFireAt ASC`, {
+              status: 'active',
+            }),
+            PlanScheduleRecordSchema,
+          ),
+        'Failed to load active schedules.',
+      )
+      const { enqueueScheduleFire } = yield* loadPlanSchedulerQueue()
+      yield* Effect.forEach(
+        activeSchedules.filter(
+          (schedule): schedule is typeof schedule & { nextFireAt: Date } => schedule.nextFireAt !== undefined,
+        ),
+        (schedule) =>
+          effectTryPromise(
+            () =>
+              enqueueScheduleFire(
+                recordIdToString(schedule.id, TABLES.PLAN_SCHEDULE),
+                Math.max(0, unsafeDateFrom(schedule.nextFireAt).getTime() - nowEpochMillis()),
+              ),
+            `Failed to re-enqueue schedule ${recordIdToString(schedule.id, TABLES.PLAN_SCHEDULE)}.`,
+          ),
+        { concurrency: 5, discard: true },
+      )
+    })
+
+  const cancelScheduleEffect = (scheduleId: RecordIdInput) => {
+    const idStr = recordIdToString(scheduleId, TABLES.PLAN_SCHEDULE)
+    return Effect.gen(function* () {
+      const { removeScheduleFireJob } = yield* loadPlanSchedulerQueue()
+      yield* effectTryPromise(() => removeScheduleFireJob(idStr), 'Failed to remove schedule fire job.')
+      yield* effectTryPromise(
+        () =>
+          db.update(
+            TABLES.PLAN_SCHEDULE,
+            ensureRecordId(scheduleId, TABLES.PLAN_SCHEDULE),
+            { status: 'cancelled' },
+            PlanScheduleRecordSchema,
+          ),
+        'Failed to cancel schedule.',
+      )
+    })
+  }
+
+  const pauseScheduleEffect = (scheduleId: RecordIdInput) => {
+    const idStr = recordIdToString(scheduleId, TABLES.PLAN_SCHEDULE)
+    return Effect.gen(function* () {
+      const { removeScheduleFireJob } = yield* loadPlanSchedulerQueue()
+      yield* effectTryPromise(() => removeScheduleFireJob(idStr), 'Failed to remove schedule fire job.')
+      yield* effectTryPromise(
+        () =>
+          db.update(
+            TABLES.PLAN_SCHEDULE,
+            ensureRecordId(scheduleId, TABLES.PLAN_SCHEDULE),
+            { status: 'paused' },
+            PlanScheduleRecordSchema,
+          ),
+        'Failed to pause schedule.',
+      )
+    })
+  }
+
+  const resumeScheduleEffect = (scheduleId: RecordIdInput) =>
+    Effect.gen(function* () {
+      const schedule = yield* effectTryPromise(
+        () =>
+          db.findOne(
+            TABLES.PLAN_SCHEDULE,
+            { id: ensureRecordId(scheduleId, TABLES.PLAN_SCHEDULE) },
+            PlanScheduleRecordSchema,
+          ),
+        'Failed to load schedule for resume.',
+      )
+      if (!schedule) {
+        return yield* new NotFoundError({
+          resource: TABLES.PLAN_SCHEDULE,
+          id: recordIdToString(scheduleId, TABLES.PLAN_SCHEDULE),
+          message: `Schedule not found: ${recordIdToString(scheduleId, TABLES.PLAN_SCHEDULE)}`,
+        })
+      }
+
+      const nextFireAt = yield* computeNextFireAtEffect(schedule.scheduleSpec)
+      yield* effectTryPromise(
+        () =>
+          db.update(
+            TABLES.PLAN_SCHEDULE,
+            ensureRecordId(scheduleId, TABLES.PLAN_SCHEDULE),
+            { status: 'active', nextFireAt: toDatabaseDateTime(nextFireAt) },
+            PlanScheduleRecordSchema,
+          ),
+        'Failed to resume schedule.',
+      )
+      const { enqueueScheduleFire } = yield* loadPlanSchedulerQueue()
+      yield* effectTryPromise(
+        () =>
+          enqueueScheduleFire(
+            recordIdToString(scheduleId, TABLES.PLAN_SCHEDULE),
+            Math.max(0, nextFireAt.getTime() - nowEpochMillis()),
+          ),
+        'Failed to enqueue resumed schedule.',
+      )
+    })
+
+  const listSchedulesEffect = (threadId: RecordIdInput) =>
+    effectTryPromise(
+      () =>
+        db.findMany(
+          TABLES.PLAN_SCHEDULE,
+          { threadId: ensureRecordId(threadId, TABLES.THREAD) },
+          PlanScheduleRecordSchema,
+          { orderBy: 'createdAt', orderDir: 'ASC' },
+        ),
+      'Failed to list schedules.',
+    )
+
+  return {
+    createSchedule: createScheduleEffect,
+    computeNextFireAt(spec: PlanScheduleSpec, baseTime: Date = nowDate()): Date {
+      return Effect.runSync(computeNextFireAtEffect(spec, baseTime))
+    },
+    /** Called by the BullMQ worker when a fire-schedule job executes. */
+    fireScheduleById: fireScheduleByIdEffect,
+    fireSchedule: fireScheduleEffect,
+    /** Re-enqueue BullMQ jobs for all active schedules. Called once at worker startup. */
+    recoverActiveSchedules: recoverActiveSchedulesEffect,
+    cancelSchedule: cancelScheduleEffect,
+    pauseSchedule: pauseScheduleEffect,
+    resumeSchedule: resumeScheduleEffect,
+    listSchedules: listSchedulesEffect,
+  }
+}
+
+export class PlanSchedulerServiceTag extends Context.Service<
+  PlanSchedulerServiceTag,
+  ReturnType<typeof makePlanSchedulerService>
+>()('PlanSchedulerService') {}
+
+export const PlanSchedulerServiceLive = Layer.effect(
+  PlanSchedulerServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    return makePlanSchedulerService(db)
+  }),
+)

package/src/services/plan/plan-template.service.ts

@@ -0,0 +1,224 @@
+import { PlanTemplateRecordSchema } from '@lota-sdk/shared'
+import type { PlanArtifactRecord, PlanDraft } from '@lota-sdk/shared'
+import { Context, Schema, Effect, Layer } from 'effect'
+
+import type { RecordIdInput } from '../../db/record-id'
+import { ensureRecordId, recordIdToString } from '../../db/record-id'
+import type { SurrealDBService } from '../../db/service'
+import { TABLES } from '../../db/tables'
+import { ValidationError } from '../../effect/errors'
+import { DatabaseServiceTag } from '../../effect/services'
+import { nowDate } from '../../utils/date-time'
+import type { makeExecutionPlanService } from '../execution-plan/execution-plan.service'
+import { ExecutionPlanServiceTag } from '../execution-plan/execution-plan.service'
+
+interface PlanTemplateDeps {
+  db: SurrealDBService
+  executionPlanService: Pick<ReturnType<typeof makeExecutionPlanService>, 'createPlan'>
+}
+
+type CreateTemplateParams = {
+  organizationId: RecordIdInput
+  name: string
+  description?: string
+  draft: PlanDraft
+  tags?: string[]
+  source?: 'user' | 'playbook' | 'system'
+  sourceRef?: string
+}
+
+type GetTemplateBySourceRefParams = {
+  organizationId: RecordIdInput
+  source: 'user' | 'playbook' | 'system'
+  sourceRef: string
+}
+
+type ListTemplatesParams = { tags?: string[]; source?: string }
+
+type UpdateTemplatePatch = Partial<{ name: string; description: string; draft: PlanDraft; tags: string[] }>
+
+type InstantiateTemplateParams = {
+  templateId: RecordIdInput
+  organizationId: RecordIdInput
+  threadId: RecordIdInput
+  sourceThreadId?: RecordIdInput
+  leadAgentId: string
+  createdByAgentId?: string
+  requireApproval?: boolean
+  overrides?: Partial<PlanDraft>
+  carryForwardArtifacts?: PlanArtifactRecord[]
+}
+
+class PlanTemplateNotFoundError extends Schema.TaggedErrorClass<PlanTemplateNotFoundError>()(
+  'PlanTemplateNotFoundError',
+  { templateId: Schema.String, message: Schema.String },
+) {}
+
+function resolveSourceIdentityEffect(params: {
+  source?: 'user' | 'playbook' | 'system'
+  sourceRef?: string
+}): Effect.Effect<{ source: 'user' | 'playbook' | 'system'; sourceRef?: string }, ValidationError> {
+  const source = params.source ?? 'user'
+  const sourceRef = params.sourceRef?.trim()
+
+  if (source !== 'user' && !sourceRef) {
+    return Effect.fail(new ValidationError({ message: `sourceRef is required when source is "${source}".` }))
+  }
+
+  return Effect.succeed({ source, sourceRef })
+}
+
+export function makePlanTemplateService(deps: PlanTemplateDeps) {
+  const { db } = deps
+
+  const createTemplateEffect = (params: CreateTemplateParams) =>
+    Effect.gen(function* () {
+      const now = nowDate()
+      const identity = yield* resolveSourceIdentityEffect({ source: params.source, sourceRef: params.sourceRef })
+      return yield* db.create(
+        TABLES.PLAN_TEMPLATE,
+        {
+          organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+          name: params.name,
+          ...(params.description ? { description: params.description } : {}),
+          draft: params.draft,
+          tags: params.tags ?? [],
+          source: identity.source,
+          ...(identity.sourceRef ? { sourceRef: identity.sourceRef } : {}),
+          createdAt: now,
+        },
+        PlanTemplateRecordSchema,
+      )
+    })
+
+  const getTemplateEffect = (templateId: RecordIdInput) =>
+    db.findOne(TABLES.PLAN_TEMPLATE, { id: ensureRecordId(templateId, TABLES.PLAN_TEMPLATE) }, PlanTemplateRecordSchema)
+
+  const getTemplateBySourceRefEffect = (params: GetTemplateBySourceRefParams) =>
+    db.findOne(
+      TABLES.PLAN_TEMPLATE,
+      {
+        organizationId: ensureRecordId(params.organizationId, TABLES.ORGANIZATION),
+        source: params.source,
+        sourceRef: params.sourceRef,
+      },
+      PlanTemplateRecordSchema,
+    )
+
+  const listTemplatesEffect = (organizationId: RecordIdInput, params?: ListTemplatesParams) => {
+    const filter: Record<string, unknown> = { organizationId: ensureRecordId(organizationId, TABLES.ORGANIZATION) }
+    if (params?.source) {
+      filter.source = params.source
+    }
+
+    return Effect.gen(function* () {
+      const templates = yield* db.findMany(TABLES.PLAN_TEMPLATE, filter, PlanTemplateRecordSchema, {
+        orderBy: 'createdAt',
+        orderDir: 'ASC',
+      })
+
+      if (params?.tags && params.tags.length > 0) {
+        const tagSet = new Set(params.tags)
+        return templates.filter((t) => t.tags.some((tag) => tagSet.has(tag)))
+      }
+
+      return templates
+    })
+  }
+
+  const updateTemplateEffect = (templateId: RecordIdInput, patch: UpdateTemplatePatch) =>
+    Effect.gen(function* () {
+      const updated = yield* db.update(
+        TABLES.PLAN_TEMPLATE,
+        ensureRecordId(templateId, TABLES.PLAN_TEMPLATE),
+        patch,
+        PlanTemplateRecordSchema,
+      )
+      if (!updated) {
+        return yield* new PlanTemplateNotFoundError({
+          templateId: recordIdToString(templateId, TABLES.PLAN_TEMPLATE),
+          message: `Template not found: ${recordIdToString(templateId, TABLES.PLAN_TEMPLATE)}`,
+        })
+      }
+
+      return updated
+    })
+
+  const upsertTemplateBySourceRefEffect = (
+    params: CreateTemplateParams & { source: 'user' | 'playbook' | 'system'; sourceRef: string },
+  ) =>
+    Effect.gen(function* () {
+      const existing = yield* getTemplateBySourceRefEffect({
+        organizationId: params.organizationId,
+        source: params.source,
+        sourceRef: params.sourceRef,
+      })
+
+      if (!existing) {
+        return yield* createTemplateEffect(params)
+      }
+
+      return yield* updateTemplateEffect(existing.id, {
+        name: params.name,
+        description: params.description,
+        draft: params.draft,
+        tags: params.tags ?? [],
+      })
+    })
+
+  const deleteTemplateEffect = (templateId: RecordIdInput) =>
+    db.deleteById(TABLES.PLAN_TEMPLATE, ensureRecordId(templateId, TABLES.PLAN_TEMPLATE)).pipe(Effect.asVoid)
+
+  const instantiateEffect = (params: InstantiateTemplateParams) =>
+    Effect.gen(function* () {
+      const template = yield* getTemplateEffect(params.templateId)
+      if (!template) {
+        return yield* new PlanTemplateNotFoundError({
+          templateId: recordIdToString(params.templateId, TABLES.PLAN_TEMPLATE),
+          message: `Template not found: ${recordIdToString(params.templateId, TABLES.PLAN_TEMPLATE)}`,
+        })
+      }
+
+      const draft: PlanDraft = { ...template.draft, ...params.overrides }
+
+      if (params.carryForwardArtifacts && params.carryForwardArtifacts.length > 0) {
+        const carryContext = params.carryForwardArtifacts.map((a) => `[carry-forward] ${a.name}: ${a.pointer}`)
+        draft.objective = `${draft.objective}\n\nCarry-forward context:\n${carryContext.join('\n')}`
+      }
+
+      return yield* deps.executionPlanService.createPlan({
+        organizationId: params.organizationId,
+        threadId: params.threadId,
+        sourceThreadId: params.sourceThreadId,
+        leadAgentId: params.leadAgentId,
+        createdByAgentId: params.createdByAgentId,
+        requireApproval: params.requireApproval,
+        input: draft,
+      })
+    })
+
+  return {
+    createTemplate: createTemplateEffect,
+    getTemplate: getTemplateEffect,
+    getTemplateBySourceRef: getTemplateBySourceRefEffect,
+    listTemplates: listTemplatesEffect,
+    updateTemplate: updateTemplateEffect,
+    upsertTemplateBySourceRef: upsertTemplateBySourceRefEffect,
+    deleteTemplate: deleteTemplateEffect,
+    instantiate: instantiateEffect,
+  }
+}
+
+export class PlanTemplateServiceTag extends Context.Service<
+  PlanTemplateServiceTag,
+  ReturnType<typeof makePlanTemplateService>
+>()('PlanTemplateService') {}
+
+export const PlanTemplateServiceLive = Layer.effect(
+  PlanTemplateServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    const executionPlanService = yield* ExecutionPlanServiceTag
+    return makePlanTemplateService({ db, executionPlanService })
+  }),
+)

package/src/services/plan/plan-transaction-events.ts

@@ -0,0 +1,33 @@
+import type { PlanEventRecord } from '@lota-sdk/shared'
+import { Schema, Effect } from 'effect'
+
+import type { DatabaseTransaction, SurrealDBService } from '../../db/service'
+import type { makePlanEventDeliveryService } from './plan-event-delivery.service'
+
+class PlanTransactionEventsError extends Schema.TaggedErrorClass<PlanTransactionEventsError>()(
+  'PlanTransactionEventsError',
+  { message: Schema.String, cause: Schema.optional(Schema.Defect) },
+) {}
+
+export function withTransactionAndEventsEffect<T, E, R>(params: {
+  db: SurrealDBService
+  planEventDeliveryService: ReturnType<typeof makePlanEventDeliveryService>
+  run: (tx: DatabaseTransaction, emittedEvents: PlanEventRecord[]) => Effect.Effect<T, E, R>
+}) {
+  return Effect.gen(function* () {
+    const emittedEvents: PlanEventRecord[] = []
+    const result = yield* params.db
+      .withTransaction((tx) => params.run(tx, emittedEvents))
+      .pipe(
+        Effect.mapError(
+          (error) => new PlanTransactionEventsError({ message: 'Failed to run plan transaction.', cause: error }),
+        ),
+      )
+    yield* Effect.tryPromise({
+      try: () => params.planEventDeliveryService.dispatchEvents(emittedEvents),
+      catch: (error) =>
+        new PlanTransactionEventsError({ message: 'Failed to dispatch plan transaction events.', cause: error }),
+    })
+    return result
+  })
+}