effect-cf 0.27.0 → 0.28.1

package/src/WorkersAi.ts

@@ -1,4 +1,4 @@
-import { Context, Data, Effect, type Layer } from "effect";
+import { Context, Data, Effect, Option, Predicate, Schema as S, type Layer } from "effect";
 import type {
   Ai as CloudflareAi,
   AiAsyncBatchResponse,
@@ -44,11 +44,13 @@ export type WorkersAiAsyncBatchResponse = AiAsyncBatchResponse;
 export type WorkersAiEmbeddingInput =
   | AiTextEmbeddingsInput
   | Ai_Cf_Qwen_Qwen3_Embedding_0_6B_Input
-  | Record<string, unknown>;
+  | Parameters<WorkersAiBinding["run"]>[1];
+
+const embeddingDimensionsKey = "shape";
 
 export interface WorkersAiEmbeddingResponse {
   readonly data: ReadonlyArray<ReadonlyArray<number>>;
-  readonly shape: ReadonlyArray<number>;
+  readonly [embeddingDimensionsKey]: ReadonlyArray<number>;
 }
 
 export interface WorkersAiClient<ModelList extends AiModelListType = AiModels> {
@@ -89,7 +91,10 @@ export interface WorkersAiClient<ModelList extends AiModelListType = AiModels> {
       input: ModelList[Name]["inputs"],
       options?: WorkersAiOptions,
     ): Effect.Effect<ModelList[Name]["postProcessedOutputs"], WorkersAiOperationError>;
-    <Input extends Record<string, unknown>, Output = Record<string, unknown>>(
+    <
+      Input extends Parameters<WorkersAiBinding["run"]>[1],
+      Output = Awaited<ReturnType<WorkersAiBinding["run"]>>,
+    >(
       model: string,
       input: Input,
       options?: WorkersAiOptions,
@@ -161,33 +166,47 @@ const tryWorkersAiSync = <A>(
     catch: (cause) => workersAiError(binding, operation, cause),
   });
 
-const hasFunction = (value: object, key: string): boolean =>
-  typeof Reflect.get(value, key) === "function";
+type WorkersAiBindingValue = S.Schema.Type<typeof S.Unknown>;
+
+const WorkersAiBindingSchema = S.declare(
+  (value: WorkersAiBindingValue): value is WorkersAiBinding =>
+    Predicate.hasProperty(value, "run") &&
+    Predicate.isFunction(value.run) &&
+    Predicate.hasProperty(value, "gateway") &&
+    Predicate.isFunction(value.gateway) &&
+    Predicate.hasProperty(value, "models") &&
+    Predicate.isFunction(value.models),
+);
+const decodeWorkersAiBinding = S.decodeUnknownOption(WorkersAiBindingSchema);
 
-export const isWorkersAiBinding = (value: unknown): value is WorkersAiBinding =>
-  typeof value === "object" &&
-  value !== null &&
-  hasFunction(value, "run") &&
-  hasFunction(value, "gateway") &&
-  hasFunction(value, "models");
+export const isWorkersAiBinding = (value: WorkersAiBindingValue): value is WorkersAiBinding =>
+  Option.isSome(decodeWorkersAiBinding(value));
 
 export const embeddingResponse = (value: {
   readonly data?: ReadonlyArray<ReadonlyArray<number>>;
-  readonly shape?: ReadonlyArray<number>;
+  readonly [embeddingDimensionsKey]?: ReadonlyArray<number>;
 }): WorkersAiEmbeddingResponse => ({
   data: value.data ?? [],
-  shape: value.shape ?? [],
+  [embeddingDimensionsKey]: value[embeddingDimensionsKey] ?? [],
 });
 
+const decodeEmbeddingResponse = S.decodeUnknownOption(
+  S.Struct({
+    data: S.optional(S.Array(S.Array(S.Number))),
+    [embeddingDimensionsKey]: S.optional(S.Array(S.Number)),
+  }),
+);
+
 export const makeClient =
   <ModelList extends AiModelListType = AiModels>(definition: WorkersAiDefinition) =>
   (ai: WorkersAiBinding<ModelList>): WorkersAiClient<ModelList> => {
     const run = Effect.fn("WorkersAi.run")(
-      (model: string, input: Record<string, unknown>, options?: WorkersAiOptions) =>
-        tryWorkersAiPromise(definition.binding, "run", () =>
-          ai.run(model as string & {}, input, options),
-        ),
-    ) as WorkersAiClient<ModelList>["run"];
+      (model: string, input: Parameters<WorkersAiBinding["run"]>[1], options?: WorkersAiOptions) =>
+        tryWorkersAiPromise(definition.binding, "run", () => {
+          // SAFETY: a non-literal string intentionally selects Cloudflare's unknown-model fallback overload.
+          return ai.run(model as string & {}, input, options);
+        }),
+    );
 
     return {
       definition,
@@ -198,17 +217,19 @@ export const makeClient =
       ),
       run,
       runEmbedding: Effect.fn("WorkersAi.runEmbedding")(
-        (model: string, input: WorkersAiEmbeddingInput, options?: WorkersAiOptions) =>
-          run(model, input as Record<string, unknown>, options).pipe(
+        (model: string, input: WorkersAiEmbeddingInput, options?: WorkersAiOptions) => {
+          // SAFETY: every WorkersAiEmbeddingInput variant is a string-keyed Workers AI payload.
+          const modelInput = input as Parameters<WorkersAiBinding["run"]>[1];
+
+          return run(model, modelInput, options).pipe(
             Effect.map((response) =>
-              embeddingResponse(
-                response as {
-                  readonly data?: ReadonlyArray<ReadonlyArray<number>>;
-                  readonly shape?: ReadonlyArray<number>;
-                },
-              ),
+              Option.match(decodeEmbeddingResponse(response), {
+                onNone: () => embeddingResponse({}),
+                onSome: embeddingResponse,
+              }),
             ),
-          ),
+          );
+        },
       ),
       models: Effect.fn("WorkersAi.models")((params?: WorkersAiModelsSearchParams) =>
         tryWorkersAiPromise(definition.binding, "models", () => ai.models(params)),
@@ -242,6 +263,7 @@ export const Tag =
 
     const makeLayer = (definition: LayerOptions) => layer(tag, definition);
 
+    // SAFETY: Object.assign attaches exactly the static id/layer members declared by TagClass.
     return Object.assign(tag, {
       id,
       layer: makeLayer,

package/src/Workflow.ts

@@ -12,7 +12,17 @@ import {
   type WorkflowStepEvent,
   type WorkflowTimeoutDuration,
 } from "cloudflare:workers";
-import { Context, Data, Effect, Layer, type ManagedRuntime, type Scope } from "effect";
+import { NonRetryableError as CloudflareNonRetryableError } from "cloudflare:workflows";
+import {
+  Cause,
+  Context,
+  Data,
+  Effect,
+  Layer,
+  type ManagedRuntime,
+  Option,
+  type Scope,
+} from "effect";
 
 import { WorkerEnvironment, type WorkerEnv } from "./Environment";
 import { ExecutionContext, WorkerContext } from "./Worker";
@@ -49,6 +59,22 @@ export class WorkflowStepError extends Data.TaggedError("WorkflowStepError")<{
   }
 }
 
+/**
+ * Typed step failure that Cloudflare must treat as terminal instead of retrying.
+ *
+ * The workflow boundary converts this value into Cloudflare's native
+ * `NonRetryableError` while preserving the original cause and its message.
+ */
+export class WorkflowStepNonRetryableError extends Data.TaggedError(
+  "WorkflowStepNonRetryableError",
+)<{
+  readonly cause: unknown;
+}> {
+  override get message(): string {
+    return `Workflow step failed without retry: ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
+
 export interface WorkflowStepService {
   readonly raw: CloudflareWorkflowStep;
   do<A, E, R>(
@@ -85,6 +111,7 @@ export class WorkflowStepContext extends Context.Service<
 const fromWorkflowEvent = <Payload>(
   event: CloudflareWorkflowEvent<Payload>,
 ): WorkflowEventService<Payload> => ({
+  // SAFETY: raw intentionally erases only the payload type while retaining the same event object.
   raw: event as CloudflareWorkflowEvent<unknown>,
   payload: event.payload,
   timestamp: event.timestamp,
@@ -92,6 +119,27 @@ const fromWorkflowEvent = <Payload>(
   workflowName: event.workflowName,
 });
 
+const toCloudflareNonRetryableError = (
+  error: WorkflowStepNonRetryableError,
+): CloudflareNonRetryableError => {
+  const cloudflareError = new CloudflareNonRetryableError(error.message);
+
+  cloudflareError.cause = error.cause;
+
+  return cloudflareError;
+};
+
+const exposeCloudflareNonRetryableError = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> =>
+  Effect.catchCause(effect, (cause) => {
+    const error = Cause.findErrorOption(cause);
+
+    return Option.isSome(error) && error.value instanceof WorkflowStepNonRetryableError
+      ? Effect.die(toCloudflareNonRetryableError(error.value))
+      : Effect.failCause(cause);
+  });
+
 const fromWorkflowStep = (
   step: CloudflareWorkflowStep,
   runPromise: RunWorkflowStepEffect,
@@ -104,17 +152,21 @@ const fromWorkflowStep = (
           try: () => {
             const run = (stepContext: CloudflareWorkflowStepContext) =>
               runPromise(
-                Effect.scoped(
-                  Effect.provideService(
-                    Effect.provideContext(
-                      effect as Effect.Effect<A, E, Exclude<R, WorkflowStepContext>>,
-                      context,
+                exposeCloudflareNonRetryableError(
+                  Effect.scoped(
+                    Effect.provideService(
+                      Effect.provideContext(
+                        // SAFETY: WorkflowStepContext is provided immediately below; context supplies every other R service.
+                        effect as Effect.Effect<A, E, Exclude<R, WorkflowStepContext>>,
+                        context,
+                      ),
+                      WorkflowStepContext,
+                      stepContext,
                     ),
-                    WorkflowStepContext,
-                    stepContext,
                   ),
                 ),
               );
+            // SAFETY: these overloads reproduce the Cloudflare WorkflowStep.do runtime signatures used here.
             const rawStep = step as {
               do(
                 name: string,
@@ -132,7 +184,7 @@ const fromWorkflowStep = (
           catch: (cause) => new WorkflowStepError({ step: name, operation: "do", cause }),
         }),
       ),
-    ) as Effect.Effect<A, WorkflowStepError, Exclude<R, WorkflowStepContext>>,
+    ),
   sleep: (name, duration) =>
     Effect.tryPromise({
       try: () => step.sleep(name, duration),
@@ -151,7 +203,10 @@ const fromWorkflowStep = (
     },
   ) =>
     Effect.tryPromise({
-      try: () => step.waitForEvent(name, options) as Promise<WorkflowStepEvent<Payload>>,
+      try: () => {
+        // SAFETY: Cloudflare returns an event whose payload is determined by the caller's event contract.
+        return step.waitForEvent(name, options) as Promise<WorkflowStepEvent<Payload>>;
+      },
       catch: (cause) => new WorkflowStepError({ step: name, operation: "waitForEvent", cause }),
     }),
 });
@@ -230,9 +285,7 @@ export const step = <A, E, R>(
   effect: Effect.Effect<A, E, R>,
   config?: WorkflowStepConfig,
 ): Effect.Effect<A, WorkflowStepError, WorkflowStep | Exclude<R, WorkflowStepContext>> =>
-  Effect.flatMap(WorkflowStep, (workflowStep) =>
-    workflowStep.do(name, effect, config),
-  ) as Effect.Effect<A, WorkflowStepError, WorkflowStep | Exclude<R, WorkflowStepContext>>;
+  Effect.flatMap(WorkflowStep, (workflowStep) => workflowStep.do(name, effect, config));
 
 export const sleep = (
   name: string,

package/src/WorkflowBinding.ts

@@ -3,8 +3,9 @@ import type {
   Workflow as CloudflareWorkflow,
   WorkflowInstance as CloudflareWorkflowInstance,
   WorkflowInstanceCreateOptions as CloudflareWorkflowInstanceCreateOptions,
+  WorkflowInstanceRestartOptions as CloudflareWorkflowInstanceRestartOptions,
 } from "@cloudflare/workers-types";
-import { type Context, Data, Effect, Option, Schema as S } from "effect";
+import { type Context, Data, Effect, Option, Predicate, Schema as S } from "effect";
 
 import * as Binding from "./Binding";
 import type * as RpcDefinition from "./RpcDefinition";
@@ -21,13 +22,7 @@ export type WorkflowInstanceCreateBatchOptions<Payload, EncodedPayload = unknown
   { readonly payload: Payload } & WorkflowInstanceCreateOptions<EncodedPayload>
 >;
 
-export interface WorkflowInstanceRestartOptions {
-  readonly from?: {
-    readonly name?: string;
-    readonly count?: number;
-    readonly type?: string;
-  };
-}
+export type WorkflowInstanceRestartOptions = CloudflareWorkflowInstanceRestartOptions;
 
 export type WorkflowInstanceStatusName = CloudflareInstanceStatus["status"];
 
@@ -129,19 +124,22 @@ const tryWorkflowPromise = <A>(
     catch: (cause) => workflowError(binding, operation, cause),
   });
 
-export const isWorkflow = <Payload>(value: unknown): value is CloudflareWorkflow<Payload> => {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
+type WorkflowBindingValue = S.Schema.Type<typeof S.Unknown>;
 
-  const resource = value as Record<string, unknown>;
+const WorkflowBindingSchema = S.declare(
+  (value: WorkflowBindingValue): value is CloudflareWorkflow<WorkflowBindingValue> =>
+    Predicate.hasProperty(value, "create") &&
+    Predicate.isFunction(value.create) &&
+    Predicate.hasProperty(value, "createBatch") &&
+    Predicate.isFunction(value.createBatch) &&
+    Predicate.hasProperty(value, "get") &&
+    Predicate.isFunction(value.get),
+);
+const decodeWorkflowBinding = S.decodeUnknownOption(WorkflowBindingSchema);
 
-  return (
-    typeof resource.create === "function" &&
-    typeof resource.createBatch === "function" &&
-    typeof resource.get === "function"
-  );
-};
+export const isWorkflow = <Payload>(
+  value: WorkflowBindingValue,
+): value is CloudflareWorkflow<Payload> => Option.isSome(decodeWorkflowBinding(value));
 
 export const makeClient = <
   Payload extends RpcDefinition.ServiceFreeSchema,
@@ -168,12 +166,7 @@ export const makeClient = <
       pause: operation("pause", () => raw.pause()),
       resume: operation("resume", () => raw.resume()),
       terminate: operation("terminate", () => raw.terminate()),
-      restart: (options) =>
-        operation("restart", () =>
-          (raw as { restart(options?: WorkflowInstanceRestartOptions): Promise<void> }).restart(
-            options,
-          ),
-        ),
+      restart: (options) => operation("restart", () => raw.restart(options)),
       status: operation("status", () => raw.status()).pipe(
         Effect.flatMap((status) =>
           Effect.gen(function* () {

package/src/WorkflowDefinition.ts

@@ -187,6 +187,7 @@ export const Tag =
 
     const rawUnsafe = Effect.flatMap(tag, (workflow) => workflow.rawUnsafe);
 
+    // SAFETY: Object.assign attaches the definition-derived static helpers declared by TagClass.
     return Object.assign(tag, {
       id: workflowDefinition.id,
       payload: workflowDefinition.payload,
@@ -216,15 +217,16 @@ const wrapHandler = <ROut, const Self extends Definition.Any>(
   return Effect.fnUntraced(function* (payload: S.Codec.Encoded<Self["payload"]>) {
     const decodedPayload = yield* decodePayload(payload);
     const event = yield* WorkflowEntrypoint.WorkflowEvent;
+    // SAFETY: replacing the encoded event payload with its schema-decoded value establishes this service type.
     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(
+    const result = yield* handler(decodedPayload).pipe(
       Effect.provideService(WorkflowEntrypoint.WorkflowEvent, decodedEvent),
     );
 
-    return yield* encodeResult(result as S.Schema.Type<Self["result"]>);
+    return yield* encodeResult(result);
   });
 };
 

package/src/internal/Entrypoint.ts

@@ -1,4 +1,4 @@
-import { Effect, Layer } from "effect";
+import { Effect, Layer, Schema } from "effect";
 
 import * as RpcDefinition from "../RpcDefinition";
 
@@ -7,18 +7,36 @@ type EntrypointRpcMethod = (...args: AnyArgs) => Effect.Effect<any, any, any>;
 
 export type EntrypointRpc = Record<string, EntrypointRpcMethod>;
 
+const invokeEntrypointRpcMethod = <Self>(
+  self: Self,
+  method: EntrypointRpcMethod,
+  args: AnyArgs,
+  run: (self: Self, effect: Effect.Effect<any, any, any>) => Promise<any>,
+  onExit: ((self: Self) => Effect.Effect<void, never, any>) | undefined,
+): Promise<any> => {
+  const handler = Effect.suspend(() => method(...args)).pipe(
+    Effect.mapError(RpcDefinition.encodeWireError),
+  );
+
+  return run(
+    self,
+    onExit === undefined ? handler : handler.pipe(Effect.onExit(() => onExit(self))),
+  );
+};
+
 export const provideEntrypointServices = <ROut, LayerError, RIn>(
   layer: Layer.Layer<ROut, LayerError, RIn>,
   services: Layer.Layer<RIn, never, never>,
 ): Layer.Layer<ROut | RIn, LayerError, never> =>
+  // SAFETY: provideMerge supplies RIn while retaining it in the output context for entrypoint consumers.
   layer.pipe(Layer.provideMerge(services)) as Layer.Layer<ROut | RIn, LayerError, never>;
 
-export const defineEntrypointRpcMethods = <Self>(
+export const defineEntrypointRpcMethods = <Self, Prototype extends object = object>(
   target: string,
-  prototype: object,
+  prototype: Prototype,
   rpc: EntrypointRpc | undefined,
   reservedMethodNames: ReadonlySet<string>,
-  run: (self: Self, effect: Effect.Effect<any, any, any>) => Promise<unknown>,
+  run: (self: Self, effect: Effect.Effect<any, any, any>) => Promise<any>,
   onExit?: (self: Self) => Effect.Effect<void, never, any>,
 ): void => {
   const methods = rpc ?? {};
@@ -29,17 +47,15 @@ export const defineEntrypointRpcMethods = <Self>(
     Object.defineProperty(prototype, key, {
       enumerable: true,
       value(this: Self, ...args: AnyArgs) {
-        const handler = Effect.suspend(() => method(...args)).pipe(
-          Effect.mapError(RpcDefinition.encodeWireError),
-        );
-
-        return run(
-          this,
-          onExit === undefined ? handler : handler.pipe(Effect.onExit(() => onExit(this))),
-        );
+        return invokeEntrypointRpcMethod(this, method, args, run, onExit);
       },
     });
   }
 };
 
-export const assumeEntrypointClass = <Class>(entrypoint: unknown): Class => entrypoint as Class;
+type EntrypointClassValue = Schema.Schema.Type<typeof Schema.Unknown>;
+
+export const assumeEntrypointClass = <Class>(entrypoint: EntrypointClassValue): Class => {
+  // SAFETY: callers pass a freshly declared Cloudflare entrypoint subclass matching Class's constructor contract.
+  return entrypoint as Class;
+};

package/src/internal/ErrorMessage.ts

@@ -3,12 +3,12 @@
  * 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;
-    }
+  if (
+    Predicate.hasProperty(cause, "message") &&
+    Predicate.isString(cause.message) &&
+    cause.message.length > 0
+  ) {
+    return cause.message;
   }
 
   try {
@@ -22,3 +22,4 @@ export const causeMessage = (cause: unknown): string => {
 export const violationsMessage = (
   violations: ReadonlyArray<{ readonly path: string; readonly message: string }>,
 ): string => violations.map((violation) => `${violation.path}: ${violation.message}`).join("; ");
+import { Predicate } from "effect";

package/src/internal/RpcInvocation.ts

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Effect, Predicate, Schema } from "effect";
 
 import type * as CloudflareRpc from "../Rpc";
 
@@ -6,7 +6,7 @@ type AnyArgs = Array<any>;
 
 export type AsyncMethodKey<Api> = {
   [Key in keyof Api]-?: Key extends string
-    ? Api[Key] extends (...args: AnyArgs) => Promise<unknown>
+    ? Api[Key] extends (...args: AnyArgs) => Promise<any>
       ? Key
       : never
     : never;
@@ -14,7 +14,7 @@ export type AsyncMethodKey<Api> = {
 
 export type AsyncMethodArgs<Api, Method extends keyof Api> = Api[Method] extends (
   ...args: infer Args
-) => Promise<unknown>
+) => Promise<any>
   ? Args
   : never;
 
@@ -28,11 +28,24 @@ export type AsyncMethodCloudflareReturn<Api, Method extends keyof Api> = Cloudfl
   AsyncMethodSuccess<Api, Method>
 >;
 
-const isPropertyTarget = (value: unknown): value is object =>
-  (typeof value === "object" || typeof value === "function") && value !== null;
+type RpcTargetValue = Schema.Schema.Type<typeof Schema.Unknown>;
+type RpcMethodOwner<Method extends PropertyKey> = {
+  readonly [Key in Method]?: RpcTargetValue;
+};
+
+const invokeWithReceiver = <Method extends PropertyKey, Args extends AnyArgs, Return>(
+  value: (...args: Args) => Return,
+  receiver: RpcMethodOwner<Method>,
+  args: Args,
+): Return => {
+  const result: RpcTargetValue = Function.prototype.apply.call(value, receiver, args);
+
+  // SAFETY: the native apply intrinsic returns value's declared Return while avoiding proxy property reads.
+  return result as Return;
+};
 
 export const lookupRpcMethod = <Api, Method extends AsyncMethodKey<Api>, Error>(
-  target: unknown,
+  target: RpcTargetValue,
   method: Method,
   makeError: (cause: unknown) => Error,
 ): Effect.Effect<
@@ -41,19 +54,29 @@ export const lookupRpcMethod = <Api, Method extends AsyncMethodKey<Api>, Error>(
 > =>
   Effect.try({
     try: () => {
-      if (!isPropertyTarget(target)) {
+      if (!Predicate.isObjectKeyword(target)) {
         throw new TypeError(`RPC target is not object-like`);
       }
 
-      const value = Reflect.get(target, method);
+      // SAFETY: this assertion enables one proxy property read; the result is validated before invocation.
+      const receiver = target as RpcMethodOwner<Method>;
+      const value = receiver[method];
 
-      if (typeof value !== "function") {
+      if (!Predicate.isFunction(value)) {
         throw new TypeError(`RPC method "${String(method)}" is not callable`);
       }
 
-      return ((...args: AsyncMethodArgs<Api, Method>) => Reflect.apply(value, target, args)) as (
+      // SAFETY: the runtime check proves callability; Api and Method supply this binding's call contract.
+      const callable = value as (
         ...args: AsyncMethodArgs<Api, Method>
       ) => AsyncMethodCloudflareReturn<Api, Method>;
+
+      return (...args: AsyncMethodArgs<Api, Method>): AsyncMethodCloudflareReturn<Api, Method> =>
+        invokeWithReceiver<
+          Method,
+          AsyncMethodArgs<Api, Method>,
+          AsyncMethodCloudflareReturn<Api, Method>
+        >(callable, receiver, args);
     },
     catch: makeError,
   });
@@ -63,7 +86,7 @@ export const invokeRpcMethod = Effect.fnUntraced(function* <
   Method extends AsyncMethodKey<Api>,
   Error,
 >(
-  target: unknown,
+  target: RpcTargetValue,
   method: Method,
   args: AsyncMethodArgs<Api, Method>,
   makeError: (cause: unknown) => Error,

package/src/internal/Runtime.ts

@@ -26,27 +26,38 @@ export const makeEntrypointRuntime = <ROut, LayerError, Services>(
   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>(
+/** Runs an event effect whose requirements are already available in the runtime. */
+export function runEventPromise<A, E, R, LayerError>(
+  runtime: ManagedRuntime.ManagedRuntime<R, LayerError>,
+  effect: Effect.Effect<A, E, NoInfer<R> | Scope.Scope>,
+  eventLayer?: undefined,
+): Promise<A>;
+/** Builds and provides an event layer inside the event effect's scope. */
+export function 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
-        >);
+  effect: Effect.Effect<A, E, NoInfer<R> | REvent | Scope.Scope>,
+  eventLayer: Layer.Layer<REvent, EventLayerError, NoInfer<R>>,
+): Promise<A>;
+export function runEventPromise<A, E, R, REvent, EventLayerError, LayerError>(
+  ...args:
+    | readonly [
+        runtime: ManagedRuntime.ManagedRuntime<R, LayerError>,
+        effect: Effect.Effect<A, E, R | Scope.Scope>,
+        eventLayer?: undefined,
+      ]
+    | readonly [
+        runtime: ManagedRuntime.ManagedRuntime<R, LayerError>,
+        effect: Effect.Effect<A, E, R | REvent | Scope.Scope>,
+        eventLayer: Layer.Layer<REvent, EventLayerError, R>,
+      ]
+): Promise<A> {
+  const [runtime, effect, eventLayer] = args;
 
-  return runtime.runPromise(Effect.scoped(withEventLayer));
-};
+  if (eventLayer === undefined) {
+    return runtime.runPromise(Effect.scoped(effect));
+  }
+
+  return runtime.runPromise(
+    Effect.scoped(effect.pipe(Effect.provide(eventLayer, { local: true }))),
+  );
+}

package/src/internal/Telemetry.ts

@@ -1,14 +1,15 @@
 import { Effect, Option } from "effect";
 import { OtlpExporter } from "effect/unstable/observability";
 
-const logFlushFailure = Effect.logError("Telemetry flush failed").pipe(Effect.ignoreCause);
-
-const logFlushSchedulingFailure = Effect.logError("Telemetry flush scheduling failed").pipe(
-  Effect.ignoreCause,
-);
+/** Maximum event lifetime spent on an internally scheduled telemetry flush. */
+const scheduledFlushTimeout = "2 seconds";
 
 /**
  * Schedules a configured OTLP flusher through the current Cloudflare event.
+ *
+ * The handed-off effect is best-effort: it settles within two seconds and
+ * silently absorbs every failure cause so telemetry cannot extend or fail the
+ * user event, or recursively log through an unhealthy exporter.
  */
 export const scheduleTelemetryFlush = <R>(
   waitUntil: (flush: Effect.Effect<void>) => Effect.Effect<void, never, R>,
@@ -20,8 +21,14 @@ export const scheduleTelemetryFlush = <R>(
       return;
     }
 
-    // Exporters and platform schedulers are foreign boundaries. Preserve a
-    // useful diagnostic without retaining their arbitrary failure causes in
-    // logs, where payloads, headers, or credentials could otherwise escape.
-    yield* waitUntil(flusher.value.flush.pipe(Effect.catchCause(() => logFlushFailure)));
-  }).pipe(Effect.catchCause(() => logFlushSchedulingFailure));
+    // Exporters and platform schedulers are foreign boundaries. Do not log
+    // their arbitrary failure causes: the configured logger may be the same
+    // unhealthy OTLP exporter and recursively increase its backlog.
+    yield* waitUntil(
+      flusher.value.flush.pipe(
+        Effect.timeoutOption(scheduledFlushTimeout),
+        Effect.ignoreCause,
+        Effect.asVoid,
+      ),
+    );
+  }).pipe(Effect.ignoreCause);