sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workflows/ Workflow.ts

import type * as runtime from "@cloudflare/workers-types";
import * as workflows from "@distilled.cloud/cloudflare/workflows";
import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
import { havePropsChanged, isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import type * as Output from "alchemy/Output";
import { ALCHEMY_PHASE } from "alchemy/Phase";
import type { PlatformServices } from "alchemy/Platform";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import { effectClass, taggedFunction } from "alchemy/Util/effect";
import type { ConfigError } from "effect/Config";
import * as Context from "effect/Context";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { Scope } from "effect/Scope";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import { localAccountId } from "../LocalAccount.ts";
import { generateLocalId } from "../LocalRuntime.ts";
import { Worker, WorkerEnvironment, type WorkerServices } from "../Workers/Worker.ts";
import { generateWorkflowName } from "./WorkflowName.ts";
import { type WorkflowEvent, WorkflowStep, WorkflowStepContext } from "./WorkflowRuntime.ts";

export class WorkflowInvalidProps extends Data.TaggedError("WorkflowInvalidProps")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export { WorkflowEvent, WorkflowStep, WorkflowStepContext } from "./WorkflowRuntime.ts";

type TypeId = "Cloudflare.Workflow";
const TypeId = "Cloudflare.Workflow" as const;

/**
 * Cron trigger metadata on a Workflow instance created by a native
 * `schedules` expression. Mirrors Cloudflare's `event.schedule`.
 */
export interface WorkflowCronSchedule {
  /**
   * The matching cron expression that created this instance.
   */
  cron: string;
  /**
   * The scheduled fire time, milliseconds since the Unix epoch.
   */
  scheduledTime: number;
}

export type WorkflowBackoff = "constant" | "linear" | "exponential";

export interface WorkflowStepConfig {
  retries?: {
    limit: number;
    delay: string | number;
    backoff?: WorkflowBackoff;
  };
  timeout?: string | number;
}

export interface WorkflowStepContextData {
  step: {
    name: string;
    count: number;
  };
  attempt: number;
  config: WorkflowStepConfig;
}

export interface WorkflowRollbackContext<Output = unknown> {
  error: Error;
  output: Output | undefined;
}

export interface WorkflowRollbackOptions<Output = unknown, R = never> {
  rollback: (context: WorkflowRollbackContext<Output>) => Effect.Effect<void, unknown, R>;
  rollbackConfig?: WorkflowStepConfig;
}

/**
 * Optional configuration for a `task` step: retry policy, timeout, and a
 * rollback handler with its own retry config.
 */
export interface WorkflowTaskConfig<
  Output = unknown,
  RollbackReq = never,
> extends WorkflowStepConfig {
  rollback?: (
    context: WorkflowRollbackContext<Output>,
  ) => Effect.Effect<void, unknown, RollbackReq>;
  rollbackConfig?: WorkflowStepConfig;
}

/**
 * Internal step descriptor passed from `task` to the bridge. Bundles the step
 * name and Effect together with the `WorkflowTaskConfig` fields.
 */
export interface WorkflowTaskOptions<
  Output = unknown,
  R = never,
  RollbackReq = never,
  E = never,
> extends WorkflowTaskConfig<Output, RollbackReq> {
  name: string;
  effect: Effect.Effect<Output, E, R>;
}

export interface WorkflowWaitForEventOptions {
  type: string;
  timeout?: string | number;
}

/**
 * The event delivered to a `waitForEvent` step. Mirrors the native
 * `WorkflowStepEvent` shape from `cloudflare:workers` 1:1.
 */
export interface WorkflowStepEvent<Payload = unknown> {
  payload: Payload;
  timestamp: Date;
  type: string;
}

type ExcludeWorkflowStepContext<R> = R extends {
  readonly key: "Cloudflare.WorkflowStepContext";
}
  ? never
  : R;

// ---------------------------------------------------------------------------
// User-facing step primitives
// ---------------------------------------------------------------------------

/**
 * Execute a named, durable workflow step. The effect is run inside the
 * Cloudflare step transaction so its result is automatically persisted
 * and replayed on retries.
 *
 * Any services the inner effect requires (e.g. `WorkerEnvironment` from a
 * binding like `kv.put` / `kv.get`) are threaded through automatically by
 * capturing the surrounding workflow body's context and providing it to
 * the inner effect before it runs inside `step.do`.
 *
 * The step name comes first, followed by the Effect. Retry config, timeout,
 * and a rollback handler can be passed in the optional third `options` arg.
 * Each attempt and rollback handler has a fresh Scope; its resources close
 * before that callback completes. Interrupting a task waits for the active
 * attempt's cleanup without waiting for Cloudflare's native retry delays.
 *
 * `Effect.fail` uses the native retry policy. On exhaustion, application failure
 * data is returned in the error channel, including on cached rejection replay.
 * The active invocation retains its original Cause; replay restores serialized
 * tags and fields, not custom prototypes, methods, or object identity.
 * Failure data supports primitives, dense arrays, records, errors, Date, bigint,
 * Uint8Array, ArrayBuffer, Map, and Set, within a 16 KiB encoded / 64-level limit.
 * Functions, symbols, cycles, shared object references, accessors, and unsupported
 * class instances fail explicitly as terminal serialization defects. Error data
 * must form a tree, including objects used as Map keys or Set members.
 * `Effect.die` and `Effect.orDie`
 * stop retries. Native timeout, validation, pause, and abort errors stay defects.
 */
export function task<T, R = never, RollbackReq = never, E = never>(
  name: string,
  effect: Effect.Effect<T, E, R>,
  options?: WorkflowTaskConfig<T, RollbackReq>,
): Effect.Effect<T, E, WorkflowStep | ExcludeWorkflowStepContext<Exclude<R | RollbackReq, Scope>>> {
  return Effect.gen(function* () {
    const step = yield* WorkflowStep;
    const context = (yield* Effect.context<
      ExcludeWorkflowStepContext<Exclude<R | RollbackReq, Scope>>
    >()).pipe(Context.omit(Scope, WorkflowStepContext));
    const rollbackEffect = options?.rollback;
    return yield* step.do({
      ...options,
      name,
      effect: effect.pipe(Effect.provide(context)),
      rollback: rollbackEffect
        ? (rollbackContext: WorkflowRollbackContext<T>) =>
            rollbackEffect(rollbackContext).pipe(Effect.provide(context))
        : undefined,
    } as WorkflowTaskOptions<T, any, any, E>);
  });
}

/**
 * Pause the workflow for the given duration.
 */
export const sleep = (
  name: string,
  duration: string | number,
): Effect.Effect<void, never, WorkflowStep> =>
  Effect.gen(function* () {
    const step = yield* WorkflowStep;
    yield* step.sleep(name, duration);
  }).pipe(Effect.orDie);

/**
 * Pause the workflow until the given timestamp.
 */
export const sleepUntil = (
  name: string,
  timestamp: Date | number,
): Effect.Effect<void, never, WorkflowStep> =>
  Effect.gen(function* () {
    const step = yield* WorkflowStep;
    yield* step.sleepUntil(name, timestamp);
  }).pipe(Effect.orDie);

/**
 * Pause the workflow until an external event is delivered with
 * `WorkflowInstance.sendEvent`. Resolves with the full
 * {@link WorkflowStepEvent} (`{ payload, timestamp, type }`), exactly like
 * the native `step.waitForEvent`.
 */
export const waitForEvent = <T = unknown>(
  name: string,
  options: WorkflowWaitForEventOptions,
): Effect.Effect<WorkflowStepEvent<T>, never, WorkflowStep> =>
  Effect.gen(function* () {
    const step = yield* WorkflowStep;
    return yield* step.waitForEvent<T>(name, options);
  }).pipe(Effect.orDie);

/**
 * The services available inside a workflow run body.
 *
 * `WorkerEnvironment` is provided to the body at runtime by the workflow
 * export wrapper (see `make(env)` below), so users can access env bindings
 * from inside workflow steps via `yield* WorkerEnvironment` — the type must
 * reflect that or `yield* WorkerEnvironment` fails to type-check inside a
 * body even though it succeeds at runtime.
 *
 * A fresh `Scope` is provided per run-invocation by `WorkflowBridge.run` and
 * threaded into every `task` via the surrounding body context, so `@binding`
 * helpers that acquire per-run resources against the ambient scope (e.g.
 * `Drizzle.Postgres`) resolve them inside workflow steps just as they do in
 * a Worker `fetch`/`queue` handler.
 */
export type WorkflowRunServices = WorkflowEvent | WorkflowStep | WorkerServices | Scope;

export type WorkflowServices = WorkflowRunServices | PlatformServices | RuntimeContext;

/**
 * Metadata stored in the worker export map to distinguish workflow exports
 * from durable object exports at bundle-generation time.
 */
export interface WorkflowExport {
  readonly kind: "workflow";
  readonly make: (env: unknown) => Effect.Effect<WorkflowImpl<any, any, unknown>>;
}

/**
 * A workflow implementation is a function from a typed `Input` payload to
 * an Effect that produces the workflow's `Result`. The Effect requires
 * `WorkflowRunServices` (event + step + env) to execute.
 */
export type WorkflowImpl<Input = unknown, Result = unknown, E = never> = (
  input: Input,
) => Effect.Effect<Result, E, WorkflowServices>;

export const isWorkflowExport = (value: unknown): value is WorkflowExport =>
  typeof value === "object" &&
  value !== null &&
  "kind" in value &&
  (value as any).kind === "workflow";

/**
 * Limits applied to the workflow on create or update.
 */
export interface WorkflowLimits {
  /**
   * Maximum number of steps a single workflow instance may execute.
   */
  steps?: number;
}

/**
 * Jurisdiction where a Workflow's instances run and store data:
 * `"eu"` (the European Union), `"us"` (the United States), or `"fedramp"`
 * (FedRAMP-Moderate data centers).
 */
export type WorkflowJurisdiction = workflows.WorkflowJurisdiction;

/**
 * Props for the reference (async) form of {@link Workflow}. Used when binding
 * a Workflow class to a plain async Worker (one without an Effect runtime) via
 * the Worker's `env`. Mirrors `DurableObjectProps`.
 */
export interface WorkflowRefProps {
  /**
   * Account-global Workflow name. Adopting an existing Workflow requires
   * `--adopt`; unused names do not. If omitted, Alchemy preserves the deployed
   * name or derives a stage-scoped default from the hosting Worker and class.
   * Changing this name replaces the Workflow. Fixed names must be unique to
   * each independently managed stack and stage.
   */
  workflowName?: string;
  /**
   * Name of the exported `WorkflowEntrypoint` class.
   *
   * @default name
   */
  className?: string;
  /**
   * Worker script that hosts the Workflow class. Omit this when the workflow
   * is hosted by the Worker that declares the binding.
   */
  scriptName?: Input<string>;
  /**
   * Limits applied to the workflow. Only applies when the workflow is hosted by
   * the Worker that declares the binding; ignored when `scriptName` is set.
   */
  limits?: WorkflowLimits;
  /**
   * Cron expressions that create a new Workflow instance on each match.
   * Wrangler-compatible: `schedules: ["0 * * * *"]`.
   *
   * Native Workflow schedules replace a Worker Cron Trigger whose
   * `scheduled` handler called `workflow.create()`. Pass an empty
   * array to remove all schedules.
   *
   * Only applies when the workflow is hosted by the Worker that declares
   * the binding; ignored when `scriptName` is set.
   *
   * Account-wide limit: 100 cron expressions.
   */
  schedules?: string[];
  /**
   * Restrict where the Workflow's instances run and store data, e.g. for
   * GDPR or FedRAMP. Workers anywhere can still create and manage instances.
   *
   * Cloudflare sets the jurisdiction when it creates the Workflow and can't
   * change it, so changing or removing it replaces the Workflow and deletes
   * its instances. Ignored when `scriptName` is set; set it on the Worker
   * that hosts the Workflow. Local development ignores it.
   */
  jurisdiction?: WorkflowJurisdiction;
}

/**
 * Props for the Effect-native form of {@link Workflow}
 * (`Workflow(name, props, impl)`). Used when the workflow's implementation is
 * defined inline by the hosting Worker.
 */
export interface WorkflowProps {
  /**
   * Account-global Workflow name. Adopting an existing Workflow requires
   * `--adopt`; unused names do not. If omitted, Alchemy preserves the deployed
   * name or derives a stage-scoped default from the hosting Worker and class.
   * Changing this name replaces the Workflow. Fixed names must be unique to
   * each independently managed stack and stage.
   */
  workflowName?: string;
  /**
   * Limits applied to the workflow.
   */
  limits?: WorkflowLimits;
  /**
   * Cron expressions that create a new Workflow instance on each match.
   * Wrangler-compatible: `schedules: ["0 * * * *"]`.
   *
   * Native Workflow schedules replace a Worker Cron Trigger whose
   * `scheduled` handler called `workflow.create()`. Pass an empty
   * array to remove all schedules.
   *
   * Account-wide limit: 100 cron expressions.
   */
  schedules?: string[];
  /**
   * Restrict where the Workflow's instances run and store data, e.g. for
   * GDPR or FedRAMP. Workers anywhere can still create and manage instances.
   *
   * Cloudflare sets the jurisdiction when it creates the Workflow and can't
   * change it, so changing or removing it replaces the Workflow and deletes
   * its instances. Local development ignores it.
   */
  jurisdiction?: WorkflowJurisdiction;
}

/**
 * A lightweight reference to a Workflow, produced by the props-only form of
 * {@link Workflow} (`Workflow(name, { className })`). Carries just enough
 * metadata to emit the `workflow` binding for an async Worker and to drive
 * the `putWorkflow` lifecycle. Mirrors `DurableObjectLike`.
 */
export interface WorkflowLike<Params = unknown> {
  kind: TypeId;
  name: string;
  /** Account-global Workflow name, when explicitly configured. */
  workflowName?: string;
  /** @internal phantom */
  className?: string;
  /** @internal phantom */
  scriptName?: Input<string>;
  /** @internal phantom */
  limits?: WorkflowLimits;
  /** @internal phantom */
  schedules?: string[];
  /** @internal phantom */
  jurisdiction?: WorkflowJurisdiction;
  /** @internal phantom */
  Params?: Params;
}

/**
 * A Workflow bound on an external/async Worker's `env`, exposed on
 * `worker.env.<name>` at declaration time, not on persisted Worker references
 * or Effect-native Workers. Carries the binding's identity as `Output`s
 * of the current deploy pass, so a sibling resource in the same stack — a
 * Queue subscription to the Workflow's lifecycle events, for instance — can
 * consume the Workflow's physical name on its very first deployment without
 * reading persisted state or re-deriving the name.
 *
 * For a locally-hosted Workflow, `workflowName` and `scriptName` resolve from
 * the {@link WorkflowResource} the binding registers, so a consumer deploys
 * after `putWorkflow` has run. A cross-script reference (`scriptName` set)
 * registers no resource; both outputs derive from the declared host script.
 */
export interface WorkflowBinding<Params = unknown> {
  kind: TypeId;
  /** Logical name of the Workflow, as passed to `Workflow(name, …)`. */
  name: string;
  /** Name of the exported `WorkflowEntrypoint` class. */
  className: string;
  /** Account-global physical Workflow name, resolved in the current deploy. */
  workflowName: Output.Output<string>;
  /** Script name of the Worker hosting the Workflow class. */
  scriptName: Output.Output<string>;
  /** @internal phantom */
  Params?: Params;
}

/**
 * Type guard for the reference (async) form of a Workflow.
 */
export const isWorkflowLike = (value: unknown): value is WorkflowLike =>
  typeof value === "object" && value !== null && (value as { kind?: unknown }).kind === TypeId;

/**
 * Type guard for workflow binding metadata in the Worker binding contract.
 */
export const isWorkflowBinding = (binding: {
  type: string;
}): binding is {
  type: "workflow";
  name: string;
  workflowName: string;
  className: string;
  scriptName?: string;
} => binding.type === "workflow";

export type WorkflowBatchDeleteResult = runtime.WorkflowBatchDeleteResult;
export type WorkflowSubscriptionEvent = runtime.WorkflowInstanceEvent;
export type WorkflowInstanceSubscribeOptions = runtime.WorkflowInstanceSubscribeOptions;

/**
 * Handle returned to the caller at deploy/bind time. Allows starting
 * workflow instances and checking their status from the Api layer.
 */
export interface WorkflowHandle<Input = unknown, Result = unknown> {
  Type: TypeId;
  name: string;
  /** Account-global physical Workflow name, for a resource that starts runs through the API. */
  workflowName: Output.Output<string> | string;
  /**
   * Start a workflow instance. Pass payload through `params`; omit `id` to let
   * Cloudflare generate an instance ID.
   */
  create(options?: WorkflowInstanceCreateOptions<Input>): Effect.Effect<WorkflowInstance<Result>>;
  createBatch(
    batch: WorkflowInstanceCreateOptions<Input>[],
  ): Effect.Effect<WorkflowInstance<Result>[]>;
  get(instanceId: string): Effect.Effect<WorkflowInstance<Result>>;
  /** Delete up to 100 instances and their stored state, returning per-instance results. */
  deleteBatch(instanceIds: string[]): Effect.Effect<WorkflowBatchDeleteResult>;
}

/** Options for starting a workflow instance. */
export interface WorkflowInstanceCreateOptions<Input = unknown> {
  id?: string;
  params?: Input;
  retention?: WorkflowInstanceRetention;
}

export interface WorkflowInstanceRetention {
  successRetention?: string | number;
  errorRetention?: string | number;
}

/** Handle for a single Cloudflare workflow instance. */
export interface WorkflowInstance<Result = unknown> {
  id: string;
  status(): Effect.Effect<WorkflowInstanceStatus<Result>>;
  pause(): Effect.Effect<void>;
  resume(): Effect.Effect<void>;
  restart(options?: WorkflowInstanceRestartOptions): Effect.Effect<void>;
  terminate(): Effect.Effect<void>;
  /** Stop execution and delete this instance and its stored state. */
  delete(): Effect.Effect<void>;
  /** Stream historical and new events; release the subscription when consumption ends. */
  subscribe(options?: WorkflowInstanceSubscribeOptions): Stream.Stream<WorkflowSubscriptionEvent>;
  sendEvent<Event = unknown>(event: WorkflowInstanceEvent<Event>): Effect.Effect<void>;
}

export interface WorkflowInstanceRestartOptions {
  from?: {
    name: string;
    count?: number;
    type?: "do" | "sleep" | "waitForEvent";
  };
}

export interface WorkflowInstanceEvent<Payload = unknown> {
  type: string;
  payload?: Payload;
}

export interface WorkflowInstanceStatus<Result = unknown> {
  status:
    | "queued"
    | "running"
    | "paused"
    | "errored"
    | "terminated"
    | "complete"
    | "waiting"
    | "waitingForPause"
    | "unknown"
    | (string & {});
  output?: Result;
  error?: { name: string; message: string } | null;
  rollback?: {
    outcome: "complete" | "failed";
    error: { name: string; message: string } | null;
  } | null;
}

export interface WorkflowClass extends Effect.Effect<WorkflowHandle, never, WorkflowHandle> {
  /** Reference a deployed Workflow by logical ID, optionally in another stack or stage. */
  ref: typeof WorkflowResource.ref;
  <_Self>(): {
    <Input = unknown, Result = unknown, InitReq = never, E = never>(
      name: string,
      impl: Effect.Effect<WorkflowImpl<Input, Result, E>, ConfigError, InitReq>,
    ): Effect.Effect<
      WorkflowHandle<Input, Result>,
      never,
      Worker | Exclude<InitReq, WorkflowServices>
    > & {
      new (_: never): WorkflowImpl<Input, Result, E>;
    };
    <Input = unknown, Result = unknown, InitReq = never, E = never>(
      name: string,
      props: WorkflowProps,
      impl: Effect.Effect<WorkflowImpl<Input, Result, E>, ConfigError, InitReq>,
    ): Effect.Effect<
      WorkflowHandle<Input, Result>,
      never,
      Worker | Exclude<InitReq, WorkflowServices>
    > & {
      new (_: never): WorkflowImpl<Input, Result, E>;
    };
  };
  <Params = unknown>(name: string, props?: WorkflowRefProps): WorkflowLike<Params>;
  <Input = unknown, Result = unknown, InitReq = never, E = never>(
    name: string,
    impl: Effect.Effect<WorkflowImpl<Input, Result, E>, ConfigError, InitReq>,
  ): Effect.Effect<
    WorkflowHandle<Input, Result>,
    never,
    Worker | Exclude<InitReq, WorkflowServices>
  >;
  <Input = unknown, Result = unknown, InitReq = never, E = never>(
    name: string,
    props: WorkflowProps,
    impl: Effect.Effect<WorkflowImpl<Input, Result, E>, ConfigError, InitReq>,
  ): Effect.Effect<
    WorkflowHandle<Input, Result>,
    never,
    Worker | Exclude<InitReq, WorkflowServices>
  >;
}

export class WorkflowScope extends Context.Service<WorkflowScope, WorkflowHandle>()(
  "Cloudflare.Workflow",
) {}

/**
 * A Cloudflare Workflow that orchestrates durable, multi-step tasks with
 * automatic retries and at-least-once delivery.
 *
 * A Workflow follows the same two-phase pattern as Workers and Durable
 * Objects. The outer `Effect.gen` resolves shared dependencies. The inner
 * `Effect.fn` is the workflow body — a function from a typed `input`
 * payload to an Effect that runs steps using `task`, `sleep`, and
 * `sleepUntil`. `task` takes the step name and Effect, plus an optional
 * config object for retries, timeout, and a rollback handler.
 *
 * ```typescript
 * Effect.gen(function* () {
 *   // Phase 1: resolve dependencies
 *   const notifier = yield* NotificationService;
 *
 *   return Effect.fn(function* (input: { orderId: string }) {
 *     // Phase 2: workflow body (durable steps)
 *     const result = yield* Cloudflare.Workflows.task("process", doWork(input.orderId));
 *     yield* Cloudflare.Workflows.sleep("cooldown", "10 seconds");
 *     return result;
 *   });
 * })
 * ```
 *
 *
 * ### Defining a Workflow
 * **Example:** Minimal workflow
 * ```typescript
 * export default class MyWorkflow extends Cloudflare.Workflow<MyWorkflow>()(
 *   "MyWorkflow",
 *   Effect.gen(function* () {
 *     return Effect.fn(function* (input: { name: string }) {
 *       return { received: input.name };
 *     });
 *   }),
 * ) {}
 * ```
 *
 * **Example:** Preserving an existing Workflow name
 *
 * An existing Workflow has no ownership marker, so the first deployment must
 * opt in with `--adopt`. Keep fixed names unique per independently managed
 * stack and stage; unlike the default, they are not stage-scoped by Alchemy.
 *
 * ```typescript
 * export default class MyWorkflow extends Cloudflare.Workflow<MyWorkflow>()(
 *   "MyWorkflow",
 *   { workflowName: "my-existing-workflow" },
 *   Effect.gen(function* () {
 *     return Effect.fn(function* (input: { name: string }) {
 *       return { received: input.name };
 *     });
 *   }),
 * ) {}
 * ```
 *
 * **Example:** Setting a step limit
 * ```typescript
 * export default class MyWorkflow extends Cloudflare.Workflow<MyWorkflow>()(
 *   "MyWorkflow",
 *   { limits: { steps: 25000 } },
 *   Effect.gen(function* () {
 *     return Effect.fn(function* (input: { name: string }) {
 *       return { received: input.name };
 *     });
 *   }),
 * ) {}
 * ```
 *
 * ### Scheduling instances
 * Each matching cron expression creates a new instance automatically —
 * no Worker Cron Trigger or `scheduled` handler required.
 * **Example:** Native cron schedules
 * ```typescript
 * export default class HourlyWorkflow extends Cloudflare.Workflow<HourlyWorkflow>()(
 *   "HourlyWorkflow",
 *   { schedules: ["0 * * * *"] },
 *   Effect.gen(function* () {
 *     return Effect.fn(function* () {
 *       const event = yield* Cloudflare.Workflows.WorkflowEvent;
 *       if (event.schedule) {
 *         return { cron: event.schedule.cron };
 *       }
 *       return {};
 *     });
 *   }),
 * ) {}
 * ```
 *
 * ### Restricting data location
 * `jurisdiction` keeps every instance's execution and stored state inside
 * the EU, the US, or FedRAMP-Moderate data centers. Cloudflare fixes it at
 * creation, so changing it replaces the Workflow and deletes its instances.
 * **Example:** EU-only Workflow
 * ```typescript
 * export default class GdprWorkflow extends Cloudflare.Workflow<GdprWorkflow>()(
 *   "GdprWorkflow",
 *   { jurisdiction: "eu" },
 *   Effect.gen(function* () {
 *     return Effect.fn(function* (input: { userId: string }) {
 *       return { processed: input.userId };
 *     });
 *   }),
 * ) {}
 * ```
 *
 * **Example:** EU-only Workflow on an async Worker
 * ```typescript
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: {
 *     GDPR_WORKFLOW: Cloudflare.Workflow("GdprWorkflow", {
 *       className: "GdprWorkflow",
 *       jurisdiction: "eu",
 *     }),
 *   },
 * });
 * ```
 *
 * ### Step Primitives
 * **Example:** Running a named task
 * ```typescript
 * const result = yield* Cloudflare.Workflows.task(
 *   "process-order",
 *   Effect.succeed({ orderId: "abc", total: 42 }),
 * );
 * ```
 *
 * **Example:** Configuring retries and reading step context
 * ```typescript
 * const result = yield* Cloudflare.Workflows.task(
 *   "call-api",
 *   Effect.gen(function* () {
 *     const context = yield* Cloudflare.Workflows.WorkflowStepContext;
 *     return { attempt: context.attempt };
 *   }),
 *   { retries: { limit: 3, delay: "5 seconds", backoff: "linear" } },
 * );
 * ```
 *
 * **Example:** Registering rollback
 * ```typescript
 * yield* Cloudflare.Workflows.task("reserve-inventory", reserveInventory, {
 *   rollback: ({ output }) =>
 *     output ? releaseInventory(output.reservationId) : Effect.void,
 *   rollbackConfig: { retries: { limit: 3, delay: "10 seconds" } },
 * });
 * ```
 *
 * **Example:** Sleeping between steps
 * ```typescript
 * yield* Cloudflare.Workflows.sleep("cooldown", "30 seconds");
 * ```
 *
 * **Example:** Waiting for an external event
 * ```typescript
 * const event = yield* Cloudflare.Workflows.waitForEvent<{ approved: boolean }>(
 *   "approval",
 *   { type: "approval", timeout: "1 day" },
 * );
 * // Same shape as the native step.waitForEvent result:
 * event.payload.approved;
 * ```
 *
 * **Example:** Accessing env bindings inside a task
 * Bind a resource (e.g. `Namespace`, `Bucket`) in the workflow's
 * outer init phase to get a typed Effect-native client, then use it
 * directly inside `task`. `task` threads the binding's service
 * requirement (`WorkerEnvironment`) through automatically so the inner
 * Effect needs no extra plumbing.
 *
 * ```typescript
 * Effect.gen(function* () {
 *   const kv = yield* Cloudflare.KV.ReadWriteNamespace(KV);
 *
 *   return Effect.fn(function* (input: { roomId: string; message: string }) {
 *     const { roomId, message } = input;
 *
 *     const stored = yield* Cloudflare.Workflows.task(
 *       "kv-roundtrip",
 *       Effect.gen(function* () {
 *         const key = `workflow:${roomId}`;
 *         yield* kv.put(key, message);
 *         return yield* kv.get(key);
 *       }).pipe(Effect.orDie),
 *     );
 *
 *     return stored;
 *   });
 * });
 * ```
 *
 * ### Starting and Monitoring Instances
 * `create` mirrors Cloudflare's native Workflow API: pass workflow input in
 * `params`, pass `id` only when you need a deterministic instance ID, and omit
 * `id` to let Cloudflare generate one.
 *
 * **Example:** Creating an instance from a Worker
 * ```typescript
 * const workflow = yield* MyWorkflow;
 * const instance = yield* workflow.create({ params: { orderId: "abc" } });
 * ```
 *
 * **Example:** Creating an instance with id and retention
 * ```typescript
 * const instance = yield* workflow.create({
 *   id: "order-abc",
 *   params: { orderId: "abc" },
 *   retention: { successRetention: "1 day", errorRetention: "7 days" },
 * });
 * ```
 *
 * **Example:** Creating a batch
 * ```typescript
 * const instances = yield* workflow.createBatch([
 *   { id: "order-a", params: { orderId: "a" } },
 *   { id: "order-b", params: { orderId: "b" } },
 * ]);
 * ```
 *
 * **Example:** Checking instance status
 * ```typescript
 * const workflow = yield* MyWorkflow;
 * const handle = yield* workflow.get(instanceId);
 * const status = yield* handle.status();
 * ```
 *
 * **Example:** Sending events and restarting instances
 * ```typescript
 * const instance = yield* workflow.get(instanceId);
 * yield* instance.sendEvent({ type: "approval", payload: { approved: true } });
 * yield* instance.restart({ from: { name: "approval", type: "waitForEvent" } });
 * ```
 *
 * ### Triggering from a Worker
 * Wire the workflow into HTTP routes so callers can fire instances
 * and poll for completion.
 *
 * **Example:** Workflow start + status routes
 * ```typescript
 * // src/worker.ts
 * const notifier = yield* MyWorkflow;
 *
 * return {
 *   fetch: Effect.gen(function* () {
 *     const request = yield* HttpServerRequest;
 *
 *     if (request.url.startsWith("/workflow/start/")) {
 *       const id = request.url.split("/").pop()!;
 *       const instance = yield* notifier.create({ params: { orderId: id } });
 *       return HttpServerResponse.json({ instanceId: instance.id });
 *     }
 *
 *     if (request.url.startsWith("/workflow/status/")) {
 *       const id = request.url.split("/").pop()!;
 *       const instance = yield* notifier.get(id);
 *       return HttpServerResponse.json(yield* instance.status());
 *     }
 *
 *     return HttpServerResponse.text("Not Found", { status: 404 });
 *   }),
 * };
 * ```
 *
 * ### Binding in an Async Worker
 * When using an Async Worker (plain `async fetch` handler, no Effect
 * runtime), declare Workflows in the `env` prop of the Worker resource.
 * Pass a `Workflow` reference with a `className` matching the exported
 * `WorkflowEntrypoint` subclass in your worker source file. If `className`
 * is omitted, it defaults to the binding name. Use `Cloudflare.InferEnv`
 * to get a fully typed `env` object that includes the workflow binding.
 *
 * **Example:** Declaring a Workflow binding in the stack
 * ```typescript
 * // alchemy.run.ts
 * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
 *
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: {
 *     MY_WORKFLOW: Cloudflare.Workflow<{ value: string }>("MyWorkflow", {
 *       className: "MyWorkflow",
 *       workflowName: "my-existing-workflow",
 *     }),
 *   },
 * });
 * ```
 *
 * **Example:** Native cron schedules on an async Workflow binding
 * ```typescript
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: {
 *     HOURLY: Cloudflare.Workflow("HourlyWorkflow", {
 *       className: "HourlyWorkflow",
 *       schedules: ["0 * * * *"],
 *     }),
 *   },
 * });
 * ```
 *
 * **Example:** Using the Workflow from a plain async handler
 * ```typescript
 * // src/worker.ts
 * import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
 * import type { WorkerEnv } from "../alchemy.run.ts";
 *
 * export class MyWorkflow extends WorkflowEntrypoint<WorkerEnv, { value: string }> {
 *   async run(event: Readonly<WorkflowEvent<{ value: string }>>, step: WorkflowStep) {
 *     return await step.do("greet", async () => `Hello, ${event.payload.value}!`);
 *   }
 * }
 *
 * export default {
 *   async fetch(request: Request, env: WorkerEnv) {
 *     const instance = await env.MY_WORKFLOW.create({ params: { value: "world" } });
 *     return Response.json({ instanceId: instance.id });
 *   },
 * };
 * ```
 *
 * ### Consuming the Workflow's Physical Name
 * An external/async Worker declaration exposes each Workflow binding on `worker.env` with
 * the Workflow's account-global `workflowName` as an `Output` of the
 * current deploy. Pass the binding directly as a Queue subscription's
 * `source`; it deploys after the Workflow is registered, including on the
 * first deployment. Explicit source descriptors remain supported for
 * Workflows referenced by physical name.
 *
 * **Example:** Subscribing a Queue to the Workflow's events
 * ```typescript
 * const worker = yield* Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: {
 *     FILE_URL_INGESTION: Cloudflare.Workflow("FileUrlIngestion", {
 *       className: "FileUrlIngestionWorkflow",
 *     }),
 *   },
 * });
 *
 * yield* Cloudflare.Queues.Subscription("WorkflowEvents", {
 *   source: worker.env.FILE_URL_INGESTION,
 *   events: ["instance.completed", "instance.errored"],
 *   queueId: queue.queueId,
 * });
 * ```
 *
 * ### Referencing a Deployed Workflow
 * `Workflow.ref` reads the same persisted resource as `WorkflowResource.ref`.
 * Use its logical ID (including any namespace), not its physical name or
 * Worker env key. Omitting `stack` and `stage` uses the current stack/stage.
 * Deploy the host first; a reference does not register or own the Workflow
 * and returns resource attributes, not a runtime `WorkflowHandle`.
 *
 * **Example:** Subscribe to a Workflow in another stack
 * ```typescript
 * yield* Cloudflare.Queues.Subscription("WorkflowEvents", {
 *   source: yield* Cloudflare.Workflow.ref("Ingestion", {
 *     stack: "workflow-host",
 *     stage: "production",
 *   }),
 *   events: ["instance.completed", "instance.errored"],
 *   queueId: queue.queueId,
 * });
 * ```
 *
 * ### Cross-Script Binding in an Async Worker
 * Async Workers can also bind to a Workflow hosted by another Worker
 * script. The host Worker declares and exports the `WorkflowEntrypoint`
 * class. The consumer Worker declares a `Workflow` with `scriptName` set
 * to the host Worker's script name. Cross-script references are bindings
 * only — Alchemy does not drive `putWorkflow` for the foreign class, so
 * deploy the host first.
 *
 * **Example:** Consumer Worker binds to the host script
 * ```typescript
 * const consumer = yield* Cloudflare.Worker("Consumer", {
 *   main: "./src/consumer.ts",
 *   env: {
 *     MY_WORKFLOW: Cloudflare.Workflow("MyWorkflow", {
 *       className: "MyWorkflow",
 *       scriptName: host.workerName,
 *       // Repeat the host's explicit or preserved physical name when it
 *       // does not use Alchemy's current generated default.
 *       workflowName: "my-existing-workflow",
 *     }),
 *   },
 * });
 * ```
 *
 * ### Testing Workflows
 * Workflows run asynchronously, so tests start an instance and poll until it
 * reaches a terminal status. Keep polling bounded with `Effect.repeat`.
 *
 * **Example:** Polling for workflow completion
 * ```typescript
 * test(
 *   "workflow completes",
 *   Effect.gen(function* () {
 *     const { url } = yield* stack;
 *
 *     const start = yield* HttpClient.post(`${url}/workflow/start/x`);
 *     const { instanceId } = (yield* start.json) as { instanceId: string };
 *
 *     const status = yield* HttpClient.get(
 *       `${url}/workflow/status/${instanceId}`,
 *     ).pipe(
 *       Effect.flatMap((res) => res.json),
 *       Effect.map((json) => json as { status: string }),
 *       Effect.repeat({
 *         schedule: Schedule.spaced("2 seconds"),
 *         until: (status) =>
 *           status.status === "complete" || status.status === "errored",
 *         times: 30,
 *       }),
 *     );
 *
 *     expect(status.status).toBe("complete");
 *   }),
 *   { timeout: 120_000 },
 * );
 * ```
 *
 * ### Observing and Deleting Instances
 * **Example:** Read an event and remove stored state
 * ```typescript
 * const instance = yield* workflow.get("report-123");
 * const events = yield* instance.subscribe({ filter: ["workflow_queued"] }).pipe(
 *   Stream.take(1),
 *   Stream.runCollect,
 * );
 * yield* instance.delete();
 * const result = yield* workflow.deleteBatch(["report-456", "report-789"]);
 * // result.deleted contains successful IDs; result.errors contains per-instance failures.
 * ```
 *
 * @resource
 * @product Workflows
 * @category Workers & Compute
 */
export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
  ...args:
    | []
    | [name: string, impl: Effect.Effect<WorkflowImpl<any, any, unknown>>]
    | [name: string, props: WorkflowProps, impl: Effect.Effect<WorkflowImpl<any, any, unknown>>]
    | [name: string, props?: WorkflowRefProps]
) => {
  if (args.length === 0) {
    return Workflow;
  }
  const [name, second, third] = args;
  const impl = Effect.isEffect(second) ? second : Effect.isEffect(third) ? third : undefined;
  if (impl === undefined) {
    // Props-only (async) reference form: returns a plain `WorkflowLike` that an
    // async Worker binds via `env`. `WorkerAsyncBindings` emits the `workflow`
    // binding and drives `putWorkflow` for locally-hosted workflows.
    const refProps = second as WorkflowRefProps | undefined;
    return {
      kind: TypeId,
      name,
      workflowName: refProps?.workflowName,
      className: refProps?.className ?? name,
      scriptName: refProps?.scriptName,
      limits: refProps?.limits,
      schedules: refProps?.schedules,
      jurisdiction: refProps?.jurisdiction,
    } satisfies WorkflowLike;
  }
  const props = Effect.isEffect(second) ? undefined : (second as WorkflowProps);
  return effectClass(
    Effect.gen(function* () {
      const worker = yield* Worker;

      const workflow = yield* WorkflowResource(name, {
        workflowName: props?.workflowName,
        className: name,
        scriptName: props?.workflowName === undefined ? worker.workerName : undefined,
        limits: props?.limits,
        schedules: props?.schedules,
        jurisdiction: props?.jurisdiction,
      });
      // Keep named identities resolvable for the engine's cold-adoption probe.
      if (props?.workflowName !== undefined) {
        yield* workflow.bind`${worker}`({ scriptName: worker.workerName });
      }

      // Add the workflow binding to the Worker metadata
      yield* worker.bind`${name}`({
        bindings: [
          {
            type: "workflow",
            name,
            workflowName: props?.workflowName ?? workflow.workflowName,
            className: name,
          },
        ],
      });

      const services = yield* Effect.context<Effect.Services<typeof impl>>();

      const binding = yield* Effect.all([WorkerEnvironment, ALCHEMY_PHASE]).pipe(
        Effect.flatMap(([env, phase]) => {
          if (env === undefined || phase === "plan") {
            return Effect.succeed(undefined as any);
          }
          const wf = env[name];
          if (!wf) {
            return Effect.die(new Error(`Workflow '${name}' not found in env`));
          }
          return Effect.succeed(wf);
        }),
      );

      const self: WorkflowHandle<any, any> = {
        Type: TypeId,
        name,
        workflowName: props?.workflowName ?? workflow.workflowName,
        create: (options?: WorkflowInstanceCreateOptions<any>) =>
          Effect.tryPromise(() => binding.create(options)).pipe(
            Effect.map(wrapInstance),
            Effect.orDie,
          ),
        createBatch: (batch: WorkflowInstanceCreateOptions<any>[]) =>
          Effect.tryPromise(() => binding.createBatch(batch) as Promise<any[]>).pipe(
            Effect.map((instances: any[]) => instances.map(wrapInstance)),
            Effect.orDie,
          ),
        deleteBatch: (instanceIds) =>
          Effect.tryPromise(
            () => binding.deleteBatch(instanceIds) as Promise<WorkflowBatchDeleteResult>,
          ).pipe(Effect.orDie),
        get: (instanceId: string) =>
          Effect.tryPromise(() => binding.get(instanceId)).pipe(
            Effect.map(wrapInstance),
            Effect.orDie,
          ),
      };

      const fn = yield* impl.pipe(Effect.provideService(WorkflowScope, self as any));

      yield* worker.export(name, {
        kind: "workflow",
        make: (env: unknown) =>
          Effect.succeed(((input: unknown) =>
            fn(input).pipe(
              Effect.provideService(WorkerEnvironment, env as Record<string, any>),
            )) as WorkflowImpl<any, any, unknown>).pipe(Effect.provideContext(services)),
      } satisfies WorkflowExport);

      return self;
    }),
  );
}) as any);

Workflow.ref = (id, options) => WorkflowResource.ref(id, options);

// ---------------------------------------------------------------------------
// WorkflowResource -- manages the Cloudflare Workflows API lifecycle
// ---------------------------------------------------------------------------

export interface WorkflowResourceProps {
  /**
   * Account-global Workflow name. If omitted, a deterministic name is derived
   * from `scriptName` and `className`.
   *
   * @internal
   */
  workflowName?: string;
  className: string;
  /** Hosting Worker script, supplied here or through a host binding. */
  scriptName?: string;
  limits?: WorkflowLimits;
  /**
   * Cron expressions that create a new Workflow instance on each match.
   * Pass an empty array to remove all schedules.
   */
  schedules?: string[];
  /**
   * Jurisdiction where instances run and store data. Fixed at creation;
   * changing it replaces the Workflow.
   */
  jurisdiction?: WorkflowJurisdiction;
}

export interface WorkflowResourceAttrs {
  workflowId: string;
  workflowName: string;
  className: string;
  scriptName: string;
  accountId: string;
  /**
   * Cron expressions currently attached to this Workflow.
   */
  schedules: string[];
  /**
   * Jurisdiction where instances run and store data, or `undefined` when
   * unrestricted.
   */
  jurisdiction: WorkflowJurisdiction | undefined;
}

const WorkflowResourceTypeId = "Cloudflare.Workflow";

export interface WorkflowResource extends Resource<
  typeof WorkflowResourceTypeId,
  WorkflowResourceProps,
  WorkflowResourceAttrs,
  { scriptName: string }
> {}

export const WorkflowResource = Resource<WorkflowResource>(WorkflowResourceTypeId);

const getWorkflowOrUndefined = (accountId: string, workflowName: string) =>
  workflows
    .getWorkflow({ accountId, workflowName })
    .pipe(Effect.catchTag("WorkflowNotFound", () => Effect.undefined));

export const ProviderLive = () =>
  Provider.succeed(WorkflowResource, {
    // `workflowId` is stable across live updates: `putWorkflow` is a
    // PUT-as-upsert keyed by the account-global `workflowName`, so re-putting
    // the same name (className/scriptName changes) preserves the workflow's
    // id. The dev→deploy id change that used to force `workflowId` out of
    // this list is now an engine-orchestrated mode-switch REPLACEMENT (the
    // persisted `providerMode` stamp differs), so the live provider never
    // sees a `dev:` id.
    stables: ["workflowId", "accountId", "workflowName"],
    // Workflows are account-scoped. Enumerate every workflow in the account
    // via the paginated list API and hydrate each into the same Attributes
    // shape `reconcile` returns (id/name/className/scriptName are all on the
    // list item, so no per-item get is needed).
    list: () =>
      Effect.gen(function* () {
        const { accountId } = yield* yield* CloudflareEnvironment;
        return yield* workflows.listWorkflows.pages({ accountId }).pipe(
          Stream.runCollect,
          Effect.map((chunk) =>
            Array.from(chunk).flatMap((page) =>
              (page.result ?? []).map((wf) => ({
                workflowId: wf.id,
                workflowName: wf.name,
                // `className`/`scriptName` can be null/absent in the list
                // payload on some accounts — fall back so listing succeeds.
                className: wf.className ?? "",
                scriptName: wf.scriptName ?? "",
                accountId,
                schedules: fromObservedSchedules(wf.schedules),
                jurisdiction: wf.jurisdiction ?? undefined,
              })),
            ),
          ),
        );
      }),
    diff: Effect.fn(function* ({ id, olds, news, output, oldBindings, newBindings }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (output?.accountId !== undefined && output.accountId !== accountId) {
        return { action: "replace" } as const;
      }

      // The host script may be unresolved even when the physical name is known.
      const explicitName =
        "workflowName" in news && isResolved(news.workflowName) ? news.workflowName : undefined;
      const oldName =
        output?.workflowName ??
        olds.workflowName ??
        (olds.scriptName === undefined
          ? undefined
          : yield* generateWorkflowName(olds.scriptName, olds.className));
      // Omitting the name preserves the deployed identity, including legacy names.
      if (explicitName !== undefined && explicitName !== oldName) {
        const existing = yield* getWorkflowOrUndefined(accountId, explicitName);
        if (existing !== undefined) {
          return yield* new OwnedBySomeoneElse({
            message: `Cannot replace Workflow '${oldName}' with occupied name '${explicitName}'. Choose an unused name.`,
            resourceType: WorkflowResourceTypeId,
            logicalId: id,
            physicalName: explicitName,
          });
        }
        return { action: "replace" } as const;
      }
      // Cloudflare fixes the jurisdiction at creation. The replacement keeps
      // the same account-global name, so the old Workflow goes first.
      if (
        "jurisdiction" in news &&
        isResolved(news.jurisdiction) &&
        news.jurisdiction !== (output?.jurisdiction ?? olds.jurisdiction)
      ) {
        return { action: "replace", deleteFirst: true } as const;
      }
      if (!isResolved(newBindings) || havePropsChanged(oldBindings, newBindings)) {
        return { action: "update" } as const;
      }
    }),
    read: Effect.fn(function* ({ output, olds, previous }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const workflowName =
        output?.workflowName ??
        olds?.workflowName ??
        (olds?.scriptName === undefined
          ? undefined
          : yield* generateWorkflowName(olds.scriptName, olds.className));
      if (workflowName === undefined) return undefined;

      const acct = output?.accountId ?? accountId;
      const workflow = yield* getWorkflowOrUndefined(acct, workflowName);
      if (workflow === undefined) return undefined;
      const attrs = {
        workflowId: workflow.id,
        workflowName: workflow.name,
        className: workflow.className,
        scriptName: workflow.scriptName,
        accountId: acct,
        schedules: fromObservedSchedules(workflow.schedules),
        jurisdiction: workflow.jurisdiction ?? undefined,
      };
      // Explicit names carry no ownership marker; cold reads require adoption,
      // except of the generation a replacement is replacing.
      return output === undefined &&
        olds?.workflowName !== undefined &&
        previous?.workflowId !== workflow.id
        ? Unowned(attrs)
        : attrs;
    }),
    reconcile: Effect.fn(function* ({ id, news, output, bindings }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const scriptName = yield* resolveWorkflowScriptName(news, bindings);
      const acct = output?.accountId ?? accountId;
      const workflowName =
        news.workflowName ??
        output?.workflowName ??
        (yield* generateWorkflowName(scriptName, news.className));

      if (
        news.workflowName !== undefined &&
        output?.workflowName !== undefined &&
        news.workflowName !== output.workflowName
      ) {
        return yield* new WorkflowInvalidProps({
          message: `Workflow physical name changed from '${output.workflowName}' to '${news.workflowName}' during an in-place update; a replacement is required.`,
        });
      }

      const existing = yield* getWorkflowOrUndefined(acct, workflowName);
      // Re-check occupied names at apply time; replacement is not adoption.
      if (news.workflowName !== undefined && output === undefined && existing !== undefined) {
        return yield* new OwnedBySomeoneElse({
          message:
            `Cannot create Workflow '${workflowName}': an existing ` +
            "Workflow has that account-global name. Choose an unused name, " +
            "or adopt it into a resource with no prior state by re-planning " +
            "with --adopt.",
          resourceType: WorkflowResourceTypeId,
          logicalId: id,
          physicalName: workflowName,
        });
      }
      // PUT keeps an existing Workflow's jurisdiction, so a mismatch can't converge.
      if (existing !== undefined && (existing.jurisdiction ?? undefined) !== news.jurisdiction) {
        return yield* new WorkflowInvalidProps({
          message:
            `Workflow '${workflowName}' has jurisdiction '${existing.jurisdiction ?? "none"}', ` +
            `but '${news.jurisdiction ?? "none"}' was requested. Cloudflare fixes a ` +
            "Workflow's jurisdiction at creation; use a new name or delete the Workflow first.",
        });
      }
      // PUT clears omitted schedules; preserve observed state unless explicitly set.
      const schedules = news.schedules ?? fromObservedSchedules(existing?.schedules);

      yield* Effect.logInfo(`Cloudflare Workflow reconcile: ${workflowName}`);
      // Cloudflare's `putWorkflow` is a true PUT-as-upsert: identical
      // payloads converge to the same state and a missing workflow is
      // created on the spot.
      const result = yield* workflows.putWorkflow({
        accountId: acct,
        workflowName,
        className: news.className,
        scriptName,
        limits: news.limits,
        schedules: toPutSchedules(schedules),
        jurisdiction: news.jurisdiction,
      });
      return {
        workflowId: result.id,
        workflowName: result.name,
        className: result.className,
        scriptName: result.scriptName,
        accountId: acct,
        schedules,
        jurisdiction: result.jurisdiction ?? news.jurisdiction,
      };
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* Effect.logInfo(`Cloudflare Workflow delete: ${output.workflowName}`);
      yield* workflows
        .deleteWorkflow({
          accountId: output.accountId,
          workflowName: output.workflowName,
        })
        .pipe(Effect.catchTag("WorkflowNotFound", () => Effect.void));
    }),
  });

/**
 * Local (dev) provider — the workflow is purely virtual: a `dev:` id keyed
 * into the local workerd workflow engine. The host worker's `workflow`
 * binding is lowered onto the local runtime's Workflow Engine DO by
 * `LocalWorkerProvider` (`Workflows.local(...)`), so no runtime layer is
 * needed here; instance state persists under the worker's local storage.
 */
export const ProviderLocal = () =>
  Provider.succeed(WorkflowResource, {
    stables: ["accountId"],
    diff: Effect.fn(function* ({ news, output, oldBindings, newBindings }) {
      const accountId = yield* localAccountId;
      if (!output?.workflowId) return { action: "update" } as const;
      if (output.accountId !== accountId) {
        return { action: "replace" } as const;
      }
      // The host script may be unresolved even when the physical name is known.
      const explicitName =
        "workflowName" in news && isResolved(news.workflowName) ? news.workflowName : undefined;
      if (explicitName !== undefined && explicitName !== output.workflowName) {
        return { action: "replace" } as const;
      }
      if (!isResolved(newBindings) || havePropsChanged(oldBindings, newBindings)) {
        return { action: "update" } as const;
      }
      // Fall through to the engine's default prop diff (className /
      // scriptName changes update in place).
    }),
    read: Effect.fn(function* ({ output }) {
      // Purely virtual — the persisted state row is the source of truth.
      return output ?? undefined;
    }),
    reconcile: Effect.fn(function* ({ news, output, bindings }) {
      const accountId = yield* localAccountId;
      const scriptName = yield* resolveWorkflowScriptName(news, bindings);
      if (
        news.workflowName !== undefined &&
        output?.workflowName !== undefined &&
        news.workflowName !== output.workflowName
      ) {
        return yield* new WorkflowInvalidProps({
          message: `Workflow physical name changed from '${output.workflowName}' to '${news.workflowName}' during an in-place update; a replacement is required.`,
        });
      }
      return {
        workflowId: output?.workflowId ?? generateLocalId(),
        workflowName:
          news.workflowName ??
          output?.workflowName ??
          (yield* generateWorkflowName(scriptName, news.className)),
        className: news.className,
        scriptName,
        accountId: output?.accountId ?? accountId,
        schedules: news.schedules ?? output?.schedules ?? [],
        jurisdiction: news.jurisdiction,
      };
    }),
    delete: Effect.fn(function* () {
      // The simulator's on-disk instance state lives under the local worker's
      // storage; dropping the state row is enough — orphaned data is
      // reclaimed with `.alchemy`.
    }),
  });

export const WorkflowProvider = () =>
  ProviderLayer.dual(WorkflowResource, {
    local: () => ProviderLocal(),
    live: () => ProviderLive(),
  });

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

const resolveWorkflowScriptName = (
  props: WorkflowResourceProps,
  bindings: ReadonlyArray<{ data: { scriptName: string } }>,
) => {
  const scripts = [
    ...new Set(
      [props.scriptName, ...bindings.map((binding) => binding.data.scriptName)].filter(
        (name) => name !== undefined,
      ),
    ),
  ];
  return scripts.length === 1
    ? Effect.succeed(scripts[0]!)
    : Effect.fail(
        new WorkflowInvalidProps({
          message: "Workflow requires exactly one hosting Worker script",
        }),
      );
};

const toPutSchedules = (schedules: string[]): workflows.UpdateRequestSchedulesList =>
  schedules.map((cron) => ({ cron }));

const fromObservedSchedules = (schedules?: ReadonlyArray<{ cron: string }> | null): string[] =>
  (schedules ?? []).map((s) => s.cron);

const wrapInstance = <Result>(raw: any): WorkflowInstance<Result> => ({
  id: raw.id,
  status: () =>
    Effect.tryPromise(() => raw.status()).pipe(
      Effect.map((s: any) => ({
        status: s.status as string,
        output: s.output as Result,
        error: s.error,
        rollback: s.rollback,
      })),
      Effect.orDie,
    ),
  pause: () => Effect.tryPromise(() => raw.pause()).pipe(Effect.orDie),
  resume: () => Effect.tryPromise(() => raw.resume()).pipe(Effect.orDie),
  restart: (options?: WorkflowInstanceRestartOptions) =>
    Effect.tryPromise(() => raw.restart(options)).pipe(Effect.orDie),
  terminate: () => Effect.tryPromise(() => raw.terminate()).pipe(Effect.orDie),
  delete: () => Effect.tryPromise(() => raw.delete()).pipe(Effect.orDie),
  subscribe: (options) =>
    Effect.acquireDisposable(
      Effect.tryPromise(
        () => raw.subscribe(options) as Promise<runtime.WorkflowInstanceSubscription & Disposable>,
      ).pipe(Effect.orDie),
    ).pipe(
      Effect.map((subscription) =>
        Stream.fromAsyncIterable(
          {
            [Symbol.asyncIterator]: () => ({
              next: () => subscription.next(),
            }),
          },
          (error) => error,
        ).pipe(Stream.orDie),
      ),
      Stream.unwrap,
    ),
  sendEvent: <Event = unknown>(event: WorkflowInstanceEvent<Event>) =>
    Effect.tryPromise(() => raw.sendEvent(event)).pipe(Effect.orDie),
});