feat(graph): wire talent-graph validation gate into the service path (warn-only)

This commit is contained in:
caelum0x 2026-08-25 18:35:08 +03:00
parent fd507e5efe
commit b46c487206
2 changed files with 222 additions and 1 deletions

View File

@ -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) {

View File

@ -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> = {}): 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,
});
});
});