From b46c487206afb0420cfd64f43456a5c98b78a750 Mon Sep 17 00:00:00 2001 From: caelum0x Date: Tue, 25 Aug 2026 18:35:08 +0300 Subject: [PATCH] feat(graph): wire talent-graph validation gate into the service path (warn-only) --- .../src/services/talentGraphService.ts | 52 +++++- .../tests/unit/talentGraphGate.test.ts | 171 ++++++++++++++++++ 2 files changed, 222 insertions(+), 1 deletion(-) create mode 100644 gitgram/backend/tests/unit/talentGraphGate.test.ts diff --git a/gitgram/backend/src/services/talentGraphService.ts b/gitgram/backend/src/services/talentGraphService.ts index d4d81b7f..ca95abfe 100644 --- a/gitgram/backend/src/services/talentGraphService.ts +++ b/gitgram/backend/src/services/talentGraphService.ts @@ -1,6 +1,9 @@ import prisma from '../utils/prisma'; +import logger from '../utils/logger'; import { normalizePublicHttpUrl } from '../utils/publicHttpUrl'; import { canonicalizeSkill, canonicalizeSkills, expandSkillQueryTokens } from './skillTaxonomyService'; +import { deriveTalentEdges, type TalentGraphView } from './talentGraphEdges'; +import { validateEdges, type EdgeBatchResult } from './talentGraphOntology'; import type { PrismaClient } from '@prisma/client'; type EvidenceLevel = 'verified' | 'linked' | 'recorded'; @@ -56,6 +59,38 @@ function projectKey(owner: string | null, name: string, fullName: string | null) return (fullName || (owner ? `${owner}/${name}` : name)).toLowerCase(); } +/** + * Non-breaking validation gate for the assembled talent graph. + * + * `getTalentGraph` assembles a read-only dossier; it does not persist edges. This + * gate realizes the ontology guardrail on that read path: it derives typed, + * provenanced candidate edges from the assembled view and vets them with + * `validateEdges` (domain/range, provenance, symmetric dedup). It is WARN-ONLY — + * it never mutates, drops, or reshapes the response. Ontology-invalid + * ("hallucinated") structure is surfaced as a single structured warning (reason + * codes + endpoint types) so violations are observable via logs/metrics without + * changing any success-path output existing consumers depend on. Returns the + * batch result so callers and tests can inspect what the gate saw. + */ +export function auditTalentGraphEdges(view: TalentGraphView): EdgeBatchResult { + const result = validateEdges(deriveTalentEdges(view)); + if (result.rejected.length > 0) { + logger.warn('talent-graph edge validation rejected ontology-invalid edges', { + event: 'talent_graph.edge_validation.rejected', + developerId: view.profile.id, + acceptedCount: result.accepted.length, + rejectedCount: result.rejected.length, + rejections: result.rejected.map((entry) => ({ + edgeType: entry.input.type, + fromType: entry.input.from?.type, + toType: entry.input.to?.type, + codes: entry.rejections.map((rejection) => rejection.code), + })), + }); + } + return result; +} + export async function getTalentGraph(userId: string, options: { publicView?: boolean } = {}) { const [user, syncedProjects, managedRepositories] = await Promise.all([ prisma.user.findUnique({ @@ -356,7 +391,7 @@ export async function getTalentGraph(userId: string, options: { publicView?: boo (a, b) => b.sharedProjects.length - a.sharedProjects.length, ); - return { + const graph = { profile: { id: user.id, username: user.username, @@ -377,6 +412,21 @@ export async function getTalentGraph(userId: string, options: { publicView?: boo collaborators: talentCollaborators, generatedAt: new Date(), }; + + // Realize the ontology guardrail on the read path. Warn-only and defensive: + // the gate observes ontology-invalid structure but never changes `graph`, and a + // failure here must never break a dossier read. + try { + auditTalentGraphEdges(graph); + } catch (error) { + logger.error('talent-graph edge validation gate failed', { + event: 'talent_graph.edge_validation.error', + developerId: user.id, + error: error instanceof Error ? error.message : String(error), + }); + } + + return graph; } export async function findTalentMatches(requiredSkills: string[], limit = 12, db: TalentMatchDb = prisma) { diff --git a/gitgram/backend/tests/unit/talentGraphGate.test.ts b/gitgram/backend/tests/unit/talentGraphGate.test.ts new file mode 100644 index 00000000..baa1bf3f --- /dev/null +++ b/gitgram/backend/tests/unit/talentGraphGate.test.ts @@ -0,0 +1,171 @@ +/** + * Tests for the talent-graph validation GATE (not just the ontology library). + * + * The ontology unit tests (talentGraphOntology.test.ts) prove validateEdge / + * validateEdges are correct in isolation. These tests prove that the gate is + * actually WIRED into the service read path — `getTalentGraph` runs the assembled + * graph through `auditTalentGraphEdges` — and that it is non-breaking: + * - valid edges pass through with no warning and the response shape is unchanged, + * - an ontology-invalid edge (here: unparseable provenance timestamp from a + * corrupt DB row) triggers exactly one structured warning while the dossier is + * still returned intact (warn-only, nothing dropped, nothing reshaped). + * + * Prisma and the logger are mocked globally by tests/setup.ts. + */ +import { auditTalentGraphEdges, getTalentGraph } from '../../src/services/talentGraphService'; +import type { TalentGraphView } from '../../src/services/talentGraphEdges'; +import { mockPrisma } from '../setup'; +import logger from '../../src/utils/logger'; + +const warn = logger.warn as jest.Mock; + +function makeView(overrides: Partial = {}): TalentGraphView { + return { + profile: { id: 'dev-1' }, + projects: [ + { + id: 'repo-1', + url: 'https://github.com/acme/repo-1', + topics: ['typescript'], + verificationLevel: 'verified', + lastVerifiedAt: new Date('2026-01-01T00:00:00Z'), + evidence: [{ kind: 'repository_claim', sourceUrl: 'https://github.com/acme/repo-1' }], + }, + ], + collaborators: [], + ...overrides, + }; +} + +describe('auditTalentGraphEdges (the gate)', () => { + it('accepts well-typed edges from a clean view and emits no warning', () => { + const result = auditTalentGraphEdges(makeView()); + + expect(result.rejected).toHaveLength(0); + // developer→repo contribution + developer→skill has_skill. + expect(result.accepted.length).toBeGreaterThanOrEqual(2); + expect(warn).not.toHaveBeenCalled(); + }); + + it('rejects an ontology-invalid edge and emits one structured warning (warn-only)', () => { + // A corrupt DB timestamp flows into edge provenance as an unparseable date. + const corrupt = makeView({ + projects: [ + { + id: 'repo-1', + url: 'https://github.com/acme/repo-1', + topics: [], + verificationLevel: 'verified', + lastVerifiedAt: new Date('not-a-real-date'), + evidence: [{ kind: 'repository_claim', sourceUrl: null }], + }, + ], + }); + + const result = auditTalentGraphEdges(corrupt); + + expect(result.rejected.length).toBeGreaterThan(0); + expect(result.rejected[0].rejections.map((r) => r.code)).toContain('invalid_observed_at'); + + expect(warn).toHaveBeenCalledTimes(1); + const [message, meta] = warn.mock.calls[0]; + expect(message).toMatch(/edge validation rejected/i); + expect(meta).toMatchObject({ + event: 'talent_graph.edge_validation.rejected', + developerId: 'dev-1', + rejectedCount: result.rejected.length, + }); + expect(meta.rejections[0].codes).toContain('invalid_observed_at'); + }); +}); + +describe('getTalentGraph invokes the gate on the real read path', () => { + const userId = 'dev-real-1'; + + function seedUser() { + mockPrisma.user.__rows = [ + { + id: userId, + username: 'dev-real', + displayName: 'Dev Real', + avatar: null, + avatarUrl: null, + bio: null, + githubId: null, + githubUsername: null, + createdAt: new Date('2025-01-01T00:00:00Z'), + isPrivate: false, + }, + ]; + // Unused-but-queried tables must resolve to empty sets. + mockPrisma.repositoryManager.__rows = []; + mockPrisma.repositoryActivity.__rows = []; + // The talent* models are not part of the shared prisma mock; stub the reads + // getTalentGraph performs so the assembly runs without touching a real DB. + mockPrisma.talentPilot = { findMany: jest.fn().mockResolvedValue([]) }; + mockPrisma.talentPublicProof = { findMany: jest.fn().mockResolvedValue([]) }; + } + + function seedProject(updatedAt: Date) { + mockPrisma.project.__rows = [ + { + id: 'proj-1', + userId, + owner: 'acme', + name: 'repo-1', + fullName: 'acme/repo-1', + description: 'a project', + url: 'https://github.com/acme/repo-1', + repoUrl: 'https://github.com/acme/repo-1', + language: 'TypeScript', + tags: ['typescript'], + stars: 3, + forks: 1, + githubId: null, + updatedAt, + }, + ]; + } + + it('runs the gate and returns the unchanged dossier shape for clean data (no warning)', async () => { + seedUser(); + seedProject(new Date('2026-02-01T00:00:00Z')); + + const graph = await getTalentGraph(userId); + + // Success-path response shape is exactly what consumers depend on. + expect(graph).not.toBeNull(); + expect(graph).toEqual( + expect.objectContaining({ + profile: expect.objectContaining({ id: userId }), + summary: expect.objectContaining({ projectCount: 1 }), + projects: expect.any(Array), + collaborators: expect.any(Array), + generatedAt: expect.any(Date), + }), + ); + expect(graph!.projects).toHaveLength(1); + // Clean data => the gate found nothing to warn about. + expect(warn).not.toHaveBeenCalled(); + }); + + it('emits a gate warning when the assembled graph carries an ontology-invalid edge, still returning the dossier', async () => { + seedUser(); + // Corrupt persisted timestamp -> invalid edge provenance on the read path. + seedProject(new Date('totally-invalid')); + + const graph = await getTalentGraph(userId); + + // Warn-only: the dossier is still returned intact, nothing dropped. + expect(graph).not.toBeNull(); + expect(graph!.projects).toHaveLength(1); + + // The gate actually ran inside getTalentGraph and flagged the violation. + expect(warn).toHaveBeenCalledTimes(1); + const [, meta] = warn.mock.calls[0]; + expect(meta).toMatchObject({ + event: 'talent_graph.edge_validation.rejected', + developerId: userId, + }); + }); +});