Keep file-watch observation from serializing unrelated IO

Scope open-registration and rename/remove ordering to overlapping paths;
let descriptor mutations and directory creation proceed without that lock.
Prove blocked opens/writes cannot stall unrelated namespaces, including a
queued rename, and retain post-rename descriptor notifications. Document
handler-owned watch lifetimes and narrow paths; test natural idle exit.

Card: SAU-359
This commit is contained in:
SAU-359 implementer
2026-10-30 21:06:10 +00:00
parent ff6fc62f05
commit 0c1ef74f6e
5 changed files with 336 additions and 19 deletions
+9 -2
View File
@@ -267,8 +267,15 @@ name visible files. External host writes are outside this contract.
Changes may coalesce, including a change already visible in the initial
scan, but a change after the last notification always produces another.
Delivery holds no filesystem locks. The watch ends with its caller; there
is no cancellation API or polling/retry loop.
Delivery holds no filesystem locks. Observation does not serialize descriptor
IO; only overlapping opens and rename/removal wait for one another.
Watch the narrowest useful path: delivery is not rate-limited, so watching a
busy parent can cause a rescan for every write.
The watch ends with its caller; there is no cancellation API or polling/retry
loop. SDK callers should poll the watch future alongside their handler's work
and drop it on return, not keep it in a background task that prevents an idle
process from exiting. Dropping the future does not cancel the host watch.
## 5. Endpoints