pub const WATCH_SCOPE_GUIDANCE: &str = "watching requires full scope and cannot be combined with max_depth or one_filesystem: a watcher cannot filter backend events against a narrowed boundary. Selection such as depth, include, and modified_since does work while watching, because it filters the retained index rather than narrowing the scan";Expand description
Why watching cannot narrow its structural scan boundary, said once for every surface. Ignored population is a supported retained-scope choice because control edits reconcile the governing directory and rebuild that population.
The CLI used to carry this guidance and the library carried “requires event-scope filtering”, which names the implementation rather than the caller’s next move – so a library caller hitting the same wall got jargon and the CLI user got help. Two messages for one rule also drift, and the parity harness could not tell they were the same rule.
The knobs are named by the calling surface: --scan-depth on the command line,
max_depth through the API. Everything else is identical, so the harness can verify
mechanically that both surfaces state the same rule.