sproutboat 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -10,6 +10,64 @@ maintained going forward by the `release` skill.
 
 ## Unreleased
 
+## [0.30.0] - 2026-10-23
+
+Built on `@sproutboat/runtime` 0.29.1, `@sproutboat/toolchain` 0.15.0 and
+`@sproutboat/wire` 0.18.0.
+
+### Fixed
+
+- Queues lost data in standalone executables. `sendBatch()` stored every
+  message body as the text `"[object Object]"`, and a consumer whose `queue()`
+  threw had its whole batch acked. Now the bodies arrive intact, and a throw
+  retries every message the consumer had not acked or retried, as on Workers.
+  `send()` and `sendBatch()` also honour `delaySeconds` there. These fixes
+  apply at every compatibility date.
+
+### Added
+
+- Durable Objects like workerd from compatibility date `2026-10-28`:
+  - An input gate: while a storage read is in flight, no other request or alarm
+    enters the object, so read-then-write updates are no longer lost under
+    concurrency. Ten concurrent increments used to end at 1.
+  - Storage methods return Promises, and `transaction()` and `sync()` are
+    available.
+  - Values keep their type: Date, Map, Set, RegExp, BigInt, `Uint8Array`,
+    `DataView`, `ArrayBuffer` and more. Other typed arrays throw a DataCloneError
+    in `put()`, for now: store their bytes in a `Uint8Array`.
+    `put(key, undefined)` throws, as on Workers.
+  - `list()` takes `start`, `startAfter`, `end` and `reverse`.
+  - `deleteAll()` also removes the alarm.
+  Earlier dates keep synchronous JSON storage.
+- From `2026-10-28`, `sendBatch(messages, { delaySeconds })` delays the whole
+  batch.
+
+### Changed
+
+- A Durable Object `list({ prefix })` matches the prefix exactly at every date.
+  `_` and `%` were wildcards, and case was ignored.
+
+## [0.29.0] - 2026-10-23
+
+Built on `@sproutboat/runtime` 0.28.0, `@sproutboat/toolchain` 0.15.0 and
+`@sproutboat/wire` 0.17.0.
+
+### Added
+
+- Offline restore of a captured D1 database, inside the app's own executable.
+  `sproutboat build --standalone --with-restore` adds an `ltx-restore` command:
+  `./my-app ltx-restore --generation DIR --output NEW_DB [--txid N]` rebuilds a
+  SQLite database from one generation of LTX files written by native capture.
+  The target needs no Node, Bun or SQLite CLI. The restore checks every
+  checksum and TXID in the chain, then runs SQLite's integrity check on the
+  result. It refuses to run while capture is still writing, and never
+  overwrites an existing file or touches the destination's `-wal`/`-shm`
+  sidecars. On success it prints the TXID, checksum and size as JSON. See
+  `docs/native-ltx-restore.md`.
+- The restore code is compiled separately from the app and runs before any app
+  code starts. Builds without `--with-restore` are unchanged, and there an
+  `ltx-restore` argument does nothing.
+
 ## [0.28.0] - 2026-10-23
 
 Built on `@sproutboat/runtime` 0.28.0, `@sproutboat/toolchain` 0.14.0 and

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.28.0
+**Package:** `sproutboat` 0.30.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] [--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. `--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] [--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. |
 | `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] [--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] [--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] [--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] [--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/THIRD_PARTY_NOTICES.md

@@ -25,3 +25,12 @@ to its upstream source.
 The complete Apache-2.0 notice for uWebSockets and uSockets is retained in the
 embedded source archive. Porffor and BearSSL retain their MIT notices in the
 source archives acquired at the revisions above.
+
+## Optional native LTX restore
+
+The trusted restore codec is adapted from `platformatic/sqlite-js-stream` at
+`a5b830d5f1e408c54a04285c2199019b40154c25` (Apache-2.0), with streaming/checksum
+and native integration changes by OpenAI Codex (GPT-6.1). See
+`vendor/ltx-restore/LICENSE` and `NOTICE` for Platformatic, Litestream and LTX
+attribution. LZ4JS 0.2.0 declares the ISC license in its retained package metadata under
+`vendor/ltx-restore/lz4js/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.28.0",
+  "version": "0.30.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.5.0",
-    "@sproutboat/runtime": "^0.28.0",
-    "@sproutboat/toolchain": "^0.14.0",
-    "@sproutboat/wire": "^0.17.0"
+    "@sproutboat/runtime": "^0.29.1",
+    "@sproutboat/toolchain": "^0.15.0",
+    "@sproutboat/wire": "^0.18.0"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.85.0",
@@ -78,10 +78,10 @@
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
-    "@sproutboat/cli-darwin-arm64": "0.28.0",
-    "@sproutboat/cli-darwin-x64": "0.28.0",
-    "@sproutboat/cli-linux-arm64": "0.28.0",
-    "@sproutboat/cli-linux-x64": "0.28.0"
+    "@sproutboat/cli-darwin-arm64": "0.30.0",
+    "@sproutboat/cli-darwin-x64": "0.30.0",
+    "@sproutboat/cli-linux-arm64": "0.30.0",
+    "@sproutboat/cli-linux-x64": "0.30.0"
   },
   "engines": {
     "node": ">=18"

package/src/build.ts

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
+import { NATIVE_RESTORE_IDENTITY } from "./native-restore";
 import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { readAssetRules, walkAssets, type AssetManifest } from "./assets";
@@ -54,6 +55,8 @@ export type BuildInput = {
   outputDirectory?: string;
   /** Stable compiler input used only by the local dev loop. */
   generatedPath?: string;
+  /** Include trusted offline restore startup in a standalone executable. */
+  withRestore?: boolean;
 };
 
 export type BuildOutput = {
@@ -79,7 +82,7 @@ async function integrationIdentity(): Promise<string> {
     const executable = await stat(process.execPath);
     return `release:${cliVersion}:${executable.size}:${executable.mtimeMs}`;
   }
-  const files = ["build.ts", "compile.ts", "sqlite.ts", "bearssl.ts", "toolchain.ts"].map((file) =>
+  const files = ["build.ts", "compile.ts", "sqlite.ts", "bearssl.ts", "toolchain.ts", "native-restore.ts"].map((file) =>
     resolve(import.meta.dir, file),
   );
   // Hash the patch implementation and its local modules so a Unicode patch
@@ -118,6 +121,10 @@ async function acquireArtifactLock(artifactDir: string): Promise<string> {
  * exactly where `buildArtifact` would.
  */
 async function prepareBuild(input: BuildInput) {
+  if (input.withRestore && input.reuseSproutPath)
+    throw new Error("--with-restore cannot reuse a previously compiled sprout");
+  if (input.withRestore && input.transport !== "embedded")
+    throw new Error("--with-restore is available only with --standalone");
   const source = input.source ?? (await readFile(input.sourcePath));
   const sourceHash = digest(source);
   const target = input.target ?? "linux-x86_64";
@@ -247,7 +254,7 @@ function unitDirFor(input: BuildInput): string {
   return resolve(
     input.projectDir,
     ".sproutboat/porffor-units",
-    `${input.target ?? "linux-x86_64"}-${input.transport ?? "broker"}-${input.optimize ?? "release"}`,
+    `${input.target ?? "linux-x86_64"}-${input.transport ?? "broker"}-${input.optimize ?? "release"}${input.withRestore ? "-restore" : ""}`,
   );
 }
 
@@ -280,6 +287,7 @@ export async function emitGenerated(input: BuildInput): Promise<{ generatedPath:
       optimize: input.optimize,
       versionMetadata,
       emitOnly: true,
+      withRestore: input.withRestore,
     });
   } finally {
     if (unitLock) await rm(unitLock, { recursive: true, force: true });
@@ -318,6 +326,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
       porffor: [PORFFOR_COMMIT_FULL, PORFFOR_ARCHIVE_SHA256],
       native: embedded ? [sqliteStamp(), bearsslStamp()] : [],
       integration: await integrationIdentity(),
+      nativeRestore: input.withRestore ? NATIVE_RESTORE_IDENTITY : null,
     }),
   ).slice("sha256:".length);
   const artifactId = versionMetadata
@@ -356,6 +365,7 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
           extraCflags: tls ? ["-I", tls.includeDir] : [],
           optimize: input.optimize,
           versionMetadata,
+          withRestore: input.withRestore,
         });
       } finally {
         if (unitLock) await rm(unitLock, { recursive: true, force: true });

package/src/compile.ts

@@ -14,6 +14,7 @@ import { chmod, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/pr
 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 { ensurePorffor } from "./porffor-toolchain";
 // The prelude + transports live in @sproutboat/runtime (next to wrap.ts, which
@@ -100,6 +101,8 @@ export type CompileInput = {
    * binary, such as a qualification run that only inspects the source.
    */
   emitOnly?: boolean;
+  /** Trusted offline restore startup, standalone builds only. Never a tenant compiler flag. */
+  withRestore?: boolean;
 };
 
 /**
@@ -242,6 +245,8 @@ async function writeGenerated(input: CompileInput): Promise<string> {
  * the wrapper, never Porffor itself.
  */
 export async function compileSprout(input: CompileInput): Promise<void> {
+  if (input.withRestore && (input.transport !== "embedded" || input.emitOnly))
+    throw new Error("--with-restore requires a standalone native compile, without --emit-only");
   if (input.emitOnly) {
     await writeGenerated(input);
     return;
@@ -298,13 +303,30 @@ export async function compileSprout(input: CompileInput): Promise<void> {
     ? [process.execPath, "__porffor", launcher]
     : [process.execPath, resolve(import.meta.dir, "main.ts"), "__porffor", launcher];
 
+  const restoreObjects = input.withRestore
+    ? await buildNativeRestore({
+        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"],
+        cflags: input.extraCflags ?? [],
+        macho: input.target === "host" && process.platform === "darwin",
+      })
+    : [];
+
   const child = Bun.spawn(
     [...command, ...porfforArgs(generatedPath, input.outPath, input.target, input.optimize, hostCompiler?.usingZig)],
     {
       cwd: outDir,
       stdout: "pipe",
       stderr: "pipe",
-      env: compileEnv(path, input.extraLink, input.extraCflags, hostCompiler),
+      env: compileEnv(
+        path,
+        [...(input.extraLink ?? []), ...restoreObjects],
+        [...(input.extraCflags ?? []), ...(input.withRestore ? ["-Dmain=sb_app_main"] : [])],
+        hostCompiler,
+      ),
     },
   );
   let timedOut = false;

package/src/main.ts

@@ -335,7 +335,11 @@ async function build(directory?: string, target: "linux-x86_64" | "host" = "linu
  * *this* machine either way in phase 0 — cross-compiling both halves comes with
  * the embedded backend, which removes the launcher entirely.
  */
-async function buildStandaloneBinary(directory: string | undefined, target: "linux-x86_64" | "host") {
+async function buildStandaloneBinary(
+  directory: string | undefined,
+  target: "linux-x86_64" | "host",
+  withRestore = false,
+) {
   const project = await readProject(directory);
   console.log(dim(`Building a standalone ${project.config.name} (${target})…`));
   try {
@@ -345,6 +349,7 @@ async function buildStandaloneBinary(directory: string | undefined, target: "lin
       sourcePath: project.sourcePath,
       source: project.bundle.code,
       target,
+      withRestore,
     });
     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`));
@@ -1339,11 +1344,17 @@ switch (command) {
     await dev(args);
     break;
   case "build": {
+    const withRestore = args.includes("--with-restore");
+    if (withRestore && (!args.includes("--standalone") || args.includes("--emit-only")))
+      usageError(
+        "--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";
     if (args.includes("--emit-only")) await emitOnly(directory, target, args.includes("--standalone"));
-    else if (args.includes("--standalone")) await buildStandaloneBinary(directory, target);
+    else if (args.includes("--standalone")) await buildStandaloneBinary(directory, target, withRestore);
     else await build(directory, target);
     break;
   }

package/src/native-restore-sources.ts

@@ -0,0 +1,48 @@
+// Text assets are embedded in the packaged CLI and compiled only as trusted restore source.
+import source0 from "../vendor/ltx-restore/crc64-native.ts.txt" with { type: "text" };
+import source1 from "../vendor/ltx-restore/errors.ts.txt" with { type: "text" };
+import source2 from "../vendor/ltx-restore/file-io.ts.txt" with { type: "text" };
+import source3 from "../vendor/ltx-restore/ltx/byte-reader.ts.txt" with { type: "text" };
+import source4 from "../vendor/ltx-restore/ltx/bytes.ts.txt" with { type: "text" };
+import source5 from "../vendor/ltx-restore/ltx/checksum.ts.txt" with { type: "text" };
+import source6 from "../vendor/ltx-restore/ltx/constants.ts.txt" with { type: "text" };
+import source7 from "../vendor/ltx-restore/ltx/crc64.ts.txt" with { type: "text" };
+import source8 from "../vendor/ltx-restore/ltx/decoder.ts.txt" with { type: "text" };
+import source9 from "../vendor/ltx-restore/ltx/header.ts.txt" with { type: "text" };
+import source10 from "../vendor/ltx-restore/ltx/lz4.ts.txt" with { type: "text" };
+import source11 from "../vendor/ltx-restore/ltx/page-index.ts.txt" with { type: "text" };
+import source12 from "../vendor/ltx-restore/ltx/page.ts.txt" with { type: "text" };
+import source13 from "../vendor/ltx-restore/ltx/sink.ts.txt" with { type: "text" };
+import source14 from "../vendor/ltx-restore/ltx/trailer.ts.txt" with { type: "text" };
+import source15 from "../vendor/ltx-restore/ltx/types.ts.txt" with { type: "text" };
+import source16 from "../vendor/ltx-restore/lz4js/lz4.js.txt" with { type: "text" };
+import source17 from "../vendor/ltx-restore/lz4js/util.js.txt" with { type: "text" };
+import source18 from "../vendor/ltx-restore/lz4js/xxh32.js.txt" with { type: "text" };
+import source19 from "../vendor/ltx-restore/program.ts.txt" with { type: "text" };
+import source20 from "../vendor/ltx-restore/restore-native.ts.txt" with { type: "text" };
+import source21 from "../vendor/ltx-restore/restore.ts.txt" with { type: "text" };
+
+export const NATIVE_RESTORE_SOURCES = {
+  "crc64-native.ts": source0,
+  "errors.ts": source1,
+  "file-io.ts": source2,
+  "ltx/byte-reader.ts": source3,
+  "ltx/bytes.ts": source4,
+  "ltx/checksum.ts": source5,
+  "ltx/constants.ts": source6,
+  "ltx/crc64.ts": source7,
+  "ltx/decoder.ts": source8,
+  "ltx/header.ts": source9,
+  "ltx/lz4.ts": source10,
+  "ltx/page-index.ts": source11,
+  "ltx/page.ts": source12,
+  "ltx/sink.ts": source13,
+  "ltx/trailer.ts": source14,
+  "ltx/types.ts": source15,
+  "lz4js/lz4.js": source16,
+  "lz4js/util.js": source17,
+  "lz4js/xxh32.js": source18,
+  "program.ts": source19,
+  "restore-native.ts": source20,
+  "restore.ts": source21,
+} satisfies Record<string, string>;

package/src/native-restore.ts

@@ -0,0 +1,155 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { NATIVE_RESTORE_SOURCES } from "./native-restore-sources";
+
+/** Included in the native artifact cache key, including in the packaged CLI. */
+export const NATIVE_RESTORE_IDENTITY = createHash("sha256")
+  .update(JSON.stringify(NATIVE_RESTORE_SOURCES))
+  .digest("hex");
+
+const CONTROLLER_HEAD = String.raw`
+static int sb_cli_restore_stdout = -1;
+`;
+const DISPATCH = String.raw`
+int sb_cli_restore_dispatch(int argc, char **argv) {
+  if (argc < 2 || strcmp(argv[1], "ltx-restore")) return -1;
+  const char *source = NULL, *output = NULL, *target = "";
+  const char *usage = "usage: APP ltx-restore --generation DIR --output NEW_DB [--txid DECIMAL_TXID]\n";
+  if (argc == 3 && (!strcmp(argv[2], "--help") || !strcmp(argv[2], "-h"))) { fputs(usage, stdout); return 0; }
+  for (int i = 2; i < argc; i += 2) {
+    if (i + 1 >= argc || !argv[i + 1][0]) { fputs(usage, stderr); return 2; }
+    if (!strcmp(argv[i], "--generation") && !source) source = argv[i + 1];
+    else if (!strcmp(argv[i], "--output") && !output) output = argv[i + 1];
+    else if (!strcmp(argv[i], "--txid") && !target[0]) target = argv[i + 1];
+    else { fputs(usage, stderr); return 2; }
+  }
+  if (!source || !output || strlen(source) > 4095 || strlen(output) > 4095) { fputs(usage, stderr); return 2; }
+  if (target[0]) {
+    uint64_t value = 0;
+    for (const unsigned char *p = (const unsigned char *)target; *p; p++) {
+      unsigned int digit = (unsigned int)(*p - '0');
+      if (digit > 9 || value > (UINT64_MAX - digit) / 10) { fputs(usage, stderr); return 2; }
+      value = value * 10 + digit;
+    }
+    if (!value) { fputs(usage, stderr); return 2; }
+  }
+  if (setenv("SB_LTX_RESTORE_GENERATION", source, 1) || setenv("SB_LTX_RESTORE_OUTPUT", output, 1) ||
+      setenv("SB_LTX_RESTORE_TXID", target, 1)) { perror("restore arguments"); return 1; }
+  sb_cli_restore_stdout = dup(STDOUT_FILENO);
+  if (sb_cli_restore_stdout < 0) { perror("restore stdout"); return 1; }
+  porf_native_fetch_runtime_init();
+  fputs("restore startup returned without completing\n", stderr);
+  return 1;
+}
+`;
+
+const STARTUP = String.raw`
+extern "C" int sb_cli_restore_dispatch(int, char **);
+int sb_app_main(void);
+int main(int argc, char **argv) {
+  const int result = sb_cli_restore_dispatch(argc, argv);
+  return result >= 0 ? result : sb_app_main();
+}
+`;
+
+async function run(command: string[]): Promise<string> {
+  const child = Bun.spawn(command, { stdout: "pipe", stderr: "pipe" });
+  const timer = setTimeout(() => child.kill("SIGKILL"), 600_000);
+  try {
+    const [code, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ]);
+    if (code !== 0) throw new Error(`native restore build failed (${command[0]}): ${stderr || stdout}`);
+    return stdout;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Prefix only defined external symbols. Undefined libc/SQLite/server imports stay external. */
+export function restoreSymbolDefines(symbols: string, macho: boolean): string {
+  const names = new Set<string>();
+  for (const line of symbols.split("\n")) {
+    const match = /^\s*[0-9a-fA-F]+\s+[A-Za-z]\s+([A-Za-z_][A-Za-z_0-9]*)\s*$/.exec(line);
+    if (!match) continue;
+    const name = macho ? match[1].slice(1) : match[1];
+    if (name !== "sb_cli_restore_dispatch") names.add(name);
+  }
+  if (!names.has("porf_mem") || !names.has("porf_native_fetch_runtime_init"))
+    throw new Error("native restore compiler symbol inventory changed");
+  return [...names]
+    .sort()
+    .map((name) => `#define ${name} sb_ltx_trusted_${name}\n`)
+    .join("");
+}
+
+/** Trusted source only. No project source, bindings, configuration or secrets enter this compile. */
+export async function buildNativeRestore(input: {
+  directory: string;
+  prelude: string;
+  porfforCommand: string[];
+  cc: string[];
+  cxx: string[];
+  cflags: string[];
+  macho: boolean;
+}): Promise<string[]> {
+  const root = resolve(input.directory, "native-restore");
+  await mkdir(root, { recursive: true });
+  for (const [name, source] of Object.entries(NATIVE_RESTORE_SOURCES)) {
+    const file = resolve(root, name);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, source);
+  }
+  const bundled = await Bun.build({ entrypoints: [resolve(root, "program.ts")], target: "browser", format: "esm" });
+  if (!bundled.success) throw new Error(`cannot bundle trusted restore: ${bundled.logs.join("\n")}`);
+  // Full released transport supplies the existing CRC kernel and SQLite declarations.
+  const generated = resolve(root, "trusted.generated.js");
+  const { wrapNativeFetchHandler, EMPTY_BINDINGS } = await import("./wrap");
+  const program = await bundled.outputs[0].text();
+  const wrapped = wrapNativeFetchHandler(
+    program,
+    input.prelude + "\nPorffor.c`" + CONTROLLER_HEAD + "`;\n",
+    {},
+    EMPTY_BINDINGS,
+    undefined,
+    "2026-10-22",
+    "ltx-restore",
+    undefined,
+    "embedded",
+  );
+  await writeFile(generated, wrapped);
+  const emitted = resolve(root, "emitted");
+  await rm(emitted, { recursive: true, force: true });
+  await run([...input.porfforCommand, "c", generated, "-o", emitted, "--sb-native-bytes-v1"]);
+  const c = (await readFile(resolve(emitted, "app.c"), "utf8")) + DISPATCH;
+  const source = resolve(root, "trusted.c"),
+    probe = resolve(root, "probe.o");
+  const compileFlags = ["-std=gnu11", "-w", ...input.cflags];
+  await writeFile(source, c);
+  await rm(probe, { force: true });
+  await run([...input.cc, ...compileFlags, "-O0", "-c", source, "-o", probe]);
+  const nm = Bun.which("nm");
+  if (!nm) throw new Error("native restore builds require nm from the native compiler tools");
+  const defines = restoreSymbolDefines(await run([nm, "-g", "-U", probe]), input.macho);
+  await writeFile(source, defines + c);
+  const object = resolve(root, "trusted.o");
+  await rm(object, { force: true });
+  await run([...input.cc, ...compileFlags, "-O3", "-c", source, "-o", object]);
+  const symbols = await run([nm, "-g", "-U", object]);
+  for (const line of symbols.split("\n")) {
+    const match = /^\s*[0-9a-fA-F]+\s+[A-Za-z]\s+(\S+)\s*$/.exec(line);
+    if (!match) continue;
+    const name = input.macho ? match[1].slice(1) : match[1];
+    if (name !== "sb_cli_restore_dispatch" && !name.startsWith("sb_ltx_trusted_"))
+      throw new Error(`native restore external symbol was not namespaced: ${name}`);
+  }
+  const startup = resolve(root, "startup.cpp"),
+    startupObject = resolve(root, "startup.o");
+  await writeFile(startup, STARTUP);
+  await rm(startupObject, { force: true });
+  await run([...input.cxx, "-O3", "-c", startup, "-o", startupObject]);
+  return [object, startupObject];
+}

package/src/surface.ts

@@ -97,10 +97,10 @@ export const COMMANDS: readonly Command[] = [
     name: "build",
     group: "Develop",
     emoji: "🔨",
-    args: "[project-dir] [--target host] [--standalone] [--emit-only]",
+    args: "[project-dir] [--target host] [--standalone] [--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. `--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. `--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",