@blamejs/core 0.18.54 → 0.18.55

package/lib/db.js

@@ -45,6 +45,7 @@
  */
 var nodeFs = require("node:fs");
 var nodePath = require("node:path");
+var nodeUrl = require("node:url");
 var { DatabaseSync } = require("node:sqlite");
 var { Readable } = require("node:stream");
 var atomicFile = require("./atomic-file");
@@ -74,6 +75,7 @@ var safeJson = require("./safe-json");
 var safeSql = require("./safe-sql");
 var sql = require("./sql");
 var validateOpts = require("./validate-opts");
+var pidProbe = require("./pid-probe");
 var vault = require("./vault");
 var vaultAad = require("./vault-aad");
 
@@ -85,6 +87,11 @@ var vaultAad = require("./vault-aad");
 var _SQL_OPTS = { dialect: "sqlite", quoteName: true };
 
 var DbError = defineClass("DbError", { alwaysPermanent: true });
+
+// Sidecar naming the process that owns an encrypted-mode working copy, so the
+// stale sweep can ask whether that process is still running instead of reading
+// the filename as proof it is not.
+var OWNER_SUFFIX = ".owner";
 var WormViolationError = require("./framework-error").WormViolationError;
 var _wormErr = WormViolationError.factory;
 
@@ -161,6 +168,15 @@ var statfsProbe   = null;      // free-space reader (fs.statfsSync; injectable f
 // reload); the flag makes it idempotent. The handler reads live module
 // state at exit time, so a later re-init is still covered.
 var _exitHandlerRegistered = false;
+// A read-only open never writes back. Two processes sharing one encrypted
+// volume each decrypt their own working copy at open time, so whichever
+// flushes last overwrites what the other wrote since. A reader that promises
+// not to flush cannot take part in that: it reads the snapshot it decrypted
+// and leaves db.enc exactly as it found it. Held as module state so the ONE
+// place that writes db.enc can honour it, rather than each of the three
+// callers remembering to.
+var readOnly  = false;
+var immutableOpen = false;
 var dataDir   = null;
 var initialized = false;
 // Monotonic identity of the live `database` handle. Bumped on every (re)open,
@@ -717,14 +733,75 @@ var log = boot("db");
 
 // ---- Tmpfs detection ----
 
-function resolveTmpDir(optsTmpDir) {
+// Where the decrypted working copy lives, and whether that place is in memory.
+//
+// Both questions take the platform and the filesystem reader as parameters. A
+// rule about what Windows does is untestable from a Linux CI host while it is
+// reached only by running on Windows, and these two rules are the difference
+// between encrypted-at-rest holding and silently not holding.
+
+// The /dev/shm probe is Linux-only, and the guard carries weight rather than
+// tidiness: a leading-slash path on Windows is DRIVE-relative, so asking
+// existsSync("/dev/shm") there asks about C:\dev\shm. That is ordinary
+// persistent NTFS, it is trivially created, and answering yes puts the
+// decrypted database on exactly the disk atRest: "encrypted" exists to keep it
+// off — with the residency check below unable to fire, because it too can only
+// read a mount table by path on Linux.
+function _resolveTmpDirFrom(optsTmpDir, platform, exists) {
   if (optsTmpDir) return optsTmpDir;
   var envTmp = safeEnv.readVar("BLAMEJS_TMPDIR");
   if (envTmp) return envTmp;
-  if (nodeFs.existsSync("/dev/shm")) return "/dev/shm";
+  if (platform !== "linux") return null;
+  if (exists("/dev/shm")) return "/dev/shm";
   return null;
 }
 
+function resolveTmpDir(optsTmpDir) {
+  return _resolveTmpDirFrom(optsTmpDir, process.platform, nodeFs.existsSync);
+}
+
+// Returns null when the path is a recognized in-memory mount, or { determined,
+// message } describing why it is not. The caller decides what each costs.
+//
+// The two cases are not the same finding, and collapsing them makes the posture
+// worse rather than stricter. On Linux the mount table can be compared against,
+// so a path outside the known tmpfs mounts is a POSITIVE determination that the
+// working copy would land on disk: determined, and refused. Off Linux nothing
+// can be compared — the heuristic is a path match against mounts only Linux has
+// — so the honest report is that we do not know, and an operator who named the
+// path is told rather than refused.
+//
+// Refusing the undetermined case would mean every macOS and Windows operator
+// setting allowNonTmpfsTmpDir: true to boot at all, and that flag travels: set
+// once in shared config, it also switches off the Linux check, which is the one
+// that works. A warning everyone sees beats a flag everyone sets.
+function _tmpDirResidencyIssue(tmpDir, platform, realpath) {
+  if (platform !== "linux") {
+    return {
+      determined: false,
+      message: "db.init: tmpDir '" + tmpDir + "' cannot be shown to be an in-memory " +
+        "mount on " + platform + " — the tmpfs heuristic compares against /dev/shm " +
+        "/run/shm /run/user /tmp, which are Linux mounts. If it is disk-backed, the " +
+        "decrypted working copy reaches backup snapshots, replication, and forensic " +
+        "disk images; verify the mount is in-memory out-of-band, or pass " +
+        "atRest: 'plain' if encryption-at-rest is not required.",
+    };
+  }
+  var realTmp = "";
+  try { realTmp = realpath(tmpDir); } catch (_e) { /* stat best-effort */ }
+  if (realTmp.indexOf("/dev/shm") === 0 || realTmp.indexOf("/run/shm") === 0 ||
+      realTmp.indexOf("/run/user/") === 0 || realTmp.indexOf("/tmp") === 0) {
+    return null;
+  }
+  return {
+    determined: true,
+    message: "db.init: tmpDir '" + tmpDir + "' (real: '" + realTmp +
+      "') does not resolve under /dev/shm /run/shm /run/user /tmp — it is not a " +
+      "recognized tmpfs mount. A persistent-disk tmpDir leaks the decrypted " +
+      "working copy into backup snapshots, replication, and forensic disk images.",
+  };
+}
+
 // ---- DB encryption key management ----
 
 // AAD binds the sealed DB encryption key to the deployment's dataDir
@@ -765,7 +842,14 @@ function loadOrCreateDbKey(dataDirPath, keyPathOverride) {
       // the next boot is AAD-verified. Read-migration preserves the key
       // bytes — no re-key, no operator action.
       b64 = vault.unseal(sealed);
-      if (b64) {
+      // The re-seal is a convenience, not part of reading the key: by this
+      // point the bytes are already in hand and the open would succeed without
+      // it. So a read-only handle unseals and moves on. Writing here would
+      // fail outright on a genuinely read-only mount, taking down an open that
+      // had no need to write, and on a writable one it would modify a volume
+      // this handle promised not to touch — to perform a rewrite the next
+      // writer performs anyway.
+      if (b64 && !readOnly) {
         atomicFile.writeSync(keyPath, vaultAad.seal(b64, aad), { fileMode: 0o600 });
         log("re-sealed DB encryption key with deployment-path binding at " + keyPath);
       }
@@ -777,6 +861,17 @@ function loadOrCreateDbKey(dataDirPath, keyPathOverride) {
     return Buffer.from(b64, "base64");
   }
   // First run — generate, AAD-seal, persist (atomic).
+  //
+  // A read-only open has no first run. There is no key, so there is no volume
+  // encrypted under one, so there is nothing for a reader to read. Generating
+  // one would write the file this handle promised not to write and then hand
+  // back an empty database indistinguishable from a successful read of an
+  // empty volume. Saying which of the two happened is the more useful answer.
+  if (readOnly) {
+    throw _dbErr("db/read-only-no-key",
+      "readOnly: no encryption key at " + keyPath + " — a read-only open reads an " +
+      "existing encrypted volume and will not create one");
+  }
   var raw = generateBytes(C.BYTES.bytes(32));
   var sealedKey = vaultAad.seal(raw.toString("base64"), aad);
   atomicFile.writeSync(keyPath, sealedKey, { fileMode: 0o600 });
@@ -945,11 +1040,116 @@ function _installWriteGate() {
   };
 }
 
+// Null when the main database file is known to carry every committed
+// transaction, or the reason that could not be established.
+//
+// Three places treat the main file as the whole database: the immutable open,
+// snapshot(), and the flush to db.enc. It is the whole database only once the
+// write-ahead log has been folded into it, and each of these would otherwise
+// produce a database that opens cleanly while missing its newest rows — worse
+// than failing outright, because nothing downstream can tell.
+//
+// The length of the log is not the question. A passive or automatic checkpoint
+// copies frames into the main file and leaves the log allocated behind it, so a
+// non-empty log does not by itself mean anything is missing, and refusing on
+// size alone would reject snapshots that are perfectly complete.
+//
+// Where the handle can write, the checkpoint itself reports what it moved, and
+// that report is the answer. Where it cannot, there is no way to ask without
+// writing. Both "cannot ask" and "cannot read the log" are unknown rather than
+// empty, and unknown fails closed: a log that is missing is a database with no
+// log, but a log that errors on stat is a log we know nothing about.
+// Stat and checkpoint are parameters for the same reason the platform is
+// elsewhere in this file: "an unreadable log must not read as an absent one"
+// and "an allocated log that is fully checkpointed is complete" are both rules
+// about states that are awkward to arrange for real and easy to describe.
+function _walNotDrainedFrom(forPath, canCheckpoint, stat, checkpoint) {
+  var walStat = null;
+  try { walStat = stat(forPath + "-wal"); }
+  catch (e) {
+    if (e && e.code === "ENOENT") return null;
+    return "the write-ahead log '" + forPath + "-wal' could not be read (" +
+      ((e && e.code) || "unknown error") + "), so whether the database file holds " +
+      "every committed transaction cannot be established";
+  }
+  if (walStat.size === 0) return null;
+
+  if (!canCheckpoint) {
+    return "'" + forPath + "-wal' holds " + walStat.size + " byte(s) and this handle " +
+      "cannot checkpoint, so whether those frames are already in the database file " +
+      "cannot be established without writing";
+  }
+
+  // PRAGMA wal_checkpoint reports (busy, log, checkpointed): total frames in
+  // the log, and how many of them reached the database file.
+  var row = null;
+  try { row = checkpoint(); }
+  catch (e) {
+    return "the checkpoint that folds the write-ahead log into the database file " +
+      "failed (" + ((e && e.message) || String(e)) + ")";
+  }
+  if (!row) return null;
+  if (Number(row.busy) !== 0) {
+    return "the checkpoint could not run to completion because the database was busy, " +
+      "so '" + forPath + "-wal' may hold transactions the database file does not";
+  }
+  var frames = Number(row.log) || 0;
+  var moved  = Number(row.checkpointed) || 0;
+  if (frames > moved) {
+    return "the checkpoint left " + (frames - moved) + " of " + frames + " frame(s) in '" +
+      forPath + "-wal', so the database file does not carry every committed transaction";
+  }
+  return null;
+}
+
+function _walNotDrained(forPath, canCheckpoint) {
+  return _walNotDrainedFrom(forPath, canCheckpoint, nodeFs.statSync, function () {
+    return database.prepare("PRAGMA wal_checkpoint(TRUNCATE)").all()[0];
+  });
+}
+
 function encryptToDisk() {
   if (!encPath) return;
-  // Force WAL checkpoint so the .db file holds all committed transactions.
-  try { runSql(database, "PRAGMA wal_checkpoint(TRUNCATE)"); } catch (_e) { /* best effort */ }
-  if (!nodeFs.existsSync(dbPath)) return;
+  // A read-only open promised not to write db.enc, and this is the one place
+  // that would. The periodic timer, close() and the exit handler all arrive
+  // here, so honouring the promise once covers all three.
+  if (readOnly) return;
+  // The checkpoint that folds committed transactions into the .db file runs
+  // below, beside the read of the file it drains into, so its result is
+  // available where the decision is made. It used to run here and discard that
+  // result, which is how a checkpoint that quietly did nothing could send a
+  // db.enc short of its newest commits and report the flush as successful.
+  // A missing working copy used to return here as though the flush had
+  // succeeded. It never can have: the source of the bytes is gone, so nothing
+  // reaches db.enc, and the caller — the periodic flush, close(), the exit
+  // handler — is told the data is safe. Every symptom of a peer having
+  // unlinked this file was invisible for exactly that reason, and one error
+  // line here would have surfaced all of them at the first flush.
+  //
+  // AFTER close() the same absence is expected and correct: close removes the
+  // working copy on purpose, having flushed first. The handle being gone is
+  // what separates "torn down" from "the file vanished underneath a running
+  // database", and only the second is a loss.
+  if (!database) return;
+  if (!nodeFs.existsSync(dbPath)) {
+    throw new DbError("db/working-copy-missing",
+      "db flush: the encrypted-mode working copy " + dbPath + " no longer exists, so " +
+      "nothing can be written to " + encPath + ". Writes made since the last successful " +
+      "flush are still in this process's open file and are NOT on disk. Another process " +
+      "sharing this tmpDir most likely removed it; give each process its own tmpDir, or " +
+      "run one process per volume.");
+  }
+  // Same reasoning as the missing working copy above, one step later: bytes
+  // that reached db.enc without the log folded in are a volume that decrypts
+  // and opens while missing its newest commits, and the flush would have
+  // reported success. Failing here names it at the first flush instead.
+  var unflushedWal = _walNotDrained(dbPath, true);
+  if (unflushedWal) {
+    throw new DbError("db/flush-pending-wal",
+      "db flush: " + unflushedWal + ". Writing the working copy to " + encPath +
+      " would store a volume that opens cleanly while missing the most recent " +
+      "writes; retry once the writer is idle.");
+  }
   atomicFile.writeSync(encPath, encryptPacked(atomicFile.fdSafeReadSync(dbPath, { maxBytes: C.BYTES.gib(2) }), encKey, _dbEncAad(dataDir)));
 }
 
@@ -984,7 +1184,22 @@ function snapshot() {
   // WAL checkpoint flushes committed transactions into the main DB file
   // so the snapshot reflects the current logical state, not just the
   // pre-WAL pages.
-  try { runSql(database, "PRAGMA wal_checkpoint(TRUNCATE)"); } catch (_e) { /* best effort */ }
+  //
+  // A read-only handle cannot perform one. The attempt used to fail into a
+  // silent catch and the copy went ahead anyway, producing a snapshot missing
+  // exactly the rows the log still held — a backup that restores cleanly and
+  // is short of its most recent writes. Whether the checkpoint ran is now
+  // checked by its result rather than assumed from its absence of an error.
+  var pendingWal = _walNotDrained(dbPath, !readOnly);
+  if (pendingWal) {
+    throw _dbErr("db/snapshot-pending-wal",
+      "snapshot: " + pendingWal + ", so a copy of the database file would be missing " +
+      "the most recent rows while still opening cleanly." +
+      (readOnly
+        ? " Take the snapshot from a handle that can write, or checkpoint the volume " +
+          "before opening it readOnly."
+        : " Retry once the writer is idle."));
+  }
   if (!nodeFs.existsSync(dbPath)) {
     throw _dbErr("db/snapshot-no-source",
       "snapshot: plaintext DB at " + dbPath + " is missing — did init complete?");
@@ -1007,11 +1222,118 @@ function removePlaintextFiles() {
   try { nodeFs.unlinkSync(dbPath); } catch (_e) { /* cleanup */ }
   try { nodeFs.unlinkSync(dbPath + "-wal"); } catch (_e) { /* cleanup */ }
   try { nodeFs.unlinkSync(dbPath + "-shm"); } catch (_e) { /* cleanup */ }
+  // The ownership record goes with the copy it describes. Leaving it would
+  // accumulate one file per open/close cycle forever, and the sweep could
+  // never reclaim them: it enumerates `.db` names, so a sidecar whose working
+  // copy is gone is invisible to it.
+  try { nodeFs.unlinkSync(dbPath + OWNER_SUFFIX); } catch (_e) { /* cleanup */ }
 }
 
-// Clean up stale plaintext DB files left by previously-crashed processes.
-// Anything matching blamejs-*.db that isn't our current process's file is
-// stale (no other process should write to /dev/shm with our prefix).
+// Which PID namespace this process's ids belong to.
+//
+// A process id only means something inside the namespace that issued it. Two
+// containers sharing a tmpDir are each pid 1, and one container probing the
+// other's pid either finds nothing (and would call a running process dead) or
+// finds an unrelated local process (and would call a dead one alive). Recording
+// the namespace alongside the pid makes that comparability testable instead of
+// assumed.
+//
+// Linux exposes it as a symlink whose target names the namespace inode.
+//
+// The fallback is where this gets decided, and it is not one case but two. On a
+// platform with no PID namespaces at all there is no such file to read, every
+// id on the host is comparable, and one shared token is right. On Linux the
+// file is supposed to be there, so failing to read it means /proc is unmounted
+// or the entry is restricted — namespaces may well be in use and we simply
+// cannot see which one we are in. Answering "host" there would tell two
+// containers with a shared tmpDir that each other's pids are comparable, which
+// is precisely the cross-namespace unlink of a LIVE database this record was
+// added to prevent.
+//
+// So that case gets a token unique to this process: no stored record can ever
+// match it, the sweep reclaims nothing, and the cost of not knowing is a leaked
+// working copy rather than someone else's data.
+//
+// Split into a function taking the platform and the reader so that branch can
+// be driven from any host. A rule about what happens when /proc is missing is
+// untestable while reaching it requires unmounting /proc.
+var _opaqueNamespace = null;
+function _namespaceFrom(platform, readlink) {
+  // Only Linux has /proc/self/ns/pid, and asking anywhere else is not a
+  // harmless miss: the leading slash is drive-relative on Windows, so the read
+  // lands on C:\proc\self\ns\pid, which an unprivileged local user can create.
+  // Answering from a planted file would let whoever wrote it name this
+  // process's namespace, and a namespace that matches is exactly what
+  // authorizes unlinking a working copy another process is using. Off Linux
+  // there is one namespace by definition, so the platform answers it.
+  if (platform !== "linux") return "host";
+  try { return String(readlink("/proc/self/ns/pid")); }
+  catch (_e) { /* decided below — /proc is unmounted or restricted */ }
+  if (!_opaqueNamespace) _opaqueNamespace = "unreadable-ns:" + generateToken(16);
+  return _opaqueNamespace;
+}
+
+function _ownerNamespace() {
+  return _namespaceFrom(process.platform, nodeFs.readlinkSync);
+}
+
+// Anchor an audit checkpoint, unless this handle promised not to write.
+//
+// Two places anchor one: boot, so a chain that moved since the last checkpoint
+// gets an anchor, and close(), so the audit.tip sidecar names the final state.
+// They are far apart and shaped differently — one awaited, one fire-and-forget
+// behind a leader check — which is how gating the first left the second live.
+// Routing both through here puts the rule in one place, so a third anchor added
+// later inherits it instead of re-deciding it.
+//
+// The read-only case returns a resolved promise rather than throwing: not
+// anchoring is the correct outcome for that handle, not an error in it.
+function _anchorCheckpoint() {
+  if (readOnly) return Promise.resolve(null);
+  return audit.checkpoint({ skipIfUnchanged: true });
+}
+
+// Is the process that owns a working copy still running?
+//
+//   true   — running, including running but owned by another user.
+//   false  — no such process, in a namespace we can compare against.
+//   null   — no record, an unreadable one, or one from another namespace.
+//
+// The liveness question itself belongs to b.pidProbe, which owns the
+// EPERM-means-alive / ESRCH-means-dead classification. What this adds is the
+// question that has to be answered BEFORE liveness: whether the recorded id is
+// ours to interpret at all. Reading "no such process" from a foreign namespace
+// as "dead owner" would unlink a live database — the exact loss the record was
+// added to prevent.
+function _tmpDbOwnerAlive(workingCopyPath) {
+  var raw;
+  try {
+    raw = atomicFile.fdSafeReadSync(workingCopyPath + OWNER_SUFFIX, {
+      maxBytes: C.BYTES.kib(1), refuseSymlink: true, encoding: "utf8",
+    });
+  } catch (_e) { return null; }                        // no record; owner unknowable
+  // "<namespace> <pid>". A record without both fields predates this format or
+  // was truncated; either way it cannot be compared, so it is left alone.
+  var parts = String(raw).trim().split(" ");
+  if (parts.length !== 2) return null;
+  if (parts[0] !== _ownerNamespace()) return null;     // another namespace's pid
+  var pid = parseInt(parts[1], 10);
+  if (!isFinite(pid) || pid <= 0) return null;
+  return pidProbe.isLivePid(pid);
+}
+
+// Reclaim working copies left behind by processes that are GONE.
+//
+// This used to unlink every `blamejs-*.db` in the directory that was not our
+// own, inferring "stale" from the filename alone. On Linux the unlink succeeds
+// against a file another process holds open, so a peer that was still running
+// kept a working descriptor, saw nothing wrong, and had every later flush
+// silently write nothing — losing its data back to its last flush. Sharing a
+// temporary directory is the normal case for a container, where the documented
+// way to get a shell is to exec into the running image.
+//
+// A name is not evidence of ownership. The owning process id is, so each
+// working copy now carries one and this sweep asks the operating system.
 function cleanStaleTmpDbs(tmpDir) {
   var entries = atomicFile.listDir(tmpDir, {
     filter: function (name) { return name.startsWith("blamejs-") && name.endsWith(".db"); },
@@ -1019,9 +1341,19 @@ function cleanStaleTmpDbs(tmpDir) {
   for (var i = 0; i < entries.length; i++) {
     var full = entries[i].fullPath;
     if (full === dbPath) continue;
+    var alive = _tmpDbOwnerAlive(full);
+    if (alive !== false) {
+      // Alive, or unprovable. A working copy written by a version that kept no
+      // ownership record is in the second group, and so is one whose record we
+      // cannot read. Leaving it costs a file; removing it cost a database.
+      log("leaving working copy " + full +
+          (alive === null ? " (owner unknown)" : " (owner still running)"));
+      continue;
+    }
     try { nodeFs.unlinkSync(full); } catch (_e) { /* concurrent cleanup */ }
     try { nodeFs.unlinkSync(full + "-wal"); } catch (_e) { /* may not exist */ }
     try { nodeFs.unlinkSync(full + "-shm"); } catch (_e) { /* may not exist */ }
+    try { nodeFs.unlinkSync(full + OWNER_SUFFIX); } catch (_e) { /* may not exist */ }
   }
 }
 
@@ -1049,8 +1381,10 @@ function cleanStaleTmpDbs(tmpDir) {
  *   dataDir:                 string,            // required — where db.enc + db.key.enc live
  *   schema:                  Array,             // required — [{ name, columns, indexes, sealedFields, derivedHashes, foreignKeys, primaryKey, subjectField, personalDataCategories }, ...]
  *   atRest:                  "encrypted"|"plain", // default "encrypted"
- *   tmpDir:                  string,            // override the encrypted-mode tmpfs path (default /dev/shm or BLAMEJS_TMPDIR)
- *   allowNonTmpfsTmpDir:     boolean,           // default false — encrypted mode THROWS when tmpDir is not a recognized tmpfs mount (plaintext-on-disk leak); pass true to downgrade to a warning when the mount is verified in-memory out-of-band
+ *   immutable:               boolean,           // default false — requires `readOnly` and `atRest: "plain"`. Declares that NOTHING writes this volume while it is open, so SQLite reads it without creating the `-wal` / `-shm` pair it otherwise needs for a WAL-mode database. That pair is what makes a plain read-only open fail on a read-only mount. Only the operator can make this claim: if a writer is in fact active, the reader's view is undefined rather than merely stale, which is why it is never inferred.
+ *   readOnly:                boolean,           // default false — open without ever writing back. Under `atRest: "encrypted"` two processes sharing one volume each decrypt their own working copy, so whichever flushes last overwrites the other's writes; a reader takes no part in that. SQLite refuses writes too, so a stray one fails where it is issued.
+ *   tmpDir:                  string,            // the encrypted-mode tmpfs path. Defaults to `BLAMEJS_TMPDIR`, then to `/dev/shm` on Linux only — off Linux nothing is inferred and encrypted mode refuses with `db/no-tmpfs` until one of the two names a mount.
+ *   allowNonTmpfsTmpDir:     boolean,           // default false — on Linux, where the mount table can be compared against, encrypted mode THROWS when tmpDir resolves outside the recognized tmpfs mounts (plaintext-on-disk leak); pass true to downgrade that to a warning when the mount is verified in-memory out-of-band. Off Linux the mount cannot be classified, so an operator-named path is always taken with a warning and this option changes nothing.
  *   migrationDir:            string,            // optional — path to ./migrations/ (run-once each)
  *   streamLimit:             number,            // default 1_000_000 — db.stream row ceiling
  *   columnGate:              "reject"|"warn"|"off", // default "reject" — refuse queries on columns not declared in the table schema
@@ -1102,6 +1436,41 @@ async function init(opts) {
     throw new DbError("db/bad-at-rest",
       "db.init: atRest must be 'encrypted' or 'plain', got: " + opts.atRest);
   }
+  // Read-only open. Throw at config-time on a typo rather than letting a
+  // truthy string read as "true" — an operator who meant to open a reader and
+  // instead opened a writer is back in the overwrite this option exists to
+  // avoid.
+  validateOpts.optionalBoolean(opts.readOnly, "db.init: readOnly",
+    DbError, "db/bad-read-only");
+  readOnly = opts.readOnly === true;
+  // `immutable` is the operator declaring that NOTHING writes this volume for
+  // the life of the open — not another process, not another host sharing the
+  // mount. That is a claim only they can make, so it is never inferred.
+  //
+  // It exists because SQLite needs a `-shm` file to read a database whose
+  // header says WAL, and creates one on open even for a reader. On a read-only
+  // mount that fails, which left `readOnly` unusable in exactly the setting it
+  // was built for. Declaring the volume immutable lets SQLite read it with no
+  // sidecars at all.
+  //
+  // Getting the claim wrong is a correctness failure, not an availability one:
+  // a concurrent writer makes the reader's view undefined rather than merely
+  // stale. That asymmetry is why the default stays the safe, sidecar-creating
+  // open, and the fast path is opt-in.
+  validateOpts.optionalBoolean(opts.immutable, "db.init: immutable",
+    DbError, "db/bad-immutable");
+  immutableOpen = opts.immutable === true;
+  if (immutableOpen && !readOnly) {
+    throw new DbError("db/bad-immutable",
+      "db.init: immutable requires readOnly: true — it declares the volume will " +
+      "not change, which says nothing about a handle that may write to it");
+  }
+  if (immutableOpen && atRest !== "plain") {
+    throw new DbError("db/bad-immutable",
+      "db.init: immutable applies to atRest: 'plain', where the volume is the " +
+      "file opened. Under 'encrypted' the handle opens a working copy this " +
+      "process just decrypted, so there is nothing for the operator to declare");
+  }
   // Operator-tunable streamLimit ceiling. Throw at config-time
   // on bad shape so a typo surfaces at boot rather than as an
   // unbounded stream at first export.
@@ -1143,12 +1512,12 @@ async function init(opts) {
     // If the resolved tmpDir is NOT actually tmpfs, the plaintext working
     // copy lives on persistent storage and leaks into backup snapshots,
     // replication, and forensic disk images — defeating the whole point of
-    // encrypted-at-rest mode. On Linux we verify the resolved path lands
-    // under a known in-memory mount (/dev/shm /run/shm /run/user, plus
-    // /tmp which is tmpfs on systemd-default + most container images).
+    // encrypted-at-rest mode. On Linux the resolved path is checked against
+    // the known in-memory mounts (/dev/shm /run/shm /run/user, plus /tmp
+    // which is tmpfs on systemd-default + most container images).
     //
-    // Fail-closed default (v0.15.0): a tmpDir that resolves OUTSIDE those
-    // mounts THROWS db/tmpdir-not-tmpfs at boot rather than logging a
+    // Fail-closed default (v0.15.0): a tmpDir that cannot be shown to be one
+    // of those THROWS db/tmpdir-not-tmpfs at boot rather than logging a
     // warning the operator never reads — the prior warn-only path silently
     // shipped plaintext to disk under the encrypted-mode default. The
     // documented opt-out is opts.allowNonTmpfsTmpDir: true, for the operator
@@ -1156,27 +1525,24 @@ async function init(opts) {
     // a tmpfs bind-mounted at a non-standard path the heuristic can't see)
     // or who has accepted the disk-residency tradeoff. The opt-out downgrades
     // to the prior warning. (Free-space headroom is enforced separately via
-    // fs.statfsSync in the storage guard below.) The heuristic is Linux-only;
-    // other platforms can't be probed by path and emit the warning unchanged.
-    if (process.platform === "linux") {
-      var realTmp = "";
-      try { realTmp = nodeFs.realpathSync(tmpDir); } catch (_e) { /* stat best-effort */ }
-      if (realTmp.indexOf("/dev/shm") !== 0 && realTmp.indexOf("/run/shm") !== 0 &&
-          realTmp.indexOf("/run/user/") !== 0 && realTmp.indexOf("/tmp") !== 0) {
-        var tmpfsMsg = "db.init: tmpDir '" + tmpDir + "' (real: '" + realTmp +
-          "') does not resolve under /dev/shm /run/shm /run/user /tmp — it is not a " +
-          "recognized tmpfs mount. A persistent-disk tmpDir leaks the decrypted " +
-          "working copy into backup snapshots, replication, and forensic disk images.";
-        if (opts.allowNonTmpfsTmpDir === true) {
-          log.warn("WARNING: " + tmpfsMsg + " (allowNonTmpfsTmpDir:true — verify the " +
-            "mount is in-memory out-of-band.)");
-        } else {
-          throw _dbErr("db/tmpdir-not-tmpfs", "FATAL: " + tmpfsMsg +
-            " Mount a tmpfs at the path (or set BLAMEJS_TMPDIR / opts.tmpDir to one), " +
-            "or pass opts.allowNonTmpfsTmpDir: true to accept the disk-residency tradeoff, " +
-            "or pass atRest: 'plain' if encryption-at-rest is not required.");
-        }
+    // fs.statfsSync in the storage guard below.)
+    //
+    // Off Linux the mount cannot be classified at all, so the finding is that
+    // it is unknown, and the operator who named the path is warned rather than
+    // refused. Nothing was emitted there before, which read as approval — and
+    // the comment above this block used to claim a warning was emitted.
+    var residencyIssue = _tmpDirResidencyIssue(tmpDir, process.platform, nodeFs.realpathSync);
+    if (residencyIssue) {
+      if (residencyIssue.determined && opts.allowNonTmpfsTmpDir !== true) {
+        throw _dbErr("db/tmpdir-not-tmpfs", "FATAL: " + residencyIssue.message +
+          " Mount a tmpfs at the path (or set BLAMEJS_TMPDIR / opts.tmpDir to one), " +
+          "or pass opts.allowNonTmpfsTmpDir: true to accept the disk-residency tradeoff, " +
+          "or pass atRest: 'plain' if encryption-at-rest is not required.");
       }
+      log.warn("WARNING: " + residencyIssue.message +
+        (residencyIssue.determined
+          ? " (allowNonTmpfsTmpDir:true — verify the mount is in-memory out-of-band.)"
+          : ""));
     }
 
     // Operator overrides for the encrypted-DB on-disk nodePath. `opts.encryptedDbPath`
@@ -1204,6 +1570,11 @@ async function init(opts) {
       : (typeof nodeFs.statfsSync === "function" ? nodeFs.statfsSync : null);
 
     cleanStaleTmpDbs(tmpDir);
+    // Claim this working copy BEFORE any bytes go into it, so a peer booting
+    // concurrently sees an owner rather than an unattributed file. Written
+    // with atomicFile so a peer never reads a half-written process id.
+    atomicFile.writeSync(dbPath + OWNER_SUFFIX,
+      Buffer.from(_ownerNamespace() + " " + process.pid.toString(10), "utf8"));
     decryptToTmp();
   } else {
     // plain mode
@@ -1225,21 +1596,78 @@ async function init(opts) {
   // Node 24.10+, comfortably under the engines floor. (SQLITE_LIMIT_ATTACHED is
   // left at the SQLite default — the snapshot / backup path relies on the
   // attach mechanism.)
-  database = new DatabaseSync(dbPath, {
+  // Being told the bytes cannot change, SQLite stops consulting the -wal
+  // sidecar entirely. That is the point — it is what removes the need to create
+  // one — but it means a volume carrying committed transactions ONLY in its WAL
+  // would be read without them.
+  //
+  // A clean close removes the -wal. One left behind with bytes in it is a
+  // writer that crashed, or a volume captured mid-write, and either way the
+  // most recent commits live only there. Reading past it would not return a
+  // stale database, which is the tradeoff `immutable` asks the operator to
+  // accept; it would return a partial one that looks whole, and the rows that
+  // went missing would be the newest.
+  //
+  // So refuse. Replaying the WAL requires a writable open, which is exactly
+  // what the operator has said they cannot do here — and guessing on their
+  // behalf is what this whole option exists to avoid.
+  if (immutableOpen) {
+    // No handle is open yet, and this one could not checkpoint if it were, so
+    // the log can only be reported on rather than resolved.
+    var walIssue = _walNotDrained(dbPath, false);
+    if (walIssue) {
+      throw _dbErr("db/immutable-pending-wal",
+        "db.init: immutable was requested but " + walIssue + ". An immutable open does " +
+        "not read the write-ahead log, so any transaction committed only there would be " +
+        "silently missing. Open the volume once writable to checkpoint and remove the " +
+        "log, or drop immutable and open it read-only on a mount that permits the " +
+        "-wal / -shm pair.");
+    }
+  }
+
+  // A declared-immutable volume is opened through a file: URI so SQLite is told
+  // the bytes cannot change and reads it without a -wal / -shm pair. The URI is
+  // built with pathToFileURL rather than by concatenation: a dataDir with a
+  // space or a parenthesis in it is ordinary, and both need percent-encoding
+  // before SQLite will parse the path back out.
+  var openTarget = immutableOpen
+    ? nodeUrl.pathToFileURL(dbPath).href + "?immutable=1"
+    : dbPath;
+  database = new DatabaseSync(openTarget, {
+    // Enforced by SQLite as well as by the flush skip, so a write under a
+    // read-only open fails where it is issued rather than succeeding into a
+    // working copy nobody will ever persist.
+    readOnly: readOnly,
     limits: {
       sqlLength: C.BYTES.mib(1),
     },
   });
   _dbGenerationCounter++;   // a new live handle — see dbGeneration()
 
-  // Performance pragmas
-  runSql(database, "PRAGMA journal_mode=WAL");
+  // Performance pragmas.
+  //
+  // Two of these change the DATABASE, not the connection: journal_mode rewrites
+  // the file header and brings a `-wal` sidecar into existence beside it, and
+  // auto_vacuum rewrites the header too. A read-only open must issue neither.
+  // Under `atRest: "encrypted"` that was invisible, because the handle is
+  // opened against a decrypted working copy in tmpfs, which is writable
+  // whatever the volume is mounted as. In plain mode the file IS the volume, so
+  // a reader pointed at a read-only mount failed on the first pragma — the mode
+  // a reader exists for was the one it could not be used in.
+  //
+  // The rest are connection settings. They configure this handle and touch
+  // nothing on disk, so a reader keeps them: cache and mmap sizing matter as
+  // much for reading, and foreign_keys / secure_delete describe writes that a
+  // read-only handle will not be making anyway.
+  if (!readOnly) {
+    runSql(database, "PRAGMA journal_mode=WAL");
+    runSql(database, "PRAGMA auto_vacuum=INCREMENTAL");
+  }
   runSql(database, "PRAGMA synchronous=NORMAL");
   runSql(database, "PRAGMA cache_size=-8000");
   runSql(database, "PRAGMA temp_store=MEMORY");
   runSql(database, "PRAGMA busy_timeout=5000");
   runSql(database, "PRAGMA mmap_size=268435456");
-  runSql(database, "PRAGMA auto_vacuum=INCREMENTAL");
   // Foreign-key enforcement is OFF by default in SQLite. Turn it ON so
   // structured `foreignKeys` declarations actually constrain writes.
   runSql(database, "PRAGMA foreign_keys=ON");
@@ -1595,6 +2023,11 @@ async function init(opts) {
       dataDir:   dataDir,
       mode:      auditSigningMode,
       algorithm: auditSigningAlg || undefined,
+      // A reader verifies with the key the volume already has; it never
+      // establishes one. Without this the signing bootstrap generated a
+      // keypair, wrote it under dataDir and swept orphaned temp files, which
+      // fails an open on a read-only mount and quietly modifies a writable one.
+      readOnly:  readOnly,
     });
   }
 
@@ -1616,7 +2049,15 @@ async function init(opts) {
 
     // Anchor a fresh checkpoint at boot if there's any new audit
     // activity since the last checkpoint (else no-op).
-    await audit.checkpoint({ skipIfUnchanged: true });
+    //
+    // A read-only open anchors nothing. `skipIfUnchanged` skips the write only
+    // when the chain has not moved, and the state a reader most wants to
+    // inspect is the opposite one: a volume left by a crash, with audit rows
+    // newer than its last checkpoint. There the insert is attempted and the
+    // read-only handle refuses it, so the advertised reader could not open
+    // precisely the snapshots it exists for. The signature verification above
+    // still runs — checkpoints are VERIFIED here, only creating one is skipped.
+    await _anchorCheckpoint();
   }
 
   // ---- NTP drift check ----
@@ -1624,13 +2065,18 @@ async function init(opts) {
   // (unless BLAMEJS_NTP_STRICT=0 / BLAMEJS_SKIP_NTP_CHECK=1).
   await _runNtpBootCheck(opts);
 
-  // Start periodic encrypt timer (encrypted mode only)
+  // Start periodic encrypt timer (encrypted mode only). A read-only open has
+  // nothing to flush, so it never arms one — encryptToDisk would return
+  // immediately, and a timer whose every firing is a no-op is a handle held
+  // open for nothing.
   if (atRest === "encrypted") {
-    encTimer = safeAsync.repeating(function () {
-      try { encryptToDisk(); } catch (e) {
-        log.error("periodic encrypt failed: " + e.message);
-      }
-    }, C.TIME.minutes(5), { name: "db-periodic-encrypt" });
+    if (!readOnly) {
+      encTimer = safeAsync.repeating(function () {
+        try { encryptToDisk(); } catch (e) {
+          log.error("periodic encrypt failed: " + e.message);
+        }
+      }, C.TIME.minutes(5), { name: "db-periodic-encrypt" });
+    }
 
     // Tmpfs free-space guard. Install the growth-write gate now (after all
     // of init's own writes), then probe on a short interval so the
@@ -2403,7 +2849,7 @@ function close() {
     // await it across the test/shutdown lifecycle. Operators who need
     // a guaranteed-flushed checkpoint should call audit.checkpoint()
     // explicitly before invoking close().
-    audit.checkpoint({ skipIfUnchanged: true }).catch(function (e) {
+    _anchorCheckpoint().catch(function (e) {
       log.error("close: final checkpoint failed: " + e.message);
     });
   }
@@ -2952,6 +3398,8 @@ function _resetForTest() {
   encPath = null;
   encKey = null;
   atRest = null;
+  readOnly = false;
+  immutableOpen = false;
   dataDir = null;
   minFreeBytes = 0;
   statfsProbe = null;
@@ -3379,6 +3827,14 @@ function getActivePosture() { return _activePosture; }
 
 module.exports = {
   init:                init,
+  // Test hook: the namespace token this process stamps into an ownership
+  // record, so a test writes the same format the sweep reads instead of
+  // hard-coding one that can drift from it.
+  _ownerNamespaceForTest: _ownerNamespace,
+  _namespaceFromForTest:  _namespaceFrom,
+  _resolveTmpDirFromForTest:    _resolveTmpDirFrom,
+  _tmpDirResidencyIssueForTest: _tmpDirResidencyIssue,
+  _walNotDrainedFromForTest:    _walNotDrainedFrom,
   _dbGeneration:       dbGeneration,
   applyPosture:        applyPosture,
   getActivePosture:    getActivePosture,