@sproutboat/runtime 0.38.0 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @sproutboat/runtime
 
+## 0.40.0
+
+### Minor Changes
+
+- 1ae7843: From the proposed compatibility date 2026-11-16, `fetch()` on the standalone binary runs off the event loop. It used to run each request to the end before it returned, so 20 concurrent fetches to a 100 ms endpoint took 2,000 ms and every other request waited behind them. They now go to a pool of up to 32 I/O threads (the same client sproutd runs on 8), the handler suspends, and the server keeps serving; the 20 fetches take about 100 ms. The reply is delivered on the loop through the uWS waker the standalone server already installs for outbound WebSockets, so JavaScript still runs on one thread. Earlier dates keep the synchronous call, because a handler that relied on one request at a time across an `await fetch()` now interleaves with others, as it does in workerd. Behaviour on sproutd and through the broker is unchanged.
+
+## 0.39.0
+
+### Minor Changes
+
+- 7030f76: Database clients that need only fetch or WebSocket (`@libsql/client`, `@neondatabase/serverless`, `@supabase/supabase-js`, `@upstash/redis`, `@planetscale/database`) run unmodified. In the runtime: `fetch()` returns a promise on the standalone binary from the compatibility date that already promises it (2026-10-22), so `fetch(url).then(...)` works and a refused request rejects; a fetched 204, 205 or 304 response no longer throws "Response with null body status cannot have body"; from the proposed compatibility date 2026-11-15 the Node/Bun/Deno global check in the bundle skips a use behind a `typeof` feature test, a global the bundle declares itself, and mentions inside strings and comments, and `Error.captureStackTrace` exists. In the toolchain: a typed array with an underlying object (a `Buffer` polyfill) shadows the builtin methods it redefines, so `buf.toString("utf8")` is the Buffer one.
+
 ## 0.38.0
 
 ### Minor Changes

package/package.json

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

package/src/native-fetch-prelude.js

@@ -12,6 +12,15 @@ function __sbEnvValue() {
 function __sbSetCompat(date) {
   __sbCompatNow = date;
   Request._cd = date;
+  if (date >= "2026-11-15" && Error.captureStackTrace === undefined) Error.captureStackTrace = __sbCaptureStackTrace;
+}
+// V8's Error.captureStackTrace(target): drivers (pg, @neondatabase/serverless) call it on the errors they
+// build and rethrow. Porffor keeps no frames, so the stack is the first line, as Error.stack is.
+function __sbCaptureStackTrace(target) {
+  if (Object(target) !== target) throw new TypeError("Invalid argument");
+  const name = target.name === undefined ? "Error" : String(target.name);
+  const message = target.message === undefined ? "" : String(target.message);
+  Object.defineProperty(target, "stack", { value: message === "" ? name : name + ": " + message, configurable: true, writable: true, enumerable: false });
 }
 function __sbSetEnv(value) {
   __sbEnvNow = value;
@@ -4253,8 +4262,12 @@ function __sbRequestBody(body) {
 }
 
 function __sbRawBodyResponse(body, init) {
-  const resp = new Response(body == null ? "" : body, init);
-  if (body != null) {
+  // 204, 205 and 304 carry no body: the constructor refuses even an empty string for them, so a
+  // fetch() of any 204 (a DELETE, a PostgREST write) threw before the caller saw the response.
+  const status = init == null ? 200 : init.status;
+  const bodiless = status === 204 || status === 205 || status === 304;
+  const resp = new Response(bodiless ? null : body == null ? "" : body, init);
+  if (body != null && !bodiless) {
     let decoded = null;
     resp.text = () => {
       if (decoded === null) decoded = __sbFromUtf8(body);
@@ -12243,7 +12256,19 @@ function __sbFollowHop(op, msg, label, mode, signal, hops) {
 function __sbUpstream(op, msg, label, signal, always) {
   if (signal) signal.throwIfAborted();
   const promised = always || __sbCompatDate() >= "2026-10-22" || __sbAsyncAtAnyDate();
-  if (!__sbHttpAsyncEnabled() || !promised) return __sbUpstreamResponse(globalThis.__sbFetchUpstream(op, msg));
+  if (!promised) return __sbUpstreamResponse(globalThis.__sbFetchUpstream(op, msg));
+  if (!__sbHttpAsyncEnabled()) {
+    // A host that runs the exchange to the end before it returns (the standalone binary) still hands
+    // back a promise from 2026-10-22: fetch(url).then(...) is how most libraries call it, and a refusal
+    // rejects instead of throwing. Earlier dates keep the Response (the embedded transport's
+    // __sbAsyncAtAnyDate is true for sproutd's sake, not for this).
+    if (!always && __sbCompatDate() < "2026-10-22") return __sbUpstreamResponse(globalThis.__sbFetchUpstream(op, msg));
+    try {
+      return Promise.resolve(__sbUpstreamResponse(globalThis.__sbFetchUpstream(op, msg)));
+    } catch (e) {
+      return Promise.reject(e);
+    }
+  }
   if (__sbCompatDate() >= "2026-10-22") return __sbUpstreamStreamed(op, msg, label, signal);
   return new Promise((resolve, reject) => {
     let onAbort = null;

package/src/source.test.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { GUARDED_GLOBALS_DATE, validateHttpSyncSource } from "./source";
+
+const wrap = (body: string) => `var d={fetch(){${body}return new Response("ok");}};export{d as default};`;
+
+const GUARDED = [
+  // a bundled `buffer` polyfill declares its own Buffer
+  `function Buffer(a){return a;}Buffer.isBuffer=function(b){return b instanceof Buffer;};`,
+  // upstash: a polyfill behind a test for another global
+  `if(typeof atob==="undefined"){global.atob=(b)=>Buffer.from(b,"base64").toString("utf8");}`,
+  // supabase-js: a Node branch behind a feature test
+  `function b64(d){if(typeof Buffer!=="undefined")return Buffer.from(d).toString("base64");return btoa(d);}`,
+  `if(typeof Deno!=="undefined"&&typeof Deno.unrefTimer==="function"){Deno.unrefTimer(t);}`,
+  // @neondatabase/serverless: the feature test names the member itself
+  `var B=typeof globalThis.Buffer=="function"&&typeof globalThis.Buffer.allocUnsafe=="function"?globalThis.Buffer:null;`,
+  // an error message that mentions an API
+  `throw new Error("Buffer.write(string, encoding, offset[, length]) is no longer supported");`,
+  `// process.env is read here in Node\n`,
+];
+
+test("before the guarded-globals date every Node global match fails, as it always did", () => {
+  for (const body of GUARDED) {
+    expect(validateHttpSyncSource(wrap(body), "2026-10-22").ok).toBe(false);
+    expect(validateHttpSyncSource(wrap(body)).ok).toBe(false);
+  }
+});
+
+test("from the guarded-globals date a feature-tested use, a string and a comment pass", () => {
+  for (const body of GUARDED) expect(validateHttpSyncSource(wrap(body), GUARDED_GLOBALS_DATE).ok).toBe(true);
+});
+
+test("from the guarded-globals date an unguarded use still fails", () => {
+  for (const body of [
+    `var x=process.env.TOKEN;`,
+    `var b=Buffer.from("a");`,
+    `var b=new Buffer(4);`,
+    `var x=Bun.file("a");`,
+    // a feature test far above does not guard this one
+    `if(typeof Deno!=="undefined"){}${" ".repeat(700)}var x=process.env.TOKEN;`,
+  ]) {
+    const result = validateHttpSyncSource(wrap(body), GUARDED_GLOBALS_DATE);
+    expect(result.ok).toBe(false);
+  }
+});

package/src/source.ts

@@ -6,6 +6,8 @@ export type SourceValidation = { ok: true } | { ok: false; errors: string[] };
 // bundling there are no imports left to reject, and a dependency reaching for a
 // Node API has to fail exactly as hand-written code would. A bare specifier
 // that resolves to nothing never gets this far — the bundler fails first.
+const NODE_GLOBAL_USE = /\b(process|Bun|Deno|Buffer)\.[a-zA-Z_$]|\bnew\s+Buffer\s*\(/;
+
 const alwaysForbidden: Array<[RegExp, string]> = [
   [/^\s*import\s/m, "an import survived bundling — only static imports can be resolved at build time"],
   [/\bimport\s*\(/, "dynamic import() is not supported: nothing can resolve it at build time"],
@@ -20,13 +22,48 @@ const alwaysForbidden: Array<[RegExp, string]> = [
   // No whitespace is allowed around the `.`: real member access never has
   // any (`process.env`, always contiguous), while prose mentioning the word
   // does (a bundled comment ending "...unique to this process. The id...").
-  [/\b(process|Bun|Deno|Buffer)\.[a-zA-Z_$]|\bnew\s+Buffer\s*\(/, "Node, Bun, and Deno APIs are not supported"],
+  [NODE_GLOBAL_USE, "Node, Bun, and Deno APIs are not supported"],
   // `node:` only means something as an import specifier; a bare substring
   // match would also flag it appearing in an ordinary string a dependency
   // happens to construct (a doc link, a log message).
   [/['"`]node:/, "Node, Bun, and Deno APIs are not supported"],
 ];
 
+/**
+ * From this compatibility date the Node/Bun/Deno global check skips a use that sits behind a
+ * `typeof X` feature test (supabase-js, @neondatabase/serverless and many others carry a Node or
+ * Deno branch next to the Web one), a global the bundle declares itself (a bundled `buffer`
+ * polyfill) and one that only appears inside a string or comment. Earlier
+ * dates keep the plain pattern match. Proposed value, to be chosen by a maintainer.
+ */
+export const GUARDED_GLOBALS_DATE = "2026-11-15";
+
+const STRINGS_AND_COMMENTS = /"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|\/\/[^\n]*|\/\*[\s\S]*?\*\//g;
+
+/**
+ * True when the module reaches for a Node/Bun/Deno global that it neither declares itself nor
+ * feature-tests first. A bundled polyfill declares its own `Buffer` (`function Buffer(){}`), and a
+ * Node branch sits behind `typeof X !== "undefined"` or `typeof atob === "undefined"`.
+ */
+function usesNodeGlobalUnguarded(module: string): boolean {
+  const code = module.replace(STRINGS_AND_COMMENTS, (m) => (m[0] === "/" ? " " : m[0] + m[0]));
+  const declared = (name: string) => new RegExp("(?:function|class|var|let|const)\\s+" + name + "\\b").test(code);
+  const local = new Set(["process", "Bun", "Deno", "Buffer"].filter(declared));
+  const re = new RegExp(NODE_GLOBAL_USE.source, "g");
+  for (let m = re.exec(code); m !== null; m = re.exec(code)) {
+    const name = m[1] ?? "Buffer";
+    if (local.has(name)) continue;
+    const before = code.slice(Math.max(0, m.index - 600), m.index);
+    // `typeof globalThis.Buffer.from`: the use is the feature test itself.
+    if (/typeof\s+(?:(?:globalThis|self|global|window)\.)?$/.test(before)) continue;
+    if (new RegExp("typeof\\s+(?:(?:globalThis|self|global|window)\\.)?" + name + "\\b").test(before)) continue;
+    // `if (typeof atob === "undefined") { ... Buffer.from(...) }`: a test for something else, just before.
+    if (/typeof\s+[\w$.]+\s*[!=]==?\s*""/.test(before.slice(-200))) continue;
+    return true;
+  }
+  return false;
+}
+
 /** `new WebSocket(url)` connects out from this compatibility date (earlier, only WebSocketPair makes one). */
 export const OUTBOUND_WEBSOCKET_DATE = "2026-11-01";
 
@@ -48,7 +85,12 @@ export function validateHttpSyncSource(module: string, compatibilityDate?: strin
       "handler must default-export an object with fetch(request), scheduled() or queue(), or a WorkerEntrypoint class",
     );
   }
-  for (const [pattern, message] of alwaysForbidden) if (pattern.test(source)) errors.push(message);
+  const guardedGlobals = compatibilityDate !== undefined && compatibilityDate >= GUARDED_GLOBALS_DATE;
+  for (const [pattern, message] of alwaysForbidden) {
+    if (pattern === NODE_GLOBAL_USE && guardedGlobals ? !usesNodeGlobalUnguarded(source) : !pattern.test(source))
+      continue;
+    errors.push(message);
+  }
   if (
     /\bWebSocket\s*\(/.test(source) &&
     !(compatibilityDate !== undefined && compatibilityDate >= OUTBOUND_WEBSOCKET_DATE)

package/src/transport-embedded.js

@@ -3145,11 +3145,16 @@ typedef struct sb_async_job {
   char *host, *path, *method, *headers, *body, *out;
   size_t body_len;
 } sb_async_job;
+// sproutd runs one host per sprout among hundreds, so a few threads each; a standalone binary is the
+// only process of its app, and workerd lets one request hold 50 subrequests.
 #define SB_ASYNC_THREADS 8
+#define SB_ASYNC_THREADS_STANDALONE 32
 static pthread_mutex_t sb_async_lock = PTHREAD_MUTEX_INITIALIZER;
 static sb_async_job *sb_async_queue = 0, *sb_async_queue_tail = 0, *sb_async_done = 0, *sb_async_current = 0;
 static int sb_async_pipe[2] = { -1, -1 };
 static int sb_async_threads = 0;
+// The standalone server's way back onto its loop (uWS defer, patchAsyncWaker); set by sb_async_set_waker.
+static void (*sb_wsc_waker)(void) = 0;
 
 int sb_async_enable(void) {
   if (sb_async_pipe[0] >= 0) return sb_async_pipe[0];
@@ -3160,7 +3165,10 @@ int sb_async_enable(void) {
   }
   return sb_async_pipe[0];
 }
-int sb_async_enabled(void) { return sb_async_pipe[0] >= 0; }
+// A host runs requests off its loop when it watches the pipe (sproutd) or gave a waker (standalone).
+int sb_async_enabled(void) { return sb_async_pipe[0] >= 0 || sb_wsc_waker != 0; }
+// Only the pipe host (sproutd) has always answered fetch() with a promise; see __sbAsyncAtAnyDate.
+int sb_async_piped(void) { return sb_async_pipe[0] >= 0; }
 static void sb_async_free(sb_async_job* j) {
   free(j->host); free(j->path); free(j->method); free(j->headers); free(j->body); free(j->out); free(j);
 }
@@ -3168,8 +3176,12 @@ static void sb_async_free(sb_async_job* j) {
 static void sb_async_finish_locked(sb_async_job* j) {
   j->next = sb_async_done;
   sb_async_done = j;
-  char one = 1;
-  while (write(sb_async_pipe[1], &one, 1) < 0 && errno == EINTR) {}
+  if (sb_async_pipe[1] >= 0) {
+    char one = 1;
+    while (write(sb_async_pipe[1], &one, 1) < 0 && errno == EINTR) {}
+  }
+  // uWS's defer is thread-safe and never takes sb_async_lock, so calling it here cannot deadlock.
+  if (sb_wsc_waker) sb_wsc_waker();
 }
 static void* sb_async_thread(void* unused) {
   (void)unused;
@@ -3192,7 +3204,7 @@ static void sb_async_start(sb_async_job* j) {
   j->next = 0;
   if (sb_async_queue_tail) sb_async_queue_tail->next = j; else sb_async_queue = j;
   sb_async_queue_tail = j;
-  int spawn = sb_async_threads < SB_ASYNC_THREADS;
+  int spawn = sb_async_threads < (sb_async_pipe[0] >= 0 ? SB_ASYNC_THREADS : SB_ASYNC_THREADS_STANDALONE);
   if (spawn) sb_async_threads++;
   pthread_mutex_unlock(&sb_async_lock);
   if (!spawn) return;
@@ -3236,7 +3248,7 @@ static void (*sb_wsc_drain_hook)(void) = 0;
 // Host: the fd became readable. Fires each finished request's callback.
 void sb_async_drain(void) {
   char buf[64];
-  while (read(sb_async_pipe[0], buf, sizeof(buf)) > 0) {}
+  if (sb_async_pipe[0] >= 0) while (read(sb_async_pipe[0], buf, sizeof(buf)) > 0) {}
   if (sb_wsc_drain_hook) sb_wsc_drain_hook();
   pthread_mutex_lock(&sb_async_lock);
   sb_async_job* done = sb_async_done;
@@ -3294,7 +3306,6 @@ typedef struct sb_wsc {
 static pthread_mutex_t sb_wsc_lock = PTHREAD_MUTEX_INITIALIZER;
 static sb_wsc* sb_wscs = 0;
 static unsigned sb_wsc_next = 0;
-static void (*sb_wsc_waker)(void) = 0;
 void sb_async_set_waker(void (*wake)(void)) { sb_wsc_waker = wake; }
 static int sb_wsc_pipe_enabled(void) { return sb_async_pipe[0] >= 0; }
 static void sb_async_poke(void) {
@@ -4318,12 +4329,21 @@ function __sbHttpAsyncResult(asyncId) {
 // placeholder timer cleared, the reply is dropped when it arrives.
 function __sbCancelAsync() {}
 
-// sproutd ran fetch() off its loop, as a promise, at every compatibility date (B18).
+// sproutd ran fetch() off its loop, as a promise, at every compatibility date (B18). The standalone
+// server (a waker, no pipe) keeps the date its fetch() promise has always had.
 function __sbAsyncAtAnyDate() {
-  return true;
+  let res = false;
+  // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
+  Porffor.c`
+    int sb_async_piped(void);
+    if (sb_async_piped()) res = porf_box(1, 2);
+  `;
+  return res;
 }
 
-// Whether the host runs async requests (sb_async_enable was called).
+// Whether the host runs async requests: sproutd (sb_async_enable was called) at any date, the
+// standalone server (it gave a waker) from the date its fetch() leaves the loop, so an app that
+// relied on one request at a time across an `await fetch()` keeps that until it opts in.
 function __sbHttpAsyncEnabled() {
   let res = false;
   // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
@@ -4331,7 +4351,7 @@ function __sbHttpAsyncEnabled() {
     int sb_async_enabled(void);
     if (sb_async_enabled()) res = porf_box(1, 2);
   `;
-  return res;
+  return res && (__sbAsyncAtAnyDate() || __sbCompatDate() >= "2026-11-16");
 }
 
 // The outbound client's JSON reply -> the fetch op's result.

package/test/fixtures/async-fetch/README.md

@@ -0,0 +1,9 @@
+Repro for standalone `fetch()` off the event loop (compatibility date 2026-11-16).
+
+```sh
+bun slow.ts 19100 &                                   # /slow?delay=MS, /echo
+sproutboat build --standalone --target host .         # compatibility_date 2026-11-16
+PORT=19201 SB_EGRESS_ALLOW=127.0.0.1 ./dist/af-fan &
+curl 'localhost:19201/fan?n=20&delay=100'             # about 110 ms; 2,040 ms at 2026-11-15
+curl 'localhost:19201/order?delay=200' & curl 'localhost:19201/order?delay=200'   # interleave from 11-16
+```

package/test/fixtures/async-fetch/slow.ts

@@ -0,0 +1,17 @@
+// bun /tmp/af/slow.ts PORT : /slow?delay=ms answers "slow-<i>" after delay; /echo returns the body
+Bun.serve({
+  port: Number(process.argv[2] || 19100),
+  hostname: "0.0.0.0",
+  async fetch(req) {
+    const u = new URL(req.url);
+    if (u.pathname === "/slow") {
+      await Bun.sleep(Number(u.searchParams.get("delay") || 100));
+      return new Response("slow-" + (u.searchParams.get("i") ?? "x"));
+    }
+    if (u.pathname === "/echo")
+      return new Response("echo:" + (await req.text()) + ":" + req.headers.get("x-test"), {
+        headers: { "content-type": "text/x-echo" },
+      });
+    return new Response("nf", { status: 404 });
+  },
+});

package/test/fixtures/async-fetch/sproutboat.jsonc

@@ -0,0 +1,5 @@
+{
+  "name": "af-fan",
+  "main": "src/index.js",
+  "compatibility_date": "2026-11-16",
+}

package/test/fixtures/async-fetch/src/index.js

@@ -0,0 +1,50 @@
+let counter = 0;
+export default {
+  async fetch(request) {
+    const u = new URL(request.url);
+    if (u.pathname === "/ping") return new Response("ok");
+    const base = u.searchParams.get("base") || "http://127.0.0.1:19100";
+    if (u.pathname === "/fan") {
+      const n = Number(u.searchParams.get("n") || 20);
+      const delay = u.searchParams.get("delay") || "100";
+      const t0 = Date.now();
+      const rs = await Promise.all(
+        Array.from({ length: n }, (_, i) => fetch(base + "/slow?i=" + i + "&delay=" + delay).then((r) => r.text())),
+      );
+      return Response.json({ n, ms: Date.now() - t0, bodies: rs.slice(0, 3), last: rs[n - 1] });
+    }
+    if (u.pathname === "/one") {
+      const r = await fetch(base + "/slow?delay=" + (u.searchParams.get("delay") || "0"));
+      return new Response(await r.text(), { status: r.status });
+    }
+    if (u.pathname === "/post") {
+      const r = await fetch(base + "/echo", { method: "POST", body: "hello-" + ++counter, headers: { "x-test": "1" } });
+      return Response.json({ status: r.status, text: await r.text(), ct: r.headers.get("content-type") });
+    }
+    if (u.pathname === "/refuse") {
+      try {
+        await fetch("http://127.0.0.1:1/");
+        return new Response("no error", { status: 500 });
+      } catch (e) {
+        return Response.json({ rejected: true, name: e.name, message: String(e.message) });
+      }
+    }
+    if (u.pathname === "/abort") {
+      const ac = new AbortController();
+      setTimeout(() => ac.abort(), 20);
+      try {
+        await fetch(base + "/slow?delay=500", { signal: ac.signal });
+        return new Response("no abort", { status: 500 });
+      } catch (e) {
+        return Response.json({ aborted: true, name: e.name });
+      }
+    }
+    if (u.pathname === "/order") {
+      // global state across an await fetch
+      const mine = ++counter;
+      await fetch(base + "/slow?delay=" + (u.searchParams.get("delay") || "50")).then((r) => r.text());
+      return Response.json({ mine, after: counter });
+    }
+    return new Response("not found", { status: 404 });
+  },
+};

package/test/standalone-restart-stress.py

@@ -0,0 +1,348 @@
+#!/usr/bin/env python3
+"""Restart stress for a standalone binary (docs/standalone.md, "Restarting without dropping a request").
+
+    standalone-restart-stress.py BINARY --mode MODE [--restarts N] [--keepalive N] [--fresh N] [--writes]
+
+Linux. Continuous load against one port while the binary is replaced N times; the count that matters
+is how many requests failed. MODE says how the swap is done:
+
+  overlap     the old recipe: start the new copy on the same port (SO_REUSEPORT), SIGTERM the old one.
+              Closing the old listener resets whatever sits in its accept queue.
+  stop-start  SIGTERM the old copy, wait for it, start the new one. Nothing listens in between.
+  systemd     a socket + service pair of user units under `systemd --user`; each swap is
+              `systemctl --user restart`. The socket stays open, so connections queue.
+  usr2        run the binary directly; each swap replaces the file on disk (install + rename) and sends
+              SIGUSR2. The running copy starts the new one on its listening socket and drains.
+
+The load is FRESH threads (a connection per request) and KEEPALIVE threads (one connection reused,
+as a proxy's pool does). A reused connection the server closes in the same instant is retried once on
+a new connection, as every client retries an idempotent request, and counted separately. With --writes
+half the requests are POST /w against a D1 table (the app's /n route returns the row count), and the
+run ends by checking that every acknowledged write is in the table, so a swap that loses or doubles one
+shows up. The app is expected to answer GET /x with 200 and, for --writes, POST /w with the new row id.
+
+Prints one JSON line; exit status 1 on any failed request or lost write.
+"""
+import argparse, http.client, json, os, shutil, signal, socket, subprocess, sys, tempfile, threading, time
+from pathlib import Path
+
+ap = argparse.ArgumentParser()
+ap.add_argument("binary")
+ap.add_argument("--mode", required=True, choices=["overlap", "stop-start", "systemd", "usr2"])
+ap.add_argument("--restarts", type=int, default=30)
+ap.add_argument("--keepalive", type=int, default=3)
+ap.add_argument("--fresh", type=int, default=3)
+ap.add_argument("--writes", action="store_true")
+ap.add_argument("--fresh-delay-ms", type=float, default=3, help="pause between a fresh loader's requests (conntrack: every connection leaves a TIME_WAIT entry, and a full nf_conntrack table silently drops SYNs)")
+ap.add_argument("--settle-ms", type=int, default=250, help="pause between swaps")
+ap.add_argument("--env", action="append", default=[], help="KEY=value for the binary")
+args = ap.parse_args()
+
+binary = Path(args.binary).resolve()
+scratch = Path(tempfile.mkdtemp(prefix="sb-restart-"))
+installed = scratch / "app"
+shutil.copy(binary, installed)
+installed.chmod(0o755)
+data = scratch / "data"
+data.mkdir()
+with socket.socket() as s:
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+env = dict(os.environ, PORT=str(port), SB_DATA_DIR=str(data))
+for item in args.env:
+    k, _, v = item.partition("=")
+    env[k] = v
+
+stop = [False]
+lock = threading.Lock()
+stats = {"ok": 0, "retried": 0, "writes_acked": 0}
+failures = []
+latencies = []
+t_start = time.time()
+
+
+def note_failure(kind, err):
+    with lock:
+        failures.append({"t": round(time.time() - t_start, 3), "kind": kind, "error": err})
+
+
+def one_request(conn, write):
+    t0 = time.time()
+    if write:
+        conn.request("POST", "/w", body=b"x")
+    else:
+        conn.request("GET", "/x")
+    r = conn.getresponse()
+    body = r.read()
+    dt = time.time() - t0
+    with lock:
+        latencies.append(dt)
+    return r.status, body.decode(errors="replace"), r.will_close
+
+
+def record(status, body, write, kind):
+    if status == 200 or (write and status in (200, 201)):
+        with lock:
+            stats["ok"] += 1
+            if write:
+                stats["writes_acked"] += 1
+    else:
+        note_failure(kind, f"status {status} {body[:40]}")
+
+
+def fresh_loader(index):
+    n = 0
+    while not stop[0]:
+        time.sleep(args.fresh_delay_ms / 1000)
+        n += 1
+        write = args.writes and (n + index) % 2 == 0
+        c = http.client.HTTPConnection("127.0.0.1", port, timeout=20)
+        try:
+            status, body, _ = one_request(c, write)
+            record(status, body, write, "fresh")
+        except Exception as e:
+            note_failure("fresh", type(e).__name__ + ": " + str(e)[:80])
+        finally:
+            c.close()
+
+
+def keepalive_loader(index):
+    conn = None
+    n = 0
+    while not stop[0]:
+        n += 1
+        write = args.writes and (n + index) % 2 == 0
+        reused = conn is not None
+        if conn is None:
+            conn = http.client.HTTPConnection("127.0.0.1", port, timeout=20)
+        try:
+            status, body, closing = one_request(conn, write)
+            if closing:
+                conn.close()
+                conn = None
+            record(status, body, write, "keepalive")
+        except Exception as e:
+            conn.close()
+            conn = None
+            if not reused or write:
+                # A write is not retried: it may have been applied, and the point is to see it fail.
+                note_failure("keepalive", ("new connection: " if not reused else "write on reused connection: ") + type(e).__name__ + ": " + str(e)[:80])
+                continue
+            c2 = http.client.HTTPConnection("127.0.0.1", port, timeout=20)
+            try:
+                status, body, _ = one_request(c2, False)
+                with lock:
+                    stats["retried"] += 1
+                record(status, body, False, "keepalive")
+            except Exception as e2:
+                note_failure("keepalive", "retry failed: " + type(e2).__name__ + ": " + str(e2)[:80])
+            finally:
+                c2.close()
+
+
+def conntrack():
+    try:
+        return int(Path("/proc/sys/net/netfilter/nf_conntrack_count").read_text())
+    except OSError:
+        return 0
+
+
+def wait_ready(timeout=10):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            c = http.client.HTTPConnection("127.0.0.1", port, timeout=2)
+            c.request("GET", "/x")
+            if c.getresponse().status == 200:
+                c.close()
+                return True
+        except Exception:
+            pass
+        time.sleep(0.05)
+    return False
+
+
+procs = []
+unit = f"sbrs-{os.getpid()}"
+unit_dir = Path.home() / ".config/systemd/user"
+log_n = [0]
+
+
+def spawn(extra_env=None):
+    log_n[0] += 1
+    log = open(scratch / f"run{log_n[0]}.log", "w")
+    p = subprocess.Popen([str(installed)], cwd=scratch, env=dict(env, **(extra_env or {})), stdout=log, stderr=log, start_new_session=True)
+    procs.append(p)
+    return p
+
+
+def exited(p, limit):
+    try:
+        p.wait(limit)
+        return True
+    except subprocess.TimeoutExpired:
+        return False
+
+
+def alive(pid, child=None):
+    """Is pid still running? A zombie nobody reaped (the container case) is gone, and our own child is reaped here."""
+    if child is not None:
+        return child.poll() is None
+    try:
+        with open(f"/proc/{pid}/stat") as f:
+            return f.read().rsplit(")", 1)[1].split()[0] != "Z"
+    except OSError:
+        return False
+
+
+def replace_binary():
+    tmp = scratch / "app.new"
+    shutil.copy(binary, tmp)
+    tmp.chmod(0o755)
+    os.replace(tmp, installed)
+
+
+def sctl(*a):
+    return subprocess.run(["systemctl", "--user", *a], capture_output=True, text=True)
+
+
+summary = {"mode": args.mode, "binary": str(binary), "port": port}
+threads = []
+try:
+    while conntrack() > 20000:
+        time.sleep(5)
+    summary["conntrack_at_start"] = conntrack()
+    swap_ms = []
+    if args.mode == "systemd":
+        # Real unit files, not systemd-run: a transient service is garbage-collected when it stops,
+        # which takes its socket with it. These are the units docs/standalone.md describes.
+        unit_dir.mkdir(parents=True, exist_ok=True)
+        (unit_dir / f"{unit}.socket").write_text(f"[Socket]\nListenStream=127.0.0.1:{port}\nBacklog=4096\nTriggerLimitIntervalSec=0\n")
+        (unit_dir / f"{unit}.service").write_text(
+            f"[Unit]\nRequires={unit}.socket\n# A stress run restarts several times a second; the default limit (5 starts in 10 s) would fail the unit.\nStartLimitIntervalSec=0\n\n[Service]\nExecStart={installed}\nWorkingDirectory={scratch}\n"
+            f"Environment=PORT={port} SB_DATA_DIR={data}\n"
+            + "".join(f"Environment={item}\n" for item in args.env)
+            + "KillSignal=SIGTERM\nTimeoutStopSec=30\nMemoryMax=256M\nMemorySwapMax=0\n"
+        )
+        for step in (["daemon-reload"], ["start", f"{unit}.socket"]):
+            r = sctl(*step)
+            if r.returncode:
+                raise SystemExit("systemctl " + " ".join(step) + " failed: " + r.stderr)
+    else:
+        current = spawn()
+        newest_pid = current.pid
+    if not wait_ready():
+        raise SystemExit("the binary did not answer GET /x")
+    t_start = time.time()
+    for i in range(args.fresh):
+        threads.append(threading.Thread(target=fresh_loader, args=(i,), daemon=True))
+    for i in range(args.keepalive):
+        threads.append(threading.Thread(target=keepalive_loader, args=(i,), daemon=True))
+    for t in threads:
+        t.start()
+    time.sleep(1)
+    seen_logs = set()
+    for i in range(args.restarts):
+        t0 = time.time()
+        if args.mode == "overlap":
+            nxt = spawn()
+            time.sleep(0.4)  # up and accepting beside the old one
+            current.send_signal(signal.SIGTERM)
+            if not exited(current, 15):
+                note_failure("restart", "old copy did not exit in 15 s")
+                current.kill()
+            current = nxt
+        elif args.mode == "stop-start":
+            current.send_signal(signal.SIGTERM)
+            if not exited(current, 15):
+                note_failure("restart", "old copy did not exit in 15 s")
+                current.kill()
+            current = spawn()
+        elif args.mode == "systemd":
+            replace_binary()
+            r = sctl("restart", f"{unit}.service")
+            if r.returncode:
+                note_failure("restart", "systemctl restart: " + r.stderr[:80])
+        elif args.mode == "usr2":
+            replace_binary()
+            pid = newest_pid
+            os.kill(pid, signal.SIGUSR2)
+            # The successor is the old copy's child; it logs its pid into the old copy's log file.
+            deadline = time.time() + 15
+            newest_pid = None
+            logfile = scratch / f"run1.log"
+            while time.time() < deadline and newest_pid is None:
+                for line in logfile.read_text().splitlines():
+                    if "restart: started" in line and line not in seen_logs:
+                        seen_logs.add(line)
+                        newest_pid = int(line.rsplit(" ", 1)[1])
+                if newest_pid is None:
+                    time.sleep(0.05)
+            if newest_pid is None:
+                note_failure("restart", "no successor started")
+                break
+            # wait for the old pid to be gone
+            while time.time() < deadline and alive(pid, current if i == 0 else None):
+                time.sleep(0.02)
+            if not wait_ready(10):
+                note_failure("restart", "successor never answered")
+        swap_ms.append(round((time.time() - t0) * 1000))
+        time.sleep(args.settle_ms / 1000)
+    time.sleep(1)
+    stop[0] = True
+    for t in threads:
+        t.join(30)
+    lost = None
+    if args.writes:
+        try:
+            c = http.client.HTTPConnection("127.0.0.1", port, timeout=20)
+            c.request("GET", "/n")
+            rows = int(c.getresponse().read().decode().strip())
+            lost = stats["writes_acked"] - rows
+            summary["rows_in_table"] = rows
+        except Exception as e:
+            lost = f"could not read /n: {e}"
+    lat = sorted(latencies)
+    summary.update({
+        "restarts": args.restarts,
+        "swap_ms_median": sorted(swap_ms)[len(swap_ms) // 2] if swap_ms else 0,
+        "swap_ms_max": max(swap_ms or [0]),
+        "requests_ok": stats["ok"],
+        "reused_retried": stats["retried"],
+        "writes_acked": stats["writes_acked"],
+        "writes_unaccounted": lost,
+        "failed": len(failures),
+        "failures": failures[:12],
+        "latency_ms": {"p50": round(lat[len(lat) // 2] * 1000, 2) if lat else 0, "p99": round(lat[int(len(lat) * 0.99)] * 1000, 1) if lat else 0, "max": round(lat[-1] * 1000, 1) if lat else 0},
+        "seconds": round(time.time() - t_start, 1),
+        "conntrack_at_end": conntrack(),
+        "loaders": {"fresh": args.fresh, "keepalive": args.keepalive},
+    })
+finally:
+    stop[0] = True
+    for p in procs:
+        if p.poll() is None:
+            try:
+                os.killpg(p.pid, signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+    if args.mode == "usr2":
+        # successors are not our children: stop each by the pid it logged
+        for log in scratch.glob("run*.log"):
+            for line in log.read_text().splitlines():
+                if "restart: started" in line:
+                    try:
+                        os.kill(int(line.rsplit(" ", 1)[1]), signal.SIGKILL)
+                    except (ProcessLookupError, ValueError):
+                        pass
+    if args.mode == "systemd":
+        sctl("stop", f"{unit}.service", f"{unit}.socket")
+        for ext in ("socket", "service"):
+            (unit_dir / f"{unit}.{ext}").unlink(missing_ok=True)
+        sctl("daemon-reload")
+    time.sleep(0.5)
+    if not os.environ.get("KEEP_SCRATCH"):
+        shutil.rmtree(scratch, ignore_errors=True)
+    print(json.dumps(summary))
+bad = summary.get("failed", 1) or (summary.get("writes_unaccounted") not in (None, 0))
+sys.exit(1 if bad else 0)