Add native filesystem observer

Cargo.toml

@@ -3,6 +3,7 @@ resolver = "2"
 members = [
     "crates/waitprims-core",
     "crates/waitprims-async",
+    "crates/waitprims-fs",
     "crates/waitprims-testkit",
     "crates/waitprims-cli",
 ]
@@ -20,6 +21,7 @@ publish = false
 [workspace.dependencies]
 waitprims-core = { version = "0.2.1", path = "crates/waitprims-core" }
 waitprims-async = { version = "0.2.1", path = "crates/waitprims-async" }
+waitprims-fs = { version = "0.2.1", path = "crates/waitprims-fs" }
 waitprims-testkit = { version = "0.2.1", path = "crates/waitprims-testkit" }
 
 serde = { version = "1.0", features = ["derive"] }
@@ -31,6 +33,7 @@ ryu-js = "1.0"
 jsonschema = { version = "0.30", default-features = false }
 
 tokio = { version = "1", default-features = false, features = ["rt", "time", "macros", "sync"] }
+notify = { version = "=8.2.0", features = ["macos_kqueue"] }
 
 clap = { version = "4.5", features = ["derive"] }
 tracing = "0.1"

crates/waitprims-fs/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "waitprims-fs"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+homepage.workspace = true
+authors.workspace = true
+rust-version.workspace = true
+publish = false
+description = "Native filesystem Observer for waitprims"
+readme = "README.md"
+
+[dependencies]
+waitprims-core.workspace = true
+waitprims-async.workspace = true
+notify.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+sha2.workspace = true
+time.workspace = true
+tokio.workspace = true
+
+[dev-dependencies]
+waitprims-testkit.workspace = true

crates/waitprims-fs/README.md

@@ -0,0 +1,28 @@
+# waitprims-fs
+
+Native local-filesystem wait arm for `waitprims`.
+
+This crate implements the existing `waitprims_async::Observer` seam with
+`notify`'s native `RecommendedWatcher`. It is not a daemon, a shell-style
+watch command, a durable event ledger, or a polling fallback.
+
+The observer:
+
+- accepts only `method_id = "file_watch"`;
+- addresses paths relative to a caller-configured canonical root;
+- accepts the closed predicate set `pred:file-create`, `pred:file-write`,
+  `pred:file-remove`, `pred:file-rename`, and `pred:file-any`;
+- supports only `baseline_policy = latest`;
+- keeps same-bind custody for `restore_ready`, but makes no cross-bind replay
+  claim;
+- returns typed fail-closed observations for overflow, native watcher failure,
+  cursor uncertainty, ambiguous classification, and unsupported filesystem
+  posture.
+
+Network and unknown filesystem postures are unsupported in this release.
+Detection is caller-declared and therefore limited. There is no
+`PollWatcher` or `NullWatcher` fallback.
+
+The event-reference sink receives only a normalized event class and
+root-relative slash-separated paths. File contents, absolute host paths,
+credentials, and capability values are never descriptor fields.