3leaps · 3leapsdave · Sep 1, 2026 · Sep 1, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,23 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-09-01
+
+- Add `waitprims-fs`, a native local-filesystem `Observer` backed by
+  `RecommendedWatcher`, with no polling fallback, and opt it in to
+  library-crate publication
+- Normalize native create, write, remove, and rename notifications into
+  root-relative event descriptors with caller-owned payload references
+- Fail closed on unsupported filesystem posture, unsafe path changes,
+  rescan requirements, ambiguous events for specific predicates, overflow,
+  and payload-reference sink failures
+- Support first-match, poll-cycle, held-follow, and held-coalesce runners
+  without changing their public contracts
+- Add diagnostic `waitprims watch` with local file inputs, one filesystem
+  source per invocation, bounded descriptor storage, and existing
+  `follow_burst` / `follow_end` JSONL
+- Add a native filesystem demo and cross-platform integration coverage
+
 ## [0.2.1] - 2026-08-27
 
 - Pin `contract: agent-wait/v0` at Crucible `v0.1.28` (`4bc95146…`)
@@ -92,7 +109,8 @@ APIs may still move.
 - CI matrix already on main (`fast` plus hosted smokes; arm64 labs
   same-repo only)
 
-[Unreleased]: https://github.com/3leaps/waitprims/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/3leaps/waitprims/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/3leaps/waitprims/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/3leaps/waitprims/compare/v0.1.3...v0.2.1
 [0.1.3]: https://github.com/3leaps/waitprims/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/3leaps/waitprims/compare/v0.1.1...v0.1.2

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -9,7 +9,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.2.1"
+version = "0.2.2"
 edition = "2021"
 rust-version = "1.88.0"
 license = "MIT OR Apache-2.0"
@@ -19,10 +19,10 @@ authors = ["3leaps Architecture Council"]
 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" }
+waitprims-core = { version = "0.2.2", path = "crates/waitprims-core" }
+waitprims-async = { version = "0.2.2", path = "crates/waitprims-async" }
+waitprims-fs = { version = "0.2.2", path = "crates/waitprims-fs" }
+waitprims-testkit = { version = "0.2.2", path = "crates/waitprims-testkit" }
 
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"

diff --git a/README.md b/README.md
@@ -55,6 +55,7 @@ silently advance cursors.
 | ----- | ---- |
 | `waitprims-core` | Types, errors, validation, digest and time helpers |
 | `waitprims-async` | First-match, poll-cycle, and held-follow runners |
+| `waitprims-fs` | Native local-filesystem observer |
 | `waitprims-testkit` | Fake clock and scripted observers |
 | `waitprims-cli` | Diagnostic CLI (`waitprims`); not on crates.io |
 
@@ -64,9 +65,10 @@ This cut enables crates.io for the library crates. After that
 publication, depend with:
 
 ```toml
-waitprims-core = "0.1"
-waitprims-async = "0.1"
-waitprims-testkit = "0.1"
+waitprims-core = "0.2"
+waitprims-async = "0.2"
+waitprims-fs = "0.2"
+waitprims-testkit = "0.2"
 ```
 
 Until then, pin a git tag. The diagnostic CLI is not published. APIs
@@ -94,7 +96,7 @@ gate. Fork PRs do not run the arm64 cells. See
 `make precommit` is fmt-check and clippy. `make prepush` adds locked
 tests and version-check. `make pr-final` also runs `make demo-follow`.
 `make release-check` packages the workspace (`cargo package --workspace`)
-and publishes none. Only the three library crates are publishable.
+and publishes none. Only the four library crates are publishable.
 See [`RELEASE_CHECKLIST.md`](RELEASE_CHECKLIST.md) for the later signed
 GitHub release flow.
 

diff --git a/RELEASE_CHECKLIST.md b/RELEASE_CHECKLIST.md
@@ -128,9 +128,10 @@ verifies local tarballs. That is **not** a registry upload.
 | `waitprims-core` | yes (first) |
 | `waitprims-async` | yes (after core is on the index) |
 | `waitprims-testkit` | yes (after async is on the index) |
+| `waitprims-fs` | yes (after testkit; name-slot check first) |
 | `waitprims-cli` | **never** (`publish = false`) |
 
-Workspace `publish` stays `false`. The three libraries opt in.
+Workspace `publish` stays `false`. The four libraries opt in.
 
 ### First cut vs later cuts
 
@@ -146,7 +147,7 @@ Workspace `publish` stays `false`. The three libraries opt in.
 
 ### Tokens (OOB)
 
-Use a crates.io token scoped to the three library crate names. Do
+Use a crates.io token scoped to the four library crate names. Do
 not reuse a Fulmen / other-org token.
 
 | Token | Endpoint scopes | When |
@@ -173,10 +174,20 @@ cargo publish -p waitprims-async
 cargo info --registry crates-io "waitprims-async@${VERSION}"
 cargo publish --dry-run -p waitprims-testkit
 cargo publish -p waitprims-testkit
+cargo info --registry crates-io "waitprims-testkit@${VERSION}"
+cargo info --registry crates-io waitprims-fs
+# For the first waitprims-fs upload, confirm the name is still unclaimed.
+cargo publish --dry-run -p waitprims-fs
+cargo publish -p waitprims-fs
+cargo info --registry crates-io "waitprims-fs@${VERSION}"
 ```
 
 - [ ] Dry-run then publish **core**, wait for the index, then **async**,
-      wait for the index, then **testkit**
+      wait for the index, then **testkit**, wait for the index, then
+      name-slot check and publish **fs**
+- [ ] Immediately before the first `waitprims-fs` publish, run
+      `cargo info --registry crates-io waitprims-fs` and confirm the
+      crate name is still unclaimed. Stop if it resolves to another owner.
 - [ ] Do **not** `cargo publish -p waitprims-cli` (must fail closed:
       `cannot be published`)
 - [ ] Confirm each predecessor with
@@ -198,7 +209,10 @@ cargo publish --dry-run -p waitprims-cli
 Consumers can replace a git tag pin with:
 
 ```toml
-waitprims-async = "0.1"
+waitprims-core = "0.2"
+waitprims-async = "0.2"
+waitprims-testkit = "0.2"
+waitprims-fs = "0.2"
 ```
 
 docs.rs builds from the crates.io tarball. Evergreen README install
@@ -323,7 +337,7 @@ gh release edit v$(cat VERSION) --draft=false
 - [ ] Verify signatures with public keys
 - [ ] After a crates.io cue: each library crate has this VERSION
       (`cargo info --registry crates-io waitprims-core@${VERSION}`,
-      same for async and testkit). Bare `cargo info` can resolve the
+      same for async, testkit, and fs). Bare `cargo info` can resolve the
       workspace and is not an index proof. Search is not a
       version-history proof; no-backfill is policy (section 2).
 

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -8,6 +8,40 @@
 
 ---
 
+## v0.2.2 — 2026-09-01
+
+Native local-filesystem observation and a diagnostic command that exercises
+it directly from a checkout.
+
+### Highlights
+
+- New `waitprims-fs` implements the existing `Observer` contract with the
+  platform-native `RecommendedWatcher`; it does not add a polling fallback.
+- Native create, write, remove, and rename notifications become minimal,
+  root-relative descriptors materialized through a caller-owned payload sink.
+- Filesystem binds fail closed on unsupported posture, unsafe path changes,
+  rescan requirements, ambiguous events for specific predicates, overflow,
+  and sink or digest failures.
+- The observer works with the existing first-match, poll-cycle, held-follow,
+  and held-coalesce runners without changing the six public wire messages.
+- Diagnostic `waitprims watch` accepts local registration and request files,
+  runs one native filesystem source, and emits the existing
+  `follow_burst` / `follow_end` JSONL views.
+- Native demo coverage runs across the supported CI platform matrix without
+  introducing a public watcher API or filesystem polling.
+
+### Upgrade notes
+
+- Workspace crates move from 0.2.1 to 0.2.2.
+- `waitprims-fs` is newly available as a library crate.
+- `waitprims-cli` remains unpublished.
+- Public JSON remains exactly the six `agent-wait/v0` message kinds.
+- Git users should pin `v0.2.2`.
+
+Full notes: [docs/releases/v0.2.2.md](docs/releases/v0.2.2.md)
+
+---
+
 ## v0.2.1 — 2026-08-27
 
 Held-follow and held-coalesce runners, deterministic diagnostic demos,
@@ -66,29 +100,3 @@ is intended.
   still drafts an unsigned GitHub release.
 
 Full notes: [docs/releases/v0.1.3.md](docs/releases/v0.1.3.md)
-
----
-
-## v0.1.2 — 2026-08-18
-
-Release-kit hygiene. No library API change is intended. This release
-does not publish to crates.io or change repository visibility.
-
-### Highlights
-
-- Makefile release leaf targets have no write-chain precursors.
-  `make release-export-keys` does not re-clean or re-download.
-- `make release` is the only serialized walk: clean, download, notes,
-  checksums, sign, export-keys, upload. Verification runs once, as
-  the upload grouping prerequisite.
-- CLI `--version` test tracks the workspace `VERSION` file.
-- Makefile `precommit` and `pr-final` sit beside `prepush`.
-
-### Upgrade notes
-
-- No public API change.
-- `publish` stays `false`. Pin from git if you already pin `v0.1.1`.
-- Signing is local MFA (`make release-sign` / `make release`). CI
-  still drafts an unsigned GitHub release.
-
-Full notes: [docs/releases/v0.1.2.md](docs/releases/v0.1.2.md)
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.2.1
+0.2.2
diff --git a/crates/waitprims-async/README.md b/crates/waitprims-async/README.md
@@ -6,7 +6,7 @@ Tokio is used for runtime, time, and synchronization only. This crate
 does not open network sockets and is not a daemon.
 
 ```toml
-waitprims-async = "0.1"
+waitprims-async = "0.2"
 ```
 
 Depends on [`waitprims-core`](https://crates.io/crates/waitprims-core).

diff --git a/crates/waitprims-core/README.md b/crates/waitprims-core/README.md
@@ -6,7 +6,7 @@ This crate has no async runtime and does not open sockets. Public JSON
 is exactly the six `agent-wait/v0` message kinds.
 
 ```toml
-waitprims-core = "0.1"
+waitprims-core = "0.2"
 ```
 
 Docs: <https://docs.rs/waitprims-core>

diff --git a/crates/waitprims-fs/Cargo.toml b/crates/waitprims-fs/Cargo.toml
@@ -7,8 +7,9 @@ repository.workspace = true
 homepage.workspace = true
 authors.workspace = true
 rust-version.workspace = true
-publish = false
+publish = true
 description = "Native filesystem Observer for waitprims"
+documentation = "https://docs.rs/waitprims-fs"
 readme = "README.md"
 
 [dependencies]

diff --git a/crates/waitprims-fs/README.md b/crates/waitprims-fs/README.md
@@ -2,6 +2,10 @@
 
 Native local-filesystem wait arm for `waitprims`.
 
+```toml
+waitprims-fs = "0.2"
+```
+
 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.

diff --git a/crates/waitprims-testkit/README.md b/crates/waitprims-testkit/README.md
@@ -4,7 +4,7 @@ Deterministic test helpers for waitprims: a logical `FakeClock` and
 scripted observers. Proofs stay off the network.
 
 ```toml
-waitprims-testkit = "0.1"
+waitprims-testkit = "0.2"
 ```
 
 Depends on [`waitprims-core`](https://crates.io/crates/waitprims-core)

diff --git a/docs/README.md b/docs/README.md
@@ -70,18 +70,20 @@ schema. Point callers at [`schemas/v0/`](../schemas/v0/). The schema
 | ----- | ---- |
 | `waitprims-core` | Types, errors, validation, digest and RFC3339 helpers |
 | `waitprims-async` | First-match, poll-cycle, and held-follow runners |
+| `waitprims-fs` | Native local-filesystem observer |
 | `waitprims-testkit` | Fake clock and scripted observers |
 | `waitprims-cli` | Diagnostic binary (`waitprims`); not on crates.io |
 
 ## Install
 
-This cut enables crates.io for the three library crates. After that
+This cut enables crates.io for the four library crates. After that
 publication, pin the minor line; do not copy a patch from this file.
 
 ```toml
-waitprims-core = "0.1"
-waitprims-async = "0.1"
-waitprims-testkit = "0.1"
+waitprims-core = "0.2"
+waitprims-async = "0.2"
+waitprims-fs = "0.2"
+waitprims-testkit = "0.2"
 ```
 
 Until the crates are on the registry, pin a git tag. The CLI is

diff --git a/docs/releases/v0.2.2.md b/docs/releases/v0.2.2.md
@@ -0,0 +1,29 @@
+# v0.2.2 — 2026-09-01
+
+Native local-filesystem observation and a diagnostic command that exercises
+it directly from a checkout.
+
+### Highlights
+
+- New `waitprims-fs` implements the existing `Observer` contract with the
+  platform-native `RecommendedWatcher`; it does not add a polling fallback.
+- Native create, write, remove, and rename notifications become minimal,
+  root-relative descriptors materialized through a caller-owned payload sink.
+- Filesystem binds fail closed on unsupported posture, unsafe path changes,
+  rescan requirements, ambiguous events for specific predicates, overflow,
+  and sink or digest failures.
+- The observer works with the existing first-match, poll-cycle, held-follow,
+  and held-coalesce runners without changing the six public wire messages.
+- Diagnostic `waitprims watch` accepts local registration and request files,
+  runs one native filesystem source, and emits the existing
+  `follow_burst` / `follow_end` JSONL views.
+- Native demo coverage runs across the supported CI platform matrix without
+  introducing a public watcher API or filesystem polling.
+
+### Upgrade notes
+
+- Workspace crates move from 0.2.1 to 0.2.2.
+- `waitprims-fs` is newly available as a library crate.
+- `waitprims-cli` remains unpublished.
+- Public JSON remains exactly the six `agent-wait/v0` message kinds.
+- Git users should pin `v0.2.2`.