/** @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