alchemy 2.0.0-beta.64 → 2.0.0-beta.66

package/src/Cloudflare/D1/QueryDatabaseLocal.ts

@@ -3,11 +3,15 @@ import * as Layer from "effect/Layer";
 import type * as HttpClient from "effect/unstable/http/HttpClient";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Credentials } from "../Credentials.ts";
+import { isLocalId } from "../LocalRuntime.ts";
 import type { Database } from "./Database.ts";
+import { localD1GatewayRuntime, withLocalD1Query } from "./LocalD1Gateway.ts";
 import { QueryDatabase } from "./QueryDatabase.ts";
 import {
   type D1Auth,
-  makeHttpQueryDatabaseClient,
+  makeD1DatabaseFromTransport,
+  makeHttpD1Database,
+  makeQueryDatabaseClientFrom,
 } from "./QueryDatabaseHttpClient.ts";
 
 /**
@@ -55,12 +59,50 @@ export const QueryDatabaseLocal = Layer.effect(
       authorize: (eff) => eff.pipe(Effect.provideContext(context)),
       accountId,
     };
+    // The FULL ambient context, for the dev-mode gateway: booting an
+    // ephemeral workerd needs the platform services (FileSystem, Path,
+    // spawner, HttpClient) and the Cloudflare environment, all of which are
+    // present during stack-eval but not statically enumerable here.
+    const ambient = yield* Effect.context<never>();
+
+    // Under `alchemy dev` the database may be a local simulator row (a
+    // `dev:` id). Queries then tunnel through an ephemeral workerd gateway
+    // into the simulator's DO SQLite (one gateway boot per query — slow but
+    // correct; Actions are deploy-time one-shots). Real ids keep the cloud
+    // HTTP query API.
+    const localTransport =
+      (databaseId: string) =>
+      (
+        body:
+          | { sql: string; params?: unknown[] }
+          | { batch: { sql: string; params?: unknown[] }[] },
+      ) =>
+        withLocalD1Query(databaseId, (query) => query(body)).pipe(
+          Effect.provide(localD1GatewayRuntime),
+          // The gateway layer's platform requirements are satisfied by the
+          // ambient stack-eval context captured above; `Context<never>`
+          // can't prove that statically, so erase the leftover R.
+          Effect.provideContext(ambient),
+          (eff) => Effect.runPromise(eff as Effect.Effect<never, never>),
+        ) as Promise<{
+          result: Array<{
+            results?: unknown;
+            success?: boolean | null;
+            meta?: unknown;
+          }>;
+        }>;
 
     return Effect.fn(function* (database: Database) {
       // Deferred accessor — resolves the databaseId against the tracker at
       // apply time. No `host.bind`: the local variant registers no binding.
       const databaseId = yield* database.databaseId;
-      return makeHttpQueryDatabaseClient(auth, databaseId);
+      return makeQueryDatabaseClientFrom(
+        Effect.map(databaseId, (id) =>
+          isLocalId(id)
+            ? makeD1DatabaseFromTransport(localTransport(id))
+            : makeHttpD1Database(auth, id),
+        ),
+      );
     });
   }),
 );

package/src/Cloudflare/Email/Address.ts

@@ -1,5 +1,6 @@
 import * as emailRouting from "@distilled.cloud/cloudflare/email-routing";
 import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
 import * as Stream from "effect/Stream";
 import { isResolved } from "../../Diff.ts";
 import * as Provider from "../../Provider.ts";
@@ -192,11 +193,27 @@ export const AddressProvider = () =>
     }),
     delete: Effect.fn(function* ({ output }) {
       if (!output?.addressId) return;
+      // Idempotent on the typed not-found; transient failures are retried
+      // bounded and a persistent failure surfaces — a swallowed failure
+      // silently leaks the destination address. Cloudflare refuses to
+      // delete an address for ~15 minutes after creation
+      // (`EmailAddressCreatedTooRecently`, code 2032) — retrying is
+      // pointless within a deploy's lifetime, so that error fails fast:
+      // either destroy later or retain the address (`RemovalPolicy.retain`).
       yield* emailRouting
         .deleteAddress({
           accountId: output.accountId,
           destinationAddressIdentifier: output.addressId,
         })
-        .pipe(Effect.catch(() => Effect.void));
+        .pipe(
+          Effect.catchTag("EmailAddressNotFound", () => Effect.void),
+          Effect.retry({
+            while: (e) => e._tag !== "EmailAddressCreatedTooRecently",
+            schedule: Schedule.max([
+              Schedule.spaced("3 seconds"),
+              Schedule.recurs(8),
+            ]),
+          }),
+        );
     }),
   });

package/src/Cloudflare/Email/SendBinding.ts

@@ -28,6 +28,7 @@ export const SendBinding = Layer.effect(
               allowedSenderAddresses: sender.allowedSenderAddresses,
             },
           ],
+          dev: sender.dev,
         });
       }
 

package/src/Cloudflare/Email/SendEmail.ts

@@ -24,6 +24,18 @@ export type SendEmailProps = {
    * {@link Routing}) and the addresses must be verified.
    */
   allowedSenderAddresses?: string[];
+  /**
+   * Configuration for the binding in `alchemy dev`.
+   * @default { remote: false }
+   */
+  dev?: {
+    /**
+     * Whether to send emails through the live Cloudflare Email service in development.
+     * If `false`, emails will be logged to the console instead.
+     * @default false
+     */
+    remote?: boolean;
+  };
 };
 
 /**
@@ -83,5 +95,6 @@ export const SendEmail: (
     destinationAddress: props?.destinationAddress,
     allowedDestinationAddresses: props?.allowedDestinationAddresses,
     allowedSenderAddresses: props?.allowedSenderAddresses,
+    dev: props?.dev,
   } satisfies SendEmail;
 });

package/src/Cloudflare/Flagship/App.ts

@@ -211,18 +211,30 @@ export const AppProvider = () =>
         .pipe(Effect.catchTag("FlagshipAppNotFound", () => Effect.void));
     }),
     // Account-scoped collection (pattern b): enumerate every app in the
-    // ambient account via the paginated listApps op. The list item shape
-    // matches GetAppResponse, so each maps directly into Attributes.
+    // ambient account via the paginated listApps op. Cloudflare's list
+    // index can contain ghost rows — apps that were deleted but survive in
+    // the listing while GET/DELETE both return "App not found" — so each
+    // row is validated via getApp and ghosts are dropped (otherwise census
+    // tooling re-discovers an undeletable app forever).
     list: Effect.fn(function* () {
       const { accountId } = yield* yield* CloudflareEnvironment;
-      return yield* flagship.listApps.pages({ accountId }).pipe(
+      const listed = yield* flagship.listApps.pages({ accountId }).pipe(
         Stream.runCollect,
         Effect.map((chunk) =>
-          Array.from(chunk).flatMap((page) =>
-            (page.result ?? []).map((app) => toAttributes(app, accountId)),
-          ),
+          Array.from(chunk).flatMap((page) => page.result ?? []),
         ),
       );
+      const rows = yield* Effect.forEach(
+        listed,
+        (app) =>
+          getApp(accountId, app.id).pipe(
+            Effect.map((observed) =>
+              observed ? toAttributes(observed, accountId) : undefined,
+            ),
+          ),
+        { concurrency: 10 },
+      );
+      return rows.filter((row): row is AppAttributes => row !== undefined);
     }),
   });
 

package/src/Cloudflare/KV/LocalKVGateway.ts

@@ -0,0 +1,86 @@
+/**
+ * Node-side path into the local workerd KV simulator, built on the
+ * runtime's platform proxy (`PlatformProxy.open` — our `getPlatformProxy`).
+ *
+ * For a `dev:` namespace there is no cloud namespace to speak REST to.
+ * Instead, each operation opens a scoped platform proxy hosting the native
+ * KV binding and runs against `proxy.env.KV` — the same
+ * `runtime.KVNamespace` surface the Worker-binding client builders
+ * (`makeReadKVClient` / `makeWriteKVClient`) already consume, so the
+ * `*Local` layers reuse those builders verbatim:
+ *
+ *   Node ── proxy.env.KV.get(...) ──▶ kv service ──▶ KVNamespaceObject
+ *
+ * One proxy boot per operation — slow but correct; the `*Local` layers run
+ * in deploy-time Actions, not on a request path. Data lands in the same
+ * `{storage}/kv` directory every local worker binding reads.
+ *
+ * NOT exported from `index.ts` — capability-internal scaffolding.
+ */
+import { KvNamespace } from "@distilled.cloud/cloudflare-runtime/bindings";
+import { open } from "@distilled.cloud/cloudflare-runtime/platform-proxy";
+import type * as runtime from "@cloudflare/workers-types";
+import type * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import { gatewayName, localGatewayRuntime } from "../LocalGateway.ts";
+import type { makeKVNamespaceHelpers } from "./NamespaceBinding.ts";
+import { NamespaceError } from "./NamespaceTypes.ts";
+
+const tryPromise = <T>(
+  fn: () => Promise<T>,
+): Effect.Effect<T, NamespaceError> =>
+  Effect.tryPromise({
+    try: fn,
+    catch: (error: any) =>
+      new NamespaceError({
+        message: error?.message ?? "Unknown error",
+        cause: error,
+      }),
+  });
+
+/**
+ * Binding-client helpers backed by a per-operation platform proxy instead
+ * of a Worker's `env`. `raw` cannot be satisfied — a native namespace only
+ * lives as long as its proxy's scope — so it dies with guidance.
+ */
+export const makeProxyKVNamespaceHelpers = (
+  namespaceId: string,
+  /**
+   * The FULL ambient stack-eval context: platform services for booting
+   * workerd plus `CloudflareEnvironment`/`AlchemyContext` for the runtime
+   * layer.
+   */
+  ambient: Context.Context<never>,
+): ReturnType<typeof makeKVNamespaceHelpers> => {
+  const use = <T>(
+    fn: (raw: runtime.KVNamespace<string>) => Promise<T>,
+  ): Effect.Effect<T, NamespaceError> =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const proxy = yield* open({
+          name: gatewayName("alchemy-kv-gateway", namespaceId),
+          bindings: [KvNamespace.local({ binding: "KV", id: namespaceId })],
+        });
+        const kv = (proxy.env as Record<string, unknown>)
+          .KV as runtime.KVNamespace<string>;
+        return yield* tryPromise(() => fn(kv));
+      }),
+    ).pipe(
+      Effect.provide(localGatewayRuntime),
+      // The gateway layer's platform requirements are satisfied by the
+      // ambient stack-eval context; `Context<never>` can't prove that
+      // statically, so erase the leftover R (and the proxy's own infra
+      // error channel) with a cast — mirroring D1's gateway.
+      Effect.provideContext(ambient),
+    ) as Effect.Effect<T, NamespaceError>;
+
+  const raw = Effect.die(
+    new NamespaceError({
+      message:
+        "A locally-emulated KV namespace has no long-lived native binding outside a Worker; use get/put/delete/list/getWithMetadata (each runs through a scoped local gateway).",
+      cause: new Error("unsupported"),
+    }),
+  ) as Effect.Effect<runtime.KVNamespace<string>>;
+
+  return { raw, use, tryPromise };
+};

package/src/Cloudflare/KV/Namespace.ts

@@ -3,10 +3,12 @@ import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
 import { isResolved } from "../../Diff.ts";
+import * as ProviderLayer from "../../Local/ProviderLayer.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
 import { isResourceOfType, Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import { generateLocalId } from "../LocalRuntime.ts";
 import type { Providers } from "../Providers.ts";
 
 export const isNamespace = (value: unknown): value is Namespace =>
@@ -71,7 +73,7 @@ export const Namespace = Resource<Namespace>("Cloudflare.KV.Namespace", {
   aliases: ["Cloudflare.KVNamespace"],
 });
 
-export const NamespaceProvider = () =>
+export const ProviderLive = () =>
   Provider.succeed(Namespace, {
     stables: ["namespaceId", "accountId"],
     diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
@@ -223,6 +225,50 @@ export const NamespaceProvider = () =>
     }),
   });
 
+/**
+ * Local (dev) provider — the namespace is purely virtual: a `dev:` id keyed
+ * into the local workerd KV simulator. `toRuntimeBinding` lowers a
+ * `kv_namespace` binding whose id is `dev:`-prefixed onto the local KV
+ * service; data persists under `.alchemy/local/kv`.
+ */
+export const ProviderLocal = () =>
+  Provider.succeed(Namespace, {
+    stables: ["accountId"],
+    diff: Effect.fn(function* ({ news = {}, output }) {
+      const { accountId } = yield* yield* CloudflareEnvironment;
+      if (!output?.namespaceId) return { action: "update" } as const;
+      if (!isResolved(news)) return undefined;
+      if (output.accountId !== accountId) {
+        return { action: "replace" } as const;
+      }
+      // Fall through to the engine's default prop diff (title renames
+      // update in place).
+    }),
+    read: Effect.fn(function* ({ output }) {
+      // Purely virtual — the persisted state row is the source of truth.
+      return output ?? undefined;
+    }),
+    reconcile: Effect.fn(function* ({ id, news = {}, output }) {
+      const { accountId } = yield* yield* CloudflareEnvironment;
+      return {
+        title: yield* createTitle(id, news.title),
+        namespaceId: output?.namespaceId ?? generateLocalId(),
+        supportsUrlEncoding: true,
+        accountId: output?.accountId ?? accountId,
+      };
+    }),
+    delete: Effect.fn(function* () {
+      // The simulator's on-disk data is keyed by the dev id; dropping the
+      // state row is enough — orphaned blobs are reclaimed with `.alchemy`.
+    }),
+  });
+
+export const NamespaceProvider = () =>
+  ProviderLayer.dual(Namespace, {
+    local: () => ProviderLocal(),
+    live: () => ProviderLive(),
+  });
+
 const createTitle = (id: string, title: string | undefined) =>
   Effect.gen(function* () {
     return title ?? (yield* createPhysicalName({ id }));

package/src/Cloudflare/KV/NamespaceLocal.ts

@@ -2,7 +2,10 @@ import * as Effect from "effect/Effect";
 import type * as HttpClient from "effect/unstable/http/HttpClient";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Credentials } from "../Credentials.ts";
+import { dispatchByMode } from "../LocalGateway.ts";
+import { makeProxyKVNamespaceHelpers } from "./LocalKVGateway.ts";
 import type { Namespace } from "./Namespace.ts";
+import type { makeKVNamespaceHelpers } from "./NamespaceBinding.ts";
 import type { KVAuth } from "./NamespaceHttp.ts";
 
 /**
@@ -10,15 +13,27 @@ import type { KVAuth } from "./NamespaceHttp.ts";
  *
  * Instead of minting a scoped {@link AccountApiToken} (the `*Http` path) or
  * resolving a native Worker binding (the `*Binding` path), it captures the
- * ambient current-credentials context available during stack-eval and builds
- * a {@link KVAuth} that provides those credentials directly to the KV HTTP
- * ops. It then delegates to the same client builders the `*Http` variant uses.
+ * ambient current-credentials context available during stack-eval and
+ * builds the client per resolved namespace id:
+ *
+ * - a REAL id gets the HTTP client (same builders as the `*Http` variant,
+ *   authorized with the current credentials — no `host.bind`, no minted
+ *   token);
+ * - a `dev:` id (local emulation under `alchemy dev`) gets the native
+ *   binding client (same builders as the `*Binding` variant) over a scoped
+ *   platform-proxy gateway (see `LocalKVGateway.ts`).
+ *
+ * The id resolves lazily at apply time, so the returned client dispatches
+ * per call.
  *
  * NOT exported from `index.ts` — this is internal scaffolding shared by the
  * three access-level Local layers.
  */
-export const makeLocalKVNamespaceBinding = <Client>(options: {
-  makeClient: (auth: KVAuth, namespaceId: Effect.Effect<string>) => Client;
+export const makeLocalKVNamespaceBinding = <Client extends object>(options: {
+  makeHttpClient: (auth: KVAuth, namespaceId: Effect.Effect<string>) => Client;
+  makeNativeClient: (
+    helpers: ReturnType<typeof makeKVNamespaceHelpers>,
+  ) => Client;
 }) =>
   Effect.gen(function* () {
     // Account + credentials are ambient during stack-eval (the stack's
@@ -28,6 +43,11 @@ export const makeLocalKVNamespaceBinding = <Client>(options: {
     const context = yield* Effect.context<
       Credentials | HttpClient.HttpClient
     >();
+    // The FULL ambient context, for the dev-mode gateway: booting an
+    // ephemeral workerd needs the platform services and the Cloudflare
+    // environment, all present during stack-eval but not statically
+    // enumerable here.
+    const ambient = yield* Effect.context<never>();
 
     return Effect.fn(function* (namespace: Namespace) {
       // Deferred accessor — resolves the namespaceId against the tracker at
@@ -37,6 +57,9 @@ export const makeLocalKVNamespaceBinding = <Client>(options: {
         authorize: (eff) => eff.pipe(Effect.provideContext(context)),
         accountId: Effect.succeed(accountId),
       };
-      return options.makeClient(auth, namespaceId);
+      const httpClient = options.makeHttpClient(auth, namespaceId);
+      return dispatchByMode(namespaceId, httpClient, (id) =>
+        options.makeNativeClient(makeProxyKVNamespaceHelpers(id, ambient)),
+      );
     });
   });

package/src/Cloudflare/KV/ReadNamespaceLocal.ts

@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import { makeReadKVClient } from "./ReadNamespaceBinding.ts";
 import { makeLocalKVNamespaceBinding } from "./NamespaceLocal.ts";
 import { ReadNamespace } from "./ReadNamespace.ts";
 import { makeReadKVHttpClient } from "./ReadNamespaceHttp.ts";
@@ -30,6 +31,9 @@ import { makeReadKVHttpClient } from "./ReadNamespaceHttp.ts";
 export const ReadNamespaceLocal = Layer.effect(
   ReadNamespace,
   Effect.suspend(() =>
-    makeLocalKVNamespaceBinding({ makeClient: makeReadKVHttpClient }),
+    makeLocalKVNamespaceBinding({
+      makeHttpClient: makeReadKVHttpClient,
+      makeNativeClient: makeReadKVClient,
+    }),
   ),
 );

package/src/Cloudflare/KV/ReadWriteNamespaceLocal.ts

@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import { makeReadWriteKVClient } from "./ReadWriteNamespaceBinding.ts";
 import { makeLocalKVNamespaceBinding } from "./NamespaceLocal.ts";
 import { ReadWriteNamespace } from "./ReadWriteNamespace.ts";
 import { makeReadWriteKVHttpClient } from "./ReadWriteNamespaceHttp.ts";
@@ -37,6 +38,9 @@ import { makeReadWriteKVHttpClient } from "./ReadWriteNamespaceHttp.ts";
 export const ReadWriteNamespaceLocal = Layer.effect(
   ReadWriteNamespace,
   Effect.suspend(() =>
-    makeLocalKVNamespaceBinding({ makeClient: makeReadWriteKVHttpClient }),
+    makeLocalKVNamespaceBinding({
+      makeHttpClient: makeReadWriteKVHttpClient,
+      makeNativeClient: makeReadWriteKVClient,
+    }),
   ),
 );

package/src/Cloudflare/KV/WriteNamespaceLocal.ts

@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import { makeWriteKVClient } from "./WriteNamespaceBinding.ts";
 import { makeLocalKVNamespaceBinding } from "./NamespaceLocal.ts";
 import { WriteNamespace } from "./WriteNamespace.ts";
 import { makeWriteKVHttpClient } from "./WriteNamespaceHttp.ts";
@@ -30,6 +31,9 @@ import { makeWriteKVHttpClient } from "./WriteNamespaceHttp.ts";
 export const WriteNamespaceLocal = Layer.effect(
   WriteNamespace,
   Effect.suspend(() =>
-    makeLocalKVNamespaceBinding({ makeClient: makeWriteKVHttpClient }),
+    makeLocalKVNamespaceBinding({
+      makeHttpClient: makeWriteKVHttpClient,
+      makeNativeClient: makeWriteKVClient,
+    }),
   ),
 );

package/src/Cloudflare/LocalGateway.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared scaffolding for the local-simulator gateways.
+ *
+ * The local binding simulators (KV, R2, D1, ...) live inside workerd — only
+ * a Worker with the native binding can reach them. Deploy-time code (Action
+ * capability clients, provider reconciles) runs in Node, so the `*Local`
+ * layers bridge the two with the runtime's platform proxy
+ * (`PlatformProxy.open` — our `getPlatformProxy`): a scoped workerd
+ * instance hosts the binding, and Node drives it through proxied clients.
+ *
+ * NOT exported from `index.ts` — provider/capability-internal scaffolding.
+ */
+import { layerRuntime } from "@distilled.cloud/cloudflare-runtime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import { AlchemyContext } from "../AlchemyContext.ts";
+import { CloudflareEnvironment } from "./CloudflareEnvironment.ts";
+import { isLocalId } from "./LocalRuntime.ts";
+
+/**
+ * A standalone local-runtime layer for gateway consumers OUTSIDE the
+ * provider stack (e.g. capability `*Local` layers running in an Action,
+ * whose ambient context has no workerd `Runtime`). Configured identically
+ * to the providers' shared runtime — same `.alchemy/local` storage
+ * directory — so it reads and writes the same simulator data.
+ */
+export const localGatewayRuntime = Layer.unwrap(
+  Effect.gen(function* () {
+    const getEnv = yield* CloudflareEnvironment;
+    const { dotAlchemy } = yield* AlchemyContext;
+    const path = yield* Path.Path;
+    return layerRuntime({
+      api: {
+        accountId: getEnv.pipe(Effect.map((env) => env.accountId)),
+      },
+      storage: {
+        directory: path.join(dotAlchemy, "local"),
+      },
+    });
+  }),
+);
+
+/** Sanitize an id into a workerd instance-name-safe suffix. */
+export const gatewayName = (prefix: string, id: string) =>
+  `${prefix}-${id.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
+
+/**
+ * Build a client whose every member resolves the resource id first and then
+ * delegates: `dev:` ids to the (memoized) native-over-gateway client, real
+ * ids to the HTTP client. Function members dispatch per call; Effect-valued
+ * members (`raw`) dispatch on evaluation. Used by the `*Local` capability
+ * scaffolding (KV, R2) where the id is a deferred accessor resolved at
+ * apply time.
+ */
+export const dispatchByMode = <Client extends object>(
+  resourceId: Effect.Effect<string>,
+  httpClient: Client,
+  makeNative: (id: string) => Client,
+): Client => {
+  let native: Client | undefined;
+  let nativeId: string | undefined;
+  const nativeFor = (id: string): Client => {
+    if (nativeId !== id) {
+      nativeId = id;
+      native = makeNative(id);
+    }
+    return native!;
+  };
+  const pick = (id: string): Client =>
+    isLocalId(id) ? nativeFor(id) : httpClient;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(httpClient)) {
+    out[key] =
+      typeof value === "function"
+        ? (...args: unknown[]) =>
+            Effect.flatMap(resourceId, (id) =>
+              (pick(id) as Record<string, any>)[key](...args),
+            )
+        : Effect.flatMap(
+            resourceId,
+            (id) => (pick(id) as Record<string, any>)[key],
+          );
+  }
+  return out as Client;
+};

package/src/Cloudflare/LocalRuntime.ts

@@ -60,7 +60,7 @@ const LocalRuntimeStateLive = Layer.succeed(
   }),
 );
 
-export const localRuntimeServices = () =>
+const makeLocalRuntimeServices = () =>
   RpcProvider.providerServicesEffect(
     Effect.gen(function* () {
       const getEnv = yield* CloudflareEnvironment;
@@ -80,6 +80,26 @@ export const localRuntimeServices = () =>
     }),
   );
 
+let _localRuntimeServices:
+  | ReturnType<typeof makeLocalRuntimeServices>
+  | undefined;
+
+/**
+ * The shared local-runtime dependency layer (workerd `Runtime`,
+ * `WorkerProxy`, {@link LocalRuntimeState}) used by every Cloudflare local
+ * provider.
+ *
+ * Returns a **module-memoized layer reference**: local providers register
+ * via `ProviderLayer.dual`, which builds each provider's local variant
+ * lazily against the stack build's shared `Layer.MemoMap` — memoization is
+ * keyed by layer identity, so Worker/Queue/Consumer/Container composing
+ * this exact reference into their local thunks share one runtime instance
+ * per stack build (a fresh build gets a fresh instance via its own memo
+ * map; the layer blueprint itself is immutable).
+ */
+export const localRuntimeServices = () =>
+  (_localRuntimeServices ??= makeLocalRuntimeServices());
+
 export const isLocalId = (id: string | undefined): id is string =>
   typeof id === "string" && id.startsWith("dev:");
 export const isLiveId = (id: string | undefined): id is string =>