@unbrained/pm-cli 2026.7.20 → 2026.7.21

package/dist/sdk/graph/durable-cache.js

@@ -0,0 +1,205 @@
+/**
+ * @module sdk/graph/durable-cache
+ *
+ * Durable, rebuildable graph query index persisted under the workspace
+ * `runtime/` cache directory. One-shot CLI invocations lose the in-process
+ * {@link WorkspaceGraphCache} memo between commands; this store persists the
+ * fingerprint-keyed deterministic query results (and the audit census
+ * baseline) across processes so repeated bounded queries on an unchanged
+ * workspace are answered without re-running assembly-derived analysis. The
+ * index is never authoritative: every entry is rebuildable from item storage,
+ * a fingerprint mismatch invalidates the whole envelope, corrupt or
+ * version-drifted files are ignored and rewritten, and writes are atomic
+ * (temp-file rename) so a crash can never publish a torn index. Persistence
+ * is optional for small projects: envelopes are written only above an item
+ * threshold or after an explicit `pm graph index --rebuild` opt-in.
+ */
+
+!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]="3c975105-d3de-51f7-939f-1abafd4c3672")}catch(e){}}();
+import path from "node:path";
+import { readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../../core/fs/fs-utils.js";
+import { acquireLock } from "../../core/lock/lock.js";
+/** Envelope format version; any change invalidates persisted entries. */
+export const GRAPH_DURABLE_CACHE_VERSION = 1;
+/** Workspaces below this item count skip implicit persistence. */
+export const GRAPH_DURABLE_CACHE_MIN_ITEMS = 500;
+/** Maximum memoized query results retained in one persisted envelope. */
+const MAX_DURABLE_RESULTS = 64;
+const DURABLE_GRAPH_CACHE_LOCK_ID = "graph-durable-cache";
+/** Serialize cache read-merge-write and clear operations across processes. */
+function acquireDurableGraphCacheLock(pmRoot) {
+    return acquireLock(pmRoot, DURABLE_GRAPH_CACHE_LOCK_ID, 30, `graph-cache:${process.pid}`, false, false, 3_000);
+}
+/** Resolve the durable graph cache file path for one workspace root. */
+export function durableGraphCachePath(pmRoot) {
+    return path.join(pmRoot, "runtime", "graph-cache.json");
+}
+/** Resolve the persisted audit census baseline path for one workspace root. */
+export function graphAuditBaselinePath(pmRoot) {
+    return path.join(pmRoot, "runtime", "graph-audit-baseline.json");
+}
+/** Decode one persisted JSON envelope, returning undefined on any defect. */
+function decodeEnvelope(raw) {
+    if (raw === null)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            parsed.version !==
+                GRAPH_DURABLE_CACHE_VERSION ||
+            typeof parsed.fingerprint !== "string" ||
+            typeof parsed.saved_at !== "string" ||
+            typeof parsed.results !== "object" ||
+            parsed.results === null ||
+            Array.isArray(parsed.results))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        // Corrupt or torn writes must never break queries; the index rebuilds.
+        return undefined;
+    }
+}
+/**
+ * Open the persisted envelope against the current workspace fingerprint. A
+ * missing, corrupt, version-drifted, or fingerprint-mismatched envelope reads
+ * as empty so stale entries can never answer for a mutated workspace.
+ */
+export async function openDurableGraphCache(pmRoot, fingerprint) {
+    const raw = await readFileIfExists(durableGraphCachePath(pmRoot));
+    const envelope = decodeEnvelope(raw);
+    const fresh = envelope?.fingerprint === fingerprint;
+    return {
+        exists: raw !== null,
+        fresh,
+        results: fresh ? envelope.results : {},
+    };
+}
+/**
+ * Persist one query result into the durable envelope, replacing any envelope
+ * recorded for a different fingerprint and trimming the oldest entries beyond
+ * the retention bound. A cross-process lock protects the read-merge-write, and
+ * the final write is atomic, so concurrent queries retain each other's entries.
+ */
+export async function persistDurableGraphResult(pmRoot, fingerprint, view, queryKey, result) {
+    const release = await acquireDurableGraphCacheLock(pmRoot);
+    try {
+        const envelope = decodeEnvelope(await readFileIfExists(durableGraphCachePath(pmRoot)));
+        const results = envelope?.fingerprint === fingerprint ? envelope.results : {};
+        delete results[queryKey];
+        results[queryKey] = result;
+        const keys = Object.keys(results);
+        for (const stale of keys.slice(0, Math.max(0, keys.length - MAX_DURABLE_RESULTS)))
+            delete results[stale];
+        await writeFileAtomic(durableGraphCachePath(pmRoot), JSON.stringify({
+            version: GRAPH_DURABLE_CACHE_VERSION,
+            fingerprint,
+            saved_at: new Date().toISOString(),
+            results,
+        }));
+        view.results = results;
+    }
+    finally {
+        await release();
+    }
+}
+/** Delete the persisted durable graph cache envelope when present. */
+export async function clearDurableGraphCache(pmRoot) {
+    const release = await acquireDurableGraphCacheLock(pmRoot);
+    try {
+        await removeFileIfExists(durableGraphCachePath(pmRoot));
+    }
+    finally {
+        await release();
+    }
+}
+/** Report the durable index status against the current workspace fingerprint. */
+export async function durableGraphCacheStatus(pmRoot, fingerprint) {
+    const cachePath = durableGraphCachePath(pmRoot);
+    const raw = await readFileIfExists(cachePath);
+    const envelope = decodeEnvelope(raw);
+    if (envelope === undefined)
+        return { exists: raw !== null, fresh: false, entry_count: 0 };
+    return {
+        exists: true,
+        fresh: envelope.fingerprint === fingerprint,
+        entry_count: Object.keys(envelope.results).length,
+        fingerprint: envelope.fingerprint.slice(0, 12),
+        saved_at: envelope.saved_at,
+        bytes: Buffer.byteLength(raw, "utf8"),
+    };
+}
+/**
+ * Decide whether implicit persistence applies to this invocation. Small
+ * workspaces skip the index unless an envelope already exists — the explicit
+ * `pm graph index --rebuild` opt-in creates it and thereby enables writes.
+ */
+export function shouldPersistDurableGraphCache(itemCount, envelopeExists) {
+    return envelopeExists || itemCount >= GRAPH_DURABLE_CACHE_MIN_ITEMS;
+}
+/** Return whether a decoded value is a string-keyed non-negative integer count map. */
+function isNonnegativeCountRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((count) => Number.isInteger(count) && count >= 0));
+}
+/** Return whether every decoded item-type coverage entry contains valid counts. */
+function isNonnegativeCoverageByTypeRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    return Object.values(value).every((entry) => typeof entry === "object" &&
+        entry !== null &&
+        !Array.isArray(entry) &&
+        [entry.active, entry.isolated, entry.degree_leq_one].every((count) => Number.isInteger(count) && count >= 0));
+}
+/** Decode one persisted audit census baseline, undefined on any defect. */
+function decodeBaseline(raw) {
+    if (raw === null)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const snapshot = parsed;
+        const profile = snapshot.profile;
+        if (typeof snapshot.saved_at !== "string" ||
+            typeof snapshot.fingerprint !== "string" ||
+            !isNonnegativeCountRecord(snapshot.affected_subjects_by_code) ||
+            typeof profile !== "object" ||
+            profile === null ||
+            ![
+                profile.nodes,
+                profile.edges,
+                profile.active_nodes,
+                profile.missing_nodes,
+                profile.isolated_active_nodes,
+                profile.degree_leq_one_active_nodes,
+            ].every((value) => Number.isInteger(value) && value >= 0) ||
+            !isNonnegativeCountRecord(profile.edges_by_kind) ||
+            (profile.coverage_by_type !== undefined &&
+                !isNonnegativeCoverageByTypeRecord(profile.coverage_by_type)))
+            return undefined;
+        return {
+            ...snapshot,
+            profile: {
+                ...profile,
+                coverage_by_type: profile.coverage_by_type ?? {},
+            },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Load the persisted audit census baseline when present and decodable. */
+export async function loadGraphAuditBaseline(pmRoot) {
+    return decodeBaseline(await readFileIfExists(graphAuditBaselinePath(pmRoot)));
+}
+/** Atomically persist one audit census snapshot as the comparison baseline. */
+export async function saveGraphAuditBaseline(pmRoot, snapshot) {
+    await writeFileAtomic(graphAuditBaselinePath(pmRoot), JSON.stringify(snapshot));
+}
+//# sourceMappingURL=durable-cache.js.map
+//# debugId=3c975105-d3de-51f7-939f-1abafd4c3672

package/dist/sdk/graph/durable-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-cache.js","sources":["sdk/graph/durable-cache.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/graph/durable-cache\n *\n * Durable, rebuildable graph query index persisted under the workspace\n * `runtime/` cache directory. One-shot CLI invocations lose the in-process\n * {@link WorkspaceGraphCache} memo between commands; this store persists the\n * fingerprint-keyed deterministic query results (and the audit census\n * baseline) across processes so repeated bounded queries on an unchanged\n * workspace are answered without re-running assembly-derived analysis. The\n * index is never authoritative: every entry is rebuildable from item storage,\n * a fingerprint mismatch invalidates the whole envelope, corrupt or\n * version-drifted files are ignored and rewritten, and writes are atomic\n * (temp-file rename) so a crash can never publish a torn index. Persistence\n * is optional for small projects: envelopes are written only above an item\n * threshold or after an explicit `pm graph index --rebuild` opt-in.\n */\nimport path from \"node:path\";\nimport {\n  readFileIfExists,\n  removeFileIfExists,\n  writeFileAtomic,\n} from \"../../core/fs/fs-utils.js\";\nimport { acquireLock } from \"../../core/lock/lock.js\";\nimport type { RelationshipAuditSnapshot } from \"./governance.js\";\n\n/** Envelope format version; any change invalidates persisted entries. */\nexport const GRAPH_DURABLE_CACHE_VERSION = 1;\n\n/** Workspaces below this item count skip implicit persistence. */\nexport const GRAPH_DURABLE_CACHE_MIN_ITEMS = 500;\n\n/** Maximum memoized query results retained in one persisted envelope. */\nconst MAX_DURABLE_RESULTS = 64;\nconst DURABLE_GRAPH_CACHE_LOCK_ID = \"graph-durable-cache\";\n\n/** Serialize cache read-merge-write and clear operations across processes. */\nfunction acquireDurableGraphCacheLock(\n  pmRoot: string,\n): Promise<() => Promise<void>> {\n  return acquireLock(\n    pmRoot,\n    DURABLE_GRAPH_CACHE_LOCK_ID,\n    30,\n    `graph-cache:${process.pid}`,\n    false,\n    false,\n    3_000,\n  );\n}\n\n/** Persisted durable graph cache envelope keyed by one workspace fingerprint. */\nexport interface DurableGraphCacheEnvelope {\n  /** Envelope format version guarding decode compatibility. */\n  version: number;\n  /** Full workspace graph fingerprint every entry answers for. */\n  fingerprint: string;\n  /** ISO timestamp of the last persisted write. */\n  saved_at: string;\n  /** Deterministic query results keyed by their canonical query key. */\n  results: Record<string, unknown>;\n}\n\n/** Compact durable index status projection for observability surfaces. */\nexport interface DurableGraphCacheStatus {\n  /** Whether an envelope file exists on disk. */\n  exists: boolean;\n  /** Whether the stored fingerprint matches the current workspace snapshot. */\n  fresh: boolean;\n  /** Stored entry count, 0 when absent. */\n  entry_count: number;\n  /** Truncated stored fingerprint, absent when no envelope exists. */\n  fingerprint?: string;\n  /** ISO timestamp of the last persisted write, absent when no envelope exists. */\n  saved_at?: string;\n  /** Envelope file size in bytes, absent when no envelope exists. */\n  bytes?: number;\n}\n\n/** Resolve the durable graph cache file path for one workspace root. */\nexport function durableGraphCachePath(pmRoot: string): string {\n  return path.join(pmRoot, \"runtime\", \"graph-cache.json\");\n}\n\n/** Resolve the persisted audit census baseline path for one workspace root. */\nexport function graphAuditBaselinePath(pmRoot: string): string {\n  return path.join(pmRoot, \"runtime\", \"graph-audit-baseline.json\");\n}\n\n/** Decode one persisted JSON envelope, returning undefined on any defect. */\nfunction decodeEnvelope(\n  raw: string | null,\n): DurableGraphCacheEnvelope | undefined {\n  if (raw === null) return undefined;\n  try {\n    const parsed: unknown = JSON.parse(raw);\n    if (\n      typeof parsed !== \"object\" ||\n      parsed === null ||\n      (parsed as DurableGraphCacheEnvelope).version !==\n        GRAPH_DURABLE_CACHE_VERSION ||\n      typeof (parsed as DurableGraphCacheEnvelope).fingerprint !== \"string\" ||\n      typeof (parsed as DurableGraphCacheEnvelope).saved_at !== \"string\" ||\n      typeof (parsed as DurableGraphCacheEnvelope).results !== \"object\" ||\n      (parsed as DurableGraphCacheEnvelope).results === null ||\n      Array.isArray((parsed as DurableGraphCacheEnvelope).results)\n    )\n      return undefined;\n    return parsed as DurableGraphCacheEnvelope;\n  } catch {\n    // Corrupt or torn writes must never break queries; the index rebuilds.\n    return undefined;\n  }\n}\n\n/** One opened durable index view bound to the current workspace fingerprint. */\nexport interface DurableGraphCacheView {\n  /** Whether any envelope file exists on disk, fresh or not. */\n  exists: boolean;\n  /** Whether the stored envelope answers for the current fingerprint. */\n  fresh: boolean;\n  /** Fingerprint-fresh persisted query results; empty when absent or stale. */\n  results: Record<string, unknown>;\n}\n\n/**\n * Open the persisted envelope against the current workspace fingerprint. A\n * missing, corrupt, version-drifted, or fingerprint-mismatched envelope reads\n * as empty so stale entries can never answer for a mutated workspace.\n */\nexport async function openDurableGraphCache(\n  pmRoot: string,\n  fingerprint: string,\n): Promise<DurableGraphCacheView> {\n  const raw = await readFileIfExists(durableGraphCachePath(pmRoot));\n  const envelope = decodeEnvelope(raw);\n  const fresh = envelope?.fingerprint === fingerprint;\n  return {\n    exists: raw !== null,\n    fresh,\n    results: fresh ? envelope!.results : {},\n  };\n}\n\n/**\n * Persist one query result into the durable envelope, replacing any envelope\n * recorded for a different fingerprint and trimming the oldest entries beyond\n * the retention bound. A cross-process lock protects the read-merge-write, and\n * the final write is atomic, so concurrent queries retain each other's entries.\n */\nexport async function persistDurableGraphResult(\n  pmRoot: string,\n  fingerprint: string,\n  view: DurableGraphCacheView,\n  queryKey: string,\n  result: unknown,\n): Promise<void> {\n  const release = await acquireDurableGraphCacheLock(pmRoot);\n  try {\n    const envelope = decodeEnvelope(\n      await readFileIfExists(durableGraphCachePath(pmRoot)),\n    );\n    const results =\n      envelope?.fingerprint === fingerprint ? envelope.results : {};\n    delete results[queryKey];\n    results[queryKey] = result;\n    const keys = Object.keys(results);\n    for (const stale of keys.slice(\n      0,\n      Math.max(0, keys.length - MAX_DURABLE_RESULTS),\n    ))\n      delete results[stale];\n    await writeFileAtomic(\n      durableGraphCachePath(pmRoot),\n      JSON.stringify({\n        version: GRAPH_DURABLE_CACHE_VERSION,\n        fingerprint,\n        saved_at: new Date().toISOString(),\n        results,\n      }),\n    );\n    view.results = results;\n  } finally {\n    await release();\n  }\n}\n\n/** Delete the persisted durable graph cache envelope when present. */\nexport async function clearDurableGraphCache(pmRoot: string): Promise<void> {\n  const release = await acquireDurableGraphCacheLock(pmRoot);\n  try {\n    await removeFileIfExists(durableGraphCachePath(pmRoot));\n  } finally {\n    await release();\n  }\n}\n\n/** Report the durable index status against the current workspace fingerprint. */\nexport async function durableGraphCacheStatus(\n  pmRoot: string,\n  fingerprint: string,\n): Promise<DurableGraphCacheStatus> {\n  const cachePath = durableGraphCachePath(pmRoot);\n  const raw = await readFileIfExists(cachePath);\n  const envelope = decodeEnvelope(raw);\n  if (envelope === undefined)\n    return { exists: raw !== null, fresh: false, entry_count: 0 };\n  return {\n    exists: true,\n    fresh: envelope.fingerprint === fingerprint,\n    entry_count: Object.keys(envelope.results).length,\n    fingerprint: envelope.fingerprint.slice(0, 12),\n    saved_at: envelope.saved_at,\n    bytes: Buffer.byteLength(raw!, \"utf8\"),\n  };\n}\n\n/**\n * Decide whether implicit persistence applies to this invocation. Small\n * workspaces skip the index unless an envelope already exists — the explicit\n * `pm graph index --rebuild` opt-in creates it and thereby enables writes.\n */\nexport function shouldPersistDurableGraphCache(\n  itemCount: number,\n  envelopeExists: boolean,\n): boolean {\n  return envelopeExists || itemCount >= GRAPH_DURABLE_CACHE_MIN_ITEMS;\n}\n\n/** Return whether a decoded value is a string-keyed non-negative integer count map. */\nfunction isNonnegativeCountRecord(\n  value: unknown,\n): value is Record<string, number> {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    !Array.isArray(value) &&\n    Object.values(value).every((count) => Number.isInteger(count) && count >= 0)\n  );\n}\n\n/** Return whether every decoded item-type coverage entry contains valid counts. */\nfunction isNonnegativeCoverageByTypeRecord(value: unknown): boolean {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value))\n    return false;\n  return Object.values(value).every(\n    (entry) =>\n      typeof entry === \"object\" &&\n      entry !== null &&\n      !Array.isArray(entry) &&\n      [entry.active, entry.isolated, entry.degree_leq_one].every(\n        (count) => Number.isInteger(count) && count >= 0,\n      ),\n  );\n}\n\n/** Decode one persisted audit census baseline, undefined on any defect. */\nfunction decodeBaseline(\n  raw: string | null,\n): RelationshipAuditSnapshot | undefined {\n  if (raw === null) return undefined;\n  try {\n    const parsed: unknown = JSON.parse(raw);\n    if (typeof parsed !== \"object\" || parsed === null) return undefined;\n    const snapshot = parsed as Partial<RelationshipAuditSnapshot>;\n    const profile = snapshot.profile;\n    if (\n      typeof snapshot.saved_at !== \"string\" ||\n      typeof snapshot.fingerprint !== \"string\" ||\n      !isNonnegativeCountRecord(snapshot.affected_subjects_by_code) ||\n      typeof profile !== \"object\" ||\n      profile === null ||\n      ![\n        profile.nodes,\n        profile.edges,\n        profile.active_nodes,\n        profile.missing_nodes,\n        profile.isolated_active_nodes,\n        profile.degree_leq_one_active_nodes,\n      ].every((value) => Number.isInteger(value) && value >= 0) ||\n      !isNonnegativeCountRecord(profile.edges_by_kind) ||\n      (profile.coverage_by_type !== undefined &&\n        !isNonnegativeCoverageByTypeRecord(profile.coverage_by_type))\n    )\n      return undefined;\n    return {\n      ...snapshot,\n      profile: {\n        ...profile,\n        coverage_by_type: profile.coverage_by_type ?? {},\n      },\n    } as RelationshipAuditSnapshot;\n  } catch {\n    return undefined;\n  }\n}\n\n/** Load the persisted audit census baseline when present and decodable. */\nexport async function loadGraphAuditBaseline(\n  pmRoot: string,\n): Promise<RelationshipAuditSnapshot | undefined> {\n  return decodeBaseline(await readFileIfExists(graphAuditBaselinePath(pmRoot)));\n}\n\n/** Atomically persist one audit census snapshot as the comparison baseline. */\nexport async function saveGraphAuditBaseline(\n  pmRoot: string,\n  snapshot: RelationshipAuditSnapshot,\n): Promise<void> {\n  await writeFileAtomic(\n    graphAuditBaselinePath(pmRoot),\n    JSON.stringify(snapshot),\n  );\n}\n"],"names":[],"mappings":"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","debugId":"3c975105-d3de-51f7-939f-1abafd4c3672"}

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

@@ -17,7 +17,7 @@ import type { WorkspaceRelationshipAssembly } from "./assembly.js";
 /** Severity ladder shared by every relationship audit finding. */
 export type RelationshipAuditSeverity = "error" | "warning" | "info";
 /** Machine-readable identifier for one relationship audit finding family. */
-export type RelationshipAuditFindingCode = "missing_reference_active" | "missing_reference_terminal" | "legacy_no_blocker_sentinel" | "ordering_cycle" | "legacy_ordering_cycle" | "duplicate_edge" | "legacy_duplicate_edge" | "stale_lifecycle_block" | "isolated_active_node" | "sparse_active_node";
+export type RelationshipAuditFindingCode = "missing_reference_active" | "missing_reference_terminal" | "legacy_no_blocker_sentinel" | "ordering_cycle" | "legacy_ordering_cycle" | "duplicate_edge" | "legacy_duplicate_edge" | "duplicate_dependency_row" | "legacy_duplicate_dependency_row" | "stale_lifecycle_block" | "isolated_active_node" | "sparse_active_node";
 /** One policy-aware relationship audit finding with bounded evidence. */
 export interface RelationshipAuditFinding {
     /** Machine-readable finding family identifier. */
@@ -37,6 +37,15 @@ export interface RelationshipAuditFinding {
     /** Safe machine-actionable next step; audits never invent or auto-apply edges. */
     remediation: string;
 }
+/** Per-item-type connectivity coverage inside a coverage profile. */
+export interface RelationshipCoverageTypeProfile {
+    /** Active nodes declaring this item type. */
+    active: number;
+    /** Active nodes of this type with no incident edges. */
+    isolated: number;
+    /** Active nodes of this type with at most one incident edge, isolates included. */
+    degree_leq_one: number;
+}
 /** Aggregate structural coverage metrics for one assembled workspace graph. */
 export interface RelationshipCoverageProfile {
     /** Total indexed nodes including materialized missing placeholders. */
@@ -53,6 +62,8 @@ export interface RelationshipCoverageProfile {
     isolated_active_nodes: number;
     /** Active nodes with at most one incident edge, isolates included. */
     degree_leq_one_active_nodes: number;
+    /** Deterministic per-type connectivity coverage; untyped nodes bucket under `(untyped)`. */
+    coverage_by_type: Record<string, RelationshipCoverageTypeProfile>;
 }
 /** Tuning and policy inputs accepted by the relationship audit. */
 export interface RelationshipAuditOptions {
@@ -62,6 +73,8 @@ export interface RelationshipAuditOptions {
     isBlocked?: (status: string) => boolean;
     /** Node identifiers that are explicitly valid isolates (roots, archives, scratch work). */
     exemptIsolates?: readonly string[];
+    /** Item types whose active nodes are policy-valid isolates or sparse nodes (case-insensitive); they stay in the coverage profile but raise no coverage finding. */
+    isolateExemptTypes?: readonly string[];
     /** Maximum sample entries retained per finding; defaults to 25. */
     maxSampleSize?: number;
     /** Abort signal checked between finding families. */
@@ -74,6 +87,15 @@ export interface RelationshipAuditReport {
     /** Structural coverage metrics computed during the audit. */
     profile: RelationshipCoverageProfile;
 }
+/**
+ * Enumerate strongly connected components with more than one member (or a
+ * self-loop) over an ordering-only successor digraph using an iterative Tarjan
+ * traversal. Only order-bearing kinds should participate: associative kinds
+ * such as `related` cannot create execution-order contradictions and stay out
+ * of cycle analysis by policy. Exported so incremental consumers (mutation
+ * advisories) share one cycle semantics with the workspace audit.
+ */
+export declare function collectOrderingCycles(successors: Map<string, string[]>): string[][];
 /** One duplicate-edge group in semantic orientation with its stored spellings. */
 export interface DuplicateRelationshipEdgeGroup {
     /** Semantic tail node shared by every stored spelling. */
@@ -106,3 +128,49 @@ export declare function collectDuplicateRelationshipEdgeGroups(assembly: Workspa
  * members so callers can decide which edge to retype, remove, or waive.
  */
 export declare function auditWorkspaceRelationshipGraph(assembly: WorkspaceRelationshipAssembly, options?: RelationshipAuditOptions): RelationshipAuditReport;
+/** One persisted point-in-time audit census used for temporal comparison. */
+export interface RelationshipAuditSnapshot {
+    /** ISO timestamp the snapshot was taken at. */
+    saved_at: string;
+    /** Workspace graph fingerprint of the audited item snapshot. */
+    fingerprint: string;
+    /** Affected-subject counts keyed by finding code at snapshot time. */
+    affected_subjects_by_code: Record<string, number>;
+    /** Structural coverage profile at snapshot time. */
+    profile: RelationshipCoverageProfile;
+}
+/** Signed change between two audit snapshots; zero-change keys are dropped. */
+export interface RelationshipAuditDelta {
+    /** ISO timestamp of the baseline snapshot the delta is measured against. */
+    baseline_saved_at: string;
+    /** Whether both snapshots audited the identical workspace fingerprint. */
+    same_snapshot: boolean;
+    /** Signed affected-subject deltas keyed by finding code. */
+    affected_subjects_by_code: Record<string, number>;
+    /** Signed structural profile deltas. */
+    profile: {
+        /** Node-count change including missing placeholders. */
+        nodes: number;
+        /** Deduplicated edge-count change. */
+        edges: number;
+        /** Active-node-count change. */
+        active_nodes: number;
+        /** Missing-placeholder-count change. */
+        missing_nodes: number;
+        /** Isolated-active-node-count change. */
+        isolated_active_nodes: number;
+        /** Degree-at-most-one active-node-count change. */
+        degree_leq_one_active_nodes: number;
+        /** Signed per-kind edge-count deltas; unchanged kinds are dropped. */
+        edges_by_kind: Record<string, number>;
+        /** Signed per-type coverage deltas; unchanged types are dropped. */
+        coverage_by_type: Record<string, RelationshipCoverageTypeProfile>;
+    };
+}
+/**
+ * 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 declare function diffRelationshipAuditSnapshots(baseline: RelationshipAuditSnapshot, current: RelationshipAuditSnapshot): RelationshipAuditDelta;

package/dist/sdk/graph/governance.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]="a78eee2f-0423-565f-91b6-88d0ab46d529")}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]="4b36a9d4-2621-5560-831f-7fd026072cf1")}catch(e){}}();
 import { isTransitiveKind, orientTransitiveEdge, transitiveFamilyKey, } from "./analytics.js";
 /** Default bounded sample size applied to every finding family. */
 const DEFAULT_MAX_SAMPLE_SIZE = 25;
@@ -93,12 +93,14 @@ function completeTarjanFrame(frame, frames, successors, state) {
         state.components.push(component.sort((left, right) => left.localeCompare(right)));
 }
 /**
- * Enumerate strongly connected components with more than one member over the
- * ordering-only digraph using an iterative Tarjan traversal. Only order-bearing
- * kinds participate: associative kinds such as `related` cannot create
- * execution-order contradictions and stay out of cycle analysis by policy.
+ * Enumerate strongly connected components with more than one member (or a
+ * self-loop) over an ordering-only successor digraph using an iterative Tarjan
+ * traversal. Only order-bearing kinds should participate: associative kinds
+ * such as `related` cannot create execution-order contradictions and stay out
+ * of cycle analysis by policy. Exported so incremental consumers (mutation
+ * advisories) share one cycle semantics with the workspace audit.
  */
-function collectOrderingCycles(successors) {
+export function collectOrderingCycles(successors) {
     const state = {
         indexes: new Map(),
         lowLinks: new Map(),
@@ -258,39 +260,75 @@ function collectDuplicateEdgeFindings(assembly, nodeStates, maxSampleSize) {
     appendFinding(findings, legacy, maxSampleSize, "legacy_duplicate_edge", "info", "Duplicated spellings between exclusively terminal items are historical noise with no scheduling effect.", (count) => `${count} duplicated relationship(s) between terminal endpoints`, "Leave as history debt or clean up in a dedicated changelog-safe closed-item batch.");
     return findings;
 }
-/** Compute structural coverage metrics and coverage-policy findings. */
-function collectCoverageReport(assembly, nodeStates, exemptIsolates, maxSampleSize, edgesByKind) {
-    let activeNodes = 0;
-    let missingNodes = 0;
-    let isolatedActiveNodes = 0;
-    let degreeLeqOneActive = 0;
-    const isolates = [];
-    const sparse = [];
+/**
+ * Collect storage-integrity findings for raw dependency rows whose exact
+ * identity is stored more than once on one holder. Graph edge-identity dedup
+ * hides these from every assembled-graph surface (duplicate_edge only covers
+ * cross-spelling parallels), so the audit reports them from the pre-assembly
+ * scan carried on the assembly.
+ */
+function collectDuplicateRowFindings(assembly, maxSampleSize) {
+    const active = [];
+    const legacy = [];
+    // Public/JSON-parsed assemblies produced before duplicate-row governance may omit this field.
+    for (const row of assembly.duplicateRows ?? []) {
+        (row.legacy_terminal ? legacy : active).push(`${row.holder_id} -> ${row.target_id} (${row.kind} x${row.occurrences})`);
+    }
+    const findings = [];
+    appendFinding(findings, active, maxSampleSize, "duplicate_dependency_row", "warning", "One dependency row must be stored once per holder; identical repeated rows are a storage-layer defect invisible to the assembled graph.", (count) => `${count} exactly duplicated stored dependency row(s) on active holder(s)`, "Remove the repeated rows so the dependency is stored exactly once; graph semantics are unchanged.");
+    appendFinding(findings, legacy, maxSampleSize, "legacy_duplicate_dependency_row", "info", "Identical repeated dependency rows on terminal holders are historical storage noise with no scheduling effect.", (count) => `${count} exactly duplicated stored dependency row(s) on terminal holder(s)`, "Leave as history debt or clean up in a dedicated changelog-safe closed-item batch.");
+    return findings;
+}
+/** Fold one active node's degree into the aggregate and per-type coverage tallies. */
+function tallyActiveCoverageNode(tallies, state, degree, exemptIsolates, isolateExemptTypes) {
+    tallies.active += 1;
+    const typeKey = state.type ?? "(untyped)";
+    let typeProfile = tallies.byType.get(typeKey);
+    if (!typeProfile) {
+        typeProfile = { active: 0, isolated: 0, degree_leq_one: 0 };
+        tallies.byType.set(typeKey, typeProfile);
+    }
+    typeProfile.active += 1;
+    if (degree > 1)
+        return;
+    tallies.degreeLeqOne += 1;
+    typeProfile.degree_leq_one += 1;
+    if (degree === 0) {
+        tallies.isolated += 1;
+        typeProfile.isolated += 1;
+    }
+    if (exemptIsolates.has(state.id.toLowerCase()) ||
+        isolateExemptTypes.has(typeKey.toLowerCase()))
+        return;
+    if (degree === 0)
+        tallies.isolates.push(state.id);
+    else
+        tallies.sparse.push(state.id);
+}
+function collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExemptTypes, maxSampleSize, edgesByKind) {
+    const tallies = {
+        active: 0,
+        missing: 0,
+        isolated: 0,
+        degreeLeqOne: 0,
+        isolates: [],
+        sparse: [],
+        byType: new Map(),
+    };
     for (const id of assembly.graph.nodes()) {
         const state = nodeStates.get(id);
         /* c8 ignore next -- every graph node originates from assembly details by construction */
         if (!state)
             continue;
         if (state.missing) {
-            missingNodes += 1;
+            tallies.missing += 1;
             continue;
         }
         if (state.terminal)
             continue;
-        activeNodes += 1;
-        const degree = assembly.graph.incidentEdges(id).length;
-        if (degree > 1)
-            continue;
-        degreeLeqOneActive += 1;
-        if (degree === 0)
-            isolatedActiveNodes += 1;
-        if (exemptIsolates.has(id.toLowerCase()))
-            continue;
-        if (degree === 0)
-            isolates.push(id);
-        else
-            sparse.push(id);
+        tallyActiveCoverageNode(tallies, state, assembly.graph.incidentEdges(id).length, exemptIsolates, isolateExemptTypes);
     }
+    const { isolates, sparse } = tallies;
     const findings = [];
     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.");
@@ -300,10 +338,11 @@ function collectCoverageReport(assembly, nodeStates, exemptIsolates, maxSampleSi
             nodes: assembly.graph.nodes().length,
             edges: assembly.graph.edges().length,
             edges_by_kind: Object.fromEntries(Object.entries(edgesByKind).sort(([left], [right]) => left.localeCompare(right))),
-            active_nodes: activeNodes,
-            missing_nodes: missingNodes,
-            isolated_active_nodes: isolatedActiveNodes,
-            degree_leq_one_active_nodes: degreeLeqOneActive,
+            active_nodes: tallies.active,
+            missing_nodes: tallies.missing,
+            isolated_active_nodes: tallies.isolated,
+            degree_leq_one_active_nodes: tallies.degreeLeqOne,
+            coverage_by_type: Object.fromEntries([...tallies.byType.entries()].sort(([left], [right]) => left < right ? -1 : 1)),
         },
     };
 }
@@ -327,6 +366,9 @@ export function auditWorkspaceRelationshipGraph(assembly, options = {}) {
     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 nodeStates = new Map(assembly.details.map((detail) => [
         detail.id,
         {
@@ -334,6 +376,7 @@ export function auditWorkspaceRelationshipGraph(assembly, options = {}) {
             status: detail.status,
             missing: assembly.missingIdSet.has(detail.id.toLowerCase()),
             terminal: isTerminal(detail.status),
+            ...(detail.type === undefined ? {} : { type: detail.type }),
         },
     ]));
     options.signal?.throwIfAborted();
@@ -344,9 +387,9 @@ export function auditWorkspaceRelationshipGraph(assembly, options = {}) {
     options.signal?.throwIfAborted();
     findings.push(...collectOrderingFindings(assembly, nodeStates, isBlocked, maxSampleSize));
     options.signal?.throwIfAborted();
-    findings.push(...collectDuplicateEdgeFindings(assembly, nodeStates, maxSampleSize));
+    findings.push(...collectDuplicateEdgeFindings(assembly, nodeStates, maxSampleSize), ...collectDuplicateRowFindings(assembly, maxSampleSize));
     options.signal?.throwIfAborted();
-    const coverage = collectCoverageReport(assembly, nodeStates, exemptIsolates, maxSampleSize, edgesByKind);
+    const coverage = collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExemptTypes, maxSampleSize, edgesByKind);
     findings.push(...coverage.findings);
     findings.sort((left, right) => SEVERITY_RANK[left.severity] - SEVERITY_RANK[right.severity] ||
         left.code.localeCompare(right.code) ||
@@ -356,5 +399,70 @@ export function auditWorkspaceRelationshipGraph(assembly, options = {}) {
         profile: coverage.profile,
     };
 }
+/** Subtract two count records, keeping only non-zero signed deltas in sorted key order. */
+function diffCountRecords(baseline, current) {
+    const keys = [
+        ...new Set([...Object.keys(baseline), ...Object.keys(current)]),
+    ].sort();
+    const deltas = {};
+    for (const key of keys) {
+        const delta = (current[key] ?? 0) - (baseline[key] ?? 0);
+        if (delta !== 0)
+            deltas[key] = delta;
+    }
+    return deltas;
+}
+/** Read per-type coverage defensively from current or legacy runtime snapshots. */
+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 = [
+        ...new Set([
+            ...Object.keys(baselineCoverageByType),
+            ...Object.keys(currentCoverageByType),
+        ]),
+    ].sort();
+    for (const type of typeKeys) {
+        const before = baselineCoverageByType[type];
+        const after = currentCoverageByType[type];
+        const delta = {
+            active: (after?.active ?? 0) - (before?.active ?? 0),
+            isolated: (after?.isolated ?? 0) - (before?.isolated ?? 0),
+            degree_leq_one: (after?.degree_leq_one ?? 0) - (before?.degree_leq_one ?? 0),
+        };
+        if (Object.values(delta).some((value) => value !== 0))
+            coverageByType[type] = delta;
+    }
+    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,
+            edges: current.profile.edges - baseline.profile.edges,
+            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 -
+                baseline.profile.isolated_active_nodes,
+            degree_leq_one_active_nodes: current.profile.degree_leq_one_active_nodes -
+                baseline.profile.degree_leq_one_active_nodes,
+            edges_by_kind: diffCountRecords(baseline.profile.edges_by_kind, current.profile.edges_by_kind),
+            coverage_by_type: coverageByType,
+        },
+    };
+}
 //# sourceMappingURL=governance.js.map
-//# debugId=a78eee2f-0423-565f-91b6-88d0ab46d529
+//# debugId=4b36a9d4-2621-5560-831f-7fd026072cf1