effect 4.0.4 → 4.0.5

package/src/workflow/WorkflowEngine.ts

@@ -84,6 +84,9 @@ export class WorkflowEngine extends Context.Service<
      * `suspendedRetrySchedule`; engines that observe the final result wake it
      * sooner. `ClusterWorkflowEngine` does so only for callers on the runner
      * that owns the execution.
+     *
+     * `detached: true` requires `discard: true` and skips parent completion
+     * wakes and interruption linkage. Otherwise, it is a defect.
      */
     readonly execute: <
       Name extends string,
@@ -97,6 +100,7 @@ export class WorkflowEngine extends Context.Service<
         readonly executionId: string
         readonly payload: Payload["Type"]
         readonly discard?: Discard | undefined
+        readonly detached?: boolean | undefined
         readonly suspendedRetrySchedule?:
           | Schedule.Schedule<any, unknown>
           | undefined
@@ -280,6 +284,12 @@ export class WorkflowInstance extends Context.Service<
      */
     cause: Cause.Cause<never> | undefined
 
+    /**
+     * Whether this workflow or an activity hit `SuspendOnFailure`, excluding
+     * inherited child failures.
+     */
+    failed: boolean
+
     /**
      * Deferred names this run waits on, counted per live wait; their
      * completions preempt the run.
@@ -298,17 +308,26 @@ export class WorkflowInstance extends Context.Service<
   static initial(
     workflow: Workflow.Any,
     executionId: string,
-    scope = Scope.makeUnsafe()
+    options?: {
+      readonly scope?: Scope.Closeable | undefined
+      /**
+       * Awaited deferred names shared with the run this instance belongs to.
+       * An activity instance registers its durable waits there so the run
+       * can be woken once it suspends, without those waits preempting it.
+       */
+      readonly awaitedDeferreds?: Map<string, number> | undefined
+    }
   ): WorkflowInstance["Service"] {
     return WorkflowInstance.of({
       executionId,
       workflow,
-      scope,
+      scope: options?.scope ?? Scope.makeUnsafe(),
       suspended: false,
       interrupted: false,
       abandoned: false,
       cause: undefined,
-      awaitedDeferreds: new Map(),
+      failed: false,
+      awaitedDeferreds: options?.awaitedDeferreds ?? new Map(),
       completedDeferreds: new Set(),
       activityState: {
         count: 0,
@@ -406,6 +425,8 @@ export interface Encoded {
       readonly payload: object
       readonly discard: Discard
       readonly parent?: WorkflowInstance["Service"] | undefined
+      /** Skip parent completion wakes and interruption linkage. */
+      readonly detached?: boolean | undefined
     }
   ) => Effect.Effect<
     Discard extends true ? void : Workflow.Result<unknown, unknown>
@@ -514,11 +535,15 @@ export const makeUnsafe = (options: Encoded): WorkflowEngine["Service"] =>
         readonly executionId: string
         readonly payload: Payload["Type"]
         readonly discard?: Discard | undefined
+        readonly detached?: boolean | undefined
         readonly suspendedRetrySchedule?:
           | Schedule.Schedule<any, unknown>
           | undefined
       }
     ) {
+      if (opts.detached && !opts.discard) {
+        return yield* Effect.die(`${self._tag}.execute: detached requires discard`)
+      }
       const payload = opts.payload
       const executionId = opts.executionId
       const suspendedRetrySchedule = opts.suspendedRetrySchedule ?? defaultRetrySchedule
@@ -527,7 +552,7 @@ export const makeUnsafe = (options: Encoded): WorkflowEngine["Service"] =>
 
       // link interruption with parent workflow
       const parentInstance = yield* Effect.serviceOption(WorkflowInstance)
-      if (Option.isSome(parentInstance)) {
+      if (Option.isSome(parentInstance) && !opts.detached) {
         const instance = parentInstance.value
         yield* Effect.addFinalizer(() => {
           if (!instance.interrupted || (Option.isSome(result) && result.value._tag === "Complete")) {
@@ -540,7 +565,8 @@ export const makeUnsafe = (options: Encoded): WorkflowEngine["Service"] =>
         executionId,
         payload: payload as object,
         discard: opts.discard ?? false,
-        parent: Option.getOrUndefined(parentInstance)
+        parent: Option.getOrUndefined(parentInstance),
+        detached: opts.detached
       }) as Effect.Effect<Workflow.Result<Success["Type"], Error["Type"]>>
 
       if (opts.discard) {
@@ -675,6 +701,11 @@ const defaultRetrySchedule = Schedule.min([
   Schedule.spaced(30000)
 ])
 
+type WakeMode = "explicit" | "automatic"
+
+const isUnwakeable = (result: Workflow.Result<unknown, unknown>, mode: WakeMode) =>
+  result._tag === "Complete" || (mode === "automatic" && result.failed === true)
+
 /**
  * Layer that provides an in-memory `WorkflowEngine`.
  *
@@ -714,7 +745,8 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
       readonly parent: string | undefined
       instance: WorkflowInstance["Service"]
       interrupted: boolean
-      resumeRequested: boolean
+      // The strongest wake requested while a run was still finishing.
+      resumeRequested: WakeMode | undefined
       fiber: Fiber.Fiber<Workflow.Result<unknown, unknown>> | undefined
       // Completed once a run succeeds with `Complete`, after which it cannot resume.
       readonly done: Deferred.Deferred<void>
@@ -728,21 +760,22 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
 
     const deferredState = makeDeferredState()
 
-    const resume = Effect.fnUntraced(function*(executionId: string): Effect.fn.Return<void> {
+    const resume = Effect.fnUntraced(function*(executionId: string, mode: WakeMode): Effect.fn.Return<void> {
       const state = executions.get(executionId)
       if (!state) return
       const exit = state.fiber?.pollUnsafe()
-      if (exit && exit._tag === "Success" && exit.value._tag === "Complete") {
+      if (exit && exit._tag === "Success" && isUnwakeable(exit.value, mode)) {
         return
       } else if (state.fiber && !exit) {
-        // A child can finish while the parent is still releasing its activity.
-        // Preserve the wake until that run has published its suspended result.
-        if (!state.resumeRequested) {
-          state.resumeRequested = true
+        // Queue wakes until the run finishes cleanup; explicit wakes take priority.
+        const requested = state.resumeRequested
+        state.resumeRequested = mode === "explicit" ? mode : requested ?? mode
+        if (requested === undefined) {
           yield* Fiber.await(state.fiber).pipe(
             Effect.flatMap(() => {
-              state.resumeRequested = false
-              return resume(executionId)
+              const mode = state.resumeRequested!
+              state.resumeRequested = undefined
+              return resume(executionId, mode)
             }),
             Effect.forkIn(scope)
           )
@@ -754,7 +787,7 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
       const instance = WorkflowInstance.initial(
         state.instance.workflow,
         state.instance.executionId,
-        state.instance.scope
+        { scope: state.instance.scope }
       )
       state.instance = instance
       state.fiber = yield* state.execute(state.payload, state.instance.executionId).pipe(
@@ -773,7 +806,7 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
           if (!state.parent || result._tag !== "Complete") {
             return Effect.void
           }
-          return Effect.forkIn(resume(state.parent), scope)
+          return Effect.forkIn(resume(state.parent, "automatic"), scope)
         }),
         Effect.onExit((exit) => {
           return Exit.isSuccess(exit) && exit.value._tag === "Complete"
@@ -809,13 +842,13 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
             execute: entry.execute,
             instance: WorkflowInstance.initial(workflow, options.executionId),
             interrupted: false,
-            resumeRequested: false,
+            resumeRequested: undefined,
             fiber: undefined,
             done: Deferred.makeUnsafe(),
-            parent: options.parent?.executionId
+            parent: options.detached ? undefined : options.parent?.executionId
           }
           executions.set(options.executionId, state)
-          yield* resume(options.executionId)
+          yield* resume(options.executionId, "explicit")
         }
         if (options.discard) return
         // Capture together so a wake that swaps in a replay cannot desync them.
@@ -836,7 +869,7 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
         const state = executions.get(executionId)
         if (!state) return
         state.interrupted = true
-        yield* resume(executionId)
+        yield* resume(executionId, "explicit")
       }),
       interruptUnsafe: Effect.fnUntraced(function*(_workflow, executionId) {
         const state = executions.get(executionId)
@@ -847,7 +880,7 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
         }
       }),
       resume(_workflow, executionId) {
-        return resume(executionId)
+        return resume(executionId, "explicit")
       },
       activityExecute: Effect.fnUntraced(function*(activity, attempt) {
         const instance = yield* WorkflowInstance
@@ -864,6 +897,11 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
           state = { exit: undefined }
           activities.set(activityId, state)
         }
+        // A pending interrupt replays only to rebuild compensations, so it must
+        // not run new activities. Finalizers run once `interrupted` is set.
+        if (executions.get(instance.executionId)?.interrupted && !instance.interrupted) {
+          return new Workflow.Suspended({})
+        }
         const activityInstance = WorkflowInstance.initial(instance.workflow, instance.executionId)
         activityInstance.interrupted = instance.interrupted
         return yield* activity.executeEncoded.pipe(
@@ -902,7 +940,7 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
           deferredResults.set(id, options.exit)
           const wake = Effect.andThen(
             deferredState.deferredDone(options.executionId, options.deferredName),
-            resume(options.executionId)
+            resume(options.executionId, "automatic")
           )
           return Effect.flatMap(Effect.serviceOption(WorkflowInstance), (instance) =>
             // A workflow finalizer cannot wait for its own run's cleanup.