alchemy 2.0.0-beta.59 → 2.0.0-beta.60

package/src/Cloudflare/Containers/LocalContainerProvider.ts

@@ -1,9 +1,10 @@
 import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
 import { AlchemyContext } from "../../AlchemyContext.ts";
 import * as Artifacts from "../../Artifacts.ts";
-import { materializeDockerfile } from "../../Bundle/Docker.ts";
 import { getStableContextDir } from "../../Bundle/TempRoot.ts";
 import { isResolved } from "../../Diff.ts";
+import { Docker } from "../../Docker/Docker.ts";
 import * as RpcProvider from "../../Local/RpcProvider.ts";
 import { sha256Object } from "../../Util/sha256.ts";
 import { normalizeNulls } from "../../Util/stable.ts";
@@ -41,6 +42,8 @@ export const LocalContainerProvider = () =>
     LOCAL_ENTRY_URL,
     Effect.gen(function* () {
       const { dotAlchemy } = yield* AlchemyContext;
+      const docker = yield* Docker;
+      const path = yield* Path.Path;
 
       // Bundle the container entrypoint and write it (plus the generated
       // Dockerfile) into a stable build context directory. `Docker.build` in
@@ -68,7 +71,7 @@ export const LocalContainerProvider = () =>
           news.external,
           news.autoInstallExternals,
         );
-        const [bundle, dockerfile] = yield* Effect.all(
+        const [bundle] = yield* Effect.all(
           [
             bundleContainerProgram({
               id,
@@ -79,13 +82,17 @@ export const LocalContainerProvider = () =>
               external: news.external,
               outdir: context,
             }),
-            materializeDockerfile(dockerfileContent, context),
+            docker.materialize({
+              context: context,
+              dockerfile: dockerfileContent,
+              files: [],
+            }),
           ],
           { concurrency: "unbounded" },
         );
         return {
           context,
-          dockerfile,
+          dockerfile: path.join(context, "Dockerfile"),
           hash: yield* sha256Object({
             bundle: bundle.hash,
             dockerfileContent,

package/src/Cloudflare/Containers/StartContainer.ts

@@ -2,6 +2,7 @@ import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Schedule from "effect/Schedule";
+import * as Semaphore from "effect/Semaphore";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
 import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
@@ -9,13 +10,62 @@ import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
 import { ALCHEMY_PHASE } from "../../Phase.ts";
 import { makeFetchRpcStub } from "../../Rpc.ts";
 import { type Fetcher } from "../Fetcher.ts";
+import { DurableObjectState } from "../Workers/DurableObjectState.ts";
 import {
+  ContainerCrashedError,
   ContainerError,
+  ContainerRateLimitedError,
   ContainerTag,
+  NoContainerInstanceError,
   type Container,
   type ContainerStartupOptions,
 } from "./Container.ts";
 
+/**
+ * Per-container-instance start coordination (start mutex + confirmed-ready
+ * port cache).
+ *
+ * `startContainer` can be invoked more than once for the same physical
+ * container: the {@link layer} helper calls it once per Durable Object, but a
+ * caller may also use `startContainer` directly from several places. If the
+ * mutex/ready-cache lived in each `startContainer` closure, those calls would
+ * not coordinate — two of them could both observe `running === false` and both
+ * call `container.start()`, with the second throwing "already running" (see
+ * cloudflare/containers#173).
+ *
+ * Keying off the Durable Object's `DurableObjectState` (stable for the life of
+ * a DO instance, and a distinct object per instance) makes the coordination
+ * per-container-instance regardless of how many `startContainer` calls share
+ * it. The map is module-scoped, but Workers isolates are per-isolate and each
+ * DO instance has its own `DurableObjectState`, so instances never collide; the
+ * `WeakMap` lets entries be collected with the instance. We deliberately do NOT
+ * key on the container's logical id — that is shared across every
+ * `getByName(...)` instance of the same class, which must each start
+ * independently.
+ */
+const startCoordination = new WeakMap<
+  object,
+  {
+    readonly startMutex: ReturnType<typeof Semaphore.makeUnsafe>;
+    readonly readyPorts: Set<number>;
+  }
+>();
+
+const getStartCoordination = (key: object) => {
+  let coordination = startCoordination.get(key);
+  if (!coordination) {
+    // `makeUnsafe` (rather than `Effect.makeSemaphore`) because this runs in a
+    // synchronous cache-miss branch; the semaphore is a plain mutable primitive
+    // shared across effects, created once per DO instance.
+    coordination = {
+      startMutex: Semaphore.makeUnsafe(1),
+      readyPorts: new Set<number>(),
+    };
+    startCoordination.set(key, coordination);
+  }
+  return coordination;
+};
+
 export const layer = <Image extends Container.Decl.Any>(
   container: Image,
   options?: ContainerStartupOptions,
@@ -45,38 +95,261 @@ export const startContainer = Effect.fn(function* <
     ? yield* bound as Effect.Effect<Container>
     : (bound as Container);
 
+  // Every constant below is taken directly from Cloudflare's own
+  // `@cloudflare/containers` runtime (`dist/lib/container.js`) rather than
+  // guessed, so our readiness behaviour matches `startAndWaitForPorts`:
+  //
+  //   INSTANCE_POLL_INTERVAL_MS  = 300    → fixed poll interval
+  //   PING_TIMEOUT_MS            = 5_000  → per-probe cap (addTimeoutSignal)
+  //   TIMEOUT_TO_GET_CONTAINER_MS = 8_000 → phase 1: find+start an instance
+  //   TIMEOUT_TO_GET_PORTS_MS    = 20_000 → phase 2: wait for the port to listen
+  //
+  // Native derives its retry COUNTS as ceil(timeout / pollInterval); we keep
+  // the two phases separate (as native does) on a 300ms cadence.
+  const READINESS_POLL_INTERVAL = Duration.millis(300); // INSTANCE_POLL_INTERVAL_MS
+  const READINESS_PROBE_TIMEOUT = Duration.seconds(5); // PING_TIMEOUT_MS
+  const TIMEOUT_TO_GET_CONTAINER_MS = 8_000;
+  const TIMEOUT_TO_GET_PORTS_MS = 20_000;
+  const GET_CONTAINER_RETRIES = Math.ceil(TIMEOUT_TO_GET_CONTAINER_MS / 300); // 27
+  const PORT_READY_RETRIES = Math.ceil(TIMEOUT_TO_GET_PORTS_MS / 300); // 67
+  // When rate limited, back off hard before retrying — hammering `start()`
+  // only prolongs the limit (native returns 429 immediately and does not loop).
+  const RATE_LIMIT_BACKOFF = Duration.seconds(2);
+  const RATE_LIMIT_RETRIES = 5;
+  // Light retry for the real request only — covers the transient
+  // "Network connection lost" window when a container instance is recycled.
+  const REQUEST_RETRIES = 3;
+
+  // Error classification, mirroring native's string matchers in
+  // `@cloudflare/containers` (`isErrorOfType` against these exact phrases).
+  const errString = (e: unknown) =>
+    (e instanceof Error ? e.message : String(e)).toLowerCase();
+  const isNoInstanceError = (e: unknown) =>
+    errString(e).includes(
+      "there is no container instance that can be provided to this durable object",
+    );
+  const isRateLimitedError = (e: unknown) =>
+    errString(e).includes("you are requesting too many containers per second");
+
+  type ReadinessError =
+    | ContainerError
+    | NoContainerInstanceError
+    | ContainerRateLimitedError
+    | ContainerCrashedError;
+
+  // Map a raw defect to a typed readiness error (native classifies the same
+  // message phrases via `isErrorOfType`).
+  const classifyDefect = (
+    defect: unknown,
+    portNumber: number,
+  ): ContainerError | NoContainerInstanceError | ContainerRateLimitedError =>
+    isRateLimitedError(defect)
+      ? new ContainerRateLimitedError({
+          message: "Rate limited starting container",
+          cause: defect,
+        })
+      : isNoInstanceError(defect)
+        ? new NoContainerInstanceError({
+            message: "No container instance available",
+            cause: defect,
+          })
+        : new ContainerError({
+            message: `Container not ready on port ${portNumber}: ${defect}`,
+            cause: defect,
+          });
+
+  // Coalesce concurrent starts and share the confirmed-ready port cache across
+  // every caller for THIS Durable Object instance (see `startCoordination`).
+  // Native uses a `startInFlight` promise so two racing callers never both
+  // invoke `container.start()` ("already running" — cloudflare/containers#173);
+  // the 1-permit mutex serialises the start path so the second entrant sees
+  // `running === true` and skips. `readyPorts` lets steady-state requests skip
+  // the readiness probe entirely (like native's `healthy` state).
+  //
+  // Key on `DurableObjectState` (stable + unique per DO instance). Requiring it
+  // is correct: a container only ever runs inside a Durable Object, so this is
+  // an honest dependency rather than a silent fallback.
+  const doState = yield* DurableObjectState;
+  const coordinationKey: object =
+    (doState.container as object | undefined) ?? doState;
+  const { startMutex, readyPorts } = getStartCoordination(coordinationKey);
+
+  const launchMonitor = Effect.forkDetach(
+    container.monitor().pipe(
+      Effect.flatMap(() => Effect.logInfo("Container monitor exited")),
+      Effect.catchTag("ContainerError", (error) =>
+        Effect.logError(`Container monitor error: ${error.message}`),
+      ),
+      // When the container exits (stopped, crashed, or slept), its ports are no
+      // longer listening — drop the confirmed-ready marks so the next request
+      // re-probes the freshly (re)started instance instead of fetching a dead
+      // port. This is the analog of native's monitor clearing the `healthy`
+      // state on exit.
+      Effect.ensuring(Effect.sync(() => readyPorts.clear())),
+    ),
+  );
+
+  // The actual (re)start, serialised through the mutex so racing callers never
+  // both invoke `container.start()` ("already running" — see
+  // cloudflare/containers#173). Re-checks `running` under the lock.
+  const startOnce = Semaphore.withPermits(
+    startMutex,
+    1,
+  )(
+    Effect.gen(function* () {
+      if (yield* container.running) return;
+      yield* Effect.logDebug("Container not running, starting...");
+      // A (re)start means nothing is listening yet — clear any stale ready
+      // marks from a previous run so the next request re-probes this instance.
+      yield* Effect.sync(() => readyPorts.clear());
+      yield* container.start(options).pipe(
+        Effect.catchDefect((defect) => Effect.fail(classifyDefect(defect, -1))),
+        // A rate limit is transient — back off well clear of the per-second
+        // window and try again a few times before surfacing it.
+        Effect.retry({
+          while: (
+            e:
+              | ContainerError
+              | NoContainerInstanceError
+              | ContainerRateLimitedError,
+          ) => e._tag === "ContainerRateLimitedError",
+          schedule: Schedule.spaced(RATE_LIMIT_BACKOFF),
+          times: RATE_LIMIT_RETRIES,
+        }),
+      );
+      yield* launchMonitor;
+    }),
+  );
+
+  // Ensure the container is running. Fast path: when it's already running (the
+  // steady state) this is a single cheap `running` read and avoids contending
+  // on the start mutex. Only an actual (re)start acquires the lock — which is
+  // also what makes auto-restart work: a stopped/crashed container has
+  // `running === false`, so the next call transparently restarts it.
   const ensureRunning = Effect.gen(function* () {
     if (yield* container.running) return;
-    yield* Effect.logInfo("Container not running, starting...");
-    yield* container.start(options);
-    yield* Effect.logInfo("Container started, launching monitor");
-    yield* Effect.forkDetach(
-      container.monitor().pipe(
-        Effect.flatMap(() => Effect.logInfo("Container monitor exited")),
-        Effect.catchTag("ContainerError", (error) =>
-          Effect.logError(`Container monitor error: ${error.message}`),
-        ),
-      ),
-    );
+    yield* startOnce;
   });
 
-  // Poll the container roughly every 2–3s while it cold-starts, but bound the
-  // total wait (~3 min) so an unreachable container surfaces a `ContainerError`
-  // instead of hanging the Durable Object request forever. Without this cap a
-  // container that never accepts connections on the requested port (e.g. it
-  // crash-loops, or the process never binds the port) would retry indefinitely
-  // and the worker request would never return.
-  const startupBackoff = Schedule.exponential(100, 1.5).pipe(
-    Schedule.modifyDelay((_, delay) =>
-      Effect.succeed(
-        Duration.min(
-          Duration.max(delay, Duration.seconds(1)),
-          Duration.seconds(3),
+  // A single readiness probe: any response at all (even a non-2xx) proves the
+  // port is accepting connections. Each probe is hard-capped so a hung connect
+  // to a not-yet-bound port cannot stall the request. If the instance has gone
+  // away (`running === false`) after we started it, surface a crash rather than
+  // polling out the whole budget (native's `if (!this.container.running)`).
+  const probePort = (portNumber: number) =>
+    container.getTcpPort(portNumber).pipe(
+      Effect.andThen((port: Fetcher) =>
+        port.fetch(
+          HttpClientRequest.get("http://containerstarthealthcheck") as any,
         ),
       ),
-    ),
-    Schedule.both(Schedule.recurs(75)),
-  );
+      Effect.timeout(READINESS_PROBE_TIMEOUT),
+      Effect.catchDefect((defect: unknown) =>
+        container.running.pipe(
+          Effect.andThen((running) =>
+            Effect.fail<ReadinessError>(
+              !running &&
+                !isRateLimitedError(defect) &&
+                !isNoInstanceError(defect)
+                ? new ContainerCrashedError({
+                    message: `Container exited while waiting for port ${portNumber}`,
+                    cause: defect,
+                  })
+                : classifyDefect(defect, portNumber),
+            ),
+          ),
+        ),
+      ),
+      // A probe that hangs past the per-attempt cap, or fails the HTTP fetch
+      // before the port is up, is just "not ready yet" — retry it like any
+      // other transient readiness failure.
+      Effect.catchTag(["TimeoutError", "HttpClientError"], (cause: unknown) =>
+        container.running.pipe(
+          Effect.andThen((running) =>
+            Effect.fail<ReadinessError>(
+              !running
+                ? new ContainerCrashedError({
+                    message: `Container exited while waiting for port ${portNumber}`,
+                    cause,
+                  })
+                : new ContainerError({
+                    message: `Container probe not ready on port ${portNumber}`,
+                    cause,
+                  }),
+            ),
+          ),
+        ),
+      ),
+    );
+
+  // Retry ONLY failures that can clear by waiting on the SAME instance:
+  //   - `ContainerError`           — the port isn't listening yet (the app is
+  //                                  still booting; the container process is up)
+  //   - `NoContainerInstanceError` — an instance is still being allocated
+  // Fail fast on the rest:
+  //   - `ContainerCrashedError`    — the container PROCESS has exited
+  //                                  (`running === false`). `running` reflects
+  //                                  the process, not the app, so this is never
+  //                                  "still starting" — it's fatal for this
+  //                                  instance. Spinning the budget on a
+  //                                  crash-looping container just wastes ~20-60s
+  //                                  per request; surface it in ~one poll.
+  //   - `ContainerRateLimitedError`— back off in `ensureRunning`, don't spin.
+  // This matches `@cloudflare/containers`, whose `waitForPort` /
+  // `doStartContainer` throw immediately on `!running`.
+  const isTransientReadiness = (e: ReadinessError) =>
+    e._tag === "ContainerError" || e._tag === "NoContainerInstanceError";
+
+  // Phase 2 (native `waitForPort`): poll the port until it accepts connections.
+  // Crash detection is poll-based (`probePort` surfaces `ContainerCrashedError`
+  // on an observed `!running`, which `isTransientReadiness` does NOT retry).
+  //
+  // NB: we deliberately do NOT race `container.monitor()` for faster crash
+  // detection. The monitor wrapper settles immediately for a not-yet-allocated
+  // instance (and loses the exit code that native uses to tell "queued" from
+  // "exited"), so racing it mis-reports healthy, still-provisioning containers
+  // as crashed under concurrent startup — it dropped a 100-instance cold start
+  // to <10% success. Polling is correct under load; the price is that crash
+  // detection is bounded by the probe cadence rather than instant.
+  const waitForPort = (portNumber: number) =>
+    readyPorts.has(portNumber)
+      ? Effect.void
+      : probePort(portNumber).pipe(
+          Effect.tapError((err) =>
+            Effect.logDebug(`Container not ready (will retry): ${err}`),
+          ),
+          Effect.retry({
+            while: isTransientReadiness,
+            schedule: Schedule.spaced(READINESS_POLL_INTERVAL),
+            times: PORT_READY_RETRIES,
+          }),
+          Effect.andThen(() =>
+            Effect.sync(() => {
+              readyPorts.add(portNumber);
+            }),
+          ),
+        );
+
+  // Phase 1 (native `doStartContainer`) + phase 2: ensure the instance is
+  // started (bounded, rate-limit aware), then wait for the port. `ensureRunning`
+  // is ALWAYS run (cheap when already running) rather than short-circuiting on
+  // `readyPorts` — otherwise a container that has since stopped/crashed would
+  // never be restarted. The port probe (`waitForPort`) is what `readyPorts`
+  // skips in steady state.
+  const ensureReady = (portNumber: number) =>
+    ensureRunning.pipe(
+      Effect.retry({
+        while: (
+          e:
+            | ContainerError
+            | NoContainerInstanceError
+            | ContainerRateLimitedError,
+        ) => e._tag === "NoContainerInstanceError",
+        schedule: Schedule.spaced(READINESS_POLL_INTERVAL),
+        times: GET_CONTAINER_RETRIES,
+      }),
+      Effect.andThen(() => waitForPort(portNumber)),
+    );
 
   const getTcpPort = (portNumber: number) =>
     Effect.succeed({
@@ -85,20 +358,31 @@ export const startContainer = Effect.fn(function* <
           | HttpClientRequest.HttpClientRequest
           | HttpServerRequest.HttpServerRequest,
       ) =>
-        ensureRunning.pipe(
+        // Block until the port is ready (bounded), THEN forward the real
+        // request exactly once. Readiness is a cheap healthcheck, so the user
+        // request is never replayed against a cold container.
+        ensureReady(portNumber).pipe(
           Effect.andThen(() => container.getTcpPort(portNumber)),
           Effect.andThen((port: Fetcher) => port.fetch(request as any)),
           Effect.catchDefect((defect: unknown) =>
             Effect.fail(
               new ContainerError({
-                message: `Container not ready on port ${portNumber}: ${defect}`,
+                message: `Container fetch failed on port ${portNumber}: ${defect}`,
+                cause: defect,
               }),
             ),
           ),
-          Effect.tapError((err) =>
-            Effect.logDebug(`Container fetch error (will retry): ${err}`),
-          ),
-          Effect.retry({ schedule: startupBackoff }),
+          // Only retry a generic transient blip: a not-yet-ready port
+          // (`ContainerError`) or a transport hiccup on the real request such
+          // as "Network connection lost" (`HttpClientError`). A crash, rate
+          // limit, or exhausted no-instance budget is surfaced immediately so a
+          // crash-looping container fails fast instead of re-starting 3× more.
+          Effect.retry({
+            while: (e) =>
+              e._tag === "ContainerError" || e._tag === "HttpClientError",
+            schedule: Schedule.spaced(READINESS_POLL_INTERVAL),
+            times: REQUEST_RETRIES,
+          }),
         )) as {
         (
           request: HttpClientRequest.HttpClientRequest,

package/src/Cloudflare/DNS/ReadDns.ts

@@ -36,7 +36,7 @@ import type { Zone } from "../Zone/Zone.ts";
  *
  * export class ReadDnserWorker extends Cloudflare.Worker<ReadDnserWorker>()(
  *   "ReadDnserWorker",
- *   { main: import.meta.filename },
+ *   { main: import.meta.url },
  *   Effect.gen(function* () {
  *     // Init phase — bind the read client scoped to the zone.
  *     const dns = yield* Cloudflare.DNS.ReadDns(Zone);

package/src/Cloudflare/DNS/ReadWriteDns.ts

@@ -32,7 +32,7 @@ import { type WriteDnsClient } from "./WriteDns.ts";
  *
  * export class Worker extends Cloudflare.Worker<Worker>()(
  *   "Worker",
- *   { main: import.meta.filename },
+ *   { main: import.meta.url },
  *   Effect.gen(function* () {
  *     // Init phase — bind the full CRUD client scoped to the zone.
  *     const dns = yield* Cloudflare.DNS.ReadWriteDns(Zone);

package/src/Cloudflare/DNS/WriteDns.ts

@@ -46,7 +46,7 @@ import type { Zone } from "../Zone/Zone.ts";
  *
  * export class WriteDnsrWorker extends Cloudflare.Worker<WriteDnsrWorker>()(
  *   "WriteDnsrWorker",
- *   { main: import.meta.filename },
+ *   { main: import.meta.url },
  *   Effect.gen(function* () {
  *     // Init phase — bind the write client scoped to the zone.
  *     const dns = yield* Cloudflare.DNS.WriteDns(Zone);

package/src/Cloudflare/Flagship/App.ts

@@ -97,7 +97,7 @@ export type App = Resource<TypeId, AppProps, AppAttributes, never, Providers>;
  *
  * Cloudflare.Worker(
  *   "FlagsWorker",
- *   { main: import.meta.filename },
+ *   { main: import.meta.url },
  *   Effect.gen(function* () {
  *     const flags = yield* Cloudflare.Flagship.ReadFlags(App);
  *     return {

package/src/Cloudflare/Images/Images.ts

@@ -33,7 +33,7 @@ export class ImagesError extends Data.TaggedError("ImagesError")<{
  * ```typescript
  * import { HttpServerRequest } from "effect/unstable/http/HttpServerRequest";
  *
- * Cloudflare.Worker("ImageWorker", { main: import.meta.filename },
+ * Cloudflare.Worker("ImageWorker", { main: import.meta.url },
  *   Effect.gen(function* () {
  *     const images = yield* Cloudflare.Images.Images("PIPELINE");
  *     return {

package/src/Cloudflare/Local.ts

@@ -1,4 +1,5 @@
 import * as Layer from "effect/Layer";
+import { DockerLive } from "../Docker/Docker.ts";
 import * as RpcServer from "../Local/RpcServer.ts";
 import { CloudflareAuth } from "./Auth/AuthProvider.ts";
 import * as CloudflareEnvironment from "./CloudflareEnvironment.ts";
@@ -25,5 +26,6 @@ Layer.mergeAll(
 ).pipe(
   Layer.provide(localRuntimeServices()),
   Layer.provide(cloudflareServices),
+  Layer.provide(DockerLive),
   RpcServer.launch,
 );

package/src/Cloudflare/Providers.ts

@@ -8,6 +8,7 @@ import * as Schedule from "effect/Schedule";
 import { CredentialsStoreLive } from "../Auth/Credentials.ts";
 import { ProfileLive } from "../Auth/Profile.ts";
 import * as Command from "../Command/index.ts";
+import { DockerLive } from "../Docker/Docker.ts";
 import { KeyPair, KeyPairProvider } from "../KeyPair.ts";
 import * as Provider from "../Provider.ts";
 import { Random, RandomProvider } from "../Random.ts";
@@ -681,6 +682,7 @@ export const providers = () =>
         RandomProvider(),
       ),
     ),
+    Layer.provide(DockerLive),
     Layer.provideMerge(localRuntimeServices()),
     Layer.provideMerge(Credentials.fromAuthProvider()),
     Layer.provideMerge(CloudflareEnvironment.fromProfile()),

package/src/Cloudflare/Queues/Consumer.ts

@@ -98,7 +98,7 @@ export type Consumer = Resource<
  *
  * yield* Cloudflare.Queues.Consumer("MyConsumer", {
  *   queueId: queue.queueId,
- *   scriptName: "my-worker",
+ *   scriptName: worker.workerName,
  * });
  * ```
  *
@@ -106,7 +106,7 @@ export type Consumer = Resource<
  * ```typescript
  * yield* Cloudflare.Queues.Consumer("MyConsumer", {
  *   queueId: queue.queueId,
- *   scriptName: "my-worker",
+ *   scriptName: worker.workerName,
  *   settings: {
  *     batchSize: 50,
  *     maxRetries: 5,
@@ -127,6 +127,12 @@ const findWorkerConsumer = (acct: string, queueId: string) =>
     Stream.filter((c): c is ObservedConsumer => c !== undefined),
     Stream.runHead,
     Effect.map(Option.getOrUndefined),
+    // A queue created earlier in the same plan is eventually consistent:
+    // listConsumers can transiently 404 (`QueueNotFound`, code 11000) before
+    // the fresh queue is visible to the consumers API. Treat that as "no
+    // consumer yet" — the caller falls through to createConsumer, which
+    // retries QueueNotFound until the queue propagates.
+    Effect.catchTag("QueueNotFound", () => Effect.succeed(undefined)),
   );
 
 export const ConsumerProviderLive = () =>
@@ -349,22 +355,25 @@ export const ConsumerProviderLive = () =>
             settings: news.settings,
           })
           .pipe(
-            // The sibling Worker resource pre-creates a placeholder
-            // script with no `queue` handler; Cloudflare returns
-            // code 11001 until the real reconcile uploads the
-            // handler. Retry until the upload propagates (capped),
-            // then surface a real failure if it never does.
+            // Two eventual-consistency races on a fresh deploy, both
+            // retried on the same bounded schedule:
+            //  - QueueHandlerMissing (11001): the sibling Worker resource
+            //    pre-creates a placeholder script with no `queue` handler;
+            //    Cloudflare returns 11001 until the real reconcile uploads
+            //    the handler.
+            //  - QueueNotFound (11000): the queue was created earlier in
+            //    this same plan but isn't yet visible to the consumers API.
             Effect.tapError((e) =>
-              e._tag === "QueueHandlerMissing"
+              e._tag === "QueueHandlerMissing" || e._tag === "QueueNotFound"
                 ? Effect.logDebug(
-                    `Consumer create: worker ` +
-                      `"${news.scriptName}" has no queue handler ` +
-                      `yet (code 11001), retrying`,
+                    `Consumer create: not ready for worker ` +
+                      `"${news.scriptName}" (${e._tag}), retrying`,
                   )
                 : Effect.void,
             ),
             Effect.retry({
-              while: (e) => e._tag === "QueueHandlerMissing",
+              while: (e) =>
+                e._tag === "QueueHandlerMissing" || e._tag === "QueueNotFound",
               schedule: queueHandlerReadinessSchedule,
             }),
             Effect.catchTag("ConsumerAlreadyExists", (cause) =>

package/src/Cloudflare/Queues/Queue.ts

@@ -82,7 +82,7 @@ export type Queue = Resource<
  *
  * export default Cloudflare.Worker(
  *   "Worker",
- *   { main: import.meta.filename },
+ *   { main: import.meta.url },
  *   Effect.gen(function* () {
  *     const queue = yield* Cloudflare.Queues.WriteQueue(Queue);
  *

package/src/Cloudflare/R2/Bucket.ts

@@ -172,7 +172,7 @@ export type Bucket = Resource<
  * @section Binding to a Worker
  * @example Reading and writing objects
  * ```typescript
- * const bucket = yield* Cloudflare.R2.ReadWrite(MyBucket);
+ * const bucket = yield* Cloudflare.R2.ReadWriteBucket(MyBucket);
  *
  * // Write an object
  * yield* bucket.put("hello.txt", "Hello, World!");
@@ -186,7 +186,7 @@ export type Bucket = Resource<
  *
  * @example Streaming upload with content length
  * ```typescript
- * const bucket = yield* Cloudflare.R2.ReadWrite(MyBucket);
+ * const bucket = yield* Cloudflare.R2.ReadWriteBucket(MyBucket);
  *
  * yield* bucket.put("upload.bin", request.stream, {
  *   contentLength: Number(request.headers["content-length"] ?? 0),

package/src/Cloudflare/StateStore/Api.ts

@@ -8,6 +8,7 @@ import * as HttpRouter from "effect/unstable/http/HttpRouter";
 import * as HttpApiBuilder from "effect/unstable/httpapi/HttpApiBuilder";
 import * as HttpApiError from "effect/unstable/httpapi/HttpApiError";
 import crypto from "node:crypto";
+import { RuntimeContext } from "../../RuntimeContext.ts";
 import {
   BearerTokenValidator,
   StateApi,
@@ -101,7 +102,7 @@ export default Worker(
   "Api",
   {
     name: STATE_STORE_SCRIPT_NAME,
-    main: import.meta.filename,
+    main: import.meta.url,
     url: true,
     compatibility: {
       flags: ["nodejs_compat"],
@@ -115,13 +116,14 @@ export default Worker(
     const bearerTokenValidator = Layer.succeed(
       BearerTokenValidator,
       BearerTokenValidator.of({
-        // @ts-expect-error - TODO(sam): fix RuntimeContext color here
         validate: Effect.fn(function* (token) {
-          const expected = yield* remoteSecret.get();
+          const expected = yield* remoteSecret
+            .get()
+            .pipe(Effect.orDie, Effect.provide(RuntimeContext.phantom));
           return !!expected &&
             timingSafeEqual(token.trim(), Redacted.value(expected).trim())
             ? yield* Effect.void
-            : yield* Effect.fail(new HttpApiError.Unauthorized());
+            : yield* new HttpApiError.Unauthorized();
         }),
       }),
     );