Module scan 

The scan layer: walking a tree, producing observations, and applying reconciliation.

Public scans emit upsert observations, and a revalidation sweep is the diff between what the index believes and what the filesystem says. Both speak the same Observation vocabulary as the watch layer. A detached one-shot index may consume equivalent parent-first directory groups privately because no observer can see its construction; every later mutation still crosses the shared observation boundary.

Status

The portable read_dir plus non-following metadata reference is what every listing falls back to. Parallel scans use it on most platforms; on macOS they first try a measured getattrlistbulk backend that returns directory entries and stat-tier metadata together. Unsupported filesystems, malformed results, mount points, and firmlinks fail closed to the portable path for the complete containing directory. On Linux with glibc every route that lists a directory (the serial and concurrent walks, revalidation, reconciliation, opened discovery) first tries a reader that lists with raw getdents64 and stats with statx against the listing’s descriptor, passing AT_NO_AUTOMOUNT; an open or enumeration failure, a malformed record, or a kernel without statx falls back the same way, and the fallback’s own stats then pass the flag too (observe_dir_entry), as does every stat of a path a route verifies by itself (observe_path). Only the walk root is resolved through a mount (root_device). So an autofs tree answers the same on every route and delivery. Every backend produces the same Observation contract.

Structs

ReconcileReport

Filesystem and index effects from an applying reconciliation pass.

ScanBackendDiagnostics

Directory enumeration backends used by one scan.

ScanConfig

Knobs for a scan.

ScanDiagnostics

Opt-in, run-scoped evidence about a filesystem scan.

ScanReport

What a scan did, including the errors it walked past.

WalkAttribution

Where a walk’s time went, so “blocked” is never one undifferentiated number.

WorkerPolicyDiagnostics

Worker-controller configuration, trace, and terminal queue state.

WorkerPolicyWindow

One controller evaluation over a half-open range of completed entry ordinals.

Enums

ScanOrder

The order directories are visited in.

WorkerPolicyDecision

Decision represented by a WorkerPolicyWindow.

WorkerPolicyOutcome

Final state of the automatic worker controller.

Constants

MAX_SCAN_BATCH_SIZE

Largest producer batch accepted before work must be published incrementally.

SCAN_DIAGNOSTICS_SCHEMA

Schema carried by ScanDiagnostics.

WATCH_SCOPE_GUIDANCE

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.

Functions

observe

Read an entry’s kind and roll-up attributes out of its metadata.

reconcile

Reconcile the full index and publish each exact commit as it lands.

reconcile_handle

Reconcile a shared index while allowing readers between applied batches.

reconcile_pending

Drain and reconcile every pending invalidation, collapsing nested requests.

reconcile_pending_handle

Drain and reconcile invalidations on a shared index.

reconcile_subtree

Reconcile one relative subtree, applying effective changes during the walk.

reconcile_subtree_handle

Reconcile one subtree of a shared index, widening to a missing/non-directory ancestor when necessary.

revalidate

Diff the filesystem against an existing index and emit conditional observations.

scan

Walk root and emit observations describing everything found.

scan_into_index

Walk root and return a fully populated index.

scan_into_index_with_diagnostics

Walk root into an index and retain the opt-in diagnostic trace for that run.

scan_with_diagnostics

Walk root, emitting observations and a bounded run-scoped diagnostic trace.