alchemy 2.0.0-beta.74 → 2.0.0-beta.76

package/src/AWS/Website/Waku.ts

@@ -1,3 +1,4 @@
+import type { InputProps } from "../../Input.ts";
 import * as Namespace from "../../Namespace.ts";
 import { makeFrameworkSite, type FrameworkSiteProps } from "./FrameworkSite.ts";
 
@@ -10,11 +11,30 @@ export const WAKU_AWS_TARGET_SPECIFIER =
 
 export interface WakuProps extends FrameworkSiteProps {
   /**
-   * Waku config overrides (`srcDir`, `distDir`, `basePath`, `vite`, ...)
-   * merged over the project's own `waku.config.ts`. `unstable_adapter` is
-   * owned by the AWS deploy target and may not be set here.
+   * Waku config overrides merged over the project's `waku.config.*`
+   * (per-key; deploy-time values win). For values that vary by stage or
+   * come from other resources — static config belongs in `waku.config.*`.
    */
-  waku?: Record<string, unknown>;
+  waku?: {
+    /**
+     * Waku `srcDir` (relative to {@link FrameworkSiteProps.rootDir}).
+     * @default "src"
+     */
+    srcDir?: string;
+    /**
+     * Waku `distDir` (relative to {@link FrameworkSiteProps.rootDir}).
+     * A custom `distDir` must be gitignored (or added to `memo.exclude`)
+     * so the build output stays excluded from the rebuild-deciding input
+     * hash.
+     * @default "dist"
+     */
+    distDir?: string;
+    /**
+     * Waku `basePath`.
+     * @default "/"
+     */
+    basePath?: string;
+  };
 }
 
 /**
@@ -52,21 +72,37 @@ export interface WakuProps extends FrameworkSiteProps {
  * ```typescript
  * const site = yield* AWS.Website.Waku("Web", {
  *   rootDir: "./app",
- *   server: {
- *     memorySize: 2048,
- *     environment: {
- *       API_BASE: api.url,
- *     },
+ *   memorySize: 2048,
+ *   env: {
+ *     API_BASE: api.url,
+ *   },
+ * });
+ * ```
+ *
+ * ### Waku Config Overrides
+ * Waku configuration lives in your `waku.config.*`. The `waku` prop
+ * overrides it per key at deploy time — for values that vary by stage
+ * or come from other resources.
+ *
+ * **Example:** Stage-dependent base path
+ * ```typescript
+ * const site = yield* AWS.Website.Waku("Web", {
+ *   waku: {
+ *     basePath: "/docs/",
  *   },
  * });
  * ```
  *
  * @resource
  */
-export const Waku = (id: string, props: WakuProps = {}) =>
-  makeFrameworkSite(id, props, {
+export const Waku = (id: string, props: InputProps<WakuProps> = {}) => {
+  const p = props as WakuProps;
+  return makeFrameworkSite(id, props, {
     name: "Waku",
     framework: WAKU_FRAMEWORK_SPECIFIER,
     target: WAKU_AWS_TARGET_SPECIFIER,
-    options: props.waku ? { waku: props.waku } : undefined,
+    // Deploy-time waku config overrides, merged over the project's
+    // `waku.config.*` by the integration (per-key; overrides win).
+    options: p.waku !== undefined ? { waku: p.waku } : undefined,
   }).pipe(Namespace.push(id));
+};

package/src/AWS/Website/index.ts

@@ -1,14 +1,17 @@
 export * from "./AssetDeployment.ts";
 export * from "./Astro.ts";
+export * from "./Foldkit.ts";
 export * from "./FrameworkSite.ts";
 export * from "./Nextjs.ts";
 export * from "./Nuxt.ts";
 export * from "./Octane.ts";
+export * from "./ReactRouter.ts";
 export * from "./Router.ts";
-export * from "./Server.ts";
 export * from "./shared.ts";
+export * from "./SolidStart.ts";
 export * from "./SsrSite.ts";
 export * from "./StaticSite.ts";
 export * from "./SvelteKit.ts";
+export * from "./TanStackStart.ts";
 export * from "./Vite.ts";
 export * from "./Waku.ts";

package/src/AWS/Website/shared.ts

@@ -31,7 +31,8 @@ export interface WebsiteRouterBindTargets {
   /**
    * The Router's Route 53 alias record set — bound hostnames get A-alias
    * records pointing at the distribution. Absent when the Router's domain
-   * sets `dns: false` or has no `hostedZoneId`.
+   * sets `dns: false`. Without an explicit `hostedZoneId`, the set infers
+   * its zone from the first bound hostname.
    */
   records?: Records;
 }
@@ -69,7 +70,11 @@ export interface WebsiteStandaloneDomainProps {
    */
   name: string;
   /**
-   * Hosted zone used for Route 53 automation.
+   * Hosted zone used for Route 53 automation. Optional — when omitted,
+   * the most specific PUBLIC hosted zone in the account containing each
+   * hostname is inferred by walking its parent domains; the deploy fails
+   * actionably when no zone matches. Pass an explicit id to pin the zone
+   * (e.g. when several zones could match).
    */
   hostedZoneId?: string;
   /**
@@ -256,6 +261,10 @@ export interface StaticSiteBuildProps {
    * Directory containing the build output, relative to `path`.
    */
   output: string;
+  /**
+   * Environment variables exposed to the build command.
+   */
+  env?: Record<string, Input<string>>;
   /**
    * Glob patterns of files to hash. Paths are relative to `path`.
    * When the hash of matched files changes, the build will re-run.

package/src/Auth/AuthProvider.ts

@@ -181,7 +181,13 @@ export const AuthProvider =
                   if (LOCKED_METHODS.has(methodName)) {
                     // First positional arg is always `profileName`.
                     const profileName = args[0] as string;
-                    eff = withLock(`${profileName}-${name}`, eff);
+                    eff = withLock(`${profileName}-${name}`, eff, {
+                      label: `${name}.${methodName} (profile '${profileName}')`,
+                      // `login`/`configure` legitimately block on the user
+                      // (browser OAuth, `aws sso login`), and a periodic
+                      // notice would trample the prompt they are answering.
+                      watchdog: !INTERACTIVE_METHODS.has(methodName),
+                    });
                   }
                   if (INTERACTIVE_METHODS.has(methodName)) {
                     eff = Semaphore.withPermits(interactiveMutex, 1)(eff);

package/src/Auth/Lock.ts

@@ -1,4 +1,5 @@
 import * as Clock from "effect/Clock";
+import * as Console from "effect/Console";
 import * as Data from "effect/Data";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
@@ -17,6 +18,9 @@ const STALE = Duration.seconds(30);
 const REFRESH = Duration.seconds(10);
 const RETRY_INTERVAL = Duration.millis(50);
 const DEFAULT_TIMEOUT = Duration.minutes(2);
+// How often to remind the user that a lock wait / locked operation is still
+// outstanding. Long enough that healthy runs never print it.
+const STALL_INTERVAL = Duration.seconds(30);
 
 class LockHeld extends Data.TaggedError("LockHeld") {}
 
@@ -131,6 +135,38 @@ const acquireFileLock = Effect.fn(function* (
   );
 });
 
+type Phase = { current: "waiting" | "held" };
+
+/**
+ * Periodic "I am not dead, I am stuck here" notice, forked for the lifetime
+ * of a {@link withLock} call.
+ *
+ * Deliberately `Console.error` rather than `Effect.logWarning`: the CLI's
+ * telemetry layer replaces the console logger with the OTLP one (see
+ * `Telemetry/Layer.ts`), so log records reach `.alchemy/log/out` but never
+ * the terminal. The whole point of this notice is to reach the user who is
+ * watching a frozen terminal, so it must not go through the logger.
+ */
+const stallNotice = (
+  lockPath: string,
+  label: string,
+  phase: Phase,
+  interval: Duration.Input,
+) =>
+  Effect.suspend(() => {
+    let seconds = 0;
+    return Effect.suspend(() => {
+      seconds += Duration.toSeconds(interval);
+      return Console.error(
+        phase.current === "waiting"
+          ? `alchemy: ${seconds}s waiting for the auth lock '${lockPath}' (${label}). ` +
+              `Another alchemy process holds it; if none is running, delete that directory.`
+          : `alchemy: ${label} has been running for ${seconds}s while holding the auth lock ` +
+              `'${lockPath}'. Re-run with --log-level debug for detail.`,
+      );
+    }).pipe(Effect.delay(interval), Effect.repeat(Schedule.spaced(interval)));
+  });
+
 /**
  * Serialise execution of `effect` for the same `key`, both within this
  * process (a semaphore) and across processes on the same machine (an atomic
@@ -144,9 +180,33 @@ const acquireFileLock = Effect.fn(function* (
 export const withLock = <A, E, R>(
   key: string,
   effect: Effect.Effect<A, E, R>,
-  options?: { readonly timeout?: Duration.Input },
+  options?: {
+    readonly timeout?: Duration.Input;
+    /**
+     * Human-readable name of the work being serialised, used in the debug
+     * log lines and the stall notice. Defaults to `key`.
+     */
+    readonly label?: string;
+    /**
+     * Print a periodic notice to stderr while this lock is being waited on
+     * or held (see {@link stallNotice}). Pass `false` for flows that
+     * legitimately block on the user — a browser OAuth round-trip, an
+     * `aws sso login` child process — where a repeating notice would be
+     * both wrong and destructive to the prompt on screen.
+     *
+     * @default true
+     */
+    readonly watchdog?: boolean;
+    /**
+     * Interval between stall notices.
+     *
+     * @internal exposed so tests need not wait 30 real seconds.
+     */
+    readonly stallInterval?: Duration.Input;
+  },
 ) => {
   const safeKey = sanitizeLockKey(key);
+  const label = options?.label ?? key;
   let semaphore = semaphores.get(safeKey);
   if (semaphore === undefined) {
     semaphore = Semaphore.makeUnsafe(1);
@@ -159,11 +219,29 @@ export const withLock = <A, E, R>(
       // `Profile -> AuthProvider -> Lock -> Profile` import cycle never
       // sees it uninitialised.
       const lockPath = path.join(rootDir, "lock", `${safeKey}.lock`);
+      const phase: Phase = { current: "waiting" };
+      if (options?.watchdog !== false) {
+        yield* Effect.forkScoped(
+          stallNotice(
+            lockPath,
+            label,
+            phase,
+            options?.stallInterval ?? STALL_INTERVAL,
+          ),
+        );
+      }
+      yield* Effect.logDebug(`auth lock: acquiring '${lockPath}' for ${label}`);
       yield* acquireFileLock(
         lockPath,
         options?.timeout ?? DEFAULT_TIMEOUT,
       ).pipe(Effect.orDie);
-      return yield* effect;
+      phase.current = "held";
+      yield* Effect.logDebug(`auth lock: acquired '${lockPath}' for ${label}`);
+      return yield* effect.pipe(
+        Effect.onExit(() =>
+          Effect.logDebug(`auth lock: releasing '${lockPath}' for ${label}`),
+        ),
+      );
     }).pipe(Effect.scoped),
   );
 };

package/src/Axiom/Dataset.ts

@@ -24,6 +24,13 @@ export type DatasetProps = {
   name: string;
   /** Free-form description shown in the Axiom UI. */
   description?: string;
+  /**
+   * Edge deployment where Axiom stores and processes the dataset's data.
+   * Defaults to the organization's default edge deployment.
+   *
+   * Cannot be changed after creation — triggers a replacement.
+   */
+  edgeDeployment?: string;
   /**
    * Dataset kind. Defaults to `axiom:events:v1`.
    *
@@ -50,8 +57,13 @@ export type Dataset = Resource<
     kind: DatasetKind;
     description: string;
     created: string;
+    /** Edge deployment where the dataset's data is stored and processed. */
+    edgeDeployment: string;
+    /** Base URL for ingesting and querying data in the dataset's edge deployment. */
+    edgeDeploymentUrl: string;
+    /** Base URL for Axiom's centralized management API. */
     apiBaseUrl: string;
-    /** Root OTLP endpoint (`${apiBaseUrl}`). Most exporters auto-append the signal path. */
+    /** Root OTLP endpoint. Most exporters auto-append the signal path. */
     otelEndpoint: string;
     /** OTLP/HTTP traces endpoint. */
     otelTracesEndpoint: string;
@@ -76,11 +88,11 @@ export type Dataset = Resource<
  * the data is shown in the UI, and **cannot be changed** after creation
  * (changing it triggers a replacement, which deletes the data).
  *
- * Datasets expose Axiom's OTLP/HTTP endpoints (`otelTracesEndpoint`,
- * `otelLogsEndpoint`, `otelMetricsEndpoint`) as output attributes so you can
- * inject them into a Worker / Lambda's env vars for OpenTelemetry shipping.
- * The bearer token is **not** stored in resource state — supply
- * `Authorization: Bearer <AXIOM_TOKEN>` separately at runtime.
+ * Datasets expose their edge deployment and Axiom's OTLP/HTTP endpoints
+ * (`otelTracesEndpoint`, `otelLogsEndpoint`, `otelMetricsEndpoint`) as output
+ * attributes so you can inject them into a Worker / Lambda's env vars for
+ * OpenTelemetry shipping. The bearer token is **not** stored in resource state
+ * — supply `Authorization: Bearer <AXIOM_TOKEN>` separately at runtime.
  * @see https://axiom.co/docs/reference/datasets
  * @see https://axiom.co/docs/send-data/opentelemetry — OTLP endpoint reference
  *
@@ -153,18 +165,6 @@ const parseMarker = (
   return { stack: m[1], stage: m[2], id: m[3] };
 };
 
-const buildOtelAttrs = (apiBaseUrl: string, name: string) => {
-  const root = apiBaseUrl.replace(/\/$/, "");
-  return {
-    apiBaseUrl: root,
-    otelEndpoint: root,
-    otelTracesEndpoint: `${root}/v1/traces`,
-    otelLogsEndpoint: `${root}/v1/logs`,
-    otelMetricsEndpoint: `${root}/v1/metrics`,
-    otelHeaders: { "X-Axiom-Dataset": name } as Record<string, string>,
-  };
-};
-
 export const DatasetProvider = () =>
   Provider.effect(
     Dataset,
@@ -176,17 +176,37 @@ export const DatasetProvider = () =>
       const listDatasets = yield* Axiom.getDatasets;
       const del = yield* Axiom.deleteDataset;
 
-      const toAttrs = (dataset: Axiom.Dataset) => ({
-        id: dataset.id,
-        name: dataset.name,
-        kind: dataset.kind,
-        description: stripMarker(dataset.description),
-        created: dataset.created,
-        ...buildOtelAttrs(apiBaseUrl, dataset.name),
+      const toAttrs = Effect.fn(function* (dataset: Axiom.Dataset) {
+        if (!dataset.edgeDeployment || !dataset.edgeDeploymentUrl) {
+          return yield* Effect.fail(
+            new Error(
+              `Axiom dataset "${dataset.name}" is missing its edge deployment metadata`,
+            ),
+          );
+        }
+        const apiRoot = apiBaseUrl.replace(/\/$/, "");
+        const otelRoot = dataset.edgeDeploymentUrl.replace(/\/$/, "");
+        return {
+          id: dataset.id,
+          name: dataset.name,
+          kind: dataset.kind,
+          description: stripMarker(dataset.description),
+          created: dataset.created,
+          edgeDeployment: dataset.edgeDeployment,
+          edgeDeploymentUrl: dataset.edgeDeploymentUrl,
+          apiBaseUrl: apiRoot,
+          otelEndpoint: otelRoot,
+          otelTracesEndpoint: `${otelRoot}/v1/traces`,
+          otelLogsEndpoint: `${otelRoot}/v1/logs`,
+          otelMetricsEndpoint: `${otelRoot}/v1/metrics`,
+          otelHeaders: {
+            "X-Axiom-Dataset": dataset.name,
+          } as Record<string, string>,
+        };
       });
 
       return {
-        stables: ["id", "name", "kind"],
+        stables: ["id", "name", "kind", "edgeDeployment", "edgeDeploymentUrl"],
         // Enumerate every dataset in the org. Axiom exposes a single
         // account-wide `GET /v2/datasets` collection op (no pagination), so we
         // fetch it once and hydrate each row into the exact `read`/`toAttrs`
@@ -194,7 +214,7 @@ export const DatasetProvider = () =>
         list: () =>
           Effect.gen(function* () {
             const datasets = yield* listDatasets({});
-            return datasets.map(toAttrs);
+            return yield* Effect.forEach(datasets, toAttrs);
           }),
         diff: Effect.fn(function* ({ olds, news, output }) {
           if (!isResolved(news)) return undefined;
@@ -204,6 +224,13 @@ export const DatasetProvider = () =>
           if (news.kind && output && news.kind !== output.kind) {
             return { action: "replace" } as const;
           }
+          if (
+            news.edgeDeployment &&
+            output &&
+            news.edgeDeployment !== output.edgeDeployment
+          ) {
+            return { action: "replace" } as const;
+          }
           if (
             news.description !== olds?.description ||
             news.retentionDays !== olds?.retentionDays ||
@@ -237,6 +264,7 @@ export const DatasetProvider = () =>
               create({
                 name: news.name,
                 description: augmentDescription(news.description, marker),
+                edgeDeployment: news.edgeDeployment,
                 kind: news.kind,
                 retentionDays: news.retentionDays,
                 useRetentionPeriod: news.useRetentionPeriod,
@@ -260,7 +288,7 @@ export const DatasetProvider = () =>
                   }),
               ),
             );
-            return toAttrs(current);
+            return yield* toAttrs(current);
           }
 
           // Sync — the dataset exists. Apply mutable aspects (description,
@@ -275,7 +303,7 @@ export const DatasetProvider = () =>
             current.retentionDays !== news.retentionDays ||
             current.useRetentionPeriod !== news.useRetentionPeriod;
           if (!needsSync) {
-            return toAttrs(current);
+            return yield* toAttrs(current);
           }
           const updated = yield* update({
             dataset_id: current.id,
@@ -283,7 +311,7 @@ export const DatasetProvider = () =>
             retentionDays: news.retentionDays,
             useRetentionPeriod: news.useRetentionPeriod,
           });
-          return toAttrs(updated);
+          return yield* toAttrs(updated);
         }),
         delete: Effect.fn(function* ({ output }) {
           yield* del({ dataset_id: output.id }).pipe(
@@ -305,7 +333,7 @@ export const DatasetProvider = () =>
             ownership.stack === stack.name &&
             ownership.stage === stage &&
             ownership.id === id;
-          const attrs = toAttrs(existing);
+          const attrs = yield* toAttrs(existing);
           return isOurs ? attrs : Unowned(attrs);
         }),
       };

package/src/Binding.ts

@@ -1,9 +1,11 @@
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import type { Input } from "./Input.ts";
 import * as Output from "./Output.ts";
-import type { ResourceLike } from "./Resource.ts";
+import { describeDataPlane, type DataPlaneResolution } from "./Provider.ts";
+import { isResource, type ResourceLike } from "./Resource.ts";
 import { Self } from "./Self.ts";
 import { taggedFunction } from "./Util/effect.ts";
 
@@ -124,7 +126,19 @@ export const Service = <
       Effect.all(
         args.map((arg) => (Effect.isEffect(arg) ? arg : Effect.succeed(arg))),
         { concurrency: "unbounded" },
-      ).pipe(Effect.flatMap((resolved) => f(...resolved))),
+      ).pipe(
+        Effect.flatMap((resolved) =>
+          f(...resolved).pipe(
+            // Deploy-time data-plane routing: the client's calls must target
+            // whatever data plane the bound resource actually lives on. In an
+            // `alchemy dev` run a local-mode resource exists only on the
+            // emulator, so invoking its client against the ambient (live)
+            // cloud environment would miss it — or worse, mutate the real
+            // cloud. See {@link routeClientDataPlane}.
+            Effect.flatMap((client) => routeClientDataPlane(resolved, client)),
+          ),
+        ),
+      ),
     );
   // Plan-time invoke (see the `execute` doc on `Service`): bind hostless —
   // `Binding.Host` is total and resolves `undefined`, so impls skip their
@@ -140,6 +154,145 @@ export const Service = <
   return taggedFunction(tag as any, callable) as unknown as Self;
 };
 
+/**
+ * Route a binding client's invocations to the data plane its bound
+ * resource(s) actually live on.
+ *
+ * A dual-provider resource in an `alchemy dev` run resolves to its LOCAL
+ * provider (unless pinned live via `Alchemy.remote()`), so the physical
+ * resource exists only on the local emulator. A client invoked at deploy
+ * time — inside an {@link ../Action.ts Action} body or a plan-time
+ * {@link Service.execute} — would otherwise resolve the ambient (live)
+ * cloud environment and miss it, or mutate the real cloud. The bound
+ * resource's provider registers the emulator context as
+ * {@link ProviderService.localDataPlane} (e.g. AWS's `flociServices()`);
+ * this wrapper provides it *closest* around every invocation, so it wins
+ * over the ambient environment exactly like the local provider's lifecycle
+ * override does.
+ *
+ * Resolution happens once per bind, in the same context the bind step ran
+ * in (the Provider registry and `AlchemyContext` are ambient during stack
+ * evaluation and apply). At runtime inside a deployed Function/Worker there
+ * is no registry and no engine — the wrapper is skipped entirely.
+ */
+const routeClientDataPlane = (
+  resolvedArgs: readonly unknown[],
+  client: unknown,
+): Effect.Effect<any> =>
+  Effect.suspend(() => {
+    if (globalThis.__ALCHEMY_RUNTIME__) return Effect.succeed(client);
+    // Bind arguments are the capability's target resources by convention —
+    // scan the top level plus one array level (multi-resource bindings like
+    // ExecuteTransaction take tuples of resources).
+    const resources = resolvedArgs.flatMap((arg): ResourceLike[] =>
+      Array.isArray(arg)
+        ? arg.filter(isResource)
+        : isResource(arg)
+          ? [arg]
+          : [],
+    );
+    // Account-scoped clients (no resource among the args) need no routing:
+    // the ambient environment is already mode-aware — a dev run's ambient IS
+    // the emulator (see AWS/Providers.ts), a deploy's is the live chain.
+    if (resources.length === 0) return Effect.succeed(client);
+    return Effect.gen(function* () {
+      const planes: DataPlaneResolution[] = [];
+      for (const resource of resources) {
+        planes.push(yield* describeDataPlane(resource));
+      }
+      const local = [
+        ...new Set(
+          planes.flatMap((p) => (p.kind === "local" ? [p.layer] : [])),
+        ),
+      ];
+      if (local.length > 0) {
+        if (local.length > 1 || planes.some((p) => p.kind !== "local")) {
+          // Say exactly where each resource lands: a dual provider that never
+          // registered a data plane is the usual culprit, and it would
+          // otherwise read as "live" — the report that sent a user chasing a
+          // `remote()` they never wrote.
+          const where = resources
+            .map((r, i) => `${r.FQN} → ${describeResolution(planes[i]!)}`)
+            .join("; ");
+          return yield* Effect.die(
+            `Binding client spans mixed data planes: ${where}. A single API ` +
+              "call cannot span the local emulator and the real cloud. If a " +
+              "resource above is meant to be emulated, its provider must " +
+              "declare `dataPlane` on its ProviderLayer.dual registration; " +
+              "otherwise make the bound resources' modes agree (e.g. pipe them " +
+              "all through Alchemy.remote(), or none).",
+          );
+        }
+        return wrapClientInvocations(client, local[0]!);
+      }
+      // Live-mode / `Alchemy.remote()`: ambient in a `dev` run is the
+      // emulator, so provide the registration-captured live environment
+      // closest (the inverse of the local wrap above).
+      const live = [
+        ...new Set(
+          planes.flatMap((p) =>
+            p.kind === "live" && p.layer !== undefined ? [p.layer] : [],
+          ),
+        ),
+      ];
+      if (live.length === 1) return wrapClientInvocations(client, live[0]!);
+      return client;
+    });
+  });
+
+const describeResolution = (plane: DataPlaneResolution): string => {
+  switch (plane.kind) {
+    case "local":
+      return "local emulator";
+    case "live":
+      return "real cloud (live mode)";
+    case "undeclared":
+      return `real cloud (its provider ${plane.providerType} is dual-mode but registers no local data plane)`;
+    case "agnostic":
+      return "real cloud (mode-agnostic provider)";
+    case "unregistered":
+      return "real cloud (no provider registered)";
+  }
+};
+
+/**
+ * Wrap every invocation surface of a binding client so its returned Effects
+ * run with `layer` provided closest. Handles the client shapes bindings
+ * return: a callable (the common per-operation client), an object of
+ * methods/Effects (multi-method clients), or a bare Effect. Anything else
+ * passes through untouched. Proxies preserve identity, extra properties,
+ * and method names.
+ */
+const wrapClientInvocations = (
+  client: unknown,
+  layer: Layer.Layer<any, any, never>,
+): unknown => {
+  const provide = (value: unknown): unknown =>
+    Effect.isEffect(value)
+      ? Effect.provide(value as Effect.Effect<any, any, any>, layer)
+      : value;
+  if (Effect.isEffect(client)) return provide(client);
+  if (typeof client === "function") {
+    return new Proxy(client, {
+      apply: (target, thisArg, argArray) =>
+        provide(Reflect.apply(target, thisArg, argArray)),
+    });
+  }
+  if (typeof client === "object" && client !== null) {
+    return new Proxy(client, {
+      get: (target, prop, receiver) => {
+        const value = Reflect.get(target, prop, receiver);
+        if (typeof value === "function") {
+          return (...args: any[]) =>
+            provide(Reflect.apply(value, target, args));
+        }
+        return provide(value);
+      },
+    });
+  }
+  return client;
+};
+
 /**
  * Resolves the host resource a binding is attaching to (the Worker / Lambda
  * Function), i.e. `Self`. It is typed WITHOUT a Context requirement because it