@unbrained/pm-cli 2026.8.13 → 2026.8.15

package/dist/sdk/graph/governance.js

@@ -1,6 +1,6 @@
 
-!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]="ab8a4904-0302-5e36-9963-750b3ba79876")}catch(e){}}();
-import { isTransitiveKind, orientTransitiveEdge, transitiveFamilyKey, } from "./analytics.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]="1955b7a4-385d-5a5d-8856-6db9f94814aa")}catch(e){}}();
+import { findRedundantRelationshipEdges, isTransitiveKind, orientTransitiveEdge, transitiveFamilyKey, } from "./analytics.js";
 import { findRelationshipCutStructure } from "./centrality.js";
 import { RELATIONSHIP_AUDIT_FINDING_CODES, } from "./governance-contracts.js";
 /** Default bounded sample size applied to every finding family. */
@@ -25,8 +25,14 @@ const SEVERITY_RANK = {
     warning: 1,
     info: 2,
 };
+/** Normalize optional exemption identifiers into a case-insensitive lookup set. */
+function normalizeExemptionSet(values) {
+    return new Set((values ?? [])
+        .filter((value) => typeof value === "string")
+        .map((value) => value.trim().toLowerCase()));
+}
 /** Build one finding with deterministic bounded sampling over sorted subjects. */
-function buildFinding(code, severity, policy, describe, subjects, maxSampleSize, remediation) {
+function buildFinding(code, severity, policy, describe, subjects, maxSampleSize, remediation, evidence) {
     const sorted = [...subjects].sort((left, right) => left.localeCompare(right));
     return {
         code,
@@ -37,6 +43,13 @@ function buildFinding(code, severity, policy, describe, subjects, maxSampleSize,
         sample: sorted.slice(0, maxSampleSize),
         sample_truncated: sorted.length > maxSampleSize,
         remediation,
+        ...(evidence === undefined
+            ? {}
+            : {
+                evidence: [...evidence]
+                    .sort((left, right) => left.localeCompare(right))
+                    .slice(0, maxSampleSize),
+            }),
     };
 }
 /** Resolve the ordering-only successor adjacency for cycle analysis. */
@@ -177,6 +190,21 @@ function isActiveAuditMember(member, nodeStates) {
         return true;
     return !state.terminal;
 }
+/** Format the exact contradictory storage pair that manufactures an ordering cycle. */
+export function formatOrderingStorageContradiction(contradiction) {
+    return `${contradiction.holder_id} -> ${contradiction.target_id} (blocked_by scalar + ${contradiction.dependency_kind} dependency)`;
+}
+/** Report active and historical scalar-versus-structured ordering contradictions. */
+function collectOrderingStorageContradictionFindings(assembly, maxSampleSize) {
+    const active = [];
+    const legacy = [];
+    for (const contradiction of assembly.orderingContradictions ?? [])
+        (contradiction.legacy_terminal ? legacy : active).push(formatOrderingStorageContradiction(contradiction));
+    const findings = [];
+    appendFinding(findings, active, maxSampleSize, "ordering_storage_contradiction", "error", "A scalar blocker and same-target structured ordering row must not assert opposite precedence.", (count) => `${count} active scalar-versus-structured ordering contradiction(s)`, "Remove the structured dependency row that points the holder before its scalar blocker, or replace both representations with one unambiguous ordering edge.");
+    appendFinding(findings, legacy, maxSampleSize, "legacy_ordering_storage_contradiction", "info", "Terminal scalar-versus-structured ordering contradictions are exact historical storage defects with no live scheduling effect.", (count) => `${count} terminal scalar-versus-structured ordering contradiction(s)`, "Remove the contradictory blocks dependency row in a dedicated changelog-safe closed-item batch; preserve the scalar blocker as the historical precedence record.");
+    return findings;
+}
 /** Collect ordering-cycle and lifecycle-block governance findings. */
 function collectOrderingFindings(assembly, nodeStates, isBlocked, maxSampleSize) {
     const findings = [];
@@ -186,9 +214,18 @@ function collectOrderingFindings(assembly, nodeStates, isBlocked, maxSampleSize)
         // it cannot make live work unschedulable, and "repairing" it would touch
         // closed items (changelog drag), so it downgrades to informational debt.
         const active = cycle.some((member) => isActiveAuditMember(member, nodeStates));
+        const cycleMembers = new Set(cycle.map((member) => member.toLowerCase()));
+        const contradictionEvidence = (assembly.orderingContradictions ?? [])
+            .filter((row) => cycleMembers.has(row.holder_id.toLowerCase()) &&
+            cycleMembers.has(row.target_id.toLowerCase()))
+            .map(formatOrderingStorageContradiction);
         findings.push(active
-            ? buildFinding("ordering_cycle", "error", "Order-bearing relationship kinds must stay acyclic; a cycle makes every member unschedulable.", (count) => `execution-order cycle across ${count} item(s)`, cycle, maxSampleSize, "Remove or retype one ordering edge inside the cycle, or split the work so precedence is linear.")
-            : buildFinding("legacy_ordering_cycle", "info", "Ordering cycles between exclusively terminal items are historical contradictions with no scheduling effect.", (count) => `terminal-only execution-order cycle across ${count} item(s)`, cycle, maxSampleSize, "Leave as history debt, or clean up in a dedicated changelog-safe closed-item batch; never repair closed items ad hoc."));
+            ? buildFinding("ordering_cycle", "error", "Order-bearing relationship kinds must stay acyclic; a cycle makes every member unschedulable.", (count) => `execution-order cycle across ${count} item(s)`, cycle, maxSampleSize, "Remove or retype one ordering edge inside the cycle, or split the work so precedence is linear.", contradictionEvidence.length === 0
+                ? undefined
+                : contradictionEvidence)
+            : buildFinding("legacy_ordering_cycle", "info", "Ordering cycles between exclusively terminal items are historical contradictions with no scheduling effect.", (count) => `terminal-only execution-order cycle across ${count} item(s)`, cycle, maxSampleSize, "Leave as history debt, or clean up in a dedicated changelog-safe closed-item batch; never repair closed items ad hoc.", contradictionEvidence.length === 0
+                ? undefined
+                : contradictionEvidence));
     }
     const predecessorsByNode = new Map();
     for (const [predecessor, adjacent] of orderingAdjacency)
@@ -448,6 +485,12 @@ function collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExem
     appendFinding(findings, isolates, maxSampleSize, "isolated_active_node", "warning", "Active work should be reachable from the graph unless explicitly declared a valid isolate.", (count) => `${count} active item(s) with no relationships`, "Link the item to its parent, prerequisite, or origin — or register it as an exempt isolate.");
     appendFinding(findings, sparse, maxSampleSize, "sparse_active_node", "info", "Active items with a single edge often miss an honest semantic partner; sparse is not automatically defective.", (count) => `${count} active item(s) with exactly one relationship`, "Investigate for an honest second edge (story->task, defect family, cross-epic complement); do not fabricate one.");
     const edgeCount = assembly.graph.edges().length;
+    const redundantEdges = findRedundantRelationshipEdges(assembly.graph, {
+        signal,
+    }).value;
+    const nonInformativeEdgeKeys = new Set(redundantEdges.map(({ edge }) => `${edge.source.toLowerCase()}\u0000${edge.target.toLowerCase()}\u0000${edge.kind}`));
+    for (const contradiction of assembly.orderingContradictions ?? [])
+        nonInformativeEdgeKeys.add(`${contradiction.holder_id.toLowerCase()}\u0000${contradiction.target_id.toLowerCase()}\u0000${contradiction.dependency_kind}`);
     const sortedEdgesByKind = Object.fromEntries(Object.entries(edgesByKind).sort(([left], [right]) => left.localeCompare(right)));
     const semanticEdges = Object.entries(sortedEdgesByKind).reduce((count, [kind, value]) => count + (isSemanticContextKind(kind) ? value : 0), 0);
     const cutStructure = findRelationshipCutStructure(assembly.graph, {
@@ -458,7 +501,11 @@ function collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExem
         findings,
         profile: {
             nodes: assembly.graph.nodes().length,
+            recorded_nodes: assembly.details.filter((detail) => detail.status !== "missing" && detail.status !== "external").length,
             edges: edgeCount,
+            informative_edges: edgeCount - nonInformativeEdgeKeys.size,
+            redundant_edges: redundantEdges.length,
+            ordering_contradiction_edges: assembly.orderingContradictions?.length ?? 0,
             edge_basis: "deduplicated_directed",
             edges_by_kind: sortedEdgesByKind,
             edge_share_by_kind: Object.fromEntries(Object.entries(sortedEdgesByKind).map(([kind, count]) => [
@@ -496,12 +543,8 @@ export function auditWorkspaceRelationshipGraph(assembly, options = {}) {
     const maxSampleSize = options.maxSampleSize ?? DEFAULT_MAX_SAMPLE_SIZE;
     if (!Number.isInteger(maxSampleSize) || maxSampleSize < 1)
         throw new TypeError(`Invalid audit sample bound: ${String(options.maxSampleSize)}`);
-    const exemptIsolates = new Set((options.exemptIsolates ?? [])
-        .filter((id) => typeof id === "string")
-        .map((id) => id.trim().toLowerCase()));
-    const isolateExemptTypes = new Set((options.isolateExemptTypes ?? [])
-        .filter((type) => typeof type === "string")
-        .map((type) => type.trim().toLowerCase()));
+    const exemptIsolates = normalizeExemptionSet(options.exemptIsolates);
+    const isolateExemptTypes = normalizeExemptionSet(options.isolateExemptTypes);
     const nodeStates = new Map(assembly.details.map((detail) => [
         detail.id,
         {
@@ -518,6 +561,8 @@ export function auditWorkspaceRelationshipGraph(assembly, options = {}) {
         edgesByKind[edge.kind] = (edgesByKind[edge.kind] ?? 0) + 1;
     const findings = collectIntegrityFindings(assembly, isTerminal, maxSampleSize);
     options.signal?.throwIfAborted();
+    findings.push(...collectOrderingStorageContradictionFindings(assembly, maxSampleSize));
+    options.signal?.throwIfAborted();
     findings.push(...collectOrderingFindings(assembly, nodeStates, isBlocked, maxSampleSize));
     options.signal?.throwIfAborted();
     findings.push(...collectDuplicateEdgeFindings(assembly, nodeStates, maxSampleSize), ...collectDuplicateRowFindings(assembly, maxSampleSize));
@@ -556,45 +601,62 @@ function diffCountRecords(baseline, current) {
 function readSnapshotCoverageByType(snapshot) {
     return snapshot.profile.coverage_by_type ?? {};
 }
-/**
- * Compare two point-in-time audit snapshots and return the signed change in
- * findings and structural coverage. This is the temporal primitive behind
- * change-since-baseline audit reporting: agents track census drift across
- * sessions without re-deriving or storing full finding collections.
- */
-export function diffRelationshipAuditSnapshots(baseline, current) {
-    const coverageByType = {};
-    // Public SDK callers may compare legacy or JSON-decoded snapshots created
-    // before per-type coverage was added, even though current typed snapshots
-    // always carry this field.
-    const baselineCoverageByType = readSnapshotCoverageByType(baseline);
-    const currentCoverageByType = readSnapshotCoverageByType(current);
-    const typeKeys = [
+/** Diff per-type coverage while omitting unchanged type rows. */
+function diffCoverageByType(baseline, current) {
+    const deltas = {};
+    const baselineCoverage = readSnapshotCoverageByType(baseline);
+    const currentCoverage = readSnapshotCoverageByType(current);
+    const types = [
         ...new Set([
-            ...Object.keys(baselineCoverageByType),
-            ...Object.keys(currentCoverageByType),
+            ...Object.keys(baselineCoverage),
+            ...Object.keys(currentCoverage),
         ]),
     ].sort();
-    for (const type of typeKeys) {
-        const before = Object.assign({ active: 0, isolated: 0, degree_leq_one: 0 }, baselineCoverageByType[type]);
-        const after = Object.assign({ active: 0, isolated: 0, degree_leq_one: 0 }, currentCoverageByType[type]);
+    for (const type of types) {
+        const before = Object.assign({ active: 0, isolated: 0, degree_leq_one: 0 }, baselineCoverage[type]);
+        const after = Object.assign({ active: 0, isolated: 0, degree_leq_one: 0 }, currentCoverage[type]);
         const delta = {
             active: after.active - before.active,
             isolated: after.isolated - before.isolated,
             degree_leq_one: after.degree_leq_one - before.degree_leq_one,
         };
         if (Object.values(delta).some((value) => value !== 0))
-            coverageByType[type] = delta;
+            deltas[type] = delta;
     }
+    return deltas;
+}
+/**
+ * Compare two point-in-time audit snapshots and return the signed change in
+ * findings and structural coverage. This is the temporal primitive behind
+ * change-since-baseline audit reporting: agents track census drift across
+ * sessions without re-deriving or storing full finding collections.
+ */
+export function diffRelationshipAuditSnapshots(baseline, current) {
+    // Public SDK callers may compare legacy or JSON-decoded snapshots created
+    // before per-type coverage was added, even though current typed snapshots
+    // always carry this field.
+    const coverageByType = diffCoverageByType(baseline, current);
     const { edge_share_by_kind: baselineEdgeShareByKind = {}, semantic_edges: baselineSemanticEdges = 0, semantic_edge_share: baselineSemanticEdgeShare = 0, } = baseline.profile;
     const { edge_share_by_kind: currentEdgeShareByKind = {}, semantic_edges: currentSemanticEdges = 0, semantic_edge_share: currentSemanticEdgeShare = 0, } = current.profile;
+    const baselineRecordedNodes = baseline.profile.recorded_nodes ?? baseline.profile.nodes;
+    const currentRecordedNodes = current.profile.recorded_nodes ?? current.profile.nodes;
+    const baselineInformativeEdges = baseline.profile.informative_edges ?? baseline.profile.edges;
+    const currentInformativeEdges = current.profile.informative_edges ?? current.profile.edges;
+    const baselineRedundantEdges = baseline.profile.redundant_edges ?? 0;
+    const currentRedundantEdges = current.profile.redundant_edges ?? 0;
+    const baselineOrderingContradictionEdges = baseline.profile.ordering_contradiction_edges ?? 0;
+    const currentOrderingContradictionEdges = current.profile.ordering_contradiction_edges ?? 0;
     return {
         baseline_saved_at: baseline.saved_at,
         same_snapshot: baseline.fingerprint === current.fingerprint,
         affected_subjects_by_code: diffCountRecords(baseline.affected_subjects_by_code, current.affected_subjects_by_code),
         profile: {
             nodes: current.profile.nodes - baseline.profile.nodes,
+            recorded_nodes: currentRecordedNodes - baselineRecordedNodes,
             edges: current.profile.edges - baseline.profile.edges,
+            informative_edges: currentInformativeEdges - baselineInformativeEdges,
+            redundant_edges: currentRedundantEdges - baselineRedundantEdges,
+            ordering_contradiction_edges: currentOrderingContradictionEdges - baselineOrderingContradictionEdges,
             active_nodes: current.profile.active_nodes - baseline.profile.active_nodes,
             missing_nodes: current.profile.missing_nodes - baseline.profile.missing_nodes,
             isolated_active_nodes: current.profile.isolated_active_nodes -
@@ -610,4 +672,4 @@ export function diffRelationshipAuditSnapshots(baseline, current) {
     };
 }
 //# sourceMappingURL=governance.js.map
-//# debugId=ab8a4904-0302-5e36-9963-750b3ba79876
+//# debugId=1955b7a4-385d-5a5d-8856-6db9f94814aa

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

@@ -12,8 +12,8 @@ export { computeRelationshipCentrality, findRelationshipCutStructure, type Graph
 export { createRelationshipGraphSnapshot, federateRelationshipGraphSnapshots, loadRelationshipGraphAdapter, MemoryRelationshipGraphAdapter, parseRelationshipGraphSnapshot, RELATIONSHIP_GRAPH_SNAPSHOT_VERSION, syncRelationshipGraphAdapter, type LoadedRelationshipGraphSnapshot, type RelationshipGraphAdapter, type RelationshipGraphAdapterContext, type RelationshipGraphAdapterReplaceContext, type RelationshipGraphAdapterSyncResult, type RelationshipGraphSnapshot, } from "./adapter.js";
 export { assertMemoryRelationshipGraphAdapterConformance, assertRelationshipGraphAdapterConformance, createRelationshipGraphScaleFixture, type RelationshipGraphAdapterConformanceCase, type RelationshipGraphAdapterConformanceReport, type RelationshipGraphScaleFixture, type RelationshipGraphScaleFixtureOptions, type RelationshipGraphScaleTopology, } from "./conformance.js";
 export { analyzeRelationshipSchedule, type GraphScheduleOptions, type RelationshipScheduleAnalysis, type RelationshipScheduleRow, } from "./scheduling.js";
-export { assembleWorkspaceRelationshipGraph, collectDanglingDependencyReferences, collectDuplicateDependencyRows, collectMissingDependencyTargetIds, normalizeDependencyGraphTarget, resolveWorkspaceRelationshipKindRegistry, type DanglingDependencyReference, type DanglingDependencyReferenceSummary, type DependencyReferenceHolder, type DependencyReferenceSource, type DuplicateDependencyRow, type WorkspaceRelationshipAssembly, type WorkspaceRelationshipItem, type WorkspaceRelationshipNodeDetails, } from "./assembly.js";
-export { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, collectOrderingCycles, diffRelationshipAuditSnapshots, formatDuplicateEdgeGroup, type DuplicateRelationshipEdgeGroup, type RelationshipAuditDelta, type RelationshipAuditFinding, type RelationshipAuditFindingCode, type RelationshipAuditOptions, type RelationshipAuditReport, type RelationshipAuditSeverity, type RelationshipAuditSnapshot, type RelationshipCoverageProfile, type RelationshipCoverageTypeProfile, } from "./governance.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 { 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";

package/dist/sdk/graph/index.js

@@ -8,14 +8,14 @@
  * `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]="2c3df51e-6b10-5da6-8340-126465d9c434")}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]="b5509c6e-1431-5316-a563-16681ced4f33")}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";
 export { assertMemoryRelationshipGraphAdapterConformance, assertRelationshipGraphAdapterConformance, createRelationshipGraphScaleFixture, } from "./conformance.js";
 export { analyzeRelationshipSchedule, } from "./scheduling.js";
-export { assembleWorkspaceRelationshipGraph, collectDanglingDependencyReferences, collectDuplicateDependencyRows, collectMissingDependencyTargetIds, normalizeDependencyGraphTarget, resolveWorkspaceRelationshipKindRegistry, } from "./assembly.js";
-export { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, collectOrderingCycles, diffRelationshipAuditSnapshots, formatDuplicateEdgeGroup, } from "./governance.js";
+export { assembleWorkspaceRelationshipGraph, collectDanglingDependencyReferences, collectDuplicateDependencyRows, collectMissingDependencyTargetIds, collectOrderingStorageContradictions, normalizeDependencyGraphTarget, resolveWorkspaceRelationshipKindRegistry, } from "./assembly.js";
+export { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, collectOrderingCycles, diffRelationshipAuditSnapshots, formatDuplicateEdgeGroup, formatOrderingStorageContradiction, } from "./governance.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 +23,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=2c3df51e-6b10-5da6-8340-126465d9c434
+//# debugId=b5509c6e-1431-5316-a563-16681ced4f33

package/dist/sdk/graph/mutation-advisory.js

@@ -1,7 +1,7 @@
 
-!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]="4198a3b2-2541-50eb-bec5-93ac58601f40")}catch(e){}}();
-import { normalizeDependencyGraphTarget, resolveWorkspaceRelationshipKindRegistry, } from "./assembly.js";
-import { collectOrderingCycles } from "./governance.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]="94e8b95b-35fa-5fc7-843a-481497e09b54")}catch(e){}}();
+import { collectOrderingStorageContradictions, normalizeDependencyGraphTarget, resolveWorkspaceRelationshipKindRegistry, } from "./assembly.js";
+import { collectOrderingCycles, formatOrderingStorageContradiction, } from "./governance.js";
 function cycleKey(component) {
     return [...component].sort().join("\u0000");
 }
@@ -153,9 +153,17 @@ export function collectNewOrderingCycleWarnings(beforeItems, afterItems, changed
     const before = collectScopedCycles(beforeItems, registry, changedItemId);
     const after = collectScopedCycles(afterItems, registry, changedItemId);
     const beforeCycles = new Set(before.cycles.map(cycleKey));
-    return after.cycles
-        .filter((component) => !beforeCycles.has(cycleKey(component)))
-        .map((component) => `ordering_cycle_created:${findCyclePath(after.successors, component, after.canonical).join(" -> ")}:items_will_not_be_ready:run_pm_graph_audit`);
+    const beforeContradictions = new Set(collectOrderingStorageContradictions(beforeItems, undefined, registry).map((row) => `${row.holder_id.toLowerCase()}\u0000${row.target_id.toLowerCase()}\u0000${row.dependency_kind}`));
+    const contradictionWarnings = collectOrderingStorageContradictions(afterItems, undefined, registry)
+        .filter((row) => row.holder_id.toLowerCase() === changedItemId.trim().toLowerCase() &&
+        !beforeContradictions.has(`${row.holder_id.toLowerCase()}\u0000${row.target_id.toLowerCase()}\u0000${row.dependency_kind}`))
+        .map((row) => `ordering_storage_contradiction_created:${formatOrderingStorageContradiction(row)}:remove_contradicting_dependency_row:run_pm_graph_audit`);
+    return [
+        ...contradictionWarnings,
+        ...after.cycles
+            .filter((component) => !beforeCycles.has(cycleKey(component)))
+            .map((component) => `ordering_cycle_created:${findCyclePath(after.successors, component, after.canonical).join(" -> ")}:items_will_not_be_ready:run_pm_graph_audit`),
+    ];
 }
 /** White-box graph-path helpers for exhaustive SDK primitive verification. */
 export const mutationAdvisoryTestOnly = {
@@ -166,4 +174,4 @@ export const mutationAdvisoryTestOnly = {
     findPathBackToStart,
 };
 //# sourceMappingURL=mutation-advisory.js.map
-//# debugId=4198a3b2-2541-50eb-bec5-93ac58601f40
+//# debugId=94e8b95b-35fa-5fc7-843a-481497e09b54

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]="9b8e22ad-6268-515d-994e-6b98a062ba93")}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]="1eb0e2cb-084a-5a54-b41c-29dfdd6d2f34")}catch(e){}}();
 import { findRedundantRelationshipEdges } from "./analytics.js";
 import { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, formatDuplicateEdgeGroup, } from "./governance.js";
 /** Per-finding-code operation template applied to every sampled subject. */
@@ -29,6 +29,16 @@ const FINDING_STEP_TEMPLATES = {
         confidence: "high",
         rationale: "Terminal-only ordering cycles have no scheduling effect; repairing them would mutate closed history (changelog drag).",
     },
+    ordering_storage_contradiction: {
+        op: "remove",
+        confidence: "high",
+        rationale: "The structured ordering row asserts the opposite precedence from the same-target scalar blocker; remove that exact dependency row or replace both representations with one unambiguous edge.",
+    },
+    legacy_ordering_storage_contradiction: {
+        op: "remove",
+        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.",
+    },
     // 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.
@@ -155,4 +165,4 @@ export function planRelationshipRemediation(assembly, options = {}) {
     };
 }
 //# sourceMappingURL=remediation.js.map
-//# debugId=9b8e22ad-6268-515d-994e-6b98a062ba93
+//# debugId=1eb0e2cb-084a-5a54-b41c-29dfdd6d2f34

package/dist/sdk/history-read.d.ts

@@ -37,6 +37,14 @@ export interface HistoryVerificationResult {
     current_item_hash?: string;
     /** Whether the supplied document matches the newest history hash. */
     current_matches_latest?: boolean;
+    /** Whether every governed workspace singleton matches the latest replayed state. */
+    workspace_state_matches_latest?: boolean;
+    /** Governed singleton paths whose JSON differs from the replayed value. */
+    workspace_state_mismatches?: string[];
+    /** Governed singleton paths absent from disk. */
+    workspace_state_missing?: string[];
+    /** Governed singleton paths unreadable as safe workspace-local JSON. */
+    workspace_state_unreadable?: string[];
 }
 /**
  * Verify a history chain and optionally compare it with a current document.

package/dist/sdk/history-read.js

@@ -7,7 +7,7 @@
  * systems without acquiring locks or appending history.
  */
 
-!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]="bccbd81b-988f-569d-8dbf-c0998d813953")}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]="04f5d4d2-4021-5ce2-b35a-2134d98d2ad7")}catch(e){}}();
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { pathExists } from "../core/fs/fs-utils.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, replayHistoryToTarget, resolveHistoryTarget, } from "../core/history/projection.js";
@@ -85,4 +85,4 @@ export async function getItemAt(id, target, options = {}) {
 }
 export { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget, resolveHistoryTarget, };
 //# sourceMappingURL=history-read.js.map
-//# debugId=bccbd81b-988f-569d-8dbf-c0998d813953
+//# debugId=04f5d4d2-4021-5ce2-b35a-2134d98d2ad7

package/dist/sdk/history-repair.d.ts

@@ -1,6 +1,7 @@
 import { type ReplayDocument } from "../core/history/replay.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { HistoryEntry } from "../types/index.js";
+import { type ProvenanceNormalizationReceipt } from "./governance/provenance-health.js";
 /** Documents the history repair command options payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairCommandOptions {
     /** Value that configures or reports dry run for this contract. */
@@ -19,6 +20,8 @@ export interface HistoryRepairCommandOptions {
     auditContextById?: Record<string, Record<string, unknown>>;
     /** Add an audit event even when replay and the current item already match. */
     forceAuditEntry?: boolean;
+    /** Remove bounded-domain-invalid provenance observations and record an aggregate privacy-safe audit receipt. */
+    normalizeProvenance?: boolean;
 }
 /** Documents the history repair result payload exchanged by command, SDK, and package integrations. */
 export interface HistoryRepairResult {
@@ -41,6 +44,9 @@ export interface HistoryRepairResult {
         audit_entry_added: boolean;
         verify_ok: boolean;
         verify_errors: string[];
+        item_hash_version_before: number | null;
+        item_hash_version_after: number;
+        version_disposition: "preserved" | "selected_for_ambiguous_stream";
     };
     /** Value that configures or reports item for this contract. */
     item: {
@@ -48,6 +54,10 @@ export interface HistoryRepairResult {
         path: string | null;
         matched_chain_before: boolean | null;
     };
+    /** Privacy-safe receipt for the explicitly requested provenance normalization mode. */
+    provenance_normalization: ProvenanceNormalizationReceipt & {
+        requested: boolean;
+    };
     /** Present when reconciling the chain with the on-disk item discards the replayed effect of earlier history events (GH-603): names the reverted fields and the authors whose mutations the reconciliation overwrites, so cross-author data loss after a lossy merge is loud instead of silent. */
     reconciliation?: HistoryRepairReconciliationReport;
     /** Value that configures or reports warnings for this contract. */
@@ -126,7 +136,9 @@ export interface HistoryRepairAllResult {
     scanned_streams: number;
     /** Value that configures or reports drifted streams for this contract. */
     drifted_streams: number;
-    /** One compact row per drifted stream (clean streams are summarized by the counts only). */
+    /** Streams selected only because invalid provenance required normalization. */
+    provenance_invalid_streams: number;
+    /** One compact row per drifted or provenance-normalization target. */
     streams: HistoryRepairAllStreamResult[];
     /** Value that configures or reports totals for this contract. */
     totals: {

package/dist/sdk/history-repair.js

@@ -4,12 +4,12 @@
  * Implements the pm history repair command surface and its agent-facing runtime behavior.
  */
 
-!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]="dd5ab9c3-bc6f-59f1-be89-ad0ab2abe7b5")}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]="de9b7f82-0f51-599d-b1fa-2d54e3acbdbc")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { patchPathToChangedField } from "../core/history/history-diff.js";
 import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
 import { executeHistoryRewrite, writeHistoryRawWithRollback, } from "../core/history/history-rewrite.js";
-import { historyEntriesToRaw, normalizeReplayPatchOps, reanchorHistoryEntries, replayHash, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
+import { historyEntriesToRaw, normalizeReplayPatchOps, reanchorHistoryEntries, replayHash, resolveHistoryRepairItemHashVersion, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 import { scanHistoryDrift } from "../core/history/drift-scan.js";
 import { invalidateHistoryDriftCache } from "../core/history/drift-cache.js";
 import { readHistoryEntries } from "../core/history/read.js";
@@ -23,6 +23,7 @@ import { listAllItemMetadataWithBody, readLocatedItem, } from "../core/store/ite
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { resolveHistorySubject } from "./history-redact.js";
+import { listInvalidProvenanceHistoryStreamIds, normalizeInvalidHistoryProvenance, } from "./governance/provenance-health.js";
 function replayFieldValue(document, field) {
     return field === "body"
         ? document.body
@@ -133,7 +134,7 @@ export function analyzeReconciliationDiscard(entries, finalReplay, currentItemRe
             : null,
     };
 }
-async function loadHistoryRepairItemReplay(subject, settings, historyEntries) {
+async function loadHistoryRepairItemReplay(subject, settings, historyEntries, itemHashVersion) {
     const currentItemPath = subject.located?.itemPath ?? null;
     const loadedItem = subject.located
         ? await readLocatedItem(subject.located, { schema: settings.schema })
@@ -152,7 +153,7 @@ async function loadHistoryRepairItemReplay(subject, settings, historyEntries) {
     return {
         currentItemReplay,
         currentItemPath,
-        matchedChainBefore: replayHash(currentItemReplay) === lastOriginalAfterHash,
+        matchedChainBefore: replayHash(currentItemReplay, itemHashVersion) === lastOriginalAfterHash,
         currentItemRawBeforeLock: loadedItem.raw,
         loadedItem,
     };
@@ -180,16 +181,19 @@ function buildHistoryRepairEntries(params) {
         patch: params.reconcileNeeded && params.currentItemReplay
             ? jsonPatch.compare(params.finalReplay, params.currentItemReplay)
             : [],
-        before_hash: replayHash(params.finalReplay),
-        after_hash: replayHash(afterReplay),
+        before_hash: replayHash(params.finalReplay, params.itemHashVersion),
+        after_hash: replayHash(afterReplay, params.itemHashVersion),
         message: params.message,
+        ...(params.explicitItemHashVersion
+            ? { item_hash_version: params.itemHashVersion }
+            : {}),
         ...(params.auditContext === undefined
             ? {}
             : { context: params.auditContext }),
     });
     return { rewrittenEntries, auditEntryAdded: true };
 }
-function collectHistoryRepairWarnings(changed, skippedOps) {
+function collectHistoryRepairWarnings(changed, skippedOps, reconciliation) {
     const warnings = [];
     if (!changed) {
         warnings.push("history_repair_no_changes");
@@ -197,6 +201,9 @@ function collectHistoryRepairWarnings(changed, skippedOps) {
     if (skippedOps > 0) {
         warnings.push(`history_repair_skipped_unresolvable_ops:${skippedOps}`);
     }
+    if (reconciliation && reconciliation.discarded_events.length > 0) {
+        warnings.push(`history_repair_reconcile_discards_events:${reconciliation.discarded_events.length}`, `history_repair_discarded_authors:${reconciliation.discarded_authors.join(",")}`);
+    }
     return warnings;
 }
 async function applyHistoryRepairRewrite(params) {
@@ -241,11 +248,28 @@ export async function runHistoryRepair(id, options, global) {
         throw new PmCliError(`No history entries exist for ${subject.id}; nothing to repair.`, EXIT_CODE.USAGE);
     }
     const chainBefore = verifyHistoryChain(historyEntries);
-    const reanchor = reanchorHistoryEntries(historyEntries);
-    const itemReplayContext = await loadHistoryRepairItemReplay(subject, settings, historyEntries);
+    const chainVersionBefore = verifyHistoryChainWithVersion(historyEntries);
+    const provenanceNormalization = options.normalizeProvenance
+        ? normalizeInvalidHistoryProvenance(historyEntries)
+        : {
+            entries: historyEntries,
+            receipt: {
+                changed: false,
+                events_changed: 0,
+                observations_removed: 0,
+                invalid_values: [],
+            },
+        };
+    const itemHashVersion = resolveHistoryRepairItemHashVersion(provenanceNormalization.entries);
+    const explicitVersionsBefore = new Set(provenanceNormalization.entries
+        .map((entry) => entry.item_hash_version)
+        .filter((version) => version !== undefined));
+    const reanchor = reanchorHistoryEntries(provenanceNormalization.entries, itemHashVersion);
+    const itemReplayContext = await loadHistoryRepairItemReplay(subject, settings, historyEntries, itemHashVersion);
     const finalReplay = reanchor.finalDocument;
     const reconcileNeeded = itemReplayContext.currentItemReplay !== null &&
-        replayHash(finalReplay) !== replayHash(itemReplayContext.currentItemReplay);
+        replayHash(finalReplay, itemHashVersion) !==
+            replayHash(itemReplayContext.currentItemReplay, itemHashVersion);
     // GH-603: reconciling toward the on-disk item can silently overwrite the
     // replayed effect of other authors' events (classic after a lossy merge).
     // Surface exactly what is being discarded before any write happens.
@@ -257,6 +281,7 @@ export async function runHistoryRepair(id, options, global) {
         reanchor.entriesPatchRepaired > 0,
         reconcileNeeded,
         options.forceAuditEntry === true,
+        provenanceNormalization.receipt.changed,
     ].some(Boolean);
     const author = resolveAuthor(options.author, settings.author_default);
     const dryRun = Boolean(options.dryRun);
@@ -275,17 +300,20 @@ export async function runHistoryRepair(id, options, global) {
         author,
         message: repairMessage,
         auditOperation: options.auditOperation ?? "history_repair",
-        auditContext: options.auditContext,
+        auditContext: provenanceNormalization.receipt.changed
+            ? {
+                ...options.auditContext,
+                provenance_normalization: provenanceNormalization.receipt,
+            }
+            : options.auditContext,
+        itemHashVersion,
+        explicitItemHashVersion: reanchor.explicitItemHashVersion,
     });
     const historyVerify = verifyHistoryChain(rewrittenEntries);
     if (!historyVerify.ok) {
         throw new PmCliError(`history-repair produced an invalid rewritten chain (${historyVerify.errors.join(", ")}).`, EXIT_CODE.GENERIC_FAILURE);
     }
-    const warnings = collectHistoryRepairWarnings(changed, reanchor.skippedOps);
-    if (reconciliation && reconciliation.discarded_events.length > 0) {
-        warnings.push(`history_repair_reconcile_discards_events:${reconciliation.discarded_events.length}`);
-        warnings.push(`history_repair_discarded_authors:${reconciliation.discarded_authors.join(",")}`);
-    }
+    const warnings = collectHistoryRepairWarnings(changed, reanchor.skippedOps, reconciliation);
     if (changed && !dryRun) {
         warnings.push(...(await applyHistoryRepairRewrite({
             pmRoot,
@@ -317,12 +345,21 @@ export async function runHistoryRepair(id, options, global) {
             audit_entry_added: auditEntryAdded,
             verify_ok: historyVerify.ok,
             verify_errors: historyVerify.errors,
+            item_hash_version_before: chainVersionBefore.item_hash_version ?? null,
+            item_hash_version_after: itemHashVersion,
+            version_disposition: explicitVersionsBefore.size > 1
+                ? "selected_for_ambiguous_stream"
+                : "preserved",
         },
         item: {
             exists: itemReplayContext.currentItemPath !== null,
             path: itemReplayContext.currentItemPath,
             matched_chain_before: itemReplayContext.matchedChainBefore,
         },
+        provenance_normalization: {
+            requested: options.normalizeProvenance === true,
+            ...provenanceNormalization.receipt,
+        },
         ...(reconciliation ? { reconciliation } : {}),
         warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
         generated_at: nowIso(),
@@ -348,10 +385,16 @@ export async function runHistoryRepairAll(options, global) {
     const itemReadWarnings = [];
     const items = await listAllItemMetadataWithBody(pmRoot, settings.item_format, typeRegistry.type_to_folder, itemReadWarnings, settings.schema, { forceSourceScan: true });
     const drift = await scanHistoryDrift(pmRoot, items);
+    const invalidProvenanceIds = options.normalizeProvenance
+        ? await listInvalidProvenanceHistoryStreamIds(pmRoot)
+        : [];
+    const targetedIds = [
+        ...new Set([...drift.driftedItems, ...invalidProvenanceIds]),
+    ].sort((left, right) => left.localeCompare(right));
     const streams = [];
     const repairWarnings = [];
     const totals = { repaired: 0, skipped_clean: 0, failed: 0 };
-    for (const driftedId of drift.driftedItems) {
+    for (const driftedId of targetedIds) {
         try {
             const result = await runHistoryRepair(driftedId, {
                 ...options,
@@ -392,6 +435,7 @@ export async function runHistoryRepairAll(options, global) {
         dry_run: Boolean(options.dryRun),
         scanned_streams: items.length,
         drifted_streams: drift.driftedItems.length,
+        provenance_invalid_streams: invalidProvenanceIds.length,
         streams,
         totals,
         warnings: [...new Set([...itemReadWarnings, ...repairWarnings])].sort((left, right) => left.localeCompare(right)),
@@ -399,4 +443,4 @@ export async function runHistoryRepairAll(options, global) {
     };
 }
 //# sourceMappingURL=history-repair.js.map
-//# debugId=dd5ab9c3-bc6f-59f1-be89-ad0ab2abe7b5
+//# debugId=de9b7f82-0f51-599d-b1fa-2d54e3acbdbc

package/dist/sdk/index.d.ts

@@ -84,7 +84,7 @@ export * from "./history-compact.js";
 export * from "./history-read.js";
 export * from "./history-provenance.js";
 export * from "./mutation-events.js";
-export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
+export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceHistoryStateAgreement, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonReconciliationOptions, type WorkspaceJsonRestoreOptions, type WorkspaceJsonRestoreResult, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
 export * from "./history-redact.js";
 export { _testOnly } from "./history-redact.js";
 export * from "./history-repair.js";