Crate fdu 

The fdu command line, and the engine it is built on.

The command line lives here and depends on fdu_core the way any consumer does, so crate:: does not reach the engine: anything the command line needs is public API, and the compiler decides that on every build rather than a reviewer deciding it in review.

The engine is re-exported, so cargo add fdu gives a library caller the whole API and there is one name to know for both installing the tool and depending on it.

Modules

admission

Fixed rules that decide which filesystem facts belong in an index.

cache

Inspecting and clearing the snapshot cache.

classify

File-type recognition.

content

Optional, versioned file-content analysis.

control

Bounded, removal-aware control state used to classify retained filesystem facts.

counters

Low-distortion performance instrumentation for fdu.

query

Queries over a built index: what to select, which roll-ups to report, and the value grammars both are written in.

report_format

Serializing a Report to text, JSON, JSONL, and YAML.

scan

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

snapshot

Persisting an index to disk and reading it back.

watch

Th OS-native watch layer: turning an unreliable event stream into verified observations.

watch_session

A live session: an index, a watcher, and the query they answer together.

Structs

AnalyzerProvenance

The analyzers a content tier’s records were produced by, and the options they ran with.

ApplyOutcome

Result of arbitrating and applying one producer observation.

ApplyStats

Summary of what one Index::apply call did.

Attrs

The stat fields an entry contributes to roll-ups, plus the ones that identify it.

Batch

One batch of applied changes.

CachePaths

The two files for one canonical root key in an application cache directory.

CacheStatus

What is known about one file in the cache directory.

Change

One effective change, already filtered through the run’s selection.

ChangePoll

Result of one opened-root journal poll.

ChangeRequest

Input to one blocking opened-root journal poll.

ChildSnapshot

One direct child captured from a shared index at a single read boundary.

ClearSummary

What one clear removed.

Clock

A monotonic logical clock, in the spirit of Watchman’s clockspec but process-local.

Commit

One atomic, exact index transition.

ContentAdmission

Proof that stored content can be projected to one requested identity.

ContentInfo

The header facts that identify a content sidecar.

ContentStatus

What is known about the content sidecar beside a snapshot.

ContentTierIdentity

Identity of a content tier: the per-file analysis records a sidecar holds.

ContinuationId

Opaque identifier for resumable work retained by one opened root.

ControlIdentity

Stable, non-sensitive identity of one retained control source.

ControlLimits

The two bounds on the control state one index retains, each liftable on its own.

ControlMatcher

A path-bound view over the controls that may govern it.

ControlObservation

The control files an observing index applied and refused.

ControlTable

Exact .gitignore sources and parsed matchers, keyed by governing directory.

DiscoveryBudget

Resource bounds applied to progressive discovery.

DiscoveryProgress

Committed, bounded discovery counters.

EngineVersion

Identity and exact sequence of one committed opened-root state.

EntryId

Identifier for an entry within an Index arena.

EntryScope

Which entries a scan retains: its depth, symlink, filesystem-boundary, hidden-entry, and special-object settings.

EntryTierIdentity

Identity of an entry tier: the entries a store holds and the roll-ups derived from them.

EntryValue

One immutable retained entry returned by an opened-root read.

ExtTally

Per-extension tally within a roll-up.

Fingerprint

The fingerprint used to decide whether an entry really changed.

FlatPage

One portable flat-entry page.

HiddenPolicy

Whether leading-dot path components are retained.

Impact

Bounded invalidation guidance derived from exact effective changes.

Index

The in-memory hierarchical index.

IndexHandle

Shareable owner for serving readers while reconciliation applies short writes.

IndexState

Coherent public state captured at an index commit boundary.

Issue

Bounded diagnostic evidence retained with an index state.

IssueSummary

Counts for the bounded issue details captured with a state.

Observation

A producer batch awaiting arbitration by the index.

ObservationOp

One observed operation together with its arbitration precondition.

OpenOptions

Configuration for a long-lived OpenedIndex.

OpenReport

What open did.

OpenedIndex

A long-lived, synchronously controlled filesystem index.

PageRequest

Output and work bounds for one resumable page.

PartitionRollUp

The two fixed aggregate partitions maintained for inventory reads.

PartitionRollUpSummary

Constant-size totals for the fixed all and unignored partitions.

PathExpectation

State and entry revisions captured at one observation boundary.

PendingSave

A snapshot write running alongside rendering.

PerformanceSummary

Operational work behind one one-shot report.

Plan

Validated policy shared by all engine execution routes.

PortablePath

A retained entry’s canonical POSIX-relative name, in the form ordered pages use.

Progress

A handle a route reports its progress through.

ProgressSnapshot

What a route has done so far, as read at one moment.

Provenance

Everything a consumer needs to decide how far to trust one value.

QueryLimit

Typed bounded-query result; no partial calculation is presented as exact.

ReadDiagnostics

Fixed-size diagnostics captured with a coherent read.

ReadRequest

Input to one coherent opened-root read.

ReadResponse

One coherent opened-root response.

ReconcileReport

Filesystem and index effects from an applying reconciliation pass.

RefreshResult

Result of one bounded, multi-path refresh.

RefusedControl

One control file whose rules an index refused, relative to the index root.

RejectedRefreshPath

One refresh path that the engine declined, with its typed reason.

ReportRequest

The read half of a request at an opened root, plus one read’s work bound.

RollUp

Pre-computed aggregate state for one directory’s entire subtree.

RollUpSummary

Constant-size directory totals suitable for bounded interactive rows.

ScanConfig

Knobs for a scan.

ScanReport

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

ScanScope

Semantic inputs that decide which entries and derived values belong in an index.

SemanticIdentity

Answer-semantics identity derived from validated classification and reducer rules.

Session

An index paired with a watcher, answering one request continuously.

SessionId

Opaque identity of one opened-root lifetime.

Since

Result of Index::since.

SnapshotIdentity

The identity of every tier a metadata snapshot holds.

SnapshotInfo

The header facts that identify a snapshot.

TreePage

One structural page of a directory’s descendants, to the requested depth.

Work

Bounded work performed while committing producer input or serving engine reads.

Enums

CachePolicy

Whether a request may read and write the snapshot cache.

CacheScope

Which snapshots a cache-lifecycle request covers.

CacheState

What a path in the cache holds.

ChangeKind

What happened to a path.

ChangeOutcome

Journal outcome at one coherent terminal version and state.

ContentState

What a content sidecar beside a snapshot holds.

ControlAdmission

What a control table did with one verified control source.

ControlCoverage

Whether an index’s ignore classification applies every control file in its scope.

ControlRefusalReason

Which of the ControlLimits refused a control source instead of applying its rules.

ControlTierIdentity

Identity of a .gitignore control tier.

CountResult

Product count whose exactness is explicit.

Coverage

Structural coverage of one opened root.

CoverageReason

Why an opened root cannot claim complete structural coverage.

EffectiveChange

One exact fact mutation performed by the index.

EntryKind

What kind of filesystem entry a record describes.

Error

Errors the engine can report.

Expectation

The condition under which an observation may be committed.

Freshness

Trust state for an index or queried subtree.

ImpactDomain

A stable fdu-native answer domain that one commit may have made stale.

InvalidateReason

Why a producer had to escalate to Op::InvalidateSubtree instead of describing a change precisely.

IssueKind

Stable category for one non-fatal condition or terminal provider failure.

Knowledge

Three-valued knowledge for a path lookup.

LeftoverKind

Which of fdu’s own files a leftover is.

LifecyclePhase

Current activity of one opened root.

LimitedProjection

Projection whose deterministic work allowance was exhausted.

Load

Which persisted state execution may read.

Op

A single change to one path.

OpenPath

Which tier of the freshness ladder an open actually used.

OutcomeClass

Whether an answer fulfills the caller’s delivery contract.

PathState

The complete indexed state of one path at an observation boundary.

ProgressPhase

Which kind of work a route is doing.

ProjectionRefusal

Why one projection of a read refused, while every other projection still answered.

ProjectionResult

One projection result, in the same position as its request.

ReadProjection

One fdu-native projection requested under a coherent read boundary.

RefreshRejection

Why one requested refresh path was not verified.

Route

The engine lifecycle that will deliver an answer.

RowShape

Retained fields copied into portable page rows.

SaveOutcome

The result of a throttled attempt to persist a live session.

ScanOrder

The order directories are visited in.

Serves

How a stored tier answers a request.

Source

Where a value came from, so a consumer can trade speed for certainty knowingly.

StaleReason

Why a snapshot fdu wrote cannot be served by this build.

StateTransition

One observable transition that did not change a retained filesystem entry.

Status

Whether a value covers everything beneath its path.

Verify

Whether execution must verify the filesystem.

Constants

CONTROL_FILE_NAME

Name of the fixed control file understood by the first engine version.

DEFAULT_CONTROL_BUDGET

Default retained control-table charge for one index, in bytes.

DEFAULT_CONTROL_LINE_LIMIT

Default longest line a control source may hold, in bytes.

DEFAULT_COUNT_CAP

Default cap for a selection count not backed by an exact maintained aggregate.

DEFAULT_JOURNAL_CAPACITY_BYTES

Approximate bytes the exact commit history used by Index::since may retain.

MAX_CONTINUATION_RECORD_BYTES

Maximum retained payload for one handle-local continuation record.

MAX_COUNT_CAP

Maximum caller-selected cap for an on-demand aggregate.

MAX_DIRTY_PATHS

Maximum number of individual dirty paths retained in one commit.

MAX_ISSUE_MESSAGE_BYTES

Maximum UTF-8 bytes retained in one rendered issue message.

MAX_ISSUE_PATH_BYTES

Maximum native encoded bytes retained for one issue path.

MAX_PAGE_ROWS

Maximum rows returned by one page projection.

MAX_PAGE_WORK

Maximum deterministic work allowance accepted by one page projection.

MAX_PRIORITY_PATHS

Maximum paths accepted by one best-effort priority request.

MAX_READ_PROJECTIONS

Maximum native projections accepted by one coherent read.

MAX_REFRESH_PATHS

Maximum paths accepted by one refresh operation.

MAX_REPORT_VIEWS

Maximum report sections and reported omissions accepted in one opened read.

MAX_RETAINED_ISSUES

Maximum issue details retained by one index image.

MIN_JOURNAL_CAPACITY_BYTES

Smallest journal budget, in bytes, an opened root accepts.

Functions

cache_status

Read one cache file’s status without materializing its index.

clear_all_caches

Remove every fdu snapshot in a cache directory, current or stale, and reclaim the files fdu left behind, leaving anything else alone.

clear_cache

Remove one snapshot, current or stale, with its content sidecar.

default_cache_dir

The application cache directory, resolved independently of a scanned root.

default_cache_path

Conventional metadata snapshot path for callers without an explicit destination.

default_cache_path_in

The conventional metadata snapshot location for a root in the resolved directory.

is_control_file

Whether a relative path names the fixed control file: the canonical path every control operation, and the table, name a directory’s rules by.

list_caches

Enumerate every entry in the cache directory.

open

Open a tree, using the snapshot cache when one is usable.

open_with_pending_save

Open a tree, returning the snapshot write for the caller to join.

plan

Validate a request and derive the least-retention plan for its delivery and route.

prepare_report

Execute a one-shot report, retaining the least state the request needs.

prepare_report_with_progress

Execute a one-shot report, reporting its progress through progress as it runs.

prepare_report_with_scan_diagnostics

Execute a one-shot report and retain scan diagnostics.

refresh

Reverify a retained index, refresh requested content, and persist according to delivery.

run_process

Run fdu through its real process boundary and return its stable numeric exit code.

serves_snapshot

Whether a snapshot of the stored identity answers a request for wanted.

throughput_rates

Cumulative walk rates over one actual elapsed sample. The byte rate is binary GiB/s, rounded to three decimals; the grouped file rate counts complete files per second. Returns (files_per_second, gib_per_second) without unit labels, or None when elapsed time is zero. Neither rate estimates storage read bandwidth.

Type Aliases

Result

Result alias for engine operations.