alchemy 2.0.0-beta.65 → 2.0.0-beta.67

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 =>

package/src/Cloudflare/Logs.ts

@@ -78,6 +78,30 @@ export const CloudflareLogs = Effect.gen(function* () {
   const createScriptTail = yield* workers.createScriptTail;
   const deleteScriptTail = yield* workers.deleteScriptTail;
 
+  /**
+   * The telemetry query needs the `workers_observability:read` OAuth scope.
+   * A token minted by an older `alchemy login` (before the scope joined the
+   * defaults) keeps its original grants forever, so the query fails with a
+   * bare `Unauthorized`/`Forbidden` even though a fresh login would work —
+   * explain the fix instead of surfacing the raw tag.
+   */
+  const explainMissingObservabilityScope = <A, R>(
+    effect: Effect.Effect<A, workers.QueryObservabilityTelemetryError, R>,
+  ): Effect.Effect<A, workers.QueryObservabilityTelemetryError, R> =>
+    effect.pipe(
+      Effect.catchTag("Unauthorized", () =>
+        Effect.die(
+          new Error(
+            "Cloudflare rejected the observability telemetry query (Unauthorized). " +
+              'Your stored credentials are likely missing the "workers_observability:read" scope — ' +
+              "OAuth tokens keep the scopes they were minted with, so tokens from an older " +
+              "`alchemy login` won't have it. Run `alchemy login` again to mint a token with " +
+              "the current default scopes, or use an API token that grants Workers Observability read access.",
+          ),
+        ),
+      ),
+    );
+
   const queryLogs = (opts: {
     accountId: string;
     filters: TelemetryFilter[];
@@ -88,30 +112,34 @@ export const CloudflareLogs = Effect.gen(function* () {
       const limit = opts.options.limit ?? 100;
 
       if (opts.options.since) {
-        const response = yield* queryTelemetry({
+        const response = yield* explainMissingObservabilityScope(
+          queryTelemetry({
+            accountId: opts.accountId,
+            queryId: "events",
+            view: "events",
+            timeframe: { from: opts.options.since.getTime(), to: now },
+            limit,
+            parameters: {
+              filters: opts.filters,
+              // orderBy: { value: "timestamp", order: "desc" },
+            },
+          }),
+        );
+        return parseEvents(response);
+      }
+
+      const response = yield* explainMissingObservabilityScope(
+        queryTelemetry({
           accountId: opts.accountId,
           queryId: "events",
           view: "events",
-          timeframe: { from: opts.options.since.getTime(), to: now },
+          timeframe: { from: now - DEFAULT_LOOKBACK_MS, to: now },
           limit,
           parameters: {
             filters: opts.filters,
-            // orderBy: { value: "timestamp", order: "desc" },
           },
-        });
-        return parseEvents(response);
-      }
-
-      const response = yield* queryTelemetry({
-        accountId: opts.accountId,
-        queryId: "events",
-        view: "events",
-        timeframe: { from: now - DEFAULT_LOOKBACK_MS, to: now },
-        limit,
-        parameters: {
-          filters: opts.filters,
-        },
-      });
+        }),
+      );
 
       return parseEvents(response);
     });
@@ -207,17 +235,19 @@ export const CloudflareLogs = Effect.gen(function* () {
           yield* Effect.sleep("2 seconds");
           const now = Date.now();
 
-          const response = yield* queryTelemetry({
-            accountId: opts.accountId,
-            queryId: "events",
-            view: "events",
-            timeframe: { from: since, to: now },
-            limit: 100,
-            parameters: {
-              filters: opts.filters,
-              orderBy: { value: "timestamp", order: "asc" },
-            },
-          });
+          const response = yield* explainMissingObservabilityScope(
+            queryTelemetry({
+              accountId: opts.accountId,
+              queryId: "events",
+              view: "events",
+              timeframe: { from: since, to: now },
+              limit: 100,
+              parameters: {
+                filters: opts.filters,
+                orderBy: { value: "timestamp", order: "asc" },
+              },
+            }),
+          );
 
           const lines = parseEvents(response);
           const nextSince =

package/src/Cloudflare/Providers.ts

@@ -78,7 +78,6 @@ import * as KeylessCertificate from "./KeylessCertificate/index.ts";
 import * as KV from "./KV/index.ts";
 import * as LeakedCredentialCheck from "./LeakedCredentialCheck/index.ts";
 import * as LoadBalancer from "./LoadBalancer/index.ts";
-import { localRuntimeServices } from "./LocalRuntime.ts";
 import * as Logpush from "./Logpush/index.ts";
 import * as LogsControl from "./LogsControl/index.ts";
 import * as MagicCloudNetworking from "./MagicCloudNetworking/index.ts";
@@ -683,7 +682,10 @@ export const providers = () =>
       ),
     ),
     Layer.provide(DockerLive),
-    Layer.provideMerge(localRuntimeServices()),
+    // Note: `localRuntimeServices()` is no longer provided globally — each
+    // local provider composes it into its `ProviderLayer.dual` local thunk,
+    // so workerd machinery only builds when a local variant is actually
+    // demanded (dev runs, or deleting a local-mode row during deploy).
     Layer.provideMerge(CloudflareApiLive()),
     Layer.orDie,
   );

package/src/Cloudflare/Queues/Consumer.ts

@@ -1,5 +1,6 @@
 import * as queues from "@distilled.cloud/cloudflare/queues";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as MutableHashMap from "effect/MutableHashMap";
 import * as Option from "effect/Option";
 import * as Schedule from "effect/Schedule";
@@ -14,6 +15,7 @@ import {
   isLiveId,
   LOCAL_ENTRY_URL,
   LocalRuntimeState,
+  localRuntimeServices,
 } from "../LocalRuntime.ts";
 import type { Providers } from "../Providers.ts";
 
@@ -72,6 +74,18 @@ export type Consumer = Resource<
     accountId: string;
     deadLetterQueue?: string;
     settings?: ConsumerSettings;
+    /**
+     * Dev only, live queues only: the real queue's name, resolved from the
+     * cloud so the local runtime can wire the broker + pull loop for a
+     * locally-running consumer of an `Alchemy.remote()` queue.
+     */
+    queueName?: string;
+    /**
+     * Dev only, live queues only: id of the `http_pull` consumer attached
+     * to the real queue so the local runtime can drain it via the HTTP
+     * pull API. Deleted when this resource is deleted.
+     */
+    pullConsumerId?: string;
   },
   never,
   Providers
@@ -636,6 +650,40 @@ export const ConsumerProviderLocal = () =>
         }),
         reconcile: Effect.fn(function* ({ news, output }) {
           const { accountId } = yield* yield* CloudflareEnvironment;
+          // A LIVE queue (`Alchemy.remote()`) consumed by a LOCAL worker:
+          // Cloudflare only pushes to deployed consumers, so the local
+          // runtime drains the real queue via the HTTP pull API instead.
+          // Observe the queue (name + existing consumers) and ensure an
+          // `http_pull` consumer exists for the pull loop to lease from.
+          let queueName: string | undefined;
+          let pullConsumerId: string | undefined;
+          if (isLiveId(news.queueId)) {
+            const queue = yield* queues.getQueue({
+              accountId,
+              queueId: news.queueId,
+            });
+            queueName = queue.queueName ?? undefined;
+            const existingPull = (queue.consumers ?? []).find(
+              (c) => c.type === "http_pull",
+            );
+            if (existingPull?.consumerId) {
+              pullConsumerId = existingPull.consumerId;
+            } else {
+              const created = yield* queues.createConsumer({
+                accountId,
+                queueId: news.queueId,
+                type: "http_pull",
+                settings: {
+                  batchSize: news.settings?.batchSize,
+                  maxRetries: news.settings?.maxRetries,
+                  retryDelay: news.settings?.retryDelay,
+                },
+              });
+              pullConsumerId =
+                ("consumerId" in created ? created.consumerId : undefined) ??
+                undefined;
+            }
+          }
           const consumer: Consumer["Attributes"] = {
             consumerId: output?.consumerId ?? `dev:${crypto.randomUUID()}`,
             queueId: news.queueId,
@@ -643,6 +691,8 @@ export const ConsumerProviderLocal = () =>
             deadLetterQueue: news.deadLetterQueue,
             accountId,
             settings: news.settings,
+            queueName,
+            pullConsumerId,
           };
           MutableHashMap.set(
             localRuntimeState.queueConsumers,
@@ -668,13 +718,31 @@ export const ConsumerProviderLocal = () =>
             output.consumerId,
           );
           yield* restartScripts([output.scriptName]);
+          // Remove the http_pull consumer this row attached to its live
+          // queue. Idempotent: gone-already (or queue deleted first) is
+          // success.
+          if (output.pullConsumerId && isLiveId(output.queueId)) {
+            yield* queues
+              .deleteConsumer({
+                accountId: output.accountId,
+                queueId: output.queueId,
+                consumerId: output.pullConsumerId,
+              })
+              .pipe(
+                Effect.catchTag(
+                  ["ConsumerNotFound", "QueueNotFound"],
+                  () => Effect.void,
+                ),
+              );
+          }
         }),
       };
     }),
   );
 
 export const ConsumerProvider = () =>
-  ProviderLayer.select({
-    local: () => ConsumerProviderLocal(),
+  ProviderLayer.dual(Consumer, {
+    local: () =>
+      ConsumerProviderLocal().pipe(Layer.provide(localRuntimeServices())),
     live: () => ConsumerProviderLive(),
   });

package/src/Cloudflare/Queues/Queue.ts

@@ -1,5 +1,6 @@
 import * as queues from "@distilled.cloud/cloudflare/queues";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as MutableHashMap from "effect/MutableHashMap";
 import * as Option from "effect/Option";
 import * as Schedule from "effect/Schedule";
@@ -13,9 +14,9 @@ import { isResourceOfType, Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import {
   generateLocalId,
-  isLiveId,
   LOCAL_ENTRY_URL,
   LocalRuntimeState,
+  localRuntimeServices,
 } from "../LocalRuntime.ts";
 import type { Providers } from "../Providers.ts";
 
@@ -109,16 +110,10 @@ export const Queue = Resource<Queue>("Cloudflare.Queues.Queue", {
 
 export const ProviderLive = () =>
   Provider.succeed(Queue, {
-    // The `queueId` is not marked as stable because if you start in dev mode, the ID will change on first deploy.
-    stables: ["accountId"],
+    stables: ["queueId", "accountId"],
     diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
       const { accountId } = yield* yield* CloudflareEnvironment;
       if (!isResolved(news)) return undefined;
-      // If the queueId is a `dev:` ID, we need to update to a live one.
-      // The live resource doesn't exist yet, so there's no need to replace even if the name or accountId changed.
-      if (!isLiveId(output?.queueId)) {
-        return { action: "update" };
-      }
       if ((output?.accountId ?? accountId) !== accountId) {
         return { action: "replace" } as const;
       }
@@ -143,9 +138,7 @@ export const ProviderLive = () =>
       let observed:
         | { queueId?: string | null; queueName?: string | null }
         | undefined;
-      // A `dev:` id never exists on Cloudflare — skip straight to the
-      // name scan (promotion from dev to live).
-      if (output?.queueId && isLiveId(output.queueId)) {
+      if (output?.queueId) {
         observed = yield* queues
           .getQueue({
             accountId: acct,
@@ -196,8 +189,6 @@ export const ProviderLive = () =>
       };
     }),
     delete: Effect.fn(function* ({ output }) {
-      // If the queueId is a `dev:` ID, the resource only exists locally, so we don't need to delete it from Cloudflare.
-      if (!isLiveId(output.queueId)) return;
       // Dependents (e.g. R2 event notification configs targeting this
       // queue) may still be tearing down concurrently — ride out the
       // dependency violation briefly, then fail loudly instead of
@@ -240,7 +231,7 @@ export const ProviderLive = () =>
     }),
     read: Effect.fn(function* ({ id, output, olds }) {
       const { accountId } = yield* yield* CloudflareEnvironment;
-      if (output?.queueId && isLiveId(output.queueId)) {
+      if (output?.queueId) {
         return yield* queues
           .getQueue({
             accountId: output.accountId,
@@ -340,7 +331,7 @@ export const ProviderLocal = () =>
   );
 
 export const QueueProvider = () =>
-  ProviderLayer.select({
-    local: () => ProviderLocal(),
+  ProviderLayer.dual(Queue, {
+    local: () => ProviderLocal().pipe(Layer.provide(localRuntimeServices())),
     live: () => ProviderLive(),
   });

package/src/Cloudflare/Queues/QueueBinding.ts

@@ -2,6 +2,7 @@ import type * as runtime from "@cloudflare/workers-types";
 import * as Effect from "effect/Effect";
 import { Worker, WorkerEnvironment } from "../Workers/Worker.ts";
 import type { Queue } from "./Queue.ts";
+import { maybeQueueShim } from "./QueueShim.ts";
 import { SendError } from "./QueueTypes.ts";
 
 /**
@@ -18,15 +19,35 @@ export const makeQueueBinding = <Client>(options: {
   Effect.gen(function* () {
     const env = yield* WorkerEnvironment;
     const host = yield* Worker;
+    // Deploy-time ambient context (providers, stack). Captured at layer
+    // init so the shim registration below can run inside the callable —
+    // whose contract requires `R = never` — without leaking engine
+    // requirements into the binding's public type. Only dereferenced under
+    // the `__ALCHEMY_RUNTIME__` guard, where the context is the stack
+    // eval's (at runtime the captured context lacks providers, but the
+    // guarded branch never runs there).
+    const context = yield* Effect.context<never>();
 
     return Effect.fn(function* (queue: Queue) {
       if (!globalThis.__ALCHEMY_RUNTIME__) {
+        // A LOCAL host binding a LIVE queue needs the dev-mode
+        // remote-producer shim (see `QueueShim.ts`) — registered here as
+        // ordinary engine-managed resources, like the `AccountApiToken`
+        // the HTTP capability layers mint.
+        const shim = yield* maybeQueueShim(queue, host).pipe(
+          Effect.provideContext(context),
+        ) as Effect.Effect<Effect.Success<ReturnType<typeof maybeQueueShim>>>;
         yield* host.bind`${queue}`({
           bindings: [
             {
               type: "queue",
               name: queue.LogicalId,
               queueName: queue.queueName,
+              // Alchemy-only mode discriminator for dev (stripped before
+              // upload): a `dev:` id keeps the local broker, a real id
+              // (Alchemy.remote()) routes through the deployed shim.
+              queueId: queue.queueId,
+              ...(shim ? { shim } : {}),
             },
           ],
         });

package/src/Cloudflare/Queues/QueueShim.ts

@@ -0,0 +1,193 @@
+/**
+ * Dev-mode remote-producer shim for `Alchemy.remote()` queues.
+ *
+ * Cloudflare's preview/remote-binding sessions reject queue bindings
+ * outright (a preview worker carrying one serves 503 for every request;
+ * wrangler has the same gap — cloudflare/workers-sdk#9929), so a locally
+ * running worker cannot produce to a live queue through the usual
+ * remote-binding proxy. Instead, alchemy deploys a REAL shim worker that
+ * holds the actual queue binding:
+ *
+ *   local worker ── env.QUEUE.send() ──▶ forwarder service (local workerd)
+ *        POST /message | /batch  +  Authorization: Bearer <token>
+ *                                   │
+ *                                   ▼
+ *                     deployed shim worker (workers.dev)
+ *                                   │  env.QUEUE.send(body, { contentType })
+ *                                   ▼
+ *                            real Cloudflare Queue
+ *
+ * The shim and its bearer token are ordinary engine-managed resources
+ * ({@link Worker} + {@link Random}), conditionally instantiated at eval
+ * time when a LOCAL worker binds a LIVE queue — the same idiom as
+ * `AccountApiToken` (capability layers minting token resources) and
+ * event-source mappings. The engine gives the full lifecycle for free:
+ * Output-based ordering (shim deploys before the local worker serves),
+ * stable-name updates, deletion on destroy, and orphan GC on promotion
+ * (`alchemy deploy` no longer registers the shim, so it is cleaned up).
+ *
+ * NOT exported from `index.ts` — binding-internal scaffolding.
+ */
+import * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type * as Output from "../../Output.ts";
+import {
+  defaultProviderMode,
+  remote,
+  type ProviderMode,
+} from "../../ProviderMode.ts";
+import { Random } from "../../Random.ts";
+import { Worker } from "../Workers/Worker.ts";
+import type { Queue } from "./Queue.ts";
+
+/**
+ * The deployed shim's script: decodes workerd's queue wire protocol
+ * (`POST /message` with raw bytes + `X-Msg-Fmt`, `POST /batch` with base64
+ * payloads) back into `send()`/`sendBatch()` calls on its real queue
+ * binding, gated by a bearer token.
+ *
+ * `v8`-serialized messages cannot cross the boundary — deserializing V8
+ * payloads in userland is not possible — so they are rejected with a clear
+ * error telling the caller to pass an explicit contentType.
+ */
+const QUEUE_SHIM_SCRIPT = `class HttpError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+
+function decodeBody(contentType, bytes) {
+  switch (contentType) {
+    case "text":
+      return { contentType, body: new TextDecoder().decode(bytes) };
+    case "json":
+      return { contentType, body: JSON.parse(new TextDecoder().decode(bytes)) };
+    case "bytes":
+      return { contentType, body: bytes.slice().buffer };
+    case "v8":
+      throw new HttpError(
+        422,
+        'v8-serialized queue messages cannot be produced to a live queue from local dev; pass an explicit contentType of "json", "text", or "bytes" to send()/sendBatch()',
+      );
+    default:
+      throw new HttpError(400, "message content type " + contentType + " is invalid");
+  }
+}
+
+function base64ToBytes(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+function getDelay(value) {
+  if (!value) return undefined;
+  const delay = Number(value);
+  if (!Number.isInteger(delay) || delay < 0) {
+    throw new HttpError(400, "message delay " + value + " is invalid");
+  }
+  return delay;
+}
+
+// workerd's queue client requires this response shape (SendMetadata);
+// the metrics are informational and synthesized as zeros here.
+const sendResponse = () =>
+  Response.json({
+    metadata: {
+      metrics: { backlogCount: 0, backlogBytes: 0, oldestMessageTimestamp: 0 },
+    },
+  });
+
+export default {
+  async fetch(request, env) {
+    try {
+      const auth = request.headers.get("authorization");
+      if (auth !== "Bearer " + env.SHIM_TOKEN) {
+        throw new HttpError(401, "unauthorized");
+      }
+      if (request.method !== "POST") {
+        throw new HttpError(405, "method " + request.method + " not allowed");
+      }
+      const url = new URL(request.url);
+      switch (url.pathname) {
+        case "/message": {
+          // workerd's absent-header default is "v8" — mirrored here so an
+          // unmarked payload is rejected rather than misparsed.
+          const contentType = request.headers.get("X-Msg-Fmt") ?? "v8";
+          const delaySeconds = getDelay(request.headers.get("X-Msg-Delay-Secs"));
+          const bytes = new Uint8Array(await request.arrayBuffer());
+          const decoded = decodeBody(contentType, bytes);
+          await env.QUEUE.send(decoded.body, {
+            contentType: decoded.contentType,
+            ...(delaySeconds !== undefined && { delaySeconds }),
+          });
+          return sendResponse();
+        }
+        case "/batch": {
+          const delaySeconds = getDelay(request.headers.get("X-Msg-Delay-Secs"));
+          const body = await request.json();
+          const messages = body.messages.map((message) => {
+            const decoded = decodeBody(message.contentType, base64ToBytes(message.body));
+            const delay = message.delaySecs ?? delaySeconds;
+            return {
+              body: decoded.body,
+              contentType: decoded.contentType,
+              ...(delay !== undefined && { delaySeconds: delay }),
+            };
+          });
+          await env.QUEUE.sendBatch(messages);
+          return sendResponse();
+        }
+        default:
+          throw new HttpError(404, "not found");
+      }
+    } catch (e) {
+      if (e instanceof HttpError) {
+        return new Response(e.message, { status: e.status });
+      }
+      const message = e instanceof Error ? e.message : String(e);
+      return new Response("queue shim failed: " + message, { status: 500 });
+    }
+  },
+};`;
+
+export interface QueueShimBinding {
+  url: Output.Output<string | undefined>;
+  token: Output.Output<Redacted.Redacted<string>>;
+}
+
+/**
+ * Conditionally instantiate the queue shim for a producer binding: when a
+ * LOCAL host worker binds a LIVE queue (dev run + `Alchemy.remote()` on the
+ * queue), register the shim worker + its token and return their outputs
+ * for the binding data. Any other mode combination returns `undefined` —
+ * including the shim worker's own eval of its queue binding (the shim is
+ * pinned live, so no recursion).
+ */
+export const maybeQueueShim = Effect.fn(function* (
+  queue: Queue,
+  host: { Mode?: ProviderMode | undefined },
+) {
+  const runDefault = yield* defaultProviderMode;
+  const hostMode = host.Mode ?? runDefault;
+  const queueMode = queue.Mode ?? runDefault;
+  if (hostMode !== "local" || queueMode !== "live") {
+    return undefined;
+  }
+  const token = yield* Random(`${queue.LogicalId}ShimToken`);
+  const shim = yield* Worker(`${queue.LogicalId}Shim`, {
+    script: QUEUE_SHIM_SCRIPT,
+    env: {
+      QUEUE: queue,
+      SHIM_TOKEN: token.text,
+    },
+  }).pipe(remote());
+  return {
+    url: shim.url,
+    token: token.text,
+  } satisfies QueueShimBinding;
+});