alchemy 2.0.0-beta.65 → 2.0.0-beta.66

package/src/Local/RpcServer.ts

@@ -30,6 +30,17 @@ export class RpcServer extends Context.Service<RpcServer, never>()(
   "alchemy/Local/RpcServer",
 ) {}
 
+/**
+ * The provider shape served over RPC. The `mode`/`modes` variant machinery
+ * (lazy Layer-built Effects, see `ProviderLayer.dual`) is process-local and
+ * cannot cross the RPC boundary — the sidecar serves the concrete provider
+ * implementation, never the mode-dispatching wrapper.
+ */
+export type RpcProviderService<R extends ResourceLike> = Omit<
+  ProviderService<R>,
+  "mode" | "modes"
+>;
+
 /**
  * The RPC API that is implemented by the server and consumed by {@link RpcProviderProxy}.
  */
@@ -40,7 +51,7 @@ export interface RpcProxyApi {
    */
   readonly getProvider: <R extends ResourceLike>(
     type: R["Type"],
-  ) => Promise<RpcSerialization.RpcWrapped<ProviderService<R>>>;
+  ) => Promise<RpcSerialization.RpcWrapped<RpcProviderService<R>>>;
 }
 
 const serverPlatformLayer = platformLayer({
@@ -128,8 +139,15 @@ export const layerServer = (
               if (!provider) {
                 throw new Error(`Provider "${type}" not found`);
               }
+              // Strip the process-local variant machinery (see
+              // RpcProviderService above) — lazy Effects don't serialize.
+              const {
+                mode: _mode,
+                modes: _modes,
+                ...serializable
+              } = provider as ProviderService<R>;
               return RpcSerialization.wrapRpcHandlers(
-                provider as ProviderService<R>,
+                serializable as RpcProviderService<R>,
                 ["tail"],
               );
             },

package/src/Plan.ts

@@ -28,6 +28,7 @@ import {
   havePropsChanged,
   isResolved,
   type NoopDiff,
+  type ReplaceDiff,
   type UpdateDiff,
 } from "./Diff.ts";
 import { parseFqn } from "./FQN.ts";
@@ -37,9 +38,11 @@ import {
   findProviderByType,
   missingProviderError,
   Provider,
+  providerForMode,
   tryFindProviderByType,
   type ProviderService,
 } from "./Provider.ts";
+import { defaultProviderMode, type ProviderMode } from "./ProviderMode.ts";
 import {
   isResource,
   type ResourceBinding,
@@ -103,6 +106,14 @@ export interface BaseNode<
 > {
   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"]>[];
 }
@@ -119,6 +130,8 @@ export interface Update<
   R extends ResourceLike = ResourceLike,
 > extends BaseNode<R> {
   action: "update";
+  /** True while this is the first reconcile after a cold adoption. */
+  adopting?: boolean;
   props: R["Props"];
   state:
     | CreatedResourceState
@@ -229,6 +242,13 @@ export type Plan<Output = any> = {
    * publish a fresh attr (the common, linear case).
    */
   cycleMembers: ReadonlySet<string>;
+  /**
+   * 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;
 };
 
 export interface MakePlanOptions {
@@ -264,6 +284,48 @@ export const make = <A>(
       });
     });
 
+    // 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* findProviderByType(resource.Type);
+      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 (legacy rows, or rows
+     * written by a mode-agnostic provider) are assumed to already be in
+     * the current run's mode — no replacement churn.
+     */
+    const hasModeSwitched = (
+      mode: ProviderMode | undefined,
+      oldState: ResourceState | undefined,
+    ): boolean =>
+      mode !== undefined &&
+      oldState?.providerMode !== undefined &&
+      oldState.providerMode !== mode;
+
     const resourceFqns = yield* state.list({
       stack: stackName,
       stage: stage,
@@ -293,7 +355,8 @@ export const make = <A>(
             Effect.gen(function* () {
               const resource = resourceExpr.src;
 
-              const provider = yield* findProviderByType(resource.Type);
+              const { provider, mode } =
+                yield* resolveProviderAndMode(resource);
               const props = yield* resolveInput(resource.Props);
               const persisted = yield* state.get({
                 stack: stackName,
@@ -310,6 +373,13 @@ export const make = <A>(
                 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
@@ -694,7 +764,7 @@ export const make = <A>(
       (yield* Effect.all(
         resources.map(
           Effect.fn("plan.diff.resource")(function* (resource) {
-            const provider = yield* findProviderByType(resource.Type);
+            const { provider, mode } = yield* resolveProviderAndMode(resource);
             const id = resource.LogicalId;
             const fqn = resource.FQN;
             const news = yield* resolveInput(resource.Props);
@@ -806,6 +876,7 @@ export const make = <A>(
                   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`
@@ -823,10 +894,19 @@ export const make = <A>(
             const oldBindings = dedupeBindings(oldState?.bindings ?? []);
             const bindingDiffs = diffBindings(oldBindings, newBindings);
 
+            // 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
+            // new mode's provider, and Apply deletes the old generation
+            // with the provider of the mode that created it (see
+            // `deleteOldGenerations` / `collectGarbage`).
+            const modeSwitched = hasModeSwitched(mode, oldState);
+
             const Node = <T extends Apply>(
               node: Omit<
                 T,
-                "provider" | "resource" | "bindings" | "downstream"
+                "provider" | "resource" | "bindings" | "downstream" | "mode"
               >,
             ) =>
               ({
@@ -835,6 +915,7 @@ export const make = <A>(
                 resource,
                 bindings: bindingDiffs,
                 downstream,
+                mode,
               }) as any as T;
 
             // Plan against the persisted state we have, not the ideal final state we
@@ -847,6 +928,7 @@ export const make = <A>(
                 state: oldState,
               });
             } else if (
+              !modeSwitched &&
               oldState.status === "creating" &&
               oldState.attr === undefined
             ) {
@@ -871,7 +953,7 @@ export const make = <A>(
                     output: oldState.attr,
                   })
                   .pipe(providePlanScope(fqn, oldState.instanceId));
-                if (attr) {
+                if (attr !== undefined) {
                   // The recovered resource may be foreign: our interrupted
                   // create could have lost a name race, or died before
                   // stamping ownership. Route `Unowned` through the same
@@ -894,11 +976,12 @@ export const make = <A>(
                       });
                     }
                   }
-                  return Node<Create>({
-                    action: "create",
-                    props: news,
-                    state: { ...oldState, attr: stripUnowned(attr) },
-                  });
+                  // Continue through the normal diff below with the recovered
+                  // live snapshot. Desired props may have changed while the
+                  // previous create was interrupted; bypassing diff here can
+                  // drive an immutable change through reconcile and falsely
+                  // persist the old physical resource as converged.
+                  oldState = { ...oldState, attr: stripUnowned(attr) };
                 }
               }
             }
@@ -908,50 +991,59 @@ export const make = <A>(
             // not the older generations stored under `old`.
             const oldProps = oldState.props;
 
-            const diff = yield* asEffect(
-              provider
-                ?.diff?.({
-                  id,
-                  fqn,
-                  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,
-              ),
-              // After a cold-start adoption (silent or takeover), force at
-              // least an update so the provider re-syncs ownership tags /
-              // config against the desired props (otherwise the engine
-              // would noop and any drift between the existing cloud
-              // resource and `news` — including foreign-owned tags after a
-              // takeover — would persist).
-              Effect.map((diff) =>
-                forceUpdateAfterAdoption && diff.action === "noop"
-                  ? ({ action: "update" } satisfies UpdateDiff)
-                  : diff,
-              ),
-            );
+            // On a mode switch the provider diff is skipped entirely:
+            // comparing props across runtimes is meaningless (and the new
+            // mode's provider has never seen the old mode's state). The
+            // action is a replacement by definition.
+            const diff = modeSwitched
+              ? ({
+                  action: "replace",
+                  deleteFirst: false,
+                } satisfies ReplaceDiff)
+              : yield* asEffect(
+                  provider
+                    ?.diff?.({
+                      id,
+                      fqn,
+                      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,
+                  ),
+                  // After a cold-start adoption (silent or takeover), force at
+                  // least an update so the provider re-syncs ownership tags /
+                  // config against the desired props (otherwise the engine
+                  // would noop and any drift between the existing cloud
+                  // resource and `news` — including foreign-owned tags after a
+                  // takeover — would persist).
+                  Effect.map((diff) =>
+                    forceUpdateAfterAdoption && diff.action === "noop"
+                      ? ({ action: "update" } satisfies UpdateDiff)
+                      : diff,
+                  ),
+                );
 
             if (oldState.status === "creating") {
               if (diff.action === "noop") {
@@ -1089,6 +1181,7 @@ export const make = <A>(
               // Stable created/updated resources follow the normal CRUD mapping.
               return Node<Update>({
                 action: "update",
+                adopting: forceUpdateAfterAdoption,
                 props: news,
                 state: oldState,
               });
@@ -1308,7 +1401,15 @@ export const make = <A>(
               // the provider the row's physical resource cannot be deleted
               // anyway. Die at plan time with a typed error naming the row
               // and the remediation instead of limping into a partial apply.
-              const providerOption = yield* tryFindProviderByType(resourceType);
+              //
+              // Orphan deletes resolve the provider variant for the mode
+              // that created the row (`providerMode`), so e.g. a local dev
+              // worker's row is deleted by the local provider even during a
+              // live deploy — and vice versa.
+              const providerOption = yield* tryFindProviderByType(
+                resourceType,
+                oldState.providerMode,
+              );
               if (Option.isNone(providerOption)) {
                 return yield* Effect.die(
                   missingProviderError(resourceType, fqn),
@@ -1326,6 +1427,7 @@ export const make = <A>(
                   action: "delete",
                   state: oldState,
                   provider: provider,
+                  mode: oldState.providerMode,
                   resource: {
                     Namespace: oldState.namespace,
                     FQN: fqn,
@@ -1337,6 +1439,7 @@ export const make = <A>(
                     Provider: Provider(resourceType),
                     RemovalPolicy: oldState.removalPolicy,
                     Adopt: undefined,
+                    Mode: oldState.providerMode,
                     RuntimeContext: undefined!,
                     Providers: undefined,
                   } as ResourceLike,
@@ -1391,6 +1494,31 @@ export const make = <A>(
     }),
   );
 
+/**
+ * Build the plan that destroys every resource of `(stack.name, stack.stage)`.
+ *
+ * The spec is emptied out so every persisted resource becomes an orphan
+ * deletion, and `output` is left undefined so `apply` does not overwrite the
+ * last deploy's persisted stack output with an empty husk. `apply` recognizes
+ * the `destroy` marker and deletes the stage's remaining persisted state (the
+ * stack output record) once the destroy has converged, so `state.getOutput`
+ * and `state.listStages` agree the stage is gone.
+ *
+ * @see https://github.com/alchemy-run/alchemy/issues/961
+ */
+export const destroy = (stack: {
+  name: string;
+  stage: string;
+}): Effect.Effect<Plan<undefined>, never, State> =>
+  make({
+    name: stack.name,
+    stage: stack.stage,
+    resources: {},
+    bindings: {},
+    actions: {},
+    output: undefined,
+  }).pipe(Effect.map((plan) => ({ ...plan, destroy: true })));
+
 const providePlanScope =
   (fqn: string, instanceId: string) =>
   <A, E, R>(

package/src/Planetscale/AuthProvider.ts

@@ -199,10 +199,23 @@ export const PlanetscaleAuth = AuthProviderLayer<
           ),
         );
         yield* Clank.info(
-          "Planetscale: waiting for authorization (up to 5 minutes)...",
+          "Planetscale: waiting for authorization (up to 5 minutes).",
         );
 
-        const credentials = yield* OAuthClient.callback(authorization);
+        const credentials = yield* Effect.raceFirst(
+          OAuthClient.callback(authorization),
+          Clank.text({
+            message: "Paste the authorization code or callback URL",
+            placeholder:
+              "The browser will complete this automatically when local",
+            validate: (value) =>
+              value.trim().length > 0 ? undefined : "Paste a code or URL",
+          }).pipe(
+            Effect.flatMap((input) =>
+              OAuthClient.exchangeCallbackInput(input, authorization),
+            ),
+          ),
+        );
         yield* store.write(profileName, "planetscale-oauth", credentials);
         yield* Clank.success("Planetscale: OAuth credentials saved.");
         return credentials;

package/src/Planetscale/Branch.ts

@@ -4,7 +4,7 @@ import * as Effect from "effect/Effect";
 import * as Schedule from "effect/Schedule";
 import * as Stream from "effect/Stream";
 import { Unowned } from "../AdoptPolicy.ts";
-import { isResolved } from "../Diff.ts";
+import { havePropsChanged, isResolved } from "../Diff.ts";
 import { createPhysicalName } from "../PhysicalName.ts";
 import * as Provider from "../Provider.ts";
 import type { ResourceClass, ResourceLike } from "../Resource.ts";
@@ -263,6 +263,29 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
     diff: Effect.fn(function* ({ news, olds, output }: any) {
       if (!isResolved(news)) return undefined;
 
+      // Branch names are rename-mutable (reconcile syncs `news.name` in
+      // place), so `name` cannot live in the provider-level stables. But
+      // almost no update is a rename — for those, advertise `name` as
+      // stable on the update so downstream consumers referencing this
+      // branch still resolve `branch.name` at plan time. Without it, a
+      // metadata-only update (e.g. an embedded database ref whose
+      // `migrationsHashes` moved) resolves consumer refs to just
+      // `{ organization, database }`, and identity-sensitive consumers
+      // (PostgresRole) falsely plan a replacement against `name: undefined`.
+      //
+      // The name only changes when the `name` prop itself changes: an
+      // explicit name renames iff it differs from the observed name, and
+      // an omitted name is engine-generated deterministically (stable
+      // across updates — the instance id only rotates on replacement).
+      const nameIsStable =
+        output?.name !== undefined &&
+        (news.name !== undefined
+          ? news.name === output.name
+          : olds?.name === undefined);
+      const stables = nameIsStable
+        ? ["organization", "database", "name"]
+        : undefined;
+
       const newDb = resolveDatabase(news.database).name;
       const oldDbRef = output?.database ?? olds.database;
       if (oldDbRef) {
@@ -289,7 +312,7 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
 
       if (news.replicas !== undefined) {
         if (output?.desiredReplicas !== news.replicas) {
-          return { action: "update" } as const;
+          return { action: "update", stables } as const;
         }
 
         const desiredHasReplicas = news.replicas > 0;
@@ -297,29 +320,39 @@ export const makeBranchProvider = <R extends ResourceLike>(opts: {
           output?.hasReplicas !== undefined &&
           output.hasReplicas !== desiredHasReplicas
         ) {
-          return { action: "update" } as const;
+          return { action: "update", stables } as const;
         }
       }
 
       if (news.migrationsDir) {
         const newHashes = yield* hashMigrations(news.migrationsDir);
         if (!recordsEqual(newHashes, output?.migrationsHashes ?? {})) {
-          return { action: "update" } as const;
+          return { action: "update", stables } as const;
         }
         if (
           (news.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE) !==
           (output?.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE)
         ) {
-          return { action: "update" } as const;
+          return { action: "update", stables } as const;
         }
       }
       if (news.importFiles?.length) {
         const newHashes = yield* hashImports(news.importFiles, yield* rootDir);
         if (!recordsEqual(newHashes, output?.importHashes ?? {})) {
-          return { action: "update" } as const;
+          return { action: "update", stables } as const;
         }
       }
 
+      // Remaining prop changes (rename, safeMigrations, clusterSize,
+      // metadata embedded in resource refs) are all in-place updates.
+      // Decide them here instead of falling back to the engine's default
+      // deep-compare so the conditional `name` stable above is attached —
+      // the default path uses the provider-level stables, which strip
+      // `name` from downstream plan resolution.
+      if (havePropsChanged(olds, news)) {
+        return { action: "update", stables } as const;
+      }
+
       return undefined;
     }),
 

package/src/Planetscale/MySQL/MySQLDatabase.ts

@@ -2,7 +2,7 @@ import { Credentials } from "@distilled.cloud/planetscale/Credentials";
 import * as planetscale from "@distilled.cloud/planetscale/Operations";
 import * as Effect from "effect/Effect";
 import * as Stream from "effect/Stream";
-import { isResolved } from "../../Diff.ts";
+import { havePropsChanged, isResolved } from "../../Diff.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
@@ -178,6 +178,25 @@ export const MySQLDatabaseProvider = () =>
     diff: Effect.fn(function* ({ news, olds, output }) {
       if (!isResolved(news)) return undefined;
 
+      // Database names are rename-mutable (reconcile folds `new_name`
+      // into the settings sync), so `name` cannot live in the
+      // provider-level stables. Almost no update is a rename though —
+      // for those, advertise `name` as stable on the update so
+      // downstream consumers (branches, passwords) still resolve
+      // `database.name` at plan time instead of seeing `undefined` and
+      // falsely planning a replacement. The name only changes when the
+      // `name` prop itself changes: an explicit name renames iff it
+      // differs from the observed name, and an omitted name is
+      // engine-generated deterministically (stable across updates).
+      const nameIsStable =
+        output?.name !== undefined &&
+        (news.name !== undefined
+          ? news.name === output.name
+          : olds?.name === undefined);
+      const stables = nameIsStable
+        ? ["id", "organization", "region", "name"]
+        : undefined;
+
       if (
         news.region?.slug !== undefined &&
         output?.region?.slug !== undefined &&
@@ -192,27 +211,36 @@ export const MySQLDatabaseProvider = () =>
         news.replicas !== undefined &&
         news.replicas !== (output?.replicas ?? olds.replicas)
       ) {
-        return { action: "update" } as const;
+        return { action: "update", stables } as const;
       }
       if (news.migrationsDir) {
         const newHashes = yield* hashMigrations(news.migrationsDir);
         if (!recordsEqual(newHashes, output?.migrationsHashes ?? {})) {
-          return { action: "update" } as const;
+          return { action: "update", stables } as const;
         }
         if (
           (news.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE) !==
           (output?.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE)
         ) {
-          return { action: "update" } as const;
+          return { action: "update", stables } as const;
         }
       }
       if (news.importFiles?.length) {
         const newHashes = yield* hashImports(news.importFiles, yield* rootDir);
         if (!recordsEqual(newHashes, output?.importHashes ?? {})) {
-          return { action: "update" } as const;
+          return { action: "update", stables } as const;
         }
       }
-      // Otherwise allow the engine to apply the default update logic.
+      // Remaining prop changes (rename, settings, clusterSize, …) are
+      // in-place updates. Decide them here instead of falling back to
+      // the engine's default deep-compare so the conditional `name`
+      // stable above is attached — the default path uses the
+      // provider-level stables, which strip `name` from downstream plan
+      // resolution.
+      if (havePropsChanged(olds, news)) {
+        return { action: "update", stables } as const;
+      }
+
       return undefined;
     }),