alchemy 2.0.0-beta.61 → 2.0.0-beta.63

package/src/Cloudflare/Tunnel/index.ts

@@ -5,9 +5,12 @@ export * from "./Tunnel.ts";
 export * from "./TunnelBinding.ts";
 export * from "./ReadTunnel.ts";
 export * from "./ReadTunnelBinding.ts";
+export * from "./ReadTunnelLocal.ts";
 export * from "./ReadWriteTunnel.ts";
 export * from "./ReadWriteTunnelBinding.ts";
+export * from "./ReadWriteTunnelLocal.ts";
 export * from "./WriteTunnel.ts";
 export * from "./WriteTunnelBinding.ts";
+export * from "./WriteTunnelLocal.ts";
 export * from "./VirtualNetwork.ts";
 export * from "./WarpConnector.ts";

package/src/Cloudflare/UrlNormalization/UrlNormalization.ts

@@ -155,10 +155,13 @@ export const UrlNormalizationProvider = () =>
             // zone never falls out of the enumeration on a blip.
             Effect.retry({
               while: (e) => e._tag === "Forbidden",
-              schedule: Schedule.exponential("500 millis").pipe(
-                Schedule.either(Schedule.spaced("5 seconds")),
-                Schedule.both(Schedule.recurs(8)),
-              ),
+              schedule: Schedule.max([
+                Schedule.min([
+                  Schedule.exponential("500 millis"),
+                  Schedule.spaced("5 seconds"),
+                ]),
+                Schedule.recurs(8),
+              ]),
             }),
             Effect.map((observed) => toAttributes(zoneId, observed)),
             // Plan-gated or partial zones reject the route; skip them.

package/src/Cloudflare/Vectorize/SearchIndexHttpClient.ts

@@ -0,0 +1,183 @@
+import type * as runtime from "@cloudflare/workers-types";
+import * as vectorize from "@distilled.cloud/cloudflare/vectorize";
+import * as Effect from "effect/Effect";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type { Credentials } from "../Credentials.ts";
+import type { SearchIndexClient } from "./SearchIndex.ts";
+
+// Shared HTTP scaffolding for the Vectorize `SearchIndex` binding. NOT
+// re-exported from `index.ts` — only the contract and the impl layers are
+// public. A future token-scoped `SearchIndexHttp` layer reuses this builder
+// with an auth minted from an `AccountApiToken`; `SearchIndexLocal` builds the
+// auth from the ambient current-credentials context.
+
+/**
+ * Injectable auth shared by the Local (current-credentials) impl and a future
+ * Http (scoped-token) impl. `authorize` discharges the
+ * `Credentials | HttpClient` requirement of a distilled op; `accountId` is the
+ * Cloudflare account the ops run against.
+ */
+export interface SearchIndexAuth {
+  authorize: <A, E>(
+    eff: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>,
+  ) => Effect.Effect<A, E>;
+  accountId: string;
+}
+
+/**
+ * Build a {@link SearchIndexClient} over the Vectorize HTTP API.
+ *
+ * `indexName` is an Effect so the resolution stays deferred to each call —
+ * inside an Action it resolves through the apply-time RuntimeContext. The
+ * credentials are provided ONLY around the distilled op (via `auth.authorize`),
+ * never around the name accessor, matching the D1 / KV Local variants. `orDie`
+ * mirrors the native binding, whose client methods surface transport failures
+ * as defects.
+ *
+ * Two methods have no Cloudflare HTTP equivalent and `Effect.die`:
+ * - `raw` — there is no HTTP-backed `runtime.Vectorize` object to hand back.
+ * - `queryById` — the HTTP query endpoint only accepts a raw vector, not an id.
+ */
+export const makeHttpSearchIndexClient = (
+  auth: SearchIndexAuth,
+  indexName: Effect.Effect<string>,
+): SearchIndexClient => {
+  const { accountId } = auth;
+  const local = <A, E>(
+    fn: (
+      name: string,
+    ) => Effect.Effect<A, E, Credentials | HttpClient.HttpClient>,
+  ): Effect.Effect<A> =>
+    Effect.flatMap(indexName, (name) => auth.authorize(fn(name))).pipe(
+      Effect.orDie,
+    );
+
+  return {
+    raw: Effect.die(
+      new Error(
+        "SearchIndex over HTTP: `raw` is not available — use a native Worker binding (SearchIndexBinding) for direct access.",
+      ),
+    ),
+    describe: () =>
+      local((name) =>
+        vectorize
+          .infoIndex({ accountId, indexName: name })
+          .pipe(Effect.map(toIndexInfo)),
+      ),
+    query: (vector, options) =>
+      local((name) =>
+        vectorize
+          .queryIndex({
+            accountId,
+            indexName: name,
+            vector: Array.from(vector),
+            topK: options?.topK,
+            returnValues: options?.returnValues,
+            returnMetadata: toReturnMetadata(options?.returnMetadata),
+            filter: options?.filter,
+          })
+          .pipe(Effect.map(toMatches)),
+      ),
+    queryById: () =>
+      Effect.die(
+        new Error(
+          "SearchIndex over HTTP: `queryById` is not supported — the HTTP query endpoint only accepts a raw query vector. Fetch the vector with `getByIds` and pass its values to `query`.",
+        ),
+      ),
+    insert: (vectors) =>
+      local((name) =>
+        vectorize
+          .insertIndex({
+            accountId,
+            indexName: name,
+            body: toNdjsonBlob(vectors),
+          })
+          .pipe(Effect.map(toMutation)),
+      ),
+    upsert: (vectors) =>
+      local((name) =>
+        vectorize
+          .upsertIndex({
+            accountId,
+            indexName: name,
+            body: toNdjsonBlob(vectors),
+          })
+          .pipe(Effect.map(toMutation)),
+      ),
+    deleteByIds: (ids) =>
+      local((name) =>
+        vectorize
+          .deleteByIdsIndex({ accountId, indexName: name, ids })
+          .pipe(Effect.map(toMutation)),
+      ),
+    getByIds: (ids) =>
+      local((name) =>
+        vectorize
+          .getByIdsIndex({ accountId, indexName: name, ids })
+          .pipe(
+            Effect.map((result) => (result ?? []) as runtime.VectorizeVector[]),
+          ),
+      ),
+  } satisfies SearchIndexClient;
+};
+
+// ── shape adapters (runtime types <-> distilled HTTP types) ─────────────────
+
+/**
+ * Serialize vectors to an ndjson Blob — the raw `application/x-ndjson` request
+ * body of the Vectorize v2 insert/upsert endpoints.
+ */
+const toNdjsonBlob = (vectors: runtime.VectorizeVector[]): Blob =>
+  new Blob([toNdjson(vectors)]);
+
+/** Serialize vectors to ndjson — one JSON vector per line. */
+const toNdjson = (vectors: runtime.VectorizeVector[]): string =>
+  vectors
+    .map((v) =>
+      JSON.stringify({
+        id: v.id,
+        // A `VectorFloatArray` (Float32Array) would `JSON.stringify` to an
+        // object, not an array — normalize to a plain number array.
+        values: Array.from(v.values),
+        ...(v.namespace !== undefined ? { namespace: v.namespace } : {}),
+        ...(v.metadata !== undefined ? { metadata: v.metadata } : {}),
+      }),
+    )
+    .join("\n");
+
+const toReturnMetadata = (
+  value: runtime.VectorizeQueryOptions["returnMetadata"],
+): "none" | "indexed" | "all" | undefined =>
+  value === undefined
+    ? undefined
+    : typeof value === "boolean"
+      ? value
+        ? "all"
+        : "none"
+      : value;
+
+const toMutation = (r: {
+  mutationId?: string | null;
+}): runtime.VectorizeAsyncMutation => ({ mutationId: r.mutationId ?? "" });
+
+const toIndexInfo = (
+  r: vectorize.InfoIndexResponse,
+): runtime.VectorizeIndexInfo =>
+  ({
+    vectorCount: r.vectorCount ?? 0,
+    dimensions: r.dimensions ?? 0,
+    processedUpToDatetime: r.processedUpToDatetime ?? undefined,
+    processedUpToMutation: r.processedUpToMutation ?? undefined,
+  }) as unknown as runtime.VectorizeIndexInfo;
+
+const toMatches = (r: vectorize.QueryIndexResponse): runtime.VectorizeMatches =>
+  ({
+    count: r.count ?? r.matches?.length ?? 0,
+    matches: (r.matches ?? []).map((m) => ({
+      id: m.id ?? "",
+      score: m.score ?? 0,
+      ...(m.values != null ? { values: m.values } : {}),
+      ...(m.namespace != null ? { namespace: m.namespace } : {}),
+      ...(m.metadata != null ? { metadata: m.metadata } : {}),
+    })),
+  }) as unknown as runtime.VectorizeMatches;

package/src/Cloudflare/Vectorize/SearchIndexLocal.ts

@@ -0,0 +1,70 @@
+import type { Credentials } from "@distilled.cloud/cloudflare/Credentials";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import { SearchIndex } from "./SearchIndex.ts";
+import {
+  type SearchIndexAuth,
+  makeHttpSearchIndexClient,
+} from "./SearchIndexHttpClient.ts";
+import type { Index } from "./VectorizeIndex.ts";
+
+/**
+ * Local implementation of the {@link SearchIndex} binding — talks to a
+ * Vectorize index over the Cloudflare HTTP API using the **current
+ * credentials** instead of a native Worker binding (`SearchIndexBinding`).
+ *
+ * Provide it on an {@link Action} (or any deploy-time Effect) so you can
+ * insert, upsert, query, and fetch vectors with the same client you'd use
+ * inside a Worker — no Worker host, no `host.bind`, no minted token:
+ *
+ * @example Seeding an index from an Action
+ * ```typescript
+ * const Seed = Alchemy.Action(
+ *   "Seed",
+ *   Effect.gen(function* () {
+ *     const vec = yield* Cloudflare.Vectorize.SearchIndex(index);
+ *     return Effect.fn(function* () {
+ *       yield* vec.upsert([
+ *         { id: "1", values: [0.1, 0.2, 0.3, 0.4] },
+ *         { id: "2", values: [0.9, 0.8, 0.7, 0.6] },
+ *       ]);
+ *       const matches = yield* vec.query([0.1, 0.2, 0.3, 0.4], { topK: 1 });
+ *       return matches;
+ *     });
+ *   }).pipe(Effect.provide(Cloudflare.Vectorize.SearchIndexLocal)),
+ * );
+ * ```
+ *
+ * The index name is resolved at apply time through the ambient
+ * {@link RuntimeContext} (in an Action, that's the resolve context the engine
+ * provides around the body), so `SearchIndex(index)` works even though the
+ * index is created in the same deploy.
+ *
+ * `raw` and `queryById` have no Cloudflare HTTP equivalent and `Effect.die` —
+ * see {@link makeHttpSearchIndexClient}.
+ */
+export const SearchIndexLocal = Layer.effect(
+  SearchIndex,
+  Effect.gen(function* () {
+    // Account + credentials are ambient during stack-eval (the stack's
+    // providers layer). Capture the full context so the HTTP ops run with the
+    // current credentials — no `host.bind`, no minted token.
+    const { accountId } = yield* yield* CloudflareEnvironment;
+    const context = yield* Effect.context<
+      Credentials | HttpClient.HttpClient
+    >();
+    const auth: SearchIndexAuth = {
+      authorize: (eff) => eff.pipe(Effect.provideContext(context)),
+      accountId,
+    };
+
+    return Effect.fn(function* (index: Index) {
+      // Deferred accessor — resolves the index name against the tracker at
+      // apply time (in an Action, that's the engine's resolve context).
+      const indexName = yield* index.indexName;
+      return makeHttpSearchIndexClient(auth, indexName);
+    });
+  }),
+);

package/src/Cloudflare/Vectorize/index.ts

@@ -1,4 +1,5 @@
 export * from "./SearchIndex.ts";
 export * from "./SearchIndexBinding.ts";
+export * from "./SearchIndexLocal.ts";
 export * from "./VectorizeIndex.ts";
 export * from "./VectorizeMetadataIndex.ts";

package/src/Cloudflare/WaitingRoom/Settings.ts

@@ -116,10 +116,13 @@ export const SettingsProvider = () =>
             // test timeout when a zone is persistently 403.
             Effect.retry({
               while: (e) => e._tag === "Forbidden",
-              schedule: Schedule.exponential("500 millis").pipe(
-                Schedule.either(Schedule.spaced("5 seconds")),
-                Schedule.both(Schedule.recurs(8)),
-              ),
+              schedule: Schedule.max([
+                Schedule.min([
+                  Schedule.exponential("500 millis"),
+                  Schedule.spaced("5 seconds"),
+                ]),
+                Schedule.recurs(8),
+              ]),
             }),
             Effect.map((observed) =>
               toAttributes(

package/src/Cloudflare/Website/Vite.ts

@@ -90,6 +90,25 @@ export interface ViteProps<Bindings extends WorkerBindingProps = {}>
  * });
  * ```
  *
+ * @section Custom Worker Entry
+ * By default the deployed Worker entry is the server bundle the
+ * framework produces. When the Worker must export more than the
+ * framework's fetch handler — Durable Object classes, additional
+ * handlers — point `main` at your own module that wraps the framework
+ * handler and re-exports the extras. `main` takes precedence over any
+ * entry configured in the Vite config.
+ *
+ * @example Custom entry hosting Durable Objects
+ * ```typescript
+ * const app = yield* Cloudflare.Website.Vite("App", {
+ *   main: "worker/index.ts",
+ *   viteEnvironments: {
+ *     entry: "rsc",
+ *     children: ["ssr"],
+ *   },
+ * });
+ * ```
+ *
  * @section Single-Page Applications
  * For SPAs (React, Vue, etc.), configure asset handling so all
  * routes fall back to `index.html`.
@@ -178,6 +197,7 @@ export const Vite: {
             ...props,
             main: undefined!,
             vite: {
+              main: props?.main,
               rootDir: props?.rootDir,
               memo: props?.memo,
               viteEnvironments: props?.viteEnvironments,

package/src/Cloudflare/Workers/BrowserHttpClient.ts

@@ -0,0 +1,201 @@
+import * as browser from "@distilled.cloud/cloudflare/browser-rendering";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
+import type { Credentials } from "../Credentials.ts";
+import {
+  type BrowserClient,
+  type BrowserContentResult,
+  BrowserError,
+  type BrowserJsonResult,
+  type BrowserLinksResult,
+  type BrowserMarkdownResult,
+  type BrowserScrapeResult,
+  type BrowserSnapshotResult,
+} from "./Browser.ts";
+
+// Shared HTTP scaffolding for the Browser Rendering binding. NOT re-exported
+// from `index.ts` — only the contract and the impl layers are public. A future
+// token-scoped `BrowserHttp` layer reuses this builder with an auth minted from
+// an `AccountApiToken`; `BrowserLocal` builds the auth from the ambient
+// current-credentials context.
+
+/**
+ * Injectable auth shared by the Local (current-credentials) impl and a future
+ * Http (scoped-token) impl. `authorize` discharges the
+ * `Credentials | HttpClient` requirement of a distilled op; `accountId` is the
+ * Cloudflare account the ops run against.
+ */
+export interface BrowserAuth {
+  authorize: <A, E>(
+    eff: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>,
+  ) => Effect.Effect<A, E>;
+  accountId: string;
+}
+
+/** A byte stream produced by a binary {@link BrowserClient} action. */
+type BrowserByteStream = Stream.Stream<
+  Uint8Array,
+  BrowserError,
+  RuntimeContext
+>;
+
+/**
+ * Build a {@link BrowserClient} over the Browser Rendering REST data-plane
+ * (`/accounts/{id}/browser-rendering/*`).
+ *
+ * The following client members `Effect.die` (or fail the stream) because they
+ * have no Cloudflare REST equivalent — use a native `BrowserBinding` inside a
+ * deployed Worker for them:
+ * - `raw` / `fetch` — the raw `BrowserRun` transport used by
+ *   `@cloudflare/puppeteer` is a Worker-runtime object, not an HTTP call.
+ * - `screenshot` / `pdf` — the binary endpoints stream image/PDF bytes, which
+ *   the distilled REST codec models as JSON status, not a byte stream.
+ *
+ * Because the REST data-plane only returns the action `result` (not the
+ * runtime binding's `meta` envelope), `content`/`snapshot` populate `meta`
+ * with a best-effort placeholder.
+ */
+export const makeHttpBrowserClient = (auth: BrowserAuth): BrowserClient => {
+  // Run a distilled Browser Rendering op with the injected auth and surface
+  // transport/API failures as {@link BrowserError} (matching the native
+  // binding's declared error channel).
+  const run = <A, E>(
+    eff: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>,
+  ): Effect.Effect<A, BrowserError, RuntimeContext> =>
+    auth.authorize(eff).pipe(
+      Effect.mapError(
+        (cause) =>
+          new BrowserError({
+            message: "Browser Rendering request failed",
+            cause,
+          }),
+      ),
+    );
+
+  // The cf option types (`url`/`html` + puppeteer options) are structurally the
+  // REST request body; add the account id and let distilled's encoder drop any
+  // fields it doesn't model.
+  const req = (options: unknown) =>
+    ({ accountId: auth.accountId, ...(options as object) }) as never;
+
+  const content = (options: unknown) =>
+    run(browser.createContent(req(options))).pipe(
+      Effect.map(
+        (result): BrowserContentResult => ({
+          success: true,
+          result,
+          meta: { status: 200, title: "" },
+        }),
+      ),
+    );
+
+  const markdown = (options: unknown) =>
+    run(browser.createMarkdown(req(options))).pipe(
+      Effect.map(
+        (result): BrowserMarkdownResult => ({ success: true, result }),
+      ),
+    );
+
+  const links = (options: unknown) =>
+    run(browser.createLink(req(options))).pipe(
+      Effect.map(
+        (result): BrowserLinksResult => ({
+          success: true,
+          result: [...result],
+        }),
+      ),
+    );
+
+  const json = (options: unknown) =>
+    run(browser.createJson(req(options))).pipe(
+      Effect.map((result): BrowserJsonResult => ({ success: true, result })),
+    );
+
+  const scrape = (options: unknown) =>
+    run(browser.createScrape(req(options))).pipe(
+      Effect.map(
+        (result): BrowserScrapeResult => ({
+          success: true,
+          result: result.map((item) => ({
+            selector: item.selector,
+            // distilled models per-selector `results` as a single object; the
+            // native shape is an array of matched elements.
+            results: (Array.isArray(item.results)
+              ? item.results
+              : [
+                  item.results,
+                ]) as BrowserScrapeResult["result"][number]["results"],
+          })),
+        }),
+      ),
+    );
+
+  const snapshot = (options: unknown) =>
+    run(browser.createSnapshot(req(options))).pipe(
+      Effect.map(
+        (result): BrowserSnapshotResult => ({
+          success: true,
+          result: {
+            content: result.content ?? "",
+            screenshot: result.screenshot ?? "",
+          },
+          meta: { status: 200, title: "" },
+        }),
+      ),
+    );
+
+  // Binary actions have no REST byte-stream equivalent through the distilled
+  // codec — fail the stream with a defect explaining the native-binding path.
+  const binaryUnsupported = (action: string): BrowserByteStream =>
+    Stream.fromEffect(
+      Effect.die(
+        new Error(
+          `Browser over HTTP: '${action}' returns binary data and is only available inside a Worker via the native BrowserBinding; the HTTP client supports the JSON quick actions (content/markdown/scrape/links/snapshot/json).`,
+        ),
+      ),
+    ) as BrowserByteStream;
+
+  const quickAction = ((action: string, options: unknown) => {
+    switch (action) {
+      case "content":
+        return content(options);
+      case "markdown":
+        return markdown(options);
+      case "links":
+        return links(options);
+      case "json":
+        return json(options);
+      case "scrape":
+        return scrape(options);
+      case "snapshot":
+        return snapshot(options);
+      default:
+        return binaryUnsupported(action);
+    }
+  }) as BrowserClient["quickAction"];
+
+  return {
+    raw: Effect.die(
+      new Error(
+        "Browser over HTTP: `raw` (the native BrowserRun binding) is only available inside a deployed Worker — use BrowserBinding.",
+      ),
+    ),
+    fetch: () =>
+      Effect.die(
+        new Error(
+          "Browser over HTTP: `fetch` proxies the raw Browser Run transport used by @cloudflare/puppeteer and is only available inside a Worker via BrowserBinding.",
+        ),
+      ),
+    quickAction,
+    screenshot: () => binaryUnsupported("screenshot"),
+    pdf: () => binaryUnsupported("pdf"),
+    content,
+    scrape,
+    links,
+    snapshot,
+    json,
+    markdown,
+  } satisfies BrowserClient;
+};

package/src/Cloudflare/Workers/BrowserLocal.ts

@@ -0,0 +1,65 @@
+import * as Effect from "effect/Effect";
+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 { Browser } from "./Browser.ts";
+import type { BrowserBinding } from "./BrowserBinding.ts";
+import {
+  type BrowserAuth,
+  makeHttpBrowserClient,
+} from "./BrowserHttpClient.ts";
+
+/**
+ * Local implementation of the {@link Browser} binding — drives Cloudflare
+ * Browser Rendering over its REST data-plane (`/accounts/{id}/browser-rendering/*`)
+ * using the **current credentials** instead of a native Worker binding
+ * (`BrowserBinding`).
+ *
+ * Provide it on an {@link Action} (or any deploy-time Effect) to run the JSON
+ * quick actions — `content`, `markdown`, `scrape`, `links`, `snapshot`,
+ * `json` — with the same client you'd use inside a Worker; no Worker host, no
+ * `host.bind`, no minted token:
+ *
+ * @example Convert a page to Markdown from an Action
+ * ```typescript
+ * const Scrape = Alchemy.Action(
+ *   "Scrape",
+ *   Effect.gen(function* () {
+ *     const browser = yield* Cloudflare.Browser("BROWSER");
+ *     return Effect.fn(function* () {
+ *       const { result } = yield* browser.markdown({
+ *         url: "https://example.com",
+ *       });
+ *       return result;
+ *     });
+ *   }).pipe(Effect.provide(Cloudflare.Workers.BrowserLocal)),
+ * );
+ * ```
+ *
+ * `raw`, `fetch`, and the binary actions (`screenshot`/`pdf`) have no
+ * Cloudflare REST equivalent and die — see {@link makeHttpBrowserClient}.
+ */
+export const BrowserLocal = Layer.effect(
+  Browser,
+  Effect.gen(function* () {
+    // Account + credentials are ambient during stack-eval (the stack's
+    // providers layer). Capture the full context so the REST ops run with the
+    // current credentials — no `host.bind`, no minted token.
+    const { accountId } = yield* yield* CloudflareEnvironment;
+    const context = yield* Effect.context<
+      Credentials | HttpClient.HttpClient
+    >();
+    const auth: BrowserAuth = {
+      authorize: (eff) => eff.pipe(Effect.provideContext(context)),
+      accountId,
+    };
+
+    return Effect.fn(function* (_binding: BrowserBinding) {
+      // Browser Rendering is account-scoped; the binding carries no cloud
+      // resource id, so nothing to resolve — the client only needs the account
+      // + injected auth.
+      return makeHttpBrowserClient(auth);
+    });
+  }),
+);

package/src/Cloudflare/Workers/Compatibility.ts

@@ -3,10 +3,53 @@ import type { WorkerProps } from "./Worker.ts";
 // TODO: figure out why the later one from workerd breaks
 const DEFAULT_COMPATIBILITY_DATE = "2026-03-17";
 
-export const getCompatibility = (props: WorkerProps) => ({
-  date: props.compatibility?.date ?? DEFAULT_COMPATIBILITY_DATE,
-  flags: [
-    ...(props.compatibility?.flags ?? []),
-    ...(props.isExternal ? [] : ["nodejs_compat"]),
-  ].filter((value, index, self) => self.indexOf(value) === index),
-});
+/**
+ * The Effect worker bridge builds its layer stack once per isolate and shares
+ * the in-flight build promise across concurrent events. Awaiting a promise
+ * created under another event's request context is only sound with workerd's
+ * corrected cross-request promise semantics (default-on since compatibility
+ * date 2024-10-14): continuations are scheduled back into the promise's
+ * origin context instead of running in whichever request happens to resolve
+ * them. A user pinning an older compatibility date must not silently revert
+ * the bridge to the broken semantics, so the flag is forced for
+ * alchemy-bundled workers — and explicitly disabling it is a deploy-time
+ * error.
+ */
+const CROSS_REQUEST_PROMISE_RESOLUTION =
+  "handle_cross_request_promise_resolution";
+
+// The date the flag became default-on. Cloudflare rejects a script that
+// specifies a flag its compatibility date already defaults on ("does not
+// need to be specified anymore"), so it is only appended for older dates.
+const CROSS_REQUEST_PROMISE_RESOLUTION_DEFAULT_ON = "2024-10-14";
+
+export const getCompatibility = (props: WorkerProps) => {
+  const userFlags = props.compatibility?.flags ?? [];
+  if (
+    !props.isExternal &&
+    userFlags.includes(`no_${CROSS_REQUEST_PROMISE_RESOLUTION}`)
+  ) {
+    throw new Error(
+      `The "no_${CROSS_REQUEST_PROMISE_RESOLUTION}" compatibility flag is not supported: ` +
+        "the alchemy Worker runtime shares its layer build across concurrent " +
+        "requests, which requires workerd's corrected cross-request promise " +
+        "semantics. Remove the flag from `compatibility.flags`.",
+    );
+  }
+  const date = props.compatibility?.date ?? DEFAULT_COMPATIBILITY_DATE;
+  return {
+    date,
+    flags: [
+      ...userFlags,
+      ...(props.isExternal
+        ? []
+        : [
+            "nodejs_compat",
+            // ISO dates compare lexically.
+            ...(date < CROSS_REQUEST_PROMISE_RESOLUTION_DEFAULT_ON
+              ? [CROSS_REQUEST_PROMISE_RESOLUTION]
+              : []),
+          ]),
+    ].filter((value, index, self) => self.indexOf(value) === index),
+  };
+};