@harness-engineering/graph 0.3.5 → 0.4.1

package/dist/index.js

@@ -33,7 +33,9 @@ __export(index_exports, {
   Assembler: () => Assembler,
   CIConnector: () => CIConnector,
   CURRENT_SCHEMA_VERSION: () => CURRENT_SCHEMA_VERSION,
+  CascadeSimulator: () => CascadeSimulator,
   CodeIngestor: () => CodeIngestor,
+  CompositeProbabilityStrategy: () => CompositeProbabilityStrategy,
   ConflictPredictor: () => ConflictPredictor,
   ConfluenceConnector: () => ConfluenceConnector,
   ContextQL: () => ContextQL,
@@ -59,6 +61,7 @@ __export(index_exports, {
   KnowledgeIngestor: () => KnowledgeIngestor,
   NODE_TYPES: () => NODE_TYPES,
   OBSERVABILITY_TYPES: () => OBSERVABILITY_TYPES,
+  RequirementIngestor: () => RequirementIngestor,
   ResponseFormatter: () => ResponseFormatter,
   SlackConnector: () => SlackConnector,
   SyncManager: () => SyncManager,
@@ -67,10 +70,12 @@ __export(index_exports, {
   VERSION: () => VERSION,
   VectorStore: () => VectorStore,
   askGraph: () => askGraph,
+  classifyNodeCategory: () => classifyNodeCategory,
   groupNodesByImpact: () => groupNodesByImpact,
   linkToCode: () => linkToCode,
   loadGraph: () => loadGraph,
   project: () => project,
+  queryTraceability: () => queryTraceability,
   saveGraph: () => saveGraph
 });
 module.exports = __toCommonJS(index_exports);
@@ -112,7 +117,9 @@ var NODE_TYPES = [
   // Design
   "design_token",
   "aesthetic_intent",
-  "design_constraint"
+  "design_constraint",
+  // Traceability
+  "requirement"
 ];
 var EDGE_TYPES = [
   // Code relationships
@@ -141,7 +148,11 @@ var EDGE_TYPES = [
   "uses_token",
   "declares_intent",
   "violates_design",
-  "platform_binding"
+  "platform_binding",
+  // Traceability relationships
+  "requires",
+  "verified_by",
+  "tested_by"
 ];
 var OBSERVABILITY_TYPES = /* @__PURE__ */ new Set(["span", "metric", "log"]);
 var CURRENT_SCHEMA_VERSION = 1;
@@ -233,6 +244,16 @@ function removeFromIndex(index, key, edge) {
   if (idx !== -1) list.splice(idx, 1);
   if (list.length === 0) index.delete(key);
 }
+function filterEdges(candidates, query) {
+  const results = [];
+  for (const edge of candidates) {
+    if (query.from !== void 0 && edge.from !== query.from) continue;
+    if (query.to !== void 0 && edge.to !== query.to) continue;
+    if (query.type !== void 0 && edge.type !== query.type) continue;
+    results.push({ ...edge });
+  }
+  return results;
+}
 var GraphStore = class {
   nodeMap = /* @__PURE__ */ new Map();
   edgeMap = /* @__PURE__ */ new Map();
@@ -300,27 +321,25 @@ var GraphStore = class {
     }
   }
   getEdges(query) {
-    let candidates;
     if (query.from !== void 0 && query.to !== void 0 && query.type !== void 0) {
       const edge = this.edgeMap.get(edgeKey(query.from, query.to, query.type));
       return edge ? [{ ...edge }] : [];
-    } else if (query.from !== void 0) {
-      candidates = this.edgesByFrom.get(query.from) ?? [];
-    } else if (query.to !== void 0) {
-      candidates = this.edgesByTo.get(query.to) ?? [];
-    } else if (query.type !== void 0) {
-      candidates = this.edgesByType.get(query.type) ?? [];
-    } else {
-      candidates = this.edgeMap.values();
     }
-    const results = [];
-    for (const edge of candidates) {
-      if (query.from !== void 0 && edge.from !== query.from) continue;
-      if (query.to !== void 0 && edge.to !== query.to) continue;
-      if (query.type !== void 0 && edge.type !== query.type) continue;
-      results.push({ ...edge });
+    const candidates = this.selectCandidates(query);
+    return filterEdges(candidates, query);
+  }
+  /** Pick the most selective index to start from. */
+  selectCandidates(query) {
+    if (query.from !== void 0) {
+      return this.edgesByFrom.get(query.from) ?? [];
     }
-    return results;
+    if (query.to !== void 0) {
+      return this.edgesByTo.get(query.to) ?? [];
+    }
+    if (query.type !== void 0) {
+      return this.edgesByType.get(query.type) ?? [];
+    }
+    return this.edgeMap.values();
   }
   getNeighbors(nodeId, direction = "both") {
     const neighborIds = /* @__PURE__ */ new Set();
@@ -616,6 +635,12 @@ var CODE_TYPES = /* @__PURE__ */ new Set([
   "method",
   "variable"
 ]);
+function classifyNodeCategory(node) {
+  if (TEST_TYPES.has(node.type)) return "tests";
+  if (DOC_TYPES.has(node.type)) return "docs";
+  if (CODE_TYPES.has(node.type)) return "code";
+  return "other";
+}
 function groupNodesByImpact(nodes, excludeId) {
   const tests = [];
   const docs = [];
@@ -623,15 +648,11 @@ function groupNodesByImpact(nodes, excludeId) {
   const other = [];
   for (const node of nodes) {
     if (excludeId && node.id === excludeId) continue;
-    if (TEST_TYPES.has(node.type)) {
-      tests.push(node);
-    } else if (DOC_TYPES.has(node.type)) {
-      docs.push(node);
-    } else if (CODE_TYPES.has(node.type)) {
-      code.push(node);
-    } else {
-      other.push(node);
-    }
+    const category = classifyNodeCategory(node);
+    if (category === "tests") tests.push(node);
+    else if (category === "docs") docs.push(node);
+    else if (category === "code") code.push(node);
+    else other.push(node);
   }
   return { tests, docs, code, other };
 }
@@ -675,6 +696,7 @@ var CodeIngestor = class {
       this.store.addEdge(edge);
       edgesAdded++;
     }
+    edgesAdded += this.extractReqAnnotations(fileContents, rootDir);
     return {
       nodesAdded,
       nodesUpdated: 0,
@@ -1033,6 +1055,48 @@ var CodeIngestor = class {
     if (/\.jsx?$/.test(filePath)) return "javascript";
     return "unknown";
   }
+  /**
+   * Scan file contents for @req annotations and create verified_by edges
+   * linking requirement nodes to the annotated files.
+   * Format: // @req <feature-name>#<index>
+   */
+  extractReqAnnotations(fileContents, rootDir) {
+    const REQ_TAG = /\/\/\s*@req\s+([\w-]+)#(\d+)/g;
+    const reqNodes = this.store.findNodes({ type: "requirement" });
+    let edgesAdded = 0;
+    for (const [filePath, content] of fileContents) {
+      let match;
+      REQ_TAG.lastIndex = 0;
+      while ((match = REQ_TAG.exec(content)) !== null) {
+        const featureName = match[1];
+        const reqIndex = parseInt(match[2], 10);
+        const reqNode = reqNodes.find(
+          (n) => n.metadata.featureName === featureName && n.metadata.index === reqIndex
+        );
+        if (!reqNode) {
+          console.warn(
+            `@req annotation references non-existent requirement: ${featureName}#${reqIndex} in ${filePath}`
+          );
+          continue;
+        }
+        const relPath = path.relative(rootDir, filePath).replace(/\\/g, "/");
+        const fileNodeId = `file:${relPath}`;
+        this.store.addEdge({
+          from: reqNode.id,
+          to: fileNodeId,
+          type: "verified_by",
+          confidence: 1,
+          metadata: {
+            method: "annotation",
+            tag: `@req ${featureName}#${reqIndex}`,
+            confidence: 1
+          }
+        });
+        edgesAdded++;
+      }
+    }
+    return edgesAdded;
+  }
 };
 
 // src/ingest/GitIngestor.ts
@@ -1509,8 +1573,218 @@ var KnowledgeIngestor = class {
   }
 };
 
-// src/ingest/connectors/ConnectorUtils.ts
+// src/ingest/RequirementIngestor.ts
+var fs3 = __toESM(require("fs/promises"));
+var path4 = __toESM(require("path"));
+var REQUIREMENT_SECTIONS = [
+  "Observable Truths",
+  "Success Criteria",
+  "Acceptance Criteria"
+];
+var SECTION_HEADING_RE = /^#{2,3}\s+(.+)$/;
+var NUMBERED_ITEM_RE = /^\s*(\d+)\.\s+(.+)$/;
+function detectEarsPattern(text) {
+  const lower = text.toLowerCase();
+  if (/^if\b.+\bthen\b.+\bshall not\b/.test(lower)) return "unwanted";
+  if (/^when\b/.test(lower)) return "event-driven";
+  if (/^while\b/.test(lower)) return "state-driven";
+  if (/^where\b/.test(lower)) return "optional";
+  if (/^the\s+\w+\s+shall\b/.test(lower)) return "ubiquitous";
+  return void 0;
+}
 var CODE_NODE_TYPES2 = ["file", "function", "class", "method", "interface", "variable"];
+var RequirementIngestor = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  /**
+   * Scan a specs directory for `<feature>/proposal.md` files,
+   * extract numbered requirements from recognized sections,
+   * and create requirement nodes with convention-based edges.
+   */
+  async ingestSpecs(specsDir) {
+    const start = Date.now();
+    const errors = [];
+    let nodesAdded = 0;
+    let edgesAdded = 0;
+    let featureDirs;
+    try {
+      const entries = await fs3.readdir(specsDir, { withFileTypes: true });
+      featureDirs = entries.filter((e) => e.isDirectory()).map((e) => path4.join(specsDir, e.name));
+    } catch {
+      return emptyResult(Date.now() - start);
+    }
+    for (const featureDir of featureDirs) {
+      const featureName = path4.basename(featureDir);
+      const specPath = path4.join(featureDir, "proposal.md").replaceAll("\\", "/");
+      let content;
+      try {
+        content = await fs3.readFile(specPath, "utf-8");
+      } catch {
+        continue;
+      }
+      try {
+        const specHash = hash(specPath);
+        const specNodeId = `file:${specPath}`;
+        this.store.addNode({
+          id: specNodeId,
+          type: "document",
+          name: path4.basename(specPath),
+          path: specPath,
+          metadata: { featureName }
+        });
+        const requirements = this.extractRequirements(content, specPath, specHash, featureName);
+        for (const req of requirements) {
+          this.store.addNode(req.node);
+          nodesAdded++;
+          this.store.addEdge({
+            from: req.node.id,
+            to: specNodeId,
+            type: "specifies"
+          });
+          edgesAdded++;
+          edgesAdded += this.linkByPathPattern(req.node.id, featureName);
+          edgesAdded += this.linkByKeywordOverlap(req.node.id, req.node.name);
+        }
+      } catch (err) {
+        errors.push(`${specPath}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    return {
+      nodesAdded,
+      nodesUpdated: 0,
+      edgesAdded,
+      edgesUpdated: 0,
+      errors,
+      durationMs: Date.now() - start
+    };
+  }
+  /**
+   * Parse markdown content and extract numbered items from recognized sections.
+   */
+  extractRequirements(content, specPath, specHash, featureName) {
+    const lines = content.split("\n");
+    const results = [];
+    let currentSection;
+    let inRequirementSection = false;
+    let globalIndex = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const headingMatch = line.match(SECTION_HEADING_RE);
+      if (headingMatch) {
+        const heading = headingMatch[1].trim();
+        const isReqSection = REQUIREMENT_SECTIONS.some(
+          (s) => heading.toLowerCase() === s.toLowerCase()
+        );
+        if (isReqSection) {
+          currentSection = heading;
+          inRequirementSection = true;
+        } else {
+          inRequirementSection = false;
+        }
+        continue;
+      }
+      if (!inRequirementSection) continue;
+      const itemMatch = line.match(NUMBERED_ITEM_RE);
+      if (!itemMatch) continue;
+      const index = parseInt(itemMatch[1], 10);
+      const text = itemMatch[2].trim();
+      const rawText = line.trim();
+      const lineNumber = i + 1;
+      globalIndex++;
+      const nodeId = `req:${specHash}:${globalIndex}`;
+      const earsPattern = detectEarsPattern(text);
+      results.push({
+        node: {
+          id: nodeId,
+          type: "requirement",
+          name: text,
+          path: specPath,
+          location: {
+            fileId: `file:${specPath}`,
+            startLine: lineNumber,
+            endLine: lineNumber
+          },
+          metadata: {
+            specPath,
+            index,
+            section: currentSection,
+            rawText,
+            earsPattern,
+            featureName
+          }
+        }
+      });
+    }
+    return results;
+  }
+  /**
+   * Convention-based linking: match requirement to code/test files
+   * by feature name in their path.
+   */
+  linkByPathPattern(reqId, featureName) {
+    let count = 0;
+    const fileNodes = this.store.findNodes({ type: "file" });
+    for (const node of fileNodes) {
+      if (!node.path) continue;
+      const normalizedPath = node.path.replace(/\\/g, "/");
+      const isCodeMatch = normalizedPath.includes("packages/") && path4.basename(normalizedPath).includes(featureName);
+      const isTestMatch = normalizedPath.includes("/tests/") && // platform-safe
+      path4.basename(normalizedPath).includes(featureName);
+      if (isCodeMatch && !isTestMatch) {
+        this.store.addEdge({
+          from: reqId,
+          to: node.id,
+          type: "requires",
+          confidence: 0.5,
+          metadata: { method: "convention", matchReason: "path-pattern" }
+        });
+        count++;
+      } else if (isTestMatch) {
+        this.store.addEdge({
+          from: reqId,
+          to: node.id,
+          type: "verified_by",
+          confidence: 0.5,
+          metadata: { method: "convention", matchReason: "path-pattern" }
+        });
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Convention-based linking: match requirement text to code nodes
+   * by keyword overlap (function/class names appearing in requirement text).
+   */
+  linkByKeywordOverlap(reqId, reqText) {
+    let count = 0;
+    for (const nodeType of CODE_NODE_TYPES2) {
+      const codeNodes = this.store.findNodes({ type: nodeType });
+      for (const node of codeNodes) {
+        if (node.name.length < 3) continue;
+        const escaped = node.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const namePattern = new RegExp(`\\b${escaped}\\b`, "i");
+        if (namePattern.test(reqText)) {
+          const edgeType = node.path?.replace(/\\/g, "/").includes("/tests/") ? "verified_by" : "requires";
+          this.store.addEdge({
+            from: reqId,
+            to: node.id,
+            type: edgeType,
+            confidence: 0.6,
+            metadata: { method: "convention", matchReason: "keyword-overlap" }
+          });
+          count++;
+        }
+      }
+    }
+    return count;
+  }
+};
+
+// src/ingest/connectors/ConnectorUtils.ts
+var CODE_NODE_TYPES3 = ["file", "function", "class", "method", "interface", "variable"];
 var SANITIZE_RULES = [
   // Strip XML/HTML-like instruction tags that could be interpreted as system prompts
   {
@@ -1545,7 +1819,7 @@ function sanitizeExternalText(text, maxLength = 2e3) {
 }
 function linkToCode(store, content, sourceNodeId, edgeType, options) {
   let edgesCreated = 0;
-  for (const type of CODE_NODE_TYPES2) {
+  for (const type of CODE_NODE_TYPES3) {
     const nodes = store.findNodes({ type });
     for (const node of nodes) {
       if (node.name.length < 3) continue;
@@ -1565,12 +1839,12 @@ function linkToCode(store, content, sourceNodeId, edgeType, options) {
 }
 
 // src/ingest/connectors/SyncManager.ts
-var fs3 = __toESM(require("fs/promises"));
-var path4 = __toESM(require("path"));
+var fs4 = __toESM(require("fs/promises"));
+var path5 = __toESM(require("path"));
 var SyncManager = class {
   constructor(store, graphDir) {
     this.store = store;
-    this.metadataPath = path4.join(graphDir, "sync-metadata.json");
+    this.metadataPath = path5.join(graphDir, "sync-metadata.json");
   }
   store;
   registrations = /* @__PURE__ */ new Map();
@@ -1625,15 +1899,15 @@ var SyncManager = class {
   }
   async loadMetadata() {
     try {
-      const raw = await fs3.readFile(this.metadataPath, "utf-8");
+      const raw = await fs4.readFile(this.metadataPath, "utf-8");
       return JSON.parse(raw);
     } catch {
       return { connectors: {} };
     }
   }
   async saveMetadata(metadata) {
-    await fs3.mkdir(path4.dirname(this.metadataPath), { recursive: true });
-    await fs3.writeFile(this.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+    await fs4.mkdir(path5.dirname(this.metadataPath), { recursive: true });
+    await fs4.writeFile(this.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
   }
 };
 
@@ -2162,7 +2436,7 @@ var FusionLayer = class {
 };
 
 // src/entropy/GraphEntropyAdapter.ts
-var CODE_NODE_TYPES3 = ["file", "function", "class", "method", "interface", "variable"];
+var CODE_NODE_TYPES4 = ["file", "function", "class", "method", "interface", "variable"];
 var GraphEntropyAdapter = class {
   constructor(store) {
     this.store = store;
@@ -2229,7 +2503,7 @@ var GraphEntropyAdapter = class {
   }
   findEntryPoints() {
     const entryPoints = [];
-    for (const nodeType of CODE_NODE_TYPES3) {
+    for (const nodeType of CODE_NODE_TYPES4) {
       const nodes = this.store.findNodes({ type: nodeType });
       for (const node of nodes) {
         const isIndexFile = nodeType === "file" && node.name === "index.ts";
@@ -2265,7 +2539,7 @@ var GraphEntropyAdapter = class {
   }
   collectUnreachableNodes(visited) {
     const unreachableNodes = [];
-    for (const nodeType of CODE_NODE_TYPES3) {
+    for (const nodeType of CODE_NODE_TYPES4) {
       const nodes = this.store.findNodes({ type: nodeType });
       for (const node of nodes) {
         if (!visited.has(node.id)) {
@@ -2710,6 +2984,7 @@ var INTENT_SIGNALS = {
       "depend",
       "blast",
       "radius",
+      "cascade",
       "risk",
       "delete",
       "remove"
@@ -2719,6 +2994,7 @@ var INTENT_SIGNALS = {
       /what\s+(breaks|happens|is affected)/,
       /if\s+i\s+(change|modify|remove|delete)/,
       /blast\s+radius/,
+      /cascad/,
       /what\s+(depend|relies)/
     ]
   },
@@ -3085,9 +3361,9 @@ var EntityExtractor = class {
     }
     const pathConsumed = /* @__PURE__ */ new Set();
     for (const match of trimmed.matchAll(FILE_PATH_RE)) {
-      const path6 = match[0];
-      add(path6);
-      pathConsumed.add(path6);
+      const path7 = match[0];
+      add(path7);
+      pathConsumed.add(path7);
     }
     const allConsumed = buildConsumedSet(quotedConsumed, casingConsumed, pathConsumed);
     const words = trimmed.split(/\s+/);
@@ -3158,8 +3434,8 @@ var EntityResolver = class {
       if (isPathLike && node.path.includes(raw)) {
         return { raw, nodeId: node.id, node, confidence: 0.6, method: "path" };
       }
-      const basename4 = node.path.split("/").pop() ?? "";
-      if (basename4.includes(raw)) {
+      const basename5 = node.path.split("/").pop() ?? "";
+      if (basename5.includes(raw)) {
         return { raw, nodeId: node.id, node, confidence: 0.6, method: "path" };
       }
       if (raw.length >= 4 && node.path.includes(raw)) {
@@ -3204,6 +3480,10 @@ var ResponseFormatter = class {
   }
   formatImpact(entityName, data) {
     const d = data;
+    if ("sourceNodeId" in d && "summary" in d) {
+      const summary = d.summary;
+      return `Blast radius of **${entityName}**: ${summary.totalAffected} affected nodes (${summary.highRisk} high risk, ${summary.mediumRisk} medium, ${summary.lowRisk} low).`;
+    }
     const code = this.safeArrayLength(d?.code);
     const tests = this.safeArrayLength(d?.tests);
     const docs = this.safeArrayLength(d?.docs);
@@ -3234,13 +3514,13 @@ var ResponseFormatter = class {
     const context = Array.isArray(d?.context) ? d.context : [];
     const firstEntity = entities[0];
     const nodeType = firstEntity?.node.type ?? "node";
-    const path6 = firstEntity?.node.path ?? "unknown";
+    const path7 = firstEntity?.node.path ?? "unknown";
     let neighborCount = 0;
     const firstContext = context[0];
     if (firstContext && Array.isArray(firstContext.nodes)) {
       neighborCount = firstContext.nodes.length;
     }
-    return `**${entityName}** is a ${nodeType} at \`${path6}\`. Connected to ${neighborCount} nodes.`;
+    return `**${entityName}** is a ${nodeType} at \`${path7}\`. Connected to ${neighborCount} nodes.`;
   }
   formatAnomaly(data) {
     const d = data;
@@ -3265,6 +3545,246 @@ var ResponseFormatter = class {
   }
 };
 
+// src/blast-radius/CompositeProbabilityStrategy.ts
+var CompositeProbabilityStrategy = class _CompositeProbabilityStrategy {
+  constructor(changeFreqMap, couplingMap) {
+    this.changeFreqMap = changeFreqMap;
+    this.couplingMap = couplingMap;
+  }
+  changeFreqMap;
+  couplingMap;
+  static BASE_WEIGHTS = {
+    imports: 0.7,
+    calls: 0.5,
+    implements: 0.6,
+    inherits: 0.6,
+    co_changes_with: 0.4,
+    references: 0.2,
+    contains: 0.3
+  };
+  static FALLBACK_WEIGHT = 0.1;
+  static EDGE_TYPE_BLEND = 0.5;
+  static CHANGE_FREQ_BLEND = 0.3;
+  static COUPLING_BLEND = 0.2;
+  getEdgeProbability(edge, _fromNode, toNode) {
+    const base = _CompositeProbabilityStrategy.BASE_WEIGHTS[edge.type] ?? _CompositeProbabilityStrategy.FALLBACK_WEIGHT;
+    const changeFreq = this.changeFreqMap.get(toNode.id) ?? 0;
+    const coupling = this.couplingMap.get(toNode.id) ?? 0;
+    return Math.min(
+      1,
+      base * _CompositeProbabilityStrategy.EDGE_TYPE_BLEND + changeFreq * _CompositeProbabilityStrategy.CHANGE_FREQ_BLEND + coupling * _CompositeProbabilityStrategy.COUPLING_BLEND
+    );
+  }
+};
+
+// src/blast-radius/CascadeSimulator.ts
+var DEFAULT_PROBABILITY_FLOOR = 0.05;
+var DEFAULT_MAX_DEPTH = 10;
+var CascadeSimulator = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  simulate(sourceNodeId, options = {}) {
+    const sourceNode = this.store.getNode(sourceNodeId);
+    if (!sourceNode) {
+      throw new Error(`Node not found: ${sourceNodeId}. Ensure the file has been ingested.`);
+    }
+    const probabilityFloor = options.probabilityFloor ?? DEFAULT_PROBABILITY_FLOOR;
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const edgeTypeFilter = options.edgeTypes ? new Set(options.edgeTypes) : null;
+    const strategy = options.strategy ?? this.buildDefaultStrategy();
+    const visited = /* @__PURE__ */ new Map();
+    const queue = [];
+    const fanOutCount = /* @__PURE__ */ new Map();
+    this.seedQueue(
+      sourceNodeId,
+      sourceNode,
+      strategy,
+      edgeTypeFilter,
+      probabilityFloor,
+      queue,
+      fanOutCount
+    );
+    const truncated = this.runBfs(
+      queue,
+      visited,
+      fanOutCount,
+      sourceNodeId,
+      strategy,
+      edgeTypeFilter,
+      probabilityFloor,
+      maxDepth
+    );
+    return this.buildResult(sourceNodeId, sourceNode.name, visited, fanOutCount, truncated);
+  }
+  seedQueue(sourceNodeId, sourceNode, strategy, edgeTypeFilter, probabilityFloor, queue, fanOutCount) {
+    const sourceEdges = this.store.getEdges({ from: sourceNodeId });
+    for (const edge of sourceEdges) {
+      if (edge.to === sourceNodeId) continue;
+      if (edgeTypeFilter && !edgeTypeFilter.has(edge.type)) continue;
+      const targetNode = this.store.getNode(edge.to);
+      if (!targetNode) continue;
+      const cumProb = strategy.getEdgeProbability(edge, sourceNode, targetNode);
+      if (cumProb < probabilityFloor) continue;
+      queue.push({
+        nodeId: edge.to,
+        cumProb,
+        depth: 1,
+        parentId: sourceNodeId,
+        incomingEdge: edge.type
+      });
+    }
+    fanOutCount.set(
+      sourceNodeId,
+      sourceEdges.filter(
+        (e) => e.to !== sourceNodeId && (!edgeTypeFilter || edgeTypeFilter.has(e.type))
+      ).length
+    );
+  }
+  runBfs(queue, visited, fanOutCount, sourceNodeId, strategy, edgeTypeFilter, probabilityFloor, maxDepth) {
+    const MAX_QUEUE_SIZE = 1e4;
+    let head = 0;
+    while (head < queue.length) {
+      if (queue.length > MAX_QUEUE_SIZE) return true;
+      const entry = queue[head++];
+      const existing = visited.get(entry.nodeId);
+      if (existing && existing.cumulativeProbability >= entry.cumProb) continue;
+      const targetNode = this.store.getNode(entry.nodeId);
+      if (!targetNode) continue;
+      visited.set(entry.nodeId, {
+        nodeId: entry.nodeId,
+        name: targetNode.name,
+        ...targetNode.path !== void 0 && { path: targetNode.path },
+        type: targetNode.type,
+        cumulativeProbability: entry.cumProb,
+        depth: entry.depth,
+        incomingEdge: entry.incomingEdge,
+        parentId: entry.parentId
+      });
+      if (entry.depth < maxDepth) {
+        const childCount = this.expandNode(
+          entry,
+          targetNode,
+          sourceNodeId,
+          strategy,
+          edgeTypeFilter,
+          probabilityFloor,
+          queue
+        );
+        fanOutCount.set(entry.nodeId, (fanOutCount.get(entry.nodeId) ?? 0) + childCount);
+      }
+    }
+    return false;
+  }
+  expandNode(entry, fromNode, sourceNodeId, strategy, edgeTypeFilter, probabilityFloor, queue) {
+    const outEdges = this.store.getEdges({ from: entry.nodeId });
+    let childCount = 0;
+    for (const edge of outEdges) {
+      if (edgeTypeFilter && !edgeTypeFilter.has(edge.type)) continue;
+      if (edge.to === sourceNodeId) continue;
+      const childNode = this.store.getNode(edge.to);
+      if (!childNode) continue;
+      const newCumProb = entry.cumProb * strategy.getEdgeProbability(edge, fromNode, childNode);
+      if (newCumProb < probabilityFloor) continue;
+      childCount++;
+      queue.push({
+        nodeId: edge.to,
+        cumProb: newCumProb,
+        depth: entry.depth + 1,
+        parentId: entry.nodeId,
+        incomingEdge: edge.type
+      });
+    }
+    return childCount;
+  }
+  buildDefaultStrategy() {
+    return new CompositeProbabilityStrategy(/* @__PURE__ */ new Map(), /* @__PURE__ */ new Map());
+  }
+  buildResult(sourceNodeId, sourceName, visited, fanOutCount, truncated = false) {
+    if (visited.size === 0) {
+      return {
+        sourceNodeId,
+        sourceName,
+        layers: [],
+        flatSummary: [],
+        summary: {
+          totalAffected: 0,
+          maxDepthReached: 0,
+          highRisk: 0,
+          mediumRisk: 0,
+          lowRisk: 0,
+          categoryBreakdown: { code: 0, tests: 0, docs: 0, other: 0 },
+          amplificationPoints: [],
+          truncated
+        }
+      };
+    }
+    const allNodes = Array.from(visited.values());
+    const flatSummary = [...allNodes].sort(
+      (a, b) => b.cumulativeProbability - a.cumulativeProbability
+    );
+    const depthMap = /* @__PURE__ */ new Map();
+    for (const node of allNodes) {
+      let list = depthMap.get(node.depth);
+      if (!list) {
+        list = [];
+        depthMap.set(node.depth, list);
+      }
+      list.push(node);
+    }
+    const layers = [];
+    const depths = Array.from(depthMap.keys()).sort((a, b) => a - b);
+    for (const depth of depths) {
+      const nodes = depthMap.get(depth);
+      const breakdown = { code: 0, tests: 0, docs: 0, other: 0 };
+      for (const n of nodes) {
+        const graphNode = this.store.getNode(n.nodeId);
+        if (graphNode) {
+          breakdown[classifyNodeCategory(graphNode)]++;
+        }
+      }
+      layers.push({ depth, nodes, categoryBreakdown: breakdown });
+    }
+    let highRisk = 0;
+    let mediumRisk = 0;
+    let lowRisk = 0;
+    const catBreakdown = { code: 0, tests: 0, docs: 0, other: 0 };
+    for (const node of allNodes) {
+      if (node.cumulativeProbability >= 0.5) highRisk++;
+      else if (node.cumulativeProbability >= 0.2) mediumRisk++;
+      else lowRisk++;
+      const graphNode = this.store.getNode(node.nodeId);
+      if (graphNode) {
+        catBreakdown[classifyNodeCategory(graphNode)]++;
+      }
+    }
+    const amplificationPoints = [];
+    for (const [nodeId, count] of fanOutCount) {
+      if (count > 3) {
+        amplificationPoints.push(nodeId);
+      }
+    }
+    const maxDepthReached = allNodes.reduce((max, n) => Math.max(max, n.depth), 0);
+    return {
+      sourceNodeId,
+      sourceName,
+      layers,
+      flatSummary,
+      summary: {
+        totalAffected: allNodes.length,
+        maxDepthReached,
+        highRisk,
+        mediumRisk,
+        lowRisk,
+        categoryBreakdown: catBreakdown,
+        amplificationPoints,
+        truncated
+      }
+    };
+  }
+};
+
 // src/nlq/index.ts
 var ENTITY_REQUIRED_INTENTS = /* @__PURE__ */ new Set(["impact", "relationships", "explain"]);
 var classifier = new IntentClassifier();
@@ -3327,6 +3847,11 @@ function executeOperation(store, intent, entities, question, fusion) {
   switch (intent) {
     case "impact": {
       const rootId = entities[0].nodeId;
+      const lowerQuestion = question.toLowerCase();
+      if (lowerQuestion.includes("blast radius") || lowerQuestion.includes("cascade")) {
+        const simulator = new CascadeSimulator(store);
+        return simulator.simulate(rootId);
+      }
       const result = cql.execute({
         rootNodeIds: [rootId],
         bidirectional: true,
@@ -3381,7 +3906,7 @@ var PHASE_NODE_TYPES = {
   debug: ["failure", "learning", "function", "method"],
   plan: ["adr", "document", "module", "layer"]
 };
-var CODE_NODE_TYPES4 = /* @__PURE__ */ new Set([
+var CODE_NODE_TYPES5 = /* @__PURE__ */ new Set([
   "file",
   "function",
   "class",
@@ -3596,7 +4121,7 @@ var Assembler = class {
    */
   checkCoverage() {
     const codeNodes = [];
-    for (const type of CODE_NODE_TYPES4) {
+    for (const type of CODE_NODE_TYPES5) {
       codeNodes.push(...this.store.findNodes({ type }));
     }
     const documented = [];
@@ -3620,6 +4145,99 @@ var Assembler = class {
   }
 };
 
+// src/query/Traceability.ts
+function extractConfidence(edge) {
+  return edge.confidence ?? edge.metadata?.confidence ?? 0;
+}
+function extractMethod(edge) {
+  return edge.metadata?.method ?? "convention";
+}
+function edgesToTracedFiles(store, edges) {
+  return edges.map((edge) => ({
+    path: store.getNode(edge.to)?.path ?? edge.to,
+    confidence: extractConfidence(edge),
+    method: extractMethod(edge)
+  }));
+}
+function determineCoverageStatus(hasCode, hasTests) {
+  if (hasCode && hasTests) return "full";
+  if (hasCode) return "code-only";
+  if (hasTests) return "test-only";
+  return "none";
+}
+function computeMaxConfidence(codeFiles, testFiles) {
+  const allConfidences = [
+    ...codeFiles.map((f) => f.confidence),
+    ...testFiles.map((f) => f.confidence)
+  ];
+  return allConfidences.length > 0 ? Math.max(...allConfidences) : 0;
+}
+function buildRequirementCoverage(store, req) {
+  const codeFiles = edgesToTracedFiles(store, store.getEdges({ from: req.id, type: "requires" }));
+  const testFiles = edgesToTracedFiles(
+    store,
+    store.getEdges({ from: req.id, type: "verified_by" })
+  );
+  const hasCode = codeFiles.length > 0;
+  const hasTests = testFiles.length > 0;
+  return {
+    requirementId: req.id,
+    requirementName: req.name,
+    index: req.metadata?.index ?? 0,
+    codeFiles,
+    testFiles,
+    status: determineCoverageStatus(hasCode, hasTests),
+    maxConfidence: computeMaxConfidence(codeFiles, testFiles)
+  };
+}
+function computeSummary(requirements) {
+  const total = requirements.length;
+  const withCode = requirements.filter((r) => r.codeFiles.length > 0).length;
+  const withTests = requirements.filter((r) => r.testFiles.length > 0).length;
+  const fullyTraced = requirements.filter((r) => r.status === "full").length;
+  const untraceable = requirements.filter((r) => r.status === "none").length;
+  const coveragePercent = total > 0 ? Math.round(fullyTraced / total * 100) : 0;
+  return { total, withCode, withTests, fullyTraced, untraceable, coveragePercent };
+}
+function queryTraceability(store, options) {
+  const allRequirements = store.findNodes({ type: "requirement" });
+  const filtered = allRequirements.filter((node) => {
+    if (options?.specPath && node.metadata?.specPath !== options.specPath) return false;
+    if (options?.featureName && node.metadata?.featureName !== options.featureName) return false;
+    return true;
+  });
+  if (filtered.length === 0) return [];
+  const groups = /* @__PURE__ */ new Map();
+  for (const req of filtered) {
+    const meta = req.metadata;
+    const specPath = meta?.specPath ?? "";
+    const featureName = meta?.featureName ?? "";
+    const key = `${specPath}\0${featureName}`;
+    const list = groups.get(key);
+    if (list) {
+      list.push(req);
+    } else {
+      groups.set(key, [req]);
+    }
+  }
+  const results = [];
+  for (const [, reqs] of groups) {
+    const firstReq = reqs[0];
+    const firstMeta = firstReq.metadata;
+    const specPath = firstMeta?.specPath ?? "";
+    const featureName = firstMeta?.featureName ?? "";
+    const requirements = reqs.map((req) => buildRequirementCoverage(store, req));
+    requirements.sort((a, b) => a.index - b.index);
+    results.push({
+      specPath,
+      featureName,
+      requirements,
+      summary: computeSummary(requirements)
+    });
+  }
+  return results;
+}
+
 // src/constraints/GraphConstraintAdapter.ts
 var import_minimatch = require("minimatch");
 var import_node_path2 = require("path");
@@ -3679,14 +4297,14 @@ var GraphConstraintAdapter = class {
 };
 
 // src/ingest/DesignIngestor.ts
-var fs4 = __toESM(require("fs/promises"));
-var path5 = __toESM(require("path"));
+var fs5 = __toESM(require("fs/promises"));
+var path6 = __toESM(require("path"));
 function isDTCGToken(obj) {
   return typeof obj === "object" && obj !== null && "$value" in obj && "$type" in obj;
 }
 async function readFileOrNull(filePath) {
   try {
-    return await fs4.readFile(filePath, "utf-8");
+    return await fs5.readFile(filePath, "utf-8");
   } catch {
     return null;
   }
@@ -3832,8 +4450,8 @@ var DesignIngestor = class {
   async ingestAll(designDir) {
     const start = Date.now();
     const [tokensResult, intentResult] = await Promise.all([
-      this.ingestTokens(path5.join(designDir, "tokens.json")),
-      this.ingestDesignIntent(path5.join(designDir, "DESIGN.md"))
+      this.ingestTokens(path6.join(designDir, "tokens.json")),
+      this.ingestDesignIntent(path6.join(designDir, "DESIGN.md"))
     ]);
     const merged = mergeResults(tokensResult, intentResult);
     return { ...merged, durationMs: Date.now() - start };
@@ -4082,10 +4700,10 @@ var TaskIndependenceAnalyzer = class {
         includeTypes: ["file"]
       });
       for (const n of queryResult.nodes) {
-        const path6 = n.path ?? n.id.replace(/^file:/, "");
-        if (!fileSet.has(path6)) {
-          if (!result.has(path6)) {
-            result.set(path6, file);
+        const path7 = n.path ?? n.id.replace(/^file:/, "");
+        if (!fileSet.has(path7)) {
+          if (!result.has(path7)) {
+            result.set(path7, file);
           }
         }
       }
@@ -4438,13 +5056,15 @@ var ConflictPredictor = class {
 };
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "0.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Assembler,
   CIConnector,
   CURRENT_SCHEMA_VERSION,
+  CascadeSimulator,
   CodeIngestor,
+  CompositeProbabilityStrategy,
   ConflictPredictor,
   ConfluenceConnector,
   ContextQL,
@@ -4470,6 +5090,7 @@ var VERSION = "0.2.0";
   KnowledgeIngestor,
   NODE_TYPES,
   OBSERVABILITY_TYPES,
+  RequirementIngestor,
   ResponseFormatter,
   SlackConnector,
   SyncManager,
@@ -4478,9 +5099,11 @@ var VERSION = "0.2.0";
   VERSION,
   VectorStore,
   askGraph,
+  classifyNodeCategory,
   groupNodesByImpact,
   linkToCode,
   loadGraph,
   project,
+  queryTraceability,
   saveGraph
 });