@unbrained/pm-cli 2026.7.17 → 2026.7.18

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

@@ -0,0 +1,52 @@
+import type { WorkspaceRelationshipAssembly } from "./assembly.js";
+import { type RelationshipAuditFindingCode, type RelationshipAuditOptions, type RelationshipAuditReport } from "./governance.js";
+/** Exact operation family a remediation step proposes; audits never auto-apply. */
+export type RelationshipRemediationOperation = "add" | "remove" | "retype" | "supersede" | "waive" | "investigate";
+/** Planner confidence that applying the proposed operation is safe and correct. */
+export type RelationshipRemediationConfidence = "high" | "medium" | "low";
+/** Policy source a remediation step was derived from. */
+export type RelationshipRemediationCode = RelationshipAuditFindingCode | "redundant_edge";
+/** One exact dry-run remediation proposal with evidence and confidence. */
+export interface RelationshipRemediationStep {
+    /** Proposed operation family. */
+    op: RelationshipRemediationOperation;
+    /** Audit finding code or `redundant_edge` for witnessed transitive shortcuts. */
+    code: RelationshipRemediationCode;
+    /** Compact deterministic subject — the edge, reference, or node to act on. */
+    subject: string;
+    /** Why this operation is proposed and what applying it means. */
+    rationale: string;
+    /** Deterministic evidence strings backing the proposal. */
+    evidence: string[];
+    /** Planner confidence in the proposal. */
+    confidence: RelationshipRemediationConfidence;
+}
+/** Tuning inputs accepted by dry-run remediation planning. */
+export interface RelationshipRemediationPlanOptions extends RelationshipAuditOptions {
+    /** Maximum witnessed redundant edges scanned into proposals; defaults to the audit sample bound. */
+    redundancyLimit?: number;
+}
+/** Complete deterministic result of one dry-run remediation planning pass. */
+export interface RelationshipRemediationPlan {
+    /** Proposed steps in audit severity order, redundancy proposals last. */
+    steps: RelationshipRemediationStep[];
+    /** The governance-audit report the plan was derived from. */
+    report: RelationshipAuditReport;
+    /** Whether bounded samples or scan limits omitted derivable proposals. */
+    truncated: boolean;
+    /** Nodes visited and edges inspected by the redundancy witness scan. */
+    cost: {
+        visitedNodes: number;
+        inspectedEdges: number;
+    };
+}
+/**
+ * Build one deterministic dry-run remediation plan over an assembled workspace
+ * relationship graph. The plan runs the shared governance audit, derives one
+ * exact proposal per bounded finding subject, then appends witnessed
+ * transitive-shortcut removal proposals from the redundancy scan (medium
+ * confidence, because shortcut edges are sometimes deliberate emphasis).
+ * `truncated` reports whether sample or scan bounds omitted derivable steps;
+ * nothing is ever applied automatically.
+ */
+export declare function planRelationshipRemediation(assembly: WorkspaceRelationshipAssembly, options?: RelationshipRemediationPlanOptions): RelationshipRemediationPlan;

package/dist/sdk/graph/remediation.js

@@ -0,0 +1,148 @@
+
+!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]="662a9796-dbb3-5fd5-bc23-22dba9adde9e")}catch(e){}}();
+import { findRedundantRelationshipEdges } from "./analytics.js";
+import { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, formatDuplicateEdgeGroup, } from "./governance.js";
+/** Per-finding-code operation template applied to every sampled subject. */
+const FINDING_STEP_TEMPLATES = {
+    missing_reference_active: {
+        op: "investigate",
+        confidence: "medium",
+        rationale: "Restore or re-create the referenced item, or remove/retype the reference on the active holder; the correct fix depends on why the target is absent.",
+    },
+    missing_reference_terminal: {
+        op: "waive",
+        confidence: "high",
+        rationale: "Terminal-holder reference to an absent item is historical debt; waive it or clean it up only in a dedicated changelog-safe closed-item batch.",
+    },
+    legacy_no_blocker_sentinel: {
+        op: "remove",
+        confidence: "high",
+        rationale: "The pre-structured-dependency no-active-blocker sentinel is retired and carries no information; blocker state derives from blocked_by edges.",
+    },
+    ordering_cycle: {
+        op: "investigate",
+        confidence: "low",
+        rationale: "Every cycle member is unschedulable until one ordering edge is removed or retyped; the planner never chooses which edge to cut.",
+    },
+    legacy_ordering_cycle: {
+        op: "waive",
+        confidence: "high",
+        rationale: "Terminal-only ordering cycles have no scheduling effect; repairing them would mutate closed history (changelog drag).",
+    },
+    // duplicate_edge findings are expanded into per-stored-edge remove steps by
+    // the planner itself (see stepsFromDuplicateGroup); this template documents
+    // the family for exhaustiveness and backs any future sample-only fallback.
+    duplicate_edge: {
+        op: "remove",
+        confidence: "high",
+        rationale: "Parallel same-family spellings state one relationship twice; remove all but one stored spelling, keeping the holder's canonical direction.",
+    },
+    legacy_duplicate_edge: {
+        op: "waive",
+        confidence: "high",
+        rationale: "Duplicated spellings between terminal items are historical noise; waive or batch changelog-safe cleanup.",
+    },
+    stale_lifecycle_block: {
+        op: "investigate",
+        confidence: "medium",
+        rationale: "Re-open the missing prerequisite as an ordering edge, or move the item back to an active status; only the holder's owner knows which is true.",
+    },
+    isolated_active_node: {
+        op: "investigate",
+        confidence: "medium",
+        rationale: "Link the item to its parent, prerequisite, or origin — or register it as an explicitly exempt isolate; the audit never fabricates an edge.",
+    },
+    sparse_active_node: {
+        op: "investigate",
+        confidence: "low",
+        rationale: "Investigate for an honest second edge (story-to-task, defect family, cross-epic complement); sparse is not automatically defective.",
+    },
+};
+/** Format one stored edge as a concrete removable identity. */
+function formatStoredEdge(edge) {
+    return `${edge.source} -${edge.kind}-> ${edge.target}`;
+}
+/**
+ * Expand one active duplicate group into concrete per-stored-edge removals.
+ * The deterministic keeper is the group's first sorted edge; every other
+ * stored spelling gets its own remove proposal naming the exact edge to drop,
+ * so the plan stays machine-executable instead of pointing at a display
+ * string that spans several stored rows.
+ */
+function stepsFromDuplicateGroup(group) {
+    const [keeper, ...extras] = group.edges;
+    return extras.map((edge) => ({
+        op: "remove",
+        code: "duplicate_edge",
+        subject: formatStoredEdge(edge),
+        rationale: "This stored spelling restates the kept canonical edge of the same semantic family; removing it leaves the relationship stated exactly once.",
+        evidence: [
+            `keep: ${formatStoredEdge(keeper)}`,
+            `group: ${formatDuplicateEdgeGroup(group)}`,
+        ],
+        confidence: "high",
+    }));
+}
+/** Derive one proposal per bounded sample subject of an audit finding. */
+function stepsFromFinding(finding, duplicateGroups) {
+    if (finding.code === "duplicate_edge") {
+        // Sample subjects are the deterministic group format strings, so each one
+        // resolves to its concrete stored-edge group for exact removal targeting.
+        return finding.sample.flatMap((subject) => stepsFromDuplicateGroup(duplicateGroups.get(subject)));
+    }
+    const template = FINDING_STEP_TEMPLATES[finding.code];
+    return finding.sample.map((subject) => ({
+        op: template.op,
+        code: finding.code,
+        subject,
+        rationale: template.rationale,
+        evidence: [finding.policy],
+        confidence: template.confidence,
+    }));
+}
+/**
+ * Build one deterministic dry-run remediation plan over an assembled workspace
+ * relationship graph. The plan runs the shared governance audit, derives one
+ * exact proposal per bounded finding subject, then appends witnessed
+ * transitive-shortcut removal proposals from the redundancy scan (medium
+ * confidence, because shortcut edges are sometimes deliberate emphasis).
+ * `truncated` reports whether sample or scan bounds omitted derivable steps;
+ * nothing is ever applied automatically.
+ */
+export function planRelationshipRemediation(assembly, options = {}) {
+    const { redundancyLimit, ...auditOptions } = options;
+    const report = auditWorkspaceRelationshipGraph(assembly, auditOptions);
+    const duplicateGroups = new Map(collectDuplicateRelationshipEdgeGroups(assembly).map((group) => [
+        formatDuplicateEdgeGroup(group),
+        group,
+    ]));
+    const steps = report.findings.flatMap((finding) => stepsFromFinding(finding, duplicateGroups));
+    let truncated = report.findings.some((finding) => finding.sample_truncated);
+    options.signal?.throwIfAborted();
+    const redundancy = findRedundantRelationshipEdges(assembly.graph, {
+        limit: redundancyLimit ?? options.maxSampleSize ?? 25,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    for (const row of redundancy.value) {
+        steps.push({
+            op: "remove",
+            code: "redundant_edge",
+            subject: `${row.edge.source} -> ${row.edge.target} (${row.edge.kind})`,
+            rationale: "The stored edge is implied by a longer same-family witness path; shortcut edges are sometimes deliberate emphasis, so confirm intent before removing.",
+            evidence: [`witness: ${row.witness.join(" -> ")}`],
+            confidence: "medium",
+        });
+    }
+    truncated = truncated || redundancy.meta.truncated;
+    return {
+        steps,
+        report,
+        truncated,
+        cost: {
+            visitedNodes: redundancy.meta.visitedNodes,
+            inspectedEdges: redundancy.meta.inspectedEdges,
+        },
+    };
+}
+//# sourceMappingURL=remediation.js.map
+//# debugId=662a9796-dbb3-5fd5-bc23-22dba9adde9e

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

@@ -0,0 +1 @@
+{"version":3,"file":"remediation.js","sources":["sdk/graph/remediation.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/graph/remediation\n *\n * Dry-run remediation planning over the relationship governance audit. The\n * planner turns bounded audit findings and transitive-redundancy evidence into\n * exact, machine-readable proposed operations — remove, retype, supersede,\n * waive, or investigate — each carrying its policy code, evidence, confidence,\n * and rationale. Planning never mutates the workspace and never invents an\n * edge: proposals with structural proof (duplicates, retired sentinels,\n * witnessed shortcuts) get actionable operations, while judgment calls stay\n * explicit `investigate` steps for a human or agent to resolve.\n */\nimport type { RelationshipEdge } from \"../relationships.js\";\nimport { findRedundantRelationshipEdges } from \"./analytics.js\";\nimport type { WorkspaceRelationshipAssembly } from \"./assembly.js\";\nimport {\n  auditWorkspaceRelationshipGraph,\n  collectDuplicateRelationshipEdgeGroups,\n  formatDuplicateEdgeGroup,\n  type DuplicateRelationshipEdgeGroup,\n  type RelationshipAuditFinding,\n  type RelationshipAuditFindingCode,\n  type RelationshipAuditOptions,\n  type RelationshipAuditReport,\n} from \"./governance.js\";\n\n/** Exact operation family a remediation step proposes; audits never auto-apply. */\nexport type RelationshipRemediationOperation =\n  | \"add\"\n  | \"remove\"\n  | \"retype\"\n  | \"supersede\"\n  | \"waive\"\n  | \"investigate\";\n\n/** Planner confidence that applying the proposed operation is safe and correct. */\nexport type RelationshipRemediationConfidence = \"high\" | \"medium\" | \"low\";\n\n/** Policy source a remediation step was derived from. */\nexport type RelationshipRemediationCode =\n  | RelationshipAuditFindingCode\n  | \"redundant_edge\";\n\n/** One exact dry-run remediation proposal with evidence and confidence. */\nexport interface RelationshipRemediationStep {\n  /** Proposed operation family. */\n  op: RelationshipRemediationOperation;\n  /** Audit finding code or `redundant_edge` for witnessed transitive shortcuts. */\n  code: RelationshipRemediationCode;\n  /** Compact deterministic subject — the edge, reference, or node to act on. */\n  subject: string;\n  /** Why this operation is proposed and what applying it means. */\n  rationale: string;\n  /** Deterministic evidence strings backing the proposal. */\n  evidence: string[];\n  /** Planner confidence in the proposal. */\n  confidence: RelationshipRemediationConfidence;\n}\n\n/** Tuning inputs accepted by dry-run remediation planning. */\nexport interface RelationshipRemediationPlanOptions\n  extends RelationshipAuditOptions {\n  /** Maximum witnessed redundant edges scanned into proposals; defaults to the audit sample bound. */\n  redundancyLimit?: number;\n}\n\n/** Complete deterministic result of one dry-run remediation planning pass. */\nexport interface RelationshipRemediationPlan {\n  /** Proposed steps in audit severity order, redundancy proposals last. */\n  steps: RelationshipRemediationStep[];\n  /** The governance-audit report the plan was derived from. */\n  report: RelationshipAuditReport;\n  /** Whether bounded samples or scan limits omitted derivable proposals. */\n  truncated: boolean;\n  /** Nodes visited and edges inspected by the redundancy witness scan. */\n  cost: { visitedNodes: number; inspectedEdges: number };\n}\n\n/** Per-finding-code operation template applied to every sampled subject. */\nconst FINDING_STEP_TEMPLATES: Record<\n  RelationshipAuditFindingCode,\n  {\n    op: RelationshipRemediationOperation;\n    confidence: RelationshipRemediationConfidence;\n    rationale: string;\n  }\n> = {\n  missing_reference_active: {\n    op: \"investigate\",\n    confidence: \"medium\",\n    rationale:\n      \"Restore or re-create the referenced item, or remove/retype the reference on the active holder; the correct fix depends on why the target is absent.\",\n  },\n  missing_reference_terminal: {\n    op: \"waive\",\n    confidence: \"high\",\n    rationale:\n      \"Terminal-holder reference to an absent item is historical debt; waive it or clean it up only in a dedicated changelog-safe closed-item batch.\",\n  },\n  legacy_no_blocker_sentinel: {\n    op: \"remove\",\n    confidence: \"high\",\n    rationale:\n      \"The pre-structured-dependency no-active-blocker sentinel is retired and carries no information; blocker state derives from blocked_by edges.\",\n  },\n  ordering_cycle: {\n    op: \"investigate\",\n    confidence: \"low\",\n    rationale:\n      \"Every cycle member is unschedulable until one ordering edge is removed or retyped; the planner never chooses which edge to cut.\",\n  },\n  legacy_ordering_cycle: {\n    op: \"waive\",\n    confidence: \"high\",\n    rationale:\n      \"Terminal-only ordering cycles have no scheduling effect; repairing them would mutate closed history (changelog drag).\",\n  },\n  // duplicate_edge findings are expanded into per-stored-edge remove steps by\n  // the planner itself (see stepsFromDuplicateGroup); this template documents\n  // the family for exhaustiveness and backs any future sample-only fallback.\n  duplicate_edge: {\n    op: \"remove\",\n    confidence: \"high\",\n    rationale:\n      \"Parallel same-family spellings state one relationship twice; remove all but one stored spelling, keeping the holder's canonical direction.\",\n  },\n  legacy_duplicate_edge: {\n    op: \"waive\",\n    confidence: \"high\",\n    rationale:\n      \"Duplicated spellings between terminal items are historical noise; waive or batch changelog-safe cleanup.\",\n  },\n  stale_lifecycle_block: {\n    op: \"investigate\",\n    confidence: \"medium\",\n    rationale:\n      \"Re-open the missing prerequisite as an ordering edge, or move the item back to an active status; only the holder's owner knows which is true.\",\n  },\n  isolated_active_node: {\n    op: \"investigate\",\n    confidence: \"medium\",\n    rationale:\n      \"Link the item to its parent, prerequisite, or origin — or register it as an explicitly exempt isolate; the audit never fabricates an edge.\",\n  },\n  sparse_active_node: {\n    op: \"investigate\",\n    confidence: \"low\",\n    rationale:\n      \"Investigate for an honest second edge (story-to-task, defect family, cross-epic complement); sparse is not automatically defective.\",\n  },\n};\n\n/** Format one stored edge as a concrete removable identity. */\nfunction formatStoredEdge(edge: RelationshipEdge): string {\n  return `${edge.source} -${edge.kind}-> ${edge.target}`;\n}\n\n/**\n * Expand one active duplicate group into concrete per-stored-edge removals.\n * The deterministic keeper is the group's first sorted edge; every other\n * stored spelling gets its own remove proposal naming the exact edge to drop,\n * so the plan stays machine-executable instead of pointing at a display\n * string that spans several stored rows.\n */\nfunction stepsFromDuplicateGroup(\n  group: DuplicateRelationshipEdgeGroup,\n): RelationshipRemediationStep[] {\n  const [keeper, ...extras] = group.edges;\n  return extras.map((edge) => ({\n    op: \"remove\" as const,\n    code: \"duplicate_edge\" as const,\n    subject: formatStoredEdge(edge),\n    rationale:\n      \"This stored spelling restates the kept canonical edge of the same semantic family; removing it leaves the relationship stated exactly once.\",\n    evidence: [\n      `keep: ${formatStoredEdge(keeper!)}`,\n      `group: ${formatDuplicateEdgeGroup(group)}`,\n    ],\n    confidence: \"high\" as const,\n  }));\n}\n\n/** Derive one proposal per bounded sample subject of an audit finding. */\nfunction stepsFromFinding(\n  finding: RelationshipAuditFinding,\n  duplicateGroups: Map<string, DuplicateRelationshipEdgeGroup>,\n): RelationshipRemediationStep[] {\n  if (finding.code === \"duplicate_edge\") {\n    // Sample subjects are the deterministic group format strings, so each one\n    // resolves to its concrete stored-edge group for exact removal targeting.\n    return finding.sample.flatMap((subject) =>\n      stepsFromDuplicateGroup(duplicateGroups.get(subject)!),\n    );\n  }\n  const template = FINDING_STEP_TEMPLATES[finding.code];\n  return finding.sample.map((subject) => ({\n    op: template.op,\n    code: finding.code,\n    subject,\n    rationale: template.rationale,\n    evidence: [finding.policy],\n    confidence: template.confidence,\n  }));\n}\n\n/**\n * Build one deterministic dry-run remediation plan over an assembled workspace\n * relationship graph. The plan runs the shared governance audit, derives one\n * exact proposal per bounded finding subject, then appends witnessed\n * transitive-shortcut removal proposals from the redundancy scan (medium\n * confidence, because shortcut edges are sometimes deliberate emphasis).\n * `truncated` reports whether sample or scan bounds omitted derivable steps;\n * nothing is ever applied automatically.\n */\nexport function planRelationshipRemediation(\n  assembly: WorkspaceRelationshipAssembly,\n  options: RelationshipRemediationPlanOptions = {},\n): RelationshipRemediationPlan {\n  const { redundancyLimit, ...auditOptions } = options;\n  const report = auditWorkspaceRelationshipGraph(assembly, auditOptions);\n  const duplicateGroups = new Map(\n    collectDuplicateRelationshipEdgeGroups(assembly).map((group) => [\n      formatDuplicateEdgeGroup(group),\n      group,\n    ]),\n  );\n  const steps = report.findings.flatMap((finding) =>\n    stepsFromFinding(finding, duplicateGroups),\n  );\n  let truncated = report.findings.some((finding) => finding.sample_truncated);\n  options.signal?.throwIfAborted();\n  const redundancy = findRedundantRelationshipEdges(assembly.graph, {\n    limit: redundancyLimit ?? options.maxSampleSize ?? 25,\n    ...(options.signal === undefined ? {} : { signal: options.signal }),\n  });\n  for (const row of redundancy.value) {\n    steps.push({\n      op: \"remove\",\n      code: \"redundant_edge\",\n      subject: `${row.edge.source} -> ${row.edge.target} (${row.edge.kind})`,\n      rationale:\n        \"The stored edge is implied by a longer same-family witness path; shortcut edges are sometimes deliberate emphasis, so confirm intent before removing.\",\n      evidence: [`witness: ${row.witness.join(\" -> \")}`],\n      confidence: \"medium\",\n    });\n  }\n  truncated = truncated || redundancy.meta.truncated;\n  return {\n    steps,\n    report,\n    truncated,\n    cost: {\n      visitedNodes: redundancy.meta.visitedNodes,\n      inspectedEdges: redundancy.meta.inspectedEdges,\n    },\n  };\n}\n"],"names":[],"mappings":";;AAaA,OAAO,EAAE,8BAA8B,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EACL,+BAA+B,EAC/B,sCAAsC,EACtC,wBAAwB,GAMzB,MAAM,iBAAiB,CAAC;AAsDzB,4EAA4E;AAC5E,MAAM,sBAAsB,GAOxB;IACF,wBAAwB,EAAE;QACxB,EAAE,EAAE,aAAa;QACjB,UAAU,EAAE,QAAQ;QACpB,SAAS,EACP,qJAAqJ;KACxJ;IACD,0BAA0B,EAAE;QAC1B,EAAE,EAAE,OAAO;QACX,UAAU,EAAE,MAAM;QAClB,SAAS,EACP,+IAA+I;KAClJ;IACD,0BAA0B,EAAE;QAC1B,EAAE,EAAE,QAAQ;QACZ,UAAU,EAAE,MAAM;QAClB,SAAS,EACP,8IAA8I;KACjJ;IACD,cAAc,EAAE;QACd,EAAE,EAAE,aAAa;QACjB,UAAU,EAAE,KAAK;QACjB,SAAS,EACP,iIAAiI;KACpI;IACD,qBAAqB,EAAE;QACrB,EAAE,EAAE,OAAO;QACX,UAAU,EAAE,MAAM;QAClB,SAAS,EACP,uHAAuH;KAC1H;IACD,4EAA4E;IAC5E,4EAA4E;IAC5E,2EAA2E;IAC3E,cAAc,EAAE;QACd,EAAE,EAAE,QAAQ;QACZ,UAAU,EAAE,MAAM;QAClB,SAAS,EACP,4IAA4I;KAC/I;IACD,qBAAqB,EAAE;QACrB,EAAE,EAAE,OAAO;QACX,UAAU,EAAE,MAAM;QAClB,SAAS,EACP,0GAA0G;KAC7G;IACD,qBAAqB,EAAE;QACrB,EAAE,EAAE,aAAa;QACjB,UAAU,EAAE,QAAQ;QACpB,SAAS,EACP,+IAA+I;KAClJ;IACD,oBAAoB,EAAE;QACpB,EAAE,EAAE,aAAa;QACjB,UAAU,EAAE,QAAQ;QACpB,SAAS,EACP,4IAA4I;KAC/I;IACD,kBAAkB,EAAE;QAClB,EAAE,EAAE,aAAa;QACjB,UAAU,EAAE,KAAK;QACjB,SAAS,EACP,qIAAqI;KACxI;CACF,CAAC;AAEF,+DAA+D;AAC/D,SAAS,gBAAgB,CAAC,IAAsB;IAC9C,OAAO,GAAG,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,uBAAuB,CAC9B,KAAqC;IAErC,MAAM,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC;IACxC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC3B,EAAE,EAAE,QAAiB;QACrB,IAAI,EAAE,gBAAyB;QAC/B,OAAO,EAAE,gBAAgB,CAAC,IAAI,CAAC;QAC/B,SAAS,EACP,6IAA6I;QAC/I,QAAQ,EAAE;YACR,SAAS,gBAAgB,CAAC,MAAO,CAAC,EAAE;YACpC,UAAU,wBAAwB,CAAC,KAAK,CAAC,EAAE;SAC5C;QACD,UAAU,EAAE,MAAe;KAC5B,CAAC,CAAC,CAAC;AACN,CAAC;AAED,0EAA0E;AAC1E,SAAS,gBAAgB,CACvB,OAAiC,EACjC,eAA4D;IAE5D,IAAI,OAAO,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;QACtC,0EAA0E;QAC1E,0EAA0E;QAC1E,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CACxC,uBAAuB,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC,CACvD,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtC,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO;QACP,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;QAC1B,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,2BAA2B,CACzC,QAAuC,EACvC,UAA8C,EAAE;IAEhD,MAAM,EAAE,eAAe,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC;IACrD,MAAM,MAAM,GAAG,+BAA+B,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IACvE,MAAM,eAAe,GAAG,IAAI,GAAG,CAC7B,sCAAsC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;QAC9D,wBAAwB,CAAC,KAAK,CAAC;QAC/B,KAAK;KACN,CAAC,CACH,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAChD,gBAAgB,CAAC,OAAO,EAAE,eAAe,CAAC,CAC3C,CAAC;IACF,IAAI,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC5E,OAAO,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC;IACjC,MAAM,UAAU,GAAG,8BAA8B,CAAC,QAAQ,CAAC,KAAK,EAAE;QAChE,KAAK,EAAE,eAAe,IAAI,OAAO,CAAC,aAAa,IAAI,EAAE;QACrD,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;KACpE,CAAC,CAAC;IACH,KAAK,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC;YACT,EAAE,EAAE,QAAQ;YACZ,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG;YACtE,SAAS,EACP,uJAAuJ;YACzJ,QAAQ,EAAE,CAAC,YAAY,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,UAAU,EAAE,QAAQ;SACrB,CAAC,CAAC;IACL,CAAC;IACD,SAAS,GAAG,SAAS,IAAI,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;IACnD,OAAO;QACL,KAAK;QACL,MAAM;QACN,SAAS;QACT,IAAI,EAAE;YACJ,YAAY,EAAE,UAAU,CAAC,IAAI,CAAC,YAAY;YAC1C,cAAc,EAAE,UAAU,CAAC,IAAI,CAAC,cAAc;SAC/C;KACF,CAAC;AACJ,CAAC","debugId":"662a9796-dbb3-5fd5-bc23-22dba9adde9e"}

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

@@ -0,0 +1,295 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type GraphCacheMetadata } from "./cache.js";
+import { type RelationshipAuditReport } from "./governance.js";
+import { type RelationshipRemediationStep } from "./remediation.js";
+import { GRAPH_SUBCOMMAND_VALUES, type GraphSubcommand } from "../cli-contracts/enum-contracts.js";
+export { GRAPH_SUBCOMMAND_VALUES, type GraphSubcommand };
+/** Documents the graph command options payload exchanged by command, SDK, and package integrations. */
+export interface GraphCommandOptions {
+    /** Restricts traversal to registered relationship kinds (repeatable or comma-separated). */
+    kind?: string | string[];
+    /** Maximum traversal depth as a non-negative integer. */
+    maxDepth?: string | number;
+    /** Maximum returned rows per bounded collection. */
+    limit?: string | number;
+    /** Resume a traversal after this previously returned node id. */
+    after?: string;
+    /** Edge orientation for paths and impact queries (outgoing, incoming, or both). */
+    direction?: string;
+    /** Maximum enumerated paths for the paths subcommand. */
+    maxPaths?: string | number;
+    /** Maximum evidence sample entries per audit finding. */
+    sample?: string | number;
+    /** Item ids treated as explicitly valid isolates by the audit. */
+    exemptIsolate?: string | string[];
+    /** Return counts-first envelopes without row collections. */
+    summary?: boolean;
+}
+/** Cost metadata attached to every graph query projection. */
+export interface GraphQueryCost {
+    /** Nodes expanded while answering the query. */
+    visited_nodes: number;
+    /** Edges inspected while answering the query. */
+    inspected_edges: number;
+}
+/** Result envelope for the transitive traversal subcommands. */
+export interface GraphTraversalResult {
+    /** Executed graph subcommand. */
+    subcommand: "ancestors" | "descendants" | "predecessors" | "successors";
+    /** Canonical root item id. */
+    root: string;
+    /** Total emitted node ids before summary suppression. */
+    count: number;
+    /** Whether configured bounds omitted reachable work. */
+    truncated: boolean;
+    /** Cursor resuming emission after the last returned node. */
+    next_cursor?: string;
+    /** Query cost metadata. */
+    cost: GraphQueryCost;
+    /** Emitted node ids in deterministic breadth-first order; absent with summary. */
+    ids?: string[];
+    /** Cache observability for this invocation. */
+    cache?: GraphCacheMetadata;
+}
+/** One enumerated path projected with relationship kinds instead of raw edges. */
+export interface GraphPathRow {
+    /** Ordered node ids from source to target inclusive. */
+    nodes: string[];
+    /** Relationship kind of each traversed edge, in path order. */
+    kinds: string[];
+    /** Number of edges in the path. */
+    length: number;
+}
+/** Result envelope for the paths subcommand. */
+export interface GraphPathsResult {
+    /** Executed graph subcommand. */
+    subcommand: "paths";
+    /** Canonical source item id. */
+    root: string;
+    /** Canonical target item id. */
+    target: string;
+    /** Traversal orientation used for the enumeration. */
+    direction: string;
+    /** Total enumerated paths before summary suppression. */
+    count: number;
+    /** Whether depth, path-count, or safety bounds stopped the search early. */
+    truncated: boolean;
+    /** Query cost metadata. */
+    cost: GraphQueryCost;
+    /** Enumerated paths, shortest first; absent with summary. */
+    paths?: GraphPathRow[];
+    /** Cache observability for this invocation. */
+    cache?: GraphCacheMetadata;
+}
+/** One affected item row in an impact projection. */
+export interface GraphImpactRow {
+    /** Affected item id. */
+    id: string;
+    /** Shortest relationship distance from the root. */
+    distance: number;
+    /** Exact node path explaining why the item is affected. */
+    path: string[];
+}
+/** Result envelope for the impact subcommand. */
+export interface GraphImpactResult {
+    /** Executed graph subcommand. */
+    subcommand: "impact";
+    /** Canonical impact-origin item id. */
+    root: string;
+    /** Traversal orientation used for the blast-radius walk. */
+    direction: string;
+    /** Total affected items before summary suppression. */
+    count: number;
+    /** Whether configured bounds omitted reachable work. */
+    truncated: boolean;
+    /** Query cost metadata. */
+    cost: GraphQueryCost;
+    /** Affected item rows ordered by discovery; absent with summary. */
+    affected?: GraphImpactRow[];
+    /** Cache observability for this invocation. */
+    cache?: GraphCacheMetadata;
+}
+/** Bounded execution-graph projection inside an analyze result. */
+export interface GraphExecutionSummary {
+    /** Whether the order-bearing graph is acyclic. */
+    acyclic: boolean;
+    /** Nodes participating in the topological order. */
+    ordered_node_count: number;
+    /** Number of parallelizable topological layers. */
+    layer_count: number;
+    /** Total items with no open prerequisites. */
+    frontier_count: number;
+    /** Bounded prerequisite-free sample; absent with summary. */
+    frontier?: string[];
+    /** Edge count of the longest execution path. */
+    critical_path_length: number;
+    /** Longest deterministic execution path; absent with summary. */
+    critical_path?: string[];
+    /** Total genuine ordering cycles. */
+    cycle_count: number;
+    /** Bounded ordering-cycle sample; absent with summary. */
+    cycles?: string[][];
+}
+/** Bounded knowledge-graph projection inside an analyze result. */
+export interface GraphKnowledgeSummary {
+    /** Total weakly connected components. */
+    component_count: number;
+    /** Node count of the largest component. */
+    largest_component_size: number;
+    /** Total nodes without any relationship edges. */
+    orphan_count: number;
+    /** Bounded orphan sample; absent with summary. */
+    orphans?: string[];
+    /** Bounded maximum-degree hubs; absent with summary. */
+    hubs?: {
+        id: string;
+        degree: number;
+    }[];
+}
+/** Result envelope for the analyze subcommand. */
+export interface GraphAnalyzeResult {
+    /** Executed graph subcommand. */
+    subcommand: "analyze";
+    /** Total indexed graph nodes. */
+    node_count: number;
+    /** Total deduplicated graph edges. */
+    edge_count: number;
+    /** Bound applied to every sample collection. */
+    sample_limit: number;
+    /** Execution-order analytics over registered ordering kinds. */
+    execution: GraphExecutionSummary;
+    /** Structural analytics over every stored edge. */
+    knowledge: GraphKnowledgeSummary;
+    /** Cache observability for this invocation. */
+    cache?: GraphCacheMetadata;
+}
+/** Result envelope for the audit subcommand. */
+export interface GraphAuditResult {
+    /** Executed graph subcommand. */
+    subcommand: "audit";
+    /** Total audit findings. */
+    finding_count: number;
+    /** Finding counts keyed by severity. */
+    findings_by_severity: Record<string, number>;
+    /** Affected-subject counts keyed by finding code. */
+    findings_by_code: Record<string, number>;
+    /** Structural coverage metrics computed during the audit. */
+    profile: RelationshipAuditReport["profile"];
+    /** Ordered findings with bounded evidence samples; absent with summary. */
+    findings?: RelationshipAuditReport["findings"];
+    /** Cache observability for this invocation. */
+    cache?: GraphCacheMetadata;
+}
+/** One bounded community row projected by the communities subcommand. */
+export interface GraphCommunityRow {
+    /** Lexicographically smallest member id, naming the community. */
+    representative: string;
+    /** Total member count before sampling. */
+    size: number;
+    /** Bounded sorted member sample. */
+    members: string[];
+}
+/** Result envelope for the communities subcommand. */
+export interface GraphCommunitiesResult {
+    /** Executed graph subcommand. */
+    subcommand: "communities";
+    /** Total detected communities meeting the size floor. */
+    community_count: number;
+    /** Member count of the largest community. */
+    largest_community_size: number;
+    /** Label-propagation sweeps executed. */
+    iterations: number;
+    /** Whether labels stabilized before the iteration bound. */
+    converged: boolean;
+    /** Whether the iteration bound stopped propagation early or the sample bound omitted rows. */
+    truncated: boolean;
+    /** Query cost metadata. */
+    cost: GraphQueryCost;
+    /** Bounded community rows, largest first; absent with summary. */
+    communities?: GraphCommunityRow[];
+    /** Cache observability for this invocation. */
+    cache?: GraphCacheMetadata;
+}
+/** One redundant stored edge projected with its witness path. */
+export interface GraphRedundancyRow {
+    /** Stored edge source id. */
+    source: string;
+    /** Stored edge target id. */
+    target: string;
+    /** Stored relationship kind. */
+    kind: string;
+    /** Semantic-orientation node path proving the edge is implied. */
+    witness: string[];
+}
+/** Result envelope for the redundancy subcommand. */
+export interface GraphRedundancyResult {
+    /** Executed graph subcommand. */
+    subcommand: "redundancy";
+    /** Total redundant edges found within configured bounds. */
+    redundant_count: number;
+    /** Whether the row limit omitted further redundant edges. */
+    truncated: boolean;
+    /** Query cost metadata. */
+    cost: GraphQueryCost;
+    /** Redundant edge rows in deterministic scan order; absent with summary. */
+    redundant?: GraphRedundancyRow[];
+    /** Cache observability for this invocation. */
+    cache?: GraphCacheMetadata;
+}
+/** One structural bottleneck row projected by the dominators subcommand. */
+export interface GraphDominatorRow {
+    /** Bottleneck node id. */
+    id: string;
+    /** Immediate dominator appearing on every root-to-node path. */
+    idom: string;
+    /** Reachable nodes strictly gated by this node. */
+    dominated_count: number;
+}
+/** Result envelope for the dominators subcommand. */
+export interface GraphDominatorsResult {
+    /** Executed graph subcommand. */
+    subcommand: "dominators";
+    /** Canonical analyzed root id. */
+    root: string;
+    /** Traversal orientation used for reachability. */
+    direction: string;
+    /** Reachable node count including the root. */
+    reachable_count: number;
+    /** Total nodes gating at least one other reachable node. */
+    bottleneck_count: number;
+    /** Whether the depth bound cut reachability or the row limit omitted bottleneck rows. */
+    truncated: boolean;
+    /** Query cost metadata. */
+    cost: GraphQueryCost;
+    /** Bounded bottleneck rows, most-gating first; absent with summary. */
+    bottlenecks?: GraphDominatorRow[];
+    /** Cache observability for this invocation. */
+    cache?: GraphCacheMetadata;
+}
+/** Result envelope for the dry-run remediation planning subcommand. */
+export interface GraphPlanResult {
+    /** Executed graph subcommand. */
+    subcommand: "plan";
+    /** Total derived remediation proposals before row bounding. */
+    step_count: number;
+    /** Proposal counts keyed by operation family. */
+    steps_by_op: Record<string, number>;
+    /** Proposal counts keyed by policy code. */
+    steps_by_code: Record<string, number>;
+    /** Total governance-audit findings the plan was derived from. */
+    finding_count: number;
+    /** Whether sample, scan, or row bounds omitted derivable proposals. */
+    truncated: boolean;
+    /** Query cost metadata. */
+    cost: GraphQueryCost;
+    /** Bounded proposal rows in audit severity order; absent with summary. */
+    steps?: RelationshipRemediationStep[];
+    /** Cache observability for this invocation. */
+    cache?: GraphCacheMetadata;
+}
+/** Union of every graph subcommand result envelope. */
+export type GraphResult = GraphTraversalResult | GraphPathsResult | GraphImpactResult | GraphAnalyzeResult | GraphAuditResult | GraphCommunitiesResult | GraphRedundancyResult | GraphDominatorsResult | GraphPlanResult;
+/** Validate the graph subcommand and its positional-id requirements. */
+export declare function parseGraphSubcommand(raw: string, id: string | undefined, target: string | undefined): GraphSubcommand;
+/** Implements run graph for the public runtime surface of this module. */
+export declare function runGraph(subcommandRaw: string, id: string | undefined, target: string | undefined, options: GraphCommandOptions, global: GlobalOptions): Promise<GraphResult>;