dirsql 0.3.24__tar.gz → 0.3.26__tar.gz

{dirsql-0.3.24 → dirsql-0.3.26}/Cargo.lock

@@ -499,7 +499,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.24"
+version = "0.3.26"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.24 → dirsql-0.3.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.24
+Version: 0.3.26
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'

{dirsql-0.3.24 → dirsql-0.3.26}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.3.24"
+version = "0.3.26"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.24 → dirsql-0.3.26}/packages/rust/src/config.rs

@@ -256,23 +256,6 @@ glob = "*.json"
         assert!(config.ignore.is_empty());
     }
 
-    #[test]
-    fn load_config_from_file() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join(".dirsql.toml");
-        std::fs::write(
-            &path,
-            r#"
-[[table]]
-ddl = "CREATE TABLE t (_path TEXT)"
-glob = "*.csv"
-"#,
-        )
-        .unwrap();
-        let config = load_config(&path).unwrap();
-        assert_eq!(config.tables.len(), 1);
-    }
-
     #[test]
     fn load_config_missing_file_returns_io_error() {
         let err = load_config(Path::new("/nonexistent/.dirsql.toml")).unwrap_err();

{dirsql-0.3.24 → dirsql-0.3.26}/packages/rust/src/lib.rs

@@ -227,6 +227,17 @@ impl Table {
 struct DirSqlInner {
     db: Mutex<Db>,
     root: PathBuf,
+    /// Canonicalized form of `root`, used **only** for the live filesystem
+    /// watcher. `notify` has surprising behavior when handed a relative path
+    /// like `.` / `./data` (it may deliver no events at all, or deliver them
+    /// under the cwd-joined path so the relative prefix no longer strips):
+    /// the CLI binary works around this by canonicalizing its root before
+    /// watching, and the SDK now does the same (#250). Derived once at
+    /// construction via [`canonical_root`] (literal fallback when
+    /// canonicalization fails, e.g. a not-yet-created root), so the user's
+    /// `root` — and therefore the initial scan, [`DirSQL::config`], and the
+    /// `_path` virtual column — stay byte-for-byte unchanged.
+    watch_root: PathBuf,
     /// Pre-compiled matcher over all table globs plus ignore patterns.
     /// Built once at construction, reused by the initial scan and every
     /// subsequent watch iteration.
@@ -393,7 +404,9 @@ impl DirSQL {
     pub fn start_watching(&self) -> Result<()> {
         let mut guard = self.inner.watcher.lock().map_err(DirSqlError::lock)?;
         if guard.is_none() {
-            let watcher = Watcher::new(&self.inner.root).map_err(DirSqlError::watch)?;
+            // Watch the canonicalized root, never the (possibly relative)
+            // user-supplied one — `notify` misbehaves on relative paths (#250).
+            let watcher = Watcher::new(&self.inner.watch_root).map_err(DirSqlError::watch)?;
             *guard = Some(watcher);
         }
         Ok(())
@@ -515,8 +528,15 @@ impl DirSQL {
         let abs_path = match &event {
             FileEvent::Created(p) | FileEvent::Modified(p) | FileEvent::Deleted(p) => p.clone(),
         };
+        // Events now arrive under the canonical `watch_root` (the watcher was
+        // started on it), so strip that first; fall back to the user-supplied
+        // `root` (covers the already-canonical/absolute-root case and any
+        // event whose path predates the watch-root change), then to the raw
+        // absolute path. This keeps the computed relative `_path` identical to
+        // the pre-#250 behavior for both absolute and relative roots.
         let rel_path_buf = abs_path
-            .strip_prefix(&self.inner.root)
+            .strip_prefix(&self.inner.watch_root)
+            .or_else(|_| abs_path.strip_prefix(&self.inner.root))
             .unwrap_or(&abs_path)
             .to_path_buf();
 
@@ -870,10 +890,17 @@ impl DirSQL {
             write_meta(db.conn(), meta).map_err(DirSqlError::sqlite)?;
         }
 
+        // Canonicalize the watch root once, here at the single shared
+        // construction point reached by both `build()` and `build_async()`,
+        // so the live watcher never sees a relative path (#250). `root` itself
+        // is left untouched.
+        let watch_root = PathBuf::from(canonical_root(&root));
+
         Ok(Self {
             inner: Arc::new(DirSqlInner {
                 db: Mutex::new(db),
                 root,
+                watch_root,
                 matcher,
                 extract_map,
                 strict_map,
@@ -1867,6 +1894,171 @@ mod internal_tests {
         assert_eq!(events.len(), 1, "non-ignored path must produce one event");
     }
 
+    // -----------------------------------------------------------------------
+    // #250: canonical `watch_root` and the strip-prefix fallbacks.
+    //
+    // `std::env::set_current_dir` is process-global, so the relative-root test
+    // serializes through this lock and restores the cwd on the way out.
+    // -----------------------------------------------------------------------
+
+    fn cwd_lock() -> &'static Mutex<()> {
+        static LOCK: std::sync::OnceLock<Mutex<()>> = std::sync::OnceLock::new();
+        LOCK.get_or_init(|| Mutex::new(()))
+    }
+
+    /// Building with a **relative** root canonicalizes `watch_root` to an
+    /// absolute path while leaving `root` (and therefore `config()` / `_path`)
+    /// exactly as the caller supplied it. This is the core of the #250 fix:
+    /// `start_watching` watches `watch_root`, so `notify` never sees `.`.
+    #[test]
+    fn relative_root_canonicalizes_watch_root_only() {
+        let dir = TempDir::new().unwrap();
+        let canonical = std::fs::canonicalize(dir.path()).unwrap();
+
+        let _guard = cwd_lock().lock().unwrap_or_else(|p| p.into_inner());
+        let original = std::env::current_dir().unwrap();
+        std::env::set_current_dir(&canonical).unwrap();
+
+        let db = DirSQL::new(
+            ".",
+            vec![Table::new("CREATE TABLE t (x TEXT)", "*.txt", |_| vec![])],
+        )
+        .unwrap();
+
+        // Restore cwd before asserting so a failure can't strand the process.
+        std::env::set_current_dir(&original).unwrap();
+
+        // `root` is preserved verbatim; `config()` echoes it.
+        assert_eq!(db.inner.root, PathBuf::from("."));
+        assert_eq!(db.config().root, PathBuf::from("."));
+        // `watch_root` is absolute and points at the canonical temp dir.
+        assert!(
+            db.inner.watch_root.is_absolute(),
+            "watch_root must be absolute, got {:?}",
+            db.inner.watch_root
+        );
+        assert_eq!(db.inner.watch_root, canonical);
+    }
+
+    /// With an absolute root the canonical `watch_root` equals the (already
+    /// canonical) root on this platform, and `process_file_event` strips that
+    /// prefix to yield a root-relative `_path` — the first `strip_prefix`
+    /// (watch_root) arm.
+    #[test]
+    fn process_file_event_strips_watch_root_prefix() {
+        let dir = TempDir::new().unwrap();
+        let canonical = std::fs::canonicalize(dir.path()).unwrap();
+        let db = DirSQL::new(
+            &canonical,
+            vec![Table::new(
+                "CREATE TABLE items (name TEXT, _path TEXT)",
+                "**/*.txt",
+                |_| {
+                    vec![Row::from_iter([(
+                        "name".to_string(),
+                        Value::Text("x".into()),
+                    )])]
+                },
+            )],
+        )
+        .unwrap();
+
+        let abs = canonical.join("nested").join("a.txt");
+        std::fs::create_dir_all(canonical.join("nested")).unwrap();
+        std::fs::write(&abs, b"").unwrap();
+
+        let events = db.process_file_event(FileEvent::Created(abs));
+        assert_eq!(events.len(), 1, "expected one insert: {events:?}");
+        match &events[0] {
+            RowEvent::Insert { row, .. } => {
+                assert_eq!(
+                    row.get("_path"),
+                    Some(&Value::Text("nested/a.txt".to_string())),
+                    "watch_root prefix must be stripped to a root-relative path"
+                );
+            }
+            other => panic!("expected Insert, got {other:?}"),
+        }
+    }
+
+    /// When an event path lies under the user-supplied `root` but not under
+    /// the canonical `watch_root`, the `.or_else` fallback strips `root`
+    /// instead. We force that split by pointing `watch_root` at a sibling that
+    /// is not a prefix of the event path, leaving `root` as the real dir.
+    #[test]
+    fn process_file_event_falls_back_to_root_prefix() {
+        let dir = TempDir::new().unwrap();
+        let canonical = std::fs::canonicalize(dir.path()).unwrap();
+        let mut db = DirSQL::new(
+            &canonical,
+            vec![Table::new(
+                "CREATE TABLE items (name TEXT, _path TEXT)",
+                "**/*.txt",
+                |_| {
+                    vec![Row::from_iter([(
+                        "name".to_string(),
+                        Value::Text("x".into()),
+                    )])]
+                },
+            )],
+        )
+        .unwrap();
+
+        // Repoint watch_root to a non-prefix sibling so the first strip misses
+        // and the `.or_else(root)` arm runs. `root` stays the real dir.
+        Arc::get_mut(&mut db.inner).unwrap().watch_root = canonical.join("does-not-prefix");
+
+        let abs = canonical.join("b.txt");
+        std::fs::write(&abs, b"").unwrap();
+        let events = db.process_file_event(FileEvent::Created(abs));
+        assert_eq!(events.len(), 1, "expected one insert: {events:?}");
+        match &events[0] {
+            RowEvent::Insert { row, .. } => {
+                assert_eq!(
+                    row.get("_path"),
+                    Some(&Value::Text("b.txt".to_string())),
+                    "root fallback must strip the user-supplied root prefix"
+                );
+            }
+            other => panic!("expected Insert, got {other:?}"),
+        }
+    }
+
+    /// When the event path is under neither `watch_root` nor `root`, the final
+    /// `unwrap_or(&abs_path)` arm keeps the absolute path. A path that matches
+    /// no table glob then yields no events, but the strip fallback is still
+    /// executed — we assert the no-event outcome to pin the arm without relying
+    /// on a row.
+    #[test]
+    fn process_file_event_keeps_absolute_path_when_no_prefix_matches() {
+        let dir = TempDir::new().unwrap();
+        let canonical = std::fs::canonicalize(dir.path()).unwrap();
+        let db = DirSQL::new(
+            &canonical,
+            vec![Table::new(
+                "CREATE TABLE items (name TEXT)",
+                "*.txt",
+                |_| {
+                    vec![Row::from_iter([(
+                        "name".to_string(),
+                        Value::Text("x".into()),
+                    )])]
+                },
+            )],
+        )
+        .unwrap();
+
+        // A path outside both roots: neither strip matches, so the absolute
+        // path is used as the relative path. It does not match `*.txt` at the
+        // root, so no events are produced.
+        let outside = PathBuf::from("/some/elsewhere/c.md");
+        let events = db.process_file_event(FileEvent::Created(outside));
+        assert!(
+            events.is_empty(),
+            "unmatched absolute path must produce no events: {events:?}"
+        );
+    }
+
     /// Drive `reconcile_scan` directly with a cached file whose
     /// `snapshot_ns <= mtime_ns`, forcing the racy-window hash-confirm branch.
     /// With a matching content hash the file is trusted.

dirsql-0.3.26/packages/rust/src/scanner.rs

@@ -0,0 +1,83 @@
+use crate::matcher::TableMatcher;
+use std::path::{Path, PathBuf};
+use walkdir::WalkDir;
+
+/// Top-level directory name reserved for `dirsql`'s own metadata (e.g. the
+/// persistent cache database). Always excluded from the scan, regardless of
+/// whether persistence is enabled.
+pub const RESERVED_DIR: &str = ".dirsql";
+
+/// Walk a directory tree and return all file paths paired with their matching table name.
+/// Ignored paths and directories are skipped. Only files (not directories) are returned.
+///
+/// The top-level `.dirsql/` directory is unconditionally excluded.
+pub fn scan_directory(root: &Path, matcher: &TableMatcher) -> Vec<(PathBuf, String)> {
+    let mut results = Vec::new();
+
+    let walker = WalkDir::new(root).into_iter().filter_entry(|entry| {
+        // Skip the reserved `.dirsql/` directory at the top level.
+        !is_reserved_dir(entry.depth(), entry.file_type().is_dir(), entry.file_name())
+    });
+
+    for entry in walker.filter_map(|e| e.ok()) {
+        let path = entry.path();
+
+        // Match against relative path so globs like "comments/**/*.jsonl" work
+        // regardless of the absolute root directory.
+        let rel_path = path.strip_prefix(root).unwrap_or(path);
+
+        if matcher.is_ignored(rel_path) {
+            continue;
+        }
+
+        if !entry.file_type().is_file() {
+            continue;
+        }
+
+        if let Some(table_name) = matcher.match_file(rel_path) {
+            results.push((path.to_path_buf(), table_name.to_string()));
+        }
+    }
+
+    results
+}
+
+/// True for the reserved top-level `.dirsql/` directory (`depth == 1`), which
+/// the scan unconditionally excludes. Factored out as a pure predicate over the
+/// facts `WalkDir` exposes so it can be unit-tested without walking a real tree
+/// -- the directory-walk behavior itself is covered by `tests/scanner.rs`.
+fn is_reserved_dir(depth: usize, is_dir: bool, file_name: &std::ffi::OsStr) -> bool {
+    depth == 1 && is_dir && file_name == RESERVED_DIR
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::ffi::OsStr;
+
+    // The directory-walk behavior of `scan_directory` (real temp trees, real
+    // files) is exercised by `tests/scanner.rs` -- those are integration tests
+    // and stay out of this inline unit module, which the `unit lint` isolation
+    // rule keeps free of effectful std. What remains here is the pure
+    // reserved-dir predicate the walker filters on.
+
+    #[test]
+    fn is_reserved_dir_matches_top_level_dirsql() {
+        assert!(is_reserved_dir(1, true, OsStr::new(RESERVED_DIR)));
+    }
+
+    #[test]
+    fn is_reserved_dir_rejects_nested_dirsql() {
+        // Only the *top-level* `.dirsql/` (depth 1) is reserved; a nested one
+        // (e.g. `sub/.dirsql/`) is an ordinary directory.
+        assert!(!is_reserved_dir(2, true, OsStr::new(RESERVED_DIR)));
+    }
+
+    #[test]
+    fn is_reserved_dir_rejects_files_and_other_names() {
+        // A file named `.dirsql` is not the reserved directory ...
+        assert!(!is_reserved_dir(1, false, OsStr::new(RESERVED_DIR)));
+        // ... and an ordinary top-level directory is not reserved.
+        assert!(!is_reserved_dir(1, true, OsStr::new("data")));
+    }
+}

dirsql-0.3.26/packages/rust/tests/config.rs

@@ -0,0 +1,26 @@
+//! Integration test for `load_config` reading a real `.dirsql.toml` off disk.
+//!
+//! The pure TOML-parsing tests (`load_config_str`) stay inline in `config.rs`;
+//! this exercises the thin file-reading wrapper, which needs a real file
+//! (effectful std), so per the `unit lint` isolation rule it belongs in the
+//! integration tier rather than the inline unit module.
+
+use dirsql::config::load_config;
+use tempfile::TempDir;
+
+#[test]
+fn load_config_from_file() {
+    let dir = TempDir::new().unwrap();
+    let path = dir.path().join(".dirsql.toml");
+    std::fs::write(
+        &path,
+        r#"
+[[table]]
+ddl = "CREATE TABLE t (_path TEXT)"
+glob = "*.csv"
+"#,
+    )
+    .unwrap();
+    let config = load_config(&path).unwrap();
+    assert_eq!(config.tables.len(), 1);
+}

dirsql-0.3.26/packages/rust/tests/scanner.rs

@@ -0,0 +1,97 @@
+//! Integration tests for `scan_directory`.
+//!
+//! These build real temp directory trees with real files and assert what the
+//! scanner returns end-to-end through its public API. They were moved out of
+//! `scanner.rs`'s inline `#[cfg(test)]` module so that module stays pure (the
+//! `testing-conventions` `unit lint` isolation rule forbids effectful std --
+//! `std::fs`, temp dirs -- in unit tests). The pure reserved-dir predicate
+//! test remains inline next to the function it covers.
+
+use std::fs;
+
+use dirsql::matcher::TableMatcher;
+use dirsql::scanner::scan_directory;
+use tempfile::TempDir;
+
+#[test]
+fn scan_finds_matching_files() {
+    let dir = TempDir::new().unwrap();
+    fs::write(dir.path().join("data.csv"), "a,b\n1,2").unwrap();
+    fs::write(dir.path().join("readme.md"), "# hi").unwrap();
+
+    let matcher = TableMatcher::new(&[("**/*.csv", "csv_table")], &[]).unwrap();
+    let results = scan_directory(dir.path(), &matcher);
+
+    assert_eq!(results.len(), 1);
+    assert!(results[0].0.ends_with("data.csv"));
+    assert_eq!(results[0].1, "csv_table");
+}
+
+#[test]
+fn scan_skips_ignored_files() {
+    let dir = TempDir::new().unwrap();
+    fs::write(dir.path().join("data.csv"), "a,b").unwrap();
+    fs::write(dir.path().join("data.tmp"), "junk").unwrap();
+
+    let matcher =
+        TableMatcher::new(&[("**/*.csv", "t"), ("**/*.tmp", "t2")], &["**/*.tmp"]).unwrap();
+    let results = scan_directory(dir.path(), &matcher);
+
+    assert_eq!(results.len(), 1);
+    assert!(results[0].0.ends_with("data.csv"));
+}
+
+#[test]
+fn scan_recurses_into_subdirectories() {
+    let dir = TempDir::new().unwrap();
+    let sub = dir.path().join("nested").join("deep");
+    fs::create_dir_all(&sub).unwrap();
+    fs::write(sub.join("events.jsonl"), "{}").unwrap();
+
+    let matcher = TableMatcher::new(&[("**/*.jsonl", "events")], &[]).unwrap();
+    let results = scan_directory(dir.path(), &matcher);
+
+    assert_eq!(results.len(), 1);
+    assert!(results[0].0.ends_with("events.jsonl"));
+    assert_eq!(results[0].1, "events");
+}
+
+#[test]
+fn scan_returns_empty_for_no_matches() {
+    let dir = TempDir::new().unwrap();
+    fs::write(dir.path().join("readme.md"), "# hi").unwrap();
+
+    let matcher = TableMatcher::new(&[("**/*.csv", "t")], &[]).unwrap();
+    let results = scan_directory(dir.path(), &matcher);
+
+    assert!(results.is_empty());
+}
+
+#[test]
+fn scan_skips_directories() {
+    let dir = TempDir::new().unwrap();
+    // Create a directory that matches the glob -- it should not appear in results
+    fs::create_dir(dir.path().join("data.csv")).unwrap();
+
+    let matcher = TableMatcher::new(&[("**/*.csv", "t")], &[]).unwrap();
+    let results = scan_directory(dir.path(), &matcher);
+
+    assert!(results.is_empty());
+}
+
+#[test]
+fn scan_excludes_top_level_dirsql_directory() {
+    let dir = TempDir::new().unwrap();
+    fs::write(dir.path().join("real.csv"), "a,b\n1,2").unwrap();
+
+    // Files inside the reserved `.dirsql/` directory (e.g. the cache db)
+    // must never be picked up by the scanner.
+    fs::create_dir(dir.path().join(".dirsql")).unwrap();
+    fs::write(dir.path().join(".dirsql").join("cache.csv"), "a,b\n1,2").unwrap();
+
+    let matcher = TableMatcher::new(&[("**/*.csv", "t")], &[]).unwrap();
+    let results = scan_directory(dir.path(), &matcher);
+
+    assert_eq!(results.len(), 1);
+    assert!(results[0].0.ends_with("real.csv"));
+}

dirsql-0.3.26/packages/rust/tests/watch_relative_root.rs

@@ -0,0 +1,134 @@
+//! Regression test for #250: the file watcher must deliver `RowEvent`s when
+//! `DirSQL` is constructed with a **relative** `root` (e.g. `DirSQL::new(".",
+//! ...)`), not just an absolute one.
+//!
+//! Root cause: `start_watching()` handed the user-supplied (possibly relative)
+//! `root` straight to `notify`, which has surprising behavior when watching
+//! relative paths like `./`. The initial scan worked fine either way; only the
+//! live watcher was broken. The CLI binary already canonicalized its root for
+//! exactly this reason — the SDK did not. The fix watches a canonicalized
+//! `watch_root` while keeping the user-supplied `root` for scanning,
+//! `config()`, and `_path` output.
+//!
+//! `std::env::set_current_dir` mutates **process-global** state, so every test
+//! in this file serializes through `CWD_LOCK` and restores the original cwd on
+//! the way out (via the `CwdGuard` drop), even on panic.
+
+use dirsql::{DirSQL, Table, Value};
+use std::fs;
+use std::path::PathBuf;
+use std::sync::{Mutex, MutexGuard, OnceLock};
+use std::time::{Duration, Instant};
+
+/// Serializes the process-global cwd across the tests in this file. A `OnceLock`
+/// avoids pulling in a `lazy_static`/`once_cell` dependency just for the test.
+fn cwd_lock() -> &'static Mutex<()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+}
+
+/// Holds the cwd lock and the original working directory, restoring it on drop.
+/// Recovers a poisoned lock: a prior test panicking while holding the guard
+/// must not cascade-fail every later cwd test.
+struct CwdGuard {
+    _guard: MutexGuard<'static, ()>,
+    original: PathBuf,
+}
+
+impl CwdGuard {
+    fn enter(target: &std::path::Path) -> Self {
+        let guard = cwd_lock().lock().unwrap_or_else(|p| p.into_inner());
+        let original = std::env::current_dir().expect("read cwd");
+        std::env::set_current_dir(target).expect("chdir into target");
+        Self {
+            _guard: guard,
+            original,
+        }
+    }
+}
+
+impl Drop for CwdGuard {
+    fn drop(&mut self) {
+        // Best-effort restore; if this fails the process is already in a bad
+        // state and later tests will surface it.
+        let _ = std::env::set_current_dir(&self.original);
+    }
+}
+
+fn items_table() -> Table {
+    Table::new(
+        "CREATE TABLE items (name TEXT, _path TEXT)",
+        "**/*.txt",
+        |path| {
+            let content = std::fs::read_to_string(path).unwrap_or_default();
+            vec![std::collections::HashMap::from([(
+                "name".to_string(),
+                Value::Text(content.trim().to_string()),
+            )])]
+        },
+    )
+}
+
+/// #250: a watcher built on a relative `root` (`"."`) must still emit an insert
+/// `RowEvent` when a matching file is created after `start_watching()`.
+///
+/// Without the fix the watcher hands `"."` to `notify`, which never delivers
+/// events, so this poll loop times out with zero events (RED). With the fix the
+/// watcher canonicalizes the root, the create is observed, and an `Insert`
+/// arrives (GREEN). The companion absolute-root assertion is intentionally
+/// *not* a separate `#[test]` so it can't race for the cwd lock; it shares this
+/// one to prove the two roots behave identically.
+#[test]
+fn watch_with_relative_root_emits_events() {
+    let dir = tempfile::TempDir::new().unwrap();
+    // Canonicalize the temp dir up front: on macOS `TempDir` lives under
+    // `/var/...` which is a symlink to `/private/var/...`, and the post-fix
+    // `_path` is computed by stripping the *canonical* watch root. Comparing
+    // against a canonical base keeps the relative-path assertion portable.
+    let canonical_dir = fs::canonicalize(dir.path()).unwrap();
+
+    let _cwd = CwdGuard::enter(&canonical_dir);
+
+    // Relative root: the exact shape from the bug report / docs examples.
+    let db = DirSQL::new(".", vec![items_table()]).unwrap();
+    db.start_watching().unwrap();
+
+    // Give the watcher a moment to register before mutating the tree.
+    std::thread::sleep(Duration::from_millis(250));
+    fs::write(canonical_dir.join("apple.txt"), "apple").unwrap();
+
+    let mut events = Vec::new();
+    let deadline = Instant::now() + Duration::from_secs(5);
+    while events.is_empty() && Instant::now() < deadline {
+        events.extend(db.poll_events(Duration::from_millis(200)).unwrap());
+    }
+
+    let insert = events
+        .iter()
+        .find(|e| matches!(e, dirsql::RowEvent::Insert { .. }));
+    assert!(
+        insert.is_some(),
+        "relative-root watcher must emit an Insert event (#250); saw: {events:?}"
+    );
+
+    // The relative `_path` must be the root-relative file name, identical to
+    // what an absolute root would have produced — proving the canonical
+    // watch-root did not leak the absolute prefix into the event path.
+    if let Some(dirsql::RowEvent::Insert { row, .. }) = insert {
+        assert_eq!(
+            row.get("_path"),
+            Some(&Value::Text("apple.txt".to_string())),
+            "_path must stay root-relative for a relative root"
+        );
+    }
+
+    // And the row landed in the in-memory index.
+    let rows = db.query("SELECT name FROM items").unwrap();
+    assert!(
+        rows.iter().any(|r| matches!(
+            r.get("name"),
+            Some(Value::Text(name)) if name == "apple"
+        )),
+        "indexed rows should include the created file"
+    );
+}