@unbrained/pm-cli 2026.8.21 → 2026.8.22

package/dist/sdk/graph/assembly.js

@@ -1,8 +1,10 @@
 
-!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]="a6fc5da1-b7d1-5b3c-8033-cecccc7861c3")}catch(e){}}();
-import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
-import { RelationshipGraph, createRelationshipKindRegistry, } from "../relationships.js";
+!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]="9a6974b3-63d7-5dc7-8329-0f15f0dc83ec")}catch(e){}}();
+import { RelationshipGraph, } from "../relationships.js";
 import { isExternalDependencySourceKind } from "../dependency-provenance.js";
+import { analyzeHierarchyIntegrity, } from "./hierarchy-integrity.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "./workspace-relationship-kind-registry.js";
+export { resolveWorkspaceRelationshipKindRegistry } from "./workspace-relationship-kind-registry.js";
 /** Normalize a decoded reference target and reject empty legacy placeholders. */
 function normalizeDependencyReferenceTarget(target) {
     if (typeof target !== "string")
@@ -20,23 +22,6 @@ export function normalizeDependencyGraphTarget(target) {
         ? undefined
         : normalized;
 }
-/**
- * Resolve the default workspace relationship-kind registry: the built-in kinds
- * merged with every active extension-contributed relationship-kind
- * registration. Assembly, mutation advisories, and standalone graph consumers
- * share this resolution so custom ordering semantics apply identically on
- * every surface.
- */
-export function resolveWorkspaceRelationshipKindRegistry() {
-    const registry = createRelationshipKindRegistry();
-    for (const registration of getActiveExtensionRegistrations()
-        ?.relationship_kinds ?? []) {
-        for (const definition of registration.definitions) {
-            registry.register(definition);
-        }
-    }
-    return registry;
-}
 /** Compare text case-insensitively with an exact-spelling deterministic tie-breaker. */
 function compareCaseFoldedText(left, right) {
     const normalizedLeft = left.toLowerCase();
@@ -242,6 +227,11 @@ export function collectExternalDependencyTargetIds(items) {
     }
     return [...targets.values()].sort((left, right) => left.localeCompare(right));
 }
+const hierarchyIntegrityByAssembly = new WeakMap();
+/** Read the hierarchy analysis paired with an assembly created by this module. */
+export function getWorkspaceHierarchyIntegrity(assembly) {
+    return assembly.hierarchyIntegrity ?? hierarchyIntegrityByAssembly.get(assembly);
+}
 /** Count raw dependency rows that use a registered compatibility alias instead of its canonical kind. */
 export function collectLegacyDependencyAliasCounts(items, registry = resolveWorkspaceRelationshipKindRegistry()) {
     const counts = {};
@@ -316,7 +306,8 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
             dependencies,
         };
     });
-    return {
+    const hierarchyIntegrity = analyzeHierarchyIntegrity(safeItems, isTerminal, relationshipRegistry);
+    const assembly = {
         graph: RelationshipGraph.fromItems([
             ...graphItems,
             ...missingIds.map((id) => ({ id })),
@@ -349,7 +340,10 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
         duplicateRows: collectDuplicateDependencyRows(safeItems, isTerminal),
         orderingContradictions: collectOrderingStorageContradictions(safeItems, isTerminal, relationshipRegistry),
         legacyAliasCounts: collectLegacyDependencyAliasCounts(safeItems, relationshipRegistry),
+        hierarchyIntegrity,
     };
+    hierarchyIntegrityByAssembly.set(assembly, hierarchyIntegrity);
+    return assembly;
 }
 //# sourceMappingURL=assembly.js.map
-//# debugId=a6fc5da1-b7d1-5b3c-8033-cecccc7861c3
+//# debugId=9a6974b3-63d7-5dc7-8329-0f15f0dc83ec

package/dist/sdk/graph/governance-contracts.d.ts

@@ -7,6 +7,6 @@
  * drifting when a finding family is added.
  */
 /** Stable machine-readable relationship audit finding families. */
-export declare const RELATIONSHIP_AUDIT_FINDING_CODES: readonly ["missing_reference_active", "missing_reference_terminal", "legacy_no_blocker_sentinel", "ordering_cycle", "legacy_ordering_cycle", "ordering_storage_contradiction", "legacy_ordering_storage_contradiction", "duplicate_edge", "legacy_duplicate_edge", "duplicate_dependency_row", "legacy_duplicate_dependency_row", "stale_lifecycle_block", "isolated_active_node", "sparse_active_node"];
+export declare const RELATIONSHIP_AUDIT_FINDING_CODES: readonly ["missing_reference_active", "missing_reference_terminal", "legacy_no_blocker_sentinel", "ordering_cycle", "legacy_ordering_cycle", "ordering_storage_contradiction", "legacy_ordering_storage_contradiction", "hierarchy_cycle", "legacy_hierarchy_cycle", "hierarchy_cardinality_violation", "legacy_hierarchy_cardinality_violation", "hierarchy_direction_violation", "legacy_hierarchy_direction_violation", "duplicate_edge", "legacy_duplicate_edge", "duplicate_dependency_row", "legacy_duplicate_dependency_row", "stale_lifecycle_block", "isolated_active_node", "sparse_active_node"];
 /** Machine-readable identifier for one relationship audit finding family. */
 export type RelationshipAuditFindingCode = (typeof RELATIONSHIP_AUDIT_FINDING_CODES)[number];

package/dist/sdk/graph/governance-contracts.js

@@ -8,7 +8,7 @@
  */
 /** Stable machine-readable relationship audit finding families. */
 
-!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]="bc561e73-75b8-5ea7-a18c-da70fb991b69")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a8bc0ebd-e5e4-57f3-8e6c-417f9809eb72")}catch(e){}}();
 export const RELATIONSHIP_AUDIT_FINDING_CODES = [
     "missing_reference_active",
     "missing_reference_terminal",
@@ -17,6 +17,12 @@ export const RELATIONSHIP_AUDIT_FINDING_CODES = [
     "legacy_ordering_cycle",
     "ordering_storage_contradiction",
     "legacy_ordering_storage_contradiction",
+    "hierarchy_cycle",
+    "legacy_hierarchy_cycle",
+    "hierarchy_cardinality_violation",
+    "legacy_hierarchy_cardinality_violation",
+    "hierarchy_direction_violation",
+    "legacy_hierarchy_direction_violation",
     "duplicate_edge",
     "legacy_duplicate_edge",
     "duplicate_dependency_row",
@@ -26,4 +32,4 @@ export const RELATIONSHIP_AUDIT_FINDING_CODES = [
     "sparse_active_node",
 ];
 //# sourceMappingURL=governance-contracts.js.map
-//# debugId=bc561e73-75b8-5ea7-a18c-da70fb991b69
+//# debugId=a8bc0ebd-e5e4-57f3-8e6c-417f9809eb72

package/dist/sdk/graph/governance.js

@@ -1,7 +1,8 @@
 
-!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]="c5dbaccd-d0e5-5511-b659-4f0a5f45ccaf")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="27de9c62-434c-566d-a000-54eddb9a16a9")}catch(e){}}();
 import { findRedundantRelationshipEdges, isTransitiveKind, orientTransitiveEdge, transitiveFamilyKey, } from "./analytics.js";
 import { findRelationshipCutStructure } from "./centrality.js";
+import { getWorkspaceHierarchyIntegrity } from "./assembly.js";
 import { RELATIONSHIP_AUDIT_FINDING_CODES, } from "./governance-contracts.js";
 /** Default bounded sample size applied to every finding family. */
 const DEFAULT_MAX_SAMPLE_SIZE = 25;
@@ -53,6 +54,48 @@ function buildFinding(code, severity, policy, describe, subjects, maxSampleSize,
             }),
     };
 }
+function collectHierarchyCycleFindings(analysis, maxSampleSize) {
+    return analysis.cycles.map((cycle) => buildFinding(cycle.legacy_terminal ? "legacy_hierarchy_cycle" : "hierarchy_cycle", cycle.legacy_terminal ? "info" : "error", "Structural hierarchy must be acyclic across scalar and registered dependency relationships.", (count) => `${count} items participate in one hierarchy cycle.`, cycle.item_ids, maxSampleSize, cycle.legacy_terminal
+        ? "Preserve historical rows unless an explicit legacy repair is approved."
+        : "Remove or retype one exact hierarchy relation before continuing mutation."));
+}
+function collectHierarchyCardinalityFindings(analysis, maxSampleSize, legacyTerminal) {
+    const rows = analysis.cardinality_violations.filter((finding) => finding.legacy_terminal === legacyTerminal);
+    if (rows.length === 0)
+        return [];
+    return [
+        buildFinding(legacyTerminal
+            ? "legacy_hierarchy_cardinality_violation"
+            : "hierarchy_cardinality_violation", legacyTerminal ? "info" : "error", "Every structural child must resolve to at most one logical parent across all hierarchy spellings.", (count) => `${count} child item${count === 1 ? "" : "s"} resolve to multiple hierarchy parents.`, rows.map((finding) => finding.child_id), maxSampleSize, legacyTerminal
+            ? "Preserve historical rows unless an explicit legacy repair is approved."
+            : "Remove the exact surplus hierarchy rows so each child has one parent.", rows.map((finding) => `${finding.child_id} <- ${finding.parent_ids.join(", ")}`)),
+    ];
+}
+function collectHierarchyDirectionFindings(analysis, maxSampleSize, legacyTerminal) {
+    const rows = analysis.divergences.filter((finding) => finding.legacy_terminal === legacyTerminal);
+    if (rows.length === 0)
+        return [];
+    return [
+        buildFinding(legacyTerminal
+            ? "legacy_hierarchy_direction_violation"
+            : "hierarchy_direction_violation", legacyTerminal ? "info" : "error", "Scalar parent metadata and dependency-backed hierarchy rows must resolve to the same logical parent.", (count) => `${count} child item${count === 1 ? "" : "s"} have divergent hierarchy storage surfaces.`, rows.map((finding) => finding.child_id), maxSampleSize, legacyTerminal
+            ? "Preserve historical rows unless an explicit legacy repair is approved."
+            : "Align the scalar parent and exact dependency rows to one canonical parent.", rows.map((finding) => `${finding.child_id}: scalar=${finding.scalar_parent_id} dependencies=${finding.dependency_parent_ids.join(",")}`)),
+    ];
+}
+/** Convert unified hierarchy analysis into lifecycle-aware governance findings. */
+function collectHierarchyIntegrityFindings(assembly, maxSampleSize) {
+    const analysis = getWorkspaceHierarchyIntegrity(assembly);
+    if (!analysis)
+        return [];
+    return [
+        ...collectHierarchyCycleFindings(analysis, maxSampleSize),
+        ...collectHierarchyCardinalityFindings(analysis, maxSampleSize, false),
+        ...collectHierarchyCardinalityFindings(analysis, maxSampleSize, true),
+        ...collectHierarchyDirectionFindings(analysis, maxSampleSize, false),
+        ...collectHierarchyDirectionFindings(analysis, maxSampleSize, true),
+    ];
+}
 /** Resolve the ordering-only successor adjacency for cycle analysis. */
 function buildOrderingAdjacency(assembly) {
     const registry = assembly.graph.registry();
@@ -577,6 +620,7 @@ export function auditWorkspaceRelationshipGraph(assembly, options = {}) {
     for (const edge of assembly.graph.edges())
         edgesByKind[edge.kind] = (edgesByKind[edge.kind] ?? 0) + 1;
     const findings = collectIntegrityFindings(assembly, isTerminal, maxSampleSize);
+    findings.push(...collectHierarchyIntegrityFindings(assembly, maxSampleSize));
     options.signal?.throwIfAborted();
     findings.push(...collectOrderingStorageContradictionFindings(assembly, maxSampleSize));
     options.signal?.throwIfAborted();
@@ -689,4 +733,4 @@ export function diffRelationshipAuditSnapshots(baseline, current) {
     };
 }
 //# sourceMappingURL=governance.js.map
-//# debugId=c5dbaccd-d0e5-5511-b659-4f0a5f45ccaf
+//# debugId=27de9c62-434c-566d-a000-54eddb9a16a9

package/dist/sdk/graph/hierarchy-integrity.d.ts

@@ -0,0 +1,94 @@
+import type { Dependency, ItemStatus } from "../../types/index.js";
+import type { RelationshipKindRegistry } from "../relationships.js";
+/** Storage surface from which one normalized hierarchy relation originated. */
+export type HierarchyRelationSource = "scalar_parent" | "dependency";
+/** Minimal workspace item shape required by hierarchy-integrity analysis. */
+export interface HierarchyIntegrityItem {
+    /** Stable item identifier. */
+    id: string;
+    /** Lifecycle status used to classify historical-only defects. */
+    status: ItemStatus;
+    /** Optional scalar structural parent. */
+    parent?: string;
+    /** Structured relationship rows that may carry hierarchy semantics. */
+    dependencies?: Dependency[];
+}
+/** One canonical parent-to-child relation with exact stored-row provenance. */
+export interface HierarchyRelation {
+    /** Canonical structural parent identifier. */
+    parent_id: string;
+    /** Canonical structural child identifier. */
+    child_id: string;
+    /** Storage surface that asserted the relation. */
+    source: HierarchyRelationSource;
+    /** Canonical relationship kind, or `parent` for the scalar field. */
+    kind: string;
+    /** Item document that stores the relation. */
+    holder_id: string;
+    /** Referenced endpoint for dependency-backed relations. */
+    target_id?: string;
+    /** Registry cardinality at the child endpoint of this relation. */
+    child_cardinality: "one" | "many";
+}
+/** One strongly connected hierarchy component. */
+export interface HierarchyCycle {
+    /** Deterministically sorted item identifiers in the cycle. */
+    item_ids: string[];
+    /** Whether every member is in a terminal lifecycle state. */
+    legacy_terminal: boolean;
+}
+/** One child assigned to more than one logical parent. */
+export interface HierarchyCardinalityViolation {
+    /** Child whose parent cardinality was exceeded. */
+    child_id: string;
+    /** Deterministically sorted unique parent identifiers. */
+    parent_ids: string[];
+    /** Whether the child and every asserted parent are terminal. */
+    legacy_terminal: boolean;
+}
+/** One scalar parent that disagrees with dependency-backed hierarchy evidence. */
+export interface HierarchyParentDivergence {
+    /** Child whose hierarchy storage surfaces disagree. */
+    child_id: string;
+    /** Parent declared by the scalar metadata field. */
+    scalar_parent_id: string;
+    /** Different dependency-backed parent identifiers. */
+    dependency_parent_ids: string[];
+    /** Whether the child and every asserted parent are terminal. */
+    legacy_terminal: boolean;
+}
+/** Complete deterministic hierarchy-integrity projection for a workspace. */
+export interface HierarchyIntegrityAnalysis {
+    /** Normalized evidence rows retained for exact diagnostics and repair. */
+    relations: HierarchyRelation[];
+    /** Cyclic structural components. */
+    cycles: HierarchyCycle[];
+    /** Logical one-parent cardinality violations. */
+    cardinality_violations: HierarchyCardinalityViolation[];
+    /** Scalar and dependency-backed parent disagreements. */
+    divergences: HierarchyParentDivergence[];
+}
+/** Deterministic adjacency indexes derived from normalized hierarchy evidence. */
+export interface HierarchyRelationIndexes {
+    /** Unique logical parents keyed by child id. */
+    parents_by_child: ReadonlyMap<string, readonly string[]>;
+    /** Unique logical children keyed by parent id. */
+    children_by_parent: ReadonlyMap<string, readonly string[]>;
+}
+/** Collect normalized hierarchy evidence without running defect analysis. */
+export declare function collectHierarchyRelations(items: readonly HierarchyIntegrityItem[], registry?: RelationshipKindRegistry): HierarchyRelation[];
+/**
+ * Analyze all runtime-recognized hierarchy spellings as canonical parent-child
+ * relations. Unknown, malformed, and dangling rows are ignored here because
+ * dedicated graph-integrity checks own those diagnostics.
+ */
+export declare function analyzeHierarchyIntegrity(items: readonly HierarchyIntegrityItem[], isTerminal?: (status: ItemStatus) => boolean, registry?: RelationshipKindRegistry): HierarchyIntegrityAnalysis;
+/** Render exact hierarchy evidence without losing its storage orientation. */
+export declare function formatHierarchyRelation(relation: HierarchyRelation): string;
+/** Index normalized hierarchy evidence for list, tree, and rollup consumers. */
+export declare function indexHierarchyRelations(relations: readonly HierarchyRelation[]): HierarchyRelationIndexes;
+/**
+ * Reject a mutation only when it introduces a new hierarchy defect involving
+ * the changed item. Existing debt remains repairable without a global bypass.
+ */
+export declare function assertHierarchyMutationAllowed(beforeItems: readonly HierarchyIntegrityItem[], afterItems: readonly HierarchyIntegrityItem[], changedItemId: string, isTerminal?: (status: ItemStatus) => boolean, registry?: RelationshipKindRegistry): void;

package/dist/sdk/graph/hierarchy-integrity.js

@@ -0,0 +1,311 @@
+/**
+ * @module sdk/graph/hierarchy-integrity
+ *
+ * Normalizes scalar and dependency-backed hierarchy evidence into one graph,
+ * reports structural defects, and rejects mutations that introduce new debt.
+ */
+
+!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]="924f7718-0527-5967-8ab0-53e8228bd665")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "./workspace-relationship-kind-registry.js";
+function normalizeItemId(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function relationIdentity(relation) {
+    return [
+        relation.parent_id,
+        relation.child_id,
+        relation.source,
+        relation.kind,
+        relation.holder_id,
+        relation.target_id ?? "",
+    ].join("\u0000");
+}
+function collectHierarchyFinishOrder(nodeIds, childrenByParent) {
+    const visited = new Set();
+    const finishOrder = [];
+    for (const root of [...nodeIds].sort()) {
+        if (visited.has(root))
+            continue;
+        visited.add(root);
+        const frames = [
+            {
+                nodeId: root,
+                children: [...(childrenByParent.get(root) ?? [])].sort(),
+                nextChild: 0,
+            },
+        ];
+        while (frames.length > 0) {
+            const frame = frames.at(-1);
+            const childId = frame.children[frame.nextChild];
+            if (childId === undefined) {
+                finishOrder.push(frame.nodeId);
+                frames.pop();
+            }
+            else {
+                frame.nextChild += 1;
+                if (!visited.has(childId)) {
+                    visited.add(childId);
+                    frames.push({
+                        nodeId: childId,
+                        children: [...(childrenByParent.get(childId) ?? [])].sort(),
+                        nextChild: 0,
+                    });
+                }
+            }
+        }
+    }
+    return finishOrder;
+}
+function collectCyclicComponents(nodeIds, childrenByParent) {
+    const sortedNodeIds = [...nodeIds].sort();
+    const finishOrder = collectHierarchyFinishOrder(sortedNodeIds, childrenByParent);
+    const visited = new Set();
+    const parentsByChild = reverseHierarchyEdges(sortedNodeIds, childrenByParent);
+    const components = [];
+    for (const root of finishOrder.reverse()) {
+        if (visited.has(root))
+            continue;
+        const component = collectReverseComponent(root, parentsByChild, visited);
+        if (component.length > 1 ||
+            childrenByParent.get(component[0])?.has(component[0]))
+            components.push(component);
+    }
+    return components.sort((left, right) => left.join("\u0000").localeCompare(right.join("\u0000")));
+}
+function reverseHierarchyEdges(nodeIds, childrenByParent) {
+    const parentsByChild = new Map(nodeIds.map((nodeId) => [nodeId, new Set()]));
+    for (const [parentId, childIds] of childrenByParent) {
+        for (const childId of childIds)
+            parentsByChild.get(childId)?.add(parentId);
+    }
+    return parentsByChild;
+}
+function collectReverseComponent(root, parentsByChild, visited) {
+    const component = [];
+    const pending = [root];
+    visited.add(root);
+    while (pending.length > 0) {
+        const nodeId = pending.pop();
+        component.push(nodeId);
+        for (const parentId of [...parentsByChild.get(nodeId)].sort()) {
+            if (visited.has(parentId))
+                continue;
+            visited.add(parentId);
+            pending.push(parentId);
+        }
+    }
+    return component.sort();
+}
+function collectHierarchyItems(items) {
+    const itemById = new Map();
+    for (const item of items) {
+        const itemId = normalizeItemId(item?.id);
+        if (itemId && !itemById.has(itemId))
+            itemById.set(itemId, item);
+    }
+    return itemById;
+}
+function buildScalarHierarchyRelation(holderId, item, itemById) {
+    const parentId = normalizeItemId(item.parent);
+    if (!parentId || !itemById.has(parentId))
+        return undefined;
+    return {
+        parent_id: parentId,
+        child_id: holderId,
+        source: "scalar_parent",
+        kind: "parent",
+        holder_id: holderId,
+        child_cardinality: "one",
+    };
+}
+function buildDependencyHierarchyRelation(holderId, dependency, itemById, registry) {
+    const targetId = normalizeItemId(dependency?.id);
+    const definition = registry.resolve(dependency?.kind);
+    if (!targetId || !itemById.has(targetId) || !definition?.hierarchy)
+        return undefined;
+    const sourceIsParent = definition.hierarchyDirection === "source_parent";
+    return {
+        parent_id: sourceIsParent ? holderId : targetId,
+        child_id: sourceIsParent ? targetId : holderId,
+        source: "dependency",
+        kind: definition.kind,
+        holder_id: holderId,
+        target_id: targetId,
+        child_cardinality: sourceIsParent
+            ? definition.incoming
+            : definition.outgoing,
+    };
+}
+function collectHierarchyRelationsFromItemMap(itemById, registry) {
+    const relationsByIdentity = new Map();
+    for (const [holderId, item] of itemById) {
+        const scalarRelation = buildScalarHierarchyRelation(holderId, item, itemById);
+        if (scalarRelation)
+            relationsByIdentity.set(relationIdentity(scalarRelation), scalarRelation);
+        for (const dependency of item.dependencies ?? []) {
+            const relation = buildDependencyHierarchyRelation(holderId, dependency, itemById, registry);
+            if (!relation)
+                continue;
+            relationsByIdentity.set(relationIdentity(relation), relation);
+        }
+    }
+    return [...relationsByIdentity.values()].sort((left, right) => relationIdentity(left).localeCompare(relationIdentity(right)));
+}
+/** Collect normalized hierarchy evidence without running defect analysis. */
+export function collectHierarchyRelations(items, registry = resolveWorkspaceRelationshipKindRegistry()) {
+    return collectHierarchyRelationsFromItemMap(collectHierarchyItems(items), registry);
+}
+function collectHierarchyCardinalityViolations(relations, parentsByChild, terminalIds) {
+    const oneCardinalityChildren = new Set(relations
+        .filter((relation) => relation.child_cardinality === "one")
+        .map((relation) => relation.child_id));
+    return [...parentsByChild]
+        .filter(([childId, parentIds]) => parentIds.length > 1 && oneCardinalityChildren.has(childId))
+        .map(([childId, parentIds]) => ({
+        child_id: childId,
+        parent_ids: [...parentIds],
+        legacy_terminal: terminalIds.has(childId) &&
+            parentIds.every((id) => terminalIds.has(id)),
+    }))
+        .sort((left, right) => left.child_id.localeCompare(right.child_id));
+}
+function collectHierarchyDivergences(itemById, relations, terminalIds) {
+    const dependencyParentsByChild = new Map();
+    for (const relation of relations) {
+        if (relation.source !== "dependency")
+            continue;
+        const parents = dependencyParentsByChild.get(relation.child_id) ?? new Set();
+        parents.add(relation.parent_id);
+        dependencyParentsByChild.set(relation.child_id, parents);
+    }
+    const divergences = [];
+    for (const [childId, item] of itemById) {
+        const scalarParentId = normalizeItemId(item.parent);
+        if (!scalarParentId || !itemById.has(scalarParentId))
+            continue;
+        const dependencyParentIds = [
+            ...(dependencyParentsByChild.get(childId) ?? []),
+        ]
+            .filter((parentId) => parentId !== scalarParentId)
+            .sort();
+        if (dependencyParentIds.length === 0)
+            continue;
+        divergences.push({
+            child_id: childId,
+            scalar_parent_id: scalarParentId,
+            dependency_parent_ids: dependencyParentIds,
+            legacy_terminal: terminalIds.has(childId) &&
+                terminalIds.has(scalarParentId) &&
+                dependencyParentIds.every((id) => terminalIds.has(id)),
+        });
+    }
+    return divergences.sort((left, right) => left.child_id.localeCompare(right.child_id));
+}
+/**
+ * Analyze all runtime-recognized hierarchy spellings as canonical parent-child
+ * relations. Unknown, malformed, and dangling rows are ignored here because
+ * dedicated graph-integrity checks own those diagnostics.
+ */
+export function analyzeHierarchyIntegrity(items, isTerminal = (status) => status === "closed" || status === "canceled", registry = resolveWorkspaceRelationshipKindRegistry()) {
+    const itemById = collectHierarchyItems(items);
+    const relations = collectHierarchyRelationsFromItemMap(itemById, registry);
+    const indexes = indexHierarchyRelations(relations);
+    const terminalIds = new Set([...itemById]
+        .filter(([, item]) => isTerminal(item.status))
+        .map(([id]) => id));
+    const cycles = collectCyclicComponents([...itemById.keys()], new Map([...indexes.children_by_parent].map(([id, childIds]) => [
+        id,
+        new Set(childIds),
+    ]))).map((itemIds) => ({
+        item_ids: itemIds,
+        legacy_terminal: itemIds.every((id) => terminalIds.has(id)),
+    }));
+    return {
+        relations,
+        cycles,
+        cardinality_violations: collectHierarchyCardinalityViolations(relations, indexes.parents_by_child, terminalIds),
+        divergences: collectHierarchyDivergences(itemById, relations, terminalIds),
+    };
+}
+/** Render exact hierarchy evidence without losing its storage orientation. */
+export function formatHierarchyRelation(relation) {
+    if (relation.source === "scalar_parent")
+        return `${relation.parent_id} -> ${relation.child_id} (scalar parent on ${relation.holder_id})`;
+    return `${relation.parent_id} -> ${relation.child_id} (${relation.kind} dependency on ${relation.holder_id})`;
+}
+/** Index normalized hierarchy evidence for list, tree, and rollup consumers. */
+export function indexHierarchyRelations(relations) {
+    const parentSets = new Map();
+    const childSets = new Map();
+    for (const relation of relations) {
+        const parents = parentSets.get(relation.child_id) ?? new Set();
+        parents.add(relation.parent_id);
+        parentSets.set(relation.child_id, parents);
+        const children = childSets.get(relation.parent_id) ?? new Set();
+        children.add(relation.child_id);
+        childSets.set(relation.parent_id, children);
+    }
+    return {
+        parents_by_child: new Map([...parentSets].map(([id, values]) => [id, [...values].sort()])),
+        children_by_parent: new Map([...childSets].map(([id, values]) => [id, [...values].sort()])),
+    };
+}
+/** Return whether every candidate identifier existed in the prior defect. */
+function isIdentifierSubset(candidate, prior) {
+    const priorIds = new Set(prior);
+    return candidate.every((id) => priorIds.has(id));
+}
+/**
+ * Reject a mutation only when it introduces a new hierarchy defect involving
+ * the changed item. Existing debt remains repairable without a global bypass.
+ */
+export function assertHierarchyMutationAllowed(beforeItems, afterItems, changedItemId, isTerminal, registry) {
+    const holderId = normalizeItemId(changedItemId);
+    if (!holderId)
+        return;
+    const before = analyzeHierarchyIntegrity(beforeItems, isTerminal, registry);
+    const after = analyzeHierarchyIntegrity(afterItems, isTerminal, registry);
+    const divergence = after.divergences.find((finding) => !before.divergences.some((prior) => prior.child_id === finding.child_id &&
+        prior.scalar_parent_id === finding.scalar_parent_id &&
+        isIdentifierSubset(finding.dependency_parent_ids, prior.dependency_parent_ids)));
+    if (divergence) {
+        const parentIds = [
+            divergence.scalar_parent_id,
+            ...divergence.dependency_parent_ids,
+        ].sort();
+        throw new PmCliError(`Hierarchy mutation would assign ${divergence.child_id} to multiple parents: ${parentIds.join(", ")}.`, EXIT_CODE.CONFLICT, {
+            code: "hierarchy_parent_divergence_created",
+            source_id: holderId,
+            target_id: divergence.child_id,
+            verification_errors: parentIds,
+        });
+    }
+    const cardinality = after.cardinality_violations.find((finding) => (finding.child_id === holderId ||
+        finding.parent_ids.includes(holderId)) &&
+        !before.cardinality_violations.some((prior) => prior.child_id === finding.child_id &&
+            isIdentifierSubset(finding.parent_ids, prior.parent_ids)));
+    if (cardinality) {
+        throw new PmCliError(`Hierarchy mutation would assign ${cardinality.child_id} to multiple parents: ${cardinality.parent_ids.join(", ")}.`, EXIT_CODE.CONFLICT, {
+            code: "hierarchy_cardinality_created",
+            source_id: holderId,
+            target_id: cardinality.child_id,
+            verification_errors: cardinality.parent_ids,
+        });
+    }
+    const cycle = after.cycles.find((finding) => finding.item_ids.includes(holderId) &&
+        !before.cycles.some((prior) => isIdentifierSubset(finding.item_ids, prior.item_ids)));
+    if (cycle) {
+        throw new PmCliError(`Hierarchy mutation would create a cycle: ${cycle.item_ids.join(" -> ")}.`, EXIT_CODE.CONFLICT, {
+            code: "hierarchy_cycle_created",
+            source_id: holderId,
+            verification_errors: cycle.item_ids,
+        });
+    }
+}
+//# sourceMappingURL=hierarchy-integrity.js.map
+//# debugId=924f7718-0527-5967-8ab0-53e8228bd665

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

@@ -14,9 +14,10 @@ export { assertMemoryRelationshipGraphAdapterConformance, assertRelationshipGrap
 export { analyzeRelationshipSchedule, type GraphScheduleOptions, type RelationshipScheduleAnalysis, type RelationshipScheduleRow, } from "./scheduling.js";
 export { assembleWorkspaceRelationshipGraph, collectDanglingDependencyReferences, collectDuplicateDependencyRows, collectMissingDependencyTargetIds, collectOrderingStorageContradictions, normalizeDependencyGraphTarget, resolveWorkspaceRelationshipKindRegistry, type DanglingDependencyReference, type DanglingDependencyReferenceSummary, type DependencyReferenceHolder, type DependencyReferenceSource, type DuplicateDependencyRow, type OrderingStorageContradiction, type WorkspaceRelationshipAssembly, type WorkspaceRelationshipItem, type WorkspaceRelationshipNodeDetails, } from "./assembly.js";
 export { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, collectOrderingCycles, diffRelationshipAuditSnapshots, formatDuplicateEdgeGroup, formatOrderingStorageContradiction, type DuplicateRelationshipEdgeGroup, type RelationshipAuditDelta, type RelationshipAuditFinding, type RelationshipAuditFindingCode, type RelationshipAuditOptions, type RelationshipAuditReport, type RelationshipAuditSeverity, type RelationshipAuditSnapshot, type RelationshipCoverageProfile, type RelationshipCoverageTypeProfile, } from "./governance.js";
+export { analyzeHierarchyIntegrity, assertHierarchyMutationAllowed, collectHierarchyRelations, formatHierarchyRelation, indexHierarchyRelations, type HierarchyCardinalityViolation, type HierarchyCycle, type HierarchyIntegrityAnalysis, type HierarchyIntegrityItem, type HierarchyParentDivergence, type HierarchyRelation, type HierarchyRelationIndexes, type HierarchyRelationSource, } from "./hierarchy-integrity.js";
 export { clearDurableGraphCache, durableGraphCachePath, durableGraphCacheStatus, GRAPH_DURABLE_CACHE_MIN_ITEMS, GRAPH_DURABLE_CACHE_VERSION, graphAuditBaselinePath, loadGraphAuditBaseline, openDurableGraphCache, persistDurableGraphResult, saveGraphAuditBaseline, shouldPersistDurableGraphCache, type DurableGraphCacheEnvelope, type DurableGraphCacheStatus, type DurableGraphCacheView, } from "./durable-cache.js";
 export { enumerateRelationshipPaths, hierarchyAncestors, hierarchyDescendants, orderingPredecessors, orderingSuccessors, type GraphPathOptions, type GraphTraversalOptions, type RelationshipPath, } from "./traversal.js";
 export { computeWorkspaceGraphFingerprint, resetWorkspaceGraphCache, workspaceGraphCache, WorkspaceGraphCache, type GraphCacheMetadata, type WorkspaceGraphCacheLookup, } from "./cache.js";
 export { planRelationshipRemediation, type RelationshipRemediationCode, type RelationshipRemediationConfidence, type RelationshipRemediationOperation, type RelationshipRemediationPlan, type RelationshipRemediationPlanOptions, type RelationshipRemediationStep, } from "./remediation.js";
 export { collectNewOrderingCycleWarnings } from "./mutation-advisory.js";
-export { GRAPH_SUBCOMMAND_VALUES, parseGraphSubcommand, runGraph, type GraphAnalyzeResult, type GraphArticulationResult, type GraphAuditResult, type GraphBridgeRow, type GraphCentralityResult, type GraphCentralityRow, type GraphCommandOptions, type GraphCommunitiesResult, type GraphCommunityRow, type GraphDominatorRow, type GraphDominatorsResult, type GraphExecutionSummary, type GraphImpactResult, type GraphImpactRow, type GraphIndexResult, type GraphKnowledgeSummary, type GraphPathRow, type GraphPathsResult, type GraphPlanResult, type GraphQueryCost, type GraphRedundancyResult, type GraphRedundancyRow, type GraphResult, type GraphScheduleRow, type GraphSlackResult, type GraphSubcommand, type GraphTraversalResult, } from "./run.js";
+export { GRAPH_SUBCOMMAND_VALUES, parseGraphSubcommand, runGraph, type GraphAnalyzeResult, type GraphArticulationResult, type GraphAuditResult, type GraphBridgeRow, type GraphCentralityResult, type GraphCentralityRow, type GraphCommandOptions, type GraphCommunitiesResult, type GraphCommunityRow, type GraphDominatorRow, type GraphDominatorsResult, type GraphExecutionSummary, type GraphImpactResult, type GraphImpactRow, type GraphHierarchySummary, type GraphIndexResult, type GraphKnowledgeSummary, type GraphPathRow, type GraphPathsResult, type GraphPlanResult, type GraphQueryCost, type GraphRedundancyResult, type GraphRedundancyRow, type GraphResult, type GraphScheduleRow, type GraphSlackResult, type GraphSubcommand, type GraphTraversalResult, } from "./run.js";

package/dist/sdk/graph/index.js

@@ -8,7 +8,7 @@
  * `sdk/relationships` and is safe for CLI, MCP, extension, and non-PM callers.
  */
 
-!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]="b5509c6e-1431-5316-a563-16681ced4f33")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="20842b89-cef6-542e-b069-76c22b340f1d")}catch(e){}}();
 export { computeRelationshipDominators, detectRelationshipCommunities, findRedundantRelationshipEdges, forEachMatchedRelationshipEdge, } from "./analytics.js";
 export { computeRelationshipCentrality, findRelationshipCutStructure, } from "./centrality.js";
 export { createRelationshipGraphSnapshot, federateRelationshipGraphSnapshots, loadRelationshipGraphAdapter, MemoryRelationshipGraphAdapter, parseRelationshipGraphSnapshot, RELATIONSHIP_GRAPH_SNAPSHOT_VERSION, syncRelationshipGraphAdapter, } from "./adapter.js";
@@ -16,6 +16,7 @@ export { assertMemoryRelationshipGraphAdapterConformance, assertRelationshipGrap
 export { analyzeRelationshipSchedule, } from "./scheduling.js";
 export { assembleWorkspaceRelationshipGraph, collectDanglingDependencyReferences, collectDuplicateDependencyRows, collectMissingDependencyTargetIds, collectOrderingStorageContradictions, normalizeDependencyGraphTarget, resolveWorkspaceRelationshipKindRegistry, } from "./assembly.js";
 export { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, collectOrderingCycles, diffRelationshipAuditSnapshots, formatDuplicateEdgeGroup, formatOrderingStorageContradiction, } from "./governance.js";
+export { analyzeHierarchyIntegrity, assertHierarchyMutationAllowed, collectHierarchyRelations, formatHierarchyRelation, indexHierarchyRelations, } from "./hierarchy-integrity.js";
 export { clearDurableGraphCache, durableGraphCachePath, durableGraphCacheStatus, GRAPH_DURABLE_CACHE_MIN_ITEMS, GRAPH_DURABLE_CACHE_VERSION, graphAuditBaselinePath, loadGraphAuditBaseline, openDurableGraphCache, persistDurableGraphResult, saveGraphAuditBaseline, shouldPersistDurableGraphCache, } from "./durable-cache.js";
 export { enumerateRelationshipPaths, hierarchyAncestors, hierarchyDescendants, orderingPredecessors, orderingSuccessors, } from "./traversal.js";
 export { computeWorkspaceGraphFingerprint, resetWorkspaceGraphCache, workspaceGraphCache, WorkspaceGraphCache, } from "./cache.js";
@@ -23,4 +24,4 @@ export { planRelationshipRemediation, } from "./remediation.js";
 export { collectNewOrderingCycleWarnings } from "./mutation-advisory.js";
 export { GRAPH_SUBCOMMAND_VALUES, parseGraphSubcommand, runGraph, } from "./run.js";
 //# sourceMappingURL=index.js.map
-//# debugId=b5509c6e-1431-5316-a563-16681ced4f33
+//# debugId=20842b89-cef6-542e-b069-76c22b340f1d