@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/graph/gaps.mjs

@@ -0,0 +1,41 @@
+/**
+ * lib/graph/gaps.mjs — coverage-gap queries over the living dependency graph.
+ *
+ * findMissingTestCapabilities() answers "which capabilities/workflows have
+ * zero validating tests" by reading the persisted graph's inbound validates
+ * edges — the C1 store already dedups test --validates--> capability edges
+ * from both registry (verification.functional/hostEmulation) and
+ * corpus-annotation (@capability tags) sources, so a zero-count here is a
+ * real gap, not a source-coverage artifact. A workflow is flagged only when
+ * every capability that embeds it also has zero validating tests, since a
+ * partially-tested workflow is a weaker signal than an untested capability.
+ */
+
+import { loadGraph, nodesByType, dependentsOf, dependenciesOf } from './store.mjs';
+
+/**
+ * @param {string} rootDir
+ * @returns {{ graphPresent: boolean, capabilities: string[], workflows: string[] }}
+ */
+export function findMissingTestCapabilities(rootDir) {
+  const graph = loadGraph(rootDir);
+  if (!graph.exists) return { graphPresent: false, capabilities: [], workflows: [] };
+
+  const untestedCapIds = new Set();
+  for (const cap of nodesByType(graph, 'capability')) {
+    if (dependentsOf(graph, cap.id, 'validates').length === 0) untestedCapIds.add(cap.id);
+  }
+
+  const untestedWorkflows = [];
+  for (const wf of nodesByType(graph, 'workflow')) {
+    const embeddingCaps = dependentsOf(graph, wf.id, 'embeds');
+    if (embeddingCaps.length === 0) continue;
+    if (embeddingCaps.every((capId) => untestedCapIds.has(capId))) untestedWorkflows.push(wf.id);
+  }
+
+  return {
+    graphPresent: true,
+    capabilities: [...untestedCapIds].sort(),
+    workflows: untestedWorkflows.sort(),
+  };
+}

package/lib/graph/impacted.mjs

@@ -0,0 +1,129 @@
+/**
+ * lib/graph/impacted.mjs — change-impact traversal for `construct graph impacted`.
+ *
+ * Given a set of changed repo-relative file paths, walks the living
+ * dependency graph forward from each changed-file node through `imports`
+ * (reverse — files/tests that import the changed file), `realizes`
+ * (changed file → capability), `embeds` (capability → workflow), `validates`
+ * (test → capability, reverse to find tests), and `documents` (doc → workflow
+ * or provider, reverse to find docs) edges to answer: which workflows, tests,
+ * and docs does this changeset touch. Scopes which checks a PR must run for a
+ * CI drift gate. A changed path absent from the graph is reported in
+ * `unknown` rather than raising — an unrecognized file (renamed, deleted,
+ * generated, or simply not yet built into the graph) is common and must not
+ * crash the traversal.
+ */
+
+import { loadGraph, dependenciesOf, dependentsOf } from './store.mjs';
+
+function toFileNodeId(rel) {
+  return rel.endsWith('.test.mjs') || rel.endsWith('.test.js') ? `test:${rel}` : `file:${rel}`;
+}
+
+function normalizeChangedPaths(changedFiles) {
+  return [...new Set((changedFiles || []).map((f) => f.split('\\').join('/').replace(/^\.\//, '')))].filter(Boolean);
+}
+
+// Reverse-import closure: every file/test/module that transitively imports
+// the changed node, so a leaf-file edit surfaces every consumer up the chain.
+
+function reverseImportClosure(graph, startId) {
+  const reached = new Set();
+  const stack = [startId];
+  while (stack.length) {
+    const id = stack.pop();
+    for (const importer of dependentsOf(graph, id, 'imports')) {
+      if (reached.has(importer)) continue;
+      reached.add(importer);
+      stack.push(importer);
+    }
+  }
+  return reached;
+}
+
+function stripPrefix(id) {
+  const colon = id.indexOf(':');
+  return colon === -1 ? id : id.slice(colon + 1);
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.rootDir — project root holding .cx/graph/.
+ * @param {string[]} opts.changedFiles — repo-relative paths.
+ * @returns {{
+ *   graphPresent: boolean,
+ *   changed: string[],
+ *   unknown: string[],
+ *   impactedWorkflows: string[],
+ *   impactedTests: string[],
+ *   impactedDocs: string[],
+ *   impactedCapabilities: string[],
+ * }}
+ */
+export function computeImpacted({ rootDir, changedFiles }) {
+  const changed = normalizeChangedPaths(changedFiles);
+  const graph = loadGraph(rootDir);
+
+  if (!graph.exists) {
+    return {
+      graphPresent: false,
+      changed,
+      unknown: changed,
+      impactedWorkflows: [],
+      impactedTests: [],
+      impactedDocs: [],
+      impactedCapabilities: [],
+    };
+  }
+
+  const unknown = [];
+  const capabilities = new Set();
+  const tests = new Set();
+  const workflows = new Set();
+  const docs = new Set();
+
+  for (const rel of changed) {
+    const id = toFileNodeId(rel);
+    if (!graph.nodes.has(id)) { unknown.push(rel); continue; }
+
+    if (id.startsWith('test:')) tests.add(id);
+
+    for (const consumer of reverseImportClosure(graph, id)) {
+      if (consumer.startsWith('test:')) tests.add(consumer);
+    }
+
+    for (const cap of dependenciesOf(graph, id, 'realizes')) capabilities.add(cap);
+  }
+
+  // A capability reached via realizes pulls in its validating tests and its
+  // embedded workflow; a test reached via the import closure pulls in every
+  // capability it validates, closing the loop in either direction.
+
+  for (const cap of [...capabilities]) {
+    for (const t of dependentsOf(graph, cap, 'validates')) tests.add(t);
+    for (const wf of dependenciesOf(graph, cap, 'embeds')) workflows.add(wf);
+  }
+  for (const t of tests) {
+    for (const cap of dependenciesOf(graph, t, 'validates')) {
+      capabilities.add(cap);
+      for (const wf of dependenciesOf(graph, cap, 'embeds')) workflows.add(wf);
+    }
+  }
+
+  // Docs point at what they document (doc --documents--> workflow|provider),
+  // so a doc is impacted when it documents a workflow already in scope.
+
+  for (const wf of workflows) {
+    for (const doc of dependentsOf(graph, wf, 'documents')) docs.add(doc);
+  }
+
+  return {
+    graphPresent: true,
+    changed,
+    unknown: unknown.sort(),
+    impactedWorkflows: [...workflows].map(stripPrefix).sort(),
+    impactedTests: [...tests].map(stripPrefix).sort(),
+    impactedDocs: [...docs].map(stripPrefix).sort(),
+    impactedCapabilities: [...capabilities].map(stripPrefix).sort(),
+  };
+}

package/lib/graph/runtime-evidence.mjs

@@ -0,0 +1,177 @@
+/**
+ * lib/graph/runtime-evidence.mjs — runtime-evidence edges: traces linked to workflow nodes (LMCP-C9).
+ *
+ * The living graph has static edges only (registry, import-graph, co-change,
+ * corpus-annotation) — a workflow can be green in every one of those and still
+ * never have executed successfully. This module closes that gap by reading
+ * persisted orchestration run records (`<stateRoot>/runtime/orchestration/runs/*.json`,
+ * ADR-0066's machine-scoped location for the Mode-A filesystem run store
+ * lib/orchestration/run-store.mjs writes to) read-only and mapping each run
+ * that resolves to a workflow type onto a
+ * `runtime-evidence:<runId> --evidenced_by--> workflow:<type>` edge, carrying
+ * `{ timestamp, outcome }` on the runtime-evidence node's attrs. One node per
+ * run (not one node per workflow) so repeated runs of the same workflow each
+ * leave their own evidence rather than collapsing into a single edge whose
+ * weight-summing (store.mjs normalizeEdges) would blur distinct timestamps.
+ *
+ * A run's workflow type is `run.request.workflowType`, falling back to
+ * `run.plan.suggestedWorkflowType` (the same fallback lib/orchestration/
+ * run-store.mjs's listRuns already exposes) — a run with neither is not
+ * attributable to a workflow node and is skipped, not fabricated onto one.
+ * Outcome favors the F4-aggregated `run.executionState` (executed |
+ * degraded-executed | prepared | failed) when present since it already
+ * reconciles every task's signal; a legacy run with no executionState falls
+ * back to a coarser mapping off `run.status`.
+ *
+ * `latestEvidenceByWorkflow` reduces the per-run nodes to one summary per
+ * workflow type (most recent timestamp wins) — the shape `graph explain` and
+ * the C6 execution-staleness dimension (staleness.mjs) both consume, so a
+ * workflow's "last execution" is defined in exactly one place.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { nodeId } from './store.mjs';
+import { listWorkflowDefs } from '../embedded-contract/workflow-defs.mjs';
+import { runtimeDir } from '../orchestration/run-store.mjs';
+
+function runsDir(rootDir) {
+  return path.join(runtimeDir(rootDir), 'runs');
+}
+
+/**
+ * Read every persisted run record. Read-only — this module never writes to
+ * the orchestration run store. A corrupt run file is skipped, not fatal.
+ *
+ * @param {string} rootDir
+ * @returns {object[]}
+ */
+export function readRunRecords(rootDir) {
+  const dir = runsDir(rootDir);
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    try {
+      out.push(JSON.parse(readFileSync(path.join(dir, name), 'utf8')));
+    } catch {
+      /* a corrupt run file is skipped, not fatal to evidence collection */
+    }
+  }
+  return out;
+}
+
+function resolveWorkflowType(run) {
+  return run?.request?.workflowType || run?.plan?.suggestedWorkflowType || null;
+}
+
+// run.executionState (LMCP-F4) already reconciles every task's signal into
+// one of executed | degraded-executed | prepared | failed; only a legacy run
+// with no executionState falls back to the coarser run.status mapping.
+
+const STATUS_TO_OUTCOME = {
+  'completed': 'executed',
+  'degraded': 'degraded-executed',
+  'completed-prepare-only': 'prepared',
+  'completed-with-failures': 'failed',
+  'cancelled': 'failed',
+  'error': 'failed',
+};
+
+function resolveOutcome(run) {
+  if (run.executionState) return run.executionState;
+  return STATUS_TO_OUTCOME[run.status] || null;
+}
+
+function resolveTimestamp(run) {
+  return run.updatedAt || run.createdAt || null;
+}
+
+/**
+ * Map every persisted run onto a runtime-evidence node + evidenced_by edge to
+ * its workflow node, when the run resolves to a known workflow type and has
+ * reached a terminal (non-planned, non-running) state.
+ *
+ * @param {object} opts
+ * @param {string} opts.rootDir
+ * @returns {{ nodes: object[], edges: object[], skippedRunIds: string[] }}
+ */
+export function buildRuntimeEvidence({ rootDir }) {
+  const runs = readRunRecords(rootDir);
+  const nodes = [];
+  const edges = [];
+  const skipped = [];
+
+  for (const run of runs) {
+    if (!run?.runId) continue;
+    if (run.status === 'planned' || run.status === 'running') { skipped.push(run.runId); continue; }
+    const workflowType = resolveWorkflowType(run);
+    if (!workflowType) { skipped.push(run.runId); continue; }
+
+    const timestamp = resolveTimestamp(run);
+    const outcome = resolveOutcome(run);
+    const evidenceId = nodeId('runtime-evidence', run.runId);
+    const workflowNodeId = nodeId('workflow', workflowType);
+
+    nodes.push({
+      id: evidenceId,
+      type: 'runtime-evidence',
+      name: run.runId,
+      attrs: {
+        runId: run.runId,
+        workflowType,
+        timestamp,
+        outcome,
+        status: run.status,
+        taskCount: Array.isArray(run.tasks) ? run.tasks.length : 0,
+      },
+    });
+    edges.push({
+      from: evidenceId,
+      to: workflowNodeId,
+      rel: 'evidenced_by',
+      source: 'runtime-evidence',
+    });
+  }
+
+  return { nodes, edges, skippedRunIds: skipped };
+}
+
+/**
+ * Reduce per-run evidence nodes to one summary per workflow type: the most
+ * recent timestamp wins. Workflow types with zero evidence are present with
+ * `lastExecution: null` so a caller can distinguish never-executed from
+ * merely-stale without a second pass over the graph.
+ *
+ * @param {{ nodes: object[] }} evidence — buildRuntimeEvidence() output.
+ * @returns {Record<string, { timestamp: string, outcome: string, runId: string }|null>}
+ */
+export function latestEvidenceByWorkflow(evidence) {
+  const byWorkflow = {};
+  for (const wf of listWorkflowDefs()) {
+    byWorkflow[wf.type] = null;
+  }
+  for (const n of evidence.nodes) {
+    if (n.type !== 'runtime-evidence') continue;
+    const { workflowType, timestamp, outcome, runId } = n.attrs || {};
+    if (!workflowType || !timestamp) continue;
+    const prev = byWorkflow[workflowType];
+    if (!prev || String(timestamp) > String(prev.timestamp)) {
+      byWorkflow[workflowType] = { timestamp, outcome, runId };
+    }
+  }
+  return byWorkflow;
+}
+
+/**
+ * Convenience: read runs directly off disk and reduce to per-workflow last
+ * execution in one call, for callers (CLI, staleness) that don't need the
+ * raw node/edge lists.
+ *
+ * @param {string} rootDir
+ * @returns {Record<string, { timestamp: string, outcome: string, runId: string }|null>}
+ */
+export function computeLastExecutionByWorkflow(rootDir) {
+  return latestEvidenceByWorkflow(buildRuntimeEvidence({ rootDir }));
+}

package/lib/graph/security-coverage.mjs

@@ -0,0 +1,113 @@
+/**
+ * lib/graph/security-coverage.mjs — wire the adversarial/security test corpus
+ * into the living graph and measure OWASP GenAI coverage (LMCP-N8).
+ *
+ * A security test disconnected from the workflows it protects leaves coverage
+ * unmeasurable. This module makes the linkage a first-class graph fact: a test
+ * annotated `@owasp LLM01` (and optionally
+ * `@secures <workflow-id>`) becomes a test node carrying its OWASP categories,
+ * plus a `test --secures--> workflow` edge for each protected workflow. The
+ * coverage queries then read that structure back out of the graph — the matrix
+ * and gap list are generated from the graph, never a hand-maintained sidecar.
+ */
+
+import { nodeId, loadGraph, nodesByType, dependentsOf } from './store.mjs';
+import { extractSecurityTestEdges } from '../test-corpus-inventory.mjs';
+import { loadEmbedCapabilities } from '../embed/capability-loader.mjs';
+
+/** OWASP GenAI (LLM) Top 10, 2025 edition — the coverage rubric. */
+export const OWASP_GENAI_TOP10 = Object.freeze([
+  { id: 'LLM01', name: 'Prompt Injection' },
+  { id: 'LLM02', name: 'Sensitive Information Disclosure' },
+  { id: 'LLM03', name: 'Supply Chain' },
+  { id: 'LLM04', name: 'Data and Model Poisoning' },
+  { id: 'LLM05', name: 'Improper Output Handling' },
+  { id: 'LLM06', name: 'Excessive Agency' },
+  { id: 'LLM07', name: 'System Prompt Leakage' },
+  { id: 'LLM08', name: 'Vector and Embedding Weaknesses' },
+  { id: 'LLM09', name: 'Misinformation' },
+  { id: 'LLM10', name: 'Unbounded Consumption' },
+]);
+
+/**
+ * Seed security-test nodes + `secures` edges from `@owasp`/`@secures` tags.
+ *
+ * @param {{ rootDir: string }} opts
+ * @returns {{ nodes: object[], edges: object[] }}
+ */
+export function buildFromSecurity({ rootDir }) {
+  const nodes = [];
+  const edges = [];
+
+  // A `@secures <id>` may name an executable workflow or an embed preset; the
+  // edge must point at whichever node actually exists, so resolve embed ids
+  // (which live as `embed:<id>`, not `workflow:<id>`) up front.
+  const embedIds = new Set(loadEmbedCapabilities({ rootDir }).capabilities.map((m) => m.id).filter(Boolean));
+
+  for (const { testPath, owasp, secures } of extractSecurityTestEdges({ rootDir })) {
+    const testId = nodeId('test', testPath);
+    nodes.push({ id: testId, type: 'test', name: testPath, attrs: { path: testPath, exists: true, owasp } });
+    for (const securedId of secures) {
+      const to = embedIds.has(securedId) ? nodeId('embed', securedId) : nodeId('workflow', securedId);
+      edges.push({ from: testId, to, rel: 'secures', source: 'corpus-annotation' });
+    }
+  }
+
+  return { nodes, edges };
+}
+
+/** Every test node carrying at least one OWASP category, from the live graph. */
+function securityTestNodes(graph) {
+  return nodesByType(graph, 'test').filter((n) => Array.isArray(n.attrs?.owasp) && n.attrs.owasp.length > 0);
+}
+
+/**
+ * OWASP coverage matrix generated from the graph: all 10 categories, each with
+ * the count and paths of the tests tagged for it (0 for uncovered categories).
+ *
+ * @param {string} rootDir
+ * @returns {{ graphPresent: boolean, categories: Array<{ id, name, testCount, tests: string[] }>, uncovered: string[] }}
+ */
+export function buildOwaspMatrix(rootDir) {
+  const graph = loadGraph(rootDir);
+  if (!graph.exists) return { graphPresent: false, categories: [], uncovered: [] };
+
+  const byCategory = new Map(OWASP_GENAI_TOP10.map((c) => [c.id, []]));
+  for (const test of securityTestNodes(graph)) {
+    for (const cat of test.attrs.owasp) {
+      if (byCategory.has(cat)) byCategory.get(cat).push(test.attrs.path ?? test.name);
+    }
+  }
+
+  const categories = OWASP_GENAI_TOP10.map(({ id, name }) => {
+    const tests = [...byCategory.get(id)].sort();
+    return { id, name, testCount: tests.length, tests };
+  });
+
+  return {
+    graphPresent: true,
+    categories,
+    uncovered: categories.filter((c) => c.testCount === 0).map((c) => c.id),
+  };
+}
+
+/**
+ * Executable workflows and embed presets with zero inbound `secures` edges —
+ * the security-coverage gap list. Embed presets are included because they are
+ * the highest-agency units (external reads + write proposals).
+ *
+ * @param {string} rootDir
+ * @returns {{ graphPresent: boolean, workflows: string[], covered: string[] }}
+ */
+export function findWorkflowsMissingSecurity(rootDir) {
+  const graph = loadGraph(rootDir);
+  if (!graph.exists) return { graphPresent: false, workflows: [], covered: [] };
+
+  const missing = [];
+  const covered = [];
+  for (const node of [...nodesByType(graph, 'workflow'), ...nodesByType(graph, 'embed')]) {
+    if (dependentsOf(graph, node.id, 'secures').length === 0) missing.push(node.id);
+    else covered.push(node.id);
+  }
+  return { graphPresent: true, workflows: missing.sort(), covered: covered.sort() };
+}