alchemy 2.0.0-beta.70 → 2.0.0-beta.71

package/src/Cloudflare/Workers/Sources/Vite.ts

@@ -1,6 +1,6 @@
 import cloudflare, {
   type CloudflareVitePluginOptions,
-} from "@distilled.cloud/cloudflare-vite-plugin";
+} from "@alchemy.run/cloudflare-runtime/vite";
 import * as ConsoleService from "effect/Console";
 import * as Effect from "effect/Effect";
 import * as Path from "effect/Path";
@@ -13,8 +13,9 @@ import {
   viteBuildOutputPlugin,
   type ViteBuildOutput,
 } from "../../../Bundle/Vite.ts";
+import { viteSupportsPortZero } from "@alchemy.run/cloudflare-runtime/core/internal/Port";
 import { hashDirectory, type MemoOptions } from "../../../Command/Memo.ts";
-import { initialCwd } from "../../../Util/Node.ts";
+import { findAvailablePort, initialCwd } from "../../../Util/Node.ts";
 import { sha256Object } from "../../../Util/sha256.ts";
 import { readAssets } from "../Assets.ts";
 import type { SourceDevHandle, SourceProvider } from "../Source.ts";
@@ -23,7 +24,7 @@ import type { ViteOptions } from "../Worker.ts";
 import { isWorkerLoader } from "../WorkerLoader.ts";
 
 /**
- * This module statically imports `@distilled.cloud/cloudflare-vite-plugin`
+ * This module statically imports `@alchemy.run/cloudflare-runtime/vite`
  * (~0.5s to load), which is only needed for vite-based workers. Importers
  * MUST load it lazily (`Effect.promise(() => import("./Sources/Vite.ts"))`
  * from the dispatch in `Source.ts`, or the legacy vite arms in the
@@ -104,27 +105,48 @@ export const viteDev = (
   pluginOptions: CloudflareVitePluginOptions,
   serverOptions: vite.ServerOptions,
 ) =>
-  Effect.acquireRelease(
-    ConsoleService.consoleWith((console) =>
-      Effect.promise(async () => {
-        process.env[ALCHEMY_CLOUDFLARE_VITE_INJECTED] = "1";
-        const vite = await loadVite(rootDir);
-        const devServer = await vite.createServer({
-          root: rootDir,
-          define: getDefine(env),
-          plugins: [cloudflare(pluginOptions)],
-          server: serverOptions,
-          customLogger: makeViteLogger(console),
-        });
-        await devServer.listen();
-        return devServer;
-      }),
-    ),
-    (devServer) =>
-      Effect.promise(async () => {
-        await devServer.close();
-      }),
-  );
+  Effect.gen(function* () {
+    yield* Effect.sync(() => {
+      process.env[ALCHEMY_CLOUDFLARE_VITE_INJECTED] = "1";
+    });
+    const vite = yield* Effect.promise(() => loadVite(rootDir));
+    // `port: 0` is a true OS-assigned random port on Vite >= 8.2.1
+    // (vitejs/vite#23158); older Vite treats it as "no port given" and
+    // hunts upward from the 5173 default — colliding with (or
+    // IPv6-shadowing) user-facing dev ports. Substitute a probed
+    // ephemeral port there; `strictPort: false` handles the small
+    // probe→bind race by moving to the next ephemeral port.
+    const server =
+      serverOptions.port === 0 && !viteSupportsPortZero(vite.version)
+        ? {
+            ...serverOptions,
+            port: yield* findAvailablePort(
+              typeof serverOptions.host === "string"
+                ? serverOptions.host
+                : undefined,
+            ).pipe(Effect.orDie),
+          }
+        : serverOptions;
+    return yield* Effect.acquireRelease(
+      ConsoleService.consoleWith((console) =>
+        Effect.promise(async () => {
+          const devServer = await vite.createServer({
+            root: rootDir,
+            define: getDefine(env),
+            plugins: [cloudflare(pluginOptions)],
+            server,
+            customLogger: makeViteLogger(console),
+          });
+          await devServer.listen();
+          return devServer;
+        }),
+      ),
+      (devServer) =>
+        Effect.promise(async () => {
+          await devServer.close();
+        }),
+    );
+  });
 
 /**
  * Run a production Vite build in a child process rooted at the project

package/src/Cloudflare/Workers/ViteChild.shared.ts

@@ -4,7 +4,7 @@ import type {
   QueueConsumer,
   RuntimeWorker,
   Workflow,
-} from "@distilled.cloud/cloudflare-runtime";
+} from "@alchemy.run/cloudflare-runtime/core";
 import type { BundleOutput } from "../../Bundle/Bundle.ts";
 import type { WorkerBinding } from "./WorkerBinding.ts";
 import type { WorkerAssetsConfig, WorkerSourceDescriptor } from "./Worker.ts";

package/src/Cloudflare/Workers/ViteChild.ts

@@ -154,6 +154,12 @@ export const runViteBuildChild = (
             stdout: "pipe",
             stderr: "pipe",
             extendEnv: true,
+            // A production build must not inherit the parent's NODE_ENV: a
+            // deploy driven from a test process (`bun test` sets
+            // NODE_ENV=test) would otherwise bake `import.meta.env.DEV`
+            // into the server bundle (e.g. SolidStart then ships its
+            // dev-only manifest and every SSR request 500s).
+            env: { NODE_ENV: "production" },
             killSignal: "SIGKILL",
           },
         ),

package/src/Cloudflare/Workers/ViteChildRunner.ts

@@ -1,4 +1,4 @@
-import { layerRuntime } from "@distilled.cloud/cloudflare-runtime";
+import { layerRuntime } from "@alchemy.run/cloudflare-runtime/core";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Stdio from "effect/Stdio";
@@ -13,7 +13,6 @@ import {
 import { CloudflareAuth } from "../Auth/AuthProvider.ts";
 import * as Credentials from "../Credentials.ts";
 import * as RpcServerEnvironment from "../../Local/RpcServerEnvironment.ts";
-import { findAvailablePort } from "../../Util/Node.ts";
 import { PlatformServices, runMain } from "../../Util/PlatformServices.ts";
 import { materializeRuntimeBindings } from "./RuntimeBindings.ts";
 import { loadSource, SourceProviderError } from "./Source.ts";
@@ -71,14 +70,10 @@ const program = Effect.scoped(
     );
     const source = config.source;
     const viteHost = "127.0.0.1";
-    // TODO(BlankParticle): replace this probe with `port: 0` once the Vite fix
-    // is released: https://github.com/vitejs/vite/pull/23158
-    // Vite currently treats `port: 0` as an absent value and falls back to
-    // its default port. Probe an ephemeral port ourselves until the fixed
-    // Vite release is available.
-    // `strictPort: false` still handles the small race between releasing the
-    // probe socket and Vite binding the selected port.
-    const vitePort = source ? undefined : yield* findAvailablePort(viteHost);
+    // `viteDev` resolves `port: 0` per the loaded Vite: a true OS-assigned
+    // random port on Vite >= 8.2.1 (vitejs/vite#23158), a probed ephemeral
+    // port on older Vite.
+    const vitePort = source ? undefined : 0;
     const url = source
       ? yield* loadSource(source.descriptor).pipe(
           // `loadSource` is typed against the full `SourceServices` union

package/src/Cloudflare/Workers/Worker.ts

@@ -39,14 +39,14 @@ import type { Reference as ZoneReference } from "../Zone/lookup.ts";
 import { type Assets, type AssetsProps } from "./Assets.ts";
 import { type DurableObjectExport } from "./DurableObject.ts";
 import { Request } from "./Request.ts";
+import type { ModuleRule } from "./Sources/Prebuilt.ts";
+import type { WorkerBuildOptions } from "./Sources/Rolldown.ts";
 import { bindWorkerAsyncBindings } from "./WorkerAsyncBindings.ts";
 import type {
   WorkerBinding,
   WorkerBindingResource,
   WorkerBindings,
 } from "./WorkerBinding.ts";
-import type { ModuleRule } from "./Sources/Prebuilt.ts";
-import type { WorkerBuildOptions } from "./Sources/Rolldown.ts";
 import {
   makeWorkerRuntimeContext,
   type WorkerRuntimeContext,
@@ -565,7 +565,10 @@ export interface WorkerVersionOptions {
 }
 
 export interface WorkerProps<
-  Bindings extends WorkerBindingProps = any,
+  // PERF: unconstrained for the same reason as `Worker<Bindings>` above —
+  // the `extends WorkerBindingProps` proof is expensive for generic mapped
+  // types and the call-site overloads already constrain user input.
+  Bindings = any,
   Assets extends WorkerAssetsConfig | undefined =
     | WorkerAssetsConfig
     | undefined,
@@ -628,6 +631,13 @@ export interface WorkerProps<
    * that hash authoritative instead — the directory is not read during
    * planning at all.
    *
+   * Requests are served assets-first by default: a request matching a file
+   * never invokes the Worker. `runWorkerFirst` inverts that — `true` routes
+   * every request through the Worker ahead of the asset layer (serve files
+   * yourself via the `ASSETS` binding), and a glob array (e.g. `["/api/*"]`)
+   * routes only matching paths worker-first. The same routing applies under
+   * `alchemy dev`.
+   *
    * When neither {@link main} nor {@link script} is provided, the Worker is
    * deployed **assets-only**: no script is uploaded at all and Cloudflare's
    * asset layer serves every request, applying `htmlHandling` /
@@ -1026,7 +1036,14 @@ export interface ViteOptions {
   };
 }
 
-export type Worker<Bindings extends WorkerBindings = any> = Resource<
+// PERF: deliberately NOT `Bindings extends WorkerBindings`. The constraint
+// forced the checker to prove the generic `NormalizedBindings<...>` mapped
+// type assignable to the ~30-member `WorkerBindingResource` union at every
+// `Worker<...>` instantiation — a single 28s structural relation that was 45%
+// of the whole program's check time. Input is already constrained at the
+// call boundary (`Bindings extends WorkerBindingProps`), so this type
+// argument is only ever produced from validated shapes.
+export type Worker<Bindings = any> = Resource<
   WorkerTypeId,
   WorkerProps<Bindings>,
   {
@@ -2126,14 +2143,17 @@ export const Worker: ResourceClassLike<Worker> &
           | Container.Application<any>
           | PlatformServices
           | Tag,
+        PropsReq = never,
       >(
         id: Id,
-        props: InputProps<WorkerProps>,
+        props:
+          | InputProps<WorkerProps>
+          | Effect.Effect<InputProps<WorkerProps>, ConfigError, PropsReq>,
         impl: Effect.Effect<Shape, ConfigError, Req>,
       ): Effect.Effect<
         Worker & Rpc<Self>,
         never,
-        Extract<Req, Container.Application<any>> | Providers
+        Extract<Req, Container.Application<any>> | Providers | PropsReq
       > &
         Named<Id> & {
           new (): MakeShape<Shape, WorkerShape> & Named<Id> & Tag;

package/src/Cloudflare/Workers/WorkerProvider.ts

@@ -29,6 +29,7 @@ import { initialCwd } from "../../Util/Node.ts";
 import { sha256Object } from "../../Util/sha256.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import { localRuntimeServices } from "../LocalRuntime.ts";
+import { detachQueueConsumersOfScript } from "../Queues/Consumer.ts";
 import { CloudflareLogs } from "../Logs.ts";
 import { resolveZoneId } from "../Zone/lookup.ts";
 import {
@@ -762,7 +763,23 @@ const deleteWorkerScript = (
         force: true,
       });
     }
-    return yield* workers.deleteScript({ accountId, scriptName, force: true });
+    return yield* workers
+      .deleteScript({ accountId, scriptName, force: true })
+      .pipe(
+        // The script is still registered as a queue consumer (even with
+        // `force`). Normally the sibling Consumer resource detaches first,
+        // but state loss (e.g. a consumer row rewritten by a pre-stamping
+        // dev run) can strand a live consumer pointing at this script with
+        // nothing left to delete it. The script is going away, so any
+        // consumer wiring pointing at it is dead — detach and retry.
+        Effect.catchTag("QueueConsumerConflict", () =>
+          detachQueueConsumersOfScript(accountId, scriptName).pipe(
+            Effect.andThen(
+              workers.deleteScript({ accountId, scriptName, force: true }),
+            ),
+          ),
+        ),
+      );
   });
 
 /**
@@ -2224,7 +2241,7 @@ export const LiveWorkerProvider = () =>
       });
 
       // Loaded lazily: `./Sources/Vite.ts` pulls in
-      // `@distilled.cloud/cloudflare-vite-plugin` (~0.5s), which is only
+      // `@alchemy.run/cloudflare-runtime/vite` (~0.5s), which is only
       // needed for vite-based workers at build time — not for every Worker
       // definition at module-load time.
       const loadVite = Effect.promise(() => import("./Sources/Vite.ts"));

package/src/Docker/Docker.ts

@@ -582,17 +582,23 @@ export const DockerLive = Layer.effect(
       ),
       container: {
         create: ({ image, env, command, context, ...options }) =>
-          run([
-            ...formatArgs({ context }),
-            "container",
-            "create",
-            ...formatArgs({
-              ...options,
-              env: env ? Object.keys(env) : undefined,
-            }),
-            image,
-            ...(command ?? []),
-          ]),
+          // `--env KEY` (name-only) keeps values off CLI arguments; Docker
+          // copies each value from the CLI process environment, so the
+          // normalized container env must be passed to the child process.
+          run(
+            [
+              ...formatArgs({ context }),
+              "container",
+              "create",
+              ...formatArgs({
+                ...options,
+                env: env ? Object.keys(env) : undefined,
+              }),
+              image,
+              ...(command ?? []),
+            ],
+            env,
+          ),
         inspect: (name, context) =>
           runInspect<Docker.Container>([
             ...formatArgs({ context }),

package/src/Drizzle/{DurableObject.ts → Cloudflare.ts}

@@ -69,6 +69,7 @@ export interface DurableObjectConfig<
  * ```
  *
  * ```typescript
+ * import * as Drizzle from "alchemy/Drizzle/Cloudflare";
  * import migrations from "./drizzle/migrations.js";
  * import { posts, relations, users } from "./schema.ts";
  *

package/src/Drizzle/MySQL.ts

@@ -1,13 +1,15 @@
-import * as MysqlClient from "@effect/sql-mysql2/MysqlClient";
+// `@effect/sql-mysql2` (and mysql2 underneath) are optional peers — value
+// imports are deferred to first use so `alchemy/Drizzle` resolves without
+// them installed.
+import type * as MysqlClient from "@effect/sql-mysql2/MysqlClient";
 import type { AnyRelations, EmptyRelations } from "drizzle-orm";
 import type { EffectMysql2Database } from "drizzle-orm/effect-mysql2";
-import * as MySqlDrizzle from "drizzle-orm/effect-mysql2";
 import type { EffectDrizzleMySqlConfig } from "drizzle-orm/mysql-core/effect/utils";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import type * as Redacted from "effect/Redacted";
 import { makeExecutionMemo } from "../Runtime/ExecutionMemo.ts";
-import { resolveMySQLConfig, type MySQLConfig } from "../SQL/MySQL.ts";
+import type { MySQLConfig } from "../SQL/MySQL.ts";
 import { proxyChain } from "../Util/proxy-chain.ts";
 
 /**
@@ -55,6 +57,14 @@ export const MySQL = <
   Effect.map(
     makeExecutionMemo(
       Effect.gen(function* () {
+        const [MysqlClient, MySqlDrizzle, { resolveMySQLConfig }] =
+          yield* Effect.promise(() =>
+            Promise.all([
+              import("@effect/sql-mysql2/MysqlClient"),
+              import("drizzle-orm/effect-mysql2"),
+              import("../SQL/MySQL.ts"),
+            ]),
+          );
         const { client, ...drizzleConfig } = config ?? {};
         const mysqlCtx = yield* Layer.build(
           MysqlClient.layer(

package/src/Drizzle/Postgres.ts

@@ -1,7 +1,9 @@
-import * as PgClient from "@effect/sql-pg/PgClient";
+// `@effect/sql-pg` (and pg underneath) are optional peers — value imports
+// are deferred to first use so `alchemy/Drizzle` resolves without them
+// installed.
+import type * as PgClient from "@effect/sql-pg/PgClient";
 import type { AnyRelations, EmptyRelations } from "drizzle-orm";
 import type { EffectPgDatabase } from "drizzle-orm/effect-postgres";
-import * as PgDrizzle from "drizzle-orm/effect-postgres";
 import type { EffectDrizzlePgConfig } from "drizzle-orm/pg-core/effect/utils";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
@@ -56,6 +58,12 @@ export const Postgres = <
   Effect.map(
     makeExecutionMemo(
       Effect.gen(function* () {
+        const [PgClient, PgDrizzle] = yield* Effect.promise(() =>
+          Promise.all([
+            import("@effect/sql-pg/PgClient"),
+            import("drizzle-orm/effect-postgres"),
+          ]),
+        );
         const pgCtx = yield* Layer.build(
           PgClient.layer({ url: yield* connectionString }),
         );

package/src/Drizzle/index.ts

@@ -1,5 +1,5 @@
 export * from "./D1.ts";
-export * from "./DurableObject.ts";
+
 // The tagged errors drizzle's effect drivers fail with — re-exported so
 // consumers can reference them without reaching into drizzle-orm
 // internals. (`Effect.catchTag` needs only the tag string; these are for
@@ -10,7 +10,10 @@ export {
   EffectTransactionRollbackError,
   MigratorInitError,
 } from "drizzle-orm/effect-core";
-export * from "./MySQL.ts";
-export * from "./Postgres.ts";
 export * from "./Providers.ts";
 export * from "./Schema.ts";
+// MySQL and Postgres are deliberately NOT re-exported here: their drivers
+// (`@effect/sql-mysql2`/`mysql2`, `@effect/sql-pg`/`pg`) are optional peer
+// dependencies, and keeping them out of the barrel keeps them out of every
+// non-user's module graph. Import them via their subpaths instead:
+// `alchemy/Drizzle/MySQL`, `alchemy/Drizzle/Postgres`.

package/src/Neon/Migrations.ts

@@ -2,18 +2,9 @@ import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
 import type { Client } from "pg";
+import { importPg } from "../SQL/PostgresDriver.ts";
 import type { SqlFile } from "../SQL/SqlFile.ts";
 
-// `pg` is an optional peer dependency — loaded lazily so importing the Neon
-// provider never requires the driver unless migrations actually run.
-const importPg = () =>
-  import("pg").catch((cause) => {
-    throw new Error(
-      "Failed to load the 'pg' driver. Install the optional peer dependency 'pg' to run Neon migrations.",
-      { cause },
-    );
-  });
-
 export class PgError extends Data.TaggedError("PgError")<{
   message: string;
   cause?: unknown;

package/src/PhysicalName.ts

@@ -19,6 +19,7 @@ export const createPhysicalName = Effect.fn(function* ({
   maxLength = 64,
   delimiter = "-",
   lowercase = false,
+  forbiddenPrefixes = [],
 }: {
   id: string;
   /**
@@ -46,6 +47,14 @@ export const createPhysicalName = Effect.fn(function* ({
   delimiter?: string;
   /** Whether to lowercase the physical name. @default false */
   lowercase?: boolean;
+  /**
+   * Service-reserved name prefixes (matched case-insensitively). When the
+   * generated prefix would start with one of these — e.g. a stack named
+   * `aws-*` colliding with S3 Tables' reserved `aws` bucket prefix — a safe
+   * `x${delimiter}` is prepended so the name stays valid. Names that don't
+   * collide are unaffected, so existing deployments never rename.
+   */
+  forbiddenPrefixes?: string[];
 }) {
   // Always generate DNS-compatible names (letters, numbers, and hyphens only).
   // This ensures physical names work across all services including S3 buckets.
@@ -56,8 +65,15 @@ export const createPhysicalName = Effect.fn(function* ({
     );
   const stack = yield* Stack;
   const stage = yield* Stage;
-  const prefix =
+  let prefix =
     _prefix ?? `${stack.name}${delimiter}${id}${delimiter}${stage}${delimiter}`;
+  if (
+    forbiddenPrefixes.some((forbidden) =>
+      prefix.toLowerCase().startsWith(forbidden.toLowerCase()),
+    )
+  ) {
+    prefix = `x${delimiter}${prefix}`;
+  }
   const randomId = base32(
     Buffer.from(instanceId ?? (yield* InstanceId), "hex"),
   );

package/src/Plan.ts

@@ -40,7 +40,11 @@ import {
   tryFindProviderByType,
   type ProviderService,
 } from "./Provider.ts";
-import { defaultProviderMode, type ProviderMode } from "./ProviderMode.ts";
+import {
+  defaultProviderMode,
+  stampedMode,
+  type ProviderMode,
+} from "./ProviderMode.ts";
 import {
   isResource,
   type ResourceBinding,
@@ -343,17 +347,20 @@ export const make = <A>(
 
     /**
      * 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.
+     * 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?.providerMode !== undefined &&
-      oldState.providerMode !== mode;
+      oldState !== undefined &&
+      stampedMode(oldState) !== mode;
 
     const resourceFqns = yield* state.list({
       stack: stackName,
@@ -1781,12 +1788,16 @@ export const make = <A>(
               // and the remediation instead of limping into a partial apply.
               //
               // Orphan deletes resolve the provider variant for the mode
-              // that created the row (`providerMode`), so e.g. a local dev
+              // that created the row (`providerMode`, or the `dev:` marker
+              // inference for legacy unstamped rows), so e.g. a local dev
               // worker's row is deleted by the local provider even during a
-              // live deploy — and vice versa.
+              // live deploy — and vice versa. Unstamped rows are physically
+              // live unless their attrs carry the marker (see stampedMode),
+              // never the run default.
+              const rowMode = stampedMode(oldState);
               const providerOption = yield* tryFindProviderByType(
                 resourceType,
-                oldState.providerMode,
+                rowMode,
               );
               if (Option.isNone(providerOption)) {
                 return yield* Effect.die(

package/src/ProviderMode.ts

@@ -59,6 +59,62 @@ export class ConflictingProviderModeError extends Data.TaggedError(
   conflictingMode: ProviderMode | undefined;
 }> {}
 
+/**
+ * Prefix marking a locally-emulated resource's physical identity. Local
+ * providers fabricate ids/names with this prefix (`dev:<uuid>` queue and
+ * namespace ids, `dev:`-prefixed bucket names, ...) so a resource's
+ * persisted attributes reveal which runtime hosts it even without the
+ * `providerMode` stamp.
+ */
+export const LOCAL_ID_PREFIX = "dev:";
+
+/**
+ * Does a persisted attributes value carry a local identity marker — any
+ * string value (at any depth) with the {@link LOCAL_ID_PREFIX}? Persisted
+ * attrs are plain JSON (state commits strip unresolved values), so a
+ * structural scan is safe.
+ */
+export const hasLocalIdentity = (value: unknown): boolean => {
+  if (typeof value === "string") return value.startsWith(LOCAL_ID_PREFIX);
+  if (Array.isArray(value)) return value.some(hasLocalIdentity);
+  if (typeof value === "object" && value !== null) {
+    return Object.values(value).some(hasLocalIdentity);
+  }
+  return false;
+};
+
+/**
+ * The mode a persisted state row was actually reconciled with: its stamped
+ * `providerMode`, or — for legacy rows written before stamping existed —
+ * `"local"` when the persisted attributes carry a {@link LOCAL_ID_PREFIX}
+ * identity marker, `"live"` otherwise.
+ *
+ * An unstamped row without a marker predates provider modes or was written
+ * by a mode-agnostic provider — in both cases the write acted on the REAL
+ * cloud, so the row's physical resource is `"live"`. Assuming the current
+ * run's mode instead silently adopts a deployed cloud resource as a local
+ * instance during `alchemy dev`: the row noops (or restarts locally over
+ * the live attrs), gets re-stamped `"local"`, and the live resource becomes
+ * untracked — it is never deleted by a later destroy or replacement, and
+ * its deployed URL keeps serving.
+ *
+ * An unstamped row WITH a marker (e.g. a queue with a `dev:<uuid>` id
+ * written by `alchemy dev` on a pre-stamping version) is the mirror case:
+ * assuming `"live"` hands the `dev:` identity to the live provider, which
+ * sends it to the real cloud API (Cloudflare rejects it as a malformed
+ * parameter, permanently wedging the destroy). The marker proves the row
+ * was reconciled locally, so it is handled as `"local"`.
+ *
+ * For mode-agnostic providers the returned mode is harmless either way:
+ * `providerForMode` ignores the mode when the provider has a single
+ * implementation.
+ */
+export const stampedMode = (row: {
+  readonly providerMode?: ProviderMode | undefined;
+  readonly attr?: unknown;
+}): ProviderMode =>
+  row.providerMode ?? (hasLocalIdentity(row.attr) ? "local" : "live");
+
 /**
  * Run the wrapped resources **remotely (against the real cloud) even during
  * `alchemy dev`** — the opt-out from local emulation. During `alchemy deploy`