@unbrained/pm-cli 2026.7.20 → 2026.7.21

package/dist/sdk/graph/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sources":["sdk/graph/cache.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/graph/cache\n *\n * Incremental workspace graph cache: fingerprint-keyed reuse of the assembled\n * relationship graph plus memoized analytics results, so long-lived processes\n * (the MCP server, SDK consumers, packages) stop paying the full-workspace\n * assembly and analysis cost on every bounded query. The fingerprint is a\n * deterministic digest of every relationship-relevant item field — id, title,\n * lifecycle status and its terminal classification, hierarchy parent, legacy\n * blocker, and structured dependency edges — so any mutation that could change\n * the graph or its projections invalidates the entry, while unrelated payload\n * churn (bodies, comments) does not enter the digest at all. Every lookup\n * reports hit/miss observability so envelopes can explain their freshness.\n */\nimport { createHash } from \"node:crypto\";\nimport type { Dependency, ItemStatus } from \"../../types/index.js\";\nimport type {\n  WorkspaceRelationshipAssembly,\n  WorkspaceRelationshipItem,\n} from \"./assembly.js\";\n\n/** Default memoized query results retained per workspace entry. */\nconst DEFAULT_MAX_RESULTS_PER_WORKSPACE = 64;\n/** Default workspace entries retained by one cache instance. */\nconst DEFAULT_MAX_WORKSPACES = 8;\n\n/** Cache observability attached to graph result envelopes. */\nexport interface GraphCacheMetadata {\n  /** Truncated workspace graph fingerprint identifying the snapshot answered from. */\n  fingerprint: string;\n  /** Whether the workspace assembly was reused from cache. */\n  assembly: \"hit\" | \"miss\";\n  /** Whether the full query result was reused from cache. */\n  result: \"hit\" | \"miss\";\n}\n\n/** Digest one item's relationship-relevant fields into a deterministic line. */\nfunction fingerprintLine(\n  item: WorkspaceRelationshipItem,\n  isTerminal: (status: ItemStatus) => boolean,\n): string {\n  const dependencies = (item.dependencies ?? [])\n    .map((rawDependency) => {\n      // Public SDK callers may supply legacy or JSON-decoded payloads; mirror\n      // assembly's defensive normalization so the digest tracks what assembly\n      // would actually index.\n      if (typeof rawDependency !== \"object\" || rawDependency === null)\n        return \"\";\n      const dependency = rawDependency as Partial<Dependency>;\n      return `${typeof dependency.kind === \"string\" ? dependency.kind : \"related\"}:${\n        typeof dependency.id === \"string\" ? dependency.id : \"\"\n      }`;\n    })\n    .sort()\n    .join(\",\");\n  return [\n    item.id,\n    item.title,\n    item.status,\n    isTerminal(item.status) ? \"1\" : \"0\",\n    item.parent ?? \"\",\n    item.blocked_by ?? \"\",\n    dependencies,\n  ].join(\"\\u0000\");\n}\n\n/**\n * Compute the deterministic workspace graph fingerprint for one item snapshot.\n * Items are digested in sorted order so storage enumeration order never\n * changes the fingerprint, and the terminal classification of each status is\n * folded in so schema changes to lifecycle semantics invalidate cached\n * assemblies even when raw statuses are unchanged.\n */\nexport function computeWorkspaceGraphFingerprint(\n  items: readonly WorkspaceRelationshipItem[],\n  isTerminal: (status: ItemStatus) => boolean = (status) =>\n    status === \"closed\" || status === \"canceled\",\n): string {\n  const lines = items\n    .filter((item) => typeof item?.id === \"string\" && item.id.trim().length > 0)\n    .map((item) => fingerprintLine(item, isTerminal))\n    .sort();\n  // Separate fields and records with control characters no stored field can\n  // contain unescaped, so adjacent free-text fields can never collide.\n  return createHash(\"sha256\").update(lines.join(\"\\u0001\")).digest(\"hex\");\n}\n\n/** One cached workspace snapshot: its assembly plus memoized query results. */\ninterface WorkspaceGraphCacheEntry {\n  /** Fingerprint of the item snapshot this entry answers for. */\n  fingerprint: string;\n  /** Assembled relationship graph reused across queries. */\n  assembly: WorkspaceRelationshipAssembly;\n  /** Bounded insertion-ordered memo of deterministic query results. */\n  results: Map<string, unknown>;\n}\n\n/** One resolved cache lookup bound to a workspace snapshot. */\nexport interface WorkspaceGraphCacheLookup {\n  /** The (possibly reused) workspace assembly. */\n  assembly: WorkspaceRelationshipAssembly;\n  /** Whether the assembly came from cache instead of being rebuilt. */\n  assemblyReused: boolean;\n  /** Full fingerprint of the snapshot this lookup is bound to. */\n  fingerprint: string;\n  /**\n   * Memoize one deterministic query result under this snapshot. On a miss the\n   * freshly computed value is returned as-is while an independent clone is\n   * stored, so mutating a miss result never corrupts the cache; every hit\n   * returns a fresh clone of the stored entry. Callers must not rely on the\n   * miss and hit paths returning the same object identity.\n   */\n  memoize<T>(queryKey: string, compute: () => T): { value: T; reused: boolean };\n}\n\n/** Validate one optional positive-integer cache bound, applying its default. */\nfunction requirePositiveCacheBound(\n  name: string,\n  value: number | undefined,\n  fallback: number,\n): number {\n  const bound = value ?? fallback;\n  if (!Number.isInteger(bound) || bound < 1)\n    throw new TypeError(`Invalid ${name} bound: ${String(value)}`);\n  return bound;\n}\n\n/**\n * Fingerprint-keyed cache of workspace relationship assemblies and memoized\n * deterministic query results. One entry is retained per workspace key; a\n * changed fingerprint atomically replaces the entry and drops its memoized\n * results. Memoized values are structured-cloned on store and on read so\n * neither the producer nor any consumer can mutate cached state.\n */\nexport class WorkspaceGraphCache {\n  readonly #entries = new Map<string, WorkspaceGraphCacheEntry>();\n  readonly #maxResultsPerWorkspace: number;\n  readonly #maxWorkspaces: number;\n\n  /** Create a cache, optionally bounding workspaces and memoized results. */\n  public constructor(\n    options: { maxResultsPerWorkspace?: number; maxWorkspaces?: number } = {},\n  ) {\n    this.#maxResultsPerWorkspace = requirePositiveCacheBound(\n      \"maxResultsPerWorkspace\",\n      options.maxResultsPerWorkspace,\n      DEFAULT_MAX_RESULTS_PER_WORKSPACE,\n    );\n    this.#maxWorkspaces = requirePositiveCacheBound(\n      \"maxWorkspaces\",\n      options.maxWorkspaces,\n      DEFAULT_MAX_WORKSPACES,\n    );\n  }\n\n  /**\n   * Resolve the cached assembly for one workspace key and fingerprint,\n   * building and storing it on miss. The returned lookup exposes snapshot-\n   * scoped memoization for query results derived from the same assembly.\n   */\n  public lookup(\n    key: string,\n    fingerprint: string,\n    build: () => WorkspaceRelationshipAssembly,\n  ): WorkspaceGraphCacheLookup {\n    let entry = this.#entries.get(key);\n    let assemblyReused = true;\n    if (entry === undefined || entry.fingerprint !== fingerprint) {\n      entry = { fingerprint, assembly: build(), results: new Map() };\n      assemblyReused = false;\n      if (\n        !this.#entries.has(key) &&\n        this.#entries.size >= this.#maxWorkspaces\n      ) {\n        // Evict the least recently used workspace; every lookup refreshes\n        // recency below, so insertion order tracks use order.\n        this.#entries.delete(this.#entries.keys().next().value!);\n      }\n    }\n    // Delete-and-reinsert keeps Map insertion order equal to recency order,\n    // making workspace eviction genuinely least-recently-used.\n    this.#entries.delete(key);\n    this.#entries.set(key, entry);\n    const resolved = entry;\n    const maxResults = this.#maxResultsPerWorkspace;\n    return {\n      assembly: resolved.assembly,\n      assemblyReused,\n      fingerprint,\n      memoize<T>(\n        queryKey: string,\n        compute: () => T,\n      ): { value: T; reused: boolean } {\n        const cached = resolved.results.get(queryKey);\n        if (cached !== undefined || resolved.results.has(queryKey)) {\n          // Refresh recency so eviction below is least-recently-used rather\n          // than first-inserted.\n          resolved.results.delete(queryKey);\n          resolved.results.set(queryKey, cached);\n          return { value: structuredClone(cached) as T, reused: true };\n        }\n        const value = compute();\n        if (resolved.results.size >= maxResults) {\n          // Evict the oldest memoized result; Map preserves insertion order.\n          resolved.results.delete(resolved.results.keys().next().value!);\n        }\n        resolved.results.set(queryKey, structuredClone(value));\n        return { value, reused: false };\n      },\n    };\n  }\n\n  /** Drop every cached workspace entry and memoized result. */\n  public clear(): void {\n    this.#entries.clear();\n  }\n}\n\n/** Process-wide shared cache used by the CLI/MCP graph and deps adapters. */\nconst sharedCache = new WorkspaceGraphCache();\n\n/** Return the process-wide shared workspace graph cache. */\nexport function workspaceGraphCache(): WorkspaceGraphCache {\n  return sharedCache;\n}\n\n/** Reset the process-wide shared workspace graph cache (tests and long-lived hosts). */\nexport function resetWorkspaceGraphCache(): void {\n  sharedCache.clear();\n}\n"],"names":[],"mappings":"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","debugId":"6c46fa7f-4566-5a15-ac76-1666770dc806"}
+{"version":3,"file":"cache.js","sources":["sdk/graph/cache.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/graph/cache\n *\n * Incremental workspace graph cache: fingerprint-keyed reuse of the assembled\n * relationship graph plus memoized analytics results, so long-lived processes\n * (the MCP server, SDK consumers, packages) stop paying the full-workspace\n * assembly and analysis cost on every bounded query. The fingerprint is a\n * deterministic digest of every relationship-relevant item field — id, title,\n * lifecycle status and its terminal classification, hierarchy parent, legacy\n * blocker, and structured dependency edges — so any mutation that could change\n * the graph or its projections invalidates the entry, while unrelated payload\n * churn (bodies, comments) does not enter the digest at all. Every lookup\n * reports hit/miss observability so envelopes can explain their freshness.\n */\nimport { createHash } from \"node:crypto\";\nimport { stableStringify } from \"../../core/shared/serialization.js\";\nimport type { Dependency, ItemStatus } from \"../../types/index.js\";\nimport {\n  createRelationshipKindRegistry,\n  type RelationshipKindRegistry,\n} from \"../relationships.js\";\nimport type {\n  WorkspaceRelationshipAssembly,\n  WorkspaceRelationshipItem,\n} from \"./assembly.js\";\n\n/** Default memoized query results retained per workspace entry. */\nconst DEFAULT_MAX_RESULTS_PER_WORKSPACE = 64;\n/** Default workspace entries retained by one cache instance. */\nconst DEFAULT_MAX_WORKSPACES = 8;\n\n/** Cache observability attached to graph result envelopes. */\nexport interface GraphCacheMetadata {\n  /** Truncated workspace graph fingerprint identifying the snapshot answered from. */\n  fingerprint: string;\n  /** Whether the workspace assembly was reused from cache. */\n  assembly: \"hit\" | \"miss\";\n  /** Whether the full query result was reused from cache. */\n  result: \"hit\" | \"miss\";\n  /** Durable cross-process index disposition: answered from it, missed it, or persistence disabled for this workspace. Absent on surfaces that never consult the durable index. */\n  durable?: \"hit\" | \"miss\" | \"off\";\n}\n\n/** Digest one item's relationship-relevant fields into a deterministic line. */\nfunction fingerprintLine(\n  item: WorkspaceRelationshipItem,\n  isTerminal: (status: ItemStatus) => boolean,\n): string {\n  const dependencies = (item.dependencies ?? [])\n    .map((rawDependency) => {\n      // Public SDK callers may supply legacy or JSON-decoded payloads; mirror\n      // assembly's defensive normalization so the digest tracks what assembly\n      // would actually index.\n      if (typeof rawDependency !== \"object\" || rawDependency === null)\n        return \"\";\n      const dependency = rawDependency as Partial<Dependency>;\n      return `${typeof dependency.kind === \"string\" ? dependency.kind : \"related\"}:${\n        typeof dependency.id === \"string\" ? dependency.id : \"\"\n      }`;\n    })\n    .sort()\n    .join(\",\");\n  return [\n    item.id,\n    item.title,\n    item.status,\n    isTerminal(item.status) ? \"1\" : \"0\",\n    // Per-type coverage profiles make the item type a projection input, so a\n    // retype must invalidate cached assemblies and memoized audit results.\n    typeof item.type === \"string\" ? item.type.trim() : \"\",\n    item.parent ?? \"\",\n    item.blocked_by ?? \"\",\n    dependencies,\n  ].join(\"\\u0000\");\n}\n\n/**\n * Compute the deterministic workspace graph fingerprint for one item snapshot.\n * Items are digested in sorted order so storage enumeration order never\n * changes the fingerprint, and the terminal classification of each status is\n * folded in so schema changes to lifecycle semantics invalidate cached\n * assemblies even when raw statuses are unchanged.\n */\nexport function computeWorkspaceGraphFingerprint(\n  items: readonly WorkspaceRelationshipItem[],\n  isTerminal: (status: ItemStatus) => boolean = (status) =>\n    status === \"closed\" || status === \"canceled\",\n  registry: RelationshipKindRegistry = createRelationshipKindRegistry(),\n): string {\n  const lines = items\n    .filter((item) => typeof item?.id === \"string\" && item.id.trim().length > 0)\n    .map((item) => fingerprintLine(item, isTerminal))\n    .sort();\n  const relationshipSemantics = registry\n    .list()\n    .map((definition) => stableStringify(definition))\n    .sort();\n  // Separate fields and records with control characters no stored field can\n  // contain unescaped, so adjacent free-text fields can never collide.\n  return createHash(\"sha256\")\n    .update(lines.join(\"\\u0001\"))\n    .update(\"\\u0002\")\n    .update(relationshipSemantics.join(\"\\u0001\"))\n    .digest(\"hex\");\n}\n\n/** One cached workspace snapshot: its assembly plus memoized query results. */\ninterface WorkspaceGraphCacheEntry {\n  /** Fingerprint of the item snapshot this entry answers for. */\n  fingerprint: string;\n  /** Assembled relationship graph reused across queries. */\n  assembly: WorkspaceRelationshipAssembly;\n  /** Bounded insertion-ordered memo of deterministic query results. */\n  results: Map<string, unknown>;\n}\n\n/** One resolved cache lookup bound to a workspace snapshot. */\nexport interface WorkspaceGraphCacheLookup {\n  /** The (possibly reused) workspace assembly. */\n  assembly: WorkspaceRelationshipAssembly;\n  /** Whether the assembly came from cache instead of being rebuilt. */\n  assemblyReused: boolean;\n  /** Full fingerprint of the snapshot this lookup is bound to. */\n  fingerprint: string;\n  /**\n   * Memoize one deterministic query result under this snapshot. On a miss the\n   * freshly computed value is returned as-is while an independent clone is\n   * stored, so mutating a miss result never corrupts the cache; every hit\n   * returns a fresh clone of the stored entry. Callers must not rely on the\n   * miss and hit paths returning the same object identity.\n   */\n  memoize<T>(queryKey: string, compute: () => T): { value: T; reused: boolean };\n}\n\n/** Validate one optional positive-integer cache bound, applying its default. */\nfunction requirePositiveCacheBound(\n  name: string,\n  value: number | undefined,\n  fallback: number,\n): number {\n  const bound = value ?? fallback;\n  if (!Number.isInteger(bound) || bound < 1)\n    throw new TypeError(`Invalid ${name} bound: ${String(value)}`);\n  return bound;\n}\n\n/**\n * Fingerprint-keyed cache of workspace relationship assemblies and memoized\n * deterministic query results. One entry is retained per workspace key; a\n * changed fingerprint atomically replaces the entry and drops its memoized\n * results. Memoized values are structured-cloned on store and on read so\n * neither the producer nor any consumer can mutate cached state.\n */\nexport class WorkspaceGraphCache {\n  readonly #entries = new Map<string, WorkspaceGraphCacheEntry>();\n  readonly #maxResultsPerWorkspace: number;\n  readonly #maxWorkspaces: number;\n\n  /** Create a cache, optionally bounding workspaces and memoized results. */\n  public constructor(\n    options: { maxResultsPerWorkspace?: number; maxWorkspaces?: number } = {},\n  ) {\n    this.#maxResultsPerWorkspace = requirePositiveCacheBound(\n      \"maxResultsPerWorkspace\",\n      options.maxResultsPerWorkspace,\n      DEFAULT_MAX_RESULTS_PER_WORKSPACE,\n    );\n    this.#maxWorkspaces = requirePositiveCacheBound(\n      \"maxWorkspaces\",\n      options.maxWorkspaces,\n      DEFAULT_MAX_WORKSPACES,\n    );\n  }\n\n  /**\n   * Resolve the cached assembly for one workspace key and fingerprint,\n   * building and storing it on miss. The returned lookup exposes snapshot-\n   * scoped memoization for query results derived from the same assembly.\n   */\n  public lookup(\n    key: string,\n    fingerprint: string,\n    build: () => WorkspaceRelationshipAssembly,\n  ): WorkspaceGraphCacheLookup {\n    let entry = this.#entries.get(key);\n    let assemblyReused = true;\n    if (entry === undefined || entry.fingerprint !== fingerprint) {\n      entry = { fingerprint, assembly: build(), results: new Map() };\n      assemblyReused = false;\n      if (\n        !this.#entries.has(key) &&\n        this.#entries.size >= this.#maxWorkspaces\n      ) {\n        // Evict the least recently used workspace; every lookup refreshes\n        // recency below, so insertion order tracks use order.\n        this.#entries.delete(this.#entries.keys().next().value!);\n      }\n    }\n    // Delete-and-reinsert keeps Map insertion order equal to recency order,\n    // making workspace eviction genuinely least-recently-used.\n    this.#entries.delete(key);\n    this.#entries.set(key, entry);\n    const resolved = entry;\n    const maxResults = this.#maxResultsPerWorkspace;\n    return {\n      assembly: resolved.assembly,\n      assemblyReused,\n      fingerprint,\n      memoize<T>(\n        queryKey: string,\n        compute: () => T,\n      ): { value: T; reused: boolean } {\n        const cached = resolved.results.get(queryKey);\n        if (cached !== undefined || resolved.results.has(queryKey)) {\n          // Refresh recency so eviction below is least-recently-used rather\n          // than first-inserted.\n          resolved.results.delete(queryKey);\n          resolved.results.set(queryKey, cached);\n          return { value: structuredClone(cached) as T, reused: true };\n        }\n        const value = compute();\n        if (resolved.results.size >= maxResults) {\n          // Evict the oldest memoized result; Map preserves insertion order.\n          resolved.results.delete(resolved.results.keys().next().value!);\n        }\n        resolved.results.set(queryKey, structuredClone(value));\n        return { value, reused: false };\n      },\n    };\n  }\n\n  /** Drop every cached workspace entry and memoized result. */\n  public clear(): void {\n    this.#entries.clear();\n  }\n}\n\n/** Process-wide shared cache used by the CLI/MCP graph and deps adapters. */\nconst sharedCache = new WorkspaceGraphCache();\n\n/** Return the process-wide shared workspace graph cache. */\nexport function workspaceGraphCache(): WorkspaceGraphCache {\n  return sharedCache;\n}\n\n/** Reset the process-wide shared workspace graph cache (tests and long-lived hosts). */\nexport function resetWorkspaceGraphCache(): void {\n  sharedCache.clear();\n}\n"],"names":[],"mappings":"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","debugId":"2131cf48-7b5e-5b17-bb53-65e8bf485100"}

package/dist/sdk/graph/centrality.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @module sdk/graph/centrality
+ *
+ * Structural-importance and fragility analytics over the undirected knowledge
+ * graph: exact shortest-path betweenness (Brandes), Wasserman–Faust closeness,
+ * undirected degree, and directed fan-in/fan-out per node, plus articulation
+ * points and bridges (single points of failure) via an iterative Tarjan
+ * low-link search. Every analysis is deterministic, cancellable, exact on the
+ * bounded workspace, and reports the visited-node and inspected-edge cost so
+ * agents can budget follow-up reads. Adjacency is the simple undirected graph
+ * (parallel edges and self-loops collapsed) so a pair connected by any kind
+ * counts once.
+ */
+import { RelationshipGraph, type RelationshipQueryResult } from "../relationships.js";
+/** One node ranked by structural centrality with directed fan-in/fan-out. */
+export interface RelationshipCentralityRow {
+    /** Node id. */
+    id: string;
+    /** Undirected unique-neighbor degree over selected kinds. */
+    degree: number;
+    /** Distinct ordering predecessors that gate this node (dependency fan-in). */
+    inDegree: number;
+    /** Distinct ordering successors this node gates (dependency fan-out). */
+    outDegree: number;
+    /** Shortest-path betweenness centrality, rounded to six decimals. */
+    betweenness: number;
+    /** Wasserman–Faust closeness centrality, rounded to six decimals. */
+    closeness: number;
+}
+/** Bounded centrality-analysis controls. */
+export interface GraphCentralityOptions {
+    /** Registered relationship kinds whose edges define adjacency. */
+    kinds?: readonly string[];
+    /** Abort signal checked once per source sweep. */
+    signal?: AbortSignal;
+}
+/** Deterministic centrality ranking over the undirected knowledge graph. */
+export interface RelationshipCentralityAnalysis {
+    /** Total indexed graph nodes. */
+    nodeCount: number;
+    /** Simple undirected edge count over selected kinds. */
+    edgeCount: number;
+    /** Node rows ranked by betweenness, then degree, then id. */
+    rows: RelationshipCentralityRow[];
+}
+/** One undirected bridge edge whose removal disconnects its endpoints. */
+export interface RelationshipBridge {
+    /** Lexicographically smaller endpoint. */
+    source: string;
+    /** Lexicographically larger endpoint. */
+    target: string;
+}
+/** Bounded cut-structure controls. */
+export interface GraphCutStructureOptions {
+    /** Registered relationship kinds whose edges define adjacency. */
+    kinds?: readonly string[];
+    /** Abort signal checked once per depth-first step. */
+    signal?: AbortSignal;
+}
+/** Articulation points and bridges of the undirected knowledge graph. */
+export interface RelationshipCutStructure {
+    /** Sorted articulation-point ids — nodes whose removal adds components. */
+    articulationPoints: string[];
+    /** Bridge edges sorted by source then target. */
+    bridges: RelationshipBridge[];
+}
+/**
+ * Compute exact shortest-path betweenness (Brandes), Wasserman–Faust closeness,
+ * undirected degree, and directed fan-in/fan-out for every node over the simple
+ * undirected graph induced by the selected kinds. Rows rank by betweenness, then
+ * degree, then id. The result is exact on the bounded workspace; callers bound
+ * the returned rows for token-aware projection.
+ */
+export declare function computeRelationshipCentrality(graph: RelationshipGraph, options?: GraphCentralityOptions): RelationshipQueryResult<RelationshipCentralityAnalysis>;
+/**
+ * Find articulation points and bridges of the undirected knowledge graph with
+ * an iterative Tarjan low-link search over the simple adjacency. An articulation
+ * point is a node whose removal increases the connected-component count; a bridge
+ * is an edge whose removal does the same — both are single points of failure in
+ * the relationship graph. Results are deterministic and exact.
+ */
+export declare function findRelationshipCutStructure(graph: RelationshipGraph, options?: GraphCutStructureOptions): RelationshipQueryResult<RelationshipCutStructure>;

package/dist/sdk/graph/centrality.js

@@ -0,0 +1,259 @@
+
+!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]="0b226d67-72f3-57f4-8428-d3af70ecf306")}catch(e){}}();
+import { forEachMatchedRelationshipEdge } from "./analytics.js";
+import { orientOrderingEdge } from "./traversal.js";
+/** Round a centrality score to six decimals to suppress floating-point noise. */
+function roundScore(value) {
+    return Math.round(value * 1e6) / 1e6;
+}
+/** Add one value to a set-valued map entry, creating the set on demand. */
+function addToSetMap(map, key, value) {
+    const set = map.get(key);
+    if (set === undefined)
+        map.set(key, new Set([value]));
+    else
+        set.add(value);
+}
+/** Build the deterministic simple undirected adjacency over every node. */
+function buildSimpleUndirectedAdjacency(graph, kinds) {
+    const sets = new Map(graph.nodes().map((id) => [id, new Set()]));
+    forEachMatchedRelationshipEdge(graph, kinds, (edge) => {
+        sets.get(edge.source).add(edge.target);
+        sets.get(edge.target).add(edge.source);
+    });
+    const adjacency = new Map();
+    for (const [id, neighbors] of sets)
+        adjacency.set(id, [...neighbors].sort());
+    return adjacency;
+}
+/**
+ * Collect distinct ordering predecessors and successors per node, oriented by
+ * each kind's declared precedence so fan-in/fan-out match the SDK's
+ * predecessor/successor traversal semantics rather than the stored edge
+ * spelling (a `blocked_by` edge counts its target as the predecessor).
+ */
+function collectOrderingDegrees(graph, kinds) {
+    const incoming = new Map();
+    const outgoing = new Map();
+    forEachMatchedRelationshipEdge(graph, kinds, (edge, definition) => {
+        if (!definition.ordering)
+            return;
+        const { predecessor, successor } = orientOrderingEdge(edge, definition);
+        // The predecessor gates the successor: predecessor -> successor.
+        addToSetMap(outgoing, predecessor, successor);
+        addToSetMap(incoming, successor, predecessor);
+    });
+    return { incoming, outgoing };
+}
+/** Run one breadth-first single-source shortest-path sweep for Brandes accumulation. */
+function brandesShortestPaths(source, adjacency, cost) {
+    const distance = new Map([[source, 0]]);
+    const sigma = new Map([[source, 1]]);
+    const predecessors = new Map();
+    const stack = [];
+    const queue = [source];
+    let reachableCount = 0;
+    let distanceSum = 0;
+    for (let index = 0; index < queue.length; index += 1) {
+        const node = queue[index];
+        cost.visitedNodes += 1;
+        stack.push(node);
+        const nodeDistance = distance.get(node);
+        if (node !== source) {
+            reachableCount += 1;
+            distanceSum += nodeDistance;
+        }
+        for (const neighbor of adjacency.get(node)) {
+            cost.inspectedEdges += 1;
+            if (!distance.has(neighbor)) {
+                distance.set(neighbor, nodeDistance + 1);
+                queue.push(neighbor);
+            }
+            if (distance.get(neighbor) === nodeDistance + 1) {
+                sigma.set(neighbor, (sigma.get(neighbor) ?? 0) + sigma.get(node));
+                const predecessorList = predecessors.get(neighbor);
+                if (predecessorList === undefined)
+                    predecessors.set(neighbor, [node]);
+                else
+                    predecessorList.push(node);
+            }
+        }
+    }
+    return { stack, sigma, predecessors, reachableCount, distanceSum };
+}
+/** Fold one completed sweep's dependencies back into the running betweenness totals. */
+function accumulateBetweenness(sweep, source, betweenness) {
+    const dependency = new Map();
+    for (let index = sweep.stack.length - 1; index >= 0; index -= 1) {
+        const node = sweep.stack[index];
+        const share = (1 + (dependency.get(node) ?? 0)) / sweep.sigma.get(node);
+        for (const predecessor of sweep.predecessors.get(node) ?? []) {
+            dependency.set(predecessor, (dependency.get(predecessor) ?? 0) + sweep.sigma.get(predecessor) * share);
+        }
+        if (node !== source)
+            betweenness.set(node, (betweenness.get(node) ?? 0) + (dependency.get(node) ?? 0));
+    }
+}
+/**
+ * Wasserman–Faust closeness normalizes reachability so disconnected graphs
+ * compare fairly. A reachable count above zero implies a positive distance sum
+ * (every shortest distance is at least one), so those two guards suffice.
+ */
+function wassermanFaustCloseness(sweep, nodeCount) {
+    if (nodeCount <= 1 || sweep.reachableCount === 0)
+        return 0;
+    return ((sweep.reachableCount / (nodeCount - 1)) *
+        (sweep.reachableCount / sweep.distanceSum));
+}
+/** Assemble one ranked centrality row from the accumulated scores. */
+function centralityRow(id, adjacency, directed, betweenness, closeness) {
+    return {
+        id,
+        degree: adjacency.get(id).length,
+        inDegree: directed.incoming.get(id)?.size ?? 0,
+        outDegree: directed.outgoing.get(id)?.size ?? 0,
+        // Undirected betweenness double-counts each ordered pair; halve it.
+        betweenness: roundScore((betweenness.get(id) ?? 0) / 2),
+        // Every node is a sweep source, so closeness is always populated.
+        closeness: roundScore(closeness.get(id)),
+    };
+}
+/**
+ * Compute exact shortest-path betweenness (Brandes), Wasserman–Faust closeness,
+ * undirected degree, and directed fan-in/fan-out for every node over the simple
+ * undirected graph induced by the selected kinds. Rows rank by betweenness, then
+ * degree, then id. The result is exact on the bounded workspace; callers bound
+ * the returned rows for token-aware projection.
+ */
+export function computeRelationshipCentrality(graph, options = {}) {
+    const adjacency = buildSimpleUndirectedAdjacency(graph, options.kinds);
+    const directed = collectOrderingDegrees(graph, options.kinds);
+    const nodes = graph.nodes();
+    const betweenness = new Map();
+    const closeness = new Map();
+    const cost = { visitedNodes: 0, inspectedEdges: 0 };
+    for (const source of nodes) {
+        options.signal?.throwIfAborted();
+        const sweep = brandesShortestPaths(source, adjacency, cost);
+        closeness.set(source, wassermanFaustCloseness(sweep, nodes.length));
+        accumulateBetweenness(sweep, source, betweenness);
+    }
+    let degreeSum = 0;
+    for (const neighbors of adjacency.values())
+        degreeSum += neighbors.length;
+    const rows = nodes
+        .map((id) => centralityRow(id, adjacency, directed, betweenness, closeness))
+        .sort((left, right) => right.betweenness - left.betweenness ||
+        right.degree - left.degree ||
+        left.id.localeCompare(right.id));
+    return {
+        value: { nodeCount: nodes.length, edgeCount: degreeSum / 2, rows },
+        meta: {
+            visitedNodes: cost.visitedNodes,
+            inspectedEdges: cost.inspectedEdges,
+            truncated: false,
+        },
+    };
+}
+/** Order one bridge endpoint pair deterministically. */
+function orderedBridge(left, right) {
+    return left <= right
+        ? { source: left, target: right }
+        : { source: right, target: left };
+}
+/**
+ * Advance the top frame by one neighbor: descend into an undiscovered neighbor,
+ * or relax the low-link against a back edge. Returns the discovered child frame
+ * to push, or undefined when the step consumed a back edge or the tree parent.
+ */
+function advanceCutFrame(frame, adjacency, state) {
+    const neighbors = adjacency.get(frame.node);
+    const neighbor = neighbors[frame.neighborIndex];
+    frame.neighborIndex += 1;
+    state.inspectedEdges += 1;
+    if (neighbor === frame.parent)
+        return undefined;
+    if (state.discovery.has(neighbor)) {
+        state.low.set(frame.node, Math.min(state.low.get(frame.node), state.discovery.get(neighbor)));
+        return undefined;
+    }
+    frame.children += 1;
+    state.discovery.set(neighbor, state.timer);
+    state.low.set(neighbor, state.timer);
+    state.timer += 1;
+    return { node: neighbor, parent: frame.node, neighborIndex: 0, children: 0 };
+}
+/** Retreat from a finished frame: fold its low-link into its parent and flag cuts. */
+function retreatCutFrame(frame, root, state) {
+    if (frame.parent === null) {
+        if (frame.children > 1)
+            state.articulation.add(frame.node);
+        return;
+    }
+    const parent = frame.parent;
+    const childLow = state.low.get(frame.node);
+    state.low.set(parent, Math.min(state.low.get(parent), childLow));
+    if (parent !== root && childLow >= state.discovery.get(parent))
+        state.articulation.add(parent);
+    if (childLow > state.discovery.get(parent))
+        state.bridges.push(orderedBridge(parent, frame.node));
+}
+/** Walk one connected component's depth-first tree, updating low-links and cuts. */
+function searchComponentCuts(root, adjacency, state, signal) {
+    state.discovery.set(root, state.timer);
+    state.low.set(root, state.timer);
+    state.timer += 1;
+    const stack = [
+        { node: root, parent: null, neighborIndex: 0, children: 0 },
+    ];
+    while (stack.length > 0) {
+        signal?.throwIfAborted();
+        const frame = stack.at(-1);
+        if (frame.neighborIndex < adjacency.get(frame.node).length) {
+            const child = advanceCutFrame(frame, adjacency, state);
+            if (child !== undefined)
+                stack.push(child);
+        }
+        else {
+            retreatCutFrame(frame, root, state);
+            stack.pop();
+        }
+    }
+}
+/**
+ * Find articulation points and bridges of the undirected knowledge graph with
+ * an iterative Tarjan low-link search over the simple adjacency. An articulation
+ * point is a node whose removal increases the connected-component count; a bridge
+ * is an edge whose removal does the same — both are single points of failure in
+ * the relationship graph. Results are deterministic and exact.
+ */
+export function findRelationshipCutStructure(graph, options = {}) {
+    const adjacency = buildSimpleUndirectedAdjacency(graph, options.kinds);
+    const state = {
+        discovery: new Map(),
+        low: new Map(),
+        timer: 0,
+        articulation: new Set(),
+        bridges: [],
+        inspectedEdges: 0,
+    };
+    for (const root of graph.nodes()) {
+        if (state.discovery.has(root))
+            continue;
+        searchComponentCuts(root, adjacency, state, options.signal);
+    }
+    return {
+        value: {
+            articulationPoints: [...state.articulation].sort(),
+            bridges: state.bridges.sort((left, right) => left.source.localeCompare(right.source) ||
+                left.target.localeCompare(right.target)),
+        },
+        meta: {
+            visitedNodes: state.discovery.size,
+            inspectedEdges: state.inspectedEdges,
+            truncated: false,
+        },
+    };
+}
+//# sourceMappingURL=centrality.js.map
+//# debugId=0b226d67-72f3-57f4-8428-d3af70ecf306

package/dist/sdk/graph/centrality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"centrality.js","sources":["sdk/graph/centrality.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/graph/centrality\n *\n * Structural-importance and fragility analytics over the undirected knowledge\n * graph: exact shortest-path betweenness (Brandes), Wasserman–Faust closeness,\n * undirected degree, and directed fan-in/fan-out per node, plus articulation\n * points and bridges (single points of failure) via an iterative Tarjan\n * low-link search. Every analysis is deterministic, cancellable, exact on the\n * bounded workspace, and reports the visited-node and inspected-edge cost so\n * agents can budget follow-up reads. Adjacency is the simple undirected graph\n * (parallel edges and self-loops collapsed) so a pair connected by any kind\n * counts once.\n */\nimport {\n  RelationshipGraph,\n  type RelationshipQueryResult,\n} from \"../relationships.js\";\nimport { forEachMatchedRelationshipEdge } from \"./analytics.js\";\nimport { orientOrderingEdge } from \"./traversal.js\";\n\n/** One node ranked by structural centrality with directed fan-in/fan-out. */\nexport interface RelationshipCentralityRow {\n  /** Node id. */\n  id: string;\n  /** Undirected unique-neighbor degree over selected kinds. */\n  degree: number;\n  /** Distinct ordering predecessors that gate this node (dependency fan-in). */\n  inDegree: number;\n  /** Distinct ordering successors this node gates (dependency fan-out). */\n  outDegree: number;\n  /** Shortest-path betweenness centrality, rounded to six decimals. */\n  betweenness: number;\n  /** Wasserman–Faust closeness centrality, rounded to six decimals. */\n  closeness: number;\n}\n\n/** Bounded centrality-analysis controls. */\nexport interface GraphCentralityOptions {\n  /** Registered relationship kinds whose edges define adjacency. */\n  kinds?: readonly string[];\n  /** Abort signal checked once per source sweep. */\n  signal?: AbortSignal;\n}\n\n/** Deterministic centrality ranking over the undirected knowledge graph. */\nexport interface RelationshipCentralityAnalysis {\n  /** Total indexed graph nodes. */\n  nodeCount: number;\n  /** Simple undirected edge count over selected kinds. */\n  edgeCount: number;\n  /** Node rows ranked by betweenness, then degree, then id. */\n  rows: RelationshipCentralityRow[];\n}\n\n/** One undirected bridge edge whose removal disconnects its endpoints. */\nexport interface RelationshipBridge {\n  /** Lexicographically smaller endpoint. */\n  source: string;\n  /** Lexicographically larger endpoint. */\n  target: string;\n}\n\n/** Bounded cut-structure controls. */\nexport interface GraphCutStructureOptions {\n  /** Registered relationship kinds whose edges define adjacency. */\n  kinds?: readonly string[];\n  /** Abort signal checked once per depth-first step. */\n  signal?: AbortSignal;\n}\n\n/** Articulation points and bridges of the undirected knowledge graph. */\nexport interface RelationshipCutStructure {\n  /** Sorted articulation-point ids — nodes whose removal adds components. */\n  articulationPoints: string[];\n  /** Bridge edges sorted by source then target. */\n  bridges: RelationshipBridge[];\n}\n\n/** Round a centrality score to six decimals to suppress floating-point noise. */\nfunction roundScore(value: number): number {\n  return Math.round(value * 1e6) / 1e6;\n}\n\n/** Add one value to a set-valued map entry, creating the set on demand. */\nfunction addToSetMap(\n  map: Map<string, Set<string>>,\n  key: string,\n  value: string,\n): void {\n  const set = map.get(key);\n  if (set === undefined) map.set(key, new Set([value]));\n  else set.add(value);\n}\n\n/** Build the deterministic simple undirected adjacency over every node. */\nfunction buildSimpleUndirectedAdjacency(\n  graph: RelationshipGraph,\n  kinds: readonly string[] | undefined,\n): Map<string, string[]> {\n  const sets = new Map(graph.nodes().map((id) => [id, new Set<string>()]));\n  forEachMatchedRelationshipEdge(graph, kinds, (edge) => {\n    sets.get(edge.source)!.add(edge.target);\n    sets.get(edge.target)!.add(edge.source);\n  });\n  const adjacency = new Map<string, string[]>();\n  for (const [id, neighbors] of sets) adjacency.set(id, [...neighbors].sort());\n  return adjacency;\n}\n\n/**\n * Collect distinct ordering predecessors and successors per node, oriented by\n * each kind's declared precedence so fan-in/fan-out match the SDK's\n * predecessor/successor traversal semantics rather than the stored edge\n * spelling (a `blocked_by` edge counts its target as the predecessor).\n */\nfunction collectOrderingDegrees(\n  graph: RelationshipGraph,\n  kinds: readonly string[] | undefined,\n): { incoming: Map<string, Set<string>>; outgoing: Map<string, Set<string>> } {\n  const incoming = new Map<string, Set<string>>();\n  const outgoing = new Map<string, Set<string>>();\n  forEachMatchedRelationshipEdge(graph, kinds, (edge, definition) => {\n    if (!definition.ordering) return;\n    const { predecessor, successor } = orientOrderingEdge(edge, definition);\n    // The predecessor gates the successor: predecessor -> successor.\n    addToSetMap(outgoing, predecessor, successor);\n    addToSetMap(incoming, successor, predecessor);\n  });\n  return { incoming, outgoing };\n}\n\n/** Single-source shortest-path state accumulated by one Brandes sweep. */\ninterface BrandesSweep {\n  /** Nodes in nondecreasing distance (breadth-first dequeue) order. */\n  stack: string[];\n  /** Number of shortest paths from the source to each node. */\n  sigma: Map<string, number>;\n  /** Shortest-path predecessors of each node. */\n  predecessors: Map<string, string[]>;\n  /** Reachable node count excluding the source. */\n  reachableCount: number;\n  /** Sum of shortest distances to every reachable node. */\n  distanceSum: number;\n}\n\n/** Run one breadth-first single-source shortest-path sweep for Brandes accumulation. */\nfunction brandesShortestPaths(\n  source: string,\n  adjacency: ReadonlyMap<string, readonly string[]>,\n  cost: { visitedNodes: number; inspectedEdges: number },\n): BrandesSweep {\n  const distance = new Map<string, number>([[source, 0]]);\n  const sigma = new Map<string, number>([[source, 1]]);\n  const predecessors = new Map<string, string[]>();\n  const stack: string[] = [];\n  const queue = [source];\n  let reachableCount = 0;\n  let distanceSum = 0;\n  for (let index = 0; index < queue.length; index += 1) {\n    const node = queue[index]!;\n    cost.visitedNodes += 1;\n    stack.push(node);\n    const nodeDistance = distance.get(node)!;\n    if (node !== source) {\n      reachableCount += 1;\n      distanceSum += nodeDistance;\n    }\n    for (const neighbor of adjacency.get(node)!) {\n      cost.inspectedEdges += 1;\n      if (!distance.has(neighbor)) {\n        distance.set(neighbor, nodeDistance + 1);\n        queue.push(neighbor);\n      }\n      if (distance.get(neighbor) === nodeDistance + 1) {\n        sigma.set(neighbor, (sigma.get(neighbor) ?? 0) + sigma.get(node)!);\n        const predecessorList = predecessors.get(neighbor);\n        if (predecessorList === undefined) predecessors.set(neighbor, [node]);\n        else predecessorList.push(node);\n      }\n    }\n  }\n  return { stack, sigma, predecessors, reachableCount, distanceSum };\n}\n\n/** Fold one completed sweep's dependencies back into the running betweenness totals. */\nfunction accumulateBetweenness(\n  sweep: BrandesSweep,\n  source: string,\n  betweenness: Map<string, number>,\n): void {\n  const dependency = new Map<string, number>();\n  for (let index = sweep.stack.length - 1; index >= 0; index -= 1) {\n    const node = sweep.stack[index]!;\n    const share = (1 + (dependency.get(node) ?? 0)) / sweep.sigma.get(node)!;\n    for (const predecessor of sweep.predecessors.get(node) ?? []) {\n      dependency.set(\n        predecessor,\n        (dependency.get(predecessor) ?? 0) + sweep.sigma.get(predecessor)! * share,\n      );\n    }\n    if (node !== source)\n      betweenness.set(node, (betweenness.get(node) ?? 0) + (dependency.get(node) ?? 0));\n  }\n}\n\n/**\n * Wasserman–Faust closeness normalizes reachability so disconnected graphs\n * compare fairly. A reachable count above zero implies a positive distance sum\n * (every shortest distance is at least one), so those two guards suffice.\n */\nfunction wassermanFaustCloseness(sweep: BrandesSweep, nodeCount: number): number {\n  if (nodeCount <= 1 || sweep.reachableCount === 0) return 0;\n  return (\n    (sweep.reachableCount / (nodeCount - 1)) *\n    (sweep.reachableCount / sweep.distanceSum)\n  );\n}\n\n/** Assemble one ranked centrality row from the accumulated scores. */\nfunction centralityRow(\n  id: string,\n  adjacency: ReadonlyMap<string, readonly string[]>,\n  directed: ReturnType<typeof collectOrderingDegrees>,\n  betweenness: Map<string, number>,\n  closeness: Map<string, number>,\n): RelationshipCentralityRow {\n  return {\n    id,\n    degree: adjacency.get(id)!.length,\n    inDegree: directed.incoming.get(id)?.size ?? 0,\n    outDegree: directed.outgoing.get(id)?.size ?? 0,\n    // Undirected betweenness double-counts each ordered pair; halve it.\n    betweenness: roundScore((betweenness.get(id) ?? 0) / 2),\n    // Every node is a sweep source, so closeness is always populated.\n    closeness: roundScore(closeness.get(id)!),\n  };\n}\n\n/**\n * Compute exact shortest-path betweenness (Brandes), Wasserman–Faust closeness,\n * undirected degree, and directed fan-in/fan-out for every node over the simple\n * undirected graph induced by the selected kinds. Rows rank by betweenness, then\n * degree, then id. The result is exact on the bounded workspace; callers bound\n * the returned rows for token-aware projection.\n */\nexport function computeRelationshipCentrality(\n  graph: RelationshipGraph,\n  options: GraphCentralityOptions = {},\n): RelationshipQueryResult<RelationshipCentralityAnalysis> {\n  const adjacency = buildSimpleUndirectedAdjacency(graph, options.kinds);\n  const directed = collectOrderingDegrees(graph, options.kinds);\n  const nodes = graph.nodes();\n  const betweenness = new Map<string, number>();\n  const closeness = new Map<string, number>();\n  const cost = { visitedNodes: 0, inspectedEdges: 0 };\n  for (const source of nodes) {\n    options.signal?.throwIfAborted();\n    const sweep = brandesShortestPaths(source, adjacency, cost);\n    closeness.set(source, wassermanFaustCloseness(sweep, nodes.length));\n    accumulateBetweenness(sweep, source, betweenness);\n  }\n  let degreeSum = 0;\n  for (const neighbors of adjacency.values()) degreeSum += neighbors.length;\n  const rows = nodes\n    .map((id) => centralityRow(id, adjacency, directed, betweenness, closeness))\n    .sort(\n      (left, right) =>\n        right.betweenness - left.betweenness ||\n        right.degree - left.degree ||\n        left.id.localeCompare(right.id),\n    );\n  return {\n    value: { nodeCount: nodes.length, edgeCount: degreeSum / 2, rows },\n    meta: {\n      visitedNodes: cost.visitedNodes,\n      inspectedEdges: cost.inspectedEdges,\n      truncated: false,\n    },\n  };\n}\n\n/** Order one bridge endpoint pair deterministically. */\nfunction orderedBridge(left: string, right: string): RelationshipBridge {\n  return left <= right\n    ? { source: left, target: right }\n    : { source: right, target: left };\n}\n\n/** Mutable depth-first frame for the iterative articulation/bridge search. */\ninterface CutFrame {\n  /** Node owned by this frame. */\n  node: string;\n  /** Depth-first tree parent, or null at a component root. */\n  parent: string | null;\n  /** Next unexplored neighbor index in the node's adjacency. */\n  neighborIndex: number;\n  /** Depth-first tree children discovered through this frame. */\n  children: number;\n}\n\n/** Shared low-link state threaded through the iterative cut-structure search. */\ninterface CutState {\n  /** Discovery index per visited node. */\n  discovery: Map<string, number>;\n  /** Low-link value per visited node. */\n  low: Map<string, number>;\n  /** Monotonic discovery counter. */\n  timer: number;\n  /** Articulation points found so far. */\n  articulation: Set<string>;\n  /** Bridge edges found so far. */\n  bridges: RelationshipBridge[];\n  /** Adjacency reads performed. */\n  inspectedEdges: number;\n}\n\n/**\n * Advance the top frame by one neighbor: descend into an undiscovered neighbor,\n * or relax the low-link against a back edge. Returns the discovered child frame\n * to push, or undefined when the step consumed a back edge or the tree parent.\n */\nfunction advanceCutFrame(\n  frame: CutFrame,\n  adjacency: ReadonlyMap<string, readonly string[]>,\n  state: CutState,\n): CutFrame | undefined {\n  const neighbors = adjacency.get(frame.node)!;\n  const neighbor = neighbors[frame.neighborIndex]!;\n  frame.neighborIndex += 1;\n  state.inspectedEdges += 1;\n  if (neighbor === frame.parent) return undefined;\n  if (state.discovery.has(neighbor)) {\n    state.low.set(\n      frame.node,\n      Math.min(state.low.get(frame.node)!, state.discovery.get(neighbor)!),\n    );\n    return undefined;\n  }\n  frame.children += 1;\n  state.discovery.set(neighbor, state.timer);\n  state.low.set(neighbor, state.timer);\n  state.timer += 1;\n  return { node: neighbor, parent: frame.node, neighborIndex: 0, children: 0 };\n}\n\n/** Retreat from a finished frame: fold its low-link into its parent and flag cuts. */\nfunction retreatCutFrame(frame: CutFrame, root: string, state: CutState): void {\n  if (frame.parent === null) {\n    if (frame.children > 1) state.articulation.add(frame.node);\n    return;\n  }\n  const parent = frame.parent;\n  const childLow = state.low.get(frame.node)!;\n  state.low.set(parent, Math.min(state.low.get(parent)!, childLow));\n  if (parent !== root && childLow >= state.discovery.get(parent)!)\n    state.articulation.add(parent);\n  if (childLow > state.discovery.get(parent)!)\n    state.bridges.push(orderedBridge(parent, frame.node));\n}\n\n/** Walk one connected component's depth-first tree, updating low-links and cuts. */\nfunction searchComponentCuts(\n  root: string,\n  adjacency: ReadonlyMap<string, readonly string[]>,\n  state: CutState,\n  signal: AbortSignal | undefined,\n): void {\n  state.discovery.set(root, state.timer);\n  state.low.set(root, state.timer);\n  state.timer += 1;\n  const stack: CutFrame[] = [\n    { node: root, parent: null, neighborIndex: 0, children: 0 },\n  ];\n  while (stack.length > 0) {\n    signal?.throwIfAborted();\n    const frame = stack.at(-1)!;\n    if (frame.neighborIndex < adjacency.get(frame.node)!.length) {\n      const child = advanceCutFrame(frame, adjacency, state);\n      if (child !== undefined) stack.push(child);\n    } else {\n      retreatCutFrame(frame, root, state);\n      stack.pop();\n    }\n  }\n}\n\n/**\n * Find articulation points and bridges of the undirected knowledge graph with\n * an iterative Tarjan low-link search over the simple adjacency. An articulation\n * point is a node whose removal increases the connected-component count; a bridge\n * is an edge whose removal does the same — both are single points of failure in\n * the relationship graph. Results are deterministic and exact.\n */\nexport function findRelationshipCutStructure(\n  graph: RelationshipGraph,\n  options: GraphCutStructureOptions = {},\n): RelationshipQueryResult<RelationshipCutStructure> {\n  const adjacency = buildSimpleUndirectedAdjacency(graph, options.kinds);\n  const state: CutState = {\n    discovery: new Map(),\n    low: new Map(),\n    timer: 0,\n    articulation: new Set(),\n    bridges: [],\n    inspectedEdges: 0,\n  };\n  for (const root of graph.nodes()) {\n    if (state.discovery.has(root)) continue;\n    searchComponentCuts(root, adjacency, state, options.signal);\n  }\n  return {\n    value: {\n      articulationPoints: [...state.articulation].sort(),\n      bridges: state.bridges.sort(\n        (left, right) =>\n          left.source.localeCompare(right.source) ||\n          left.target.localeCompare(right.target),\n      ),\n    },\n    meta: {\n      visitedNodes: state.discovery.size,\n      inspectedEdges: state.inspectedEdges,\n      truncated: false,\n    },\n  };\n}\n"],"names":[],"mappings":"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","debugId":"0b226d67-72f3-57f4-8428-d3af70ecf306"}

package/dist/sdk/graph/durable-cache.d.ts

@@ -0,0 +1,71 @@
+import type { RelationshipAuditSnapshot } from "./governance.js";
+/** Envelope format version; any change invalidates persisted entries. */
+export declare const GRAPH_DURABLE_CACHE_VERSION = 1;
+/** Workspaces below this item count skip implicit persistence. */
+export declare const GRAPH_DURABLE_CACHE_MIN_ITEMS = 500;
+/** Persisted durable graph cache envelope keyed by one workspace fingerprint. */
+export interface DurableGraphCacheEnvelope {
+    /** Envelope format version guarding decode compatibility. */
+    version: number;
+    /** Full workspace graph fingerprint every entry answers for. */
+    fingerprint: string;
+    /** ISO timestamp of the last persisted write. */
+    saved_at: string;
+    /** Deterministic query results keyed by their canonical query key. */
+    results: Record<string, unknown>;
+}
+/** Compact durable index status projection for observability surfaces. */
+export interface DurableGraphCacheStatus {
+    /** Whether an envelope file exists on disk. */
+    exists: boolean;
+    /** Whether the stored fingerprint matches the current workspace snapshot. */
+    fresh: boolean;
+    /** Stored entry count, 0 when absent. */
+    entry_count: number;
+    /** Truncated stored fingerprint, absent when no envelope exists. */
+    fingerprint?: string;
+    /** ISO timestamp of the last persisted write, absent when no envelope exists. */
+    saved_at?: string;
+    /** Envelope file size in bytes, absent when no envelope exists. */
+    bytes?: number;
+}
+/** Resolve the durable graph cache file path for one workspace root. */
+export declare function durableGraphCachePath(pmRoot: string): string;
+/** Resolve the persisted audit census baseline path for one workspace root. */
+export declare function graphAuditBaselinePath(pmRoot: string): string;
+/** One opened durable index view bound to the current workspace fingerprint. */
+export interface DurableGraphCacheView {
+    /** Whether any envelope file exists on disk, fresh or not. */
+    exists: boolean;
+    /** Whether the stored envelope answers for the current fingerprint. */
+    fresh: boolean;
+    /** Fingerprint-fresh persisted query results; empty when absent or stale. */
+    results: Record<string, unknown>;
+}
+/**
+ * Open the persisted envelope against the current workspace fingerprint. A
+ * missing, corrupt, version-drifted, or fingerprint-mismatched envelope reads
+ * as empty so stale entries can never answer for a mutated workspace.
+ */
+export declare function openDurableGraphCache(pmRoot: string, fingerprint: string): Promise<DurableGraphCacheView>;
+/**
+ * Persist one query result into the durable envelope, replacing any envelope
+ * recorded for a different fingerprint and trimming the oldest entries beyond
+ * the retention bound. A cross-process lock protects the read-merge-write, and
+ * the final write is atomic, so concurrent queries retain each other's entries.
+ */
+export declare function persistDurableGraphResult(pmRoot: string, fingerprint: string, view: DurableGraphCacheView, queryKey: string, result: unknown): Promise<void>;
+/** Delete the persisted durable graph cache envelope when present. */
+export declare function clearDurableGraphCache(pmRoot: string): Promise<void>;
+/** Report the durable index status against the current workspace fingerprint. */
+export declare function durableGraphCacheStatus(pmRoot: string, fingerprint: string): Promise<DurableGraphCacheStatus>;
+/**
+ * Decide whether implicit persistence applies to this invocation. Small
+ * workspaces skip the index unless an envelope already exists — the explicit
+ * `pm graph index --rebuild` opt-in creates it and thereby enables writes.
+ */
+export declare function shouldPersistDurableGraphCache(itemCount: number, envelopeExists: boolean): boolean;
+/** Load the persisted audit census baseline when present and decodable. */
+export declare function loadGraphAuditBaseline(pmRoot: string): Promise<RelationshipAuditSnapshot | undefined>;
+/** Atomically persist one audit census snapshot as the comparison baseline. */
+export declare function saveGraphAuditBaseline(pmRoot: string, snapshot: RelationshipAuditSnapshot): Promise<void>;