sproutboat 0.7.0 → 0.9.0

package/src/native-fetch-prelude.js

@@ -283,16 +283,10 @@ if (globalThis.crypto.randomUUID == null) {
 // sprout event-loop turn per request, so a blocking roundtrip is acceptable).
 // Wire frame:
 //   [u32 LE len][ <token> "\n" <json> ]   reply: [u32 LE len][ <json> ]
-// SB_BROKER_PORT / SB_BROKER_TOKEN are set by the supervisor next to $PORT.
-// If SB_BROKER_PORT is unset the shims below are never installed (compile.ts
-// only emits the __sbInstallBindings call when the project declares bindings),
-// so a plain sprout is byte-for-byte unchanged.
-// ponytail: text values only; still AF_INET loopback, not AF_UNIX. A failed
-// exchange reconnects and resends once — a broker crash between "request applied"
-// and "reply read" can double-apply a non-idempotent op (queue.send, INSERT);
-// the old fresh-connection-per-call path just failed the call there instead.
-// Binary values + AF_UNIX = v2.
-
+// Shared C preamble: the headers, the two Porffor marshalling helpers every
+// inline-C block uses, and the CSPRNG. Lives here rather than in a transport so
+// both transports — and __sbRandomBytes / __sbEnv below — compile against the
+// same declarations.
 // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
 Porffor.c`
 #include <sys/socket.h>
@@ -330,118 +324,9 @@ static int sb_os_random(unsigned char* buf, size_t n) {
   return 0;
 }
 
-static int sb_io_all(int fd, unsigned char* buf, size_t len, int writing) {
-  size_t done = 0;
-  while (done < len) {
-    long n = writing ? write(fd, buf + done, len - done) : read(fd, buf + done, len - done);
-    if (n <= 0) {
-      if (n < 0 && errno == EINTR) continue;
-      return -1;
-    }
-    done += (size_t)n;
-  }
-  return 0;
-}
-
-// One long-lived loopback connection to the broker, reused across every binding
-// call. The broker frames each request/reply independently and keeps the socket
-// open, so the steady-state per-call cost is just write + read — no socket(),
-// connect() handshake or close() each time. -1 = not connected.
-static int sb_broker_fd = -1;
-
-static int sb_broker_connect(void) {
-  const char* port_s = getenv("SB_BROKER_PORT");
-  if (!port_s) return -10;
-  signal(SIGPIPE, SIG_IGN); // a dead broker must yield EPIPE, not kill the sprout
-  int fd = socket(AF_INET, SOCK_STREAM, 0);
-  if (fd < 0) return -1;
-  int one = 1;
-  setsockopt(fd, IPPROTO_TCP, TCP_NODELAY, &one, sizeof(one));
-  struct sockaddr_in addr;
-  memset(&addr, 0, sizeof(addr));
-  addr.sin_family = AF_INET;
-  addr.sin_port = htons((unsigned short)atoi(port_s));
-  addr.sin_addr.s_addr = htonl(0x7f000001u); // 127.0.0.1
-  if (connect(fd, (struct sockaddr*)&addr, sizeof(addr)) != 0) { close(fd); return -2; }
-  sb_broker_fd = fd;
-  return 0;
-}
-
-// Send one framed request, read one framed reply, on the persistent fd.
-static int sb_broker_exchange(const char* req, size_t req_len, char** resp_out, size_t* resp_len_out) {
-  const char* tok = getenv("SB_BROKER_TOKEN");
-  size_t tok_len = tok ? strlen(tok) : 0;
-
-  // frame body: token "\n" json
-  size_t body_len = tok_len + 1 + req_len;
-  unsigned char* frame = (unsigned char*)malloc(4 + body_len);
-  if (!frame) return -5;
-  frame[0] = (unsigned char)(body_len & 0xff);
-  frame[1] = (unsigned char)((body_len >> 8) & 0xff);
-  frame[2] = (unsigned char)((body_len >> 16) & 0xff);
-  frame[3] = (unsigned char)((body_len >> 24) & 0xff);
-  if (tok_len) memcpy(frame + 4, tok, tok_len);
-  frame[4 + tok_len] = '\n';
-  if (req_len) memcpy(frame + 4 + tok_len + 1, req, req_len);
-  int wr = sb_io_all(sb_broker_fd, frame, 4 + body_len, 1);
-  free(frame);
-  if (wr != 0) return -3;
-
-  unsigned char rhdr[4];
-  if (sb_io_all(sb_broker_fd, rhdr, 4, 0) != 0) return -4;
-  size_t rlen = (size_t)rhdr[0] | ((size_t)rhdr[1] << 8) | ((size_t)rhdr[2] << 16) | ((size_t)rhdr[3] << 24);
-
-  char* buf = (char*)malloc(rlen ? rlen : 1);
-  if (!buf) return -5;
-  if (rlen && sb_io_all(sb_broker_fd, (unsigned char*)buf, rlen, 0) != 0) { free(buf); return -6; }
-
-  *resp_out = buf;
-  *resp_len_out = rlen;
-  return 0;
-}
-
-static int sb_broker_roundtrip(const char* req, size_t req_len, char** resp_out, size_t* resp_len_out) {
-  *resp_out = NULL;
-  *resp_len_out = 0;
-  // Two tries: a broker restart (or an idle-closed socket) invalidates the fd,
-  // so a failed exchange drops the connection and reconnects once before failing.
-  for (int attempt = 0; attempt < 2; attempt++) {
-    if (sb_broker_fd < 0) {
-      int rc = sb_broker_connect();
-      if (rc != 0) return rc;
-    }
-    int rc = sb_broker_exchange(req, req_len, resp_out, resp_len_out);
-    if (rc == 0) return 0;
-    close(sb_broker_fd);
-    sb_broker_fd = -1;
-  }
-  return -3;
-}
 `;
 
-// One request string in, one reply string out. `reqJson` is a parameter, so the
-// generated C names it directly in the RawC block below.
-// oxlint-disable-next-line no-unused-vars -- `reqJson` is read inside the RawC block below, not by JS.
-function __sbCall(reqJson) {
-  let res = "";
-  // oxlint-disable-next-line no-unused-expressions -- Porffor.c`...` is inline C the compiler consumes, not a JS expression.
-  Porffor.c`
-    const char* __req; size_t __reqlen; char* __reqowned = 0;
-    porf_native_fetch_read_value(reqJson, &__req, &__reqlen, &__reqowned);
-    char* __resp = 0; size_t __resplen = 0;
-    int __rc = sb_broker_roundtrip(__req, __reqlen, &__resp, &__resplen);
-    if (__reqowned) free(__reqowned);
-    if (__rc == 0) {
-      res = porf_box((f64)porf_native_fetch_alloc_bytestring(__resp, __resplen), 195);
-      free(__resp);
-    } else {
-      char __e[40];
-      int __n = snprintf(__e, sizeof(__e), "{\"ok\":false,\"error\":\"broker rc %d\"}", __rc);
-      res = porf_box((f64)porf_native_fetch_alloc_bytestring(__e, (size_t)__n), 195);
-    }
-  `;
-  return res;
-}
+// TRANSPORT: wrap.ts splices one of transport-broker.js / transport-embedded.js here.
 
 // `nStr` is the decimal byte count as a string (same string-param pattern as
 // __sbEnv). Returns a bytestring of that many CSPRNG bytes, or '' on failure.
@@ -469,8 +354,14 @@ function __sbRandomBytes(nStr) {
   return out;
 }
 
+// #63 — every request carries the protocol version it was built against and an
+// id unique to this process. The id is what makes a resend safe: the transport
+// retries the *same bytes*, so a broker that already applied the request can
+// recognise it and replay its answer instead of applying it twice.
+var __sbReqId = 0;
+
 function __sbRpc(op, extra) {
-  const req = { op };
+  const req = { v: 1, id: ++__sbReqId, op };
   if (extra) for (const k in extra) req[k] = extra[k];
   const reply = JSON.parse(__sbCall(JSON.stringify(req)));
   if (reply && reply.ok === false) throw new Error(`sproutboat ${op}: ${reply.error || "failed"}`);
@@ -609,16 +500,19 @@ globalThis.__sbInstallBindings = function (target, bindings) {
     target[name] = {
       put(key, value, options) {
         const o = options || {};
-        return __sbRpc("r2.put", {
-          bucket: name,
-          key: String(key),
-          body: value == null ? "" : String(value),
-          httpMetadata: o.httpMetadata || {},
-          customMetadata: o.customMetadata || {},
-        }).object;
+        // #56 — the body goes out of band where the transport allows it.
+        return __sbR2Put(
+          name,
+          String(key),
+          value == null ? "" : String(value),
+          o.httpMetadata || {},
+          o.customMetadata || {},
+        ).object;
       },
       get(key) {
-        const r = __sbRpc("r2.get", { bucket: name, key: String(key) });
+        // #56 — bytes come back out of band on a transport that supports it, so
+        // an object body is never JSON-escaped into a frame.
+        const r = __sbR2Get(name, String(key));
         return r.found ? __sbR2Object(r.object, r.body == null ? "" : r.body) : null;
       },
       head(key) {
@@ -693,8 +587,8 @@ globalThis.__sbInstallBindings = function (target, bindings) {
 
   // Static assets: env.<ASSETS>.fetch(request) -> broker `assets.get`. The edge
   // already serves matching files directly; the sprout only calls this for paths
-  // it wants to own (SPA fallback, auth-gated files). Text assets only — binary
-  // files go through the edge (the broker frame is UTF-8 JSON).
+  // it wants to own (SPA fallback, auth-gated files). The transport keeps the
+  // body byte-preserving for binary assets.
   if (bindings.assets) {
     target[bindings.assets] = {
       fetch(input) {
@@ -704,7 +598,7 @@ globalThis.__sbInstallBindings = function (target, bindings) {
         } catch {
           /* use as-is */
         }
-        const r = __sbRpc("assets.get", { path });
+        const r = globalThis.__sbAssetsGet(path);
         const headers = {};
         if (r.type) headers["content-type"] = r.type;
         if (r.found) headers["etag"] = '"' + r.hash + '"';
@@ -713,6 +607,34 @@ globalThis.__sbInstallBindings = function (target, bindings) {
     };
   }
 
+  // #48 — worker-to-worker. Same wire shape as outbound fetch, but the broker
+  // resolves the target itself and forwards it internally, so this is not
+  // egress and is not subject to the outbound allowlist.
+  for (let i = 0; i < (bindings.services || []).length; i++) {
+    const binding = bindings.services[i].binding;
+    target[binding] = {
+      fetch(input, init) {
+        const url = __sbIsStr(input) ? input : String((input && input.url) || "https://service/");
+        const opts = init || (!__sbIsStr(input) && input) || {};
+        const headers = [];
+        if (opts.headers) {
+          if (__sbIsFn(opts.headers.forEach)) opts.headers.forEach((v, k) => headers.push([k, v]));
+          else for (const k in opts.headers) headers.push([k, opts.headers[k]]);
+        }
+        const r = __sbRpc("service.fetch", {
+          binding,
+          url,
+          method: opts.method || "GET",
+          headers,
+          body: opts.body == null ? null : String(opts.body),
+        });
+        const respHeaders = new Headers();
+        for (let j = 0; j < (r.headers || []).length; j++) respHeaders.set(r.headers[j][0], r.headers[j][1]);
+        return new Response(r.body == null ? "" : r.body, { status: r.status || 502, headers: respHeaders });
+      },
+    };
+  }
+
   if ((bindings.outbound || []).length > 0) {
     globalThis.fetch = function (input, init) {
       const url = __sbIsStr(input) ? input : String(input.url);
@@ -858,6 +780,19 @@ function __sbDOStorage(cls, id) {
     deleteAll() {
       __sbRpc("do.storage.delete_all", { cls, id });
     },
+    // #125 — alarms. Cloudflare takes a Date or epoch ms; at most one is
+    // pending per object, so setting one replaces any earlier alarm.
+    setAlarm(when) {
+      const at = when instanceof Date ? when.getTime() : Number(when);
+      __sbRpc("do.alarm.set", { cls, id, at: at });
+    },
+    getAlarm() {
+      const r = __sbRpc("do.alarm.get", { cls, id });
+      return r.at == null ? null : r.at;
+    },
+    deleteAlarm() {
+      __sbRpc("do.alarm.delete", { cls, id });
+    },
     list(options) {
       const o = options || {};
       const r = __sbRpc("do.storage.list", {
@@ -898,7 +833,14 @@ function __sbEnv(name) {
 
 function __sbTriggerAuthed(request) {
   const want = __sbEnv("SB_BROKER_TOKEN");
-  if (!want) return true; // no token configured (local/dev)
+  // No token configured means no caller can be trusted to send one, so refuse
+  // rather than wave the request through. Every path that legitimately delivers
+  // a trigger over HTTP sets SB_BROKER_TOKEN — the supervisor per deployment,
+  // `sproutboat dev`, the standalone launcher. The one build that has no token
+  // is the embedded binary (#15), which fires its own triggers in-process and
+  // is also the one most likely to be listening on a public interface: exactly
+  // where "anyone may invoke scheduled()" would be a hole.
+  if (!want) return false;
   return request.headers.get("x-sb-token") === want;
 }
 
@@ -931,50 +873,67 @@ globalThis.__sbEntry = function (handlers, request) {
 
   if (trigger === "queue") {
     if (!__sbIsFn(handlers.queue)) return new Response("no queue handler", { status: 404 });
+    const result = __sbRunQueueBatch(handlers, __sbReadJson(request));
+    return new Response(JSON.stringify(result), { headers: { "content-type": "application/json" } });
+  }
+
+  if (trigger === "alarm") {
     const body = __sbReadJson(request);
-    const acked = [];
-    const retried = [];
-    const raw = body.messages || [];
-    const messages = [];
-    for (let i = 0; i < raw.length; i++) {
-      const m = raw[i];
-      const msg = {
-        id: m.id,
-        timestamp: m.timestamp,
-        attempts: m.attempts || 1,
-        body: __sbTryParse(m.body),
-        ack() {
-          if (acked.indexOf(m.id) === -1) acked.push(m.id);
-        },
-        retry() {
-          if (retried.indexOf(m.id) === -1) retried.push(m.id);
-        },
-      };
-      messages.push(msg);
-    }
-    const batch = {
-      queue: body.queue || "",
-      messages,
-      ackAll() {
-        for (let i = 0; i < messages.length; i++) messages[i].ack();
-      },
-      retryAll() {
-        for (let i = 0; i < messages.length; i++) messages[i].retry();
-      },
-    };
-    handlers.queue(batch);
-    // default: any message neither acked nor retried is treated as acked
-    for (let i = 0; i < messages.length; i++) {
-      if (acked.indexOf(messages[i].id) === -1 && retried.indexOf(messages[i].id) === -1) acked.push(messages[i].id);
-    }
-    return new Response(JSON.stringify({ ack: acked, retry: retried }), {
-      headers: { "content-type": "application/json" },
-    });
+    const inst = __sbGetDOInstance(String(body.cls || ""), String(body.id || ""));
+    if (!__sbIsFn(inst.alarm)) return new Response("no alarm handler", { status: 404 });
+    inst.alarm();
+    return new Response("", { status: 204 });
   }
 
   return new Response("unknown trigger", { status: 400 });
 };
 
+/**
+ * Run one queue batch through the handler and report what it acked.
+ *
+ * Shared so the two ways a batch can arrive agree: over HTTP from the broker
+ * (deployed, and the phase-0 standalone launcher), or straight from the local
+ * timer in an embedded binary that has no broker to be delivered from.
+ */
+function __sbRunQueueBatch(handlers, body) {
+  const acked = [];
+  const retried = [];
+  const raw = body.messages || [];
+  const messages = [];
+  for (let i = 0; i < raw.length; i++) {
+    const m = raw[i];
+    const msg = {
+      id: m.id,
+      timestamp: m.timestamp,
+      attempts: m.attempts || 1,
+      body: __sbTryParse(m.body),
+      ack() {
+        if (acked.indexOf(m.id) === -1) acked.push(m.id);
+      },
+      retry() {
+        if (retried.indexOf(m.id) === -1) retried.push(m.id);
+      },
+    };
+    messages.push(msg);
+  }
+  const batch = {
+    queue: body.queue || "",
+    messages,
+    ackAll() {
+      for (let i = 0; i < messages.length; i++) messages[i].ack();
+    },
+    retryAll() {
+      for (let i = 0; i < messages.length; i++) messages[i].retry();
+    },
+  };
+  handlers.queue(batch);
+  // default: any message neither acked nor retried is treated as acked
+  for (let i = 0; i < messages.length; i++) {
+    if (acked.indexOf(messages[i].id) === -1 && retried.indexOf(messages[i].id) === -1) acked.push(messages[i].id);
+  }
+  return { ack: acked, retry: retried };
+}
+
 function __sbReadJson(request) {
   try {
     return JSON.parse(request.body == null ? "{}" : String(request.body));

package/src/patch-porffor.ts

@@ -16,20 +16,119 @@ import { readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { porfforRoot } from "./toolchain";
 
-// Splice INJECT in immediately after the opening brace, before the return.
+// Each edit below is independent and idempotent, with its own marker: a file
+// patched by an older version of this file must still receive the newer edits.
 const ANCHOR = "f64 porf_native_fetch_get_port(void) {\n";
-const INJECT =
+
+/** Port from $PORT (the supervisor and `sproutboat dev` set it). */
+const ENV_INJECT =
   '  const char* __sb_port = getenv("PORT");\n' +
   "  if (__sb_port && *__sb_port) { long __sb_v = strtol(__sb_port, NULL, 10); if (__sb_v > 0 && __sb_v < 65536) return (f64)__sb_v; }\n";
-const MARKER = 'getenv("PORT")';
+const ENV_MARKER = 'getenv("PORT")';
+
+// #15 — no `--port` flag: Porffor's native-fetch entry point calls
+// `porf_init(0, NULL)` (see porf_native_fetch_runtime_init in render.js), so a
+// native-fetch binary never sees argv at all. A standalone binary takes its
+// port and data directory from the environment instead, which is what systemd
+// and docker set anyway. Worth an upstream note alongside the $PORT ask.
+
+/**
+ * #15 — let the build add objects to the native-fetch link line.
+ *
+ * Porffor builds `linkArgs` as a fixed array, so an embedded backend that needs
+ * SQLite compiled into the sprout has nowhere to put it. `CXX` is not a way in:
+ * a musl (deploy) build overrides it outright. This splices one spread of
+ * `SB_EXTRA_LINK` before `-lm`, inert unless the variable is set.
+ */
+const LINK_ANCHOR = "          uSocketsArchive,\n          '-lm'\n";
+const LINK_INJECT =
+  "          ...(process.env.SB_EXTRA_LINK ? process.env.SB_EXTRA_LINK.split(' ').filter(Boolean) : []),\n";
+const LINK_MARKER = "SB_EXTRA_LINK";
+
+/**
+ * #15 — and the same for the compile step, so the prelude's inline C can
+ * `#include <bearssl.h>`. The link patch alone is not enough: Porffor compiles
+ * the generated C from stdin with a fixed argument list, so there is otherwise
+ * no way to add an include path.
+ */
+const CFLAGS_ANCHOR = "          '-xc', '-', '-c',\n";
+const CFLAGS_INJECT =
+  "          ...(process.env.SB_EXTRA_CFLAGS ? process.env.SB_EXTRA_CFLAGS.split(' ').filter(Boolean) : []),\n";
+const CFLAGS_MARKER = "SB_EXTRA_CFLAGS";
+
+/**
+ * #56 — make the inbound request-body limit configurable.
+ *
+ * Porffor's uWebSockets shim hardcodes 1 MiB and answers anything larger with a
+ * bare `413 request body too large` before the handler runs, so a project can
+ * neither accept a bigger upload nor say anything useful about the refusal.
+ *
+ * The default stays 1 MiB: a larger body is held in memory whole, so raising it
+ * is a decision about this deployment's memory, not something to inherit.
+ */
+const BODY_ANCHOR = "static const size_t REQUEST_BODY_MAX_BYTES = 1024u * 1024u;";
+const BODY_INJECT = `static size_t sb_request_body_max(void) {
+  static size_t cached = 0;
+  if (cached == 0) {
+    const char* raw = getenv("SB_REQUEST_BODY_MAX");
+    long parsed = raw && *raw ? atol(raw) : 0;
+    cached = parsed > 0 ? (size_t)parsed : 1024u * 1024u;
+  }
+  return cached;
+}
+#define REQUEST_BODY_MAX_BYTES sb_request_body_max()`;
+const BODY_MARKER = "sb_request_body_max";
 
 let done = false;
 
+/** The uWebSockets shim source, which is where the body limit lives. */
+async function patchBodyLimit(): Promise<void> {
+  const file = resolve(porfforRoot(), "compiler/uwebsockets.js");
+  const src = await readFile(file, "utf8");
+  if (src.includes(BODY_MARKER)) return;
+  if (!src.includes(BODY_ANCHOR)) {
+    throw new Error(
+      `could not patch Porffor's request body limit: anchor not found in ${file}. ` +
+        "Porffor's uWebSockets shim changed — check patches/UPSTREAM.md.",
+    );
+  }
+  await writeFile(file, src.replace(BODY_ANCHOR, BODY_INJECT));
+}
+
+async function patchCompilerArgs(): Promise<void> {
+  const file = resolve(porfforRoot(), "compiler/index.js");
+  let src = await readFile(file, "utf8");
+  let changed = false;
+  for (const [marker, anchor, inject, what] of [
+    [LINK_MARKER, LINK_ANCHOR, LINK_INJECT, "extra link args"],
+    [CFLAGS_MARKER, CFLAGS_ANCHOR, CFLAGS_INJECT, "extra compiler flags"],
+  ] as const) {
+    if (src.includes(marker)) continue;
+    const at = src.indexOf(anchor);
+    if (at === -1) {
+      throw new Error(
+        `could not patch Porffor for ${what}: anchor not found in ${file}. ` +
+          "Porffor's native-fetch build changed — check patches/UPSTREAM.md.",
+      );
+    }
+    // After the anchor for cflags (the args follow it), before it for the link
+    // line (the object list ends with it).
+    src =
+      marker === CFLAGS_MARKER
+        ? src.slice(0, at + anchor.length) + inject + src.slice(at + anchor.length)
+        : src.slice(0, at) + inject + src.slice(at);
+    changed = true;
+  }
+  if (changed) await writeFile(file, src);
+}
+
 export async function ensurePorfforPatched(): Promise<void> {
   if (done) return;
+  await patchCompilerArgs();
+  await patchBodyLimit();
   const file = resolve(porfforRoot(), "compiler/render.js");
   const src = await readFile(file, "utf8");
-  if (src.includes(MARKER)) {
+  if (src.includes(ENV_MARKER)) {
     done = true;
     return;
   }
@@ -40,7 +139,6 @@ export async function ensurePorfforPatched(): Promise<void> {
         "Porffor's native-fetch renderer changed — check patches/UPSTREAM.md.",
     );
   }
-  const patched = src.slice(0, anchorAt + ANCHOR.length) + INJECT + src.slice(anchorAt + ANCHOR.length);
-  await writeFile(file, patched);
+  await writeFile(file, src.slice(0, anchorAt + ANCHOR.length) + ENV_INJECT + src.slice(anchorAt + ANCHOR.length));
   done = true;
 }

package/src/sqlite.ts

@@ -0,0 +1,99 @@
+/**
+ * #15 — the SQLite object an embedded-backend sprout links against.
+ *
+ * Built once and cached: the amalgamation is a single 9 MB C file that takes
+ * ~10s to compile, which is fine once per toolchain and intolerable per build.
+ * Cached beside the Zig toolchain, keyed by version + target, so switching
+ * targets or bumping SQLite cannot silently reuse the wrong object.
+ *
+ * The amalgamation is downloaded rather than vendored: 9 MB of third-party C in
+ * the repo would dwarf the CLI, and the checksum below is what makes the
+ * download safe to trust.
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+
+export const SQLITE_VERSION = "3.50.4";
+
+/** Same cache root Zig uses, so one `rm -rf ~/.cache/sproutboat` clears everything. */
+const cacheDir = (): string => resolve(homedir(), ".cache/sproutboat", `sqlite-${SQLITE_VERSION}`);
+const SQLITE_ZIP = `https://sqlite.org/2025/sqlite-amalgamation-3500400.zip`;
+const SQLITE_SHA256 = "1d3049dd0f830a025a53105fc79fd2ab9431aea99e137809d064d8ee8356b032";
+
+/**
+ * Compile flags. THREADSAFE=0 because a sprout serves one turn at a time;
+ * DQS=0 rejects double-quoted string literals, which is the setting that turns
+ * a typo'd column name in user SQL into an error instead of a string.
+ */
+const SQLITE_DEFINES = [
+  "-DSQLITE_THREADSAFE=0",
+  "-DSQLITE_OMIT_LOAD_EXTENSION",
+  "-DSQLITE_DQS=0",
+  "-DSQLITE_DEFAULT_MEMSTATUS=0",
+  "-DSQLITE_OMIT_DEPRECATED",
+  "-DSQLITE_DEFAULT_WAL_SYNCHRONOUS=1",
+];
+
+const run = (cmd: string, args: string[]): Promise<{ code: number; stderr: string }> =>
+  new Promise((done) => {
+    const child = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => (stderr += String(chunk)));
+    child.on("close", (code) => done({ code: code ?? 1, stderr }));
+  });
+
+async function amalgamation(): Promise<string> {
+  const dir = cacheDir();
+  const source = resolve(dir, "sqlite3.c");
+  if (existsSync(source)) return source;
+  await mkdir(dir, { recursive: true });
+
+  const response = await fetch(SQLITE_ZIP);
+  if (!response.ok) throw new Error(`could not download SQLite ${SQLITE_VERSION}: HTTP ${response.status}`);
+  const zip = Buffer.from(await response.arrayBuffer());
+  const digest = createHash("sha256").update(zip).digest("hex");
+  if (digest !== SQLITE_SHA256) {
+    throw new Error(`SQLite amalgamation checksum mismatch: expected ${SQLITE_SHA256}, got ${digest}`);
+  }
+  const zipPath = resolve(dir, "amalgamation.zip");
+  await writeFile(zipPath, zip);
+  const unzip = await run("unzip", ["-oqj", zipPath, "-d", dir]);
+  if (unzip.code !== 0) throw new Error(`could not unpack the SQLite amalgamation: ${unzip.stderr}`);
+  if (!existsSync(source)) throw new Error("the SQLite amalgamation did not contain sqlite3.c");
+  return source;
+}
+
+export type SqliteObjectInput = {
+  /** `host` compiles with cc; `linux-x86_64` cross-compiles with the pinned Zig. */
+  target: "linux-x86_64" | "host";
+  /** Zig binary, required for the linux target. */
+  zigBin?: string;
+};
+
+/** Path to `sqlite3.o` for this target, building it on first use. */
+export async function ensureSqliteObject(input: SqliteObjectInput): Promise<string> {
+  const dir = cacheDir();
+  const objectPath = resolve(dir, `sqlite3-${input.target}.o`);
+  if (existsSync(objectPath)) return objectPath;
+
+  const source = await amalgamation();
+  const [cmd, prefix] =
+    input.target === "host"
+      ? (["cc", []] as const)
+      : ([input.zigBin ?? "zig", ["cc", "-target", "x86_64-linux-musl"]] as const);
+  const result = await run(cmd, [...prefix, "-c", source, "-o", objectPath, "-O2", ...SQLITE_DEFINES]);
+  if (result.code !== 0) throw new Error(`could not compile SQLite for ${input.target}:\n${result.stderr}`);
+  return objectPath;
+}
+
+/** The SQLite build stamp, for the artifact manifest's provenance string. */
+export const sqliteStamp = (): string => `sqlite/${SQLITE_VERSION}`;
+
+/** Read back the compiled object's size, for reporting. */
+export async function sqliteObjectSize(path: string): Promise<number> {
+  return (await readFile(path)).byteLength;
+}

package/src/standalone-build.ts

@@ -0,0 +1,64 @@
+/**
+ * #15 — `sproutboat build --standalone`.
+ *
+ * Emits ONE executable carrying the compiled sprout, its static assets and its
+ * binding declarations, with SQLite linked in so there is no broker and no
+ * second process. The build is thin on purpose: `buildArtifact` with the
+ * embedded transport already produces exactly the binary we want, so this
+ * copies it out and enforces the one thing a standalone binary cannot do.
+ */
+import { chmod, cp, mkdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { buildArtifact, type BuildInput } from "./build";
+import type { Bindings } from "./wrap";
+
+export type StandaloneBuildInput = BuildInput & {
+  /** Where to write the executable. Defaults to `<projectDir>/dist/<name>`. */
+  outPath?: string;
+};
+
+export type StandaloneBuildResult = { outPath: string; bytes: number };
+
+/**
+ * Bindings a standalone binary cannot serve.
+ *
+ * A build error, not a runtime no-op: a binary whose binding silently does
+ * nothing is discovered in production, on a device someone has to reach
+ * physically.
+ *
+ * Outbound `fetch` is absent from this list: http and https both work, with
+ * BearSSL and the Mozilla root set compiled in.
+ */
+export function unsupportedBindings(bindings: Partial<Bindings>): string[] {
+  const reasons: string[] = [];
+  if ((bindings.services ?? []).length > 0) {
+    reasons.push("service bindings call another deployment through an edge, which a standalone binary has none of");
+  }
+  return reasons;
+}
+
+export async function buildStandalone(input: StandaloneBuildInput): Promise<StandaloneBuildResult> {
+  const artifact = await buildArtifact({ ...input, transport: "embedded" });
+
+  let bindings: Partial<Bindings> = {};
+  try {
+    // SAFETY: bindings.json is written by buildArtifact from the validated
+    // config in this same call — our own output, not user input.
+    bindings = JSON.parse(await readFile(resolve(artifact.artifactDir, "bindings.json"), "utf8")) as Partial<Bindings>;
+  } catch {
+    bindings = {}; // a project with no bindings at all
+  }
+
+  const blocked = unsupportedBindings(bindings);
+  if (blocked.length > 0) {
+    throw new Error(`cannot build a standalone binary for this project:\n  - ${blocked.join("\n  - ")}`);
+  }
+
+  // The sprout *is* the binary: assets and bindings are compiled into it, and
+  // everything else it needs (port, data dir, secrets) arrives at run time.
+  const outPath = input.outPath ?? resolve(input.projectDir, "dist", input.config.name);
+  await mkdir(resolve(outPath, ".."), { recursive: true });
+  await cp(resolve(artifact.artifactDir, "sprout"), outPath);
+  await chmod(outPath, 0o755);
+  return { outPath, bytes: Bun.file(outPath).size };
+}