honker 0.3.2 → 0.5.0

data/ext/honker/honker-core/src/lib.rs

@@ -42,6 +42,9 @@ mod kernel_watcher;
 mod shm_watcher;
 
 pub use honker_ops::attach_honker_functions;
+// Shared by the loadable extension's own watcher SQL functions so every
+// honker_* function coerces integer arguments the same way.
+pub use honker_ops::{arg_i64, arg_opt_i64};
 
 use parking_lot::{Condvar, Mutex};
 use rusqlite::functions::FunctionFlags;
@@ -198,21 +201,25 @@ pub enum Error {
 
 /// Default PRAGMA block applied on every connection open. Rationale:
 ///
+///   * `busy_timeout=5000`       — wait up to 5s for the writer lock
+///     before returning SQLITE_BUSY. **Must come first.** Converting
+///     the journal to WAL takes a brief exclusive lock, and until the
+///     timeout is set it is 0, so two processes opening the same fresh
+///     file at once make one of them fail instantly with "database is
+///     locked". Ordering this after `journal_mode` is a real bug, not
+///     a style question.
 ///   * `journal_mode=WAL`        — concurrent readers with one writer.
 ///   * `synchronous=NORMAL`      — fsync WAL at checkpoint, not every
 ///     commit. Safe against app crashes; OS crashes may lose the last
 ///     few unchecked-pointed transactions.
-///   * `busy_timeout=5000`       — wait up to 5s for the writer lock
-///     before returning SQLITE_BUSY.
 ///   * `foreign_keys=ON`         — enforce FK constraints (off by
 ///     default in SQLite, a real footgun).
 ///   * `cache_size=-32000`       — 32MB page cache (default was 2MB).
 ///   * `temp_store=MEMORY`       — temp B-trees in RAM, not disk.
 ///   * `wal_autocheckpoint=10000`— fsync every 10k WAL pages. Reduces
 ///     fsync frequency 10× vs the default of 1k.
-pub const DEFAULT_PRAGMAS: &str = "PRAGMA journal_mode = WAL;
+pub const DEFAULT_PRAGMAS: &str = "PRAGMA busy_timeout = 5000;
          PRAGMA synchronous = NORMAL;
-         PRAGMA busy_timeout = 5000;
          PRAGMA foreign_keys = ON;
          PRAGMA cache_size = -32000;
          PRAGMA temp_store = MEMORY;
@@ -221,9 +228,59 @@ pub const DEFAULT_PRAGMAS: &str = "PRAGMA journal_mode = WAL;
 /// Apply the library's default PRAGMAs to an already-open connection.
 /// Idempotent.
 pub fn apply_default_pragmas(conn: &Connection) -> rusqlite::Result<()> {
+    // busy_timeout has to land before anything that can contend, and
+    // the WAL conversion needs its own retry on top — see
+    // `set_journal_mode_wal`.
+    conn.execute_batch("PRAGMA busy_timeout = 5000;")?;
+    set_journal_mode_wal(conn)?;
     conn.execute_batch(DEFAULT_PRAGMAS)
 }
 
+/// Put the database into WAL mode, retrying while another connection
+/// holds the lock.
+///
+/// `PRAGMA journal_mode = WAL` takes a brief exclusive lock, and SQLite
+/// does **not** run the busy handler for it — `busy_timeout` buys
+/// nothing here. Two processes opening the same file at once and one
+/// fails immediately with "database is locked". That is exactly what a
+/// worker pool does on startup, and it is why the multiprocess
+/// pressure test failed intermittently.
+///
+/// WAL is a persistent property of the file, so the common case after
+/// the first open is a read with no lock at all.
+fn set_journal_mode_wal(conn: &Connection) -> rusqlite::Result<()> {
+    let already_wal = |conn: &Connection| -> rusqlite::Result<bool> {
+        let mode: String = conn.query_row("PRAGMA journal_mode", [], |row| row.get(0))?;
+        Ok(mode.eq_ignore_ascii_case("wal"))
+    };
+
+    if already_wal(conn)? {
+        return Ok(());
+    }
+
+    // Bounded to roughly the busy_timeout above, so a genuinely stuck
+    // lock still surfaces as an error rather than hanging.
+    let deadline = std::time::Instant::now() + std::time::Duration::from_millis(5000);
+    let mut backoff = std::time::Duration::from_millis(1);
+    loop {
+        match conn.execute_batch("PRAGMA journal_mode = WAL;") {
+            Ok(()) => return Ok(()),
+            Err(e) => {
+                // Someone else may have completed the conversion while
+                // we were waiting; that is a success, not a failure.
+                if already_wal(conn).unwrap_or(false) {
+                    return Ok(());
+                }
+                if std::time::Instant::now() >= deadline {
+                    return Err(e);
+                }
+                std::thread::sleep(backoff);
+                backoff = (backoff * 2).min(std::time::Duration::from_millis(50));
+            }
+        }
+    }
+}
+
 // ---------------------------------------------------------------------
 // notify() SQL function + notifications schema
 // ---------------------------------------------------------------------
@@ -1556,9 +1613,10 @@ mod tests {
                 // try_recv returns Err(Empty) for "alive but no msg",
                 // Err(Disconnected) for "watcher died, sender cleared".
                 // Use blocking recv with a poll instead.
-                match rx.recv_timeout(Duration::from_millis(100)) {
-                    Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => break,
-                    _ => {}
+                if let Err(std::sync::mpsc::RecvTimeoutError::Disconnected) =
+                    rx.recv_timeout(Duration::from_millis(100))
+                {
+                    break;
                 }
             }
             if std::time::Instant::now() > deadline {
@@ -1914,7 +1972,7 @@ mod tests {
                     .map(|s| s.success())
                     .unwrap_or(false)
             })
-            .map(|s| *s);
+            .copied();
         let Some(python) = python else {
             eprintln!(
                 "writer_killed_mid_workload_leaves_db_consistent: \
@@ -1992,11 +2050,10 @@ while True:
                 );
             }
             if let Ok(c) = read_conn.query_row("SELECT count(*) FROM q", [], |r| r.get::<_, i64>(0))
+                && c > 0
             {
-                if c > 0 {
-                    high_water = c;
-                    break;
-                }
+                high_water = c;
+                break;
             }
             std::thread::sleep(Duration::from_millis(50));
         }
@@ -2377,20 +2434,33 @@ while True:
     /// Run the wake/listen suite against the kernel-watch backend.
     /// Each commit separated by 20 ms ensures both the 1 ms poller
     /// and the kernel-watch loop have time to fire before the next.
+    ///
+    /// Windows: ReadDirectoryChangesW coalesces and drops notifications,
+    /// so the no-missed-commit assertion below does not hold there —
+    /// observed 3 wakes for 5 commits on a CI runner. kernel_watcher.rs
+    /// documents missed wakes as permitted, and this backend has no
+    /// data_version verification or safety-net poll behind it, so there
+    /// is nothing to recover the lost event. Windows still runs the test
+    /// and enforces the runaway-wake bound; only its lower bound is waived.
+    /// Linux and macOS deliver reliably and stay gated.
     #[test]
     #[cfg(feature = "kernel-watcher")]
     fn kernel_watcher_detects_all_commits() {
         use std::sync::atomic::{AtomicU32, Ordering as AO};
 
-        let tmp = std::env::temp_dir().join(format!(
-            "honker-kernel-watcher-{}-{}",
+        // The kernel backend watches the database's parent directory.
+        // Give this test an isolated directory so parallel tests and
+        // unrelated /tmp activity cannot inflate the runaway-wake count.
+        let tmp_dir = std::env::temp_dir().join(format!(
+            "honker-kernel-watcher-dir-{}-{}",
             std::process::id(),
             std::time::SystemTime::now()
                 .duration_since(std::time::UNIX_EPOCH)
                 .unwrap()
                 .subsec_nanos()
         ));
-        let _ = std::fs::remove_file(&tmp);
+        std::fs::create_dir(&tmp_dir).unwrap();
+        let tmp = tmp_dir.join("app.db");
 
         let writer = open_conn(tmp.to_str().unwrap(), false).unwrap();
         writer.execute_batch("CREATE TABLE t (x INT)").unwrap();
@@ -2432,19 +2502,391 @@ while True:
 
         let observed = count.load(AO::SeqCst);
         drop(watcher);
+        drop(writer);
         let _ = std::fs::remove_file(&tmp);
         let _ = std::fs::remove_file(format!("{}-wal", tmp.display()));
         let _ = std::fs::remove_file(format!("{}-shm", tmp.display()));
+        let _ = std::fs::remove_dir_all(&tmp_dir);
 
         // Experimental contract: spurious wakes are allowed (the backend
         // fires on every filesystem event, and SQLite produces several
-        // events per commit). The thing that must not happen is a *missed*
-        // commit — assert at least n wakes.
+        // events per commit). Keep a generous upper bound on every platform
+        // so a runaway watcher cannot hide behind a Windows test carve-out.
+        let upper = n * 200;
+        assert!(
+            observed <= upper,
+            "kernel watcher detected {observed} wakes for {n} commits, \
+             upper bound {upper} (runaway watcher?)"
+        );
+        #[cfg(not(windows))]
         assert!(
             observed >= n,
             "kernel watcher detected {observed} wakes for {n} commits — \
              missed at least one"
         );
+        #[cfg(windows)]
+        if observed < n {
+            eprintln!(
+                "kernel watcher under-delivered on Windows: \
+                 {observed} wakes for {n} commits"
+            );
+        }
+    }
+
+    // -----------------------------------------------------------------
+    // Issue #80 — the kernel backend must not release SQLite's locks
+    // -----------------------------------------------------------------
+
+    /// Child-process half of the issue-#80 regression test. Inert unless
+    /// `HONKER_ISSUE80_REAP_DB` is set; the parent re-execs this test
+    /// binary with that variable so the open/close happens in a *separate
+    /// process*. That matters: in WAL mode the last connection to close
+    /// deletes `-wal` and `-shm`, but only if it can take an EXCLUSIVE
+    /// lock on the main database file — which the parent's live connection
+    /// is supposed to prevent.
+    /// Byte offsets SQLite locks, from `os_unix.c`.
+    /// `UNIX_SHM_BASE = (22 + SQLITE_SHM_NLOCK) * 4 = 120`; the deadman
+    /// switch sits one past the eight lock slots, at 128. On the main
+    /// database file, `SHARED_FIRST = PENDING_BYTE + 2` and
+    /// `SHARED_SIZE = 510`.
+    #[cfg(all(
+        unix,
+        feature = "bundled-sqlite",
+        any(feature = "kernel-watcher", feature = "shm-fast-path")
+    ))]
+    const SHM_DMS_BYTE: libc::off_t = 128;
+    #[cfg(all(
+        unix,
+        feature = "bundled-sqlite",
+        any(feature = "kernel-watcher", feature = "shm-fast-path")
+    ))]
+    const DB_SHARED_FIRST: libc::off_t = 0x4000_0000 + 2;
+    #[cfg(all(
+        unix,
+        feature = "bundled-sqlite",
+        any(feature = "kernel-watcher", feature = "shm-fast-path")
+    ))]
+    const DB_SHARED_SIZE: libc::off_t = 510;
+
+    /// Is any lock held on `[off, off+len)` of `path`?
+    ///
+    /// Asks for a write lock, so an existing read *or* write lock reports
+    /// as a conflict. Must run in a different process than the lock holder:
+    /// `F_GETLK` never reports the calling process's own locks.
+    #[cfg(all(
+        unix,
+        feature = "bundled-sqlite",
+        any(feature = "kernel-watcher", feature = "shm-fast-path")
+    ))]
+    fn lock_is_held(path: &std::path::Path, off: libc::off_t, len: libc::off_t) -> bool {
+        let c = std::ffi::CString::new(std::os::unix::ffi::OsStrExt::as_bytes(path.as_os_str()))
+            .unwrap();
+        let fd = unsafe { libc::open(c.as_ptr(), libc::O_RDONLY) };
+        assert!(fd >= 0, "lock probe: could not open {path:?}");
+        let mut fl: libc::flock = unsafe { std::mem::zeroed() };
+        fl.l_type = libc::F_WRLCK as libc::c_short;
+        fl.l_whence = libc::SEEK_SET as libc::c_short;
+        fl.l_start = off;
+        fl.l_len = len;
+        let rc = unsafe { libc::fcntl(fd, libc::F_GETLK, &mut fl) };
+        unsafe { libc::close(fd) };
+        assert_eq!(rc, 0, "lock probe: F_GETLK failed on {path:?}");
+        fl.l_type != libc::F_UNLCK as libc::c_short
+    }
+
+    /// Child-process half of the issue-#80 regression tests.
+    ///
+    /// Inert unless `HONKER_ISSUE80_PROBE_DB` is set; the parent re-execs
+    /// this test binary with that variable, because `F_GETLK` never reports
+    /// the calling process's own locks — the probe *must* be out-of-process.
+    /// Prints one line the parent parses.
+    #[test]
+    #[cfg(all(
+        unix,
+        feature = "bundled-sqlite",
+        any(feature = "kernel-watcher", feature = "shm-fast-path")
+    ))]
+    fn issue_80_lock_probe_child() {
+        let Ok(path) = std::env::var("HONKER_ISSUE80_PROBE_DB") else {
+            return;
+        };
+        let db = PathBuf::from(&path);
+        let shm = PathBuf::from(format!("{path}-shm"));
+        let dms = lock_is_held(&shm, SHM_DMS_BYTE, 1);
+        let shared = lock_is_held(&db, DB_SHARED_FIRST, DB_SHARED_SIZE);
+        println!("HONKER_ISSUE80_RESULT shm_dms={dms} db_shared={shared}");
+    }
+
+    /// Which of SQLite's two lock-bearing files this process still holds.
+    #[cfg(all(
+        unix,
+        feature = "bundled-sqlite",
+        any(feature = "kernel-watcher", feature = "shm-fast-path")
+    ))]
+    #[derive(Debug, PartialEq, Eq)]
+    struct SqliteLockState {
+        /// The `-shm` deadman-switch lock. Held for a WAL connection's life.
+        shm_dms: bool,
+        /// The main database file's SHARED lock. Same lifetime in WAL mode.
+        db_shared: bool,
+    }
+
+    #[cfg(all(
+        unix,
+        feature = "bundled-sqlite",
+        any(feature = "kernel-watcher", feature = "shm-fast-path")
+    ))]
+    fn probe_sqlite_locks_from_another_process(db_path: &std::path::Path) -> SqliteLockState {
+        let exe = std::env::current_exe().expect("current_exe");
+        let out = std::process::Command::new(exe)
+            .args([
+                "--exact",
+                "tests::issue_80_lock_probe_child",
+                "--test-threads=1",
+                "--nocapture",
+            ])
+            .env("HONKER_ISSUE80_PROBE_DB", db_path)
+            .output()
+            .expect("spawn lock probe child");
+        let stdout = String::from_utf8_lossy(&out.stdout);
+        // `contains`, not `starts_with`: under --nocapture libtest prints
+        // the test name without a trailing newline, so the child's own
+        // println lands on the same line.
+        let line = stdout
+            .lines()
+            .find(|l| l.contains("HONKER_ISSUE80_RESULT"))
+            .unwrap_or_else(|| {
+                panic!(
+                    "lock probe child produced no result: {stdout}{}",
+                    String::from_utf8_lossy(&out.stderr)
+                )
+            });
+        SqliteLockState {
+            shm_dms: line.contains("shm_dms=true"),
+            db_shared: line.contains("db_shared=true"),
+        }
+    }
+
+    /// The control perturbation: raw `open()` + `close()` on the two files
+    /// SQLite locks, i.e. what the pre-fix backends did. Every "real
+    /// backend" arm is compared against this.
+    #[cfg(all(
+        unix,
+        feature = "bundled-sqlite",
+        any(feature = "kernel-watcher", feature = "shm-fast-path")
+    ))]
+    fn issue_80_raw_close_lock_bearing_files(db: &std::path::Path) {
+        let shm = PathBuf::from(format!("{}-shm", db.display()));
+        for path in [db, shm.as_path()] {
+            let c =
+                std::ffi::CString::new(std::os::unix::ffi::OsStrExt::as_bytes(path.as_os_str()))
+                    .unwrap();
+            // O_RDONLY, not O_EVTONLY: this arm must compile and behave
+            // identically on every unix, and the lock-drop does not depend
+            // on the open mode.
+            let fd = unsafe { libc::open(c.as_ptr(), libc::O_RDONLY) };
+            assert!(fd >= 0, "control: could not open {path:?}");
+            unsafe { libc::close(fd) };
+        }
+    }
+
+    /// Spawn `backend`, let it settle, then shut it down — while this
+    /// process's SQLite connection is still open.
+    ///
+    /// Shutdown is the case that matters. Both backends hold their
+    /// descriptors for the watcher's lifetime, so nothing is released
+    /// until something closes them. A test that only spawns the watcher
+    /// and never stops it passes against the broken code — that mistake
+    /// was made once already while writing these tests.
+    #[cfg(all(
+        unix,
+        feature = "bundled-sqlite",
+        any(feature = "kernel-watcher", feature = "shm-fast-path")
+    ))]
+    fn issue_80_run_backend_then_shutdown(backend: WatcherBackend, db: &std::path::Path) {
+        let watcher = UpdateWatcher::spawn_with_config(
+            db.to_path_buf(),
+            || {},
+            WatcherConfig::with_backend(backend),
+        );
+        std::thread::sleep(Duration::from_millis(200));
+        watcher.join().expect("watcher thread panicked");
+    }
+
+    /// Hold a live WAL connection, apply `perturb`, then ask another
+    /// process which of SQLite's locks this process still holds.
+    ///
+    /// Asserting the locks directly, rather than a downstream symptom, is
+    /// deliberate. The two ways lock loss shows up are *different*: losing
+    /// the database file's SHARED lock lets another process reap
+    /// `-wal`/`-shm`, while losing only the `-shm` DMS lock instead lets a
+    /// fresh connection win the deadman race and `ftruncate` `-shm` under a
+    /// live mapping. A test that watches for reaping alone is blind to the
+    /// second, and the shm-fast-path defect is exactly the second.
+    #[cfg(all(
+        unix,
+        feature = "bundled-sqlite",
+        any(feature = "kernel-watcher", feature = "shm-fast-path")
+    ))]
+    fn sqlite_locks_after(perturb: impl FnOnce(&std::path::Path)) -> SqliteLockState {
+        let tmp = std::env::temp_dir().join(format!(
+            "honker-issue80-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        let wal = PathBuf::from(format!("{}-wal", tmp.display()));
+        let shm = PathBuf::from(format!("{}-shm", tmp.display()));
+        for p in [&tmp, &wal, &shm] {
+            let _ = std::fs::remove_file(p);
+        }
+
+        // Live WAL connection: takes a SHARED lock on the db file and the
+        // DMS read lock on -shm, and holds both for its whole lifetime.
+        let conn = open_conn(tmp.to_str().unwrap(), false).unwrap();
+        conn.execute_batch("CREATE TABLE t (x INT)").unwrap();
+        conn.execute("INSERT INTO t VALUES (1)", []).unwrap();
+        let _: i64 = conn
+            .query_row("SELECT count(*) FROM t", [], |r| r.get(0))
+            .unwrap();
+        assert!(wal.exists() && shm.exists(), "setup: -wal/-shm not created");
+
+        perturb(&tmp);
+
+        assert!(
+            wal.exists() && shm.exists(),
+            "precondition: -wal/-shm vanished before the lock probe ran"
+        );
+        let state = probe_sqlite_locks_from_another_process(&tmp);
+
+        drop(conn);
+        for p in [&tmp, &wal, &shm] {
+            let _ = std::fs::remove_file(p);
+        }
+        state
+    }
+
+    /// Issue #80: the kernel-watch backend must never release this
+    /// process's SQLite POSIX locks.
+    ///
+    /// When it does, another process's last-connection close deletes
+    /// `-wal`/`-shm` out from under our live connection. The connection
+    /// keeps working against unlinked files, so its next `COMMIT` returns
+    /// `SQLITE_OK` and is then invisible to every other process — a
+    /// successful commit that never lands. The SIGBUS seen in CI is the
+    /// same lock loss taking the other branch, where a fresh connection
+    /// wins the DMS race and `ftruncate`s `-shm` under a live mapping.
+    ///
+    /// # This test proves its own sensitivity
+    ///
+    /// It only means something where SQLite uses *process-scoped* POSIX
+    /// locks (`fcntl(F_SETLK)`). Apple's system libsqlite3 uses
+    /// `fcntl(F_OFD_SETLK)` instead — open-file-description locks, which a
+    /// foreign `close()` cannot release — so on a macOS build linked
+    /// against the system library the property is unfalsifiable and a
+    /// green result would mean nothing. The control arm below asserts the
+    /// defect *is* reproducible in this build before trusting the real
+    /// arm. Build with `--features bundled-sqlite` on macOS.
+    ///
+    /// That is why the whole issue-#80 proof is gated on `bundled-sqlite`:
+    /// it is the only feature that guarantees an upstream amalgamation,
+    /// whose `os_unix.c` uses `fcntl(F_SETLK)`. CI runs the experimental
+    /// backends with that feature on macOS and Windows.
+    #[test]
+    #[cfg(all(unix, feature = "kernel-watcher", feature = "bundled-sqlite"))]
+    fn kernel_watcher_does_not_release_sqlite_wal_locks() {
+        let held = SqliteLockState {
+            shm_dms: true,
+            db_shared: true,
+        };
+
+        let control = sqlite_locks_after(issue_80_raw_close_lock_bearing_files);
+        assert_ne!(
+            control,
+            held,
+            "control arm did not reproduce the defect: a raw open()+close() on \
+             the database file and -shm left SQLite's locks intact, so this \
+             build cannot detect issue #80 at all. SQLite {} is linked; Apple's \
+             system libsqlite3 uses F_OFD_SETLK, whose locks survive a foreign \
+             close. Re-run with --features bundled-sqlite.",
+            rusqlite::version()
+        );
+
+        let baseline = sqlite_locks_after(|_| {});
+        assert_eq!(
+            baseline, held,
+            "a live WAL connection should hold both the -shm deadman lock and \
+             the database file's SHARED lock; the probe is measuring the wrong \
+             byte ranges"
+        );
+
+        let after = sqlite_locks_after(|db| {
+            issue_80_run_backend_then_shutdown(WatcherBackend::KernelWatch, db)
+        });
+        assert_eq!(
+            after, held,
+            "kernel-watch backend released this process's SQLite locks on \
+             shutdown while a live WAL connection was open. It must not hold a \
+             descriptor on the database file or -shm — see \
+             kernel_watcher::macos::candidate_paths and issue #80."
+        );
+    }
+
+    /// Issue #80, shm-fast-path half: the `-shm` fast path must never
+    /// release this process's SQLite WAL-index locks either.
+    ///
+    /// This backend had the defect at three sites, and `probe()` is the
+    /// worst of them: it ran on *every* `honker.open()`, after the caller's
+    /// writer connection had already created `-wal`/`-shm`, so a plain
+    /// `File::open` + drop dropped the whole process's WAL-index locks
+    /// once per open — no churn or contention needed. The other two are
+    /// the identity-change reopen and the watcher's own shutdown.
+    ///
+    /// Both arms below go through the same sensitivity control as the
+    /// kernel test; see that test for why `bundled-sqlite` is required.
+    #[test]
+    #[cfg(all(unix, feature = "shm-fast-path", feature = "bundled-sqlite"))]
+    fn shm_fast_path_does_not_release_sqlite_wal_locks() {
+        let held = SqliteLockState {
+            shm_dms: true,
+            db_shared: true,
+        };
+
+        let control = sqlite_locks_after(issue_80_raw_close_lock_bearing_files);
+        assert_ne!(
+            control,
+            held,
+            "control arm did not reproduce the defect, so this build cannot \
+             detect issue #80. SQLite {} is linked. Re-run with \
+             --features bundled-sqlite.",
+            rusqlite::version()
+        );
+
+        // probe() alone, with no watcher ever spawned. This is the site
+        // that fired on every honker.open().
+        let after_probe = sqlite_locks_after(|db| {
+            WatcherBackend::ShmFastPath
+                .probe(db)
+                .expect("shm probe should succeed on a live WAL database");
+        });
+        assert_eq!(
+            after_probe, held,
+            "shm-fast-path probe() released this process's SQLite locks. \
+             probe() must acquire its -shm descriptor through the registry, \
+             never File::open + drop — see shm_watcher.rs and issue #80."
+        );
+
+        // Full watcher lifecycle, shut down while the connection is live.
+        let after_watcher = sqlite_locks_after(|db| {
+            issue_80_run_backend_then_shutdown(WatcherBackend::ShmFastPath, db)
+        });
+        assert_eq!(
+            after_watcher, held,
+            "shm-fast-path released this process's SQLite locks on watcher \
+             shutdown while a live WAL connection was open — see issue #80."
+        );
     }
 
     /// Prove that the shm fast path fires on the same commits as the
@@ -2551,14 +2993,15 @@ while True:
     //   backend.
     // -----------------------------------------------------------------
 
-    /// Drive `n` committed inserts through `writer`, spaced
-    /// `spacing_ms` apart, and return how many `on_change()` calls the
-    /// watcher observed (with the initial drain already deducted).
+    /// Drive `n` committed inserts through `writer`, giving the watcher
+    /// up to `observation_ms` to acknowledge each one before sending the
+    /// next, and return how many `on_change()` calls were observed (with
+    /// the initial drain already deducted).
     fn drive_and_count_wakes(
         backend: WatcherBackend,
         db_path: PathBuf,
         n: u32,
-        spacing_ms: u64,
+        observation_ms: u64,
     ) -> u32 {
         use std::sync::atomic::{AtomicU32, Ordering as AO};
 
@@ -2581,7 +3024,10 @@ while True:
             writer
                 .execute(&format!("INSERT INTO t VALUES ({i})"), [])
                 .unwrap();
-            std::thread::sleep(Duration::from_millis(spacing_ms));
+            let deadline = std::time::Instant::now() + Duration::from_millis(observation_ms);
+            while count.load(AO::SeqCst) < i && std::time::Instant::now() < deadline {
+                std::thread::sleep(Duration::from_millis(1));
+            }
         }
         // Drain the slowest safety net (kernel = 500 ms) + one cycle.
         std::thread::sleep(Duration::from_millis(700));
@@ -2596,8 +3042,11 @@ while True:
     /// detects every committed insert. Tolerates +1 wake (a commit
     /// straddling the drain boundary) but does not tolerate misses.
     fn watcher_works_in_journal_mode(backend: WatcherBackend, mode: &str) {
-        let tmp = std::env::temp_dir().join(format!(
-            "honker-watcher-{}-{}-{}-{}",
+        // Kernel watchers observe every entry event in the parent
+        // directory. Isolate the database so upper bounds measure this
+        // watcher, not unrelated files created by parallel tests.
+        let tmp_dir = std::env::temp_dir().join(format!(
+            "honker-watcher-dir-{}-{}-{}-{}",
             mode.to_ascii_lowercase(),
             std::process::id(),
             std::time::SystemTime::now()
@@ -2612,7 +3061,8 @@ while True:
                 WatcherBackend::ShmFastPath => "shm",
             },
         ));
-        let _ = std::fs::remove_file(&tmp);
+        std::fs::create_dir(&tmp_dir).unwrap();
+        let tmp = tmp_dir.join("app.db");
 
         // Watcher inherits the file's journal mode, so set it before opening.
         let setup = Connection::open(&tmp).unwrap();
@@ -2646,13 +3096,17 @@ while True:
         };
 
         let n: u32 = 5;
-        let observed = drive_and_count_wakes(backend.clone(), tmp.clone(), n, 30);
+        // Wait for each wake before sending the next commit. The watcher is
+        // deliberately coalescing, so fixed delays can turn five distinct
+        // test commits into four valid wakes under a loaded scheduler.
+        let observed = drive_and_count_wakes(backend.clone(), tmp.clone(), n, 100);
 
         drop(_pinning);
         let _ = std::fs::remove_file(&tmp);
         let _ = std::fs::remove_file(format!("{}-wal", tmp.display()));
         let _ = std::fs::remove_file(format!("{}-shm", tmp.display()));
         let _ = std::fs::remove_file(format!("{}-journal", tmp.display()));
+        let _ = std::fs::remove_dir_all(&tmp_dir);
 
         // Polling/shm dedupe → ~1 wake per commit. Kernel fires per
         // filesystem event (inotify is granular) → upper bound is just
@@ -2664,16 +3118,27 @@ while True:
             #[cfg(feature = "shm-fast-path")]
             WatcherBackend::ShmFastPath => n + 1,
         };
-        assert!(
-            observed >= n,
-            "journal_mode={mode}: observed {observed} wakes for {n} commits \
-             (missed at least one)"
-        );
         assert!(
             observed <= upper,
             "journal_mode={mode}: observed {observed} wakes for {n} commits, \
              upper bound {upper} (runaway watcher?)"
         );
+        #[cfg(feature = "kernel-watcher")]
+        let allows_missed_wakes = cfg!(windows) && matches!(backend, WatcherBackend::KernelWatch);
+        #[cfg(not(feature = "kernel-watcher"))]
+        let allows_missed_wakes = false;
+        if allows_missed_wakes && observed < n {
+            eprintln!(
+                "journal_mode={mode}: kernel watcher under-delivered on Windows: \
+                 {observed} wakes for {n} commits"
+            );
+        } else {
+            assert!(
+                observed >= n,
+                "journal_mode={mode}: observed {observed} wakes for {n} commits \
+                 (missed at least one)"
+            );
+        }
     }
 
     // ---- Polling × every supported journal mode (regression coverage) ----
@@ -2708,7 +3173,14 @@ while True:
     // attach to db + journal + dir to maximize coverage, and ship the
     // backend with documented "missed wakes possible" semantics, but
     // we don't gate CI on a behavior the kernel won't reliably deliver.
-    // WAL-mode kernel coverage stays mandatory (kernel_watcher_works_in_wal).
+    //
+    // Windows hits the same wall for a different reason:
+    // ReadDirectoryChangesW coalesces and drops notifications, so the
+    // `observed >= n` assertion in watcher_works_in_journal_mode is not
+    // sound there either. Same call: don't gate CI on it.
+    //
+    // Linux remains gated on all three modes, and every platform except
+    // Windows stays gated on WAL via kernel_watcher_detects_all_commits.
     #[test]
     #[cfg(feature = "kernel-watcher")]
     #[cfg_attr(
@@ -2850,10 +3322,6 @@ while True:
         ignore = "notify/kqueue can drop the watcher thread under CI load; functional kernel watcher tests still run"
     )]
     #[cfg(feature = "kernel-watcher")]
-    #[cfg_attr(
-        target_os = "macos",
-        ignore = "kqueue under CI load may deliver zero wakes"
-    )]
     fn kernel_watcher_wake_latency_is_event_driven() {
         let tmp = std::env::temp_dir().join(format!(
             "honker-kw-lat-{}-{}",
@@ -3305,3 +3773,76 @@ while True:
         let _ = std::fs::remove_file(format!("{}-shm", path.display()));
     }
 }
+
+#[cfg(test)]
+mod open_race_tests {
+    use std::sync::{Arc, Barrier};
+
+    /// Many connections opening the same fresh database at once must
+    /// all succeed.
+    ///
+    /// `PRAGMA journal_mode = WAL` needs exclusive access to convert the
+    /// journal, and SQLite does **not** run the busy handler for it, so
+    /// `busy_timeout` buys nothing. Without the retry in
+    /// `set_journal_mode_wal`, converters collide with each other and
+    /// the losers fail outright with "database is locked". A worker pool
+    /// starting against a fresh file is exactly that shape, which is
+    /// what made `test_many_processes_enqueue_claim_and_ack_exactly_once`
+    /// fail intermittently on Windows.
+    ///
+    /// The collision is converter-versus-converter, so it can only be
+    /// provoked by racing — holding a read or write lock from a single
+    /// other connection does not block the conversion. Hence the
+    /// deliberately high pressure: enough rounds and openers that the
+    /// old behavior fails essentially every time.
+    #[test]
+    fn concurrent_opens_never_return_database_is_locked() {
+        const ROUNDS: usize = 24;
+        const OPENERS: usize = 32;
+
+        for round in 0..ROUNDS {
+            let dir = std::env::temp_dir().join(format!(
+                "honker-open-race-{}-{round}-{:?}",
+                std::process::id(),
+                std::time::SystemTime::now()
+                    .duration_since(std::time::UNIX_EPOCH)
+                    .unwrap()
+                    .as_nanos()
+            ));
+            std::fs::create_dir_all(&dir).unwrap();
+            let path = dir.join("pressure.db");
+
+            let barrier = Arc::new(Barrier::new(OPENERS));
+            let handles: Vec<_> = (0..OPENERS)
+                .map(|_| {
+                    let path = path.clone();
+                    let barrier = Arc::clone(&barrier);
+                    std::thread::spawn(move || {
+                        let conn = rusqlite::Connection::open(&path)?;
+                        // Converge on the conversion together.
+                        barrier.wait();
+                        super::apply_default_pragmas(&conn)?;
+                        let mode: String =
+                            conn.query_row("PRAGMA journal_mode", [], |row| row.get(0))?;
+                        assert!(
+                            mode.eq_ignore_ascii_case("wal"),
+                            "expected WAL after open, got {mode}"
+                        );
+                        Ok::<_, rusqlite::Error>(())
+                    })
+                })
+                .collect();
+
+            let failures: Vec<String> = handles
+                .into_iter()
+                .filter_map(|h| h.join().unwrap().err().map(|e| e.to_string()))
+                .collect();
+
+            std::fs::remove_dir_all(&dir).ok();
+            assert!(
+                failures.is_empty(),
+                "round {round}: concurrent opens failed: {failures:?}"
+            );
+        }
+    }
+}