Watchbound
A conservative Linux recursive directory watcher with explicit coverage, bounded resources, and joined lifecycle guarantees.
Copyright (c) 2026 by Gadi Cohen. MIT Licensed.
Intro
Watchbound is an experimental Linux-first watcher built directly on inotify. It reports conservative path invalidations and makes complete, partial, or uncertain filesystem coverage part of every result. It never silently turns resource pressure or event loss into a claim of complete coverage.
Packages are available from npm and JSR. Version history and availability come from registry metadata, Git tags, and GitHub Releases.
The checked-in source can be ahead of those immutable releases. Before using an API described on this branch, verify that the installed package's declarations and exports include it.
Contents
- Why Watchbound
- Install and start
- Support matrix
- Benchmarks
- Compare with Parcel
- Understand the contract
- Project status and documentation
- Contributing
- AI agent skill
Why Watchbound
Watchbound is for consumers that can rescan after a conservative invalidation and need explicit limits, loss reporting, and cleanup guarantees:
- Truthful coverage: every establishment, batch, and recovery result reports
complete, reasonedpartial, or reasoneduncertaincoverage - Bounded pressure: watch budgets, batch sizes, native output queues, and JavaScript callback admission are bounded and observable
- Recursive correctness: populated moved-in directories are scanned before their transition becomes observable
- Explicit recovery: overflow, topology races, backpressure, and root replacement have typed states and policy-gated recovery paths
- Joined lifecycle: establishment cancellation rolls back owned resources, and
dispose()prevents a callback from starting after its promise resolves
The API reports invalidated paths, not an exact filesystem journal. When coverage is uncertain, rescan the reported boundary instead of inferring missing create, update, delete, or rename events.
Install and start
Install the Node package with your package manager:
pnpm add watchbound
Qualify the host and root before enabling the watcher. Keep the subscription alive for the required lifetime, then join disposal during shutdown:
import { qualifyRoot, subscribe } from "watchbound";
const root = process.cwd();
const qualification = qualifyRoot(root);
if (qualification.state !== "qualified") {
throw new Error(
`Watchbound root is ${qualification.state}: ${qualification.reasons.join(", ")}`,
);
}
const subscription = await subscribe(root, (batch) => {
console.log(batch.coverage.state, batch.invalidatedPaths);
}, {
excludedDirectoryNames: [".git", "node_modules"],
observedExcludedPaths: [".git"],
});
await new Promise<void>((resolve) => process.once("SIGINT", () => resolve()));
await subscription.dispose();
Callbacks are ordered and serialized per subscription. On uncertain coverage, rescan the safe reported boundary or use the applicable recovery operation. On partial coverage, surface the ongoing blind spot or maintain a fallback; a one-time rescan does not make future coverage complete. See the API and lifecycle contract for exclusion replacement, cancellation, reconciliation, root recovery, and callback shutdown.
Support matrix
The release-qualification badge at the top reports the live main workflow. For release candidates, that workflow calls the full continuous integration (CI) matrix across every native target. GitHub exposes a workflow badge rather than one badge per matrix cell, so each check below links to the retained exact-commit qualification record.
| Target | Native package | Runtime baseline | Status |
|---|---|---|---|
| GNU/Linux x64 | @gadicc/watchbound-node-linux-x64-gnu | Node >=18.15.0, Node-API 6+, kernel 5.15+, glibc 2.35+ | ✅ Supported |
| GNU/Linux ARM64 | @gadicc/watchbound-node-linux-arm64-gnu | Node >=18.15.0, Node-API 6+, kernel 5.15+, glibc 2.35+ | ✅ Supported |
| GNU/Linux ARMv7 hard-float | @gadicc/watchbound-node-linux-arm-gnueabihf | Node >=18.15.0, Node-API 6+, ARMv7-A hard-float little-endian glibc, kernel 5.15+ | ✅ Supported |
The supported native targets remain deliberately narrow. Detected WSL and environments with recognized container evidence cannot qualify. Musl, soft-float or unknown 32-bit ARM ABIs, big-endian ARM, and non-Linux platforms fail closed.
Node support is not a tested-version allowlist. The JavaScript API requires Node 18.15.0 or newer, the native addon requires process Node-API 6 or newer, and exact CI versions are evidence points. The loader has no Node upper bound, but it retains exact target selection and all platform, ARM ABI, libc, kernel, ELF, digest, metadata, and capability checks. See the Node and Electron compatibility policy.
CI also exercises pinned Ubuntu, Debian, Fedora, Arch x64, openSUSE, Nix, kernel 5.15, representative Node and Electron releases, an ARMv7 QEMU-user Electron lifecycle lane, and a real ARMHF 5.15 kernel under system QEMU. ARMv7 execution evidence is emulated and makes no native-hardware or performance claim. The full support and qualification matrix records exact lanes, architectures, artifacts, and promotion evidence; immutable registry and release records identify what a particular published version contains.
Loading a compatible native package does not qualify the host or root. Call qualifyRoot(root) and require state === "qualified"; the runtime qualification contract explains every accepted and rejected state.
Benchmarks
The retained performance series is historical feasibility evidence, not a claim about current source performance. It compared a recorded Watchbound build, the exact configured Codex Linux JavaScript helper, and exactly @parcel/watcher 2.5.6 with its inotify backend forced.
Each cell is median subscription time in milliseconds with [min–max] across seven passing trials on tmpfs:
| Tree and phase | Watchbound | Codex JavaScript | Parcel 2.5.6 |
|---|---|---|---|
| 1,001 directories, cold | 7.20 [3.47–8.20] | 38.44 [28.77–47.00] | 5.58 [4.21–9.01] |
| 1,001 directories, warm | 7.54 [3.25–8.30] | 37.25 [31.37–42.07] | 8.58 [5.88–9.68] |
| 10,001 directories, cold | 32.31 [31.55–44.39] | 273.05 [249.56–319.78] | 49.11 [45.61–52.74] |
| 10,001 directories, warm | 36.59 [32.76–40.04] | 239.37 [184.88–380.16] | 47.42 [43.51–50.65] |
On that host and tree shape, Watchbound's 10,001-directory startup medians were 23% to 34% below Parcel's and used less incremental resident set size (RSS). The 1,001-directory cold ranges overlap, so the series does not establish a small-tree win. The source predates later runtime, delivery, exclusions, and recovery work, and tmpfs does not predict persistent-filesystem or application performance.
The separate final conformance report recorded 30 applicable Watchbound trials, all passing. CI runs a bounded benchmark smoke to catch functional regressions, but its timings are not promoted as performance evidence.
Read the complete benchmark results for memory, bursts, disposal, artifact hashes, host state, and caveats. The methodology defines pass-only aggregation, rotating adapter order, quiet-host preparation, and the safety boundary for forced overflow.
Compare with Parcel
Parcel remains the better default when its public contract is sufficient. It is mature, cross-platform, prebuilt, and exposes typed events and historical snapshot queries. Watchbound targets a narrower Linux use case with stronger resource, loss, and lifecycle semantics.
| Need | Watchbound | @parcel/watcher 2.5.6 |
|---|---|---|
| Platforms | Qualified GNU/Linux x64, ARM64, and exact ARMv7 hard-float | Broad cross-platform prebuild coverage |
| Event model | Conservative invalidated paths | Coalesced create, update, and delete events |
| Coverage and loss | Explicit complete, partial, and uncertain states | No public coverage state |
| Limits and pressure | Public watch limits, bounded queues, and accounting | No public active-watch or backpressure state |
| Exclusions | Exact-byte initial policy and atomic active replacement | Subscribe-time path and glob ignores |
| Recovery | Manual and bounded opt-in automatic reconciliation | No public reconciliation operation |
| Disposal | Idempotent join with no later callback start | Async unsubscribe() without the same public guarantee |
The comparison is scoped to Parcel's public API and reproduced Linux inotify behavior at exactly 2.5.6. It is not a claim about every Parcel backend, version, or workload. See the correctness and capability findings for source attribution and reproduced scenarios.
Understand the contract
Watchbound's central invariant is conservative coverage: detailed paths may be collapsed to a root invalidation, but lost detail is never reported as complete.
| Coverage | Meaning | Consumer action |
|---|---|---|
complete | The watcher can account for the covered topology and delivered invalidations | Process the invalidations normally |
partial | A known resource or permission limit left directories unwatched | Treat uncovered state as unavailable or change the limit |
uncertain | Overflow, topology change, root replacement, or consumer pressure may have lost detail | Rescan or invoke the applicable recovery operation |
The native addon runs inside the Node or Electron process. Filesystem traversal and engine transactions run off the JavaScript thread, but module loading, option validation, state access, and callbacks do not. Slow callbacks create bounded, subscription-local backpressure; separate Worker environments are required for independent JavaScript progress.
Subscription options support logical watch limits, a process-wide native watch budget, exact exclusions, establishment-only cancellation, bounded batches, and opt-in automatic reconciliation. Batch callbacks receive an AbortSignal and stop() request, while dispose() joins native cleanup and any callback already admitted.
Read the architecture decision record, Node binding design, structured error contract, and security and path threat model for the complete semantics.
Project status and documentation
Watchbound remains an experimental Linux-first project. The Rust engine owns filesystem semantics; the Node-API binding translates representations and lifecycle; the JavaScript package supplies the public wrapper. Consumer policy such as Git ignore rules, UI behavior, and logical workspace mapping stays outside the engine.
The source manifests use a development placeholder and remain private to prevent accidental publication. Controlled release trees materialize registry packages and versions. The maintenance policy, native delivery contract, and release runbook define those boundaries.
Use the documentation index to navigate architecture, API, qualification, benchmarks, packaging, evidence, and decision records.
Contributing
See CONTRIBUTING.md for prerequisites, repository layout, the test-driven workflow, required checks, benchmark safety, package documentation invariants, and commit conventions.
AI agent skill
This repository includes an Agent Skills-compatible Watchbound skill with package integration, coverage, lifecycle, recovery, and contributor guidance. Install it for a compatible coding agent with:
npx skills add gadicc/watchbound