Module source_registration 

Unified source registration — slice 3c.unify.picker-generator-trait-unify (7a).

Defines the shapes that picker, cmdline-completion, and (post-WASM-host) plugins all use to register a candidate source. The design comes out of the LSP cross-check in docs/dev/architecture/completion-pipeline-unification.md § “LSP cross-check: the design that survives”.

Status

Slice 7a lands the shapes: traits, enums, the SourceRegistration bundle. No first-party source migration yet (that’s 7b); no registry integration (that’s 7c); no :picker <name> cutover (that’s 7d). This file exists so 7b can migrate against a stable target.

End-state architecture

lattice-completion::
    CandidateGenerator      // existing — pull-based source
    AcceptHandler           // NEW — stateless accept dispatch
    AcceptAction            // NEW — what the host should do on accept
    CandidateSourceKind     // NEW — pull (Generator) vs push (PreSupplied)
    SourceRegistration      // NEW — the bundle: generator/accept/spec/overrides
    SourceSpec              // NEW — metadata (id, doc, args-schema, live flag)

lattice-picker::
    PickerSourceGenerator   // KEEPS WORKING during migration
    // First-party sources will impl CandidateGenerator + AcceptHandler;
    // PickerSourceGenerator becomes a deprecated thin adapter,
    // then retires once 7d cuts the registry over.

Structs

AcceptToken

Opaque marker the host uses to find the right pending_* table for a stateful AcceptAction. v1: a u64 that the host generates per-LSP-request; the LSP cache keys on the same token. Plugins use the same scheme for their own pending tables.

ArgsSchema

Opaque positional-arg schema. v1 placeholder — description string. A future slice can grow this to a typed validator (number of required args, whether trailing args are allowed, etc.).

CustomAcceptPayload

Opaque payload for AcceptAction::Custom. Wrapper exists to give AcceptAction Debug + Clone impls that don’t require the inner type to expose those bounds.

DefaultAcceptHandler

Default handler: reads RawCandidate::accept_action set at candidate-build time. Covers every picker source whose candidates carry their action directly — which is the expected case after slice 7b.

SourceRegistration

The substrate: bundle of every input the pipeline needs to produce + dispatch a source’s candidates.

SourceSpec

Metadata for a source. Returned by the source-registration’s spec field; used for :describe-picker / :picker <Tab> / :apropos introspection.

Enums

AcceptAction

What the host should do when the user accepts a candidate. Cleanup-and-rename of today’s lattice_picker::RoutingPayload plus new variants for cmdline-completion (InsertText) and plugin extensibility (Custom).

CandidateSourceKind

How candidates flow into the pipeline. Picker calls have two shapes (per the LSP cross-check): synchronous enumeration (gen:files walks the FS per filter) vs. push-from-async (LSP picker host-builds rows from an async response before opening the picker).

Traits

AcceptHandler

Translate a chosen candidate into a typed action the host dispatches. Stateless: the handler reads the candidate, the host runs the action. State lookup for indexed variants (LSP completion / code-actions / etc.) happens at dispatch time inside the host, where Editor::pending_*_items is in scope.