sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workers/ DurableObject.ts

import type * as cf from "@cloudflare/workers-types";
import type { Dependencies } from "alchemy/Dependencies";
import type { HttpEffect } from "alchemy/Http";
import type { Input } from "alchemy/Input";
import * as Output from "alchemy/Output";
import { ALCHEMY_PHASE } from "alchemy/Phase";
import type { MainRpc, PlatformServices } from "alchemy/Platform";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import { effectClass, taggedFunction } from "alchemy/Util/effect";
import { asEffect } from "alchemy/Util/types";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import type { HttpServerError } from "effect/http/HttpServerError";
import * as HttpServerRequest from "effect/http/HttpServerRequest";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import * as Layer from "effect/Layer";
import * as Predicate from "effect/Predicate";
import type { Scope } from "effect/Scope";
import type { Container } from "../Containers/Container.ts";
import { DurableObjectState, fromDurableObjectState } from "./DurableObjectState.ts";
import { makeRpcStub, type RpcErrorClass } from "./Rpc.ts";
import { type WebSocket } from "./WebSocket.ts";
import { isWorker, Worker, WorkerEnvironment, type WorkerServices } from "./Worker.ts";

export interface DurableObjectExport {
  readonly kind: "durableObject";
  readonly constructor: Effect.Effect<
    Effect.Effect<DurableObjectShape, never, RuntimeContext>,
    never,
    DurableObjectState
  >;
  readonly services: Context.Context<never>;
}

export const isDurableObjectExport = (value: unknown): value is DurableObjectExport =>
  typeof value === "object" && (value as any)?.kind === "durableObject";

export type DurableObjectId = cf.DurableObjectId;
export type DurableObjectJurisdiction = cf.DurableObjectJurisdiction;
export type DurableObjectGetDurableObjectOptions = cf.DurableObjectNamespaceGetDurableObjectOptions;
/**
 * The regions a Durable Object can be *hinted* toward at creation —
 * `"wnam"`, `"enam"`, `"sam"`, `"weur"`, `"eeur"`, `"apac"`, `"oc"`, … See
 * the "Placing a Durable Object in a Region" section on {@link DurableObject}.
 */
export type DurableObjectLocationHint = cf.DurableObjectLocationHint;

export type AlarmInvocationInfo = cf.AlarmInvocationInfo;

type TypeId = "Cloudflare.DurableObject";
const TypeId = "Cloudflare.DurableObject";

export const isDurableObjectLike = (value: unknown): value is DurableObjectLike =>
  typeof value === "object" && (value as any)?.kind === TypeId;

export interface DurableObjectLike<Shape = any> {
  kind: TypeId;
  name: string;
  /** @internal phantom */
  className?: string;
  /** @internal phantom */
  scriptName?: Input<string>;
  /** @internal phantom */
  transferredFrom?: DurableObjectTransferSource | DurableObjectTransferSource[];
  /** @internal phantom */
  storage?: "sqlite" | "legacy-kv";
  /** @internal Durable Object-managed Containers attached to the class. */
  containers?: ReadonlyArray<Container.Decl.Any>;
  /** @internal phantom */
  Shape?: Shape;
}

export interface DurableObject<Shape = unknown> extends DurableObjectLike<Shape> {
  Type: TypeId;
  /** The namespace's logical id. */
  LogicalId: string;
  name: string;
  namespaceId: Output.Output<string>;
  getByName: (
    name: string,
    options?: DurableObjectGetDurableObjectOptions,
  ) => DurableObjectStub<Shape>;
  newUniqueId: () => DurableObjectId;
  idFromName: (name: string) => DurableObjectId;
  idFromString: (id: string) => DurableObjectId;
  get: (
    id: DurableObjectId,
    options?: DurableObjectGetDurableObjectOptions,
  ) => DurableObjectStub<Shape>;
  /**
   * A view of this namespace whose objects are created and stored only inside
   * the given jurisdiction (e.g. `"eu"`). The same name addresses a different
   * object than it does in the unrestricted namespace.
   *
   * Enforced when deployed, not emulated in `alchemy dev`: local workerd does
   * not implement jurisdictions, so there this returns the unrestricted
   * namespace, and the same name addresses the same object in both.
   *
   * @example
   * ```typescript
   * const room = rooms.jurisdiction("eu").getByName(roomId);
   * ```
   */
  jurisdiction: (jurisdiction: DurableObjectJurisdiction) => DurableObject<Shape>;
}

export interface DurableObjectShape {
  fetch?: HttpEffect<DurableObjectState | RuntimeContext>;
  alarm?: (alarmInfo?: AlarmInvocationInfo) => Effect.Effect<void, never, RuntimeContext>;
  webSocketMessage?: (socket: WebSocket, message: string | ArrayBuffer) => Effect.Effect<void>;
  webSocketClose?: (
    socket: WebSocket,
    code: number,
    reason: string,
    wasClean: boolean,
  ) => Effect.Effect<void>;
  /**
   * Called when a hibernatable WebSocket errors. The runtime closes the
   * socket after this handler; use it to drop the peer's session state.
   */
  webSocketError?: (socket: WebSocket, error: unknown) => Effect.Effect<void>;
}

export type DurableObjectServices =
  | DurableObject
  | DurableObjectState
  | DurableObjectScope
  | WorkerServices
  | WorkerEnvironment
  | PlatformServices;

/**
 * A reference to the Worker that previously hosted a Durable Object class,
 * accepted by {@link DurableObjectProps.transferredFrom}:
 *
 * - the Worker's **logical id** (same stack + stage) or **physical script
 *   name** (cross-stack) as a string
 * - the Worker **resource** (`const b = yield* Cloudflare.Worker(...)`)
 * - the Worker **class** (`transferredFrom: WorkerA`)
 * - a **thunk** of any of the above (`() => WorkerA`) — use this for
 *   forward references and import cycles; it is evaluated lazily at plan
 *   time, after all modules have loaded
 * - a string `Output` (e.g. a cross-stack `stackRef`'s worker name)
 *
 * Every form is normalized at plan time to a plain identifier: a Worker
 * reference contributes its logical id, and a same-stack `workerName`
 * Output contributes its source resource's logical id rather than the
 * Output itself. Keeping the former host's *value* out of the binding data
 * matters — consuming its Output would add a dependency edge from the new
 * host onto the former host, inverting the deploy order the transfer
 * requires (the new host must upload first).
 */
export type DurableObjectTransferSource =
  | Input<string>
  | Worker
  | Effect.Effect<Worker, any, any>
  | (() => DurableObjectTransferSource);

const resolveTransferSourceRef = (
  source: DurableObjectTransferSource,
  depth = 0,
): Input<string> => {
  if (typeof source === "string") {
    return source;
  }
  // A Worker resource — contribute its logical id.
  if (isWorker(source)) {
    return source.LogicalId;
  }
  // A Worker platform class — carries its logical id statically. (On an
  // Output proxy this property access yields another Output, never a
  // string, so the check cannot misfire there.)
  const logicalId = (source as { LogicalId?: unknown }).LogicalId;
  if (typeof logicalId === "string") {
    return logicalId;
  }
  // A same-stack Output on a Worker (e.g. `b.workerName`): take the
  // identity from its provenance, not the value.
  if (Output.isPropExpr(source)) {
    const expr = (source as Output.PropExpr<any, any>).expr;
    if (Output.isResourceExpr(expr) && isWorker(expr.src)) {
      return expr.src.LogicalId;
    }
  }
  if (Output.isResourceExpr(source) && isWorker(source.src)) {
    return source.src.LogicalId;
  }
  if (Output.isOutput(source)) {
    // No local resource to take identity from (e.g. a cross-stack
    // `stackRef`) — the engine resolves the string at deploy time.
    return source as Input<string>;
  }
  if (typeof source === "function" && depth < 8) {
    return resolveTransferSourceRef((source as () => DurableObjectTransferSource)(), depth + 1);
  }
  throw new Error(
    "Invalid transferredFrom entry: pass the former host's logical id or script name, its Worker class or resource, a thunk of one of those, or a string Output.",
  );
};

/**
 * Normalize a `transferredFrom` declaration to plain host identifiers at
 * plan time. See {@link DurableObjectTransferSource} for the accepted forms
 * and why Worker references reduce to logical ids instead of Outputs.
 *
 * @internal
 */
export const normalizeTransferredFrom = (
  value: DurableObjectTransferSource | readonly DurableObjectTransferSource[] | undefined,
): Input<string>[] | undefined =>
  value === undefined
    ? undefined
    : (Array.isArray(value)
        ? (value as readonly DurableObjectTransferSource[])
        : [value as DurableObjectTransferSource]
      ).map((source) => resolveTransferSourceRef(source));

/**
 * `ns` restricted to `jurisdiction`. Local workerd (`alchemy dev`) does not
 * implement jurisdictions and throws on `jurisdiction()`, so there the
 * unrestricted namespace is used, the same way a D1 database, R2 bucket or
 * Queue declared with a jurisdiction runs unrestricted on the local simulator.
 */
const restrictToJurisdiction = (
  ns: cf.DurableObjectNamespace | undefined,
  jurisdiction: DurableObjectJurisdiction,
): cf.DurableObjectNamespace | undefined => {
  try {
    return ns?.jurisdiction(jurisdiction);
  } catch (error) {
    // workerd's message; a deployed Worker never throws it.
    if (
      Predicate.hasProperty(error, "message") &&
      String(error.message).includes("Jurisdiction restrictions are not implemented")
    ) {
      return ns;
    }
    throw error;
  }
};

export interface DurableObjectProps {
  /**
   * Name of the exported `DurableObject` class.
   *
   * @default name
   */
  className?: string;
  /**
   * Worker script that hosts the Durable Object class. Omit this when the
   * namespace is hosted by the Worker that declares the binding.
   */
  scriptName?: Input<string> | undefined;
  /**
   * The Worker(s) that previously hosted this Durable Object class. When one
   * of them still holds the namespace, the deploy transfers it — including
   * all stored objects — from that script to this Worker: this Worker
   * declares the class `expecting-transfer` in its `exports`, and the former
   * host commits the move with a `transferred` tombstone.
   *
   * Each entry names a former host — see
   * {@link DurableObjectTransferSource} for the accepted forms: a string
   * (Worker logical id in this stack + stage, or physical script name for
   * cross-stack moves), the Worker class or resource itself, or a thunk
   * (`() => WorkerA`) for forward references. Moving a class is always
   * declared this way — there is no inference. A list is a host *history*:
   * as the class moves again, append the previous host so stages that lag
   * behind (or skipped an intermediate release) still transfer from
   * wherever their namespace currently lives.
   *
   * When no listed host holds the namespace — a fresh stage, or every
   * transfer already completed — the property is inert and the class is
   * created fresh (or left as-is), so it is safe to leave in place
   * indefinitely.
   */
  transferredFrom?: DurableObjectTransferSource | DurableObjectTransferSource[] | undefined;
  /**
   * Storage backend of the class, as Wrangler's `storage` declares it.
   * `"legacy-kv"` describes a class created before SQLite-backed Durable
   * Objects: deploys keep an existing namespace's backend, and Cloudflare
   * no longer creates new key-value backed namespaces. In `alchemy dev` a
   * `"legacy-kv"` class has no SQL storage, as on Cloudflare.
   *
   * @default "sqlite"
   */
  storage?: "sqlite" | "legacy-kv" | undefined;
  /**
   * Tagged-error classes this Durable Object's RPC methods can fail with.
   *
   * Effect failures crossing the Worker↔DO RPC boundary are serialized to
   * plain `{ _tag, ...fields }` objects; declaring the classes here lets
   * the calling side reconstruct real instances (both sides import this
   * same class declaration, so the schema is shared by construction) —
   * `Effect.catchTag`, `instanceof`, and schema encoders (e.g. HttpApi
   * error responses) then all see the class the DO actually failed with.
   *
   * ```typescript
   * export class Repo extends Cloudflare.DurableObject<Repo, RepoShape>()(
   *   "Repo",
   *   { errors: [RepoNotFound, StoreError] },
   * ) {}
   * ```
   */
  errors?: ReadonlyArray<RpcErrorClass> | undefined;
  // environment?: string | undefined;
  // sqlite?: boolean | undefined;
  // namespaceId?: string | undefined;
}

/**
 * Props of an async Worker's Durable Object binding,
 * `Cloudflare.DurableObject(className, props)` in `env`.
 */
export interface DurableObjectBindingProps extends DurableObjectProps {
  /**
   * Durable Object-managed Containers (`schedulingPolicy: "durable_object"`)
   * this class starts. Each adds its image to the class's container
   * application under the Container's id, read at runtime from
   * `ctx.container.images`. A Container may be listed by several classes.
   *
   * Only for a plain (async) Durable Object class the Worker hosts.
   * Effect-native Durable Objects `yield*` their Containers instead; listing
   * Containers for one fails with `DurableObjectContainersOnEffectNativeClass`.
   *
   * ```typescript
   * env: {
   *   AGENT: Cloudflare.DurableObject("Agent", { containers: [Node, Python] }),
   * }
   * ```
   */
  containers?: ReadonlyArray<Container.Decl.Any> | undefined;
}

export interface DurableObjectClass extends Effect.Effect<DurableObject, never, DurableObject> {
  <Self, Shape>(): {
    <Name extends string>(
      name: Name,
      props?: Pick<DurableObjectProps, "transferredFrom" | "errors">,
    ): Effect.Effect<DurableObject<Self>, never, Worker | Self> & {
      new (_: never): Shape & {
        /** @internal */
        "~alchemy/name": Name;
      };
      from(scriptName: Input<string>): Effect.Effect<DurableObject<Self>, never, Worker>;
      from<Req = never>(
        worker: Dependencies<Self> | Effect.Effect<Dependencies<Self>, never, Req>,
      ): Effect.Effect<DurableObject<Self>, never, Worker | Req>;
      make<Req = never>(
        impl: Effect.Effect<
          Effect.Effect<Shape, never, RuntimeContext | DurableObjectState | Scope>,
          never,
          Req
        >,
        // `Exclude` (rather than `DurableObjectServices | Req` inference)
        // so ambient DO services resolved in the outer init effect never
        // leak into the host Worker's requirements — mirrors Worker.make's
        // `Exclude<InitReq, Self | WorkerServices>`.
      ): Layer.Layer<Self, never, Worker | Exclude<Req, DurableObjectServices>>;
    };
  };
  <Self>(): {
    <
      Shape extends MainRpc<DurableObjectState>,
      Req extends DurableObjectServices | Container.Application<any> = never,
    >(
      name: string,
      impl: Effect.Effect<
        Effect.Effect<Shape, never, RuntimeContext | DurableObjectState | Scope>,
        never,
        Req
      >,
    ): Effect.Effect<
      DurableObject<Self>,
      never,
      Worker | Extract<Req, Container.Application<any>>
    > & {
      new (_: never): Shape;
    };
  };
  <Shape>(name: string, props?: DurableObjectBindingProps): DurableObjectLike<Shape>;
  <Shape, InitReq = never>(
    name: string,
    impl: Effect.Effect<Shape, never, DurableObjectServices | InitReq>,
  ): Effect.Effect<DurableObject<Shape>, never, Worker | Exclude<InitReq, DurableObjectServices>>;
}

export class DurableObjectScope extends Context.Service<DurableObjectScope, DurableObject>()(
  "Cloudflare.DurableObject",
) {}

/**
 * A Cloudflare Durable Object namespace that manages globally unique, stateful
 * instances with WebSocket hibernation support.
 *
 * A Durable Object uses a two-phase pattern with two nested `Effect.gen`
 * blocks. The outer Effect resolves shared dependencies (other DOs,
 * containers, etc.) and the instance state *reference*
 * (`Cloudflare.DurableObjectState`). The inner Effect returns the
 * object's public methods and WebSocket handlers — and is the only
 * place the state's `RuntimeContext`-colored methods (`storage.get`,
 * `storage.put`, …) can actually run.
 *
 * ```typescript
 * Effect.gen(function* () {
 *   // Phase 1: resolve shared dependencies + the instance state ref
 *   const db = yield* Cloudflare.D1.QueryDatabase(MyDatabase);
 *   const state = yield* Cloudflare.DurableObjectState;
 *
 *   return Effect.gen(function* () {
 *     // Phase 2: per-instance setup and public API. `state`'s methods
 *     // (storage.get/put, …) are RuntimeContext-colored, so the actual
 *     // I/O happens here, in the runtime closure.
 *     return {
 *       save: (data: string) => db.exec("INSERT ..."),
 *       fetch: Effect.gen(function* () { ... }),
 *       webSocketMessage: Effect.fn(function* (ws, msg) { ... }),
 *     };
 *   });
 * })
 * ```
 *
 * There are two ways to define a Durable Object. See the
 * [Runtime](/infrastructure-as-effects/runtime) page
 * for the full explanation.
 *
 * - **Inline** — Effect implementation passed directly, single file.
 * - **Modular** — class and implementation in separate files for tree-shaking.
 *
 *
 * ### Inline Durable Objects
 * Pass the Effect implementation as the second argument. This is the
 * simplest approach — everything lives in one file. Convenient when
 * the DO doesn't need to be referenced by other Workers or DOs that
 * would pull in its runtime dependencies.
 *
 * **Example:** Inline Durable Object
 * ```typescript
 * export default class Counter extends Cloudflare.DurableObject<Counter>()(
 *   "Counter",
 *   Effect.gen(function* () {
 *     // init: bind resources + resolve the instance state ref
 *     const db = yield* Cloudflare.D1.QueryDatabase(MyDatabase);
 *     const state = yield* Cloudflare.DurableObjectState;
 *
 *     return Effect.gen(function* () {
 *       // runtime: state's storage methods are RuntimeContext-colored,
 *       // so the reads/writes live here
 *       const count = (yield* state.storage.get<number>("count")) ?? 0;
 *
 *       return {
 *         increment: () =>
 *           Effect.gen(function* () {
 *             const next = count + 1;
 *             yield* state.storage.put("count", next);
 *             return next;
 *           }),
 *         get: () => Effect.succeed(count),
 *       };
 *     });
 *   }),
 * ) {}
 * ```
 *
 * ### Modular Durable Objects
 * When a Worker and a DO reference each other, or multiple Workers
 * bind the same DO, define the class separately from its `.make()`
 * call. The class is a lightweight identifier; `.make()` provides
 * the runtime implementation as an `export default`. Rolldown treats
 * `.make()` as pure, so the bundler tree-shakes it and all its
 * runtime dependencies out of any consumer's bundle.
 *
 * The class and `.make()` can live in the same file. This is the
 * same pattern used by `Worker` and `Container`.
 *
 * **Example:** Modular Durable Object (class + .make() in one file)
 * ```typescript
 * // src/Counter.ts
 * export class Counter extends Cloudflare.DurableObject<Counter>()(
 *   "Counter",
 * ) {}
 *
 * export default Counter.make(
 *   Effect.gen(function* () {
 *     // init: bind resources + resolve the instance state ref
 *     const db = yield* Cloudflare.D1.QueryDatabase(MyDatabase);
 *     const state = yield* Cloudflare.DurableObjectState;
 *
 *     return Effect.gen(function* () {
 *       // runtime: state's storage methods are RuntimeContext-colored,
 *       // so the reads/writes live here
 *       const count = (yield* state.storage.get<number>("count")) ?? 0;
 *
 *       return {
 *         increment: () =>
 *           Effect.gen(function* () {
 *             const next = count + 1;
 *             yield* state.storage.put("count", next);
 *             yield* db.prepare("INSERT INTO logs (count) VALUES (?)").bind(next).run();
 *             return next;
 *           }),
 *         get: () => Effect.succeed(count),
 *       };
 *     });
 *   }),
 * );
 * ```
 *
 * **Example:** Binding a modular DO from a Worker
 * ```typescript
 * // imports Counter; bundler tree-shakes .make()
 * import Counter from "./Counter.ts";
 *
 * // init
 * const counters = yield* Counter;
 *
 * return {
 *   fetch: Effect.gen(function* () {
 *     const counter = counters.getByName("user-123");
 *     return HttpServerResponse.text(String(yield* counter.get()));
 *   }),
 * };
 * ```
 *
 * ### Cross-Worker Binding
 * A Durable Object is _hosted_ by exactly one Worker, but any
 * number of other Workers can bind to the same DO. This is how
 * you share state across Workers: one Worker hosts the DO, every
 * other Worker addresses it by `scriptName` and gets a typed stub.
 *
 * To make this type-safe, the **host Worker** must declare the DO
 * as part of its public contract via the third type argument to
 * `Cloudflare.Worker<Self, Bindings, Deps>()`. `Deps` is the set
 * of DO classes (or other Workers) the script exposes for other
 * scripts to bind to.
 *
 * **Example:** Host Worker declares the DO in its contract
 * ```typescript
 * // workerA.ts — hosts Counter
 * import { Counter, CounterLive } from "./object.ts";
 *
 * //                                       ^^^^^^^ declared as part of WorkerA's public contract
 * export class WorkerA extends Cloudflare.Worker<WorkerA, {}, Counter>()(
 *   "WorkerA",
 *   { main: import.meta.url },
 * ) {}
 *
 * // WorkerA's Layer also provides the DO's Live implementation.
 * export default WorkerA.make(
 *   Effect.gen(function* () {
 *     const counter = yield* Counter;
 *     return { fetch: Effect.gen(function* () { ... }) };
 *   }).pipe(Effect.provide(CounterLive)),
 * );
 * ```
 *
 * **Example:** Consumer Worker binds the DO via `Counter.from(WorkerA)`
 * ```typescript
 * // workerB.ts — binds to the same Counter, hosted by WorkerA
 * import { Counter } from "./object.ts";
 * import { WorkerA } from "./workerA.ts";
 *
 * export default class WorkerB extends Cloudflare.Worker<WorkerB>()(
 *   "WorkerB",
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     //              ^^^^^^^^^^^^ scriptName-bound stub of WorkerA's Counter
 *     const counter = yield* Counter.from(WorkerA);
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const value = yield* counter.getByName("shared").get();
 *         return HttpServerResponse.text(String(value));
 *       }),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * :::tip
 * The `, Counter` in `Worker<WorkerA, {}, Counter>` is what makes
 * `Counter.from(WorkerA)` type-check. You can still bind across
 * scripts without it (the runtime works either way), but consumers
 * will get a TypeScript error because `WorkerA` doesn't declare
 * `Counter` as part of its public contract.
 * :::
 *
 * Only the host Worker's Stack provides `CounterLive` — the
 * consumer Worker just imports the `Counter` class as a typed
 * identifier. Rolldown tree-shakes `CounterLive` (and its
 * dependencies) out of WorkerB's bundle.
 *
 * ### Using `.from(Self)` Inside the Host
 * Inside the host Worker, `yield* Counter` and
 * `yield* Counter.from(Self)` resolve to the same local namespace.
 * The `.from(Self)` form is preferred — especially in code that
 * may be extracted into a reusable Layer — because it makes the
 * scriptName explicit and lets the same Layer shape work whether
 * the consumer is the host or another script.
 *
 * **Example:** `Counter.from(WorkerA)` inside WorkerA itself
 * ```typescript
 * // workerA.ts — host uses `.from(Self)` instead of bare `yield* Counter`
 * export default WorkerA.make(
 *   Effect.gen(function* () {
 *     const counter = yield* Counter.from(WorkerA); // same as `yield* Counter`
 *     return { fetch: Effect.gen(function* () { ... }) };
 *   }).pipe(Effect.provide(CounterLive)),
 * );
 * ```
 *
 * A Worker can also host its **own isolated** namespace this way.
 * If a second host Worker declares `Counter` in its contract and
 * provides `CounterLive`, the DO instances under that script are
 * separate from the original host's — same class, two namespaces.
 *
 * **Example:** Two hosts, two isolated namespaces
 * ```typescript
 * // workerC.ts — another host of Counter, isolated from WorkerA
 * export class WorkerC extends Cloudflare.Worker<WorkerC, {}, Counter>()(
 *   "WorkerC",
 *   { main: import.meta.url },
 * ) {}
 *
 * export default WorkerC.make(
 *   Effect.gen(function* () {
 *     // .from(WorkerC) binds to WorkerC's own Counter namespace —
 *     // writes here are NOT visible from WorkerA's Counter.
 *     const counter = yield* Counter.from(WorkerC);
 *     return { fetch: Effect.gen(function* () { ... }) };
 *   }).pipe(Effect.provide(CounterLive)),
 * );
 * ```
 *
 * ### RPC Methods
 * Any function you return from the inner Effect becomes an RPC method
 * that Workers can call through a stub. Methods must return an `Effect`.
 * The caller gets a fully typed stub — if your DO returns `increment`
 * and `get`, the stub exposes `counter.increment()` and `counter.get()`.
 *
 * **Example:** Defining RPC methods
 * ```typescript
 * return {
 *   increment: () => Effect.succeed(++count),
 *   get: () => Effect.succeed(count),
 *   reset: () => Effect.sync(() => { count = 0; }),
 * };
 * ```
 *
 * ### Redeploying a Busy Durable Object
 * A redeploy reaches your Workers right away, but Cloudflare moves each
 * Durable Object onto the new code separately. An object idle for about
 * 10 seconds starts on the new code at its next call. An object that keeps
 * receiving traffic (requests, an open WebSocket, or a recurring alarm)
 * keeps running its previous code for up to about 5 minutes after the
 * deploy, until Cloudflare restarts it; open WebSockets disconnect (code
 * 1006) when that happens. Until then a new Worker calling a method that
 * only the new code defines fails with `RpcCallError` ("The RPC receiver
 * does not implement the method"). Keep RPC changes backward compatible
 * across a deploy: add a method, ship the callers in a later deploy, and
 * remove old methods last.
 *
 * **Example:** Tolerate an object that has not picked up a new method yet
 * ```typescript
 * const result = yield* counter.incrementBy(5).pipe(
 *   // Older code is still serving this object: use the old method.
 *   Effect.catchCause((cause) =>
 *     Cause.squash(cause) instanceof Cloudflare.RpcCallError
 *       ? counter.increment()
 *       : Effect.failCause(cause),
 *   ),
 * );
 * ```
 *
 * ### Returning Streams from RPC
 * RPC methods can return an Effect `Stream` and the caller will see
 * the chunks as they're produced. Combine with `Stream.schedule` to
 * pace emission, or with `Stream.fromQueue` to bridge an inbound
 * subscription.
 *
 * **Example:** Streaming sequential numbers
 * ```typescript
 * import * as Schedule from "effect/Schedule";
 * import * as Stream from "effect/Stream";
 *
 * return {
 *   tick: (n: number) =>
 *     Stream.iterate(0, (i) => i + 1).pipe(
 *       Stream.take(n),
 *       Stream.schedule(Schedule.spaced("100 millis")),
 *     ),
 * };
 * ```
 *
 * **Example:** Forwarding the stream as a chunked HTTP response
 * ```typescript
 * // in a Worker fetch handler
 * const counter = counters.getByName("tick");
 * const stream = counter.tick(5).pipe(
 *   Stream.map((i) => `${i}\n`),
 *   Stream.encodeText,
 * );
 * return HttpServerResponse.stream(stream, {
 *   headers: { "content-type": "text/plain" },
 * });
 * ```
 *
 * ### Worker → DO HTTP forwarding
 * In addition to RPC methods, the typed stub exposes a `fetch`
 * method that forwards an `HttpServerRequest` straight to the DO.
 * The DO's own `fetch` Effect produces the response — useful for
 * WebSocket upgrades and other request-shaped interactions.
 *
 * **Example:** Forwarding an HTTP request to a DO
 * ```typescript
 * const room = rooms.getByName(roomId);
 * return yield* room.fetch(request);
 * ```
 *
 * ### Placing a Durable Object in a Region
 * A Durable Object is created wherever its *first-ever* request
 * came from, and it stays there for life. That default is right for
 * an instance whose traffic all comes from the user who created it,
 * and wrong for one whose name is derived from something other than
 * geography (a shard index, a hash, a fixed roster) — a Sydney user
 * routed onto an instance that some Frankfurt request happened to
 * create first pays a cross-planet round trip on every call.
 *
 * Pass a `locationHint` to place the instance near the traffic you
 * expect instead. It only applies to *creation*: an instance that
 * already exists is unaffected, so a hint can't move a live DO.
 *
 * **Example:** Sharding instances by region
 * ```typescript
 * // Both the name and the hint derive from the caller's region, so
 * // each shard is created in the region whose users address it.
 * const region = hintFor(request.cf?.continent); // "apac", "weur", …
 * const shard = shards.getByName(`pool:${region}:${index}`, {
 *   locationHint: region,
 * });
 * ```
 *
 * :::caution
 * A hint is a hint: Cloudflare places the instance in the nearest
 * location it *can*, which may not be the hinted one, and only the
 * first request to a given name has any say. Derive the name from
 * the same region you hint with — otherwise two regions race to
 * create one shared instance and the loser is stuck with it.
 * :::
 *
 * ### Accessing Instance State
 * Each Durable Object instance has its own transactional key-value
 * storage via `Cloudflare.DurableObjectState`. Resolve the `state`
 * *reference* in the outer (init) Effect, but call its methods —
 * `storage.get`, `storage.put`, … — only from the inner (runtime)
 * Effect: those methods are `RuntimeContext`-colored, so the type
 * system only allows them inside the runtime closure.
 *
 * **Example:** Reading and writing durable storage
 * ```typescript
 * // inner (runtime) Effect — `state` was resolved in the outer Effect
 * yield* state.storage.put("counter", 42);
 * const value = yield* state.storage.get("counter");
 * ```
 *
 * ### Background Work & Scopes
 * Every RPC call and fetch into a Durable Object gets its own Effect
 * `Scope`. When the method finishes, the bridge closes that scope and
 * registers the close promise with workerd's `state.waitUntil` — so
 * finalizers added with `Effect.addFinalizer` inside a method run *after*
 * the result is returned to the caller, without blocking it, and the
 * object stays alive until they settle.
 *
 * For ad-hoc background work, `state.waitUntil(effect)` forks an Effect
 * with the caller's full context and keeps the object alive until it
 * settles.
 *
 * Attach cleanup to method scopes, not the constructor (init) closure —
 * the constructor runs once per in-memory instance under
 * `blockConcurrencyWhile`, and its scope is not tied to any call.
 *
 * **Example:** Responding before finishing the work
 * ```typescript
 * return {
 *   record: Effect.fn(function* (entry: string) {
 *     // runs after `record` returns; the DO stays alive until it settles
 *     yield* Effect.addFinalizer(() =>
 *       state.storage.put(`audit:${entry}`, Date.now()).pipe(Effect.ignore),
 *     );
 *     return "accepted" as const;
 *   }),
 *
 *   refresh: Effect.fn(function* () {
 *     // same idea, explicit form
 *     yield* state.waitUntil(recomputeExpensiveView());
 *     return "scheduled" as const;
 *   }),
 * };
 * ```
 *
 * ### WebSocket Hibernation
 * Durable Objects support WebSocket hibernation — the runtime can
 * evict the object from memory while keeping connections open. Use
 * `Cloudflare.upgrade()` to accept a connection, and return
 * `webSocketMessage` / `webSocketClose` / `webSocketError` handlers to
 * process events when the object wakes back up.
 *
 * **Example:** Accepting a WebSocket connection
 * ```typescript
 * return {
 *   fetch: Effect.gen(function* () {
 *     const [response, socket] = yield* Cloudflare.upgrade();
 *     socket.serializeAttachment({ id: crypto.randomUUID() });
 *     return response;
 *   }),
 * };
 * ```
 *
 * **Example:** Handling messages and close events
 * ```typescript
 * return {
 *   webSocketMessage: Effect.fn(function* (
 *     socket: Cloudflare.WebSocket,
 *     message: string | Uint8Array,
 *   ) {
 *     const text = typeof message === "string"
 *       ? message
 *       : new TextDecoder().decode(message);
 *     // process the message
 *   }),
 *   webSocketClose: Effect.fn(function* (
 *     ws: Cloudflare.WebSocket,
 *     code: number,
 *     reason: string,
 *   ) {
 *     yield* ws.close(code, reason);
 *   }),
 *   webSocketError: Effect.fn(function* (
 *     ws: Cloudflare.WebSocket,
 *     error: unknown,
 *   ) {
 *     // the runtime closes the socket afterwards; clear its session here
 *     ws.serializeAttachment(null);
 *   }),
 * };
 * ```
 *
 * **Example:** Recovering sessions after hibernation
 * Resolve the `state` reference in the outer Effect, but place the
 * rehydration loop (`state.getWebSockets()` is `RuntimeContext`-colored)
 * **inside the inner `Effect.gen`** so it runs every time the DO
 * instance is reconstructed (including after Cloudflare wakes the DO
 * from hibernation).
 *
 * ```typescript
 * Effect.gen(function* () {
 *   const state = yield* Cloudflare.DurableObjectState;
 *
 *   return Effect.gen(function* () {
 *     const sessions = new Map<string, Cloudflare.WebSocket>();
 *
 *     // Rehydrate the in-memory session map after hibernation.
 *     for (const socket of yield* state.getWebSockets()) {
 *       const data = socket.deserializeAttachment<{ id: string }>();
 *       if (data) sessions.set(data.id, socket);
 *     }
 *
 *     return {
 *       fetch: Effect.gen(function* () {
 *         const [response, socket] = yield* Cloudflare.upgrade();
 *         const id = crypto.randomUUID();
 *         socket.serializeAttachment({ id });
 *         sessions.set(id, socket);
 *         return response;
 *       }),
 *       webSocketMessage: Effect.fn(function* (socket, message) {
 *         const text =
 *           typeof message === "string" ? message : new TextDecoder().decode(message);
 *         for (const peer of sessions.values()) {
 *           yield* peer.send(text);
 *         }
 *       }),
 *     };
 *   });
 * });
 * ```
 *
 * ### Durable Callbacks
 * Register `Alchemy.makeCallback` handlers in the inner, per-instance Effect.
 * Durable Objects supply callback registration on their instance RuntimeContext
 * using SQLite and native alarms. Scheduling participates in the current storage
 * transaction, and each job is acknowledged only after its handler succeeds.
 * No explicit `alarm` handler is needed.
 *
 * **Example:** Save state and schedule a typed callback atomically
 * ```typescript
 * const state = yield* Cloudflare.DurableObjectState;
 * return Effect.gen(function* () {
 *   const onArchive = yield* Alchemy.makeCallback(
 *     "archive",
 *     Effect.fn(function* (payload: { key: string; body: string }) {
 *       yield* archive.put(payload.key, payload.body);
 *     }),
 *   );
 *   return {
 *     save: Effect.fn(function* (id: string, body: string) {
 *       yield* state.storage.transaction(
 *         Effect.gen(function* () {
 *           yield* state.storage.put(id, body);
 *           yield* onArchive.schedule(id, {
 *             after: "30 seconds",
 *             payload: { key: id, body },
 *           });
 *         }),
 *       );
 *     }),
 *   };
 * });
 * ```
 *
 * Callbacks receive JSON-serializable payloads and deliver at least once, so
 * external writes must be idempotent. A recovery wake is persisted before each
 * attempt. Failures use exponential backoff with a 30-second initial delay and
 * park after eight attempts without progress, retaining work for hourly recovery.
 * Configure these with the third argument, `{ retry: { delay: "1 second",
 * maxAttempts: 8, parkedDelay: "1 hour" } }`. The retry floor is one second;
 * parked retries are at least one hour apart. Scheduling the same callback name
 * and ID replaces the pending job; `onArchive.cancel(id)` cancels it. Retain
 * handlers for old callback names while their jobs are pending. Each native
 * alarm processes up to 100 due jobs; direct `setAlarm`/`deleteAlarm` calls
 * bypass the scheduler's coordination.
 * Leave native alarm retries enabled when aborting an instance. Passing
 * `{ retryAlarm: false }` removes the automatic-recovery guarantee: Cloudflare
 * can suppress a replacement wake even after its timestamp is persisted. Jobs
 * remain stored, but may need an explicitly rearmed native alarm.
 *
 * Self-rescheduling inherits the invocation's budget, even when cancelling or
 * changing IDs. Commit application state and an increasing `progress` cursor
 * in the same storage transaction to reset that budget. Replayed external
 * cursors cannot replace newer work; an external schedule without a cursor
 * explicitly starts a fresh budget. Detached fibers cannot mutate callbacks
 * after their invocation ends.
 *
 * **Example:** Inspect and recover a parked job from an incoming request
 * ```typescript
 * const status = yield* onArchive.getStatus("revision-42");
 * if (status?.parked) {
 *   yield* onArchive.schedule("revision-42", {
 *     after: 0,
 *     payload: { key: "42.txt", body: "hello" },
 *   });
 * }
 * ```
 *
 * Status includes the original `scheduledAt`, separate `retryAt`, attempt count,
 * parked flag, and latest progress cursor without decoding the payload. Parking
 * emits a warning without job identifiers or payloads. Status remains durable
 * across instance reconstruction.
 *
 * The scheduler migrates its unversioned and version-one SQLite schemas to
 * version two atomically, preserving existing events and callback deadlines.
 * Old events still use the explicit `alarm` handler below; their rows have no
 * callback name to infer. Both APIs coordinate the same native alarm. Unknown
 * newer schema versions fail closed.
 *
 * ### Scheduled Alarms
 * Each Durable Object can have a single alarm timestamp. Alchemy
 * layers a small SQLite-backed scheduler on top via
 * `Cloudflare.Workers.scheduleEvent` and `Cloudflare.Workers.processScheduledEvents`,
 * so you can register many named events with arbitrary payloads and
 * fire them from a single `alarm` handler.
 *
 * **Example:** Scheduling and processing events
 * ```typescript
 * // schedule from a request or message handler
 * yield* Cloudflare.Workers.scheduleEvent(
 *   "reminder-1",
 *   new Date(Date.now() + 60_000),
 *   { message: "your meeting starts in a minute" },
 * );
 *
 * return {
 *   alarm: () =>
 *     Effect.gen(function* () {
 *       const fired = yield* Cloudflare.Workers.processScheduledEvents;
 *       for (const event of fired) {
 *         const payload = event.payload as { message: string };
 *         // dispatch / broadcast / persist...
 *       }
 *     }),
 * };
 * ```
 *
 * ### Aborting a Durable Object
 * `state.abort(reason?, options?)` forcibly resets the isolate. By
 * default an in-progress alarm retries after the reset. Pass
 * `{ retryAlarm: false }` when the alarm should stop instead — for
 * example an alarm that deletes storage so the constructor does not
 * recreate it.
 *
 * **Example:** Stop alarm retries after cleanup
 * ```typescript
 * export class CleanupTask extends Cloudflare.DurableObject<CleanupTask>()(
 *   "CleanupTask",
 *   Effect.gen(function* () {
 *     const state = yield* Cloudflare.DurableObjectState;
 *
 *     return Effect.gen(function* () {
 *       // This won't be re-run after the alarm is aborted
 *       yield* state.storage.sql.exec(`
 *         CREATE TABLE IF NOT EXISTS foo (
 *           id INTEGER PRIMARY KEY
 *         )
 *       `);
 *
 *       return {
 *         alarm: () =>
 *           Effect.gen(function* () {
 *             yield* state.storage.sql.exec("DROP TABLE foo");
 *             yield* state.abort("Cleanup complete", { retryAlarm: false });
 *           }),
 *       };
 *     });
 *   }),
 * ) {}
 * ```
 *
 * ### Using from a Worker
 * Yield the DO class in your Worker's init phase to get a namespace
 * handle. Call `getByName` or `getById` to get a typed stub, then
 * call any RPC method or forward an HTTP request with `fetch`.
 *
 * **Example:** Calling RPC methods
 * ```typescript
 * // init
 * const counters = yield* Counter;
 *
 * return {
 *   fetch: Effect.gen(function* () {
 *     const counter = counters.getByName("user-123");
 *     yield* counter.increment();
 *     const value = yield* counter.get();
 *     return HttpServerResponse.text(String(value));
 *   }),
 * };
 * ```
 *
 * **Example:** Forwarding an HTTP request
 * ```typescript
 * // init
 * const rooms = yield* Room;
 *
 * return {
 *   fetch: Effect.gen(function* () {
 *     const request = yield* HttpServerRequest;
 *     const room = rooms.getByName(roomId);
 *     return yield* room.fetch(request);
 *   }),
 * };
 * ```
 *
 * ### Binding in an Async Worker
 * When using an Async Worker (plain `async fetch` handler, no Effect
 * runtime), declare Durable Objects in the `bindings` prop of the
 * Worker resource. Pass a `DurableObject` reference with a
 * `className` matching the exported `DurableObject` subclass in your
 * worker source file. If `className` is omitted, it defaults to the
 * namespace name. Use `Cloudflare.InferEnv` to get a fully typed
 * `env` object that includes the namespace.
 *
 * **Example:** Declaring a DO binding in the stack
 * ```typescript
 * // alchemy.run.ts
 * import type { Counter } from "./src/worker.ts";
 *
 * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
 *
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   bindings: {
 *     Counter: Cloudflare.DurableObject<Counter>("Counter"),
 *   },
 * });
 * ```
 *
 * **Example:** Using the DO from a plain async handler
 * ```typescript
 * // src/worker.ts
 * import { DurableObject } from "cloudflare:workers";
 * import type { WorkerEnv } from "../alchemy.run.ts";
 *
 * export default {
 *   async fetch(request: Request, env: WorkerEnv) {
 *     const counter = env.Counter.getByName("my-counter");
 *     const count = await counter.increment();
 *     return new Response(JSON.stringify({ count }));
 *   },
 * };
 *
 * export class Counter extends DurableObject {
 *   private counter = 0;
 *   async increment() {
 *     return ++this.counter;
 *   }
 * }
 * ```
 *
 * ### Cross-Script Binding in an Async Worker
 * Async Workers can also bind to a Durable Object hosted by another
 * Worker script. The host Worker declares and exports the DO class. The
 * consumer Worker declares a `DurableObject` with `scriptName`
 * set to the host Worker's script name.
 *
 * Cross-script async bindings are references only: the consumer uploads
 * the binding metadata, but Alchemy does not drive class migrations for
 * the foreign class. Deploy the host first so Cloudflare can verify that
 * the target script exports the requested class.
 *
 * **Example:** Host Worker owns the Durable Object class
 * ```typescript
 * const host = yield* Cloudflare.Worker("Host", {
 *   main: "./src/host.ts",
 *   bindings: {
 *     Counter: Cloudflare.DurableObject<Counter>("Counter"),
 *   },
 * });
 * ```
 *
 * **Example:** Consumer Worker binds to the host script
 * ```typescript
 * const consumer = yield* Cloudflare.Worker("Consumer", {
 *   main: "./src/consumer.ts",
 *   bindings: {
 *     Counter: Cloudflare.DurableObject<Counter>("Counter", {
 *       scriptName: host.workerName,
 *     }),
 *   },
 * });
 * ```
 *
 * **Example:** Binding to a different exported class name
 * ```typescript
 * const consumer = yield* Cloudflare.Worker("Consumer", {
 *   main: "./src/consumer.ts",
 *   bindings: {
 *     Counter: Cloudflare.DurableObject<Counter>("Counter", {
 *       className: "CounterV2",
 *       scriptName: host.workerName,
 *     }),
 *   },
 * });
 * ```
 *
 * ### Container-Backed Durable Objects in an Async Worker
 * A container-backed class is declared by binding a `Cloudflare.Container`
 * directly in the async Worker's `env` — the Container *is* the Durable
 * Object binding plus its ContainerApplication. See the Async Workers
 * section on {@link Container} for the full walkthrough.
 *
 * **Example:** A Container binding declares the container-backed class
 * ```typescript
 * // `Sandbox` is the container-backed DO class exported by the worker
 * // script (extends `@cloudflare/containers`' `Container`).
 * import type { Sandbox } from "./src/worker.ts";
 *
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   env: {
 *     Sandbox: Cloudflare.Container<Sandbox>("Sandbox", {
 *       image: "docker.io/cloudflare/sandbox:0.1.3",
 *     }),
 *   },
 * });
 * ```
 *
 * ### Native Containers in an Async Worker
 * A plain Durable Object class can start Durable Object-managed Containers
 * (`schedulingPolicy: "durable_object"`). List them in its binding's
 * `containers`: each adds its image to the class's container application,
 * keyed by the Container's id in `ctx.container.images`. A Container may be
 * shared by several classes.
 *
 * **Example:** Two classes, one shared image
 * ```typescript
 * const Node = Cloudflare.Container("Node", {
 *   schedulingPolicy: "durable_object",
 *   image: "node:24-slim",
 * });
 * const Python = Cloudflare.Container("Python", {
 *   schedulingPolicy: "durable_object",
 *   image: "python:3.13-slim",
 * });
 * const Rust = Cloudflare.Container("Rust", {
 *   schedulingPolicy: "durable_object",
 *   image: "rust:1.90-slim",
 * });
 *
 * export const Worker = Cloudflare.Worker("App", {
 *   main: "./src/worker.ts",
 *   env: {
 *     AGENT: Cloudflare.DurableObject("Agent", { containers: [Node, Python] }),
 *     REVIEWER: Cloudflare.DurableObject("Reviewer", { containers: [Node, Rust] }),
 *   },
 * });
 * ```
 *
 * **Example:** Starting a Container's image from the class
 * ```typescript
 * // src/worker.ts
 * export class Agent extends DurableObject {
 *   async run(cmd: string[]) {
 *     const container = this.ctx.container!;
 *     if (!container.running) {
 *       container.start({
 *         image: container.images.Node,
 *         entrypoint: ["sleep", "infinity"],
 *         enableInternet: false,
 *       });
 *     }
 *     return (await container.exec(cmd)).output();
 *   }
 * }
 * ```
 *
 * ### Moving a Class Between Workers
 * A Durable Object class can move from one Worker to another with its
 * data intact. The move is always **declared** — a class that disappears
 * from one worker and appears on another is otherwise ambiguous between
 * "transfer the data" and "delete it, start fresh", so Alchemy never
 * guesses (removing a DO deletes it; that is the default). Declare
 * `transferredFrom` on the Durable Object at its **new host**, naming the
 * former host, and the new host's deploy moves the namespace with its
 * data (Cloudflare's `expecting-transfer` / `transferred` exports
 * entries). The former host's deploy converges on its own — nothing is
 * deleted for a class that moved away.
 *
 * Each `transferredFrom` entry is either the former host's Worker
 * **logical id** (same stack + stage, resolved via alchemy's ownership
 * tags) or its **physical script name** (required for cross-stack moves).
 * When no listed host holds the namespace — a fresh stage, or the
 * transfer already completed — the declaration is inert, so it is safe to
 * leave in place indefinitely.
 *
 * **Example:** Move a class from WorkerB to WorkerA
 * ```typescript
 * // BEFORE: worker-b hosts the class
 * const b = yield* Cloudflare.Worker("WorkerB", {
 *   main: "./src/worker-b.ts", // exports MyDOClass
 *   bindings: {
 *     MyDO: Cloudflare.DurableObject("MyDO", { className: "MyDOClass" }),
 *   },
 * });
 *
 * // AFTER: worker-a hosts it and declares where it came from;
 * // worker-b keeps a cross-script reference.
 * const a = yield* Cloudflare.Worker("WorkerA", {
 *   main: "./src/worker-a.ts", // now exports MyDOClass
 *   bindings: {
 *     MyDO: Cloudflare.DurableObject("MyDO", {
 *       className: "MyDOClass",
 *       transferredFrom: "WorkerB", // logical id (or its script name)
 *     }),
 *   },
 * });
 * const b = yield* Cloudflare.Worker("WorkerB", {
 *   main: "./src/worker-b.ts", // no longer exports MyDOClass
 *   bindings: {
 *     MyDO: Cloudflare.DurableObject("MyDO", {
 *       className: "MyDOClass",
 *       scriptName: a.workerName,
 *     }),
 *   },
 * });
 * ```
 *
 * Forgetting the declaration is safe: when the former host still
 * references the class cross-script, its deploy fails before any upload
 * with `DurableObjectTransferRequired`, telling you exactly what to
 * declare — data is never silently destroyed or forked.
 *
 * **Example:** Chained moves keep the host history
 * ```typescript
 * // The class moved WorkerB → WorkerA last release and WorkerA →
 * // WorkerC this release. Keep the full history so a stage that lagged
 * // behind (or skipped the intermediate release) still transfers from
 * // wherever its namespace currently lives.
 * Cloudflare.DurableObject("MyDO", {
 *   className: "MyDOClass",
 *   transferredFrom: ["WorkerB", "WorkerA"],
 * })
 * ```
 *
 * Two rules for multi-worker migrations:
 *
 * - **Pure moves (the former host drops the DO entirely, keeping no
 *   cross-script reference) must be two deploys**: first add the class to
 *   the new host with `transferredFrom` and deploy; then remove it from
 *   the former host and deploy. In a single deploy nothing orders the
 *   transfer before the former host's delete.
 * - **Cross-stack moves deploy the new host's stack first**, naming the
 *   former host by physical script name; the former host's stack deploys
 *   after and converges.
 *
 * ### Adopting an Existing Durable Object
 * When you adopt a Worker that already exists on Cloudflare — created
 * outside Alchemy via Wrangler, the dashboard, or the raw API — its
 * Durable Object classes are adopted along with it. You opt in to the
 * takeover the same way you adopt any foreign resource: with
 * `adopt(true)` (or the `--adopt` CLI flag), since `Worker.read` reports
 * a worker with no Alchemy ownership tags as `Unowned`.
 *
 * Alchemy normally tracks which class backs each binding through an
 * `alchemy:dos:` metadata tag it writes on the script (mapping each
 * binding's logical id to its class name). A
 * foreign worker has no such tag, so on the **adopting deploy** Alchemy
 * falls back to matching your binding to the live class **by binding
 * name**. The class is then reused in place — not recreated — so
 * Cloudflare's migration engine doesn't reject the upload for creating a
 * class that already exists.
 *
 * The consequence is a one-time constraint: **on the adopting deploy the
 * binding's `className` must match the class that already exists on the
 * worker.** You cannot rename the class in the same deploy that adopts
 * it. Once the deploy completes, Alchemy owns the worker and has written
 * the `alchemy:dos:` tag, so subsequent renames are driven by logical id
 * and work normally.
 *
 * **Example:** Adopting a worker whose `Counter` class already exists
 * ```typescript
 * // The worker + `Counter` class were created outside Alchemy.
 * // `className` must match the existing class on this first deploy.
 * const worker = yield* Cloudflare.Worker("Worker", {
 *   name: "existing-worker",
 *   main: "./src/worker.ts",
 *   bindings: {
 *     Counter: Cloudflare.DurableObject<Counter>("Counter"),
 *   },
 * }).pipe(adopt(true));
 * ```
 *
 * **Example:** Renaming the class — only after adoption
 * ```typescript
 * // A SECOND deploy, after the one above. Alchemy now owns the worker
 * // and maps the binding by logical id, so the class can be renamed.
 * const worker = yield* Cloudflare.Worker("Worker", {
 *   name: "existing-worker",
 *   main: "./src/worker.ts",
 *   bindings: {
 *     Counter: Cloudflare.DurableObject<Counter>("Counter", {
 *       className: "CounterV2",
 *     }),
 *   },
 * });
 * ```
 *
 * @resource
 * @product Workers
 * @category Workers & Compute
 */
export const DurableObject: DurableObjectClass = taggedFunction(
  DurableObjectScope,
  function (
    ...args:
      | []
      | [
          name: string,
          props?: DurableObjectProps,
          // phantom argument
          isClassForm?: true,
        ]
      | [
          name: string,
          impl: Effect.Effect<Effect.Effect<DurableObject<any>, never, DurableObjectState>>,
          // phantom argument
          isClassForm?: true,
        ]
  ) {
    if (args.length === 0) {
      return (name: string, propsOrImpl?: any) =>
        // @ts-expect-error
        DurableObject(name, propsOrImpl, true);
    }
    const namespace = args[0];
    const isClassForm = args[2] === true;
    const propsOrImpl = args[1];
    const tag = Context.Service(namespace);

    const binding = (
      scriptName?: Input<string>,
      transferredFrom?: DurableObjectTransferSource | DurableObjectTransferSource[],
      errors?: ReadonlyArray<RpcErrorClass>,
    ) =>
      Effect.gen(function* () {
        const worker = yield* Worker;

        yield* worker.bind`${namespace}`({
          bindings: [
            {
              type: "durable_object_namespace",
              name: namespace,
              className: namespace,
              scriptName,
              transferredFrom: normalizeTransferredFrom(transferredFrom),
            },
          ],
        });

        const binding = yield* Effect.all([WorkerEnvironment, ALCHEMY_PHASE]).pipe(
          Effect.flatMap(([env, phase]) => {
            if (env === undefined || phase === "plan") {
              // should be fine to return undefined here (it is only undefined at plantime)
              return Effect.undefined;
            }
            const ns = env[namespace];
            if (!ns) {
              return Effect.die(new Error(`DurableObject '${namespace}' not found`));
            } else if (typeof ns.getByName === "function") {
              return Effect.succeed(ns);
            } else {
              return Effect.die(new Error(`DurableObject '${namespace}' is not a DurableObject`));
            }
          }),
        );

        // `undefined` at plan time; every method is only called at runtime.
        // A function because `jurisdiction` wraps the sub-namespace it returns.
        // The return annotation checks the value against the interface, so a
        // method missing here is a compile error.
        // Without a `scriptName` the class is hosted by this Worker, so its
        // `DurableObjectBridge` ships in this bundle and strips the trace
        // context a stub appends. A class in another script may be plain JS
        // or an older deploy, so its calls carry only the caller's arguments.
        const stubOptions = { errors, traceContext: scriptName === undefined };
        const makeNamespace = (ns: cf.DurableObjectNamespace | undefined): DurableObject<any> => ({
          // `kind` + `scriptName`/`transferredFrom` let a namespace passed in
          // a Worker's `env` bind as the `durable_object_namespace` it is.
          kind: TypeId,
          scriptName,
          transferredFrom,
          Type: TypeId,
          LogicalId: namespace,
          name: namespace,
          namespaceId: worker.durableObjectNamespaces.pipe(
            Output.map((durableObjectNamespaces) => durableObjectNamespaces?.[namespace]),
          ),
          getByName: (name: string, options?: DurableObjectGetDurableObjectOptions) =>
            makeRpcStub(ns!.getByName(name, options), stubOptions),
          newUniqueId: () => ns!.newUniqueId(),
          idFromName: (name: string) => ns!.idFromName(name),
          idFromString: (id: string) => ns!.idFromString(id),
          get: (id: DurableObjectId, options?: DurableObjectGetDurableObjectOptions) =>
            makeRpcStub(ns!.get(id, options), stubOptions),
          jurisdiction: (jurisdiction: DurableObjectJurisdiction) =>
            makeNamespace(restrictToJurisdiction(ns, jurisdiction)),
        });

        return makeNamespace(binding);
      });

    // Class-form declarations (`DurableObject<Self>()("Name", props?)`) can
    // carry `transferredFrom` so the host's local binding drives a
    // data-preserving transfer migration.
    const classProps =
      isClassForm && !Effect.isEffect(propsOrImpl)
        ? (propsOrImpl as Pick<DurableObjectProps, "transferredFrom" | "errors"> | undefined)
        : undefined;

    const make = Effect.fn(function* (
      impl: Effect.Effect<Effect.Effect<DurableObjectShape>, never, DurableObjectState>,
    ) {
      // Register the local DO binding (no `scriptName`) and obtain the
      // namespace handle. We provide this same handle as
      // `DurableObjectScope` to the user's constructor effect
      // and also return it so a `Layer.effect(tag, make(impl))` Layer
      // resolves the tag to a concrete namespace value.
      const self = yield* binding(undefined, classProps?.transferredFrom, classProps?.errors);
      const phase = yield* ALCHEMY_PHASE;
      const constructor = impl.pipe(Effect.provideService(DurableObjectScope, self as any));
      if (phase === "plan") {
        // during plan time, we evaluate the constructor with a mock DurableObjectState
        // to trigger discovery of bindings
        yield* constructor.pipe(
          Effect.provide(
            Layer.succeed(
              DurableObjectState,
              // mock during plan time
              fromDurableObjectState({ storage: {} } as any),
            ),
          ),
          Effect.asVoid,
        );
      }
      yield* (yield* Worker).export(namespace, {
        kind: "durableObject",
        // initialize the object's constructor (apply infra dependencies)
        constructor,
        // grab the object's infra dependencies so we can apply them when calling the instance's methods
        services: yield* Effect.context<Effect.Services<typeof impl>>(),
      } satisfies DurableObjectExport);
      return self;
    });

    if (!isClassForm && !Effect.isEffect(args[1])) {
      // this is an in-line, async only DO (no implementation, props only)
      return {
        kind: TypeId,
        name: namespace,
        className: (args[1] as DurableObjectProps)?.className || namespace,
        scriptName: (args[1] as DurableObjectProps)?.scriptName,
        transferredFrom: (args[1] as DurableObjectProps)?.transferredFrom,
        storage: (args[1] as DurableObjectProps)?.storage,
        containers: (args[1] as DurableObjectBindingProps)?.containers,
      };
    } else if (Effect.isEffect(propsOrImpl)) {
      // inline Effect DO
      return effectClass(
        Effect.tap(binding(), () =>
          make(propsOrImpl as any).pipe(
            Effect.provideService(
              DurableObjectState,
              fromDurableObjectState(
                // everything is lazy, so this should build a proper mock
                {
                  storage: {},
                } as any,
              ),
            ),
          ),
        ),
      );
    } else {
      // Tagged Effect DO. Yielding the class resolves the `tag`, which
      // forces the `CounterLive` Layer (built by `Counter.make(impl)`) to
      // run so `worker.export(namespace, …)` is invoked — without this,
      // the class would never be registered with the Worker's exports
      // map and the deployed bundle would have no DO class for
      // Cloudflare to instantiate.
      return class extends effectClass(tag as Effect.Effect<any, never, any>) {
        static make = <Req = never>(
          impl: Effect.Effect<Effect.Effect<DurableObjectShape, never, DurableObjectState | Req>>,
        ) => Layer.effect(tag, make(impl as any));

        static from = (worker: string | Worker | Effect.Effect<Worker, any, any>) => {
          // Resolve `worker` to an Effect that yields the actual Worker
          // instance (or a plain string scriptName).
          //
          // A class produced by `Cloudflare.Worker<T>()(...)` exposes
          // `asEffect()` returning the Self tag — yielding that tag
          // resolves to the live Worker instance whose `workerName`
          // is a `PropExpr`, which is what we need so the engine can:
          //   1) Track WorkerB → WorkerA as a binding-level upstream
          //      dependency (so WorkerA reconciles first).
          //   2) Persist `scriptName` as a real value (not `undefined`)
          //      on the cross-script binding so the migration code in
          //      Worker.ts can detect it and skip emitting class
          //      migrations for the foreign class.
          // Plain Effects and string literals are passed through as-is.
          const resolved: Effect.Effect<Worker | string, any, any> =
            typeof worker === "string" ? Effect.succeed(worker) : asEffect(worker);

          return resolved.pipe(
            Effect.flatMap((w) =>
              binding(typeof w === "string" ? w : w.workerName, undefined, classProps?.errors),
            ),
          );
        };
      };
    }
  },
) as any;

export type DurableObjectStub<Shape> = {
  // TODO(sam): do we need to transform? hopefully not
  [key in keyof Shape]: Shape[key];
} & {
  fetch: (
    request: HttpServerRequest.HttpServerRequest,
  ) => Effect.Effect<HttpServerResponse.HttpServerResponse, HttpServerError, never>;
};