@unbrained/pm-cli 2026.8.21 → 2026.8.23

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

package/dist/sdk/graph/remediation.js

@@ -1,5 +1,5 @@
 
-!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]="1eb0e2cb-084a-5a54-b41c-29dfdd6d2f34")}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]="7054952e-444a-5be2-b0c1-fcc3b72afde5")}catch(e){}}();
 import { findRedundantRelationshipEdges } from "./analytics.js";
 import { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, formatDuplicateEdgeGroup, } from "./governance.js";
 /** Per-finding-code operation template applied to every sampled subject. */
@@ -39,6 +39,36 @@ const FINDING_STEP_TEMPLATES = {
         confidence: "high",
         rationale: "The terminal holder contains a proven contradictory structured ordering row; remove it in a dedicated changelog-safe batch while preserving the scalar blocker as history.",
     },
+    hierarchy_cycle: {
+        op: "investigate",
+        confidence: "low",
+        rationale: "Cut or retype one exact structural relation in the cycle; the planner preserves every evidence row because intent determines the correct parent.",
+    },
+    legacy_hierarchy_cycle: {
+        op: "waive",
+        confidence: "high",
+        rationale: "Terminal-only hierarchy cycles are historical debt; waive them unless an explicit closed-history repair is approved.",
+    },
+    hierarchy_cardinality_violation: {
+        op: "investigate",
+        confidence: "medium",
+        rationale: "Choose the canonical parent and remove or retype the exact surplus hierarchy rows; the planner cannot infer ownership intent.",
+    },
+    legacy_hierarchy_cardinality_violation: {
+        op: "waive",
+        confidence: "high",
+        rationale: "Multiple parents confined to terminal items are historical debt; waive them unless a dedicated history repair is approved.",
+    },
+    hierarchy_direction_violation: {
+        op: "investigate",
+        confidence: "medium",
+        rationale: "Align the scalar parent and dependency-backed hierarchy rows to the intended canonical parent.",
+    },
+    legacy_hierarchy_direction_violation: {
+        op: "waive",
+        confidence: "high",
+        rationale: "Divergent hierarchy storage confined to terminal items is historical debt; waive it unless a dedicated history repair is approved.",
+    },
     // 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.
@@ -165,4 +195,4 @@ export function planRelationshipRemediation(assembly, options = {}) {
     };
 }
 //# sourceMappingURL=remediation.js.map
-//# debugId=1eb0e2cb-084a-5a54-b41c-29dfdd6d2f34
+//# debugId=7054952e-444a-5be2-b0c1-fcc3b72afde5

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

@@ -159,6 +159,33 @@ export interface GraphKnowledgeSummary {
         degree: number;
     }[];
 }
+/** Unified hierarchy-integrity projection inside an analyze result. */
+export interface GraphHierarchySummary {
+    /** Whether the structural hierarchy is acyclic. */
+    acyclic: boolean;
+    /** Total canonical parent-child evidence rows. */
+    relation_count: number;
+    /** Total strongly connected hierarchy components. */
+    cycle_count: number;
+    /** Active hierarchy cycles that require remediation. */
+    active_cycle_count?: number;
+    /** Terminal-only hierarchy cycles retained as historical debt. */
+    legacy_cycle_count?: number;
+    /** Total children that resolve to more than one logical parent. */
+    cardinality_violation_count: number;
+    /** Active one-parent cardinality violations. */
+    active_cardinality_violation_count?: number;
+    /** Terminal-only one-parent cardinality violations. */
+    legacy_cardinality_violation_count?: number;
+    /** Total scalar/dependency parent disagreements. */
+    parent_divergence_count: number;
+    /** Active scalar/dependency parent disagreements. */
+    active_parent_divergence_count?: number;
+    /** Terminal-only scalar/dependency parent disagreements. */
+    legacy_parent_divergence_count?: number;
+    /** Bounded hierarchy-cycle sample; absent with summary. */
+    cycles?: string[][];
+}
 /** Result envelope for the analyze subcommand. */
 export interface GraphAnalyzeResult {
     /** Executed graph subcommand. */
@@ -175,6 +202,8 @@ export interface GraphAnalyzeResult {
     execution: GraphExecutionSummary;
     /** Structural analytics over every stored edge. */
     knowledge: GraphKnowledgeSummary;
+    /** Registry-driven structural hierarchy integrity across all storage surfaces. */
+    hierarchy?: GraphHierarchySummary;
     /** Cache observability for this invocation. */
     cache?: GraphCacheMetadata;
 }
@@ -192,8 +221,8 @@ export interface GraphAuditResult {
     affected_subjects_by_severity: Record<string, number>;
     /** Affected-subject counts keyed by finding code. */
     affected_subjects_by_code: Record<string, number>;
-    /** Structural coverage metrics computed during the audit. */
-    profile: RelationshipAuditReport["profile"];
+    /** Structural coverage metrics; the duplicated finding census is absent with summary. */
+    profile: Omit<RelationshipAuditReport["profile"], "finding_subjects_by_code"> & Partial<Pick<RelationshipAuditReport["profile"], "finding_subjects_by_code">>;
     /** Stored legacy relationship aliases grouped by spelling; canonical graph counts remain in profile. */
     legacy_alias_counts?: Record<string, number>;
     /** Ordered findings with bounded evidence samples; absent with summary. */