Module candidate 

Candidate value types that flow through the completion pipeline (DESIGN.md §5.11.3).

Three shapes, one per pipeline stage:

• RawCandidate – output of a generator. Insertion text + kind + structured payload.
• ScoredCandidate – after the matcher: RawCandidate + score + the byte ranges the matcher considered “matched” (vertico’s match-face highlights these).
• RenderedCandidate – after annotators: above + a vec of typed Annotations the renderer paints to the right of each candidate (MARG.1, see docs/dev/architecture/marginalia.md).

Three shapes (not one with optional fields) so the type system enforces stage ordering: a generator produces only RawCandidates; a matcher produces only ScoredCandidates; annotators only mutate RenderedCandidates. Pipeline order can’t accidentally invert.

Structs

AnnotationColumns

MARG.5 (2026-06-03): pre-computed per-category column layout for the picker / completion annotation column. The renderer builds one of these from the visible candidate set, then renders each row against it — every row’s annotation cells line up vertically because each column width is the max across visible candidates and rows that don’t have a particular category render a blank cell of the same width.

AnnotationSegment

MARG §8: one run of marginalia text sharing a theme slot, the unit of an Annotation::Styled cell. slot is a theme element name the renderer resolves at paint time (unknown slot → the custom/plugin annotation color); it is NEVER a baked color, so a :colorscheme swap recolors it live on both peers.

CacheKey

Cache key for crate::CandidateGenerator::cache_key. Treated as opaque by the caching layer; semantic meaning is per-generator.

DisplaySpan

PH.1: a syntax-styled run within a candidate’s display text. Carries a semantic Style (a closed enum with an existing Style → ElementId map), NOT a resolved color — the renderer resolves it via resolve_syntax_style at paint so :colorscheme recolors live, mirroring the Annotation::Styled carry-semantic / resolve-at-seam invariant (marginalia §3 / §8.2). range is a byte range into display.

MatchScore

Score the matcher assigned. Higher is better; 0 means “doesn’t match” (and the candidate is filtered out before it becomes a ScoredCandidate).

RawCandidate

Output of a generator. The pipeline passes these through the matcher next.

RenderedCandidate

What the renderer paints. Annotators append to annotations; the renderer paints each typed Annotation with the style that category resolves to, joined by two spaces of row-styled padding. MARG.1 (2026-06-03): replaced Vec<String> with Vec<Annotation> so annotation category survives into the paint path.

ScoredCandidate

A RawCandidate plus the matcher’s verdict. Survives the match stage; consumed by the ranker and (in turn) the annotators.

Enums

Annotation

One annotation attached to a completion candidate.

CandidateData

Generator-supplied metadata travelling alongside the candidate. Annotators read this to produce display text without re-querying the underlying registry. Plugin generators stash their own payload in Extension (msgpack on the wire when WASM lands).

CandidateKind

What kind of thing this candidate is. Drives icon / colour / grouping in the popup, and (for CommandKind) hints at the follow-up :describe-* target.