sproutboat 0.47.0 → 0.49.0

package/CHANGELOG.md

@@ -10,6 +10,55 @@ maintained going forward by the `release` skill.
 
 ## Unreleased
 
+## [0.49.0] - 2026-10-31
+
+Built on `@sproutboat/runtime` 0.39.0, `@sproutboat/toolchain` 0.22.0 and `@sproutboat/wire` 0.21.2. Nothing an app can observe changes, so there is no new compatibility date.
+
+### Added
+
+- **A standalone binary restarts without dropping a request.** The listening socket is never closed by a restart: under systemd socket activation the binary serves on the socket it is given (`LISTEN_FDS`), and `kill -USR2` starts the binary now on disk as a child that inherits the socket and then drains. `SIGTERM` and `SIGINT` drain too (stop accepting, `Connection: close`, exit when idle). Tuned by `SB_DRAIN_SECONDS`, `SB_DRAIN_QUIET_MS` and `SB_EXEC_PATH`. On a 2-core box, 200 swaps under load by either route served over 100,000 requests each with none failed; the old recipe reset 134 of 283,966.
+- **`build --standalone --target linux-arm64`**, and `--target linux-x64` as a name for the default, build a static musl binary for an aarch64 box from any machine. uSockets, SQLite and BearSSL are built for the target and cached.
+- **`build --standalone --deploy-files`** writes a `FROM scratch` Dockerfile (6.5 MB image), a systemd socket and service, a `fly.toml` and one-command `deploy-vps.sh` and `deploy-fly.sh` scripts beside the binary.
+
+### Changed
+
+- The standalone docs say that several copies behind `SO_REUSEPORT` need `SB_SQLITE_EXCLUSIVE=0`, and cover restarting, targets, containers and Fly.io.
+
+### CI
+
+- The macOS runners moved from `macos-14` to `macos-15` ahead of the macOS 14 retirement.
+
+## [0.48.1] - 2026-10-31
+
+Same packages as 0.48.0 (`@sproutboat/runtime` 0.39.0, `@sproutboat/toolchain` 0.21.3, `@sproutboat/wire` 0.21.2). The v0.48.0 tag
+published the four platform packages but not `sproutboat` itself, because the release job's test run timed out; 0.48.1 publishes all
+five at one version.
+
+### Fixed
+
+- **The release test run no longer times out**: the native restore test builds two standalone binaries cold, which took 476 s on CI at
+  0.47.0 and over 600 s at 0.48.0 as the prelude grew; its limit is now 1,200 s.
+
+## [0.48.0] - 2026-10-30
+
+Built on `@sproutboat/runtime` 0.39.0, `@sproutboat/toolchain` 0.21.3 and `@sproutboat/wire` 0.21.2. Each change below that an
+existing app could observe starts at a new compatibility date; earlier dates answer as before.
+
+### Added
+
+- **Database clients that need only `fetch` or WebSocket build and run unmodified from `2026-11-15`** (`@libsql/client`,
+  `@neondatabase/serverless`, `@supabase/supabase-js`, `@upstash/redis`, `@planetscale/database`; 113 of 117 comparisons with workerd
+  match, the rest being the wording of a network error). The build check for Node, Bun and Deno globals skips a use behind a
+  `typeof` test, a global the bundle declares itself, and mentions in strings and comments; `Error.captureStackTrace` exists.
+
+### Fixed
+
+- **`fetch()` on a standalone binary returns a promise from `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".
+- **A `Uint8Array` subclass that redefines a builtin method** (a `Buffer` polyfill's `toString("hex")`) reaches its own method.
+- **A collector crash (SIGBUS)** when an object grew (toolchain 0.21.3).
+
 ## [0.47.0] - 2026-10-30
 
 Built on `@sproutboat/runtime` 0.38.0, `@sproutboat/toolchain` 0.21.1 and `@sproutboat/wire` 0.21.1.

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.47.0
+**Package:** `sproutboat` 0.49.0
 
 ## Commands
 
@@ -13,7 +13,7 @@
 | `check` | `[project-dir]` | Validate the config and entry point without building. |
 | `types` | `[project-dir]` | Write sproutboat-env.d.ts from the config, so an editor knows what `env` holds. `dev` and `deploy` refresh it when the config is newer. |
 | `dev` | `[project-dir] [--port <n>] [--no-watch]` | Run the project on this machine against a real broker, rebuilding on save. |
-| `build` | `[project-dir] [--target host] [--standalone] [--with-restore] [--emit-only]` | Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally, not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process. `--with-restore` adds an offline `APP ltx-restore --generation DIR --output NEW_DB [--txid N]` startup command to a standalone executable; it runs before app initialization. `--emit-only` stops after writing `.sproutboat/porffor-units/<shape>/sprout.generated.js`, the module Porffor would compile, and prints its path: every check still runs, nothing is compiled. |
+| `build` | `[project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--deploy-files] [--with-restore] [--emit-only]` | Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally, not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process; add `--target linux-arm64` for an aarch64 box (the default is `linux-x64`) and `--deploy-files` to write a Dockerfile, a systemd socket and service, a fly.toml and a push script beside it. `--with-restore` adds an offline `APP ltx-restore --generation DIR --output NEW_DB [--txid N]` startup command to a standalone executable; it runs before app initialization. `--emit-only` stops after writing `.sproutboat/porffor-units/<shape>/sprout.generated.js`, the module Porffor would compile, and prints its path: every check still runs, nothing is compiled. |
 | `toolchain` | `doctor [--json]` | Report the selected compiler inputs, cache locations, overrides, and host prerequisites without downloading or compiling anything. |
 | `deploy` | `[project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision]` | Build (unless --artifact), auto-provision id-less storage bindings and pin their ids into sproutboat.jsonc, print the report, upload, wait until the URL serves. The control plane skips an upload that matches the live artifact byte-for-byte. --dry-run stops before upload; --no-wait skips the health check; --no-provision leaves id-less bindings as ephemeral deploy-scoped stores. |
 | `versions` | `<list | view <version-id>> [project-dir]` | List the project's deployed versions, or show one version's artifact and bindings. |
@@ -32,7 +32,7 @@
 | `complete` | `[bash | zsh | fish]` | Print a shell completion script for the top-level commands (defaults to $SHELL). |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host] [--standalone] [--with-restore] [--emit-only] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami | complete [bash | zsh | fish]>
+usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--deploy-files] [--with-restore] [--emit-only] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami | complete [bash | zsh | fish]>
 ```
 
 ## Environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -64,9 +64,9 @@
     "@sproutboat/artifact": "^0.3.0",
     "@sproutboat/assets": "^0.3.0",
     "@sproutboat/config": "^0.6.0",
-    "@sproutboat/runtime": "^0.38.0",
-    "@sproutboat/toolchain": "^0.21.1",
-    "@sproutboat/wire": "^0.21.1"
+    "@sproutboat/runtime": "^0.39.0",
+    "@sproutboat/toolchain": "^0.22.0",
+    "@sproutboat/wire": "^0.21.2"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.85.0",
@@ -78,10 +78,10 @@
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
-    "@sproutboat/cli-darwin-arm64": "0.47.0",
-    "@sproutboat/cli-darwin-x64": "0.47.0",
-    "@sproutboat/cli-linux-arm64": "0.47.0",
-    "@sproutboat/cli-linux-x64": "0.47.0"
+    "@sproutboat/cli-darwin-arm64": "0.49.0",
+    "@sproutboat/cli-darwin-x64": "0.49.0",
+    "@sproutboat/cli-linux-arm64": "0.49.0",
+    "@sproutboat/cli-linux-x64": "0.49.0"
   },
   "engines": {
     "node": ">=18"

package/src/bearssl.ts

@@ -19,6 +19,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { LINUX_TARGETS, type BuildTarget } from "./targets";
 import { resolveHostCompiler } from "./toolchain";
 
 export const BEARSSL_VERSION = "0.6";
@@ -75,7 +76,7 @@ async function withBearsslLock<T>(dir: string, name: string, action: () => Promi
 }
 
 export type BearsslInput = {
-  target: "linux-x86_64" | "host";
+  target: BuildTarget;
   /** Zig binary, required for the linux target. */
   zigBin?: string;
 };
@@ -248,7 +249,7 @@ export async function ensureBearssl(input: BearsslInput): Promise<BearsslBuild>
   const [cc, ...prefix] =
     input.target === "host"
       ? (await resolveHostCompiler()).cc
-      : [input.zigBin ?? "zig", "cc", "-target", "x86_64-linux-musl"];
+      : [input.zigBin ?? "zig", "cc", "-target", LINUX_TARGETS[input.target].triple];
   const includes = [includeDir, resolve(tree, "src")];
   const sourceFiles = await sources(tree);
   const anchors = await trustAnchorSource(tree);

package/src/build.ts

@@ -9,6 +9,7 @@ import { sqliteStamp } from "./sqlite";
 import { bearsslStamp, ensureBearssl } from "./bearssl";
 import { compileSprout, loadPrelude, type Transport } from "./compile";
 import { compileCached } from "./compile-cache";
+import type { BuildTarget } from "./targets";
 import {
   ARTIFACT_SCHEMA_VERSION,
   CAPABILITY_PROFILE,
@@ -38,7 +39,7 @@ export type BuildInput = {
    * box, so `sproutboat dev` can run the sprout locally. The manifest records
    * the real target, which is what stops the result being deployed.
    */
-  target?: "linux-x86_64" | "host";
+  target?: BuildTarget;
   /** #15 — `embedded` compiles SQLite into the sprout instead of a broker
    *  transport. Defaults to the broker transport. */
   transport?: Transport;
@@ -129,6 +130,8 @@ async function prepareBuild(input: BuildInput) {
   const sourceHash = digest(source);
   const target = input.target ?? "linux-x86_64";
   const embedded = input.transport === "embedded";
+  if (target === "linux-arm64" && !embedded)
+    throw new Error("linux-arm64 builds are for --standalone: the platform that `deploy` targets runs x86_64");
 
   // #74 — split each storage-binding array into its binding-name list (the
   // legacy shape the prelude/broker read) plus a `resources` map { binding ->
@@ -420,7 +423,8 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     const manifest: ArtifactManifest & { compileMs: number } = {
       schemaVersion: ARTIFACT_SCHEMA_VERSION,
       project: input.config.name,
-      target: host ? hostTarget() : DEPLOY_TARGET,
+      // An arm64 binary is never deployable (the platform runs x86_64), so its manifest says what it is.
+      target: host ? hostTarget() : target === "linux-arm64" ? target : DEPLOY_TARGET,
       runtime: RUNTIME,
       capabilityProfile: CAPABILITY_PROFILE,
       porfforVersion: porfforVersion(),

package/src/compile.ts

@@ -15,7 +15,14 @@ import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { ensurePorfforPatched } from "./patch-porffor";
 import { buildNativeRestore } from "./native-restore";
-import { ensureUWebSockets, ensureUWebSocketsHost, resolveHostCompiler, UwsUnavailableError } from "./toolchain";
+import {
+  ensureUWebSockets,
+  ensureUWebSocketsHost,
+  ensureUWebSocketsStandalone,
+  resolveHostCompiler,
+  UwsUnavailableError,
+} from "./toolchain";
+import { isLinuxTarget, LINUX_TARGETS, linuxTriple, type BuildTarget } from "./targets";
 import { ensurePorffor } from "./porffor-toolchain";
 // The prelude + transports live in @sproutboat/runtime (next to wrap.ts, which
 // locates them by file URL). `preludePath`/`transportPath` read them from there
@@ -83,7 +90,7 @@ export type CompileInput = {
    * file. Anything that could be deployed stays at -O3.
    */
   optimize?: "dev" | "release";
-  /** Cross-compiler for `linux-x86_64`. Not needed, and not used, for `host`. */
+  /** Cross-compiler for a Linux target. Not needed, and not used, for `host`. */
   zigBin?: string;
   /** #126 — `env.<binding> = { id, tag, timestamp }`, baked directly into the module. */
   versionMetadata?: { binding: string; id: string; tag: string; timestamp: string };
@@ -93,7 +100,7 @@ export type CompileInput = {
    * dev` can actually serve a sprout on a developer's laptop — an arm64 Mac
    * cannot execute the deploy artifact.
    */
-  target?: "linux-x86_64" | "host";
+  target?: BuildTarget;
   /**
    * Write `generatedPath` exactly as a full compile would, then stop: no
    * Porffor, no uWebSockets, no compiler, nothing at `outPath`. For callers
@@ -169,10 +176,19 @@ function compileEnv(
   extraLink?: string[],
   extraCflags?: string[],
   compiler?: { cc: string[]; cxx: string[] },
+  linux?: { triple: string; uwsVariant: string },
 ) {
   const link = extraLink && extraLink.length > 0 ? extraLink.join(" ") : undefined;
   const cflags = extraCflags && extraCflags.length > 0 ? extraCflags.join(" ") : undefined;
-  const env = { ...process.env, PATH: path, SB_EXTRA_LINK: link, SB_EXTRA_CFLAGS: cflags };
+  const env = {
+    ...process.env,
+    PATH: path,
+    SB_EXTRA_LINK: link,
+    SB_EXTRA_CFLAGS: cflags,
+    // The toolchain patch (patchMuslTarget) reads these; unset, Porffor builds x86_64 against its usual tree.
+    SB_MUSL_TARGET: linux?.triple,
+    SB_UWS_VARIANT: linux?.uwsVariant,
+  };
   if (compiler) return { ...env, CC: compiler.cc.join(" "), CXX: compiler.cxx.join(" ") };
   return env;
 }
@@ -258,9 +274,12 @@ export async function compileSprout(input: CompileInput): Promise<void> {
   // the first build needs no `git` / `make`. The two targets keep separate
   // cache trees and separate uSockets.a, so seed whichever this build wants.
   // Fall back to Porffor's own git+make path if the archive is unusable.
+  let uwsVariant: string | undefined;
   try {
     if (input.target === "host") await ensureUWebSocketsHost();
-    else await ensureUWebSockets();
+    else if (input.transport === "embedded" && input.zigBin) {
+      uwsVariant = await ensureUWebSocketsStandalone(input.target ?? "linux-x86_64", input.zigBin);
+    } else await ensureUWebSockets();
   } catch (error) {
     if (!(error instanceof UwsUnavailableError)) throw error;
     if (process.env.SPROUTBOAT_BUILD_UWS_FROM_SOURCE !== "1") throw error;
@@ -308,8 +327,8 @@ export async function compileSprout(input: CompileInput): Promise<void> {
         directory: dirname(generatedPath),
         prelude: await loadPrelude("embedded"),
         porfforCommand: command,
-        cc: hostCompiler?.cc ?? [input.zigBin!, "cc", "-target", "x86_64-linux-musl"],
-        cxx: hostCompiler?.cxx ?? [input.zigBin!, "c++", "-target", "x86_64-linux-musl"],
+        cc: hostCompiler?.cc ?? [input.zigBin!, "cc", "-target", linuxTriple(input.target)],
+        cxx: hostCompiler?.cxx ?? [input.zigBin!, "c++", "-target", linuxTriple(input.target)],
         cflags: input.extraCflags ?? [],
         macho: input.target === "host" && process.platform === "darwin",
       })
@@ -326,6 +345,9 @@ export async function compileSprout(input: CompileInput): Promise<void> {
         [...(input.extraLink ?? []), ...restoreObjects],
         [...(input.extraCflags ?? []), ...(input.withRestore ? ["-Dmain=sb_app_main"] : [])],
         hostCompiler,
+        uwsVariant && input.target && isLinuxTarget(input.target)
+          ? { triple: LINUX_TARGETS[input.target].triple, uwsVariant }
+          : undefined,
       ),
     },
   );

package/src/main.ts

@@ -20,6 +20,8 @@ import { controlVersionWarning } from "./api-version";
 import { amber, bold, dim, leaf, ok, rose } from "./style";
 import { pathToFileURL } from "node:url";
 import { inspectToolchain } from "./toolchain";
+import { isLinuxTarget, parseTarget, TARGET_NAMES, type BuildTarget } from "./targets";
+import { writeDeployFiles } from "./standalone-deploy";
 import { parseTailArgs, runTail, TAIL_USAGE, tailQuery } from "./tail";
 
 // A compiled Bun executable is not a general-purpose `bun` command. Porffor
@@ -306,7 +308,7 @@ async function refreshTypes(projectDir: string, config: SproutboatConfig): Promi
   console.log(dim(`  ${TYPES_FILE} refreshed from sproutboat.jsonc`));
 }
 
-async function build(directory?: string, target: "linux-x86_64" | "host" = "linux-x86_64") {
+async function build(directory?: string, target: BuildTarget = "linux-x86_64") {
   const project = await readProject(directory);
   console.log(
     target === "host"
@@ -338,8 +340,9 @@ async function build(directory?: string, target: "linux-x86_64" | "host" = "linu
  */
 async function buildStandaloneBinary(
   directory: string | undefined,
-  target: "linux-x86_64" | "host",
+  target: BuildTarget,
   withRestore = false,
+  deployFiles = false,
 ) {
   const project = await readProject(directory);
   console.log(dim(`Building a standalone ${project.config.name} (${target})…`));
@@ -354,6 +357,12 @@ async function buildStandaloneBinary(
     });
     console.log(ok(`built ${result.outPath} (${(result.bytes / 1_000_000).toFixed(1)} MB)`));
     console.log(dim(`  run it: ${result.outPath}   ·   state lands in ./${project.config.name}.data`));
+    if (target === "linux-arm64") console.log(dim("  linux-arm64: runs on an aarch64 Linux box, not on this machine"));
+    if (deployFiles && isLinuxTarget(target)) {
+      const written = await writeDeployFiles({ name: project.config.name, target, binary: result.outPath });
+      console.log(ok(`deploy files in ${written.dir}`));
+      console.log(dim(`  ${written.files.join(" · ")}   ·   how to use them: docs/standalone.md`));
+    }
   } catch (error) {
     fail(error instanceof Error ? error.message : String(error));
   }
@@ -366,7 +375,7 @@ async function buildStandaloneBinary(
  * fails the build; no compiler, SQLite or BearSSL is acquired and no binary is
  * written.
  */
-async function emitOnly(directory: string | undefined, target: "linux-x86_64" | "host", standalone: boolean) {
+async function emitOnly(directory: string | undefined, target: BuildTarget, standalone: boolean) {
   const project = await readProject(directory);
   console.log(
     dim(`Emitting ${standalone ? "the standalone " : ""}${project.config.name} source (${target}, no native compile)…`),
@@ -1370,11 +1379,28 @@ switch (command) {
         "--with-restore requires --standalone without --emit-only",
         "build --standalone --with-restore [--target host] [project-dir]",
       );
-    const hostBuild = args.includes("--target") && args[args.indexOf("--target") + 1] === "host";
-    const directory = args.find((arg) => !arg.startsWith("--") && arg !== "host");
-    const target = hostBuild ? "host" : "linux-x86_64";
+    const targetAt = args.indexOf("--target");
+    const targetArg = targetAt >= 0 ? args[targetAt + 1] : undefined;
+    const target = targetAt < 0 ? "linux-x86_64" : parseTarget(targetArg);
+    if (target === undefined)
+      usageError(
+        `unknown --target ${targetArg === undefined ? "(missing)" : `"${targetArg}"`}`,
+        `build [--target ${TARGET_NAMES}] [project-dir]`,
+      );
+    const directory = args.find((arg, at) => !arg.startsWith("--") && (targetAt < 0 || at !== targetAt + 1));
+    const deployFiles = args.includes("--deploy-files");
+    if ((deployFiles || target === "linux-arm64") && !args.includes("--standalone"))
+      usageError(
+        `${deployFiles ? "--deploy-files" : "--target linux-arm64"} requires --standalone: the platform runs x86_64`,
+        "build --standalone [--target linux-x64 | linux-arm64] [--deploy-files] [project-dir]",
+      );
+    if (deployFiles && !isLinuxTarget(target))
+      usageError(
+        "--deploy-files needs a Linux target",
+        "build --standalone --target linux-x64 --deploy-files [project-dir]",
+      );
     if (args.includes("--emit-only")) await emitOnly(directory, target, args.includes("--standalone"));
-    else if (args.includes("--standalone")) await buildStandaloneBinary(directory, target, withRestore);
+    else if (args.includes("--standalone")) await buildStandaloneBinary(directory, target, withRestore, deployFiles);
     else await build(directory, target);
     break;
   }

package/src/sqlite.ts

@@ -16,6 +16,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
+import { LINUX_TARGETS, type BuildTarget } from "./targets";
 import { resolveHostCompiler } from "./toolchain";
 
 export const SQLITE_VERSION = "3.50.4";
@@ -134,8 +135,8 @@ async function acquireAmalgamation(dir: string): Promise<string> {
 }
 
 export type SqliteObjectInput = {
-  /** `host` compiles with cc; `linux-x86_64` cross-compiles with the pinned Zig. */
-  target: "linux-x86_64" | "host";
+  /** `host` compiles with cc; a Linux target cross-compiles with the pinned Zig. */
+  target: BuildTarget;
   /** Zig binary, required for the linux target. */
   zigBin?: string;
 };
@@ -151,7 +152,7 @@ export async function ensureSqliteObject(input: SqliteObjectInput): Promise<stri
   const [cmd, ...prefix] =
     input.target === "host"
       ? (await resolveHostCompiler()).cc
-      : [input.zigBin ?? "zig", "cc", "-target", "x86_64-linux-musl"];
+      : [input.zigBin ?? "zig", "cc", "-target", LINUX_TARGETS[input.target].triple];
   const command = [cmd, ...prefix];
   const validCache = async (): Promise<boolean> => {
     try {

package/src/standalone-deploy.ts

@@ -0,0 +1,211 @@
+/**
+ * Deploy recipes for a standalone binary: `build --standalone --deploy-files` writes them beside it.
+ *
+ * Nothing here terminates TLS. The binary is a plain HTTP server, and every recipe puts it behind
+ * something that owns the certificate (Fly's edge, a reverse proxy, a load balancer). The recipes are
+ * strings so they can be tested without a build; docs/standalone.md explains what they do.
+ */
+import { chmod, copyFile, mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { LINUX_TARGETS, type LinuxTarget } from "./targets";
+
+export type DeployFilesInput = {
+  /** The project name: the binary, unit and Fly app are all called this. */
+  name: string;
+  target: LinuxTarget;
+};
+
+/** A scratch image, so the container is the binary and nothing else. See docs/standalone.md. */
+export function dockerfile(input: DeployFilesInput): string {
+  const { name } = input;
+  return `# syntax=docker/dockerfile:1
+# ${LINUX_TARGETS[input.target].platform}. Build:  docker build --platform ${LINUX_TARGETS[input.target].platform} -t ${name} .
+# The binary is static and carries its own CA roots, so there is no base image and no libc.
+FROM scratch
+# 65532 is the usual unprivileged uid. data/ is an empty directory this recipe ships, so the volume
+# below starts out writable by that uid without a RUN step (scratch has no shell).
+COPY --chown=65532:65532 data/ /data/
+COPY --chown=65532:65532 --chmod=0755 ${name} /app/${name}
+ENV PORT=8080 SB_DATA_DIR=/data SB_DRAIN_SECONDS=8
+EXPOSE 8080
+VOLUME /data
+USER 65532:65532
+# SIGTERM drains: it stops accepting, answers what is in flight and exits. docker stop waits 10 s.
+STOPSIGNAL SIGTERM
+ENTRYPOINT ["/app/${name}"]
+`;
+}
+
+export function dockerignore(): string {
+  return "deploy-vps.sh\ndeploy-fly.sh\n*.service\n*.socket\nfly.toml\n";
+}
+
+/** The socket systemd keeps open across a restart: the connections waiting in it are never reset. */
+export function systemdSocket(input: DeployFilesInput): string {
+  const { name } = input;
+  return `[Unit]
+Description=${name} (listening socket)
+
+[Socket]
+# systemd binds this and hands it to ${name}.service as fd 3. The binary serves on it instead of
+# binding PORT. It stays open while the service stops and starts, so a restart resets nothing.
+ListenStream=8080
+Backlog=4096
+# By default systemd closes the socket if more than 200 starts are triggered in 2 s, which a busy
+# restart can do. Closing it is the reset this exists to avoid.
+TriggerLimitIntervalSec=0
+
+[Install]
+WantedBy=sockets.target
+`;
+}
+
+export function systemdService(input: DeployFilesInput): string {
+  const { name } = input;
+  return `[Unit]
+Description=${name}
+Requires=${name}.socket
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/opt/${name}/${name}
+# State (SQLite files, R2 objects) lives here; systemd creates it and owns it for the dynamic user.
+StateDirectory=${name}
+Environment=SB_DATA_DIR=/var/lib/${name}
+# Secrets and other settings, one KEY=value per line. The dash makes the file optional.
+EnvironmentFile=-/etc/${name}.env
+DynamicUser=yes
+# A restart sends SIGTERM: the old process answers what it has accepted and exits, then systemd
+# starts the new binary on the same socket. Allow it longer than SB_DRAIN_SECONDS.
+KillSignal=SIGTERM
+Environment=SB_DRAIN_SECONDS=20
+TimeoutStopSec=30
+Restart=on-failure
+NoNewPrivileges=yes
+ProtectSystem=strict
+ProtectHome=yes
+PrivateTmp=yes
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+/** One command: first run installs the units, every later run swaps the binary. */
+export function deployVpsScript(input: DeployFilesInput): string {
+  const { name } = input;
+  return `#!/bin/sh
+# Usage: ./deploy-vps.sh user@host [ssh options]
+# Copies the binary and the systemd units to a Linux box and restarts the service on its socket,
+# so the connections waiting at the moment of the swap are served by the new binary, not reset.
+# The user needs sudo on the box. TLS is yours: put nginx, Caddy or a load balancer in front of :8080.
+set -eu
+HOST=\${1:?usage: deploy-vps.sh user@host}
+shift
+HERE=$(cd "$(dirname "$0")" && pwd)
+scp "$@" "$HERE/${name}" "$HERE/${name}.service" "$HERE/${name}.socket" "$HOST:/tmp/"
+ssh "$@" "$HOST" 'sudo sh -eu' <<'REMOTE'
+mkdir -p /opt/${name}
+install -m 0755 /tmp/${name} /opt/${name}/${name}.new
+mv -f /opt/${name}/${name}.new /opt/${name}/${name}
+install -m 0644 /tmp/${name}.service /tmp/${name}.socket /etc/systemd/system/
+rm -f /tmp/${name} /tmp/${name}.service /tmp/${name}.socket
+systemctl daemon-reload
+systemctl enable --now ${name}.socket
+systemctl restart ${name}.service
+systemctl --no-pager --lines=5 status ${name}.service
+REMOTE
+`;
+}
+
+export function flyToml(input: DeployFilesInput): string {
+  const { name } = input;
+  return `app = "${name}"
+# Pick the region closest to your users: fly platform regions
+primary_region = "iad"
+kill_signal = "SIGTERM"
+kill_timeout = 10
+
+[build]
+  dockerfile = "Dockerfile"
+
+[env]
+  PORT = "8080"
+  SB_DATA_DIR = "/data"
+  SB_DRAIN_SECONDS = "8"
+
+# State lives on a volume. A volume attaches to one machine, so a deploy stops it and starts the new
+# one and there is a few seconds with no machine. For an app with no state (no KV, D1, R2, queues or
+# Durable Objects), delete this block and run two machines: Fly then replaces them one at a time.
+[mounts]
+  source = "data"
+  destination = "/data"
+
+# Fly terminates TLS at its edge and speaks plain HTTP to the binary.
+[[services]]
+  protocol = "tcp"
+  internal_port = 8080
+  auto_stop_machines = "off"
+  auto_start_machines = true
+  min_machines_running = 1
+
+  [[services.ports]]
+    port = 80
+    handlers = ["http"]
+    force_https = true
+
+  [[services.ports]]
+    port = 443
+    handlers = ["tls", "http"]
+
+  [[services.tcp_checks]]
+    grace_period = "5s"
+    interval = "10s"
+    timeout = "2s"
+
+[[vm]]
+  size = "shared-cpu-1x"
+  memory = "256mb"
+`;
+}
+
+/** One command: creates the app and its volume the first time, then deploys. Needs a logged-in fly CLI. */
+export function deployFlyScript(input: DeployFilesInput): string {
+  const { name } = input;
+  return `#!/bin/sh
+# Usage: ./deploy-fly.sh [region]
+# Needs the fly CLI, logged in (fly auth login). Creates the app and its 1 GB volume on the first run.
+set -eu
+cd "$(dirname "$0")"
+REGION=\${1:-iad}
+fly apps list --json | grep -q '"Name": *"${name}"' || fly apps create ${name}
+fly volumes list -a ${name} --json | grep -q '"name": *"data"' || fly volumes create data -a ${name} --region "$REGION" --size 1 --yes
+fly deploy -a ${name} --config fly.toml
+`;
+}
+
+export type DeployFiles = { dir: string; files: string[] };
+
+/** Write the recipes into `<binary>.deploy/`, with a copy of the binary where the Dockerfile and scp expect it. */
+export async function writeDeployFiles(input: DeployFilesInput & { binary: string }): Promise<DeployFiles> {
+  const dir = resolve(dirname(input.binary), `${basename(input.binary)}.deploy`);
+  await mkdir(resolve(dir, "data"), { recursive: true });
+  await writeFile(resolve(dir, "data/.keep"), "");
+  await copyFile(input.binary, resolve(dir, input.name));
+  await chmod(resolve(dir, input.name), 0o755);
+  const text: [string, string][] = [
+    ["Dockerfile", dockerfile(input)],
+    [".dockerignore", dockerignore()],
+    [`${input.name}.socket`, systemdSocket(input)],
+    [`${input.name}.service`, systemdService(input)],
+    ["fly.toml", flyToml(input)],
+    ["deploy-vps.sh", deployVpsScript(input)],
+    ["deploy-fly.sh", deployFlyScript(input)],
+  ];
+  for (const [file, body] of text) {
+    await writeFile(resolve(dir, file), body);
+    if (file.endsWith(".sh")) await chmod(resolve(dir, file), 0o755);
+  }
+  return { dir, files: [input.name, ...text.map(([file]) => file).filter((file) => file !== ".dockerignore")] };
+}

package/src/surface.ts

@@ -97,10 +97,10 @@ export const COMMANDS: readonly Command[] = [
     name: "build",
     group: "Develop",
     emoji: "🔨",
-    args: "[project-dir] [--target host] [--standalone] [--with-restore] [--emit-only]",
+    args: "[project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--deploy-files] [--with-restore] [--emit-only]",
     brief: "[project-dir]",
     summary:
-      "Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally, not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process. `--with-restore` adds an offline `APP ltx-restore --generation DIR --output NEW_DB [--txid N]` startup command to a standalone executable; it runs before app initialization. `--emit-only` stops after writing `.sproutboat/porffor-units/<shape>/sprout.generated.js`, the module Porffor would compile, and prints its path: every check still runs, nothing is compiled.",
+      "Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally, not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process; add `--target linux-arm64` for an aarch64 box (the default is `linux-x64`) and `--deploy-files` to write a Dockerfile, a systemd socket and service, a fly.toml and a push script beside it. `--with-restore` adds an offline `APP ltx-restore --generation DIR --output NEW_DB [--txid N]` startup command to a standalone executable; it runs before app initialization. `--emit-only` stops after writing `.sproutboat/porffor-units/<shape>/sprout.generated.js`, the module Porffor would compile, and prints its path: every check still runs, nothing is compiled.",
   },
   {
     name: "toolchain",

package/src/targets.ts

@@ -0,0 +1,50 @@
+/**
+ * The machines a binary can be built for.
+ *
+ * `linux-x86_64` is the deploy target (static musl, the one `deploy` accepts). `linux-arm64` is the
+ * same static musl build for an aarch64 box (a Raspberry Pi, Graviton, Ampere, an Apple-silicon
+ * Linux VM) and exists for `--standalone` only: the platform runs x86_64. `host` is this machine.
+ */
+export type LinuxTarget = "linux-x86_64" | "linux-arm64";
+export type BuildTarget = LinuxTarget | "host";
+
+type LinuxInfo = {
+  /** Zig and uSockets name for the architecture. */
+  arch: "x86_64" | "aarch64";
+  /** The Zig target triple: a static binary needs no libc on the box. */
+  triple: string;
+  /** Container platform for `docker --platform`. */
+  platform: "linux/amd64" | "linux/arm64";
+};
+
+export const LINUX_TARGETS = {
+  "linux-x86_64": { arch: "x86_64", triple: "x86_64-linux-musl", platform: "linux/amd64" },
+  "linux-arm64": { arch: "aarch64", triple: "aarch64-linux-musl", platform: "linux/arm64" },
+} satisfies Record<LinuxTarget, LinuxInfo>;
+
+const ALIASES = new Map<string, BuildTarget>([
+  ["host", "host"],
+  ["linux-x86_64", "linux-x86_64"],
+  ["linux-x64", "linux-x86_64"],
+  ["linux-amd64", "linux-x86_64"],
+  ["x86_64-linux", "linux-x86_64"],
+  ["linux-arm64", "linux-arm64"],
+  ["linux-aarch64", "linux-arm64"],
+  ["aarch64-linux", "linux-arm64"],
+]);
+
+/** `--target` value to a build target; undefined when it names none. */
+export function parseTarget(value: string | undefined): BuildTarget | undefined {
+  return value === undefined ? undefined : ALIASES.get(value);
+}
+
+export const TARGET_NAMES = "host | linux-x64 | linux-arm64";
+
+export function isLinuxTarget(target: BuildTarget): target is LinuxTarget {
+  return target !== "host";
+}
+
+/** The Zig triple for a Linux target; x86_64 for anything else, which is what Porffor builds by default. */
+export function linuxTriple(target: BuildTarget | undefined): string {
+  return LINUX_TARGETS[target === "linux-arm64" ? "linux-arm64" : "linux-x86_64"].triple;
+}

package/src/toolchain.ts

@@ -18,6 +18,7 @@ import embeddedUwsArchive from "../vendor/uwebsockets-360c276d-musl.tar.xz" with
 import { BEARSSL_VERSION } from "./bearssl";
 import { cachedPorfforRoot, PORFFOR_CHANNEL, PORFFOR_COMMIT } from "./porffor-toolchain";
 import { SQLITE_VERSION } from "./sqlite";
+import { LINUX_TARGETS, type LinuxTarget } from "./targets";
 
 export const ZIG_VERSION = "0.16.0";
 
@@ -695,3 +696,86 @@ function uwsCommit(): string {
 export function toolchainStamp(): string {
   return `zig-musl/${ZIG_VERSION}+porffor/${PORFFOR_COMMIT}+uws/${uwsCommit()}`;
 }
+
+/**
+ * Zero-drop restart (docs/standalone.md): a standalone binary's uSockets asks the binary for an
+ * inherited listening socket (systemd socket activation, or the predecessor of a SIGUSR2 restart)
+ * before it binds one. uSockets has no such hook, so its `bsd_create_listen_socket` gets one line, the
+ * same one sproutd's host build adds: a weak reference to `sb_inherited_listen_fd`, which the
+ * toolchain's native server defines. Anchored and idempotent, like every edit here.
+ */
+const USOCKETS_LISTEN_ANCHOR =
+  "LIBUS_SOCKET_DESCRIPTOR bsd_create_listen_socket(const char *host, int port, int options) {\n";
+const USOCKETS_LISTEN_HOOK =
+  "    extern int sb_inherited_listen_fd(const char *, int) __attribute__((weak));\n" +
+  "    if (sb_inherited_listen_fd) { int inherited = sb_inherited_listen_fd(host, port); if (inherited >= 0) return inherited; }\n";
+/** Bump when the hook above changes: it is part of the cache stamp, so a stale tree is rebuilt. */
+const USOCKETS_HOOK_VERSION = "listen-hook-1";
+
+export async function patchUSocketsListenHook(uSocketsDir: string): Promise<void> {
+  const file = resolve(uSocketsDir, "src/bsd.c");
+  const text = await readFile(file, "utf8");
+  if (text.includes("sb_inherited_listen_fd")) return;
+  if (text.split(USOCKETS_LISTEN_ANCHOR).length !== 2)
+    throw new UwsUnavailableError(`uSockets bsd.c changed: the listen-socket anchor is gone (${file})`);
+  await writeFile(file, text.replace(USOCKETS_LISTEN_ANCHOR, USOCKETS_LISTEN_ANCHOR + USOCKETS_LISTEN_HOOK));
+}
+
+/**
+ * The uWebSockets tree for a **standalone** Linux binary, built for `target`'s architecture.
+ *
+ * Same seeding as `ensureUWebSockets` (the vendored archive is a full checkout, and only
+ * `uSockets.a` depends on the target), but uSockets is compiled here, from the patched source, with
+ * the pinned Zig: for x86_64 as well as arm64, so the one recipe is the one that is tested. The tree
+ * lives beside the broker's (`-musl`), in `-musl-sa-<arch>`, so a deploy build keeps its unpatched
+ * uSockets. Porffor is pointed at it with `SB_UWS_VARIANT` (see the toolchain's patchMuslTarget).
+ *
+ * Returns the variant name to pass as `SB_UWS_VARIANT`.
+ */
+export async function ensureUWebSocketsStandalone(target: LinuxTarget, zigBin: string): Promise<string> {
+  const { arch, triple } = LINUX_TARGETS[target];
+  const variant = `sa-${arch}`;
+  const commit = uwsCommitFull();
+  const dir = resolve(homedir(), ".cache/porffor/deps", `uWebSockets-${commit}-musl-${variant}`);
+  const command = [zigBin, "cc", "-target", triple, "-std=c11", "-DLIBUS_NO_SSL", "-O3", USOCKETS_HOOK_VERSION];
+  if (await uwsComplete(dir, command)) return variant;
+
+  await withUwsLock(dir, async () => {
+    if (await uwsComplete(dir, command)) return;
+    const vendored = process.env.SPROUTBOAT_UWS_TARBALL || uwsVendorArchive(commit.slice(0, 8));
+    if (!existsSync(vendored)) throw new UwsUnavailableError(`no vendored uWebSockets archive at ${vendored}`);
+    if (!process.env.SPROUTBOAT_UWS_TARBALL) {
+      const actual = await sha256File(vendored);
+      if (actual !== UWS_TARBALL_SHA256) {
+        throw new UwsUnavailableError(
+          `vendored uWebSockets sha256 mismatch\n  expected ${UWS_TARBALL_SHA256}\n  got      ${actual}`,
+        );
+      }
+    }
+    await extractUws(vendored, dir);
+    const uSockets = resolve(dir, "uSockets");
+    // The archive carries a prebuilt x86_64 uSockets.a and its object; neither is this target's.
+    await rm(resolve(uSockets, "uSockets.a"), { force: true });
+    await rm(resolve(uSockets, "bsd.o"), { force: true });
+    await patchUSocketsListenHook(uSockets);
+
+    const sources = ["src/*.c", "src/eventing/*.c", "src/crypto/*.c", "src/io_uring/*.c"];
+    const build = Bun.spawn(
+      [
+        "sh",
+        "-c",
+        `"${zigBin}" cc -target ${triple} -std=c11 -Isrc -DLIBUS_NO_SSL -O3 -c ${sources.join(" ")} && ` +
+          `"${zigBin}" ar rcs uSockets.a *.o && rm -f *.o`,
+      ],
+      { cwd: uSockets, stdout: "pipe", stderr: "pipe" },
+    );
+    const [code, err] = await Promise.all([build.exited, new Response(build.stderr).text()]);
+    if (code !== 0 || !existsSync(resolve(uSockets, "uSockets.a"))) {
+      throw new UwsUnavailableError(
+        `could not build uSockets for ${triple}: ${err.trim().split("\n").slice(-3).join(" ")}`,
+      );
+    }
+    await writeUwsManifest(dir, command);
+  });
+  return variant;
+}