feat(cloudflare/workers): declare Durable Object class transfers between workers

[sam-goodwin]

Moving a Durable Object class to another Worker is now supported via Cloudflare's data-preserving transferred_classes migration. Moves are always declared — a class deleted on one worker and created on another is ambiguous between "move the data" and "delete it, start fresh" (the same reason Terraform requires moved blocks), so Alchemy never guesses. The new host names where the class came from:

// 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 (same stack) or script name
    }),
  },
});
const b = yield* Cloudflare.Worker("WorkerB", {
  main: "./src/worker-b.ts",
  bindings: {
    MyDO: Cloudflare.DurableObject("MyDO", {
      className: "MyDOClass",
      scriptName: a.workerName,
    }),
  },
});

transferredFrom semantics

• Each entry names a former host by its Worker logical id in the same stack + stage (resolved via the alchemy:id/alchemy:stack/alchemy:stage ownership tags among scripts observed to currently host the class) or by its physical script name (required for cross-stack moves).

• Besides strings, entries accept the Worker class or resource itself, or a thunk for forward references and import cycles:

  Cloudflare.DurableObject("Counter", { transferredFrom: b })            // resource
  Cloudflare.DurableObject<C>()("Counter", { transferredFrom: () => WorkerA }) // class via thunk

  References are normalized at plan time to the worker's logical id — never its Output — since consuming the former host's Output would add a new-host→former-host dependency edge and invert the deploy order the transfer requires. A same-stack workerName Output is likewise reduced to its source resource's logical id via provenance.

• It's a host history: transferredFrom: ["WorkerB", "WorkerA"] transfers from whichever listed host currently holds the namespace, so stages that lag behind or skipped an intermediate release still converge. When none does (fresh stage, transfer already completed) the declaration is inert — safe to keep in code indefinitely.

• Multiple matching sources (e.g. an orphaned script left by a name change) fail with the typed AmbiguousDurableObjectTransfer rather than guessing whose data to move.

Safety interlocks

• An undeclared move — the former host re-binds a class it still hosts as a cross-script reference — fails before any upload with the typed DurableObjectTransferRequired, naming the exact declaration to add. This replaces Cloudflare's opaque deleted_classes-vs-binding rejection from the issue; data is never silently destroyed or forked.
• The former host's deploy validates deleted_classes against observed namespace ownership (with a short bounded re-observation for listing lag): a class that transferred away is skipped, so the former host converges on its own.
• Transfer-destination classes are excluded from the precreate placeholder (Cloudflare forbids pre-creating a transfer's destination class).
• Pure moves (former host drops the DO entirely, no cross-script reference) are two deploys — add to the new host with transferredFrom and deploy, then remove from the former host — since nothing orders a single deploy's transfer before the former host's delete. Documented on the resource.

Verified live in DurableObjectNamespace.test.ts: a move declared by logical id preserves data across the transfer and is inert on redeploy; a move declared by physical script name via a thunk (the cross-stack shape) transfers as well; the documented two-deploy pure move driven by a resource reference transfers and the former host's DO removal converges without a delete; an undeclared move fails with DurableObjectTransferRequired.

Closes #799

🤖 Generated with Claude Code

[alchemy-version-bot]

Install the packages built from this commit:

alchemy

bun add alchemy@https://pkg.ing/alchemy/21b9a8c

@alchemy.run/better-auth

bun add @alchemy.run/better-auth@https://pkg.ing/@alchemy.run/better-auth/21b9a8c

@alchemy.run/pr-package

bun add @alchemy.run/pr-package@https://pkg.ing/@alchemy.run/pr-package/21b9a8c