alchemy 2.0.0-beta.76 → 2.0.0-beta.78

package/lib/Cloudflare/Workers/Worker.d.ts

@@ -1,8 +1,6 @@
-import type * as cf from "@cloudflare/workers-types";
 import * as workers from "@distilled.cloud/cloudflare/workers";
 import type * as Config from "effect/Config";
 import type { ConfigError } from "effect/Config";
-import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import type * as Layer from "effect/Layer";
 import * as Redacted from "effect/Redacted";
@@ -12,7 +10,7 @@ import type { InputProps } from "../../Input.ts";
 import type { Named, Tag } from "../../Named.ts";
 import type * as Output from "../../Output.ts";
 import { type Main, type MainRpc, type MakeShape, type PlatformProps, type PlatformServices } from "../../Platform.ts";
-import { Resource, type ResourceClassLike } from "../../Resource.ts";
+import { Resource, type ResourceClass, type ResourceClassLike } from "../../Resource.ts";
 import type { Rpc } from "../../Rpc.ts";
 import type { RuntimeContext } from "../../RuntimeContext.ts";
 import type { Self as SelfService } from "../../Self.ts";
@@ -25,88 +23,16 @@ import type { DispatchNamespace } from "../WorkersForPlatforms/DispatchNamespace
 import type { WorkflowExport } from "../Workflows/Workflow.ts";
 import type { Reference as ZoneReference } from "../Zone/lookup.ts";
 import { type Assets, type AssetsProps } from "./Assets.ts";
-import { type WorkerAccessConfig, type WorkerAccessIdentity, type WorkerExecutionContextAccess } from "./WorkerAccess.ts";
+import type { WorkerAccessConfig, WorkerAccessIdentity } from "./WorkerAccess.ts";
+import { WorkerEnvironment, WorkerExecutionContext, WorkerTypeId } from "./WorkerRuntime.ts";
 import { type DurableObjectExport } from "./DurableObject.ts";
 import { Request } from "./Request.ts";
 import type { ModuleRule } from "./Sources/Prebuilt.ts";
 import type { WorkerBuildOptions } from "./Sources/Rolldown.ts";
 import type { WorkerBinding, WorkerBindingResource } from "./WorkerBinding.ts";
 import { type WorkerRuntimeContext } from "./WorkerRuntimeContext.ts";
-export declare const WorkerTypeId = "Cloudflare.Worker";
-export type WorkerTypeId = typeof WorkerTypeId;
+export * from "./WorkerRuntime.ts";
 export declare const isWorker: <T>(value: T) => value is T & Worker;
-declare const WorkerEnvironment_base: Context.ServiceClass<WorkerEnvironment, "Cloudflare.Workers.WorkerEnvironment", Record<string, any>>;
-export declare class WorkerEnvironment extends WorkerEnvironment_base {
-}
-declare const CachePurgeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "CachePurgeError";
-} & Readonly<A>;
-export declare class CachePurgeError extends CachePurgeError_base<{
-    message: string;
-    cause?: unknown;
-}> {
-}
-/**
- * Effect-native view of the Workers Cache runtime API on the execution
- * context (`ctx.cache`). Only available when the Worker has Workers Cache
- * enabled (the `cache` prop or `yield* Cloudflare.cache()`).
- */
-export interface WorkerExecutionContextCache {
-    /**
-     * Purge cached responses by `Cache-Tag`, path prefix, or everything.
-     */
-    purge(options: cf.CachePurgeOptions): Effect.Effect<cf.CachePurgeResult, CachePurgeError, RuntimeContext>;
-}
-declare const WorkerExecutionContext_base: Context.ServiceClass<WorkerExecutionContext, "Cloudflare.Workers.WorkerExecutionContext", {
-    /**
-     * Run an Effect in the background without blocking the response, keeping
-     * the Worker alive until it settles. The Effect runs with the caller's
-     * full context (services, tracing), and the resulting promise is
-     * registered with workerd's `ctx.waitUntil`.
-     */
-    waitUntil<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<void, never, R | RuntimeContext>;
-    /**
-     * Forward the request to the origin if the Worker throws an unhandled
-     * exception, instead of returning an error page.
-     */
-    passThroughOnException(): Effect.Effect<void, never, RuntimeContext>;
-    /**
-     * The Workers Cache runtime API (`ctx.cache`).
-     */
-    readonly cache: WorkerExecutionContextCache;
-    /**
-     * The Cloudflare Access context for the current request (`ctx.access`),
-     * or `undefined` when the request did not pass through Access. Under
-     * `alchemy dev` the Worker's `dev.access` config simulates it.
-     */
-    readonly access: Effect.Effect<WorkerExecutionContextAccess | undefined, never, RuntimeContext>;
-    /**
-     * The raw workerd ExecutionContext, for interop with async APIs.
-     */
-    readonly raw: cf.ExecutionContext;
-}>;
-export declare class WorkerExecutionContext extends WorkerExecutionContext_base {
-}
-export declare const fromExecutionContext: (ctx: cf.ExecutionContext, env?: Record<string, unknown>) => WorkerExecutionContext["Service"];
-/**
- * A {@link WorkerExecutionContext} whose methods resolve the live per-event
- * context from the calling fiber at call time. Provided during the Worker's
- * init phase (plan and runtime module init) so the service can be yielded
- * and closed over in the top-level closure; every method is colored with
- * `RuntimeContext`, so it can only be *run* inside a handler, where the
- * bridge provides the real per-event context that these methods defer to.
- */
-export declare const deferredExecutionContext: WorkerExecutionContext["Service"];
-export type WorkerEvent = Exclude<{
-    [type in keyof cf.ExportedHandler]: {
-        kind: "Cloudflare.Workers.WorkerEvent";
-        type: type;
-        input: Parameters<Exclude<cf.ExportedHandler[type], undefined>>[0];
-        env: Parameters<Exclude<cf.ExportedHandler[type], undefined>>[1];
-        context: Parameters<Exclude<cf.ExportedHandler[type], undefined>>[2];
-    };
-}[keyof cf.ExportedHandler], undefined>;
-export declare const isWorkerEvent: (value: any) => value is WorkerEvent;
 /**
  * Assets configuration that includes a pre-computed hash.
  * When hash is provided, it's used directly for diffing instead of computing from directory contents.
@@ -126,7 +52,6 @@ export interface WorkerLimits extends Exclude<workers.PutScriptRequest["metadata
 export interface WorkerCache extends Exclude<workers.PutScriptRequest["metadata"]["cacheOptions"], undefined> {
 }
 export type WorkerPlacement = Exclude<workers.PutScriptRequest["metadata"]["placement"], undefined>;
-export declare const ExportedHandlerMethods: ["fetch", "tail", "trace", "tailStream", "scheduled", "test", "email", "queue"];
 export type WorkerServices = Worker | Request | WorkerExecutionContext | WorkerEnvironment | CloudflareEnvironment | Container.Application<any> | SelfService;
 export type WorkerShape<Req = never> = Main<WorkerServices | Req> & MainRpc<WorkerServices | Req>;
 export type WorkerEnv = Record<string, string | number | boolean | null | readonly unknown[] | {
@@ -214,6 +139,22 @@ export interface WorkerDomainConfig {
      * Alternative to {@link zoneId} / {@link zoneName}.
      */
     zone?: ZoneReference;
+    /**
+     * Opt into custom-domain Worker Previews (private beta). When `true`,
+     * Previews of this Worker are served at `<preview-name>.<name>` (and a
+     * pinned `<deployment-id>-<preview-name>.<name>` per deploy). Cloudflare
+     * provisions a wildcard DNS record and certificate. Equivalent to
+     * Wrangler's `previews_enabled` on a custom-domain route.
+     *
+     * Unset, the field is not sent to Cloudflare — existing custom-domain
+     * attaches are unchanged. This is a **parent** setting: enable it on
+     * the production Worker, not on the Preview Worker. A dedicated Preview
+     * hostname (`previews.example.com`) avoids colliding with existing
+     * subdomains.
+     *
+     * @default false
+     */
+    previews?: boolean;
 }
 export interface WorkerRouteConfig {
     /**
@@ -414,6 +355,61 @@ export interface WorkerVersionOptions {
      */
     tag?: string;
 }
+/**
+ * Worker Preview configuration — uploads this Worker as a first-class
+ * [Preview](https://developers.cloudflare.com/workers/previews/) of
+ * another Worker's script instead of creating a script of its own.
+ *
+ * Distinct from {@link WorkerVersionOptions}: a version is an immutable
+ * upload onto the parent script (gradual rollouts, canaries, Version
+ * URLs). A Preview is a named copy with its own variables, secrets,
+ * bindings, and isolated same-Worker Durable Object / Container state.
+ * Cloudflare recommends Previews for branch and pull-request testing.
+ *
+ * Mutually exclusive with {@link WorkerVersionOptions.parent}.
+ */
+export interface WorkerPreviewOptions {
+    /**
+     * The Worker this Preview belongs to. Accepts a Worker reference —
+     * typically `yield* Cloudflare.Worker.ref(id, { stage, stack })` for
+     * a Worker deployed in another stage/stack, or a locally-declared
+     * Worker — or a literal script name as an escape hatch.
+     *
+     * When set, this resource does not create a script of its own: it
+     * creates (or updates) a Preview of the parent's script and deploys
+     * this Worker's code, assets, and bindings to it. Script-level
+     * settings that belong to the parent — `name`, `namespace`, `crons`,
+     * `domain`, `routes`, `workersDev`, `access` — cannot be set on a
+     * Preview Worker. Locally-hosted Durable Object and Workflow classes
+     * *are* allowed: each Preview gets its own isolated namespace.
+     *
+     * Changing the parent replaces the resource (a Preview belongs to
+     * exactly one script).
+     */
+    of: string | Worker;
+    /**
+     * Preview name. Defaults to a DNS-safe form of the stack stage
+     * (`pr-123`, `feat-login`). Appears in Preview URLs:
+     * `https://<name>-<worker>.<subdomain>.workers.dev` and, when the
+     * parent has {@link WorkerDomainConfig.previews} enabled,
+     * `https://<name>.<domain>`.
+     *
+     * Must start with a lowercase letter, contain only lowercase letters,
+     * digits, and dashes, and `<name>-<worker-name>` must fit in 63
+     * characters (a DNS label).
+     */
+    name?: string;
+    /**
+     * Human-readable annotation attached to the Preview deployment,
+     * shown in the Cloudflare dashboard.
+     */
+    message?: string;
+    /**
+     * Machine-readable tag annotation attached to the Preview deployment
+     * (e.g. a git commit SHA or PR number).
+     */
+    tag?: string;
+}
 export interface WorkerProps<Bindings = any, Assets extends WorkerAssetsConfig | undefined = WorkerAssetsConfig | undefined> extends PlatformProps {
     /**
      * Worker name override. If omitted, Alchemy derives a deterministic physical
@@ -443,12 +439,23 @@ export interface WorkerProps<Bindings = any, Assets extends WorkerAssetsConfig |
     namespace?: string | DispatchNamespace;
     /**
      * Worker versions & gradual deployments. Set `version.parent` to upload
-     * this Worker as a preview/canary *version* of another Worker's script
+     * this Worker as a canary *version* of another Worker's script
      * instead of creating its own; set `version.traffic` below 100 to
-     * gradually roll out a deploy of this Worker's own script. See
+     * gradually roll out a deploy of this Worker's own script. For branch
+     * and pull-request testing, use {@link preview} instead. See
      * {@link WorkerVersionOptions}.
      */
     version?: WorkerVersionOptions;
+    /**
+     * Opt into Cloudflare's [Worker Previews](https://developers.cloudflare.com/workers/previews/)
+     * (private beta). Unset, this Worker deploys as a normal script and none
+     * of the Preview APIs are called. Set `preview.of` to upload this Worker
+     * as a Preview of another Worker's script instead: own URL, bindings,
+     * and isolated Durable Object state; the parent's live deployment is
+     * untouched. Mutually exclusive with {@link version.parent}. See
+     * {@link WorkerPreviewOptions}.
+     */
+    preview?: WorkerPreviewOptions;
     /**
      * Controls the Worker's `workers.dev` surface.
      *
@@ -609,8 +616,8 @@ export interface WorkerProps<Bindings = any, Assets extends WorkerAssetsConfig |
      * - Resource references (R2 bucket, KV namespace, D1 database,
      *   another Worker, Durable Object, etc.) — emitted as the
      *   corresponding native binding.
-     * - `effect/Config` values (`Config.redacted`, `Config.string`,
-     *   `Config.number`, …) — resolved at deploy time and bound as
+     * - `effect/Config` values (`Config.Redacted`, `Config.String`,
+     *   `Config.Number`, …) — resolved at deploy time and bound as
      *   `secret_text` on Cloudflare regardless of the `Config`
      *   constructor used. See
      *   [Secrets & env](/cloudflare/security/secrets-env).
@@ -994,6 +1001,7 @@ export type Worker<Bindings = any> = Resource<WorkerTypeId, WorkerProps<Bindings
         aliases: string[];
         redirects: string[];
         zone?: ZoneReference;
+        previews?: boolean;
     } | undefined;
     tags: string[] | undefined;
     durableObjectNamespaces: Record<string, string>;
@@ -1033,6 +1041,34 @@ export type Worker<Bindings = any> = Resource<WorkerTypeId, WorkerProps<Bindings
      * avoid treating the parent's script as this resource's own.
      */
     versionOf?: string | undefined;
+    /**
+     * The parent script name this Worker is a Preview of, when this
+     * resource is a Preview Worker (`preview.of` set). `undefined` for
+     * a Worker that owns its own script. Discriminator `read`/`delete`
+     * use so they never treat the parent's script as this resource's own.
+     */
+    previewOf?: string | undefined;
+    /**
+     * Cloudflare's immutable Preview id. Set when this resource is a
+     * Preview Worker (`preview.of`).
+     */
+    previewId?: string | undefined;
+    /**
+     * The Preview name as created — the user-provided `preview.name`, or
+     * the auto-derived name from the stack stage.
+     */
+    previewName?: string | undefined;
+    /**
+     * DNS-safe slug Cloudflare assigned to this Preview. Used in Preview
+     * URLs (`<slug>-<worker>.<subdomain>.workers.dev` and
+     * `<slug>.<domain>` when the parent has custom-domain Previews).
+     */
+    previewSlug?: string | undefined;
+    /**
+     * Same-Worker Durable Object class names hosted on the last Preview
+     * deploy — the baseline for the next Preview's class migrations.
+     */
+    previewDoClasses?: string[] | undefined;
     /**
      * The id of the version uploaded by the most recent deploy. Only set
      * when versioning is in play: always for a version worker
@@ -1072,12 +1108,27 @@ export type Worker<Bindings = any> = Resource<WorkerTypeId, WorkerProps<Bindings
     };
 }, {
     bindings?: WorkerBinding[];
+    /**
+     * Extra env vars merged into the Worker at reconcile. `Redacted`
+     * values deploy as `secret_text`. Used by later resources (e.g. a
+     * Stripe webhook signing secret) to attach env without the Worker
+     * init depending on that resource.
+     */
+    env?: Record<string, any>;
     /**
      * Workers Cache settings contributed by `yield* Cloudflare.cache()`.
      * Merged into the upload metadata's `cache_options`; an explicit
      * `WorkerProps.cache` takes precedence.
      */
     cache?: WorkerCache;
+    /**
+     * Workers Observability traces settings contributed by
+     * `Cloudflare.Telemetry()`. Deep-merged into upload metadata: bound
+     * traces fill in when `WorkerProps.observability.traces` is omitted,
+     * and never clobber the default logs config. An explicit
+     * `observability.traces` object wins.
+     */
+    observability?: Pick<WorkerObservability, "traces">;
     containers?: {
         className: string;
         dev: DevContainerImage | undefined;
@@ -1185,11 +1236,11 @@ export declare const isSelf: (value: unknown) => value is Self;
  *
  * ```typescript
  * Effect.gen(function* () {
- *   // Phase 1: bind resources (runs at deploy time)
+ *   // Construction: bind resources (deploy time and cold start)
  *   const kv = yield* Cloudflare.KV.ReadWriteNamespace(MyKV);
  *
  *   return {
- *     // Phase 2: runtime handlers (runs on each request)
+ *     // Runtime: handlers, once per request
  *     fetch: Effect.gen(function* () {
  *       const value = yield* kv.get("key");
  *       return HttpServerResponse.text(value ?? "not found");
@@ -1199,7 +1250,7 @@ export declare const isSelf: (value: unknown) => value is Self;
  * ```
  *
  * There are three ways to define a Worker, from simplest to most
- * flexible. See the [Functions & Servers](/infrastructure-as-effects/functions-and-servers)
+ * flexible. See the [Runtime](/infrastructure-as-effects/runtime)
  * page for the full explanation.
  *
  * - **Async** — plain `async fetch` handler, no Effect runtime in the bundle.
@@ -1306,6 +1357,37 @@ export declare const isSelf: (value: unknown) => value is Self;
  * };
  * ```
  *
+ * **Example:** Binding a named entrypoint
+ *
+ * `env: { TARGET: worker }` targets the Worker's default entrypoint.
+ * `Cloudflare.WorkerEntrypoint` binds one of its named
+ * `WorkerEntrypoint` class exports instead; `InferEnv` types the entry
+ * as a `Fetcher` stub whose RPC methods are called directly.
+ * ```typescript
+ * const caller = yield* Cloudflare.Worker("Caller", {
+ *   main: "./src/caller.ts",
+ *   env: {
+ *     API: Cloudflare.WorkerEntrypoint(target, "Api"), // env.API.greet("alice")
+ *   },
+ * });
+ * ```
+ *
+ * **Example:** Entrypoint props
+ *
+ * The options form attaches properties the target entrypoint reads from
+ * `this.ctx.props`. `Output` values resolve at deploy time. `alchemy dev`
+ * delivers `props` to the local workerd; the deploy API's binding schema
+ * does not carry the field yet, so `props` are dropped at upload while the
+ * binding itself deploys correctly.
+ * ```typescript
+ * env: {
+ *   VENDOR: Cloudflare.WorkerEntrypoint(vendorWorker, {
+ *     entrypoint: "Vendor",
+ *     props: { baseUrl: site.url },
+ *   }),
+ * }
+ * ```
+ *
  * ### Python Workers
  * Point `main` at a `.py` file to deploy a
  * [Python Worker](https://developers.cloudflare.com/workers/languages/python/)
@@ -1369,11 +1451,11 @@ export declare const isSelf: (value: unknown) => value is Self;
  *   "MyWorker",
  *   { main: import.meta.url },
  *   Effect.gen(function* () {
- *     // init: bind resources
+ *     // Construction: bind resources
  *     const kv = yield* Cloudflare.KV.ReadWriteNamespace(MyKV);
  *
  *     return {
- *       // runtime: use them
+ *       // Runtime: use them
  *       fetch: Effect.gen(function* () {
  *         const value = yield* kv.get("key");
  *         return HttpServerResponse.text(value ?? "not found");
@@ -1409,11 +1491,11 @@ export declare const isSelf: (value: unknown) => value is Self;
  * export default WorkerB.make(
  *   { main: import.meta.url },
  *   Effect.gen(function* () {
- *     // init: bind resources
+ *     // Construction: bind resources
  *     const kv = yield* Cloudflare.KV.ReadWriteNamespace(MyKV);
  *
  *     return {
- *       // runtime: use them
+ *       // Runtime: use them
  *       greet: (name: string) =>
  *         Effect.gen(function* () {
  *           yield* kv.put("last-greeted", name);
@@ -1453,7 +1535,7 @@ export declare const isSelf: (value: unknown) => value is Self;
  *   main: import.meta.url,
  *   compatibility: {
  *     flags: ["nodejs_compat"],
- *     date: "2026-03-17",
+ *     date: "2026-08-31",
  *   },
  * }
  * ```
@@ -1466,6 +1548,25 @@ export declare const isSelf: (value: unknown) => value is Self;
  * }
  * ```
  *
+ * **Example:** Run the Worker before the asset layer
+ *
+ * A path that matches no asset already falls through to the Worker.
+ * `runWorkerFirst` routes the listed paths (or, with `true`, every
+ * request) through the Worker ahead of asset matching, for an asset
+ * that would otherwise shadow a route or an SPA fallback that would
+ * answer an API call. A `_headers` or `_redirects` file in the
+ * directory is applied automatically and `.assetsignore` excludes
+ * files from the upload.
+ * ```typescript
+ * {
+ *   main: import.meta.url,
+ *   assets: {
+ *     directory: "./public",
+ *     runWorkerFirst: ["/api/*", "/admin/*"],
+ *   },
+ * }
+ * ```
+ *
  * **Example:** Assets-only Worker (static site)
  * Omit `main` and `script` entirely to deploy a static site: no Worker
  * code is uploaded — Cloudflare's asset layer serves every request and
@@ -1509,17 +1610,13 @@ export declare const isSelf: (value: unknown) => value is Self;
  * ```
  *
  * ### Bundling & Tree-shaking
- * `main` is bundled with rolldown at deploy time. Top-level calls in the
- * `effect`, `@effect/*`, `alchemy`, `@alchemy.run/*`, and
- * `@distilled.cloud/*` packages receive `#__PURE__` annotations by
- * default, so anything the Worker doesn't use from those packages is
- * tree-shaken out of the bundle. Any other
- * package — including your own app — is left untouched unless you list
- * it explicitly.
- *
- * **Example:** Treat additional packages as pure
- * Pass package names (or picomatch globs) via `build.pure.packages` to
- * annotate them in addition to the defaults.
+ * `main` is bundled with rolldown at deploy time. Unused code is
+ * tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
+ * pure so unused parts prune more aggressively. Your app is not
+ * marked pure.
+ *
+ * **Example:** Mark additional packages as pure
+ * Only list packages with no top-level side effects.
  * ```typescript
  * {
  *   main: "./src/worker.ts",
@@ -1529,18 +1626,7 @@ export declare const isSelf: (value: unknown) => value is Self;
  * }
  * ```
  *
- * Listing a package annotates calls whose result is bound (variable
- * initializers, exports) — safe anywhere. If a listed package also
- * declares `"sideEffects": false` (or `[]`) in its `package.json`, that
- * combination opts it into full annotation: top-level calls whose result
- * is discarded (e.g. `router.on("/path", handler)` registrations) are
- * also marked pure and deleted under minification when unused. Only list
- * a `sideEffects: false` package if its modules really are free of
- * meaningful top-level side effects. The `effect`, `alchemy`, and
- * `@distilled.cloud` defaults declare exactly that, on purpose — their
- * modules are designed to be fully tree-shakeable.
- *
- * **Example:** Disable pure annotations
+ * **Example:** Turn it off
  * ```typescript
  * {
  *   main: "./src/worker.ts",
@@ -1599,15 +1685,49 @@ export declare const isSelf: (value: unknown) => value is Self;
  * });
  * ```
  *
+ * ### Worker Previews
+ * The `preview` prop maps Cloudflare's
+ * [Worker Previews](https://developers.cloudflare.com/workers/previews/) —
+ * a named copy of a Worker with its own URL, variables, secrets, bindings,
+ * and isolated same-Worker Durable Object state. Use it for branch and
+ * pull-request testing. Distinct from {@link version}: a version is an
+ * immutable upload onto the parent script (gradual rollouts, canaries);
+ * a Preview does not take production traffic.
+ *
+ * A Preview Worker's `url` is its stable Preview URL
+ * (`<name>-<parent>.<subdomain>.workers.dev`, or
+ * `<name>.<domain>` when the parent has `domain.previews`). The name
+ * defaults to the stack stage (override with `preview.name`). Destroying
+ * the Preview Worker deletes the Preview; the parent is untouched.
+ *
+ * **Example:** PR preview of another stage's Worker
+ * ```typescript
+ * const parent = yield* Cloudflare.Worker.ref("Api", { stage: "prod" });
+ * const preview = yield* Cloudflare.Worker("Api", {
+ *   main: "./src/api.ts",
+ *   preview: { of: parent, message: `PR #${process.env.PR_NUMBER}` },
+ * });
+ * // preview.url -> https://<stage>-<name>.<subdomain>.workers.dev
+ * ```
+ *
+ * **Example:** Custom-domain Preview URLs
+ * ```typescript
+ * // On the production Worker:
+ * yield* Cloudflare.Worker("Api", {
+ *   main: "./src/api.ts",
+ *   domain: { name: "app.example.com", previews: true },
+ * });
+ * // A Preview of that Worker is then at https://<preview-name>.app.example.com
+ * ```
+ *
  * ### Versions & Gradual Deployments
  * The `version` prop maps Cloudflare's
  * [versions and gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/)
  * onto Alchemy stages. A Worker with `version.parent` set uploads an
  * immutable *version* to the parent Worker's script instead of creating its
- * own — by default with no traffic, reachable only at its preview URL
- * (`worker.url`), which is the PR-preview workflow. Give it `traffic` to
- * run it as a canary, or use `version.traffic` on a normal Worker to roll
- * out its own deploys gradually.
+ * own — give it `traffic` to run it as a canary, or use `version.traffic`
+ * on a normal Worker to roll out its own deploys gradually. For branch
+ * and pull-request testing, use {@link preview} instead.
  *
  * A version worker's `url` is its *aliased* preview URL
  * (`<alias>-<name>.<subdomain>.workers.dev`) — the alias is derived from
@@ -1623,20 +1743,14 @@ export declare const isSelf: (value: unknown) => value is Self;
  * as are locally-hosted Durable Object or Workflow classes. Preview URLs
  * require the parent's workers.dev subdomain to be enabled (the default).
  *
- * **Example:** PR preview: a version of another stage's Worker
+ * **Example:** Upload a version without routing traffic
  * ```typescript
- * // The staging stage deploys the real Worker; a PR stage uploads its
- * // code as a zero-traffic version of staging's script and gets back a
- * // stable preview URL.
- * const parent = yield* Cloudflare.Worker.ref("MyWorker", {
- *   stage: "staging",
- * });
- * const preview = yield* Cloudflare.Worker("MyWorker", {
+ * // Inspect this upload at its Version URL before a gradual rollout.
+ * // For branch/PR testing, use `preview.of` instead.
+ * yield* Cloudflare.Worker("MyWorker", {
  *   main: "./src/worker.ts",
- *   version: { parent, message: `PR #${process.env.PR_NUMBER}` },
+ *   version: { traffic: 0, tag: process.env.GITHUB_SHA },
  * });
- * // preview.url -> https://<alias>-<name>.<subdomain>.workers.dev
- * // (stable across deploys; re-points at each newly uploaded version)
  * ```
  *
  * **Example:** Canary: send 10% of the parent's traffic to a version
@@ -1692,10 +1806,10 @@ export declare const isSelf: (value: unknown) => value is Self;
  *     return {
  *       fetch: Effect.gen(function* () {
  *         const publicUrl = yield* url;
- *         return Response.json({ url: publicUrl });
+ *         return yield* HttpServerResponse.json({ url: publicUrl });
  *       }),
  *     };
- *   }).pipe(Effect.provide(Cloudflare.Workers.URLBinding)),
+ *   }),
  * );
  * ```
  *
@@ -1720,6 +1834,12 @@ export declare const isSelf: (value: unknown) => value is Self;
  * turn on the new `traces` channel (the same toggle the dashboard's
  * Observability tab writes).
  *
+ * Effect-native Workers should prefer `Cloudflare.Telemetry()` over
+ * setting `observability.traces` by hand: providing the Layer enables
+ * traces on this Worker and mirrors `Effect.withSpan` into the Cloudflare
+ * waterfall. Pin `compatibility: { date: "2026-08-25" }` (or later) until
+ * the global default date is raised past 2026-07-28.
+ *
  * Field names match the Cloudflare API (camelCased): `headSamplingRate`,
  * `invocationLogs`, etc.
  *
@@ -1793,7 +1913,7 @@ export declare const isSelf: (value: unknown) => value is Self;
  * Workers Cache puts a regionally tiered cache in front of the Worker —
  * cache hits are served from the edge without invoking the Worker (and
  * without billing CPU time). In an Effect-native Worker, enable it by
- * yielding `Cloudflare.cache()` in the init phase, which also returns the
+ * yielding `Cloudflare.cache()` in the Construction phase, which also returns the
  * runtime purge client; async Workers use the `cache` prop instead. Control
  * what gets cached from your handlers via standard response headers:
  * `Cache-Control` (including `stale-while-revalidate`), `Cache-Tag` for
@@ -1806,7 +1926,7 @@ export declare const isSelf: (value: unknown) => value is Self;
  * **Example:** Enabling and purging the cache in an Effect Worker
  * ```typescript
  * Effect.gen(function* () {
- *   // init: enable Workers Cache on this Worker
+ *   // Construction: enable Workers Cache on this Worker
  *   const { purge } = yield* Cloudflare.cache({ crossVersionCache: true });
  *
  *   return {
@@ -1849,17 +1969,17 @@ export declare const isSelf: (value: unknown) => value is Self;
  *
  * For ad-hoc background work, `WorkerExecutionContext.waitUntil(effect)`
  * forks an Effect with the caller's full context and keeps the invocation
- * alive until it settles. The context can be yielded once in the init
- * closure and used from any handler; its methods are `RuntimeContext`-
+ * alive until it settles. The context can be yielded once in the
+ * constructor and used from any handler; its methods are `RuntimeContext`-
  * colored, so they can only run inside a handler.
  *
- * The init closure is evaluated once per isolate: the bridge builds the
+ * The constructor is evaluated once per isolate: the bridge builds the
  * Worker's layer stack on the first event and every later event reuses the
  * built services. Resolve services, bind resources, build handlers there —
  * one-shot I/O that caches a plain value (e.g. fetching a secret for a
  * client) is fine, but nothing disposable: the build scope is never closed
- * (workerd has no isolate-teardown hook), so a finalizer added in the init
- * closure never runs, and I/O-backed objects (sockets, response bodies) are
+ * (workerd has no isolate-teardown hook), so a finalizer added in the
+ * constructor never runs, and I/O-backed objects (sockets, response bodies) are
  * pinned to the request that created them. Anything that needs cleanup
  * belongs in a handler, where `Effect.addFinalizer` attaches to the
  * per-event scope.
@@ -1877,7 +1997,7 @@ export declare const isSelf: (value: unknown) => value is Self;
  *
  * **Example:** Background work with waitUntil
  * ```typescript
- * // init
+ * // Construction
  * const exec = yield* Cloudflare.WorkerExecutionContext;
  *
  * return {
@@ -1890,13 +2010,13 @@ export declare const isSelf: (value: unknown) => value is Self;
  * ```
  *
  * ### R2 Bucket
- * Bind an R2 bucket in the init phase with `Cloudflare.R2.ReadWriteBucket`.
+ * Bind an R2 bucket in the Construction phase with `Cloudflare.R2.ReadWriteBucket`.
  * The returned handle exposes `get`, `put`, `delete`, and `list`
  * methods you can call in your runtime handlers.
  *
  * **Example:** Binding and using R2
  * ```typescript
- * // init
+ * // Construction
  * const bucket = yield* Cloudflare.R2.ReadWriteBucket(MyBucket);
  *
  * return {
@@ -1924,7 +2044,7 @@ export declare const isSelf: (value: unknown) => value is Self;
  *
  * **Example:** Binding and using KV
  * ```typescript
- * // init
+ * // Construction
  * const kv = yield* Cloudflare.KV.ReadWriteNamespace(MyKV);
  *
  * return {
@@ -1942,7 +2062,7 @@ export declare const isSelf: (value: unknown) => value is Self;
  *
  * **Example:** Binding and querying D1
  * ```typescript
- * // init
+ * // Construction
  * const db = yield* Cloudflare.D1.QueryDatabase(MyDatabase);
  *
  * return {
@@ -1957,13 +2077,13 @@ export declare const isSelf: (value: unknown) => value is Self;
  * ```
  *
  * ### Durable Objects
- * Yield a `DurableObject` class in the init phase to get a
+ * Yield a `DurableObject` class in the Construction phase to get a
  * namespace handle. Call `getByName` or `getById` to get a typed RPC
  * stub, then call its methods from your runtime handlers.
  *
  * **Example:** Using a Durable Object
  * ```typescript
- * // init
+ * // Construction
  * const counters = yield* Counter;
  *
  * return {
@@ -1977,7 +2097,7 @@ export declare const isSelf: (value: unknown) => value is Self;
  *
  * ### Containers
  * Containers run long-lived processes alongside Durable Objects.
- * Provide `Cloudflare.Containers.layer(Sandbox, …)` on a DO's init to
+ * Provide `Cloudflare.Containers.layer(Sandbox, …)` on a DO's constructor to
  * bind, start, and monitor the container; then `yield* Sandbox`
  * resolves the **running** instance. Call its typed methods or use
  * `getTcpPort` to make HTTP requests to its exposed ports.
@@ -2017,13 +2137,13 @@ export declare const isSelf: (value: unknown) => value is Self;
  *
  * **Example:** Loading a dynamic Worker
  * ```typescript
- * // init
+ * // Construction
  * const loader = yield* Cloudflare.WorkerLoader("Loader");
  *
  * return {
  *   fetch: Effect.gen(function* () {
  *     const worker = yield* loader.load({
- *       compatibilityDate: "2026-01-28",
+ *       compatibilityDate: "2026-08-31",
  *       mainModule: "worker.js",
  *       modules: {
  *         "worker.js": `export default {
@@ -2044,7 +2164,7 @@ export declare const isSelf: (value: unknown) => value is Self;
  * @product Workers
  * @category Workers & Compute
  */
-export declare const Worker: ResourceClassLike<Worker> & Effect.Effect<Worker & WorkerRuntimeContext & RuntimeContext, never, Worker> & {
+export declare const Worker: ResourceClassLike<Worker> & Pick<ResourceClass<Worker>, "ref"> & Effect.Effect<Worker & WorkerRuntimeContext & RuntimeContext, never, Worker> & {
     <Self, Shape extends WorkerShape, Deps = never>(): {
         <const Id extends string>(id: Id): Effect.Effect<Worker & Rpc<Self> & Dependencies<Deps>, never, Self | Extract<Deps, Container.Application<any>> | Providers> & Named<Id> & {
             new (_: never): MakeShape<Shape, WorkerShape> & Named<Id> & Tag<WorkerTypeId>;
@@ -2083,5 +2203,4 @@ export declare const Worker: ResourceClassLike<Worker> & Effect.Effect<Worker &
      */
     readonly URL: URLEffect;
 };
-export {};
 //# sourceMappingURL=Worker.d.ts.map