@yolk-sdk/harness 0.1.0-canary.77

package/src/driver/durable-object.ts

@@ -0,0 +1,34 @@
+import { Layer } from 'effect'
+import type { Effect } from 'effect'
+import {
+  makeDriverLayer,
+  type Drain,
+  type Driver,
+  type InvalidMaxResumeAttempts
+} from '../driver.ts'
+import { makeInMemoryInboxLayer } from '../inbox.ts'
+import type { Inbox } from '../inbox.ts'
+import { makeSnapshotRunStoreLayer, type DurableRunStoreSnapshot, type RunStore } from '../store.ts'
+
+export type { DurableRunStoreSnapshot }
+
+type DurableObjectDriverBase = {
+  readonly load: Effect.Effect<DurableRunStoreSnapshot | undefined>
+  readonly save: (snapshot: DurableRunStoreSnapshot) => Effect.Effect<void>
+  readonly drain?: Drain
+}
+
+export function makeDurableObjectDriverLayer(
+  options: DurableObjectDriverBase & { readonly maxResumeAttempts?: undefined }
+): Layer.Layer<Driver | RunStore | Inbox>
+export function makeDurableObjectDriverLayer(
+  options: DurableObjectDriverBase & { readonly maxResumeAttempts?: number }
+): Layer.Layer<Driver | RunStore | Inbox, InvalidMaxResumeAttempts>
+export function makeDurableObjectDriverLayer(
+  options: DurableObjectDriverBase & { readonly maxResumeAttempts?: number }
+) {
+  return makeDriverLayer(options).pipe(
+    Layer.provideMerge(makeSnapshotRunStoreLayer(options)),
+    Layer.provideMerge(makeInMemoryInboxLayer())
+  )
+}

package/src/driver/memory.ts

@@ -0,0 +1,38 @@
+import { Layer } from 'effect'
+import {
+  makeDriverLayer,
+  type Drain,
+  type Driver,
+  type DriverLayerOptions,
+  type InvalidMaxResumeAttempts
+} from '../driver.ts'
+import { makeInMemoryInboxLayer, type Inbox } from '../inbox.ts'
+import { makeInMemoryRunStoreLayer, type RunStore } from '../store.ts'
+
+export function makeInMemoryDriverLayer(): Layer.Layer<Driver, never, RunStore | Inbox>
+export function makeInMemoryDriverLayer(options?: {
+  readonly drain?: Drain
+  readonly maxResumeAttempts?: undefined
+}): Layer.Layer<Driver, never, RunStore | Inbox>
+export function makeInMemoryDriverLayer(
+  options?: DriverLayerOptions
+): Layer.Layer<Driver, InvalidMaxResumeAttempts, RunStore | Inbox>
+export function makeInMemoryDriverLayer(options?: DriverLayerOptions) {
+  return options === undefined ? makeDriverLayer() : makeDriverLayer(options)
+}
+
+export function makeInMemoryHarnessLayer(): Layer.Layer<Driver | RunStore | Inbox>
+export function makeInMemoryHarnessLayer(options?: {
+  readonly drain?: Drain
+  readonly maxResumeAttempts?: undefined
+}): Layer.Layer<Driver | RunStore | Inbox>
+export function makeInMemoryHarnessLayer(
+  options?: DriverLayerOptions
+): Layer.Layer<Driver | RunStore | Inbox, InvalidMaxResumeAttempts>
+export function makeInMemoryHarnessLayer(options?: DriverLayerOptions) {
+  const driver = options === undefined ? makeDriverLayer() : makeDriverLayer(options)
+  return driver.pipe(
+    Layer.provideMerge(makeInMemoryRunStoreLayer()),
+    Layer.provideMerge(makeInMemoryInboxLayer())
+  )
+}

package/src/driver.ts

@@ -0,0 +1,250 @@
+import { Cause, Context, Data, Effect, Exit, Layer, Semaphore } from 'effect'
+import { makeCoordinator, type Promotable } from './coordinator.ts'
+import {
+  Inbox,
+  type HitlAdmission,
+  type HitlDecision,
+  type InboxItem,
+  type ParkedResponse,
+  type PauseDecision
+} from './inbox.ts'
+import { RunStore } from './store.ts'
+
+export type InterruptReason = 'user' | 'shutdown'
+
+export const defaultMaxResumeAttempts = 10
+
+export class InvalidMaxResumeAttempts extends Data.TaggedError('InvalidMaxResumeAttempts')<{
+  readonly maxResumeAttempts: number
+}> {}
+
+const isValidMaxResumeAttempts = (value: number) => Number.isSafeInteger(value) && value >= 0
+
+export type ResumeSuspendedResult = {
+  readonly resumed: ReadonlyArray<string>
+  readonly exhausted: ReadonlyArray<string>
+}
+
+export type DrainContext = {
+  readonly drainToken: string
+  readonly readyResponses: ReadonlyArray<ParkedResponse>
+}
+
+export type Drain = (
+  runId: string,
+  force: boolean,
+  scope: Promotable,
+  context: DrainContext
+) => Effect.Effect<void, never, Inbox | RunStore>
+
+export type DriverLayerOptions = {
+  readonly drain?: Drain
+  readonly maxResumeAttempts?: number
+}
+
+export type StopDecision =
+  | { readonly _tag: 'Interrupted' }
+  | { readonly _tag: 'ParkCleared' }
+  | { readonly _tag: 'Idle' }
+
+export type DriverShape = {
+  readonly active: Effect.Effect<ReadonlySet<string>>
+  readonly isActive: (runId: string) => Effect.Effect<boolean>
+  readonly run: (runId: string) => Effect.Effect<void>
+  readonly wake: (runId: string, scope?: Promotable) => Effect.Effect<void>
+  readonly interrupt: (
+    runId: string,
+    options?: { readonly reason?: InterruptReason; readonly awaitSettlement?: boolean }
+  ) => Effect.Effect<boolean>
+  readonly awaitIdle: (runId: string) => Effect.Effect<void>
+  readonly resumeSuspended: Effect.Effect<ResumeSuspendedResult>
+  readonly admit: (item: InboxItem) => Effect.Effect<void>
+  readonly pause: (
+    runId: string,
+    requestIds: ReadonlyArray<string>,
+    drainToken: string
+  ) => Effect.Effect<PauseDecision>
+  readonly resumeHitl: (runId: string, admission: HitlAdmission) => Effect.Effect<HitlDecision>
+  readonly stop: (runId: string) => Effect.Effect<StopDecision>
+}
+
+export class Driver extends Context.Service<Driver, DriverShape>()('@yolk-sdk/harness/Driver') {}
+
+export const makeHarness = <DE, DR, SE, SR, IE, IR>(input: {
+  readonly driver: Layer.Layer<Driver, DE, DR>
+  readonly store: Layer.Layer<RunStore, SE, SR>
+  readonly inbox: Layer.Layer<Inbox, IE, IR>
+}): Layer.Layer<Driver | RunStore | Inbox, DE | SE | IE, DR | SR | IR> =>
+  Layer.mergeAll(input.driver, input.store, input.inbox)
+
+export const admit = (item: InboxItem) => Effect.flatMap(Driver, driver => driver.admit(item))
+
+const makeValidatedDriverLayer = (
+  maxResumeAttempts: number,
+  hostDrain: Drain
+): Layer.Layer<Driver, never, RunStore | Inbox> =>
+  Layer.effect(
+    Driver,
+    Effect.gen(function* () {
+      const store = yield* RunStore
+      const inbox = yield* Inbox
+      const sweep = yield* Semaphore.make(1)
+      const acquired = new Set<string>()
+      const coordinator = yield* makeCoordinator<string, never, InterruptReason>({
+        drain: (runId, force, scope) =>
+          inbox.beginDrain(runId, scope).pipe(
+            Effect.flatMap(begun => {
+              if (begun._tag === 'Skip') return Effect.void
+              return Effect.suspend(() =>
+                hostDrain(runId, force, scope, {
+                  drainToken: begun.drainToken,
+                  readyResponses: begun.readyResponses
+                })
+              ).pipe(
+                Effect.provideService(Inbox, inbox),
+                Effect.provideService(RunStore, store),
+                Effect.onExit(exit => inbox.endDrain(runId, begun.drainToken, Exit.isSuccess(exit)))
+              )
+            })
+          ),
+        started: runId =>
+          store.claim(runId).pipe(
+            Effect.tap(() =>
+              Effect.sync(() => {
+                acquired.add(runId)
+              })
+            )
+          ),
+        settled: (runId, exit, reason) =>
+          Effect.suspend(() => {
+            const owned = acquired.delete(runId)
+            if (
+              owned &&
+              (reason === 'user' || (reason === undefined && !Exit.hasInterrupts(exit)))
+            ) {
+              return store.release(runId)
+            }
+            // Acquisition receipt guards automatic failed-start settlement only.
+            // Explicit user-terminal authority still releases a leftover claim
+            // after this owner has actually settled, matching Idle/Settling stop.
+            if (reason === 'user' && !owned) {
+              return store
+                .isClaimed(runId)
+                .pipe(Effect.flatMap(claimed => (claimed ? store.release(runId) : Effect.void)))
+            }
+            return Effect.void
+          }).pipe(
+            Effect.exit,
+            Effect.flatMap(settledExit => {
+              if (Exit.isSuccess(settledExit)) return Effect.void
+              return Effect.failCause(
+                Exit.isFailure(exit)
+                  ? Cause.combine(exit.cause, settledExit.cause)
+                  : settledExit.cause
+              )
+            })
+          )
+      })
+
+      const resumeSuspended = sweep.withPermits(1)(
+        Effect.gen(function* () {
+          const claimed = yield* store.claimed
+          const resumed: Array<string> = []
+          const exhausted: Array<string> = []
+
+          for (const runId of claimed) {
+            const admission = yield* inbox.admitRecovery(
+              runId,
+              Effect.gen(function* () {
+                if (yield* coordinator.isActive(runId)) return { _tag: 'Skip' } as const
+                if (!(yield* store.isClaimed(runId))) return { _tag: 'Skip' } as const
+                const count = yield* store.resumeCount(runId)
+                if (count >= maxResumeAttempts) {
+                  yield* store.release(runId)
+                  return { _tag: 'Exhausted' } as const
+                }
+                yield* store.incrementResumeCount(runId)
+                return { _tag: 'Resume' } as const
+              }),
+              coordinator.wake(runId, 'input')
+            )
+            if (admission._tag === 'Resumed') resumed.push(runId)
+            else if (admission._tag === 'Exhausted') exhausted.push(runId)
+          }
+
+          return { resumed, exhausted }
+        })
+      )
+
+      return Driver.of({
+        active: coordinator.active,
+        isActive: coordinator.isActive,
+        run: runId => {
+          const continueRun = (): Effect.Effect<void> =>
+            inbox.startIfUnblocked(runId, coordinator.captureRun(runId)).pipe(
+              Effect.flatMap(ticket => {
+                if (ticket === undefined) return Effect.void
+                if (ticket._tag === 'Stopping') {
+                  return ticket.awaitSettlement.pipe(Effect.andThen(Effect.suspend(continueRun)))
+                }
+                return ticket.join
+              })
+            )
+          return continueRun()
+        },
+        wake: (runId, scope = 'input') =>
+          inbox.wakeIfUnblocked(runId, scope, coordinator.wake(runId, scope)).pipe(Effect.asVoid),
+        interrupt: (runId, interruptOptions) =>
+          coordinator.interrupt(runId, interruptOptions?.reason ?? 'user', interruptOptions),
+        awaitIdle: coordinator.awaitIdle,
+        resumeSuspended,
+        admit: item =>
+          inbox.enqueueAndWake(
+            item,
+            coordinator.wake(item.runId, item.delivery === 'steer' ? 'steer' : 'input')
+          ),
+        pause: (runId, requestIds, drainToken) => inbox.park(runId, requestIds, drainToken),
+        resumeHitl: (runId, admission) =>
+          inbox.acceptHitl(runId, admission, coordinator.wake(runId, 'input')),
+        stop: runId =>
+          inbox
+            .invalidate(
+              runId,
+              coordinator
+                .terminalStop(runId, 'user')
+                .pipe(
+                  Effect.map(
+                    receipt => receipt._tag === 'Interrupted' || receipt._tag === 'LiveStopping'
+                  )
+                ),
+              store
+                .isClaimed(runId)
+                .pipe(Effect.flatMap(claimed => (claimed ? store.release(runId) : Effect.void)))
+            )
+            .pipe(
+              Effect.map(result => {
+                if (result.interrupted) return { _tag: 'Interrupted' } as const
+                if (result.hadPark) return { _tag: 'ParkCleared' } as const
+                return { _tag: 'Idle' } as const
+              })
+            )
+      })
+    })
+  )
+
+export function makeDriverLayer(): Layer.Layer<Driver, never, RunStore | Inbox>
+export function makeDriverLayer(options?: {
+  readonly drain?: Drain
+  readonly maxResumeAttempts?: undefined
+}): Layer.Layer<Driver, never, RunStore | Inbox>
+export function makeDriverLayer(
+  options?: DriverLayerOptions
+): Layer.Layer<Driver, InvalidMaxResumeAttempts, RunStore | Inbox>
+export function makeDriverLayer(options?: DriverLayerOptions) {
+  const hostDrain = options?.drain ?? ((_runId, _force, _scope, _context) => Effect.void)
+  const maxResumeAttempts = options?.maxResumeAttempts ?? defaultMaxResumeAttempts
+  if (!isValidMaxResumeAttempts(maxResumeAttempts)) {
+    return Layer.effect(Driver, Effect.fail(new InvalidMaxResumeAttempts({ maxResumeAttempts })))
+  }
+  return makeValidatedDriverLayer(maxResumeAttempts, hostDrain)
+}