package matching import ( "context" "encoding/json" "fmt" "strings" "time" "github.com/google/uuid" "github.com/jackc/pgx/v5" "github.com/missionworkforce/missionmatch/internal/modules/matching/engine" "github.com/missionworkforce/missionmatch/internal/platform/audit" "github.com/missionworkforce/missionmatch/internal/platform/database/dbgen" ) // missioncheck.go is the W1 Mission Check application surface. It parses a resume (and, in Mode B, a // pasted job description) IN MEMORY, scores it through the single engine.ScoreCandidate path with the // same injected matcher every other surface uses, records ONE ephemeral AEDT audit row, and stores // nothing. No candidate is created and no resume text is persisted unless the user explicitly saves. // MissionCheckOpportunities is Mode A: an in memory resume scored against every open opportunity, ranked // by Mission Readiness, each row carrying the derived advisory. It writes only ephemeral audit rows. func (s *Service) MissionCheckOpportunities(ctx context.Context, resumeText string, limit int) (MissionCheckModeAResult, error) { if s.db == nil { return MissionCheckModeAResult{}, ErrNoDatabase } if s.extractor == nil { return MissionCheckModeAResult{}, ErrNoExtractor } if limit <= 0 || limit > 100 { limit = 10 } rx, err := s.extractor.ExtractResume(ctx, resumeText) if err != nil { return MissionCheckModeAResult{}, fmt.Errorf("extract resume: %w", err) } if !rx.HasSignal() { return MissionCheckModeAResult{}, ErrBadRequest } ec := engineCandidateFromExtraction(rx) rows := []MissionCheckFitRow{} err = s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { fits, err := s.rankOpenOpportunities(ctx, tx, ec, limit, func(res engine.MatchResult) error { return s.auditOnTx(ctx, tx, ephemeralScoreEvent("missionCheck.opportunities", res)) }) if err != nil { return err } rows = make([]MissionCheckFitRow, len(fits)) for i, f := range fits { rec := recommendFromBandCode(f.Band) rows[i] = MissionCheckFitRow{OpportunityFitView: f, Recommendation: rec.Value, RecommendationReason: rec.Reason} } return nil }) if err != nil { return MissionCheckModeAResult{}, err } return MissionCheckModeAResult{ Rows: rows, Candidate: parsedCandidateFromExtraction(rx), Assumptions: missionCheckAssumptions, DataCategories: missionCheckDataCategories, }, nil } // MissionCheckJD is Mode B: an in memory resume scored against one pasted job description, once. It // returns the EXACT ScreenView /screen returns so the result ties out, plus the derived advisory. It // writes only one ephemeral audit row and persists nothing. func (s *Service) MissionCheckJD(ctx context.Context, resumeText, jdText string) (MissionCheckModeBResult, error) { if s.db == nil { return MissionCheckModeBResult{}, ErrNoDatabase } if s.extractor == nil { return MissionCheckModeBResult{}, ErrNoExtractor } rxC, err := s.extractor.ExtractResume(ctx, resumeText) if err != nil { return MissionCheckModeBResult{}, fmt.Errorf("extract resume: %w", err) } rxR, err := s.extractor.ExtractRequirement(ctx, jdText) if err != nil { return MissionCheckModeBResult{}, fmt.Errorf("extract requirement: %w", err) } if !rxC.HasSignal() || !rxR.HasSignal() { return MissionCheckModeBResult{}, ErrBadRequest } ec := engineCandidateFromExtraction(rxC) er := engineRequirementFromExtraction(rxR) asOf := s.clock() var view ScreenView var rec Recommendation err = s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { res := engine.ScoreCandidate(ctx, ec, er, s.matcher) view = assembleScreenView(ec, er, res, factsFromExtraction(rxC), asOf) rec = RecommendFromBand(res.Band) // Fail closed: an AEDT score that cannot be recorded is not returned (the served score contract). return s.auditOnTx(ctx, tx, ephemeralScoreEvent("missionCheck.screen", res)) }) if err != nil { return MissionCheckModeBResult{}, err } return MissionCheckModeBResult{ View: view, Recommendation: rec.Value, RecommendationReason: rec.Reason, Candidate: parsedCandidateFromExtraction(rxC), Requirement: parsedRequirementFromExtraction(rxR), Assumptions: missionCheckAssumptions, DataCategories: missionCheckDataCategories, }, nil } // ephemeralScoreEvent records a Mission Check served score with NO candidate id and NO PII. It uses a // DISTINCT action (aedt.ephemeral.evaluated, never aedt.score.served) so an ephemeral check never enters // the four fifths served score denominator the compliance pool joins to a demographic bucket: an // ephemeral check has no candidate row and therefore no bucket. The payload carries only the tool, the // score, the band, the derived advisory, the model version, and the advisory and persisted flags. Never // put a name, email, or resume text in the payload or the entity id. func ephemeralScoreEvent(tool string, res engine.MatchResult) audit.Event { rec := RecommendFromBand(res.Band) payload, _ := json.Marshal(map[string]any{ "tool": tool, "score": res.Total.StringFixed(2), "band": res.Band.Code(), "recommendation": rec.Value, "model_version": engine.ModelVersion, "advisory": true, "persisted": false, }) return audit.Event{Action: "aedt.ephemeral.evaluated", EntityType: "mission_check", EntityID: "", NewValues: payload} } // SaveCandidateInput is the reviewed, structured candidate the user chose to persist from a Mission // Check result. Clearance is the self reported parse the user confirmed, never a verified value. type SaveCandidateInput struct { FullName string ClearanceLevel string ClearancePoly string ClearanceStatus string YearsExperience int Location string Remote bool Relocatable bool Available bool Skills []string Certifications []string CustomerExperience []string } // SaveCandidate creates a candidate from a reviewed Mission Check result in ONE transaction: the // candidate row, its skills (skill names upserted into the ontology, the only place Mission Check writes // the ontology, and only on an explicit save), certifications, and customer experience, then a // candidate.created audit row. It fails closed: any error, including an unwritable audit row, rolls the // whole record back. Clearance is stored as the self reported indicator the user confirmed. func (s *Service) SaveCandidate(ctx context.Context, in SaveCandidateInput) (uuid.UUID, error) { if s.db == nil { return uuid.Nil, ErrNoDatabase } if strings.TrimSpace(in.FullName) == "" { return uuid.Nil, ErrBadRequest } var newID uuid.UUID err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { q := dbgen.New(tx) org, err := s.orgID(ctx) if err != nil { return err } cand, err := q.CreateCandidate(ctx, dbgen.CreateCandidateParams{ OrganizationID: org, FullName: strings.TrimSpace(in.FullName), ClearanceLevel: validLevelCode(in.ClearanceLevel), ClearancePoly: validPolyCode(in.ClearancePoly), ClearanceStatus: validStatusCode(in.ClearanceStatus), YearsExperience: int32(clampYears(in.YearsExperience)), Location: nilIfEmpty(in.Location), Remote: in.Remote, Relocatable: in.Relocatable, Available: in.Available, }) if err != nil { return fmt.Errorf("create candidate: %w", err) } for _, name := range dedupeNonEmpty(in.Skills) { sk, err := q.UpsertSkill(ctx, dbgen.UpsertSkillParams{Name: name}) if err != nil { return fmt.Errorf("upsert skill: %w", err) } if err := q.AddCandidateSkill(ctx, dbgen.AddCandidateSkillParams{OrganizationID: org, CandidateID: cand.ID, SkillID: sk.ID}); err != nil { return fmt.Errorf("add candidate skill: %w", err) } } for _, name := range dedupeNonEmpty(in.Certifications) { if err := q.AddCandidateCertification(ctx, dbgen.AddCandidateCertificationParams{OrganizationID: org, CandidateID: cand.ID, Name: name}); err != nil { return fmt.Errorf("add candidate certification: %w", err) } } for _, agency := range dedupeNonEmpty(in.CustomerExperience) { if err := q.AddCandidateCustomerExperience(ctx, dbgen.AddCandidateCustomerExperienceParams{OrganizationID: org, CandidateID: cand.ID, Agency: agency}); err != nil { return fmt.Errorf("add candidate customer experience: %w", err) } } newID = cand.ID return s.auditOnTx(ctx, tx, audit.Event{Action: "candidate.created", EntityType: "candidate", EntityID: cand.ID.String()}) }) return newID, err } // SetClearanceProvenance records HOW a candidate's clearance is known (an org FSO action). It validates // the provenance code, stamps verified_at for an actual verification (the supplied date, else now) and // clears it for self_reported, and audits the change fail closed. The platform never verifies a // clearance itself; this records the org's authoritative assertion so ranking and the UI stay honest. func (s *Service) SetClearanceProvenance(ctx context.Context, candidateID uuid.UUID, provenance string, verifiedAt *time.Time) error { if s.db == nil { return ErrNoDatabase } if !validProvenance(provenance) { return ErrBadRequest } var va *time.Time switch { case provenance == "self_reported": va = nil // a self reported indicator is not a verification case verifiedAt != nil: va = verifiedAt default: now := s.clock() va = &now } return s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { n, err := dbgen.New(tx).SetCandidateClearanceProvenance(ctx, dbgen.SetCandidateClearanceProvenanceParams{ ID: candidateID, ClearanceProvenance: provenance, ClearanceVerifiedAt: va, }) if err != nil { return fmt.Errorf("set clearance provenance: %w", err) } if n == 0 { return ErrNotFound } payload, _ := json.Marshal(map[string]any{"provenance": provenance}) return s.auditOnTx(ctx, tx, audit.Event{Action: "candidate.clearance_provenance.set", EntityType: "candidate", EntityID: candidateID.String(), NewValues: payload}) }) } func validProvenance(p string) bool { switch p { case "self_reported", "sponsor_verified", "document", "continuous_vetting": return true default: return false } } // validLevelCode, validPolyCode, and validStatusCode clamp a self reported clearance code to a value the // DB CHECK constraint accepts, defaulting to the fail safe Unknown or None on anything unrecognized so a // malformed code can never be stored or score as a held clearance. func validLevelCode(code string) string { if _, err := engine.ParseClearanceLevel(code); err == nil { return code } return "unknown" } func validPolyCode(code string) string { if _, err := engine.ParsePolygraph(code); err == nil { return code } return "none" } func validStatusCode(code string) string { if _, err := engine.ParseClearanceStatus(code); err == nil { return code } return "unknown" } func clampYears(y int) int { if y < 0 { return 0 } if y > 60 { return 60 } return y } func nilIfEmpty(s string) *string { s = strings.TrimSpace(s) if s == "" { return nil } return &s } func dedupeNonEmpty(items []string) []string { seen := map[string]bool{} out := make([]string, 0, len(items)) for _, it := range items { t := strings.TrimSpace(it) if t == "" { continue } k := strings.ToLower(t) if seen[k] { continue } seen[k] = true out = append(out, t) } return out }