The public top-level crate of the tributaries filesystem-notification stack:
overlapping watch subscriptions, subsumed onto disjoint kernel roots and attributed
back to every covering subscriber.
Introduction
tributary-fs deliberately watches only disjoint roots (it rejects a new root
that overlaps an existing one) because subsuming overlapping trees is the layer
above's job. tributaries is that layer. It:
- accepts possibly-overlapping watch subscriptions from the caller and
subsumes them into the disjoint roots
tributary-fsrequires — N overlapping subscriptions collapse to one kernel watch of their common ancestor; - attributes each raw event back to every caller subscription that covers its path, retagged with that subscription's id;
- offers optional consumer conveniences — a filter and an opt-in settle/debounce coalescer — without touching the hardened core.
Everything hard (identity, move-pairing, loss-is-a-Rescan, epoch dominance) already
lives in the tributary-proto Monitor and ships through tributary-fs's own
event type; tributaries adds routing and consumer ergonomics, not new correctness
logic.
The local-filesystem binding — FsSource, the RootHandle / WatcherOptions
re-exports, the pure-fs constructor and runtime aliases — rides the fs feature, on
by default. With it off, the crate is the generic core over tributary-proto alone:
bring your own Source (or LocalSource) and construct through
Tributaries::with_source / Tributaries::parts / Tributaries::parts_local.
Installation
[]
= { = "0.1", = ["tokio"] }
The minimum supported Rust version (MSRV) is 1.95 (edition 2024).
Quick start
Watch possibly-overlapping paths — each under its own per-watch WatchOptions
(interest, Filter, Debounce posture) — optionally settle bursts with a
DebounceConfig, and pull the merged, attributed stream. Each event is retagged with
the Subscription it belongs to, so one change under an overlap is delivered to every
covering subscription under its own id.
#
# async
Subsumption
The subsumption engine is the control plane: a sans-I/O state machine over an
iradix radix keyed by canonical root paths. It plans each watch into one of three
cases — the subtree is already covered, the new path widens over existing roots
(which are drained and re-pointed onto it), or it is disjoint — keeping the live root
set pairwise disjoint at all times. It is pure logic over paths and an abstract
root-id, so it is exhaustively property-tested with no real filesystem, clock, or
runtime.
Settle / debounce (opt-in)
A caller that only cares about the settled state of a file — not every intermediate
write of an editor-save or a cp — can opt into the coalescer by setting a
DebounceConfig on TributariesOptions. It is a second sans-I/O state machine: it
buffers attributed events per (subscription, path) and collapses a burst to a single
emission on a settle timer, while treating a Moved atomically and flushing on a
Rescan so coverage loss is never held back or lost.
The global config is a per-subscription default: each watch can override its own
posture with a Debounce on its WatchOptions — Debounce::Off for raw pass-through
while siblings settle, Debounce::Custom for its own windows (which also enables
settling when the global debounce is off). Absent a DebounceConfig and absent any
Custom override, events pass through untouched at zero cost.
Hosting on a !Send runtime
The umbrella runs on thread-per-core / completion-based apps (compio, a pinned
LocalSet) in either of two shapes:
- A
Sendsource, a!Sendapp (the common case — the fs source isSend): spawn ONE auxiliary thread running any supported runtime, build there viaTributaries::parts, and poll the returned driver future on it. The whole handle plane is executor-agnostic and thread-mobile —TributariesisClone + Send,WatchViewis a cheapClone + Send + Syncread handle,SubscriptionisCopy— sowatch/unwatch/next/closeare awaitable from the!Sendapp directly; only the driver lives on the auxiliary thread.Demux::partsreturns aSendrouting future that can be hosted on either side. - A
!Sendsource (thread-local state, anRc, a ring handle): implementLocalSourceinstead ofSourceand construct viaTributaries::parts_local; the returned driver future is!Sendand must be polled on the thread that owns the source (block_on,LocalSet::run_until, or the executor's own local API).
Do not reach for agnostic-lite's spawn_local* for either shape: its smol
local spawner panics (smol has no ambient thread-local executor to target) and its
tokio one panics outside a LocalSet. Poll the future directly, or use the host
executor's own local-spawn API.
Feature flags
fs(default) — the local-filesystem binding overtributary-fs. Off, the crate is the generic core overtributary-protoalone, and a custom-Sourceconsumer skips the whole fs stack.tokio/smol— the async runtime, throughagnostic-lite. Orthogonal tofs: they gate the driver'sTokioTributaries/SmolTributariesaliases and forward the runtime intotributary-fsonly when the fs binding is enabled too. The sans-I/O engines need no runtime.
The family
tributaries (this crate — the consumer surface) · tributary-fs (the std
async filesystem source) · tributary-proto (the pure no_std Sans-I/O state
machine).
The identity and coordinate primitives — ChangeId, Epoch, Location, Segment —
are owned by tributary-proto and re-exported from here directly. The per-watch
Interest is not among them: the umbrella owns its own source-neutral mask
(aligned to its EventKind), and the proto/fs Interest stays a purely fs-internal
arm mask for consumers driving a raw fs watcher.
License
tributaries is dual-licensed under the terms of both the MIT license and the
Apache License (Version 2.0).
See LICENSE-APACHE, LICENSE-MIT for details.
Copyright (c) 2026 Al Liu.