alchemy 2.0.0-beta.1 → 2.0.0-beta.2

package/src/Plan.ts

@@ -1,5 +1,6 @@
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 import { asEffect } from ".//Util/types.ts";
 import {
   Artifacts,
@@ -8,7 +9,6 @@ import {
   ensureArtifactStore,
   makeScopedArtifacts,
 } from "./Artifacts.ts";
-import * as Option from "effect/Option";
 import {
   diffBindings,
   havePropsChanged,
@@ -19,7 +19,7 @@ import { parseFqn } from "./FQN.ts";
 import { InstanceId } from "./InstanceId.ts";
 import * as Output from "./Output.ts";
 import {
-  getProviderByType,
+  findProviderByType,
   Provider,
   type ProviderService,
 } from "./Provider.ts";
@@ -157,653 +157,652 @@ export const make = <A>(
   options: MakePlanOptions = {},
 ): Effect.Effect<Plan<A>, never, State> =>
   // @ts-expect-error
-  ensureArtifactStore(
-    Effect.gen(function* () {
-      const state = yield* State;
-
-      const resources = Object.values(stack.resources);
-
-      // TODO(sam): rename terminology to Stack
-      const stackName = stack.name;
-      const stage = stack.stage;
-
-      const resourceFqns = yield* state.list({
-        stack: stackName,
-        stage: stage,
-      });
-      const oldResources = yield* Effect.all(
-        resourceFqns.map((fqn) =>
-          state.get({ stack: stackName, stage: stage, fqn }),
-        ),
-        { concurrency: "unbounded" },
-      );
-
-      const resolvedResources: Record<string, Effect.Effect<any>> = {};
-
-      const resolveResource = (
-        resourceExpr: Output.ResourceExpr<any, any>,
-      ): Effect.Effect<any> =>
-        Effect.gen(function* () {
-          // @ts-expect-error
-          return yield* (resolvedResources[resourceExpr.src.FQN] ??=
-            yield* Effect.cached(
-              Effect.gen(function* () {
-                const resource = resourceExpr.src;
-
-                const provider = yield* Provider(resource.Type);
-                const props = yield* resolveInput(resource.Props);
-                const oldState = yield* state.get({
-                  stack: stackName,
-                  stage: stage,
-                  fqn: resource.FQN,
-                });
-
-                if (!oldState || oldState.status === "creating") {
-                  return resourceExpr;
-                }
-
-                const oldProps =
-                  oldState.status === "updating"
-                    ? oldState.old.props
-                    : oldState.props;
-
-                const oldBindings = oldState.bindings ?? [];
-                const newBindings = stack.bindings[resource.FQN] ?? [];
-
-                const diff = yield* provider.diff
-                  ? provider
-                      .diff({
-                        id: resource.LogicalId,
-                        olds: oldProps,
-                        instanceId: oldState.instanceId,
-                        news: props,
-                        output: oldState.attr,
-                        oldBindings,
-                        newBindings,
-                      })
-                      .pipe(providePlanScope(resource.FQN, oldState.instanceId))
-                  : Effect.succeed(undefined);
-
-                const stables: string[] = [
-                  ...(provider.stables ?? []),
-                  ...(diff?.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)) {
-                    // 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;
-                }
-                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;
-                }
-              }),
-            ));
-        });
-
-      const resolveInput = (input: any): Effect.Effect<any> =>
-        Effect.gen(function* () {
-          if (!input) {
-            return input;
-          } else if (Output.isExpr(input)) {
-            return yield* resolveOutput(input);
-          } else if (Array.isArray(input)) {
-            return yield* Effect.all(input.map(resolveInput), {
-              concurrency: "unbounded",
-            });
-          } 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);
-            return yield* resolveInput(resolved);
-          } else if (typeof input === "object") {
-            return Object.fromEntries(
-              yield* Effect.all(
-                Object.entries(input).map(([key, value]) =>
-                  resolveInput(value).pipe(Effect.map((value) => [key, value])),
-                ),
-                { concurrency: "unbounded" },
-              ),
-            );
-          }
-          return input;
-        });
-
-      const resolveOutput = (expr: Output.Expr<any>): Effect.Effect<any> =>
-        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.isAllExpr(expr)) {
-            return yield* Effect.all(expr.outs.map(resolveOutput), {
-              concurrency: "unbounded",
-            });
-          } else if (Output.isLiteralExpr(expr)) {
-            return expr.value;
-          }
-          return yield* Effect.die(new Error("Not implemented yet"));
-        });
-
-      // map of resource FQN -> its downstream dependencies (resources that depend on it)
-      const oldDownstreamDependencies: {
-        [fqn: string]: string[];
-      } = Object.fromEntries(
-        oldResources
-          .filter((resource) => !!resource)
-          .map((resource) => [resource.fqn, resource.downstream]),
-      );
-
-      // Build a set of FQNs for the new resources to detect orphans
-      const newResourceFqns = new Set(resources.map((r) => r.FQN));
-
-      // Map FQN -> list of upstream FQNs (resources this one depends on via props)
-      const newUpstreamDependencies: {
-        [fqn: string]: string[];
-      } = Object.fromEntries(
-        resources.map((resource) => [
-          resource.FQN,
-          Object.values(Output.upstreamAny(resource.Props)).map((r) => r.FQN),
-        ]),
-      );
-
-      // 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(
-        resources.map((resource) => {
-          const fqn = resource.FQN;
-          const propDeps = newUpstreamDependencies[fqn] ?? [];
-          const bindDeps = bindingUpstreamDependencies[fqn] ?? [];
-          return [fqn, [...new Set([...propDeps, ...bindDeps])]];
-        }),
-      );
-
-      // Combined prop + binding upstream, filtered to resources 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) => newResourceFqns.has(dep))];
-        }),
-      );
-
-      // Map FQN -> list of downstream FQNs (resources that depend on this one)
-      const newDownstreamDependencies: {
-        [fqn: string]: string[];
-      } = Object.fromEntries(
-        resources.map((resource) => [
-          resource.FQN,
-          Object.entries(newUpstreamDependencies)
-            .filter(([_, upstream]) => upstream.includes(resource.FQN))
-            .map(([depFqn]) => depFqn),
-        ]),
-      );
-
-      const resourceGraph = Object.fromEntries(
-        (yield* Effect.all(
-          resources.map(
-            Effect.fn(function* (resource) {
-              const provider = yield* Provider(resource.Type);
-              const id = resource.LogicalId;
-              const fqn = resource.FQN;
-              const news = yield* resolveInput(resource.Props);
-              const downstream = newDownstreamDependencies[fqn] ?? [];
-
-              const newBindings: ResourceBinding[] = yield* resolveInput(
-                stack.bindings[fqn] ?? [],
-              );
+  Effect.gen(function* () {
+    const state = yield* State;
+
+    const resources = Object.values(stack.resources);
+
+    // TODO(sam): rename terminology to Stack
+    const stackName = stack.name;
+    const stage = stack.stage;
+
+    const resourceFqns = yield* state.list({
+      stack: stackName,
+      stage: stage,
+    });
+    const oldResources = yield* Effect.all(
+      resourceFqns.map((fqn) =>
+        state.get({ stack: stackName, stage: stage, fqn }),
+      ),
+      { concurrency: "unbounded" },
+    );
+
+    const resolvedResources: Record<string, Effect.Effect<any>> = {};
+
+    const resolveResource = (
+      resourceExpr: Output.ResourceExpr<any, any>,
+    ): Effect.Effect<any> =>
+      Effect.gen(function* () {
+        // @ts-expect-error
+        return yield* (resolvedResources[resourceExpr.src.FQN] ??=
+          yield* Effect.cached(
+            Effect.gen(function* () {
+              const resource = resourceExpr.src;
+
+              const provider = yield* findProviderByType(resource.Type);
+              const props = yield* resolveInput(resource.Props);
               const oldState = yield* state.get({
                 stack: stackName,
                 stage: stage,
-                fqn,
+                fqn: resource.FQN,
               });
-              const oldBindings = oldState?.bindings ?? [];
-              const bindingDiffs = diffBindings(oldBindings, newBindings);
-
-              const Node = <T extends Apply>(
-                node: Omit<
-                  T,
-                  "provider" | "resource" | "bindings" | "downstream"
-                >,
-              ) =>
-                ({
-                  ...node,
-                  provider,
-                  resource,
-                  bindings: bindingDiffs,
-                  downstream,
-                }) as any as T;
-
-              // Plan against the persisted state we have, not the ideal final state we
-              // hoped to reach last time. Recovery is expressed by mapping each
-              // intermediate state back onto a fresh CRUD action.
-              if (oldState === undefined) {
-                return Node<Create>({
-                  action: "create",
-                  props: news,
-                  state: oldState,
-                });
-              } else if (
-                oldState.status === "creating" &&
-                oldState.attr === undefined
-              ) {
-                // A create may have succeeded before state persistence failed. If the
-                // provider can recover an attribute snapshot, keep driving the same
-                // create instead of starting over blindly.
-                if (provider.read) {
-                  const attr = yield* provider
-                    .read({
-                      id,
+
+              if (!oldState || oldState.status === "creating") {
+                return resourceExpr;
+              }
+
+              const oldProps =
+                oldState.status === "updating"
+                  ? oldState.old.props
+                  : oldState.props;
+
+              const oldBindings = oldState.bindings ?? [];
+              const newBindings = stack.bindings[resource.FQN] ?? [];
+
+              const diff = yield* provider.diff
+                ? provider
+                    .diff({
+                      id: resource.LogicalId,
+                      olds: oldProps,
                       instanceId: oldState.instanceId,
-                      olds: oldState.props,
+                      news: props,
                       output: oldState.attr,
+                      oldBindings,
+                      newBindings,
                     })
-                    .pipe(providePlanScope(fqn, oldState.instanceId));
-                  if (attr) {
-                    return Node<Create>({
-                      action: "create",
-                      props: news,
-                      state: { ...oldState, attr },
-                    });
-                  }
+                    .pipe(providePlanScope(resource.FQN, oldState.instanceId))
+                : Effect.succeed(undefined);
+
+              const stables: string[] = [
+                ...(provider.stables ?? []),
+                ...(diff?.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)) {
+                  // 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;
+              }
+              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;
               }
+            }),
+          ));
+      });
 
-              // Diff against whatever props represent the best-known current attempt.
-              // For replacement recovery that means the top-level replacement props,
-              // not the older generations stored under `old`.
-              const oldProps = oldState.props;
+    const resolveInput = (input: any): Effect.Effect<any> =>
+      Effect.gen(function* () {
+        if (!input) {
+          return input;
+        } else if (Output.isExpr(input)) {
+          return yield* resolveOutput(input);
+        } else if (Array.isArray(input)) {
+          return yield* Effect.all(input.map(resolveInput), {
+            concurrency: "unbounded",
+          });
+        } 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);
+          return yield* resolveInput(resolved);
+        } else if (typeof input === "object") {
+          return Object.fromEntries(
+            yield* Effect.all(
+              Object.entries(input).map(([key, value]) =>
+                resolveInput(value).pipe(Effect.map((value) => [key, value])),
+              ),
+              { concurrency: "unbounded" },
+            ),
+          );
+        }
+        return input;
+      });
 
-              const diff = yield* asEffect(
-                provider
-                  ?.diff?.({
+    const resolveOutput = (expr: Output.Expr<any>): Effect.Effect<any> =>
+      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.isAllExpr(expr)) {
+          return yield* Effect.all(expr.outs.map(resolveOutput), {
+            concurrency: "unbounded",
+          });
+        } else if (Output.isLiteralExpr(expr)) {
+          return expr.value;
+        }
+        return yield* Effect.die(new Error("Not implemented yet"));
+      });
+
+    // map of resource FQN -> its downstream dependencies (resources that depend on it)
+    const oldDownstreamDependencies: {
+      [fqn: string]: string[];
+    } = Object.fromEntries(
+      oldResources
+        .filter((resource) => !!resource)
+        .map((resource) => [resource.fqn, resource.downstream]),
+    );
+
+    // Build a set of FQNs for the new resources to detect orphans
+    const newResourceFqns = new Set(resources.map((r) => r.FQN));
+
+    // Map FQN -> list of upstream FQNs (resources this one depends on via props)
+    const newUpstreamDependencies: {
+      [fqn: string]: string[];
+    } = Object.fromEntries(
+      resources.map((resource) => [
+        resource.FQN,
+        Object.values(Output.upstreamAny(resource.Props)).map((r) => r.FQN),
+      ]),
+    );
+
+    // 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(
+      resources.map((resource) => {
+        const fqn = resource.FQN;
+        const propDeps = newUpstreamDependencies[fqn] ?? [];
+        const bindDeps = bindingUpstreamDependencies[fqn] ?? [];
+        return [fqn, [...new Set([...propDeps, ...bindDeps])]];
+      }),
+    );
+
+    // Combined prop + binding upstream, filtered to resources 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) => newResourceFqns.has(dep))];
+      }),
+    );
+
+    // Map FQN -> list of downstream FQNs (resources that depend on this one)
+    const newDownstreamDependencies: {
+      [fqn: string]: string[];
+    } = Object.fromEntries(
+      resources.map((resource) => [
+        resource.FQN,
+        Object.entries(newUpstreamDependencies)
+          .filter(([_, upstream]) => upstream.includes(resource.FQN))
+          .map(([depFqn]) => depFqn),
+      ]),
+    );
+
+    const resourceGraph = Object.fromEntries(
+      (yield* Effect.all(
+        resources.map(
+          Effect.fn(function* (resource) {
+            const provider = yield* findProviderByType(resource.Type);
+            const id = resource.LogicalId;
+            const fqn = resource.FQN;
+            const news = yield* resolveInput(resource.Props);
+            const downstream = newDownstreamDependencies[fqn] ?? [];
+
+            const newBindings: ResourceBinding[] = yield* resolveInput(
+              stack.bindings[fqn] ?? [],
+            );
+            const oldState = yield* state.get({
+              stack: stackName,
+              stage: stage,
+              fqn,
+            });
+            const oldBindings = oldState?.bindings ?? [];
+            const bindingDiffs = diffBindings(oldBindings, newBindings);
+
+            const Node = <T extends Apply>(
+              node: Omit<
+                T,
+                "provider" | "resource" | "bindings" | "downstream"
+              >,
+            ) =>
+              ({
+                ...node,
+                provider,
+                resource,
+                bindings: bindingDiffs,
+                downstream,
+              }) as any as T;
+
+            // Plan against the persisted state we have, not the ideal final state we
+            // hoped to reach last time. Recovery is expressed by mapping each
+            // intermediate state back onto a fresh CRUD action.
+            if (oldState === undefined) {
+              return Node<Create>({
+                action: "create",
+                props: news,
+                state: oldState,
+              });
+            } else if (
+              oldState.status === "creating" &&
+              oldState.attr === undefined
+            ) {
+              // A create may have succeeded before state persistence failed. If the
+              // provider can recover an attribute snapshot, keep driving the same
+              // create instead of starting over blindly.
+              if (provider.read) {
+                const attr = yield* provider
+                  .read({
                     id,
-                    olds: oldProps,
                     instanceId: oldState.instanceId,
+                    olds: oldState.props,
                     output: oldState.attr,
-                    news,
-                    oldBindings,
-                    newBindings,
                   })
-                  .pipe(providePlanScope(fqn, oldState.instanceId)),
-              ).pipe(
-                Effect.map(
-                  (diff) =>
-                    diff ??
-                    ({
-                      action:
-                        havePropsChanged(oldProps, news) ||
-                        bindingDiffs.some((b) => b.action !== "noop")
-                          ? "update"
-                          : "noop",
-                    } as UpdateDiff | NoopDiff),
-                ),
-                Effect.map((diff) =>
-                  options.force && diff.action === "noop"
-                    ? ({
-                        action: "update",
-                      } satisfies UpdateDiff)
-                    : diff,
-                ),
-              );
-
-              if (oldState.status === "creating") {
-                if (diff.action === "noop") {
-                  // we're in the creating state and props are un-changed
-                  // let's just continue where we left off
-                  return Node<Create>({
-                    action: "create",
-                    props: news,
-                    state: oldState,
-                  });
-                } else if (diff.action === "update") {
-                  // props have changed in a way that is updatable
-                  // again, just continue with the create
-                  // TODO(sam): should we maybe try an update instead?
+                  .pipe(providePlanScope(fqn, oldState.instanceId));
+                if (attr) {
                   return Node<Create>({
                     action: "create",
                     props: news,
-                    state: oldState,
-                  });
-                } else {
-                  // props have changed in an incompatible way
-                  // because it's possible that an un-updatable resource has already been created
-                  // we must use a replace step to create a new one and delete the potential old one
-                  return Node<Replace>({
-                    action: "replace",
-                    props: news,
-                    deleteFirst: diff.deleteFirst ?? false,
-                    state: oldState,
-                  });
-                }
-              } else if (oldState.status === "updating") {
-                // Updating already targets the live resource, so noop/update both mean
-                // "finish the interrupted update". Only a replace diff escalates it
-                // into a fresh replacement.
-                if (diff.action === "update" || diff.action === "noop") {
-                  // we can continue where we left off
-                  return Node<Update>({
-                    action: "update",
-                    props: news,
-                    state: oldState,
-                  });
-                } else {
-                  // we started to update a resource but now believe we should replace it
-                  return Node<Replace>({
-                    action: "replace",
-                    deleteFirst: diff.deleteFirst ?? false,
-                    props: news,
-                    // TODO(sam): can Apply handle replacements when the oldState is UpdatingResourceState?
-                    // -> or should we do a provider.read to try and reconcile back to UpdatedResourceState?
-                    state: oldState,
-                  });
-                }
-              } else if (oldState.status === "replacing") {
-                // The replacement candidate is still being created. Noop/update keep
-                // driving the same generation; replace means that candidate itself is
-                // now obsolete and must be wrapped in a new outer generation.
-                if (diff.action === "noop") {
-                  // this is the stable case - noop means just continue with the replacement
-                  return Node<Replace>({
-                    action: "replace",
-                    deleteFirst: oldState.deleteFirst,
-                    props: news,
-                    state: oldState,
-                  });
-                } else if (diff.action === "update") {
-                  // potential problem here - the props have changed since we tried to replace,
-                  // but not enough to trigger another replacement. the resource provider should
-                  // be designed as idempotent to converge to the right state when creating the new resource
-                  // the newly generated instanceId is intended to assist with this
-                  return Node<Replace>({
-                    action: "replace",
-                    deleteFirst: oldState.deleteFirst,
-                    props: news,
-                    state: oldState,
-                  });
-                } else {
-                  // The in-flight replacement candidate itself now needs replacement.
-                  // Mark this as a restart so Apply creates a fresh generation instead
-                  // of resuming the old replacement instance.
-                  return Node<Replace>({
-                    restart: true,
-                    action: "replace",
-                    deleteFirst: diff.deleteFirst ?? oldState.deleteFirst,
-                    props: news,
-                    state: oldState,
-                  });
-                }
-              } else if (oldState.status === "replaced") {
-                // The new resource already exists. Noop means "just let GC finish",
-                // update means "mutate the current replacement before GC finishes",
-                // and replace means "the current replacement also became obsolete".
-                if (diff.action === "noop") {
-                  // this is the stable case - noop means just continue cleaning up the replacement
-                  return Node<Replace>({
-                    action: "replace",
-                    deleteFirst: oldState.deleteFirst,
-                    props: news,
-                    state: oldState,
-                  });
-                } else if (diff.action === "update") {
-                  // the replacement has been created but now also needs to be updated
-                  // the resource provider should:
-                  // 1. Update the newly created replacement resource
-                  // 2. Then proceed as normal to delete the replaced resources (after all downstream references are updated)
-                  return Node<Update>({
-                    action: "update",
-                    props: news,
-                    state: oldState,
-                  });
-                } else {
-                  // Cleanup is still pending, but the current "new" resource has already
-                  // become obsolete. Start another replacement generation and preserve
-                  // the existing replaced node as part of the recursive old chain.
-                  return Node<Replace>({
-                    restart: true,
-                    action: "replace",
-                    deleteFirst: diff.deleteFirst ?? oldState.deleteFirst,
-                    props: news,
-                    state: oldState,
+                    state: { ...oldState, attr },
                   });
                 }
-              } else if (oldState.status === "deleting") {
-                // we're in a partially deleted state, it is unclear whether it was or was not deleted
-                // so continue by re-creating it with the same instanceId and desired props
+              }
+            }
+
+            // Diff against whatever props represent the best-known current attempt.
+            // For replacement recovery that means the top-level replacement props,
+            // not the older generations stored under `old`.
+            const oldProps = oldState.props;
+
+            const diff = yield* asEffect(
+              provider
+                ?.diff?.({
+                  id,
+                  olds: oldProps,
+                  instanceId: oldState.instanceId,
+                  output: oldState.attr,
+                  news,
+                  oldBindings,
+                  newBindings,
+                })
+                .pipe(providePlanScope(fqn, oldState.instanceId)),
+            ).pipe(
+              Effect.map(
+                (diff) =>
+                  diff ??
+                  ({
+                    action:
+                      havePropsChanged(oldProps, news) ||
+                      bindingDiffs.some((b) => b.action !== "noop")
+                        ? "update"
+                        : "noop",
+                  } as UpdateDiff | NoopDiff),
+              ),
+              Effect.map((diff) =>
+                options.force && diff.action === "noop"
+                  ? ({
+                      action: "update",
+                    } satisfies UpdateDiff)
+                  : diff,
+              ),
+            );
+
+            if (oldState.status === "creating") {
+              if (diff.action === "noop") {
+                // we're in the creating state and props are un-changed
+                // let's just continue where we left off
                 return Node<Create>({
                   action: "create",
                   props: news,
-                  state: {
-                    ...oldState,
-                    status: "creating",
-                    props: news,
-                  },
+                  state: oldState,
                 });
               } else if (diff.action === "update") {
-                // Stable created/updated resources follow the normal CRUD mapping.
+                // props have changed in a way that is updatable
+                // again, just continue with the create
+                // TODO(sam): should we maybe try an update instead?
+                return Node<Create>({
+                  action: "create",
+                  props: news,
+                  state: oldState,
+                });
+              } else {
+                // props have changed in an incompatible way
+                // because it's possible that an un-updatable resource has already been created
+                // we must use a replace step to create a new one and delete the potential old one
+                return Node<Replace>({
+                  action: "replace",
+                  props: news,
+                  deleteFirst: diff.deleteFirst ?? false,
+                  state: oldState,
+                });
+              }
+            } else if (oldState.status === "updating") {
+              // Updating already targets the live resource, so noop/update both mean
+              // "finish the interrupted update". Only a replace diff escalates it
+              // into a fresh replacement.
+              if (diff.action === "update" || diff.action === "noop") {
+                // we can continue where we left off
                 return Node<Update>({
                   action: "update",
                   props: news,
                   state: oldState,
                 });
-              } else if (diff.action === "replace") {
+              } else {
+                // we started to update a resource but now believe we should replace it
+                return Node<Replace>({
+                  action: "replace",
+                  deleteFirst: diff.deleteFirst ?? false,
+                  props: news,
+                  // TODO(sam): can Apply handle replacements when the oldState is UpdatingResourceState?
+                  // -> or should we do a provider.read to try and reconcile back to UpdatedResourceState?
+                  state: oldState,
+                });
+              }
+            } else if (oldState.status === "replacing") {
+              // The replacement candidate is still being created. Noop/update keep
+              // driving the same generation; replace means that candidate itself is
+              // now obsolete and must be wrapped in a new outer generation.
+              if (diff.action === "noop") {
+                // this is the stable case - noop means just continue with the replacement
+                return Node<Replace>({
+                  action: "replace",
+                  deleteFirst: oldState.deleteFirst,
+                  props: news,
+                  state: oldState,
+                });
+              } else if (diff.action === "update") {
+                // potential problem here - the props have changed since we tried to replace,
+                // but not enough to trigger another replacement. the resource provider should
+                // be designed as idempotent to converge to the right state when creating the new resource
+                // the newly generated instanceId is intended to assist with this
                 return Node<Replace>({
                   action: "replace",
+                  deleteFirst: oldState.deleteFirst,
                   props: news,
                   state: oldState,
-                  deleteFirst: diff?.deleteFirst ?? false,
                 });
               } else {
-                return Node<NoopUpdate>({
-                  action: "noop",
+                // The in-flight replacement candidate itself now needs replacement.
+                // Mark this as a restart so Apply creates a fresh generation instead
+                // of resuming the old replacement instance.
+                return Node<Replace>({
+                  restart: true,
+                  action: "replace",
+                  deleteFirst: diff.deleteFirst ?? oldState.deleteFirst,
+                  props: news,
                   state: oldState,
                 });
               }
-            }),
+            } else if (oldState.status === "replaced") {
+              // The new resource already exists. Noop means "just let GC finish",
+              // update means "mutate the current replacement before GC finishes",
+              // and replace means "the current replacement also became obsolete".
+              if (diff.action === "noop") {
+                // this is the stable case - noop means just continue cleaning up the replacement
+                return Node<Replace>({
+                  action: "replace",
+                  deleteFirst: oldState.deleteFirst,
+                  props: news,
+                  state: oldState,
+                });
+              } else if (diff.action === "update") {
+                // the replacement has been created but now also needs to be updated
+                // the resource provider should:
+                // 1. Update the newly created replacement resource
+                // 2. Then proceed as normal to delete the replaced resources (after all downstream references are updated)
+                return Node<Update>({
+                  action: "update",
+                  props: news,
+                  state: oldState,
+                });
+              } else {
+                // Cleanup is still pending, but the current "new" resource has already
+                // become obsolete. Start another replacement generation and preserve
+                // the existing replaced node as part of the recursive old chain.
+                return Node<Replace>({
+                  restart: true,
+                  action: "replace",
+                  deleteFirst: diff.deleteFirst ?? oldState.deleteFirst,
+                  props: news,
+                  state: oldState,
+                });
+              }
+            } else if (oldState.status === "deleting") {
+              // we're in a partially deleted state, it is unclear whether it was or was not deleted
+              // so continue by re-creating it with the same instanceId and desired props
+              return Node<Create>({
+                action: "create",
+                props: news,
+                state: {
+                  ...oldState,
+                  status: "creating",
+                  props: news,
+                },
+              });
+            } else if (diff.action === "update") {
+              // Stable created/updated resources follow the normal CRUD mapping.
+              return Node<Update>({
+                action: "update",
+                props: news,
+                state: oldState,
+              });
+            } else if (diff.action === "replace") {
+              return Node<Replace>({
+                action: "replace",
+                props: news,
+                state: oldState,
+                deleteFirst: diff?.deleteFirst ?? false,
+              });
+            } else {
+              return Node<NoopUpdate>({
+                action: "noop",
+                state: oldState,
+              });
+            }
+          }),
+        ),
+        { concurrency: "unbounded" },
+      )).map((update) => [update.resource.FQN, update]),
+    ) as Plan["resources"];
+
+    // Detect unsatisfiable dependency cycles among create/replace nodes.
+    // Update/noop nodes signal their Deferred before waitForDeps so they
+    // cannot deadlock. Create/replace nodes only signal early when they
+    // have a precreate handler. Simulate the concurrent execution:
+    // precreate nodes are immediately "resolved", then iteratively resolve
+    // any node whose deps are all resolved. Remaining nodes would deadlock.
+    {
+      const createReplaceNodes = new Set(
+        Object.entries(resourceGraph)
+          .filter(
+            ([_, node]) =>
+              node.action === "create" || node.action === "replace",
+          )
+          .map(([fqn]) => fqn),
+      );
+
+      if (createReplaceNodes.size > 0) {
+        const hasPrecreate = new Set(
+          [...createReplaceNodes].filter(
+            (fqn) => !!resourceGraph[fqn]?.provider?.precreate,
           ),
-          { concurrency: "unbounded" },
-        )).map((update) => [update.resource.FQN, update]),
-      ) as Plan["resources"];
-
-      // Detect unsatisfiable dependency cycles among create/replace nodes.
-      // Update/noop nodes signal their Deferred before waitForDeps so they
-      // cannot deadlock. Create/replace nodes only signal early when they
-      // have a precreate handler. Simulate the concurrent execution:
-      // precreate nodes are immediately "resolved", then iteratively resolve
-      // any node whose deps are all resolved. Remaining nodes would deadlock.
-      {
-        const createReplaceNodes = new Set(
-          Object.entries(resourceGraph)
-            .filter(
-              ([_, node]) =>
-                node.action === "create" || node.action === "replace",
-            )
-            .map(([fqn]) => fqn),
         );
 
-        if (createReplaceNodes.size > 0) {
-          const hasPrecreate = new Set(
-            [...createReplaceNodes].filter(
-              (fqn) => !!resourceGraph[fqn]?.provider?.precreate,
-            ),
-          );
-
-          const resolved = new Set(hasPrecreate);
-          let changed = true;
-          while (changed) {
-            changed = false;
-            for (const fqn of createReplaceNodes) {
-              if (resolved.has(fqn)) continue;
-              const deps = (allUpstreamDependencies[fqn] ?? []).filter((dep) =>
-                createReplaceNodes.has(dep),
-              );
-              if (deps.every((dep) => resolved.has(dep))) {
-                resolved.add(fqn);
-                changed = true;
-              }
+        const resolved = new Set(hasPrecreate);
+        let changed = true;
+        while (changed) {
+          changed = false;
+          for (const fqn of createReplaceNodes) {
+            if (resolved.has(fqn)) continue;
+            const deps = (allUpstreamDependencies[fqn] ?? []).filter((dep) =>
+              createReplaceNodes.has(dep),
+            );
+            if (deps.every((dep) => resolved.has(dep))) {
+              resolved.add(fqn);
+              changed = true;
             }
           }
+        }
 
-          const deadlocked = [...createReplaceNodes].filter(
-            (fqn) => !resolved.has(fqn),
+        const deadlocked = [...createReplaceNodes].filter(
+          (fqn) => !resolved.has(fqn),
+        );
+        if (deadlocked.length > 0) {
+          const missingPrecreate = deadlocked.filter(
+            (fqn) => !hasPrecreate.has(fqn),
+          );
+          return yield* Effect.die(
+            new UnsatisfiedResourceCycle({
+              message:
+                `Circular dependency detected that cannot be resolved: [${deadlocked.join(", ")}]. ` +
+                `Resources lacking a precreate handler: [${missingPrecreate.join(", ")}]. ` +
+                `All resources in a dependency cycle must implement precreate to allow early signaling.`,
+              cycle: deadlocked,
+              missingPrecreate,
+            }),
           );
-          if (deadlocked.length > 0) {
-            const missingPrecreate = deadlocked.filter(
-              (fqn) => !hasPrecreate.has(fqn),
-            );
-            return yield* Effect.die(
-              new UnsatisfiedResourceCycle({
-                message:
-                  `Circular dependency detected that cannot be resolved: [${deadlocked.join(", ")}]. ` +
-                  `Resources lacking a precreate handler: [${missingPrecreate.join(", ")}]. ` +
-                  `All resources in a dependency cycle must implement precreate to allow early signaling.`,
-                cycle: deadlocked,
-                missingPrecreate,
-              }),
-            );
-          }
         }
       }
+    }
 
-      const deletions = Object.fromEntries(
-        (yield* Effect.all(
-          (yield* state.list({ stack: stackName, stage: stage })).map(
-            Effect.fn(function* (fqn) {
-              // Check if this FQN is in the new resources
-              if (newResourceFqns.has(fqn)) {
-                return;
-              }
-              const oldState = yield* state.get({
-                stack: stackName,
-                stage: stage,
-                fqn,
-              });
-              let attr: any = oldState?.attr;
-              if (oldState) {
-                const { logicalId } = parseFqn(fqn);
-                const resourceType = oldState.resourceType;
-                const provider = yield* getProviderByType(resourceType);
-                if (oldState.attr === undefined) {
-                  if (provider.read) {
-                    attr = yield* provider
-                      .read({
-                        id: logicalId,
-                        instanceId: oldState.instanceId,
-                        olds: oldState.props as never,
-                        output: oldState.attr as never,
-                      })
-                      .pipe(providePlanScope(fqn, oldState.instanceId));
-                  }
+    const deletions = Object.fromEntries(
+      (yield* Effect.all(
+        (yield* state.list({ stack: stackName, stage: stage })).map(
+          Effect.fn(function* (fqn) {
+            // Check if this FQN is in the new resources
+            if (newResourceFqns.has(fqn)) {
+              return;
+            }
+            const oldState = yield* state.get({
+              stack: stackName,
+              stage: stage,
+              fqn,
+            });
+            let attr: any = oldState?.attr;
+            if (oldState) {
+              const { logicalId } = parseFqn(fqn);
+              const resourceType = oldState.resourceType;
+              const provider = yield* findProviderByType(resourceType);
+              if (oldState.attr === undefined) {
+                if (provider.read) {
+                  attr = yield* provider
+                    .read({
+                      id: logicalId,
+                      instanceId: oldState.instanceId,
+                      olds: oldState.props as never,
+                      output: oldState.attr as never,
+                    })
+                    .pipe(providePlanScope(fqn, oldState.instanceId));
                 }
-                return [
-                  fqn,
-                  {
-                    action: "delete",
-                    state: { ...oldState, attr },
-                    provider: provider,
-                    resource: {
-                      Namespace: oldState.namespace,
-                      FQN: fqn,
-                      LogicalId: logicalId,
-                      Type: oldState.resourceType,
-                      Attributes: attr,
-                      Props: oldState.props,
-                      Binding: undefined!,
-                      Provider: Provider(resourceType),
-                      RemovalPolicy: oldState.removalPolicy,
-                      ExecutionContext: undefined!,
-                    } as ResourceLike,
-                    downstream: oldDownstreamDependencies[fqn] ?? [],
-                    bindings: oldState.bindings.map((binding) => ({
-                      sid: binding.sid,
-                      action: "delete" as const,
-                      data: binding.data,
-                    })),
-                  } satisfies Delete,
-                ] as const;
               }
-            }),
-          ),
-          { concurrency: "unbounded" },
-        )).filter((v) => !!v),
-      );
-
-      for (const resourceFqn of Object.keys(deletions)) {
-        const dependencies = Object.entries(rawUpstreamDependencies)
-          .filter(
-            ([survivorFqn, upstream]) =>
-              survivorFqn in resourceGraph && upstream.includes(resourceFqn),
-          )
-          .map(([survivorFqn]) => survivorFqn);
-        if (dependencies.length > 0) {
-          return yield* new DeleteResourceHasDownstreamDependencies({
-            message: `Resource ${resourceFqn} has downstream dependencies`,
-            resourceId: resourceFqn,
-            dependencies,
-          });
-        }
+              return [
+                fqn,
+                {
+                  action: "delete",
+                  state: { ...oldState, attr },
+                  provider: provider,
+                  resource: {
+                    Namespace: oldState.namespace,
+                    FQN: fqn,
+                    LogicalId: logicalId,
+                    Type: oldState.resourceType,
+                    Attributes: attr,
+                    Props: oldState.props,
+                    Binding: undefined!,
+                    Provider: Provider(resourceType),
+                    RemovalPolicy: oldState.removalPolicy,
+                    ExecutionContext: undefined!,
+                    Providers: undefined,
+                  } as ResourceLike,
+                  downstream: oldDownstreamDependencies[fqn] ?? [],
+                  bindings: oldState.bindings.map((binding) => ({
+                    sid: binding.sid,
+                    action: "delete" as const,
+                    data: binding.data,
+                  })),
+                } satisfies Delete,
+              ] as const;
+            }
+          }),
+        ),
+        { concurrency: "unbounded" },
+      )).filter((v) => !!v),
+    );
+
+    for (const resourceFqn of Object.keys(deletions)) {
+      const dependencies = Object.entries(rawUpstreamDependencies)
+        .filter(
+          ([survivorFqn, upstream]) =>
+            survivorFqn in resourceGraph && upstream.includes(resourceFqn),
+        )
+        .map(([survivorFqn]) => survivorFqn);
+      if (dependencies.length > 0) {
+        return yield* new DeleteResourceHasDownstreamDependencies({
+          message: `Resource ${resourceFqn} has downstream dependencies`,
+          resourceId: resourceFqn,
+          dependencies,
+        });
       }
+    }
 
-      return {
-        resources: resourceGraph,
-        deletions,
-        output: stack.output,
-      } satisfies Plan<A> as Plan<A>;
-    }),
-  );
+    return {
+      resources: resourceGraph,
+      deletions,
+      output: stack.output,
+    } satisfies Plan<A> as Plan<A>;
+  }).pipe(ensureArtifactStore);
 
 const providePlanScope =
   (fqn: string, instanceId: string) =>