[#4253 1/8] feat(pe): core selection engine Select + MatchReport

[stevenvegt]

Parent PRD

#4253

Item 1 of 8. Foundation for the credential-selection rewrite. Also folds in the developer-diagnostics work from #4218 (this MatchReport supersedes the logging approach in closed PR #4225).

Summary

Introduce the new pure matching engine pe.Select in vcr/pe, with structured diagnostics (MatchReport). Select is consolidated: it owns the whole matching pipeline in three steps: (1) find which credentials match each descriptor's constraints and format; (2) search for a combination of credentials whose shared-id field values agree; (3) apply the PD's submission-requirement rules (pick/all/min/max) to that combination, reusing the existing groups()/apply()/deduplicate() helpers. No existing caller is changed in this PR; the engine is exercised entirely by a new black-box test suite. Item #3 then rewires Match onto Select and deletes matchConstraints/matchBasic/matchSubmissionRequirements/MatchWithSelector and the CredentialSelector abstraction.

Design note (decided during implementation): the engine is consolidated, not layered. Once Select receives the whole PD it can derive everything it needs from the PD itself, including which descriptors are allowed to go unfilled, so there is no reason for the caller to compute and pass that. Floor-aware pick min>=1 cooperation stays out of scope (PRD #4253 "Out of Scope"); Select uses a simple skip rule.

Implementation Spec

Surface (all new, in vcr/pe)

type SelectionStrategy int
const (
    FirstMatch SelectionStrategy = iota // default ("loose"): take the first consistent assignment
    Strict                              // ErrMultipleCredentials on a second consistent assignment
)

type Option func(*selectOptions)
func WithInitialBindings(b map[string]string) Option // seed id->value (credential_selection)
func WithStrategy(s SelectionStrategy) Option
func WithSelectionTrace() Option                     // populate Result.Report; default off

func Select(pd PresentationDefinition, candidates []vc.VerifiableCredential, opts ...Option) (Result, error)

type Result struct {
    Candidates []Candidate        // reuse existing type; VC == nil => descriptor unfilled (skipped, or dropped by a submission-requirement rule)
    Bindings   map[string]string  // resolved id->value of the chosen assignment
    Report     *MatchReport       // non-nil only when WithSelectionTrace() is set
}

Bindings is map[string]string, reusing the value stringification already in matchesSelections (selector.go).

Algorithm (three steps)

Step 1: match each descriptor on its own. For each input descriptor, evaluate every candidate credential via the existing matchConstraint (presentation_definition.go:400) + matchFormat, with no cross-descriptor binding yet. Record pass/fail and, on fail, the reason (no value / filter / format). No new field-matching logic.

Step 2: search for a consistent combination (depth-first over the matching credentials, in PD order):

• Binding consistency (P3, always on): a candidate is consistent only if its id-bearing resolved values agree with the running bindings. Seed from WithInitialBindings; keys not present as field ids on this PD are dropped.
• Backtracking + optional skip (P4): try every consistent candidate; a required descriptor with no consistent candidate fails the branch and backtracks; an optional descriptor is skipped (VC=nil) only after its candidates are exhausted. Whether a descriptor may be left unfilled is derived from pd.SubmissionRequirements with a simple rule: with no submission requirements every descriptor is required; otherwise a descriptor is optional when its group can be satisfied without it.
• Unresolved optional doesn't bind (P6): a candidate's optional:true field that resolves to no value contributes no binding. Initial bindings are stricter (decided 2026-07-14): a candidate for a descriptor whose field id appears in the initial bindings must resolve that field to the bound value; unresolved optional fields are rejected for that descriptor (preserves legacy matchesSelections semantics).
• Ambiguity (P5): see strategies below.
• Scale (decided 2026-07-14): eligible pools are hash-indexed by their id-bearing values, so binding-consistency filtering is a lookup, not a scan; large homogeneous wallets (20k per-patient credentials) cost a hash join, linear in wallet size. The search carries a node-visit cap (order 1e6) and aborts with an error naming the PD when hit, because PDs are counterparty-supplied in wallet flows and an unbounded search would be remotely triggerable CPU exhaustion.

Step 3: apply the submission-requirement rules. Select passes the step-2 combination to the existing groups()/apply()/deduplicate() helpers (rule logic unchanged) to enforce the PD's pick/all/count/min/max/nested rules and produce the final selection; a descriptor dropped by a rule ends with VC=nil. The descriptor-map / JSON-path formatting that matchBasic and matchSubmissionRequirements did is not part of Select; it moves to the thin Match wrapper in item #3. The simple skip rule from step 2 can disagree with exact rule satisfaction in the deferred pick min>=1 case; that limitation is documented and now lives in one place.

Selection strategies

The engine always enforces binding consistency (P3), backtracking/optional-skip (P4), and unresolved-optional-doesn't-bind (P6). The strategy controls only what happens when more than one complete, binding-consistent assignment exists:

• FirstMatch (default): return the first assignment. This is the lenient, backward-compatible behavior. For any PD that does not reuse an id across descriptors it reproduces today's matcher, including NewFieldSelector's ErrMultipleCredentials when a caller-bound descriptor still resolves to more than one binding tuple. Matches identical on every declared field id are interchangeable and first-picked (decided 2026-07-15: the PD is the data contract; only declared fields reach token introspection, and multi-value filters such as issuer patterns are deliberate equivalence declarations). The one deliberate loosening vs. today: a reissued duplicate no longer fails a caller-bound request; diverging credentialSubjects among interchangeable matches are flagged in the MatchReport instead.
• Strict: a second complete consistent assignment is ErrMultipleCredentials (Policy 5), naming the ambiguous descriptors so the caller can add disambiguating selection keys. Strict supersedes FirstMatch. Rivals are counted per distinct binding tuple, not per credential tuple (decided 2026-07-14): credentials identical in every id-bearing value are interchangeable, never ambiguous (no credential_selection key could separate them; the engine picks the first). This also keeps Strict uniqueness proofs cheap on wallets holding many interchangeable credentials.

Policy 5 (ambiguity-as-error) is the behavior-risk to be aware of. It is the only rule here that can turn a previously-succeeding match into an error: a descriptor with several equally-valid credentials that the caller did not disambiguate is silently first-picked today but errors under Strict. That is exactly why it is gated behind the strategy rather than always on. By contrast Policy 3 (same-id agreement) is always on but safe — it only affects PDs that reuse an id across descriptors, which is a new pattern with no deployed users.

Strategy is an input, not parsed here (scope)

Select takes a SelectionStrategy value and honors it. How that value is chosen is out of scope for this PR. The intent is to declare it per-PD at the config layer (policy credentialProfileConfig / discovery ServiceDefinition), defaulting to FirstMatch ("loose") and flipped to Strict in a future major release — but parsing and registration of that config land in items #5/#7. This PR only defines the enum and makes the engine behave correctly for each value.

MatchReport (diagnostics; supersedes closed PR #4225)

type MatchReport struct {
    Descriptors          []DescriptorReport // one per input descriptor, in PD order
    Outcome              Outcome            // matched | no_credentials | multiple_credentials
    AmbiguousDescriptors []string           // descriptor ids carrying >1 choice (multiple_credentials only)
}
type DescriptorReport struct {
    DescriptorID string
    Optional     bool
    Considered   []CandidateReport // every candidate VC evaluated against this descriptor
    SelectedID   string            // chosen credential id; "" if skipped/unfilled
    Skipped      bool
}
type CandidateReport struct {
    CredentialID string
    Eligible     bool       // passed this descriptor's constraints + format
    Dismissal    *Dismissal // why it wasn't used; nil when selected
}
type Dismissal struct {
    Reason   DismissalReason
    FieldID  string // constraint/binding reasons, when known
    Path     string // JSON path evaluated (constraint reasons)
    Expected string // filter const/type, or the bound value (binding conflict)
    Found    string // value found; "" = none
    Message  string // pre-rendered human-readable line (lazy, only under trace)
}
type DismissalReason string
const (
    ReasonNoValue         DismissalReason = "constraint_no_value"
    ReasonFilter          DismissalReason = "constraint_filter"
    ReasonFormat          DismissalReason = "format_mismatch"
    ReasonBindingConflict DismissalReason = "binding_conflict"
    ReasonNotSelected     DismissalReason = "not_selected"
)

Populated only under WithSelectionTrace() (Message rendered lazily, so a non-trace run pays nothing). Trace depth: step-1 (per-descriptor) dismissals recorded fully; binding conflicts recorded on the decisive path (the chosen assignment, or the conflicts that caused failure/ambiguity), not every backtracking visit. No surface (endpoint/UI) in this PR — consuming the report is a follow-up to #4218.

Testing

Black-box select_test.go, no mocks or on-disk fixtures. Two buckets:

• Characterization (proves equivalence before Add error handling middleware to echo server #3 rewires callers): FirstMatch+bindings reproduces the TestNewFieldSelector matrix (single/multi-field AND, multi-descriptor, type conversions string/float64/bool, zero-match -> unfilled); FirstMatch with no bindings reproduces FirstMatchSelector; an all-required PD reproduces matchBasic (every descriptor must fill, else ErrNoCredentials); a representative submission-requirements PD reproduces matchSubmissionRequirements (all, and pick with min/max); ErrNoCredentials cases.
• New policies: P3, P4, P5 (both strategies), P6 worked examples from the PRD; trace on/off asserting MatchReport contents for a dismissed VC and for an ambiguity; the two-VP composition pattern (two Select calls chained through a bindings filter).
• Scale and contract edges (added 2026-07-14): interchangeable credentials (identical binding tuples) are not ambiguous under Strict while distinct binding tuples are; the node-visit cap aborts a crafted exponential PD with a clear error; Result.Candidates keeps one entry per input descriptor, in PD order, on every error path; format gating (PD-level and descriptor-level) and nil-Constraints descriptors are covered.

Exhaustive submission-requirement rule cases stay in submission_requirement_test.go (the apply() logic is unchanged) and the integration-level TestMatch suites; #1 adds only representative satisfaction characterization, not a full duplication.

Acceptance Criteria

• Select with functional options as specified; Result reuses Candidate.
• P3/P4/P6 always on; P5 gated by Strict; FirstMatch is the default.
• Characterization tests prove FirstMatch reproduces both FirstMatchSelector and NewFieldSelector behavior.
• Select applies submission-requirement rules by reusing groups()/apply()/deduplicate(); whether a descriptor may go unfilled is derived from pd.SubmissionRequirements.
• Characterization tests prove FirstMatch also reproduces matchBasic (all-required) and matchSubmissionRequirements (all/pick/min/max).
• MatchReport populated only under WithSelectionTrace(), with the specified reasons and decisive-path conflict narration.
• Ambiguity counted per distinct binding tuple; interchangeable credentials never error.
• Caller-bound multiplicity counted per binding tuple; both consent scenarios pinned (declared field errors, undeclared field first-picks); diverging interchangeable alternatives flagged in MatchReport.
• Initial bindings require resolution (legacy field-selector semantics); P6 leniency covers only search-accumulated bindings.
• Eligible pools are hash-indexed; node-visit cap aborts pathological searches with a clear error.
• Result.Candidates is full length (one entry per descriptor, PD order) on every path, including errors.
• No caller or behavior changes outside vcr/pe; existing vcr/pe tests still green.
• go build ./... and go test ./vcr/pe/... pass.

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on feature/4253-credential-selection by 0.16%.

Modified Files with Diff Coverage (3)

Rating	File	% Diff	Uncovered Line #s
	vcr/pe/presentation_definition.go	66.7%	434-438
	vcr/pe/match_report.go	97.0%	246-247, 279-280
	vcr/pe/select.go	92.9%	150-151, 231-234...
	Total	93.1%

🤖 Increase coverage with AI coding...

In the `4253-1-select-engine` branch, add test coverage for this new code:

- `vcr/pe/match_report.go` -- Lines 246-247 and 279-280
- `vcr/pe/presentation_definition.go` -- Line 434-438
- `vcr/pe/select.go` -- Lines 150-151, 231-234, 373-374, 458-459, 514, 552, 555, 567-568, 578-579, 589-595, 640-641, 713-714, and 732-733

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.