sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Plan.ts

/** @effect-diagnostics anyUnknownInErrorContext:off */
/** @effect-diagnostics missingEffectError:off */
import * as Cause from "effect/Cause";
import * as Config from "effect/Config";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Ref from "effect/Ref";
import { asEffect } from ".//Util/types.ts";
import { isAction, type ActionLike } from "./Action.ts";
import {
  AdoptPolicy,
  OwnedBySomeoneElse,
  stripUnowned,
  Unowned,
  UnverifiableReplacement,
} from "./AdoptPolicy.ts";
import { AlchemyContext } from "./AlchemyContext.ts";
import {
  Artifacts,
  ArtifactStore,
  createArtifactStore,
  ensureArtifactStore,
  makeScopedArtifacts,
} from "./Artifacts.ts";
import { demandRemoteCredentials, failCredentialsRequired } from "./Auth/Demand.ts";
import {
  dedupeBindings,
  diffBindings,
  havePropsChanged,
  isResolved,
  type NoopDiff,
  type ReplaceDiff,
  type UpdateDiff,
} from "./Diff.ts";
import { emit, type PlannedAction, type PlannedBinding, type PlannedResource } from "./Events.ts";
import { parseFqn } from "./FQN.ts";
import { generateInstanceId } from "./InstanceId.ts";
import * as Output from "./Output.ts";
import {
  tryFindProviderRegistrationByType,
  missingProviderError,
  Provider,
  providerForMode,
  tryFindProviderByType,
  type ProviderService,
} from "./Provider.ts";
import { defaultProviderMode, stampedMode, type ProviderMode } from "./ProviderMode.ts";
import {
  isResource,
  missingImplementation,
  type ResourceBinding,
  type ResourceLike,
} from "./Resource.ts";
import { ResourceContext } from "./ResourceContext.ts";
import {
  InvalidResourceSelection,
  UnsafeSelectionBoundary,
  selectResources,
  type ResourceSelection,
  type SelectionOutput,
} from "./ResourceSelection.ts";
import { capturedEnvKeys } from "./RuntimeContext.ts";
import { cachedInScope } from "./Util/Memoize.ts";
export { InvalidResourceSelection, UnsafeSelectionBoundary } from "./ResourceSelection.ts";
import { type StackSpec } from "./Stack.ts";
import {
  isActionState,
  State,
  type ActionState,
  type CreatedResourceState,
  type CreatingResourceState,
  type RanActionState,
  type ReplacedResourceState,
  type ReplacingResourceState,
  type ResourceState,
  type StateStoreError,
  type UpdatedResourceState,
  type UpdatingReourceState,
} from "./State/index.ts";
import { isPlainData, mapPlainData } from "./Util/data.ts";
import { findCycleMembers } from "./Util/scc.ts";
import { hashInput } from "./Util/sha256.ts";

export type PlanError = never;

/**
 * A node in the plan that represents a resource CRUD operation.
 */
export type CRUD<R extends ResourceLike = ResourceLike> =
  | Create<R>
  | Update<R>
  | Delete<R>
  | Replace<R>
  | NoopUpdate<R>;

export type Apply<R extends ResourceLike = ResourceLike> =
  | Create<R>
  | Update<R>
  | Replace<R>
  | NoopUpdate<R>;

export type BindingAction = "create" | "update" | "delete" | "noop";

export interface BindingNode<Data = any> extends ResourceBinding {
  action: BindingAction;
  data: Data;
}

export interface BaseNode<R extends ResourceLike<string> = ResourceLike<string>> {
  resource: R;
  provider: ProviderService<R>;
  /**
   * The {@link ProviderMode} this node's `provider` was resolved for.
   * `undefined` for mode-agnostic providers (a single implementation
   * serves both dev and deploy) — such resources never persist a mode and
   * never replace on a mode switch. Apply stamps this onto every state
   * commit as `providerMode`.
   */
  mode: ProviderMode | undefined;
  downstream: string[];
  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> {
  /** Cloud attribute drift attached to synthetic drift-repair plans. */
  drift?: {
    readonly expected: unknown;
    readonly actual: unknown;
    readonly missing?: boolean;
  };
  /**
   * 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;
  /** Preserve the FQN-reuse exclusion across generations and state transitions. */
  adoptionBlocked?: "migrated-fqn";
}

export interface Create<R extends ResourceLike = ResourceLike> extends ApplyNodeBase<R> {
  action: "create";
  props: R["Props"];
  state: CreatingResourceState | undefined;
  /** Ownership probe deferred until upstream identities resolve during apply. */
  deferredAdoption?: { adopt: boolean };
}

export interface Update<R extends ResourceLike = ResourceLike> extends ApplyNodeBase<R> {
  action: "update" | "adopted";
  /** True while this is the first reconcile after a cold adoption. */
  adopting?: boolean;
  props: R["Props"];
  state:
    | CreatedResourceState
    | UpdatedResourceState
    | UpdatingReourceState
    // the props can change after creating the replacement resource,
    // so Apply needs to handle updates and then continue with cleaning up the replaced graph
    | ReplacedResourceState;
}

export interface Delete<R extends ResourceLike = ResourceLike> extends BaseNode<R> {
  action: "delete" | "orphaned";
  // a resource can be deleted no matter what state it's in
  state: ResourceState;
}

export interface NoopUpdate<R extends ResourceLike = ResourceLike> extends ApplyNodeBase<R> {
  action: "noop";
  state: CreatedResourceState | UpdatedResourceState;
}

export interface Replace<R extends ResourceLike = ResourceLike> extends ApplyNodeBase<R> {
  action: "replace";
  props: any;
  deleteFirst: boolean;
  restart?: boolean;
  /** Ownership probe of the replacement's physical identity, run before any mutation. */
  deferredAdoption?: { adopt: boolean };
  state:
    | CreatingResourceState
    | CreatedResourceState
    | UpdatingReourceState
    | UpdatedResourceState
    | ReplacingResourceState
    | ReplacedResourceState;
}

// ── Tasks ──────────────────────────────────────────────────────────────────
//
// Tasks live in the same FQN namespace as resources and participate in the
// same DAG (downstream/upstream edges, cycle detection). Their plan nodes
// have a different shape because they have no provider lifecycle.

export type ActionApply<T extends ActionLike = ActionLike> = ActionRun<T> | ActionNoop<T>;

export interface ActionNodeBase<T extends ActionLike = ActionLike> {
  readonly kind: "action";
  def: T;
  downstream: string[];
}

export interface ActionRun<T extends ActionLike = ActionLike> extends ActionNodeBase<T> {
  action: "run";
  /** Input expression — resolved against tracker outputs during apply. */
  input: T["Input"];
  /** Previous state, if any. `undefined` on the first run. */
  state: ActionState | undefined;
  /** True when `--force` triggered the re-run regardless of input drift. */
  forced: boolean;
}

export interface ActionNoop<T extends ActionLike = ActionLike> extends ActionNodeBase<T> {
  action: "noop";
  state: RanActionState;
}

export interface ActionDelete<T extends ActionLike = ActionLike> extends ActionNodeBase<T> {
  action: "delete";
  state: ActionState;
}

export type Plan<Output = any> = {
  /** Closed selection for partial apply and GC; absent for a full plan. */
  selectedFqns?: ReadonlySet<string>;
  resources: {
    [id in string]: Apply<any>;
  };
  /**
   * Tasks scheduled for this apply. Keyed by FQN, same namespace as
   * `resources` — Apply's scheduler merges both into a single DAG.
   */
  actions: {
    [id in string]: ActionApply;
  };
  deletions: {
    [id in string]?: Delete<ResourceLike>;
  };
  /** Tasks whose state should be dropped (no body invoked on removal). */
  actionDeletions: {
    [id in string]?: ActionDelete;
  };
  output: Output;
  /**
   * FQNs of resources that participate in a strongly-connected component
   * of the upstream dependency graph (or have a self-edge). The scheduler
   * uses this to decide whether an `update` node must publish its prior
   * attr early to break the cycle, or can simply wait for upstreams and
   * publish a fresh attr (the common, linear case).
   */
  cycleMembers: ReadonlySet<string>;
  /**
   * The run-level default {@link ProviderMode} this plan was built with
   * (`alchemy dev` → `"local"`, `alchemy deploy` → `"live"`). Renderers use
   * it to tag only the EXCEPTIONS — rows whose resolved mode differs from
   * the run default. `undefined` (plans built by older/auxiliary builders)
   * is treated as `"live"`.
   */
  defaultMode?: ProviderMode;
  /**
   * Marks a plan built by {@link destroy}. `apply` finishes a destroy plan
   * by deleting the stage's remaining persisted state — notably the stack
   * output record written by the last deploy — instead of persisting a new
   * (empty) output.
   */
  destroy?: boolean;
};

const describeBinding = (binding: BindingNode): PlannedBinding => ({
  sid: binding.sid,
  action: binding.action,
});

/** The serializable row view of one resource node (see {@link describePlan}). */
export const describeResource = (node: CRUD): PlannedResource => ({
  fqn: node.resource.FQN,
  logicalId: node.resource.LogicalId,
  resourceType: node.resource.Type,
  action: node.action,
  bindings: node.bindings.map(describeBinding),
  providerMode: node.mode,
  fromProviderMode:
    node.action === "replace" &&
    node.mode !== undefined &&
    node.state.providerMode !== undefined &&
    node.state.providerMode !== node.mode
      ? node.state.providerMode
      : undefined,
});

/** The serializable row view of one stack-action node. */
export const describeAction = (node: ActionApply | ActionDelete): PlannedAction => ({
  fqn: node.def.FQN,
  logicalId: node.def.LogicalId,
  actionType: node.def.Type,
  action: node.action,
});

/**
 * Serializable per-row views of a plan — everything a renderer or remote
 * consumer needs without holding the native plan: resource rows with their
 * bindings and provider modes, orphan deletions, and stack actions.
 */
export const describePlan = (
  plan: Plan,
): {
  readonly resources: ReadonlyArray<PlannedResource>;
  readonly actions: ReadonlyArray<PlannedAction>;
} => ({
  resources: [
    ...Object.values(plan.resources),
    ...Object.values(plan.deletions).filter((node): node is Delete => node !== undefined),
  ].map(describeResource),
  actions: [...Object.values(plan.actions ?? {}), ...Object.values(plan.actionDeletions ?? {})]
    .filter((node): node is ActionApply | ActionDelete => node !== undefined)
    .map(describeAction),
});

export interface MakePlanOptions {
  force?: boolean;
  include?: never;
  exclude?: never;
}

export interface FilteredPlanOptions
  extends Omit<MakePlanOptions, keyof ResourceSelection>, ResourceSelection {
  /**
   * Exact FQNs, unique logical IDs, or FQN globs, plus transitive input, capture,
   * and binding dependencies. An empty selection is an error. Other rows
   * and persisted stack outputs are untouched; filtered apply returns void.
   * The entire stack declaration still evaluates before selection. Renames
   * with persisted former rows require a full deployment. Replacement/GC
   * fails when prior or declared dependents are outside the selection.
   * Detaching a selected intermediate also requires selecting all consumers
   * reachable through its declared or historical downstream paths.
   * Historical bindings require selecting every persisted resource and Action
   * for replacement/GC. Clearing the last binding evidence also requires that
   * complete selection, since stored payloads cannot recover binding-cycle edges.
   * Only already-persisted, continuously retained bindings count as evidence.
   * Reconciling a row with incomplete downstream history requires that selection.
   * Exclusions are hard barriers, even for unchanged dependencies. Quote globs
   * in the CLI: `--include 'App/**' --exclude 'App/Legacy'`. Each occurrence
   * supplies one pattern; commas are literal. Dependencies hidden inside
   * callbacks must be declared explicitly.
   */
  include?: ReadonlyArray<string>;
}

type FullPlanCall = [options?: MakePlanOptions];

export function make<A, Call extends [options?: FilteredPlanOptions] = FullPlanCall>(
  stack: StackSpec<A>,
  ...call: Call
): Effect.Effect<Plan<SelectionOutput<A, Call[0]>>, never, State>;
export function make<A>(stack: StackSpec<A>, options: FilteredPlanOptions = {}) {
  return makePlan(stack, options);
}

/**
 * Bind every ref to a resource this program declares in its own stack and
 * stage, so the ref is a dependency like a direct reference: the target is
 * created first and deleted last, and the ref resolves to the target's fresh
 * attributes (see `Output.bindRef`). A ref is matched by its id against the
 * declared resource's FQN, which is what the ref reads from state. A
 * resource's ref to itself stays unbound: it reads its own persisted state.
 */
const bindSameStackRefs = (
  stack: StackSpec<any>,
  resources: ReadonlyArray<ResourceLike>,
  actions: ReadonlyArray<ActionLike>,
) => {
  const byFqn = new Map(resources.map((resource) => [resource.FQN, resource]));
  const bind = (owner: string, value: unknown) => {
    for (const ref of Output.collectRefs(value)) {
      if ((ref.stack ?? stack.name) !== stack.name) continue;
      if ((ref.stage ?? stack.stage) !== stack.stage) continue;
      if (ref.resourceId === owner) continue;
      const target = byFqn.get(ref.resourceId);
      if (target !== undefined) Output.bindRef(ref, target);
    }
  };
  for (const resource of resources) {
    bind(resource.FQN, resource.Props);
    bind(resource.FQN, stack.bindings[resource.FQN] ?? []);
  }
  for (const action of actions) {
    bind(action.FQN, [action.Input, action.Captures]);
  }
};

const makePlan = <A>(
  stack: StackSpec<A>,
  options: FilteredPlanOptions = {},
): Effect.Effect<Plan<A | undefined>, never, State> =>
  // @ts-expect-error
  Effect.gen(function* () {
    // Per-resource plan progress and phase markers are reported through
    // events as the work happens, so a renderer can show
    // plan computation while it runs. The default reporter is a no-op.

    const declaredResources = Object.values(stack.resources);
    const declaredActions = Object.values(stack.actions ?? {});
    const declared = [...declaredResources, ...declaredActions];
    bindSameStackRefs(stack, declaredResources, declaredActions);
    const upstream = (node: ResourceLike | ActionLike) =>
      Object.keys(
        Output.upstreamAny(
          isAction(node)
            ? [node.Input, node.Captures]
            : [node.Props, stack.bindings[node.FQN] ?? []],
        ),
      );
    const selected = yield* selectResources(declared, upstream, options);
    const resources = declaredResources.filter((node) => !selected || selected.has(node.FQN));
    const actions = declaredActions.filter((node) => !selected || selected.has(node.FQN));

    // Resolving the state service may bootstrap a remote store.
    yield* emit({ type: "plan.phase", phase: "loading-state" });
    const state = yield* yield* State;

    // A bare platform tag yields a forward reference registered with
    // `undefined` props (and `RequiresImplementation`); its `.make(props,
    // impl)` Layer repairs the props when it builds (in either order — the
    // #874 circular env-tag pattern). Props still `undefined` after the
    // whole program evaluated means the tag was yielded but its Layer was
    // never provided — fail fast naming the class and its Layer instead of
    // letting a provider read `undefined` props (#1054). Plain resources
    // may legitimately be yielded without props (a reference to
    // already-deployed state), so the check is scoped to platform tags.
    for (const resource of resources) {
      if (resource.RequiresImplementation && resource.Props === undefined) {
        return yield* Effect.die(missingImplementation(resource.Type, resource.LogicalId));
      }
    }

    // TODO(sam): rename terminology to Stack
    const stackName = stack.name;
    const stage = stack.stage;

    // Resolve the effective adoption setting for this plan. AdoptPolicy
    // (provided by the CLI or scoped via `adopt(...)`) takes precedence; if
    // unset, fall back to the AlchemyContext's `adopt` default; otherwise
    // adoption is disabled.
    const shouldAdopt = Effect.gen(function* () {
      const fromService = yield* Effect.serviceOption(AdoptPolicy);
      if (Option.isSome(fromService)) return fromService.value;
      const ctx = yield* Effect.serviceOption(AlchemyContext);
      return Option.match(ctx, {
        onNone: () => false,
        onSome: (c) => c.adopt,
      });
    });

    // The run-level default provider mode (`alchemy dev` → "local",
    // `alchemy deploy` → "live"). A resource-scoped `remote()` (captured on
    // the resource at registration as `Mode`) opts out of local emulation.
    const runDefaultMode = yield* defaultProviderMode;

    /**
     * Resolve the effective provider mode and the concrete provider
     * service for a resource.
     *
     * The mode only "sticks" when the provider actually distinguishes
     * modes (registered via `ProviderLayer.dual`). Mode-agnostic providers
     * satisfy any requested mode with their single implementation — in a
     * dev run, a construct that mixes emulatable resources with live-only
     * ones (e.g. R2 buckets) just works.
     */
    const resolveProviderAndMode = Effect.fn(function* (resource: {
      Type: string;
      Mode?: ProviderMode | undefined;
    }) {
      const base = yield* tryFindProviderRegistrationByType(resource.Type).pipe(
        Effect.flatMap(
          Option.match({
            onNone: () => Effect.die(`Provider not found for ${resource.Type}`),
            onSome: Effect.succeed,
          }),
        ),
      );
      const mode = base.modes !== undefined ? (resource.Mode ?? runDefaultMode) : undefined;
      const provider = yield* providerForMode(base, mode);
      return { provider, mode };
    });

    /**
     * Has this resource switched provider modes since it was last
     * reconciled? Rows without a persisted mode were written by a
     * pre-provider-mode engine (or a provider that only became dual-mode
     * later) — their physical resource is LIVE unless its attrs carry a
     * `dev:` identity marker proving it was reconciled locally (see
     * {@link stampedMode}). A dev run replaces unstamped live rows exactly
     * like stamped live rows; live runs replace unstamped marker rows.
     */
    const hasModeSwitched = (
      mode: ProviderMode | undefined,
      oldState: ResourceState | undefined,
    ): boolean => mode !== undefined && oldState !== undefined && stampedMode(oldState) !== mode;

    const resourceFqns = yield* state.list({
      stack: stackName,
      stage: stage,
    });
    const oldResources = yield* Effect.forEach(
      resourceFqns,
      (fqn) => state.get({ stack: stackName, stage: stage, fqn }),
      { 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]]));

    // Updating snapshots also retain prior bindings and downstream metadata.
    type DependencySnapshot = {
      downstream?: ReadonlyArray<string>;
      bindings?: ReadonlyArray<unknown>;
      old?: DependencySnapshot;
    };
    function* historicalRows(row: DependencySnapshot | undefined) {
      while (row) {
        yield row;
        row = row.old;
      }
    }

    if (selected) {
      for (const action of actions) {
        const row = persistedRows.get(action.FQN);
        if (row && !isActionState(row)) {
          return yield* Effect.die(
            new UnsafeSelectionBoundary({
              message: `Filtered Action '${action.FQN}' cannot overwrite persisted resource state. Finish resource cleanup before reusing its FQN for an Action.`,
            }),
          );
        }
      }
      for (const resource of declaredResources) {
        for (const former of resource.FormerFqns ?? []) {
          if (former === resource.FQN) continue;
          if (
            (selected.has(resource.FQN) && persistedRows.has(former)) ||
            (!selected.has(resource.FQN) && selected.has(former))
          ) {
            return yield* Effect.die(
              new UnsafeSelectionBoundary({
                message: `Filtered reconciliation cannot migrate '${former}' to '${resource.FQN}'. Run a full deployment for renames.`,
              }),
            );
          }
        }
      }
    }

    // Credential-free dev: the adoption probe below runs each new row's
    // `read` — for `Alchemy.remote()` rows that is a real cloud call, and
    // it happens before apply's demand gate. Demand those credentials up
    // front so a dev plan with nothing configured fails with the typed
    // CredentialsRequired rather than the first read's raw auth error.
    if (runDefaultMode === "local") {
      const remote: Array<{ Type: string; FQN: string }> = [];
      for (const resource of resources) {
        const { mode } = yield* resolveProviderAndMode(resource);
        if (mode === "live") remote.push(resource);
      }
      if (remote.length > 0) yield* demandRemoteCredentials(remote);
    }

    yield* emit({ type: "plan.phase", phase: "computing-plan" });

    // ── 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* tryFindProviderRegistrationByType(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 };
    });

    // Shared resolutions run in fibers of the plan's own scope (see
    // `cachedInScope`): a diff that fails or is cancelled must not take the
    // resolution every other diff is waiting on down with it.
    const memoScope = yield* Effect.scope;
    const resolvedResources: Record<string, Effect.Effect<any>> = {};

    const resolveResource = (
      resourceExpr: Output.ResourceExpr<any, any>,
    ): Effect.Effect<any, Config.ConfigError | StateStoreError> =>
      Effect.gen(function* () {
        if (selected && !selected.has(resourceExpr.src.FQN)) {
          return yield* Effect.die(
            new UnsafeSelectionBoundary({
              message: `Output evaluation discovered unselected dependency '${resourceExpr.src.FQN}'. Declare the dependency explicitly or run a full deployment.`,
            }),
          );
        }
        if (isAction(resourceExpr.src)) {
          const node = yield* diffAction(resourceExpr.src);
          return node.action === "noop" ? node.state.output : resourceExpr;
        }
        // @ts-expect-error
        return yield* (resolvedResources[resourceExpr.src.FQN] ??= yield* cachedInScope(memoScope)(
          Effect.gen(function* () {
            const resource = resourceExpr.src;

            const { provider, mode } = yield* resolveProviderAndMode(resource);
            const props = materializeStableRefs(yield* resolveInput(resource.Props));
            // 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;
            }

            // The resource is switching provider modes (local ⇄ live):
            // it will be replaced, so nothing about the persisted attrs
            // is stable for downstream consumers.
            if (hasModeSwitched(mode, oldState)) {
              return resourceExpr;
            }

            const oldProps = oldState.status === "updating" ? oldState.old.props : oldState.props;

            // Normalize both sides through `dedupeBindings` so the binding
            // sets handed to `diff` are deduped AND sid-sorted — provider
            // diffs that hash/compare the arrays never churn on
            // registration-order flips (or on legacy unsorted state).
            const oldBindings = dedupeBindings(oldState.bindings ?? []);
            const bindings = stack.bindings[resource.FQN] ?? [];
            const newBindings = dedupeBindings(
              combinedCycleMembers.has(resource.FQN) ? bindings : yield* resolveInput(bindings),
            );

            const diff = yield* provider.diff
              ? provider
                  .diff({
                    id: resource.LogicalId,
                    fqn: resource.FQN,
                    olds: oldProps,
                    instanceId: oldState.instanceId,
                    news: props,
                    output: oldState.attr,
                    oldBindings,
                    newBindings,
                  })
                  .pipe(providePlanScope(resource, oldState.instanceId))
              : Effect.undefined;

            // A present `diff.stables` is authoritative for this update and
            // overrides `provider.stables`. We only fall back to the
            // provider-level "always stable" list when the diff does not
            // return one (e.g. no diff fn, or a diff that omits `stables`).
            const stables: string[] = diff?.stables ?? provider.stables ?? [];

            const withStables = (output: any) =>
              stables.length > 0
                ? new Output.ResourceExpr(
                    resourceExpr.src,
                    Object.fromEntries(stables.map((stable) => [stable, output?.[stable]])),
                  )
                : // if there are no stable properties, treat every property as changed
                  resourceExpr;

            if (diff == null) {
              if (
                havePropsChanged(oldProps, props) ||
                (!combinedCycleMembers.has(resource.FQN) &&
                  diffBindings(oldBindings, newBindings).some(
                    (binding) => binding.action !== "noop",
                  ))
              ) {
                // the props have changed but the provider did not provide any hints as to what is stable
                // so we must assume everything has changed
                return withStables(oldState?.attr);
              }
            } else if (diff.action === "update") {
              return withStables(oldState?.attr);
            } else if (diff.action === "replace") {
              return resourceExpr;
            }
            // `--force` upgrades this resource's noop to an update (see the
            // diff mapping in the resource-graph pass below), so its
            // `reconcile` WILL re-run and may produce fresh attributes —
            // that is the point of --force. Returning the persisted attr
            // snapshot here would bake potentially-stale values into every
            // consumer's plan props and binding data, so consumers would
            // keep the stale attrs even though the upstream just
            // re-reconciled. Expose only the stable attributes and let
            // apply re-evaluate the rest against the forced reconcile's
            // fresh output. A noop diff may carry `stables` for exactly this
            // case (conditional stables such as a rename-mutable `name`);
            // without them the forced upstream would only expose
            // `provider.stables` and identity-sensitive consumers would
            // falsely plan a replacement (#1832).
            if (options.force) {
              return withStables(oldState?.attr);
            }
            if (
              oldState.status === "created" ||
              oldState.status === "updated" ||
              oldState.status === "replaced"
            ) {
              // we can safely return the attributes if we know they have stabilized
              return oldState?.attr;
            } else {
              // we must assume the resource doesn't exist if it hasn't stabilized
              return resourceExpr;
            }
          }),
        ));
      });

    /**
     * Resolve an input value as far as *truth* permits, keeping everything
     * else evaluable. A whole-resource reference to an updating upstream
     * stays a `ResourceExpr` (its stable attributes riding along): the
     * non-stable attributes are unknown at plan time and MUST be
     * re-evaluated — Apply runs `Output.evaluate(node.props, outputs)`
     * against the upstream's fresh post-reconcile attributes right before
     * `reconcile`. This is the value plan nodes carry; the diff-facing view
     * is derived from it by {@link materializeStableRefs}.
     */
    const resolveInput = (
      input: any,
      // Ancestor chain of the current walk. A value that appears on its own
      // ancestor path is a true cycle and is cut to `undefined` (a cycle can
      // never persist or serialize anyway); an immutable per-level set (not
      // a shared visited-set) keeps legitimately-shared diamond references
      // intact and is race-free under `concurrency: "unbounded"` (#1082).
      ancestors: ReadonlySet<object> = new Set(),
    ): Effect.Effect<any, Config.ConfigError | StateStoreError> =>
      Effect.gen(function* () {
        if (!input) {
          return input;
        } else if (Output.isExpr(input)) {
          return yield* resolveOutput(input);
        } else if (Config.isConfig(input)) {
          // Config is a lazy reference to the deploy environment. Resolve it
          // here so the concrete value flows into diffing/hashing (an opaque
          // Config hashes the same regardless of the underlying value) and so
          // providers receive a resolved value instead of a Config object.
          // `Config.Redacted` resolves to a `Redacted`, which stays opaque via
          // the branch below.
          return yield* resolveInput(yield* input, ancestors);
        } else if (isResource(input)) {
          // Resource objects have dynamic properties (path, hash, etc.) that are
          // created on-demand by a Proxy getter and aren't enumerable via Object.entries.
          // Resolve the ResourceExpr to get the actual resource output, then continue
          // resolving any nested outputs in the result.
          const resourceExpr = Output.of(input);
          const resolved = yield* resolveOutput(resourceExpr);
          if (Output.isResourceExpr(resolved)) {
            // Still-unresolved reference (creating, replacing, or updating
            // upstream) — keep it evaluable for Apply.
            return resolved;
          }
          return yield* resolveInput(resolved, ancestors);
        } else if (isPlainData(input)) {
          if (ancestors.has(input)) {
            return undefined;
          }
          const nested = new Set(ancestors).add(input);
          if (Array.isArray(input)) {
            return yield* Effect.forEach(input, (item) => resolveInput(item, nested), {
              concurrency: "unbounded",
            });
          }
          return Object.fromEntries(
            yield* Effect.forEach(
              Object.entries(input),
              ([key, value]) =>
                resolveInput(value, nested).pipe(Effect.map((value) => [key, value])),
              { concurrency: "unbounded" },
            ),
          );
        }
        // Everything else is an opaque leaf returned by identity: Duration,
        // Redacted, Date, and effect runtime values (a Worker's `exports`
        // carries each DO's `constructor` Effect and captured `services`
        // Context). Rebuilding a class instance entry-by-entry would strip
        // its prototype, and effect ≥4.0.0-beta.103's Context is cyclic
        // (#1082). Redacted additionally stays wrapped to preserve the
        // secrecy boundary. This sits after `Config.isConfig` on purpose —
        // Configs are Effects but must still resolve.
        return input;
      });

    /**
     * Project a {@link resolveInput} resolution into the DIFF-facing view:
     * replace each whole-resource `ResourceExpr` that carries stable
     * attributes (an upstream being *updated* in place — see `withStables` in
     * `resolveResource`) with a plain object of those stables, so the known
     * values flow into the consumer's `diff` and `havePropsChanged` instead
     * of the whole reference looking unresolved and `isResolved`
     * short-circuiting (#670 — this forced the Neon `Branch` to hand-extract
     * `project.projectId`).
     *
     * The projection is deliberately lossy — diffs compare VALUES. Plan nodes
     * never carry it: they keep the evaluable resolution so `reconcile` sees
     * the upstream's fresh non-stable attributes (e.g. a Lambda Version's
     * `version` number — #993's alias promotion bug).
     */
    const materializeStableRefs = (
      input: any,
      // Ancestor-path cycle guard — see resolveInput (#1082). Sync DFS, so
      // add/delete around the recursion is race-free.
      ancestors: WeakSet<object> = new WeakSet(),
    ): any => {
      // Expr checks come first: Output proxies are callable, so a plain
      // `typeof input === "object"` guard would let them slip through.
      if (Output.isResourceExpr(input) && input.stables) {
        return materializeStableRefs(input.stables, ancestors);
      } else if (Output.isExpr(input)) {
        // Genuinely unknown (e.g. a creating upstream) — nothing to show diff.
        return input;
      } else if (!input || !isPlainData(input)) {
        // Primitives and non-plain instances (Duration, Redacted, Date,
        // Effect/Layer/Context) are leaves — see isPlainData (#1082).
        return input;
      }
      return mapPlainData(input, ancestors, (child) => materializeStableRefs(child, ancestors));
    };

    const resolveOutput = (
      expr: Output.Expr<any>,
    ): Effect.Effect<any, Config.ConfigError | StateStoreError> =>
      Effect.gen(function* () {
        if (Output.isResourceExpr(expr)) {
          return yield* resolveResource(expr);
        } else if (Output.isPropExpr(expr)) {
          const upstream = yield* resolveOutput(expr.expr);
          return upstream?.[expr.identifier];
        } else if (Output.isApplyExpr(expr)) {
          const upstream = yield* resolveOutput(expr.expr);
          return Output.hasOutputs(upstream) ? expr : expr.f(upstream);
        } else if (Output.isEffectExpr(expr)) {
          const upstream = yield* resolveOutput(expr.expr);
          return Output.hasOutputs(upstream) ? expr : yield* expr.f(upstream);
        } else if (Output.isFlatMapExpr(expr)) {
          const upstream = yield* resolveOutput(expr.expr);
          // Source still unresolved -> keep the flatMap intact for a later pass.
          // Otherwise run `f` to produce the next Output and resolve into it.
          return Output.hasOutputs(upstream)
            ? expr
            : yield* resolveOutput(Output.asOutput(expr.f(upstream)) as Output.Expr<any>);
        } else if (Output.isAllExpr(expr)) {
          return yield* Effect.forEach(expr.outs, resolveOutput, {
            concurrency: "unbounded",
          });
        } else if (Output.isLiteralExpr(expr)) {
          return expr.value;
        } else if (Output.isRefExpr(expr)) {
          // A ref bound to a declared resource resolves like a direct
          // reference: unknown while that resource is being created.
          const target = Output.refTarget(expr);
          if (target !== undefined) {
            return yield* resolveResource(
              Output.of(target as any) as Output.ResourceExpr<any, any>,
            );
          }
          const refStack = expr.stack ?? stackName;
          const refStage = expr.stage ?? stage;
          const refState = yield* state
            .get({
              stack: refStack,
              stage: refStage,
              fqn: expr.resourceId,
            })
            .pipe(Effect.orDie);
          if (!refState) {
            return yield* Effect.die(
              new Output.InvalidReferenceError({
                message: `Reference to '${expr.resourceId}' in stack '${refStack}' and stage '${refStage}' not found. Have you deployed '${refStage}' of '${refStack}'?`,
                stack: refStack,
                stage: refStage,
                resourceId: expr.resourceId,
              }),
            );
          }
          return (refState as any).attr ?? (refState as any).output;
        } else if (Output.isStackRefExpr(expr)) {
          const refStack = expr.stack;
          const refStage = expr.stage ?? stage;
          const output = yield* state
            .getOutput({
              stack: refStack,
              stage: refStage,
            })
            .pipe(Effect.orDie);
          if (output == null) {
            return yield* Effect.die(
              new Output.InvalidReferenceError({
                message: `Reference to stack '${refStack}' at stage '${refStage}' not found. Have you deployed stage '${refStage}' of '${refStack}'?`,
                stack: refStack,
                stage: refStage,
                resourceId: refStack,
              }),
            );
          }
          return output;
        } else if (Output.isNamedExpr(expr)) {
          return yield* resolveOutput(expr.expr);
        }
        return yield* Effect.die(new Error("Not implemented yet" + (expr as any).kind));
      });

    // Build a set of FQNs for the new resources to detect orphans
    const newResourceFqns = new Set(resources.map((r) => r.FQN));
    const newActionFqns = new Set(actions.map((t) => t.FQN));
    // Unified set used wherever the DAG must include both kinds.
    const newNodeFqns = new Set<string>([...newResourceFqns, ...newActionFqns]);

    // Map FQN -> list of upstream FQNs (resources this one depends on via props).
    // Tasks contribute upstream edges through their `Input` expression.
    const newUpstreamDependencies: {
      [fqn: string]: string[];
    } = Object.fromEntries([
      ...resources.map(
        (resource) =>
          [
            resource.FQN,
            Object.values(Output.upstreamAny(resource.Props)).map((r) => r.FQN),
          ] as const,
      ),
      ...actions.map(
        (action) =>
          [
            action.FQN,
            // An Action depends on the resources referenced by its Input *and*
            // any Output captured via `yield* output` inside its init Effect.
            Array.from(
              new Set([
                ...Object.values(Output.upstreamAny(action.Input)).map((r) => r.FQN),
                ...Object.values(Output.upstreamAny(action.Captures)).map((r) => r.FQN),
              ]),
            ),
          ] as const,
      ),
    ]);

    // Map FQN -> list of upstream FQNs from bindings
    const bindingUpstreamDependencies: {
      [fqn: string]: string[];
    } = Object.fromEntries(
      resources.map((resource) => [
        resource.FQN,
        Object.values(Output.upstreamAny(stack.bindings[resource.FQN] ?? [])).map((r) => r.FQN),
      ]),
    );

    // Combined prop + binding upstream for the desired graph, including
    // references to resources outside the current graph so delete validation can
    // tell whether any surviving resource still points at an orphan.
    const rawUpstreamDependencies: {
      [fqn: string]: string[];
    } = Object.fromEntries<string[]>([
      ...resources.map((resource): [string, string[]] => {
        const fqn = resource.FQN;
        const propDeps = newUpstreamDependencies[fqn] ?? [];
        const bindDeps = bindingUpstreamDependencies[fqn] ?? [];
        return [fqn, [...new Set([...propDeps, ...bindDeps])]];
      }),
      // Actions have no bindings — their upstream is input + init captures,
      // both already folded into newUpstreamDependencies above.
      ...actions.map((action): [string, string[]] => {
        const fqn = action.FQN;
        return [fqn, newUpstreamDependencies[fqn] ?? []];
      }),
    ]);

    // Combined prop + binding upstream, filtered to resources/tasks in this
    // graph for scheduling and cycle detection.
    const allUpstreamDependencies: {
      [fqn: string]: string[];
    } = Object.fromEntries([
      ...resources.map((resource) => {
        const fqn = resource.FQN;
        const deps = rawUpstreamDependencies[fqn] ?? [];
        return [fqn, deps.filter((dep) => newNodeFqns.has(dep))] as const;
      }),
      ...actions.map((action) => {
        const fqn = action.FQN;
        const deps = newUpstreamDependencies[fqn] ?? [];
        return [fqn, deps.filter((dep) => newNodeFqns.has(dep))] as const;
      }),
    ]);

    // Resources that participate in a cycle when both prop and binding
    // edges are considered. Used below to decide whether an acyclic
    // binding edge should also become a downstream edge.
    const combinedCycleMembers = findCycleMembers(allUpstreamDependencies);
    const inputCycleMembers = findCycleMembers({
      ...newUpstreamDependencies,
      ...Object.fromEntries(
        actions.map((action) => [
          action.FQN,
          Object.values(Output.upstreamAny(action.Input)).map((r) => r.FQN),
        ]),
      ),
    });

    // Map FQN -> list of downstream FQNs (resources/actions that depend on
    // this one).
    //
    // Prop edges always become downstream edges — they can't form cycles
    // (the resource graph is a DAG by construction once props are fully
    // resolved). Binding edges become downstream edges too, except when
    // they participate in a cycle in the combined graph: mutual bindings
    // (A binds to B's data, B binds to A's data) intentionally do not
    // create downstream edges, so deletion does not deadlock waiting on
    // each other (see the "binding-only cycles inside a construct" test
    // in `plan.test.ts`).
    //
    // Including acyclic binding edges is required for cloud APIs that
    // enforce the binding at the provider level — e.g. a Cloudflare
    // Worker with a `service` binding to another Worker cannot delete
    // the upstream worker until the downstream worker's binding has been
    // removed. Without the binding edge in `downstream`, the two delete
    // concurrently and the upstream delete fails with
    // `ServiceBindingConflict`.
    //
    // Actions don't have bindings, so for action upstreams we use only
    // prop edges (which collapse to `newUpstreamDependencies` lookups).
    //
    // The edges are inverted in one pass (in `rawUpstreamDependencies` order,
    // so each downstream list keeps that order) — scanning every node's
    // upstream list per node was quadratic in resource count (#2400).
    const directDownstream = new Map<string, string[]>();
    for (const [downFqn, upstreams] of Object.entries(rawUpstreamDependencies)) {
      const propDeps = new Set(newUpstreamDependencies[downFqn]);
      for (const upFqn of upstreams) {
        if (downFqn === upFqn) continue;
        // Binding-only edge — exclude when both endpoints sit inside
        // the same SCC of the combined graph.
        if (
          !propDeps.has(upFqn) &&
          combinedCycleMembers.has(upFqn) &&
          combinedCycleMembers.has(downFqn)
        ) {
          continue;
        }
        let downstream = directDownstream.get(upFqn);
        if (!downstream) directDownstream.set(upFqn, (downstream = []));
        downstream.push(downFqn);
      }
    }

    const computeDownstream = (upFqn: string): string[] => {
      const downstream = [...(directDownstream.get(upFqn) ?? [])];
      if (selected) {
        for (const row of historicalRows(persistedRows.get(upFqn))) {
          for (const dep of row.downstream ?? []) {
            if (!selected.has(dep) && !downstream.includes(dep)) downstream.push(dep);
          }
        }
      }
      return downstream;
    };

    const newDownstreamDependencies: {
      [fqn: string]: string[];
    } = Object.fromEntries([
      ...resources.map((resource) => [resource.FQN, computeDownstream(resource.FQN)] as const),
      ...actions.map((action) => [action.FQN, computeDownstream(action.FQN)] as const),
    ]);

    const actionPlans: Record<
      string,
      Effect.Effect<ActionRun | ActionNoop, Config.ConfigError | StateStoreError>
    > = {};
    const diffAction = Effect.fn("plan.diff.action")(function* (action: ActionLike) {
      return yield* (actionPlans[action.FQN] ??= yield* cachedInScope(memoScope)(
        Effect.gen(function* () {
          const fqn = action.FQN;
          const downstream = newDownstreamDependencies[fqn] ?? [];
          const oldState = yield* state.get({ stack: stackName, stage, fqn });
          const prior = isActionState(oldState) ? oldState : undefined;
          const resolvedInput = inputCycleMembers.has(fqn)
            ? action.Input
            : yield* resolveInput(action.Input);
          // Actions are pure in their inputs. Only a completed, unforced run
          // with fully known, identical inputs has a reusable output.
          if (
            prior?.status === "ran" &&
            !options.force &&
            !inputCycleMembers.has(fqn) &&
            isResolved(resolvedInput) &&
            prior.inputHash === (yield* hashInput(resolvedInput))
          ) {
            return {
              kind: "action",
              action: "noop",
              def: action,
              state: prior,
              downstream,
            } satisfies ActionNoop;
          }
          return {
            kind: "action",
            action: "run",
            def: action,
            input: action.Input,
            state: prior,
            downstream,
            forced: !!options.force,
          } satisfies ActionRun;
        }),
      ));
    });

    const plannedCount = yield* Ref.make(0);
    const resourcePlanned = (node: CRUD) =>
      Ref.updateAndGet(plannedCount, (count) => count + 1).pipe(
        Effect.flatMap((completed) =>
          emit({
            type: "plan.resource.completed",
            ...describeResource(node),
            completed,
            total: resources.length,
          }),
        ),
      );

    const diffResource = Effect.fn("plan.diff.resource")(function* (resource: ResourceLike) {
      const { provider, mode } = yield* resolveProviderAndMode(resource);
      const id = resource.LogicalId;
      const fqn = resource.FQN;
      // Paired with the resource-planned completion below so renderers can
      // show what is actually in flight (diffs may read the cloud and run
      // concurrently — completions alone hide the slow tail).
      yield* emit({
        type: "plan.resource.started",
        fqn,
        logicalId: id,
        resourceType: resource.Type,
        total: resources.length,
      });
      // Apply-facing props (stored on the plan node): whole-resource
      // references to updating upstreams stay evaluable `ResourceExpr`s.
      // Apply runs `Output.evaluate(node.props, outputs)` right before
      // `reconcile`, so these references resolve to the upstream's
      // fresh post-reconcile attributes.
      const applyProps = yield* resolveInput(resource.Props);
      // Diff-facing view of the same resolution: stable attributes
      // materialized so their known values flow into `diff` /
      // `havePropsChanged`.
      const news = materializeStableRefs(applyProps);
      const downstream = newDownstreamDependencies[fqn] ?? [];

      // Apply-facing binding rows, mirroring `applyProps`: payloads
      // whose data embeds a whole-resource reference to an updating
      // upstream keep it as an evaluable `ResourceExpr`. Apply runs
      // `Output.evaluate(node.bindings, outputs)` right before
      // `reconcile`, so the host receives the upstream's fresh
      // post-reconcile attributes. Collapse duplicates by sid so the
      // binding set handed to `diff` matches what `reconcile` receives
      // (see `dedupeBindings`).
      const applyBindings: ResourceBinding[] = dedupeBindings(
        yield* resolveInput(stack.bindings[fqn] ?? []),
      );
      // Diff-facing view of the same rows: stable attributes
      // materialized so `diffBindings` / `provider.diff` compare known
      // values. Terminal commits still persist the payload the provider
      // actually reconciled with (#874) — Apply commits the evaluated
      // `bindingOutputs`, not these plan-time shapes.
      const newBindings: ResourceBinding[] = materializeStableRefs(applyBindings);
      // 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
      // each lifecycle method — owns the existence/ownership decision.
      //
      // The provider returns one of:
      //   - `undefined`        → resource doesn't exist; create it
      //   - plain attrs        → exists and is owned by us; silent adopt
      //   - `Unowned(attrs)`   → exists but is *not* ours
      //
      // Routing:
      //   - owned                          → adopt the `created` state
      //                                      from attrs and continue
      //                                      through the normal diff
      //                                      path (so subsequent props
      //                                      drift produces an update).
      //   - unowned + adopt enabled        → take over: adopt the
      //                                      `created` state and let the
      //                                      next update overwrite tags.
      //   - unowned + adopt disabled       → fail with
      //                                      `OwnedBySomeoneElse`.
      //
      // Plan construction is side-effect-free: the adopted `created`
      // state is only held in-memory here (to drive the diff) and rides
      // onto the plan node as `node.state`. Persisting it to the state
      // store happens exclusively during APPLY of that node (the update
      // lifecycle commits `updating` / `updated` carrying this state).
      // If planning persisted here, a mere `alchemy plan` / `--dry-run`
      // would claim ownership of an unowned cloud resource, arming a
      // later unrelated deploy to orphan-delete it. See
      // https://github.com/alchemy-run/alchemy/issues/793.
      //
      // After a cold-start adoption (engine just discovered an
      // existing cloud resource via `read`), force the engine's
      // normal `update` path so the provider can re-sync ownership
      // tags, configuration, etc. against the desired props.
      // Adoption carries state with `props: news`, so the default
      // diff sees no drift and would noop — which would leave any
      // foreign-owned tags / divergent config in place. Forcing
      // update keeps the deploy idempotent: if cloud state already
      // matches news, the provider's update is a no-op write.
      //
      // Skip the adoption probe entirely when `news` still contains
      // unresolved upstream Outputs (e.g. a `streamArn` referencing
      // a stream being created in the same plan). Calling `read` with
      // an unresolved value would surface as `ParseError` from the
      // SDK protocol layer. Upstream creation can produce existing children
      // (e.g. a cloned branch's Auth integration), so Apply must perform the
      // deferred ownership probe once those identities resolve.
      // 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 claimant = formerFqnClaims.get(fqn);
      const claimantRow = claimant === undefined ? undefined : persistedRows.get(claimant);
      const reusesMigratedFqn =
        migratedRowFqns.has(fqn) ||
        oldState?.adoptionBlocked === "migrated-fqn" ||
        // Migration can commit before the fresh create records its exclusion.
        (oldState === undefined && claimantRow !== undefined && !isActionState(claimantRow));
      let forceUpdateAfterAdoption = false;
      if (oldState === undefined && provider.read && isResolved(news) && !reusesMigratedFqn) {
        const adoptInstanceId = yield* generateInstanceId();
        const readResult = yield* provider
          .read({
            id,
            fqn,
            instanceId: adoptInstanceId,
            olds: news,
            output: undefined,
          })
          .pipe(providePlanScope(resource, adoptInstanceId));
        if (readResult !== undefined) {
          const isUnowned = Unowned.is(readResult);
          // A resource-scoped `adopt(...)` (captured on the resource at
          // registration) overrides the stack/CLI default.
          const adoptThis = resource.Adopt ?? (yield* shouldAdopt);
          if (isUnowned && !adoptThis) {
            return yield* new OwnedBySomeoneElse({
              message:
                `Cannot adopt resource '${fqn}' (${resource.Type}): ` +
                "it exists in the cloud but is not owned by this " +
                "stack/stage/logical-id. Re-run with `--adopt` (or " +
                "wrap the effect in `adopt(true)`) to take it over.",
              resourceType: resource.Type,
              logicalId: id,
            });
          }
          const adoptedState = {
            status: "created" as const,
            fqn,
            logicalId: id,
            instanceId: adoptInstanceId,
            namespace: resource.Namespace,
            resourceType: resource.Type,
            props: news,
            attr: stripUnowned(readResult),
            providerVersion: provider.version ?? 0,
            bindings: [],
            downstream,
            removalPolicy: resource.RemovalPolicy,
            providerMode: mode,
          } satisfies CreatedResourceState;
          // In-memory only — do NOT persist here. Plan.make runs for
          // `alchemy plan` / `deploy --dry-run` too, so a `state.set`
          // would mutate persistent state during a read-only preview.
          // The adopted state rides onto the plan node via `oldState`
          // (→ `node.state`) and is persisted at APPLY time by the
          // update lifecycle's `updating` / `updated` commits. See
          // https://github.com/alchemy-run/alchemy/issues/793.
          oldState = adoptedState;
          forceUpdateAfterAdoption = true;
        }
      }

      // Sid-sorted like `newBindings` (see the resolveResource note).
      const oldBindings = dedupeBindings(oldState?.bindings ?? []);
      // Actions come from the materialized comparison (`newBindings`);
      // the payloads the node carries into Apply come from the
      // apply-faithful rows, joined by sid — both are views of the same
      // deduped `stack.bindings[fqn]` rows, so action and payload can
      // never drift. `delete` rows keep the persisted old data.
      const applyBindingData = new Map(applyBindings.map((b) => [b.sid, b.data]));
      const bindingDiffs = diffBindings(oldBindings, newBindings).map((b) =>
        b.action === "delete" || !applyBindingData.has(b.sid)
          ? b
          : { ...b, data: applyBindingData.get(b.sid) },
      );

      // Local ⇄ live switch: the persisted row was reconciled by a
      // different provider mode than the one resolved for this run.
      // The two runtimes host distinct physical instances, so this is
      // always a replacement — the new instance is created with the