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

Source identity

Field	Recorded value
Source type	GitHub source
Original record	Janady13/missionmatch / internal/modules/matching/missioncheck.go
Date	Not specified in source
Repository	Janady13/missionmatch
Revision	720d47fae476b0d38477ae4401697d372b1ea2bc
Branch	feature/opportunity-to-outcome
Path or archive member	internal/modules/matching/missioncheck.go
Original SHA-256	2d361ff9a7fe06a7b84cf1e64a059662b13b84e3aaeec414e847c30e47897d0d
Git blob SHA	a8f024127dcc86fd4ed5afd0fad43f2b59c681a9
Reading-copy SHA-256	2d361ff9a7fe06a7b84cf1e64a059662b13b84e3aaeec414e847c30e47897d0d
Original source ↗
Recovered source transcript

Download complete source text ↓331 lines · 12.1 KB
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 {
		score, err := s.scorerOnTx(ctx, tx)
		if err != nil {
			return err
		}
		res := score(ctx, ec, er)
		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
	Email              string
	Headline           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),
			Email:           nilIfEmpty(strings.ToLower(strings.TrimSpace(in.Email))),
			Headline:        nilIfEmpty(strings.TrimSpace(in.Headline)),
			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.
// validLevelCode maps whatever a caller sent onto the STORED CODE.
//
// It used to accept only an exact code and degrade everything else to "unknown", which meant a caller sending
// the human label the interface displays, TS/SCI, silently lost the clearance. That is data loss dressed as
// validation: the record saved, no error was raised, and the person simply had no clearance any more. The
// search surface found it, because a bench where every clearance reads "unknown" cannot be filtered.
//
// It shares its translation with the search filter, so what can be STORED and what can be SEARCHED FOR are
// the same vocabulary by construction.
func validLevelCode(code string) string {
	if c, ok := clearanceLevelCode(code); ok {
		return c
	}
	return "unknown"
}

func validPolyCode(code string) string {
	if _, err := engine.ParsePolygraph(code); err == nil {
		return code
	}
	return "none"
}

// validStatusCode has the same contract as validLevelCode.
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
}