@decantr/core 3.4.0 → 3.5.0

package/README.md

@@ -25,11 +25,11 @@ npm install @decantr/core
 - execution-pack schema URLs
 - markdown rendering for compiled packs
 - IR and pipeline helpers used by higher-level Decantr surfaces
-- draft Decantr 3 typed graph types, graph constants, Essence/IR-to-graph snapshot derivation, temporal snapshot/diff shapes, source import/reference edges, contract capsule derivation with a bounded source-artifact path index, task-aware route-context ranking, behavior-obligation LocalRule projection support through existing graph shapes, node impact context extraction, and an in-memory `GraphStore` adapter for early graph-foundation work
+- Decantr 3 typed graph types, graph constants, Essence/IR-to-graph snapshot derivation, temporal snapshot/diff shapes, source import/reference edges, contract capsule derivation with a bounded source-artifact path index, deterministic hybrid route/impact ranking, behavior-obligation LocalRule projection support through existing graph shapes, evidence/proof ingestion, test-coverage hint edges, node impact context extraction, and an in-memory `GraphStore` adapter
 
 In the current workflow architecture, `@decantr/core` owns the canonical adapter labels used by compiled packs, while runnable greenfield bootstrap adapters are resolved in the CLI on top of those labels.
 
-The graph exports are draft Decantr 3 foundation APIs. They establish the storage boundary, typed schema shape, temporal snapshot/diff shape, payload-filterable node queries, task-aware route-context ranking, node impact traversal, and provider-neutral contract capsule shape for CLI, MCP, verifier, and CI integration. Behavior obligations remain app-owned local law in `.decantr/local-patterns.json`; higher-level packages project accepted obligations into existing `LocalRule` graph nodes with `payload.kind = "behavior-obligation"` instead of adding a new graph node type. The capsule keeps the contract cache key stable while listing bounded SourceArtifact paths agents can use for file-impact follow-up queries. The core package remains pure library code: filesystem graph persistence belongs in higher-level packages such as the CLI.
+The graph exports establish the storage boundary, typed schema shape, temporal snapshot/diff shape, payload-filterable node queries, hybrid route-context ranking, hybrid node/source impact traversal, and provider-neutral contract capsule shape for CLI, MCP, verifier, Studio, and CI integration. Ranking blends deterministic weighted traversal with local personalized PageRank and optional task-text boosts, so central graph nodes and task-relevant nodes both surface without introducing a graph database dependency. Behavior obligations remain app-owned local law in `.decantr/local-patterns.json`; higher-level packages project accepted obligations into existing `LocalRule` graph nodes with `payload.kind = "behavior-obligation"` instead of adding a new graph node type. Evidence Bundles, runtime probes, visual manifests, baseline diffs, repair plans, and proof reports are ingested through existing graph node/edge shapes where possible, and `TEST_COVERS_NODE` edges act as verification hints rather than proof of production UI behavior. The capsule keeps the contract cache key stable while listing bounded SourceArtifact paths agents can use for file-impact follow-up queries. The core package remains pure library code: filesystem graph persistence belongs in higher-level packages such as the CLI.
 
 ## FAQ
 

package/dist/index.d.ts

@@ -371,7 +371,7 @@ interface GraphRouteContext {
     sourceHash: string;
     routeNode: GraphNode;
     ranking: {
-        method: 'weighted_traversal' | 'weighted_traversal_with_task_boost';
+        method: 'weighted_traversal' | 'weighted_traversal_with_task_boost' | 'hybrid_weighted_pagerank' | 'hybrid_weighted_pagerank_with_task_boost';
         seed: string;
         task_keywords: string[];
     };
@@ -420,7 +420,7 @@ interface GraphImpactContext {
     seedNodes: GraphNode[];
     missingNodeIds: string[];
     ranking: {
-        method: 'impact_traversal' | 'impact_traversal_with_task_boost';
+        method: 'impact_traversal' | 'impact_traversal_with_task_boost' | 'hybrid_impact_pagerank' | 'hybrid_impact_pagerank_with_task_boost';
         seed: string[];
         task_keywords: string[];
     };

package/dist/index.js

@@ -415,7 +415,86 @@ function buildContractCapsuleFromSnapshot(snapshot, options = {}) {
     open_findings: openFindings
   };
 }
-function rankGraphRouteContextNodes(nodes, routeNodeId, ids, keywords = []) {
+var PAGERANK_DAMPING = 0.82;
+var PAGERANK_ITERATIONS = 16;
+var RELATION_RANK_WEIGHTS = {
+  PAGE_ROUTED_AT_ROUTE: 1,
+  PAGE_USES_SHELL: 0.9,
+  PAGE_COMPOSES_PATTERN: 0.88,
+  PATTERN_NEEDS_COMPONENT: 0.82,
+  COMPONENT_STYLED_WITH_TOKEN: 0.62,
+  LOCAL_RULE_APPLIES_TO: 0.72,
+  STYLE_BRIDGE_MAPS_TO: 0.7,
+  FINDING_ANCHORED_AT: 0.78,
+  EVIDENCE_SUPPORTS_FINDING: 0.58,
+  EVIDENCE_CAPTURED_FOR: 0.56,
+  REPAIR_FIXES_FINDING: 0.54,
+  NODE_DERIVED_FROM_SOURCE: 0.5,
+  SOURCE_IMPORTS_SOURCE: 0.42,
+  TEST_COVERS_NODE: 0.36
+};
+function personalizedPageRank(nodes, edges, seedIds) {
+  const nodeIds = new Set(nodes.map((node) => node.id));
+  const seeds = [...seedIds].filter((id) => nodeIds.has(id)).sort();
+  const activeSeeds = seeds.length > 0 ? seeds : sortGraphNodes(nodes).slice(0, 1).map((node) => node.id);
+  const teleport = /* @__PURE__ */ new Map();
+  for (const node of nodes) teleport.set(node.id, 0);
+  for (const seed of activeSeeds) teleport.set(seed, 1 / activeSeeds.length);
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const node of nodes) adjacency.set(node.id, []);
+  for (const edge of edges) {
+    if (!nodeIds.has(edge.src) || !nodeIds.has(edge.dst)) continue;
+    const weight = RELATION_RANK_WEIGHTS[edge.relation] ?? 0.32;
+    adjacency.get(edge.src)?.push({ id: edge.dst, weight });
+    adjacency.get(edge.dst)?.push({ id: edge.src, weight: weight * 0.82 });
+  }
+  let rank = new Map(teleport);
+  for (let pass = 0; pass < PAGERANK_ITERATIONS; pass += 1) {
+    const next = /* @__PURE__ */ new Map();
+    for (const node of nodes) {
+      next.set(node.id, (1 - PAGERANK_DAMPING) * (teleport.get(node.id) ?? 0));
+    }
+    for (const node of nodes) {
+      const outgoing = adjacency.get(node.id) ?? [];
+      const current = rank.get(node.id) ?? 0;
+      const totalWeight = outgoing.reduce((sum, edge) => sum + edge.weight, 0);
+      if (totalWeight <= 0) {
+        next.set(node.id, (next.get(node.id) ?? 0) + PAGERANK_DAMPING * current);
+        continue;
+      }
+      for (const edge of outgoing) {
+        next.set(
+          edge.id,
+          (next.get(edge.id) ?? 0) + PAGERANK_DAMPING * current * (edge.weight / totalWeight)
+        );
+      }
+    }
+    rank = next;
+  }
+  const max = Math.max(...[...rank.values()], 1e-5);
+  return new Map([...rank.entries()].map(([id, value]) => [id, value / max]));
+}
+function hybridRankNodes(nodes, edges, seedIds, baseRank, keywords) {
+  const ppr = personalizedPageRank(nodes, edges, seedIds);
+  return nodes.map((node) => {
+    const ranked = baseRank(node);
+    const searchText = keywords.length > 0 ? graphNodeSearchText(node) : "";
+    const matchedTerms = keywords.filter((keyword) => searchText.includes(keyword));
+    const taskBoost = Math.min(0.12, matchedTerms.length * 0.035);
+    const graphBoost = (ppr.get(node.id) ?? 0) * 0.32;
+    const weightedScore = ranked.score * 0.68 + graphBoost + taskBoost;
+    return {
+      id: node.id,
+      type: node.type,
+      score: Number(Math.min(1, weightedScore).toFixed(3)),
+      reason: matchedTerms.length > 0 ? `${ranked.reason}+pagerank+task_match` : `${ranked.reason}+pagerank`,
+      ...matchedTerms.length > 0 ? { matched_terms: matchedTerms } : {}
+    };
+  }).sort(
+    (a, b) => b.score - a.score || (b.matched_terms?.length ?? 0) - (a.matched_terms?.length ?? 0) || a.id.localeCompare(b.id)
+  );
+}
+function rankGraphRouteContextNodes(nodes, edges, routeNodeId, ids, keywords = []) {
   const scoreForNode = (node) => {
     if (node.id === routeNodeId) return { score: 1, reason: "requested_route" };
     if (ids.pages.includes(node.id)) return { score: 0.95, reason: "route_page" };
@@ -430,21 +509,7 @@ function rankGraphRouteContextNodes(nodes, routeNodeId, ids, keywords = []) {
     if (ids.sourceArtifacts.includes(node.id)) return { score: 0.32, reason: "source_provenance" };
     return { score: 0.24, reason: "included_context" };
   };
-  return nodes.map((node) => {
-    const ranked = scoreForNode(node);
-    const searchText = keywords.length > 0 ? graphNodeSearchText(node) : "";
-    const matchedTerms = keywords.filter((keyword) => searchText.includes(keyword));
-    const taskBoost = Math.min(0.12, matchedTerms.length * 0.035);
-    return {
-      id: node.id,
-      type: node.type,
-      score: Number(Math.min(1, ranked.score + taskBoost).toFixed(3)),
-      reason: matchedTerms.length > 0 ? `${ranked.reason}+task_match` : ranked.reason,
-      ...matchedTerms.length > 0 ? { matched_terms: matchedTerms } : {}
-    };
-  }).sort(
-    (a, b) => b.score - a.score || (b.matched_terms?.length ?? 0) - (a.matched_terms?.length ?? 0) || a.id.localeCompare(b.id)
-  );
+  return hybridRankNodes(nodes, edges, /* @__PURE__ */ new Set([routeNodeId]), scoreForNode, keywords);
 }
 function buildGraphRouteContext(snapshot, route, options = {}) {
   if (!snapshot) return null;
@@ -555,7 +620,7 @@ function buildGraphRouteContext(snapshot, route, options = {}) {
     sourceHash: snapshot.source_hash,
     routeNode,
     ranking: {
-      method: keywords.length > 0 ? "weighted_traversal_with_task_boost" : "weighted_traversal",
+      method: keywords.length > 0 ? "hybrid_weighted_pagerank_with_task_boost" : "hybrid_weighted_pagerank",
       seed: routeNode.id,
       task_keywords: keywords
     },
@@ -574,7 +639,7 @@ function buildGraphRouteContext(snapshot, route, options = {}) {
       sourceArtifacts: graphNodeIdsByType(nodes, "SourceArtifact").length
     },
     ids,
-    ranked: rankGraphRouteContextNodes(nodes, routeNode.id, ids, keywords),
+    ranked: rankGraphRouteContextNodes(nodes, edges, routeNode.id, ids, keywords),
     nodes,
     edges
   };
@@ -616,7 +681,7 @@ function impactIds(nodes) {
     sourceArtifacts: graphNodeIdsByType(nodes, "SourceArtifact")
   };
 }
-function rankGraphImpactContextNodes(nodes, seedIds, ids, keywords = []) {
+function rankGraphImpactContextNodes(nodes, edges, seedIds, ids, keywords = []) {
   const scoreForNode = (node) => {
     if (seedIds.has(node.id)) return { score: 1, reason: "seed_node" };
     if (ids.routes.includes(node.id)) return { score: 0.92, reason: "affected_route" };
@@ -633,21 +698,7 @@ function rankGraphImpactContextNodes(nodes, seedIds, ids, keywords = []) {
     if (ids.sourceArtifacts.includes(node.id)) return { score: 0.34, reason: "source_provenance" };
     return { score: 0.24, reason: "included_impact" };
   };
-  return nodes.map((node) => {
-    const ranked = scoreForNode(node);
-    const searchText = keywords.length > 0 ? graphNodeSearchText(node) : "";
-    const matchedTerms = keywords.filter((keyword) => searchText.includes(keyword));
-    const taskBoost = Math.min(0.12, matchedTerms.length * 0.035);
-    return {
-      id: node.id,
-      type: node.type,
-      score: Number(Math.min(1, ranked.score + taskBoost).toFixed(3)),
-      reason: matchedTerms.length > 0 ? `${ranked.reason}+task_match` : ranked.reason,
-      ...matchedTerms.length > 0 ? { matched_terms: matchedTerms } : {}
-    };
-  }).sort(
-    (a, b) => b.score - a.score || (b.matched_terms?.length ?? 0) - (a.matched_terms?.length ?? 0) || a.id.localeCompare(b.id)
-  );
+  return hybridRankNodes(nodes, edges, seedIds, scoreForNode, keywords);
 }
 function shouldTraverseImpactEdge(edge, includedNodeIds, projectId) {
   if (!IMPACT_TRAVERSAL_RELATIONS.has(edge.relation)) return false;
@@ -721,7 +772,7 @@ function buildGraphImpactContext(snapshot, seed, options = {}) {
   const totalEdges = edges.length;
   const keywords = taskKeywords(options.task);
   const fullIds = impactIds(nodes);
-  const fullRanked = rankGraphImpactContextNodes(nodes, seedNodeIds, fullIds, keywords);
+  const fullRanked = rankGraphImpactContextNodes(nodes, edges, seedNodeIds, fullIds, keywords);
   const boundedLimit = typeof options.limit === "number" && Number.isFinite(options.limit) && options.limit > 0 ? Math.floor(options.limit) : void 0;
   let truncated = false;
   if (boundedLimit && nodes.length > boundedLimit) {
@@ -737,14 +788,14 @@ function buildGraphImpactContext(snapshot, seed, options = {}) {
     truncated = true;
   }
   const ids = impactIds(nodes);
-  const ranked = rankGraphImpactContextNodes(nodes, seedNodeIds, ids, keywords);
+  const ranked = rankGraphImpactContextNodes(nodes, edges, seedNodeIds, ids, keywords);
   return {
     snapshotId: snapshot.id,
     sourceHash: snapshot.source_hash,
     seedNodes: sortGraphNodes(seedNodes),
     missingNodeIds,
     ranking: {
-      method: keywords.length > 0 ? "impact_traversal_with_task_boost" : "impact_traversal",
+      method: keywords.length > 0 ? "hybrid_impact_pagerank_with_task_boost" : "hybrid_impact_pagerank",
       seed: [...seedNodeIds].sort(),
       task_keywords: keywords
     },