@sproutboat/runtime 0.42.2 → 0.43.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sproutboat/runtime
 
+## 0.43.0
+
+### Minor Changes
+
+- 201f8ff: runtime: with `SB_LOG=json` in its environment a binary writes structured records to stderr, one JSON line each (#268). A request writes `{"type":"request","v":1,"id","timestamp","method","path","status","durationMs","outcome"}` once its response is built, and every uncaught error (a handler, `scheduled()`, `queue()`, an alarm, a WebSocket handler, a rejected promise or a `waitUntil` task) writes `{"type":"error","v":1,"id","timestamp","source","name","message","stack"}` in place of the plain `Uncaught (in ...)` text. An error raised while answering a request carries that request's `id`; background work has `id: null`. Bodies, headers, the query string and the client address are never written, and the value of a declared secret that appears in a message or stack is replaced with `[redacted]`. Output is bounded: fields are cut to fixed lengths and at most 200 lines a second are written; the rest are counted and reported by a `{"type":"dropped","count"}` line when the next second starts. Without `SB_LOG=json` nothing changes, so no compatibility date applies.
+
 ## 0.42.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutboat/runtime",
-  "version": "0.42.2",
+  "version": "0.43.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/native-fetch-prelude.js

@@ -11561,6 +11561,7 @@ function __sbMakeQueue(binding) {
 
 globalThis.__sbInstallBindings = function (target, bindings) {
   if (!target) return;
+  __sbLogSecretNames = bindings.secrets || [];
 
   __sbQueueSetup(bindings);
 
@@ -13992,7 +13993,7 @@ function __sbTrustedProxyHeader(request, name) {
 // own.
 const __SB_WAITUNTIL_TIMEOUT_MS = 25000;
 
-async function __sbDrainWaitUntil(tasks) {
+async function __sbDrainWaitUntil(tasks, logRec) {
   if (!tasks.length) return;
   const pending = tasks.splice(0, tasks.length);
   // Clear the cap's timer once the tasks finish: a pending timer kept the process
@@ -14001,16 +14002,17 @@ async function __sbDrainWaitUntil(tasks) {
   const cap = new Promise((resolve) => {
     timer = setTimeout(resolve, __SB_WAITUNTIL_TIMEOUT_MS);
   });
-  await Promise.race([__sbDrainAll(pending), cap]);
+  await Promise.race([__sbDrainAll(pending, logRec), cap]);
   clearTimeout(timer);
 }
 
-async function __sbDrainAll(pending) {
+async function __sbDrainAll(pending, logRec) {
   for (let i = 0; i < pending.length; i++) {
     try {
       await pending[i];
-    } catch {
-      /* a background task's rejection must not fail the response */
+    } catch (error) {
+      /* a background task's rejection must not fail the response; with SB_LOG=json it is recorded (#268) */
+      if (__sbLogJson()) __sbLogError("waitUntil", error, logRec);
     }
   }
 }
@@ -15332,8 +15334,9 @@ function __sbInstallWebSockets() {
   globalThis.WebSocketRequestResponsePair = __SbWebSocketRequestResponsePair;
 }
 
-async function __sbFetchWithDrain(res, tasks, bindingCall, rethrow, top, cpuCell) {
+async function __sbFetchWithDrain(res, tasks, bindingCall, rethrow, top, cpuCell, logRec) {
   let r;
+  let threw = 0;
   try {
     r = res && __sbIsFn(res.then) ? await res : res;
     if (top && __sbHasWebSocket(r)) r = __sbWsHostResponse(r);
@@ -15348,7 +15351,8 @@ async function __sbFetchWithDrain(res, tasks, bindingCall, rethrow, top, cpuCell
       throw error;
     }
     // #179 — a rejected handler promise must not take the process down with it.
-    r = __sbErrorResponse(error, bindingCall);
+    threw = 1;
+    r = __sbErrorResponse(error, bindingCall, logRec);
   }
   // From 2026-11-02 an async handler reports its CPU too: the thread time of the slices in which this
   // request ran, not its neighbours' (before it, only a handler that answered synchronously did).
@@ -15359,7 +15363,8 @@ async function __sbFetchWithDrain(res, tasks, bindingCall, rethrow, top, cpuCell
   // The response goes out now and ctx.waitUntil work keeps running after it, as in
   // workerd; it was awaited first, so a 1.5 s background task delayed the response by
   // 1.5 s. The 25 s cap still bounds it. Not called for no tasks: an async call is a coroutine and a promise.
-  if (tasks.length) __sbDrainWaitUntil(tasks);
+  if (logRec) __sbLogRequest(logRec, r, threw);
+  if (tasks.length) __sbDrainWaitUntil(tasks, logRec);
   return r;
 }
 
@@ -15367,8 +15372,8 @@ async function __sbFetchWithDrain(res, tasks, bindingCall, rethrow, top, cpuCell
 // propagate past __sbEntry and crash the whole server. Logged first, the way a
 // Worker logs "Uncaught Error: ...": a swallowed exception left a 500 with
 // nothing on stderr, which hid #168 entirely.
-function __sbErrorResponse(error, bindingCall) {
-  __sbLogUncaught("fetch", error);
+function __sbErrorResponse(error, bindingCall, logRec) {
+  __sbLogUncaught("fetch", error, logRec);
   // Untyped, as workerd sends it: the text/plain default is for handlers' bodies.
   const response = new Response("Internal Server Error", { status: 500 });
   response.headers.delete("content-type");
@@ -15438,7 +15443,11 @@ function __sbHeader(headers, name) {
   return count > 1 ? headers.get(name) : found;
 }
 
-function __sbLogUncaught(where, error) {
+function __sbLogUncaught(where, error, logRec) {
+  if (__sbLogJson()) {
+    __sbLogError(where, error, logRec);
+    return;
+  }
   try {
     let text = "";
     if (error && error.stack) text = String(error.stack);
@@ -15450,6 +15459,113 @@ function __sbLogUncaught(where, error) {
   }
 }
 
+// #268 — structured request and error records for a standalone binary. Off unless SB_LOG=json, so
+// nothing an app can observe changes and the per-request cost of "off" is one cached boolean. On, every
+// request writes one JSON line to stderr after its response is built, and every uncaught error (in a
+// handler, scheduled(), queue(), an alarm, a WebSocket handler, a rejected promise or a waitUntil task)
+// writes one more, in place of the plain "Uncaught (in ...)" text, so the stream stays parseable.
+//
+// What is never written: request or response bodies, headers (cookies and authorization among them), the
+// query string (it is where tokens end up), the client address, and the value of any declared secret (the
+// ones the message or stack happens to contain are replaced). Output is bounded: fields are cut to fixed
+// lengths and at most 200 lines a second go out; the rest are counted and reported by one "dropped" line
+// when the next second starts. A record's "id" ties a request line to the errors of the same request;
+// background work has id null.
+let __sbLogOn;
+let __sbLogSecretNames = [];
+let __sbLogSeq = 0;
+let __sbLogWindow = 0;
+let __sbLogCount = 0;
+let __sbLogDropped = 0;
+const __SB_LOG_PER_SECOND = 200;
+function __sbLogJson() {
+  if (__sbLogOn === undefined) __sbLogOn = __sbEnv("SB_LOG") === "json";
+  return __sbLogOn;
+}
+// Tests turn the records on without an environment, like __sbSetCompat.
+function __sbSetLog(on) {
+  __sbLogOn = on;
+}
+function __sbLogCut(text, max) {
+  const s = String(text);
+  return s.length > max ? s.slice(0, max) + "..." : s;
+}
+function __sbLogRedact(text) {
+  let out = text;
+  for (let i = 0; i < __sbLogSecretNames.length; i++) {
+    const raw = __sbEnv(__sbLogSecretNames[i]);
+    if (!raw || raw.length < 4) continue;
+    out = out.split(raw).join("[redacted]");
+    const decoded = __sbFromUtf8(raw);
+    if (decoded !== raw && decoded.length >= 4) out = out.split(decoded).join("[redacted]");
+  }
+  return out;
+}
+function __sbLogWrite(record) {
+  const now = Date.now();
+  const second = Math.floor(now / 1000);
+  if (second !== __sbLogWindow) {
+    if (__sbLogDropped > 0) {
+      console.error(JSON.stringify({ type: "dropped", v: 1, timestamp: now, count: __sbLogDropped, reason: "rate" }));
+      __sbLogDropped = 0;
+    }
+    __sbLogWindow = second;
+    __sbLogCount = 0;
+  }
+  if (__sbLogCount >= __SB_LOG_PER_SECOND) {
+    __sbLogDropped++;
+    return;
+  }
+  __sbLogCount++;
+  console.error(JSON.stringify(record));
+}
+function __sbLogBegin(request) {
+  __sbLogSeq++;
+  let path = "/";
+  try {
+    path = new URL(request.url).pathname;
+  } catch {
+    /* a request without a parseable URL is logged as "/" */
+  }
+  return { id: String(Math.floor(Date.now() / 1000)) + "-" + __sbLogSeq, t0: Date.now(), method: String(request.method), path: __sbLogCut(path, 256) };
+}
+function __sbLogRequest(rec, response, threw) {
+  try {
+    __sbLogWrite({
+      type: "request",
+      v: 1,
+      id: rec.id,
+      timestamp: rec.t0,
+      method: __sbLogCut(rec.method, 16),
+      path: rec.path,
+      status: response && response.status ? response.status : 0,
+      durationMs: Date.now() - rec.t0,
+      outcome: threw === 1 ? "exception" : "ok",
+    });
+  } catch {
+    /* logging must never turn a served request into a crash */
+  }
+}
+function __sbLogError(where, error, rec) {
+  try {
+    const name = error && error.name ? String(error.name) : "Error";
+    const message = error && error.message != null ? String(error.message) : String(error);
+    const record = {
+      type: "error",
+      v: 1,
+      id: rec ? rec.id : null,
+      timestamp: Date.now(),
+      source: __sbLogCut(where, 40),
+      name: __sbLogCut(name, 100),
+      message: __sbLogCut(__sbLogRedact(message), 1000),
+    };
+    if (error && error.stack) record.stack = __sbLogCut(__sbLogRedact(String(error.stack)), 2000);
+    __sbLogWrite(record);
+  } catch {
+    /* logging must never turn a handled error into a crash */
+  }
+}
+
 // A promise rejected and nothing was waiting on it (an un-awaited `db.prepare(...).run()`
 // that failed, say). As on Workers the request, the process and every other request go on:
 // the rejection is logged, and an "unhandledrejection" event fires on the global scope when
@@ -15785,6 +15901,8 @@ globalThis.__sbEntry = function (handlers, request) {
     // async handlers (see LogEvent in services/edge) — that is this.
     const __cpuCell = __sbCpuBegin();
     const __t0 = __cpuCell ? 0 : __sbCpuMs();
+    // #268 — one record per request when SB_LOG=json; null (and no work at all) otherwise.
+    const __logRec = __sbLogJson() ? __sbLogBegin(request) : null;
     const __sbTasks = [];
     const ctx = {
       waitUntil(p) {
@@ -15807,19 +15925,24 @@ globalThis.__sbEntry = function (handlers, request) {
       // #179 — a synchronous throw anywhere in the handler must not take the
       // whole process (and every other in-flight request) down with it.
       __sbCpuEnd(__cpuCell);
-      return __sbErrorResponse(error, bindingCall);
+      const __failed = __sbErrorResponse(error, bindingCall, __logRec);
+      if (__logRec) __sbLogRequest(__logRec, __failed, 1);
+      return __failed;
     }
     // Same promise-identity rule as above applies to `__sbFetchWithDrain`'s
     // own return, which is why it's tail-called rather than chained on here.
-    if (__sbTasks.length || (__res && __sbIsFn(__res.then)) || __sbHasStreamBody(__res)) return __sbFetchWithDrain(__res, __sbTasks, bindingCall, false, true, __cpuCell);
+    if (__sbTasks.length || (__res && __sbIsFn(__res.then)) || __sbHasStreamBody(__res)) return __sbFetchWithDrain(__res, __sbTasks, bindingCall, false, true, __cpuCell, __logRec);
     // A WebSocket handshake answer (from 2026-10-30): its client end becomes the host socket.
     if (__sbHasWebSocket(__res)) {
       __sbCpuEnd(__cpuCell);
-      return __sbWsHostResponse(__res);
+      const __ws = __sbWsHostResponse(__res);
+      if (__logRec) __sbLogRequest(__logRec, __ws, 0);
+      return __ws;
     }
     // The request ran alone from start to here: its own slices, or the process delta where no slot was free.
     const __cpu = __cpuCell ? __sbCpuTake(__cpuCell) : __sbCpuMs() - __t0;
     __sbCpuEnd(__cpuCell);
+    if (__logRec) __sbLogRequest(__logRec, __res, 0);
     return __sbTagCpu(__res, __cpu);
   }
   if (!__sbTriggerAuthed(request)) return new Response("forbidden", { status: 403 });

package/test/native-base64.ts

@@ -1,14 +1,18 @@
 import assert from "node:assert/strict";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
-import { ensurePorffor } from "../../toolchain/src/acquire";
+import { join } from "node:path";
+import { compileNative } from "./native-compile";
 import { preludePath, TRANSPORT_MARKER, transportPath, wrapNativeFetchHandler } from "../src/wrap";
 
-const expected = Array.from({length:10}, (_,length) => {
-  const bytes=Uint8Array.from({length}, (_,i) => (i*71+251)%256);
-  const padded=Buffer.from(bytes).toString("base64");
-  return {padded,url:padded.replaceAll("+","-").replaceAll("/","_").replace(/=+$/, ""),decoded:Array.from(bytes)};
+const expected = Array.from({ length: 10 }, (_, length) => {
+  const bytes = Uint8Array.from({ length }, (_, i) => (i * 71 + 251) % 256);
+  const padded = Buffer.from(bytes).toString("base64");
+  return {
+    padded,
+    url: padded.replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, ""),
+    decoded: Array.from(bytes),
+  };
 });
 const handler = `export default {fetch() {
   const rows=[];
@@ -37,14 +41,7 @@ function freePort(): number {
 const workdir = await mkdtemp(join(tmpdir(), "sb-native-base64-"));
 let server: ReturnType<typeof Bun.spawn> | undefined;
 try {
-  const porffor = await ensurePorffor();
-  const node = Bun.which("node");
-  if (!node) throw new Error("native streams test needs node on PATH");
-
-  const [core, broker] = await Promise.all([
-    readFile(preludePath, "utf8"),
-    readFile(transportPath("broker"), "utf8"),
-  ]);
+  const [core, broker] = await Promise.all([readFile(preludePath, "utf8"), readFile(transportPath("broker"), "utf8")]);
   assert(core.includes(TRANSPORT_MARKER), "runtime prelude is missing its transport marker");
   const prelude = core.replace(TRANSPORT_MARKER, broker);
   const generated = join(workdir, "base64.generated.js");
@@ -52,18 +49,7 @@ try {
   await writeFile(generated, wrapNativeFetchHandler(handler, prelude));
   await rm(binary, { force: true });
 
-  const compile = Bun.spawn([node, resolve(porffor, "runtime/index.js"), "native", generated, "-o", binary, "-s", "-O0"], {
-    cwd: workdir,
-    env: process.env,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const [exitCode, stdout, stderr] = await Promise.all([
-    compile.exited,
-    new Response(compile.stdout).text(),
-    new Response(compile.stderr).text(),
-  ]);
-  assert.equal(exitCode, 0, `Porffor native compile failed:\n${stderr}\n${stdout}`);
+  await compileNative({ generated, binary, dir: workdir });
 
   const port = freePort();
   server = Bun.spawn([binary], {

package/test/native-bodies.ts

@@ -1,8 +1,8 @@
 import assert from "node:assert/strict";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
-import { ensurePorffor } from "../../toolchain/src/acquire";
+import { join } from "node:path";
+import { compileNative } from "./native-compile";
 import { preludePath, TRANSPORT_MARKER, transportPath, wrapNativeFetchHandler } from "../src/wrap";
 
 // Bodies on the wire and the Fetch classes, against Bun: byte bodies go out as their bytes
@@ -80,14 +80,7 @@ function freePort(): number {
 const workdir = await mkdtemp(join(tmpdir(), "sb-native-bodies-"));
 let server: ReturnType<typeof Bun.spawn> | undefined;
 try {
-  const porffor = await ensurePorffor();
-  const node = Bun.which("node");
-  if (!node) throw new Error("native streams test needs node on PATH");
-
-  const [core, broker] = await Promise.all([
-    readFile(preludePath, "utf8"),
-    readFile(transportPath("broker"), "utf8"),
-  ]);
+  const [core, broker] = await Promise.all([readFile(preludePath, "utf8"), readFile(transportPath("broker"), "utf8")]);
   assert(core.includes(TRANSPORT_MARKER), "runtime prelude is missing its transport marker");
   const prelude = core.replace(TRANSPORT_MARKER, broker);
   const generated = join(workdir, "bodies.generated.js");
@@ -95,18 +88,7 @@ try {
   await writeFile(generated, wrapNativeFetchHandler(handler, prelude, undefined, undefined, undefined, "2026-10-21"));
   await rm(binary, { force: true });
 
-  const compile = Bun.spawn([node, resolve(porffor, "runtime/index.js"), "native", generated, "-o", binary, "-s", "-O0"], {
-    cwd: workdir,
-    env: process.env,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const [exitCode, stdout, stderr] = await Promise.all([
-    compile.exited,
-    new Response(compile.stdout).text(),
-    new Response(compile.stderr).text(),
-  ]);
-  assert.equal(exitCode, 0, `Porffor native compile failed:\n${stderr}\n${stdout}`);
+  await compileNative({ generated, binary, dir: workdir });
 
   const port = freePort();
   server = Bun.spawn([binary], {
@@ -142,7 +124,9 @@ try {
   const form = await fetch(`http://127.0.0.1:${port}/form`);
   const boundary = (form.headers.get("content-type") || "").split("boundary=")[1];
   assert(boundary, "multipart content type");
-  const parsed = await new Response(await form.arrayBuffer(), { headers: { "content-type": `multipart/form-data; boundary=${boundary}` } }).formData();
+  const parsed = await new Response(await form.arrayBuffer(), {
+    headers: { "content-type": `multipart/form-data; boundary=${boundary}` },
+  }).formData();
   assert.equal(parsed.get("a"), "1");
   const file = parsed.get("f");
   assert(file instanceof File, "the file part parses back as a File");
@@ -153,11 +137,20 @@ try {
   const got = JSON.parse(await (await fetch(`http://127.0.0.1:${port}/cases`)).text()) as string[];
   const want: string[] = [];
   // SAFETY: CASE_SOURCES is the handler's own literal list of case functions.
-  const reference = new Function(`return (() => { ${CASE_SOURCES} return cases; })()`)() as Array<() => Promise<string> | string>;
+  const reference = new Function(`return (() => { ${CASE_SOURCES} return cases; })()`)() as Array<
+    () => Promise<string> | string
+  >;
   for (const run of reference) {
-    try { want.push(String(await run())); } catch (e) { want.push("THROWS " + (e instanceof Error ? e.name : String(e))); }
+    try {
+      want.push(String(await run()));
+    } catch (e) {
+      want.push("THROWS " + (e instanceof Error ? e.name : String(e)));
+    }
   }
-  assert.deepEqual(got, want.map((w) => (w.startsWith("workerd:") ? "workerd:TypeError" : w)));
+  assert.deepEqual(
+    got,
+    want.map((w) => (w.startsWith("workerd:") ? "workerd:TypeError" : w)),
+  );
   console.log(`Native bodies are sent as bytes and ${want.length} Fetch class cases match Bun`);
 } finally {
   if (server) {

package/test/native-byte-text.ts

@@ -1,8 +1,8 @@
 import assert from "node:assert/strict";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
-import { ensurePorffor } from "../../toolchain/src/acquire";
+import { join } from "node:path";
+import { compileNative } from "./native-compile";
 import { preludePath, TRANSPORT_MARKER, transportPath, wrapNativeFetchHandler } from "../src/wrap";
 
 // sproutd #22: __sbFromUtf8 and __sbToBytes run in C (__sbFromUtf8Native, __sbToBytesNative).
@@ -92,28 +92,12 @@ function freePort(): number {
 const workdir = await mkdtemp(join(tmpdir(), "sb-native-byte-text-"));
 let server: ReturnType<typeof Bun.spawn> | undefined;
 try {
-  const porffor = await ensurePorffor();
-  const node = Bun.which("node");
-  if (!node) throw new Error("native byte-text test needs node on PATH");
   const broker = await readFile(transportPath("broker"), "utf8");
   assert(core.includes(TRANSPORT_MARKER), "runtime prelude is missing its transport marker");
   const generated = join(workdir, "bytes.generated.js");
   const binary = join(workdir, "bytes-native");
   await writeFile(generated, wrapNativeFetchHandler(handler, core.replace(TRANSPORT_MARKER, broker)));
-  const compile = Bun.spawn(
-    [node, resolve(porffor, "runtime/index.js"), "native", generated, "-o", binary, "-s", "-O0"],
-    {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    },
-  );
-  const [exitCode, stdout, stderr] = await Promise.all([
-    compile.exited,
-    new Response(compile.stdout).text(),
-    new Response(compile.stderr).text(),
-  ]);
-  assert.equal(exitCode, 0, `Porffor native compile failed:\n${stderr}\n${stdout}`);
+  await compileNative({ generated, binary, dir: workdir });
 
   const port = freePort();
   // Peak RSS: /proc's high-water mark on Linux, time(1) on macOS.

package/test/native-compile.ts

@@ -0,0 +1,163 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { ensurePorffor } from "../../toolchain/src/acquire";
+import { ensurePorfforA21 } from "../../toolchain/src/a21/acquire";
+import {
+  composeStandaloneA21,
+  SHARED_PRELUDE_FILE,
+  STANDALONE_A21_COMPILE_FLAGS,
+} from "../../toolchain/src/a21/standalone";
+import { buildStandaloneA21 } from "../../toolchain/src/a21/standalone-build";
+import { standaloneChannel } from "../../toolchain/src/a21/standalone-channel";
+import { bearsslEnv } from "./bearssl";
+
+export type NativeCompileInput = {
+  /** The generated module (`wrapNativeFetchHandler` output), already written to disk. */
+  generated: string;
+  /** Where the compiled binary goes. */
+  binary: string;
+  /** Working directory of the compile, and where alpha 22 puts its intermediate files. Default: the binary's directory. */
+  dir?: string;
+  /** Toolchain cache root for the alpha 19 tree (`ensurePorffor({ cacheRoot })`). */
+  cacheRoot?: string;
+  /** Objects and link flags for the link line (alpha 19: `SB_EXTRA_LINK`). */
+  extraLink?: string[];
+  /** Flags for every C compile (alpha 19: `SB_EXTRA_CFLAGS`). */
+  extraCflags?: string[];
+  /** Link BearSSL, as a test that uses crypto.subtle needs. */
+  bearssl?: boolean;
+  /** `-O` level. Default 0. */
+  optimize?: number;
+  /** Extra environment for the alpha 19 compiler process (the default is `process.env`). */
+  env?: Record<string, string>;
+  /** Message prefix of the failure assertion. Default "Porffor native compile failed". */
+  failure?: string;
+};
+
+type UwsModule = {
+  UWS_COMMIT: string;
+  ensureUWebSockets: () => string;
+  ensureUSocketsBuilt: (dir: string) => void;
+};
+
+let renderQueue: Promise<void> = Promise.resolve();
+
+const channel = () => standaloneChannel();
+
+const split = (flags: string | undefined): string[] => (flags ?? "").split(" ").filter(Boolean);
+
+async function drain(child: Bun.Subprocess<"ignore", "pipe", "pipe">) {
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ]);
+  return { exitCode, stdout, stderr };
+}
+
+/** The host uWebSockets checkout with a built uSockets.a, built on first use. */
+async function uwsDirectory(alpha19: string): Promise<string> {
+  // SAFETY: the patched alpha 19 tree's compiler/uwebsockets.js exports these (see the toolchain's standaloneShimSource).
+  const mod: UwsModule = await import(resolve(alpha19, "compiler/uwebsockets.js"));
+  const dir = resolve(homedir(), ".cache/porffor/deps", `uWebSockets-${mod.UWS_COMMIT}`);
+  if (!existsSync(join(dir, "uSockets/uSockets.a"))) {
+    // SAFETY: the compiler's prefs.js installs `Prefs` on globalThis as a plain flag object.
+    const g = globalThis as { Prefs?: { eventLoop?: boolean } };
+    const prev = g.Prefs;
+    g.Prefs = { ...prev, eventLoop: true };
+    try {
+      mod.ensureUSocketsBuilt(mod.ensureUWebSockets());
+    } finally {
+      if (prev === undefined) delete g.Prefs;
+      else g.Prefs = prev;
+    }
+  }
+  return dir;
+}
+
+/** Compile a generated module into a native binary on the standalone channel (alpha 22 by default, `SPROUTBOAT_PORFFOR_CHANNEL=alpha-19` for the fallback). */
+export async function compileNative(input: NativeCompileInput): Promise<void> {
+  const which = channel();
+  const dir = input.dir ?? dirname(input.binary);
+  const optimize = input.optimize ?? 0;
+  const failure = input.failure ?? "Porffor native compile failed";
+  const bearssl = input.bearssl ? await bearsslEnv() : undefined;
+  const extraLink = [...(input.extraLink ?? []), ...split(bearssl?.SB_EXTRA_LINK)];
+  const extraCflags = [...(input.extraCflags ?? []), ...split(bearssl?.SB_EXTRA_CFLAGS)];
+  const alpha19 = await ensurePorffor(input.cacheRoot === undefined ? {} : { cacheRoot: input.cacheRoot });
+
+  if (which === "alpha-19") {
+    const node = Bun.which("node");
+    if (!node) throw new Error("native compile needs node on PATH");
+    const env = { ...process.env, ...input.env };
+    if (extraLink.length > 0) env.SB_EXTRA_LINK = extraLink.join(" ");
+    if (extraCflags.length > 0) env.SB_EXTRA_CFLAGS = extraCflags.join(" ");
+    const compile = Bun.spawn(
+      [
+        node,
+        resolve(alpha19, "runtime/index.js"),
+        "native",
+        input.generated,
+        "-o",
+        input.binary,
+        "-s",
+        `-O${optimize}`,
+      ],
+      { cwd: dir, env, stdout: "pipe", stderr: "pipe" },
+    );
+    const { exitCode, stdout, stderr } = await drain(compile);
+    if (exitCode !== 0) throw new Error(`${failure}:\n${stderr}\n${stdout}`);
+    return;
+  }
+
+  const bun = process.execPath;
+  const alpha22 = await ensurePorfforA21("alpha-22");
+  const work = join(dir, `a22-${(input.binary.split("/").pop() ?? "bin").replace(/[^\w.-]/g, "_")}`);
+  await rm(work, { recursive: true, force: true });
+  await mkdir(work, { recursive: true });
+  const composed = composeStandaloneA21(await readFile(input.generated, "utf8"), alpha19);
+  // Beside the generated module: its relative imports (a handler's sibling helper files) resolve from the
+  // directory of the file they were written in, and the shared prelude carries the module's body. The
+  // chain recognises the prelude by its file name, so a test that compiles several variants from one
+  // directory at once (native-websockets) takes turns: the render is the only step that reads it.
+  const source = dirname(resolve(input.generated));
+  const entry = join(source, "entry.a22.js");
+  const turn = renderQueue;
+  let release = () => {};
+  renderQueue = new Promise<void>((done) => (release = done));
+  await turn;
+  let rendered: Awaited<ReturnType<typeof drain>>;
+  try {
+    await writeFile(join(source, SHARED_PRELUDE_FILE), composed.sharedPrelude);
+    await writeFile(entry, composed.entry);
+    const unitsDir = join(work, "units");
+    const render = Bun.spawn(
+      [bun, resolve(alpha22, "runtime/index.js"), "c", entry, "-o", `${unitsDir}/`, ...STANDALONE_A21_COMPILE_FLAGS],
+      { cwd: work, env: { ...process.env, ...input.env }, stdout: "pipe", stderr: "pipe" },
+    );
+    rendered = await drain(render);
+  } finally {
+    release();
+  }
+  if (rendered.exitCode !== 0) throw new Error(`${failure} (alpha 22 render):\n${rendered.stderr}\n${rendered.stdout}`);
+  const unitsDir = join(work, "units");
+  await rm(input.binary, { force: true });
+  await buildStandaloneA21({
+    unitsDir,
+    alpha19Root: alpha19,
+    outPath: input.binary,
+    cc: ["cc"],
+    cxx: ["c++"],
+    uwsDir: await uwsDirectory(alpha19),
+    extraLink,
+    extraCflags,
+    optimize,
+    flto: false,
+    musl: false,
+    strip: true,
+  }).catch((error: Error) => {
+    throw new Error(`${failure} (alpha 22 build):\n${error.message}`);
+  });
+}

package/test/native-cpu-requests.ts

@@ -1,8 +1,8 @@
 import assert from "node:assert/strict";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
-import { ensurePorffor } from "../../toolchain/src/acquire";
+import { join } from "node:path";
+import { compileNative } from "./native-compile";
 import { preludePath, TRANSPORT_MARKER, transportPath, wrapNativeFetchHandler } from "../src/wrap";
 
 // Per-request CPU (design 02): x-sb-cpu-ms counts the thread CPU time of the slices in which one
@@ -43,9 +43,6 @@ function freePort(): number {
 const workdir = await mkdtemp(join(tmpdir(), "sb-native-cpu-requests-"));
 const servers: ReturnType<typeof Bun.spawn>[] = [];
 async function build(date: string): Promise<number> {
-  const porffor = await ensurePorffor();
-  const node = Bun.which("node");
-  if (!node) throw new Error("native cpu test needs node on PATH");
   const [core, broker] = await Promise.all([readFile(preludePath, "utf8"), readFile(transportPath("broker"), "utf8")]);
   assert(core.includes(TRANSPORT_MARKER), "runtime prelude is missing its transport marker");
   const generated = join(workdir, `cpu-${date}.generated.js`);
@@ -54,21 +51,7 @@ async function build(date: string): Promise<number> {
     generated,
     wrapNativeFetchHandler(handler, core.replace(TRANSPORT_MARKER, broker), undefined, undefined, undefined, date),
   );
-  const compile = Bun.spawn(
-    [node, resolve(porffor, "runtime/index.js"), "native", generated, "-o", binary, "-s", "-O0"],
-    {
-      cwd: workdir,
-      env: process.env,
-      stdout: "pipe",
-      stderr: "pipe",
-    },
-  );
-  const [exitCode, stdout, stderr] = await Promise.all([
-    compile.exited,
-    new Response(compile.stdout).text(),
-    new Response(compile.stderr).text(),
-  ]);
-  assert.equal(exitCode, 0, `Porffor native compile failed:\n${stderr}\n${stdout}`);
+  await compileNative({ generated, binary, dir: workdir });
   const port = freePort();
   const server = Bun.spawn([binary], {
     cwd: workdir,