create-walle 0.10.0 → 0.10.2

package/template/shared/sqlite-write-lock.js

@@ -1,5 +1,25 @@
 'use strict';
 
+// Write-lock protocol 2 — the EXCLUSION primitive is a kernel lock, not a file.
+//
+// A write hold is `BEGIN EXCLUSIVE` on `<db>.write-lock.mutex`, a SQLite database
+// that is NEVER written (no table, no pragma that writes, rollback journal — never
+// WAL). SQLite's own fcntl locks are the exclusion, so a SIGKILLed holder's lock is
+// released by the OS and no age-based stealing is needed or allowed. Nothing else in
+// the process may open that .mutex path: POSIX advisory locks are per-process, so an
+// unrelated open()+close() on the same file silently drops the holder's lock (D-6,
+// enforced by bin/lint-shared-copy-parity.js). Holder identity is a fixed 1,024-byte
+// space-padded JSON record at the old claim path, pwritten in place at offset 0
+// through an fd kept open for the life of the handle (D-3). The fd is opened
+// O_RDWR | O_CREAT — never 'a+': on Linux pwrite(2) ignores the offset on an
+// O_APPEND fd and appends, so the record would grow by 1 KiB per acquire (§1.2).
+//
+// The identity record persists after release, so a reader sees "the last writer",
+// not "a write is in flight". `_fence` re-checks the path after every kernel-lock
+// acquire, because a v1 process (or a boot sweep) can replace the record's inode
+// under a live v2 holder (D-8b); a v1 claim found at the path is honored while its
+// pid is alive and reaped once when it is not (D-8c).
+
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
@@ -9,10 +29,15 @@ const { isMainThread, threadId } = require('node:worker_threads');
 const WRITE_SQL_RE = /^\s*(?:INSERT|UPDATE|DELETE|REPLACE|CREATE|ALTER|DROP|VACUUM|REINDEX|ANALYZE|ATTACH|DETACH|BEGIN|COMMIT|ROLLBACK)\b/i;
 const WRITE_PRAGMA_RE = /^\s*(?:journal_mode|wal_checkpoint|user_version|foreign_keys|synchronous|locking_mode|auto_vacuum|optimize)\b/i;
 const DEFAULT_TIMEOUT_MS = 0;
-const DEFAULT_STALE_MS = 10 * 60 * 1000;
 const DEFAULT_POLL_MS = 25;
-const DEFAULT_CLAIM_STALE_MS = 1000;
-const DEFAULT_STALE_RECOVERY_TIMEOUT_MS = 5000;
+// D-1e: the lock DB is `<db>.write-lock.mutex`, NOT `<db>.write-lock.db` — code that
+// enumerates *.db in a data dir (production-update.js, both test template copiers)
+// would otherwise open and checkpoint the lock file as if it were a database.
+const LOCK_DB_SUFFIX = '.mutex';
+// D-3: the identity record is exactly this many bytes, written in place at offset 0.
+const IDENTITY_RECORD_BYTES = 1024;
+// D-8: the marker that distinguishes a v2 record from a pre-WP-1 claim.
+const LOCK_PROTOCOL = 2;
 // R3 (round-2 WP-0, §6.2): a foreign (not-this-pid) hold at or beyond this age gets
 // exactly one incident-log record + /healthz.write_lock projection. A CONSTANT, not
 // an env flag (F-4) — tests inject a smaller value via opts.foreignHoldIncidentMs.
@@ -33,6 +58,9 @@ const MAIN_THREAD_WRITE_ALLOWANCE_POLICIES = Object.freeze({
 const globalState = globalThis[GLOBAL_STATE_KEY] || (globalThis[GLOBAL_STATE_KEY] = {
   token: `${process.pid}:${threadId}:${crypto.randomBytes(8).toString('hex')}`,
   locks: new Map(),
+  // D-7: per-thread, strongly referenced lock handles, keyed by canonical lock path.
+  // IndexedDB-style handles ({ db, begin, commit, identityFd, ... }) — see _lockHandle.
+  lockDbs: new Map(),
   mainWriteEnforcement: false,
   mainWriteAllowanceStorage: new AsyncLocalStorage(),
   mainWriteInventory: new Set(),
@@ -53,6 +81,7 @@ if (!(globalState.mainWriteInventory instanceof Set)) globalState.mainWriteInven
 if (!(globalState.mainWriteEscapeLastAt instanceof Map)) globalState.mainWriteEscapeLastAt = new Map();
 if (!(globalState.mainWriteEscapeBySite instanceof Map)) globalState.mainWriteEscapeBySite = new Map();
 if (!Number.isFinite(globalState.mainWriteEscapeCount)) globalState.mainWriteEscapeCount = 0;
+if (!(globalState.lockDbs instanceof Map)) globalState.lockDbs = new Map();
 if (!(globalState.mainWriteAllowanceStorage instanceof AsyncLocalStorage)) {
   globalState.mainWriteAllowanceStorage = new AsyncLocalStorage();
 }
@@ -215,37 +244,21 @@ function _pidAlive(pid) {
   }
 }
 
-function _readLock(lockPath) {
+// D-3: the holder record, read off disk. null covers ENOENT, an unreadable record and
+// a torn read (a v2 holder pwrites in place, so a concurrent reader can observe a
+// half-updated buffer) — every one of those means "no usable identity", never "throw".
+function _readIdentity(lockPath) {
   try {
     return JSON.parse(fs.readFileSync(lockPath, 'utf8'));
   } catch {
+    /* expected: ENOENT (no record yet), EISDIR (a directory sits at the path) and a
+       torn read of a v2 in-place write all mean "no identity readable right now" —
+       the caller decides via the error code, and a thief that cannot be identified
+       must never be granted the lock. */
     return null;
   }
 }
 
-function _inspectLock(lockPath) {
-  let stat = null;
-  try {
-    stat = fs.statSync(lockPath);
-  } catch (error) {
-    if (error?.code === 'ENOENT') return { exists: false, stat: null, raw: '', info: null, parseError: null };
-    return { exists: true, stat: null, raw: '', info: null, parseError: error };
-  }
-
-  let raw = '';
-  try {
-    raw = fs.readFileSync(lockPath, 'utf8');
-    try {
-      return { exists: true, stat, raw, info: JSON.parse(raw), parseError: null };
-    } catch (parseError) {
-      return { exists: true, stat, raw, info: null, parseError };
-    }
-  } catch (error) {
-    if (error?.code === 'ENOENT') return { exists: false, stat: null, raw: '', info: null, parseError: null };
-    return { exists: true, stat, raw, info: null, parseError: error };
-  }
-}
-
 // Canonical path is stable for the process lifetime (the parent directory's symlink
 // chain doesn't change), so cache it. _acquire runs this on every write — without the
 // cache it pays a realpathSync.native syscall per write, which is pure overhead on the
@@ -283,83 +296,222 @@ function _canonicalLockPath(lockPath) {
   return result;
 }
 
-function _releaseLockFile(lockPath, token) {
+// D-7: the per-thread lock handle. Created lazily, once per canonical lock path, and
+// kept strongly referenced in globalState.lockDbs — an unreachable holder connection
+// is garbage-collected and its lock silently released, which is exactly the failure
+// this map exists to rule out.
+//
+// The kernel lock and the identity fd are opened on FIRST ACQUIRE (`_openLockResources`),
+// not here, because installSqliteWriteLock calls this for every wrapped connection —
+// including the no-op stubs the boot-sweep tests install — and opening/creating files
+// at install time would both break those tests and leave a record for a database that
+// was never written. `refs` (D-7b) is therefore live from install onward.
+function _lockHandle(lockPath, canonical, opts) {
+  const existing = globalState.lockDbs.get(canonical);
+  if (existing) return existing;
+  if (typeof opts.Database !== 'function') {
+    throw new TypeError('createSqliteWriteLock: opts.Database is required');
+  }
+  const handle = {
+    Database: opts.Database,
+    db: null,           // D-1: opened on first acquire, from opts.Database (D-5)
+    begin: null,
+    commit: null,
+    identityFd: null,   // D-3: O_RDWR|O_CREAT fd on lockPath, never 'a+'
+    identityIno: 0,
+    acquireSeq: 0,      // ++ per acquire → the token suffix
+    refs: 0,            // wrapped connections currently open on this lock path (D-7b)
+    refsWarned: false,
+  };
+  globalState.lockDbs.set(canonical, handle);
+  return handle;
+}
+
+// D-3/D-8c: the identity fd. Created with O_EXCL so "we made this record file" is a fact, and
+// creating it is a race we can lose but never a steal: EEXIST means something is already at the
+// path — a v2 record from a previous holder (which _fence adopts; D-3 deliberately keeps the
+// record after release) or a pre-WP-1 claim (which _fence leaves alone and reports busy while
+// its holder lives). An unopenable object at the path (EISDIR: a directory, the fixture the
+// fail-fast tests use) is the same "somebody else's claim" case. Both leave identityFd null, so
+// _fence classifies whatever is there on every acquire it takes. Never O_APPEND (§1.2).
+function _openIdentityFd(handle, lockPath) {
   try {
-    const info = _readLock(lockPath);
-    if (info?.token === token) fs.unlinkSync(lockPath);
-  } catch {}
+    const fd = fs.openSync(lockPath, fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+    handle.identityFd = fd;
+    handle.identityIno = fs.fstatSync(fd).ino;
+    return;
+  } catch (error) {
+    if (error?.code !== 'EEXIST' && error?.code !== 'EISDIR') throw error;
+    handle.identityFd = null;
+    handle.identityIno = -1;
+  }
 }
 
-function _lockAgeMs(inspected, now = Date.now()) {
-  const createdAt = Number(inspected?.info?.created_at_ms || 0);
-  const basis = createdAt || Number(inspected?.stat?.mtimeMs || 0);
-  if (!basis) return Number.POSITIVE_INFINITY;
-  return Math.max(0, now - basis);
+function _openLockResources(handle, lockPath) {
+  if (handle.db) return handle;
+  // D-5: the constructor of the connection being wrapped, never a fresh require — a
+  // second copy of the SQLite library in one process breaks its in-process lock table.
+  handle.db = new handle.Database(`${lockPath}${LOCK_DB_SUFFIX}`, { timeout: 0 });
+  handle.begin = handle.db.prepare('BEGIN EXCLUSIVE');
+  handle.commit = handle.db.prepare('COMMIT');
+  _openIdentityFd(handle, lockPath);
+  return handle;
 }
 
-function _lockUnchanged(a, b) {
-  if (!a?.exists || !b?.exists) return false;
-  if (a.info?.token || b.info?.token) return a.info?.token && a.info.token === b.info?.token;
-  if (!a.stat || !b.stat) return false;
-  if (a.raw || b.raw) return a.raw === b.raw && a.stat.size === b.stat.size && Math.abs(a.stat.mtimeMs - b.stat.mtimeMs) < 1;
-  return a.stat.dev === b.stat.dev &&
-    a.stat.ino === b.stat.ino &&
-    a.stat.size === b.stat.size &&
-    Math.abs(a.stat.mtimeMs - b.stat.mtimeMs) < 1 &&
-    Math.abs(a.stat.ctimeMs - b.stat.ctimeMs) < 1;
+function _retainHandle(handle) {
+  handle.refs += 1;
 }
 
-function _unlinkIfUnchanged(lockPath, observed) {
-  const current = _inspectLock(lockPath);
-  if (!current.exists) return true;
-  if (!_lockUnchanged(observed, current)) return false;
+// D-7b: the handle is released with the LAST wrapped connection, because every test
+// file (and every db.close()/reopen) would otherwise leak two fds and one SQLite
+// connection per database. Closing the lock DB through SQLite while another thread's
+// connection holds the lock is safe — the unix VFS works around POSIX advisory locking
+// quirks (How To Corrupt §2.2).
+function _releaseHandle(canonical) {
+  const handle = globalState.lockDbs.get(canonical);
+  if (!handle) return false;
+  handle.refs = Math.max(0, handle.refs - 1);
+  if (handle.refs > 0) return false;
+  if (handle.db && handle.db.inTransaction) {
+    // A close() while a hold is still open is a caller bug. Dropping the handle here
+    // would release a lock somebody still believes they hold; keep it and say so once.
+    if (!handle.refsWarned) {
+      handle.refsWarned = true;
+      try {
+        console.warn(`[sqlite-write-lock] close() with an open write-lock hold; keeping the lock handle: ${canonical}`);
+      } catch {
+        /* expected: console.warn on a torn-down stdio (worker exiting) must not turn a
+           caller's close() bug into a different, less legible failure. */
+      }
+    }
+    return false;
+  }
+  globalState.lockDbs.delete(canonical);
+  _closeHandleResources(handle);
+  return true;
+}
+
+function _closeHandleResources(handle) {
+  if (handle.db) {
+    try { handle.db.close(); } catch {
+      /* expected: the lock DB may already be closed by closeSqliteWriteLocksForTests or
+         by an earlier teardown in the same test; the identity fd below is the part
+         that must not be forgotten, and it is closed unconditionally. */
+    }
+    handle.db = null;
+  }
+  if (handle.identityFd !== null) {
+    try { fs.closeSync(handle.identityFd); } catch {
+      /* expected: an fd already closed (EBADF) or a double release is not an error —
+         the handle is being torn down either way. */
+    }
+    handle.identityFd = null;
+  }
+}
+
+// D-8b: adopt the record file at lockPath — either because it went missing (recreate
+// with O_EXCL, so exactly one process wins the race) or because the inode under us was
+// replaced (reopen the existing file). Returns false when another process won the
+// O_EXCL race or removed the path first; the acquire loop then re-fences.
+function _adoptIdentity(handle, lockPath, flags) {
+  let fd;
   try {
-    fs.unlinkSync(lockPath);
-    return true;
+    fd = fs.openSync(lockPath, flags, 0o600);
   } catch (error) {
-    return error?.code === 'ENOENT';
+    if (error?.code === 'EEXIST' || error?.code === 'ENOENT') return false;
+    throw error;
+  }
+  try { fs.closeSync(handle.identityFd); } catch {
+    /* expected: the old fd is a plain fd on the record file (not the lock DB) and may already
+       be closed if a previous adopt lost a race, or be null when the first open found somebody
+       else's object at the path (EEXIST/EISDIR) — the new fd is what matters either way. */
+  }
+  handle.identityFd = fd;
+  handle.identityIno = fs.fstatSync(fd).ino;
+  return true;
+}
+
+// D-1d: a failed BEGIN EXCLUSIVE needs no cleanup — but if the connection is somehow
+// inside a transaction anyway, the state is not one this module understands: roll back
+// and fail loudly rather than loop forever against it.
+function _tryKernelLock(handle) {
+  try {
+    handle.begin.run();
+    return true;
+  } catch (e) {
+    if (handle.db.inTransaction) {
+      handle.db.prepare('ROLLBACK').run();
+      throw Object.assign(new Error('write-lock DB left in a transaction'), { code: 'SQLITE_WRITE_LOCK_STATE' });
+    }
+    if (e.code === 'SQLITE_BUSY') return false;
+    throw e;
+  }
+}
+
+// D-8: what is at the lock path? 'v2' — our record (possibly a torn read of an
+// in-place write, or empty); 'v1-live' — a pre-WP-1 claim whose holder is alive, or
+// anything unparseable that is not a torn v2 record; 'v1-dead' — a v1 claim whose
+// holder is provably gone (the single cutover-only reason this module removes a path).
+function _classifyRecord(lockPath, st) {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(lockPath, 'utf8');
+  } catch {
+    /* expected: the path can vanish between the fence's statSync and this read; an
+       unreadable record is classified as a live foreign claim below, never as ours. */
   }
+  if (st.size === 0) return 'v2';
+  let info;
+  try {
+    info = JSON.parse(raw);
+  } catch {
+    return st.size === IDENTITY_RECORD_BYTES ? 'v2' : 'v1-live';
+  }
+  if (info && info.protocol === LOCK_PROTOCOL) return 'v2';
+  // v1 writes a complete record before linkSync (sqlite-write-lock-v1.js:381-383), so a
+  // v1 claim is never empty or torn — anything else with a dead pid is reapable.
+  return _pidAlive(info && info.pid) ? 'v1-live' : 'v1-dead';
 }
 
-function _staleReason(inspected, staleMs, claimStaleMs, now = Date.now()) {
-  if (!inspected?.exists) return 'missing';
-  const ageMs = _lockAgeMs(inspected, now);
-  if (!inspected.info) {
-    return ageMs > claimStaleMs ? 'orphaned-claim' : '';
+// D-8b/D-8c: runs only after the kernel lock is held. The inode can change under a live
+// holder (a v1 steal, a boot sweep, another process's adopt), and the first draft's
+// "different inode ⇒ busy" would then spin this process busy until it restarted.
+function _fence(handle, lockPath) {
+  let st;
+  try {
+    st = fs.statSync(lockPath);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    st = null;
   }
-  if (ageMs > staleMs) return 'expired';
-  const info = inspected.info;
-  // Holder identity is pid + a per-process-launch token (already written by
-  // _writeLockClaim). Old-format records (no token) fall straight through to the
-  // pid-only liveness check below — unchanged behavior, fully backward compatible.
-  //
-  // A recycled pid can make `_pidAlive(pid)` return true for a lock a DIFFERENT,
-  // now-dead process wrote (the OS handed that same pid to an unrelated live
-  // process). We can only DISPROVE this cheaply — with zero extra syscalls — in
-  // one specific case: when the recorded pid is OUR OWN pid. If it is, and the
-  // token doesn't match our own launch token, the record cannot possibly be ours:
-  // the OS just recycled this exact pid onto us after the original holder (some
-  // earlier, now-dead process) crashed while holding the lock. That's provable
-  // with no OS calls at all, so treat it as a dead owner immediately. Proving
-  // recycling for any OTHER pid would need a real cross-process start-time check
-  // (e.g. `ps -o lstart`), which is too expensive to pay on this hot path; those
-  // cases fall back to a plain liveness check and are still bounded by the
-  // `staleMs` ceiling above if the lock is genuinely abandoned.
-  // IMPORTANT: tokens are per-THREAD (`pid:threadId:rand`, and globalState
-  // lives on the per-thread globalThis), so "same pid, different token" is NOT
-  // proof of a dead owner by itself — a live sibling worker_thread of THIS
-  // process has our pid and a different token. Only when the record claims our
-  // exact pid AND threadId with a different launch-random is it provably from
-  // a previous (dead) process that our pid was recycled from.
-  if (
-    info.pid === process.pid
-    && typeof info.token === 'string'
-    && info.token !== globalState.token
-    && info.token.startsWith(`${process.pid}:${threadId}:`)
-  ) {
-    return 'dead-owner';
+  if (st === null) {
+    return _adoptIdentity(handle, lockPath, fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL) ? 'ok' : 'busy';
+  }
+  if (st.ino === handle.identityIno) return 'ok';
+  if (st.isDirectory()) return 'busy';
+  switch (_classifyRecord(lockPath, st)) {
+    case 'v2':
+      return _adoptIdentity(handle, lockPath, fs.constants.O_RDWR) ? 'ok' : 'busy';
+    case 'v1-dead':
+      try {
+        fs.unlinkSync(lockPath);
+      } catch {
+        /* expected: another process may reap the same dead v1 claim first (ENOENT), or
+           the path may have been replaced (a directory) — either way the next loop
+           iteration re-fences and the outcome is decided there. */
+      }
+      return _adoptIdentity(handle, lockPath, fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL) ? 'ok' : 'busy';
+    default:
+      return 'busy';
   }
-  return _pidAlive(info.pid) ? '' : 'dead-owner';
+}
+
+// D-3: one in-place 1,024-byte write at offset 0 on the fd adopted above. No close, no
+// fsync, no unlink — release does not touch the record.
+function _writeIdentity(handle, info) {
+  const buf = Buffer.alloc(IDENTITY_RECORD_BYTES, 0x20);
+  buf.write(JSON.stringify({ protocol: LOCK_PROTOCOL, ...info }));
+  fs.writeSync(handle.identityFd, buf, 0, buf.length, 0);
 }
 
 // Pure deadline-slicing helper shared by every wait branch in the acquire loop:
@@ -374,31 +526,6 @@ function _remainingWaitMs(deadline, sliceMs, now = Date.now()) {
   return Math.min(sliceMs, remaining);
 }
 
-function _writeLockClaim(lockPath, payload) {
-  const dir = path.dirname(lockPath);
-  const base = path.basename(lockPath);
-  const tempPath = path.join(dir, `.${base}.${process.pid}.${threadId}.${Date.now()}.${crypto.randomBytes(4).toString('hex')}.tmp`);
-  const text = JSON.stringify(payload);
-  try {
-    fs.writeFileSync(tempPath, text, { flag: 'wx', mode: 0o600 });
-    fs.linkSync(tempPath, lockPath);
-  } catch (error) {
-    if (error?.code !== 'EEXIST' && ['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'EXDEV'].includes(error?.code)) {
-      let fd = null;
-      try {
-        fd = fs.openSync(lockPath, 'wx', 0o600);
-        fs.writeFileSync(fd, text);
-        return;
-      } finally {
-        try { if (fd !== null) fs.closeSync(fd); } catch {}
-      }
-    }
-    throw error;
-  } finally {
-    try { fs.unlinkSync(tempPath); } catch {}
-  }
-}
-
 function _durationMs(value, fallback, min = 0) {
   const n = Number(value);
   return Number.isFinite(n) ? Math.max(min, Math.trunc(n)) : fallback;
@@ -584,23 +711,14 @@ function _resetWriteLockForeignHoldForTests(store = globalState) {
 
 function _acquire(lockPath, opts = {}) {
   const timeoutMs = _durationMs(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 0);
-  const staleMs = _durationMs(opts.staleMs ?? DEFAULT_STALE_MS, DEFAULT_STALE_MS, 1000);
   // Floor of 1ms (not 5) so a background writer can poll tightly and reliably win
   // the lock in the brief window after the main thread releases — the main thread
   // can never wait, so the worker winning fast is how we avoid starving it.
   const pollMs = _durationMs(opts.pollMs ?? DEFAULT_POLL_MS, DEFAULT_POLL_MS, 1);
-  const claimStaleMs = _durationMs(opts.claimStaleMs ?? DEFAULT_CLAIM_STALE_MS, DEFAULT_CLAIM_STALE_MS, 1);
-  const staleRecoveryTimeoutMs = _durationMs(
-    opts.staleRecoveryTimeoutMs ?? DEFAULT_STALE_RECOVERY_TIMEOUT_MS,
-    DEFAULT_STALE_RECOVERY_TIMEOUT_MS,
-    0
-  );
   const { now = Date.now, sleepSync = _sleepSync } = opts;
   const startedAt = now();
   const deadline = startedAt + timeoutMs;
-  const dir = path.dirname(lockPath);
   const canonical = _canonicalLockPath(lockPath);
-  let staleRecoveryDeadline = 0;
   let contended = false;
   const held = globalState.locks.get(canonical);
   if (held) {
@@ -610,94 +728,82 @@ function _acquire(lockPath, opts = {}) {
       contended: false,
       release: () => {
         held.depth -= 1;
-        if (held.depth <= 0) {
-          globalState.locks.delete(canonical);
-          _releaseLockFile(held.lockPath, held.token);
-        }
       },
     };
   }
 
-  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  const handle = _lockHandle(lockPath, canonical, opts);
+  // v1 parity (sqlite-write-lock-v1.js:621): a cached handle can outlive the directory it was
+  // created in — coding-task-manager/db.js keeps its per-domain opens by name across initDb()
+  // calls — and the identity open below would then fail ENOENT and report a busy lock that names
+  // nobody. mkdir on a directory that exists writes nothing, so the steady state is unchanged.
+  try {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  } catch {
+    /* expected: a directory that cannot be created (EACCES/ENOTDIR/a removed temp root) is not a
+       lock verdict — the identity open below reports the real error, and a live foreign holder is
+       still attributed by the fence. */
+  }
+  _openLockResources(handle, lockPath);
 
   while (true) {
-    try {
-      const token = globalState.token;
-      // R3 (round-2 WP-0, §6.2): identity fields on the holder record — role/argv0/
-      // purpose let a contended waiter (and /healthz) attribute WHO holds the lock,
-      // not just that it's busy. acquiredAt mirrors created_at_ms (kept for
-      // _lockAgeMs/_staleReason, which are untouched) under the spec's field name.
-      const claimedAtMs = now();
-      _writeLockClaim(lockPath, {
-        pid: process.pid,
-        thread_id: threadId,
-        token,
-        created_at_ms: claimedAtMs,
-        acquiredAt: claimedAtMs,
-        // WALL_E_PROCESS_ROLE (not CTM_PROCESS_ROLE — the §6.2 spec text names the
-        // latter, but that's CTM's own foreign-owner marker, always unset for wall-e's
-        // OWN daemon/workers; WALL_E_PROCESS_ROLE is the identity every legitimate
-        // wall-e opener actually sets — see lib/live-data-role-guard.js's enumeration.
-        // Also avoids a NEW raw CTM_* env read here, which the flag-read ratchet forbids).
-        role: opts.role || process.env.WALL_E_PROCESS_ROLE || 'unknown',
-        argv0: opts.argv0 || path.basename(process.argv[1] || ''),
-        purpose: String(opts.purpose || opts.label || '').slice(0, 80),
-        label: opts.label || '',
-      });
-      const entry = { depth: 1, lockPath, token };
-      globalState.locks.set(canonical, entry);
-      return {
-        waitedMs: now() - startedAt,
-        contended,
-        release: () => {
-          entry.depth -= 1;
-          if (entry.depth > 0) return;
-          globalState.locks.delete(canonical);
-          _releaseLockFile(lockPath, token);
-        },
-      };
-    } catch (err) {
-      if (err?.code !== 'EEXIST') throw err;
-      contended = true;
-      const observed = _inspectLock(lockPath);
-      // R3 (round-2 WP-0, §6.2): a FOREIGN (not-this-pid) holder at/beyond the
-      // incident threshold gets exactly one incident record + /healthz projection,
-      // independent of staleness (a live foreign hold is never "stale" by the
-      // 10-minute ceiling below, but 30s is already an incident-worthy hold).
-      if (observed?.info && observed.info.pid !== process.pid) {
-        _maybeRecordForeignHold(observed, opts);
-      }
-      const staleReason = _staleReason(observed, staleMs, claimStaleMs, now());
-      if (staleReason) {
-        if (_unlinkIfUnchanged(lockPath, observed)) continue;
-        if (!staleRecoveryDeadline) staleRecoveryDeadline = now() + staleRecoveryTimeoutMs;
-        if (now() < staleRecoveryDeadline) {
-          // Was: unconditional `_sleepSync(pollMs)`, ignoring the CALLER's deadline —
-          // a 0ms caller could be dragged through the full staleRecoveryTimeoutMs
-          // (default 5000ms) when the stale lock couldn't be unlinked (it changed
-          // under us). _remainingWaitMs makes the caller's deadline always win.
-          const wait = _remainingWaitMs(deadline, pollMs, now());
-          if (wait < 0) throw _lockBusyError(lockPath, observed.info);
-          sleepSync(wait);
-          continue;
-        }
-      } else if (!observed.info) {
-        // Was: unconditional `_sleepSync(waitMs)` here too — same bypass for a
-        // still-forming (orphaned) claim.
-        const slice = Math.min(pollMs, Math.max(1, claimStaleMs - _lockAgeMs(observed, now())));
-        const wait = _remainingWaitMs(deadline, slice, now());
-        if (wait < 0) throw _lockBusyError(lockPath, observed.info);
-        sleepSync(wait);
-        continue;
-      } else {
-        staleRecoveryDeadline = 0;
-      }
-      {
-        const wait = _remainingWaitMs(deadline, pollMs, now());
-        if (wait < 0) throw _lockBusyError(lockPath, observed.info);
-        sleepSync(wait);
+    if (_tryKernelLock(handle)) {
+      if (_fence(handle, lockPath) === 'ok') {
+        // R3 (round-2 WP-0, §6.2): identity fields on the holder record — role/argv0/
+        // purpose let a contended waiter (and /healthz) attribute WHO holds the lock,
+        // not just that it's busy.
+        const acquiredAtMs = now();
+        _writeIdentity(handle, {
+          pid: process.pid,
+          thread_id: threadId,
+          token: `${globalState.token}:${++handle.acquireSeq}`,
+          created_at_ms: acquiredAtMs,
+          acquiredAt: acquiredAtMs,
+          // WALL_E_PROCESS_ROLE (not CTM_PROCESS_ROLE — the §6.2 spec text names the
+          // latter, but that's CTM's own foreign-owner marker, always unset for wall-e's
+          // OWN daemon/workers; WALL_E_PROCESS_ROLE is the identity every legitimate
+          // wall-e opener actually sets — see lib/live-data-role-guard.js's enumeration.
+          // Also avoids a NEW raw CTM_* env read here, which the flag-read ratchet forbids).
+          role: opts.role || process.env.WALL_E_PROCESS_ROLE || 'unknown',
+          argv0: opts.argv0 || path.basename(process.argv[1] || ''),
+          purpose: String(opts.purpose || opts.label || '').slice(0, 80),
+          label: opts.label || '',
+        });
+        const entry = { depth: 1, lockPath, token: globalState.token };
+        globalState.locks.set(canonical, entry);
+        return {
+          waitedMs: now() - startedAt,
+          contended,
+          // D-1: release is COMMIT — never an unlink, never a record rewrite.
+          release: () => {
+            entry.depth -= 1;
+            if (entry.depth > 0) return;
+            globalState.locks.delete(canonical);
+            handle.commit.run();
+          },
+        };
       }
+      // A live foreign claim (a pre-WP-1 process, or a directory) owns the path:
+      // give the kernel lock back and wait like any other busy acquirer.
+      handle.commit.run();
+      contended = true;
+    } else {
+      contended = true;
+    }
+    // R3 (round-2 WP-0, §6.2): a FOREIGN (not-this-pid) holder at/beyond the incident
+    // threshold gets exactly one incident record + /healthz projection. Both contended
+    // branches end in the same busy error below, so both must attribute the holder the same
+    // way: under D-3 the record at the path is the identity of whoever is inside its hold,
+    // and under D-8c it is the only identity a live pre-WP-1 claim has.
+    const info = _readIdentity(lockPath);
+    if (info && info.pid !== process.pid) {
+      _maybeRecordForeignHold({ info }, opts);
     }
+    const wait = _remainingWaitMs(deadline, pollMs, now());
+    // D-4: no age-based stealing. A holder that is alive keeps the lock; the waiter
+    // fails busy at its own deadline and the incident log is the escalation.
+    if (wait < 0) throw _lockBusyError(lockPath, _readIdentity(lockPath));
+    sleepSync(wait);
   }
 }
 
@@ -928,21 +1034,27 @@ function containsLikelyWriteSql(sql) {
     });
 }
 
-// One-pass boot sweep for a single lock file: crashed processes leave their
-// write-lock file behind forever otherwise (nothing else ever revisits a lock
-// path once no writer contends for it). Only ever removes a lock whose holder
-// pid is provably dead (ESRCH via _pidAlive) — a live holder, or a record we
-// can't parse/attribute, is left alone for the normal acquire-time staleness
-// path (staleMs / claimStaleMs) to handle instead. Safe to call repeatedly
-// (idempotent) and safe under a real concurrent acquirer (reuses the same
-// observed-then-unlink-if-unchanged compare as the acquire loop).
+// One-pass boot sweep for a single lock file: crashed processes leave their record
+// behind forever otherwise (nothing else ever revisits a lock path once no writer
+// contends for it). Only ever removes a record whose holder pid is provably dead
+// (ESRCH via _pidAlive) — a live holder, or a record we can't parse/attribute, is left
+// alone. Protocol-agnostic: a dead v2 process's record is removed too, and any live v2
+// holder of that path adopts the new inode on its next acquire (D-8b). The re-inspect
+// before the unlink is the race guard that replaces _unlinkIfUnchanged; this never
+// touches `${lockPath}.mutex`. Safe to call repeatedly (idempotent) and safe under a
+// real concurrent acquirer.
 function _bootSweepLockFile(lockPath, logger = console) {
-  const inspected = _inspectLock(lockPath);
-  if (!inspected.exists) return false;
-  const pid = inspected.info?.pid;
+  const pid = _readIdentity(lockPath)?.pid;
   if (pid == null || _pidAlive(pid)) return false;
-  const removed = _unlinkIfUnchanged(lockPath, inspected);
-  if (removed && logger && typeof logger.warn === 'function') {
+  // Re-inspect: the record may have been replaced (a new writer, another sweep) since
+  // the read above — only remove the very record whose dead pid we proved.
+  if (Number(_readIdentity(lockPath)?.pid) !== Number(pid)) return false;
+  try {
+    fs.unlinkSync(lockPath);
+  } catch (error) {
+    return error?.code === 'ENOENT';
+  }
+  if (logger && typeof logger.warn === 'function') {
     try {
       logger.warn(`[sqlite-write-lock] boot sweep removed stale lock (dead pid=${pid}): ${lockPath}`);
     } catch {
@@ -951,13 +1063,26 @@ function _bootSweepLockFile(lockPath, logger = console) {
          an already-successful boot sweep into a startup failure */
     }
   }
-  return removed;
+  return true;
 }
 
 function lockBootSweepEnabled(env = process.env) {
   return String(env.WALLE_LOCK_BOOT_SWEEP ?? '1') !== '0';
 }
 
+// Test seam only: tests that call createSqliteWriteLock directly have no wrapped
+// db.close() to release the handle through (D-7b), so they call this in after().
+function closeSqliteWriteLocksForTests() {
+  const entries = [...globalState.lockDbs.entries()];
+  globalState.lockDbs.clear();
+  for (const [canonical, handle] of entries) {
+    if (handle.db && handle.db.inTransaction) {
+      throw new Error(`closeSqliteWriteLocksForTests: lock DB still in a transaction: ${canonical}`);
+    }
+    _closeHandleResources(handle);
+  }
+}
+
 function installSqliteWriteLock(db, dbPath, opts = {}) {
   if (!db || db.__sqliteWriteLockInstalled) return db;
   const lockPath = opts.lockPath || `${dbPath}.write-lock`;
@@ -965,12 +1090,24 @@ function installSqliteWriteLock(db, dbPath, opts = {}) {
     try {
       _bootSweepLockFile(lockPath, opts.logger || console);
     } catch {
-      /* expected: _bootSweepLockFile's own doc comment (above its definition) says a lock it
-         can't remove is left for the normal acquire-time staleness check to handle instead —
-         a thrown error here (e.g. an unreadable lock dir) must fall through to that same
-         acquire-time path rather than abort DB install */
+      /* expected: a record the sweep can't remove is left for the acquire-time fence to
+         handle instead — a thrown error here (e.g. an unreadable lock dir) must fall
+         through to that same path rather than abort DB install */
     }
   }
+  // D-7b: one handle per (thread, lock path), refcounted per wrapped connection and
+  // released by the LAST db.close(). D-5: the lock DB comes from the constructor of the
+  // connection being wrapped.
+  const canonical = _canonicalLockPath(lockPath);
+  _retainHandle(_lockHandle(lockPath, canonical, { ...opts, Database: db.constructor }));
+  if (typeof db.close === 'function') {
+    const originalClose = db.close.bind(db);
+    db.close = (...a) => {
+      const result = originalClose(...a);
+      _releaseHandle(canonical);
+      return result;
+    };
+  }
   const upstreamOnEvent = typeof opts.onEvent === 'function' ? opts.onEvent : null;
   let eventSequence = 0;
   let lastEvent = null;
@@ -1051,8 +1188,9 @@ module.exports = {
   suspendWriteLockHoldBudget,
   // WP-P3 test seams: internal, hermetic-tests-only. Not part of the public API.
   _remainingWaitMsForTests: _remainingWaitMs,
-  _staleReasonForTests: _staleReason,
   _bootSweepLockFileForTests: _bootSweepLockFile,
+  // D-7b: direct createSqliteWriteLock callers (no wrapped db.close) release here.
+  closeSqliteWriteLocksForTests,
   _currentLockTokenForTests: () => globalState.token,
   _resetWriteLockForeignHoldForTests,
 };