alchemy 2.0.0-beta.64 → 2.0.0-beta.66

package/lib/Cloudflare/Workers/LocalWorkerProvider.js

@@ -1,11 +1,10 @@
-import { Runtime, RuntimeError, } from "@distilled.cloud/cloudflare-runtime";
+import { Runtime, } from "@distilled.cloud/cloudflare-runtime";
 import { Ai, AiSearch, AnalyticsEngine, Artifacts, Assets, Browser, D1, Data, DispatchNamespace, DurableObjectNamespace, Flagship, Hyperdrive, Images, Json, KvNamespace, MtlsCertificate, Pipelines, Queue, R2Bucket, RateLimit, SendEmail, Service, Text, Vectorize, VersionMetadata, WasmModule, WorkerLoader, Workflows, } from "@distilled.cloud/cloudflare-runtime/bindings";
 import * as WorkerProxy from "@distilled.cloud/cloudflare-runtime/proxy/WorkerProxy";
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Equal from "effect/Equal";
 import * as Exit from "effect/Exit";
-import * as Fiber from "effect/Fiber";
 import * as MutableHashMap from "effect/MutableHashMap";
 import * as Option from "effect/Option";
 import * as Path from "effect/Path";
@@ -15,36 +14,92 @@ import * as Schema from "effect/Schema";
 import * as Scope from "effect/Scope";
 import * as Semaphore from "effect/Semaphore";
 import * as Stream from "effect/Stream";
-import { isResolved, stripEffects } from "../../Diff.js";
-import * as RpcProvider from "../../Local/RpcProvider.js";
+import * as os from "node:os";
+import * as LocalProvider from "../../Local/LocalProvider.js";
 import { Stack } from "../../Stack.js";
-import { sha256, unwrapRedacted } from "../../Util/index.js";
+import { unwrapRedacted } from "../../Util/index.js";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.js";
-import { LOCAL_ENTRY_URL, LocalRuntimeState } from "../LocalRuntime.js";
+import { isLiveId, isLocalId, LOCAL_ENTRY_URL, LocalRuntimeState, } from "../LocalRuntime.js";
+import { readAssetsConfigFiles } from "./Assets.js";
 import { getCompatibility } from "./Compatibility.js";
 import { isPythonMain, watchPythonWorkerBundle } from "./PythonWorkerBundle.js";
-import { Worker } from "./Worker.js";
+import { isSelfUrl, Worker } from "./Worker.js";
 import { getCronBindings } from "./WorkerAsyncBindings.js";
 import { WorkerBundle } from "./WorkerBundle.js";
 import { createWorkerName } from "./WorkerName.js";
+// Hosts that bind every interface — the dev server is then reachable at
+// `localhost` *and* at each LAN address, like Vite's `--host` output.
+const isWildcardHost = (host) => host === "0.0.0.0" || host === "::" || host === "[::]" || host === "*";
+/**
+ * Resolve every URL a local dev server is reachable at, most relevant
+ * first. A loopback or explicit host yields just that URL; a wildcard host
+ * (`0.0.0.0`, `::`) yields `http://localhost:<port>` followed by one URL
+ * per external IPv4 interface (`http://192.168.0.12:<port>`, ...) —
+ * mirroring Vite's "Local / Network" dev-server output.
+ */
+const resolveLocalUrls = (serverUrl) => Effect.sync(() => {
+    const port = serverUrl.port;
+    const host = serverUrl.hostname;
+    if (!isWildcardHost(host)) {
+        return [serverUrl.origin];
+    }
+    // `os.networkInterfaces()` is a sync, CPU-only syscall with no Effect
+    // platform equivalent — wrapped in `Effect.sync` so it participates in
+    // the runtime.
+    const interfaces = os.networkInterfaces();
+    const lanAddresses = Object.values(interfaces)
+        .flatMap((addresses) => addresses ?? [])
+        .filter((address) => address.family === "IPv4" && !address.internal)
+        .map((address) => address.address);
+    return [
+        `http://localhost:${port}`,
+        ...lanAddresses.map((address) => `http://${address}:${port}`),
+    ];
+});
 export class WorkerValidationError extends Schema.TaggedErrorClass()("WorkerValidationError", {
     message: Schema.String,
     hint: Schema.optional(Schema.String),
     value: Schema.Unknown,
 }) {
 }
-export const LocalWorkerProvider = () => RpcProvider.effect(Worker, LOCAL_ENTRY_URL, Effect.gen(function* () {
+export const LocalWorkerProvider = () => LocalProvider.make(Worker, LOCAL_ENTRY_URL, Effect.gen(function* () {
     const bundler = yield* WorkerBundle;
     const runtime = yield* Runtime;
     const stack = yield* Stack;
     const path = yield* Path.Path;
     const localRuntimeState = yield* LocalRuntimeState;
     const workerProxy = yield* WorkerProxy.WorkerProxy;
+    const cloudflareEnv = yield* CloudflareEnvironment;
+    const context = yield* Effect.context();
+    const rootScope = yield* Effect.scope;
+    // Proxies are deliberately NOT owned by the per-instance scope: they
+    // survive restarts so the worker's URL stays stable across rebuilds
+    // and config changes. Torn down by `stop` on delete.
     const proxyInstances = new Map();
     const getQueueConsumers = Effect.fn(function* (scriptName) {
         const consumers = [];
         for (const consumer of MutableHashMap.values(localRuntimeState.queueConsumers)) {
             if (consumer.scriptName === scriptName) {
+                // A LIVE queue (`Alchemy.remote()`) consumed locally: the broker
+                // is still local, but it is fed by the runtime's pull loop
+                // draining the real queue over the HTTP pull API (the
+                // Consumer's local provider attached the `http_pull` consumer
+                // and resolved the queue's real name).
+                if (isLiveId(consumer.queueId)) {
+                    if (!consumer.queueName) {
+                        return yield* Effect.die(`Consumer of live queue ${consumer.queueId} is missing its resolved queueName — re-deploy the consumer`);
+                    }
+                    consumers.push({
+                        queueName: consumer.queueName,
+                        deadLetterQueue: consumer.deadLetterQueue,
+                        ...consumer.settings,
+                        pull: {
+                            queueId: consumer.queueId,
+                            accountId: consumer.accountId,
+                        },
+                    });
+                    continue;
+                }
                 const queue = MutableHashMap.get(localRuntimeState.queues, consumer.queueId).pipe(Option.getOrUndefined);
                 if (queue) {
                     consumers.push({
@@ -145,123 +200,25 @@ export const LocalWorkerProvider = () => RpcProvider.effect(Worker, LOCAL_ENTRY_
         }
         return modules;
     });
-    // Latest successful serve per worker id, so runtime wiring changes
-    // that arrive AFTER workerd started (e.g. a sibling `Consumer`
-    // resource registering this script as a queue consumer) can restart
-    // the instance with the same bundle. `scope` is the parent scope the
-    // workerd child scope is forked from (the instance scope), NOT the
-    // caller's ambient scope — restarts are triggered from other
-    // providers' reconcile fibers whose scopes must not own workerd.
-    const latestServes = new Map();
-    // Serializes serves per worker id: a restart triggered by a sibling
-    // resource may otherwise interleave with a rebuild-triggered serve
-    // and leak a workerd scope.
-    const serveLocks = new Map();
-    const serveLock = (id) => {
-        let lock = serveLocks.get(id);
-        if (!lock) {
-            lock = Semaphore.makeUnsafe(1);
-            serveLocks.set(id, lock);
-        }
-        return lock;
-    };
-    const serveWith = (worker, bundle, proxy, parentScope) => Semaphore.withPermits(serveLock(worker.id), 1)(Effect.gen(function* () {
-        // Queue-consumer wiring can change while `runtime.start` is in
-        // flight (a sibling `Consumer` reconcile), before the restart
-        // hook below exists to pick it up. We hold the serve lock, so a
-        // restart would deadlock — instead, loop and serve again until
-        // the wiring is stable across a start.
-        while (true) {
-            const previous = workerdScopes.get(worker.id);
-            if (previous) {
-                // Both runtimes use the same registry key. Close the old scope first so
-                // its unregister finalizer cannot delete the replacement registration.
-                yield* Scope.close(previous, Exit.void);
-                workerdScopes.delete(worker.id);
-            }
-            const queueConsumers = yield* getQueueConsumers(worker.name);
-            const scope = yield* Scope.fork(parentScope);
-            const url = yield* runtime
-                .start({
-                name: worker.name,
-                compatibilityDate: worker.compatibility.date,
-                compatibilityFlags: worker.compatibility.flags,
-                bindings: worker.workerBindings,
-                hyperdrives: worker.hyperdrives,
-                durableObjectNamespaces: worker.durableObjectNamespaces,
-                queueConsumers,
-                modules: yield* toRuntimeModules(bundle),
-                assets: toRuntimeAssets(worker.assets),
-            })
-                .pipe(Scope.provide(scope));
-            workerdScopes.set(worker.id, scope);
-            latestServes.set(worker.id, {
-                worker,
-                bundle,
-                proxy,
-                scope: parentScope,
-            });
-            // Register the restart hook before the re-check below: changes
-            // landing after the re-check find the hook; changes before it
-            // are caught by the re-check. Nothing falls in between.
-            MutableHashMap.set(localRuntimeState.workerRestarts, worker.name, restartWorker(worker.id));
-            const currentConsumers = yield* getQueueConsumers(worker.name);
-            if (JSON.stringify(currentConsumers) !==
-                JSON.stringify(queueConsumers)) {
-                // Wiring changed while workerd was starting — serve again with
-                // the fresh consumers before exposing the instance.
-                continue;
-            }
-            yield* proxy.set(url);
-            return url;
-        }
-    }));
-    const serveScoped = Effect.fn(function* (worker, bundle, proxy) {
-        const parentScope = yield* Effect.scope;
-        return yield* serveWith(worker, bundle, proxy, parentScope);
-    });
     /**
-     * Restart a running worker with its latest bundle so start-time
-     * runtime wiring (queue consumers) is re-read from
-     * {@link LocalRuntimeState}. No-op if the worker hasn't served yet —
-     * the pending first serve will already observe the updated state.
+     * The restart-relevant, canonically-hashable view of a local Worker's
+     * desired state — `LocalProvider`'s `resolveConfig`. Everything here
+     * is plain data: binding *descriptors* (not `BindingHook` closures —
+     * those are materialized in `start` via {@link toRuntimeBinding}),
+     * DO-namespace/hyperdrive/container-image records, bundle options.
+     *
+     * Queue consumers are deliberately EXCLUDED: `getQueueConsumers`
+     * reads `LocalRuntimeState` at serve time and sibling `Consumer`
+     * reconciles drive restarts through the `workerRestarts` hook — they
+     * are runtime wiring observed at start, not desired-state config.
      */
-    const restartWorker = (id) => Effect.suspend(() => {
-        const latest = latestServes.get(id);
-        if (!latest)
-            return Effect.void;
-        return serveWith(latest.worker, latest.bundle, latest.proxy, latest.scope).pipe(Effect.asVoid, Effect.catchCause((cause) => Effect.logWarning(`[${id}] Failed to restart local worker`, Cause.squash(cause))));
-    });
-    // Note: `serveLocks` entries are intentionally retained — an
-    // in-flight restart may still hold the semaphore when the instance
-    // is torn down, and a same-id re-create must serialize against it.
-    const dropServeState = (id) => {
-        const latest = latestServes.get(id);
-        if (latest) {
-            MutableHashMap.remove(localRuntimeState.workerRestarts, latest.worker.name);
-            latestServes.delete(id);
-        }
-    };
-    const buildConfig = Effect.fn(function* ({ id, props, bindings, }) {
-        const { accountId } = yield* yield* CloudflareEnvironment;
+    const resolveConfig = Effect.fn(function* ({ id, news, bindings, }) {
+        const props = news;
         const name = yield* createWorkerName(id, props.name);
         const compatibility = getCompatibility(props);
-        const workerBindings = [
-            Text.local("ALCHEMY_PHASE", "runtime"),
-            Text.local("ALCHEMY_STACK_NAME", stack.name),
-            Text.local("ALCHEMY_STAGE", stack.stage),
-            Text.local("ALCHEMY_CLOUDFLARE_ACCOUNT_ID", accountId),
-            ...Object.entries(props.env ?? {}).map(([key, value]) => {
-                const unredacted = Redacted.isRedacted(value)
-                    ? Redacted.value(value)
-                    : value;
-                return typeof unredacted === "string"
-                    ? Text.local(key, unredacted)
-                    : Json.local(key, unredacted);
-            }),
-            ...(props.assets || props.vite ? [Assets.local("ASSETS")] : []),
-        ];
+        const bindingDescriptors = [];
         const durableObjectNamespaces = {};
+        const workflows = {};
         const hyperdrives = {};
         const containers = {};
         for (const { data } of bindings) {
@@ -279,13 +236,20 @@ export const LocalWorkerProvider = () => RpcProvider.effect(Worker, LOCAL_ENTRY_
                         uniqueKey: namespaceId,
                         sql: true,
                     };
-                    workerBindings.push(yield* toRuntimeBinding({
-                        ...binding,
-                        namespaceId,
-                    }));
+                    bindingDescriptors.push({ ...binding, namespaceId });
                 }
                 else {
-                    workerBindings.push(yield* toRuntimeBinding(binding));
+                    if (binding.type === "workflow" &&
+                        // Same ownership rule as DOs: only declare workflows hosted by
+                        // this worker. Cross-script workflow bindings are routed via
+                        // the registry proxy.
+                        (!binding.scriptName || binding.scriptName === name)) {
+                        workflows[binding.workflowName] = {
+                            workflowName: binding.workflowName,
+                            className: binding.className,
+                        };
+                    }
+                    bindingDescriptors.push(binding);
                 }
             }
             if (data.hyperdrives) {
@@ -319,38 +283,271 @@ export const LocalWorkerProvider = () => RpcProvider.effect(Worker, LOCAL_ENTRY_
             }
             durableObjectNamespaces[className].container = dev;
         }
+        const dev = props.dev?.mode === "external"
+            ? props.dev
+            : {
+                ...props.dev,
+                mode: "worker",
+                // This is the default. Vite and cloudflare-runtime will retry
+                // if unavailable, unless `strictPort` is true.
+                port: props.dev?.port ?? 1337,
+            };
         return {
             id,
             name,
             compatibility,
-            workerBindings,
+            /** User env (Redacted preserved — the canonical hasher unwraps). */
+            env: props.env,
+            /**
+             * Raw inline module source (mutually exclusive with `main`).
+             * Serves as-is without the bundler; part of the hashed config so
+             * editing the script restarts the instance.
+             */
+            script: props.script,
+            hasAssets: !!(props.assets || props.vite),
+            /**
+             * Assets-only Worker (no entry module at all): served locally by
+             * a stub that delegates every request to the ASSETS binding.
+             */
+            assetsOnly: props.main === undefined &&
+                props.script === undefined &&
+                !props.vite &&
+                !!props.assets,
+            bindingDescriptors,
             durableObjectNamespaces: Object.values(durableObjectNamespaces),
-            viteMain: props.vite?.main,
-            viteEnvironments: props.vite?.viteEnvironments,
+            workflows: Object.values(workflows),
             hyperdrives,
-            env: props.env,
+            vite: !!props.vite,
+            // Relative `vite.main` resolves from the Vite root (see the
+            // matching normalization in WorkerProvider's `viteBuild`).
+            viteMain: props.vite?.main
+                ? path.resolve(props.vite.rootDir ?? process.cwd(), props.vite.main)
+                : undefined,
+            viteEnvironments: props.vite?.viteEnvironments,
+            viteRootDir: props.vite?.rootDir,
             bundleOptions: {
                 id,
                 main: props.main,
                 compatibility,
                 entry: props.isExternal
                     ? { kind: "external" }
-                    : { kind: "effect", exports: props.exports ?? {} },
+                    : {
+                        kind: "effect",
+                        exports: props.exports ?? {},
+                    },
                 stack: { name: stack.name, stage: stack.stage },
                 extraOptions: props.build,
             },
             assets: props.assets,
-            dev: {
-                ...props.dev,
-                // This is the default. Vite and cloudflare-runtime will retry if unavailable, unless `strictPort` is true.
-                port: props.dev?.port ?? 1337,
-            },
+            dev,
+            crons: Array.from(new Set([...getCronBindings(bindings), ...(props.crons ?? [])])),
         };
     });
+    /**
+     * Materialize the plain binding descriptors from {@link resolveConfig}
+     * into live cloudflare-runtime `BindingHook`s. This is the non-plain
+     * half of the old `buildConfig` — kept out of the hashed config.
+     */
+    const materializeWorkerBindings = Effect.fn(function* (config, selfUrl) {
+        const { accountId } = yield* cloudflareEnv;
+        // Resource-backed env entries (e.g. `env: { KV: namespace }`) are
+        // represented by their binding descriptor (same name) — don't ALSO
+        // serialize the resolved attributes as a duplicate json binding.
+        const descriptorNames = new Set(config.bindingDescriptors.map((descriptor) => descriptor.name));
+        const workerBindings = [
+            Text.local("ALCHEMY_PHASE", "runtime"),
+            Text.local("ALCHEMY_WORKER_NAME", config.name),
+            Text.local("ALCHEMY_STACK_NAME", stack.name),
+            Text.local("ALCHEMY_STAGE", stack.stage),
+            Text.local("ALCHEMY_CLOUDFLARE_ACCOUNT_ID", accountId),
+            ...Object.entries(config.env ?? {})
+                .filter(([key]) => !descriptorNames.has(key))
+                .map(([key, value]) => {
+                if (isSelfUrl(value)) {
+                    return Text.local(key, selfUrl);
+                }
+                const unredacted = Redacted.isRedacted(value)
+                    ? Redacted.value(value)
+                    : value;
+                return typeof unredacted === "string"
+                    ? Text.local(key, unredacted)
+                    : Json.local(key, unredacted);
+            }),
+            ...(config.hasAssets ? [Assets.local("ASSETS")] : []),
+        ];
+        for (const descriptor of config.bindingDescriptors) {
+            if (descriptor.type === "self_url") {
+                // Lowered here rather than in `toRuntimeBinding` — only this
+                // scope knows the worker's own dev-proxy URL.
+                workerBindings.push(Text.local(descriptor.name, selfUrl));
+                continue;
+            }
+            workerBindings.push(yield* toRuntimeBinding(descriptor));
+        }
+        return workerBindings;
+    });
+    // Latest successful serve per worker id, so runtime wiring changes
+    // that arrive AFTER workerd started (e.g. a sibling `Consumer`
+    // resource registering this script as a queue consumer) can restart
+    // the instance with the same bundle.
+    const latestServes = new Map();
+    // Serializes serves per worker id: a restart triggered by a sibling
+    // resource may otherwise interleave with a rebuild-triggered serve
+    // and leak a workerd scope.
+    const serveLocks = new Map();
+    const serveLock = (id) => {
+        let lock = serveLocks.get(id);
+        if (!lock) {
+            lock = Semaphore.makeUnsafe(1);
+            serveLocks.set(id, lock);
+        }
+        return lock;
+    };
+    const workerdScopes = new Map();
+    // Serve with make-before-break semantics: start the replacement
+    // workerd while the previous instance (if any) keeps serving — and
+    // stays registered in the dev registry — then cut the proxy over and
+    // tear the previous instance down. Cross-script consumers (e.g. a DO
+    // bound via `scriptName` from another Worker) therefore never observe
+    // a window where the script has no running instance and no registry
+    // entry, even when `runtime.start` is slow (container image builds).
+    // Both instances use the same registry key; the registry's entry
+    // removal is owner-aware, so closing the old scope after the
+    // replacement has re-registered cannot delete the replacement's
+    // registration.
+    //
+    // The workerd scope is forked from the provider's `rootScope`, NOT
+    // the instance scope: a reconcile that replaces the instance (or a
+    // restart triggered from a sibling provider's fiber) tears down the
+    // bundle watcher without killing the currently serving workerd — the
+    // last good instance keeps serving until the replacement's first
+    // serve completes. Ownership is tracked in `workerdScopes`, closed by
+    // the next successful serve, by `delete`, or by provider shutdown.
+    const serveWith = (worker, bundle, proxy) => Semaphore.withPermits(serveLock(worker.id), 1)(
+    // The bookkeeping around `runtime.start` must not be torn in half
+    // by an interrupt: once a replacement workerd is up, it must be
+    // recorded in `workerdScopes` and the superseded instances must be
+    // closed, or one of the workerds would leak until provider
+    // shutdown while holding the shared registry key.
+    Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+        const previous = workerdScopes.get(worker.id);
+        // Instances whose queue-consumer wiring went stale while they
+        // were starting; never exposed via the proxy, closed together
+        // with `previous` after the cutover below.
+        const superseded = [];
+        let scope;
+        let url;
+        // Queue-consumer wiring can change while `runtime.start` is in
+        // flight (a sibling `Consumer` reconcile), before the restart
+        // hook below exists to pick it up. We hold the serve lock, so a
+        // restart would deadlock — instead, loop and serve again until
+        // the wiring is stable across a start.
+        while (true) {
+            const queueConsumers = yield* getQueueConsumers(worker.name);
+            scope = yield* Scope.fork(rootScope);
+            url = yield* restore(runtime
+                .start({
+                name: worker.name,
+                compatibilityDate: worker.compatibility.date,
+                compatibilityFlags: worker.compatibility.flags,
+                bindings: worker.workerBindings,
+                hyperdrives: worker.hyperdrives,
+                durableObjectNamespaces: worker.durableObjectNamespaces,
+                workflows: worker.workflows,
+                queueConsumers,
+                // Cache API opt-out (`dev: { cache: false }`) — matches
+                // production workers.dev, where the Cache API is a no-op.
+                cache: worker.dev.cache,
+                // Per-worker request.cf override (`dev: { cf: {...} }`).
+                cf: worker.dev.cf,
+                modules: yield* toRuntimeModules(bundle),
+                assets: yield* toRuntimeAssets(worker.assets),
+            })
+                .pipe(Scope.provide(scope))).pipe(
+            // The scope hangs off `rootScope`, so a failed or
+            // interrupted start must close it here — nothing else owns
+            // it yet.
+            Effect.onExit((exit) => exit._tag === "Failure"
+                ? Scope.close(scope, exit)
+                : Effect.void));
+            workerdScopes.set(worker.id, scope);
+            latestServes.set(worker.id, { worker, bundle, proxy });
+            // Register the restart hook before the re-check below: changes
+            // landing after the re-check find the hook; changes before it
+            // are caught by the re-check. Nothing falls in between.
+            MutableHashMap.set(localRuntimeState.workerRestarts, worker.name, restartWorker(worker.id));
+            const currentConsumers = yield* getQueueConsumers(worker.name);
+            if (JSON.stringify(currentConsumers) !==
+                JSON.stringify(queueConsumers)) {
+                // Wiring changed while workerd was starting — serve again
+                // with the fresh consumers before exposing the instance.
+                superseded.push(scope);
+                continue;
+            }
+            break;
+        }
+        yield* proxy.set(url);
+        // Only now tear the replaced instances down: `previous` kept
+        // serving — and stayed registered in the dev registry — until
+        // the cutover above. The registry's entry removal is
+        // owner-aware, so these closes cannot delete the replacement's
+        // registration.
+        for (const replaced of previous
+            ? [...superseded, previous]
+            : superseded) {
+            yield* Scope.close(replaced, Exit.void).pipe(Effect.catchCause((cause) => Effect.logWarning(`[${worker.id}] Failed to stop previous local worker instance`, Cause.squash(cause))));
+        }
+        return url;
+    })));
+    /**
+     * Restart a running worker with its latest bundle so start-time
+     * runtime wiring (queue consumers) is re-read from
+     * {@link LocalRuntimeState}. No-op if the worker hasn't served yet —
+     * the pending first serve will already observe the updated state.
+     */
+    const restartWorker = (id) => Effect.suspend(() => {
+        const latest = latestServes.get(id);
+        if (!latest)
+            return Effect.void;
+        return serveWith(latest.worker, latest.bundle, latest.proxy).pipe(Effect.asVoid, Effect.catchCause((cause) => Effect.logWarning(`[${id}] Failed to restart local worker`, Cause.squash(cause))));
+    });
+    // Tear down the running workerd for a worker id, if any. Used when the
+    // Worker is deleted or handed off to an external dev process —
+    // instance replacement does NOT go through this: the previous workerd
+    // keeps serving until the replacement's first serve closes it.
+    const closeWorkerd = Effect.fn(function* (id) {
+        const scope = workerdScopes.get(id);
+        if (scope) {
+            workerdScopes.delete(id);
+            yield* Scope.close(scope, Exit.void);
+        }
+    });
+    // Note: `serveLocks` entries are intentionally retained — an
+    // in-flight restart may still hold the semaphore when the instance
+    // is torn down, and a same-id re-create must serialize against it.
+    const dropServeState = (id) => {
+        const latest = latestServes.get(id);
+        if (latest) {
+            MutableHashMap.remove(localRuntimeState.workerRestarts, latest.worker.name);
+            latestServes.delete(id);
+        }
+    };
     const runWorker = Effect.fn(function* (worker) {
         let start = Date.now();
         let status = "start";
         const proxy = yield* maybeStartProxy(worker.id, worker.dev);
+        // Inline `script` workers bypass the bundler entirely — the string
+        // IS the module (mirroring the deploy path, which uploads it as a
+        // single `main.js`). There is nothing to watch: script changes flow
+        // through the hashed config and restart the instance.
+        if (worker.script !== undefined) {
+            yield* serveWith(worker, {
+                files: [{ path: "main.js", content: worker.script, hash: "" }],
+                hash: "",
+            }, proxy);
+            yield* Effect.log(`[${worker.id}] Started in ${Math.round(Date.now() - start)}ms`);
+            return proxy.url;
+        }
         yield* (isPythonMain(worker.bundleOptions.main)
             ? watchPythonWorkerBundle({
                 id: worker.bundleOptions.id,
@@ -374,7 +571,7 @@ export const LocalWorkerProvider = () => RpcProvider.effect(Worker, LOCAL_ENTRY_
             return Effect.void;
         }), Stream.filterMap((event) => event._tag === "Success"
             ? Result.succeed(event.output)
-            : Result.failVoid), Stream.mapEffect((bundle) => serveScoped(worker, bundle, proxy).pipe(Effect.exit, Effect.tap((exit) => {
+            : Result.failVoid), Stream.mapEffect((bundle) => serveWith(worker, bundle, proxy).pipe(Effect.exit, Effect.tap((exit) => {
             if (exit._tag === "Success") {
                 const message = Effect.log(`[${worker.id}] ${status === "update" ? "Updated" : "Started"} in ${Math.round(Date.now() - start)}ms`);
                 status = "update";
@@ -386,6 +583,29 @@ export const LocalWorkerProvider = () => RpcProvider.effect(Worker, LOCAL_ENTRY_
         }))), Stream.runDrain, Effect.forkScoped);
         return proxy.url;
     });
+    // Assets-only Worker: there is no entry module to bundle or watch.
+    // The local runtime requires a user worker module, so serve a stub
+    // that delegates every request to the ASSETS binding — the assets
+    // worker applies `htmlHandling` / `notFoundHandling` (including SPA
+    // fallback) itself, matching Cloudflare's deployed assets-only
+    // behavior.
+    const assetsOnlyBundle = {
+        files: [
+            {
+                path: "main.js",
+                content: "export default { fetch: (request, env) => env.ASSETS.fetch(request) };",
+                hash: "assets-only-stub",
+            },
+        ],
+        hash: "assets-only-stub",
+    };
+    const runAssetsOnly = Effect.fn(function* (worker) {
+        const start = Date.now();
+        const proxy = yield* maybeStartProxy(worker.id, worker.dev);
+        yield* serveWith(worker, assetsOnlyBundle, proxy);
+        yield* Effect.log(`[${worker.id}] Started in ${Math.round(Date.now() - start)}ms`);
+        return proxy.url;
+    });
     const runVite = Effect.fn(function* (worker, rootDir) {
         const proxy = yield* maybeStartProxy(worker.id, worker.dev);
         yield* proxy.unset().pipe(Effect.forkChild);
@@ -401,70 +621,22 @@ export const LocalWorkerProvider = () => RpcProvider.effect(Worker, LOCAL_ENTRY_
                 name: worker.name,
                 bindings: worker.workerBindings,
                 durableObjectNamespaces: worker.durableObjectNamespaces,
+                workflows: worker.workflows,
                 hyperdrives: worker.hyperdrives,
                 queueConsumers: yield* getQueueConsumers(worker.name),
-                assets: toRuntimeAssets(worker.assets),
+                assets: yield* toRuntimeAssets(worker.assets),
             },
             context,
         }, { port: 0 });
         yield* proxy.set(new URL(devServer.resolvedUrls.local[0]));
         return proxy.url;
     });
-    const rootScope = yield* Effect.scope;
-    const workerdScopes = new Map();
-    const context = yield* Effect.context();
-    const instances = new Map();
-    const runInstance = Effect.fn(function* (options) {
-        const { accountId } = yield* yield* CloudflareEnvironment;
-        const { props, bindings } = options;
-        const config = yield* buildConfig(options);
-        const url = yield* (props.vite ? runVite(config, props.vite.rootDir) : runWorker(config)).pipe(Effect.map((url) => url.toString()));
-        return {
-            workerId: config.name,
-            workerName: config.name,
-            namespace: undefined,
-            logpush: undefined,
-            url,
-            tags: [],
-            durableObjectNamespaces: Object.fromEntries(config.durableObjectNamespaces.map((namespace) => [
-                namespace.className,
-                namespace.uniqueKey,
-            ])),
-            domains: [url],
-            routes: [],
-            crons: Array.from(new Set([...getCronBindings(bindings), ...(props.crons ?? [])])),
-            accountId,
-        };
-    });
     return {
-        // Local dev provider: there is no cloud enumeration API. The set of
-        // locally running Workers is the in-memory `instances` map; each
-        // instance's fiber resolves to the Worker Attributes once it has
-        // started, so enumerate that local state.
-        list: () => Effect.forEach(Array.from(instances.values()), (instance) => Fiber.join(instance.fiber), { concurrency: "unbounded" }),
-        diff: Effect.fn(function* ({ id, news: desired, newBindings, output }) {
-            // Effect-valued `env` entries (tagged Worker classes) never resolve
-            // at plan time; their identity is carried by the resolved binding
-            // data. Strip them so the signature-based diff still runs — same
-            // rationale as the cloud WorkerProvider (#874).
-            const news = stripEffects(desired);
-            if (!isResolved(news) || !isResolved(newBindings))
-                return undefined;
-            const options = {
-                id,
-                props: news,
-                bindings: newBindings,
-            };
-            const signature = yield* structuralSignature(options);
-            if (instances.get(options.id)?.signature === signature) {
-                return { action: "noop" };
-            }
-            const name = yield* createWorkerName(id, news.name);
-            return {
-                action: "update",
-                stables: output?.workerName === name ? ["workerName"] : undefined,
-            };
-        }),
+        resolveConfig,
+        // The physical name only survives an update when it isn't changing.
+        stables: ({ output, config }) => Effect.succeed(output?.workerName === config.name
+            ? ["workerName"]
+            : undefined),
         precreate: Effect.fn(function* ({ id, news, bindings }) {
             const name = yield* createWorkerName(id, news.name);
             const durableObjectNamespaces = {};
@@ -477,93 +649,123 @@ export const LocalWorkerProvider = () => RpcProvider.effect(Worker, LOCAL_ENTRY_
                     }
                 }
             }
-            const { accountId } = yield* yield* CloudflareEnvironment;
-            const url = news.dev?.mode === "external"
+            const { accountId } = yield* cloudflareEnv;
+            const urls = news.dev?.mode === "external"
                 ? // news.dev.url may be an unresolved output; avoid trying to resolve it here.
-                    undefined
+                    []
                 : yield* maybeStartProxy(id, {
                     ...news.dev,
+                    mode: "worker",
                     port: news.dev?.port ?? 1337,
-                }).pipe(Effect.map((proxy) => proxy.url.toString()));
+                }).pipe(Effect.flatMap((proxy) => resolveLocalUrls(proxy.url)));
             return {
                 workerId: name,
                 workerName: name,
                 namespace: undefined,
                 logpush: undefined,
-                url,
+                url: urls[0],
+                urls,
+                domain: undefined,
                 tags: [],
                 durableObjectNamespaces,
-                domains: url ? [url] : [],
                 routes: [],
                 crons: Array.from(new Set([...getCronBindings(bindings), ...(news.crons ?? [])])),
                 accountId,
             };
         }),
-        reconcile: Effect.fn(function* ({ id, news, bindings }) {
-            // `dev: false` opts out of running a local Worker entirely —
-            // typically because an external dev process (DevCommand) is
-            // serving requests. Tear down any prior instance and return a
-            // stub Attributes; the resource exists in state but has no
-            // running workerd / proxy behind it.
-            if (news.dev?.mode === "external") {
-                const { accountId } = yield* yield* CloudflareEnvironment;
-                const existing = instances.get(id);
-                if (existing) {
-                    yield* Fiber.interrupt(existing.fiber);
-                    yield* Scope.close(existing.scope, Exit.void);
-                    instances.delete(id);
-                    dropServeState(id);
-                }
-                const name = yield* createWorkerName(id, news.name);
+        start: Effect.fn(function* ({ id, config }) {
+            const { accountId } = yield* cloudflareEnv;
+            // `dev: { mode: "external" }` opts out of running a local Worker
+            // entirely — typically because an external dev process
+            // (Command.Dev) is serving requests. The instance exists in the
+            // registry (with an empty scope) but has no workerd behind it. A
+            // previous worker-mode instance for this id may have registered
+            // serve/restart state — drop it, and tear down its workerd (with
+            // make-before-break the running workerd outlives instance scopes
+            // and must be closed explicitly on handoff).
+            if (config.dev.mode === "external") {
+                dropServeState(id);
+                yield* closeWorkerd(id);
+                const urls = config.dev.url ? [config.dev.url] : [];
                 return {
-                    workerId: name,
-                    workerName: name,
+                    workerId: config.name,
+                    workerName: config.name,
                     namespace: undefined,
                     logpush: undefined,
-                    url: news.dev.url,
+                    url: urls[0],
+                    urls,
+                    domain: undefined,
                     tags: [],
                     durableObjectNamespaces: {},
                     accountId,
-                    domains: [],
                     routes: [],
-                    crons: news.crons ?? [],
+                    crons: config.crons,
                 };
             }
-            const options = { id, props: news, bindings };
-            const signature = yield* structuralSignature(options);
-            const existing = instances.get(options.id);
-            if (existing) {
-                if (existing.signature === signature) {
-                    yield* Effect.log(`[${options.id}] No changes, using existing instance`);
-                    return yield* Fiber.join(existing.fiber);
-                }
-                yield* Effect.log(`[${options.id}] Changes detected, interrupting existing instance`);
-                yield* Fiber.interrupt(existing.fiber);
-                yield* Scope.close(existing.scope, Exit.void);
-                instances.delete(options.id);
-                dropServeState(options.id);
-            }
-            const scope = yield* Scope.fork(rootScope);
-            const fiber = yield* runInstance(options).pipe(Effect.forkDetach, Scope.provide(scope));
-            instances.set(options.id, { signature, fiber, scope });
-            return yield* Fiber.join(fiber).pipe(Effect.onExit((exit) => Effect.sync(() => {
-                if (exit._tag === "Failure") {
-                    instances.delete(options.id);
-                }
-            })));
+            // `Worker.URL` locally resolves to the worker's dev-proxy URL —
+            // the proxy is stable per worker id (the same instance `runWorker`
+            // / `runVite` attach to below), so the URL is known before workerd
+            // starts. Trailing slash stripped to match the cloud value's shape.
+            const needsSelfUrl = config.bindingDescriptors.some((b) => b.type === "self_url") ||
+                Object.values(config.env ?? {}).some(isSelfUrl);
+            const selfUrl = needsSelfUrl
+                ? (yield* maybeStartProxy(id, config.dev)).url
+                    .toString()
+                    .replace(/\/$/, "")
+                : undefined;
+            const workerBindings = yield* materializeWorkerBindings(config, selfUrl);
+            const worker = {
+                ...config,
+                // Substitute `Worker.URL` sentinels so the Vite dev server
+                // inlines the local URL into VITE_*-prefixed define entries.
+                env: config.env && selfUrl !== undefined
+                    ? Object.fromEntries(Object.entries(config.env).map(([key, value]) => [
+                        key,
+                        isSelfUrl(value) ? selfUrl : value,
+                    ]))
+                    : config.env,
+                dev: config.dev,
+                workerBindings,
+            };
+            const serverUrl = yield* config.vite
+                ? runVite(worker, config.viteRootDir)
+                : config.assetsOnly
+                    ? runAssetsOnly(worker)
+                    : runWorker(worker);
+            // In dev, `urls` is the dev server's actual surface — localhost
+            // first, then LAN addresses for wildcard hosts. Deployed domains
+            // are not served by this session, so they don't appear.
+            const urls = yield* resolveLocalUrls(serverUrl);
+            return {
+                workerId: config.name,
+                workerName: config.name,
+                namespace: undefined,
+                logpush: undefined,
+                url: urls[0],
+                urls,
+                domain: undefined,
+                tags: [],
+                durableObjectNamespaces: Object.fromEntries(config.durableObjectNamespaces.map((namespace) => [
+                    namespace.className,
+                    namespace.uniqueKey,
+                ])),
+                routes: [],
+                crons: config.crons,
+                accountId,
+            };
         }),
-        delete: Effect.fn(function* ({ id }) {
-            const existing = instances.get(id);
-            if (existing) {
-                yield* Fiber.interrupt(existing.fiber);
-                yield* Scope.close(existing.scope, Exit.void);
-                instances.delete(id);
-                dropServeState(id);
-            }
+        stop: Effect.fn(function* ({ id }) {
+            // Cross-restart state: the serve/restart bookkeeping, the running
+            // workerd (which outlives instance scopes for make-before-break),
+            // and the URL proxy live outside instance scopes and are only
+            // reclaimed on a real delete.
+            dropServeState(id);
+            yield* closeWorkerd(id);
+            yield* stopProxy(id);
         }),
     };
 }));
-export const toRuntimeBinding = Effect.fn(function* (b) {
+export const toRuntimeBinding = Effect.fn(function* (b, dev) {
     const unsupported = () => new WorkerValidationError({
         message: `${b.type} bindings are not supported in local mode`,
         value: b,
@@ -584,7 +786,12 @@ export const toRuntimeBinding = Effect.fn(function* (b) {
         case "browser":
             return Browser.remote(b.name);
         case "d1":
-            return D1.remote(b.name, b.databaseId);
+            // A `dev:` id belongs to a locally-emulated database (local D1
+            // provider); a real id is a live database the dev worker proxies to
+            // (e.g. the resource opted out of emulation via `Alchemy.remote()`).
+            return isLocalId(b.databaseId)
+                ? D1.local({ binding: b.name, id: b.databaseId })
+                : D1.remote(b.name, b.databaseId);
         case "data_blob":
             return Data.local(b.name, Buffer.from(b.part));
         case "dispatch_namespace":
@@ -611,20 +818,57 @@ export const toRuntimeBinding = Effect.fn(function* (b) {
         case "json":
             return Json.local(b.name, b.json);
         case "kv_namespace":
-            return KvNamespace.remote(b.name, b.namespaceId);
+            // A `dev:` id belongs to a locally-emulated namespace; a real id is
+            // a live namespace the dev worker proxies to.
+            return isLocalId(b.namespaceId)
+                ? KvNamespace.local({ binding: b.name, id: b.namespaceId })
+                : KvNamespace.remote(b.name, b.namespaceId);
         case "mtls_certificate":
             return MtlsCertificate.remote(b.name, b.certificateId);
         case "pipelines":
             return Pipelines.remote(b.name, b.pipeline);
         case "plain_text":
             return Text.local(b.name, b.text);
-        case "queue":
+        case "queue": {
+            // A real queueId belongs to an `Alchemy.remote()` queue. Queue bindings
+            // are NOT supported in Cloudflare's remote/preview sessions — a
+            // platform limitation (cloudflare/workers-sdk#9929) — so live
+            // production goes through the deployed shim worker registered at
+            // eval time (see `Queues/QueueShim.ts`): the local binding targets a
+            // forwarder service that relays the queue wire protocol to the shim
+            // over HTTPS with a bearer token.
+            if (b.queueId !== undefined && !isLocalId(b.queueId)) {
+                const url = b.shim?.url;
+                const token = b.shim?.token;
+                if (url === undefined || token === undefined) {
+                    // Defensive: binding data produced by current eval always carries
+                    // the shim for this mode combination.
+                    return yield* new WorkerValidationError({
+                        message: `Queue binding "${b.name}" targets a live queue ` +
+                            "(Alchemy.remote()) but no producer shim was registered for it — " +
+                            "re-deploy, or remove remote() from the queue (local emulation).",
+                        value: b,
+                    });
+                }
+                return Queue.remote({
+                    binding: b.name,
+                    queueName: b.queueName,
+                    url,
+                    token: typeof token === "string" ? token : Redacted.value(token),
+                });
+            }
             return Queue.local({
                 binding: b.name,
                 queueName: b.queueName,
             });
+        }
         case "r2_bucket":
-            return R2Bucket.remote(b.name, b.bucketName, b.jurisdiction);
+            // A `dev:`-prefixed bucket name belongs to a locally-emulated bucket
+            // (R2 has no opaque id — the name is the identity); a real name is a
+            // live bucket the dev worker proxies to.
+            return isLocalId(b.bucketName)
+                ? R2Bucket.local({ binding: b.name, id: b.bucketName })
+                : R2Bucket.remote(b.name, b.bucketName, b.jurisdiction);
         case "ratelimit":
             return RateLimit.local({
                 binding: b.name,
@@ -638,7 +882,7 @@ export const toRuntimeBinding = Effect.fn(function* (b) {
         case "secrets_store_secret":
             return yield* unsupported();
         case "send_email":
-            return SendEmail.remote({
+            return SendEmail[dev?.remote ? "remote" : "local"]({
                 binding: b.name,
                 destinationAddress: b.destinationAddress,
                 allowedDestinationAddresses: b.allowedDestinationAddresses,
@@ -671,62 +915,36 @@ export const toRuntimeBinding = Effect.fn(function* (b) {
             return yield* unsupported();
     }
 });
-/**
- * Stable, collision-free structural signature used to decide whether a
- * locally-running dev Worker needs to be torn down and restarted.
- *
- * We deliberately do NOT use `Hash.structure` here: Effect's structural
- * hash folds sibling fields together with XOR, so when the *same* value
- * change appears in two sibling subtrees the diffs cancel and the hash is
- * unchanged. The Worker config mirrors `env` values into `bindings`
- * (e.g. `DEV_MARKER`/an R2 bucket name appear in both `props.env` and the
- * derived `bindings`), which is exactly the shape that collides — so an
- * env-only or rebind change would be silently treated as "no change" and
- * the dev Worker would never restart with the new bindings.
- *
- * A canonical JSON serialization (sorted keys, unwrapped `Redacted`,
- * cycle-safe) gives an exact comparison instead of a lossy fingerprint. We
- * hash that serialization with SHA-256 so each retained signature is a fixed
- * 64-char digest rather than a copy of the whole props/bindings blob.
- */
-const structuralSignature = (value) => {
-    const seen = new WeakSet();
-    const normalize = (input) => {
-        if (typeof input === "bigint")
-            return `bigint:${input.toString()}`;
-        if (input === null || typeof input !== "object")
-            return input;
-        if (Redacted.isRedacted(input)) {
-            return { __redacted: normalize(Redacted.value(input)) };
-        }
-        if (seen.has(input))
-            return "[circular]";
-        seen.add(input);
-        if (input instanceof Uint8Array)
-            return { __bytes: Array.from(input) };
-        if (Array.isArray(input))
-            return input.map(normalize);
-        return Object.fromEntries(Object.keys(input)
-            .sort()
-            .map((key) => [
-            key,
-            normalize(input[key]),
-        ]));
-    };
-    return sha256(JSON.stringify(normalize(value)));
-};
-const toRuntimeAssets = (assets) => {
+const toRuntimeAssets = Effect.fn(function* (assets) {
     if (!assets)
         return undefined;
+    // Mirror the deploy path: the special `_headers` / `_redirects` files
+    // in the assets directory carry the rules unless overridden by
+    // explicit `headers` / `redirects` props. The local runtime parses
+    // the raw string contents just like Cloudflare does.
+    //
+    // A Vite website's `assets` is config-only (`{ runWorkerFirst: true }`) —
+    // the client output directory is the build's business, and in `dev` the
+    // vite plugin serves assets from the dev server, so there is no directory
+    // to read here.
+    const directory = typeof assets === "string" ? assets : assets.directory;
+    // An unreadable file just means no rules here — the assets plugin
+    // reports directory problems itself.
+    const files = yield* readAssetsConfigFiles(directory).pipe(Effect.orElseSucceed(() => ({
+        _headers: undefined,
+        _redirects: undefined,
+    })));
     if (typeof assets === "string") {
         return {
             directory: assets,
+            headers: files._headers,
+            redirects: files._redirects,
         };
     }
     return {
         directory: assets.directory,
-        headers: assets.headers,
-        redirects: assets.redirects,
+        headers: assets.headers ?? files._headers,
+        redirects: assets.redirects ?? files._redirects,
         // Distilled widened generated string enums to open unions (`string & {}`);
         // the API only ever returns the known variants here.
         htmlHandling: assets.htmlHandling,
@@ -734,7 +952,7 @@ const toRuntimeAssets = (assets) => {
         runWorkerFirst: assets.runWorkerFirst,
         serveDirectly: assets.serveDirectly,
     };
-};
+});
 const moduleTypeFromExtension = (ext) => {
     switch (ext) {
         case ".wasm":