Janady13/missionmatch / internal/modules/ai/graph_clearance.go

1package ai 2 3// G5 the clearance lattice. This file adds the clearance reachability plane as FIXED, named, 4// parameterized QueryIntents. Two of them are GLOBAL reference reads over the four clearance reference 5// tables seeded by migration 0023 (clearance_levels, polygraph_types, clearance_compartments, 6// clearance_reciprocity): they carry NO person data, so they need no suppression, but they follow the 7// same db *tenant.DB and RunInTenantTx signature as every other intent for uniformity. The third intent, 8// bench_clearance_coverage, intersects the global clearance_levels ladder with the RLS protected 9// candidates table, so it runs under RunInTenantTx (the app role sees only the caller's bench) and pipes 10// its partition through the deterministic small cell suppression layer before any count leaves the 11// process. 12// 13// The graph NEVER computes a match score, a band, or any employment decision number. The reachability 14// ladder reports which required levels a held level satisfies (a FACT from the rank ladder plus any 15// seeded reciprocity exception), and the coverage intent reports a suppressed headcount per level (a 16// STRUCTURAL count, never a score). The frozen engine in internal/modules/matching/engine stays the only 17// scorer and is untouched. The model never authors this SQL: every statement is a static, reviewed 18// constant, registered in the closed Registry, asserted by ValidateRegistry at boot, and re guarded by 19// GuardReadOnlyQuery on every execution. 20// 21// Headcounts are int (a headcount is an integer, suppressed as a unit). No float touches any surfaced 22// number on this plane: the reachability ladder surfaces ranks (int) and a satisfies boolean, and the 23// coverage intent surfaces an int headcount, so there is no ratio or aggregate that could pass through 24// float64. 25 26import ( 27 "context" 28 "errors" 29 30 "github.com/jackc/pgx/v5" 31 32 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 33) 34 35// The registered names of the three G5 clearance intents. Each is a FIXED entry in the closed Registry in 36// tag.go, so ValidateRegistry asserts it at boot and ExecuteIntent runs it through the same guard, tenant 37// transaction, and audit posture as every other TAG intent. 38const ( 39 IntentClearanceReachability = "clearance_reachability" 40 IntentCompartmentRequirement = "compartment_requirement_closure" 41 IntentBenchClearanceCoverage = "bench_clearance_coverage" 42) 43 44// clearanceReachabilitySQL returns, for a held clearance code, every required level it satisfies. The 45// base rule is the rank ladder (a held rank satisfies any required rank at or below it). A seeded 46// clearance_reciprocity row can ADD a satisfaction edge that the ladder would not grant (an agency 47// specific exception); it never removes one. Today clearance_reciprocity is empty, so this returns the 48// pure ladder, the live engine behavior. Deterministic ORDER BY on the required rank then the required 49// code, a total order over the cross joined levels. 50const clearanceReachabilitySQL = ` 51SELECT 52 held.code AS held_code, 53 req.code AS required_code, 54 req.rank AS required_rank, 55 (held.rank >= req.rank 56 OR EXISTS (SELECT 1 FROM clearance_reciprocity cr 57 WHERE cr.held_code = held.code AND cr.required_code = req.code AND cr.satisfies)) 58 AS satisfies 59FROM clearance_levels held 60CROSS JOIN clearance_levels req 61WHERE held.code = $1 62ORDER BY req.rank DESC, req.code ASC` 63 64// compartmentRequirementClosureSQL resolves a requirement's listed compartment codes to their kind (sci 65// or sap), so a compartment gap can be explained (a requirement that lists SI and TK needs those exact 66// SCI control systems, a requirement that lists SAP needs a special access program). The required codes 67// arrive as a single comma separated text parameter ($1); regexp_split_to_array splits the list on a comma 68// with the surrounding whitespace consumed by the pattern, so a list like "SI, TK" splits to the clean 69// codes, and the scalar array membership predicate (= ANY) keeps only the rows of the global 70// clearance_compartments reference table whose code is in the list. A listed code that is not a known 71// compartment simply does not match, so the closure returns only the recognized compartments (an unknown 72// marker is silently excluded, never fabricated). The split is a SCALAR array expression, never a FROM 73// clause set returning function, so the read stays over the single allowlisted clearance_compartments 74// table. Deterministic ORDER BY on the compartment code, a unique key over the table. 75const compartmentRequirementClosureSQL = ` 76SELECT 77 cc.code AS compartment_code, 78 cc.kind AS compartment_kind, 79 cc.label AS compartment_label 80FROM clearance_compartments cc 81WHERE cc.code = ANY (regexp_split_to_array(btrim($1), '\s*,\s*')) 82ORDER BY cc.code ASC` 83 84// benchClearanceCoverageSQL counts DISTINCT candidates per held clearance level for the caller's org. RLS 85// scopes it to the caller's bench. The COUNT is a headcount; the result is a partition of the bench (every 86// non deleted, non anonymized candidate has exactly one clearance_level, which is FK enforced against 87// clearance_levels), so the cells sum to the bench size and Suppress can apply complementary suppression 88// correctly. The LEFT JOIN keeps a level with zero holders in the partition (a true zero), so the 89// partition spans every level and a suppressed cell is indistinguishable from an empty one. The soft 90// delete and anonymize filters mirror count_candidates_by_clearance so an erased candidate is never 91// counted. Deterministic ORDER BY on the level rank then the level code, a total order over the levels. 92const benchClearanceCoverageSQL = ` 93SELECT 94 cl.code AS level_code, 95 cl.rank AS level_rank, 96 count(DISTINCT c.id) AS headcount 97FROM clearance_levels cl 98LEFT JOIN candidates c 99 ON c.clearance_level = cl.code 100 AND c.deleted_at IS NULL 101 AND c.anonymized_at IS NULL 102GROUP BY cl.code, cl.rank 103ORDER BY cl.rank DESC, cl.code ASC` 104 105// ClearanceReach is one reachability edge: a held clearance code, a required level (its code and rank), 106// and whether the held level satisfies that required level (by the rank ladder or a seeded reciprocity 107// exception). It carries no score and no employment decision number, only the lattice fact. 108type ClearanceReach struct { 109 HeldCode string `json:"held_code"` 110 RequiredCode string `json:"required_code"` 111 RequiredRank int `json:"required_rank"` 112 Satisfies bool `json:"satisfies"` 113} 114 115// ClearanceReachability runs the registered clearance_reachability intent for a held clearance code, 116// returning every required level it satisfies by the rank ladder plus any seeded reciprocity exception. 117// It is a GLOBAL reference read (no person data), but follows the db *tenant.DB and RunInTenantTx 118// signature for uniformity with every other intent. 119func ClearanceReachability(ctx context.Context, db *tenant.DB, heldCode string) ([]ClearanceReach, error) { 120 if db == nil { 121 return nil, errors.New("ai: no database") 122 } 123 var out []ClearanceReach 124 err := db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 125 if err := GuardReadOnlyQuery(clearanceReachabilitySQL, ReadAllowlist); err != nil { 126 return err 127 } 128 rows, err := tx.Query(ctx, clearanceReachabilitySQL, heldCode) 129 if err != nil { 130 return err 131 } 132 defer rows.Close() 133 for rows.Next() { 134 var r ClearanceReach 135 if err := rows.Scan(&r.HeldCode, &r.RequiredCode, &r.RequiredRank, &r.Satisfies); err != nil { 136 return err 137 } 138 out = append(out, r) 139 } 140 return rows.Err() 141 }) 142 return out, err 143} 144 145// CompartmentReq is one resolved compartment in a requirement's closure: the compartment code, its kind 146// (sci or sap), and its label. It explains a compartment gap (which exact control systems a requirement 147// demands); it carries no score and no person data. 148type CompartmentReq struct { 149 Code string `json:"compartment_code"` 150 Kind string `json:"compartment_kind"` 151 Label string `json:"compartment_label"` 152} 153 154// CompartmentRequirementClosure runs the registered compartment_requirement_closure intent. It takes a 155// comma separated list of required compartment codes (for example "SI,TK") and resolves each recognized 156// code to its kind and label over the global clearance_compartments reference table, so a compartment gap 157// can be explained. An unrecognized code does not join and is excluded, never fabricated. It is a GLOBAL 158// reference read (no person data) and follows the uniform RunInTenantTx signature. 159func CompartmentRequirementClosure(ctx context.Context, db *tenant.DB, compartmentList string) ([]CompartmentReq, error) { 160 if db == nil { 161 return nil, errors.New("ai: no database") 162 } 163 var out []CompartmentReq 164 err := db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 165 if err := GuardReadOnlyQuery(compartmentRequirementClosureSQL, ReadAllowlist); err != nil { 166 return err 167 } 168 rows, err := tx.Query(ctx, compartmentRequirementClosureSQL, compartmentList) 169 if err != nil { 170 return err 171 } 172 defer rows.Close() 173 for rows.Next() { 174 var r CompartmentReq 175 if err := rows.Scan(&r.Code, &r.Kind, &r.Label); err != nil { 176 return err 177 } 178 out = append(out, r) 179 } 180 return rows.Err() 181 }) 182 return out, err 183} 184 185// BenchCoverageRow is one clearance level in the bench coverage partition: the level code and rank, and 186// the suppressed Cell carrying the headcount. The caller renders RenderCount(Cell), never the raw Count, 187// so a suppressed sub k headcount renders the sentinel and never leaves the process as a number. It 188// carries no score and no candidate id, only a structural headcount. 189type BenchCoverageRow struct { 190 LevelCode string `json:"level_code"` 191 LevelRank int `json:"level_rank"` 192 Cell Cell `json:"cell"` 193} 194 195// BenchClearanceCoverage runs the registered bench_clearance_coverage intent under RLS (the app role sees 196// only the caller's bench), counting DISTINCT candidates per clearance level, then pipes the partition 197// through Suppress with the caller supplied threshold k (the caller passes ConfiguredSuppressionThreshold). 198// Because every candidate has exactly one FK enforced clearance level, the cells form a partition of the 199// bench, so the counts sum to the bench size and complementary suppression is well defined. The suppressed 200// cells are written back onto the rows; the caller renders RenderCount, never the raw Count, for a 201// suppressed cell. This is the FIRST person touching read on the clearance plane, so it is RLS scoped and 202// suppressed by construction. 203func BenchClearanceCoverage(ctx context.Context, db *tenant.DB, k int) ([]BenchCoverageRow, error) { 204 if db == nil { 205 return nil, errors.New("ai: no database") 206 } 207 var out []BenchCoverageRow 208 err := db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 209 if err := GuardReadOnlyQuery(benchClearanceCoverageSQL, ReadAllowlist); err != nil { 210 return err 211 } 212 rows, err := tx.Query(ctx, benchClearanceCoverageSQL) 213 if err != nil { 214 return err 215 } 216 defer rows.Close() 217 for rows.Next() { 218 var ( 219 r BenchCoverageRow 220 headcount int 221 ) 222 if err := rows.Scan(&r.LevelCode, &r.LevelRank, &headcount); err != nil { 223 return err 224 } 225 r.Cell = Cell{Key: []string{r.LevelCode}, Count: headcount} 226 out = append(out, r) 227 } 228 return rows.Err() 229 }) 230 if err != nil { 231 return nil, err 232 } 233 // Apply suppression over the partition before returning. The caller renders RenderCount, never the 234 // raw Count, for a suppressed cell, so a sub k headcount never leaves the process as a number. 235 cells := make([]Cell, len(out)) 236 for i := range out { 237 cells[i] = out[i].Cell 238 } 239 cells = Suppress(cells, k) 240 for i := range out { 241 out[i].Cell = cells[i] 242 } 243 return out, nil 244} 245