alchemy 2.0.0-beta.28 → 2.0.0-beta.29

package/src/Cloudflare/AiGateway/index.ts

@@ -0,0 +1,2 @@
+export * from "./AiGateway.ts";
+export * from "./AiGatewayBinding.ts";

package/src/Cloudflare/EdgeSession.ts

@@ -3,6 +3,7 @@ import * as workers from "@distilled.cloud/cloudflare/workers";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as HttpClient from "effect/unstable/http/HttpClient";
+import { Access } from "./Access.ts";
 import { CloudflareEnvironment } from "./CloudflareEnvironment.ts";
 
 /**
@@ -127,18 +128,27 @@ export const createEdgeSession = (
 ): Effect.Effect<
   EdgeSessionHandle,
   EdgeSessionError,
-  CloudflareEnvironment | HttpClient.HttpClient | Credentials
+  CloudflareEnvironment | HttpClient.HttpClient | Credentials | Access
 > =>
   Effect.gen(function* () {
-    const [{ previewToken }, host] = yield* Effect.all(
+    const [{ previewToken }, { url, headers }] = yield* Effect.all(
       [
         createUploadToken.pipe(Effect.flatMap((t) => uploadScript(options, t))),
-        workerHost(options.scriptName),
+        workerHost(options.scriptName).pipe(
+          Effect.flatMap(
+            Effect.fn(function* (host) {
+              const headers = yield* Access.use((access) =>
+                access.getAccessHeaders(host),
+              );
+              return { url: `https://${host}`, headers };
+            }),
+          ),
+        ),
       ],
       { concurrency: "unbounded" },
     );
     return {
-      url: `https://${host}`,
-      headers: { "cf-workers-preview-token": previewToken },
+      url,
+      headers: { ...headers, "cf-workers-preview-token": previewToken },
     } satisfies EdgeSessionHandle;
   }).pipe((e) => wrap(e, "Failed to create edge preview session"));

package/src/Cloudflare/Providers.ts

@@ -3,6 +3,8 @@ import { Command } from "../Build/Command.ts";
 import * as Build from "../Build/index.ts";
 import * as Provider from "../Provider.ts";
 import { Random, RandomProvider } from "../Random.ts";
+import * as Access from "./Access.ts";
+import * as AiGateway from "./AiGateway/index.ts";
 import * as ApiToken from "./ApiToken/index.ts";
 import * as Artifacts from "./Artifacts/index.ts";
 import { CloudflareAuth } from "./Auth/AuthProvider.ts";
@@ -34,6 +36,8 @@ export const providers = () =>
     Provider.collection([
       ApiToken.AccountApiToken,
       ApiToken.UserApiToken,
+      AiGateway.AiGateway,
+      AiGateway.AiGatewayBindingPolicy,
       Artifacts.ArtifactsBindingPolicy,
       Command,
       Containers.Container,
@@ -60,6 +64,8 @@ export const providers = () =>
       Layer.mergeAll(
         ApiToken.AccountApiTokenProvider(),
         ApiToken.UserApiTokenProvider(),
+        AiGateway.AiGatewayProvider(),
+        AiGateway.AiGatewayBindingPolicyLive,
         Artifacts.ArtifactsBindingPolicyLive,
         Containers.ContainerProvider(),
         D1.D1ConnectionPolicyLive,
@@ -86,5 +92,6 @@ export const providers = () =>
     Layer.provideMerge(Credentials.fromAuthProvider()),
     Layer.provideMerge(CloudflareEnvironment.fromProfile()),
     Layer.provideMerge(CloudflareAuth),
+    Layer.provideMerge(Access.AccessLive),
     Layer.orDie,
   );

package/src/Cloudflare/StateStore/Api.ts

@@ -20,6 +20,17 @@ import { AuthToken } from "./Token.ts";
 
 export const STATE_STORE_SCRIPT_NAME = "alchemy-state-store" as const;
 
+/**
+ * Version of the deployed Cloudflare State Store worker contract.
+ *
+ * Bump this whenever the wire format or runtime behaviour of the
+ * worker changes in a way that an older deployed copy can no longer
+ * satisfy. Clients query `/version` on the deployed worker and
+ * compare against this constant; a mismatch (or 404) triggers a
+ * forced redeploy via the bootstrap flow.
+ */
+export const STATE_STORE_VERSION = 1 as const;
+
 /**
  * Path on disk to *this* file, used as the worker's bundling entry.
  *
@@ -63,6 +74,12 @@ export default Worker(
       ),
     );
 
+    const versionApi = HttpApiBuilder.group(StateApi, "version", (handlers) =>
+      handlers.handle("getVersion", () =>
+        Effect.succeed({ version: STATE_STORE_VERSION }),
+      ),
+    );
+
     const stateApi = HttpApiBuilder.group(StateApi, "state", (handlers) =>
       handlers
         .handle("listStacks", () =>
@@ -133,6 +150,7 @@ export default Worker(
     return {
       fetch: HttpApiBuilder.layer(StateApi).pipe(
         Layer.provide(stateApi),
+        Layer.provide(versionApi),
         Layer.provide(StateAuthLive),
         Layer.provide(bearerTokenValidator),
         // The state-store worker never serves files, so HttpPlatform's

package/src/Cloudflare/StateStore/State.ts

@@ -5,6 +5,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Redacted from "effect/Redacted";
 import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
 
 import * as Config from "effect/Config";
 import { adopt } from "../../AdoptPolicy.ts";
@@ -14,6 +15,7 @@ import { ALCHEMY_PROFILE } from "../../Auth/Profile.ts";
 import * as Cloudflare from "../../Cloudflare/Providers.ts";
 import { deploy } from "../../Deploy.ts";
 import * as Alchemy from "../../Stack.ts";
+import { StateApi } from "../../State/HttpStateApi.ts";
 import {
   makeHttpStateStore,
   type HttpStateStoreProps,
@@ -26,9 +28,10 @@ import { makeLocalState } from "../../State/LocalState.ts";
 import { State, type StateService } from "../../State/State.ts";
 import { recordStateStoreOp } from "../../Telemetry/Metrics.ts";
 import * as Clank from "../../Util/Clank.ts";
+import * as Access from "../Access.ts";
 import { CloudflareAuth } from "../Auth/AuthProvider.ts";
 import { EdgeSessionError, createEdgeSession } from "../EdgeSession.ts";
-import Api, { STATE_STORE_SCRIPT_NAME } from "./Api.ts";
+import Api, { STATE_STORE_SCRIPT_NAME, STATE_STORE_VERSION } from "./Api.ts";
 import { AuthTokenSecretName, TokenValue } from "./Token.ts";
 
 /** Filename used for stored credentials under the profile directory. */
@@ -111,6 +114,13 @@ export const bootstrap = (options: BootstrapOptions = {}) =>
           credentials,
         );
       }
+      yield* redeployIfStale({
+        scriptName,
+        profileName,
+        localState,
+        isCI,
+        url: credentials.url,
+      });
       yield* Clank.success(`Cloudflare State Store '${scriptName}' is ready.`);
       return;
     }
@@ -179,9 +189,21 @@ export const state = (props?: {
         });
       }
 
-      // TODO(sam): support upgrading state store, right now we only deploy once
       if (credentials) {
-        // it's in the profile, let's go
+        // We have local credentials. Before trusting them, verify
+        // the deployed worker is on the version this CLI was built
+        // against. If it isn't, `redeployIfStale` runs the idempotent
+        // bootstrap flow and short-circuits with the freshly-deployed
+        // store.
+        const fresh = yield* redeployIfStale({
+          scriptName,
+          profileName,
+          localState,
+          isCI,
+          url: credentials.url,
+        });
+        if (fresh) return fresh;
+
         const httpState = yield* makeHttpStateStore(credentials);
 
         if (alchemyContext.updateStateStore) {
@@ -213,6 +235,16 @@ export const state = (props?: {
             credentials,
           );
         }
+
+        const fresh = yield* redeployIfStale({
+          scriptName,
+          profileName,
+          localState,
+          isCI,
+          url: credentials.url,
+        });
+        if (fresh) return fresh;
+
         const httpState = yield* makeHttpStateStore(credentials);
 
         if (alchemyContext.updateStateStore) {
@@ -251,6 +283,7 @@ export const state = (props?: {
     Layer.provideMerge(Credentials.fromAuthProvider()),
     Layer.provideMerge(CloudflareEnvironment.fromProfile()),
     Layer.provideMerge(CloudflareAuth),
+    Layer.provideMerge(Access.AccessLive),
     Layer.orDie,
   );
 
@@ -424,7 +457,19 @@ export const loginWithCloudflare = () =>
     }
 
     // 2. Fetch the auth-token value via an edge-preview worker.
-    const authToken = yield* readSecretViaEdge(store.id, AuthTokenSecretName);
+    //    We piggy-back on the already-deployed state-store script so the
+    //    `cf-workers-preview-token` header has a real workers.dev route to
+    //    swap onto. Uploading the probe under a brand-new script name fails
+    //    on accounts where that script has never been deployed (or where
+    //    workers.dev preview URLs are off by default — the post-2024
+    //    Cloudflare default for new accounts) because the host doesn't
+    //    resolve and Cloudflare's edge serves a 400 HTML error page
+    //    instead of routing to the preview.
+    const authToken = yield* readSecretViaEdge(
+      STATE_STORE_SCRIPT_NAME,
+      store.id,
+      AuthTokenSecretName,
+    );
 
     // 3. Derive the deployed worker URL.
     const { subdomain } = yield* workers.getSubdomain({ accountId });
@@ -468,8 +513,61 @@ export const loginWithCloudflare = () =>
     ),
   );
 
-/** Preview script name used by the edge-probe worker. */
-const PROBE_SCRIPT_NAME = "alchemy-state-store-probe";
+/**
+ * Run {@link finishBootstrap} iff the worker at `url` fails the
+ * version probe; otherwise resolve to `undefined`. Centralises the
+ * "is the deployed worker still compatible?" guard used by every
+ * code path that already has a presumably-valid worker URL.
+ */
+const redeployIfStale = ({
+  url,
+  scriptName,
+  profileName,
+  localState,
+  isCI,
+}: {
+  url: string;
+  scriptName: string;
+  profileName: string;
+  localState: StateService;
+  isCI: boolean;
+}) =>
+  Effect.gen(function* () {
+    if (yield* checkStateStoreVersion(url)) return undefined;
+    yield* Clank.info(
+      `Cloudflare State Store '${scriptName}' is out of date; redeploying...`,
+    );
+    return yield* finishBootstrap({
+      scriptName,
+      profileName,
+      localState,
+      isCI,
+    });
+  });
+
+/**
+ * Probe the deployed worker's `/version` endpoint and decide whether
+ * it satisfies the current {@link STATE_STORE_VERSION} contract.
+ *
+ * Reuses the same typed {@link StateApi} client the rest of the store
+ * speaks, just without the bearer-token transform — the `/version`
+ * route is intentionally unauthenticated so we can probe it before
+ * trusting any locally-cached credentials.
+ *
+ * Returns `true` only on a successful response carrying the matching
+ * version. Any failure (404 from a pre-`/version` deploy, transport
+ * error, schema mismatch, version mismatch) collapses to `false`,
+ * since the caller's response in every case is the same: fall
+ * through to the idempotent bootstrap flow.
+ */
+const checkStateStoreVersion = (url: string) =>
+  Effect.gen(function* () {
+    const client = yield* HttpApiClient.make(StateApi, { baseUrl: url });
+    const result = yield* client.version
+      .getVersion()
+      .pipe(Effect.catch(() => Effect.succeed(undefined)));
+    return result?.version === STATE_STORE_VERSION;
+  });
 
 /**
  * Tiny ES-module worker that reads `env.SECRET.get()` and echoes it
@@ -488,19 +586,32 @@ const SECRET_PROBE_SOURCE = `export default {
 };`;
 
 /**
- * Upload a tiny edge-preview worker that binds the given Secrets
- * Store secret, call it once, and return the decoded value. The
- * Cloudflare REST API deliberately hides secret values; only worker
- * bindings can resolve them, so this is the out-of-band path.
+ * Upload an ephemeral edge-preview build of the given (already
+ * deployed) script that binds the requested Secrets Store secret,
+ * call it once with the preview token, and return the decoded value.
+ * The Cloudflare REST API deliberately hides secret values; only
+ * worker bindings can resolve them, so this is the out-of-band path.
+ *
+ * `scriptName` MUST be a script that is already deployed on the
+ * account with workers.dev enabled — the `cf-workers-preview-token`
+ * header swaps our probe code in for an existing route, it does not
+ * create one. Using an undeployed name (or a deployed script that
+ * doesn't have workers.dev enabled) makes the workers.dev edge serve
+ * a generic Cloudflare 400 HTML error page instead of routing to the
+ * preview. The state-store script itself satisfies both conditions.
  */
-const readSecretViaEdge = (storeId: string, secretName: string) =>
+const readSecretViaEdge = (
+  scriptName: string,
+  storeId: string,
+  secretName: string,
+) =>
   Effect.gen(function* () {
     const http = yield* HttpClient.HttpClient;
     const file = new File([SECRET_PROBE_SOURCE], "worker.js", {
       type: "application/javascript+module",
     });
     const session = yield* createEdgeSession({
-      scriptName: PROBE_SCRIPT_NAME,
+      scriptName,
       files: [file],
       bindings: [
         { type: "secrets_store_secret", name: "SECRET", secretName, storeId },
@@ -513,6 +624,13 @@ const readSecretViaEdge = (storeId: string, secretName: string) =>
       const body = yield* response.text.pipe(
         Effect.catch(() => Effect.succeed("")),
       );
+      // TEMP(sam): dump the full body so we can capture the exact
+      // Cloudflare error page when the probe fails in the wild. Drop
+      // this once we've confirmed the routing fix covers all the
+      // observed failure modes.
+      yield* Effect.logWarning(
+        `Secret probe failed (${response.status}) at ${session.url}\n${body}`,
+      );
       return yield* Effect.fail(
         new EdgeSessionError({
           message: `Secret probe returned ${response.status}: ${body.slice(0, 200)}`,

package/src/Cloudflare/Workers/InferEnv.ts

@@ -23,8 +23,10 @@ type GetBindingType<T> = T extends Cloudflare.Assets
         ? KVNamespace
         : T extends Cloudflare.Queue
           ? Queue<unknown>
-          : T extends Cloudflare.Artifacts
-            ? Artifacts
-            : T extends Cloudflare.DurableObjectNamespaceLike
-              ? DurableObjectNamespace<Exclude<T["Shape"], undefined>>
-              : never;
+          : T extends Cloudflare.AiGateway
+            ? Ai
+            : T extends Cloudflare.Artifacts
+              ? Artifacts
+              : T extends Cloudflare.DurableObjectNamespaceLike
+                ? DurableObjectNamespace<Exclude<T["Shape"], undefined>>
+                : never;

package/src/Cloudflare/Workers/Worker.ts

@@ -51,6 +51,7 @@ import { Self } from "../../Self.ts";
 import * as Serverless from "../../Serverless/index.ts";
 import { Stack } from "../../Stack.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import type { AiGateway } from "../AiGateway/AiGateway.ts";
 import { D1Database } from "../D1/D1Database.ts";
 import { fromCloudflareFetcher } from "../Fetcher.ts";
 import type { KVNamespace } from "../KV/KVNamespace.ts";
@@ -190,6 +191,7 @@ export type WorkerBindingResource =
   | D1Database
   | KVNamespace
   | CloudflareQueue
+  | AiGateway
   | ArtifactsBinding
   | DurableObjectNamespaceLike<any>;
 
@@ -727,8 +729,13 @@ export const Worker: Platform<
                           name: bindingName,
                           queueName: binding.queueName,
                         }
-                      : // TODO(sam): handle others
-                        undefined;
+                      : binding.Type === "Cloudflare.AiGateway"
+                        ? {
+                            type: "ai",
+                            name: bindingName,
+                          }
+                        : // TODO(sam): handle others
+                          undefined;
 
         if (bindingMeta) {
           yield* resource.bind`${bindingName}`({
@@ -1499,7 +1506,7 @@ ${[
           getCompatibility(props);
 
         yield* Effect.promise(async () => {
-          const vite = await loadVite();
+          const vite = await loadVite(props.vite?.rootDir);
           const builder = await vite.createBuilder(
             {
               root: props.vite?.rootDir,
@@ -1579,7 +1586,20 @@ ${[
         Effect.gen(function* () {
           if (props.vite) {
             const [{ assets, bundle }, input] = yield* Effect.all(
-              [viteBuild(props), hashDirectory(props.vite)],
+              [
+                viteBuild(props),
+                // hashDirectory expects `{ cwd, memo }`. The vite props
+                // store the project root under `rootDir`, so map it
+                // here. Without this, `cwd` falls back to
+                // `process.cwd()` and the input hash is computed over
+                // the wrong directory tree (often the entire monorepo
+                // root), making it both slow and unable to detect
+                // changes scoped to the actual Vite project.
+                hashDirectory({
+                  cwd: props.vite.rootDir,
+                  memo: props.vite.memo,
+                }),
+              ],
               { concurrency: "unbounded" },
             );
             return { assets, bundle, input };
@@ -1944,19 +1964,18 @@ ${[
         output: Worker["Attributes"],
       ) {
         if (props.vite) {
-          const input = yield* hashDirectory(props.vite);
+          const input = yield* hashDirectory({
+            cwd: props.vite.rootDir,
+            memo: props.vite.memo,
+          });
           return input !== output.hash?.input;
         }
-        // Always recompute both hashes by walking `dist/` (assets) and
-        // re-bundling the worker. The previous short-circuit
-        // (`Effect.succeed(output.hash.assets)`) compared the cached
-        // hash to itself and could never detect drift, and the
-        // `props.assets.hash` form is the *input* (source) hash which
-        // misses non-deterministic build output (e.g. Astro/Vite
-        // shuffling content-hashed filenames between builds). The
-        // result of either shortcut was deploying a new bundle on top
-        // of stale assets and 404'ing in production. Re-walking is the
-        // only correct comparison.
+        // The asset hash comes from walking the actual `outdir` —
+        // whatever bytes are on disk are what we'd be deploying, so
+        // that's what we diff against. Non-deterministic build outputs
+        // (e.g. Astro/Vite shuffling content-hashed chunk filenames)
+        // are a property of the build, not something we should paper
+        // over here. The bundle hash is similarly recomputed.
         const [assetsHash, bundleHash] = yield* Effect.all(
           [
             prepareAssets(props.assets).pipe(Effect.map((a) => a?.hash)),
@@ -2432,31 +2451,23 @@ const contentTypeFromExtension = (extension: string) => {
 };
 
 type ViteModule = typeof import("vite");
-let _viteModule: ViteModule | null = null;
 
 /**
  * Dynamically load Vite from the project root. Falls back to the bundled
  * copy if the project doesn't have its own Vite installation.
  */
-async function loadVite(): Promise<ViteModule> {
-  if (_viteModule) return _viteModule;
-
-  const projectRoot = process.cwd();
-  let vitePath: string;
-
+async function loadVite(
+  projectRoot: string = process.cwd(),
+): Promise<ViteModule> {
   try {
-    // Resolve "vite" from the project root, not from vinext's location
     const require = createRequire(path.join(projectRoot, "package.json"));
-    vitePath = require.resolve("vite");
+    const vitePath = require.resolve("vite");
+    // On Windows, absolute paths must be file:// URLs for ESM import().
+    const viteUrl = pathToFileURL(vitePath);
+    return await import(/* @vite-ignore */ viteUrl.href);
   } catch {
-    // Fallback: use the Vite that ships with vinext (works for non-linked installs)
-    vitePath = "vite";
+    // Fallback: try to import vite from the global node_modules (works for non-linked installs)
+    // The fallback is a bare specifier and works as-is.
+    return await import("vite");
   }
-
-  // On Windows, absolute paths must be file:// URLs for ESM import().
-  // The fallback ("vite") is a bare specifier and works as-is.
-  const viteUrl = vitePath === "vite" ? vitePath : pathToFileURL(vitePath).href;
-  const vite = (await import(/* @vite-ignore */ viteUrl)) as ViteModule;
-  _viteModule = vite;
-  return vite;
 }

package/src/Cloudflare/index.ts

@@ -1,5 +1,6 @@
 export * from "./ApiToken/index.ts";
 export * from "./Artifacts/index.ts";
+export * from "./AiGateway/index.ts";
 export * from "./CloudflareEnvironment.ts";
 export * from "./Container/index.ts";
 export * from "./D1/index.ts";

package/src/Plan.ts

@@ -30,6 +30,7 @@ import {
   type ResourceLike,
 } from "./Resource.ts";
 import { type StackSpec } from "./Stack.ts";
+import { findCycleMembers } from "./Util/scc.ts";
 import {
   State,
   type CreatedResourceState,
@@ -147,6 +148,14 @@ export type Plan<Output = any> = {
     [id in string]?: Delete<ResourceLike>;
   };
   output: Output;
+  /**
+   * FQNs of resources that participate in a strongly-connected component
+   * of the upstream dependency graph (or have a self-edge). The scheduler
+   * uses this to decide whether an `update` node must publish its prior
+   * attr early to break the cycle, or can simply wait for upstreams and
+   * publish a fresh attr (the common, linear case).
+   */
+  cycleMembers: ReadonlySet<string>;
 };
 
 export interface MakePlanOptions {
@@ -660,12 +669,18 @@ export const make = <A>(
       )).map((update) => [update.resource.FQN, update]),
     ) as Plan["resources"];
 
+    // Compute SCC membership once. Apply uses it to decide whether an
+    // update node must publish its prior attr early to break a cycle, or
+    // can simply wait for upstreams like a DAG node (the common case).
+    const cycleMembers = findCycleMembers(allUpstreamDependencies);
+
     // Detect unsatisfiable dependency cycles among create/replace nodes.
-    // Update/noop nodes signal their Deferred before waitForDeps so they
-    // cannot deadlock. Create/replace nodes only signal early when they
-    // have a precreate handler. Simulate the concurrent execution:
-    // precreate nodes are immediately "resolved", then iteratively resolve
-    // any node whose deps are all resolved. Remaining nodes would deadlock.
+    // Update/noop nodes signal their Deferred before waitForDeps when in a
+    // cycle so they cannot deadlock. Create/replace nodes only signal
+    // early when they have a precreate handler. Simulate the concurrent
+    // execution: precreate nodes are immediately "resolved", then
+    // iteratively resolve any node whose deps are all resolved. Remaining
+    // nodes would deadlock.
     {
       const createReplaceNodes = new Set(
         Object.entries(resourceGraph)
@@ -803,6 +818,7 @@ export const make = <A>(
       resources: resourceGraph,
       deletions,
       output: stack.output,
+      cycleMembers,
     } satisfies Plan<A> as Plan<A>;
   }).pipe(
     ensureArtifactStore,

package/src/State/HttpStateApi.ts

@@ -141,6 +141,21 @@ export const GetReplacedResources = HttpApiEndpoint.get(
   },
 );
 
+/** Response shape for the unauthenticated `/version` probe. */
+export const VersionResponse = Schema.Struct({
+  version: Schema.Number,
+});
+
+/**
+ * Unauthenticated probe so clients can detect a stale (or absent)
+ * deployed worker without holding a valid bearer token. The returned
+ * version is bumped whenever the wire / behavioural contract changes
+ * in a way that requires a redeploy.
+ */
+export const GetVersion = HttpApiEndpoint.get("getVersion", "/version", {
+  success: VersionResponse,
+});
+
 export class StateGroup extends HttpApiGroup.make("state")
   .add(ListStacks)
   .add(ListStages)
@@ -152,4 +167,10 @@ export class StateGroup extends HttpApiGroup.make("state")
   .add(DeleteStack)
   .middleware(StateAuth) {}
 
-export class StateApi extends HttpApi.make("alchemy-state").add(StateGroup) {}
+export class VersionGroup extends HttpApiGroup.make("version").add(
+  GetVersion,
+) {}
+
+export class StateApi extends HttpApi.make("alchemy-state")
+  .add(StateGroup)
+  .add(VersionGroup) {}

package/src/Util/cached-function.ts

@@ -0,0 +1,75 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+
+/**
+ * Options for creating a cached function.
+ */
+export interface CachedFunctionOptions<A> {
+  /**
+   * Function to convert arguments to a cache key string.
+   * Defaults to `JSON.stringify`.
+   */
+  readonly key?: (args: A) => string;
+}
+
+/**
+ * Creates a memoized version of a function that returns an Effect.
+ *
+ * The key feature is deduplication of concurrent calls with the same inputs -
+ * only one execution happens while other callers wait for and receive the same result.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect";
+ * import { cachedFunction } from "~/lib/cached-function";
+ *
+ * const fetchUser = (id: string) =>
+ *   Effect.promise(() => fetch(`/users/${id}`).then(r => r.json()));
+ *
+ * const program = Effect.gen(function* () {
+ *   const cachedFetchUser = yield* cachedFunction(fetchUser);
+ *
+ *   // These concurrent calls will only trigger one fetch
+ *   const [user1, user2] = yield* Effect.all([
+ *     cachedFetchUser("123"),
+ *     cachedFetchUser("123"),
+ *   ]);
+ * });
+ * ```
+ */
+export const cachedFunction = <A, B, E, R>(
+  fn: (args: A) => Effect.Effect<B, E, R>,
+  options?: CachedFunctionOptions<A>,
+): Effect.Effect<(args: A) => Effect.Effect<B, E, R>> =>
+  Effect.sync(() => {
+    const keyFn = options?.key ?? JSON.stringify;
+    const cache = new Map<string, Deferred.Deferred<B, E>>();
+
+    return (args: A): Effect.Effect<B, E, R> =>
+      Effect.suspend(() => {
+        const cacheKey = keyFn(args);
+        const existing = cache.get(cacheKey);
+
+        // If there's already a deferred for this key, wait on it
+        if (existing) {
+          return Deferred.await(existing);
+        }
+
+        // Create a new deferred and store it
+        return Effect.gen(function* () {
+          const deferred = yield* Deferred.make<B, E>();
+          cache.set(cacheKey, deferred);
+
+          // Execute the effect and complete the deferred
+          const exit = yield* Effect.exit(fn(args));
+          yield* Deferred.done(deferred, exit);
+
+          if (exit._tag === "Failure") {
+            cache.delete(cacheKey);
+          }
+
+          // Return the result
+          return yield* exit;
+        });
+      });
+  });