@sproutboat/runtime 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @sproutboat/runtime
 
+## 0.26.0
+
+### Minor Changes
+
+- 9b15539: KV matches workerd from compatibility date `2026-10-25`:
+  
+  - `get`, `getWithMetadata`, `put`, `delete` and `list` return Promises, and errors reject them.
+  - `get(key, type)` takes `"text"`, `"json"`, `"arrayBuffer"` and `"stream"`, and `get([keys])` returns a `Map`.
+  - `getWithMetadata(key, type)` returns `{ value, metadata, cacheStatus }`.
+  - `put(key, value, { expiration, expirationTtl, metadata })` takes strings, bytes and `ReadableStream`s, and stores the metadata.
+  - `list({ prefix, limit, cursor })` returns `{ keys: [{ name, expiration?, metadata? }], list_complete, cursor?, cacheStatus }` and pages at up to 1,000 keys.
+  - Keys, values, expirations, metadata and list limits fail with KV's own errors. For example: `Key name cannot be empty.`, `KV PUT failed: 414 UTF-8 encoded length of 513 exceeds key length limit of 512.`, `KV PUT failed: 400 Invalid expiration_ttl of 30. Expiration TTL must be at least 60.`, and `KV PUT failed: 413 Metadata length of 1110 exceeds limit of 1024.`
+  
+  Earlier dates keep the synchronous shim. Two changes apply at every date:
+  
+  - **A `list()` prefix now matches exactly.** It used SQL `LIKE`, so it ignored case and read `_` and `%` as wildcards. For example, the prefix `a_` also listed `ab`, and `a` also listed `AB`.
+  - **Both transports store KV metadata in a new column.** It's added to existing stores when they open.
+
+### Patch Changes
+
+- 1c36119: Create the LTX page-index scratch file inside the database's replication spool
+  instead of libc's global temporary directory, fixing capture initialization when
+  a worker's filesystem sandbox permits writes only beneath its own state directory.
+  The scratch file is private and immediately unlinked. If a kill lands before
+  unlink, the next capture-lock owner removes the stale regular index file before
+  recovery. After unlink, closing the writer or killing the process releases it.
+  Its anonymous transient disk use is not counted by the
+  directory-walk quota. Capture retains its existing explicit opt-in and compatibility
+  date of 2026-10-22; capture-off apps and earlier dates keep their existing behavior.
+- 3cad1f0: The storage quota counts a D1 database's WAL file, which can hold space the app has already freed. While the app is over its quota, the runtime now checkpoints and truncates each D1 database's WAL before measuring again, at most once a second. So `DELETE` then `VACUUM` is enough to get back under the quota, and the app no longer has to run a checkpoint itself. Databases under LTX capture are left alone: capture owns their checkpoints, and they stay frozen until the quota is raised or other data is deleted.
+
 ## 0.25.0
 
 ### Minor Changes

package/LTX_REPLICATION.md

@@ -53,7 +53,18 @@ for this opted-in binding. Use the base LTX file for replication.
 
 Files live under `<database-path>.ltx/epoch-XXXXXX/`. Completed names are
 `<minTXID as 16 hex digits>-<maxTXID as 16 hex digits>.ltx`.
-The encoder streams one page at a time and spools index records with `tmpfile()`.
+The encoder streams one page at a time. It creates its index scratch file with
+`mkstemp()` beneath `<database-path>.ltx/`, immediately unlinks the name, and uses
+the open descriptor until the writer closes. This needs no access to a global
+temporary directory, which a sandboxed worker may not have. The scratch file is
+private (0600). A kill between creation and unlink can leave a named index file.
+On startup, after acquiring the capture lock and before recovery, the owner removes
+only regular root-level files matching the reserved `index-` plus six alphanumeric
+characters. It does not follow symlinks or remove directories or unrelated names.
+After unlink, process death releases the anonymous scratch space automatically.
+Its transient disk usage grows with the index records and is not visible to the
+directory-walk storage quota after unlink. Allow disk headroom for that scratch
+space as well as the LTX output; the quota is not a hard filesystem limit.
 
 For every LTX file:
 
@@ -78,7 +89,10 @@ applications must use idempotent transaction identifiers for retries.
 ## Qualification status
 
 Capture is tested against the exact inline C through `bun run test:native-ltx`,
-including independent BigInt CRC and index verification, a 102-file chain,
+with global `tmpfile()` access deliberately denied in the driver so the capture
+path cannot depend on it. This portable regression does not itself qualify the
+Linux Landlock/seccomp sandbox; sproutd's capture-on lifecycle smoke must do that.
+The tests cover independent BigInt CRC and index verification, a 102-file chain,
 byte-exact restore, integrity checking, oversized transaction rollback, database truncation, explicit rollback and late position-write failure latching.
 The workspace prototype additionally tests the compiled Porffor executable,
 including external writer exclusion and invariant PRAGMA rejection.
@@ -103,8 +117,9 @@ time. It also checks the last LTX file. Five native restarts each at 4.2 MB and
 The 51.1 MB verification took 399 to 446 ms on macOS arm64 (plus about 13 ms to
 health readiness); this is not a 9 ms cold-start claim for large databases.
 
-The regression SIGKILLs at ten durability boundaries, including both sides of
-clean-marker publication, and verifies matching-prefix resume and fallback cases.
+The regression SIGKILLs at eleven durability boundaries, including the interval
+between index creation and unlink and both sides of clean-marker publication,
+and verifies scratch cleanup, matching-prefix resume and fallback cases.
 It also recovers a committed tail beyond the durable cursor. The full Porffor executable passed 200 seeded random SIGKILL iterations on macOS
 arm64: 1,675 acknowledged writes retained, 88 same-generation resumes and 112
 fresh-base recoveries. Every finished chain passed file/database CRC verification,

package/package.json

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

package/src/kv-shim.test.js

@@ -0,0 +1,124 @@
+// The KV shim (`env.KV`) at compatibility dates before and from 2026-10-25, over an
+// in-memory transport with the kv.* contract both transports implement (broker.test.ts
+// covers the broker's side; sproutd's conformance/bindings/kv.js the whole path).
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+
+const source = readFileSync(new URL("./native-fetch-prelude.js", import.meta.url), "utf8");
+let rows;
+const call = (json) => {
+  const msg = JSON.parse(json);
+  const reply = (() => {
+    if (msg.op === "kv.get") {
+      const r = rows.get(msg.key);
+      return r ? { ok: true, found: true, value: r.value, binary: r.binary, metadata: r.metadata ?? null, expiration: r.expiration ?? null } : { ok: true, found: false, value: null };
+    }
+    if (msg.op === "kv.put") {
+      rows.set(msg.key, { value: msg.value, binary: msg.binary === true, metadata: msg.metadata, expiration: msg.expiration ?? (msg.expirationTtl ? Math.floor(Date.now() / 1000) + msg.expirationTtl : undefined) });
+      return { ok: true };
+    }
+    if (msg.op === "kv.delete") {
+      rows.delete(msg.key);
+      return { ok: true };
+    }
+    if (msg.op === "kv.list") {
+      const keys = [...rows.keys()].filter((k) => k.startsWith(msg.prefix) && (!msg.cursor || k > msg.cursor)).sort();
+      const limit = msg.limit ?? keys.length;
+      const page = keys.slice(0, limit);
+      const complete = keys.length <= limit;
+      return {
+        ok: true,
+        keys: page,
+        entries: page.map((k) => ({ name: k, expiration: rows.get(k).expiration ?? null, metadata: rows.get(k).metadata ?? null })),
+        list_complete: complete,
+        cursor: complete ? "" : page[page.length - 1],
+      };
+    }
+    return { ok: false, error: "unknown op" };
+  })();
+  return JSON.stringify(reply);
+};
+// oxlint-disable-next-line no-function-constructor -- the prelude is prepended as text in production too
+const { makeEnv } = new Function(
+  "Porffor",
+  "__testCall",
+  `${source}\n__sbCall = __testCall; return { makeEnv: (target) => { __sbInstallBindings(target, { kv: ["KV"] }); return target; } };`,
+)({ c: () => "" }, call);
+const fresh = (date) => {
+  globalThis.__sbCompat = date;
+  rows = new Map();
+  return makeEnv({}).KV;
+};
+const failure = async (fn) => {
+  try {
+    await fn();
+  } catch (error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return "did not throw";
+};
+
+test("before 2026-10-25: the synchronous shim, unchanged", () => {
+  const KV = fresh("2026-10-24");
+  expect(KV.put("a", "v")).toBeUndefined();
+  expect(KV.get("a")).toBe("v");
+  expect(KV.list("a")).toEqual(["a"]);
+  expect(KV.getWithMetadata).toBeUndefined();
+});
+
+test("from 2026-10-25: Promises, metadata, typed gets and get(keys)", async () => {
+  const KV = fresh("2026-10-25");
+  expect(KV.put("a", "v", { metadata: { n: 1 } })).toBeInstanceOf(Promise);
+  await KV.put("a", '{"x":1}', { metadata: { n: 1 } });
+  expect(await KV.get("a", "json")).toEqual({ x: 1 });
+  expect(await KV.get("a", { type: "text" })).toBe('{"x":1}');
+  expect(await KV.getWithMetadata("a", "json")).toEqual({ value: { x: 1 }, metadata: { n: 1 }, cacheStatus: null });
+  expect(await KV.getWithMetadata("missing")).toEqual({ value: null, metadata: null, cacheStatus: null });
+  await KV.put("b", new Uint8Array([0, 255]));
+  expect(Array.from(new Uint8Array(await KV.get("b", "arrayBuffer")))).toEqual([0, 255]);
+  // (ReadableStream values and the "stream" type use the prelude's own streams: checked end to
+  // end by sproutd's conformance/bindings/kv.js, not here against Bun's.)
+  const many = await KV.get(["a", "missing"]);
+  expect(many).toBeInstanceOf(Map);
+  expect([...many.entries()]).toEqual([["a", '{"x":1}'], ["missing", null]]);
+  expect(await KV.delete("a")).toBeUndefined();
+  expect(await KV.get("a")).toBeNull();
+});
+
+test("from 2026-10-25: KV's errors for keys, values, expiration and metadata", async () => {
+  const KV = fresh("2026-10-25");
+  expect(await failure(() => KV.put("", "v"))).toBe("TypeError: Key name cannot be empty.");
+  expect(await failure(() => KV.put("..", "v"))).toBe('TypeError: ".." is not allowed as a key name.');
+  expect(await failure(() => KV.put("k".repeat(513), "v"))).toBe("Error: KV PUT failed: 414 UTF-8 encoded length of 513 exceeds key length limit of 512.");
+  expect(await failure(() => KV.get("k".repeat(513)))).toBe("Error: KV GET failed: 414 UTF-8 encoded length of 513 exceeds key length limit of 512.");
+  expect(await failure(() => KV.put("a", { a: 1 }))).toBe("TypeError: KV put() accepts only strings, ArrayBuffers, ArrayBufferViews, and ReadableStreams as values.");
+  expect(await failure(() => KV.put("a", "v", { expirationTtl: 30 }))).toBe("Error: KV PUT failed: 400 Invalid expiration_ttl of 30. Expiration TTL must be at least 60.");
+  expect(await failure(() => KV.put("a", "v", { expirationTtl: "soon" }))).toBe("Error: KV PUT failed: 400 Invalid expiration_ttl of 0. Please specify integer greater than 0.");
+  expect(await failure(() => KV.put("a", "v", { expiration: 1000 }))).toBe(
+    "Error: KV PUT failed: 400 Invalid expiration of 1000. Please specify integer greater than the current number of seconds since the UNIX epoch.",
+  );
+  expect(await failure(() => KV.put("a", "v", { metadata: { big: "x".repeat(1100) } }))).toBe("Error: KV PUT failed: 413 Metadata length of 1110 exceeds limit of 1024.");
+  expect(await KV.get("missing", "nope")).toBeNull();
+  await KV.put("there", "v");
+  expect(await failure(() => KV.get("there", "nope"))).toBe('TypeError: Unknown response type. Possible types are "text", "arrayBuffer", "json", and "stream".');
+  expect(await failure(() => KV.list({ limit: 1001 }))).toBe("Error: KV GET failed: 400 Invalid key_count_limit of 1001. Please specify an integer less than 1000.");
+  // A failing get rejects rather than throws.
+  const rejected = KV.get("");
+  expect(rejected).toBeInstanceOf(Promise);
+  expect(await rejected.catch((e) => e.message)).toBe("Key name cannot be empty.");
+});
+
+test("from 2026-10-25: list() pages with limit and cursor, with expiration and metadata", async () => {
+  const KV = fresh("2026-10-25");
+  for (const k of ["b", "a", "c"]) await KV.put(k, "v", k === "a" ? { metadata: { t: 1 }, expirationTtl: 3600 } : undefined);
+  const first = await KV.list({ limit: 2 });
+  expect(first.keys.map((k) => k.name)).toEqual(["a", "b"]);
+  expect(first.keys[0].metadata).toEqual({ t: 1 });
+  expect(Number.isInteger(first.keys[0].expiration)).toBe(true);
+  expect("expiration" in first.keys[1]).toBe(false);
+  expect(first.list_complete).toBe(false);
+  const rest = await KV.list({ limit: 2, cursor: first.cursor });
+  expect(rest.keys.map((k) => k.name)).toEqual(["c"]);
+  expect(Object.keys(rest).sort()).toEqual(["cacheStatus", "keys", "list_complete"]);
+  expect(await KV.list({ limit: 0 })).toEqual({ keys: [], list_complete: true, cacheStatus: null });
+});

package/src/native-fetch-prelude.js

@@ -4807,6 +4807,126 @@ function __sbRpc(op, extra) {
   return reply;
 }
 
+// KV from compatibility date 2026-10-25: workerd's surface. Every method returns a
+// Promise; keys and options are checked with KV's errors; get() takes a list of keys and
+// the "stream" type; getWithMetadata(); put() takes a ReadableStream and metadata; list()
+// pages with limit and cursor and returns each key's expiration and metadata. Earlier
+// dates keep the synchronous shim below.
+function __sbKvStrict() {
+  return globalThis.__sbCompat >= "2026-10-25";
+}
+function __sbKvKey(key, verb) {
+  const name = String(key);
+  if (name === "") throw new TypeError("Key name cannot be empty.");
+  if (name === "." || name === "..") throw new TypeError('"' + name + '" is not allowed as a key name.');
+  const length = new TextEncoder().encode(name).length;
+  if (length > 512) throw new Error("KV " + verb + " failed: 414 UTF-8 encoded length of " + length + " exceeds key length limit of 512.");
+  return name;
+}
+function __sbKvType(typeOrOptions) {
+  return typeOrOptions == null ? "text" : __sbIsStr(typeOrOptions) ? typeOrOptions : typeOrOptions.type || "text";
+}
+// An unknown type fails only when there is a value to decode: a missing key is null
+// whatever the type, as in workerd.
+function __sbKvDecode(r, type) {
+  if (type !== "text" && type !== "json" && type !== "arrayBuffer" && type !== "stream")
+    throw new TypeError('Unknown response type. Possible types are "text", "arrayBuffer", "json", and "stream".');
+  if (type === "arrayBuffer") return __sbBufFrom(r.binary ? r.value : __sbToBytes(r.value));
+  if (type === "stream") return new Response(__sbBufFrom(r.binary ? r.value : __sbToBytes(r.value))).body;
+  const text = r.binary ? __sbFromUtf8(r.value) : r.value;
+  return type === "json" ? JSON.parse(text) : text;
+}
+function __sbKvMetadata(text) {
+  return text == null ? null : JSON.parse(text);
+}
+function __sbMakeKv(ns) {
+  const one = (key, type) => {
+    const r = __sbRpc("kv.get", { ns, key: __sbKvKey(key, "GET") });
+    return r.found ? { value: __sbKvDecode(r, type), metadata: __sbKvMetadata(r.metadata) } : { value: null, metadata: null };
+  };
+  const attempt = (run) => {
+    try {
+      return Promise.resolve(run());
+    } catch (err) {
+      return Promise.reject(err);
+    }
+  };
+  return {
+    get(key, typeOrOptions) {
+      return attempt(() => {
+        const type = __sbKvType(typeOrOptions);
+        if (!Array.isArray(key)) return one(key, type).value;
+        const out = new Map();
+        for (let i = 0; i < key.length; i++) out.set(String(key[i]), one(key[i], type).value);
+        return out;
+      });
+    },
+    getWithMetadata(key, typeOrOptions) {
+      return attempt(() => {
+        const r = one(key, __sbKvType(typeOrOptions));
+        return { value: r.value, metadata: r.metadata, cacheStatus: null };
+      });
+    },
+    async put(key, value, options) {
+      const msg = { ns, key: __sbKvKey(key, "PUT"), value: "" };
+      value = __sbUnwrapBody(value);
+      if (value != null && __sbIsFn(value.getReader)) value = new Uint8Array(await new Response(value).arrayBuffer());
+      if (value != null && !__sbIsStr(value) && value.byteLength !== undefined) {
+        const bytes = value.buffer !== undefined ? new Uint8Array(value.buffer, value.byteOffset, value.byteLength) : new Uint8Array(value);
+        msg.value = __sbToBytes(bytes);
+        msg.binary = true;
+      } else if (__sbIsStr(value) || value === Number(value) || value === true || value === false) msg.value = String(value);
+      else throw new TypeError("KV put() accepts only strings, ArrayBuffers, ArrayBufferViews, and ReadableStreams as values.");
+      const o = options || {};
+      if (o.expirationTtl != null) {
+        const ttl = Math.floor(Number(o.expirationTtl)) || 0;
+        if (ttl <= 0) throw new Error("KV PUT failed: 400 Invalid expiration_ttl of " + ttl + ". Please specify integer greater than 0.");
+        if (ttl < 60) throw new Error("KV PUT failed: 400 Invalid expiration_ttl of " + ttl + ". Expiration TTL must be at least 60.");
+        msg.expirationTtl = ttl;
+      } else if (o.expiration != null) {
+        const at = Math.floor(Number(o.expiration)) || 0;
+        if (at <= Math.floor(Date.now() / 1000))
+          throw new Error("KV PUT failed: 400 Invalid expiration of " + at + ". Please specify integer greater than the current number of seconds since the UNIX epoch.");
+        msg.expiration = at;
+      }
+      if (o.metadata !== undefined) {
+        const json = JSON.stringify(o.metadata);
+        const length = new TextEncoder().encode(json).length;
+        if (length > 1024) throw new Error("KV PUT failed: 413 Metadata length of " + length + " exceeds limit of 1024.");
+        msg.metadata = json;
+      }
+      __sbRpc("kv.put", msg);
+    },
+    delete(key) {
+      return attempt(() => {
+        __sbRpc("kv.delete", { ns, key: __sbKvKey(key, "DELETE") });
+      });
+    },
+    list(options) {
+      return attempt(() => {
+        const o = options || {};
+        const limit = o.limit == null ? 1000 : Math.floor(Number(o.limit));
+        if (!(limit >= 0) || limit > 1000)
+          throw new Error("KV GET failed: 400 Invalid key_count_limit of " + o.limit + ". Please specify an integer less than 1000.");
+        if (limit === 0) return { keys: [], list_complete: true, cacheStatus: null };
+        const r = __sbRpc("kv.list", { ns, prefix: o.prefix == null ? "" : String(o.prefix), limit, cursor: o.cursor == null ? "" : String(o.cursor) });
+        const keys = [];
+        const entries = r.entries || [];
+        for (let i = 0; i < entries.length; i++) {
+          const k = { name: entries[i].name };
+          if (entries[i].expiration != null) k.expiration = entries[i].expiration;
+          if (entries[i].metadata != null) k.metadata = __sbKvMetadata(entries[i].metadata);
+          keys.push(k);
+        }
+        const out = { keys, list_complete: r.list_complete !== false };
+        if (!out.list_complete) out.cursor = r.cursor;
+        out.cacheStatus = null;
+        return out;
+      });
+    },
+  };
+}
+
 // D1: a Cloudflare-shaped `env.<DB>` (prepare / bind / all / run / raw / first,
 // plus batch and exec). Every call is one broker roundtrip.
 //
@@ -5185,7 +5305,7 @@ globalThis.__sbInstallBindings = function (target, bindings) {
 
   for (let i = 0; i < (bindings.kv || []).length; i++) {
     const ns = bindings.kv[i];
-    target[ns] = {
+    target[ns] = __sbKvStrict() ? __sbMakeKv(ns) : {
       // #233 — Workers' get(key, type | { type }): "text" (default), "json",
       // "arrayBuffer". A value put as bytes is stored one char per byte and
       // flagged, so text decodes it as UTF-8 and arrayBuffer returns it

package/src/transport-embedded.js

@@ -419,9 +419,26 @@ static int sb_ltx_begin(sb_ltx_writer *w, const char *path, sb_ltx_state *s, uin
   memset(w, 0, sizeof(*w));
   w->hash = UINT64_MAX;
   w->page_size = s->page_size;
+  // Global temporary directories are outside a sandboxed worker's writable tree.
+  // After unlink, close (including process death) reclaims the scratch file.
+  char index_path[SB_LTX_PATH];
+  if (snprintf(index_path, sizeof(index_path), "%s/index-XXXXXX", s->root) >= sizeof(index_path))
+    return -1;
+  int index = mkstemp(index_path);
+  if (index < 0)
+    return -1;
+  sb_ltx_phase("index-created");
+  if (unlink(index_path)) {
+    close(index);
+    return -1;
+  }
+  w->index = fdopen(index, "w+b");
+  if (!w->index) {
+    close(index);
+    return -1;
+  }
   w->out = fopen(path, "wbx");
-  w->index = tmpfile();
-  if (!w->out || !w->index)
+  if (!w->out)
     return -1;
   unsigned char h[100] = {0};
   memcpy(h, "LTX1", 4);
@@ -1048,6 +1065,41 @@ done:
   return 1;
 }
 
+// The capture lock is already held. Remove only reserved, regular scratch files;
+// do not open them (a hard link could share the database's POSIX-locked inode).
+static int sb_ltx_sweep_indexes(const char *root) {
+  DIR *dir = opendir(root);
+  if (!dir)
+    return -1;
+  int rc = 0;
+  for (;;) {
+    errno = 0;
+    struct dirent *entry = readdir(dir);
+    if (!entry) {
+      if (errno)
+        rc = -1;
+      break;
+    }
+    const char *name = entry->d_name;
+    if (strlen(name) != 12 || strncmp(name, "index-", 6) ||
+        strspn(name + 6, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789") != 6)
+      continue;
+    struct stat st;
+    if (fstatat(dirfd(dir), name, &st, AT_SYMLINK_NOFOLLOW)) {
+      if (errno == ENOENT)
+        continue;
+      rc = -1;
+      break;
+    }
+    if (S_ISREG(st.st_mode) && unlinkat(dirfd(dir), name, 0) && errno != ENOENT) {
+      rc = -1;
+      break;
+    }
+  }
+  if (closedir(dir))
+    rc = -1;
+  return rc;
+}
 static int sb_ltx_start(int idx, sqlite3 *db, const char *path, int lock) {
   sb_ltx_state *s = &sb_ltx_states[idx];
   memset(s, 0, sizeof(*s));
@@ -1059,6 +1111,8 @@ static int sb_ltx_start(int idx, sqlite3 *db, const char *path, int lock) {
     return -1;
   if (mkdir(s->root, 0700) && errno != EEXIST)
     return -1;
+  if (sb_ltx_sweep_indexes(s->root))
+    return -1;
   char parent[SB_LTX_PATH];
   snprintf(parent, sizeof(parent), "%s", path);
   char *slash = strrchr(parent, '/');
@@ -2137,12 +2191,12 @@ static int sb_db_page_size(const char* path) {
   if (st) sqlite3_finalize(st);
   return size;
 }
-// Freeze (refuse writes to) or thaw a database for the quota. Returns 1 when the database
-// is under LTX capture, 0 when not, -1 when it cannot be opened.
+// Freeze (refuse writes to) or thaw a database for the quota; on < 0 only asks. Returns 1
+// when the database is under LTX capture, 0 when not, -1 when it cannot be opened.
 static int sb_db_quota_freeze(const char* path, int on) {
   int idx = sb_db_for(path);
   if (idx < 0) return -1;
-  sb_quota_frozen[idx] = on && sb_ltx_states[idx].db ? 1 : 0;
+  if (on >= 0) sb_quota_frozen[idx] = on && sb_ltx_states[idx].db ? 1 : 0;
   return sb_ltx_states[idx].db ? 1 : 0;
 }
 
@@ -3197,7 +3251,7 @@ function __sbD1DbRaw(path, what) {
     if (__po) free(__po);
     const char* __w; size_t __wl; char* __wo = 0;
     porf_native_fetch_read_value(what, &__w, &__wl, &__wo);
-    int __r = __wl && __w[0] == 'p' ? sb_db_page_size(__path) : sb_db_quota_freeze(__path, __wl && __w[0] == 'f');
+    int __r = __wl && __w[0] == 'p' ? sb_db_page_size(__path) : __wl && __w[0] == 'c' ? sb_db_quota_freeze(__path, -1) : sb_db_quota_freeze(__path, __wl && __w[0] == 'f');
     if (__wo) free(__wo);
     free(__path);
     char __n[16]; int __k = snprintf(__n, sizeof(__n), "%d", __r);
@@ -3455,11 +3509,31 @@ var __sbQuotaOps = {
 // A database under LTX capture is frozen instead: every write is refused, because even a
 // DELETE adds a file to the replication spool, which counts toward the quota.
 var __sbD1Capped = {};
+var __sbD1Captured = {};
+var __sbD1Checkpointed = {};
 function __sbD1Quota(path) {
-  const full = __sbQuotaFull();
+  // Whether capture owns this database, from the private helper (no SQL), before anything
+  // below depends on it. A database that cannot open (or whose capture failed) is left to
+  // the call itself, which reports why.
+  const status = Number(__sbD1DbRaw(path, "captured"));
+  if (status < 0) return;
+  __sbD1Captured[path] = status === 1;
+  let full = __sbQuotaFull();
+  // Over the quota, a database's -wal file can hold space the app has already freed (a
+  // DELETE, a VACUUM): checkpoint it into the database and truncate it, at most once a
+  // second, then measure again. Not under capture: LTX owns that database's checkpoints.
+  if (full && !__sbD1Captured[path] && Date.now() - (__sbD1Checkpointed[path] || 0) >= 1000) {
+    __sbD1Checkpointed[path] = Date.now();
+    JSON.parse(__sbSqlRaw(path, "PRAGMA wal_checkpoint(TRUNCATE)", "[]"));
+    __sbQuotaAt = -1;
+    full = __sbQuotaFull();
+  }
   if (__sbD1Capped[path] === full) return;
   __sbD1Capped[path] = full;
-  const captured = Number(__sbD1DbRaw(path, full ? "freeze" : "thaw")) === 1;
+  const frozen = Number(__sbD1DbRaw(path, full ? "freeze" : "thaw"));
+  if (frozen < 0) return;
+  const captured = frozen === 1;
+  __sbD1Captured[path] = captured;
   if (full && captured) return;
   const size = Number(__sbD1DbRaw(path, "page_size")) || 4096;
   const pages = full
@@ -3499,6 +3573,10 @@ function __sbEnsureSchema() {
   let hasKvBinary = false;
   for (let i = 0; i < kvColumns.length; i++) if (kvColumns[i][1] === "binary") hasKvBinary = true;
   if (!hasKvBinary) __sbSql(s, "ALTER TABLE kv ADD COLUMN binary INTEGER NOT NULL DEFAULT 0", []);
+  // A key's metadata (put(key, value, { metadata })), as JSON text; same column as the broker's.
+  let hasKvMetadata = false;
+  for (let i = 0; i < kvColumns.length; i++) if (kvColumns[i][1] === "metadata") hasKvMetadata = true;
+  if (!hasKvMetadata) __sbSql(s, "ALTER TABLE kv ADD COLUMN metadata TEXT", []);
   // #56 — no `body` column: an object's bytes live in their own file under
   // "<data-dir>/r2-blobs/" (sb_r2_put_c/sb_r2_get_c), never in the sqlite row.
   __sbSql(
@@ -3602,7 +3680,7 @@ function __sbEmbeddedDispatch(msg) {
   if (op === "ping") return { ok: true, op: "pong", echo: msg.msg };
 
   if (op === "kv.get") {
-    const r = __sbSql(store, "SELECT value, expires_at, binary FROM kv WHERE ns = ? AND key = ?", [
+    const r = __sbSql(store, "SELECT value, expires_at, binary, metadata FROM kv WHERE ns = ? AND key = ?", [
       msg.ns,
       msg.key,
     ]);
@@ -3612,7 +3690,14 @@ function __sbEmbeddedDispatch(msg) {
       __sbSql(store, "DELETE FROM kv WHERE ns = ? AND key = ?", [msg.ns, msg.key]);
       return { ok: true, found: false, value: null };
     }
-    return { ok: true, found: true, value: r.rows[0][0], binary: r.rows[0][2] === 1 };
+    return {
+      ok: true,
+      found: true,
+      value: r.rows[0][0],
+      binary: r.rows[0][2] === 1,
+      metadata: r.rows[0][3],
+      expiration: expiresAt == null ? null : Math.floor(expiresAt / 1000),
+    };
   }
   if (op === "kv.put") {
     // #58 — CF rejects expirationTtl under 60 seconds; matched here.
@@ -3626,8 +3711,8 @@ function __sbEmbeddedDispatch(msg) {
     }
     __sbSql(
       store,
-      "INSERT INTO kv (ns, key, value, expires_at, binary) VALUES (?1,?2,?3,?4,?5) ON CONFLICT (ns, key) DO UPDATE SET value = ?3, expires_at = ?4, binary = ?5",
-      [msg.ns, msg.key, msg.value, expiresAt, msg.binary === true ? 1 : 0],
+      "INSERT INTO kv (ns, key, value, expires_at, binary, metadata) VALUES (?1,?2,?3,?4,?5,?6) ON CONFLICT (ns, key) DO UPDATE SET value = ?3, expires_at = ?4, binary = ?5, metadata = ?6",
+      [msg.ns, msg.key, msg.value, expiresAt, msg.binary === true ? 1 : 0, msg.metadata == null ? null : String(msg.metadata)],
     );
     return { ok: true };
   }
@@ -3636,14 +3721,28 @@ function __sbEmbeddedDispatch(msg) {
     return { ok: true };
   }
   if (op === "kv.list") {
+    // The prefix matches exactly: LIKE ignored case and read "_" and "%" in it as wildcards.
+    // With a limit (the shim from 2026-10-25), a page of entries after the cursor (the last
+    // key of the previous page), with each key's expiration and metadata; without one,
+    // every key, as before.
+    const prefix = msg.prefix || "";
+    const paged = msg.limit != null;
+    const limit = paged ? Math.max(0, Math.floor(Number(msg.limit))) : -1;
     const r = __sbSql(
       store,
-      "SELECT key FROM kv WHERE ns = ? AND key LIKE ? || '%' AND (expires_at IS NULL OR expires_at > ?) ORDER BY key",
-      [msg.ns, msg.prefix || "", Date.now()],
+      "SELECT key, expires_at, metadata FROM kv WHERE ns = ?1 AND substr(key, 1, length(?2)) = ?2 AND key > ?3 " +
+        "AND (expires_at IS NULL OR expires_at > ?4) ORDER BY key LIMIT ?5",
+      [msg.ns, prefix, paged && msg.cursor ? String(msg.cursor) : "", Date.now(), paged ? limit + 1 : -1],
     );
     const keys = [];
-    for (let i = 0; i < r.rows.length; i++) keys.push(r.rows[i][0]);
-    return { ok: true, keys };
+    const entries = [];
+    const count = paged ? Math.min(r.rows.length, limit) : r.rows.length;
+    for (let i = 0; i < count; i++) {
+      keys.push(r.rows[i][0]);
+      entries.push({ name: r.rows[i][0], expiration: r.rows[i][1] == null ? null : Math.floor(r.rows[i][1] / 1000), metadata: r.rows[i][2] });
+    }
+    const complete = !paged || r.rows.length <= limit;
+    return { ok: true, keys, entries, list_complete: complete, cursor: complete ? "" : keys[keys.length - 1] };
   }
 
   if (op === "assets.get") {

package/test/ltx-restore.ts

@@ -0,0 +1,110 @@
+// LTX chain restore, the same independent checker as native-ltx.ts (copied, so that test
+// stays as it is): every file's CRCs, checksums and TXIDs verified, pages applied in order.
+import assert from "node:assert/strict";
+import { readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// Independent CRC baseline in Bun. This intentionally uses BigInt, unlike C.
+const table: bigint[] = [];
+for (let i = 0; i < 256; i++) {
+  let c = BigInt(i);
+  for (let j = 0; j < 8; j++) c = (c >> 1n) ^ (c & 1n ? 0xd800000000000000n : 0n);
+  table.push(c);
+}
+function crc(data: Uint8Array, init = 0xffffffffffffffffn) {
+  let c = init;
+  for (const b of data) c = table[Number((c ^ BigInt(b)) & 255n)] ^ (c >> 8n);
+  return c;
+}
+const flag = 0x8000000000000000n,
+  mask = 0xffffffffffffffffn;
+function pageCrc(pgno: number, page: Uint8Array) {
+  const p = new Uint8Array(4);
+  new DataView(p.buffer).setUint32(0, pgno);
+  return flag | (crc(page, crc(p)) ^ mask);
+}
+
+export async function restore(epoch: string, output: string) {
+  const files = (await readdir(epoch)).filter((n) => n.endsWith(".ltx")).sort();
+  let db = new Uint8Array(0),
+    checksum = 0n,
+    txid = 0n;
+  for (const file of files) {
+    const b = new Uint8Array(await readFile(join(epoch, file)));
+    const v = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    assert.equal(new TextDecoder().decode(b.subarray(0, 4)), "LTX1");
+    const pageSize = v.getUint32(8),
+      commit = v.getUint32(12);
+    assert.equal(v.getBigUint64(16), txid + 1n);
+    assert.equal(v.getBigUint64(40), checksum);
+    const next = new Uint8Array(commit * pageSize);
+    next.set(db.subarray(0, next.length));
+    db = next;
+    let offset = 100,
+      hash = crc(b.subarray(0, 100));
+    const entries = [];
+    for (;;) {
+      const begin = offset,
+        pgno = v.getUint32(offset),
+        flags = v.getUint16(offset + 4);
+      hash = crc(b.subarray(offset, offset + 6), hash);
+      offset += 6;
+      if (!pgno) {
+        assert.equal(flags, 0);
+        break;
+      }
+      assert.equal(flags, 1);
+      assert(pgno <= commit);
+      const size = v.getUint32(offset);
+      hash = crc(b.subarray(offset, offset + 4), hash);
+      offset += 4;
+      const stop = offset + size;
+      assert(stop <= b.length);
+      assert.equal(b[offset++], 0xf0);
+      let literals = 15,
+        byte;
+      do {
+        byte = b[offset++];
+        literals += byte;
+      } while (byte === 255);
+      assert.equal(literals, pageSize);
+      assert.equal(offset + pageSize, stop);
+      const page = b.subarray(offset, stop);
+      db.set(page, (pgno - 1) * pageSize);
+      hash = crc(page, hash);
+      offset = stop;
+      entries.push({ pgno, offset: begin, size: stop - begin });
+    }
+    const indexStart = offset;
+    function varint() {
+      let n = 0n,
+        s = 0n;
+      for (let i = 0; i < 10; i++) {
+        assert(offset < b.length);
+        const c = b[offset++];
+        n |= BigInt(c & 127) << s;
+        if (c < 128) return Number(n);
+        s += 7n;
+      }
+      throw new Error("varint overflow");
+    }
+    for (const entry of entries) {
+      assert.equal(varint(), entry.pgno);
+      assert.equal(varint(), entry.offset);
+      assert.equal(varint(), entry.size);
+    }
+    assert.equal(varint(), 0);
+    assert.equal(v.getBigUint64(offset), BigInt(offset - indexStart));
+    offset += 8;
+    hash = crc(b.subarray(indexStart, offset + 8), hash);
+    checksum = flag;
+    for (let p = 1; p <= commit; p++)
+      checksum = flag | (checksum ^ pageCrc(p, db.subarray((p - 1) * pageSize, p * pageSize)));
+    assert.equal(v.getBigUint64(offset), checksum, file);
+    assert.equal(v.getBigUint64(offset + 8), flag | (hash ^ mask), file);
+    assert.equal(offset + 16, b.length);
+    txid = v.getBigUint64(24);
+  }
+  await writeFile(output, db);
+  return { files: files.length, txid };
+}

package/test/native-d1.ts

@@ -1,4 +1,6 @@
 import assert from "node:assert/strict";
+import { Database } from "bun:sqlite";
+import { restore } from "./ltx-restore";
 import { closeSync, openSync, readFileSync, readdirSync, readSync, writeSync } from "node:fs";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -47,7 +49,7 @@ int main(void) {
     if (!strncmp(line, ":break ", 7)) { line[strcspn(line, "\\t")] = 0; char p[1024]; snprintf(p, sizeof(p), "%s.ltx/position.tmp", line + 7); mkdir(p, 0700); puts("{}"); fflush(stdout); continue; }
     char* sql = strchr(line, '\\t'); if (!sql) return 2; *sql++ = 0;
     char* params = strchr(sql, '\\t'); if (!params) return 2; *params++ = 0;
-    if (!strncmp(line, ":db ", 4)) { int r = sql[0] == 'p' ? sb_db_page_size(line + 4) : sb_db_quota_freeze(line + 4, sql[0] == 'f'); printf("{\\"n\\":%d}\\n", r); fflush(stdout); continue; }
+    if (!strncmp(line, ":db ", 4)) { int r = sql[0] == 'p' ? sb_db_page_size(line + 4) : sb_db_quota_freeze(line + 4, sql[0] == 'c' ? -1 : sql[0] == 'f'); printf("{\\"n\\":%d}\\n", r); fflush(stdout); continue; }
     if (!strncmp(line, ":bytes ", 7)) { line[strcspn(line, "\\t")] = 0; printf("{\\"n\\":%lld}\\n", sb_dir_bytes(line + 7, 0)); fflush(stdout); continue; }
     // ":script PATH" runs SQL as a script (sb_sql_script, what exec() uses).
     char* out = !strncmp(line, ":script ", 8) ? sb_sql_script(line + 8, sql) : sb_sql_run(line, sql, params); puts(out); fflush(stdout); free(out);
@@ -149,7 +151,9 @@ int main(void) {
   const toDriver = openSync(fifoIn, "w"),
     fromDriver = openSync(fifoOut, "r");
   let pending = "";
+  let driverClosed = false;
   const sqlRaw = (path: string, sql: string, params: string) => {
+    if (driverClosed) throw new Error("original D1 driver is closed");
     writeSync(toDriver, `${path}\t${sql}\t${params}\n`);
     const chunk = Buffer.alloc(65536);
     while (!pending.includes("\n")) {
@@ -185,6 +189,7 @@ int main(void) {
       "__sbDirBytesRaw",
       "__sbD1DbRaw",
       "__sbSql",
+      "__sbSqlRaw",
       `${transport.slice(quotaStart, quotaEnd)}\nreturn { __sbQuotaCheck, __sbD1Quota, __sbQuotaFull, expire() { __sbQuotaAt = -1; } };`,
     )(
       (name: string) => (name === "SB_STORAGE_MAX_BYTES" ? String(limit) : ""),
@@ -192,8 +197,70 @@ int main(void) {
       (d: string) => String(JSON.parse(sqlRaw(":bytes " + d, "", "")).n),
       (path: string, what: string) => String(JSON.parse(sqlRaw(":db " + path, what, "")).n),
       sql,
+      sqlRaw,
     );
   const dirBytes = (d: string) => Number(JSON.parse(sqlRaw(":bytes " + d, "", "")).n);
+  // Another driver process (a restarted worker), with its own FIFOs and lifted blocks.
+  const connect = (tag: string) => {
+    const inPath = join(work, "in-" + tag),
+      outPath = join(work, "out-" + tag);
+    assert.equal(Bun.spawnSync(["mkfifo", inPath, outPath]).exitCode, 0);
+    const child = Bun.spawn(["sh", "-c", `exec "${binary}" < "${inPath}" > "${outPath}"`], {
+      env: { ...process.env, SB_LTX_ENABLE: "1", SB_LTX_DATABASE: "LTX" },
+    });
+    const to = openSync(inPath, "w"),
+      from = openSync(outPath, "r");
+    let buffered = "";
+    const raw = (path: string, text: string, params: string) => {
+      writeSync(to, `${path}\t${text}\t${params}\n`);
+      const chunk = Buffer.alloc(65536);
+      while (!buffered.includes("\n")) {
+        const n = readSync(from, chunk, 0, chunk.length, null);
+        if (n <= 0) throw new Error("driver exited");
+        buffered += chunk.toString("utf8", 0, n);
+      }
+      const line = buffered.slice(0, buffered.indexOf("\n"));
+      buffered = buffered.slice(line.length + 1);
+      return line;
+    };
+    const run = (path: string, text: string, params: unknown[]) => {
+      const r = JSON.parse(raw(path, text, JSON.stringify(params)));
+      if (r.ok === false) throw new Error("sqlite: " + r.error);
+      return r;
+    };
+    // oxlint-disable-next-line no-function-constructor -- lifting a block out of the text-only transport
+    const lifted = new Function(
+      "__sbSqlRaw",
+      "__sbSql",
+      "__sbSqlScriptRaw",
+      `${transport.slice(opsStart, opsEnd)}\nreturn { __sbD1Run, __sbD1Batch, __sbD1Open, __sbD1ExecLines };`,
+    )(raw, run, (path: string, text: string) => raw(":script " + path, text, "[]"));
+    const lift = (dir: string, limit: number) =>
+      // oxlint-disable-next-line no-function-constructor -- lifting a block out of the text-only transport
+      new Function(
+        "__sbEnv",
+        "__sbDir",
+        "__sbDirBytesRaw",
+        "__sbD1DbRaw",
+        "__sbSql",
+        "__sbSqlRaw",
+        `${transport.slice(quotaStart, quotaEnd)}\nreturn { __sbQuotaCheck, __sbD1Quota, __sbQuotaFull };`,
+      )(
+        (name: string) => (name === "SB_STORAGE_MAX_BYTES" ? String(limit) : ""),
+        () => dir,
+        (d: string) => String(JSON.parse(raw(":bytes " + d, "", "")).n),
+        (path: string, what: string) => String(JSON.parse(raw(":db " + path, what, "")).n),
+        run,
+        raw,
+      );
+    return {
+      sqlRaw: raw,
+      ops: lifted,
+      liftQuota: lift,
+      exited: child.exited,
+      close: () => (closeSync(to), closeSync(from)),
+    };
+  };
   // exec() from 2026-10-24: line by line, all or nothing, the failing line named.
   const ex = join(work, "data/d1/EXEC.sqlite");
   ops.__sbD1ExecLines(ex, ["CREATE TABLE x (id INTEGER)", "INSERT INTO x VALUES (1); INSERT INTO x VALUES (2);"]);
@@ -282,8 +349,14 @@ int main(void) {
   // With capture on, an authorization failure says so (it read "not an error" once capture
   // had run), and the quota works: its page size comes from capture, not from the
   // page_size pragma the capture authorizer refuses.
-  assert.throws(() => ops.__sbD1Run(ltx, "PRAGMA page_size", [], true), (e: Error) => e.message === "D1_ERROR: not authorized: SQLITE_AUTH");
-  assert.throws(() => ops.__sbD1ExecLines(ltx, ["PRAGMA journal_mode = DELETE"]), (e: Error) => e.message === "D1_EXEC_ERROR: Error in line 1: PRAGMA journal_mode = DELETE: not authorized");
+  assert.throws(
+    () => ops.__sbD1Run(ltx, "PRAGMA page_size", [], true),
+    (e: Error) => e.message === "D1_ERROR: not authorized: SQLITE_AUTH",
+  );
+  assert.throws(
+    () => ops.__sbD1ExecLines(ltx, ["PRAGMA journal_mode = DELETE"]),
+    (e: Error) => e.message === "D1_EXEC_ERROR: Error in line 1: PRAGMA journal_mode = DELETE: not authorized",
+  );
   const data = join(work, "data");
   const roomy = liftQuota(data, dirBytes(data) + (1 << 20));
   roomy.__sbD1Quota(ltx);
@@ -295,12 +368,39 @@ int main(void) {
   const tight = liftQuota(data, 1);
   tight.__sbD1Quota(ltx);
   const spool = ltxFiles();
-  const QUOTA = "D1_ERROR: storage quota exceeded: writes are refused while this app's data, including its replication log, is over its quota: SQLITE_FULL";
-  for (const write of ["INSERT INTO e VALUES (11, 'x')", "UPDATE e SET v = 'y' WHERE id = 10", "DELETE FROM e WHERE id = 10"])
-    assert.throws(() => ops.__sbD1Run(ltx, write, [], true), (e: Error) => e.message === QUOTA, write);
-  assert.throws(() => ops.__sbD1ExecLines(ltx, ["UPDATE e SET v = 'z'"]), (e: Error) => e.message.startsWith("D1_EXEC_ERROR: Error in line 1: UPDATE e SET v = 'z': storage quota exceeded"));
-  assert.throws(() => ops.__sbD1Batch(ltx, [{ sql: "SELECT 1", params: [] }, { sql: "DELETE FROM e", params: [] }], true), (e: Error) => e.message === QUOTA);
-  assert.equal(ops.__sbD1Batch(ltx, [{ sql: "SELECT count(*) FROM e", params: [] }], true).length, 1, "a read-only batch runs");
+  const QUOTA =
+    "D1_ERROR: storage quota exceeded: writes are refused while this app's data, including its replication log, is over its quota: SQLITE_FULL";
+  for (const write of [
+    "INSERT INTO e VALUES (11, 'x')",
+    "UPDATE e SET v = 'y' WHERE id = 10",
+    "DELETE FROM e WHERE id = 10",
+  ])
+    assert.throws(
+      () => ops.__sbD1Run(ltx, write, [], true),
+      (e: Error) => e.message === QUOTA,
+      write,
+    );
+  assert.throws(
+    () => ops.__sbD1ExecLines(ltx, ["UPDATE e SET v = 'z'"]),
+    (e: Error) => e.message.startsWith("D1_EXEC_ERROR: Error in line 1: UPDATE e SET v = 'z': storage quota exceeded"),
+  );
+  assert.throws(
+    () =>
+      ops.__sbD1Batch(
+        ltx,
+        [
+          { sql: "SELECT 1", params: [] },
+          { sql: "DELETE FROM e", params: [] },
+        ],
+        true,
+      ),
+    (e: Error) => e.message === QUOTA,
+  );
+  assert.equal(
+    ops.__sbD1Batch(ltx, [{ sql: "SELECT count(*) FROM e", params: [] }], true).length,
+    1,
+    "a read-only batch runs",
+  );
   assert.equal(ops.__sbD1Run(ltx, "SELECT v FROM e WHERE id = 10", [], true).rows[0][0], "under the quota");
   assert.equal(ltxFiles(), spool, "no LTX file while over the quota");
   const again = liftQuota(data, dirBytes(data) + (1 << 20));
@@ -314,10 +414,14 @@ int main(void) {
     "__sbSql",
     "__sbSqlScriptRaw",
     `${transport.slice(opsStart, opsEnd)}\nreturn { __sbD1Run, __sbD1Batch };`,
-  )((path: string, text: string, params: string) => {
-    if (text === "RELEASE sb_d1_batch") sqlRaw(":break " + path, "", "");
-    return sqlRaw(path, text, params);
-  }, sql, scriptRaw);
+  )(
+    (path: string, text: string, params: string) => {
+      if (text === "RELEASE sb_d1_batch") sqlRaw(":break " + path, "", "");
+      return sqlRaw(path, text, params);
+    },
+    sql,
+    scriptRaw,
+  );
   const LTX_FAILED =
     "D1_ERROR: LTX capture failed: the transaction may be committed locally but is not durable in the replication log; writes are refused until restart: SQLITE_IOERR";
   assert.throws(
@@ -336,7 +440,9 @@ int main(void) {
   );
   assert.throws(
     () => ops.__sbD1ExecLines(ltx, ["INSERT INTO e VALUES (5, 'e')"]),
-    (e: Error) => e.message === "D1_ERROR: LTX capture failed: the transaction may be committed locally but is not durable in the replication log; writes are refused until restart: SQLITE_IOERR",
+    (e: Error) =>
+      e.message ===
+      "D1_ERROR: LTX capture failed: the transaction may be committed locally but is not durable in the replication log; writes are refused until restart: SQLITE_IOERR",
     "exec() after a capture failure",
   );
   const qdir = join(work, "quota");
@@ -349,25 +455,86 @@ int main(void) {
   // SQLITE_FULL; then the directory is over, a KV write is refused, and reads and deletes
   // keep working. VACUUM gives the space back and writes resume.
   let rows = 0;
-  assert.throws(() => {
-    for (; rows < 64; rows++) ops.__sbD1Run(qdb, "INSERT INTO q VALUES (zeroblob(65536))", [], true);
-  }, (e: Error) => e.message === "D1_ERROR: database or disk is full: SQLITE_FULL");
+  assert.throws(
+    () => {
+      for (; rows < 64; rows++) ops.__sbD1Run(qdb, "INSERT INTO q VALUES (zeroblob(65536))", [], true);
+    },
+    (e: Error) => e.message === "D1_ERROR: database or disk is full: SQLITE_FULL",
+  );
   assert(rows >= 2 && rows < 5, "filled to about 256 KiB: " + rows);
   quota.expire();
   assert.equal(quota.__sbQuotaFull(), true);
-  assert.throws(() => quota.__sbQuotaCheck("KV put()"), /^Error: KV put\(\) failed: storage quota exceeded \(this app stores \d+ bytes; the limit is 262144\)$/);
+  assert.throws(
+    () => quota.__sbQuotaCheck("KV put()"),
+    /^Error: KV put\(\) failed: storage quota exceeded \(this app stores \d+ bytes; the limit is 262144\)$/,
+  );
   quota.__sbD1Quota(qdb);
   assert.equal(ops.__sbD1Run(qdb, "SELECT count(*) FROM q", [], true).rows[0][0], rows, "reads still work");
   ops.__sbD1Run(qdb, "DELETE FROM q", [], true);
   ops.__sbD1Run(qdb, "VACUUM", [], true);
-  ops.__sbD1Run(qdb, "PRAGMA wal_checkpoint(TRUNCATE)", [], true);
+  // No checkpoint by the app: over the quota the runtime checkpoints and truncates the WAL
+  // (once a second) before measuring again, so DELETE and VACUUM alone make room.
+  await Bun.sleep(1000);
   quota.expire();
   quota.__sbD1Quota(qdb);
   quota.__sbQuotaCheck("KV put()");
   ops.__sbD1Run(qdb, "INSERT INTO q VALUES (zeroblob(65536))", [], true);
+  driverClosed = true;
   closeSync(toDriver);
   closeSync(fromDriver);
   await driver.exited;
+
+  // A restart that finds the app over its quota, capture on: the first D1 call of the new
+  // worker (process) already freezes. Reads work, writes are refused, the spool and its
+  // position stay exactly as they were, and the chain restores the database byte for byte.
+  // A capture failure still reads as one, over the quota too.
+  await rm(ltx + ".ltx/position.tmp", { recursive: true, force: true });
+  const second = connect("restart");
+  const quota2 = second.liftQuota(data, 1);
+  quota2.__sbD1Quota(ltx);
+  const spoolBefore = readdirSync(generation()).sort();
+  const positionBefore = readFileSync(ltx + ".ltx/position", "utf8");
+  const count = second.ops.__sbD1Run(ltx, "SELECT count(*) FROM e", [], true).rows[0][0];
+  for (const write of ["INSERT INTO e VALUES (20, 'x')", "UPDATE e SET v = v", "DELETE FROM e"])
+    assert.throws(
+      () => second.ops.__sbD1Run(ltx, write, [], true),
+      (e: Error) => e.message === QUOTA,
+      "restart, over the quota: " + write,
+    );
+  assert.deepEqual(readdirSync(generation()).sort(), spoolBefore, "no LTX file after a clean resume over the quota");
+  assert.equal(readFileSync(ltx + ".ltx/position", "utf8"), positionBefore, "the position is unchanged");
+  second.close();
+  await second.exited;
+  {
+    const live = new Database(ltx);
+    live.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    assert.equal(live.query("SELECT count(*) AS n FROM e").get()?.n, count);
+    live.close();
+    const restored = join(work, "restart-restored.sqlite");
+    await restore(generation(), restored);
+    assert.deepEqual(
+      await readFile(restored),
+      await readFile(ltx),
+      "the retained chain restores the database byte for byte",
+    );
+  }
+  const third = connect("failure");
+  const thirdBytes = Number(JSON.parse(third.sqlRaw(":bytes " + data, "", "")).n);
+  third.liftQuota(data, thirdBytes + (1 << 20)).__sbD1Quota(ltx);
+  const breaking3 = (path: string, text: string, params: string) => {
+    if (text.startsWith("INSERT INTO e VALUES (30")) third.sqlRaw(":break " + path, "", "");
+    return third.sqlRaw(path, text, params);
+  };
+  const brokenWrite = JSON.parse(breaking3(ltx, "INSERT INTO e VALUES (30, 'x')", "[]"));
+  assert.equal(brokenWrite.code, 10, "a capture failure reports SQLITE_IOERR");
+  const failed3 = JSON.parse(third.sqlRaw(ltx, "INSERT INTO e VALUES (31, 'y')", "[]"));
+  assert.equal(failed3.code, 10, "after a capture failure, writes report it");
+  third.liftQuota(data, 1).__sbD1Quota(ltx);
+  const failedOver = JSON.parse(third.sqlRaw(ltx, "INSERT INTO e VALUES (32, 'z')", "[]"));
+  assert.equal(failedOver.code, 10, "over the quota too, the capture failure is what a write reports");
+  assert.match(failedOver.error, /^LTX capture failed/);
+  third.close();
+  await third.exited;
   console.log(
     "native d1: sb_sql_run and the D1 ops pass (blob binds, atomic batch, strict counts, foreign keys, error text)",
   );

package/test/native-ltx.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdtemp, readFile, readdir, rm, writeFile, stat } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, readdir, rm, symlink, writeFile, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Database } from "bun:sqlite";
@@ -24,12 +24,18 @@ const source = `
 #include <sys/stat.h>
 #include <time.h>
 #include <signal.h>
+#include <errno.h>
+// Reproduce denial of global temporary-file access on every test platform.
+// The sproutd sandbox qualification separately exercises real Linux Landlock.
+static FILE *forbidden_tmpfile(void) { errno=EACCES; return NULL; }
+#define tmpfile forbidden_tmpfile
 #define SB_MAX_DB 16
 ${transport.slice(start, end)}
 int main(int argc,char **argv) {
   if(argc!=2)return 2;sb_ltx_compat=1;if(sb_ltx_register())return 3;
   char lockpath[1024];snprintf(lockpath,sizeof(lockpath),"%s.ltx.lock",argv[1]);
   int lock=open(lockpath,O_RDWR|O_CREAT,0600);if(lock<0||flock(lock,LOCK_EX|LOCK_NB))return 4;
+  if(getenv("SB_LTX_TEST_HOLD_LOCK")){puts("locked");fflush(stdout);getchar();close(lock);return 0;}
   sqlite3 *db=0;if(sqlite3_open_v2(argv[1],&db,6,"sb-ltx-bounded"))return 5;
   if(getenv("SB_LTX_TEST_AUTO_VACUUM"))sqlite3_exec(db,"PRAGMA auto_vacuum=INCREMENTAL;",0,0,0);
   if(sqlite3_exec(db,"PRAGMA journal_mode=WAL;PRAGMA cache_size=-2000;",0,0,0)||sb_ltx_start(0,db,argv[1],lock))return 6;
@@ -153,6 +159,13 @@ async function restore(epoch: string, output: string) {
   await writeFile(output, db);
   return { files: files.length, txid };
 }
+async function noIndexScratch(path: string) {
+  const entries = await readdir(path + ".ltx", { withFileTypes: true });
+  assert(
+    !entries.some((entry) => entry.isFile() && /^index-[a-zA-Z0-9]{6}$/.test(entry.name)),
+    "index scratch file leaked",
+  );
+}
 async function run(path: string, sql: string, extra: Record<string, string> = {}) {
   const child = Bun.spawn([binary, path], {
     env: { ...process.env, ...extra },
@@ -169,6 +182,7 @@ async function run(path: string, sql: string, extra: Record<string, string> = {}
   ]);
   assert.equal(code, 0, error);
   assert(out.startsWith("ready\n"), out);
+  await noIndexScratch(path);
   return out.split("\n").slice(1).filter(Boolean);
 }
 async function stoppedCommit(path: string, phase: string, count = 1) {
@@ -212,6 +226,10 @@ async function stoppedCommit(path: string, phase: string, count = 1) {
   }
   child.kill("SIGKILL");
   await child.exited;
+  if (phase === "index-created") {
+    const entries = await readdir(path + ".ltx", { withFileTypes: true });
+    assert.equal(entries.filter((entry) => entry.isFile() && /^index-[a-zA-Z0-9]{6}$/.test(entry.name)).length, 1);
+  } else await noIndexScratch(path);
   assert(stopped, "did not reach crash boundary " + phase);
   return epoch;
 }
@@ -241,6 +259,45 @@ try {
   const cleanPosition = await readFile(root + "/position", "utf8");
   assert(cleanPosition.split("\n")[2].startsWith("C "));
   const finishedBefore = await readdir(join(root, epoch));
+  // SIGKILL can land between mkstemp and unlink. Only the next lock owner may
+  // discard that reserved scratch name; unrelated files and links stay intact.
+  const strayIndex = join(root, "index-abc123");
+  await writeFile(strayIndex, "stale index");
+  const unrelatedIndex = join(root, "index-not-scratch");
+  await writeFile(unrelatedIndex, "keep");
+  const indexDirectory = join(root, "index-DIR123");
+  await mkdir(indexDirectory);
+  await writeFile(join(indexDirectory, "keep"), "keep directory");
+  const outside = join(work, "outside-index-target");
+  await writeFile(outside, "keep target");
+  const indexLink = join(root, "index-LNK123");
+  await symlink(outside, indexLink);
+  const owner = Bun.spawn([binary, path], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, SB_LTX_TEST_HOLD_LOCK: "1" },
+  });
+  const lockReader = owner.stdout.getReader();
+  try {
+    const ready = await lockReader.read();
+    assert.equal(new TextDecoder().decode(ready.value), "locked\n");
+    const blocked = Bun.spawnSync([binary, path], { stdin: "ignore" });
+    assert.equal(blocked.exitCode, 4, "non-owner cannot initialize capture");
+    assert.equal(await readFile(strayIndex, "utf8"), "stale index", "non-owner must not sweep indexes");
+  } finally {
+    owner.stdin.end();
+    await owner.exited;
+    lockReader.releaseLock();
+  }
+  await run(path, "SELECT 1;\n");
+  assert(!(await readdir(root)).includes("index-abc123"), "resume must reclaim stale index");
+  assert.equal(await readFile(unrelatedIndex, "utf8"), "keep");
+  assert.equal(await readFile(join(indexDirectory, "keep"), "utf8"), "keep directory");
+  assert.equal(await readFile(indexLink, "utf8"), "keep target");
+  assert.equal(await readFile(outside, "utf8"), "keep target");
+  assert.equal(await readFile(root + "/position", "utf8"), cleanPosition);
+  assert.deepEqual(await readdir(join(root, epoch)), finishedBefore);
   for (let n = 0; n < 5; n++) {
     await run(path, "SELECT 1;\n");
     assert.equal(await readFile(root + "/position", "utf8"), cleanPosition, "idle restart must not rewrite position");
@@ -361,6 +418,7 @@ try {
   failedDb.close();
   const phases = [
     "wal-committed",
+    "index-created",
     "ltx-written",
     "ltx-fsynced",
     "ltx-published",
@@ -408,7 +466,7 @@ try {
   assert.equal(pdb.query("PRAGMA integrity_check").get()?.integrity_check, "ok");
   pdb.close();
   console.log(
-    "PASS restart: 10 SIGKILL durability boundaries, matching-prefix resume, orphan/missing/reset fallback, pending committed WAL tail captured before serving",
+    "PASS restart: 11 SIGKILL durability boundaries, matching-prefix resume, orphan/missing/reset fallback, pending committed WAL tail captured before serving",
   );
   console.log(
     "PASS native LTX: 102-file chain, independent CRC/index checks, byte-exact restore, integrity, hard WAL ceiling and oversized transaction rollback",