Janady13/missionmatch / docs/plans/2026-06-30-graphrag-phase2-bench-clearance.md

1# GraphRAG Phase 2: Bench and Clearance Planes Implementation Plan 2 3> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. Steps use checkbox (`- [ ]`) syntax. 4 5**Goal:** Bring the FIRST person touching graph plane online under RLS: G4 the bench graph (structural questions about a tenant's own cleared workforce) and G5 the clearance lattice (reachability over the global clearance reference tables), guarded by a new deterministic small cell suppression layer so aggregate bench answers can never re identify an individual. 6 7**Architecture:** Two new intent files (`graph_clearance.go` for G5, `graph_bench.go` for G4) of named parameterized QueryIntents in the existing CLOSED Registry, plus one new cross cutting security control (`suppression.go`). G5 reference intents read the four GLOBAL clearance reference tables (no person data, no suppression). Every intent that touches the RLS protected person tables (`candidates`, `candidate_skills`, `candidate_evaluations`) runs under `RunInTenantTx` and pipes its aggregate cells through the suppression layer before any value leaves the process. The frozen engine stays the only scorer; suppression touches ONLY aggregate structural answers, NEVER the per candidate engine, score, or rationale. 8 9**Tech Stack:** Go 1.26, pgx/v5, sqlc, shopspring/decimal, FIPS (CGO_ENABLED=0 GOFIPS140=v1.0.0), no Python. 10 11**Branch:** `graphrag-foundation` (continues Phase 0 and Phase 1). Migration head 0032; Phase 2 adds NO migration (G5 reuses the 0023 clearance reference tables; G4 reuses the 0002 person tables; the suppression threshold is config, not schema). The ModelVersion stays v1.4.0 (no scoring change). Validate on M4 `brain_staging`. 12 13--- 14 15## The suppression policy this plan implements (decided 2026-06-30) 16 17A four angle de identification research workflow (NIST SP 800-188, FCSM Working Paper 22, Sweeney k anonymity, Machanavajjhala l diversity, NCES and OPM and Census and EEOC precedent, Aggarwal high dimensionality, Dinur Nissim reconstruction, NYC LL144) set the policy. The findings and the founder threat model refinement: 18 191. **k = 10 hard floor.** Any aggregate structural bench cell contributed to by fewer than 10 distinct individuals is suppressed. This satisfies every standard's floor at once (FCSM and NIST endorse 3 or 5, UK Data Service defaults to 10 for queryable surfaces). Override is `MM_BENCH_SUPPRESSION_K`, clamped to never go below 5. 20 212. **k is the least important control; the architecture carries the protection.** On a 50 to 200 person bench with about six rich quasi identifiers, every individual is near population unique, so a per query threshold is theater against the binding attack, query differencing. The load bearing controls are query auditing, fixed generalization, and (for the cross tenant surface) a privacy budget. 22 233. **Threat model scope.** G4 answers a tenant's questions about ITS OWN bench to ITS OWN authenticated owners, who already own those candidate records. That is NOT the published statistics threat. So Phase 2 ships the deterministic owner queries own data controls: the k = 10 floor with a value free sentinel, complementary (secondary) suppression with a margin back solve check, a fixed pre published generalization basis, and counts only auditing. The heavyweight defenses (a per querier differential privacy epsilon budget with composition, tracker and overlap refusal, calibrated noise) are DEFERRED to the cross tenant market surface, the WS8 cross tenant DP path that is flag off today, where differencing on a crowd you do NOT own actually binds. This matches the locked WS8 Posture B. 24 254. **l diversity is not computed in Phase 2, by design.** The homogeneity attack needs a sensitive attribute inside the released group. The graph carries NO protected attribute: the EEO module is unreachable (ForbidEEO plus the allowlist excludes the eeo schema). So there is no sensitive value to infer within G4. The l diversity guard would matter only if a protected attribute entered the graph, which a stronger control already forbids. This is documented in `suppression.go`, not implemented as dead code. 26 27--- 28 29## Hard invariants (every task) 30 311. **Suppression boundary, never crossed.** Suppression touches ONLY aggregate STRUCTURAL bench answers (counts and distributions over bench attributes). It MUST NEVER alter, round, noise, or withhold: (a) any individual candidate's own match score, rationale, decision trace, or AEDT notice; (b) the deterministic per candidate scoring engine path (`internal/modules/matching/engine`, ModelVersion pinned), which runs on the full record with zero suppression; (c) the human in the loop, never auto reject decision. The privacy floor and the explainability mandate act on different objects, so there is no conflict. 32 332. **RLS for every person touching intent.** Every G4 intent and the one G5 bench intersection intent takes `db *tenant.DB` and runs inside `RunInTenantTx`, so the app role reads only the caller's org (composite FK plus `app.current_org_id`). No intent reads a person table through the migrator pool. G5 reference intents read only the global reference tables and may run on either pool, but follow the same signature for uniformity. 34 353. **The frozen engine is the only scorer.** No intent computes a match score or band. Bench aggregates (counts, readiness distributions sourced from the already audited `candidate_evaluations`, coverage ratios) are computed in `shopspring/decimal` and are explicitly NOT match scores. `internal/modules/matching/engine` is untouched; golden and frozen tests stay byte identical. 36 374. **Closed Registry, deterministic, EEO unreachable.** Every traversal is a FIXED named QueryIntent, asserted by `ValidateRegistry`, re guarded by `GuardReadOnlyQuery`. Any recursive CTE carries a depth cap, a cycle guard (visited path plus `UNION`), a unique id tiebreaker, and a base term `::numeric` cast. Every list ORDER BY ends with a unique id tiebreaker for byte stable output. No intent references the eeo schema; the `safety_test.go` EEO walk covers the new files; the audit carries counts only. 38 395. **Decimal not float.** No `float64` or `::float8`/`::real`/`::double precision` touches a count, ratio, or readiness aggregate surfaced as evidence; scan numeric into `shopspring/decimal`. Headcounts are `int` (a headcount is an integer, suppressed as a unit). 40 416. **Fixed generalization basis (pre published, never per query adaptive).** Quasi identifiers are generalized to a fixed lattice before counting: `clearance_level` and `clearance_compartments` and `available` are already coarse enums or boolean and are used as is; `location` generalizes to a US state code through the existing location resolver, else the bucket `"unspecified"`; a skill family grouping generalizes to the ontology parent term through `skill_relationships` broader edges. Per query adaptive coarsening is itself a leak and is forbidden. 42 437. Standard rules: no Python; no dashes in written output except URLs, CLI flags, import paths, identifiers; both cloud core ANSI SQL plus the existing pgvector, no Neptune/Cosmos/cloud specific graph primitive; FIPS. 44 45--- 46 47## File Structure 48 49- Create `internal/modules/ai/suppression.go` (+ `suppression_test.go`): the deterministic small cell suppression control. The security critical unit; exhaustively tested. 50- Create `internal/modules/ai/graph_clearance.go` (+ `_test.go`): G5 intents. Reference reachability over the global clearance tables, plus one suppressed bench coverage intent. 51- Create `internal/modules/ai/graph_bench.go` (+ `_test.go`): G4 bench aggregate intents, all suppressed. 52- Modify `internal/modules/ai/safety.go`: add the four clearance reference tables to `ReadAllowlist`. 53- Modify `internal/modules/ai/tag.go`: register the new intents. 54- Modify `internal/modules/ai/graph_route.go`: add the new intents to `graphIntents` and a few conservative NL classifier keywords; gate bench intents behind an authenticated tenant context. 55- Integration tests under `internal/integration/`: RLS scoped, suppression applied, differencing refused, proven live on `brain_staging`. 56 57**Reference template:** follow `internal/modules/ai/graph_market.go` for the intent file shape (a `const xxxSQL` string, a `type XxxRow struct`, a `func XxxName(ctx, db *tenant.DB, params) ([]XxxRow, error)` executor that scans into decimal), and `internal/modules/ai/tag.go` for registration. 58 59--- 60 61## Phase 2.A: the suppression layer (the new security control) 62 63### Task A1: the deterministic small cell suppression function 64 65**Files:** 66- Create: `internal/modules/ai/suppression.go` 67- Test: `internal/modules/ai/suppression_test.go` 68 69- [ ] **Step 1: Write the failing tests** 70 71```go 72package ai 73 74import ( 75 "testing" 76) 77 78func TestSuppressBelowThresholdHidesSmallCells(t *testing.T) { 79 // Total is 40, above k, so the answer is allowed. Cells under 10 are hidden. 80 cells := []Cell{ 81 {Key: []string{"secret"}, Count: 22}, 82 {Key: []string{"top_secret"}, Count: 12}, 83 {Key: []string{"ts_sci"}, Count: 6}, 84 } 85 out := Suppress(cells, 10) 86 if out[0].Suppressed || out[1].Suppressed { 87 t.Fatal("cells at or above k must not be suppressed") 88 } 89 if !out[2].Suppressed { 90 t.Fatal("a cell of 6 (below k=10) must be suppressed") 91 } 92} 93 94func TestSuppressComplementaryHidesASecondCell(t *testing.T) { 95 // Exactly one cell is naturally below k. If only it were hidden, it could be recovered as 96 // total minus the published cells. So a second (the smallest published) cell must also hide. 97 cells := []Cell{ 98 {Key: []string{"secret"}, Count: 30}, 99 {Key: []string{"top_secret"}, Count: 14}, 100 {Key: []string{"ts_sci"}, Count: 6}, 101 } 102 out := Suppress(cells, 10) 103 suppressed := 0 104 for _, c := range out { 105 if c.Suppressed { 106 suppressed++ 107 } 108 } 109 if suppressed < 2 { 110 t.Fatalf("complementary suppression must hide at least 2 cells, got %d", suppressed) 111 } 112 // The smallest published cell (top_secret, 14) is the one chosen to also hide, not the larger. 113 if out[1].Key[0] != "top_secret" || !out[1].Suppressed { 114 t.Fatal("the smallest published cell must be the complementary suppression") 115 } 116} 117 118func TestSuppressRefusesWhenTotalBelowThreshold(t *testing.T) { 119 // If the whole matched set is below k, even its existence is sub threshold: hide everything. 120 cells := []Cell{ 121 {Key: []string{"secret"}, Count: 4}, 122 {Key: []string{"ts_sci"}, Count: 3}, 123 } 124 out := Suppress(cells, 10) 125 for _, c := range out { 126 if !c.Suppressed { 127 t.Fatal("when the total is below k every cell must be suppressed") 128 } 129 } 130} 131 132func TestSuppressNoSmallCellsLeavesAllPublished(t *testing.T) { 133 cells := []Cell{ 134 {Key: []string{"secret"}, Count: 22}, 135 {Key: []string{"top_secret"}, Count: 18}, 136 } 137 out := Suppress(cells, 10) 138 for _, c := range out { 139 if c.Suppressed { 140 t.Fatal("no cell below k means nothing is suppressed") 141 } 142 } 143} 144 145func TestSuppressIsDeterministic(t *testing.T) { 146 cells := []Cell{ 147 {Key: []string{"a"}, Count: 6}, 148 {Key: []string{"b"}, Count: 6}, 149 {Key: []string{"c"}, Count: 28}, 150 } 151 a := Suppress(append([]Cell(nil), cells...), 10) 152 b := Suppress(append([]Cell(nil), cells...), 10) 153 for i := range a { 154 if a[i].Suppressed != b[i].Suppressed { 155 t.Fatal("suppression must be deterministic across runs") 156 } 157 } 158} 159``` 160 161- [ ] **Step 2: Run the tests to verify they fail** 162 163Run: `go test ./internal/modules/ai/ -run TestSuppress -v` 164Expected: FAIL (Cell, Suppress undefined). 165 166- [ ] **Step 3: Write the implementation** 167 168```go 169package ai 170 171import ( 172 "os" 173 "sort" 174 "strconv" 175 176 "github.com/shopspring/decimal" 177) 178 179// BenchSuppressionThreshold is the small cell suppression floor k for aggregate structural answers about 180// a tenant bench. Cells contributed to by fewer than k distinct individuals are suppressed. Set by the 181// 2026-06-30 de identification research (NIST SP 800-188, FCSM WP22, l diversity, NYC LL144): k = 10 is 182// the hard floor; the load bearing protection is the architecture, not k. l diversity is intentionally 183// NOT computed here: the graph carries no protected attribute (the EEO module is unreachable), so there 184// is no sensitive value for the homogeneity attack to infer. The heavyweight differencing defenses (a per 185// querier DP epsilon budget, tracker and overlap refusal, calibrated noise) live on the cross tenant 186// market surface (flag off today), not on this owner queries own data path. 187const BenchSuppressionThreshold = 10 188 189// minSuppressionThreshold is the floor below which k may never be configured (the research dissent's hard 190// line). Any MM_BENCH_SUPPRESSION_K under this is ignored. 191const minSuppressionThreshold = 5 192 193// SuppressionSentinel is the single value free token rendered for every suppressed cell. It is identical 194// for a true zero and any cell of 1 to k-1, so the token itself carries no count signal: a real 0 and a 195// small nonzero are indistinguishable. 196const SuppressionSentinel = "below reporting threshold" 197 198// Cell is one aggregate cell in a bench answer: a generalized quasi identifier bucket and the count of 199// DISTINCT individuals contributing to it. Value is an optional decimal aggregate (for example a median 200// readiness) suppressed alongside the count. Cells of a single intent form a PARTITION of the matched set 201// (each matched individual lands in exactly one bucket), so the counts sum to the matched total. 202type Cell struct { 203 Key []string 204 Count int 205 Value decimal.Decimal 206 HasValue bool 207 Suppressed bool 208} 209 210// ConfiguredSuppressionThreshold reads MM_BENCH_SUPPRESSION_K, clamps it to never drop below 211// minSuppressionThreshold, and defaults to BenchSuppressionThreshold. 212func ConfiguredSuppressionThreshold() int { 213 k := BenchSuppressionThreshold 214 if v := os.Getenv("MM_BENCH_SUPPRESSION_K"); v != "" { 215 if n, err := strconv.Atoi(v); err == nil && n >= minSuppressionThreshold { 216 k = n 217 } 218 } 219 return k 220} 221 222// Suppress applies deterministic small cell suppression to one intent's partition of cells. The input 223// order is preserved; only the Suppressed flag is set. The rules: 224// 225// 1. Refuse the whole answer when the matched total is below k: even the existence of the set is sub 226// threshold, so every cell is suppressed. 227// 2. Primary: suppress any cell with Count < k (Count of 0 to k-1). 228// 3. Complementary: if exactly one cell ends up suppressed, its value is recoverable as the total minus 229// the published cells, so suppress the smallest published cell as well. This guarantees at least two 230// hidden cells whenever any cell is hidden, the FCSM Working Paper 22 secondary suppression rule. 231// 232// Suppress is pure and deterministic: the complementary choice breaks ties by smallest count then by Key 233// order, so the same input always yields the same suppression pattern. 234func Suppress(cells []Cell, k int) []Cell { 235 if k < minSuppressionThreshold { 236 k = minSuppressionThreshold 237 } 238 total := 0 239 for _, c := range cells { 240 total += c.Count 241 } 242 if total < k { 243 for i := range cells { 244 cells[i].Suppressed = true 245 } 246 return cells 247 } 248 249 suppressedCount := 0 250 for i := range cells { 251 if cells[i].Count < k { 252 cells[i].Suppressed = true 253 suppressedCount++ 254 } 255 } 256 if suppressedCount == 0 { 257 return cells 258 } 259 260 if suppressedCount == 1 { 261 // Choose the smallest published cell to also hide (least utility lost), tie broken by Key order 262 // so the pattern is deterministic. Index order of published cells. 263 published := make([]int, 0, len(cells)) 264 for i := range cells { 265 if !cells[i].Suppressed { 266 published = append(published, i) 267 } 268 } 269 sort.SliceStable(published, func(a, b int) bool { 270 ia, ib := published[a], published[b] 271 if cells[ia].Count != cells[ib].Count { 272 return cells[ia].Count < cells[ib].Count 273 } 274 return keyLess(cells[ia].Key, cells[ib].Key) 275 }) 276 if len(published) > 0 { 277 cells[published[0]].Suppressed = true 278 } 279 } 280 return cells 281} 282 283// keyLess is a total order over generalized bucket keys for deterministic tie breaking. 284func keyLess(a, b []string) bool { 285 for i := 0; i < len(a) && i < len(b); i++ { 286 if a[i] != b[i] { 287 return a[i] < b[i] 288 } 289 } 290 return len(a) < len(b) 291} 292 293// RenderCount returns the displayable count for a cell: the sentinel when suppressed, else the number. 294// The audit and the faithfulness narration use this so a suppressed count never leaves the process. 295func RenderCount(c Cell) string { 296 if c.Suppressed { 297 return SuppressionSentinel 298 } 299 return strconv.Itoa(c.Count) 300} 301``` 302 303- [ ] **Step 4: Run the tests to verify they pass** 304 305Run: `go test ./internal/modules/ai/ -run TestSuppress -v` 306Expected: PASS (all 5). 307 308- [ ] **Step 5: Add adversarial differencing and property tests** 309 310```go 311func TestSuppressDifferencingTwoQueriesCannotIsolateOne(t *testing.T) { 312 // The classic differencing attack: a broad query and a narrow query that differ by one person. With 313 // suppression, the narrow query's small residual cell is hidden, so subtraction cannot isolate the 314 // individual. This proves the per answer floor blocks the naive single subtraction (the cross query 315 // budget that blocks the iterated attack is the deferred cross tenant control, documented). 316 broad := []Cell{{Key: []string{"secret"}, Count: 11}} 317 narrow := []Cell{{Key: []string{"secret"}, Count: 1}} // the broad set minus ten others, one person 318 bo := Suppress(broad, 10) 319 no := Suppress(narrow, 10) 320 if bo[0].Suppressed { 321 t.Fatal("a published cell of 11 should remain") 322 } 323 if !no[0].Suppressed { 324 t.Fatal("a residual cell of 1 must be suppressed so subtraction cannot isolate the person") 325 } 326} 327 328func TestSuppressNeverPublishesBelowK(t *testing.T) { 329 // Property: after Suppress, no published cell has a count below k. Exhaustive over small grids. 330 k := 10 331 for total := 0; total <= 60; total++ { 332 for a := 0; a <= total; a++ { 333 cells := []Cell{{Key: []string{"a"}, Count: a}, {Key: []string{"b"}, Count: total - a}} 334 out := Suppress(cells, k) 335 for _, c := range out { 336 if !c.Suppressed && c.Count < k { 337 t.Fatalf("published a cell of %d below k=%d (total=%d)", c.Count, k, total) 338 } 339 } 340 } 341 } 342} 343 344func TestSuppressAtLeastTwoOrZeroHidden(t *testing.T) { 345 // Property: the hidden count is never exactly one (complementary suppression invariant). 346 k := 10 347 for total := 0; total <= 60; total++ { 348 for a := 0; a <= total; a++ { 349 cells := []Cell{{Key: []string{"a"}, Count: a}, {Key: []string{"b"}, Count: total - a}} 350 out := Suppress(cells, k) 351 hidden := 0 352 for _, c := range out { 353 if c.Suppressed { 354 hidden++ 355 } 356 } 357 if hidden == 1 { 358 t.Fatalf("exactly one cell hidden (recoverable) at total=%d a=%d", total, a) 359 } 360 } 361 } 362} 363``` 364 365- [ ] **Step 6: Run the full suppression suite** 366 367Run: `go test ./internal/modules/ai/ -run TestSuppress -v` 368Expected: PASS (all 8). 369 370- [ ] **Step 7: Commit** 371 372```bash 373git add internal/modules/ai/suppression.go internal/modules/ai/suppression_test.go 374git commit -m "feat(graphrag): deterministic small cell suppression for the bench plane" 375``` 376 377--- 378 379## Phase 2.B: G5 the clearance lattice 380 381The G5 reference intents read only the four GLOBAL clearance reference tables (`clearance_levels`, `polygraph_types`, `clearance_compartments`, `clearance_reciprocity`), so they carry no person data and no suppression. The reciprocity table is seeded empty, so the non rank reciprocity half is a documented scaffold that becomes richer when an FSO curates exceptions; the rank ladder is the live behavior today. One bench intersection intent (`bench_clearance_coverage`) touches `candidates` and is therefore suppressed and RLS scoped. 382 383### Task B1: add the clearance reference tables to the read allowlist 384 385**Files:** 386- Modify: `internal/modules/ai/safety.go:124-150` 387- Test: `internal/modules/ai/safety_test.go` 388 389- [ ] **Step 1: Add the four tables to `ReadAllowlist`** (after the `award_incumbent_roles` entry): 390 391```go 392 // Global clearance reference tables (no PII, FK enforced reference data) for the G5 clearance lattice. 393 "clearance_levels": true, 394 "polygraph_types": true, 395 "clearance_compartments": true, 396 "clearance_reciprocity": true, 397``` 398 399- [ ] **Step 2: Confirm the EEO walk still rejects** (no change needed, just run): `go test ./internal/modules/ai/ -run TestSafety -v` Expected: PASS. 400 401### Task B2: the G5 clearance reachability intents 402 403**Files:** 404- Create: `internal/modules/ai/graph_clearance.go` 405- Test: `internal/modules/ai/graph_clearance_test.go` 406- Modify: `internal/modules/ai/tag.go` (register), `internal/modules/ai/graph_route.go` (graphIntents + keywords) 407 408Reference the `graph_market.go` shape. Define intent name constants, the SQL, the row types, and the executors. 409 410- [ ] **Step 1: Write `clearance_reachability`** (which required levels a held level satisfies, by the rank ladder, plus any seeded reciprocity exception): 411 412```go 413package ai 414 415import ( 416 "context" 417 418 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 419) 420 421const ( 422 IntentClearanceReachability = "clearance_reachability" 423 IntentCompartmentRequirement = "compartment_requirement_closure" 424) 425 426// clearanceReachabilitySQL returns, for a held clearance code, every required level it satisfies. The 427// base rule is the rank ladder (a held rank satisfies any required rank at or below it). A seeded 428// clearance_reciprocity row can ADD a satisfaction edge that the ladder would not grant (an agency 429// specific exception); it never removes one. Today clearance_reciprocity is empty, so this returns the 430// pure ladder, the live engine behavior. Deterministic ORDER BY on the required rank then code. 431const clearanceReachabilitySQL = ` 432SELECT 433 held.code AS held_code, 434 req.code AS required_code, 435 req.rank AS required_rank, 436 (held.rank >= req.rank 437 OR EXISTS (SELECT 1 FROM clearance_reciprocity cr 438 WHERE cr.held_code = held.code AND cr.required_code = req.code AND cr.satisfies)) 439 AS satisfies 440FROM clearance_levels held 441CROSS JOIN clearance_levels req 442WHERE held.code = $1 443ORDER BY req.rank DESC, req.code ASC 444` 445 446type ClearanceReach struct { 447 HeldCode string 448 RequiredCode string 449 RequiredRank int 450 Satisfies bool 451} 452 453func ClearanceReachability(ctx context.Context, db *tenant.DB, heldCode string) ([]ClearanceReach, error) { 454 var out []ClearanceReach 455 err := db.RunInTenantTx(ctx, func(q tenant.Queryer) error { 456 rows, err := q.Query(ctx, clearanceReachabilitySQL, heldCode) 457 if err != nil { 458 return err 459 } 460 defer rows.Close() 461 for rows.Next() { 462 var r ClearanceReach 463 if err := rows.Scan(&r.HeldCode, &r.RequiredCode, &r.RequiredRank, &r.Satisfies); err != nil { 464 return err 465 } 466 out = append(out, r) 467 } 468 return rows.Err() 469 }) 470 return out, err 471} 472``` 473 474(NOTE to implementer: confirm the exact `tenant.DB` transaction helper name and `Queryer` type against `graph_market.go`; reuse whatever that file uses verbatim. Add `compartment_requirement_closure` over `clearance_compartments` in the same file, returning the kind sci or sap for each compartment a requirement parameter lists, used to explain a compartment gap. Both are global reference reads.) 475 476- [ ] **Step 2: Register both intents in `tag.go`** with `ParamEnum` for `held_code` (Allowed the six clearance codes) and `ParamText` for the requirement compartment list. Add both names to `graphIntents` in `graph_route.go` and a couple of conservative classifier keywords ("clearance satisfies", "compartment required"). Add a unit test asserting the ladder is monotonic (a higher held rank satisfies every required code a lower held rank does) so the intent stays pinned to the engine's clearance hierarchy. Commit. 477 478### Task B3: the G5 bench clearance coverage intent (suppressed, RLS) 479 480**Files:** 481- Modify: `internal/modules/ai/graph_clearance.go` 482- Test: `internal/modules/ai/graph_clearance_test.go` 483 484- [ ] **Step 1: Write `bench_clearance_coverage`** (how many bench candidates hold each clearance level), running under RLS and piped through `Suppress`: 485 486```go 487const IntentBenchClearanceCoverage = "bench_clearance_coverage" 488 489// benchClearanceCoverageSQL counts DISTINCT candidates per held clearance level for the caller's org. 490// RLS scopes it to the caller's bench. The COUNT is a headcount; the result is a partition of the bench 491// (every candidate has exactly one clearance_level), so the cells sum to the bench size and Suppress can 492// apply complementary suppression correctly. Deterministic ORDER BY on the level rank. 493const benchClearanceCoverageSQL = ` 494SELECT cl.code AS level_code, cl.rank AS level_rank, count(DISTINCT c.id) AS headcount 495FROM clearance_levels cl 496LEFT JOIN candidates c ON c.clearance_level = cl.code 497GROUP BY cl.code, cl.rank 498ORDER BY cl.rank DESC, cl.code ASC 499` 500 501type BenchCoverageRow struct { 502 LevelCode string 503 LevelRank int 504 Cell Cell 505} 506 507func BenchClearanceCoverage(ctx context.Context, db *tenant.DB, k int) ([]BenchCoverageRow, error) { 508 var out []BenchCoverageRow 509 err := db.RunInTenantTx(ctx, func(q tenant.Queryer) error { 510 rows, err := q.Query(ctx, benchClearanceCoverageSQL) 511 if err != nil { 512 return err 513 } 514 defer rows.Close() 515 for rows.Next() { 516 var r BenchCoverageRow 517 var headcount int 518 if err := rows.Scan(&r.LevelCode, &r.LevelRank, &headcount); err != nil { 519 return err 520 } 521 r.Cell = Cell{Key: []string{r.LevelCode}, Count: headcount} 522 out = append(out, r) 523 } 524 return rows.Err() 525 }) 526 if err != nil { 527 return nil, err 528 } 529 // Apply suppression over the partition before returning. The caller renders RenderCount, never the 530 // raw Count, for a suppressed cell. 531 cells := make([]Cell, len(out)) 532 for i := range out { 533 cells[i] = out[i].Cell 534 } 535 cells = Suppress(cells, k) 536 for i := range out { 537 out[i].Cell = cells[i] 538 } 539 return out, nil 540} 541``` 542 543- [ ] **Step 2: Unit test the partition and suppression wiring** (a fake or a staging row set asserting a sub k level renders the sentinel and the partition sums to the bench size). Register the intent, add to graphIntents and keywords. Commit. 544 545--- 546 547## Phase 2.C: G4 the bench graph 548 549Every G4 intent reads the RLS protected person tables, runs under `RunInTenantTx`, partitions the bench, and pipes the partition through `Suppress`. Follow the `BenchClearanceCoverage` shape exactly. 550 551### Task C1: bench skill coverage 552 553**Files:** 554- Create: `internal/modules/ai/graph_bench.go` 555- Test: `internal/modules/ai/graph_bench_test.go` 556 557- [ ] **Step 1: Write `bench_skill_coverage`** (how many bench candidates hold a given skill, or each skill in an ontology family), partitioned to hold or not hold so the cells sum to the bench size, suppressed. Use `candidate_skills` joined to `candidates` (RLS), and generalize the skill to its ontology parent through `skill_relationships` broader edges when a family is asked. Provide `IntentBenchSkillCoverage`, the SQL, a `BenchSkillRow` with an embedded `Cell`, and the executor that calls `Suppress`. 558 559- [ ] **Step 2: Test, register, route, commit.** 560 561### Task C2: bench readiness distribution 562 563**Files:** 564- Modify: `internal/modules/ai/graph_bench.go` 565- Test: `internal/modules/ai/graph_bench_test.go` 566 567- [ ] **Step 1: Write `bench_readiness_distribution`** (how many bench candidates fall in each band green, yellow, red FOR A GIVEN requirement), reading the ALREADY AUDITED `candidate_evaluations` (never recomputing a score; the band came from the frozen engine at evaluation time). Partition by band so the cells sum to the evaluated count, suppressed. This is the honest structural view: it reports the distribution of decisions the engine already made and audited, it does not score anyone. Provide `IntentBenchReadinessDistribution`, the SQL filtered by `requirement_id` under RLS, the row with an embedded `Cell` keyed by band, and the suppressed executor. 568 569- [ ] **Step 2: Test, register, route, commit.** 570 571### Task C3: bench gap for a requirement (structural, not a score) 572 573**Files:** 574- Modify: `internal/modules/ai/graph_bench.go` 575- Test: `internal/modules/ai/graph_bench_test.go` 576 577- [ ] **Step 1: Write `bench_gap_for_requirement`** (how many bench candidates hold at least the required clearance AND a given fraction of the required skills, partitioned into meets and does not meet buckets), a STRUCTURAL coverage count, explicitly NOT a match score. State in the doc comment that the per candidate score and ranking remain the frozen engine; this intent only counts structural coverage to size a gap. Suppressed, RLS. 578 579- [ ] **Step 2: Test, register, route, commit.** 580 581--- 582 583## Phase 2.D: routing, audit, and the least privilege gate 584 585### Task D1: gate the bench intents behind an authenticated tenant context and counts only audit 586 587**Files:** 588- Modify: `internal/modules/ai/graph_route.go` 589- Modify: `internal/modules/ai/orchestrator.go` (audit emission) 590- Test: `internal/modules/ai/graph_route_test.go` 591 592- [ ] **Step 1: Require a tenant context for bench intents.** In `AnswerGraph`, a bench or bench coverage intent (the suppressed set) requires a resolved `(org_id, user_id)` from the session; with no authenticated tenant context it refuses (the G5 reference intents do not). Add the suppressed intent names to a `benchIntents` set used for this check. 593 594- [ ] **Step 2: Emit a counts only, suppression aware audit.** The audit row for a bench intent records the intent name, the number of cells returned, the number suppressed, and the configured k, and carries NO candidate id, NO PII, and NO raw sub k count. Assert in a test that the audit payload contains no candidate id and that a suppressed cell's count is absent. 595 596- [ ] **Step 3: Add the faithfulness narration rule** so a suppressed answer narrates only published cells plus a fixed line "N buckets withheld to protect individuals (fewer than k)". Commit. 597 598--- 599 600## Phase 2.E: live integration on M4 brain_staging 601 602### Task E1: RLS, suppression, and differencing proven live 603 604**Files:** 605- Create: `internal/integration/graph_bench_integration_test.go` 606- Create: `internal/integration/graph_clearance_integration_test.go` 607 608- [ ] **Step 1: Seed a per run org** with a bench large enough to exercise both sides of the floor: at least 10 candidates at one clearance level (published) and fewer than 10 at another (suppressed). Use a unique per run org id and unique candidate ids (the lesson from the G2 cross run accumulation bug, since some tables are global, though candidates is RLS scoped per org). 609 610- [ ] **Step 2: Assert RLS isolation** (a second org sees only its own bench; the coverage counts differ), **suppression** (the sub k level renders `SuppressionSentinel`, never the raw number, and at least two cells are hidden when any is), and **the partition sums to the seeded bench size for published plus suppressed cells**. 611 612- [ ] **Step 3: Assert the differencing refusal** end to end: a broad query that is published and a narrow query whose residual cell is one person both go through the live route, and the narrow residual is suppressed (the per answer floor holds live). 613 614- [ ] **Step 4: Assert the G5 reachability ladder live** (ts_sci satisfies secret, secret does not satisfy ts_sci) against the seeded reference tables, with `clearance_reciprocity` empty. 615 616- [ ] **Step 5: Run on staging.** 617 618Run (with the brain_staging DSNs exported as in Phase 1): 619```bash 620GOFIPS140=v1.0.0 CGO_ENABLED=0 go test -tags=integration -count=1 -run "TestG4|TestG5|TestBench|TestClearance" ./internal/integration/... -v 621``` 622Expected: PASS. 623 624- [ ] **Step 6: Run the full graph suite to confirm no regression**, then commit. 625 626```bash 627GOFIPS140=v1.0.0 CGO_ENABLED=0 go test -tags=integration -count=1 -run "TestG1|TestG2|TestG3|TestG4|TestG5|TestG7|TestG9|TestGraphRoute|TestBench|TestClearance" ./internal/integration/... -v 628git add internal/integration/graph_bench_integration_test.go internal/integration/graph_clearance_integration_test.go 629git commit -m "test(graphrag): live RLS, suppression, and differencing proof for the bench and clearance planes" 630``` 631 632--- 633 634## Self review checklist (run before the final review subagent) 635 6361. **Suppression boundary:** grep the new files for any path that suppresses or alters an individual candidate's own score or rationale. There must be NONE; suppression touches only the aggregate `Cell` partitions. The frozen engine and the per candidate handler are untouched. 6372. **RLS:** every G4 intent and `bench_clearance_coverage` runs under `RunInTenantTx` and takes `db *tenant.DB`. No person table is read through the migrator pool. 6383. **No float:** no `float64` or float SQL cast on any surfaced count, ratio, or readiness aggregate. 6394. **EEO unreachable:** `safety_test.go` EEO walk covers the new files; no intent references the eeo schema; the allowlist still excludes it. 6405. **Determinism:** every list ORDER BY ends with a unique tiebreaker; `Suppress` is pure and order preserving; no `Date.now`/random. 6416. **Migration free:** Phase 2 adds no migration; the threshold is config (`MM_BENCH_SUPPRESSION_K`, floored at 5). 6427. **Frozen golden held:** `go test ./internal/modules/matching/...` byte identical. 643