alchemy 2.0.0-beta.51 → 2.0.0-beta.53

package/src/Cloudflare/Workers/WorkerAsyncBindings.ts

@@ -1,12 +1,10 @@
 import type { PutScriptRequest } from "@distilled.cloud/cloudflare/workers";
-import * as Config from "effect/Config";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
 import type { InputProps } from "../../Input.ts";
 import * as Output from "../../Output.ts";
 import type { ResourceBinding } from "../../Resource.ts";
 import { isYieldableEffectLike } from "../../Util/effect.ts";
-import { asEffect } from "../../Util/types.ts";
 import { isAiGateway } from "../AiGateway/AiGateway.ts";
 import { isAnalyticsEngineDataset } from "../AnalyticsEngine/AnalyticsEngineDataset.ts";
 import { isArtifacts } from "../Artifacts/Artifacts.ts";
@@ -25,6 +23,7 @@ import { isVectorizeIndex } from "../Vectorize/VectorizeIndex.ts";
 import { isAssets } from "./Assets.ts";
 import { isDurableObjectNamespaceLike } from "./DurableObjectNamespace.ts";
 import { isDynamicWorkerLoader } from "./DynamicWorkerLoader.ts";
+import { isVersionMetadata } from "./VersionMetadata.ts";
 import type { WorkerBindingProps } from "./Worker.ts";
 import { isWorker, type Worker, type WorkerProps } from "./Worker.ts";
 import type { WorkerBinding, WorkerBindingResource } from "./WorkerBinding.ts";
@@ -50,8 +49,10 @@ export const bindWorkerAsyncBindings = Effect.fnUntraced(function* (
           : bindingEff
       ) as WorkerBindingResource;
 
-      const bindingMeta: InputProps<WorkerBinding> | undefined =
-        yield* asEffect(toBinding(bindingName, binding));
+      const bindingMeta: InputProps<WorkerBinding> | undefined = toBinding(
+        bindingName,
+        binding,
+      );
 
       if (bindingMeta) {
         yield* resource.bind`${bindingName}`({
@@ -74,20 +75,14 @@ type BindingSpec = InputProps<
 const toBinding = (
   bindingName: string,
   binding: WorkerBindingResource,
-): BindingSpec | Effect.Effect<BindingSpec> | undefined => {
-  // narrowing to Config<unknown> doesn't work for us, we need any
-  const isConfig: (a: any) => a is Config.Config<any> = Config.isConfig;
-  // narrowing to Redacted<unknown> doesn't work for us, we need any
-  const isRedacted: (a: any) => a is Redacted.Redacted<any> =
-    Redacted.isRedacted;
-
+): BindingSpec => {
   if (typeof binding === "string") {
     return {
       type: "plain_text",
       name: bindingName,
       text: binding,
     };
-  } else if (isRedacted(binding)) {
+  } else if (Redacted.isRedacted(binding)) {
     const val = Redacted.value(binding);
     if (typeof val === "string") {
       return {
@@ -102,14 +97,6 @@ const toBinding = (
         text: JSON.stringify(val),
       };
     }
-  } else if (isConfig(binding)) {
-    return binding.pipe(
-      Effect.flatMap((json) => {
-        const b = toBinding(bindingName, json)!;
-        return Effect.isEffect(b) ? b : Effect.succeed(b);
-      }),
-      Effect.orDie,
-    );
   } else if (isAssets(binding)) {
     return {
       type: "assets",
@@ -218,11 +205,16 @@ const toBinding = (
       secretName: binding.secretName,
       storeId: binding.storeId,
     };
+  } else if (isVersionMetadata(binding)) {
+    return {
+      type: "version_metadata",
+      name: bindingName,
+    };
   } else if (isDynamicWorkerLoader(binding)) {
     return {
       type: "worker_loader",
       name: bindingName,
-    } as any;
+    };
   } else {
     return {
       type: "json",

package/src/Cloudflare/Workers/WorkerBinding.ts

@@ -23,6 +23,7 @@ import type { VectorizeIndex } from "../Vectorize/VectorizeIndex.ts";
 import type { Assets } from "./Assets.ts";
 import type { DurableObjectNamespaceLike } from "./DurableObjectNamespace.ts";
 import type { DynamicWorkerLoader } from "./DynamicWorkerLoader.ts";
+import type { VersionMetadata } from "./VersionMetadata.ts";
 import { makeRpcStub } from "./Rpc.ts";
 import { isWorker, Worker, WorkerEnvironment } from "./Worker.ts";
 
@@ -59,6 +60,7 @@ export type WorkerBindingResource =
   | Secret
   | Worker
   | DynamicWorkerLoader
+  | VersionMetadata
   | DurableObjectNamespaceLike<any>;
 
 export type WorkerBindings = {

package/src/Cloudflare/Workers/Workflow.ts

@@ -3,6 +3,7 @@ import type { ConfigError } from "effect/Config";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import { AlchemyContext } from "../../AlchemyContext.ts";
+import { ExecutionContext } from "../../ExecutionContext.ts";
 import { ALCHEMY_PHASE } from "../../Phase.ts";
 import type { PlatformServices } from "../../Platform.ts";
 import * as Provider from "../../Provider.ts";
@@ -100,8 +101,18 @@ export const sleepUntil = (
  * from inside workflow steps via `yield* WorkerEnvironment` — the type must
  * reflect that or `yield* WorkerEnvironment` fails to type-check inside a
  * body even though it succeeds at runtime.
+ *
+ * `ExecutionContext` (scope + cache) is provided per run-invocation by
+ * `WorkflowBridge.run` and threaded into every `task` via the surrounding
+ * body context, so `@binding` helpers that need it (e.g. `Drizzle.postgres`)
+ * resolve their per-run resources inside workflow steps just as they do in a
+ * Worker `fetch`/`queue` handler.
  */
-export type WorkflowRunServices = WorkflowEvent | WorkflowStep | WorkerServices;
+export type WorkflowRunServices =
+  | WorkflowEvent
+  | WorkflowStep
+  | WorkerServices
+  | ExecutionContext;
 
 export type WorkflowServices = WorkflowRunServices | PlatformServices;
 
@@ -480,9 +491,6 @@ export const WorkflowProvider = () =>
     WorkflowResource,
     Effect.gen(function* () {
       const ctx = yield* AlchemyContext;
-      const { accountId } = yield* CloudflareEnvironment;
-      const putWorkflow = yield* workflows.putWorkflow;
-      const deleteWorkflow = yield* workflows.deleteWorkflow;
 
       return WorkflowResource.Provider.of({
         // The `workflowId` is no longer marked as stable because if you start in dev mode, the ID will change on first deploy.
@@ -494,6 +502,7 @@ export const WorkflowProvider = () =>
           }
         }),
         reconcile: Effect.fnUntraced(function* ({ news, output }) {
+          const { accountId } = yield* yield* CloudflareEnvironment;
           const acct = output?.accountId ?? accountId;
           yield* Effect.logInfo(
             `Cloudflare Workflow reconcile: ${news.workflowName}`,
@@ -511,7 +520,7 @@ export const WorkflowProvider = () =>
           // payloads converge to the same state and a missing workflow is
           // created on the spot. There is no separate observe step needed
           // — the API is naturally reconciler-shaped.
-          const result = yield* putWorkflow({
+          const result = yield* workflows.putWorkflow({
             accountId: acct,
             workflowName: news.workflowName,
             className: news.className,
@@ -529,10 +538,12 @@ export const WorkflowProvider = () =>
           yield* Effect.logInfo(
             `Cloudflare Workflow delete: ${output.workflowName}`,
           );
-          yield* deleteWorkflow({
-            accountId: output.accountId,
-            workflowName: output.workflowName,
-          }).pipe(Effect.catchTag("WorkflowNotFound", () => Effect.void));
+          yield* workflows
+            .deleteWorkflow({
+              accountId: output.accountId,
+              workflowName: output.workflowName,
+            })
+            .pipe(Effect.catchTag("WorkflowNotFound", () => Effect.void));
         }),
       });
     }),

package/src/Cloudflare/Workers/WorkflowBridge.ts

@@ -1,11 +1,17 @@
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Scope from "effect/Scope";
+import { ExecutionContext } from "../../ExecutionContext.ts";
+import { isScopeEjected } from "./HttpServer.ts";
+import { getWorkerExport } from "./WorkerBridge.ts";
 import {
   WorkflowEvent as WorkflowEventService,
   type WorkflowExport,
   type WorkflowImpl,
   WorkflowStep,
 } from "./Workflow.ts";
-import { getWorkerExport } from "./WorkerBridge.ts";
 
 /**
  * Create a WorkflowBridge class that extends `WorkflowEntrypoint` and
@@ -52,15 +58,50 @@ export const makeWorkflowBridge =
 
       async run(event: any, step: any): Promise<unknown> {
         const fn = await this.fn;
-        return Effect.runPromise(
+        // Each run-invocation gets a fresh ExecutionContext (scope + cache),
+        // following the same per-invocation-scope pattern as
+        // `WorkerBridge.processEvent`. `task` threads this into every step via
+        // the surrounding body context, so `@binding` helpers that need it
+        // (e.g. `Drizzle.postgres`) resolve their per-run resources inside
+        // workflow steps. The same scope is also provided as the ambient
+        // `Scope` service, matching the Worker and Durable Object bridges.
+        const scope = Scope.makeUnsafe();
+        const exit = await Effect.runPromiseExit(
           fn(event.payload).pipe(
-            Effect.provideService(
-              WorkflowEventService,
-              wrapWorkflowEvent(event),
+            Effect.provide(
+              Layer.succeed(
+                WorkflowEventService,
+                wrapWorkflowEvent(event),
+              ).pipe(
+                Layer.provideMerge(
+                  Layer.succeed(WorkflowStep, wrapWorkflowStep(step)),
+                ),
+                Layer.provideMerge(
+                  Layer.succeed(ExecutionContext, { scope, cache: {} }),
+                ),
+                Layer.provideMerge(Layer.succeed(Scope.Scope, scope)),
+              ),
             ),
-            Effect.provideService(WorkflowStep, wrapWorkflowStep(step)),
           ) as Effect.Effect<unknown>,
         );
+        // Settle the run's resources with its real exit, unless a binding
+        // ejected the scope to outlive the invocation. The workflow runtime has
+        // no `waitUntil` to detach cleanup to, so close inline — a failing
+        // finalizer (e.g. a pg pool `end()` on a dropped connection) is logged
+        // and ignored so it can't mask the run's outcome.
+        if (!isScopeEjected(scope)) {
+          await Scope.close(scope, exit).pipe(
+            Effect.ignoreCause({
+              log: "Warn",
+              message: "Workflow run scope close failed",
+            }),
+            Effect.runPromise,
+          );
+        }
+        if (Exit.isSuccess(exit)) {
+          return exit.value;
+        }
+        throw Cause.squash(exit.cause);
       }
     };
 

package/src/Cloudflare/Workers/index.ts

@@ -16,6 +16,8 @@ export * from "./Rpc.ts";
 export * from "./RpcDurableObjectNamespace.ts";
 export * from "./RpcWorker.ts";
 export * from "./ScheduledEvents.ts";
+export * from "./VersionMetadata.ts";
+export * from "./VersionMetadataBinding.ts";
 export * from "./WebSocket.ts";
 export * from "./Worker.ts";
 export * from "./WorkerBinding.ts";

package/src/Cloudflare/Zaraz/ZarazConfig.ts

@@ -194,6 +194,93 @@ export const ZarazConfig = Object.assign(
   },
 );
 
+export const ZarazConfigProvider = () =>
+  Provider.succeed(ZarazConfig, {
+    stables: ["zoneId"],
+    diff: Effect.fn(function* ({ olds, news, output }) {
+      if (!output) return undefined;
+      if (!isResolved(news)) return undefined;
+
+      const zoneId = yield* resolve(news.zone);
+      if (zoneId !== output.zoneId) {
+        return { action: "replace" } as const;
+      }
+
+      const outputConfig = fromAttributes(output);
+      const comparableOutput = configForCompare(outputConfig, olds, news);
+      const desired = desiredConfig(outputConfig, news);
+      const desiredWorkflow = news.workflow ?? output.workflow;
+      if (
+        desiredWorkflow !== output.workflow ||
+        !deepEqual(
+          comparableConfig(comparableOutput),
+          comparableConfig(desired),
+        )
+      ) {
+        return { action: "update" } as const;
+      }
+    }),
+    read: Effect.fn(function* ({ olds, output }) {
+      const zoneId =
+        output?.zoneId ?? (olds ? yield* resolve(olds.zone) : undefined);
+      if (!zoneId) return undefined;
+      return yield* observe(zoneId);
+    }),
+    reconcile: Effect.fn(function* ({ news, output }) {
+      const zoneId = output?.zoneId ?? (yield* resolve(news.zone));
+      const observed = yield* observe(zoneId);
+      const observedConfig = fromAttributes(observed);
+      const desired = desiredConfig(observedConfig, news);
+      const desiredWorkflow = news.workflow ?? observed.workflow;
+
+      const updatedConfig = deepEqual(
+        comparableConfig(observedConfig),
+        comparableConfig(desired),
+      )
+        ? observedConfig
+        : yield* zaraz.putConfig(toPutConfig(zoneId, desired));
+      const updatedWorkflow =
+        desiredWorkflow === observed.workflow
+          ? observed.workflow
+          : yield* zaraz.putZaraz({
+              zoneId,
+              workflow: desiredWorkflow,
+            });
+
+      return toAttributes(zoneId, updatedConfig, updatedWorkflow);
+    }),
+    delete: Effect.fn(function* ({ output, olds }) {
+      if (olds.delete !== true) return;
+      const defaults = yield* zaraz.getDefault({ zoneId: output.zoneId });
+      yield* zaraz.putConfig(toPutConfig(output.zoneId, defaults));
+      if (olds.workflow !== undefined) {
+        yield* zaraz.putZaraz({
+          zoneId: output.zoneId,
+          workflow: "realtime",
+        });
+      }
+    }),
+  });
+
+const resolve = Effect.fnUntraced(function* (zone: ZoneReference) {
+  const { accountId } = yield* yield* CloudflareEnvironment;
+  return yield* resolveZoneId({
+    accountId,
+    zone,
+    hostname: typeof zone === "string" ? zone : (zone.name ?? ""),
+  });
+});
+
+const observe = (zoneId: string) =>
+  Effect.all({
+    config: zaraz.getConfig({ zoneId }),
+    workflow: zaraz.getWorkflow({ zoneId }),
+  }).pipe(
+    Effect.map(({ config, workflow }) =>
+      toAttributes(zoneId, config, workflow),
+    ),
+  );
+
 type ConfigResponse =
   | zaraz.GetConfigResponse
   | zaraz.PutConfigResponse
@@ -302,102 +389,3 @@ const configForCompare = (
     variables: props.variables,
   };
 };
-
-export const ZarazConfigProvider = () =>
-  Provider.effect(
-    ZarazConfig,
-    Effect.gen(function* () {
-      const { accountId } = yield* CloudflareEnvironment;
-      const getConfig = yield* zaraz.getConfig;
-      const putConfig = yield* zaraz.putConfig;
-      const getDefault = yield* zaraz.getDefault;
-      const getWorkflow = yield* zaraz.getWorkflow;
-      // Cloudflare's OpenAPI operation name is `putZaraz`, but the endpoint
-      // updates the zone's Zaraz workflow mode.
-      const putWorkflow = yield* zaraz.putZaraz;
-
-      const resolve = (zone: ZoneReference) =>
-        resolveZoneId({
-          accountId,
-          zone,
-          hostname: typeof zone === "string" ? zone : (zone.name ?? ""),
-        });
-
-      const observe = (zoneId: string) =>
-        Effect.all({
-          config: getConfig({ zoneId }),
-          workflow: getWorkflow({ zoneId }),
-        }).pipe(
-          Effect.map(({ config, workflow }) =>
-            toAttributes(zoneId, config, workflow),
-          ),
-        );
-
-      return {
-        stables: ["zoneId"],
-        diff: Effect.fn(function* ({ olds, news, output }) {
-          if (!output) return undefined;
-          if (!isResolved(news)) return undefined;
-
-          const zoneId = yield* resolve(news.zone);
-          if (zoneId !== output.zoneId) {
-            return { action: "replace" } as const;
-          }
-
-          const outputConfig = fromAttributes(output);
-          const comparableOutput = configForCompare(outputConfig, olds, news);
-          const desired = desiredConfig(outputConfig, news);
-          const desiredWorkflow = news.workflow ?? output.workflow;
-          if (
-            desiredWorkflow !== output.workflow ||
-            !deepEqual(
-              comparableConfig(comparableOutput),
-              comparableConfig(desired),
-            )
-          ) {
-            return { action: "update" } as const;
-          }
-        }),
-        read: Effect.fn(function* ({ olds, output }) {
-          const zoneId =
-            output?.zoneId ?? (olds ? yield* resolve(olds.zone) : undefined);
-          if (!zoneId) return undefined;
-          return yield* observe(zoneId);
-        }),
-        reconcile: Effect.fn(function* ({ news, output }) {
-          const zoneId = output?.zoneId ?? (yield* resolve(news.zone));
-          const observed = yield* observe(zoneId);
-          const observedConfig = fromAttributes(observed);
-          const desired = desiredConfig(observedConfig, news);
-          const desiredWorkflow = news.workflow ?? observed.workflow;
-
-          const updatedConfig = deepEqual(
-            comparableConfig(observedConfig),
-            comparableConfig(desired),
-          )
-            ? observedConfig
-            : yield* putConfig(toPutConfig(zoneId, desired));
-          const updatedWorkflow =
-            desiredWorkflow === observed.workflow
-              ? observed.workflow
-              : yield* putWorkflow({
-                  zoneId,
-                  workflow: desiredWorkflow,
-                });
-
-          return toAttributes(zoneId, updatedConfig, updatedWorkflow);
-        }),
-        delete: Effect.fn(function* ({ output, olds }) {
-          if (olds.delete !== true) return;
-          const defaults = yield* getDefault({ zoneId: output.zoneId });
-          yield* putConfig(toPutConfig(output.zoneId, defaults));
-          if (olds.workflow !== undefined) {
-            yield* putWorkflow({
-              zoneId: output.zoneId,
-              workflow: "realtime",
-            });
-          }
-        }),
-      };
-    }),
-  );

package/src/Cloudflare/Zone/Zone.ts

@@ -193,11 +193,10 @@ export const ZoneProvider = () =>
   Provider.effect(
     Zone,
     Effect.gen(function* () {
-      const { accountId } = yield* CloudflareEnvironment;
-      const get = yield* zones.getZone;
-      const create = yield* zones.createZone;
-      const patch = yield* zones.patchZone;
-      const del = yield* zones.deleteZone;
+      // const get = yield* zones.getZone;
+      // const create = yield* zones.createZone;
+      // const patch = yield* zones.patchZone;
+      // const del = yield* zones.deleteZone;
 
       return {
         stables: ["name", "zoneId", "accountId"],
@@ -220,12 +219,13 @@ export const ZoneProvider = () =>
           return undefined;
         }),
         read: Effect.fn(function* ({ output, olds }) {
+          const { accountId } = yield* yield* CloudflareEnvironment;
           const name = output?.name ?? olds?.name;
           // Owned path: we have persisted state (our own zoneId) — refresh it.
           if (output?.zoneId) {
-            const result = yield* get({ zoneId: output.zoneId }).pipe(
-              Effect.catch(() => Effect.succeed(undefined)),
-            );
+            const result = yield* zones
+              .getZone({ zoneId: output.zoneId })
+              .pipe(Effect.catch(() => Effect.succeed(undefined)));
             if (result) return toZoneAttributes(result, accountId);
           }
           // Adoption path: no state of our own, but a zone with this name
@@ -236,12 +236,13 @@ export const ZoneProvider = () =>
           if (name) {
             const match = yield* findZoneByName({ accountId, name });
             if (!match) return undefined;
-            const result = yield* get({ zoneId: match.id });
+            const result = yield* zones.getZone({ zoneId: match.id });
             return Unowned(toZoneAttributes(result, accountId));
           }
           return undefined;
         }),
         reconcile: Effect.fn(function* ({ news, output }) {
+          const { accountId } = yield* yield* CloudflareEnvironment;
           // 1. Observe — do we have a live zone for this name?
           let zoneId = output?.zoneId;
           if (!zoneId) {
@@ -254,33 +255,35 @@ export const ZoneProvider = () =>
 
           // 2. Ensure — create if missing.
           if (!zoneId) {
-            zoneId = yield* create({
-              account: { id: accountId },
-              name: news.name,
-              type: news.type ?? "full",
-            }).pipe(
-              Effect.map((created) => created.id),
-              // A concurrent deploy (or a prior crashed run) may have created
-              // the zone between our observe and create — recover by resolving
-              // its id rather than failing the reconcile.
-              Effect.catchTag("ZoneAlreadyExists", () =>
-                findZoneByName({ accountId, name: news.name }).pipe(
-                  Effect.flatMap((match) =>
-                    match
-                      ? Effect.succeed(match.id)
-                      : Effect.fail(
-                          new Error(
-                            `Cloudflare reported zone ${news.name} already exists but it could not be found`,
+            zoneId = yield* zones
+              .createZone({
+                account: { id: accountId },
+                name: news.name,
+                type: news.type ?? "full",
+              })
+              .pipe(
+                Effect.map((created) => created.id),
+                // A concurrent deploy (or a prior crashed run) may have created
+                // the zone between our observe and create — recover by resolving
+                // its id rather than failing the reconcile.
+                Effect.catchTag("ZoneAlreadyExists", () =>
+                  findZoneByName({ accountId, name: news.name }).pipe(
+                    Effect.flatMap((match) =>
+                      match
+                        ? Effect.succeed(match.id)
+                        : Effect.fail(
+                            new Error(
+                              `Cloudflare reported zone ${news.name} already exists but it could not be found`,
+                            ),
                           ),
-                        ),
+                    ),
                   ),
                 ),
-              ),
-            );
+              );
           }
 
           // 3. Sync — apply mutable settings (type/paused/vanity NS).
-          const observed = yield* get({ zoneId });
+          const observed = yield* zones.getZone({ zoneId });
           const desiredType = news.type ?? "full";
           const desiredPaused = news.paused ?? false;
           const desiredVanity = news.vanityNameServers ?? [];
@@ -290,7 +293,7 @@ export const ZoneProvider = () =>
             !stringArrayEq(observed.vanityNameServers ?? [], desiredVanity);
 
           if (needsPatch) {
-            yield* patch({
+            yield* zones.patchZone({
               zoneId,
               type: desiredType,
               paused: desiredPaused,
@@ -298,12 +301,12 @@ export const ZoneProvider = () =>
             });
           }
 
-          const final = yield* get({ zoneId });
+          const final = yield* zones.getZone({ zoneId });
           return toZoneAttributes(final, accountId);
         }),
         delete: Effect.fn(function* ({ output }) {
           if (!output.zoneId) return;
-          yield* del({ zoneId: output.zoneId }).pipe(
+          yield* zones.deleteZone({ zoneId: output.zoneId }).pipe(
             // Zone already gone — idempotent delete.
             Effect.catchTag("InvalidZoneIdentifier", () => Effect.void),
           );

package/src/Diff.ts

@@ -1,4 +1,5 @@
 import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
 import type { Input } from "./Input.ts";
 import * as Output from "./Output.ts";
 import type { BindingNode } from "./Plan.ts";
@@ -119,6 +120,12 @@ export const deepEqual = (
 
 const canonicalize = (value: unknown, stripNullish: boolean): unknown => {
   if (stripNullish && value == null) return undefined;
+  if (Redacted.isRedacted(value)) {
+    return {
+      _tag: "Redacted",
+      value: Redacted.value(value),
+    };
+  }
   if (Array.isArray(value)) {
     return value.map((v) => canonicalize(v, stripNullish));
   }

package/src/Drizzle/Postgres.ts

@@ -25,19 +25,20 @@ import { proxyChain } from "../Util/proxy-chain.ts";
  * });
  * ```
  *
- * Behind the scenes the actual connect work is wrapped in `Effect.cached`,
- * so the pool is built at most once per JS realm. Yielding the
- * connection string is also deferred until first query, so deploy /
- * plan-time invocations (where `WorkerEnvironment` isn't provided)
- * never trigger a real connection attempt.
+ * The connect work is deferred until the first query and memoized on the
+ * current `ExecutionContext` (`ctx.cache`), so the pool is built at most
+ * once per execution — a Worker `fetch`/`queue`/`scheduled` event or a
+ * Workflow run — and reused across every query and `task` step in that
+ * execution. Yielding the connection string is likewise deferred, so
+ * deploy / plan-time invocations (where `WorkerEnvironment` isn't
+ * provided) never trigger a real connection attempt.
  *
- * The PgClient pool is built against an isolated, never-closing `Scope`
- * so it outlives whatever scope this helper is yielded under. In a
- * Cloudflare Worker the surrounding `Cloudflare.Worker` runs init
- * inside `Effect.scoped`, which closes after returning the exports
- * object — without an isolated scope, the pool's `end` finalizer
- * would fire there and every subsequent request would see "Cannot
- * use a pool after end".
+ * The pool is built against the execution's `Scope` (`ctx.scope`), so its
+ * `end` finalizer fires when that scope closes — when the request / run
+ * settles, not when the `Cloudflare.Worker` init scope closes. Init runs
+ * inside `Effect.scoped` and closes after returning the exports object;
+ * building lazily against `ctx.scope` (rather than that init scope) is
+ * what keeps later requests from seeing "Cannot use a pool after end".
  *
  * @binding
  */