Module source 

Picker source registry (metadata layer).

Each picker source — files, recent, lines, marks, lsp-references, … — registers a PickerSourceSpec into a PickerRegistry at boot. The registry powers three things:

1. :picker <Tab> completion. The cmdline source-id completion mode iterates the registry and surfaces every registered source as a candidate.
2. Source-arg completion. Once the source id is resolved, arg-2+ completion consults the source’s [ArgSpec::completion] hooks — same gen:* completion sources every other ex-command uses.
3. :describe-picker introspection. Walks the registry to render :describe-picker (and :describe-picker <id> for per-source detail).

The registry only holds metadata at this stage. The PickerSourceGenerator trait (slice 4 in docs/dev/architecture/picker.md) elevates the registry to hold generator trait objects so source dispatch is registry- driven end-to-end. Today the App still owns the source_id → method dispatch table; the registry just supplies the names + arg schemas the grammar needs.

WIT mirror (Phase 7)

When the plugin host lands, WIT-imported sources register their spec record into the same PickerRegistry. Plugin sources are indistinguishable from first-party at the registry level — both appear under :picker <Tab> and flow through the same dispatch.

The registry interface is therefore deliberately small: register, get, iter. Nothing host-specific leaks in.

Structs

PickerRegistry

Registry of every picker source the :picker <id> ex-command can dispatch to. Populated at boot by each feature crate’s register_picker_sources entry point.

PickerSourceSpec

Static metadata describing one picker source.

RegistryEntry

Registry entry: either metadata-only (slice 12 path, retained for tab-completion of source ids whose generator isn’t yet wired) or metadata + generator (the canonical slice 13 path – dispatch resolves the generator from here).

Enums

PickerInitResult

Three init shapes covering every Phase 4-8 picker pattern. The choice is per-invocation – a single source can return different shapes depending on args (e.g. a future grep source could Inline an empty result on empty pattern, Stream otherwise).

Traits

PickerSourceGenerator

Source generators implement this trait. Registered into PickerRegistry at boot; the :picker <source> dispatcher looks up by spec().id and calls init to obtain candidates, then accept to translate the user’s chosen routing payload into a typed outcome.

Type Aliases

AcceptFuture

One-shot async future a source returns from accept_async when translating the chosen routing payload requires off-thread work — the motivating case is a WASM plugin source whose accept is an async guest call bound to its actor task (lattice-plugin-host). Same 'static + Send contract as CandidateFuture: the source extracts everything it needs (the projected context, the routing token) during the synchronous accept_async prelude and moves it into the closure.

CandidateBatch

One batch of (candidate, routing payload) pairs from a source. Identical shape across all three init flavors; the host’s seat / append paths use it uniformly.

CandidateFuture

One-shot async future a source returns when the candidate set requires off-thread work (LSP request, large directory walk, etc.). 'static + Send because the source extracted everything it needs from the context during the synchronous init call and moved it into the closure.

CandidateStream

Streaming source channel. Sources spawn a producer task during init and return the receiver; the host pumps each batch into the picker incrementally so the popup updates as results arrive (live-grep, future live-LSP-completion).

PickerRegistryHandle

The runtime-mutable registry handle the editor holds and shares as a service. ArcSwap gives wait-free reads on the picker-open path and copy-on-write RCU writes for runtime plugin-source registration (:plugin-load / boot-discovery): clone the current registry, register_generator / unregister, then store the new snapshot. The plugin loader (lattice-plugin-loader) reaches this via service::<PickerRegistryHandle>() and RCU-registers each loaded picker plugin’s WasmPickerSource.

SourceResult

Source-side fallible result. Errors are user-facing strings the host echoes verbatim. Wrapping in Result<...,String> rather than a typed error keeps the WIT mirror (Phase 7) trivial – plugin-emitted errors cross the boundary as strings.