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

1package ai 2 3import ( 4 "context" 5 "errors" 6 "fmt" 7 "strings" 8 9 "github.com/jackc/pgx/v5" 10 11 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 12) 13 14// TAG (table augmented generation) answers questions that require the database to COMPUTE (count, sum, 15// filter, aggregate), which retrieval over text cannot do. The research is explicit that aggregation 16// questions must go to the database, not to vector RAG (docs/AI_RESEARCH.md, TAG). 17// 18// For cleared data the safe design is structured tool use, NOT free form natural language to SQL: the 19// model selects from a CURATED set of named, parameterized, read only intents and supplies typed 20// parameters. The model never authors SQL. Every intent is validated at startup against the read only 21// guard and the table allowlist, and references no eeo table, so a write or a demographics read is 22// impossible from the natural language path by construction. 23 24// ParamKind constrains an intent parameter so a model supplied value is type checked before binding. 25type ParamKind string 26 27const ( 28 ParamText ParamKind = "text" 29 ParamInt ParamKind = "int" 30 ParamUUID ParamKind = "uuid" 31 ParamEnum ParamKind = "enum" // value must be in Allowed 32 ParamBoolean ParamKind = "bool" 33) 34 35// Param describes one bound parameter of an intent. 36type Param struct { 37 Name string 38 Kind ParamKind 39 Allowed []string // for ParamEnum 40 Min int // for ParamInt: lower clamp bound (used only when Max > 0) 41 Max int // for ParamInt: upper clamp bound; 0 means no clamp 42} 43 44// Executor selects how a registered intent runs. ExecutorSQL (the default and the only value for every TAG 45// and graph intent) means the intent is a curated read only SELECT run through ExecuteIntent. ExecutorModel 46// means the intent is a MAG (Model Augmented Generation) intent: a model backed intent whose answer is a 47// calibrated number computed from stored coefficients over features gathered from other Registry intents, 48// NOT raw SQL. A model intent carries NO reachable SQL and ExecuteIntent hard rejects it, so it can never run 49// as a raw query; it runs only through ExecuteModelIntent. 50type Executor string 51 52const ( 53 ExecutorSQL Executor = "sql" // the default: a curated read only SELECT run through ExecuteIntent 54 ExecutorModel Executor = "model" // a MAG intent scored from stored coefficients, run through ExecuteModelIntent 55) 56 57// OutputKind is the HARD enum a MAG intent may emit. It is THE mechanism that keeps the frozen decimal engine 58// (internal/modules/matching, ModelVersion v1.4.0) the only per candidate scorer by construction: a learned 59// model may emit ONLY an opportunity level number, a display order, or a confidence, NEVER a per candidate 60// match score. A ModelSpec whose OutputKind is not one of these three fails ValidateRegistry at boot, and the 61// same three values are the CHECK constraint on aedt_learned_models.output_kind, so a candidate score is 62// impossible to register, impossible to store, and impossible to emit. 63const ( 64 OutputKindOpportunityScore = "opportunity_score" 65 OutputKindDisplayOrder = "display_order" 66 OutputKindConfidence = "confidence" 67) 68 69// validOutputKind reports whether a MAG output kind is one of the three legal values. Anything else (most of 70// all a candidate score) is rejected by ValidateRegistry, so it can never ship. 71func validOutputKind(kind string) bool { 72 switch kind { 73 case OutputKindOpportunityScore, OutputKindDisplayOrder, OutputKindConfidence: 74 return true 75 default: 76 return false 77 } 78} 79 80// ModelSpec is the static shape of a MAG intent: the champion model_key it serves, the OutputKind it may 81// emit (one of the three legal kinds), and the FeatureIntents it gathers its features from. Every 82// FeatureIntent MUST be another name in the closed Registry, so a model intent reads its features only 83// through the already guarded ExecuteIntent path (RLS, ReadAllowlist, ForbidEEO, suppression all hold). The 84// champion coefficients themselves are loaded from aedt_learned_models at serve time (a runtime check), so 85// this static spec carries no coefficient and no value. 86type ModelSpec struct { 87 ModelKey string 88 OutputKind string 89 FeatureIntents []string 90} 91 92// QueryIntent is one safe, named, read only question the TAG layer can answer. SQL is parameterized 93// ($1, $2, ...) and runs RLS scoped as the application role, so it sees only the caller's tenant. A MAG 94// intent sets Executor to ExecutorModel and carries a Model spec instead of a reachable SQL body; ExecuteIntent 95// rejects it, so it runs only through ExecuteModelIntent. 96type QueryIntent struct { 97 Name string 98 Description string // what question it answers, used for model routing 99 SQL string 100 Params []Param 101 // Executor is the empty string for a SQL intent (treated as ExecutorSQL) and ExecutorModel for a MAG 102 // intent. Model is nil for a SQL intent and non nil for a MAG intent. 103 Executor Executor 104 Model *ModelSpec 105} 106 107// IsSQLIntent reports whether an intent runs as a curated read only SELECT (the default). A MAG intent is the 108// only non SQL kind; every existing TAG and graph intent leaves Executor empty and is a SQL intent. 109func (it QueryIntent) IsSQLIntent() bool { return it.Executor != ExecutorModel } 110 111// Registry is the closed set of TAG intents. Adding one is a reviewed security decision. 112var Registry = []QueryIntent{ 113 { 114 Name: "count_candidates_by_clearance", 115 Description: "How many candidates hold a given clearance level (and optionally are available).", 116 SQL: "SELECT clearance_level, count(*) AS n FROM candidates WHERE deleted_at IS NULL AND anonymized_at IS NULL AND ($1 = '' OR clearance_level = $1) GROUP BY clearance_level ORDER BY n DESC", 117 Params: []Param{{Name: "clearance_level", Kind: ParamEnum, Allowed: []string{"", "none", "confidential", "secret", "top_secret", "ts_sci"}}}, 118 }, 119 { 120 Name: "proposal_ready_for_requirement", 121 Description: "How many persisted evaluations for a requirement are in the Green (proposal ready) band.", 122 SQL: "SELECT band, count(*) AS n FROM candidate_evaluations WHERE requirement_id = $1 GROUP BY band ORDER BY n DESC", 123 Params: []Param{{Name: "requirement_id", Kind: ParamUUID}}, 124 }, 125 { 126 Name: "open_requirements_count", 127 Description: "How many requirements are open (not soft deleted), optionally for one customer agency.", 128 SQL: "SELECT count(*) AS n FROM requirements WHERE deleted_at IS NULL AND ($1 = '' OR customer_agency = $1)", 129 Params: []Param{{Name: "customer_agency", Kind: ParamText}}, 130 }, 131 { 132 Name: "slate_decision_mix", 133 Description: "The approve/reject/pending decision mix of a slate's members.", 134 SQL: "SELECT decision, count(*) AS n FROM slate_members WHERE slate_id = $1 GROUP BY decision ORDER BY n DESC", 135 Params: []Param{{Name: "slate_id", Kind: ParamUUID}}, 136 }, 137 // G3 skill and role adjacency graph (Phase 0.B). Two FIXED recursive traversals over the curated 138 // global skill_relationships graph and the ontology_crosswalk taxonomy. The recursive CTE text is a 139 // reviewed static constant in graph_skill.go (skillSubstitutionClosureSQL, skillGapBridgeSQL); each 140 // carries a hard depth cap, a visited path cycle guard, and a total order tiebreaker, so the same 141 // inputs yield byte identical rows. They read only GLOBAL public reference tables, never eeo, never a 142 // score. ValidateRegistry asserts them at boot and ExecuteIntent re guards them at execution. 143 { 144 Name: IntentSkillSubstitutionClosure, 145 Description: "From a skill, the transitive curated substitution and broadening neighborhood with the accumulated curated strength per hop and the evidence path of edges, bounded by a hard depth cap with a cycle guard.", 146 SQL: skillSubstitutionClosureSQL, 147 Params: []Param{ 148 {Name: "start_skill_id", Kind: ParamUUID}, 149 {Name: "max_depth", Kind: ParamInt, Min: 1, Max: 5}, 150 }, 151 }, 152 { 153 Name: IntentSkillGapBridge, 154 Description: "Given a required skill not exactly held, the nearest curated skills one or two hops away plus any ontology crosswalk bridge that maps to it, each with the evidence path, bounded by a hard depth cap with a cycle guard.", 155 SQL: skillGapBridgeSQL, 156 Params: []Param{ 157 {Name: "required_skill_id", Kind: ParamUUID}, 158 {Name: "max_depth", Kind: ParamInt, Min: 1, Max: 5}, 159 }, 160 }, 161 // G1 market and relationship graph (Phase 0.C). Four FIXED capture intelligence reads over the GLOBAL 162 // public market tables usaspending_awards, opportunity_records, and sam_opportunities. Mostly aggregates 163 // and a full_parent_path string split for the agency hierarchy, NOT recursion (the data already carries 164 // the keys). The SQL text is a reviewed static constant in graph_market.go. Honesty is enforced by 165 // construction: the awards competitor field and the incumbent walk key ONLY on (agency, naics) because 166 // usaspending_awards carries no psc, set_aside, or pop_state column; every incumbent edge is labeled 167 // prime-of-record because the staffing subcontractor reality is absent from public award data; the finer 168 // slices come from opportunity_records, which does carry the full tuple. Every dollar and share figure is 169 // numeric end to end and is scanned into shopspring/decimal in Go, never float. These reads compute MARKET 170 // aggregates, never a match score, a band, or any employment decision number; the frozen engine stays the 171 // only scorer. ValidateRegistry asserts them at boot and ExecuteIntent re guards them on every execution. 172 { 173 Name: IntentSegmentCompetitorField, 174 Description: "For an agency and NAICS, the recency weighted dollar share of each recipient UEI awarded in that segment, ordered share descending with a UEI tiebreaker, so a dominant share reads wired and a fragmented field reads open, with the contributing award count as evidence and the tenant's own past performance labeled.", 175 SQL: segmentCompetitorFieldSQL, 176 Params: []Param{ 177 {Name: "agency", Kind: ParamText}, 178 {Name: "naics", Kind: ParamText}, 179 {Name: "lookback_years", Kind: ParamInt}, 180 }, 181 }, 182 { 183 Name: IntentIncumbentOfRecord, 184 Description: "For an opportunity record, the predecessor award matched on agency, NAICS, and the cross source dedupe key, returning the prime recipient UEI explicitly labeled prime-of-record with the matched award as evidence.", 185 SQL: incumbentOfRecordSQL, 186 Params: []Param{ 187 {Name: "opportunity_id", Kind: ParamUUID}, 188 }, 189 }, 190 { 191 Name: IntentRecompetePipeline, 192 Description: "For an agency and a forward window in months, the opportunities and awards whose period of performance end falls inside the window, the takeaway pipeline ordered by that end date with a record id tiebreaker, each row carrying its source so an award is never conflated with an opportunity.", 193 SQL: recompetePipelineSQL, 194 Params: []Param{ 195 {Name: "agency", Kind: ParamText}, 196 // Min 1 Max 60 matches the sibling window intents (recompete_clock, recompete_teaming) so the 197 // planner path, which runs this through ExecuteIntent and validateIntentArgs, clamps the window 198 // identically to the dedicated RecompetePipeline wrapper and a 999 month question cannot broaden 199 // the read only scan past five years. 200 {Name: "window_months", Kind: ParamInt, Min: 1, Max: 60}, 201 }, 202 }, 203 { 204 Name: IntentAgencyBuyingPattern, 205 Description: "For an agency or department prefix (rolled up through the sam_opportunities full_parent_path string split) and an optional NAICS, the NAICS and PSC distribution, set aside mix, and estimated value band of that buyer's opportunities, the where to position view.", 206 SQL: agencyBuyingPatternSQL, 207 Params: []Param{ 208 {Name: "agency_prefix", Kind: ParamText}, 209 {Name: "naics", Kind: ParamText}, 210 }, 211 }, 212 // G9 recompete lifecycle and foresight graph (Phase 1.A). Three FIXED lifecycle reads over the GLOBAL 213 // public market tables opportunity_records, usaspending_awards, federal_mission_tags, and mission_areas. 214 // The succession is a FIXED set of LEFT JOINs over opportunity_records (the only table with the full 215 // (agency, naics, psc, pop_state, set_aside) segment tuple), NOT a recursive CTE, because the dedupe_key 216 // already links the phases. The recompete clock and the forecast runway are forward window reads; the 217 // clock award arm keys ONLY on awarding_agency because usaspending_awards carries no finer key. Every 218 // incumbent edge is labeled prime-of-record. Every dollar (estimated_value, award_amount) is numeric end 219 // to end and is scanned into shopspring/decimal in Go, never float. These reads compute lifecycle FACTS, 220 // never a match score, a band, or any employment decision number; the frozen engine stays the only 221 // scorer. The window_months ParamInt carries Min 1 Max 60 so the structured path clamps the scan to the 222 // bounded range. ValidateRegistry asserts them at boot and ExecuteIntent re guards them on every 223 // execution. 224 { 225 Name: IntentProcurementSuccession, 226 Description: "For an active solicitation opportunity, the lifecycle succession walked through the dedupe key within the same agency, NAICS, PSC, place of performance state, and set aside segment to the predecessor contract award and any announcing forecast, returning whether it is a new start or a recompete, the prior award amount and the prior prime UEI explicitly labeled prime-of-record, with the cited record ids and dates.", 227 SQL: procurementSuccessionSQL, 228 Params: []Param{ 229 {Name: "opportunity_id", Kind: ParamUUID}, 230 }, 231 }, 232 { 233 Name: IntentRecompeteClock, 234 Description: "For an agency and a forward window in months, the opportunities and awards whose period of performance end falls inside the window, the takeaway pipeline ordered by that end date with a record id tiebreaker, each row carrying its source so an award is never conflated with an opportunity and the incumbent prime named and labeled prime-of-record.", 235 SQL: recompeteClockSQL, 236 Params: []Param{ 237 {Name: "agency", Kind: ParamText}, 238 {Name: "window_months", Kind: ParamInt, Min: 1, Max: 60}, 239 }, 240 }, 241 { 242 Name: IntentForecastRunway, 243 Description: "For a forward window in months, the forecasts whose estimated award date falls inside the window, the lead time runway joined to the federal mission area and carrying the place of performance state, ordered by estimated award date with an id tiebreaker.", 244 SQL: forecastRunwaySQL, 245 Params: []Param{ 246 {Name: "window_months", Kind: ParamInt, Min: 1, Max: 60}, 247 }, 248 }, 249 // G7 agency buying pattern graph (Phase 1.B). Three FIXED aggregate reads over the GLOBAL public market 250 // tables opportunity_records, usaspending_awards, and sam_opportunities. The agency rollup is a 251 // split_part(full_parent_path, '.', 1) string split plus a GROUP BY, NOT a recursive CTE, because the SAM 252 // hierarchy is already a materialized dotted path. Honesty is enforced by construction: the award dollar 253 // totals, the vendor concentration, and the spend trend key ONLY on (agency, naics) because 254 // usaspending_awards carries no psc, set_aside, or pop_state column; the finer slices (the vehicle mix, the 255 // set aside mix, the NAICS and PSC distribution, the value band) come from opportunity_records, which does 256 // carry the full tuple. The spend trend keys the award fiscal period on pop_start_date because the award 257 // table has no award_date column. Every dollar, average, median (percentile_cont, a numeric), and share is 258 // numeric end to end and is scanned into shopspring/decimal in Go, never float; nullable text slices are 259 // COALESCEd and nullable numerics are scanned into decimal pointers (the G9 NULL discipline). These reads 260 // compute MARKET aggregates, never a match score, a band, or any employment decision number; the frozen 261 // engine stays the only scorer. ValidateRegistry asserts them at boot and ExecuteIntent re guards them on 262 // every execution. 263 { 264 Name: IntentAgencyBuyingPatternDetail, 265 Description: "For an agency or department prefix (rolled up through the sam_opportunities full_parent_path string split) and an optional NAICS, the vehicle mix, set aside mix, NAICS and PSC distribution, and average and median estimated value band of the buyer's opportunity records, plus the usaspending_awards obligation totals keyed on agency and NAICS, each slice carrying the contributing record count as evidence, the where to position view.", 266 SQL: agencyBuyingPatternDetailSQL, 267 Params: []Param{ 268 {Name: "agency_prefix", Kind: ParamText}, 269 {Name: "naics", Kind: ParamText}, 270 }, 271 }, 272 { 273 Name: IntentAgencyVendorConcentration, 274 Description: "For an agency and NAICS, the recency weighted recipient UEI dollar share over the award segment, ordered share descending with a UEI tiebreaker, the wired versus open read, with the tenant's own past performance labeled and the contributing award count as evidence.", 275 SQL: agencyVendorConcentrationSQL, 276 Params: []Param{ 277 {Name: "agency", Kind: ParamText}, 278 {Name: "naics", Kind: ParamText}, 279 }, 280 }, 281 { 282 Name: IntentAgencySpendTrend, 283 Description: "For an agency and NAICS, the obligation total and award count per fiscal period over the award segment, ordered by the period, so the capture team reads whether the buyer's spend is concentrating or fragmenting.", 284 SQL: agencySpendTrendSQL, 285 Params: []Param{ 286 {Name: "agency", Kind: ParamText}, 287 {Name: "naics", Kind: ParamText}, 288 }, 289 }, 290 // G2 public vendor co occurrence and teaming field graph (Phase 1.C). Three FIXED reads over the GLOBAL 291 // PUBLIC market tables usaspending_awards and opportunity_records ONLY. The Phase 1 scope boundary is 292 // enforced by construction: NONE of these read a tenant table (no requirements, no candidates, no bench, 293 // never the eeo schema); the tenant gap intersection questions (which partner closes OUR bench gap) are 294 // DEFERRED to Phase 2 and G6, when the person plane comes online under RLS. The only tenant side these 295 // reads touch is the PUBLIC is_galapagos self tag on usaspending_awards, a column on the public award 296 // catalog, never a tenant table. Honesty is enforced by construction: the awards co occurrence keys ONLY 297 // on (agency, naics) because usaspending_awards carries no psc, set_aside, or pop_state column; the finer 298 // five tuple precision is opportunity_records sourced and each edge carries its source_table; every vendor 299 // edge is labeled prime-of-record. The team versus compete ratio is a numeric over a numeric guarded with 300 // NULLIF so a partner with no compete market divides safely (a null ratio, never a divide by zero). Every 301 // dollar, concentration, and ratio is numeric end to end and is scanned into shopspring/decimal in Go, 302 // never float; nullable text is COALESCEd and nullable numerics are scanned into decimal pointers (the G9 303 // NULL discipline). These reads compute MARKET aggregates, never a match score, a band, or any employment 304 // decision number; the frozen engine stays the only scorer. The window_months ParamInt carries Min 1 Max 305 // 60 so the structured path clamps the scan to the bounded range. ValidateRegistry asserts them at boot and 306 // ExecuteIntent re guards them on every execution. 307 { 308 Name: IntentVendorCooccurrenceField, 309 Description: "For an agency and NAICS segment, the set of recipient and incumbent UEIs that co occur in that segment, the likely teaming and competitor field, ordered by dollar concentration with a UEI tiebreaker, each edge labeled prime-of-record and carrying its source so an award keyed on agency and NAICS is never conflated with an opportunity sourced slice.", 310 SQL: vendorCooccurrenceFieldSQL, 311 Params: []Param{ 312 {Name: "agency", Kind: ParamText}, 313 {Name: "naics", Kind: ParamText}, 314 }, 315 }, 316 { 317 Name: IntentPartnerOrCompetitorRatio, 318 Description: "For a target partner UEI and a core NAICS, from public co occurrence alone, the count of markets where the partner co occurs with the tenant's own past performance (the is_galapagos self tag, same side teaming context) versus the markets where the partner holds the prime in the core NAICS, expressed as a team versus compete ratio guarded against a divide by zero, never a tenant table.", 319 SQL: partnerOrCompetitorRatioSQL, 320 Params: []Param{ 321 {Name: "partner_uei", Kind: ParamText}, 322 {Name: "naics", Kind: ParamText}, 323 }, 324 }, 325 { 326 Name: IntentRecompeteTeamingField, 327 Description: "For an agency and a forward window in months, the opportunities whose period of performance end falls inside the window, each carrying its incumbent UEI labeled prime-of-record joined to that incumbent's co occurring vendor neighborhood in the same NAICS over the public awards, the likely teaming field before the RFP drops, ordered by the period of performance end with a unique tiebreaker.", 328 SQL: recompeteTeamingFieldSQL, 329 Params: []Param{ 330 {Name: "agency", Kind: ParamText}, 331 {Name: "window_months", Kind: ParamInt, Min: 1, Max: 60}, 332 }, 333 }, 334 // G5 clearance lattice (Phase 2.B). Two GLOBAL reference reads over the four clearance reference tables 335 // seeded by migration 0023 (clearance_reachability over the rank ladder plus any seeded reciprocity 336 // exception, compartment_requirement_closure resolving a requirement's compartment codes to their kind), 337 // plus one person touching read (bench_clearance_coverage) that intersects the global clearance_levels 338 // ladder with the RLS protected candidates table. The two reference intents carry no person data and need 339 // no suppression; the coverage intent runs under RunInTenantTx (the app role sees only the caller's bench) 340 // and pipes its partition through the deterministic small cell suppression layer before any count leaves 341 // the process. The SQL text is a reviewed static constant in graph_clearance.go. These reads compute a 342 // lattice FACT and a suppressed structural headcount, never a match score, a band, or any employment 343 // decision number; the frozen engine stays the only scorer. The held_code ParamEnum bounds the held 344 // clearance to the six reference codes; the required_compartments ParamText carries the comma separated 345 // compartment list; bench_clearance_coverage takes no SQL parameter (the suppression threshold is a Go 346 // argument, not a bound SQL param). ValidateRegistry asserts them at boot and ExecuteIntent re guards them 347 // on every execution. 348 { 349 Name: IntentClearanceReachability, 350 Description: "For a held clearance code, every required clearance level it satisfies by the rank ladder (a held rank satisfies any required rank at or below it) plus any seeded reciprocity exception, the lattice fact a capture team reads to know which requirements a cleared candidate can fill, ordered by the required rank descending with a required code tiebreaker.", 351 SQL: clearanceReachabilitySQL, 352 Params: []Param{ 353 {Name: "held_code", Kind: ParamEnum, Allowed: []string{"none", "confidential", "secret", "top_secret", "ts_sci", "unknown"}}, 354 }, 355 }, 356 { 357 Name: IntentCompartmentRequirement, 358 Description: "For a requirement's comma separated list of required compartment codes, each recognized compartment resolved to its kind (sci or sap) and label over the global clearance compartment reference table, the closure a capture team reads to explain a compartment gap, ordered by the compartment code.", 359 SQL: compartmentRequirementClosureSQL, 360 Params: []Param{ 361 {Name: "required_compartments", Kind: ParamText}, 362 }, 363 }, 364 { 365 Name: IntentBenchClearanceCoverage, 366 Description: "How many bench candidates hold each clearance level for the caller's org, a suppressed structural headcount partition (every candidate has exactly one FK enforced clearance level, so the cells sum to the bench size), RLS scoped and piped through small cell suppression so a sub k level never surfaces a raw count, ordered by the level rank descending with a level code tiebreaker.", 367 SQL: benchClearanceCoverageSQL, 368 Params: nil, 369 }, 370 // G4 bench graph (Phase 2.C). Three FIXED person touching structural reads over the RLS protected person 371 // tables (candidates, candidate_skills, candidate_evaluations). Each runs under RunInTenantTx (the app 372 // role sees only the caller's bench) and pipes its aggregate partition through the deterministic small 373 // cell suppression layer before any count leaves the process. The SQL text is a reviewed static constant 374 // in graph_bench.go; each builds a closed partition whose counts sum to the matched total so complementary 375 // suppression is well defined. bench_skill_coverage partitions the bench into holds versus does not hold a 376 // skill; bench_readiness_distribution reports the distribution of bands the frozen engine ALREADY decided 377 // and audited at evaluation time read from candidate_evaluations, recomputing nothing; bench_gap_for_ 378 // requirement partitions the bench into meets versus does not meet by a STRUCTURAL coverage test (the 379 // clearance rank ladder plus a fixed fraction of the required skills), a count to size a gap, never a match 380 // score. The per candidate score and ranking remain the frozen engine, which is untouched. Each binds one 381 // ParamUUID id; the suppression threshold is a Go argument, not a bound SQL param. ValidateRegistry asserts 382 // them at boot and ExecuteIntent re guards them on every execution. 383 { 384 Name: IntentBenchSkillCoverage, 385 Description: "How many bench candidates hold a given skill versus do not hold it for the caller's org, a suppressed two bucket structural headcount partition (each candidate either holds the skill or does not, so the cells sum to the bench size), RLS scoped and piped through small cell suppression so a sub k bucket never surfaces a raw count, ordered by the bucket label. The single skill partition is the only version; a multi skill ontology family rollup is deferred because a family is not a partition.", 386 SQL: benchSkillCoverageSQL, 387 Params: []Param{ 388 {Name: "skill_id", Kind: ParamUUID}, 389 }, 390 }, 391 { 392 Name: IntentBenchReadinessDistribution, 393 Description: "For a requirement, how many evaluated bench candidates fall in each band green, yellow, red for the caller's org, read from the already audited candidate_evaluations (the band the frozen engine assigned at evaluation time, never a recomputed score), a suppressed single valued distribution (each evaluation has one band, so the cells sum to the evaluated count), RLS scoped and piped through small cell suppression, ordered by the band label.", 394 SQL: benchReadinessDistributionSQL, 395 Params: []Param{ 396 {Name: "requirement_id", Kind: ParamUUID}, 397 }, 398 }, 399 { 400 Name: IntentBenchGapForRequirement, 401 Description: "For a requirement, how many bench candidates STRUCTURALLY meet it (hold at least the required clearance level by the rank ladder AND at least four fifths of the required skills) versus do not, a suppressed two bucket headcount partition to size a gap, explicitly NOT a match score (the per candidate score and ranking remain the frozen engine), RLS scoped and piped through small cell suppression, ordered by the bucket label.", 402 SQL: benchGapForRequirementSQL, 403 Params: []Param{ 404 {Name: "requirement_id", Kind: ParamUUID}, 405 }, 406 }, 407 // G6 the loop (Phase 3). capture_picture_for_requirement is an ORCHESTRATOR COMPOSITION, NOT a raw SQL 408 // intent: it reuses the already validated bench and market planes (G4 bench_gap_for_requirement, G5 409 // bench_clearance_coverage, G9 recompete_clock, G1 segment_competitor_field) to answer one integrated 410 // capture question for a requirement, who on the caller's bench can structurally staff it (the SUPPRESSED 411 // person touching legs), the public market context (the recompete clock and, when a naics binds, the 412 // incumbent and competitor field), and the gap, plus the price to win honest floor. It is registered here 413 // so ValidateRegistry asserts it at boot and so it carries a real guarded read, but it NEVER runs through 414 // the raw ExecuteIntent path: it is a benchIntent (person touching), so ExecuteIntent hard rejects it and 415 // the AnswerGraph bench fork routes it to the answerCapturePicture composition instead. The registered SQL 416 // is the segment resolver read (requirementSegmentSQL in graph_loop.go), a valid allowlisted single SELECT 417 // over requirements, opportunities, and opportunity_records that passes the read only guard; it is the read 418 // the composition runs to resolve the requirement's market segment under RLS, never a reachable raw query. 419 // The composition computes a STRUCTURAL bench coverage and public market structure, never a match score, a 420 // band, or any employment decision number; the frozen engine stays the only scorer. 421 { 422 Name: IntentCapturePictureForRequirement, 423 Description: "For a requirement, the integrated capture picture composed across the planes: who on the caller's bench can structurally staff it (the suppressed bench gap and clearance coverage), the public market context (the recompete clock for the customer agency and, when a linked opportunity naics binds, the incumbent and competitor field), the structural gap, and the price to win honest floor, RLS scoped and small cell suppressed on the bench legs, explicitly NOT a match score (the per candidate score and ranking remain the frozen engine).", 424 SQL: requirementSegmentSQL, 425 Params: []Param{ 426 {Name: "requirement_id", Kind: ParamUUID}, 427 }, 428 }, 429 // M7 bid outcomes advisory base rate (bid_baserate.go). ONE aggregate read over the caller's own 430 // bid_outcomes ledger joined to the linked requirement for the customer agency segment. It is a plain TAG 431 // aggregate intent, NOT a graph intent and NOT a bench intent: it reads no person table, it is not in 432 // graphIntents or benchIntents, and it runs the standard ExecuteIntent path RLS scoped as the tenant. It 433 // reports an advisory MARKET base rate (the win count, the total decided, and the win rate as a numeric 434 // ratio guarded with NULLIF against a divide by zero), explicitly NOT a candidate score and NOT an 435 // employment decision number; the frozen engine stays the only scorer and no learned model consumes it 436 // yet. The win rate is scanned into shopspring/decimal in Go, never float. It takes no SQL parameter (it 437 // reports every segment of the caller's ledger). ValidateRegistry asserts it at boot and ExecuteIntent re 438 // guards it on every execution. 439 { 440 Name: IntentBidWinRateBySegment, 441 Description: "An advisory market base rate over the caller's own bid outcomes ledger: per customer agency segment read from the linked requirement, the win count, the total decided bids (win plus loss), and the win rate as a numeric ratio guarded against a divide by zero, RLS scoped, explicitly NOT a candidate score and NOT an employment decision number.", 442 SQL: bidWinRateBySegmentSQL, 443 Params: nil, 444 }, 445 // M5 price to win OEWS wage band (graph_wage.go). ONE aggregate read over the GLOBAL public bls_wages 446 // reference, pivoting the two metric rows (annual_mean and annual_median) for a SOC occupation code and an 447 // OEWS area code (HI or NM) into one advisory wage band row. It is PUBLIC reference data, NOT a bench 448 // intent (it reads no person table), NOT suppressed, and NOT a candidate score: it reports an advisory 449 // MARKET labor rate a capture analyst reads, explicitly NOT a match score and NOT an employment decision 450 // number; the frozen engine stays the only scorer. The mean and median are numeric(14,2) scanned into 451 // shopspring/decimal in Go, never float. It is a graph intent (it feeds the G6 price to win leg) but the NL 452 // path binds it only on a clearly quoted role and a named state. ValidateRegistry asserts it at boot and 453 // ExecuteIntent re guards it on every execution. 454 { 455 Name: IntentLaborRateBand, 456 Description: "For a SOC occupation code and an OEWS area code (HI or NM), the advisory OEWS wage band pivoted from the annual mean and annual median metric rows of the global bls_wages reference, carrying the occupation title, the Galapagos role label, and the area name, both dollar figures exact decimal, explicitly NOT a match score and NOT an employment decision number.", 457 SQL: laborRateBandSQL, 458 Params: []Param{ 459 {Name: "occupation_code", Kind: ParamText}, 460 {Name: "area", Kind: ParamEnum, Allowed: []string{"HI", "NM"}}, 461 }, 462 }, 463 // MAG (Model Augmented Generation) opportunity win probability (mag.go). The FIRST model backed intent 464 // on the closed Registry. It is Executor ExecutorModel and carries a Model spec, NOT a reachable SQL body: 465 // ExecuteIntent hard rejects it (like a bench intent), so it can never run as a raw query. It runs ONLY 466 // through ExecuteModelIntent, which loads the CHAMPION coefficients from aedt_learned_models, gathers its 467 // features by running each FeatureIntent through the existing ExecuteIntent path (so RLS, ReadAllowlist, 468 // ForbidEEO, and suppression all hold), computes a calibrated probability in shopspring/decimal, and 469 // returns an additive per feature contribution trace shaped like engine.ComponentScore. Its OutputKind is 470 // opportunity_score, one of the three legal kinds; it can NEVER emit a per candidate match score, so the 471 // frozen v1.4.0 engine stays the only per candidate scorer. The registered SQL is empty (a model intent 472 // carries no query the guard would run); ValidateRegistry asserts the static MAG shape at boot and the 473 // champion row is resolved at serve time. Params carry the segment keys it needs to bind its feature 474 // source: an agency, and optionally a naics, bound like the other market intents. 475 { 476 Name: IntentOpportunityWinProbability, 477 Description: "For a customer agency segment (and optionally a naics), the calibrated probability of winning an opportunity in that segment, a MAG opportunity_score computed from the champion opportunity_win_probability coefficients over the advisory market base rate feature, returned with the ordered per feature driver contributions and a reliability disclosure. Prior only at v0 (all learned coefficients zero), so it returns the shrunk market base rate, explicitly NOT a per candidate match score and NOT an employment decision number; the frozen engine stays the only per candidate scorer.", 478 SQL: "", // a MAG intent carries no reachable SQL; ExecuteIntent rejects it and it runs only through ExecuteModelIntent 479 Executor: ExecutorModel, 480 Model: &ModelSpec{ 481 ModelKey: WinProbabilityModelKey, 482 OutputKind: OutputKindOpportunityScore, 483 FeatureIntents: []string{IntentBidWinRateBySegment}, 484 }, 485 Params: []Param{ 486 {Name: "agency", Kind: ParamText}, 487 {Name: "naics", Kind: ParamText}, 488 }, 489 }, 490 // Capture Readiness (capture_readiness.go), the bid pursue decision. A graph COMPOSITION, not a raw SQL 491 // intent and not a MAG model intent: AnswerGraph intercepts it by name and dispatches to 492 // answerCaptureReadiness, which resolves the opportunity's agency segment under RLS (this registered SQL, 493 // guarded read only), gathers the four opportunity level factors (market win likelihood and engagement depth 494 // from the caller's own bid ledger, staffing readiness from the opportunity's requirements, incumbency 495 // position from the public award reference), reads the tunable weights from the coefficient store, composes 496 // an EXACT decimal weighted average, and maps it to a GO / REVIEW / NO_GO recommendation. It is an 497 // OPPORTUNITY level advisory, explicitly NOT a per candidate match score and NOT an employment decision; the 498 // frozen engine stays the only per candidate scorer and it never touches the eeo schema. The registered SQL 499 // resolves only the opportunity's segment; the composition runs it, never a reachable raw query for scoring. 500 { 501 Name: IntentOpportunityCaptureReadiness, 502 Description: "For an opportunity, a Capture Readiness Score and a GO / REVIEW / NO_GO bid pursue recommendation composed from grounded opportunity level factors (the segment win likelihood, the org's engagement depth, the staffing readiness of the requirements, and the agency incumbency structure), each factor's value and weight and contribution in the trace, the weights tunable in the coefficient store. An advisory bid decision aid a human resolves, explicitly NOT a per candidate match score and NOT an employment decision number; the frozen engine stays the only per candidate scorer.", 503 SQL: captureContextSQL, 504 Params: []Param{ 505 {Name: "opportunity_id", Kind: ParamUUID}, 506 }, 507 }, 508} 509 510// ValidateRegistry asserts every intent is safe: a SQL intent is read only, references no eeo, and touches 511// only allowlisted tables; a MAG (ExecutorModel) intent has a legal OutputKind, a non empty ModelKey, and a 512// feature spec that references NO eeo marker and only names in the Registry. It is called at startup and by a 513// test, so an unsafe intent cannot ship. The champion coefficient row is resolved at SERVE time (boot has no 514// database), so at boot the MAG branch asserts only the static shape. 515func ValidateRegistry() error { 516 names := map[string]bool{} 517 for _, it := range Registry { 518 names[it.Name] = true 519 } 520 for _, it := range Registry { 521 if it.Executor == ExecutorModel { 522 if err := validateModelIntent(it, names); err != nil { 523 return err 524 } 525 continue 526 } 527 if err := GuardReadOnlyQuery(it.SQL, ReadAllowlist); err != nil { 528 return fmt.Errorf("ai: intent %q is unsafe: %w", it.Name, err) 529 } 530 } 531 return nil 532} 533 534// validateModelIntent asserts the static shape of a MAG intent at boot: a non nil Model spec, a legal 535// OutputKind (one of the three legal kinds, so a candidate score is structurally impossible), a non empty 536// ModelKey, at least one FeatureIntent, and every FeatureIntent both present in the closed Registry AND free 537// of any eeo marker (reusing the eeo guard, so a demographics feature can never be declared). A MAG intent 538// must NOT carry a reachable SQL body (it never runs through the raw path), so a non empty SQL is rejected. 539// The champion coefficient row is resolved at serve time (boot has no database), not here. 540func validateModelIntent(it QueryIntent, registered map[string]bool) error { 541 if it.Model == nil { 542 return fmt.Errorf("ai: model intent %q has no ModelSpec", it.Name) 543 } 544 if strings.TrimSpace(it.SQL) != "" { 545 return fmt.Errorf("ai: model intent %q must carry no reachable SQL", it.Name) 546 } 547 if !validOutputKind(it.Model.OutputKind) { 548 return fmt.Errorf("ai: model intent %q has an illegal output kind %q; a candidate score is forbidden by construction", it.Name, it.Model.OutputKind) 549 } 550 if strings.TrimSpace(it.Model.ModelKey) == "" { 551 return fmt.Errorf("ai: model intent %q has an empty model key", it.Name) 552 } 553 if len(it.Model.FeatureIntents) == 0 { 554 return fmt.Errorf("ai: model intent %q declares no feature intents", it.Name) 555 } 556 // The feature spec (the model key and every feature intent name) must name no eeo marker, so a 557 // demographics feature can never be declared even by a crafted spec. 558 if err := ForbidEEO(it.Model.ModelKey); err != nil { 559 return fmt.Errorf("ai: model intent %q references eeo in its model key: %w", it.Name, err) 560 } 561 for _, fi := range it.Model.FeatureIntents { 562 if err := ForbidEEO(fi); err != nil { 563 return fmt.Errorf("ai: model intent %q references eeo in a feature intent: %w", it.Name, err) 564 } 565 if !registered[fi] { 566 return fmt.Errorf("ai: model intent %q declares feature intent %q that is not in the closed Registry", it.Name, fi) 567 } 568 } 569 return nil 570} 571 572// IsModelIntent reports whether a registered intent name is a MAG (model backed) intent, so the dispatcher 573// routes it to ExecuteModelIntent rather than the raw SQL path. An unknown or empty name is not a model 574// intent. 575func IsModelIntent(name string) bool { 576 it, ok := IntentByName(name) 577 return ok && it.Executor == ExecutorModel 578} 579 580// IntentByName returns a registered intent. 581func IntentByName(name string) (QueryIntent, bool) { 582 for _, it := range Registry { 583 if it.Name == name { 584 return it, true 585 } 586 } 587 return QueryIntent{}, false 588} 589 590// TAGResult is the executed answer: the column names and the rows, ready to narrate. It carries no free 591// text from the model, only data the database returned. 592type TAGResult struct { 593 Intent string 594 Columns []string 595 Rows [][]any 596} 597 598// ExecuteIntent binds the model supplied args (in the order of Params) and runs the intent RLS scoped as 599// the tenant. It re validates the SQL through the guard at execution time too (defense in depth), so even 600// a tampered registry cannot run a write or reach eeo. 601func ExecuteIntent(ctx context.Context, db *tenant.DB, intent QueryIntent, args []any) (*TAGResult, error) { 602 if db == nil { 603 return nil, errors.New("ai: no database") 604 } 605 // Defense in depth: a person touching bench intent must run through its suppressing executor, which builds 606 // the partition and applies small cell suppression in Go. The raw intent path returns the database rows 607 // verbatim, which for a bench intent would be the UNSUPPRESSED sub k headcounts, a re identification leak. 608 // So the raw path hard rejects every bench intent; the only way to run one is the suppressing executor. 609 if IsBenchIntent(intent.Name) { 610 return nil, fmt.Errorf("ai: %q is a suppressed bench intent and must run through its suppressing executor, not the raw intent path", intent.Name) 611 } 612 // Defense in depth: a MAG (model backed) intent carries no reachable SQL and computes a calibrated number 613 // from stored coefficients, NOT a database read. The raw path would try to run an empty query. So the raw 614 // path hard rejects every model intent; the only way to run one is ExecuteModelIntent. 615 if intent.Executor == ExecutorModel { 616 return nil, fmt.Errorf("ai: %q is a model backed MAG intent and must run through ExecuteModelIntent, not the raw intent path", intent.Name) 617 } 618 if err := GuardReadOnlyQuery(intent.SQL, ReadAllowlist); err != nil { 619 return nil, err 620 } 621 if len(args) != len(intent.Params) { 622 return nil, fmt.Errorf("ai: intent %q expects %d params, got %d", intent.Name, len(intent.Params), len(args)) 623 } 624 // Defense in depth on the structured API path: enforce the declared ParamEnum allowlist and clamp a 625 // bounded ParamInt (for example max_depth) to its range, so a caller cannot bind an out of vocabulary 626 // enum value or an unbounded recursion depth. The recursive walks also carry an independent cycle guard, 627 // so this is hardening, not the only bound. 628 args, err := validateIntentArgs(intent, args) 629 if err != nil { 630 return nil, err 631 } 632 out := &TAGResult{Intent: intent.Name} 633 err = db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 634 rows, err := tx.Query(ctx, intent.SQL, args...) 635 if err != nil { 636 return err 637 } 638 defer rows.Close() 639 for _, fd := range rows.FieldDescriptions() { 640 out.Columns = append(out.Columns, string(fd.Name)) 641 } 642 for rows.Next() { 643 vals, err := rows.Values() 644 if err != nil { 645 return err 646 } 647 out.Rows = append(out.Rows, vals) 648 } 649 return rows.Err() 650 }) 651 if err != nil { 652 return nil, err 653 } 654 return out, nil 655} 656 657// validateIntentArgs enforces the declared parameter contract before binding: a ParamEnum value must be in 658// its Allowed set, and a bounded ParamInt is clamped to [Min, Max]. It returns a copy of args with any 659// clamped integer replaced, so a caller on the structured API path cannot bind an out of vocabulary enum or 660// an unbounded value. Other kinds (UUID, text, bool) are left to pgx to type check at bind time. 661func validateIntentArgs(intent QueryIntent, args []any) ([]any, error) { 662 out := make([]any, len(args)) 663 copy(out, args) 664 for i, p := range intent.Params { 665 switch p.Kind { 666 case ParamEnum: 667 s, ok := out[i].(string) 668 if !ok { 669 return nil, fmt.Errorf("ai: param %q must be a string", p.Name) 670 } 671 if !allowedValue(s, p.Allowed) { 672 return nil, fmt.Errorf("ai: param %q value is not in the allowed set", p.Name) 673 } 674 case ParamInt: 675 if p.Max > 0 { 676 n, err := asInt(out[i]) 677 if err != nil { 678 return nil, fmt.Errorf("ai: param %q must be an integer: %w", p.Name, err) 679 } 680 if n < p.Min { 681 n = p.Min 682 } 683 if n > p.Max { 684 n = p.Max 685 } 686 out[i] = n 687 } 688 } 689 } 690 return out, nil 691} 692 693// allowedValue reports whether v is in the allowed set. 694func allowedValue(v string, allowed []string) bool { 695 for _, a := range allowed { 696 if v == a { 697 return true 698 } 699 } 700 return false 701} 702 703// asInt coerces a bound argument to an int across the common numeric shapes a request decoder produces 704// (int, int32, int64, and a JSON float64 that is a whole number), so a bounded ParamInt can be clamped. 705func asInt(v any) (int, error) { 706 switch n := v.(type) { 707 case int: 708 return n, nil 709 case int32: 710 return int(n), nil 711 case int64: 712 return int(n), nil 713 case float64: 714 if n == float64(int64(n)) { 715 return int(n), nil 716 } 717 return 0, fmt.Errorf("not a whole number") 718 default: 719 return 0, fmt.Errorf("unsupported integer type %T", v) 720 } 721} 722