Module candidate_version 

Immutable candidate versions: identity, pathname, mode, change and object per path. What: An immutable candidate version: the paths one Git state changes, each with its identity, mode and object. Why: Every policy of one pass must judge the same files. A version is listed once and then only read, so path metadata is shared instead of re-queried, and a later fix or replay produces a new version instead of altering this one.

In TS you’d write (pseudocode):

type CandidateVersion = { readonly candidates: readonly Candidate[] };

Structs

Candidate

What: One changed path of a version. Vec<u8> is an owned byte list (sibling String would require UTF-8). Option<ObjectId> is “an object name or nothing”. Why: Git pathnames are arbitrary bytes on Unix and are kept exactly. A deleted path has no object, which the type states.

CandidateIdentity

What: The identity of one candidate within one invocation. u64 is an unsigned 64-bit counter (siblings u32, usize); usize is the unsigned integer every index uses. Why: Identity must not be derived from the pathname, which the scanner may mask. The generation tells a candidate of an invalidated version from a current one; u64 cannot run out within a process. The index is the candidate’s position in its version, and usize is what indexing and the scanner take.

CandidateVersion

What: The candidates of one listed state. Fields are private: a version is built once by build_version and never changed. Why: Immutability is what lets several policies share one listing safely.

Enums

CandidateSource

What: Which Git state a version lists, and what it is compared with. #[derive(...)] generates cloning, debug printing and ==. Why: A commit being prepared is judged by what is staged; a landed commit by what it changed. Naming the comparison makes the version reproducible.

Functions

build_version

What: Build a version from listing records, keeping the first record of each pathname. Vec<CandidateRecord> is taken by value: the records’ bytes move into the version without being copied. Why: A merge commit lists one comparison per parent, so a pathname can appear more than once; the first appearance decides, as it did in the TypeScript wrapper.