Janady13/missionmatch / internal/modules/matching/convert.go

1// Package matching is the SHARED SCORING CORE: the single source of truth for every Match and Mission 2// Readiness number in the product. It loads candidates and requirements from the DB, runs the pure 3// engine (internal/modules/matching/engine, the frozen weights and bands), and persists the 4// explainable result. The engine stays pure; THIS package owns the DB<->engine boundary, including 5// enum encode/decode (engine.Code/Parse) and the clearance expiry as of date rule. 6// 7// Today every scoring surface is served by the one flat handler in this package (handler.go). The 8// three tool separation splits that handler into screenMATCH, slateMATCH, and missionMATCH routers, 9// and each tool MUST keep calling these same service methods rather than re implement scoring: 10// - screenMATCH: Screen, ScreenCandidate, RankCandidates, and the Mission Check flow (single 11// candidate and pool qualification). 12// - slateMATCH: GenerateSlate, DecideSlateMember, SlateMemberTrace (proposal slates). 13// - missionMATCH: CandidateIntelligence here, plus the commandcenter rollups that read the persisted 14// slates and evaluations rather than recompute them. 15// 16// Because there is exactly one scoring path, the same candidate shows the same numbers in every tool. 17// The frozen weights and bands are guarded by engine.TestFrozenScoringConstants, the values are locked 18// by engine.TestGoldenScoringSnapshot, and the cross tool equality is proven by the integration test 19// TestSharedCoreScoresIdenticalAcrossTools. Do not add a second scoring path to any tool. 20package matching 21 22import ( 23 "encoding/json" 24 "fmt" 25 "time" 26 27 "github.com/google/uuid" 28 "github.com/jackc/pgx/v5/pgtype" 29 30 "github.com/missionworkforce/missionmatch/internal/modules/matching/engine" 31 "github.com/missionworkforce/missionmatch/internal/modules/matching/intelligence" 32 "github.com/missionworkforce/missionmatch/internal/platform/database/dbgen" 33) 34 35// ClearanceFactsFrom builds the intelligence ClearanceFacts (with the clearance dates the engine 36// omits) from a DB candidate row plus its loaded customer agencies. Codes are CHECK constrained at 37// the DB so parsing always succeeds for a stored row. 38func ClearanceFactsFrom(c dbgen.Candidate, customerAgencies []string) intelligence.ClearanceFacts { 39 level, _ := engine.ParseClearanceLevel(c.ClearanceLevel) 40 poly, _ := engine.ParsePolygraph(c.ClearancePoly) 41 status, _ := engine.ParseClearanceStatus(c.ClearanceStatus) 42 return intelligence.ClearanceFacts{ 43 Level: level, 44 Poly: poly, 45 Status: status, 46 GrantedAt: datePtr(c.ClearanceGrantedAt), 47 ExpiresAt: datePtr(c.ClearanceExpiresAt), 48 ReinvestigationDueAt: datePtr(c.ReinvestigationDueAt), 49 CustomerAgencies: customerAgencies, 50 Provenance: c.ClearanceProvenance, 51 VerifiedAt: c.ClearanceVerifiedAt, 52 } 53} 54 55func datePtr(d pgtype.Date) *time.Time { 56 if !d.Valid { 57 return nil 58 } 59 t := d.Time 60 return &t 61} 62 63// ToEngineCandidate maps a DB candidate (+ its loaded skills/certs/customer experience) into the 64// pure engine input. asOf is the evaluation date: clearance_expires_at is the source of truth, so an 65// Active flag with a past expiry is treated as Expired (review COMPL-1). It NEVER reads a demographic 66// field, there is none on the candidate row by design (AEDT). 67func ToEngineCandidate(c dbgen.Candidate, skills []dbgen.ListCandidateSkillsRow, certs, custExp []string, asOf time.Time) (engine.Candidate, error) { 68 level, err := engine.ParseClearanceLevel(c.ClearanceLevel) 69 if err != nil { 70 return engine.Candidate{}, fmt.Errorf("candidate %s: %w", c.ID, err) 71 } 72 poly, err := engine.ParsePolygraph(c.ClearancePoly) 73 if err != nil { 74 return engine.Candidate{}, fmt.Errorf("candidate %s: %w", c.ID, err) 75 } 76 status, err := engine.ParseClearanceStatus(c.ClearanceStatus) 77 if err != nil { 78 return engine.Candidate{}, fmt.Errorf("candidate %s: %w", c.ID, err) 79 } 80 status = effectiveStatus(status, c.ClearanceExpiresAt, asOf) 81 82 es := make([]engine.CandidateSkill, len(skills)) 83 for i, s := range skills { 84 es[i] = engine.CandidateSkill{SkillID: s.ID.String(), Name: s.Name} 85 } 86 87 return engine.Candidate{ 88 ID: c.ID.String(), 89 Clearance: engine.Clearance{Level: level, Poly: poly, Status: status}, 90 Skills: es, 91 Certifications: certs, 92 CustomerExperience: custExp, 93 YearsExperience: int(c.YearsExperience), 94 Location: deref(c.Location), 95 Remote: c.Remote, 96 Relocatable: c.Relocatable, 97 Available: c.Available, 98 }, nil 99} 100 101// effectiveStatus downgrades an Active clearance to Expired when its expiry date has passed as of the 102// evaluation date. The date column is authoritative over the stored flag. The comparison is on the 103// CIVIL DATE (asOf truncated to midnight UTC of its Y/M/D) so a clearance expiring exactly on the 104// as of day is still effective, matching the Command Center's `clearance_expires_at >= as_of::date` 105// byte for byte regardless of the wall clock time carried by asOf [review ENGINE-1/EN-1]. 106func effectiveStatus(stored engine.ClearanceStatus, expires pgtype.Date, asOf time.Time) engine.ClearanceStatus { 107 asOfDate := time.Date(asOf.Year(), asOf.Month(), asOf.Day(), 0, 0, 0, 0, time.UTC) 108 if stored == engine.StatusActive && expires.Valid && expires.Time.Before(asOfDate) { 109 return engine.StatusExpired 110 } 111 return stored 112} 113 114// ToEngineRequirement maps a DB requirement (+ its required skills/certs) into the pure engine input. 115func ToEngineRequirement(r dbgen.Requirement, reqSkills []dbgen.ListRequiredSkillsRow, reqCerts []string) (engine.Requirement, error) { 116 level, err := engine.ParseClearanceLevel(r.RequiredLevel) 117 if err != nil { 118 return engine.Requirement{}, fmt.Errorf("requirement %s: %w", r.ID, err) 119 } 120 poly, err := engine.ParsePolygraph(r.RequiredPoly) 121 if err != nil { 122 return engine.Requirement{}, fmt.Errorf("requirement %s: %w", r.ID, err) 123 } 124 125 rs := make([]engine.RequiredSkill, len(reqSkills)) 126 for i, s := range reqSkills { 127 rs[i] = engine.RequiredSkill{SkillID: s.ID.String(), Name: s.Name, Mandatory: s.Mandatory} 128 } 129 130 return engine.Requirement{ 131 ID: r.ID.String(), 132 RequiredLevel: level, 133 RequiredPoly: poly, 134 RequiredSkills: rs, 135 RequiredCerts: reqCerts, 136 CustomerAgency: deref(r.CustomerAgency), 137 RequiredYears: int(r.RequiredYears), 138 WorkLocation: deref(r.WorkLocation), 139 RemoteAllowed: r.RemoteAllowed, 140 KeyPersonnel: r.KeyPersonnel, 141 }, nil 142} 143 144// ToSlateMemberParams freezes an engine result into the AEDT decision record. Band is the DB Code() 145// (never String()), and the full trace + gap summary are persisted as jsonb so the decision is 146// reproducible and explainable. 147func ToSlateMemberParams(orgID, slateID, candidateID uuid.UUID, res engine.MatchResult, rank *int32) (dbgen.AddSlateMemberParams, error) { 148 trace, err := json.Marshal(res.Trace) 149 if err != nil { 150 return dbgen.AddSlateMemberParams{}, fmt.Errorf("marshal decision trace: %w", err) 151 } 152 gaps := []byte("[]") 153 if len(res.GapSummary) > 0 { 154 if gaps, err = json.Marshal(res.GapSummary); err != nil { 155 return dbgen.AddSlateMemberParams{}, fmt.Errorf("marshal gap summary: %w", err) 156 } 157 } 158 159 return dbgen.AddSlateMemberParams{ 160 OrganizationID: orgID, 161 SlateID: slateID, 162 CandidateID: candidateID, 163 TotalScore: res.Total, 164 Band: res.Band.Code(), 165 ClearanceScore: res.Clearance, 166 SkillsScore: res.Skills, 167 CertsScore: res.Certifications, 168 CustomerScore: res.CustomerExperience, 169 ExperienceScore: res.Experience, 170 LocationScore: res.Location, 171 Explanation: res.Explanation, 172 Trace: trace, 173 GapSummary: gaps, 174 Rank: rank, 175 ModelVersion: strPtr(engine.ModelVersion), 176 }, nil 177} 178 179func strPtr(s string) *string { return &s } 180 181// ToCandidateEvaluationParams builds the upsert params for the persisted screenMATCH qualification of 182// one candidate against one requirement. It is the same frozen MatchResult the slate stores, shaped 183// for the candidate_evaluations table (the stored artifact missionMATCH reads). evaluatedBy is the 184// actor or nil. Like the slate member, the band is the stored CODE (never String()) and the matched 185// skills and gap summary are persisted as jsonb so the stored evaluation stays explainable. 186func ToCandidateEvaluationParams(orgID, candidateID, requirementID uuid.UUID, res engine.MatchResult, evaluatedBy *uuid.UUID) (dbgen.UpsertCandidateEvaluationParams, error) { 187 matched := []byte("[]") 188 if len(res.MatchedSkills) > 0 { 189 m, err := json.Marshal(res.MatchedSkills) 190 if err != nil { 191 return dbgen.UpsertCandidateEvaluationParams{}, fmt.Errorf("marshal matched skills: %w", err) 192 } 193 matched = m 194 } 195 gaps := []byte("[]") 196 if len(res.GapSummary) > 0 { 197 g, err := json.Marshal(res.GapSummary) 198 if err != nil { 199 return dbgen.UpsertCandidateEvaluationParams{}, fmt.Errorf("marshal gap summary: %w", err) 200 } 201 gaps = g 202 } 203 return dbgen.UpsertCandidateEvaluationParams{ 204 OrganizationID: orgID, 205 CandidateID: candidateID, 206 RequirementID: requirementID, 207 TotalScore: res.Total, 208 Band: res.Band.Code(), 209 ClearanceScore: res.Clearance, 210 SkillsScore: res.Skills, 211 CertsScore: res.Certifications, 212 CustomerScore: res.CustomerExperience, 213 ExperienceScore: res.Experience, 214 LocationScore: res.Location, 215 Explanation: res.Explanation, 216 MatchedSkills: matched, 217 GapSummary: gaps, 218 ModelVersion: engine.ModelVersion, 219 EvaluatedBy: evaluatedBy, 220 }, nil 221} 222 223func deref(s *string) string { 224 if s == nil { 225 return "" 226 } 227 return *s 228} 229