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

1// Package governance is the AEDT governance surface: the model version registry, the org AEDT 2// inventory, the candidate notice and disclosure record, the retention sweep, and the audit read. It 3// runs on the app pool under RLS and never touches the eeo schema (that is the compliance pool's job). 4package governance 5 6import ( 7 "context" 8 "encoding/json" 9 "errors" 10 11 "github.com/google/uuid" 12 "github.com/jackc/pgx/v5" 13 14 "github.com/missionworkforce/missionmatch/internal/platform/audit" 15 "github.com/missionworkforce/missionmatch/internal/platform/database/dbgen" 16 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 17) 18 19// ErrNoDatabase is returned when no app pool is configured. 20var ErrNoDatabase = errors.New("governance: no database configured") 21 22// Service implements the AEDT governance operations. 23type Service struct { 24 db *tenant.DB 25 aud *audit.Writer 26 retentionDays int 27} 28 29// NewService builds the service. retentionDays is the configured retention window for identifiable 30// screening artifacts after a decision. 31func NewService(db *tenant.DB, aud *audit.Writer, retentionDays int) *Service { 32 return &Service{db: db, aud: aud, retentionDays: retentionDays} 33} 34 35func (s *Service) ok() error { 36 if s.db == nil || s.db.Pool == nil { 37 return ErrNoDatabase 38 } 39 return nil 40} 41 42// ListModelVersions returns the scoring model registry: each version with the weights and band cuts it 43// used, so a frozen decision is reproducible against the version that produced it. 44func (s *Service) ListModelVersions(ctx context.Context) ([]dbgen.AedtModelVersion, error) { 45 if err := s.ok(); err != nil { 46 return nil, err 47 } 48 var out []dbgen.AedtModelVersion 49 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 50 var e error 51 out, e = dbgen.New(tx).ListModelVersions(ctx) 52 return e 53 }) 54 return out, err 55} 56 57// ListInventory returns the org's register of automated employment decision tools in use. 58func (s *Service) ListInventory(ctx context.Context) ([]dbgen.AedtInventory, error) { 59 if err := s.ok(); err != nil { 60 return nil, err 61 } 62 var out []dbgen.AedtInventory 63 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 64 var e error 65 out, e = dbgen.New(tx).ListAedtInventory(ctx) 66 return e 67 }) 68 return out, err 69} 70 71// InventoryInput registers or updates one AEDT tool in the org inventory. 72type InventoryInput struct { 73 ToolKey string `json:"tool_key"` 74 DisplayName string `json:"display_name"` 75 Purpose string `json:"purpose"` 76 ModelVersion string `json:"model_version"` 77} 78 79// UpsertInventory records a tool in the org inventory and audits the change. 80func (s *Service) UpsertInventory(ctx context.Context, in InventoryInput) (dbgen.AedtInventory, error) { 81 if err := s.ok(); err != nil { 82 return dbgen.AedtInventory{}, err 83 } 84 var row dbgen.AedtInventory 85 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 86 var mv *string 87 if in.ModelVersion != "" { 88 mv = &in.ModelVersion 89 } 90 r, e := dbgen.New(tx).UpsertAedtInventory(ctx, dbgen.UpsertAedtInventoryParams{ 91 ToolKey: in.ToolKey, DisplayName: in.DisplayName, Purpose: in.Purpose, ModelVersion: mv, 92 }) 93 if e != nil { 94 return e 95 } 96 row = r 97 return s.audit(ctx, tx, audit.Event{Action: "aedt.inventory.recorded", EntityType: "aedt_tool", EntityID: in.ToolKey}) 98 }) 99 return row, err 100} 101 102// NoticeInput records that a candidate was given the AEDT notice and disclosure. 103type NoticeInput struct { 104 NoticeVersion string `json:"notice_version"` 105 DataCategories []string `json:"data_categories"` 106} 107 108// RecordNotice writes the candidate notice and disclosure record on the tenant tx and audits it. The 109// candidate consent itself lives in the unreadable eeo schema; this is the public schema disclosure 110// that the notice was provided. 111func (s *Service) RecordNotice(ctx context.Context, candidateID uuid.UUID, in NoticeInput) (dbgen.AedtCandidateNotice, error) { 112 if err := s.ok(); err != nil { 113 return dbgen.AedtCandidateNotice{}, err 114 } 115 cats := in.DataCategories 116 if len(cats) == 0 { 117 cats = DefaultDataCategories 118 } 119 catJSON, _ := json.Marshal(cats) 120 var row dbgen.AedtCandidateNotice 121 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 122 r, e := dbgen.New(tx).InsertCandidateNotice(ctx, dbgen.InsertCandidateNoticeParams{ 123 CandidateID: candidateID, 124 NoticeVersion: in.NoticeVersion, 125 DataCategories: catJSON, 126 RetentionDays: int32(s.retentionDays), 127 DisclosedBy: actorPtr(ctx), 128 }) 129 if e != nil { 130 return e 131 } 132 row = r 133 return s.audit(ctx, tx, audit.Event{Action: "aedt.candidate.notice_disclosed", EntityType: "candidate", EntityID: candidateID.String()}) 134 }) 135 return row, err 136} 137 138// RunRetention anonymizes the org's candidates whose most recent decision is older than the retention 139// window, wiping PII while keeping the de identified outcomes. It returns the number anonymized and 140// audits each. This is the on demand, RLS scoped sweep; a platform wide scheduled sweep needs a 141// privileged cross org enumeration and is a separate, flagged enhancement. 142func (s *Service) RunRetention(ctx context.Context) (int, error) { 143 if err := s.ok(); err != nil { 144 return 0, err 145 } 146 count := 0 147 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 148 q := dbgen.New(tx) 149 due, e := q.RetentionDueCandidates(ctx, int32(s.retentionDays)) 150 if e != nil { 151 return e 152 } 153 for _, id := range due { 154 rows, e := q.AnonymizeCandidate(ctx, id) 155 if e != nil { 156 return e 157 } 158 if rows > 0 { 159 count++ 160 // Purge the qualification child data too so the retention sweep leaves no child PII, 161 // matching the on demand erasure. The frozen slate_members outcomes are untouched. 162 for _, stmt := range []string{ 163 `DELETE FROM candidate_skills WHERE candidate_id = $1`, 164 `DELETE FROM candidate_certifications WHERE candidate_id = $1`, 165 `DELETE FROM candidate_customer_experience WHERE candidate_id = $1`, 166 } { 167 if _, e := tx.Exec(ctx, stmt, id); e != nil { 168 return e 169 } 170 } 171 if e := s.audit(ctx, tx, audit.Event{Action: "retention.candidate.anonymized", EntityType: "candidate", EntityID: id.String()}); e != nil { 172 return e 173 } 174 } 175 } 176 return nil 177 }) 178 return count, err 179} 180 181// ListAudit returns the org's audit trail (org isolated through the GUC bound query, not a Go filter). 182func (s *Service) ListAudit(ctx context.Context, limit, offset int32) ([]dbgen.AuditLog, error) { 183 if err := s.ok(); err != nil { 184 return nil, err 185 } 186 if limit <= 0 || limit > 500 { 187 limit = 100 188 } 189 var out []dbgen.AuditLog 190 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 191 var e error 192 out, e = dbgen.New(tx).ListAuditLogsForOrg(ctx, dbgen.ListAuditLogsForOrgParams{Limit: limit, Offset: offset}) 193 return e 194 }) 195 return out, err 196} 197 198// audit records a governance event on the caller's tenant tx and returns the write error so the 199// caller fails closed: a mutation that cannot be audited rolls back, matching the auth, sourcing, and 200// matching modules and the append only audit contract. 201func (s *Service) audit(ctx context.Context, tx pgx.Tx, e audit.Event) error { 202 if s.aud == nil { 203 return nil 204 } 205 e.ActorUserID = actorPtr(ctx) 206 return s.aud.OnTx(ctx, tx, e) 207} 208 209func actorPtr(ctx context.Context) *uuid.UUID { 210 if p, ok := tenant.UserFromContext(ctx); ok { 211 if id, err := uuid.Parse(p.UserID); err == nil { 212 return &id 213 } 214 } 215 return nil 216} 217 218// DefaultDataCategories is the AEDT disclosure list: the categories of data the scoring tools assess. 219// It is the single source of truth for the candidate notice, reused by the Mission Check result so the 220// in modal disclosure names exactly what governance records. None of these is a demographic attribute. 221var DefaultDataCategories = []string{ 222 "clearance self reported indicator", 223 "skills", 224 "certifications", 225 "customer agency experience", 226 "years of experience", 227 "work location and availability", 228} 229