alchemy 2.0.0-beta.68 → 2.0.0-beta.69

package/src/Cloudflare/Access/Group.ts

@@ -24,6 +24,20 @@ import type { Providers } from "../Providers.ts";
 export type GroupRule =
   zeroTrust.CreateAccessGroupForAccountRequest["include"][number];
 
+/**
+ * One arm of the exclude-side rule union, and its require-side twin.
+ * Cloudflare's spec types the exclude/require rule lists separately from
+ * include — a few rule kinds (e.g. the GitHub-organization rule) carry the
+ * raw wire shape there — so these props use the SDK's own unions rather
+ * than reusing {@link GroupRule}.
+ */
+export type GroupExcludeRule = NonNullable<
+  zeroTrust.CreateAccessGroupForAccountRequest["exclude"]
+>[number];
+export type GroupRequireRule = NonNullable<
+  zeroTrust.CreateAccessGroupForAccountRequest["require"]
+>[number];
+
 export type GroupProps = {
   /**
    * Display name for the group. Used as a stable identifier so the provider
@@ -42,12 +56,12 @@ export type GroupProps = {
    * Rules combined with logical NOT. A user matching any Exclude rule does
    * not match the group, even if they satisfied an Include rule.
    */
-  exclude?: GroupRule[];
+  exclude?: GroupExcludeRule[];
   /**
    * Rules combined with logical AND. A user must satisfy every Require rule
    * in addition to an Include rule.
    */
-  require?: GroupRule[];
+  require?: GroupRequireRule[];
   /**
    * Whether this is the default group for the Zero Trust organization.
    *

package/src/Cloudflare/Access/Policy.ts

@@ -21,6 +21,20 @@ import type { Providers } from "../Providers.ts";
  */
 export type PolicyRule = zeroTrust.CreateAccessPolicyRequest["include"][number];
 
+/**
+ * One arm of the exclude-side rule union, and its require-side twin.
+ * Cloudflare's spec types the exclude/require rule lists separately from
+ * include — a few rule kinds (e.g. the GitHub-organization rule) carry the
+ * raw wire shape there — so these props use the SDK's own unions rather
+ * than reusing {@link PolicyRule}.
+ */
+export type PolicyExcludeRule = NonNullable<
+  zeroTrust.CreateAccessPolicyRequest["exclude"]
+>[number];
+export type PolicyRequireRule = NonNullable<
+  zeroTrust.CreateAccessPolicyRequest["require"]
+>[number];
+
 /**
  * Decision Cloudflare Access takes when a request matches this policy.
  *
@@ -61,12 +75,12 @@ export type PolicyProps = {
    * Rules combined with logical NOT. A request matching any exclude rule is
    * rejected by the policy even if it satisfied an include rule.
    */
-  exclude?: Policy.RuleGroup[];
+  exclude?: PolicyExcludeRule[];
   /**
    * Rules combined with logical AND. A request must satisfy every require
    * rule in addition to an include rule.
    */
-  require?: Policy.RuleGroup[];
+  require?: PolicyRequireRule[];
   /**
    * Duration of issued session tokens. Format: `300ms`, `2h45m`, etc. When
    * unset, applications using this policy fall back to their own configured

package/src/Cloudflare/Website/StaticSite.ts

@@ -6,6 +6,7 @@ import * as Command from "../../Command/index.ts";
 import type { Input, InputProps } from "../../Input.ts";
 import * as Namespace from "../../Namespace.ts";
 import * as Output from "../../Output.ts";
+import { renamedFrom } from "../../Rename.ts";
 import {
   effectClass,
   isYieldableEffectLike,
@@ -297,6 +298,12 @@ const makeStaticSite = <
     // Pure-static sites (neither `main` nor `script`) deploy as
     // assets-only Workers: no script is uploaded and Cloudflare's asset
     // layer serves every request itself.
+    //
+    // The Worker's FQN was `<id>/Worker` before #1053 flattened it to
+    // `<id>`; `renamedFrom` migrates the pre-existing state row to the new
+    // FQN instead of letting the engine plan a create+delete replacement
+    // (a new physical name, a torn-down workers.dev URL, and a
+    // custom-domain handover that crashes the deploy).
     return yield* Worker<Bindings, WorkerAssetsConfig, Req>(id, {
       ...props,
       assets: build
@@ -311,7 +318,7 @@ const makeStaticSite = <
       // state with a stub Attributes shape.
       dev: dev ? { mode: "external", url: dev.url } : undefined,
       script: props.script,
-    });
+    }).pipe(renamedFrom(`${id}/Worker`));
   });
 
 /**

package/src/Plan.ts

@@ -117,9 +117,31 @@ export interface BaseNode<
   bindings: BindingNode<R["Binding"]>[];
 }
 
+/**
+ * Base for the apply-side nodes (create/update/replace/noop) — the nodes a
+ * DECLARED resource plans to. Only these can carry a rename: a `Delete`
+ * node is an orphaned row with no declaration, so nothing can claim to
+ * have renamed it (migrating rows are excluded from the orphan pass
+ * entirely).
+ */
+export interface ApplyNodeBase<
+  R extends ResourceLike<string> = ResourceLike<string>,
+> extends BaseNode<R> {
+  /**
+   * Set when this resource's persisted row was found under former FQNs
+   * (`renamedFrom(...)`) — the migration source (no row at the current FQN
+   * yet) and/or stale leftovers from interrupted migrations (same
+   * `instanceId` as the resource's row; a rename chain with repeated
+   * partial failures can leave several). Apply persists the move up-front,
+   * before any lifecycle operation runs: commit `state` at the current
+   * FQN, then delete every former row.
+   */
+  renamedFrom?: string[] | undefined;
+}
+
 export interface Create<
   R extends ResourceLike = ResourceLike,
-> extends BaseNode<R> {
+> extends ApplyNodeBase<R> {
   action: "create";
   props: R["Props"];
   state: CreatingResourceState | undefined;
@@ -127,7 +149,7 @@ export interface Create<
 
 export interface Update<
   R extends ResourceLike = ResourceLike,
-> extends BaseNode<R> {
+> extends ApplyNodeBase<R> {
   action: "update";
   /** True while this is the first reconcile after a cold adoption. */
   adopting?: boolean;
@@ -151,14 +173,14 @@ export interface Delete<
 
 export interface NoopUpdate<
   R extends ResourceLike = ResourceLike,
-> extends BaseNode<R> {
+> extends ApplyNodeBase<R> {
   action: "noop";
   state: CreatedResourceState | UpdatedResourceState;
 }
 
 export interface Replace<
   R extends ResourceLike = ResourceLike,
-> extends BaseNode<R> {
+> extends ApplyNodeBase<R> {
   action: "replace";
   props: any;
   deleteFirst: boolean;
@@ -344,6 +366,211 @@ export const make = <A>(
       { concurrency: "unbounded" },
     );
 
+    // Snapshot of every persisted row, keyed by FQN. The rename resolution
+    // below reads from this map instead of issuing per-FQN `state.get`s —
+    // every renamedFrom-decorated resource (each StaticSite carries one
+    // forever) would otherwise add two round-trips per resource to every
+    // plan against a remote state store. Plan is read-only, so the
+    // snapshot cannot go stale within this run.
+    const persistedRows = new Map(
+      resourceFqns.map((fqn, i) => [fqn, oldResources[i]]),
+    );
+
+    // ── FQN renames ──────────────────────────────────────────────────────
+    // Map every former FQN claimed via `renamedFrom(...)` to its claimant's
+    // current FQN. Two resources claiming the same former FQN is ambiguous
+    // and fatal. A former FQN MAY still be actively declared — that is the
+    // "old id reused by a new resource" case: the rename claim wins the
+    // row (it is an explicit user statement that the row was theirs), and
+    // the reusing resource plans a fresh create.
+    const formerFqnClaims = new Map<string, string>();
+    for (const resource of resources) {
+      for (const formerFqn of resource.FormerFqns ?? []) {
+        if (formerFqn === resource.FQN) continue;
+        const claimant = formerFqnClaims.get(formerFqn);
+        if (claimant !== undefined && claimant !== resource.FQN) {
+          return yield* Effect.die(
+            new Error(
+              `Resources '${claimant}' and '${resource.FQN}' both claim ` +
+                `former FQN '${formerFqn}' via renamedFrom(...). A former ` +
+                "FQN can migrate to exactly one resource — remove the " +
+                "decoration from one of them.",
+            ),
+          );
+        }
+        formerFqnClaims.set(formerFqn, resource.FQN);
+      }
+    }
+
+    // Resolve every rename migration up-front against the state snapshot,
+    // BEFORE any node is built — other resources' planning depends on the
+    // outcome (a resource declared at a former FQN whose row is migrating
+    // away must start from scratch).
+    //
+    // For each renamer, in former-id declaration order (most recent
+    // first):
+    //
+    // - `source` is the row that defines the resource's physical identity:
+    //   the row at its own FQN when present AND type-matching, otherwise
+    //   the first type-matching former row (→ `moved`).
+    // - every OTHER type-matching former row sharing `source.instanceId`
+    //   is a leftover from an interrupted migration (only migration copies
+    //   instanceIds) — collected for state-only cleanup.
+    // - former rows with a different instanceId belong to someone else and
+    //   are left to normal orphan handling; former rows with a different
+    //   resourceType (modulo registered type-aliases) can never be this
+    //   resource's row and are skipped entirely.
+    // - a FOREIGN-typed row at the renamer's own FQN blocks the migration
+    //   fatally: landing the migrated row there would silently abandon
+    //   that row's cloud resource.
+    const renameMigrations = new Map<
+      string,
+      { row: ResourceState; renamedFrom: string[]; moved: boolean }
+    >();
+    const migratedRowFqns = new Set<string>();
+
+    const resolveRenamer = Effect.fn(function* (resource: ResourceLike) {
+      const provider = Option.getOrUndefined(
+        yield* tryFindProviderByType(resource.Type),
+      );
+      const allowedTypes = new Set([
+        resource.Type,
+        ...(provider?.aliases ?? []),
+      ]);
+      const persisted = persistedRows.get(resource.FQN);
+      const persistedRow = isActionState(persisted)
+        ? undefined
+        : (persisted as ResourceState | undefined);
+      // A row at this resource's own FQN that a PREVIOUSLY RESOLVED
+      // renamer claimed (a same-deploy shift: A→B while B→C — C took the
+      // row at B) is moving away: it is not ours to keep and it does not
+      // block the migration landing here.
+      const rowTaken = migratedRowFqns.has(resource.FQN);
+      const ownRow =
+        !rowTaken &&
+        persistedRow !== undefined &&
+        allowedTypes.has(persistedRow.resourceType)
+          ? persistedRow
+          : undefined;
+
+      let source: ResourceState | undefined = ownRow;
+      let adopted: ResourceState | undefined = ownRow;
+      const renamedFrom: string[] = [];
+      for (const formerFqn of resource.FormerFqns!) {
+        if (formerFqnClaims.get(formerFqn) !== resource.FQN) continue;
+        // The same former id may be listed twice (or resolve identically);
+        // collect each former row once.
+        if (renamedFrom.includes(formerFqn)) continue;
+        const formerPersisted = persistedRows.get(formerFqn);
+        if (formerPersisted === undefined || isActionState(formerPersisted)) {
+          continue;
+        }
+        const formerRow = formerPersisted as ResourceState;
+        if (!allowedTypes.has(formerRow.resourceType)) continue;
+        if (source === undefined) {
+          source = formerRow;
+          adopted = {
+            ...formerRow,
+            fqn: resource.FQN,
+            logicalId: resource.LogicalId,
+            namespace: resource.Namespace,
+          } as ResourceState;
+          renamedFrom.push(formerFqn);
+        } else if (source.instanceId === formerRow.instanceId) {
+          renamedFrom.push(formerFqn);
+        }
+      }
+      if (renamedFrom.length === 0) return;
+      if (persistedRow !== undefined && ownRow === undefined && !rowTaken) {
+        return yield* Effect.die(
+          new Error(
+            `Cannot migrate '${renamedFrom[0]}' to '${resource.FQN}': a ` +
+              `state row of a different type ('${persistedRow.resourceType}') ` +
+              `already occupies '${resource.FQN}'. Migrating over it would ` +
+              "silently abandon that row's cloud resource. Delete or " +
+              "rename the conflicting resource first, then re-deploy.",
+          ),
+        );
+      }
+      renameMigrations.set(resource.FQN, {
+        row: adopted!,
+        renamedFrom,
+        moved: adopted !== ownRow,
+      });
+      for (const formerFqn of renamedFrom) migratedRowFqns.add(formerFqn);
+    });
+
+    // Resolve renamers in claim-dependency order: when resource R's OWN
+    // FQN is claimed as a former id by resource S (a same-deploy shift:
+    // A→B while B→C), S must resolve first — whether S takes R's row
+    // decides whether R still owns it, or falls back to ITS former rows.
+    // Iterate to fixpoint; anything left is a claim CYCLE (a swap: A⇄B),
+    // which cannot be persisted safely — the migrations would overwrite
+    // and delete each other's rows — and dies loudly.
+    let pendingRenamers = resources.filter((r) => r.FormerFqns?.length);
+    const resolvedRenamers = new Set<string>();
+    while (pendingRenamers.length > 0) {
+      const ready = pendingRenamers.filter((resource) => {
+        const claimant = formerFqnClaims.get(resource.FQN);
+        return claimant === undefined || resolvedRenamers.has(claimant);
+      });
+      if (ready.length === 0) {
+        return yield* Effect.die(
+          new Error(
+            `Rename cycle detected among [${pendingRenamers
+              .map((r) => `'${r.FQN}'`)
+              .join(
+                ", ",
+              )}]: their renamedFrom(...) declarations claim each other's ` +
+              "FQNs. Swapping ids in one deploy is not supported — rename " +
+              "through a temporary id across two deploys instead.",
+          ),
+        );
+      }
+      for (const resource of ready) {
+        yield* resolveRenamer(resource);
+        resolvedRenamers.add(resource.FQN);
+      }
+      pendingRenamers = pendingRenamers.filter(
+        (r) => !resolvedRenamers.has(r.FQN),
+      );
+    }
+
+    /**
+     * Fetch the persisted row for a declared resource, resolving renames
+     * (see the pre-computed `renameMigrations` above):
+     *
+     * - a renamer plans from its migrated row (`renamedFrom` rides onto
+     *   the plan node; apply persists the move before any lifecycle op)
+     * - a resource declared at a former FQN whose row is migrating away
+     *   starts from scratch — the row is NOT its state, whatever the FQN
+     *   says
+     */
+    const getPersistedRow = Effect.fn(function* (
+      resource: Pick<ResourceLike, "FQN">,
+    ) {
+      const migration = renameMigrations.get(resource.FQN);
+      if (migration !== undefined) {
+        return {
+          row: migration.row,
+          renamedFrom: migration.renamedFrom,
+          renameMoved: migration.moved,
+        };
+      }
+      const persisted = yield* state.get({
+        stack: stackName,
+        stage: stage,
+        fqn: resource.FQN,
+      });
+      const row = isActionState(persisted)
+        ? undefined
+        : (persisted as ResourceState | undefined);
+      if (row !== undefined && migratedRowFqns.has(resource.FQN)) {
+        return { row: undefined, renamedFrom: undefined, renameMoved: false };
+      }
+      return { row, renamedFrom: undefined, renameMoved: false };
+    });
+
     const resolvedResources: Record<string, Effect.Effect<any>> = {};
 
     const resolveResource = (
@@ -367,16 +594,10 @@ export const make = <A>(
               const props = materializeStableRefs(
                 yield* resolveInput(resource.Props),
               );
-              const persisted = yield* state.get({
-                stack: stackName,
-                stage: stage,
-                fqn: resource.FQN,
-              });
-              const oldState: ResourceState | undefined = isActionState(
-                persisted,
-              )
-                ? undefined
-                : (persisted as ResourceState | undefined);
+              // Falls back to the row at a former FQN (`renamedFrom`) so a
+              // renamed resource's stable attributes keep flowing to
+              // downstream diffs across the migration.
+              const { row: oldState } = yield* getPersistedRow(resource);
 
               if (!oldState || oldState.status === "creating") {
                 return resourceExpr;
@@ -865,17 +1086,18 @@ export const make = <A>(
             // `bindingOutputs`, not these plan-time shapes.
             const newBindings: ResourceBinding[] =
               materializeStableRefs(applyBindings);
-            const persisted = yield* state.get({
-              stack: stackName,
-              stage: stage,
-              fqn,
-            });
-            // A Task previously held this FQN. Treat as if there were no
-            // prior state — the Task's row will be reaped by `actionDeletions`
-            // below and the resource starts from scratch.
-            let oldState: ResourceState | undefined = isActionState(persisted)
-              ? undefined
-              : (persisted as ResourceState | undefined);
+            // The row is looked up at the resource's FQN with a fallback to
+            // its former FQNs (`renamedFrom`); a row found under a former
+            // FQN arrives here already remapped to the new identity, and
+            // `renamedFrom` rides onto the plan node so apply persists the
+            // move. (A Task previously holding this FQN is treated as no
+            // prior state — its row is reaped by `actionDeletions` below.)
+            const {
+              row: persistedRow,
+              renamedFrom,
+              renameMoved,
+            } = yield* getPersistedRow(resource);
+            let oldState: ResourceState | undefined = persistedRow;
 
             // Engine-level adoption. When there is no prior state, always
             // consult `provider.read` (if implemented) so the engine — not
@@ -925,8 +1147,20 @@ export const make = <A>(
             // SDK protocol layer. Resources whose props depend on
             // not-yet-created upstreams cannot themselves be pre-existing
             // — there's nothing to adopt.
+            // A resource declared at a former FQN whose row just migrated
+            // away is genuinely NEW by declaration — skip the probe. Its
+            // predecessor's physical resource still carries tags branded
+            // with THIS logical id (the migrated row's reconcile hasn't
+            // re-branded them yet), so a tag-based `read` would find it
+            // and silently adopt the very resource that was renamed away.
+            const reusesMigratedFqn = migratedRowFqns.has(fqn);
             let forceUpdateAfterAdoption = false;
-            if (oldState === undefined && provider.read && isResolved(news)) {
+            if (
+              oldState === undefined &&
+              provider.read &&
+              isResolved(news) &&
+              !reusesMigratedFqn
+            ) {
               const adoptInstanceId = yield* generateInstanceId();
               const readResult = yield* provider
                 .read({
@@ -1019,6 +1253,7 @@ export const make = <A>(
                 bindings: bindingDiffs,
                 downstream,
                 mode,
+                renamedFrom,
               }) as any as T;
 
             // Plan against the persisted state we have, not the ideal final state we
@@ -1159,8 +1394,16 @@ export const make = <A>(
                   // would noop and any drift between the existing cloud
                   // resource and `news` — including foreign-owned tags after a
                   // takeover — would persist).
+                  //
+                  // A row that just migrated from a former FQN (`renameMoved`)
+                  // gets the same treatment: its cloud resource is still
+                  // branded with the OLD logical id's tags, and if the old id
+                  // is being reused by a new resource, leaving them stale
+                  // would let the reuser's future adoption probes match the
+                  // wrong physical resource.
                   Effect.map((diff) =>
-                    forceUpdateAfterAdoption && diff.action === "noop"
+                    (forceUpdateAfterAdoption || renameMoved) &&
+                    diff.action === "noop"
                       ? ({ action: "update" } satisfies UpdateDiff)
                       : diff,
                   ),
@@ -1519,6 +1762,15 @@ export const make = <A>(
             if (isActionState(persisted)) return;
             const oldState = persisted as ResourceState | undefined;
             if (oldState) {
+              // A row being migrated by a rename (`renameMigrations`) is
+              // moving, not orphaned — apply drops it state-only after
+              // committing the migrated row at its new FQN. Rows at former
+              // FQNs that did NOT migrate (foreign type, different
+              // instanceId, unclaimed) are absent from this set and fall
+              // through to normal orphan deletion.
+              if (migratedRowFqns.has(fqn)) {
+                return;
+              }
               const { logicalId } = parseFqn(fqn);
               const resourceType = oldState.resourceType;
               // A "zombie" row references a type with no registered provider
@@ -1566,6 +1818,7 @@ export const make = <A>(
                     RemovalPolicy: oldState.removalPolicy,
                     Adopt: undefined,
                     Mode: oldState.providerMode,
+                    FormerFqns: undefined,
                     RuntimeContext: undefined!,
                     Providers: undefined,
                   } as ResourceLike,
@@ -1752,7 +2005,10 @@ export const printPlan = (plan: Plan): string => {
     const downstream = node.state?.downstream?.length
       ? ` → [${node.state?.downstream.join(", ")}]`
       : "";
-    lines.push(`│ [${symbol}] ${id} (${type})${downstream}`);
+    const renamed = node.renamedFrom?.length
+      ? ` (renamed from ${node.renamedFrom.join(", ")})`
+      : "";
+    lines.push(`│ [${symbol}] ${id} (${type})${downstream}${renamed}`);
   }
   if (resourceIds.length === 0) {
     lines.push("│ (none)");

package/src/Rename.ts

@@ -0,0 +1,135 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+
+/**
+ * A former id a resource was previously declared under:
+ *
+ * - a bare `string` resolves against the ambient namespace, exactly like
+ *   the resource's own `id` argument does
+ * - `{ fqn: "..." }` is absolute — the full FQN as persisted in state,
+ *   ignoring any surrounding namespace. Needed when a resource moved
+ *   BETWEEN namespaces (a relative id can only address the current
+ *   namespace's subtree).
+ */
+export type FormerId = string | { fqn: string };
+
+/**
+ * RenamePolicy carries the former ids a resource was previously declared
+ * under. It is captured from the ambient context at registration time (like
+ * `AdoptPolicy` / `RemovalPolicy`) and resolved against the same namespace
+ * as the resource's own id — see `ResourceLike.FormerFqns`.
+ */
+export class RenamePolicy extends Context.Service<
+  RenamePolicy,
+  readonly FormerId[]
+>()("RenamePolicy") {}
+
+/**
+ * Declare the logical id(s) this resource was previously registered under,
+ * so the engine migrates its persisted state row instead of planning a
+ * create+delete replacement when the id changes.
+ *
+ * ```ts
+ * // was: Bucket("Bucket") — the row migrates and the deploy plans a noop
+ * const bucket = yield* Bucket("Assets").pipe(renamedFrom("Bucket"));
+ * ```
+ *
+ * A bare string resolves against the ambient namespace, exactly like the
+ * resource's own `id`:
+ *
+ * ```ts
+ * // FQN `Site/Assets`, former FQN `Site/Bucket`
+ * yield* Bucket("Assets").pipe(
+ *   renamedFrom("Bucket"),
+ *   Namespace.push("Site"),
+ * );
+ * ```
+ *
+ * Moved between namespaces? Pass `{ fqn }` — the absolute FQN exactly as
+ * persisted in state, ignoring the ambient namespace:
+ *
+ * ```ts
+ * // former FQN `LegacySite/Assets` (NOT `NewSite/LegacySite/Assets`)
+ * yield* Bucket("Assets").pipe(
+ *   renamedFrom({ fqn: "LegacySite/Assets" }),
+ *   Namespace.push("NewSite"),
+ * );
+ * ```
+ *
+ * Renamed more than once? List every former id, most recent first — the
+ * planner checks them in order and migrates from the first matching row:
+ *
+ * ```ts
+ * // rename history: Bucket → StaticAssets → Assets
+ * yield* Bucket("Assets").pipe(renamedFrom("StaticAssets", "Bucket"));
+ * ```
+ *
+ * Migration semantics, by state-row shape (see Plan's rename resolution;
+ * `new` = the row at the resource's FQN, `old` = a row at a former FQN):
+ *
+ * ```text
+ * new                     old                     → outcome
+ * ──────────────────────────────────────────────────────────────────────
+ * —                       row                     → migrate: the old row
+ *                                                   IS the resource's
+ *                                                   state; apply moves it
+ *                                                   before any lifecycle
+ *                                                   op, and ONE update
+ *                                                   reconcile re-brands
+ *                                                   the physical resource
+ *                                                   under the new logical
+ *                                                   id (never a create)
+ * row, same instanceId    row                     → interrupted
+ *                                                   migration: leftovers
+ *                                                   dropped state-only —
+ *                                                   ALL of them in one
+ *                                                   apply — the physical
+ *                                                   resource is never
+ *                                                   touched
+ * row, diff instanceId    row                     → someone else's row (a
+ *                                                   resource reused the
+ *                                                   old name after the
+ *                                                   rename shipped):
+ *                                                   ignored, normal
+ *                                                   orphan handling
+ * row, diff resourceType  row                     → FATAL: migrating over
+ *                                                   the foreign-typed row
+ *                                                   would silently
+ *                                                   abandon its cloud
+ *                                                   resource — resolve
+ *                                                   the collision first
+ * any                     row, diff resourceType  → never migrated —
+ *                                                   cannot be this
+ *                                                   resource's row,
+ *                                                   whatever its FQN says
+ * ```
+ *
+ * The old id can be REUSED by a new resource in the same deploy — the
+ * rename claim wins the row (it is an explicit statement that the row was
+ * the renamer's), and the reusing resource is created fresh:
+ *
+ * ```ts
+ * // `Assets` keeps the physical resource previously known as `Bucket`;
+ * // this `Bucket` is a brand-new one.
+ * yield* Bucket("Assets").pipe(renamedFrom("Bucket"));
+ * yield* Bucket("Bucket");
+ * ```
+ *
+ * Renames may SHIFT through each other in one deploy — each row follows
+ * its resource (resolved in claim-dependency order):
+ *
+ * ```ts
+ * // the resource at `A` is now `B`; the resource at `B` is now `C`
+ * yield* Bucket("B").pipe(renamedFrom("A"));
+ * yield* Bucket("C").pipe(renamedFrom("B"));
+ * ```
+ *
+ * A SWAP (`A` ⇄ `B`) is a rename cycle and fails the plan loudly — the two
+ * migrations would overwrite and delete each other's rows. Rename through
+ * a temporary id across two deploys instead. Two resources claiming the
+ * same former FQN also fail loudly.
+ */
+export const renamedFrom =
+  (...formerIds: [FormerId, ...FormerId[]]) =>
+  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+    Effect.provideService(effect, RenamePolicy, formerIds);