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

1package matching 2 3import ( 4 "context" 5 "encoding/json" 6 "fmt" 7 "strings" 8 "time" 9 10 "github.com/google/uuid" 11 "github.com/jackc/pgx/v5" 12 13 "github.com/missionworkforce/missionmatch/internal/modules/matching/engine" 14 "github.com/missionworkforce/missionmatch/internal/platform/audit" 15 "github.com/missionworkforce/missionmatch/internal/platform/database/dbgen" 16) 17 18// missioncheck.go is the W1 Mission Check application surface. It parses a resume (and, in Mode B, a 19// pasted job description) IN MEMORY, scores it through the single engine.ScoreCandidate path with the 20// same injected matcher every other surface uses, records ONE ephemeral AEDT audit row, and stores 21// nothing. No candidate is created and no resume text is persisted unless the user explicitly saves. 22 23// MissionCheckOpportunities is Mode A: an in memory resume scored against every open opportunity, ranked 24// by Mission Readiness, each row carrying the derived advisory. It writes only ephemeral audit rows. 25func (s *Service) MissionCheckOpportunities(ctx context.Context, resumeText string, limit int) (MissionCheckModeAResult, error) { 26 if s.db == nil { 27 return MissionCheckModeAResult{}, ErrNoDatabase 28 } 29 if s.extractor == nil { 30 return MissionCheckModeAResult{}, ErrNoExtractor 31 } 32 if limit <= 0 || limit > 100 { 33 limit = 10 34 } 35 rx, err := s.extractor.ExtractResume(ctx, resumeText) 36 if err != nil { 37 return MissionCheckModeAResult{}, fmt.Errorf("extract resume: %w", err) 38 } 39 if !rx.HasSignal() { 40 return MissionCheckModeAResult{}, ErrBadRequest 41 } 42 ec := engineCandidateFromExtraction(rx) 43 44 rows := []MissionCheckFitRow{} 45 err = s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 46 fits, err := s.rankOpenOpportunities(ctx, tx, ec, limit, func(res engine.MatchResult) error { 47 return s.auditOnTx(ctx, tx, ephemeralScoreEvent("missionCheck.opportunities", res)) 48 }) 49 if err != nil { 50 return err 51 } 52 rows = make([]MissionCheckFitRow, len(fits)) 53 for i, f := range fits { 54 rec := recommendFromBandCode(f.Band) 55 rows[i] = MissionCheckFitRow{OpportunityFitView: f, Recommendation: rec.Value, RecommendationReason: rec.Reason} 56 } 57 return nil 58 }) 59 if err != nil { 60 return MissionCheckModeAResult{}, err 61 } 62 return MissionCheckModeAResult{ 63 Rows: rows, Candidate: parsedCandidateFromExtraction(rx), 64 Assumptions: missionCheckAssumptions, DataCategories: missionCheckDataCategories, 65 }, nil 66} 67 68// MissionCheckJD is Mode B: an in memory resume scored against one pasted job description, once. It 69// returns the EXACT ScreenView /screen returns so the result ties out, plus the derived advisory. It 70// writes only one ephemeral audit row and persists nothing. 71func (s *Service) MissionCheckJD(ctx context.Context, resumeText, jdText string) (MissionCheckModeBResult, error) { 72 if s.db == nil { 73 return MissionCheckModeBResult{}, ErrNoDatabase 74 } 75 if s.extractor == nil { 76 return MissionCheckModeBResult{}, ErrNoExtractor 77 } 78 rxC, err := s.extractor.ExtractResume(ctx, resumeText) 79 if err != nil { 80 return MissionCheckModeBResult{}, fmt.Errorf("extract resume: %w", err) 81 } 82 rxR, err := s.extractor.ExtractRequirement(ctx, jdText) 83 if err != nil { 84 return MissionCheckModeBResult{}, fmt.Errorf("extract requirement: %w", err) 85 } 86 if !rxC.HasSignal() || !rxR.HasSignal() { 87 return MissionCheckModeBResult{}, ErrBadRequest 88 } 89 ec := engineCandidateFromExtraction(rxC) 90 er := engineRequirementFromExtraction(rxR) 91 asOf := s.clock() 92 93 var view ScreenView 94 var rec Recommendation 95 err = s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 96 res := engine.ScoreCandidate(ctx, ec, er, s.matcher) 97 view = assembleScreenView(ec, er, res, factsFromExtraction(rxC), asOf) 98 rec = RecommendFromBand(res.Band) 99 // Fail closed: an AEDT score that cannot be recorded is not returned (the served score contract). 100 return s.auditOnTx(ctx, tx, ephemeralScoreEvent("missionCheck.screen", res)) 101 }) 102 if err != nil { 103 return MissionCheckModeBResult{}, err 104 } 105 return MissionCheckModeBResult{ 106 View: view, Recommendation: rec.Value, RecommendationReason: rec.Reason, 107 Candidate: parsedCandidateFromExtraction(rxC), 108 Requirement: parsedRequirementFromExtraction(rxR), 109 Assumptions: missionCheckAssumptions, DataCategories: missionCheckDataCategories, 110 }, nil 111} 112 113// ephemeralScoreEvent records a Mission Check served score with NO candidate id and NO PII. It uses a 114// DISTINCT action (aedt.ephemeral.evaluated, never aedt.score.served) so an ephemeral check never enters 115// the four fifths served score denominator the compliance pool joins to a demographic bucket: an 116// ephemeral check has no candidate row and therefore no bucket. The payload carries only the tool, the 117// score, the band, the derived advisory, the model version, and the advisory and persisted flags. Never 118// put a name, email, or resume text in the payload or the entity id. 119func ephemeralScoreEvent(tool string, res engine.MatchResult) audit.Event { 120 rec := RecommendFromBand(res.Band) 121 payload, _ := json.Marshal(map[string]any{ 122 "tool": tool, 123 "score": res.Total.StringFixed(2), 124 "band": res.Band.Code(), 125 "recommendation": rec.Value, 126 "model_version": engine.ModelVersion, 127 "advisory": true, 128 "persisted": false, 129 }) 130 return audit.Event{Action: "aedt.ephemeral.evaluated", EntityType: "mission_check", EntityID: "", NewValues: payload} 131} 132 133// SaveCandidateInput is the reviewed, structured candidate the user chose to persist from a Mission 134// Check result. Clearance is the self reported parse the user confirmed, never a verified value. 135type SaveCandidateInput struct { 136 FullName string 137 ClearanceLevel string 138 ClearancePoly string 139 ClearanceStatus string 140 YearsExperience int 141 Location string 142 Remote bool 143 Relocatable bool 144 Available bool 145 Skills []string 146 Certifications []string 147 CustomerExperience []string 148} 149 150// SaveCandidate creates a candidate from a reviewed Mission Check result in ONE transaction: the 151// candidate row, its skills (skill names upserted into the ontology, the only place Mission Check writes 152// the ontology, and only on an explicit save), certifications, and customer experience, then a 153// candidate.created audit row. It fails closed: any error, including an unwritable audit row, rolls the 154// whole record back. Clearance is stored as the self reported indicator the user confirmed. 155func (s *Service) SaveCandidate(ctx context.Context, in SaveCandidateInput) (uuid.UUID, error) { 156 if s.db == nil { 157 return uuid.Nil, ErrNoDatabase 158 } 159 if strings.TrimSpace(in.FullName) == "" { 160 return uuid.Nil, ErrBadRequest 161 } 162 var newID uuid.UUID 163 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 164 q := dbgen.New(tx) 165 org, err := s.orgID(ctx) 166 if err != nil { 167 return err 168 } 169 cand, err := q.CreateCandidate(ctx, dbgen.CreateCandidateParams{ 170 OrganizationID: org, 171 FullName: strings.TrimSpace(in.FullName), 172 ClearanceLevel: validLevelCode(in.ClearanceLevel), 173 ClearancePoly: validPolyCode(in.ClearancePoly), 174 ClearanceStatus: validStatusCode(in.ClearanceStatus), 175 YearsExperience: int32(clampYears(in.YearsExperience)), 176 Location: nilIfEmpty(in.Location), 177 Remote: in.Remote, 178 Relocatable: in.Relocatable, 179 Available: in.Available, 180 }) 181 if err != nil { 182 return fmt.Errorf("create candidate: %w", err) 183 } 184 for _, name := range dedupeNonEmpty(in.Skills) { 185 sk, err := q.UpsertSkill(ctx, dbgen.UpsertSkillParams{Name: name}) 186 if err != nil { 187 return fmt.Errorf("upsert skill: %w", err) 188 } 189 if err := q.AddCandidateSkill(ctx, dbgen.AddCandidateSkillParams{OrganizationID: org, CandidateID: cand.ID, SkillID: sk.ID}); err != nil { 190 return fmt.Errorf("add candidate skill: %w", err) 191 } 192 } 193 for _, name := range dedupeNonEmpty(in.Certifications) { 194 if err := q.AddCandidateCertification(ctx, dbgen.AddCandidateCertificationParams{OrganizationID: org, CandidateID: cand.ID, Name: name}); err != nil { 195 return fmt.Errorf("add candidate certification: %w", err) 196 } 197 } 198 for _, agency := range dedupeNonEmpty(in.CustomerExperience) { 199 if err := q.AddCandidateCustomerExperience(ctx, dbgen.AddCandidateCustomerExperienceParams{OrganizationID: org, CandidateID: cand.ID, Agency: agency}); err != nil { 200 return fmt.Errorf("add candidate customer experience: %w", err) 201 } 202 } 203 newID = cand.ID 204 return s.auditOnTx(ctx, tx, audit.Event{Action: "candidate.created", EntityType: "candidate", EntityID: cand.ID.String()}) 205 }) 206 return newID, err 207} 208 209// SetClearanceProvenance records HOW a candidate's clearance is known (an org FSO action). It validates 210// the provenance code, stamps verified_at for an actual verification (the supplied date, else now) and 211// clears it for self_reported, and audits the change fail closed. The platform never verifies a 212// clearance itself; this records the org's authoritative assertion so ranking and the UI stay honest. 213func (s *Service) SetClearanceProvenance(ctx context.Context, candidateID uuid.UUID, provenance string, verifiedAt *time.Time) error { 214 if s.db == nil { 215 return ErrNoDatabase 216 } 217 if !validProvenance(provenance) { 218 return ErrBadRequest 219 } 220 var va *time.Time 221 switch { 222 case provenance == "self_reported": 223 va = nil // a self reported indicator is not a verification 224 case verifiedAt != nil: 225 va = verifiedAt 226 default: 227 now := s.clock() 228 va = &now 229 } 230 return s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 231 n, err := dbgen.New(tx).SetCandidateClearanceProvenance(ctx, dbgen.SetCandidateClearanceProvenanceParams{ 232 ID: candidateID, ClearanceProvenance: provenance, ClearanceVerifiedAt: va, 233 }) 234 if err != nil { 235 return fmt.Errorf("set clearance provenance: %w", err) 236 } 237 if n == 0 { 238 return ErrNotFound 239 } 240 payload, _ := json.Marshal(map[string]any{"provenance": provenance}) 241 return s.auditOnTx(ctx, tx, audit.Event{Action: "candidate.clearance_provenance.set", EntityType: "candidate", EntityID: candidateID.String(), NewValues: payload}) 242 }) 243} 244 245func validProvenance(p string) bool { 246 switch p { 247 case "self_reported", "sponsor_verified", "document", "continuous_vetting": 248 return true 249 default: 250 return false 251 } 252} 253 254// validLevelCode, validPolyCode, and validStatusCode clamp a self reported clearance code to a value the 255// DB CHECK constraint accepts, defaulting to the fail safe Unknown or None on anything unrecognized so a 256// malformed code can never be stored or score as a held clearance. 257func validLevelCode(code string) string { 258 if _, err := engine.ParseClearanceLevel(code); err == nil { 259 return code 260 } 261 return "unknown" 262} 263 264func validPolyCode(code string) string { 265 if _, err := engine.ParsePolygraph(code); err == nil { 266 return code 267 } 268 return "none" 269} 270 271func validStatusCode(code string) string { 272 if _, err := engine.ParseClearanceStatus(code); err == nil { 273 return code 274 } 275 return "unknown" 276} 277 278func clampYears(y int) int { 279 if y < 0 { 280 return 0 281 } 282 if y > 60 { 283 return 60 284 } 285 return y 286} 287 288func nilIfEmpty(s string) *string { 289 s = strings.TrimSpace(s) 290 if s == "" { 291 return nil 292 } 293 return &s 294} 295 296func dedupeNonEmpty(items []string) []string { 297 seen := map[string]bool{} 298 out := make([]string, 0, len(items)) 299 for _, it := range items { 300 t := strings.TrimSpace(it) 301 if t == "" { 302 continue 303 } 304 k := strings.ToLower(t) 305 if seen[k] { 306 continue 307 } 308 seen[k] = true 309 out = append(out, t) 310 } 311 return out 312} 313