snipara-companion 3.6.0 → 3.6.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.6.2
+
+- Adds `snipara.semantic.v1` to local code overlays and impact results with
+  evidence-backed public APIs, implicit contracts, architecture roles, and
+  critical-versus-incidental dependency classification.
+- Marks explicit TypeScript and Go exports during extraction and bumps the
+  local extractor version to `3` while preserving the overlay v2 envelope.
+- Adds semantic risk points to local impact, preserving every contributing
+  assertion and rule as inspectable evidence.
+- Merges local and hosted semantic assertions with explicit provenance in
+  hybrid mode. Historical regression-path associations stay shadow-only and
+  cannot silently change the risk score.
+
+## New In 3.6.1
+
+- Enforces `--max-nodes` as a strict total traversal budget, including seed
+  symbols, so impact analysis cannot exceed the configured graph bound for
+  symbol-heavy files.
+
 ## New In 3.6.0
 
 - Upgrades the local code overlay to v2 with TypeScript Compiler API symbols,

package/dist/index.d.ts

@@ -1808,6 +1808,61 @@ interface LocalCodeOverlaySymbol {
     endLine?: number;
     qualifiedName: string;
     localKey: string;
+    exported?: boolean;
+    defaultExport?: boolean;
+}
+type LocalSemanticPredicate = "public_api" | "implicit_contract" | "architecture_role" | "dependency_criticality";
+interface LocalSemanticEvidence {
+    kind: string;
+    detail: string;
+    filePath?: string;
+    line?: number;
+    edgeKind?: LocalCodeOverlayEdge["kind"];
+}
+interface LocalSemanticAssertion {
+    id: string;
+    subject: string;
+    predicate: LocalSemanticPredicate;
+    value: string | boolean;
+    confidence: number;
+    source: "typescript-compiler-api" | "language-parser" | "architecture-pattern-rules" | "criticality-rules" | "graph-criticality-rules";
+    extractorVersion: 1;
+    evidence: LocalSemanticEvidence[];
+}
+interface LocalSemanticModel {
+    version: "snipara.semantic.v1";
+    extractorVersion: 1;
+    source: "deterministic-graph-inference";
+    scope: "repository" | "impact";
+    assertions: LocalSemanticAssertion[];
+    publicContracts: LocalSemanticAssertion[];
+    architectureRoles: LocalSemanticAssertion[];
+    dependencyCriticality: LocalSemanticAssertion[];
+    truncation: {
+        truncated: boolean;
+        totalAssertionCount: number;
+        returnedAssertionCount: number;
+        assertionLimit: number;
+    };
+    historicalRegression: {
+        mode: "shadow";
+        sampleThreshold: 3;
+        failureEventCount: 0;
+        associations: [];
+        riskContributionEnabled: false;
+        suggestedRiskDelta: 0;
+        caveat: string;
+    };
+    summary: {
+        assertionCount: number;
+        publicContractCount: number;
+        architectureRoleCount: number;
+        criticalDependencyCount: number;
+        criticalEdgeCount: number;
+        incidentalDependencyCount: number;
+        historicalAssociationCount: 0;
+    };
+    caveats: string[];
 }
 interface LocalCodeOverlayImportBinding {
     localName: string;
@@ -1854,7 +1909,7 @@ interface LocalCodeOverlayExcludedFile {
 }
 interface LocalCodeOverlayManifest {
     version: "snipara.local_code_overlay.v2";
-    extractorVersion: 2;
+    extractorVersion: 2 | 3;
     generatedAt: string;
     indexedAt: string;
     repoRoot: string;
@@ -1874,6 +1929,7 @@ interface LocalCodeOverlayManifest {
     imports: LocalCodeOverlayImport[];
     references: LocalCodeOverlayReference[];
     edges: LocalCodeOverlayEdge[];
+    semantic?: LocalSemanticModel;
     incremental: {
         reusedFiles: number;
         parsedFiles: number;
@@ -2010,6 +2066,7 @@ interface LocalCodeOverlaySummary {
         imports: number;
         references: number;
         edges: number;
+        semanticAssertions: number;
         excluded: number;
     };
     incremental: LocalCodeOverlayManifest["incremental"];

package/dist/index.js

@@ -3440,6 +3440,17 @@ function typeScriptLine(sourceFile, node) {
 function typeScriptEndLine(sourceFile, node) {
   return sourceFile.getLineAndCharacterOfPosition(node.getEnd()).line + 1;
 }
+function typeScriptExportStatus(node, name, namedExports) {
+  let declaration = node;
+  if (import_typescript.default.isVariableDeclaration(node) && import_typescript.default.isVariableDeclarationList(node.parent)) {
+    const statement = node.parent.parent;
+    if (import_typescript.default.isVariableStatement(statement)) declaration = statement;
+  }
+  const modifiers = import_typescript.default.canHaveModifiers(declaration) ? import_typescript.default.getModifiers(declaration) : void 0;
+  const exported = namedExports.has(name) || modifiers?.some((modifier) => modifier.kind === import_typescript.default.SyntaxKind.ExportKeyword);
+  const defaultExport = modifiers?.some((modifier) => modifier.kind === import_typescript.default.SyntaxKind.DefaultKeyword) ?? false;
+  return { exported: Boolean(exported || defaultExport), defaultExport };
+}
 function extractTypeScript(content, filePath) {
   const symbols = [];
   const imports = [];
@@ -3452,9 +3463,18 @@ function extractTypeScript(content, filePath) {
     true,
     typeScriptScriptKind(filePath)
   );
+  const namedExports = /* @__PURE__ */ new Set();
+  for (const statement of sourceFile.statements) {
+    if (import_typescript.default.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && import_typescript.default.isNamedExports(statement.exportClause)) {
+      for (const element of statement.exportClause.elements) {
+        namedExports.add(element.propertyName?.text ?? element.name.text);
+      }
+    }
+  }
   const addSymbol = (node, name, kind, ownerQualifiedName, ownerKey) => {
     const qualifiedName = ownerQualifiedName ? `${ownerQualifiedName}.${name}` : name;
     const line = typeScriptLine(sourceFile, node);
+    const exportStatus = ownerQualifiedName ? { exported: false, defaultExport: false } : typeScriptExportStatus(node, name, namedExports);
     const symbol = {
       name,
       kind,
@@ -3462,7 +3482,9 @@ function extractTypeScript(content, filePath) {
       line,
       endLine: typeScriptEndLine(sourceFile, node),
       qualifiedName,
-      localKey: buildSymbolKey(filePath, qualifiedName, kind)
+      localKey: buildSymbolKey(filePath, qualifiedName, kind),
+      exported: exportStatus.exported,
+      defaultExport: exportStatus.defaultExport
     };
     symbols.push(symbol);
     if (ownerKey) {
@@ -3604,7 +3626,9 @@ function extractPython(content, filePath) {
       filePath,
       line,
       qualifiedName,
-      localKey: buildSymbolKey(filePath, qualifiedName, kind)
+      localKey: buildSymbolKey(filePath, qualifiedName, kind),
+      exported: /^[A-Z]/.test(name),
+      defaultExport: false
     });
   }
   for (const match of content.matchAll(importPattern)) {
@@ -3771,7 +3795,7 @@ function buildLocalCodeOverlay(options = {}) {
     }
     const contentHash2 = sha2563(indexedContent);
     const previousFile = previousFiles.get(filePath);
-    const canReuse = previous?.version === "snipara.local_code_overlay.v2" && previous.extractorVersion === 2 && previousFile?.sha256 === contentHash2 && previousFile.language === language;
+    const canReuse = previous?.version === "snipara.local_code_overlay.v2" && previous.extractorVersion === 3 && previousFile?.sha256 === contentHash2 && previousFile.language === language;
     const extracted = canReuse ? {
       symbols: previous.symbols.filter((item) => item.filePath === filePath),
       imports: previous.imports.filter((item) => item.filePath === filePath),
@@ -3798,6 +3822,7 @@ function buildLocalCodeOverlay(options = {}) {
     extractedEdges.push(...extracted.edges);
   }
   const edges = resolveLocalGraphEdges(files, symbols, imports, references2, extractedEdges);
+  const semantic = buildLocalSemanticModel({ symbols, edges });
   for (const file of files) {
     file.edgeCount = edges.filter((edge) => edge.filePath === file.path).length;
   }
@@ -3833,7 +3858,7 @@ function buildLocalCodeOverlay(options = {}) {
   ) : null;
   return {
     version: "snipara.local_code_overlay.v2",
-    extractorVersion: 2,
+    extractorVersion: 3,
     generatedAt: now,
     indexedAt: now,
     repoRoot,
@@ -3859,6 +3884,7 @@ function buildLocalCodeOverlay(options = {}) {
     imports,
     references: references2,
     edges,
+    semantic,
     incremental: {
       reusedFiles,
       parsedFiles,
@@ -3895,6 +3921,7 @@ function summarizeLocalCodeOverlay(manifest) {
       imports: manifest.imports.length,
       references: manifest.references.length,
       edges: manifest.edges.length,
+      semanticAssertions: manifest.semantic?.assertions.length ?? 0,
       excluded: manifest.excluded.total
     },
     incremental: manifest.incremental,
@@ -4226,9 +4253,10 @@ function traverseLocalGraph(manifest, seeds, options) {
     incoming.set(edge.to, [...incoming.get(edge.to) ?? [], edge]);
     outgoing.set(edge.from, [...outgoing.get(edge.from) ?? [], edge]);
   }
-  const seedSet = new Set(seeds);
-  const visited = new Set(seeds);
-  const queue = seeds.map((key) => ({
+  const uniqueSeeds = [...new Set(seeds)];
+  const boundedSeeds = uniqueSeeds.slice(0, options.maxNodes);
+  const visited = new Set(boundedSeeds);
+  const queue = boundedSeeds.map((key) => ({
     key,
     depth: 0,
     path: [key],
@@ -4236,7 +4264,7 @@ function traverseLocalGraph(manifest, seeds, options) {
   }));
   const nodes = [];
   const traversedEdges = [];
-  let truncated = false;
+  let truncated = boundedSeeds.length < uniqueSeeds.length;
   while (queue.length > 0) {
     const current = queue.shift();
     if (!current || current.depth >= options.depth) continue;
@@ -4246,7 +4274,7 @@ function traverseLocalGraph(manifest, seeds, options) {
     ];
     for (const candidate of candidates) {
       if (visited.has(candidate.next)) continue;
-      if (visited.size >= options.maxNodes + seedSet.size) {
+      if (visited.size >= options.maxNodes) {
         truncated = true;
         queue.length = 0;
         break;
@@ -4280,6 +4308,366 @@ function uniqueTraversalFiles(nodes, excluded) {
     )
   ].sort();
 }
+var LOCAL_SEMANTIC_TEST_PATH = /(^|\/)(tests?|__tests__|fixtures?)(\/|$)|\.(test|spec)\./i;
+var LOCAL_SEMANTIC_SENSITIVE_PATH = /(^|\/)(auth|middleware|billing|payments?|stripe|webhooks?|prisma|schema|migrations?|deploy)(\/|\.|$)/i;
+var LOCAL_SEMANTIC_CONTRACT_PATH = /(^|\/)(schemas?|contracts?|protocols?|interfaces?|config|tool_defs)(\/|\.|$)|route\.(ts|tsx|py)$/i;
+function localSemanticEvidence(kind, detail, metadata = {}) {
+  return { kind, detail, ...metadata };
+}
+function localSemanticAssertion(subject, predicate, value, confidence, source2, evidence) {
+  const identity = JSON.stringify([subject, predicate, value, source2]);
+  return {
+    id: `semantic-${sha2563(identity).slice(0, 16)}`,
+    subject,
+    predicate,
+    value,
+    confidence: Math.round(Math.max(0, Math.min(1, confidence)) * 1e3) / 1e3,
+    source: source2,
+    extractorVersion: 1,
+    evidence
+  };
+}
+function localArchitectureRoles(symbol) {
+  const haystack = `${symbol.filePath} ${symbol.name}`;
+  const candidates = [
+    { role: "repository", pattern: /repository|(^|[_.])repo($|[_.])/i, confidence: 0.9 },
+    { role: "adapter", pattern: /adapter/i, confidence: 0.9 },
+    { role: "facade", pattern: /facade/i, confidence: 0.9 },
+    { role: "controller", pattern: /controller/i, confidence: 0.85 },
+    { role: "service", pattern: /service/i, confidence: 0.78 },
+    { role: "worker", pattern: /worker|background[_-]?job|indexer/i, confidence: 0.82 },
+    { role: "factory", pattern: /factory|builder/i, confidence: 0.76 }
+  ];
+  const roles = [];
+  if (/\/app\/api\//i.test(symbol.filePath) || /\/route\.(ts|tsx|py)$/i.test(symbol.filePath)) {
+    roles.push(
+      localSemanticAssertion(
+        symbol.localKey,
+        "architecture_role",
+        "route_handler",
+        0.94,
+        "architecture-pattern-rules",
+        [
+          localSemanticEvidence("route_path", "Route path identifies an API boundary.", {
+            filePath: symbol.filePath,
+            line: symbol.line
+          })
+        ]
+      )
+    );
+  }
+  if (LOCAL_SEMANTIC_TEST_PATH.test(symbol.filePath)) {
+    roles.push(
+      localSemanticAssertion(
+        symbol.localKey,
+        "architecture_role",
+        "test",
+        0.98,
+        "architecture-pattern-rules",
+        [localSemanticEvidence("test_path", "File is under a test surface.")]
+      )
+    );
+  }
+  for (const candidate of candidates) {
+    if (!candidate.pattern.test(haystack)) continue;
+    roles.push(
+      localSemanticAssertion(
+        symbol.localKey,
+        "architecture_role",
+        candidate.role,
+        candidate.confidence,
+        "architecture-pattern-rules",
+        [
+          localSemanticEvidence(
+            "name_or_path_pattern",
+            `Name or path matches the ${candidate.role} pattern.`,
+            { filePath: symbol.filePath, line: symbol.line }
+          )
+        ]
+      )
+    );
+  }
+  return roles;
+}
+function localSymbolSemanticAssertions(symbol) {
+  const assertions = [];
+  const routeSurface = /\/app\/api\//i.test(symbol.filePath) || /\/route\.(ts|tsx|py)$/i.test(symbol.filePath);
+  const toolSurface = /(^|\/)(mcp|tool_defs)(\/|\.|$)/i.test(symbol.filePath);
+  const publicEvidence = [];
+  if (symbol.exported) {
+    publicEvidence.push(
+      localSemanticEvidence(
+        "explicit_export",
+        "TypeScript/Go declaration is explicitly exported.",
+        {
+          filePath: symbol.filePath,
+          line: symbol.line
+        }
+      )
+    );
+  }
+  if (routeSurface) {
+    publicEvidence.push(
+      localSemanticEvidence("route_path", "Symbol is declared in a route module.", {
+        filePath: symbol.filePath,
+        line: symbol.line
+      })
+    );
+  }
+  if (toolSurface) {
+    publicEvidence.push(
+      localSemanticEvidence(
+        "tool_surface",
+        "Symbol is declared in an MCP/tool-definition surface.",
+        {
+          filePath: symbol.filePath,
+          line: symbol.line
+        }
+      )
+    );
+  }
+  if (publicEvidence.length > 0) {
+    assertions.push(
+      localSemanticAssertion(
+        symbol.localKey,
+        "public_api",
+        true,
+        Math.min(0.98, 0.82 + publicEvidence.length * 0.05),
+        symbol.exported ? "typescript-compiler-api" : "architecture-pattern-rules",
+        publicEvidence
+      )
+    );
+  }
+  let contractKind = null;
+  const contractEvidence = [];
+  if (symbol.exported && ["interface", "type"].includes(symbol.kind)) {
+    contractKind = "exported_type_contract";
+    contractEvidence.push(
+      localSemanticEvidence("symbol_kind", `Exported ${symbol.kind} defines a structural contract.`)
+    );
+  } else if (LOCAL_SEMANTIC_CONTRACT_PATH.test(symbol.filePath)) {
+    contractKind = "repository_boundary_contract";
+    contractEvidence.push(
+      localSemanticEvidence(
+        "contract_path",
+        "File path denotes a schema, contract, config, route, or tool boundary."
+      )
+    );
+  } else if (symbol.exported) {
+    contractKind = "public_surface_contract";
+    contractEvidence.push(...publicEvidence.slice(0, 1));
+  }
+  if (contractKind) {
+    assertions.push(
+      localSemanticAssertion(
+        symbol.localKey,
+        "implicit_contract",
+        contractKind,
+        ["interface", "type"].includes(symbol.kind) ? 0.92 : 0.78,
+        symbol.exported ? "typescript-compiler-api" : "architecture-pattern-rules",
+        contractEvidence
+      )
+    );
+  }
+  assertions.push(...localArchitectureRoles(symbol));
+  let criticality = "ordinary";
+  let criticalityConfidence = 0.58;
+  let criticalityEvidence = [
+    localSemanticEvidence("default", "No critical or incidental evidence matched.")
+  ];
+  if (LOCAL_SEMANTIC_TEST_PATH.test(symbol.filePath)) {
+    criticality = "incidental";
+    criticalityConfidence = 0.95;
+    criticalityEvidence = [localSemanticEvidence("test_path", "Test-only dependency.")];
+  } else if (LOCAL_SEMANTIC_SENSITIVE_PATH.test(symbol.filePath) || routeSurface || toolSurface) {
+    criticality = "critical";
+    criticalityConfidence = 0.92;
+    criticalityEvidence = [
+      localSemanticEvidence(
+        "sensitive_surface",
+        "Path identifies an auth, billing, schema, webhook, deploy, route, or MCP surface."
+      )
+    ];
+  } else if (publicEvidence.length > 0) {
+    criticality = "important";
+    criticalityConfidence = 0.85;
+    criticalityEvidence = [
+      localSemanticEvidence(
+        "exported_surface",
+        "Explicit export defines a module contract but is not by itself a critical runtime surface."
+      )
+    ];
+  } else if (contractKind) {
+    criticality = "important";
+    criticalityConfidence = 0.82;
+    criticalityEvidence = [
+      localSemanticEvidence("contract_surface", "Dependency defines a repository contract.")
+    ];
+  }
+  assertions.push(
+    localSemanticAssertion(
+      symbol.localKey,
+      "dependency_criticality",
+      criticality,
+      criticalityConfidence,
+      "criticality-rules",
+      criticalityEvidence
+    )
+  );
+  return assertions;
+}
+function buildLocalSemanticModel(manifest, options = {}) {
+  const symbols = options.symbolKeys ? manifest.symbols.filter((symbol) => options.symbolKeys?.has(symbol.localKey)) : manifest.symbols;
+  const assertions = symbols.flatMap(localSymbolSemanticAssertions);
+  const symbolByKey = new Map(manifest.symbols.map((symbol) => [symbol.localKey, symbol]));
+  const criticalityBySymbol = new Map(
+    assertions.filter((assertion) => assertion.predicate === "dependency_criticality").map((assertion) => [assertion.subject, String(assertion.value)])
+  );
+  const criticalityRank = {
+    incidental: 0,
+    ordinary: 1,
+    important: 2,
+    critical: 3
+  };
+  const criticalityByFile = /* @__PURE__ */ new Map();
+  for (const symbol of manifest.symbols) {
+    const value = criticalityBySymbol.get(symbol.localKey);
+    if (!value) continue;
+    const current = criticalityByFile.get(symbol.filePath);
+    if (!current || criticalityRank[value] > criticalityRank[current]) {
+      criticalityByFile.set(symbol.filePath, value);
+    }
+  }
+  for (const edge of options.edges ?? []) {
+    const fromSymbol = symbolByKey.get(edge.from);
+    const toSymbol = symbolByKey.get(edge.to);
+    const fromFile = fromSymbol?.filePath ?? edge.from.replace(/^local-file::/, "");
+    const toFile = toSymbol?.filePath ?? edge.to.replace(/^local-file::/, "");
+    const fromCriticality = criticalityBySymbol.get(edge.from) ?? criticalityByFile.get(fromFile);
+    const toCriticality = criticalityBySymbol.get(edge.to) ?? criticalityByFile.get(toFile);
+    const edgeSubject = `edge::${edge.from}::${edge.kind}::${edge.to}`;
+    const evidence = [
+      localSemanticEvidence("graph_edge", `${edge.kind} from ${fromFile} to ${toFile}.`, {
+        filePath: edge.filePath,
+        line: edge.line,
+        edgeKind: edge.kind
+      })
+    ];
+    let value = "ordinary";
+    let confidence = 0.62;
+    if (LOCAL_SEMANTIC_TEST_PATH.test(fromFile) || LOCAL_SEMANTIC_TEST_PATH.test(toFile)) {
+      value = "incidental";
+      confidence = 0.92;
+      evidence.push(localSemanticEvidence("test_path", "At least one edge endpoint is test-only."));
+    } else if (fromCriticality === "critical" || toCriticality === "critical") {
+      value = "critical";
+      confidence = 0.9;
+      evidence.push(
+        localSemanticEvidence("critical_endpoint", "At least one dependency endpoint is critical.")
+      );
+    } else if (edge.kind === "CONTAINS" || edge.confidence < 0.65) {
+      value = "incidental";
+      confidence = 0.78;
+      evidence.push(
+        localSemanticEvidence(
+          "weak_or_structural",
+          "Containment or low-confidence evidence is incidental to change propagation."
+        )
+      );
+    } else if (fromCriticality === "important" || toCriticality === "important") {
+      value = "important";
+      confidence = 0.82;
+      evidence.push(
+        localSemanticEvidence(
+          "contract_endpoint",
+          "At least one dependency endpoint is a contract."
+        )
+      );
+    }
+    assertions.push(
+      localSemanticAssertion(
+        edgeSubject,
+        "dependency_criticality",
+        value,
+        confidence,
+        "graph-criticality-rules",
+        evidence
+      )
+    );
+  }
+  const allAssertions = [
+    ...new Map(assertions.map((assertion) => [assertion.id, assertion])).values()
+  ].sort(
+    (left, right) => `${left.subject}:${left.predicate}:${String(left.value)}`.localeCompare(
+      `${right.subject}:${right.predicate}:${String(right.value)}`
+    )
+  );
+  const assertionLimit = (options.scope ?? "repository") === "impact" ? 2e3 : 5e3;
+  const returnedAssertions = allAssertions.slice(0, assertionLimit);
+  const allPublicContracts = allAssertions.filter(
+    (assertion) => assertion.predicate === "public_api" || assertion.predicate === "implicit_contract"
+  );
+  const allArchitectureRoles = allAssertions.filter(
+    (assertion) => assertion.predicate === "architecture_role"
+  );
+  const allDependencyCriticality = allAssertions.filter(
+    (assertion) => assertion.predicate === "dependency_criticality"
+  );
+  const publicContracts = returnedAssertions.filter(
+    (assertion) => assertion.predicate === "public_api" || assertion.predicate === "implicit_contract"
+  );
+  const architectureRoles = returnedAssertions.filter(
+    (assertion) => assertion.predicate === "architecture_role"
+  );
+  const dependencyCriticality = returnedAssertions.filter(
+    (assertion) => assertion.predicate === "dependency_criticality"
+  );
+  return {
+    version: "snipara.semantic.v1",
+    extractorVersion: 1,
+    source: "deterministic-graph-inference",
+    scope: options.scope ?? "repository",
+    assertions: returnedAssertions,
+    publicContracts,
+    architectureRoles,
+    dependencyCriticality,
+    truncation: {
+      truncated: allAssertions.length > assertionLimit,
+      totalAssertionCount: allAssertions.length,
+      returnedAssertionCount: returnedAssertions.length,
+      assertionLimit
+    },
+    historicalRegression: {
+      mode: "shadow",
+      sampleThreshold: 3,
+      failureEventCount: 0,
+      associations: [],
+      riskContributionEnabled: false,
+      suggestedRiskDelta: 0,
+      caveat: "The local overlay has no durable regression outcome stream. Historical path learning stays shadow-only until hosted evidence is available."
+    },
+    summary: {
+      assertionCount: allAssertions.length,
+      publicContractCount: allPublicContracts.length,
+      architectureRoleCount: allArchitectureRoles.length,
+      criticalDependencyCount: allDependencyCriticality.filter(
+        (assertion) => assertion.value === "critical"
+      ).length,
+      criticalEdgeCount: allDependencyCriticality.filter(
+        (assertion) => assertion.value === "critical" && assertion.subject.startsWith("edge::")
+      ).length,
+      incidentalDependencyCount: allDependencyCriticality.filter(
+        (assertion) => assertion.value === "incidental"
+      ).length,
+      historicalAssociationCount: 0
+    },
+    caveats: [
+      "Semantic assertions are deterministic inferences, not declarations of author intent.",
+      "Name-only architecture patterns use lower confidence than explicit export or path evidence.",
+      "Historical regression learning requires hosted outcome evidence and remains shadow-only."
+    ]
+  };
+}
 function loadLocalRiskConfig(repoRoot) {
   const defaults = {
     depthDecay: 0.65,
@@ -4304,7 +4692,7 @@ function loadLocalRiskConfig(repoRoot) {
     return defaults;
   }
 }
-function buildLocalRisk(manifest, changedFiles, traversal, depth) {
+function buildLocalRisk(manifest, changedFiles, traversal, depth, semantic) {
   const config = loadLocalRiskConfig(manifest.repoRoot);
   const allFiles = [
     ...changedFiles,
@@ -4343,13 +4731,27 @@ function buildLocalRisk(manifest, changedFiles, traversal, depth) {
     (reference) => changedFiles.includes(reference.filePath) && !resolvedReferenceKeys.has(`${reference.from}:${reference.line}`)
   ).length;
   const uncertaintyPenalty = Math.min(15, unresolvedReferences * 2 + (traversal.truncated ? 8 : 0));
-  const rawScore = criticality * (directFiles.size * 8 + propagation * 4) + uncertaintyPenalty;
+  const criticalSemanticDependencies = semantic.summary.criticalEdgeCount;
+  const changedSymbolKeys = new Set(
+    manifest.symbols.filter((symbol) => changedFiles.includes(symbol.filePath)).map((symbol) => symbol.localKey)
+  );
+  const changedContracts = manifest.symbols.filter((symbol) => changedSymbolKeys.has(symbol.localKey)).flatMap(localSymbolSemanticAssertions).filter(
+    (assertion) => assertion.predicate === "public_api" || assertion.predicate === "implicit_contract"
+  ).length;
+  const semanticRiskPoints = Math.min(20, criticalSemanticDependencies * 3) + Math.min(10, changedContracts * 2);
+  const rawScore = criticality * (directFiles.size * 8 + propagation * 4) + uncertaintyPenalty + semanticRiskPoints;
   const score = Math.max(0, Math.min(100, Math.round(rawScore)));
   const reasons = [
     `${directFiles.size} direct dependent file${directFiles.size === 1 ? "" : "s"}`,
     `${transitiveFiles.size} transitive dependent file${transitiveFiles.size === 1 ? "" : "s"}`,
     ...criticalMatches.length ? [`critical-surface multiplier ${criticality.toFixed(2)}`] : [],
     ...unresolvedReferences ? [`${unresolvedReferences} unresolved reference${unresolvedReferences === 1 ? "" : "s"}`] : [],
+    ...criticalSemanticDependencies ? [
+      `${criticalSemanticDependencies} critical semantic dependenc${criticalSemanticDependencies === 1 ? "y" : "ies"}`
+    ] : [],
+    ...changedContracts ? [
+      `${changedContracts} public or implicit contract assertion${changedContracts === 1 ? "" : "s"}`
+    ] : [],
     ...traversal.truncated ? ["traversal truncated by max-nodes"] : []
   ];
   return {
@@ -4360,9 +4762,12 @@ function buildLocalRisk(manifest, changedFiles, traversal, depth) {
     transitiveDependentFiles: transitiveFiles.size,
     criticality,
     uncertaintyPenalty,
+    semanticRiskPoints,
+    criticalSemanticDependencies,
+    changedContracts,
     unresolvedReferences,
     reasons,
-    formula: "criticality * (directImpact + decayedEdgePropagation) + uncertaintyPenalty"
+    formula: "criticality * (directImpact + decayedEdgePropagation) + uncertaintyPenalty + semanticRiskPoints"
   };
 }
 function missingTargetDetail(manifest, filePath) {
@@ -4678,6 +5083,42 @@ function hybridRisk(local, hosted) {
     )
   };
 }
+function hybridSemantic(local, hosted) {
+  const localSemantic = asUnknownRecord(local.semantic);
+  const hostedSemantic = asUnknownRecord(hosted.semantic);
+  if (Object.keys(localSemantic).length === 0 && Object.keys(hostedSemantic).length === 0) {
+    return void 0;
+  }
+  const assertions = mergeResultArrays(
+    [{ assertions: hostedSemantic.assertions }, { assertions: localSemantic.assertions }],
+    ["assertions"]
+  );
+  return {
+    version: "snipara.semantic.hybrid.v1",
+    mode: "hybrid",
+    provenance: {
+      canonicalBase: Object.keys(hostedSemantic).length > 0 ? "hosted_graph" : "unavailable",
+      checkoutDelta: Object.keys(localSemantic).length > 0 ? "local_overlay" : "unavailable",
+      crossSourceAssertionSynthesis: false
+    },
+    assertions,
+    summary: {
+      assertionCount: assertions.length,
+      publicContractCount: assertions.filter(
+        (item) => asUnknownRecord(item).predicate === "public_api" || asUnknownRecord(item).predicate === "implicit_contract"
+      ).length,
+      architectureRoleCount: assertions.filter(
+        (item) => asUnknownRecord(item).predicate === "architecture_role"
+      ).length,
+      criticalDependencyCount: assertions.filter(
+        (item) => asUnknownRecord(item).predicate === "dependency_criticality" && asUnknownRecord(item).value === "critical"
+      ).length
+    },
+    historicalRegression: hostedSemantic.historical_regression ?? hostedSemantic.historicalRegression ?? localSemantic.historicalRegression ?? null,
+    local: Object.keys(localSemantic).length > 0 ? localSemantic : null,
+    hosted: Object.keys(hostedSemantic).length > 0 ? hostedSemantic : null
+  };
+}
 function mergeHybridCodeResults(verb, localResult, hostedResult, hostedError) {
   const local = asUnknownRecord(localResult);
   const hosted = asUnknownRecord(hostedResult);
@@ -4697,6 +5138,7 @@ function mergeHybridCodeResults(verb, localResult, hostedResult, hostedError) {
   collectStringValues(local, /* @__PURE__ */ new Set(["changed_files", "changedFiles"]), changedFiles);
   collectStringValues(hosted, /* @__PURE__ */ new Set(["changed_files", "changedFiles"]), changedFiles);
   const risk = hybridRisk(local, hosted);
+  const semantic = hybridSemantic(local, hosted);
   const recommendedTests = mergeResultArrays(
     [hosted, local],
     ["recommended_tests", "recommendedTests", "related_tests", "relatedTests", "tests"]
@@ -4724,6 +5166,7 @@ function mergeHybridCodeResults(verb, localResult, hostedResult, hostedError) {
     changed_files: [...changedFiles].sort(),
     impactedFiles: [...affectedFiles].sort(),
     ...risk ? { risk } : {},
+    ...semantic ? { semantic } : {},
     recommended_tests: recommendedTests,
     recommended_actions: recommendedActions,
     coverage_gaps: coverageGaps,
@@ -5341,6 +5784,24 @@ function buildLocalImpactResult(options) {
     edgeKinds: options.edgeKinds?.length ? options.edgeKinds : ["IMPORTS", "CALLS", "REFERENCES"],
     maxNodes
   });
+  const traversalEdges = [
+    ...new Map(
+      traversal.nodes.flatMap((node) => node.edges).map((edge) => [`${edge.from}:${edge.kind}:${edge.to}:${edge.line}`, edge])
+    ).values()
+  ];
+  const semanticSymbolKeys = /* @__PURE__ */ new Set([...seedKeys, ...traversal.nodes.map((node) => node.key)]);
+  const semanticFiles = /* @__PURE__ */ new Set([
+    ...changedFiles,
+    ...traversal.nodes.flatMap((node) => node.filePath ? [node.filePath] : [])
+  ]);
+  for (const candidate of manifest.symbols) {
+    if (semanticFiles.has(candidate.filePath)) semanticSymbolKeys.add(candidate.localKey);
+  }
+  const semantic = buildLocalSemanticModel(manifest, {
+    scope: "impact",
+    symbolKeys: semanticSymbolKeys,
+    edges: traversalEdges
+  });
   const transitiveFiles = uniqueTraversalFiles(traversal.nodes, selectedFiles);
   const impactedFiles = [.../* @__PURE__ */ new Set([...directImpactedFiles, ...transitiveFiles])].sort();
   const relevantWarningFiles = /* @__PURE__ */ new Set([
@@ -5381,7 +5842,8 @@ function buildLocalImpactResult(options) {
       visitedCount: traversal.visitedCount,
       maxNodes
     },
-    risk: buildLocalRisk(manifest, changedFiles, traversal, depth)
+    semantic,
+    risk: buildLocalRisk(manifest, changedFiles, traversal, depth, semantic)
   };
 }
 async function codeLocalImportsCommand(options) {

package/docs/CODE_GRAPH.md

@@ -0,0 +1,74 @@
+# Semantic Code Graph
+
+`snipara-companion code impact` builds a structural graph from the current
+checkout and adds a deterministic semantic model above it. The semantic layer
+does not replace `CALLS`, `REFERENCES`, `IMPORTS`, or `CONTAINS` edges. It
+classifies what those nodes and edges mean for a change.
+
+## Semantic model v1
+
+Local manifests and impact results expose `snipara.semantic.v1`. Each assertion
+contains:
+
+- `subject`: a stable local symbol key or edge identity;
+- `predicate`: `public_api`, `implicit_contract`, `architecture_role`, or
+  `dependency_criticality`;
+- `value`: the inferred classification;
+- `confidence`: a bounded score from `0` to `1`;
+- `source` and `extractorVersion`;
+- `evidence`: the export modifier, symbol kind, file/path pattern, or graph edge
+  that produced the assertion.
+
+The extractor recognizes explicit TypeScript and Go exports, route and MCP
+surfaces, exported type contracts, and common Repository, Adapter, Facade,
+Controller, Service, Worker, Factory, schema, route-handler, and test roles.
+Name-only patterns have lower confidence than explicit export, route, or graph
+evidence.
+
+## Dependency criticality
+
+Criticality is evaluated for symbols and for the edges traversed by impact:
+
+- `critical`: runtime-exposed route/MCP surfaces and sensitive auth, billing,
+  schema, webhook, or deploy paths;
+- `important`: explicit module exports and inferred contract boundaries;
+- `ordinary`: normal application dependencies without stronger evidence;
+- `incidental`: test-only, containment, or weak-confidence dependencies.
+
+Local risk scoring adds bounded `semanticRiskPoints` for critical traversed
+dependencies and contracts in the changed files. The output lists the exact
+assertions and the formula; callers never receive a hidden semantic multiplier.
+Large impact traversals cap returned assertions at 2,000 (repository manifests
+at 5,000) and report total/returned counts in `semantic.truncation`; risk uses
+the complete pre-truncation counts.
+
+## Hybrid provenance
+
+Hybrid queries preserve hosted canonical assertions and local checkout-delta
+assertions under `snipara.semantic.hybrid.v1`. Snipara unions the evidence but
+does not manufacture cross-source edges or assertions.
+
+## Historical regression paths
+
+Hosted impact can associate sanitized warning/error execution traces with
+graph paths by their tracked files. Version 1 reports sample count, confidence,
+event IDs, and a suggested risk delta. This surface is intentionally
+`mode: shadow` and `riskContributionEnabled: false`: temporal association is
+not causal proof, and it cannot affect risk until separately calibrated and
+promoted.
+
+The local overlay has no durable outcome stream, so it returns the same shadow
+contract with zero samples and directs callers to hosted evidence when needed.
+
+## Example
+
+```bash
+npx -y snipara-companion code impact \
+  --source local \
+  --changed-files src/auth/session-repository.ts \
+  --depth 4 \
+  --json
+```
+
+Inspect `result.semantic.assertions`, `result.semantic.summary`, and
+`result.risk.semanticRiskPoints` in the response.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "3.6.0",
+  "version": "3.6.2",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {