@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/evals/dataset.mjs

@@ -0,0 +1,137 @@
+/**
+ * lib/evals/dataset.mjs — provenance-backed evaluation dataset: validation,
+ * leakage-safe splitting, expiry, and held-out selection (construct-6zga.1.6).
+ *
+ * A dataset item carries the provenance the governed improvement loop needs to
+ * evaluate a candidate on data it did not generate: source trace ids, human-label
+ * provenance, redaction state, a capability snapshot, the allowed tools, the
+ * expected evidence and contract behavior, a split assignment, and an expiry.
+ * Split assignment is deterministic and keyed on task family plus source trace, so
+ * every item from one trace lands in the same split — a candidate's generating
+ * trace can never leak across the train/dev/test boundary. selectEvalSet then
+ * strips the generating trace, near-duplicates, and the same user correction from
+ * the evaluation set so a candidate is never scored on its own origin. Reference
+ * shape: schemas/eval-dataset.schema.json.
+ */
+import crypto from 'node:crypto';
+
+export const EVAL_DATASET_SCHEMA_VERSION = 1;
+
+export const DATASET_SPLITS = Object.freeze(['train', 'dev', 'test']);
+export const REDACTION_STATES = Object.freeze(['raw', 'redacted', 'synthetic']);
+export const EVIDENCE_REQUIREMENTS = Object.freeze(['none', 'preferred', 'required']);
+export const LABEL_PROVENANCE = Object.freeze(['human', 'model-assisted', 'unlabeled']);
+export const CONTRACT_OUTCOMES = Object.freeze(['pass', 'fail', 'blocker', 'handoff']);
+export const CAPABILITY_CLASSES = Object.freeze(['hosted-direct', 'hosted-routed', 'local-capable', 'local-constrained', 'unknown']);
+
+function hashBucket(text) {
+  const digest = crypto.createHash('sha256').update(String(text)).digest();
+  return digest.readUInt32BE(0) % 100;
+}
+
+function normalizePrompt(text) {
+  return String(text || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function promptOf(item) {
+  return item?.taskInput?.prompt ?? item?.prompt ?? '';
+}
+
+export function nearDuplicateKey(item) {
+  const normalized = normalizePrompt(promptOf(item));
+  if (!normalized) return null;
+  return crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+}
+
+function primarySourceTrace(item) {
+  return Array.isArray(item?.sourceTraceIds) && item.sourceTraceIds.length ? item.sourceTraceIds[0] : null;
+}
+
+/**
+ * Deterministically assign a split. The bucket is keyed on task family plus the
+ * item's primary source trace, so all items sharing a trace co-locate in one
+ * split. devRatio/testRatio are fractions of the bucket space; the remainder is
+ * train.
+ */
+export function assignSplit(item, { devRatio = 0.15, testRatio = 0.15 } = {}) {
+  const trace = primarySourceTrace(item) || item?.id || '';
+  const bucket = hashBucket(`${item?.taskFamily || ''}:${trace}`);
+  const testCut = Math.round(testRatio * 100);
+  const devCut = testCut + Math.round(devRatio * 100);
+  if (bucket < testCut) return 'test';
+  if (bucket < devCut) return 'dev';
+  return 'train';
+}
+
+export function isExpired(item, nowIso) {
+  if (!item?.expiry || !nowIso) return false;
+  return String(item.expiry) <= String(nowIso);
+}
+
+/**
+ * Strip every item that would leak into a candidate's evaluation: the candidate's
+ * own generating / source traces, a near-duplicate task input, and the same user
+ * correction. This is the held-out guarantee (construct-6zga.1.6 AC2).
+ */
+export function excludeLeakage(items, candidate = {}) {
+  const list = Array.isArray(items) ? items : [];
+  const generatingTraces = new Set([
+    ...(Array.isArray(candidate.generatingTraceIds) ? candidate.generatingTraceIds : []),
+    ...(Array.isArray(candidate.sourceTraceIds) ? candidate.sourceTraceIds : []),
+  ]);
+  const candidateDupKey = nearDuplicateKey(candidate);
+  const candidateCorrection = candidate.correctionId ?? candidate.humanLabel?.correctionId ?? null;
+
+  return list.filter((item) => {
+    const traces = Array.isArray(item?.sourceTraceIds) ? item.sourceTraceIds : [];
+    if (traces.some((t) => generatingTraces.has(t))) return false;
+    if (candidateDupKey && nearDuplicateKey(item) === candidateDupKey) return false;
+    const correction = item?.humanLabel?.correctionId ?? null;
+    if (candidateCorrection && correction && correction === candidateCorrection) return false;
+    return true;
+  });
+}
+
+/**
+ * Build the evaluation set for a candidate: the items in the requested split,
+ * minus expired items, minus anything that would leak (excludeLeakage).
+ */
+export function selectEvalSet(items, candidate = {}, { split = 'test', nowIso = null } = {}) {
+  const list = Array.isArray(items) ? items : [];
+  const inSplit = list.filter((item) => item?.split === split && !isExpired(item, nowIso));
+  return excludeLeakage(inSplit, candidate);
+}
+
+/**
+ * Hand-rolled validator (no ajv — Construct stays dependency-free at startup).
+ * Returns { valid, errors } against schemas/eval-dataset.schema.json.
+ */
+export function validateDatasetItem(item) {
+  const errors = [];
+  if (!item || typeof item !== 'object') return { valid: false, errors: ['item is not an object'] };
+  if (item.schemaVersion !== EVAL_DATASET_SCHEMA_VERSION) errors.push(`schemaVersion must be ${EVAL_DATASET_SCHEMA_VERSION}`);
+  if (typeof item.id !== 'string' || !item.id) errors.push('id required');
+  if (typeof item.taskFamily !== 'string' || !item.taskFamily) errors.push('taskFamily required');
+  if (!item.taskInput || typeof item.taskInput.prompt !== 'string') errors.push('taskInput.prompt required');
+
+  if (!item.capabilitySnapshot || !CAPABILITY_CLASSES.includes(item.capabilitySnapshot.capabilityClass)) {
+    errors.push('capabilitySnapshot.capabilityClass invalid');
+  }
+  if (!Array.isArray(item.allowedTools)) errors.push('allowedTools must be an array');
+
+  const ev = item.expectedEvidenceBehavior;
+  if (!ev || !EVIDENCE_REQUIREMENTS.includes(ev.requirement) || typeof ev.citationsRequired !== 'boolean') {
+    errors.push('expectedEvidenceBehavior invalid');
+  }
+  if (!item.expectedContractResult || !CONTRACT_OUTCOMES.includes(item.expectedContractResult.outcome)) {
+    errors.push('expectedContractResult.outcome invalid');
+  }
+  if (!item.redaction || !REDACTION_STATES.includes(item.redaction.state)) errors.push('redaction.state invalid');
+
+  if (!Array.isArray(item.sourceTraceIds) || item.sourceTraceIds.length < 1) errors.push('sourceTraceIds must be non-empty');
+  if (!item.humanLabel || !LABEL_PROVENANCE.includes(item.humanLabel.provenance)) errors.push('humanLabel.provenance invalid');
+  if (!DATASET_SPLITS.includes(item.split)) errors.push(`split invalid: ${item.split}`);
+  if (item.expiry !== null && typeof item.expiry !== 'string') errors.push('expiry must be an ISO string or null');
+
+  return { valid: errors.length === 0, errors };
+}

package/lib/evals/gates.mjs

@@ -0,0 +1,175 @@
+/**
+ * lib/evals/gates.mjs — independent evaluation gates for the governed improvement
+ * loop (construct-6zga.1.6).
+ *
+ * Six deterministic gates run first and own the promotion decision: contract
+ * schema, source provenance, safety/permission behavior, tool use, cost/latency
+ * budgets, and output structure. Any deterministic regression blocks promotion —
+ * a candidate that fabricates a source, uses a disallowed tool, busts the budget,
+ * or returns the wrong contract outcome cannot ship. Model judges are supplemental:
+ * recordJudgeMetadata captures the model, profile, rubric/prompt version,
+ * repetitions, disagreement, human calibration, and abstention failures behind each
+ * verdict, and decidePromotion treats judges as a veto that can withhold promotion
+ * but never as a standalone signal that grants it. buildEvaluationReport presents
+ * the baseline/candidate deltas alongside the gate results and evaluator metadata.
+ */
+import { CONTRACT_OUTCOMES } from './dataset.mjs';
+
+export const EVAL_REPORT_SCHEMA_VERSION = 1;
+
+export const DETERMINISTIC_GATES = Object.freeze([
+  'contract-schema',
+  'source-provenance',
+  'safety-permission',
+  'tool-use',
+  'cost-latency',
+  'output-structure',
+]);
+
+export const JUDGE_VERDICTS = Object.freeze(['pass', 'fail', 'abstain']);
+
+function gate(name, pass, detail = null) {
+  return { gate: name, pass, detail: pass ? null : detail };
+}
+
+export function contractSchemaGate(candidate, item) {
+  const expected = item?.expectedContractResult?.outcome;
+  const actual = candidate?.contractResult?.outcome;
+  const pass = CONTRACT_OUTCOMES.includes(actual) && actual === expected;
+  return gate('contract-schema', pass, `expected ${expected}, got ${actual ?? 'none'}`);
+}
+
+// Every cited source must resolve to a known source trace, and required evidence
+// must be present — a fabricated citation or missing required evidence fails the
+// gate even if the answer looks right.
+
+export function sourceProvenanceGate(candidate, item) {
+  const known = new Set(Array.isArray(item?.sourceTraceIds) ? item.sourceTraceIds : []);
+  const cited = Array.isArray(candidate?.citedSourceIds) ? candidate.citedSourceIds : [];
+  const fabricated = cited.filter((c) => !known.has(c));
+  const requirement = item?.expectedEvidenceBehavior?.requirement || 'none';
+  const citationsRequired = item?.expectedEvidenceBehavior?.citationsRequired === true;
+  const missingEvidence = requirement === 'required' && candidate?.evidence?.provided !== true;
+  const missingCitations = citationsRequired && cited.length === 0;
+  const pass = fabricated.length === 0 && !missingEvidence && !missingCitations;
+  const reasons = [
+    fabricated.length ? `fabricated sources: ${fabricated.join(', ')}` : null,
+    missingEvidence ? 'required evidence missing' : null,
+    missingCitations ? 'required citations missing' : null,
+  ].filter(Boolean).join('; ');
+  return gate('source-provenance', pass, reasons);
+}
+
+export function safetyPermissionGate(candidate) {
+  const violations = Array.isArray(candidate?.permissionViolations) ? candidate.permissionViolations : [];
+  return gate('safety-permission', violations.length === 0, `permission violations: ${violations.join(', ')}`);
+}
+
+export function toolUseGate(candidate, item) {
+  const allowed = new Set(Array.isArray(item?.allowedTools) ? item.allowedTools : []);
+  const used = Array.isArray(candidate?.toolsUsed) ? candidate.toolsUsed : [];
+  const disallowed = used.filter((t) => !allowed.has(t));
+  return gate('tool-use', disallowed.length === 0, `disallowed tools: ${disallowed.join(', ')}`);
+}
+
+export function costLatencyGate(candidate, budgets = {}) {
+  const maxCost = Number.isFinite(budgets?.maxCost) ? budgets.maxCost : Infinity;
+  const maxLatencyMs = Number.isFinite(budgets?.maxLatencyMs) ? budgets.maxLatencyMs : Infinity;
+  const overCost = Number.isFinite(candidate?.cost) && candidate.cost > maxCost;
+  const overLatency = Number.isFinite(candidate?.latencyMs) && candidate.latencyMs > maxLatencyMs;
+  const reasons = [
+    overCost ? `cost ${candidate.cost} > ${maxCost}` : null,
+    overLatency ? `latency ${candidate.latencyMs}ms > ${maxLatencyMs}ms` : null,
+  ].filter(Boolean).join('; ');
+  return gate('cost-latency', !overCost && !overLatency, reasons);
+}
+
+export function outputStructureGate(candidate) {
+  const pass = candidate?.output != null && candidate?.outputStructured !== false;
+  return gate('output-structure', pass, 'output missing or structurally invalid');
+}
+
+/**
+ * Run all deterministic gates. Any failure blocks promotion (construct-6zga.1.6
+ * AC3): the regression list names every gate that failed.
+ */
+export function runDeterministicGates(candidate, item, budgets = {}) {
+  const gates = [
+    contractSchemaGate(candidate, item),
+    sourceProvenanceGate(candidate, item),
+    safetyPermissionGate(candidate),
+    toolUseGate(candidate, item),
+    costLatencyGate(candidate, budgets),
+    outputStructureGate(candidate),
+  ];
+  const regressions = gates.filter((g) => !g.pass).map((g) => g.gate);
+  return { gates, blocked: regressions.length > 0, regressions };
+}
+
+/**
+ * Normalize a model-judge record. A judge is supplemental evidence; the record
+ * keeps the metadata that makes its verdict auditable and calibratable.
+ */
+export function recordJudgeMetadata(judge = {}) {
+  return {
+    model: judge.model ?? null,
+    profile: judge.profile ?? null,
+    rubricVersion: judge.rubricVersion ?? null,
+    promptVersion: judge.promptVersion ?? null,
+    repetitions: Number.isFinite(judge.repetitions) ? judge.repetitions : 0,
+    disagreement: Number.isFinite(judge.disagreement) ? judge.disagreement : null,
+    humanCalibration: Number.isFinite(judge.humanCalibration) ? judge.humanCalibration : null,
+    abstentionFailures: Number.isFinite(judge.abstentionFailures) ? judge.abstentionFailures : 0,
+    verdict: JUDGE_VERDICTS.includes(judge.verdict) ? judge.verdict : 'abstain',
+  };
+}
+
+/**
+ * Decide promotion. Deterministic gates are mandatory and final: a missing or
+ * blocked deterministic result is never promotable, and no judge can override a
+ * deterministic block. Judges are a veto only — they can withhold promotion with a
+ * fail verdict but never grant it on their own (construct-6zga.1.6 AC4).
+ */
+export function decidePromotion({ deterministic = null, judges = [] } = {}) {
+  const judging = Array.isArray(judges) ? judges.map(recordJudgeMetadata) : [];
+  if (!deterministic || deterministic.blocked) {
+    const reason = deterministic?.blocked
+      ? `deterministic regression: ${deterministic.regressions.join(', ')}`
+      : 'no deterministic gate result';
+    return { promotable: false, reason, judgesConsulted: judging.length };
+  }
+  const failing = judging.filter((j) => j.verdict === 'fail');
+  if (failing.length > 0) {
+    return { promotable: false, reason: `judge withheld: ${failing.length} fail verdict(s)`, judgesConsulted: judging.length };
+  }
+  return { promotable: true, reason: 'deterministic gates passed; no judge objection', judgesConsulted: judging.length };
+}
+
+function numDelta(baseline, candidate) {
+  if (!Number.isFinite(baseline) || !Number.isFinite(candidate)) return null;
+  return { baseline, candidate, delta: candidate - baseline };
+}
+
+/**
+ * Build the evaluation report: baseline/candidate deltas, the deterministic gate
+ * results, the evaluator (judge) metadata, and the promotion decision. Judges
+ * never stand alone — the decision is computed through decidePromotion.
+ */
+export function buildEvaluationReport({ baseline = null, candidate = null, deterministic = null, judges = [] } = {}) {
+  const deltas = baseline && candidate
+    ? {
+      cost: numDelta(baseline.cost, candidate.cost),
+      latencyMs: numDelta(baseline.latencyMs, candidate.latencyMs),
+      contractOutcome: { baseline: baseline.contractResult?.outcome ?? null, candidate: candidate.contractResult?.outcome ?? null },
+    }
+    : null;
+
+  return {
+    schemaVersion: EVAL_REPORT_SCHEMA_VERSION,
+    deltas,
+    gates: deterministic?.gates || [],
+    blocked: deterministic?.blocked ?? null,
+    evaluators: (Array.isArray(judges) ? judges : []).map(recordJudgeMetadata),
+    decision: decidePromotion({ deterministic, judges }),
+  };
+}

package/lib/export-branding.mjs

@@ -0,0 +1,32 @@
+/**
+ * lib/export-branding.mjs — one honest branding contract for distribution exports.
+ */
+
+import { BRAND_CAPABLE_FORMATS, PLAIN_OUTPUT_FORMATS } from './artifact-manifest.mjs';
+
+export const EXPORT_BRANDING_CAPABILITIES = Object.freeze({
+  pdf: { capable: true, mechanism: 'typst-template', asset: 'construct-pdf.typ' },
+  html: { capable: true, mechanism: 'pandoc-template', asset: 'construct-web.html' },
+  deck: { capable: true, mechanism: 'pandoc-template', asset: 'construct-deck.html' },
+  pptx: { capable: true, mechanism: 'native-pptx', asset: 'pptxgenjs' },
+  docx: { capable: true, mechanism: 'reference-doc', asset: 'construct-reference.docx' },
+  doc: { capable: true, mechanism: 'docx-reference-via-libreoffice', asset: 'construct-reference.docx' },
+  rtf: { capable: true, mechanism: 'pandoc-writer', asset: null },
+  odt: { capable: true, mechanism: 'pandoc-writer', asset: null },
+  epub: { capable: true, mechanism: 'pandoc-writer', asset: null },
+  tex: { capable: true, mechanism: 'pandoc-writer', asset: null },
+  txt: { capable: false, mechanism: 'plain-source', asset: null },
+  md: { capable: false, mechanism: 'plain-source', asset: null },
+  mdx: { capable: false, mechanism: 'plain-source', asset: null },
+});
+
+export function resolveExportBranding(format, requested = 'construct') {
+  const capability = EXPORT_BRANDING_CAPABILITIES[format];
+  if (!capability) return { requested, applied: 'none', capable: false, reason: 'unsupported format' };
+  if (!BRAND_CAPABLE_FORMATS.includes(format) || PLAIN_OUTPUT_FORMATS.includes(format)) {
+    return { requested, applied: 'none', capable: false, reason: 'format has no styling surface' };
+  }
+  if (requested === 'plain') return { requested, applied: 'plain', capable: true, mechanism: capability.mechanism, reason: 'explicit opt-out' };
+  return { requested: 'construct', applied: 'construct', capable: true, mechanism: capability.mechanism, asset: capability.asset, reason: 'default policy' };
+}
+

package/lib/graph/build-co-change.mjs

@@ -0,0 +1,54 @@
+/**
+ * lib/graph/build-co-change.mjs — co-change corroboration layer.
+ *
+ * Adds the third leg of hybrid population (after registry ingest and static
+ * import derivation): module nodes for each source directory, `contains` edges
+ * (module→file/test) that anchor those modules to the file graph, and
+ * `co_changes` edges between directories that change together in git history.
+ *
+ * The git analysis reuses captureDependencyPatterns, which also records the
+ * same directory relationships into the knowledge-graph entity store — so the
+ * matrix and the entity graph share one co-change source of truth.
+ */
+
+import { captureDependencyPatterns } from '../artifact-capture.mjs';
+import { nodeId } from './store.mjs';
+
+function moduleOf(rel) {
+  return rel.split('/').slice(0, 2).join('/');
+}
+
+function fileNodeId(rel) {
+  return (rel.endsWith('.test.mjs') || rel.endsWith('.test.js')) ? `test:${rel}` : `file:${rel}`;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.rootDir — repo whose git history and entity store are read/written.
+ * @param {string[]} [opts.sourceRels] — repo-relative source paths to anchor under modules.
+ * @returns {{ nodes: object[], edges: object[] }}
+ */
+export function buildCoChange({ rootDir, sourceRels = [] }) {
+  const nodes = [];
+  const edges = [];
+  const modules = new Set();
+
+  for (const rel of sourceRels) {
+    const mod = moduleOf(rel);
+    modules.add(mod);
+    edges.push({ from: nodeId('module', mod), to: fileNodeId(rel), rel: 'contains', source: 'import-graph' });
+  }
+
+  let pairs = [];
+  try { pairs = captureDependencyPatterns(rootDir) || []; } catch { pairs = []; }
+  for (const { a, b, count } of pairs) {
+    modules.add(a);
+    modules.add(b);
+    const [from, to] = [a, b].sort();
+    edges.push({ from: nodeId('module', from), to: nodeId('module', to), rel: 'co_changes', weight: count, source: 'co-change' });
+  }
+
+  for (const mod of modules) nodes.push({ id: nodeId('module', mod), type: 'module', name: mod, attrs: {} });
+
+  return { nodes, edges };
+}

package/lib/graph/build-from-registry.mjs

@@ -0,0 +1,136 @@
+/**
+ * lib/graph/build-from-registry.mjs — seed the dependency graph from the
+ * authoritative declarative catalogs.
+ *
+ * Ingests registry/capabilities.json, lib/embedded-contract/workflow-defs.mjs,
+ * and specialists/contracts.json into typed nodes and directed edges:
+ *   capability --embeds-->     workflow      (embeddedWorkflow)
+ *   test       --validates-->  capability    (verification.functional / hostEmulation / per-surface test)
+ *   capability --uses-->       skill | rule  (skill + dependencies.skills/.rules)
+ *   capability --governed_by-->contract      (contracts[])
+ *   capability --exposes-->    surface       (supported surfaces)
+ * Node existence on disk (tests, skills, rules) is stamped as an attr so the
+ * Oracle collector can later distinguish declared-but-missing from realized.
+ * Covers the registry half of the hybrid population; the import-graph half
+ * (file/module nodes, imports/covers/realizes) lands in build-import-graph.
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+import { listWorkflowDefs } from '../embedded-contract/workflow-defs.mjs';
+import { loadCapabilityRegistry } from '../registry/validate.mjs';
+import { nodeId } from './store.mjs';
+
+function readJsonSafe(filePath) {
+  try { return JSON.parse(readFileSync(filePath, 'utf8')); } catch { return null; }
+}
+
+function existsRel(rootDir, rel) {
+  return !!rel && existsSync(path.join(rootDir, rel));
+}
+
+function hashFiles(rootDir, rels) {
+  const h = createHash('sha256');
+  for (const rel of rels) {
+    h.update(rel);
+    try { h.update(readFileSync(path.join(rootDir, rel))); } catch { h.update('\0missing'); }
+  }
+  return h.digest('hex').slice(0, 16);
+}
+
+/**
+ * Build the registry-seeded portion of the dependency graph.
+ *
+ * @param {object} opts
+ * @param {string} opts.rootDir — Construct package root holding registry/, specialists/.
+ * @returns {{ nodes: object[], edges: object[], sourceHash: string }}
+ */
+export function buildFromRegistry({ rootDir }) {
+  const nodes = [];
+  const edges = [];
+  const node = (type, key, name, attrs) => nodes.push({ id: nodeId(type, key), type, name: name ?? key, attrs: attrs || {} });
+  const edge = (from, rel, to) => edges.push({ from, to, rel, source: 'registry' });
+
+  // Workflow catalog: every embedded workflow type is a node regardless of
+  // capability coverage, so reverse queries see uncovered workflows.
+
+  const workflowDefs = listWorkflowDefs();
+  for (const wf of workflowDefs) {
+    node('workflow', wf.type, wf.type, {
+      tier: wf.tier,
+      defaultApprovalMode: wf.defaultApprovalMode,
+      chain: wf.chain,
+      description: wf.description,
+    });
+  }
+
+  const contractsDoc = readJsonSafe(path.join(rootDir, 'specialists', 'contracts.json'));
+  for (const c of contractsDoc?.contracts ?? []) {
+    if (!c?.id) continue;
+    node('contract', c.id, c.id, { producer: c.producer ?? null, consumer: c.consumer ?? null });
+  }
+
+  const registry = loadCapabilityRegistry({ rootDir });
+  for (const cap of registry.capabilities ?? []) {
+    if (!cap.id) continue;
+    const capNode = nodeId('capability', cap.id);
+    node('capability', cap.id, cap.name ?? cap.id, {
+      kind: cap.kind ?? 'capability',
+      criticality: cap.criticality ?? null,
+      humanGate: cap.humanGate ?? null,
+      lastValidated: cap.lastValidated ?? null,
+      ownerSpecialists: cap.ownerSpecialists ?? [],
+      surfaces: cap.surfaces ?? {},
+    });
+
+    if (cap.embeddedWorkflow) edge(capNode, 'embeds', nodeId('workflow', cap.embeddedWorkflow));
+
+    const ver = cap.verification ?? {};
+    for (const rel of [ver.functional, ver.hostEmulation].filter(Boolean)) {
+      const tid = nodeId('test', rel);
+      node('test', rel, rel, { path: rel, exists: existsRel(rootDir, rel) });
+      edge(tid, 'validates', capNode);
+    }
+
+    for (const [surface, status] of Object.entries(cap.surfaces ?? {})) {
+      if (!status?.supported) continue;
+      node('surface', surface, surface, {});
+      edge(capNode, 'exposes', nodeId('surface', surface));
+      if (status.primary) {
+        const tierTest = path.join('tests', 'capabilities', cap.id, `${surface}.test.mjs`);
+        if (existsRel(rootDir, tierTest)) {
+          node('test', tierTest, tierTest, { path: tierTest, exists: true });
+          edge(nodeId('test', tierTest), 'validates', capNode);
+        }
+      }
+    }
+
+    const skillIds = new Set([cap.skill, ...(cap.dependencies?.skills ?? [])].filter(Boolean));
+    for (const sid of skillIds) {
+      node('skill', sid, sid, { exists: existsRel(rootDir, path.join('skills', `${sid}.md`)) });
+      edge(capNode, 'uses', nodeId('skill', sid));
+    }
+
+    for (const rid of cap.dependencies?.rules ?? []) {
+      node('rule', rid, rid, { exists: existsRel(rootDir, rid) });
+      edge(capNode, 'uses', nodeId('rule', rid));
+    }
+
+    for (const cid of cap.contracts ?? []) {
+      node('contract', cid, cid, {});
+      edge(capNode, 'governed_by', nodeId('contract', cid));
+    }
+  }
+
+  const sourceHash = hashFiles(rootDir, [
+    'registry/capabilities.json',
+    'specialists/contracts.json',
+    'lib/embedded-contract/workflow-defs.mjs',
+  ]);
+
+  return { nodes, edges, sourceHash };
+}
+
+export { hashFiles };