swarmlite 0.2.0

package/src/feeds.js

@@ -0,0 +1,135 @@
+// swarmlite feeds (JS): resolve a Swarm feed (owner, topic) to the
+// immutable root it currently points at, via the gateway's /feeds
+// endpoint. The gateway does the SOC lookup server-side; the reference
+// travels in the response's Etag header (verified live against Bee
+// 2.8.1, `Swarm-Feed-Resolved-Version: v1` — the body streams the
+// resolved content, which we cancel unread). For gateways that return
+// the raw update payload as the body instead, parsing that is the
+// fallback.
+//
+// Resolution happens once, BEFORE open(): a feed can move mid-session,
+// a database must not (see SwarmVFS.js). Typical use:
+//
+//   const { reference } = await resolveFeed(api, owner, topic);
+//   const db = await open(`${api}/bzz/${reference}/site.db`);
+//
+// Client-side SOC signature verification (so an untrusted gateway
+// cannot forge an update) is a documented follow-up, together with
+// chunk/BMT verification — both need only keccak256, already vendored.
+
+import { keccak256 } from '../vendor/js-sha3/index.js';
+import {
+  VerificationError, feedIdentifier, fromHex, socAddress, toHex, verifySoc,
+} from './verify.js';
+
+const HEX64 = /^[0-9a-fA-F]{64}$/;
+
+/** 32-byte feed topic as hex: a raw 64-hex string passes through,
+ * anything else is keccak256 of the utf-8 string — mirrors swarmfs
+ * topic_bytes(), so topics printed by `swarmlite publish` resolve. */
+export function topicHex(topic) {
+  return HEX64.test(topic) ? topic.toLowerCase() : keccak256(topic);
+}
+
+/** Resolve bzzf://<owner>/<topic> to { reference, index } using a Bee
+ * API/gateway URL. Throws with an actionable message on any failure —
+ * never returns a guess.
+ *
+ * With `verify: true` the update's single-owner chunk is fetched and
+ * checked client-side (address derivation + owner-signature recovery),
+ * so an untrusted gateway cannot forge a feed update. What cannot be
+ * proven client-side is *latestness* — a malicious gateway could serve
+ * an older (but genuine) update; that limitation is shared with every
+ * feed reader, including swarmfs. */
+export async function resolveFeed(apiUrl, owner, topic, { fetchFn, verify = false } = {}) {
+  const doFetch = fetchFn ?? ((...args) => globalThis.fetch(...args));
+  owner = owner.toLowerCase().replace(/^0x/, '');
+  if (!/^[0-9a-f]{40}$/.test(owner)) {
+    throw new Error(`feed owner must be a 20-byte hex address, got "${owner}"`);
+  }
+  const api = apiUrl.replace(/\/+$/, '');
+  const url = `${api}/feeds/${owner}/${topicHex(topic)}?type=sequence`;
+  if (verify) {
+    return resolveVerified(doFetch, api, url, owner, topicHex(topic));
+  }
+  const resp = await doFetch(url);
+  if (!resp.ok) {
+    throw new Error(
+      `feed lookup failed: HTTP ${resp.status} for ${url}` +
+      (resp.status === 404 ? ' — feed has no updates yet, or still syncing' : ''),
+    );
+  }
+  const index = parseInt(resp.headers.get('swarm-feed-index') ?? '', 16);
+  const done = (reference) =>
+    ({ reference, index: Number.isNaN(index) ? null : index });
+
+  // Bee resolves the update server-side; Etag carries the reference and
+  // the body streams the content it points at — skip the download.
+  const etag = (resp.headers.get('etag') ?? '').replaceAll('"', '');
+  if (HEX64.test(etag)) {
+    await resp.body?.cancel?.();
+    return done(etag.toLowerCase());
+  }
+
+  // fallback: the body is the raw update payload (bee-js format)
+  const payload = new Uint8Array(await resp.arrayBuffer());
+  if (payload.byteLength === 40 || payload.byteLength === 72) {
+    return done(toHex(payload.subarray(8))); // timestamp(8) + ref(32|64)
+  }
+  if (payload.byteLength === 32 || payload.byteLength === 64) {
+    return done(toHex(payload)); // bare reference, no timestamp
+  }
+  throw new Error(
+    `unexpected /feeds response from ${url}: no reference Etag, and the ` +
+    `body (${payload.byteLength} bytes) is not a bee-js feed update ` +
+    '(timestamp + reference) — was the feed published with swarmlite/swarmfs?',
+  );
+}
+
+/** Verified resolution: take only the update INDEX from the gateway's
+ * headers (server-side sequence lookup), then fetch the single-owner
+ * chunk at the address we derive ourselves and verify it fully —
+ * mirrors swarmfs FeedOps.latest(verify=True). */
+async function resolveVerified(doFetch, api, url, owner, topicHexStr) {
+  const head = await doFetch(url, {
+    headers: { 'Swarm-Only-Root-Chunk': 'true' }, // headers only, skip content
+  });
+  if (!head.ok) {
+    throw new Error(
+      `feed lookup failed: HTTP ${head.status} for ${url}` +
+      (head.status === 404 ? ' — feed has no updates yet, or still syncing' : ''),
+    );
+  }
+  await head.body?.cancel?.();
+  const indexHex = head.headers.get('swarm-feed-index');
+  if (!/^[0-9a-fA-F]{16}$/.test(indexHex ?? '')) {
+    throw new VerificationError(
+      `cannot verify: no Swarm-Feed-Index header on ${url} (got ${indexHex})`,
+    );
+  }
+  const index = parseInt(indexHex, 16);
+  const ownerBytes = fromHex(owner);
+  const addr = socAddress(feedIdentifier(fromHex(topicHexStr), index), ownerBytes);
+  const resp = await doFetch(`${api}/chunks/${toHex(addr)}`);
+  if (!resp.ok) {
+    throw new Error(
+      `feed update chunk ${toHex(addr).slice(0, 16)}… not retrievable ` +
+      `(HTTP ${resp.status}) — the gateway reported index ${index} but ` +
+      'does not serve the corresponding single-owner chunk',
+    );
+  }
+  const soc = new Uint8Array(await resp.arrayBuffer());
+  const payload = verifySoc(soc, ownerBytes, addr); // throws VerificationError on forgery
+  let ref;
+  if (payload.byteLength === 40 || payload.byteLength === 72) {
+    ref = payload.subarray(8); // timestamp(8) + reference(32|64)
+  } else if (payload.byteLength === 32 || payload.byteLength === 64) {
+    ref = payload;
+  } else {
+    throw new VerificationError(
+      `verified feed update carries an unexpected ${payload.byteLength}-byte ` +
+      'payload — not a bee-js update (timestamp + reference)',
+    );
+  }
+  return { reference: toHex(ref), index };
+}

package/src/index.js

@@ -0,0 +1,97 @@
+// swarmlite/js: open a SQLite database published on Swarm, lazily.
+//
+//   import { open } from './src/index.js';
+//   const db = await open('http://localhost:1633/bzz/<root>/site.db');
+//   const rows = await db.query('SELECT title FROM posts LIMIT 5');
+//   console.log(db.stats());   // pages/bytes fetched vs. file size
+//
+// Fully self-contained: wa-sqlite is vendored, everything loads from
+// relative URLs, so the whole reader can itself be published on Swarm.
+
+import SQLiteAsyncESMFactory from '../vendor/wa-sqlite/dist/wa-sqlite-async.mjs';
+import * as SQLite from '../vendor/wa-sqlite/src/sqlite-api.js';
+import { SwarmVFS } from './SwarmVFS.js';
+import { NodeStore, lookupPath } from './mantaray.js';
+import { VerifiedChunkStore, verifiedRead, verifiedSize } from './verify.js';
+
+export { SwarmVFS, PAGE_SIZE } from './SwarmVFS.js';
+export { resolveFeed, topicHex } from './feeds.js';
+export { VerificationError } from './verify.js';
+
+let modulePromise = null;
+let aliasCounter = 0;
+
+/** Open a read-only lazy connection to a database URL (gateway URL with
+ * Range support). Returns { query, stats, close, sqlite3, db, vfs }.
+ *
+ * With `verify: true` every byte is checked against the 32-byte root in
+ * the URL: the manifest is resolved client-side and pages are read
+ * chunk-by-chunk via /chunks, each BMT-verified — safe against a
+ * tampering gateway, at the cost of one request per 4 KB chunk (a local
+ * light node verifies natively, so the default fast path is fine
+ * there). Requires a '<api>/bzz/<64-hex root>/<path>' URL. */
+export async function open(url, { cachePages, moduleOptions, verify = false, fetchFn } = {}) {
+  modulePromise ??= SQLiteAsyncESMFactory(moduleOptions);
+  const module = await modulePromise;
+  const sqlite3 = SQLite.Factory(module);
+
+  const vfs = new SwarmVFS({ cachePages, fetchFn });
+  // register a unique VFS name per open (each VFS instance carries its
+  // own cache/stats), and open via a short alias — SQLite VFS filename
+  // buffers can be as small as 64 bytes, too short for gateway URLs
+  vfs.name = `swarmlite-${++aliasCounter}`;
+  const alias = `db-${aliasCounter}`;
+  let chunkStore = null;
+  if (verify) {
+    const m = /^(.+?)\/bzz\/([0-9a-fA-F]{64})\/(.+)$/.exec(url);
+    if (!m) {
+      throw new Error(
+        `verify: true needs a '<api>/bzz/<64-hex root>/<path>' URL to ` +
+        `know what to verify against, got ${url}`,
+      );
+    }
+    const [, api, root, path] = m;
+    chunkStore = new VerifiedChunkStore(api, { fetchFn });
+    const nodes = new NodeStore((ref) => verifiedRead(chunkStore, ref));
+    const entry = await lookupPath(nodes, root.toLowerCase(), path);
+    if (!entry) {
+      throw new Error(`verify: '${path}' is not a file in manifest ${root}`);
+    }
+    const size = await verifiedSize(chunkStore, entry.reference);
+    vfs.registerSource(alias, {
+      size,
+      read: (from, toInclusive) =>
+        verifiedRead(chunkStore, entry.reference, from, toInclusive + 1),
+    });
+  } else {
+    vfs.registerUrl(alias, url);
+  }
+  sqlite3.vfs_register(vfs, false);
+  const db = await sqlite3.open_v2(alias, SQLite.SQLITE_OPEN_READONLY, vfs.name);
+
+  /** Run SQL; returns [{col: value, ...}, ...]. */
+  async function query(sql, bindings) {
+    const rows = [];
+    for await (const stmt of sqlite3.statements(db, sql)) {
+      if (bindings) sqlite3.bind_collection(stmt, bindings);
+      const cols = sqlite3.column_names(stmt);
+      while ((await sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+        const row = {};
+        cols.forEach((c, i) => { row[c] = sqlite3.column(stmt, i); });
+        rows.push(row);
+      }
+    }
+    return rows;
+  }
+
+  return {
+    query,
+    // verified mode adds chunk-level counters (network = chunk bytes,
+    // including intermediate tree/manifest chunks)
+    stats: () => ({ ...vfs.statsFor(alias), ...(chunkStore?.stats ?? {}) }),
+    close: () => sqlite3.close(db),
+    sqlite3,
+    db,
+    vfs,
+  };
+}

package/src/mantaray.js

@@ -0,0 +1,157 @@
+// Mantaray manifest lookup: resolve a path inside a manifest trie to
+// the file's data reference, fetching nodes on demand. A read-only port
+// of swarmfs's mantaray/node.py (unmarshal) and mantaray/walk.py
+// (NodeStore/locate) — see there for the wire-format documentation.
+// Only lookup is ported; listing and building stay publisher-side.
+//
+// Transport-agnostic: the store's `load` function (ref hex -> node
+// bytes) is the only I/O dependency. Load through verifiedRead and the
+// whole manifest resolution is trustless.
+
+export class MantarayFormatError extends Error {
+  name = 'MantarayFormatError';
+}
+
+const OBFUSCATION_KEY_SIZE = 32;
+const VERSION_HASH_SIZE = 31;
+const HEADER_SIZE = OBFUSCATION_KEY_SIZE + VERSION_HASH_SIZE + 1; // 64
+const FORK_HEADER_SIZE = 2;
+const FORK_PRE_REFERENCE_SIZE = 32;
+const PREFIX_MAX_SIZE = FORK_PRE_REFERENCE_SIZE - FORK_HEADER_SIZE; // 30
+const METADATA_SIZE_SIZE = 2;
+
+// keccak256("mantaray:0.1") / keccak256("mantaray:0.2") truncated to 31
+// bytes, as pre-computed in bee's pkg/manifest/mantaray/marshal.go
+const VERSION_01_HASH = '025184789d63635766d78c41900196b57d7400875ebe4d9b5d1e76bd9652a9';
+const VERSION_02_HASH = '5768b3b6a7db56d21d1abff40d41cebfc83448fed8d7e9b06ec0d3b073f28f';
+
+const NT_VALUE = 0x02;
+const NT_EDGE = 0x04;
+
+const hex = (bytes) =>
+  Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+
+/** Decode one serialized Mantaray node. Returns
+ * { entry: hex|null, forks: Map<byte, fork> } with fork =
+ * { nodeType, prefix: Uint8Array, ref: hex, metadata: object|null }. */
+export function unmarshal(data) {
+  if (data.length < HEADER_SIZE) {
+    throw new MantarayFormatError(`serialized node too short: ${data.length} bytes`);
+  }
+  const key = data.subarray(0, OBFUSCATION_KEY_SIZE);
+  const body = data.slice(OBFUSCATION_KEY_SIZE); // copy — XORed in place
+  if (key.some((b) => b !== 0)) {
+    for (let i = 0; i < body.length; i++) body[i] ^= key[i % OBFUSCATION_KEY_SIZE];
+  }
+
+  const versionHash = hex(body.subarray(0, VERSION_HASH_SIZE));
+  let version;
+  if (versionHash === VERSION_01_HASH) version = 1;
+  else if (versionHash === VERSION_02_HASH) version = 2;
+  else throw new MantarayFormatError(`unknown version hash: ${versionHash}`);
+
+  const rbs = body[VERSION_HASH_SIZE];
+  let off = VERSION_HASH_SIZE + 1;
+  if (body.length < off + rbs + 32) {
+    throw new MantarayFormatError('serialized node too short for entry + fork bitmap');
+  }
+  const entryBytes = body.subarray(off, off + rbs);
+  off += rbs;
+  const bitmap = body.subarray(off, off + 32);
+  off += 32;
+
+  const node = {
+    entry: entryBytes.some((b) => b !== 0) ? hex(entryBytes) : null,
+    forks: new Map(),
+  };
+
+  for (let b = 0; b < 256; b++) {
+    if (!((bitmap[b >> 3] >> (b & 7)) & 1)) continue;
+    if (version === 2 && rbs === 0) continue; // bee skips fork parsing here
+    const base = FORK_PRE_REFERENCE_SIZE + rbs;
+    if (body.length < off + base) {
+      throw new MantarayFormatError(`truncated fork record for byte ${b}`);
+    }
+    const nodeType = body[off];
+    const prefixLen = body[off + 1];
+    if (prefixLen === 0 || prefixLen > PREFIX_MAX_SIZE) {
+      throw new MantarayFormatError(`invalid fork prefix length: ${prefixLen}`);
+    }
+    const prefix = body.subarray(off + FORK_HEADER_SIZE, off + FORK_HEADER_SIZE + prefixLen);
+    const ref = hex(body.subarray(off + FORK_PRE_REFERENCE_SIZE, off + base));
+
+    let metadata = null;
+    let size = base;
+    if (version === 2 && nodeType & 0x10 /* NT_WITH_METADATA */) {
+      const msize = (body[off + base] << 8) | body[off + base + 1];
+      size = base + METADATA_SIZE_SIZE + msize;
+      if (body.length < off + size) {
+        throw new MantarayFormatError(`truncated fork metadata for byte ${b}`);
+      }
+      const raw = body.subarray(off + base + METADATA_SIZE_SIZE, off + size);
+      try {
+        metadata = JSON.parse(new TextDecoder().decode(raw)); // '\n' padding is valid JSON whitespace
+      } catch (e) {
+        throw new MantarayFormatError(`bad fork metadata JSON: ${e}`);
+      }
+    }
+    node.forks.set(b, { nodeType, prefix, ref, metadata });
+    off += size;
+  }
+  return node;
+}
+
+/** Fetch-and-parse cache for manifest nodes, keyed by reference (hex).
+ * Content-addressed, so cached nodes never go stale. */
+export class NodeStore {
+  #load;
+  #cache = new Map();
+  #cacheSize;
+
+  constructor(load, { cacheSize = 4096 } = {}) {
+    this.#load = load;
+    this.#cacheSize = cacheSize;
+  }
+
+  async get(refHex) {
+    const hit = this.#cache.get(refHex);
+    if (hit !== undefined) {
+      this.#cache.delete(refHex);
+      this.#cache.set(refHex, hit);
+      return hit;
+    }
+    const node = unmarshal(await this.#load(refHex));
+    this.#cache.set(refHex, node);
+    while (this.#cache.size > this.#cacheSize) {
+      this.#cache.delete(this.#cache.keys().next().value);
+    }
+    return node;
+  }
+}
+
+const startsWith = (bytes, prefix) =>
+  prefix.length <= bytes.length && prefix.every((b, i) => bytes[i] === b);
+
+/** Resolve `path` inside the manifest at `rootRefHex` to the file's
+ * data reference: { reference: hex, metadata } — or null if the path
+ * does not name a file in the manifest. */
+export async function lookupPath(store, rootRefHex, path) {
+  let needle = new TextEncoder().encode(path);
+  let node = await store.get(rootRefHex);
+  while (needle.length) {
+    const fork = node.forks.get(needle[0]);
+    if (fork === undefined || !startsWith(needle, fork.prefix)) return null;
+    needle = needle.subarray(fork.prefix.length);
+    if (!needle.length) {
+      // path consumed exactly at this fork: a file iff it's a value
+      // fork whose child carries an entry
+      if (!(fork.nodeType & NT_VALUE)) return null;
+      const child = await store.get(fork.ref);
+      return child.entry ? { reference: child.entry, metadata: fork.metadata } : null;
+    }
+    if (!(fork.nodeType & NT_EDGE)) return null;
+    node = await store.get(fork.ref);
+  }
+  // empty path = the manifest root itself: a directory, not a file
+  return null;
+}

package/src/memvfs.js

@@ -0,0 +1,112 @@
+// A tiny writable in-memory VFS for wa-sqlite, used by the publisher's
+// prepare step (js/src/prepare.js): the database file and its rollback
+// journal live in RAM, the checklist runs (VACUUM etc.), and the
+// finished bytes are read back out. Fully synchronous — no Asyncify
+// round trips — and never touches disk or network.
+
+import * as VFS from '../vendor/wa-sqlite/src/VFS.js';
+
+class MemFile {
+  data = new Uint8Array(0);
+  size = 0;
+
+  ensure(capacity) {
+    if (capacity <= this.data.length) return;
+    const grown = new Uint8Array(Math.max(capacity, this.data.length * 2, 4096));
+    grown.set(this.data);
+    this.data = grown;
+  }
+}
+
+export class MemVFS extends VFS.Base {
+  name = 'swarmlite-mem';
+  mxPathName = 512;
+
+  /** @type {Map<string, MemFile>} filename -> contents */
+  files = new Map();
+  /** @type {Map<number, {file: MemFile, name: string, deleteOnClose: boolean}>} */
+  #open = new Map();
+
+  /** Preload a file (e.g. the database to prepare). */
+  put(name, bytes) {
+    const f = new MemFile();
+    f.data = new Uint8Array(bytes); // private copy
+    f.size = bytes.byteLength;
+    this.files.set(name, f);
+  }
+
+  /** Read a file's current contents (e.g. the prepared database). */
+  get(name) {
+    const f = this.files.get(name);
+    return f ? f.data.slice(0, f.size) : null;
+  }
+
+  xOpen(name, fileId, flags, pOutFlags) {
+    name = name ?? `temp-${fileId}`; // anonymous temp files
+    let file = this.files.get(name);
+    if (!file) {
+      if (!(flags & VFS.SQLITE_OPEN_CREATE)) return VFS.SQLITE_CANTOPEN;
+      file = new MemFile();
+      this.files.set(name, file);
+    }
+    this.#open.set(fileId, {
+      file, name,
+      deleteOnClose: Boolean(flags & VFS.SQLITE_OPEN_DELETEONCLOSE),
+    });
+    pOutFlags.setInt32(0, flags, true);
+    return VFS.SQLITE_OK;
+  }
+
+  xClose(fileId) {
+    const entry = this.#open.get(fileId);
+    this.#open.delete(fileId);
+    if (entry?.deleteOnClose) this.files.delete(entry.name);
+    return VFS.SQLITE_OK;
+  }
+
+  xRead(fileId, pData, iOffset) {
+    const { file } = this.#open.get(fileId);
+    const available = Math.max(file.size - iOffset, 0);
+    const n = Math.min(pData.byteLength, available);
+    if (n > 0) pData.set(file.data.subarray(iOffset, iOffset + n), 0);
+    if (n < pData.byteLength) {
+      pData.fill(0, n);
+      return VFS.SQLITE_IOERR_SHORT_READ;
+    }
+    return VFS.SQLITE_OK;
+  }
+
+  xWrite(fileId, pData, iOffset) {
+    const { file } = this.#open.get(fileId);
+    file.ensure(iOffset + pData.byteLength);
+    file.data.set(pData, iOffset);
+    file.size = Math.max(file.size, iOffset + pData.byteLength);
+    return VFS.SQLITE_OK;
+  }
+
+  xTruncate(fileId, iSize) {
+    const { file } = this.#open.get(fileId);
+    file.size = Math.min(file.size, iSize);
+    return VFS.SQLITE_OK;
+  }
+
+  xFileSize(fileId, pSize64) {
+    const { file } = this.#open.get(fileId);
+    pSize64.setBigInt64(0, BigInt(file.size), true);
+    return VFS.SQLITE_OK;
+  }
+
+  xSync() {
+    return VFS.SQLITE_OK; // RAM is always "synced"
+  }
+
+  xDelete(name) {
+    this.files.delete(name);
+    return VFS.SQLITE_OK;
+  }
+
+  xAccess(name, flags, pResOut) {
+    pResOut.setInt32(0, this.files.has(name) ? 1 : 0, true);
+    return VFS.SQLITE_OK;
+  }
+}

package/src/prepare.js

@@ -0,0 +1,104 @@
+// The publisher's checklist, in JS: mirror of swarmlite/publish.py
+// prepare() — PRAGMA page_size=4096, ANALYZE, VACUUM, integrity_check,
+// and the same missing-index warnings (PRAGMA table_list: shadow tables
+// skipped, WITHOUT ROWID counts as indexed). Runs entirely in memory on
+// wa-sqlite via MemVFS; the input bytes are never modified.
+//
+// One divergence from the Python publisher: WAL-mode inputs are
+// REJECTED rather than converted. Switching out of WAL requires
+// opening the database, and WAL needs shared-memory VFS support that
+// the in-memory VFS (deliberately) does not have. The fix is a
+// one-liner for the caller, stated in the error.
+
+import SQLiteAsyncESMFactory from '../vendor/wa-sqlite/dist/wa-sqlite-async.mjs';
+import * as SQLite from '../vendor/wa-sqlite/src/sqlite-api.js';
+import { MemVFS } from './memvfs.js';
+
+export const PAGE_SIZE = 4096; // one SQLite page = one Swarm chunk
+const LARGE_TABLE_ROWS = 5000;
+
+export class PrepareError extends Error {
+  name = 'PrepareError';
+}
+
+let modulePromise = null;
+let vfsCounter = 0;
+
+/** Produce a publish-ready copy of a SQLite database.
+ * @param {Uint8Array} bytes - the database file's contents
+ * @returns {Promise<{bytes: Uint8Array, warnings: string[]}>} */
+export async function prepare(bytes, { moduleOptions } = {}) {
+  if (bytes.byteLength < 100 ||
+      new TextDecoder().decode(bytes.subarray(0, 15)) !== 'SQLite format 3') {
+    throw new PrepareError('not a SQLite database (bad header magic)');
+  }
+  if (bytes[18] === 2 || bytes[19] === 2) {
+    throw new PrepareError(
+      'database is in WAL mode, which cannot ship to Swarm (WAL needs ' +
+      'sidecar files). Switch it locally first — ' +
+      `sqlite3 your.db "PRAGMA journal_mode=DELETE" — and re-run`,
+    );
+  }
+
+  modulePromise ??= SQLiteAsyncESMFactory(moduleOptions);
+  const sqlite3 = SQLite.Factory(await modulePromise);
+  const vfs = new MemVFS();
+  vfs.name = `swarmlite-mem-${++vfsCounter}`;
+  vfs.put('work.db', bytes);
+  sqlite3.vfs_register(vfs, false);
+  const db = await sqlite3.open_v2(
+    'work.db', SQLite.SQLITE_OPEN_READWRITE | SQLite.SQLITE_OPEN_CREATE, vfs.name);
+
+  async function rows(sql) {
+    const out = [];
+    for await (const stmt of sqlite3.statements(db, sql)) {
+      while ((await sqlite3.step(stmt)) === SQLite.SQLITE_ROW) {
+        out.push(sqlite3.row(stmt));
+      }
+    }
+    return out;
+  }
+
+  const warnings = [];
+  try {
+    const [[pageSize]] = await rows('PRAGMA page_size');
+    if (pageSize !== PAGE_SIZE) {
+      await rows(`PRAGMA page_size=${PAGE_SIZE}`);
+      warnings.push(
+        `page_size was ${pageSize}; rewriting to ${PAGE_SIZE} ` +
+        '(one page = one Swarm chunk)',
+      );
+    }
+
+    // ordinary tables only: 'shadow' skips virtual-table internals, and
+    // wr=1 (WITHOUT ROWID) means the PRIMARY KEY is the table's B-tree
+    for (const [schema, table, type, _ncol, wr] of await rows('PRAGMA table_list')) {
+      if (schema !== 'main' || type !== 'table' || wr) continue;
+      if (table.startsWith('sqlite_')) continue;
+      const [[n]] = await rows(`SELECT count(*) FROM "${table}"`);
+      const [[idx]] = await rows(
+        `SELECT count(*) FROM sqlite_master WHERE type='index' ` +
+        `AND tbl_name='${table.replaceAll("'", "''")}'`);
+      if (n >= LARGE_TABLE_ROWS && idx === 0) {
+        warnings.push(
+          `table '${table}' has ${n} rows and no index — remote queries ` +
+          'filtering on non-rowid columns will scan the whole file ' +
+          '(INTEGER PRIMARY KEY lookups are still fine)',
+        );
+      }
+    }
+
+    await rows('ANALYZE');
+    await rows('VACUUM'); // applies the page size, defragments
+
+    const check = (await rows('PRAGMA integrity_check')).map((r) => r[0]);
+    if (check.length !== 1 || check[0] !== 'ok') {
+      throw new PrepareError(
+        `integrity_check failed: ${check.slice(0, 5).join('; ')}`);
+    }
+  } finally {
+    await sqlite3.close(db);
+  }
+
+  return { bytes: vfs.get('work.db'), warnings };
+}