effect-cf 0.20.1 → 0.23.0

package/src/Workflow.ts

@@ -1,3 +1,7 @@
+/**
+ * Effect wrapper for Cloudflare Workflows entrypoints and bindings; distinct
+ * from Effect's runtime-agnostic `effect/unstable/workflow` cluster module.
+ */
 import {
   WorkflowEntrypoint as CloudflareWorkflowEntrypoint,
   type WorkflowEvent as CloudflareWorkflowEvent,
@@ -8,13 +12,15 @@ import {
   type WorkflowStepEvent,
   type WorkflowTimeoutDuration,
 } from "cloudflare:workers";
-import { ConfigProvider, Context, Effect, Layer, ManagedRuntime, type Scope } from "effect";
+import { Context, Data, Effect, Layer, type ManagedRuntime, type Scope } from "effect";
 
-import { WorkerConfig, WorkerEnvironment, type WorkerEnv } from "./Environment";
+import { WorkerEnvironment, type WorkerEnv } from "./Environment";
 import { ExecutionContext, WorkerContext } from "./Worker";
 import * as WorkflowDefinition from "./WorkflowDefinition";
 import * as Entrypoint from "./internal/Entrypoint";
-import { fromExecutionContext, type RunWaitUntilEffect } from "./internal/WorkerContext";
+import * as ErrorMessage from "./internal/ErrorMessage";
+import * as Runtime from "./internal/Runtime";
+import { fromExecutionContext } from "./internal/WorkerContext";
 
 export interface WorkflowEventService<Payload = unknown> {
   readonly raw: CloudflareWorkflowEvent<unknown>;
@@ -30,22 +36,41 @@ export class WorkflowEvent extends Context.Service<WorkflowEvent, WorkflowEventS
 
 type RunWorkflowStepEffect = <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>;
 
+/** Failure raised when a Cloudflare Workflow step operation rejects. */
+export class WorkflowStepError extends Data.TaggedError("WorkflowStepError")<{
+  readonly step?: string;
+  readonly operation: string;
+  readonly cause: unknown;
+}> {
+  override get message(): string {
+    const step = this.step === undefined ? "" : ` in step "${this.step}"`;
+
+    return `Workflow ${this.operation} failed${step}: ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
+
 export interface WorkflowStepService {
   readonly raw: CloudflareWorkflowStep;
   do<A, E, R>(
     name: string,
     effect: Effect.Effect<A, E, R>,
     config?: WorkflowStepConfig,
-  ): Effect.Effect<A, unknown, Exclude<R, WorkflowStepContext>>;
-  readonly sleep: (name: string, duration: WorkflowSleepDuration) => Effect.Effect<void, unknown>;
-  readonly sleepUntil: (name: string, timestamp: Date | number) => Effect.Effect<void, unknown>;
+  ): Effect.Effect<A, WorkflowStepError, Exclude<R, WorkflowStepContext>>;
+  readonly sleep: (
+    name: string,
+    duration: WorkflowSleepDuration,
+  ) => Effect.Effect<void, WorkflowStepError>;
+  readonly sleepUntil: (
+    name: string,
+    timestamp: Date | number,
+  ) => Effect.Effect<void, WorkflowStepError>;
   readonly waitForEvent: <Payload>(
     name: string,
     options: {
       readonly type: string;
       readonly timeout?: WorkflowTimeoutDuration | number;
     },
-  ) => Effect.Effect<WorkflowStepEvent<Payload>, unknown>;
+  ) => Effect.Effect<WorkflowStepEvent<Payload>, WorkflowStepError>;
 }
 
 export class WorkflowStep extends Context.Service<WorkflowStep, WorkflowStepService>()(
@@ -104,19 +129,19 @@ const fromWorkflowStep = (
 
             return config === undefined ? rawStep.do(name, run) : rawStep.do(name, config, run);
           },
-          catch: (cause) => cause,
+          catch: (cause) => new WorkflowStepError({ step: name, operation: "do", cause }),
         }),
       ),
-    ) as Effect.Effect<A, unknown, Exclude<R, WorkflowStepContext>>,
+    ) as Effect.Effect<A, WorkflowStepError, Exclude<R, WorkflowStepContext>>,
   sleep: (name, duration) =>
     Effect.tryPromise({
       try: () => step.sleep(name, duration),
-      catch: (cause) => cause,
+      catch: (cause) => new WorkflowStepError({ step: name, operation: "sleep", cause }),
     }),
   sleepUntil: (name, timestamp) =>
     Effect.tryPromise({
       try: () => step.sleepUntil(name, timestamp),
-      catch: (cause) => cause,
+      catch: (cause) => new WorkflowStepError({ step: name, operation: "sleepUntil", cause }),
     }),
   waitForEvent: <Payload>(
     name: string,
@@ -127,7 +152,7 @@ const fromWorkflowStep = (
   ) =>
     Effect.tryPromise({
       try: () => step.waitForEvent(name, options) as Promise<WorkflowStepEvent<Payload>>,
-      catch: (cause) => cause,
+      catch: (cause) => new WorkflowStepError({ step: name, operation: "waitForEvent", cause }),
     }),
 });
 
@@ -167,28 +192,18 @@ export const make = <ROut, LayerError, Payload = unknown, Result = unknown>(
     constructor(ctx: globalThis.ExecutionContext, env: WorkerEnv) {
       super(ctx, env);
 
-      let runWaitUntilEffect: RunWaitUntilEffect = () =>
-        Promise.reject(new Error("WorkerContext runtime is not initialized"));
-
-      const services = Layer.mergeAll(
-        Layer.succeed(ExecutionContext, ctx),
-        ConfigProvider.layer(Effect.succeed(WorkerConfig.providerFromEnv(env))),
-        Layer.succeed(
-          WorkerContext,
-          fromExecutionContext(ctx, (effect) => runWaitUntilEffect(effect)),
-        ),
-        Layer.succeed(WorkerEnvironment, env),
-      ) as Layer.Layer<ExecutionContext | WorkerContext | WorkerEnvironment, never, never>;
-
-      const runtimeLayer = Entrypoint.provideEntrypointServices<
+      this.runtime = Runtime.makeEntrypointRuntime<
         ROut,
         LayerError,
-        ExecutionContext | WorkerContext | WorkerEnvironment
-      >(layer, services);
-
-      this.runtime = ManagedRuntime.make(runtimeLayer);
-      runWaitUntilEffect = <A, E>(effect: Effect.Effect<A, E, never>) =>
-        this.runtime.runPromiseExit(effect as Effect.Effect<A, E, RuntimeContext<ROut>>);
+        ExecutionContext | WorkerContext
+      >(
+        layer,
+        env,
+        Layer.mergeAll(
+          Layer.succeed(ExecutionContext, ctx),
+          Layer.succeed(WorkerContext, fromExecutionContext(ctx)),
+        ),
+      );
     }
 
     run(
@@ -199,21 +214,11 @@ export const make = <ROut, LayerError, Payload = unknown, Result = unknown>(
         Layer.succeed(WorkflowEvent, fromWorkflowEvent(event)),
         Layer.succeed(
           WorkflowStep,
-          fromWorkflowStep(
-            step,
-            (effect) =>
-              this.runtime.runPromise(
-                effect as Effect.Effect<unknown, unknown, RuntimeContext<ROut>>,
-              ) as never,
-          ),
+          fromWorkflowStep(step, (effect) => this.runtime.runPromise(effect)),
         ),
       );
 
-      return this.runtime.runPromise(
-        Effect.scoped(
-          options.run(event.payload).pipe(Effect.provide(workflowServices)),
-        ) as Effect.Effect<Result, unknown, RuntimeContext<ROut>>,
-      );
+      return Runtime.runEventPromise(this.runtime, options.run(event.payload), workflowServices);
     }
   }
 
@@ -224,21 +229,21 @@ export const step = <A, E, R>(
   name: string,
   effect: Effect.Effect<A, E, R>,
   config?: WorkflowStepConfig,
-): Effect.Effect<A, unknown, WorkflowStep | Exclude<R, WorkflowStepContext>> =>
+): Effect.Effect<A, WorkflowStepError, WorkflowStep | Exclude<R, WorkflowStepContext>> =>
   Effect.flatMap(WorkflowStep, (workflowStep) =>
     workflowStep.do(name, effect, config),
-  ) as Effect.Effect<A, unknown, WorkflowStep | Exclude<R, WorkflowStepContext>>;
+  ) as Effect.Effect<A, WorkflowStepError, WorkflowStep | Exclude<R, WorkflowStepContext>>;
 
 export const sleep = (
   name: string,
   duration: WorkflowSleepDuration,
-): Effect.Effect<void, unknown, WorkflowStep> =>
+): Effect.Effect<void, WorkflowStepError, WorkflowStep> =>
   Effect.flatMap(WorkflowStep, (workflowStep) => workflowStep.sleep(name, duration));
 
 export const sleepUntil = (
   name: string,
   timestamp: Date | number,
-): Effect.Effect<void, unknown, WorkflowStep> =>
+): Effect.Effect<void, WorkflowStepError, WorkflowStep> =>
   Effect.flatMap(WorkflowStep, (workflowStep) => workflowStep.sleepUntil(name, timestamp));
 
 export const waitForEvent = <Payload>(
@@ -247,7 +252,7 @@ export const waitForEvent = <Payload>(
     readonly type: string;
     readonly timeout?: WorkflowTimeoutDuration | number;
   },
-): Effect.Effect<WorkflowStepEvent<Payload>, unknown, WorkflowStep> =>
+): Effect.Effect<WorkflowStepEvent<Payload>, WorkflowStepError, WorkflowStep> =>
   Effect.flatMap(WorkflowStep, (workflowStep) => workflowStep.waitForEvent<Payload>(name, options));
 
 export type Definition<

package/src/WorkflowBinding.ts

@@ -8,6 +8,7 @@ import { type Context, Data, Effect, Option, Schema as S } from "effect";
 
 import * as Binding from "./Binding";
 import type * as RpcDefinition from "./RpcDefinition";
+import * as ErrorMessage from "./internal/ErrorMessage";
 
 const expectedWorkflow = "Workflow binding with create(), createBatch(), and get()";
 
@@ -92,20 +93,28 @@ export interface WorkflowBindingClient<
   readonly get: (
     instanceId: string,
   ) => Effect.Effect<WorkflowInstance<S.Schema.Type<Result>>, WorkflowOperationError>;
-  readonly unsafeRaw: Effect.Effect<CloudflareWorkflow<S.Codec.Encoded<Payload>>>;
+  readonly rawUnsafe: Effect.Effect<CloudflareWorkflow<S.Codec.Encoded<Payload>>>;
 }
 
 export class WorkflowOperationError extends Data.TaggedError("WorkflowOperationError")<{
   readonly binding: string;
   readonly operation: string;
   readonly cause: unknown;
-}> {}
+}> {
+  override get message(): string {
+    return `Workflow ${this.operation} failed for binding "${this.binding}": ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 export class WorkflowResultDecodeError extends Data.TaggedError("WorkflowResultDecodeError")<{
   readonly binding: string;
   readonly instanceId: string;
   readonly cause: unknown;
-}> {}
+}> {
+  override get message(): string {
+    return `Workflow result decode failed for binding "${this.binding}" instance "${this.instanceId}": ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
 
 const workflowError = (binding: string, operation: string, cause: unknown) =>
   new WorkflowOperationError({ binding, operation, cause });
@@ -200,10 +209,9 @@ export const makeClient = <
   };
 
   return (workflow) => ({
-    create: Effect.fnUntraced(function* (
-      payload: PayloadValue,
-      options?: WorkflowInstanceCreateOptions<EncodedPayload>,
-    ) {
+    create: Effect.fn("WorkflowBinding.create", {
+      attributes: { binding: definition.binding, operation: "create" },
+    })(function* (payload: PayloadValue, options?: WorkflowInstanceCreateOptions<EncodedPayload>) {
       const encoded = yield* encodePayload(payload);
       const raw = yield* tryWorkflowPromise(definition.binding, "create", () =>
         workflow.create({ ...options, params: encoded }),
@@ -211,9 +219,9 @@ export const makeClient = <
 
       return wrapInstance(raw);
     }),
-    createBatch: Effect.fnUntraced(function* (
-      batch: WorkflowInstanceCreateBatchOptions<PayloadValue, EncodedPayload>,
-    ) {
+    createBatch: Effect.fn("WorkflowBinding.createBatch", {
+      attributes: { binding: definition.binding, operation: "createBatch" },
+    })(function* (batch: WorkflowInstanceCreateBatchOptions<PayloadValue, EncodedPayload>) {
       const encodedBatch: Array<CloudflareWorkflowInstanceCreateOptions<EncodedPayload>> = [];
 
       for (const item of batch) {
@@ -235,7 +243,7 @@ export const makeClient = <
       tryWorkflowPromise(definition.binding, "get", () => workflow.get(instanceId)).pipe(
         Effect.map(wrapInstance),
       ),
-    unsafeRaw: Effect.succeed(workflow),
+    rawUnsafe: Effect.succeed(workflow),
   });
 };
 

package/src/WorkflowDefinition.ts

@@ -46,7 +46,11 @@ export interface TagClass<
   Id extends string,
   Payload extends RpcDefinition.ServiceFreeSchema,
   Result extends RpcDefinition.ServiceFreeSchema,
-> extends Context.ServiceClass<Self, Id, WorkflowBinding.WorkflowBindingClient<Payload, Result>> {
+> extends Context.ServiceClass<
+  Self,
+  `effect-cf/Workflow/${Id}`,
+  WorkflowBinding.WorkflowBindingClient<Payload, Result>
+> {
   readonly id: Id;
   readonly payload: Payload;
   readonly result: Result;
@@ -86,11 +90,7 @@ export interface TagClass<
     WorkflowBinding.WorkflowOperationError,
     Self
   >;
-  readonly unsafeRaw: () => Effect.Effect<
-    globalThis.Workflow<S.Codec.Encoded<Payload>>,
-    never,
-    Self
-  >;
+  readonly rawUnsafe: Effect.Effect<globalThis.Workflow<S.Codec.Encoded<Payload>>, never, Self>;
 }
 
 const makeDefinition = <
@@ -148,7 +148,9 @@ export const Tag =
     },
   ) => {
     const workflowDefinition = makeDefinition(id, definition);
-    const tag = Context.Service<Self, WorkflowBinding.WorkflowBindingClient<Payload, Result>>()(id);
+    const tag = Context.Service<Self, WorkflowBinding.WorkflowBindingClient<Payload, Result>>()(
+      `effect-cf/Workflow/${id}` as const,
+    );
 
     const layer = (binding: LayerOptions) =>
       WorkflowBinding.layer(tag, {
@@ -183,11 +185,7 @@ export const Tag =
       return yield* workflow.get(instanceId);
     });
 
-    const unsafeRaw = Effect.fnUntraced(function* () {
-      const workflow = yield* tag;
-
-      return yield* workflow.unsafeRaw;
-    });
+    const rawUnsafe = Effect.flatMap(tag, (workflow) => workflow.rawUnsafe);
 
     return Object.assign(tag, {
       id: workflowDefinition.id,
@@ -198,7 +196,7 @@ export const Tag =
       create,
       createBatch,
       get,
-      unsafeRaw,
+      rawUnsafe,
     }) as TagClass<Self, Id, Payload, Result>;
   };
 
@@ -215,20 +213,19 @@ const wrapHandler = <ROut, const Self extends Definition.Any>(
   const decodePayload = S.decodeUnknownEffect(definition.payload);
   const encodeResult = S.encodeEffect(definition.result);
 
-  return (payload) =>
-    Effect.gen(function* () {
-      const decodedPayload = yield* decodePayload(payload);
-      const event = yield* WorkflowEntrypoint.WorkflowEvent;
-      const decodedEvent = {
-        ...event,
-        payload: decodedPayload,
-      } as WorkflowEntrypoint.WorkflowEventService<S.Schema.Type<Self["payload"]>>;
-      const result = yield* handler(decodedPayload as S.Schema.Type<Self["payload"]>).pipe(
-        Effect.provideService(WorkflowEntrypoint.WorkflowEvent, decodedEvent),
-      );
-
-      return yield* encodeResult(result as S.Schema.Type<Self["result"]>);
-    });
+  return Effect.fnUntraced(function* (payload: S.Codec.Encoded<Self["payload"]>) {
+    const decodedPayload = yield* decodePayload(payload);
+    const event = yield* WorkflowEntrypoint.WorkflowEvent;
+    const decodedEvent = {
+      ...event,
+      payload: decodedPayload,
+    } as WorkflowEntrypoint.WorkflowEventService<S.Schema.Type<Self["payload"]>>;
+    const result = yield* handler(decodedPayload as S.Schema.Type<Self["payload"]>).pipe(
+      Effect.provideService(WorkflowEntrypoint.WorkflowEvent, decodedEvent),
+    );
+
+    return yield* encodeResult(result as S.Schema.Type<Self["result"]>);
+  });
 };
 
 export const implement = <ROut, const Self extends Definition.Any>(

package/src/index.ts

@@ -13,9 +13,10 @@ export * as DurableObjectNamespace from "./DurableObjectNamespace";
 export * as DurableObjectRpcWebSocket from "./DurableObjectRpcWebSocket";
 export * as DurableObjectSqlite from "./DurableObjectSqlite";
 export * as DurableObjectState from "./DurableObjectState";
-export * as DurableObjectWebSocket from "./DurableObjectWebSocket";
 export * as DurableObjectStorage from "./DurableObjectStorage";
+export * as DurableObjectWebSocket from "./DurableObjectWebSocket";
 export * as Email from "./Email";
+export * as Environment from "./Environment";
 export * as Hyperdrive from "./Hyperdrive";
 export * as Images from "./Images";
 export * as Kv from "./Kv";
@@ -26,11 +27,11 @@ export * as R2 from "./R2";
 export * as Rpc from "./Rpc";
 export * as RpcDefinition from "./RpcDefinition";
 export * as ServiceBinding from "./ServiceBinding";
+export * as Vectorize from "./Vectorize";
 export * as Worker from "./Worker";
 export * as WorkerDefinition from "./WorkerDefinition";
+export * as WorkersAi from "./WorkersAi";
 export * as Workflow from "./Workflow";
 export * as WorkflowBinding from "./WorkflowBinding";
 export * as WorkflowDefinition from "./WorkflowDefinition";
-export * as Vectorize from "./Vectorize";
-export * as WorkersAi from "./WorkersAi";
 export { WorkerConfig, WorkerEnvironment, type WorkerEnv } from "./Environment";

package/src/internal/Entrypoint.ts

@@ -30,7 +30,9 @@ export const defineEntrypointRpcMethods = <Self>(
       value(this: Self, ...args: AnyArgs) {
         return run(
           this,
-          Effect.suspend(() => method(...args)),
+          Effect.suspend(() => method(...args)).pipe(
+            Effect.mapError(RpcDefinition.encodeWireError),
+          ),
         );
       },
     });

package/src/internal/ErrorMessage.ts

@@ -0,0 +1,24 @@
+/**
+ * Renders the most useful human-readable description of an unknown `cause`
+ * for use in tagged error `message` getters.
+ */
+export const causeMessage = (cause: unknown): string => {
+  if (typeof cause === "object" && cause !== null) {
+    const message = Reflect.get(cause, "message");
+
+    if (typeof message === "string" && message.length > 0) {
+      return message;
+    }
+  }
+
+  try {
+    return String(cause);
+  } catch {
+    return "unknown cause";
+  }
+};
+
+/** Renders a violation list as a single `path: message; ...` line. */
+export const violationsMessage = (
+  violations: ReadonlyArray<{ readonly path: string; readonly message: string }>,
+): string => violations.map((violation) => `${violation.path}: ${violation.message}`).join("; ");

package/src/internal/RpcInvocation.ts

@@ -58,17 +58,20 @@ export const lookupRpcMethod = <Api, Method extends AsyncMethodKey<Api>, Error>(
     catch: makeError,
   });
 
-export const invokeRpcMethod = <Api, Method extends AsyncMethodKey<Api>, Error>(
+export const invokeRpcMethod = Effect.fnUntraced(function* <
+  Api,
+  Method extends AsyncMethodKey<Api>,
+  Error,
+>(
   target: unknown,
   method: Method,
   args: AsyncMethodArgs<Api, Method>,
   makeError: (cause: unknown) => Error,
-): Effect.Effect<AsyncMethodCloudflareReturn<Api, Method>, Error> =>
-  Effect.gen(function* () {
-    const fn = yield* lookupRpcMethod<Api, Method, Error>(target, method, makeError);
+): Effect.fn.Return<AsyncMethodCloudflareReturn<Api, Method>, Error> {
+  const fn = yield* lookupRpcMethod<Api, Method, Error>(target, method, makeError);
 
-    return yield* Effect.try({
-      try: () => fn(...args),
-      catch: makeError,
-    });
+  return yield* Effect.try({
+    try: () => fn(...args),
+    catch: makeError,
   });
+});

package/src/internal/Runtime.ts

@@ -0,0 +1,52 @@
+import { ConfigProvider, Effect, Layer, ManagedRuntime, type Scope } from "effect";
+
+import { WorkerConfig, WorkerEnvironment, type WorkerEnv } from "../Environment";
+import { provideEntrypointServices } from "./Entrypoint";
+
+/**
+ * Assembles the shared `ManagedRuntime` used by the Cloudflare entrypoint
+ * classes (Worker, Durable Object, Workflow).
+ *
+ * The entrypoint-specific services are merged with the env-backed
+ * `ConfigProvider` and `WorkerEnvironment`, then provided to the user-supplied
+ * layer so the resulting runtime satisfies both the user services and the
+ * platform services.
+ */
+export const makeEntrypointRuntime = <ROut, LayerError, Services>(
+  layer: Layer.Layer<ROut, LayerError, Services | WorkerEnvironment>,
+  env: WorkerEnv,
+  services: Layer.Layer<Services>,
+): ManagedRuntime.ManagedRuntime<ROut | Services | WorkerEnvironment, LayerError> => {
+  const entrypointServices = Layer.mergeAll(
+    services,
+    ConfigProvider.layer(WorkerConfig.providerFromEnv(env)),
+    Layer.succeed(WorkerEnvironment, env),
+  );
+
+  return ManagedRuntime.make(provideEntrypointServices(layer, entrypointServices));
+};
+
+/**
+ * Runs a Cloudflare event effect on an entrypoint runtime.
+ *
+ * When an event layer is given it is built inside the event's Effect scope
+ * (finalized when the event effect completes). The casts widen away the
+ * `REvent` requirement satisfied by the event layer; TypeScript cannot reduce
+ * `Exclude<...>` over the generic union.
+ */
+export const runEventPromise = <A, E, R, REvent, EventLayerError, LayerError>(
+  runtime: ManagedRuntime.ManagedRuntime<R, LayerError>,
+  effect: Effect.Effect<A, E, R | REvent | Scope.Scope>,
+  eventLayer: Layer.Layer<REvent, EventLayerError, R> | undefined,
+): Promise<A> => {
+  const withEventLayer =
+    eventLayer === undefined
+      ? (effect as Effect.Effect<A, E, R | Scope.Scope>)
+      : (effect.pipe(Effect.provide(eventLayer, { local: true })) as Effect.Effect<
+          A,
+          E | EventLayerError,
+          R | Scope.Scope
+        >);
+
+  return runtime.runPromise(Effect.scoped(withEventLayer));
+};

package/src/internal/WorkerContext.ts

@@ -6,30 +6,41 @@ export type RunWaitUntilEffect = <A, E>(
   effect: Effect.Effect<A, E, never>,
 ) => Promise<Exit.Exit<A, unknown>>;
 
-const causeError = <E>(cause: Cause.Cause<E>) => new Error(Cause.pretty(cause));
+const causeError = <E>(cause: Cause.Cause<E>) => {
+  const squashed = Cause.squash(cause);
+
+  return squashed instanceof Error ? squashed : new Error(Cause.pretty(cause), { cause: squashed });
+};
 
 const failureHandler = <E, R>(
+  label: string,
   cause: Cause.Cause<E>,
   options: WorkerContextWaitUntilOptions<E, R> | undefined,
 ) =>
-  (
-    options?.onFailure?.(cause) ??
-    Effect.logError("WorkerContext.waitUntil failed", Cause.pretty(cause))
-  ).pipe(
+  (options?.onFailure?.(cause) ?? Effect.logError(`${label} failed`, Cause.pretty(cause))).pipe(
     Effect.catchCause((handlerCause) =>
       Effect.logError(
-        "WorkerContext.waitUntil failure handler failed",
+        `${label} failure handler failed`,
         Cause.pretty(cause),
         Cause.pretty(handlerCause),
       ),
     ),
   );
 
-export const fromExecutionContext = (
-  ctx: globalThis.ExecutionContext,
-  runPromiseExit: RunWaitUntilEffect,
-): WorkerContextService => {
-  const schedule = <A, E, R, R2 = never>(
+/**
+ * Builds a `waitUntil` scheduler for any Cloudflare lifecycle that accepts
+ * background promises (`ExecutionContext`, `DurableObjectState`).
+ *
+ * Background effects capture the calling fiber's context via `Effect.context`
+ * before being registered, so the default module-level `Effect.runPromiseExit`
+ * runner is sufficient; entrypoints may still pass a runtime-bound runner.
+ */
+export const makeWaitUntilScheduler = (
+  label: string,
+  register: (promise: Promise<unknown>) => void,
+  runPromiseExit: RunWaitUntilEffect = (effect) => Effect.runPromiseExit(effect),
+) => {
+  return <A, E, R, R2 = never>(
     effect: Effect.Effect<A, E, R>,
     options: WorkerContextWaitUntilOptions<E, R2> | undefined,
     mode: "observe" | "propagate",
@@ -39,17 +50,14 @@ export const fromExecutionContext = (
         Effect.sync(() => {
           const runHandler = (cause: Cause.Cause<E>) =>
             runPromiseExit(
-              Effect.scoped(Effect.provideContext(failureHandler(cause, options), context)),
+              Effect.scoped(Effect.provideContext(failureHandler(label, cause, options), context)),
             ).then((exit) => {
               if (Exit.isFailure(exit)) {
-                console.error(
-                  "WorkerContext.waitUntil failure handler failed",
-                  Cause.pretty(exit.cause),
-                );
+                console.error(`${label} failure handler failed`, Cause.pretty(exit.cause));
               }
             });
 
-          ctx.waitUntil(
+          register(
             runPromiseExit(Effect.scoped(Effect.provideContext(effect, context))).then(
               async (exit) => {
                 if (Exit.isSuccess(exit)) {
@@ -67,6 +75,20 @@ export const fromExecutionContext = (
         }),
       ),
     );
+};
+
+/**
+ * Builds the `WorkerContext` service from a native `ExecutionContext`.
+ */
+export const fromExecutionContext = (
+  ctx: globalThis.ExecutionContext,
+  runPromiseExit: RunWaitUntilEffect = (effect) => Effect.runPromiseExit(effect),
+): WorkerContextService => {
+  const schedule = makeWaitUntilScheduler(
+    "WorkerContext.waitUntil",
+    (promise) => ctx.waitUntil(promise),
+    runPromiseExit,
+  );
 
   return {
     raw: ctx,