alchemy 2.0.0-beta.73 → 2.0.0-beta.75

package/src/Local/DockerHostGateway.ts

@@ -0,0 +1,18 @@
+/**
+ * Hostnames that mean "this machine" in a connection string. Inside a Docker
+ * container they resolve to the container itself, so alchemy rewrites them to
+ * `host.docker.localhost` (Prisma's `prisma+postgres://` plain-HTTP gate
+ * requires a localhost-looking host).
+ *
+ * Native Linux Docker cannot SYN Docker's `host-gateway` (bridge IP) without
+ * hitting host INPUT / UFW. Binding extra host IPs does not skip that.
+ * The workerd sidecar proxy instead unix-socket-tunnels these ports into
+ * the container netns — see `DockerLoopback.ts` in cloudflare-runtime.
+ */
+export const isLoopbackHost = (hostname: string) =>
+  hostname === "localhost" ||
+  hostname === "127.0.0.1" ||
+  hostname === "0.0.0.0" ||
+  hostname === "::1" ||
+  hostname === "[::1]" ||
+  hostname.endsWith(".localhost");

package/src/Local/ProviderLayer.ts

@@ -64,6 +64,26 @@ export const dual = <
   input: {
     live: () => LayerLive;
     local: () => LayerLocal;
+    /**
+     * Data-plane override context for the local mode — the layer of cloud
+     * environment services (endpoint, credentials, region) the local
+     * lifecycle variant runs under (e.g. AWS's `flociServices()`). Stamped
+     * onto the registered service as
+     * {@link ProviderService.localDataPlane} so `Binding.Service` clients
+     * can route deploy-time data-plane calls (Action bodies, plan-time
+     * `execute`) to the emulator when the bound resource resolves local.
+     * Pass a module-memoized layer reference.
+     */
+    dataPlane?: () => Layer.Layer<any, any, never>;
+    /**
+     * Data-plane override for **live** mode — the inverse of
+     * {@link dataPlane}. Stamped as {@link ProviderService.liveDataPlane} so
+     * `Alchemy.remote()` binding clients in a `dev` run provide the live
+     * chain closest (ambient is the emulator). Pass a module-memoized
+     * layer reference. AWS duals also get this from
+     * `pinCollectionEnvironment`.
+     */
+    liveDataPlane?: () => Layer.Layer<any, any, never>;
   },
 ): Layer.Layer<
   Layer.Success<LayerLive | LayerLocal>,
@@ -119,6 +139,8 @@ export const dual = <
         ...defaultService,
         mode: defaultMode,
         modes,
+        localDataPlane: input.dataPlane,
+        liveDataPlane: input.liveDataPlane,
       } satisfies ProviderService<R>);
     }),
   ) as any;

package/src/Local/RpcProvider.ts

@@ -165,7 +165,7 @@ export const effect = <
   LogsReq = never,
   ListReq = never,
 >(
-  cls: ResourceClassLike<R> | Platform<R, any, any, any, any>,
+  cls: ResourceClassLike<R> | Platform<R, any, any, any, any, any>,
   serverEntryUrl: string,
   eff: Effect.Effect<
     RpcProviderService<

package/src/Local/RpcProviderProxy.ts

@@ -48,7 +48,31 @@ const make = Effect.fn(function* (spawnerUrl: string) {
       // The spawner returns one shared child per entry URL; the stack-specific
       // environment rides the session websocket so the child can build (and
       // memoize) a provider context per stack.
-      const websocketUrl = new URL(yield* response.text);
+      const body = yield* response.text;
+      if (response.status !== 200) {
+        return yield* Effect.fail(
+          new Error(
+            `RPC spawner POST ${spawnerUrl} returned ${response.status}: ${body.slice(0, 300)}`,
+          ),
+        );
+      }
+      let websocketUrl: URL;
+      try {
+        websocketUrl = new URL(body);
+      } catch {
+        return yield* Effect.fail(
+          new Error(
+            `RPC spawner POST ${spawnerUrl} did not return a websocket URL (got ${JSON.stringify(body.slice(0, 200))})`,
+          ),
+        );
+      }
+      if (websocketUrl.protocol !== "ws:" && websocketUrl.protocol !== "wss:") {
+        return yield* Effect.fail(
+          new Error(
+            `RPC spawner POST ${spawnerUrl} returned a non-websocket URL: ${websocketUrl.toString()}`,
+          ),
+        );
+      }
       websocketUrl.searchParams.set(SESSION_ENV_PARAM, sessionEnv);
       return newWebSocketRpcSession<RpcProxyApi>(websocketUrl.toString());
     },

package/src/Planetscale/Postgres/PostgresBranch.ts

@@ -24,7 +24,8 @@ export interface PostgresBranchProps extends BaseBranchProps {
 
   /**
    * PostgreSQL cluster size for the branch. Required if `backupId` is provided.
-   * Short sizes are expanded using the target branch region.
+   * Short NAS sizes are expanded using the target branch region. Metal
+   * requires the full SKU (e.g. `"M1_10_AWS_ARM_D_METAL_10"`).
    */
   clusterSize?: PostgresClusterSize;
 

package/src/Planetscale/Postgres/PostgresClusterSize.ts

@@ -3,15 +3,135 @@ import * as Effect from "effect/Effect";
 import * as Schedule from "effect/Schedule";
 import { pollUntil, waitForBranchReady } from "../Util.ts";
 
+/**
+ * Published PlanetScale Metal SKUs for Postgres (AWS).
+ *
+ * Short display names (`"M-10"`, `"M_10"`) are **not** valid SKUs. Each
+ * Metal SKU encodes CPU series, compute size, provider, architecture, and
+ * NVMe storage size.
+ *
+ * Hyphenated SKUs copied from PlanetScale's pricing docs
+ * (`"M1-10-AWS-ARM-D-METAL-10"`) are accepted and normalized to
+ * underscores by {@link toPostgresClusterSku}. GCP and custom SKUs are
+ * still valid via {@link PostgresClusterSize}'s open-string fallback.
+ *
+ * @see https://planetscale.com/docs/postgres/pricing
+ * @see https://planetscale.com/docs/metal
+ */
+export type PostgresMetalClusterSize =
+  | "M1_10_AWS_ARM_D_METAL_10"
+  | "M1_10_AWS_AMD_D_METAL_10"
+  | "M1_10_AWS_ARM_D_METAL_25"
+  | "M1_10_AWS_AMD_D_METAL_25"
+  | "M1_10_AWS_ARM_D_METAL_50"
+  | "M1_10_AWS_AMD_D_METAL_50"
+  | "M1_10_AWS_ARM_D_METAL_100"
+  | "M1_10_AWS_AMD_D_METAL_100"
+  | "M1_10_AWS_ARM_D_METAL_200"
+  | "M1_10_AWS_AMD_D_METAL_200"
+  | "M1_20_AWS_ARM_D_METAL_10"
+  | "M1_20_AWS_AMD_D_METAL_10"
+  | "M1_20_AWS_ARM_D_METAL_25"
+  | "M1_20_AWS_AMD_D_METAL_25"
+  | "M1_20_AWS_ARM_D_METAL_50"
+  | "M1_20_AWS_AMD_D_METAL_50"
+  | "M1_20_AWS_ARM_D_METAL_100"
+  | "M1_20_AWS_AMD_D_METAL_100"
+  | "M1_20_AWS_ARM_D_METAL_200"
+  | "M1_20_AWS_AMD_D_METAL_200"
+  | "M1_40_AWS_ARM_D_METAL_10"
+  | "M1_40_AWS_AMD_D_METAL_10"
+  | "M1_40_AWS_ARM_D_METAL_25"
+  | "M1_40_AWS_AMD_D_METAL_25"
+  | "M1_40_AWS_ARM_D_METAL_50"
+  | "M1_40_AWS_AMD_D_METAL_50"
+  | "M1_40_AWS_ARM_D_METAL_100"
+  | "M1_40_AWS_AMD_D_METAL_100"
+  | "M1_40_AWS_ARM_D_METAL_200"
+  | "M1_40_AWS_AMD_D_METAL_200"
+  | "M1_40_AWS_ARM_D_METAL_400"
+  | "M1_40_AWS_AMD_D_METAL_400"
+  | "M1_40_AWS_ARM_D_METAL_800"
+  | "M1_40_AWS_AMD_D_METAL_800"
+  | "M1_40_AWS_ARM_D_METAL_1200"
+  | "M1_40_AWS_AMD_D_METAL_1200"
+  | "M1_80_AWS_ARM_D_METAL_100"
+  | "M1_80_AWS_AMD_D_METAL_100"
+  | "M1_80_AWS_ARM_D_METAL_200"
+  | "M1_80_AWS_AMD_D_METAL_200"
+  | "M1_80_AWS_ARM_D_METAL_400"
+  | "M1_80_AWS_AMD_D_METAL_400"
+  | "M1_80_AWS_ARM_D_METAL_800"
+  | "M1_80_AWS_AMD_D_METAL_800"
+  | "M1_80_AWS_ARM_D_METAL_1200"
+  | "M1_80_AWS_AMD_D_METAL_1200"
+  | "M1_160_AWS_ARM_D_METAL_100"
+  | "M1_160_AWS_AMD_D_METAL_100"
+  | "M1_160_AWS_ARM_D_METAL_200"
+  | "M1_160_AWS_AMD_D_METAL_200"
+  | "M1_160_AWS_ARM_D_METAL_400"
+  | "M1_160_AWS_AMD_D_METAL_400"
+  | "M1_160_AWS_ARM_D_METAL_800"
+  | "M1_160_AWS_AMD_D_METAL_800"
+  | "M1_160_AWS_ARM_D_METAL_1200"
+  | "M1_160_AWS_AMD_D_METAL_1200"
+  | "M8_160_AWS_ARM_D_METAL_118"
+  | "M6_160_AWS_INTEL_D_METAL_118"
+  | "M7_160_AWS_INTEL_D_METAL_468"
+  | "M7_160_AWS_INTEL_D_METAL_1250"
+  | "M8_320_AWS_ARM_D_METAL_237"
+  | "M6_320_AWS_INTEL_D_METAL_237"
+  | "M7_320_AWS_INTEL_D_METAL_937"
+  | "M7_320_AWS_INTEL_D_METAL_2500"
+  | "M8_640_AWS_ARM_D_METAL_474"
+  | "M6_640_AWS_INTEL_D_METAL_474"
+  | "M7_640_AWS_INTEL_D_METAL_1875"
+  | "M7_640_AWS_INTEL_D_METAL_5000"
+  | "M7_960_AWS_INTEL_D_METAL_7500"
+  | "M8_1280_AWS_ARM_D_METAL_950"
+  | "M6_1280_AWS_INTEL_D_METAL_950"
+  | "M7_1280_AWS_INTEL_D_METAL_3750"
+  | "M7_1920_AWS_INTEL_D_METAL_15000"
+  | "M8_2560_AWS_ARM_D_METAL_1900"
+  | "M6_2560_AWS_INTEL_D_METAL_1900"
+  | "M7_2560_AWS_INTEL_D_METAL_7500"
+  | "M8_3840_AWS_ARM_D_METAL_2850"
+  | "M6_3840_AWS_INTEL_D_METAL_2850"
+  | "M7_3840_AWS_INTEL_D_METAL_11250"
+  | "M7_3840_AWS_INTEL_D_METAL_30000"
+  | "M8_5120_AWS_ARM_D_METAL_3800"
+  | "M6_5120_AWS_INTEL_D_METAL_3800"
+  | "M7_5120_AWS_INTEL_D_METAL_15000"
+  | "M7_5760_AWS_INTEL_D_METAL_45000"
+  | "M8_7680_AWS_ARM_D_METAL_5700"
+  | "M6_7680_AWS_INTEL_D_METAL_5700"
+  | "M7_7680_AWS_INTEL_D_METAL_22500"
+  | "M7_7680_AWS_INTEL_D_METAL_60000"
+  | "M6_10240_AWS_INTEL_D_METAL_7600"
+  | "M8_15360_AWS_ARM_D_METAL_11400"
+  | "M7_15360_AWS_INTEL_D_METAL_45000"
+  | "M7_15360_AWS_INTEL_D_METAL_120000";
+
 /**
  * Available PlanetScale PostgreSQL cluster sizes.
  *
- * `PS_*` sizes are backed by network-attached storage (NAS) and can be
- * specified either as the short size (`"PS_10"`) or the API SKU
- * (`"PS_10_AWS_X86"`). Short NAS sizes are expanded to a SKU by
- * {@link toPostgresClusterSku} using the target region and arch.
+ * ## Network-attached storage (NAS)
+ *
+ * `PS_*` sizes are backed by network-attached storage and can be specified
+ * either as the short size (`"PS_10"`) or the API SKU (`"PS_10_AWS_X86"`).
+ * Short NAS sizes are expanded to a SKU by {@link toPostgresClusterSku}
+ * using the target region and arch.
+ *
+ * ## Metal
+ *
+ * [PlanetScale Metal](https://planetscale.com/docs/metal) sizes are backed
+ * by locally-attached NVMe. Pass a **full Metal SKU** from
+ * {@link PostgresMetalClusterSize} — short `M-*` names are not valid on
+ * their own because Metal SKUs also encode CPU series, architecture, and
+ * drive size. See [Postgres pricing](https://planetscale.com/docs/postgres/pricing).
  *
  * @see https://planetscale.com/docs/postgres/pricing
+ * @see https://planetscale.com/docs/metal
  */
 export type PostgresClusterSize =
   | "PS_DEV"
@@ -25,20 +145,25 @@ export type PostgresClusterSize =
   | "PS_640"
   | "PS_1280"
   | "PS_2560"
+  | PostgresMetalClusterSize
   | (string & {});
 
 /**
  * Converts a {@link PostgresClusterSize} into the SKU string expected by
  * the PlanetScale API.
  *
+ * Hyphens are normalized to underscores so SKUs copied from PlanetScale
+ * docs (`"PS-10"`, `"M1-10-AWS-ARM-D-METAL-10"`) match the API form.
+ *
  * For NAS-backed clusters, the API expects a suffixed name like
  * `PS_<size>_<provider>_<arch>`. Short `PS_*` sizes are expanded using the
  * supplied region and arch.
  *
- * Metal-backed sizes (anything starting with `M`) are passed through
- * unchanged. The short `M_*` form is not a valid SKU on its own — the API
- * requires the full Metal SKU (e.g. `M6_640_AWS_INTEL_D_METAL_474`), which
- * encodes the CPU series, provider, arch, and storage size
+ * Metal-backed sizes (anything starting with `M`) are passed through after
+ * hyphen normalization. The short `M_*` / `M-*` form is not a valid SKU on
+ * its own — the API requires the full Metal SKU (e.g.
+ * `M1_10_AWS_ARM_D_METAL_10`), which encodes the CPU series, provider,
+ * arch, and storage size.
  *
  * Already-suffixed NAS sizes are also passed through unchanged.
  */
@@ -47,7 +172,7 @@ export function toPostgresClusterSku(input: {
   arch?: "x86" | "arm";
   region?: string;
 }): string {
-  const size = input.size;
+  const size = input.size.replaceAll("-", "_");
   if (!size.startsWith("PS_") || size.match(/(AWS|GCP)/)) return size;
   // Not all AWS regions start with "aws-", but all GCP regions start with "gcp-".
   const provider = input.region?.startsWith("gcp") ? "GCP" : "AWS";

package/src/Planetscale/Postgres/PostgresDatabase.ts

@@ -37,8 +37,14 @@ import {
 export interface PostgresDatabaseProps extends BaseDatabaseProps {
   /**
    * The PostgreSQL database cluster size. Required.
-   * Short sizes are expanded using the target region and architecture.
+   *
+   * Short NAS sizes (`"PS_10"`) are expanded using the target region and
+   * architecture. [PlanetScale Metal](https://planetscale.com/docs/metal)
+   * requires the full SKU (e.g. `"M1_10_AWS_ARM_D_METAL_10"`) because
+   * Metal also encodes CPU series, architecture, and NVMe drive size.
+   *
    * @see https://planetscale.com/docs/postgres/pricing
+   * @see {@link PostgresClusterSize}
    */
   clusterSize: PostgresClusterSize;
 
@@ -75,6 +81,14 @@ export interface PostgresDatabaseAttributes extends BaseDatabaseAttributes {
  * });
  * ```
  *
+ * **Example:** PlanetScale Metal (NVMe)
+ * ```typescript
+ * const db = yield* Planetscale.PostgresDatabase("MyDb", {
+ *   clusterSize: "M1_10_AWS_ARM_D_METAL_10",
+ *   arch: "arm",
+ * });
+ * ```
+ *
  * ### Migrations and seed data
  * **Example:** Apply migrations and seed files
  * ```typescript

package/src/Platform.ts

@@ -156,6 +156,7 @@ export interface Platform<
   MainShape,
   RuntimeContext extends BaseRuntimeContext,
   BaseShape = {},
+  InlineProps extends Resource["Props"] = Resource["Props"],
 > extends Effect.Effect<Resource & RuntimeContext, never, Resource> {
   Type: Resource["Type"];
   Provider: Provider<Resource>;
@@ -171,9 +172,9 @@ export interface Platform<
       Named<Id> & {
         make<PropsReq = never, InitReq = never>(
           props:
-            | InputProps<Resource["Props"]>
+            | InputProps<InlineProps>
             | Effect.Effect<
-                InputProps<Resource["Props"]>,
+                InputProps<InlineProps>,
                 ConfigError.ConfigError,
                 PropsReq
               >,
@@ -199,9 +200,9 @@ export interface Platform<
     >(
       id: Id,
       props:
-        | InputProps<Resource["Props"]>
+        | InputProps<InlineProps>
         | Effect.Effect<
-            InputProps<Resource["Props"]>,
+            InputProps<InlineProps>,
             ConfigError.ConfigError,
             PropsReq
           >,
@@ -228,9 +229,9 @@ export interface Platform<
           InitReq extends Services | PlatformServices | Resource = never,
         >(
           props:
-            | InputProps<Resource["Props"]>
+            | InputProps<InlineProps>
             | Effect.Effect<
-                InputProps<Resource["Props"]>,
+                InputProps<InlineProps>,
                 ConfigError.ConfigError,
                 PropsReq
               >,
@@ -264,8 +265,8 @@ export interface Platform<
   >(
     id: Id,
     props:
-      | InputProps<Resource["Props"]>
-      | Effect.Effect<InputProps<Resource["Props"]>, never, PropsReq>,
+      | InputProps<InlineProps>
+      | Effect.Effect<InputProps<InlineProps>, never, PropsReq>,
     impl: Effect.Effect<Shape, ConfigError.ConfigError, InitReq>,
   ): Effect.Effect<
     Resource & Rpc<Shape> & Named<Id>,

package/src/Prisma/Compute.ts

@@ -30,7 +30,6 @@ import * as ProviderLayer from "../Local/ProviderLayer.ts";
 import { Resource, type ResourceBinding } from "../Resource.ts";
 import { RuntimeContext } from "../RuntimeContext.ts";
 import type * as Server from "../Server/index.ts";
-import { Self } from "../Self.ts";
 import { Stack } from "../Stack.ts";
 import { sha256Object } from "../Util/sha256.ts";
 import {
@@ -1459,79 +1458,22 @@ const bundleEffectCompute = Effect.fn(function* (props: ComputeProps) {
       input: realMain,
       cwd,
       platform: "node",
+      // Prisma Compute runs the bundle on bun.
+      resolve: {
+        conditionNames: [...Bundle.BUN_CONDITION_NAMES],
+        ...props.bundle?.input?.resolve,
+      },
       plugins: [
         props.bundle?.input?.plugins,
         virtualEntryPlugin(
           (importPath) => `
-import { BunServices } from "@effect/platform-bun";
-import { BunHttpServer } from "alchemy/Http";
-import { Stack } from "alchemy/Stack";
-import { Stage } from "alchemy/Stage";
-import { makeEntrypointLayer } from "alchemy/Runtime";
-import * as ConfigProvider from "effect/ConfigProvider";
-import * as Context from "effect/Context";
-import * as Effect from "effect/Effect";
-import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
-import * as Layer from "effect/Layer";
-import * as Logger from "effect/Logger";
-import { MinimumLogLevel } from "effect/References";
-
+import { bootstrap } from "alchemy/Runtime/Bootstrap/Prisma";
 ${importEntrypoint} from ${JSON.stringify(importPath)};
 
-process.env.PORT ??= ${JSON.stringify(String(defaultPort))};
-
-const tag = Context.Service("${Self.key}");
-const layer = makeEntrypointLayer(tag, entrypoint);
-
-const platform = Layer.mergeAll(
-  BunServices.layer,
-  FetchHttpClient.layer,
-  Logger.layer([Logger.consolePretty()]),
-);
-
-const stack = Layer.mergeAll(
-  Layer.succeed(Stack, {
-    name: ${JSON.stringify(stack.name)},
-    stage: ${JSON.stringify(stack.stage)},
-    bindings: {},
-    resources: {},
-  }),
-  Layer.succeed(Stage, ${JSON.stringify(stack.stage)}),
-);
-
-const program = tag.pipe(
-  Effect.flatMap((app) => app.RuntimeContext.exports),
-  Effect.flatMap((exports) => exports.default),
-  Effect.provide(
-    layer.pipe(
-      Layer.provideMerge(stack),
-      Layer.provideMerge(BunHttpServer({ hostname: "0.0.0.0" })),
-      Layer.provideMerge(platform),
-      Layer.provideMerge(
-        Layer.succeed(
-          ConfigProvider.ConfigProvider,
-          ConfigProvider.orElse(
-            ConfigProvider.fromUnknown({ ALCHEMY_PHASE: "runtime" }),
-            ConfigProvider.fromEnv(),
-          ),
-        ),
-      ),
-      Layer.provideMerge(
-        Layer.succeed(
-          MinimumLogLevel,
-          process.env.DEBUG ? "Debug" : "Info",
-        ),
-      ),
-    ),
-  ),
-  Effect.scoped,
-);
-
-console.log("Prisma Compute bootstrap starting...");
-await Effect.runPromise(program).catch((error) => {
-  console.error("Prisma Compute bootstrap failed:", error);
-  process.exit(1);
-});
+await bootstrap(entrypoint, ${JSON.stringify({
+            port: defaultPort,
+            stack: { name: stack.name, stage: stack.stage },
+          })});
 `,
         ),
       ],

package/src/Prisma/PrismaDevDatabase.ts

@@ -314,6 +314,9 @@ export const ensurePrismaDevDatabase = Effect.fn(function* (
       servers.delete(databaseId);
     }
     const server = yield* startServer(databaseId, options);
+    // `@prisma/dev` binds Postgres/HTTP to 127.0.0.1. Native Linux Docker
+    // must not SYN the bridge IP (UFW INPUT). The workerd sidecar proxy
+    // unix-socket-tunnels these ports into the container netns.
     const attrsResult = yield* Effect.result(
       prismaDevDatabaseAttrsFromServer(server),
     );
@@ -341,7 +344,12 @@ export const ensurePrismaDevDatabase = Effect.fn(function* (
       return yield* Effect.fail(attrsResult.failure);
     }
     const attrs = attrsResult.success;
-    entry = { optionsKey, migrationKey: undefined, server, attrs };
+    entry = {
+      optionsKey,
+      migrationKey: undefined,
+      server,
+      attrs,
+    };
     servers.set(databaseId, entry);
   }
 

package/src/Provider.ts

@@ -10,7 +10,7 @@ import type { Diff } from "./Diff.ts";
 import type { Input } from "./Input.ts";
 import type { InstanceId } from "./InstanceId.ts";
 import type { Platform } from "./Platform.ts";
-import type { ProviderMode } from "./ProviderMode.ts";
+import { defaultProviderMode, type ProviderMode } from "./ProviderMode.ts";
 import type {
   ResourceBinding,
   ResourceClass,
@@ -133,6 +133,31 @@ export interface ProviderService<
    * even during a live deploy (and vice versa).
    */
   modes?: { readonly [M in ProviderMode]: Effect.Effect<ProviderService<Res>> };
+  /**
+   * Data-plane override context for this provider's **local** mode: a layer
+   * of cloud environment services (endpoint, credentials, region,
+   * environment) that points data-plane API calls at the local emulator —
+   * the same override the local lifecycle variant runs under (e.g. AWS's
+   * `flociServices()`).
+   *
+   * Set by `ProviderLayer.dual` registrations that pass `dataPlane`.
+   * Consumed by `Binding.Service`'s client wrapper (via
+   * {@link resolveLocalDataPlane}) so deploy-time binding invocations —
+   * inside an `Action` body or a plan-time `execute` — target whatever
+   * data plane the bound resource actually lives on: a local-mode resource
+   * routes to the emulator while an `Alchemy.remote()` resource keeps
+   * hitting the real cloud. Pass a module-memoized layer reference.
+   */
+  localDataPlane?: () => Layer.Layer<any, any, never>;
+  /**
+   * Data-plane override context for this provider's **live** mode: the
+   * cloud environment captured at provider registration (credentials,
+   * region, endpoint). In an `alchemy dev` run the ambient environment IS
+   * the emulator, so an unwrapped live client would hit floci. Stamp this
+   * so `Alchemy.remote()` binding calls are provided the live chain
+   * closest, the inverse of {@link localDataPlane}.
+   */
+  liveDataPlane?: () => Layer.Layer<any, any, never>;
   /**
    * Account-wide teardown (`alchemy unsafe nuke`) behaviour. Providers whose
    * resources can't meaningfully be deleted opt out here so nuke doesn't
@@ -405,7 +430,7 @@ export const effect = <
   LogsReq = never,
   ListReq = never,
 >(
-  cls: ResourceClassLike<R> | Platform<R, any, any, any, any>,
+  cls: ResourceClassLike<R> | Platform<R, any, any, any, any, any>,
   eff: Effect.Effect<
     ProviderServiceInput<
       R,
@@ -449,7 +474,7 @@ export const succeed = <
   LogsReq = never,
   ListReq = never,
 >(
-  cls: ResourceClass<R> | Platform<R, any, any, any, any>,
+  cls: ResourceClass<R> | Platform<R, any, any, any, any, any>,
   service: ProviderServiceInput<
     R,
     ReadReq,
@@ -514,13 +539,13 @@ export interface ProviderCollectionService {
 }
 
 export const collection = <
-  R extends ResourceClassLike<any> | Platform<any, any, any, any, any>,
+  R extends ResourceClassLike<any> | Platform<any, any, any, any, any, any>,
 >(
   resources: R[],
 ): Effect.Effect<
   ProviderCollectionService,
   never,
-  R extends ResourceClass<infer R> | Platform<infer R, any, any, any, any>
+  R extends ResourceClass<infer R> | Platform<infer R, any, any, any, any, any>
     ? Provider<R>
     : never
 > =>
@@ -595,6 +620,78 @@ export const providerForMode = <R extends ResourceLike>(
     ? service.modes[mode]
     : Effect.succeed(service);
 
+/**
+ * Why a resource's deploy-time binding clients target the data plane they
+ * do — see {@link describeDataPlane}.
+ *
+ * - `local` — the resource runs on its provider's local emulator; `layer`
+ *   is the override to provide closest around every client call.
+ * - `live` — the resource targets the real cloud: either pinned there
+ *   (`Alchemy.remote()`) or the run is a plain deploy. `layer` is the
+ *   registration-captured live environment, provided closest around every
+ *   client call so a `remote()` resource still hits the real cloud when the
+ *   ambient environment is the emulator.
+ * - `undeclared` — the resource resolves to local mode, but its provider
+ *   is a dual registration without a {@link ProviderService.localDataPlane}
+ *   (a process-hosted local variant with no API to route to, or a missing
+ *   `dataPlane` on a hand-written `ProviderLayer.dual`). Clients fall back
+ *   to the real cloud — reported by name so the two are never confused.
+ * - `agnostic` — the provider is mode-agnostic (plain registration); its
+ *   resources live on the real cloud even in dev.
+ * - `unregistered` — no provider in context (bare runtime, unit tests).
+ */
+export type DataPlaneResolution =
+  | { readonly kind: "local"; readonly layer: Layer.Layer<any, any, never> }
+  | {
+      readonly kind: "live";
+      readonly layer?: Layer.Layer<any, any, never> | undefined;
+    }
+  | { readonly kind: "undeclared"; readonly providerType: string }
+  | { readonly kind: "agnostic" }
+  | { readonly kind: "unregistered" };
+
+/**
+ * Resolve where a resource's deploy-time binding clients should be routed:
+ * its registration-captured {@link ResourceLike.Mode} (`Alchemy.remote()`
+ * → `"live"`) or the run default (`alchemy dev` → `"local"`) — the same
+ * resolution `Plan.make` applies to lifecycle operations — combined with
+ * whether the provider registered a local data plane at all.
+ */
+export const describeDataPlane = (resource: {
+  readonly Type: string;
+  readonly Mode?: ProviderMode | undefined;
+}): Effect.Effect<DataPlaneResolution> =>
+  Effect.gen(function* () {
+    const found = yield* tryFindProviderByType(resource.Type);
+    if (Option.isNone(found)) return { kind: "unregistered" as const };
+    const provider = found.value;
+    if (provider.modes === undefined) return { kind: "agnostic" as const };
+    const mode = resource.Mode ?? (yield* defaultProviderMode);
+    if (mode !== "local") {
+      const layer = provider.liveDataPlane?.();
+      return layer !== undefined
+        ? { kind: "live" as const, layer }
+        : { kind: "live" as const };
+    }
+    if (provider.localDataPlane === undefined) {
+      return { kind: "undeclared" as const, providerType: resource.Type };
+    }
+    return { kind: "local" as const, layer: provider.localDataPlane() };
+  });
+
+/**
+ * The data-plane override layer for a resource, or `undefined` when its
+ * clients target the real cloud for any reason (see
+ * {@link describeDataPlane} for which).
+ */
+export const resolveLocalDataPlane = (resource: {
+  readonly Type: string;
+  readonly Mode?: ProviderMode | undefined;
+}): Effect.Effect<Layer.Layer<any, any, never> | undefined> =>
+  describeDataPlane(resource).pipe(
+    Effect.map((plane) => (plane.kind === "local" ? plane.layer : undefined)),
+  );
+
 export const findProviderByType: {
   <R extends ResourceLike>(
     resourceType: R["Type"],
@@ -618,7 +715,7 @@ export const findProviderByType: {
  */
 export const findProvider: {
   <R extends ResourceLike>(
-    resource: ResourceClassLike<R> | Platform<R, any, any, any, any>,
+    resource: ResourceClassLike<R> | Platform<R, any, any, any, any, any>,
     mode?: ProviderMode,
   ): Effect.Effect<ProviderService<R>>;
 } = (resource: { Type?: string; key?: string }, mode?: ProviderMode) =>