@unbrained/pm-cli 2026.7.17 → 2026.7.18

package/dist/sdk/graph/run.js

@@ -0,0 +1,468 @@
+/**
+ * @module sdk/graph/run
+ *
+ * Workspace-facing `pm graph` runner: one thin orchestrator that loads the
+ * tracker once, resolves the fingerprint-keyed workspace assembly through the
+ * shared graph cache, and dispatches bounded traversal, path, impact,
+ * analytics, governance-audit, and remediation-planning queries through the
+ * public graph toolkit. Every projection is counts-first, deterministic, and
+ * carries explicit cost, truncation, and cache metadata so agents can budget
+ * follow-up reads without re-scanning the workspace; identical repeated
+ * queries in long-lived hosts are answered from the memoized snapshot.
+ */
+
+!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]="3d4c5f7b-bcd4-569b-8bea-b06cc9f115e5")}catch(e){}}();
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { isTerminalStatus } from "../../core/item/status.js";
+import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { resolveRuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { listAllItemMetadataLight } from "../../core/store/item-store.js";
+import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { parseDirection, parseKinds, parseMaxDepth, parsePositiveInteger, } from "../dependencies.js";
+import { analyzeGraphImpact, analyzeKnowledgeGraph, analyzeRelationshipExecution, } from "../relationship-analytics.js";
+import { computeRelationshipDominators, detectRelationshipCommunities, findRedundantRelationshipEdges, } from "./analytics.js";
+import { assembleWorkspaceRelationshipGraph, } from "./assembly.js";
+import { computeWorkspaceGraphFingerprint, workspaceGraphCache, } from "./cache.js";
+import { auditWorkspaceRelationshipGraph, } from "./governance.js";
+import { planRelationshipRemediation, } from "./remediation.js";
+import { enumerateRelationshipPaths, hierarchyAncestors, hierarchyDescendants, orderingPredecessors, orderingSuccessors, } from "./traversal.js";
+import { GRAPH_SUBCOMMAND_VALUES, } from "../cli-contracts/enum-contracts.js";
+export { GRAPH_SUBCOMMAND_VALUES };
+/** Graph subcommands that require a root item id. */
+const ROOTED_SUBCOMMANDS = new Set([
+    "ancestors",
+    "descendants",
+    "predecessors",
+    "successors",
+    "paths",
+    "impact",
+    "dominators",
+]);
+/** Default bounded sample rows returned by analyze/audit projections. */
+const DEFAULT_SAMPLE_LIMIT = 10;
+/** Normalize repeatable or comma-separated id options into a flat list. */
+function normalizeIdList(raw) {
+    if (raw === undefined)
+        return [];
+    return (Array.isArray(raw) ? raw : [raw])
+        .flatMap((value) => value.split(","))
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+}
+/** Validate the graph subcommand and its positional-id requirements. */
+export function parseGraphSubcommand(raw, id, target) {
+    const candidate = raw.trim().toLowerCase();
+    if (!GRAPH_SUBCOMMAND_VALUES.includes(candidate)) {
+        throw new PmCliError(`Invalid graph subcommand "${raw}". Use one of: ${GRAPH_SUBCOMMAND_VALUES.join(", ")}.`, EXIT_CODE.USAGE);
+    }
+    const subcommand = candidate;
+    if (ROOTED_SUBCOMMANDS.has(subcommand) && !id?.trim()) {
+        throw new PmCliError(`graph ${subcommand} requires an item id.`, EXIT_CODE.USAGE);
+    }
+    if (subcommand === "paths" && !target?.trim()) {
+        throw new PmCliError("graph paths requires a source and a target item id.", EXIT_CODE.USAGE);
+    }
+    return subcommand;
+}
+/**
+ * Re-throw graph-kernel semantic option misuse (non-family kind, unknown
+ * cursor, non-transitive redundancy kind) as a usage error carrying the
+ * original explanation instead of an opaque crash.
+ */
+function rethrowGraphUsage(error) {
+    if (error instanceof TypeError)
+        throw new PmCliError(error.message, EXIT_CODE.USAGE);
+    throw error;
+}
+/** Convert traversal metadata into the shared cost/truncation projection. */
+function projectQueryMeta(meta) {
+    return {
+        truncated: meta.truncated,
+        cost: {
+            visited_nodes: meta.visitedNodes,
+            inspected_edges: meta.inspectedEdges,
+        },
+    };
+}
+/** Resolve one item id case-insensitively against the assembled graph. */
+function canonicalizeGraphId(assembly, raw) {
+    const wanted = raw.trim().toLowerCase();
+    for (const detail of assembly.details) {
+        if (detail.id.trim().toLowerCase() === wanted &&
+            !assembly.missingIdSet.has(detail.id.toLowerCase())) {
+            return detail.id;
+        }
+    }
+    throw new PmCliError(`Item ${raw} not found`, EXIT_CODE.NOT_FOUND);
+}
+/** Execute one transitive traversal subcommand over the assembled graph. */
+function runGraphTraversal(subcommand, root, invocation) {
+    const walk = {
+        ancestors: hierarchyAncestors,
+        descendants: hierarchyDescendants,
+        predecessors: orderingPredecessors,
+        successors: orderingSuccessors,
+    }[subcommand];
+    let result;
+    try {
+        result = walk(invocation.assembly.graph, root, {
+            ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),
+            ...(invocation.maxDepth === undefined
+                ? {}
+                : { maxDepth: invocation.maxDepth }),
+            ...(invocation.limit === undefined ? {} : { limit: invocation.limit }),
+            ...(invocation.after === undefined ? {} : { after: invocation.after }),
+        });
+    }
+    catch (error) {
+        rethrowGraphUsage(error);
+    }
+    const meta = projectQueryMeta(result.meta);
+    return {
+        subcommand,
+        root,
+        count: result.value.length,
+        ...meta,
+        ...(result.meta.nextCursor === undefined
+            ? {}
+            : { next_cursor: result.meta.nextCursor }),
+        ...(invocation.summary ? {} : { ids: result.value }),
+    };
+}
+/** Execute the bounded simple-path enumeration subcommand. */
+function runGraphPaths(root, target, invocation) {
+    const result = enumerateRelationshipPaths(invocation.assembly.graph, root, target, {
+        direction: invocation.direction,
+        ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),
+        ...(invocation.maxDepth === undefined
+            ? {}
+            : { maxDepth: invocation.maxDepth }),
+        ...(invocation.maxPaths === undefined
+            ? {}
+            : { maxPaths: invocation.maxPaths }),
+    });
+    return {
+        subcommand: "paths",
+        root,
+        target,
+        direction: invocation.direction,
+        count: result.value.length,
+        ...projectQueryMeta(result.meta),
+        ...(invocation.summary
+            ? {}
+            : {
+                paths: result.value.map((path) => ({
+                    nodes: path.nodes,
+                    kinds: path.edges.map((edge) => edge.kind),
+                    length: path.length,
+                })),
+            }),
+    };
+}
+/** Execute the bounded blast-radius impact subcommand. */
+function runGraphImpact(root, invocation) {
+    const analysis = analyzeGraphImpact(invocation.assembly.graph, root, {
+        direction: invocation.direction,
+        ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),
+        ...(invocation.maxDepth === undefined
+            ? {}
+            : { maxDepth: invocation.maxDepth }),
+        ...(invocation.limit === undefined ? {} : { limit: invocation.limit }),
+    });
+    return {
+        subcommand: "impact",
+        root,
+        direction: invocation.direction,
+        count: analysis.affected.length,
+        truncated: analysis.truncated,
+        cost: {
+            visited_nodes: analysis.cost.visitedNodes,
+            inspected_edges: analysis.cost.inspectedEdges,
+        },
+        ...(invocation.summary ? {} : { affected: analysis.affected }),
+    };
+}
+/** Execute the workspace-wide execution and knowledge analytics subcommand. */
+function runGraphAnalyze(invocation) {
+    const graph = invocation.assembly.graph;
+    const sampleLimit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;
+    const execution = analyzeRelationshipExecution(graph, {
+        registry: graph.registry(),
+    });
+    const knowledge = analyzeKnowledgeGraph(graph);
+    return {
+        subcommand: "analyze",
+        node_count: graph.nodes().length,
+        edge_count: graph.edges().length,
+        sample_limit: sampleLimit,
+        execution: {
+            acyclic: execution.acyclic,
+            ordered_node_count: execution.order.length,
+            layer_count: execution.layers.length,
+            frontier_count: execution.frontier.length,
+            critical_path_length: execution.criticalPathLength,
+            cycle_count: execution.cycles.length,
+            ...(invocation.summary
+                ? {}
+                : {
+                    frontier: execution.frontier.slice(0, sampleLimit),
+                    critical_path: execution.criticalPath.slice(0, sampleLimit),
+                    cycles: execution.cycles.slice(0, sampleLimit),
+                }),
+        },
+        knowledge: {
+            component_count: knowledge.components.length,
+            largest_component_size: knowledge.components[0]?.length ?? 0,
+            orphan_count: knowledge.orphans.length,
+            ...(invocation.summary
+                ? {}
+                : {
+                    orphans: knowledge.orphans.slice(0, sampleLimit),
+                    hubs: knowledge.hubs.slice(0, sampleLimit),
+                }),
+        },
+    };
+}
+/** Execute the governance-audit subcommand over the assembled graph. */
+function runGraphAudit(invocation, isTerminal) {
+    const report = auditWorkspaceRelationshipGraph(invocation.assembly, {
+        isTerminal,
+        ...(invocation.sample === undefined
+            ? {}
+            : { maxSampleSize: invocation.sample }),
+        ...(invocation.exemptIsolates.length === 0
+            ? {}
+            : { exemptIsolates: invocation.exemptIsolates }),
+    });
+    const bySeverity = {};
+    const byCode = {};
+    for (const finding of report.findings) {
+        bySeverity[finding.severity] = (bySeverity[finding.severity] ?? 0) + 1;
+        byCode[finding.code] = (byCode[finding.code] ?? 0) + finding.count;
+    }
+    return {
+        subcommand: "audit",
+        finding_count: report.findings.length,
+        findings_by_severity: bySeverity,
+        findings_by_code: byCode,
+        profile: report.profile,
+        ...(invocation.summary ? {} : { findings: report.findings }),
+    };
+}
+/** Execute the deterministic community-detection subcommand. */
+function runGraphCommunities(invocation) {
+    const sampleLimit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;
+    const result = detectRelationshipCommunities(invocation.assembly.graph, {
+        ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),
+    });
+    const analysis = result.value;
+    return {
+        subcommand: "communities",
+        community_count: analysis.communities.length,
+        largest_community_size: analysis.communities[0]?.size ?? 0,
+        iterations: analysis.iterations,
+        converged: analysis.converged,
+        truncated: !analysis.converged || analysis.communities.length > sampleLimit,
+        cost: {
+            visited_nodes: result.meta.visitedNodes,
+            inspected_edges: result.meta.inspectedEdges,
+        },
+        ...(invocation.summary
+            ? {}
+            : {
+                communities: analysis.communities
+                    .slice(0, sampleLimit)
+                    .map((community) => ({
+                    representative: community.representative,
+                    size: community.size,
+                    members: community.members.slice(0, sampleLimit),
+                })),
+            }),
+    };
+}
+/** Execute the transitive-redundancy scan subcommand. */
+function runGraphRedundancy(invocation) {
+    let result;
+    try {
+        result = findRedundantRelationshipEdges(invocation.assembly.graph, {
+            ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),
+            ...(invocation.maxDepth === undefined
+                ? {}
+                : { maxDepth: invocation.maxDepth }),
+            ...(invocation.limit === undefined ? {} : { limit: invocation.limit }),
+        });
+    }
+    catch (error) {
+        rethrowGraphUsage(error);
+    }
+    return {
+        subcommand: "redundancy",
+        redundant_count: result.value.length,
+        ...projectQueryMeta(result.meta),
+        ...(invocation.summary
+            ? {}
+            : {
+                redundant: result.value.map((row) => ({
+                    source: row.edge.source,
+                    target: row.edge.target,
+                    kind: row.edge.kind,
+                    witness: row.witness,
+                })),
+            }),
+    };
+}
+/** Execute the dominator/bottleneck analysis subcommand. */
+function runGraphDominators(root, invocation) {
+    const limit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;
+    const result = computeRelationshipDominators(invocation.assembly.graph, root, {
+        direction: invocation.direction,
+        ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),
+        ...(invocation.maxDepth === undefined
+            ? {}
+            : { maxDepth: invocation.maxDepth }),
+    });
+    const bottlenecks = result.value.rows.filter((row) => row.dominatedCount > 0);
+    return {
+        subcommand: "dominators",
+        root,
+        direction: invocation.direction,
+        reachable_count: result.value.reachableCount,
+        bottleneck_count: bottlenecks.length,
+        truncated: result.meta.truncated || bottlenecks.length > limit,
+        cost: {
+            visited_nodes: result.meta.visitedNodes,
+            inspected_edges: result.meta.inspectedEdges,
+        },
+        ...(invocation.summary
+            ? {}
+            : {
+                bottlenecks: bottlenecks.slice(0, limit).map((row) => ({
+                    id: row.id,
+                    idom: row.idom,
+                    dominated_count: row.dominatedCount,
+                })),
+            }),
+    };
+}
+/** Execute the dry-run remediation planning subcommand. */
+function runGraphPlan(invocation, isTerminal) {
+    const limit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;
+    const plan = planRelationshipRemediation(invocation.assembly, {
+        isTerminal,
+        redundancyLimit: limit,
+        ...(invocation.sample === undefined
+            ? {}
+            : { maxSampleSize: invocation.sample }),
+        ...(invocation.exemptIsolates.length === 0
+            ? {}
+            : { exemptIsolates: invocation.exemptIsolates }),
+    });
+    const byOp = {};
+    const byCode = {};
+    for (const step of plan.steps) {
+        byOp[step.op] = (byOp[step.op] ?? 0) + 1;
+        byCode[step.code] = (byCode[step.code] ?? 0) + 1;
+    }
+    return {
+        subcommand: "plan",
+        step_count: plan.steps.length,
+        steps_by_op: byOp,
+        steps_by_code: byCode,
+        finding_count: plan.report.findings.length,
+        truncated: plan.truncated || plan.steps.length > limit,
+        cost: {
+            visited_nodes: plan.cost.visitedNodes,
+            inspected_edges: plan.cost.inspectedEdges,
+        },
+        ...(invocation.summary ? {} : { steps: plan.steps.slice(0, limit) }),
+    };
+}
+/** Build the deterministic memoization key covering every query-shaping input. */
+function buildGraphQueryKey(subcommand, root, pathsTarget, invocation) {
+    return JSON.stringify({
+        subcommand,
+        root: root ?? null,
+        target: pathsTarget ?? null,
+        kinds: invocation.kinds ?? null,
+        maxDepth: invocation.maxDepth ?? null,
+        limit: invocation.limit ?? null,
+        after: invocation.after ?? null,
+        direction: invocation.direction,
+        maxPaths: invocation.maxPaths ?? null,
+        sample: invocation.sample ?? null,
+        // The audit consumes exemptions as a case-insensitive set, so the key
+        // must not distinguish logically identical spellings or orderings.
+        exemptIsolates: [
+            ...new Set(invocation.exemptIsolates.map((id) => id.toLowerCase())),
+        ].sort(),
+        summary: invocation.summary,
+    });
+}
+/** Dispatch one parsed graph subcommand to its executor. */
+function executeGraphSubcommand(subcommand, root, pathsTarget, invocation, isTerminal) {
+    if (subcommand === "analyze")
+        return runGraphAnalyze(invocation);
+    if (subcommand === "audit")
+        return runGraphAudit(invocation, isTerminal);
+    if (subcommand === "plan")
+        return runGraphPlan(invocation, isTerminal);
+    if (subcommand === "communities")
+        return runGraphCommunities(invocation);
+    if (subcommand === "redundancy")
+        return runGraphRedundancy(invocation);
+    if (subcommand === "dominators")
+        return runGraphDominators(root, invocation);
+    if (subcommand === "paths")
+        return runGraphPaths(root, pathsTarget, invocation);
+    if (subcommand === "impact")
+        return runGraphImpact(root, invocation);
+    return runGraphTraversal(subcommand, root, invocation);
+}
+/** Implements run graph for the public runtime surface of this module. */
+export async function runGraph(subcommandRaw, id, target, options, global) {
+    const subcommand = parseGraphSubcommand(subcommandRaw, id, target);
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const settings = await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const items = await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema);
+    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const isTerminal = (status) => isTerminalStatus(status, statusRegistry);
+    const kinds = parseKinds(options.kind);
+    const lookup = workspaceGraphCache().lookup(pmRoot, computeWorkspaceGraphFingerprint(items, isTerminal), () => assembleWorkspaceRelationshipGraph(items, isTerminal));
+    const invocation = {
+        assembly: lookup.assembly,
+        ...(kinds === undefined ? {} : { kinds }),
+        maxDepth: parseMaxDepth(options.maxDepth),
+        limit: parsePositiveInteger(options.limit, "limit"),
+        after: options.after?.trim() || undefined,
+        direction: parseDirection(options.direction),
+        maxPaths: parsePositiveInteger(options.maxPaths, "max-paths"),
+        sample: parsePositiveInteger(options.sample, "sample"),
+        exemptIsolates: normalizeIdList(options.exemptIsolate),
+        summary: options.summary === true,
+    };
+    const root = ROOTED_SUBCOMMANDS.has(subcommand)
+        ? canonicalizeGraphId(invocation.assembly, id)
+        : undefined;
+    const pathsTarget = subcommand === "paths"
+        ? canonicalizeGraphId(invocation.assembly, target)
+        : undefined;
+    const memo = lookup.memoize(buildGraphQueryKey(subcommand, root, pathsTarget, invocation), () => executeGraphSubcommand(subcommand, root, pathsTarget, invocation, isTerminal));
+    return {
+        ...memo.value,
+        cache: {
+            fingerprint: lookup.fingerprint.slice(0, 12),
+            assembly: lookup.assemblyReused ? "hit" : "miss",
+            result: memo.reused ? "hit" : "miss",
+        },
+    };
+}
+//# sourceMappingURL=run.js.map
+//# debugId=3d4c5f7b-bcd4-569b-8bea-b06cc9f115e5

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sources":["sdk/graph/run.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/graph/run\n *\n * Workspace-facing `pm graph` runner: one thin orchestrator that loads the\n * tracker once, resolves the fingerprint-keyed workspace assembly through the\n * shared graph cache, and dispatches bounded traversal, path, impact,\n * analytics, governance-audit, and remediation-planning queries through the\n * public graph toolkit. Every projection is counts-first, deterministic, and\n * carries explicit cost, truncation, and cache metadata so agents can budget\n * follow-up reads without re-scanning the workspace; identical repeated\n * queries in long-lived hosts are answered from the memoized snapshot.\n */\nimport { getActiveExtensionRegistrations } from \"../../core/extensions/index.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { isTerminalStatus } from \"../../core/item/status.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { resolveRuntimeStatusRegistry } from \"../../core/schema/runtime-schema.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { listAllItemMetadataLight } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport {\n  parseDirection,\n  parseKinds,\n  parseMaxDepth,\n  parsePositiveInteger,\n} from \"../dependencies.js\";\nimport {\n  analyzeGraphImpact,\n  analyzeKnowledgeGraph,\n  analyzeRelationshipExecution,\n} from \"../relationship-analytics.js\";\nimport type { RelationshipQueryMeta } from \"../relationships.js\";\nimport {\n  computeRelationshipDominators,\n  detectRelationshipCommunities,\n  findRedundantRelationshipEdges,\n} from \"./analytics.js\";\nimport {\n  assembleWorkspaceRelationshipGraph,\n  type WorkspaceRelationshipAssembly,\n} from \"./assembly.js\";\nimport {\n  computeWorkspaceGraphFingerprint,\n  workspaceGraphCache,\n  type GraphCacheMetadata,\n} from \"./cache.js\";\nimport {\n  auditWorkspaceRelationshipGraph,\n  type RelationshipAuditReport,\n} from \"./governance.js\";\nimport {\n  planRelationshipRemediation,\n  type RelationshipRemediationStep,\n} from \"./remediation.js\";\nimport {\n  enumerateRelationshipPaths,\n  hierarchyAncestors,\n  hierarchyDescendants,\n  orderingPredecessors,\n  orderingSuccessors,\n} from \"./traversal.js\";\n\nimport {\n  GRAPH_SUBCOMMAND_VALUES,\n  type GraphSubcommand,\n} from \"../cli-contracts/enum-contracts.js\";\n\nexport { GRAPH_SUBCOMMAND_VALUES, type GraphSubcommand };\n\n/** Graph subcommands that require a root item id. */\nconst ROOTED_SUBCOMMANDS = new Set<GraphSubcommand>([\n  \"ancestors\",\n  \"descendants\",\n  \"predecessors\",\n  \"successors\",\n  \"paths\",\n  \"impact\",\n  \"dominators\",\n]);\n\n/** Default bounded sample rows returned by analyze/audit projections. */\nconst DEFAULT_SAMPLE_LIMIT = 10;\n\n/** Documents the graph command options payload exchanged by command, SDK, and package integrations. */\nexport interface GraphCommandOptions {\n  /** Restricts traversal to registered relationship kinds (repeatable or comma-separated). */\n  kind?: string | string[];\n  /** Maximum traversal depth as a non-negative integer. */\n  maxDepth?: string | number;\n  /** Maximum returned rows per bounded collection. */\n  limit?: string | number;\n  /** Resume a traversal after this previously returned node id. */\n  after?: string;\n  /** Edge orientation for paths and impact queries (outgoing, incoming, or both). */\n  direction?: string;\n  /** Maximum enumerated paths for the paths subcommand. */\n  maxPaths?: string | number;\n  /** Maximum evidence sample entries per audit finding. */\n  sample?: string | number;\n  /** Item ids treated as explicitly valid isolates by the audit. */\n  exemptIsolate?: string | string[];\n  /** Return counts-first envelopes without row collections. */\n  summary?: boolean;\n}\n\n/** Cost metadata attached to every graph query projection. */\nexport interface GraphQueryCost {\n  /** Nodes expanded while answering the query. */\n  visited_nodes: number;\n  /** Edges inspected while answering the query. */\n  inspected_edges: number;\n}\n\n/** Result envelope for the transitive traversal subcommands. */\nexport interface GraphTraversalResult {\n  /** Executed graph subcommand. */\n  subcommand: \"ancestors\" | \"descendants\" | \"predecessors\" | \"successors\";\n  /** Canonical root item id. */\n  root: string;\n  /** Total emitted node ids before summary suppression. */\n  count: number;\n  /** Whether configured bounds omitted reachable work. */\n  truncated: boolean;\n  /** Cursor resuming emission after the last returned node. */\n  next_cursor?: string;\n  /** Query cost metadata. */\n  cost: GraphQueryCost;\n  /** Emitted node ids in deterministic breadth-first order; absent with summary. */\n  ids?: string[];\n  /** Cache observability for this invocation. */\n  cache?: GraphCacheMetadata;\n}\n\n/** One enumerated path projected with relationship kinds instead of raw edges. */\nexport interface GraphPathRow {\n  /** Ordered node ids from source to target inclusive. */\n  nodes: string[];\n  /** Relationship kind of each traversed edge, in path order. */\n  kinds: string[];\n  /** Number of edges in the path. */\n  length: number;\n}\n\n/** Result envelope for the paths subcommand. */\nexport interface GraphPathsResult {\n  /** Executed graph subcommand. */\n  subcommand: \"paths\";\n  /** Canonical source item id. */\n  root: string;\n  /** Canonical target item id. */\n  target: string;\n  /** Traversal orientation used for the enumeration. */\n  direction: string;\n  /** Total enumerated paths before summary suppression. */\n  count: number;\n  /** Whether depth, path-count, or safety bounds stopped the search early. */\n  truncated: boolean;\n  /** Query cost metadata. */\n  cost: GraphQueryCost;\n  /** Enumerated paths, shortest first; absent with summary. */\n  paths?: GraphPathRow[];\n  /** Cache observability for this invocation. */\n  cache?: GraphCacheMetadata;\n}\n\n/** One affected item row in an impact projection. */\nexport interface GraphImpactRow {\n  /** Affected item id. */\n  id: string;\n  /** Shortest relationship distance from the root. */\n  distance: number;\n  /** Exact node path explaining why the item is affected. */\n  path: string[];\n}\n\n/** Result envelope for the impact subcommand. */\nexport interface GraphImpactResult {\n  /** Executed graph subcommand. */\n  subcommand: \"impact\";\n  /** Canonical impact-origin item id. */\n  root: string;\n  /** Traversal orientation used for the blast-radius walk. */\n  direction: string;\n  /** Total affected items before summary suppression. */\n  count: number;\n  /** Whether configured bounds omitted reachable work. */\n  truncated: boolean;\n  /** Query cost metadata. */\n  cost: GraphQueryCost;\n  /** Affected item rows ordered by discovery; absent with summary. */\n  affected?: GraphImpactRow[];\n  /** Cache observability for this invocation. */\n  cache?: GraphCacheMetadata;\n}\n\n/** Bounded execution-graph projection inside an analyze result. */\nexport interface GraphExecutionSummary {\n  /** Whether the order-bearing graph is acyclic. */\n  acyclic: boolean;\n  /** Nodes participating in the topological order. */\n  ordered_node_count: number;\n  /** Number of parallelizable topological layers. */\n  layer_count: number;\n  /** Total items with no open prerequisites. */\n  frontier_count: number;\n  /** Bounded prerequisite-free sample; absent with summary. */\n  frontier?: string[];\n  /** Edge count of the longest execution path. */\n  critical_path_length: number;\n  /** Longest deterministic execution path; absent with summary. */\n  critical_path?: string[];\n  /** Total genuine ordering cycles. */\n  cycle_count: number;\n  /** Bounded ordering-cycle sample; absent with summary. */\n  cycles?: string[][];\n}\n\n/** Bounded knowledge-graph projection inside an analyze result. */\nexport interface GraphKnowledgeSummary {\n  /** Total weakly connected components. */\n  component_count: number;\n  /** Node count of the largest component. */\n  largest_component_size: number;\n  /** Total nodes without any relationship edges. */\n  orphan_count: number;\n  /** Bounded orphan sample; absent with summary. */\n  orphans?: string[];\n  /** Bounded maximum-degree hubs; absent with summary. */\n  hubs?: { id: string; degree: number }[];\n}\n\n/** Result envelope for the analyze subcommand. */\nexport interface GraphAnalyzeResult {\n  /** Executed graph subcommand. */\n  subcommand: \"analyze\";\n  /** Total indexed graph nodes. */\n  node_count: number;\n  /** Total deduplicated graph edges. */\n  edge_count: number;\n  /** Bound applied to every sample collection. */\n  sample_limit: number;\n  /** Execution-order analytics over registered ordering kinds. */\n  execution: GraphExecutionSummary;\n  /** Structural analytics over every stored edge. */\n  knowledge: GraphKnowledgeSummary;\n  /** Cache observability for this invocation. */\n  cache?: GraphCacheMetadata;\n}\n\n/** Result envelope for the audit subcommand. */\nexport interface GraphAuditResult {\n  /** Executed graph subcommand. */\n  subcommand: \"audit\";\n  /** Total audit findings. */\n  finding_count: number;\n  /** Finding counts keyed by severity. */\n  findings_by_severity: Record<string, number>;\n  /** Affected-subject counts keyed by finding code. */\n  findings_by_code: Record<string, number>;\n  /** Structural coverage metrics computed during the audit. */\n  profile: RelationshipAuditReport[\"profile\"];\n  /** Ordered findings with bounded evidence samples; absent with summary. */\n  findings?: RelationshipAuditReport[\"findings\"];\n  /** Cache observability for this invocation. */\n  cache?: GraphCacheMetadata;\n}\n\n/** One bounded community row projected by the communities subcommand. */\nexport interface GraphCommunityRow {\n  /** Lexicographically smallest member id, naming the community. */\n  representative: string;\n  /** Total member count before sampling. */\n  size: number;\n  /** Bounded sorted member sample. */\n  members: string[];\n}\n\n/** Result envelope for the communities subcommand. */\nexport interface GraphCommunitiesResult {\n  /** Executed graph subcommand. */\n  subcommand: \"communities\";\n  /** Total detected communities meeting the size floor. */\n  community_count: number;\n  /** Member count of the largest community. */\n  largest_community_size: number;\n  /** Label-propagation sweeps executed. */\n  iterations: number;\n  /** Whether labels stabilized before the iteration bound. */\n  converged: boolean;\n  /** Whether the iteration bound stopped propagation early or the sample bound omitted rows. */\n  truncated: boolean;\n  /** Query cost metadata. */\n  cost: GraphQueryCost;\n  /** Bounded community rows, largest first; absent with summary. */\n  communities?: GraphCommunityRow[];\n  /** Cache observability for this invocation. */\n  cache?: GraphCacheMetadata;\n}\n\n/** One redundant stored edge projected with its witness path. */\nexport interface GraphRedundancyRow {\n  /** Stored edge source id. */\n  source: string;\n  /** Stored edge target id. */\n  target: string;\n  /** Stored relationship kind. */\n  kind: string;\n  /** Semantic-orientation node path proving the edge is implied. */\n  witness: string[];\n}\n\n/** Result envelope for the redundancy subcommand. */\nexport interface GraphRedundancyResult {\n  /** Executed graph subcommand. */\n  subcommand: \"redundancy\";\n  /** Total redundant edges found within configured bounds. */\n  redundant_count: number;\n  /** Whether the row limit omitted further redundant edges. */\n  truncated: boolean;\n  /** Query cost metadata. */\n  cost: GraphQueryCost;\n  /** Redundant edge rows in deterministic scan order; absent with summary. */\n  redundant?: GraphRedundancyRow[];\n  /** Cache observability for this invocation. */\n  cache?: GraphCacheMetadata;\n}\n\n/** One structural bottleneck row projected by the dominators subcommand. */\nexport interface GraphDominatorRow {\n  /** Bottleneck node id. */\n  id: string;\n  /** Immediate dominator appearing on every root-to-node path. */\n  idom: string;\n  /** Reachable nodes strictly gated by this node. */\n  dominated_count: number;\n}\n\n/** Result envelope for the dominators subcommand. */\nexport interface GraphDominatorsResult {\n  /** Executed graph subcommand. */\n  subcommand: \"dominators\";\n  /** Canonical analyzed root id. */\n  root: string;\n  /** Traversal orientation used for reachability. */\n  direction: string;\n  /** Reachable node count including the root. */\n  reachable_count: number;\n  /** Total nodes gating at least one other reachable node. */\n  bottleneck_count: number;\n  /** Whether the depth bound cut reachability or the row limit omitted bottleneck rows. */\n  truncated: boolean;\n  /** Query cost metadata. */\n  cost: GraphQueryCost;\n  /** Bounded bottleneck rows, most-gating first; absent with summary. */\n  bottlenecks?: GraphDominatorRow[];\n  /** Cache observability for this invocation. */\n  cache?: GraphCacheMetadata;\n}\n\n/** Result envelope for the dry-run remediation planning subcommand. */\nexport interface GraphPlanResult {\n  /** Executed graph subcommand. */\n  subcommand: \"plan\";\n  /** Total derived remediation proposals before row bounding. */\n  step_count: number;\n  /** Proposal counts keyed by operation family. */\n  steps_by_op: Record<string, number>;\n  /** Proposal counts keyed by policy code. */\n  steps_by_code: Record<string, number>;\n  /** Total governance-audit findings the plan was derived from. */\n  finding_count: number;\n  /** Whether sample, scan, or row bounds omitted derivable proposals. */\n  truncated: boolean;\n  /** Query cost metadata. */\n  cost: GraphQueryCost;\n  /** Bounded proposal rows in audit severity order; absent with summary. */\n  steps?: RelationshipRemediationStep[];\n  /** Cache observability for this invocation. */\n  cache?: GraphCacheMetadata;\n}\n\n/** Union of every graph subcommand result envelope. */\nexport type GraphResult =\n  | GraphTraversalResult\n  | GraphPathsResult\n  | GraphImpactResult\n  | GraphAnalyzeResult\n  | GraphAuditResult\n  | GraphCommunitiesResult\n  | GraphRedundancyResult\n  | GraphDominatorsResult\n  | GraphPlanResult;\n\n/** Fully parsed graph invocation shared by the subcommand executors. */\ninterface GraphInvocation {\n  /** Assembled workspace relationship graph and node details. */\n  assembly: WorkspaceRelationshipAssembly;\n  /** Canonical registered kind filters, when provided. */\n  kinds?: string[];\n  /** Parsed non-negative depth bound. */\n  maxDepth?: number;\n  /** Parsed positive row bound. */\n  limit?: number;\n  /** Traversal resume cursor. */\n  after?: string;\n  /** Validated traversal orientation. */\n  direction: \"outgoing\" | \"incoming\" | \"both\";\n  /** Parsed positive path-count bound. */\n  maxPaths?: number;\n  /** Parsed positive audit sample bound. */\n  sample?: number;\n  /** Normalized audit isolate exemptions. */\n  exemptIsolates: string[];\n  /** Whether row collections are suppressed. */\n  summary: boolean;\n}\n\n/** Normalize repeatable or comma-separated id options into a flat list. */\nfunction normalizeIdList(raw: string | string[] | undefined): string[] {\n  if (raw === undefined) return [];\n  return (Array.isArray(raw) ? raw : [raw])\n    .flatMap((value) => value.split(\",\"))\n    .map((value) => value.trim())\n    .filter((value) => value.length > 0);\n}\n\n/** Validate the graph subcommand and its positional-id requirements. */\nexport function parseGraphSubcommand(\n  raw: string,\n  id: string | undefined,\n  target: string | undefined,\n): GraphSubcommand {\n  const candidate = raw.trim().toLowerCase();\n  if (!(GRAPH_SUBCOMMAND_VALUES as readonly string[]).includes(candidate)) {\n    throw new PmCliError(\n      `Invalid graph subcommand \"${raw}\". Use one of: ${GRAPH_SUBCOMMAND_VALUES.join(\", \")}.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  const subcommand = candidate as GraphSubcommand;\n  if (ROOTED_SUBCOMMANDS.has(subcommand) && !id?.trim()) {\n    throw new PmCliError(\n      `graph ${subcommand} requires an item id.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  if (subcommand === \"paths\" && !target?.trim()) {\n    throw new PmCliError(\n      \"graph paths requires a source and a target item id.\",\n      EXIT_CODE.USAGE,\n    );\n  }\n  return subcommand;\n}\n\n/**\n * Re-throw graph-kernel semantic option misuse (non-family kind, unknown\n * cursor, non-transitive redundancy kind) as a usage error carrying the\n * original explanation instead of an opaque crash.\n */\nfunction rethrowGraphUsage(error: unknown): never {\n  if (error instanceof TypeError)\n    throw new PmCliError(error.message, EXIT_CODE.USAGE);\n  throw error;\n}\n\n/** Convert traversal metadata into the shared cost/truncation projection. */\nfunction projectQueryMeta(meta: RelationshipQueryMeta): {\n  truncated: boolean;\n  cost: GraphQueryCost;\n} {\n  return {\n    truncated: meta.truncated,\n    cost: {\n      visited_nodes: meta.visitedNodes,\n      inspected_edges: meta.inspectedEdges,\n    },\n  };\n}\n\n/** Resolve one item id case-insensitively against the assembled graph. */\nfunction canonicalizeGraphId(\n  assembly: WorkspaceRelationshipAssembly,\n  raw: string,\n): string {\n  const wanted = raw.trim().toLowerCase();\n  for (const detail of assembly.details) {\n    if (\n      detail.id.trim().toLowerCase() === wanted &&\n      !assembly.missingIdSet.has(detail.id.toLowerCase())\n    ) {\n      return detail.id;\n    }\n  }\n  throw new PmCliError(`Item ${raw} not found`, EXIT_CODE.NOT_FOUND);\n}\n\n/** Execute one transitive traversal subcommand over the assembled graph. */\nfunction runGraphTraversal(\n  subcommand: \"ancestors\" | \"descendants\" | \"predecessors\" | \"successors\",\n  root: string,\n  invocation: GraphInvocation,\n): GraphTraversalResult {\n  const walk = {\n    ancestors: hierarchyAncestors,\n    descendants: hierarchyDescendants,\n    predecessors: orderingPredecessors,\n    successors: orderingSuccessors,\n  }[subcommand];\n  let result;\n  try {\n    result = walk(invocation.assembly.graph, root, {\n      ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),\n      ...(invocation.maxDepth === undefined\n        ? {}\n        : { maxDepth: invocation.maxDepth }),\n      ...(invocation.limit === undefined ? {} : { limit: invocation.limit }),\n      ...(invocation.after === undefined ? {} : { after: invocation.after }),\n    });\n  } catch (error) {\n    rethrowGraphUsage(error);\n  }\n  const meta = projectQueryMeta(result.meta);\n  return {\n    subcommand,\n    root,\n    count: result.value.length,\n    ...meta,\n    ...(result.meta.nextCursor === undefined\n      ? {}\n      : { next_cursor: result.meta.nextCursor }),\n    ...(invocation.summary ? {} : { ids: result.value }),\n  };\n}\n\n/** Execute the bounded simple-path enumeration subcommand. */\nfunction runGraphPaths(\n  root: string,\n  target: string,\n  invocation: GraphInvocation,\n): GraphPathsResult {\n  const result = enumerateRelationshipPaths(\n    invocation.assembly.graph,\n    root,\n    target,\n    {\n      direction: invocation.direction,\n      ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),\n      ...(invocation.maxDepth === undefined\n        ? {}\n        : { maxDepth: invocation.maxDepth }),\n      ...(invocation.maxPaths === undefined\n        ? {}\n        : { maxPaths: invocation.maxPaths }),\n    },\n  );\n  return {\n    subcommand: \"paths\",\n    root,\n    target,\n    direction: invocation.direction,\n    count: result.value.length,\n    ...projectQueryMeta(result.meta),\n    ...(invocation.summary\n      ? {}\n      : {\n          paths: result.value.map((path) => ({\n            nodes: path.nodes,\n            kinds: path.edges.map((edge) => edge.kind),\n            length: path.length,\n          })),\n        }),\n  };\n}\n\n/** Execute the bounded blast-radius impact subcommand. */\nfunction runGraphImpact(\n  root: string,\n  invocation: GraphInvocation,\n): GraphImpactResult {\n  const analysis = analyzeGraphImpact(invocation.assembly.graph, root, {\n    direction: invocation.direction,\n    ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),\n    ...(invocation.maxDepth === undefined\n      ? {}\n      : { maxDepth: invocation.maxDepth }),\n    ...(invocation.limit === undefined ? {} : { limit: invocation.limit }),\n  });\n  return {\n    subcommand: \"impact\",\n    root,\n    direction: invocation.direction,\n    count: analysis.affected.length,\n    truncated: analysis.truncated,\n    cost: {\n      visited_nodes: analysis.cost.visitedNodes,\n      inspected_edges: analysis.cost.inspectedEdges,\n    },\n    ...(invocation.summary ? {} : { affected: analysis.affected }),\n  };\n}\n\n/** Execute the workspace-wide execution and knowledge analytics subcommand. */\nfunction runGraphAnalyze(invocation: GraphInvocation): GraphAnalyzeResult {\n  const graph = invocation.assembly.graph;\n  const sampleLimit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;\n  const execution = analyzeRelationshipExecution(graph, {\n    registry: graph.registry(),\n  });\n  const knowledge = analyzeKnowledgeGraph(graph);\n  return {\n    subcommand: \"analyze\",\n    node_count: graph.nodes().length,\n    edge_count: graph.edges().length,\n    sample_limit: sampleLimit,\n    execution: {\n      acyclic: execution.acyclic,\n      ordered_node_count: execution.order.length,\n      layer_count: execution.layers.length,\n      frontier_count: execution.frontier.length,\n      critical_path_length: execution.criticalPathLength,\n      cycle_count: execution.cycles.length,\n      ...(invocation.summary\n        ? {}\n        : {\n            frontier: execution.frontier.slice(0, sampleLimit),\n            critical_path: execution.criticalPath.slice(0, sampleLimit),\n            cycles: execution.cycles.slice(0, sampleLimit),\n          }),\n    },\n    knowledge: {\n      component_count: knowledge.components.length,\n      largest_component_size: knowledge.components[0]?.length ?? 0,\n      orphan_count: knowledge.orphans.length,\n      ...(invocation.summary\n        ? {}\n        : {\n            orphans: knowledge.orphans.slice(0, sampleLimit),\n            hubs: knowledge.hubs.slice(0, sampleLimit),\n          }),\n    },\n  };\n}\n\n/** Execute the governance-audit subcommand over the assembled graph. */\nfunction runGraphAudit(\n  invocation: GraphInvocation,\n  isTerminal: (status: string) => boolean,\n): GraphAuditResult {\n  const report = auditWorkspaceRelationshipGraph(invocation.assembly, {\n    isTerminal,\n    ...(invocation.sample === undefined\n      ? {}\n      : { maxSampleSize: invocation.sample }),\n    ...(invocation.exemptIsolates.length === 0\n      ? {}\n      : { exemptIsolates: invocation.exemptIsolates }),\n  });\n  const bySeverity: Record<string, number> = {};\n  const byCode: Record<string, number> = {};\n  for (const finding of report.findings) {\n    bySeverity[finding.severity] = (bySeverity[finding.severity] ?? 0) + 1;\n    byCode[finding.code] = (byCode[finding.code] ?? 0) + finding.count;\n  }\n  return {\n    subcommand: \"audit\",\n    finding_count: report.findings.length,\n    findings_by_severity: bySeverity,\n    findings_by_code: byCode,\n    profile: report.profile,\n    ...(invocation.summary ? {} : { findings: report.findings }),\n  };\n}\n\n/** Execute the deterministic community-detection subcommand. */\nfunction runGraphCommunities(\n  invocation: GraphInvocation,\n): GraphCommunitiesResult {\n  const sampleLimit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;\n  const result = detectRelationshipCommunities(invocation.assembly.graph, {\n    ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),\n  });\n  const analysis = result.value;\n  return {\n    subcommand: \"communities\",\n    community_count: analysis.communities.length,\n    largest_community_size: analysis.communities[0]?.size ?? 0,\n    iterations: analysis.iterations,\n    converged: analysis.converged,\n    truncated: !analysis.converged || analysis.communities.length > sampleLimit,\n    cost: {\n      visited_nodes: result.meta.visitedNodes,\n      inspected_edges: result.meta.inspectedEdges,\n    },\n    ...(invocation.summary\n      ? {}\n      : {\n          communities: analysis.communities\n            .slice(0, sampleLimit)\n            .map((community) => ({\n              representative: community.representative,\n              size: community.size,\n              members: community.members.slice(0, sampleLimit),\n            })),\n        }),\n  };\n}\n\n/** Execute the transitive-redundancy scan subcommand. */\nfunction runGraphRedundancy(\n  invocation: GraphInvocation,\n): GraphRedundancyResult {\n  let result;\n  try {\n    result = findRedundantRelationshipEdges(invocation.assembly.graph, {\n      ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),\n      ...(invocation.maxDepth === undefined\n        ? {}\n        : { maxDepth: invocation.maxDepth }),\n      ...(invocation.limit === undefined ? {} : { limit: invocation.limit }),\n    });\n  } catch (error) {\n    rethrowGraphUsage(error);\n  }\n  return {\n    subcommand: \"redundancy\",\n    redundant_count: result.value.length,\n    ...projectQueryMeta(result.meta),\n    ...(invocation.summary\n      ? {}\n      : {\n          redundant: result.value.map((row) => ({\n            source: row.edge.source,\n            target: row.edge.target,\n            kind: row.edge.kind,\n            witness: row.witness,\n          })),\n        }),\n  };\n}\n\n/** Execute the dominator/bottleneck analysis subcommand. */\nfunction runGraphDominators(\n  root: string,\n  invocation: GraphInvocation,\n): GraphDominatorsResult {\n  const limit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;\n  const result = computeRelationshipDominators(\n    invocation.assembly.graph,\n    root,\n    {\n      direction: invocation.direction,\n      ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),\n      ...(invocation.maxDepth === undefined\n        ? {}\n        : { maxDepth: invocation.maxDepth }),\n    },\n  );\n  const bottlenecks = result.value.rows.filter((row) => row.dominatedCount > 0);\n  return {\n    subcommand: \"dominators\",\n    root,\n    direction: invocation.direction,\n    reachable_count: result.value.reachableCount,\n    bottleneck_count: bottlenecks.length,\n    truncated: result.meta.truncated || bottlenecks.length > limit,\n    cost: {\n      visited_nodes: result.meta.visitedNodes,\n      inspected_edges: result.meta.inspectedEdges,\n    },\n    ...(invocation.summary\n      ? {}\n      : {\n          bottlenecks: bottlenecks.slice(0, limit).map((row) => ({\n            id: row.id,\n            idom: row.idom,\n            dominated_count: row.dominatedCount,\n          })),\n        }),\n  };\n}\n\n/** Execute the dry-run remediation planning subcommand. */\nfunction runGraphPlan(\n  invocation: GraphInvocation,\n  isTerminal: (status: string) => boolean,\n): GraphPlanResult {\n  const limit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;\n  const plan = planRelationshipRemediation(invocation.assembly, {\n    isTerminal,\n    redundancyLimit: limit,\n    ...(invocation.sample === undefined\n      ? {}\n      : { maxSampleSize: invocation.sample }),\n    ...(invocation.exemptIsolates.length === 0\n      ? {}\n      : { exemptIsolates: invocation.exemptIsolates }),\n  });\n  const byOp: Record<string, number> = {};\n  const byCode: Record<string, number> = {};\n  for (const step of plan.steps) {\n    byOp[step.op] = (byOp[step.op] ?? 0) + 1;\n    byCode[step.code] = (byCode[step.code] ?? 0) + 1;\n  }\n  return {\n    subcommand: \"plan\",\n    step_count: plan.steps.length,\n    steps_by_op: byOp,\n    steps_by_code: byCode,\n    finding_count: plan.report.findings.length,\n    truncated: plan.truncated || plan.steps.length > limit,\n    cost: {\n      visited_nodes: plan.cost.visitedNodes,\n      inspected_edges: plan.cost.inspectedEdges,\n    },\n    ...(invocation.summary ? {} : { steps: plan.steps.slice(0, limit) }),\n  };\n}\n\n/** Build the deterministic memoization key covering every query-shaping input. */\nfunction buildGraphQueryKey(\n  subcommand: GraphSubcommand,\n  root: string | undefined,\n  pathsTarget: string | undefined,\n  invocation: GraphInvocation,\n): string {\n  return JSON.stringify({\n    subcommand,\n    root: root ?? null,\n    target: pathsTarget ?? null,\n    kinds: invocation.kinds ?? null,\n    maxDepth: invocation.maxDepth ?? null,\n    limit: invocation.limit ?? null,\n    after: invocation.after ?? null,\n    direction: invocation.direction,\n    maxPaths: invocation.maxPaths ?? null,\n    sample: invocation.sample ?? null,\n    // The audit consumes exemptions as a case-insensitive set, so the key\n    // must not distinguish logically identical spellings or orderings.\n    exemptIsolates: [\n      ...new Set(invocation.exemptIsolates.map((id) => id.toLowerCase())),\n    ].sort(),\n    summary: invocation.summary,\n  });\n}\n\n/** Dispatch one parsed graph subcommand to its executor. */\nfunction executeGraphSubcommand(\n  subcommand: GraphSubcommand,\n  root: string | undefined,\n  pathsTarget: string | undefined,\n  invocation: GraphInvocation,\n  isTerminal: (status: string) => boolean,\n): GraphResult {\n  if (subcommand === \"analyze\") return runGraphAnalyze(invocation);\n  if (subcommand === \"audit\") return runGraphAudit(invocation, isTerminal);\n  if (subcommand === \"plan\") return runGraphPlan(invocation, isTerminal);\n  if (subcommand === \"communities\") return runGraphCommunities(invocation);\n  if (subcommand === \"redundancy\") return runGraphRedundancy(invocation);\n  if (subcommand === \"dominators\") return runGraphDominators(root!, invocation);\n  if (subcommand === \"paths\")\n    return runGraphPaths(root!, pathsTarget!, invocation);\n  if (subcommand === \"impact\") return runGraphImpact(root!, invocation);\n  return runGraphTraversal(subcommand, root!, invocation);\n}\n\n/** Implements run graph for the public runtime surface of this module. */\nexport async function runGraph(\n  subcommandRaw: string,\n  id: string | undefined,\n  target: string | undefined,\n  options: GraphCommandOptions,\n  global: GlobalOptions,\n): Promise<GraphResult> {\n  const subcommand = parseGraphSubcommand(subcommandRaw, id, target);\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(\n      `Tracker is not initialized at ${pmRoot}. Run pm init first.`,\n      EXIT_CODE.NOT_FOUND,\n    );\n  }\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(\n    settings,\n    getActiveExtensionRegistrations(),\n  );\n  const items = await listAllItemMetadataLight(\n    pmRoot,\n    settings.item_format,\n    typeRegistry.type_to_folder,\n    undefined,\n    settings.schema,\n  );\n  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  const isTerminal = (status: string): boolean =>\n    isTerminalStatus(status, statusRegistry);\n  const kinds = parseKinds(options.kind);\n  const lookup = workspaceGraphCache().lookup(\n    pmRoot,\n    computeWorkspaceGraphFingerprint(items, isTerminal),\n    () => assembleWorkspaceRelationshipGraph(items, isTerminal),\n  );\n  const invocation: GraphInvocation = {\n    assembly: lookup.assembly,\n    ...(kinds === undefined ? {} : { kinds }),\n    maxDepth: parseMaxDepth(options.maxDepth),\n    limit: parsePositiveInteger(options.limit, \"limit\"),\n    after: options.after?.trim() || undefined,\n    direction: parseDirection(options.direction),\n    maxPaths: parsePositiveInteger(options.maxPaths, \"max-paths\"),\n    sample: parsePositiveInteger(options.sample, \"sample\"),\n    exemptIsolates: normalizeIdList(options.exemptIsolate),\n    summary: options.summary === true,\n  };\n  const root = ROOTED_SUBCOMMANDS.has(subcommand)\n    ? canonicalizeGraphId(invocation.assembly, id!)\n    : undefined;\n  const pathsTarget =\n    subcommand === \"paths\"\n      ? canonicalizeGraphId(invocation.assembly, target!)\n      : undefined;\n  const memo = lookup.memoize(\n    buildGraphQueryKey(subcommand, root, pathsTarget, invocation),\n    () =>\n      executeGraphSubcommand(\n        subcommand,\n        root,\n        pathsTarget,\n        invocation,\n        isTerminal,\n      ),\n  );\n  return {\n    ...memo.value,\n    cache: {\n      fingerprint: lookup.fingerprint.slice(0, 12),\n      assembly: lookup.assemblyReused ? \"hit\" : \"miss\",\n      result: memo.reused ? \"hit\" : \"miss\",\n    },\n  };\n}\n"],"names":[],"mappings":"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","debugId":"3d4c5f7b-bcd4-569b-8bea-b06cc9f115e5"}

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

@@ -0,0 +1,77 @@
+/**
+ * @module sdk/graph/traversal
+ *
+ * Registry-semantics graph traversal primitives layered over the bounded
+ * relationship kernel: hierarchy walks (ancestors/descendants), execution-order
+ * walks (predecessors/successors), and bounded simple-path enumeration. Every
+ * query is deterministic, cancellable, resumable via an explicit cursor, and
+ * reports exact cost and truncation metadata so agents can budget follow-up
+ * calls without re-reading the workspace.
+ */
+import { RelationshipGraph, type RelationshipEdge, type RelationshipKindDefinition, type RelationshipQueryOptions, type RelationshipQueryResult } from "../relationships.js";
+/**
+ * Shared bounded-traversal controls extended with deterministic resumption.
+ * Semantic hierarchy and ordering orientation comes from the relationship-kind
+ * registry, so callers cannot supply the generic graph `direction` option.
+ */
+export interface GraphTraversalOptions extends Omit<RelationshipQueryOptions, "direction"> {
+    /**
+     * Resume emission after this previously returned node identifier. The
+     * traversal re-walks the same deterministic sequence and starts emitting
+     * after the cursor node; an identifier the sequence never reaches fails fast
+     * instead of silently returning an empty page.
+     */
+    after?: string;
+}
+/** One enumerated simple path between two nodes. */
+export interface RelationshipPath {
+    /** Ordered node identifiers from source to target inclusive. */
+    nodes: string[];
+    /** Edges connecting consecutive path nodes, in traversal order. */
+    edges: RelationshipEdge[];
+    /** Number of edges in the path. */
+    length: number;
+}
+/** Bounded-path enumeration controls. */
+export interface GraphPathOptions extends RelationshipQueryOptions {
+    /** Maximum number of returned paths; defaults to 5. */
+    maxPaths?: number;
+    /** Safety bound on expanded partial paths before truncation; defaults to 10000. */
+    maxVisitedPaths?: number;
+}
+/** Endpoint of a hierarchy edge that represents the structural parent. */
+export declare function hierarchyParentEndpoint(edge: RelationshipEdge, definition: RelationshipKindDefinition): string;
+/** Endpoint of an ordering edge that must finish first. */
+export declare function orderingPredecessorEndpoint(edge: RelationshipEdge, definition: RelationshipKindDefinition): string;
+/**
+ * Return the bounded transitive hierarchy ancestors of one node in
+ * breadth-first discovery order, honoring each hierarchy kind's declared
+ * parent endpoint (so `parent` and inverse `child` spellings agree).
+ */
+export declare function hierarchyAncestors(graph: RelationshipGraph, id: string, options?: GraphTraversalOptions): RelationshipQueryResult<string[]>;
+/**
+ * Return the bounded transitive hierarchy descendants of one node in
+ * breadth-first discovery order, honoring each hierarchy kind's declared
+ * parent endpoint.
+ */
+export declare function hierarchyDescendants(graph: RelationshipGraph, id: string, options?: GraphTraversalOptions): RelationshipQueryResult<string[]>;
+/**
+ * Return the bounded transitive execution predecessors of one node — the work
+ * that must finish before it — in breadth-first discovery order, honoring each
+ * ordering kind's declared precedence (so `blocked_by` and inverse `blocks`
+ * spellings agree).
+ */
+export declare function orderingPredecessors(graph: RelationshipGraph, id: string, options?: GraphTraversalOptions): RelationshipQueryResult<string[]>;
+/**
+ * Return the bounded transitive execution successors of one node — the work
+ * this node gates — in breadth-first discovery order, honoring each ordering
+ * kind's declared precedence.
+ */
+export declare function orderingSuccessors(graph: RelationshipGraph, id: string, options?: GraphTraversalOptions): RelationshipQueryResult<string[]>;
+/**
+ * Enumerate bounded simple paths between two nodes, shortest first and
+ * lexicographic within equal length. Traversal honors direction and kind
+ * filters, caps returned paths, and reports truncation when depth, path-count,
+ * or the expansion-safety bound stops the search early.
+ */
+export declare function enumerateRelationshipPaths(graph: RelationshipGraph, source: string, target: string, options?: GraphPathOptions): RelationshipQueryResult<RelationshipPath[]>;