@unbrained/pm-cli 2026.7.16 → 2026.7.18

package/dist/sdk/relationship-context.js

@@ -5,9 +5,18 @@
  * packet for agents, custom tools, and presentation-layer adapters.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="dfd47ca8-a68d-50e1-9aba-638d974a0027")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cf26c4d0-d60f-5ec5-858f-957ad719383e")}catch(e){}}();
 import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, } from "./pagination.js";
 import { createRelationshipKindRegistry, } from "./relationships.js";
+/** Deterministic priority used when one node matches several semantic families. */
+const RELATIONSHIP_CONTEXT_ROLE_PRIORITY = [
+    "prerequisite",
+    "dependent",
+    "ancestor",
+    "descendant",
+    "provenance",
+    "related",
+];
 const tokenEncoder = new TextEncoder();
 function positiveInteger(value, fallback, field) {
     const resolved = value ?? fallback;
@@ -18,16 +27,16 @@ function positiveInteger(value, fallback, field) {
 function estimateTokens(value) {
     return Math.max(1, Math.ceil(tokenEncoder.encode(JSON.stringify(value)).byteLength / 4));
 }
-function explainDirectEdge(edge, root, node, registry) {
-    const definition = registry.require(edge.kind);
-    if (definition.ordering) {
+function explainDirectEdge(edge, node, registry) {
+    const definition = registry.resolve(edge.kind);
+    if (definition?.ordering) {
         // Legacy and JSON-parsed definitions may predate explicit precedence.
         const sourceFirst = (definition.precedence ?? "source_before_target") ===
             "source_before_target";
         const before = sourceFirst ? edge.source : edge.target;
         return node === before ? "prerequisite" : "dependent";
     }
-    if (definition.hierarchy) {
+    if (definition?.hierarchy) {
         // Legacy and JSON-parsed definitions may predate explicit hierarchy direction.
         const sourceIsParent = (definition.hierarchyDirection ?? "source_parent") === "source_parent";
         const parent = sourceIsParent ? edge.source : edge.target;
@@ -41,16 +50,24 @@ function directReasons(rootEdges, root, node, registry) {
     const reasons = rootEdges
         .filter((edge) => (edge.source === root && edge.target === node) ||
         (edge.target === root && edge.source === node))
-        .map((edge) => explainDirectEdge(edge, root, node, registry));
+        .map((edge) => explainDirectEdge(edge, node, registry));
     return [...new Set(reasons)].sort();
 }
-function discoverNodes(graph, root, options) {
+/** Pick the deterministic primary family when a node matches several. */
+function primaryRole(roles) {
+    // Callers only pass non-empty classification sets drawn from the fixed
+    // family list, so a priority match always exists.
+    return RELATIONSHIP_CONTEXT_ROLE_PRIORITY.find((role) => roles.includes(role));
+}
+function discoverNodes(graph, root, registry, options) {
     const direction = options.direction ?? "both";
     const maxDepth = options.maxDepth ?? 3;
     if (!Number.isInteger(maxDepth) || maxDepth < 0)
         throw new TypeError("Relationship context maxDepth must be non-negative");
     const seen = new Set([root]);
-    const queue = [{ id: root, distance: 0 }];
+    const queue = [
+        { id: root, distance: 0 },
+    ];
     const rows = [];
     let inspectedEdges = 0;
     let depthTruncated = false;
@@ -59,22 +76,27 @@ function discoverNodes(graph, root, options) {
         const current = queue[index];
         if (current.distance >= maxDepth && depthTruncated)
             continue;
-        const adjacent = graph.adjacency(current.id, {
+        const adjacent = graph.neighborEdges(current.id, {
             direction,
             kinds: options.kinds,
             signal: options.signal,
         });
         inspectedEdges += adjacent.meta.inspectedEdges;
         if (current.distance >= maxDepth) {
-            if (adjacent.value.some((id) => !seen.has(id)))
+            if (adjacent.value.some((row) => !seen.has(row.id)))
                 depthTruncated = true;
             continue;
         }
-        for (const id of adjacent.value) {
+        for (const { id, edge } of adjacent.value) {
             if (seen.has(id))
                 continue;
             seen.add(id);
-            const row = { id, distance: current.distance + 1 };
+            const row = {
+                id,
+                distance: current.distance + 1,
+                via: current.id,
+                role: explainDirectEdge(edge, id, registry),
+            };
             rows.push(row);
             queue.push(row);
         }
@@ -87,19 +109,48 @@ function discoverNodes(graph, root, options) {
         depthTruncated,
     };
 }
+/** Count root-incident edges per semantic family under the active filters. */
+function summarizeDirectEdges(graph, root, registry, options) {
+    const directEdges = {
+        prerequisite: 0,
+        dependent: 0,
+        ancestor: 0,
+        descendant: 0,
+        provenance: 0,
+        related: 0,
+    };
+    const rows = graph.neighborEdges(root, {
+        direction: options.direction ?? "both",
+        kinds: options.kinds,
+        signal: options.signal,
+    }).value;
+    for (const { id, edge } of rows)
+        directEdges[explainDirectEdge(edge, id, registry)] += 1;
+    return {
+        directEdges,
+        directTotal: rows.length,
+        rootEdges: rows.map(({ edge }) => edge),
+    };
+}
 function selectContextNodes(params) {
     const nodes = [];
     let usedTokens = params.initialTokens;
-    const rootEdges = params.graph.incidentEdges(params.rootId);
     for (const candidate of params.candidates) {
         if (nodes.length >= params.nodeLimit)
             break;
+        const direct = candidate.distance === 1
+            ? directReasons(params.rootEdges, params.rootId, candidate.id, params.registry)
+            : [];
         const node = {
             ...(params.details.get(candidate.id) ?? { id: candidate.id }),
             distance: candidate.distance,
-            reasons: candidate.distance === 1
-                ? directReasons(rootEdges, params.rootId, candidate.id, params.registry)
-                : [`reachable at depth ${candidate.distance}`],
+            role: direct.length > 0 ? primaryRole(direct) : candidate.role,
+            via: candidate.via,
+            reasons: direct.length > 0
+                ? direct
+                : [
+                    `${candidate.role} via ${candidate.via} (depth ${candidate.distance})`,
+                ],
         };
         const cost = estimateTokens(node);
         if (usedTokens + cost > params.tokenBudget)
@@ -112,9 +163,20 @@ function selectContextNodes(params) {
     return { nodes, usedTokens };
 }
 function selectContextEdges(params) {
+    const kinds = params.options.kinds
+        ? new Set(params.options.kinds.map((kind) => params.registry.require(kind).kind))
+        : undefined;
     const candidates = params.graph
         .edges()
-        .filter((edge) => params.included.has(edge.source) && params.included.has(edge.target));
+        .filter((edge) => {
+        if (!params.included.has(edge.source) ||
+            !params.included.has(edge.target))
+            return false;
+        if (kinds === undefined || kinds.has(edge.kind))
+            return true;
+        const inverse = params.registry.resolve(edge.kind)?.inverse;
+        return inverse !== undefined && kinds.has(inverse);
+    });
     const edges = [];
     let usedTokens = params.initialTokens;
     for (const edge of candidates) {
@@ -142,7 +204,8 @@ export function buildRelationshipContext(graph, rootId, details, options = {}) {
     };
     const { evidence: rootEvidence = [], ...root } = rootDetails;
     const evidence = [...rootEvidence];
-    const discovery = discoverNodes(graph, rootId, options);
+    const discovery = discoverNodes(graph, rootId, registry, options);
+    const { rootEdges, ...directSummary } = summarizeDirectEdges(graph, rootId, registry, options);
     const fingerprint = createQueryFingerprint("relationship-context", {
         rootId,
         direction: options.direction ?? "both",
@@ -157,7 +220,7 @@ export function buildRelationshipContext(graph, rootId, details, options = {}) {
     const nodeSelection = selectContextNodes({
         candidates,
         details: byId,
-        graph,
+        rootEdges,
         rootId,
         registry,
         nodeLimit,
@@ -169,6 +232,8 @@ export function buildRelationshipContext(graph, rootId, details, options = {}) {
     const edgeSelection = selectContextEdges({
         graph,
         included,
+        options,
+        registry,
         edgeLimit,
         tokenBudget,
         initialTokens: nodeSelection.usedTokens,
@@ -179,14 +244,28 @@ export function buildRelationshipContext(graph, rootId, details, options = {}) {
     const lastNode = nodes.at(-1);
     const omittedEdges = edgeSelection.candidateCount - edges.length;
     const truncated = discovery.depthTruncated || hasMoreNodes || omittedEdges > 0;
+    const summary = {
+        rootId,
+        ...(root.status === undefined ? {} : { rootStatus: root.status }),
+        ...directSummary,
+        discoveredNodes: discovery.rows.length,
+        returnedNodes: nodes.length,
+        returnedEdges: edges.length,
+        omittedNodes: discovery.rows.length - consumed,
+        omittedEdges,
+        evidenceCount: evidence.length,
+        hasMore: hasMoreNodes,
+    };
     return {
         root,
+        summary,
         nodes,
         edges,
         evidence,
         meta: {
             exact: true,
             truncated,
+            completeness: truncated ? "truncated" : "complete",
             nodeLimit,
             edgeLimit,
             tokenBudget,
@@ -204,4 +283,4 @@ export function buildRelationshipContext(graph, rootId, details, options = {}) {
     };
 }
 //# sourceMappingURL=relationship-context.js.map
-//# debugId=dfd47ca8-a68d-50e1-9aba-638d974a0027
+//# debugId=cf26c4d0-d60f-5ec5-858f-957ad719383e

package/dist/sdk/relationship-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-context.js","sources":["sdk/relationship-context.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/relationship-context\n *\n * Assembles one explainable, cursorable, token-bounded relationship context\n * packet for agents, custom tools, and presentation-layer adapters.\n */\nimport {\n  createQueryFingerprint,\n  encodeQueryCursor,\n  resolveQueryCursorStart,\n} from \"./pagination.js\";\nimport {\n  RelationshipGraph,\n  RelationshipKindRegistry,\n  createRelationshipKindRegistry,\n  type RelationshipEdge,\n  type RelationshipTraversalDirection,\n} from \"./relationships.js\";\n\n/** Caller-owned compact node details joined into graph context. */\nexport interface RelationshipContextNodeDetails {\n  /** Stable graph node identifier. */\n  id: string;\n  /** Optional display title. */\n  title?: string;\n  /** Optional lifecycle status. */\n  status?: string;\n  /** Optional evidence pointers such as files, tests, or history ids. */\n  evidence?: readonly string[];\n}\n\n/** One selected graph-context node with explainable inclusion. */\nexport interface RelationshipContextNode extends RelationshipContextNodeDetails {\n  /** Shortest bounded distance from the root. */\n  distance: number;\n  /** Concise deterministic reasons the node was selected. */\n  reasons: string[];\n}\n\n/** Controls for bounded graph-context assembly. */\nexport interface RelationshipContextOptions {\n  /** Traversal direction relative to each visited node. */\n  direction?: RelationshipTraversalDirection;\n  /** Optional registered kind filter. */\n  kinds?: readonly string[];\n  /** Maximum traversal depth. */\n  maxDepth?: number;\n  /** Maximum nodes returned in this page. */\n  nodeLimit?: number;\n  /** Maximum edges returned in this page. */\n  edgeLimit?: number;\n  /** Maximum estimated output tokens charged to rows and edges. */\n  tokenBudget?: number;\n  /** Opaque continuation from an equivalent query. */\n  cursor?: string;\n  /** Registry used to explain custom relationship semantics. */\n  registry?: RelationshipKindRegistry;\n  /** Abort signal checked during traversal. */\n  signal?: AbortSignal;\n}\n\n/** Explainable graph context packet. */\nexport interface RelationshipContextResult {\n  /** Root node details. */\n  root: RelationshipContextNodeDetails;\n  /** Bounded related-node page. */\n  nodes: RelationshipContextNode[];\n  /** Bounded edges whose endpoints are present in the packet. */\n  edges: RelationshipEdge[];\n  /** Root evidence pointers promoted for immediate consumption. */\n  evidence: string[];\n  /** Completeness, continuation, and cost envelope. */\n  meta: {\n    exact: true;\n    truncated: boolean;\n    nodeLimit: number;\n    edgeLimit: number;\n    tokenBudget: number;\n    usedTokens: number;\n    visitedNodes: number;\n    inspectedEdges: number;\n    omittedNodes: number;\n    omittedEdges: number;\n    nextCursor?: string;\n  };\n}\n\ninterface DiscoveredNode {\n  id: string;\n  distance: number;\n}\n\nconst tokenEncoder = new TextEncoder();\n\nfunction positiveInteger(\n  value: number | undefined,\n  fallback: number,\n  field: string,\n): number {\n  const resolved = value ?? fallback;\n  if (!Number.isInteger(resolved) || resolved < 1)\n    throw new TypeError(`Relationship context ${field} must be positive`);\n  return resolved;\n}\n\nfunction estimateTokens(value: unknown): number {\n  return Math.max(\n    1,\n    Math.ceil(tokenEncoder.encode(JSON.stringify(value)).byteLength / 4),\n  );\n}\n\nfunction explainDirectEdge(\n  edge: RelationshipEdge,\n  root: string,\n  node: string,\n  registry: RelationshipKindRegistry,\n): string {\n  const definition = registry.require(edge.kind);\n  if (definition.ordering) {\n    // Legacy and JSON-parsed definitions may predate explicit precedence.\n    const sourceFirst =\n      (definition.precedence ?? \"source_before_target\") ===\n      \"source_before_target\";\n    const before = sourceFirst ? edge.source : edge.target;\n    return node === before ? \"prerequisite\" : \"dependent\";\n  }\n  if (definition.hierarchy) {\n    // Legacy and JSON-parsed definitions may predate explicit hierarchy direction.\n    const sourceIsParent =\n      (definition.hierarchyDirection ?? \"source_parent\") === \"source_parent\";\n    const parent = sourceIsParent ? edge.source : edge.target;\n    return node === parent ? \"ancestor\" : \"descendant\";\n  }\n  if (edge.kind === \"discovered_from\" || edge.kind === \"incident_from\")\n    return \"provenance\";\n  return \"related\";\n}\n\nfunction directReasons(\n  rootEdges: readonly RelationshipEdge[],\n  root: string,\n  node: string,\n  registry: RelationshipKindRegistry,\n): string[] {\n  const reasons = rootEdges\n    .filter(\n      (edge) =>\n        (edge.source === root && edge.target === node) ||\n        (edge.target === root && edge.source === node),\n    )\n    .map((edge) => explainDirectEdge(edge, root, node, registry));\n  return [...new Set(reasons)].sort();\n}\n\nfunction discoverNodes(\n  graph: RelationshipGraph,\n  root: string,\n  options: RelationshipContextOptions,\n): {\n  rows: DiscoveredNode[];\n  visitedNodes: number;\n  inspectedEdges: number;\n  depthTruncated: boolean;\n} {\n  const direction = options.direction ?? \"both\";\n  const maxDepth = options.maxDepth ?? 3;\n  if (!Number.isInteger(maxDepth) || maxDepth < 0)\n    throw new TypeError(\"Relationship context maxDepth must be non-negative\");\n  const seen = new Set([root]);\n  const queue = [{ id: root, distance: 0 }];\n  const rows: DiscoveredNode[] = [];\n  let inspectedEdges = 0;\n  let depthTruncated = false;\n  for (let index = 0; index < queue.length; index += 1) {\n    options.signal?.throwIfAborted();\n    const current = queue[index]!;\n    if (current.distance >= maxDepth && depthTruncated) continue;\n    const adjacent = graph.adjacency(current.id, {\n      direction,\n      kinds: options.kinds,\n      signal: options.signal,\n    });\n    inspectedEdges += adjacent.meta.inspectedEdges;\n    if (current.distance >= maxDepth) {\n      if (adjacent.value.some((id) => !seen.has(id))) depthTruncated = true;\n      continue;\n    }\n    for (const id of adjacent.value) {\n      if (seen.has(id)) continue;\n      seen.add(id);\n      const row = { id, distance: current.distance + 1 };\n      rows.push(row);\n      queue.push(row);\n    }\n  }\n  rows.sort(\n    (left, right) =>\n      left.distance - right.distance || left.id.localeCompare(right.id),\n  );\n  return {\n    rows,\n    visitedNodes: queue.length,\n    inspectedEdges,\n    depthTruncated,\n  };\n}\n\nfunction selectContextNodes(params: {\n  candidates: readonly DiscoveredNode[];\n  details: ReadonlyMap<string, RelationshipContextNodeDetails>;\n  graph: RelationshipGraph;\n  rootId: string;\n  registry: RelationshipKindRegistry;\n  nodeLimit: number;\n  tokenBudget: number;\n  initialTokens: number;\n}): { nodes: RelationshipContextNode[]; usedTokens: number } {\n  const nodes: RelationshipContextNode[] = [];\n  let usedTokens = params.initialTokens;\n  const rootEdges = params.graph.incidentEdges(params.rootId);\n  for (const candidate of params.candidates) {\n    if (nodes.length >= params.nodeLimit) break;\n    const node: RelationshipContextNode = {\n      ...(params.details.get(candidate.id) ?? { id: candidate.id }),\n      distance: candidate.distance,\n      reasons:\n        candidate.distance === 1\n          ? directReasons(\n              rootEdges,\n              params.rootId,\n              candidate.id,\n              params.registry,\n            )\n          : [`reachable at depth ${candidate.distance}`],\n    };\n    const cost = estimateTokens(node);\n    if (usedTokens + cost > params.tokenBudget) break;\n    nodes.push(node);\n    usedTokens += cost;\n  }\n  if (params.candidates.length > 0 && nodes.length === 0)\n    throw new TypeError(\"Relationship context tokenBudget cannot fit one node\");\n  return { nodes, usedTokens };\n}\n\nfunction selectContextEdges(params: {\n  graph: RelationshipGraph;\n  included: ReadonlySet<string>;\n  edgeLimit: number;\n  tokenBudget: number;\n  initialTokens: number;\n}): {\n  edges: RelationshipEdge[];\n  usedTokens: number;\n  candidateCount: number;\n} {\n  const candidates = params.graph\n    .edges()\n    .filter(\n      (edge) =>\n        params.included.has(edge.source) && params.included.has(edge.target),\n    );\n  const edges: RelationshipEdge[] = [];\n  let usedTokens = params.initialTokens;\n  for (const edge of candidates) {\n    if (edges.length >= params.edgeLimit) break;\n    const cost = estimateTokens(edge);\n    if (usedTokens + cost > params.tokenBudget) break;\n    edges.push(edge);\n    usedTokens += cost;\n  }\n  return { edges, usedTokens, candidateCount: candidates.length };\n}\n\n/** Build one deterministic bounded graph-context packet with continuation. */\nexport function buildRelationshipContext(\n  graph: RelationshipGraph,\n  rootId: string,\n  details: readonly RelationshipContextNodeDetails[],\n  options: RelationshipContextOptions = {},\n): RelationshipContextResult {\n  if (!graph.nodes().includes(rootId))\n    throw new TypeError(`Relationship node not found: ${rootId}`);\n  const nodeLimit = positiveInteger(options.nodeLimit, 20, \"nodeLimit\");\n  const edgeLimit = positiveInteger(options.edgeLimit, 40, \"edgeLimit\");\n  const tokenBudget = positiveInteger(options.tokenBudget, 1200, \"tokenBudget\");\n  const registry = options.registry ?? createRelationshipKindRegistry();\n  const byId = new Map(details.map((detail) => [detail.id, detail]));\n  const rootDetails: RelationshipContextNodeDetails = byId.get(rootId) ?? {\n    id: rootId,\n  };\n  const { evidence: rootEvidence = [], ...root } = rootDetails;\n  const evidence = [...rootEvidence];\n  const discovery = discoverNodes(graph, rootId, options);\n  const fingerprint = createQueryFingerprint(\"relationship-context\", {\n    rootId,\n    direction: options.direction ?? \"both\",\n    kinds: [...(options.kinds ?? [])].sort(),\n    maxDepth: options.maxDepth ?? 3,\n  });\n  const pageStart = resolveQueryCursorStart(\n    discovery.rows,\n    options.cursor,\n    fingerprint,\n    ({ id }) => id,\n  );\n  const candidates = discovery.rows.slice(pageStart);\n  const initialTokens = estimateTokens(root) + estimateTokens(evidence);\n  if (initialTokens > tokenBudget)\n    throw new TypeError(\n      \"Relationship context tokenBudget cannot fit root and evidence\",\n    );\n  const nodeSelection = selectContextNodes({\n    candidates,\n    details: byId,\n    graph,\n    rootId,\n    registry,\n    nodeLimit,\n    tokenBudget,\n    initialTokens,\n  });\n  const { nodes } = nodeSelection;\n\n  const included = new Set([rootId, ...nodes.map(({ id }) => id)]);\n  const edgeSelection = selectContextEdges({\n    graph,\n    included,\n    edgeLimit,\n    tokenBudget,\n    initialTokens: nodeSelection.usedTokens,\n  });\n  const { edges, usedTokens } = edgeSelection;\n\n  const consumed = pageStart + nodes.length;\n  const hasMoreNodes = consumed < discovery.rows.length;\n  const lastNode = nodes.at(-1);\n  const omittedEdges = edgeSelection.candidateCount - edges.length;\n  const truncated =\n    discovery.depthTruncated || hasMoreNodes || omittedEdges > 0;\n  return {\n    root,\n    nodes,\n    edges,\n    evidence,\n    meta: {\n      exact: true,\n      truncated,\n      nodeLimit,\n      edgeLimit,\n      tokenBudget,\n      usedTokens,\n      visitedNodes: discovery.visitedNodes,\n      inspectedEdges: discovery.inspectedEdges,\n      omittedNodes: discovery.rows.length - consumed,\n      omittedEdges,\n      ...(hasMoreNodes && lastNode\n        ? {\n            nextCursor: encodeQueryCursor(\n              fingerprint,\n              lastNode.id,\n              consumed - 1,\n            ),\n          }\n        : {}),\n    },\n  };\n}\n"],"names":[],"mappings":"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","debugId":"dfd47ca8-a68d-50e1-9aba-638d974a0027"}
+{"version":3,"file":"relationship-context.js","sources":["sdk/relationship-context.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/relationship-context\n *\n * Assembles one explainable, cursorable, token-bounded relationship context\n * packet for agents, custom tools, and presentation-layer adapters.\n */\nimport {\n  createQueryFingerprint,\n  encodeQueryCursor,\n  resolveQueryCursorStart,\n} from \"./pagination.js\";\nimport {\n  RelationshipGraph,\n  RelationshipKindRegistry,\n  createRelationshipKindRegistry,\n  type RelationshipEdge,\n  type RelationshipTraversalDirection,\n} from \"./relationships.js\";\n\n/** Semantic family explaining why a node or edge participates in graph context. */\nexport type RelationshipContextRole =\n  | \"prerequisite\"\n  | \"dependent\"\n  | \"ancestor\"\n  | \"descendant\"\n  | \"provenance\"\n  | \"related\";\n\n/**\n * Completeness marker for one graph-context packet.\n *\n * The exact in-memory kernel only produces \"complete\" and \"truncated\" today;\n * the remaining values are reserved so index-backed, sampled, or policy-redacted\n * providers can report their result quality through the same contract.\n */\nexport type RelationshipContextCompleteness =\n  | \"complete\"\n  | \"truncated\"\n  | \"sampled\"\n  | \"approximate\"\n  | \"stale_index\"\n  | \"redacted\";\n\n/** Caller-owned compact node details joined into graph context. */\nexport interface RelationshipContextNodeDetails {\n  /** Stable graph node identifier. */\n  id: string;\n  /** Optional display title. */\n  title?: string;\n  /** Optional lifecycle status. */\n  status?: string;\n  /** Optional evidence pointers such as files, tests, or history ids. */\n  evidence?: readonly string[];\n}\n\n/** One selected graph-context node with explainable inclusion. */\nexport interface RelationshipContextNode extends RelationshipContextNodeDetails {\n  /** Shortest bounded distance from the root. */\n  distance: number;\n  /** Semantic family of this node relative to its discovery counterpart. */\n  role: RelationshipContextRole;\n  /** Node through which bounded traversal first discovered this node. */\n  via: string;\n  /** Concise deterministic reasons the node was selected. */\n  reasons: string[];\n}\n\n/** Counts-first packet overview served before any row payload. */\nexport interface RelationshipContextSummary {\n  /** Root node identifier. */\n  rootId: string;\n  /** Root lifecycle status when the caller supplied node details. */\n  rootStatus?: string;\n  /** Root-incident edge counts per semantic family under the active filters. */\n  directEdges: Record<RelationshipContextRole, number>;\n  /** Total root-incident edges under the active filters. */\n  directTotal: number;\n  /** Nodes discovered by the bounded traversal, excluding the root. */\n  discoveredNodes: number;\n  /** Nodes returned in this page. */\n  returnedNodes: number;\n  /** Edges returned in this page. */\n  returnedEdges: number;\n  /** Discovered nodes omitted by pagination, node, or token bounds. */\n  omittedNodes: number;\n  /** Qualifying edges omitted by edge or token bounds. */\n  omittedEdges: number;\n  /** Root evidence pointers promoted into the packet. */\n  evidenceCount: number;\n  /** Whether a continuation cursor is available. */\n  hasMore: boolean;\n}\n\n/** Controls for bounded graph-context assembly. */\nexport interface RelationshipContextOptions {\n  /** Traversal direction relative to each visited node. */\n  direction?: RelationshipTraversalDirection;\n  /** Optional registered kind filter. */\n  kinds?: readonly string[];\n  /** Maximum traversal depth. */\n  maxDepth?: number;\n  /** Maximum nodes returned in this page. */\n  nodeLimit?: number;\n  /** Maximum edges returned in this page. */\n  edgeLimit?: number;\n  /** Maximum estimated output tokens charged to rows and edges. */\n  tokenBudget?: number;\n  /** Opaque continuation from an equivalent query. */\n  cursor?: string;\n  /** Registry used to explain custom relationship semantics. */\n  registry?: RelationshipKindRegistry;\n  /** Abort signal checked during traversal. */\n  signal?: AbortSignal;\n}\n\n/** Explainable graph context packet. */\nexport interface RelationshipContextResult {\n  /** Root node details. */\n  root: RelationshipContextNodeDetails;\n  /** Counts-first overview of the packet. */\n  summary: RelationshipContextSummary;\n  /** Bounded related-node page. */\n  nodes: RelationshipContextNode[];\n  /** Bounded edges whose endpoints are present in the packet. */\n  edges: RelationshipEdge[];\n  /** Root evidence pointers promoted for immediate consumption. */\n  evidence: string[];\n  /** Completeness, continuation, and cost envelope. */\n  meta: {\n    exact: true;\n    truncated: boolean;\n    completeness: RelationshipContextCompleteness;\n    nodeLimit: number;\n    edgeLimit: number;\n    tokenBudget: number;\n    usedTokens: number;\n    visitedNodes: number;\n    inspectedEdges: number;\n    omittedNodes: number;\n    omittedEdges: number;\n    nextCursor?: string;\n  };\n}\n\ninterface DiscoveredNode {\n  id: string;\n  distance: number;\n  via: string;\n  role: RelationshipContextRole;\n}\n\n/** Deterministic priority used when one node matches several semantic families. */\nconst RELATIONSHIP_CONTEXT_ROLE_PRIORITY: readonly RelationshipContextRole[] = [\n  \"prerequisite\",\n  \"dependent\",\n  \"ancestor\",\n  \"descendant\",\n  \"provenance\",\n  \"related\",\n];\n\nconst tokenEncoder = new TextEncoder();\n\nfunction positiveInteger(\n  value: number | undefined,\n  fallback: number,\n  field: string,\n): number {\n  const resolved = value ?? fallback;\n  if (!Number.isInteger(resolved) || resolved < 1)\n    throw new TypeError(`Relationship context ${field} must be positive`);\n  return resolved;\n}\n\nfunction estimateTokens(value: unknown): number {\n  return Math.max(\n    1,\n    Math.ceil(tokenEncoder.encode(JSON.stringify(value)).byteLength / 4),\n  );\n}\n\nfunction explainDirectEdge(\n  edge: RelationshipEdge,\n  node: string,\n  registry: RelationshipKindRegistry,\n): RelationshipContextRole {\n  const definition = registry.resolve(edge.kind);\n  if (definition?.ordering) {\n    // Legacy and JSON-parsed definitions may predate explicit precedence.\n    const sourceFirst =\n      (definition.precedence ?? \"source_before_target\") ===\n      \"source_before_target\";\n    const before = sourceFirst ? edge.source : edge.target;\n    return node === before ? \"prerequisite\" : \"dependent\";\n  }\n  if (definition?.hierarchy) {\n    // Legacy and JSON-parsed definitions may predate explicit hierarchy direction.\n    const sourceIsParent =\n      (definition.hierarchyDirection ?? \"source_parent\") === \"source_parent\";\n    const parent = sourceIsParent ? edge.source : edge.target;\n    return node === parent ? \"ancestor\" : \"descendant\";\n  }\n  if (edge.kind === \"discovered_from\" || edge.kind === \"incident_from\")\n    return \"provenance\";\n  return \"related\";\n}\n\nfunction directReasons(\n  rootEdges: readonly RelationshipEdge[],\n  root: string,\n  node: string,\n  registry: RelationshipKindRegistry,\n): RelationshipContextRole[] {\n  const reasons = rootEdges\n    .filter(\n      (edge) =>\n        (edge.source === root && edge.target === node) ||\n        (edge.target === root && edge.source === node),\n    )\n    .map((edge) => explainDirectEdge(edge, node, registry));\n  return [...new Set(reasons)].sort();\n}\n\n/** Pick the deterministic primary family when a node matches several. */\nfunction primaryRole(\n  roles: readonly RelationshipContextRole[],\n): RelationshipContextRole {\n  // Callers only pass non-empty classification sets drawn from the fixed\n  // family list, so a priority match always exists.\n  return RELATIONSHIP_CONTEXT_ROLE_PRIORITY.find((role) =>\n    roles.includes(role),\n  )!;\n}\n\nfunction discoverNodes(\n  graph: RelationshipGraph,\n  root: string,\n  registry: RelationshipKindRegistry,\n  options: RelationshipContextOptions,\n): {\n  rows: DiscoveredNode[];\n  visitedNodes: number;\n  inspectedEdges: number;\n  depthTruncated: boolean;\n} {\n  const direction = options.direction ?? \"both\";\n  const maxDepth = options.maxDepth ?? 3;\n  if (!Number.isInteger(maxDepth) || maxDepth < 0)\n    throw new TypeError(\"Relationship context maxDepth must be non-negative\");\n  const seen = new Set([root]);\n  const queue: { id: string; distance: number }[] = [\n    { id: root, distance: 0 },\n  ];\n  const rows: DiscoveredNode[] = [];\n  let inspectedEdges = 0;\n  let depthTruncated = false;\n  for (let index = 0; index < queue.length; index += 1) {\n    options.signal?.throwIfAborted();\n    const current = queue[index]!;\n    if (current.distance >= maxDepth && depthTruncated) continue;\n    const adjacent = graph.neighborEdges(current.id, {\n      direction,\n      kinds: options.kinds,\n      signal: options.signal,\n    });\n    inspectedEdges += adjacent.meta.inspectedEdges;\n    if (current.distance >= maxDepth) {\n      if (adjacent.value.some((row) => !seen.has(row.id))) depthTruncated = true;\n      continue;\n    }\n    for (const { id, edge } of adjacent.value) {\n      if (seen.has(id)) continue;\n      seen.add(id);\n      const row = {\n        id,\n        distance: current.distance + 1,\n        via: current.id,\n        role: explainDirectEdge(edge, id, registry),\n      };\n      rows.push(row);\n      queue.push(row);\n    }\n  }\n  rows.sort(\n    (left, right) =>\n      left.distance - right.distance || left.id.localeCompare(right.id),\n  );\n  return {\n    rows,\n    visitedNodes: queue.length,\n    inspectedEdges,\n    depthTruncated,\n  };\n}\n\n/** Count root-incident edges per semantic family under the active filters. */\nfunction summarizeDirectEdges(\n  graph: RelationshipGraph,\n  root: string,\n  registry: RelationshipKindRegistry,\n  options: RelationshipContextOptions,\n): {\n  directEdges: Record<RelationshipContextRole, number>;\n  directTotal: number;\n  rootEdges: RelationshipEdge[];\n} {\n  const directEdges: Record<RelationshipContextRole, number> = {\n    prerequisite: 0,\n    dependent: 0,\n    ancestor: 0,\n    descendant: 0,\n    provenance: 0,\n    related: 0,\n  };\n  const rows = graph.neighborEdges(root, {\n    direction: options.direction ?? \"both\",\n    kinds: options.kinds,\n    signal: options.signal,\n  }).value;\n  for (const { id, edge } of rows)\n    directEdges[explainDirectEdge(edge, id, registry)] += 1;\n  return {\n    directEdges,\n    directTotal: rows.length,\n    rootEdges: rows.map(({ edge }) => edge),\n  };\n}\n\nfunction selectContextNodes(params: {\n  candidates: readonly DiscoveredNode[];\n  details: ReadonlyMap<string, RelationshipContextNodeDetails>;\n  rootEdges: readonly RelationshipEdge[];\n  rootId: string;\n  registry: RelationshipKindRegistry;\n  nodeLimit: number;\n  tokenBudget: number;\n  initialTokens: number;\n}): { nodes: RelationshipContextNode[]; usedTokens: number } {\n  const nodes: RelationshipContextNode[] = [];\n  let usedTokens = params.initialTokens;\n  for (const candidate of params.candidates) {\n    if (nodes.length >= params.nodeLimit) break;\n    const direct =\n      candidate.distance === 1\n        ? directReasons(\n            params.rootEdges,\n            params.rootId,\n            candidate.id,\n            params.registry,\n          )\n        : [];\n    const node: RelationshipContextNode = {\n      ...(params.details.get(candidate.id) ?? { id: candidate.id }),\n      distance: candidate.distance,\n      role: direct.length > 0 ? primaryRole(direct) : candidate.role,\n      via: candidate.via,\n      reasons:\n        direct.length > 0\n          ? direct\n          : [\n              `${candidate.role} via ${candidate.via} (depth ${candidate.distance})`,\n            ],\n    };\n    const cost = estimateTokens(node);\n    if (usedTokens + cost > params.tokenBudget) break;\n    nodes.push(node);\n    usedTokens += cost;\n  }\n  if (params.candidates.length > 0 && nodes.length === 0)\n    throw new TypeError(\"Relationship context tokenBudget cannot fit one node\");\n  return { nodes, usedTokens };\n}\n\nfunction selectContextEdges(params: {\n  graph: RelationshipGraph;\n  included: ReadonlySet<string>;\n  options: RelationshipContextOptions;\n  registry: RelationshipKindRegistry;\n  edgeLimit: number;\n  tokenBudget: number;\n  initialTokens: number;\n}): {\n  edges: RelationshipEdge[];\n  usedTokens: number;\n  candidateCount: number;\n} {\n  const kinds = params.options.kinds\n    ? new Set(\n        params.options.kinds.map((kind) => params.registry.require(kind).kind),\n      )\n    : undefined;\n  const candidates = params.graph\n    .edges()\n    .filter(\n      (edge) => {\n        if (\n          !params.included.has(edge.source) ||\n          !params.included.has(edge.target)\n        )\n          return false;\n        if (kinds === undefined || kinds.has(edge.kind)) return true;\n        const inverse = params.registry.resolve(edge.kind)?.inverse;\n        return inverse !== undefined && kinds.has(inverse);\n      },\n    );\n  const edges: RelationshipEdge[] = [];\n  let usedTokens = params.initialTokens;\n  for (const edge of candidates) {\n    if (edges.length >= params.edgeLimit) break;\n    const cost = estimateTokens(edge);\n    if (usedTokens + cost > params.tokenBudget) break;\n    edges.push(edge);\n    usedTokens += cost;\n  }\n  return { edges, usedTokens, candidateCount: candidates.length };\n}\n\n/** Build one deterministic bounded graph-context packet with continuation. */\nexport function buildRelationshipContext(\n  graph: RelationshipGraph,\n  rootId: string,\n  details: readonly RelationshipContextNodeDetails[],\n  options: RelationshipContextOptions = {},\n): RelationshipContextResult {\n  if (!graph.nodes().includes(rootId))\n    throw new TypeError(`Relationship node not found: ${rootId}`);\n  const nodeLimit = positiveInteger(options.nodeLimit, 20, \"nodeLimit\");\n  const edgeLimit = positiveInteger(options.edgeLimit, 40, \"edgeLimit\");\n  const tokenBudget = positiveInteger(options.tokenBudget, 1200, \"tokenBudget\");\n  const registry = options.registry ?? createRelationshipKindRegistry();\n  const byId = new Map(details.map((detail) => [detail.id, detail]));\n  const rootDetails: RelationshipContextNodeDetails = byId.get(rootId) ?? {\n    id: rootId,\n  };\n  const { evidence: rootEvidence = [], ...root } = rootDetails;\n  const evidence = [...rootEvidence];\n  const discovery = discoverNodes(graph, rootId, registry, options);\n  const { rootEdges, ...directSummary } = summarizeDirectEdges(\n    graph,\n    rootId,\n    registry,\n    options,\n  );\n  const fingerprint = createQueryFingerprint(\"relationship-context\", {\n    rootId,\n    direction: options.direction ?? \"both\",\n    kinds: [...(options.kinds ?? [])].sort(),\n    maxDepth: options.maxDepth ?? 3,\n  });\n  const pageStart = resolveQueryCursorStart(\n    discovery.rows,\n    options.cursor,\n    fingerprint,\n    ({ id }) => id,\n  );\n  const candidates = discovery.rows.slice(pageStart);\n  const initialTokens = estimateTokens(root) + estimateTokens(evidence);\n  if (initialTokens > tokenBudget)\n    throw new TypeError(\n      \"Relationship context tokenBudget cannot fit root and evidence\",\n    );\n  const nodeSelection = selectContextNodes({\n    candidates,\n    details: byId,\n    rootEdges,\n    rootId,\n    registry,\n    nodeLimit,\n    tokenBudget,\n    initialTokens,\n  });\n  const { nodes } = nodeSelection;\n\n  const included = new Set([rootId, ...nodes.map(({ id }) => id)]);\n  const edgeSelection = selectContextEdges({\n    graph,\n    included,\n    options,\n    registry,\n    edgeLimit,\n    tokenBudget,\n    initialTokens: nodeSelection.usedTokens,\n  });\n  const { edges, usedTokens } = edgeSelection;\n\n  const consumed = pageStart + nodes.length;\n  const hasMoreNodes = consumed < discovery.rows.length;\n  const lastNode = nodes.at(-1);\n  const omittedEdges = edgeSelection.candidateCount - edges.length;\n  const truncated =\n    discovery.depthTruncated || hasMoreNodes || omittedEdges > 0;\n  const summary: RelationshipContextSummary = {\n    rootId,\n    ...(root.status === undefined ? {} : { rootStatus: root.status }),\n    ...directSummary,\n    discoveredNodes: discovery.rows.length,\n    returnedNodes: nodes.length,\n    returnedEdges: edges.length,\n    omittedNodes: discovery.rows.length - consumed,\n    omittedEdges,\n    evidenceCount: evidence.length,\n    hasMore: hasMoreNodes,\n  };\n  return {\n    root,\n    summary,\n    nodes,\n    edges,\n    evidence,\n    meta: {\n      exact: true,\n      truncated,\n      completeness: truncated ? \"truncated\" : \"complete\",\n      nodeLimit,\n      edgeLimit,\n      tokenBudget,\n      usedTokens,\n      visitedNodes: discovery.visitedNodes,\n      inspectedEdges: discovery.inspectedEdges,\n      omittedNodes: discovery.rows.length - consumed,\n      omittedEdges,\n      ...(hasMoreNodes && lastNode\n        ? {\n            nextCursor: encodeQueryCursor(\n              fingerprint,\n              lastNode.id,\n              consumed - 1,\n            ),\n          }\n        : {}),\n    },\n  };\n}\n"],"names":[],"mappings":"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","debugId":"cf26c4d0-d60f-5ec5-858f-957ad719383e"}

package/dist/sdk/relationships.d.ts

@@ -94,6 +94,13 @@ export interface RelationshipQueryResult<T> {
     /** Explicit query work and truncation metadata. */
     meta: RelationshipQueryMeta;
 }
+/** One neighbor row pairing an adjacent node with the edge that connects it. */
+export interface RelationshipNeighborEdge {
+    /** Adjacent node identifier. */
+    id: string;
+    /** Edge connecting the queried node to this neighbor. */
+    edge: RelationshipEdge;
+}
 /** Induced subgraph returned by bounded traversal. */
 export interface RelationshipSubgraph {
     /** Deterministically ordered node identifiers. */
@@ -132,8 +139,14 @@ export declare class RelationshipGraph {
     incidentEdges(id: string): readonly RelationshipEdge[];
     /** Return the deterministic immutable node snapshot. */
     nodes(): readonly string[];
+    /** Report whether an identifier names an indexed node. */
+    hasNode(id: string): boolean;
+    /** Return the registry that interprets this graph's relationship kinds. */
+    registry(): RelationshipKindRegistry;
     /** Return one-hop adjacent node identifiers. */
     adjacency(id: string, options?: RelationshipQueryOptions): RelationshipQueryResult<string[]>;
+    /** Return deterministic one-hop neighbor rows paired with each connecting edge. */
+    neighborEdges(id: string, options?: RelationshipQueryOptions): RelationshipQueryResult<RelationshipNeighborEdge[]>;
     /** Return bounded transitive closure in breadth-first discovery order. */
     closure(id: string, options?: RelationshipQueryOptions): RelationshipQueryResult<string[]>;
     /** Return a deterministic shortest path, or an empty array when disconnected. */

package/dist/sdk/relationships.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f5e9e0a6-4550-5e55-9fef-ee54ec06a495")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="00588d49-70aa-59c8-bc85-d0bbd5e77d4b")}catch(e){}}();
 const BUILTIN_RELATIONSHIP_KINDS = [
     {
         kind: "blocked_by",
@@ -368,6 +368,14 @@ export class RelationshipGraph {
     nodes() {
         return this.#nodeSnapshot;
     }
+    /** Report whether an identifier names an indexed node. */
+    hasNode(id) {
+        return this.#nodes.has(id);
+    }
+    /** Return the registry that interprets this graph's relationship kinds. */
+    registry() {
+        return this.#registry;
+    }
     #assertNode(id) {
         if (!this.#nodes.has(id))
             throw new TypeError(`Relationship node not found: ${id}`);
@@ -414,6 +422,26 @@ export class RelationshipGraph {
             },
         };
     }
+    /** Return deterministic one-hop neighbor rows paired with each connecting edge. */
+    neighborEdges(id, options = {}) {
+        this.#assertNode(id);
+        options.signal?.throwIfAborted();
+        const kinds = options.kinds
+            ? new Set(options.kinds.map((kind) => this.#registry.require(kind).kind))
+            : undefined;
+        const rows = this.#neighbors(id, options.direction ?? "outgoing", kinds);
+        const limit = options.limit ?? Number.POSITIVE_INFINITY;
+        const value = rows.slice(0, limit);
+        return {
+            value,
+            meta: {
+                visitedNodes: 1,
+                inspectedEdges: rows.length,
+                truncated: value.length < rows.length,
+                nextCursor: value.at(-1)?.id,
+            },
+        };
+    }
     /** Return bounded transitive closure in breadth-first discovery order. */
     closure(id, options = {}) {
         this.#assertNode(id);
@@ -548,4 +576,4 @@ export function dependencyToRelationship(source, dependency, registry = defaultR
     };
 }
 //# sourceMappingURL=relationships.js.map
-//# debugId=f5e9e0a6-4550-5e55-9fef-ee54ec06a495
+//# debugId=00588d49-70aa-59c8-bc85-d0bbd5e77d4b