@unbrained/pm-cli 2026.7.14 → 2026.7.16

package/dist/sdk/relationship-context.js

@@ -0,0 +1,207 @@
+/**
+ * @module sdk/relationship-context
+ *
+ * Assembles one explainable, cursorable, token-bounded relationship context
+ * 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){}}();
+import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, } from "./pagination.js";
+import { createRelationshipKindRegistry, } from "./relationships.js";
+const tokenEncoder = new TextEncoder();
+function positiveInteger(value, fallback, field) {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) || resolved < 1)
+        throw new TypeError(`Relationship context ${field} must be positive`);
+    return resolved;
+}
+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) {
+        // 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) {
+        // 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;
+        return node === parent ? "ancestor" : "descendant";
+    }
+    if (edge.kind === "discovered_from" || edge.kind === "incident_from")
+        return "provenance";
+    return "related";
+}
+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));
+    return [...new Set(reasons)].sort();
+}
+function discoverNodes(graph, root, 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 rows = [];
+    let inspectedEdges = 0;
+    let depthTruncated = false;
+    for (let index = 0; index < queue.length; index += 1) {
+        options.signal?.throwIfAborted();
+        const current = queue[index];
+        if (current.distance >= maxDepth && depthTruncated)
+            continue;
+        const adjacent = graph.adjacency(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)))
+                depthTruncated = true;
+            continue;
+        }
+        for (const id of adjacent.value) {
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const row = { id, distance: current.distance + 1 };
+            rows.push(row);
+            queue.push(row);
+        }
+    }
+    rows.sort((left, right) => left.distance - right.distance || left.id.localeCompare(right.id));
+    return {
+        rows,
+        visitedNodes: queue.length,
+        inspectedEdges,
+        depthTruncated,
+    };
+}
+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 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}`],
+        };
+        const cost = estimateTokens(node);
+        if (usedTokens + cost > params.tokenBudget)
+            break;
+        nodes.push(node);
+        usedTokens += cost;
+    }
+    if (params.candidates.length > 0 && nodes.length === 0)
+        throw new TypeError("Relationship context tokenBudget cannot fit one node");
+    return { nodes, usedTokens };
+}
+function selectContextEdges(params) {
+    const candidates = params.graph
+        .edges()
+        .filter((edge) => params.included.has(edge.source) && params.included.has(edge.target));
+    const edges = [];
+    let usedTokens = params.initialTokens;
+    for (const edge of candidates) {
+        if (edges.length >= params.edgeLimit)
+            break;
+        const cost = estimateTokens(edge);
+        if (usedTokens + cost > params.tokenBudget)
+            break;
+        edges.push(edge);
+        usedTokens += cost;
+    }
+    return { edges, usedTokens, candidateCount: candidates.length };
+}
+/** Build one deterministic bounded graph-context packet with continuation. */
+export function buildRelationshipContext(graph, rootId, details, options = {}) {
+    if (!graph.nodes().includes(rootId))
+        throw new TypeError(`Relationship node not found: ${rootId}`);
+    const nodeLimit = positiveInteger(options.nodeLimit, 20, "nodeLimit");
+    const edgeLimit = positiveInteger(options.edgeLimit, 40, "edgeLimit");
+    const tokenBudget = positiveInteger(options.tokenBudget, 1200, "tokenBudget");
+    const registry = options.registry ?? createRelationshipKindRegistry();
+    const byId = new Map(details.map((detail) => [detail.id, detail]));
+    const rootDetails = byId.get(rootId) ?? {
+        id: rootId,
+    };
+    const { evidence: rootEvidence = [], ...root } = rootDetails;
+    const evidence = [...rootEvidence];
+    const discovery = discoverNodes(graph, rootId, options);
+    const fingerprint = createQueryFingerprint("relationship-context", {
+        rootId,
+        direction: options.direction ?? "both",
+        kinds: [...(options.kinds ?? [])].sort(),
+        maxDepth: options.maxDepth ?? 3,
+    });
+    const pageStart = resolveQueryCursorStart(discovery.rows, options.cursor, fingerprint, ({ id }) => id);
+    const candidates = discovery.rows.slice(pageStart);
+    const initialTokens = estimateTokens(root) + estimateTokens(evidence);
+    if (initialTokens > tokenBudget)
+        throw new TypeError("Relationship context tokenBudget cannot fit root and evidence");
+    const nodeSelection = selectContextNodes({
+        candidates,
+        details: byId,
+        graph,
+        rootId,
+        registry,
+        nodeLimit,
+        tokenBudget,
+        initialTokens,
+    });
+    const { nodes } = nodeSelection;
+    const included = new Set([rootId, ...nodes.map(({ id }) => id)]);
+    const edgeSelection = selectContextEdges({
+        graph,
+        included,
+        edgeLimit,
+        tokenBudget,
+        initialTokens: nodeSelection.usedTokens,
+    });
+    const { edges, usedTokens } = edgeSelection;
+    const consumed = pageStart + nodes.length;
+    const hasMoreNodes = consumed < discovery.rows.length;
+    const lastNode = nodes.at(-1);
+    const omittedEdges = edgeSelection.candidateCount - edges.length;
+    const truncated = discovery.depthTruncated || hasMoreNodes || omittedEdges > 0;
+    return {
+        root,
+        nodes,
+        edges,
+        evidence,
+        meta: {
+            exact: true,
+            truncated,
+            nodeLimit,
+            edgeLimit,
+            tokenBudget,
+            usedTokens,
+            visitedNodes: discovery.visitedNodes,
+            inspectedEdges: discovery.inspectedEdges,
+            omittedNodes: discovery.rows.length - consumed,
+            omittedEdges,
+            ...(hasMoreNodes && lastNode
+                ? {
+                    nextCursor: encodeQueryCursor(fingerprint, lastNode.id, consumed - 1),
+                }
+                : {}),
+        },
+    };
+}
+//# sourceMappingURL=relationship-context.js.map
+//# debugId=dfd47ca8-a68d-50e1-9aba-638d974a0027

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

@@ -0,0 +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":"AAAA;;;;;GAKG;;;AACH,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,8BAA8B,GAG/B,MAAM,oBAAoB,CAAC;AA2E5B,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAC;AAEvC,SAAS,eAAe,CACtB,KAAyB,EACzB,QAAgB,EAChB,KAAa;IAEb,MAAM,QAAQ,GAAG,KAAK,IAAI,QAAQ,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC;QAC7C,MAAM,IAAI,SAAS,CAAC,wBAAwB,KAAK,mBAAmB,CAAC,CAAC;IACxE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,IAAI,CAAC,GAAG,CACb,CAAC,EACD,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,CACrE,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CACxB,IAAsB,EACtB,IAAY,EACZ,IAAY,EACZ,QAAkC;IAElC,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC;QACxB,sEAAsE;QACtE,MAAM,WAAW,GACf,CAAC,UAAU,CAAC,UAAU,IAAI,sBAAsB,CAAC;YACjD,sBAAsB,CAAC;QACzB,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;QACvD,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC;IACxD,CAAC;IACD,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;QACzB,+EAA+E;QAC/E,MAAM,cAAc,GAClB,CAAC,UAAU,CAAC,kBAAkB,IAAI,eAAe,CAAC,KAAK,eAAe,CAAC;QACzE,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;QAC1D,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC;IACrD,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB,IAAI,IAAI,CAAC,IAAI,KAAK,eAAe;QAClE,OAAO,YAAY,CAAC;IACtB,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,aAAa,CACpB,SAAsC,EACtC,IAAY,EACZ,IAAY,EACZ,QAAkC;IAElC,MAAM,OAAO,GAAG,SAAS;SACtB,MAAM,CACL,CAAC,IAAI,EAAE,EAAE,CACP,CAAC,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC;QAC9C,CAAC,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,CACjD;SACA,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChE,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACtC,CAAC;AAED,SAAS,aAAa,CACpB,KAAwB,EACxB,IAAY,EACZ,OAAmC;IAOnC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC;QAC7C,MAAM,IAAI,SAAS,CAAC,oDAAoD,CAAC,CAAC;IAC5E,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAqB,EAAE,CAAC;IAClC,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACrD,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAE,CAAC;QAC9B,IAAI,OAAO,CAAC,QAAQ,IAAI,QAAQ,IAAI,cAAc;YAAE,SAAS;QAC7D,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE;YAC3C,SAAS;YACT,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QACH,cAAc,IAAI,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC;QAC/C,IAAI,OAAO,CAAC,QAAQ,IAAI,QAAQ,EAAE,CAAC;YACjC,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAAE,cAAc,GAAG,IAAI,CAAC;YACtE,SAAS;QACX,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,SAAS;YAC3B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACb,MAAM,GAAG,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,IAAI,CAAC,IAAI,CACP,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACd,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CACpE,CAAC;IACF,OAAO;QACL,IAAI;QACJ,YAAY,EAAE,KAAK,CAAC,MAAM;QAC1B,cAAc;QACd,cAAc;KACf,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,MAS3B;IACC,MAAM,KAAK,GAA8B,EAAE,CAAC;IAC5C,IAAI,UAAU,GAAG,MAAM,CAAC,aAAa,CAAC;IACtC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5D,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAC1C,IAAI,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,SAAS;YAAE,MAAM;QAC5C,MAAM,IAAI,GAA4B;YACpC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC;YAC7D,QAAQ,EAAE,SAAS,CAAC,QAAQ;YAC5B,OAAO,EACL,SAAS,CAAC,QAAQ,KAAK,CAAC;gBACtB,CAAC,CAAC,aAAa,CACX,SAAS,EACT,MAAM,CAAC,MAAM,EACb,SAAS,CAAC,EAAE,EACZ,MAAM,CAAC,QAAQ,CAChB;gBACH,CAAC,CAAC,CAAC,sBAAsB,SAAS,CAAC,QAAQ,EAAE,CAAC;SACnD,CAAC;QACF,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,UAAU,GAAG,IAAI,GAAG,MAAM,CAAC,WAAW;YAAE,MAAM;QAClD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,UAAU,IAAI,IAAI,CAAC;IACrB,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QACpD,MAAM,IAAI,SAAS,CAAC,sDAAsD,CAAC,CAAC;IAC9E,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAC/B,CAAC;AAED,SAAS,kBAAkB,CAAC,MAM3B;IAKC,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK;SAC5B,KAAK,EAAE;SACP,MAAM,CACL,CAAC,IAAI,EAAE,EAAE,CACP,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CACvE,CAAC;IACJ,MAAM,KAAK,GAAuB,EAAE,CAAC;IACrC,IAAI,UAAU,GAAG,MAAM,CAAC,aAAa,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,SAAS;YAAE,MAAM;QAC5C,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,UAAU,GAAG,IAAI,GAAG,MAAM,CAAC,WAAW;YAAE,MAAM;QAClD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,UAAU,IAAI,IAAI,CAAC;IACrB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;AAClE,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,wBAAwB,CACtC,KAAwB,EACxB,MAAc,EACd,OAAkD,EAClD,UAAsC,EAAE;IAExC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC;QACjC,MAAM,IAAI,SAAS,CAAC,gCAAgC,MAAM,EAAE,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;IACtE,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;IAC9E,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,8BAA8B,EAAE,CAAC;IACtE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACnE,MAAM,WAAW,GAAmC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI;QACtE,EAAE,EAAE,MAAM;KACX,CAAC;IACF,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,WAAW,CAAC;IAC7D,MAAM,QAAQ,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC;IACnC,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,WAAW,GAAG,sBAAsB,CAAC,sBAAsB,EAAE;QACjE,MAAM;QACN,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,MAAM;QACtC,KAAK,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE;QACxC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC;KAChC,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,uBAAuB,CACvC,SAAS,CAAC,IAAI,EACd,OAAO,CAAC,MAAM,EACd,WAAW,EACX,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CACf,CAAC;IACF,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,aAAa,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACtE,IAAI,aAAa,GAAG,WAAW;QAC7B,MAAM,IAAI,SAAS,CACjB,+DAA+D,CAChE,CAAC;IACJ,MAAM,aAAa,GAAG,kBAAkB,CAAC;QACvC,UAAU;QACV,OAAO,EAAE,IAAI;QACb,KAAK;QACL,MAAM;QACN,QAAQ;QACR,SAAS;QACT,WAAW;QACX,aAAa;KACd,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,EAAE,GAAG,aAAa,CAAC;IAEhC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACjE,MAAM,aAAa,GAAG,kBAAkB,CAAC;QACvC,KAAK;QACL,QAAQ;QACR,SAAS;QACT,WAAW;QACX,aAAa,EAAE,aAAa,CAAC,UAAU;KACxC,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,aAAa,CAAC;IAE5C,MAAM,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1C,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;IACtD,MAAM,QAAQ,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,MAAM,YAAY,GAAG,aAAa,CAAC,cAAc,GAAG,KAAK,CAAC,MAAM,CAAC;IACjE,MAAM,SAAS,GACb,SAAS,CAAC,cAAc,IAAI,YAAY,IAAI,YAAY,GAAG,CAAC,CAAC;IAC/D,OAAO;QACL,IAAI;QACJ,KAAK;QACL,KAAK;QACL,QAAQ;QACR,IAAI,EAAE;YACJ,KAAK,EAAE,IAAI;YACX,SAAS;YACT,SAAS;YACT,SAAS;YACT,WAAW;YACX,UAAU;YACV,YAAY,EAAE,SAAS,CAAC,YAAY;YACpC,cAAc,EAAE,SAAS,CAAC,cAAc;YACxC,YAAY,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,GAAG,QAAQ;YAC9C,YAAY;YACZ,GAAG,CAAC,YAAY,IAAI,QAAQ;gBAC1B,CAAC,CAAC;oBACE,UAAU,EAAE,iBAAiB,CAC3B,WAAW,EACX,QAAQ,CAAC,EAAE,EACX,QAAQ,GAAG,CAAC,CACb;iBACF;gBACH,CAAC,CAAC,EAAE,CAAC;SACR;KACF,CAAC;AACJ,CAAC","debugId":"dfd47ca8-a68d-50e1-9aba-638d974a0027"}

package/dist/sdk/relationship-history.d.ts

@@ -0,0 +1,109 @@
+import { RelationshipGraph, RelationshipKindRegistry, type RelationshipEdge } from "./relationships.js";
+/** Mutation kinds retained in the immutable relationship event stream. */
+export type RelationshipEventAction = "add" | "remove" | "supersede";
+/** Caller-authored relationship mutation before its sequence is assigned. */
+export interface RelationshipEventInput {
+    /** Globally unique idempotency key for this event. */
+    eventId: string;
+    /** Stable logical relationship identifier across superseding events. */
+    relationshipId: string;
+    /** Append, remove, or replace the logical relationship. */
+    action: RelationshipEventAction;
+    /** Edge required for add and supersede actions. */
+    edge?: RelationshipEdge;
+    /** Attributable actor responsible for the mutation. */
+    author: string;
+    /** Valid event-time timestamp. */
+    timestamp: string;
+    /** Optional optimistic concurrency precondition. */
+    expectedVersion?: number;
+    /** Optional human-readable mutation rationale. */
+    reason?: string;
+}
+/** One immutable sequenced relationship mutation. */
+export interface RelationshipEvent extends Omit<RelationshipEventInput, "expectedVersion"> {
+    /** One-based append sequence assigned by the ledger. */
+    sequence: number;
+}
+/** Point-in-time materialized relationship view. */
+export interface RelationshipSnapshot {
+    /** Final event sequence included in this snapshot. */
+    version: number;
+    /** Timestamp of the final included event, when one exists. */
+    asOf?: string;
+    /** Deterministic active edge materialization. */
+    edges: readonly RelationshipEdge[];
+    /** Immutable graph query view over the active edges. */
+    graph: RelationshipGraph;
+}
+/** Stable cursor page over a fixed relationship event-log version. */
+export interface RelationshipEventPage {
+    /** Log version against which this page was produced. */
+    version: number;
+    /** Events in append order. */
+    events: RelationshipEvent[];
+    /** Whether another event page exists. */
+    hasMore: boolean;
+    /** Opaque continuation cursor when another page exists. */
+    nextCursor?: string;
+}
+/** Construction controls for the in-memory reference ledger. */
+export interface RelationshipEventLogOptions {
+    /** Registry defining edge semantics and cardinality. */
+    registry?: RelationshipKindRegistry;
+}
+/** Filesystem controls for the durable relationship event store. */
+export interface RelationshipEventStoreOptions extends RelationshipEventLogOptions {
+    /** Tracker root that owns the relationship history directory. */
+    pmRoot: string;
+    /** Fixed node universe validated by every replay and append. */
+    nodes: Iterable<string>;
+    /** Optional JSONL path relative to the tracker root. */
+    relativePath?: string;
+}
+/**
+ * Append-only in-memory reference ledger. Durable adapters can persist the
+ * returned immutable events while reusing the same replay and validation model.
+ */
+export declare class RelationshipEventLog {
+    #private;
+    /** Create an empty relationship ledger for a fixed node universe. */
+    constructor(nodes: Iterable<string>, options?: RelationshipEventLogOptions);
+    /** Current append sequence. */
+    get version(): number;
+    /** Return an immutable copy of the full event stream. */
+    events(): readonly RelationshipEvent[];
+    /** Validate and append one attributable relationship mutation. */
+    append(input: RelationshipEventInput): RelationshipEvent;
+    /** Materialize an exact point-in-time graph without mutating the ledger. */
+    snapshot(options?: {
+        atVersion?: number;
+        atTimestamp?: string;
+    }): RelationshipSnapshot;
+    /** Page the immutable event stream with a cursor bound to this log version. */
+    page(options: {
+        limit: number;
+        cursor?: string;
+    }): RelationshipEventPage;
+}
+/**
+ * Lock-serialized durable JSONL adapter for {@link RelationshipEventLog}.
+ * Every append replays the current stream while holding the workspace lock, so
+ * independent processes share optimistic versions without lost updates.
+ */
+export declare class RelationshipEventStore {
+    #private;
+    private constructor();
+    /** Open and validate an existing stream or create an empty store view. */
+    static open(options: RelationshipEventStoreOptions): Promise<RelationshipEventStore>;
+    /** Absolute JSONL path, exposed for diagnostics and backup tooling. */
+    get path(): string;
+    /** Refresh from durable history and return the current validated append sequence. */
+    currentVersion(): Promise<number>;
+    /** Append one event after refreshing under the shared workspace lock. */
+    append(input: RelationshipEventInput): Promise<RelationshipEvent>;
+    /** Refresh from durable history and materialize an exact validated snapshot. */
+    snapshot(options?: Parameters<RelationshipEventLog["snapshot"]>[0]): Promise<RelationshipSnapshot>;
+    /** Refresh from durable history and page immutable events. */
+    page(options: Parameters<RelationshipEventLog["page"]>[0]): Promise<RelationshipEventPage>;
+}