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

Source identity

Field	Recorded value
Source type	GitHub source
Original record	Janady13/missionmatch / internal/modules/ai/safety.go
Date	Not specified in source
Repository	Janady13/missionmatch
Revision	43d56387270ef4da4cabd794d97ca6a49909bc7d
Branch	w3-ai-staffing-recommendations
Path or archive member	internal/modules/ai/safety.go
Original SHA-256	6346ec8bfa4e6307724c313044b061173620007c26feedca2fbf6c1c16383d13
Git blob SHA	2046b48bd40ee45aed33f520dd787af7cba0ede1
Reading-copy SHA-256	6346ec8bfa4e6307724c313044b061173620007c26feedca2fbf6c1c16383d13

Original source ↗

Every recorded occurrence

These 3 records contain identical original source bytes. Their paths and revisions remain part of the archive.

Original record	Branch or archive	Revision / identifier	Original location
Janady13/missionmatch / internal/modules/ai/safety.go	w3-ai-staffing-recommendations	43d56387270ef4da4cabd794d97ca6a49909bc7d	Open original
Janady13/missionmatch / internal/modules/ai/safety.go	ai-intelligence-layer	5d5ddff70393a197c5f54a45280bb5dd42b24755	Open original
Janady13/missionmatch / internal/modules/ai/safety.go	w3-ai-staffing-recommendations	43d56387270ef4da4cabd794d97ca6a49909bc7d	Open original

Recovered source transcript

Download complete source text ↓126 lines · 5.8 KB

// Package ai is the augmented generation layer that sits ON TOP of the deterministic engine, never
// around it. It composes the augmented generation family (RAG over tenant documents, TAG over the tenant
// database of record, KAG over clearance and skills, GraphRAG over awards and opportunities, CAG over
// the stable public rules), routes each question to the cheapest sufficient strategy, and runs a
// faithfulness gate before any answer ships. It enforces, by construction, the platform's hard
// boundaries:
//
//   - EEO isolation is absolute. NO AI path may read, index, reference, or name the eeo schema. The
//     guards in this file refuse any SQL that mentions it, and a test walks every file in this package
//     and fails if the word ever appears outside a prohibition comment.
//   - The deterministic engine is the floor. The AI layer reads engine outputs and tenant data and
//     narrates; it never recomputes a score or routes around engine.ScoreCandidate.
//   - Reads are read only, parameterized, RLS scoped, and table allowlisted. The TAG layer chooses from
//     a curated set of safe query intents, never free form SQL, the injection resistant pattern.
//   - Every AI action emits an append only AEDT audit event.
package ai

import (
	"errors"
	"regexp"
	"strings"
)

// ErrEEOForbidden is returned when any AI path references the segregated EEO schema. It is a hard,
// non recoverable refusal: demographics must never reach a model, an index, a graph, or a generated query.
var ErrEEOForbidden = errors.New("ai: the eeo schema is forbidden to every AI path")

// ErrNotReadOnly is returned when a TAG query is anything other than a single read.
var ErrNotReadOnly = errors.New("ai: only a single read only statement is allowed")

// eeoMarkerRe matches any reference to the EEO schema, its table, or its demographic columns, in any
// casing. This is the runtime backstop behind the structural separation (sqlc never models eeo).
var eeoMarkerRe = regexp.MustCompile(`(?i)\beeo\b|candidate_demographics|race_ethnicity|veteran_status|disability_status`)

// mutatingRe matches any statement that is not a pure read. The TAG layer is read only.
var mutatingRe = regexp.MustCompile(`(?i)\b(insert|update|delete|drop|alter|create|truncate|grant|revoke|copy|merge|call|do|vacuum|comment|reindex|set|reset|begin|commit|rollback)\b`)

// ForbidEEO refuses any text (a generated query, a prompt, a retrieved chunk, a memory record) that
// references the EEO schema. Every AI code path that touches SQL or model context calls this; the test
// suite proves no path can skip it.
func ForbidEEO(text string) error {
	if eeoMarkerRe.MatchString(text) {
		return ErrEEOForbidden
	}
	return nil
}

// GuardReadOnlyQuery is the TAG safety gate. A query may execute only if it is a single SELECT (or a
// read only CTE leading to SELECT), references no EEO marker, and uses only allowlisted tables. It is the
// last line of defense behind the intent registry (which already constrains queries to a curated set);
// together they make a write or an EEO read impossible from the natural language path.
func GuardReadOnlyQuery(sql string, allowedTables map[string]bool) error {
	trimmed := strings.TrimSpace(sql)
	if trimmed == "" {
		return ErrNotReadOnly
	}
	// Exactly one statement: a stray semicolon (stacked queries) is refused.
	if strings.Count(strings.TrimRight(trimmed, "; \n\t"), ";") > 0 {
		return errors.New("ai: stacked statements are not allowed")
	}
	if err := ForbidEEO(trimmed); err != nil {
		return err
	}
	lower := strings.ToLower(trimmed)
	if !strings.HasPrefix(lower, "select") && !strings.HasPrefix(lower, "with") {
		return ErrNotReadOnly
	}
	// No mutating keyword may appear anywhere (a WITH ... that hides an INSERT, for example).
	if mutatingRe.MatchString(lower) {
		return ErrNotReadOnly
	}
	// Every referenced table (FROM/JOIN target) must be in the allowlist OR be a CTE defined in this same
	// query (a name introduced by WITH ... AS, which is not a real table).
	ctes := cteNames(lower)
	for _, tbl := range referencedTables(lower) {
		if !allowedTables[tbl] && !ctes[tbl] {
			return errors.New("ai: table " + tbl + " is not in the read allowlist")
		}
	}
	return nil
}

var tableRefRe = regexp.MustCompile(`(?i)\b(?:from|join)\s+([a-z_][a-z0-9_]*)`)
var cteNameRe = regexp.MustCompile(`(?i)(?:with|,)\s+([a-z_][a-z0-9_]*)\s+as\s*\(`)

// cteNames returns the names introduced by WITH ... AS in a read query, so the allowlist check does not
// reject a reference to a query local CTE.
func cteNames(lowerSQL string) map[string]bool {
	out := map[string]bool{}
	for _, m := range cteNameRe.FindAllStringSubmatch(lowerSQL, -1) {
		out[m[1]] = true
	}
	return out
}

// referencedTables extracts the FROM/JOIN table identifiers from a read query (lowercased). It is a
// conservative helper for the allowlist check; the intent registry is the primary control.
func referencedTables(lowerSQL string) []string {
	var out []string
	for _, m := range tableRefRe.FindAllStringSubmatch(lowerSQL, -1) {
		out = append(out, m[1])
	}
	return out
}

// ReadAllowlist is the set of tables the TAG layer may read. It is deliberately a curated subset of the
// public schema and contains NO eeo table, NO auth secret table, and NO demographic column source.
// Changing it is a security decision.
var ReadAllowlist = map[string]bool{
	"candidates":                    true,
	"candidate_skills":              true,
	"candidate_certifications":      true,
	"candidate_customer_experience": true,
	"requirements":                  true,
	"required_skills":               true,
	"opportunities":                 true,
	"opportunity_records":           true,
	"slates":                        true,
	"slate_members":                 true,
	"candidate_evaluations":         true,
	"skills":                        true,
	"sam_opportunities":             true,
	"usaspending_awards":            true,
	"bls_wages":                     true,
}