sproutboat 0.11.12 → 0.12.0

package/CHANGELOG.md

@@ -8,6 +8,35 @@ a breaking change.
 Reconstructed from git history on 2026-09-03 for everything through v0.4.11;
 maintained going forward by the `release` skill.
 
+## Unreleased
+
+## [0.12.0] - 2026-09-28
+
+### Added
+- Run three original Cloudflare Worker examples unchanged: JSON responses,
+  cookie parsing, and redirects. The example suite now checks 21 native apps.
+- Pass `(request, env, ctx)` to fetch handlers using the 2026-09-28
+  compatibility date while preserving the earlier two-argument form for older apps.
+
+### Changed
+- Update to Porffor alpha 10 via `@sproutboat/toolchain@^0.4.14` and use
+  `@sproutboat/runtime@^0.13.0` for native request decoding and redirects.
+
+## [0.11.13] - 2026-09-26
+
+### Added
+- Record compile duration in the artifact manifest so the platform can show it per deployment.
+- Support selected `node:path`, `node:url`, and `node:querystring` APIs in handlers.
+
+### Changed
+- Reuse checksum-verified native binaries for identical release builds and
+  refresh broker asset sidecars without recompiling the handler.
+- Report native compilation time and binary cache status after `build`.
+- Reject unsupported service bindings before starting a standalone build.
+- Fetch the pinned Mozilla CA bundle from curl's dated archive so new upstream
+  revisions do not break fresh standalone builds.
+- Update the pinned toolchain to `0.4.13` and the artifact contract to `0.3.0`.
+
 ## [0.11.12] - 2026-09-24
 
 ### Changed
@@ -610,7 +639,9 @@ its own package.
 - Renamed the package to `sproutboat` (was `@sproutboat/cli`); dropped the
   `sprout` bin alias in favour of a user-defined shell alias.
 
-[Unreleased]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.12...HEAD
+[Unreleased]: https://github.com/baronunread/sproutboat-cli/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.13...v0.12.0
+[0.11.13]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.12...v0.11.13
 [0.11.12]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.11...v0.11.12
 [0.11.11]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.10...v0.11.11
 [0.11.10]: https://github.com/baronunread/sproutboat-cli/compare/v0.11.9...v0.11.10

package/SURFACE.md

@@ -3,7 +3,7 @@
 > Generated by `src/surface.test.ts` from `src/surface.ts` + the pinned
 > toolchain constants. Do not edit by hand — run `UPDATE_SURFACE=1 bun test`.
 
-**Package:** `sproutboat` 0.11.12 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.12.0 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -76,7 +76,7 @@ usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev
 | | |
 | --- | --- |
 | Zig | `0.16.0` (`zig cc -target x86_64-linux-musl`, static) |
-| Provenance stamp | `zig-musl/0.16.0+porffor/de4eb58+uws/360c276d` |
+| Provenance stamp | `zig-musl/0.16.0+porffor/08ac7ee+uws/360c276d` |
 | Artifact schema | `2` |
 | Runtime | `native-fetch` |
 | Capability profile | `http-sync-v0` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.11.12",
+  "version": "0.12.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -61,26 +61,27 @@
     "kitchen-sink:standalone": "bun examples/kitchen-sink/harness-standalone.ts"
   },
   "dependencies": {
-    "@sproutboat/artifact": "^0.2.0",
+    "@sproutboat/artifact": "^0.3.0",
     "@sproutboat/assets": "^0.3.0",
     "@sproutboat/config": "^0.4.0",
-    "@sproutboat/runtime": "^0.12.1",
-    "@sproutboat/toolchain": "^0.4.12",
+    "@sproutboat/runtime": "^0.13.0",
+    "@sproutboat/toolchain": "^0.4.14",
     "@sproutboat/wire": "^0.9.1"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.81.0",
     "@types/bun": "1.4.0",
+    "cookie": "2.0.1",
     "lefthook": "2.1.12",
     "oxfmt": "0.66.0",
     "oxlint": "1.81.0",
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
-    "@sproutboat/cli-darwin-arm64": "0.11.12",
-    "@sproutboat/cli-darwin-x64": "0.11.12",
-    "@sproutboat/cli-linux-arm64": "0.11.12",
-    "@sproutboat/cli-linux-x64": "0.11.12"
+    "@sproutboat/cli-darwin-arm64": "0.12.0",
+    "@sproutboat/cli-darwin-x64": "0.12.0",
+    "@sproutboat/cli-linux-arm64": "0.12.0",
+    "@sproutboat/cli-linux-x64": "0.12.0"
   },
   "engines": {
     "node": ">=18"

package/src/bearssl.ts

@@ -34,7 +34,8 @@ const BEARSSL_SHA256 = "6705bba1714961b41a728dfc5debbe348d2966c117649392f8c8139e
  * release is unknown until the next one. Fine while releases are frequent;
  * revisit if a user is ever stuck on an old CLI for months.
  */
-const CACERT_URL = "https://curl.se/ca/cacert.pem";
+// Use the dated archive so its bytes stay equal to the pinned digest.
+const CACERT_URL = "https://curl.se/ca/cacert-2026-08-13.pem";
 const CACERT_SHA256 = "f66dff1bdf8f96060b8177976f8b7d9254bc89bc4db933d769f7384d28480bc9";
 
 const cacheDir = (): string =>

package/src/build.ts

@@ -1,12 +1,13 @@
-import { createHash } from "node:crypto";
-import { cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import { walkAssets, type AssetManifest } from "./assets";
 import { resourceRefs, type SproutboatConfig } from "./config";
 import { ensureSqliteObject } from "./sqlite";
 import { sqliteStamp } from "./sqlite";
 import { bearsslStamp, ensureBearssl } from "./bearssl";
-import { compileSprout, type Transport } from "./compile";
+import { compileSprout, loadPrelude, type Transport } from "./compile";
+import { compileCached } from "./compile-cache";
 import {
   ARTIFACT_SCHEMA_VERSION,
   CAPABILITY_PROFILE,
@@ -16,6 +17,10 @@ import {
   type ArtifactManifest,
 } from "./manifest";
 import { ensureZig, esbuildVersion, porfforVersion, toolchainStamp } from "./toolchain";
+import { PORFFOR_ARCHIVE_SHA256, PORFFOR_COMMIT_FULL } from "./porffor-toolchain";
+import { version as toolchainPackageVersion } from "@sproutboat/toolchain/package.json" with { type: "json" };
+import { version as cliVersion } from "../package.json" with { type: "json" };
+import { wrapNativeFetchHandler } from "./wrap";
 
 export type BuildInput = {
   projectDir: string;
@@ -54,6 +59,8 @@ export type BuildInput = {
 export type BuildOutput = {
   artifactDir: string;
   manifest: ArtifactManifest;
+  compileCache: "hit" | "miss" | "bypass";
+  compileMs: number;
 };
 
 /** Baking megabytes of assets into the module makes the Porffor compile crawl;
@@ -64,6 +71,45 @@ function digest(value: Uint8Array | string): `sha256:${string}` {
   return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }
 
+async function integrationIdentity(): Promise<string> {
+  // A published CLI has immutable bundled integration code and a release
+  // version. Source checkouts also hash their live files, so local edits never
+  // accidentally reuse a binary compiled by an earlier checkout state.
+  if (import.meta.url.includes("/$bunfs/")) {
+    const executable = await stat(process.execPath);
+    return `release:${cliVersion}:${executable.size}:${executable.mtimeMs}`;
+  }
+  const files = ["build.ts", "compile.ts", "sqlite.ts", "bearssl.ts", "toolchain.ts"].map((file) =>
+    resolve(import.meta.dir, file),
+  );
+  // Hash the patch implementation and its local modules so a Unicode patch
+  // edit cannot reuse a binary compiled with earlier builtin semantics.
+  const patchDir = dirname(Bun.resolveSync("@sproutboat/toolchain/patch", import.meta.dir));
+  const toolchainFiles = (await readdir(patchDir))
+    .filter((file) => file.endsWith(".ts") && !file.endsWith(".test.ts"))
+    .sort();
+  files.push(...toolchainFiles.map((file) => resolve(patchDir, file)));
+  return digest(Buffer.concat(await Promise.all(files.map((file) => readFile(file)))));
+}
+
+async function acquireArtifactLock(artifactDir: string): Promise<string> {
+  const lock = `${artifactDir}.lock`;
+  await mkdir(dirname(lock), { recursive: true });
+  const deadline = Date.now() + 12 * 60_000;
+  while (true) {
+    try {
+      await mkdir(lock);
+      return lock;
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+      if (Date.now() > deadline) throw new Error(`timed out waiting for artifact lock ${lock}`);
+      const info = await stat(lock).catch(() => null);
+      if (info && Date.now() - info.mtimeMs > 15 * 60_000) await rm(lock, { recursive: true, force: true });
+      else await Bun.sleep(100);
+    }
+  }
+}
+
 /**
  * Cross-compile a handler into a linux-x86_64 native-fetch server binary with
  * Porffor + Zig — no Docker. The binary is not run here (the build host may not
@@ -75,30 +121,6 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
   const sourceHash = digest(source);
   const target = input.target ?? "linux-x86_64";
   const embedded = input.transport === "embedded";
-  // The directory identity must change whenever an input that changes the
-  // generated C or link line changes. A source digest alone reused an artifact
-  // path across compiler pins, targets, and standalone ABI settings.
-  const artifactId = digest(
-    JSON.stringify({
-      sourceHash,
-      target,
-      transport: input.transport ?? "broker",
-      optimize: input.optimize ?? "release",
-      compatibilityDate: input.config.compatibility_date,
-      config: input.config,
-      toolchain: toolchainStamp(),
-      compiler:
-        target === "host"
-          ? `host:${process.env.CC ?? "cc"}`
-          : process.env.SPROUTBOAT_ZIG
-            ? `override:${process.env.SPROUTBOAT_ZIG}`
-            : "managed-zig",
-      native: embedded ? [sqliteStamp(), bearsslStamp()] : [],
-    }),
-  ).slice("sha256:".length, 24);
-  const artifactDir = input.outputDirectory ?? resolve(input.projectDir, ".sproutboat/dist", artifactId);
-  const sproutPath = resolve(artifactDir, "sprout");
-  await mkdir(artifactDir, { recursive: true });
 
   // #74 — split each storage-binding array into its binding-name list (the
   // legacy shape the prelude/broker read) plus a `resources` map { binding ->
@@ -134,33 +156,34 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     resources,
   };
 
-  // A host build never shells out to `zig`, so do not fetch a 50 MB toolchain
-  // for it — that download is the slowest part of a first local build.
-  const host = input.target === "host";
-  const zigBin = host ? undefined : await ensureZig();
-  // #15 — an embedded sprout carries its own storage and TLS instead of talking
-  // to a broker: SQLite and BearSSL are compiled once per target and added to
-  // the link line, and BearSSL's header to the compile line.
-  const sqliteObject = embedded ? await ensureSqliteObject({ target, zigBin }) : null;
-  const tls = embedded ? await ensureBearssl({ target, zigBin }) : null;
-  const extraLink = [...(sqliteObject ? [sqliteObject] : []), ...(tls ? tls.objects : [])];
-  const extraCflags = tls ? ["-I", tls.includeDir] : [];
+  const host = target === "host";
+  const assetDir = input.config.assets ? resolve(input.projectDir, input.config.assets.directory) : undefined;
+  if (
+    assetDir &&
+    !(await stat(assetDir)
+      .then((s) => s.isDirectory())
+      .catch(() => false))
+  ) {
+    throw new Error(`assets.directory "${input.config.assets?.directory}" not found — run your site build first`);
+  }
+  const assetManifest: AssetManifest | undefined =
+    assetDir && input.config.assets
+      ? {
+          notFound: input.config.assets.not_found_handling ?? "none",
+          runSproutFirst: input.config.assets.run_sprout_first ?? false,
+          files: walkAssets(assetDir),
+        }
+      : undefined;
   // #15 — an embedded binary has no files beside it, so assets are baked into
   // the module. Read them from the source directory: the artifact copy happens
   // after the compile, and the compile is what needs them. Bytes travel as a
   // latin1 string, one char per byte, which is what the asset shim hands back.
   let bakedAssets: { manifest: AssetManifest; files: Record<string, string> } | undefined;
-  if (input.transport === "embedded" && input.config.assets) {
-    const dir = resolve(input.projectDir, input.config.assets.directory);
-    const manifest: AssetManifest = {
-      notFound: input.config.assets.not_found_handling ?? "none",
-      runSproutFirst: input.config.assets.run_sprout_first ?? false,
-      files: walkAssets(dir),
-    };
+  if (embedded && assetDir && assetManifest) {
     const files: Record<string, string> = {};
     let total = 0;
-    for (const key of Object.keys(manifest.files)) {
-      const bytes = await readFile(resolve(dir, `.${key}`));
+    for (const key of Object.keys(assetManifest.files)) {
+      const bytes = await readFile(resolve(assetDir, `.${key}`));
       total += bytes.byteLength;
       if (total > MAX_BAKED_ASSET_BYTES) {
         throw new Error(
@@ -170,86 +193,156 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
       }
       files[key] = bytes.toString("latin1");
     }
-    bakedAssets = { manifest, files };
+    bakedAssets = { manifest: assetManifest, files };
   }
 
-  // Hoisted above the compile: #126 bakes it into the binary, and the manifest
-  // records the same instant rather than a slightly later one.
+  // Version metadata is compiled into the executable. Its timestamp makes a
+  // new binary necessary on every build when this binding is configured.
   const builtAt = new Date().toISOString();
+  const versionId = digest(
+    JSON.stringify({ sourceHash, target, config: input.config, assets: assetManifest, toolchain: toolchainStamp() }),
+  ).slice("sha256:".length, 24);
   const versionMetadata = input.config.version_metadata
-    ? { binding: input.config.version_metadata, id: artifactId, tag: input.config.name, timestamp: builtAt }
+    ? { binding: input.config.version_metadata, id: versionId, tag: input.config.name, timestamp: builtAt }
     : undefined;
+  const generatedSource = wrapNativeFetchHandler(
+    source.toString(),
+    await loadPrelude(input.transport ?? "broker"),
+    input.config.vars ?? {},
+    bindings,
+    undefined,
+    input.config.compatibility_date,
+    input.config.name,
+    bakedAssets,
+    input.transport,
+    versionMetadata,
+  );
+  const compileKey = digest(
+    JSON.stringify({
+      generatedSource,
+      target,
+      optimize: input.optimize ?? "release",
+      toolchain: toolchainStamp(),
+      toolchainPackageVersion,
+      porffor: [PORFFOR_COMMIT_FULL, PORFFOR_ARCHIVE_SHA256],
+      native: embedded ? [sqliteStamp(), bearsslStamp()] : [],
+      integration: await integrationIdentity(),
+    }),
+  ).slice("sha256:".length);
+  const artifactId = versionMetadata
+    ? versionId
+    : digest(JSON.stringify({ compileKey, config: input.config, assets: assetManifest })).slice("sha256:".length, 24);
+  const artifactDir = input.outputDirectory ?? resolve(input.projectDir, ".sproutboat/dist", artifactId);
+  const sproutPath = resolve(artifactDir, "sprout");
+  const artifactLock = await acquireArtifactLock(artifactDir);
+  try {
+    await mkdir(artifactDir, { recursive: true });
 
-  if (input.reuseSproutPath) await cp(input.reuseSproutPath, sproutPath);
-  else
-    await compileSprout({
-      sourcePath: input.sourcePath,
-      generatedPath: input.generatedPath,
-      source: input.source,
-      outPath: sproutPath,
-      vars: input.config.vars ?? {},
-      bindings,
-      zigBin,
-      target: input.target,
-      compatibilityDate: input.config.compatibility_date,
-      transport: input.transport,
-      appName: input.config.name,
-      assets: bakedAssets,
-      extraLink,
-      extraCflags,
-      optimize: input.optimize,
-      versionMetadata,
-    });
-
-  const sprout = await readFile(sproutPath);
-  const manifest: ArtifactManifest = {
-    schemaVersion: ARTIFACT_SCHEMA_VERSION,
-    project: input.config.name,
-    target: host ? hostTarget() : DEPLOY_TARGET,
-    runtime: RUNTIME,
-    capabilityProfile: CAPABILITY_PROFILE,
-    porfforVersion: porfforVersion(),
-    esbuildVersion: esbuildVersion(),
-    buildImage: toolchainStamp(),
-    compatibilityDate: input.config.compatibility_date,
-    sourceHash,
-    binaryHash: digest(sprout),
-    binarySize: (await stat(sproutPath)).size,
-    builtAt,
-  };
-  await writeFile(resolve(artifactDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-  // Bindings live beside the manifest, not in it: the artifact manifest schema is
-  // frozen at v2. The control plane reads this to configure the per-deployment
-  // broker (KV / D1 / R2 / queue names, secret names, outbound allowlist, cron
-  // schedules, Durable Object classes).
-  const hasBindings =
-    Object.values(bindings).some((value) => Array.isArray(value) && value.length > 0) ||
-    Object.keys(bindings.resources).length > 0 ||
-    Object.keys(bindings.vars).length > 0;
-  if (hasBindings) {
-    await writeFile(resolve(artifactDir, "bindings.json"), `${JSON.stringify(bindings, null, 2)}\n`);
-  }
-
-  // Static assets: copy the directory next to the artifact and record a manifest
-  // the edge serves from directly (assets-first) and the broker reads for
-  // `env.<ASSETS>.fetch()`.
-  if (input.config.assets) {
-    const srcDir = resolve(input.projectDir, input.config.assets.directory);
-    const outDir = resolve(artifactDir, "assets");
+    const compile = async (outPath: string) => {
+      // Acquire native inputs only after a cache miss. A host build never needs
+      // the cross-compiler; embedded builds link SQLite and BearSSL as well.
+      const zigBin = host ? undefined : await ensureZig();
+      const [sqliteObject, tls] = embedded
+        ? await Promise.all([ensureSqliteObject({ target, zigBin }), ensureBearssl({ target, zigBin })])
+        : [null, null];
+      await compileSprout({
+        sourcePath: input.sourcePath,
+        generatedPath: input.generatedPath,
+        generatedSource,
+        outPath,
+        vars: input.config.vars ?? {},
+        bindings,
+        zigBin,
+        target: input.target,
+        compatibilityDate: input.config.compatibility_date,
+        transport: input.transport,
+        appName: input.config.name,
+        assets: bakedAssets,
+        extraLink: [...(sqliteObject ? [sqliteObject] : []), ...(tls ? tls.objects : [])],
+        extraCflags: tls ? ["-I", tls.includeDir] : [],
+        optimize: input.optimize,
+        versionMetadata,
+      });
+    };
+    let compileCache: BuildOutput["compileCache"] = "bypass";
+    const compileStartedAt = performance.now();
     if (
-      !(await stat(srcDir)
-        .then((s) => s.isDirectory())
-        .catch(() => false))
+      !input.reuseSproutPath &&
+      !host &&
+      input.optimize !== "dev" &&
+      !input.outputDirectory &&
+      !versionMetadata &&
+      !process.env.SPROUTBOAT_PORFFOR_DIR &&
+      !process.env.SPROUTBOAT_ZIG &&
+      !process.env.SPROUTBOAT_UWS_TARBALL &&
+      !process.env.SPROUTBOAT_BUILD_UWS_FROM_SOURCE &&
+      !process.env.PORFFOR_VERSION
     ) {
-      throw new Error(`assets.directory "${input.config.assets.directory}" not found — run your site build first`);
+      compileCache = await compileCached(
+        resolve(input.projectDir, ".sproutboat/compile-cache"),
+        compileKey,
+        sproutPath,
+        compile,
+      );
+    } else {
+      const candidate = resolve(artifactDir, `.sprout-${randomUUID()}`);
+      try {
+        if (input.reuseSproutPath) await cp(input.reuseSproutPath, candidate);
+        else await compile(candidate);
+        await rename(candidate, sproutPath);
+      } finally {
+        await rm(candidate, { force: true });
+      }
     }
-    await cp(srcDir, outDir, { recursive: true });
-    const assetManifest: AssetManifest = {
-      notFound: input.config.assets.not_found_handling ?? "none",
-      runSproutFirst: input.config.assets.run_sprout_first ?? false,
-      files: walkAssets(outDir),
+    const compileMs = Math.round(performance.now() - compileStartedAt);
+
+    const sprout = await readFile(sproutPath);
+    const manifest: ArtifactManifest & { compileMs: number } = {
+      schemaVersion: ARTIFACT_SCHEMA_VERSION,
+      project: input.config.name,
+      target: host ? hostTarget() : DEPLOY_TARGET,
+      runtime: RUNTIME,
+      capabilityProfile: CAPABILITY_PROFILE,
+      porfforVersion: porfforVersion(),
+      esbuildVersion: esbuildVersion(),
+      buildImage: toolchainStamp(),
+      compatibilityDate: input.config.compatibility_date,
+      sourceHash,
+      binaryHash: digest(sprout),
+      binarySize: (await stat(sproutPath)).size,
+      compileMs,
+      builtAt,
     };
-    await writeFile(resolve(artifactDir, "assets.json"), `${JSON.stringify(assetManifest, null, 2)}\n`);
+    await writeFile(resolve(artifactDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    // Bindings live beside the manifest, not in it: the artifact manifest schema is
+    // frozen at v2. The control plane reads this to configure the per-deployment
+    // broker (KV / D1 / R2 / queue names, secret names, outbound allowlist, cron
+    // schedules, Durable Object classes).
+    const hasBindings =
+      Object.values(bindings).some((value) => Array.isArray(value) && value.length > 0) ||
+      Object.keys(bindings.resources).length > 0 ||
+      Object.keys(bindings.vars).length > 0;
+    if (hasBindings) {
+      await writeFile(resolve(artifactDir, "bindings.json"), `${JSON.stringify(bindings, null, 2)}\n`);
+    } else await rm(resolve(artifactDir, "bindings.json"), { force: true });
+
+    // Static assets: copy the directory next to the artifact and record a manifest
+    // the edge serves from directly (assets-first) and the broker reads for
+    // `env.<ASSETS>.fetch()`.
+    if (assetDir && assetManifest) {
+      const outDir = resolve(artifactDir, "assets");
+      await rm(outDir, { recursive: true, force: true });
+      await cp(assetDir, outDir, { recursive: true });
+      if (JSON.stringify(walkAssets(outDir)) !== JSON.stringify(assetManifest.files)) {
+        throw new Error("assets changed during the build; retry after the asset build finishes");
+      }
+      await writeFile(resolve(artifactDir, "assets.json"), `${JSON.stringify(assetManifest, null, 2)}\n`);
+    } else {
+      await rm(resolve(artifactDir, "assets.json"), { force: true });
+      await rm(resolve(artifactDir, "assets"), { recursive: true, force: true });
+    }
+    return { artifactDir, manifest, compileCache, compileMs };
+  } finally {
+    await rm(artifactLock, { recursive: true, force: true });
   }
-  return { artifactDir, manifest };
 }

package/src/bundle.ts

@@ -1,7 +1,7 @@
 /**
  * #89 — bundle the handler before Porffor sees it.
  *
- * Porffor alpha 9 supports ESM imports. We still bundle first so capability
+ * Porffor supports ESM imports. We still bundle first so capability
  * validation sees every dependency and the runtime wrapper receives one
  * controlled default export.
  *
@@ -12,6 +12,7 @@
  * reaching for a Node API fails exactly as user code would.
  */
 import { relative } from "node:path";
+import { NODE_SHIMS } from "./node-shims";
 
 export type BundleResult = {
   /** One self-contained ESM module: what gets validated, hashed, and compiled. */
@@ -27,6 +28,32 @@ export class BundleError extends Error {
 
 const entryLabel = (entryPath: string, projectDir: string): string => relative(projectDir, entryPath) || entryPath;
 
+const shimSpecifiers = new RegExp(
+  `^(${Object.keys(NODE_SHIMS)
+    .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("|")})$`,
+);
+
+/**
+ * Bun already bundles working polyfills for most node:* built-ins under
+ * `target: "browser"` (verified for node:url, node:querystring). This
+ * plugin only overrides the ones in NODE_SHIMS — currently just node:path,
+ * whose bundled resolve() otherwise falls back to `process.cwd()`.
+ */
+const nodeShimsPlugin: import("bun").BunPlugin = {
+  name: "sproutboat-node-shims",
+  setup(build) {
+    build.onResolve({ filter: shimSpecifiers }, (args) => ({ path: args.path, namespace: "sb-node-shim" }));
+    build.onLoad({ filter: /.*/, namespace: "sb-node-shim" }, (args) => ({
+      // SAFETY: onResolve above only ever routes a specifier matched by
+      // shimSpecifiers (built from NODE_SHIMS's own keys) into this
+      // namespace, so args.path is always one of NODE_SHIMS's keys here.
+      contents: (NODE_SHIMS as Record<string, string>)[args.path],
+      loader: "js",
+    }));
+  },
+};
+
 /** Bun reports resolution failures on `AggregateError.errors`; its own message is just "Bundle failed". */
 function bundleDetail(cause: unknown): string {
   const errors = cause instanceof AggregateError ? cause.errors : [];
@@ -51,6 +78,7 @@ export async function bundleHandler(entryPath: string, projectDir: string): Prom
       minify: false,
       splitting: false,
       sourcemap: "none",
+      plugins: [nodeShimsPlugin],
     });
   } catch (cause) {
     // An unresolvable specifier arrives as an AggregateError whose `errors`

package/src/compile-cache.ts

@@ -0,0 +1,98 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+type CacheRecord = { key: string; hash: string; size: number };
+
+function digest(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+async function verified(entry: string, key: string): Promise<Buffer | null> {
+  try {
+    // SAFETY: cache.json is private cache data; the key, metadata and binary
+    // digest are all checked before this entry can be used.
+    const record = JSON.parse(await readFile(resolve(entry, "cache.json"), "utf8")) as CacheRecord;
+    if (record.key !== key) return null;
+    const path = resolve(entry, "sprout");
+    const info = await stat(path);
+    if (!info.isFile() || (info.mode & 0o111) === 0 || info.size !== record.size) return null;
+    const bytes = await readFile(path);
+    return digest(bytes) === record.hash ? bytes : null;
+  } catch {
+    return null;
+  }
+}
+
+async function publish(bytes: Uint8Array, outPath: string): Promise<void> {
+  await mkdir(dirname(outPath), { recursive: true });
+  const candidate = `${outPath}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(candidate, bytes);
+    await chmod(candidate, 0o555);
+    await rename(candidate, outPath);
+  } finally {
+    await rm(candidate, { force: true });
+  }
+}
+
+/** A per-project binary cache. The lock covers compilation and publication, so
+ * another process can only read a complete, checksum-verified entry. */
+export async function compileCached(
+  cacheRoot: string,
+  key: string,
+  outPath: string,
+  compile: (candidatePath: string) => Promise<void>,
+): Promise<"hit" | "miss"> {
+  const entry = resolve(cacheRoot, key);
+  const cached = await verified(entry, key);
+  if (cached) {
+    await publish(cached, outPath);
+    return "hit";
+  }
+  await mkdir(cacheRoot, { recursive: true });
+  const lock = `${entry}.lock`;
+  const deadline = Date.now() + 12 * 60_000;
+  while (true) {
+    try {
+      await mkdir(lock);
+      break;
+    } catch (error) {
+      // SAFETY: Node filesystem errors expose code; unrelated failures are
+      // rethrown instead of being treated as a held lock.
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const ready = await verified(entry, key);
+      if (ready) {
+        await publish(ready, outPath);
+        return "hit";
+      }
+      if (Date.now() > deadline) throw new Error(`timed out waiting for compile cache lock ${lock}`);
+      const lockInfo = await stat(lock).catch(() => null);
+      if (lockInfo && Date.now() - lockInfo.mtimeMs > 15 * 60_000) await rm(lock, { recursive: true, force: true });
+      else await Bun.sleep(100);
+    }
+  }
+  let stage: string | undefined;
+  try {
+    const ready = await verified(entry, key);
+    if (ready) {
+      await publish(ready, outPath);
+      return "hit";
+    }
+    await rm(entry, { recursive: true, force: true });
+    stage = await mkdtemp(resolve(cacheRoot, `.candidate-${key}-`));
+    const candidate = resolve(stage, "sprout");
+    await compile(candidate);
+    const bytes = await readFile(candidate);
+    const record: CacheRecord = { key, hash: digest(bytes), size: bytes.byteLength };
+    await chmod(candidate, 0o555);
+    await writeFile(resolve(stage, "cache.json"), JSON.stringify(record));
+    await rename(stage, entry);
+    stage = undefined;
+    await publish(bytes, outPath);
+    return "miss";
+  } finally {
+    if (stage) await rm(stage, { recursive: true, force: true });
+    await rm(lock, { recursive: true, force: true });
+  }
+}

package/src/compile.ts

@@ -53,6 +53,8 @@ export type CompileInput = {
   generatedPath?: string;
   /** The bundled module (#89). Falls back to reading `sourcePath` verbatim. */
   source?: string;
+  /** The exact wrapped module used to compute a verified compile-cache key. */
+  generatedSource?: string;
   outPath: string;
   vars: Record<string, string>;
   bindings?: Bindings;
@@ -198,25 +200,27 @@ export async function compileSprout(input: CompileInput): Promise<void> {
   await rm(input.outPath, { force: true });
   const generatedPath = input.generatedPath ?? resolve(outDir, "sprout.generated.js");
   await mkdir(dirname(generatedPath), { recursive: true });
-  const [source, prelude] = await Promise.all([
-    input.source === undefined ? readFile(input.sourcePath, "utf8") : Promise.resolve(input.source),
-    loadPrelude(input.transport ?? "broker"),
-  ]);
-  await writeFile(
-    generatedPath,
-    wrapNativeFetchHandler(
-      source,
-      prelude,
-      input.vars,
-      input.bindings ?? EMPTY_BINDINGS,
-      undefined,
-      input.compatibilityDate,
-      input.appName,
-      input.assets,
-      input.transport,
-      input.versionMetadata,
-    ),
-  );
+  const generatedSource =
+    input.generatedSource ??
+    (await (async () => {
+      const [source, prelude] = await Promise.all([
+        input.source === undefined ? readFile(input.sourcePath, "utf8") : Promise.resolve(input.source),
+        loadPrelude(input.transport ?? "broker"),
+      ]);
+      return wrapNativeFetchHandler(
+        source,
+        prelude,
+        input.vars,
+        input.bindings ?? EMPTY_BINDINGS,
+        undefined,
+        input.compatibilityDate,
+        input.appName,
+        input.assets,
+        input.transport,
+        input.versionMetadata,
+      );
+    })());
+  await writeFile(generatedPath, generatedSource);
 
   const launcher = resolve(porffor, "runtime/index.js");
   // A musl build shells `zig` bare (Porffor hardcodes the literal command), so

package/src/main.ts

@@ -319,6 +319,7 @@ async function build(directory?: string, target: "linux-x86_64" | "host" = "linu
     target,
   });
   console.log(ok(`built ${project.config.name}`));
+  console.log(dim(`  compile  ${artifact.compileMs} ms · binary cache ${artifact.compileCache}`));
   if (target === "host")
     console.log(dim("  host build — runs here, not deployable; drop --target host to build for a box"));
   console.log(artifact.artifactDir);

package/src/node-shims.ts

@@ -0,0 +1,378 @@
+/**
+ * Bun's bundler ships full Node-compatible polyfills for node:path,
+ * node:url, and node:querystring under `target: "browser"`, but each has
+ * exactly one thing wrong with it for a Porffor-compiled handler — found
+ * by auditing bundled output against the capability check (source.ts) and,
+ * for node:url, by an actual failure through the real Porffor compiler.
+ * Auditing the bundle alone was not enough:
+ *
+ * - node:path's bundled `resolve()` falls back to `process.cwd()`, which
+ *   trips the `process.` ban in `../packages/runtime/src/source.ts`.
+ * - node:querystring's bundled polyfill pulls in Bun's full Buffer
+ *   implementation internally (for percent-decoding), tripping the
+ *   `Buffer.` ban.
+ * - node:url's bundled `URL`/`URLSearchParams` exports are
+ *   `var { URL, URLSearchParams } = globalThis;` — passes every capability
+ *   check (no banned pattern in it) but Porffor's compiler rejects it at
+ *   parse time as `Identifier 'URL' has already been declared`: Porffor
+ *   pre-binds `URL` as a global, and a second top-level declaration of
+ *   that exact name is a compile error, confirmed by actually building a
+ *   handler through `sproutboat build` rather than just checking the
+ *   bundle. `URL`/`URLSearchParams` are already global in a compiled
+ *   handler (see `docs/concepts/handler.mdx`), so nothing needs importing
+ *   — the fix is a shim that re-exports the globals under aliased local
+ *   names instead of declaring anything literally named `URL`.
+ *
+ * None of these are the capability check being wrong — every case is a
+ * real thing (`process.cwd()`, `Buffer`, a name Porffor itself reserves)
+ * that doesn't exist the way a compiled handler needs it to, so the shims
+ * replace it rather than the check being loosened.
+ */
+const NODE_PATH_SHIM = `
+function assertPath(path) {
+  if (typeof path !== "string")
+    throw TypeError("Path must be a string. Received " + JSON.stringify(path));
+}
+function normalizeStringPosix(path, allowAboveRoot) {
+  var res = "", lastSegmentLength = 0, lastSlash = -1, dots = 0, code;
+  for (var i = 0; i <= path.length; ++i) {
+    if (i < path.length) code = path.charCodeAt(i);
+    else if (code === 47) break;
+    else code = 47;
+    if (code === 47) {
+      if (lastSlash === i - 1 || dots === 1) {
+      } else if (lastSlash !== i - 1 && dots === 2) {
+        if (res.length < 2 || lastSegmentLength !== 2 || res.charCodeAt(res.length - 1) !== 46 || res.charCodeAt(res.length - 2) !== 46) {
+          if (res.length > 2) {
+            var lastSlashIndex = res.lastIndexOf("/");
+            if (lastSlashIndex !== res.length - 1) {
+              if (lastSlashIndex === -1) res = "", lastSegmentLength = 0;
+              else res = res.slice(0, lastSlashIndex), lastSegmentLength = res.length - 1 - res.lastIndexOf("/");
+              lastSlash = i, dots = 0;
+              continue;
+            }
+          } else if (res.length === 2 || res.length === 1) {
+            res = "", lastSegmentLength = 0, lastSlash = i, dots = 0;
+            continue;
+          }
+        }
+        if (allowAboveRoot) {
+          if (res.length > 0) res += "/..";
+          else res = "..";
+          lastSegmentLength = 2;
+        }
+      } else {
+        if (res.length > 0) res += "/" + path.slice(lastSlash + 1, i);
+        else res = path.slice(lastSlash + 1, i);
+        lastSegmentLength = i - lastSlash - 1;
+      }
+      lastSlash = i, dots = 0;
+    } else if (code === 46 && dots !== -1) ++dots;
+    else dots = -1;
+  }
+  return res;
+}
+function _format(sep, pathObject) {
+  var dir = pathObject.dir || pathObject.root, base = pathObject.base || (pathObject.name || "") + (pathObject.ext || "");
+  if (!dir) return base;
+  if (dir === pathObject.root) return dir + base;
+  return dir + sep + base;
+}
+function resolve() {
+  // Node falls back to process.cwd() here; a compiled handler has no real
+  // filesystem or cwd, so an all-relative resolve() resolves against a
+  // fixed virtual root instead.
+  var resolvedPath = "", resolvedAbsolute = false, cwd;
+  for (var i = arguments.length - 1; i >= -1 && !resolvedAbsolute; i--) {
+    var path;
+    if (i >= 0) path = arguments[i];
+    else {
+      if (cwd === undefined) cwd = "/";
+      path = cwd;
+    }
+    if (assertPath(path), path.length === 0) continue;
+    resolvedPath = path + "/" + resolvedPath, resolvedAbsolute = path.charCodeAt(0) === 47;
+  }
+  if (resolvedPath = normalizeStringPosix(resolvedPath, !resolvedAbsolute), resolvedAbsolute)
+    if (resolvedPath.length > 0) return "/" + resolvedPath;
+    else return "/";
+  else if (resolvedPath.length > 0) return resolvedPath;
+  else return ".";
+}
+function normalize(path) {
+  if (assertPath(path), path.length === 0) return ".";
+  var isAbsolute = path.charCodeAt(0) === 47, trailingSeparator = path.charCodeAt(path.length - 1) === 47;
+  if (path = normalizeStringPosix(path, !isAbsolute), path.length === 0 && !isAbsolute) path = ".";
+  if (path.length > 0 && trailingSeparator) path += "/";
+  if (isAbsolute) return "/" + path;
+  return path;
+}
+function isAbsolute(path) {
+  return assertPath(path), path.length > 0 && path.charCodeAt(0) === 47;
+}
+function join() {
+  if (arguments.length === 0) return ".";
+  var joined;
+  for (var i = 0; i < arguments.length; ++i) {
+    var arg = arguments[i];
+    if (assertPath(arg), arg.length > 0)
+      if (joined === undefined) joined = arg;
+      else joined += "/" + arg;
+  }
+  if (joined === undefined) return ".";
+  return normalize(joined);
+}
+function relative(from, to) {
+  if (assertPath(from), assertPath(to), from === to) return "";
+  if (from = resolve(from), to = resolve(to), from === to) return "";
+  var fromStart = 1;
+  for (; fromStart < from.length; ++fromStart) if (from.charCodeAt(fromStart) !== 47) break;
+  var fromEnd = from.length, fromLen = fromEnd - fromStart, toStart = 1;
+  for (; toStart < to.length; ++toStart) if (to.charCodeAt(toStart) !== 47) break;
+  var toEnd = to.length, toLen = toEnd - toStart, length = fromLen < toLen ? fromLen : toLen, lastCommonSep = -1, i = 0;
+  for (; i <= length; ++i) {
+    if (i === length) {
+      if (toLen > length) {
+        if (to.charCodeAt(toStart + i) === 47) return to.slice(toStart + i + 1);
+        else if (i === 0) return to.slice(toStart + i);
+      } else if (fromLen > length) {
+        if (from.charCodeAt(fromStart + i) === 47) lastCommonSep = i;
+        else if (i === 0) lastCommonSep = 0;
+      }
+      break;
+    }
+    var fromCode = from.charCodeAt(fromStart + i), toCode = to.charCodeAt(toStart + i);
+    if (fromCode !== toCode) break;
+    else if (fromCode === 47) lastCommonSep = i;
+  }
+  var out = "";
+  for (i = fromStart + lastCommonSep + 1; i <= fromEnd; ++i)
+    if (i === fromEnd || from.charCodeAt(i) === 47)
+      if (out.length === 0) out += "..";
+      else out += "/..";
+  if (out.length > 0) return out + to.slice(toStart + lastCommonSep);
+  else {
+    if (toStart += lastCommonSep, to.charCodeAt(toStart) === 47) ++toStart;
+    return to.slice(toStart);
+  }
+}
+function dirname(path) {
+  if (assertPath(path), path.length === 0) return ".";
+  var code = path.charCodeAt(0), hasRoot = code === 47, end = -1, matchedSlash = true;
+  for (var i = path.length - 1; i >= 1; --i)
+    if (code = path.charCodeAt(i), code === 47) {
+      if (!matchedSlash) { end = i; break; }
+    } else matchedSlash = false;
+  if (end === -1) return hasRoot ? "/" : ".";
+  if (hasRoot && end === 1) return "//";
+  return path.slice(0, end);
+}
+function basename(path, ext) {
+  if (ext !== undefined && typeof ext !== "string") throw TypeError('"ext" argument must be a string');
+  assertPath(path);
+  var start = 0, end = -1, matchedSlash = true, i;
+  if (ext !== undefined && ext.length > 0 && ext.length <= path.length) {
+    if (ext.length === path.length && ext === path) return "";
+    var extIdx = ext.length - 1, firstNonSlashEnd = -1;
+    for (i = path.length - 1; i >= 0; --i) {
+      var code = path.charCodeAt(i);
+      if (code === 47) {
+        if (!matchedSlash) { start = i + 1; break; }
+      } else {
+        if (firstNonSlashEnd === -1) matchedSlash = false, firstNonSlashEnd = i + 1;
+        if (extIdx >= 0)
+          if (code === ext.charCodeAt(extIdx)) { if (--extIdx === -1) end = i; }
+          else extIdx = -1, end = firstNonSlashEnd;
+      }
+    }
+    if (start === end) end = firstNonSlashEnd;
+    else if (end === -1) end = path.length;
+    return path.slice(start, end);
+  } else {
+    for (i = path.length - 1; i >= 0; --i)
+      if (path.charCodeAt(i) === 47) {
+        if (!matchedSlash) { start = i + 1; break; }
+      } else if (end === -1) matchedSlash = false, end = i + 1;
+    if (end === -1) return "";
+    return path.slice(start, end);
+  }
+}
+function extname(path) {
+  assertPath(path);
+  var startDot = -1, startPart = 0, end = -1, matchedSlash = true, preDotState = 0;
+  for (var i = path.length - 1; i >= 0; --i) {
+    var code = path.charCodeAt(i);
+    if (code === 47) {
+      if (!matchedSlash) { startPart = i + 1; break; }
+      continue;
+    }
+    if (end === -1) matchedSlash = false, end = i + 1;
+    if (code === 46) { if (startDot === -1) startDot = i; else if (preDotState !== 1) preDotState = 1; }
+    else if (startDot !== -1) preDotState = -1;
+  }
+  if (startDot === -1 || end === -1 || preDotState === 0 || preDotState === 1 && startDot === end - 1 && startDot === startPart + 1) return "";
+  return path.slice(startDot, end);
+}
+function format(pathObject) {
+  if (pathObject === null || typeof pathObject !== "object")
+    throw TypeError('The "pathObject" argument must be of type Object. Received type ' + typeof pathObject);
+  return _format("/", pathObject);
+}
+function parse(path) {
+  assertPath(path);
+  var ret = { root: "", dir: "", base: "", ext: "", name: "" };
+  if (path.length === 0) return ret;
+  var code = path.charCodeAt(0), isAbsolute2 = code === 47, start;
+  if (isAbsolute2) ret.root = "/", start = 1;
+  else start = 0;
+  var startDot = -1, startPart = 0, end = -1, matchedSlash = true, i = path.length - 1, preDotState = 0;
+  for (; i >= start; --i) {
+    if (code = path.charCodeAt(i), code === 47) {
+      if (!matchedSlash) { startPart = i + 1; break; }
+      continue;
+    }
+    if (end === -1) matchedSlash = false, end = i + 1;
+    if (code === 46) { if (startDot === -1) startDot = i; else if (preDotState !== 1) preDotState = 1; }
+    else if (startDot !== -1) preDotState = -1;
+  }
+  if (startDot === -1 || end === -1 || preDotState === 0 || preDotState === 1 && startDot === end - 1 && startDot === startPart + 1) {
+    if (end !== -1)
+      if (startPart === 0 && isAbsolute2) ret.base = ret.name = path.slice(1, end);
+      else ret.base = ret.name = path.slice(startPart, end);
+  } else {
+    if (startPart === 0 && isAbsolute2) ret.name = path.slice(1, startDot), ret.base = path.slice(1, end);
+    else ret.name = path.slice(startPart, startDot), ret.base = path.slice(startPart, end);
+    ret.ext = path.slice(startDot, end);
+  }
+  if (startPart > 0) ret.dir = path.slice(0, startPart - 1);
+  else if (isAbsolute2) ret.dir = "/";
+  return ret;
+}
+var sep = "/";
+var delimiter = ":";
+var path = { resolve, normalize, isAbsolute, join, relative, dirname, basename, extname, format, parse, sep, delimiter };
+path.posix = path;
+path.win32 = path;
+export default path;
+export { resolve, normalize, isAbsolute, join, relative, dirname, basename, extname, format, parse, sep, delimiter };
+`;
+
+/**
+ * node:querystring's bundled polyfill pulls in Bun's full Buffer
+ * implementation (used internally for percent-decoding), which the
+ * capability check correctly rejects — Buffer isn't something Porffor's
+ * compiled output can rely on. This shim implements parse/stringify/
+ * escape/unescape (plus the encode/decode aliases Node exports) over
+ * plain string ops and encodeURIComponent/decodeURIComponent instead.
+ */
+const NODE_QUERYSTRING_SHIM = `
+function qsUnescape(str) {
+  try { return decodeURIComponent(String(str).replace(/\\+/g, " ")); }
+  catch { return String(str); }
+}
+function qsEscape(str) {
+  return encodeURIComponent(String(str));
+}
+function parse(qs, sep, eq, options) {
+  sep = sep || "&";
+  eq = eq || "=";
+  var obj = Object.create(null);
+  if (typeof qs !== "string" || qs.length === 0) return obj;
+  var decode = (options && options.decodeURIComponent) || qsUnescape;
+  var maxKeys = options && typeof options.maxKeys === "number" ? options.maxKeys : 1000;
+  var pairs = qs.split(sep);
+  var limit = maxKeys > 0 ? Math.min(pairs.length, maxKeys) : pairs.length;
+  for (var i = 0; i < limit; i++) {
+    var pair = pairs[i];
+    var eqIdx = pair.indexOf(eq);
+    var key, value;
+    if (eqIdx >= 0) { key = pair.slice(0, eqIdx); value = pair.slice(eqIdx + eq.length); }
+    else { key = pair; value = ""; }
+    key = decode(key);
+    value = decode(value);
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      if (Array.isArray(obj[key])) obj[key].push(value);
+      else obj[key] = [obj[key], value];
+    } else obj[key] = value;
+  }
+  return obj;
+}
+function stringify(obj, sep, eq, options) {
+  sep = sep || "&";
+  eq = eq || "=";
+  obj = obj || {};
+  var encode = (options && options.encodeURIComponent) || qsEscape;
+  var parts = [];
+  for (var key in obj) {
+    if (!Object.prototype.hasOwnProperty.call(obj, key)) continue;
+    var value = obj[key];
+    var encodedKey = encode(key);
+    if (Array.isArray(value)) {
+      for (var i = 0; i < value.length; i++) parts.push(encodedKey + eq + encode(value[i]));
+    } else {
+      parts.push(encodedKey + eq + encode(value));
+    }
+  }
+  return parts.join(sep);
+}
+export { parse, stringify, qsEscape as escape, qsUnescape as unescape, stringify as encode, parse as decode };
+export default { parse, stringify, escape: qsEscape, unescape: qsUnescape, encode: stringify, decode: parse };
+`;
+
+/**
+ * `URL`/`URLSearchParams` are re-exported under aliased local names
+ * (`NodeURL`/`NodeURLSearchParams`) rather than declared as top-level
+ * `URL`/`URLSearchParams` — Porffor pre-binds `URL` as a global and
+ * rejects a second top-level declaration of that name. legacy
+ * parse/format/resolve are hand-written over the WHATWG URL rather than
+ * Bun's internal legacy-Url implementation, which isn't something this
+ * shim can import from; good enough for the common absolute-URL case,
+ * not a byte-for-byte port of Node's edge cases (relative/protocol-less
+ * input, unusual schemes).
+ */
+const NODE_URL_SHIM = `
+var NodeURL = globalThis.URL;
+var NodeURLSearchParams = globalThis.URLSearchParams;
+function urlFormat(urlObject) {
+  if (typeof urlObject === "string") return urlObject;
+  if (urlObject instanceof NodeURL) return urlObject.href;
+  var protocol = urlObject.protocol || "";
+  var slashes = urlObject.slashes !== false && !!(urlObject.host || urlObject.hostname);
+  var auth = urlObject.auth ? urlObject.auth + "@" : "";
+  var host = urlObject.host || ((urlObject.hostname || "") + (urlObject.port ? ":" + urlObject.port : ""));
+  var pathname = urlObject.pathname || "";
+  var search = urlObject.search || (urlObject.query ? "?" + (typeof urlObject.query === "string" ? urlObject.query : "") : "");
+  var hash = urlObject.hash || "";
+  return protocol + (slashes ? "//" : "") + auth + host + pathname + search + hash;
+}
+function legacyFromURL(u) {
+  return {
+    protocol: u.protocol,
+    slashes: true,
+    auth: u.username ? u.username + (u.password ? ":" + u.password : "") : null,
+    host: u.host,
+    port: u.port || null,
+    hostname: u.hostname,
+    hash: u.hash || null,
+    search: u.search || null,
+    query: u.search ? u.search.slice(1) : null,
+    pathname: u.pathname,
+    path: u.pathname + (u.search || ""),
+    href: u.href,
+  };
+}
+function urlParse(input) {
+  return legacyFromURL(new NodeURL(input));
+}
+function urlResolve(from, to) {
+  return new NodeURL(to, new NodeURL(from)).href;
+}
+export { NodeURL as URL, NodeURLSearchParams as URLSearchParams, urlFormat as format, urlParse as parse, urlResolve as resolve };
+export default { URL: NodeURL, URLSearchParams: NodeURLSearchParams, format: urlFormat, parse: urlParse, resolve: urlResolve };
+`;
+
+export const NODE_SHIMS = {
+  "node:path": NODE_PATH_SHIM,
+  "node:querystring": NODE_QUERYSTRING_SHIM,
+  "node:url": NODE_URL_SHIM,
+} satisfies Record<string, string>;

package/src/standalone-build.ts

@@ -7,7 +7,7 @@
  * embedded transport already produces exactly the binary we want, so this
  * copies it out and enforces the one thing a standalone binary cannot do.
  */
-import { chmod, cp, mkdir, readFile } from "node:fs/promises";
+import { chmod, cp, mkdir } from "node:fs/promises";
 import { resolve } from "node:path";
 import { buildArtifact, type BuildInput } from "./build";
 import type { Bindings } from "./wrap";
@@ -29,7 +29,7 @@ export type StandaloneBuildResult = { outPath: string; bytes: number };
  * Outbound `fetch` is absent from this list: http and https both work, with
  * BearSSL and the Mozilla root set compiled in.
  */
-export function unsupportedBindings(bindings: Partial<Bindings>): string[] {
+export function unsupportedBindings(bindings: Pick<Partial<Bindings>, "services" | "outbound">): string[] {
   const reasons: string[] = [];
   if ((bindings.services ?? []).length > 0) {
     reasons.push("service bindings call another deployment through an edge, which a standalone binary has none of");
@@ -38,21 +38,11 @@ export function unsupportedBindings(bindings: Partial<Bindings>): string[] {
 }
 
 export async function buildStandalone(input: StandaloneBuildInput): Promise<StandaloneBuildResult> {
-  const artifact = await buildArtifact({ ...input, transport: "embedded" });
-
-  let bindings: Partial<Bindings> = {};
-  try {
-    // SAFETY: bindings.json is written by buildArtifact from the validated
-    // config in this same call — our own output, not user input.
-    bindings = JSON.parse(await readFile(resolve(artifact.artifactDir, "bindings.json"), "utf8")) as Partial<Bindings>;
-  } catch {
-    bindings = {}; // a project with no bindings at all
-  }
-
-  const blocked = unsupportedBindings(bindings);
+  const blocked = unsupportedBindings(input.config);
   if (blocked.length > 0) {
     throw new Error(`cannot build a standalone binary for this project:\n  - ${blocked.join("\n  - ")}`);
   }
+  const artifact = await buildArtifact({ ...input, transport: "embedded" });
 
   // The sprout *is* the binary: assets and bindings are compiled into it, and
   // everything else it needs (port, data dir, secrets) arrives at run time.

package/src/toolchain.ts

@@ -38,7 +38,7 @@ const ZIG_SHA256 = {
 // frozen reference handlers and update its COMPAT.md for any new mismatch before
 // releasing — the alpha compiler's output can shift between pins. Checked by
 // hand at bump time, not in CI.
-// uWebSockets commit Porffor alpha-4 fetches for the native-fetch server.
+// uWebSockets commit Porffor alpha-10 fetches for the native-fetch server.
 const UWS_COMMIT = "360c276d";
 const UWS_COMMIT_FULL = "360c276d609d59af56ae6932adb95154ace9f15f";
 
@@ -678,7 +678,7 @@ export function porfforVersion(): string {
 
 export function esbuildVersion(): string {
   // Legacy artifact field, retained so older control planes can read manifests.
-  // Handler bundling uses Bun.build and Porffor alpha 9 needs no esbuild binary.
+  // Handler bundling uses Bun.build and Porffor alpha 10 needs no esbuild binary.
   return "unused";
 }
 

package/src/types-gen.ts

@@ -1,10 +1,9 @@
 /**
  * `sproutboat types` — the project's `env`, as TypeScript.
  *
- * In Workers `env` is a parameter, so an editor can infer it from a signature.
- * Here it is a global, which means nothing is inferable at all: `env.SESSIONS`
- * is an undeclared identifier until this file exists. That makes generated
- * types worth more here than they are there, not less.
+ * `env` remains available as a global in both compatibility modes. This file
+ * gives it the project's binding names and types. From 2026-09-28 it is also
+ * the second handler argument.
  *
  * The output declares `env` from `sproutboat.jsonc` and references the ambient
  * types shipped in `types/sproutboat.d.ts`, so binding *shapes* version with
@@ -75,6 +74,11 @@ export function generateTypes(config: SproutboatConfig): string {
         .join("\n")
     : "    // No bindings declared in sproutboat.jsonc yet.";
 
+  const handlerNote =
+    config.compatibility_date >= "2026-09-28"
+      ? "The same object is passed as the second handler argument: fetch(request, env, ctx)."
+      : "The handler signature is fetch(request, ctx); env is only a global.";
+
   return `${HEADER}
 /// <reference types="sproutboat/types" />
 
@@ -82,7 +86,7 @@ declare global {
   /**
    * Bindings from sproutboat.jsonc, for project "${config.name}".
    *
-   * A global, not a parameter: the handler signature is \`fetch(request)\`.
+   * ${handlerNote}
    * Every call on these is synchronous, so \`await\` is allowed and does
    * nothing.
    */

package/types/sproutboat.d.ts

@@ -6,9 +6,9 @@
  * generates a project's `sproutboat-env.d.ts`, which references this file and
  * declares `env` with that project's bindings.
  *
- * Two things differ from Cloudflare Workers and are the reason these exist:
- * `env` is a global rather than a parameter, so nothing is inferable from a
- * signature, and every binding call is synchronous.
+ * Bindings are synchronous. Before compatibility date 2026-09-28, `env` is a
+ * global only and `ctx` is the second handler argument. From that date, `env`
+ * is also passed as the second argument and `ctx` as the third.
  */
 
 declare global {
@@ -300,11 +300,7 @@ declare global {
     scheduledTime: number;
   }
 
-  /**
-   * `env` is a global, not a parameter. `ctx` is the second argument, and its
-   * only member is `waitUntil`: work that outlives the response, drained
-   * in-process and capped at 25s.
-   */
+  /** Work that outlives the response, drained in-process and capped at 25s. */
   interface ExecutionContext {
     waitUntil(promise: Promise<unknown>): void;
   }
@@ -318,6 +314,13 @@ declare global {
     queue?(batch: MessageBatch<QueueBody>, ctx: ExecutionContext): void | Promise<void>;
   }
 
+  /** Handler signature for compatibility dates from 2026-09-28. */
+  interface WorkersHandler<Bindings = Record<string, unknown>, QueueBody = unknown> {
+    fetch(request: Request, env: Bindings, ctx: ExecutionContext): Response | Promise<Response>;
+    scheduled?(event: ScheduledEvent, env: Bindings, ctx: ExecutionContext): void | Promise<void>;
+    queue?(batch: MessageBatch<QueueBody>, env: Bindings, ctx: ExecutionContext): void | Promise<void>;
+  }
+
   /**
    * What a Durable Object class implements. Declare it above the default
    * export and name it in `durable_objects`.