Janady13/missionmatch / internal/modules/eeo/service.go

1// Package eeo computes adverse impact reporting over the segregated eeo schema. It is the ONLY code 2// path that reads demographic data, and it runs exclusively on the compliance database role through a 3// separate pool. The application and scoring roles have no grant on the eeo schema, so demographics 4// can never reach a score; they flow one way, into this report. The platform PRODUCES the four fifths 5// data for the deploying employer's independent audit; it does not itself constitute the audit. 6package eeo 7 8import ( 9 "context" 10 "errors" 11 "time" 12 13 "github.com/jackc/pgx/v5" 14 "github.com/shopspring/decimal" 15 16 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 17) 18 19// ErrNoCompliance is returned when no compliance pool is configured, so adverse impact reporting is 20// unavailable (the endpoint returns 503 rather than silently producing an empty, misleading report). 21var ErrNoCompliance = errors.New("eeo: compliance database not configured") 22 23// fourFifths is the 0.80 impact ratio threshold (the EEOC Uniform Guidelines four fifths rule). A 24// group whose selection rate divided by the highest group rate falls below this is flagged. 25var fourFifths = decimal.RequireFromString("0.80") 26 27const unknownLabel = "unknown" 28 29// Service computes adverse impact over the compliance pool. The pool authenticates as the compliance 30// role and is the only pool with eeo access. Every query runs inside a tenant transaction so RLS 31// scopes both the eeo and the outcome tables to the caller's org. 32type Service struct{ compliance *tenant.DB } 33 34// NewService builds the service. compliance may be nil (then AdverseImpact returns ErrNoCompliance). 35func NewService(compliance *tenant.DB) *Service { return &Service{compliance: compliance} } 36 37// candRow is one candidate's demographic group and whether they were selected at a stage. 38type candRow struct { 39 gender string // display label, "unknown" when not provided 40 race string 41 genderUnknown bool // true only when the value is genuinely missing, not a real value named "unknown" 42 raceUnknown bool 43 selected bool 44} 45 46// AdverseImpact builds the report for the caller's org: a selection stage analysis over recorded slate 47// decisions and a screening stage analysis over served scores, each with four fifths impact ratios. 48func (s *Service) AdverseImpact(ctx context.Context, now time.Time) (Report, error) { 49 if s.compliance == nil || s.compliance.Pool == nil { 50 return Report{}, ErrNoCompliance 51 } 52 rep := Report{ 53 GeneratedAt: now.UTC().Format(time.RFC3339), 54 Source: "Voluntary self identification demographic data in the segregated eeo schema, joined to recorded AEDT outcomes. Read by the compliance role only.", 55 Method: "Four fifths rule (EEOC Uniform Guidelines). Selection rate per demographic group divided by the highest group rate. A ratio below 0.80 is flagged. The unknown category is reported as a count and excluded from the ratio comparison. The platform supplies this data for an independent audit run by the deploying employer.", 56 } 57 err := s.compliance.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 58 sel, e := s.stageRows(ctx, tx, selectionQuery) 59 if e != nil { 60 return e 61 } 62 scr, e := s.stageRows(ctx, tx, screeningQuery) 63 if e != nil { 64 return e 65 } 66 from, to, e := dateRange(ctx, tx) 67 if e != nil { 68 return e 69 } 70 selNoDemo, e := countQuery(ctx, tx, selectionNoDemoQuery) 71 if e != nil { 72 return e 73 } 74 scrNoDemo, e := countQuery(ctx, tx, screeningNoDemoQuery) 75 if e != nil { 76 return e 77 } 78 rep.DataFrom, rep.DataTo = from, to 79 rep.Selection = analyze("selection (recorded slate decisions)", sel, selNoDemo) 80 rep.Screening = analyze("screening (served scores)", scr, scrNoDemo) 81 return nil 82 }) 83 if err != nil { 84 return Report{}, err 85 } 86 return rep, nil 87} 88 89func (s *Service) stageRows(ctx context.Context, tx pgx.Tx, query string) ([]candRow, error) { 90 rows, err := tx.Query(ctx, query) 91 if err != nil { 92 return nil, err 93 } 94 defer rows.Close() 95 var out []candRow 96 for rows.Next() { 97 var r candRow 98 if err := rows.Scan(&r.gender, &r.race, &r.genderUnknown, &r.raceUnknown, &r.selected); err != nil { 99 return nil, err 100 } 101 out = append(out, r) 102 } 103 return out, rows.Err() 104} 105 106func countQuery(ctx context.Context, tx pgx.Tx, query string) (int, error) { 107 var n int 108 err := tx.QueryRow(ctx, query).Scan(&n) 109 return n, err 110} 111 112func dateRange(ctx context.Context, tx pgx.Tx) (string, string, error) { 113 var from, to *time.Time 114 err := tx.QueryRow(ctx, `SELECT min(created_at), max(created_at) FROM slate_members`).Scan(&from, &to) 115 if err != nil { 116 return "", "", err 117 } 118 fmtT := func(t *time.Time) string { 119 if t == nil { 120 return "" 121 } 122 return t.UTC().Format("2006-01-02") 123 } 124 return fmtT(from), fmtT(to), nil 125} 126 127// genderRace is the intersectional map key. Keying on a struct, not a delimiter joined string, means a 128// demographic value that happens to contain the display separator can never collide across cells. 129type genderRace struct{ gender, race string } 130 131// analyze rolls candidate rows into the three required cuts (by gender, by race or ethnicity, and the 132// intersectional cross tab) plus the unknown count. Whether a group is a known comparison group comes 133// from explicit per dimension flags carried out of SQL, never from overloading a sentinel string, so a 134// real demographic value of "unknown" is treated as known data. noDemographics is the count of decided 135// candidates with no consented demographics at all, surfaced to disclose consent coverage. 136func analyze(stage string, rows []candRow, noDemographics int) AnalysisSection { 137 byGender := map[string]*tally{} 138 byRace := map[string]*tally{} 139 byBoth := map[genderRace]*tally{} 140 unknown := 0 141 for _, r := range rows { 142 add(byGender, r.gender, !r.genderUnknown, r.selected) 143 add(byRace, r.race, !r.raceUnknown, r.selected) 144 add(byBoth, genderRace{r.gender, r.race}, !r.genderUnknown && !r.raceUnknown, r.selected) 145 if r.genderUnknown || r.raceUnknown { 146 unknown++ 147 } 148 } 149 bothStats := make([]groupStat, 0, len(byBoth)) 150 for k, t := range byBoth { 151 bothStats = append(bothStats, groupStat{label: k.gender + " / " + k.race, known: t.known, considered: t.considered, selected: t.selected}) 152 } 153 return AnalysisSection{ 154 Stage: stage, 155 TotalN: len(rows), 156 UnknownCount: unknown, 157 NoDemographicsCount: noDemographics, 158 ByGender: impactRows(statsFrom(byGender)), 159 ByRace: impactRows(statsFrom(byRace)), 160 Intersectional: impactRows(bothStats), 161 } 162} 163 164type tally struct { 165 considered, selected int 166 known bool 167} 168 169type groupStat struct { 170 label string 171 known bool 172 considered, selected int 173} 174 175// add tallies a candidate into a group keyed by any comparable type (a gender or race label, or the 176// intersectional struct). 177func add[K comparable](m map[K]*tally, key K, known, selected bool) { 178 t := m[key] 179 if t == nil { 180 t = &tally{known: known} 181 m[key] = t 182 } 183 t.considered++ 184 if selected { 185 t.selected++ 186 } 187} 188 189func statsFrom(m map[string]*tally) []groupStat { 190 out := make([]groupStat, 0, len(m)) 191 for label, t := range m { 192 out = append(out, groupStat{label: label, known: t.known, considered: t.considered, selected: t.selected}) 193 } 194 return out 195} 196 197// impactRows computes the selection rate per group and the four fifths impact ratio against the 198// highest rate among KNOWN groups. A four fifths comparison needs at least two known groups: with 199// fewer, the lone known group would self reference to a passing 1.0000 and mask a real disparity, so 200// every known row emits n/a instead. Unknown groups are listed with their rate but are never the 201// reference and are never flagged, since the unknown bucket is a count, not a comparison group. 202func impactRows(groups []groupStat) []ImpactRow { 203 ref := decimal.Zero 204 knownCount := 0 205 rates := make([]decimal.Decimal, len(groups)) 206 for i, g := range groups { 207 r := decimal.Zero 208 if g.considered > 0 { 209 r = decimal.NewFromInt(int64(g.selected)).DivRound(decimal.NewFromInt(int64(g.considered)), 6) 210 } 211 rates[i] = r 212 if g.known { 213 knownCount++ 214 if r.GreaterThan(ref) { 215 ref = r 216 } 217 } 218 } 219 validRef := knownCount >= 2 && ref.GreaterThan(decimal.Zero) 220 out := make([]ImpactRow, 0, len(groups)) 221 for i, g := range groups { 222 row := ImpactRow{Group: g.label, Considered: g.considered, Selected: g.selected, Rate: rates[i].StringFixed(4)} 223 if g.known && validRef { 224 ratio := rates[i].DivRound(ref, 6) 225 row.ImpactRatio = ratio.StringFixed(4) 226 row.Flagged = ratio.LessThan(fourFifths) 227 } else { 228 row.ImpactRatio = "n/a" 229 } 230 out = append(out, row) 231 } 232 sortRows(out) 233 return out 234} 235 236// selectionQuery: the latest consented demographics per candidate joined to their recorded slate 237// decisions. A candidate is selected if approved on any slate. RLS scopes both tables to the org. 238const selectionQuery = ` 239WITH latest AS ( 240 SELECT DISTINCT ON (candidate_id) candidate_id, 241 COALESCE(NULLIF(gender, ''), 'unknown') AS gender, 242 COALESCE(NULLIF(race_ethnicity, ''), 'unknown') AS race, 243 (NULLIF(gender, '') IS NULL) AS gender_unknown, 244 (NULLIF(race_ethnicity, '') IS NULL) AS race_unknown 245 FROM eeo.candidate_demographics 246 WHERE consent_given = true 247 ORDER BY candidate_id, collected_at DESC 248) 249SELECT l.gender, l.race, l.gender_unknown, l.race_unknown, bool_or(sm.decision = 'approved') AS selected 250FROM latest l 251JOIN slate_members sm ON sm.candidate_id = l.candidate_id 252GROUP BY l.candidate_id, l.gender, l.race, l.gender_unknown, l.race_unknown` 253 254// selectionNoDemoQuery counts decided candidates with no consented demographics, so the report 255// discloses how many recorded decisions are outside the four fifths analysis for want of self ID. 256const selectionNoDemoQuery = ` 257SELECT count(DISTINCT sm.candidate_id) 258FROM slate_members sm 259WHERE sm.decision IN ('approved', 'rejected') 260 AND NOT EXISTS ( 261 SELECT 1 FROM eeo.candidate_demographics d 262 WHERE d.candidate_id = sm.candidate_id AND d.consent_given = true)` 263 264// screeningQuery: the latest consented demographics joined to served score events. A candidate is 265// screened in if any served score was band green. audit_logs is outside RLS, so the org filter is 266// explicit on the GUC. 267const screeningQuery = ` 268WITH latest AS ( 269 SELECT DISTINCT ON (candidate_id) candidate_id, 270 COALESCE(NULLIF(gender, ''), 'unknown') AS gender, 271 COALESCE(NULLIF(race_ethnicity, ''), 'unknown') AS race, 272 (NULLIF(gender, '') IS NULL) AS gender_unknown, 273 (NULLIF(race_ethnicity, '') IS NULL) AS race_unknown 274 FROM eeo.candidate_demographics 275 WHERE consent_given = true 276 ORDER BY candidate_id, collected_at DESC 277), 278served AS ( 279 SELECT (entity_id)::uuid AS candidate_id, 280 bool_or((new_values->>'band') = 'green') AS screened_in 281 FROM audit_logs 282 WHERE action = 'aedt.score.served' AND entity_type = 'candidate' 283 AND organization_id = NULLIF(current_setting('app.current_org_id', true), '')::uuid 284 AND entity_id IS NOT NULL 285 GROUP BY entity_id 286) 287SELECT l.gender, l.race, l.gender_unknown, l.race_unknown, bool_or(s.screened_in) AS selected 288FROM latest l 289JOIN served s ON s.candidate_id = l.candidate_id 290GROUP BY l.candidate_id, l.gender, l.race, l.gender_unknown, l.race_unknown` 291 292// screeningNoDemoQuery counts candidates with a served score event but no consented demographics. 293const screeningNoDemoQuery = ` 294SELECT count(DISTINCT (entity_id)::uuid) 295FROM audit_logs a 296WHERE a.action = 'aedt.score.served' AND a.entity_type = 'candidate' AND a.entity_id IS NOT NULL 297 AND a.organization_id = NULLIF(current_setting('app.current_org_id', true), '')::uuid 298 AND NOT EXISTS ( 299 SELECT 1 FROM eeo.candidate_demographics d 300 WHERE d.candidate_id = (a.entity_id)::uuid AND d.consent_given = true)` 301