feat(genome): demand-aligned-recall PR-3f — MustIncludeCandidateSource

[joelteply]

Summary

PR-3f of demand-aligned-recall. Resolves CapabilityQuery::must_include hard pins as candidates per GENOME-FOUNDRY-SENTINEL Part 7: "Hard pins — recall MUST include these in the RankedPool even if their score is low."

Plays through the composite seam (PR-3e #1380): wired AFTER WorkingSetCandidateSource with ByArtifactId dedup, must-include items that ARE resident get the working-set's Hot residency + factor data; items NOT resident get this source's NotResident placeholder (still ranked, just lower combined score).

What lands

• MustIncludeCandidateSource — zero-state unit struct (no Arc state needed; the source is pure-function over the query).
• CandidateSource::fetch impl that:
  • reads query.must_include Vec
  • maps each variant (LoRALayer / MoEExpert / Engram) to a CandidateArtifact with the appropriate PageKind
  • marks every must-include candidate as ResidencyHint::NotResident { acquirable_from: SentinelRefinement }
  • uses NEUTRAL_FACTOR_STUB (0.5) for the three non-tier factors — same convention as PR-3d

Recommended composite wiring

let composite = CompositeCandidateSource::with_default_dedup(vec![
    Arc::new(WorkingSetCandidateSource::new(mgr)),     // Hot wins
    Arc::new(MustIncludeCandidateSource::new()),       // Pins
    // future: catalog walker, federation source
]);

Spec contract met: every hard-pinned artifact surfaces; if resident, full residency-aware score; if not, still appears at lower combined so composition can see "pinned but not here — schedule the foundry."

Test plan

• cargo test --lib --features metal,accelerate genome::recall_source_must_include — 6/6 pass:
  • empty_must_include_returns_empty_candidates
  • variant_mapping_preserves_page_kind
  • must_include_marks_candidates_as_not_resident
  • factors_use_neutral_stubs_consistent_with_working_set_source
  • source_is_object_safe_for_dyn_dispatch
  • composite_with_dedup_resident_wins_must_include_for_pinned_hot_artifact — the architectural payoff: resident pin keeps Hot, non-resident pin gets NotResident, both appear in merged Vec
• No regressions across other 2873 lib tests
• Pre-push gate clean

Stack

• feat(genome): working-set-manager PR-1 — typed data layer for cache hierarchy + paging #1346 / feat(genome): working-set-manager PR-2 — WorkingSetManager + TierStore traits (+sentinel cleanup) #1353 / feat(genome): working-set-manager PR-3 — LocalWorkingSetManager per-process impl #1355 / feat(genome): working-set-manager PR-4 — canonical ArtifactKeys + bus publishing helpers #1358 / feat(genome): working-set-manager PR-5 — LocalWorkingSetManager auto-publishes via bus hook (+MessageBus borrow fix) #1362 — my working-set-manager
• feat(genome): demand-aligned-recall PR-1 — typed data layer (Part 7) #1366 — DAR PR-1: pure types
• feat(genome): demand-aligned-recall PR-2 — DemandAlignedRecall trait + composite types #1367 + fix(genome): align recall generated type names #1370 — DAR PR-2: trait + composite types
• feat(genome): demand-aligned-recall PR-3a — scoring function + per-factor curves #1371 — DAR PR-3a: scoring function + per-factor curves
• feat(genome): demand-aligned-recall PR-3b — LocalDemandAlignedRecall ranking engine #1372 — DAR PR-3b: LocalDemandAlignedRecall ranking engine
• feat(genome): demand-aligned-recall PR-3c — trait impl + CandidateSource seam #1374 — DAR PR-3c: trait impl + CandidateSource seam
• feat(genome): demand-aligned-recall PR-3d — WorkingSetCandidateSource (genome stack payoff) #1378 — DAR PR-3d: WorkingSetCandidateSource
• feat(genome): demand-aligned-recall PR-3e — CompositeCandidateSource #1380 — DAR PR-3e: CompositeCandidateSource
• This PR — DAR PR-3f: MustIncludeCandidateSource (hard-pin source)

🤖 Generated with Claude Code