@unbrained/pm-cli 2026.9.6 → 2026.9.8

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

@@ -1,362 +1,2 @@
-/**
- * @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]="9e4aa41d-fca4-5e55-ab2b-d99f06d90ae2")}catch(e){}}();
-import path from "node:path";
-import { readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../../core/fs/fs-utils.js";
-import { acquireLock } from "../../core/lock/lock.js";
-import { isSemanticContextKind, } from "./governance.js";
-import { RELATIONSHIP_AUDIT_FINDING_CODES } from "./governance-contracts.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 isRecord(value) && Object.values(value).every(isNonnegativeInteger);
-}
-/** Return whether a decoded value is a non-array record. */
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** Return whether a decoded value is a non-negative integer. */
-function isNonnegativeInteger(value) {
-    return Number.isInteger(value) && Number(value) >= 0;
-}
-/** Return whether a decoded value is a finite share in the inclusive unit interval. */
-function isUnitShare(value) {
-    return (typeof value === "number" &&
-        Number.isFinite(value) &&
-        value >= 0 &&
-        value <= 1);
-}
-/** Apply a validator only when an optional decoded value is present. */
-function isOptionalValid(value, validate) {
-    return value === undefined || validate(value);
-}
-/** Return whether a decoded record contains finite shares in the inclusive unit interval. */
-function isUnitShareRecord(value) {
-    return isRecord(value) && Object.values(value).every(isUnitShare);
-}
-/** Return whether every decoded item-type coverage entry contains valid counts. */
-function isNonnegativeCoverageByTypeRecord(value) {
-    if (!isRecord(value))
-        return false;
-    return Object.values(value).every((entry) => isRecord(entry) &&
-        [entry.active, entry.isolated, entry.degree_leq_one].every(isNonnegativeInteger));
-}
-/** Decode the additive information-bearing census as one coherent field group. */
-function decodeInformativeProfile(profile, nodes, edges) {
-    const fields = [
-        "recorded_nodes",
-        "informative_edges",
-        "redundant_edges",
-        "ordering_contradiction_edges",
-    ];
-    const presentCount = fields.filter((field) => profile[field] !== undefined).length;
-    if (presentCount !== 0 && presentCount !== fields.length)
-        return undefined;
-    if (!fields.every((field) => isOptionalValid(profile[field], isNonnegativeInteger)))
-        return undefined;
-    const decoded = {
-        recorded_nodes: profile.recorded_nodes ?? nodes,
-        informative_edges: profile.informative_edges ?? edges,
-        redundant_edges: profile.redundant_edges ?? 0,
-        ordering_contradiction_edges: profile.ordering_contradiction_edges ?? 0,
-    };
-    return decoded.recorded_nodes <= nodes &&
-        decoded.informative_edges <= edges &&
-        decoded.redundant_edges <= edges &&
-        decoded.ordering_contradiction_edges <= edges
-        ? decoded
-        : undefined;
-}
-/** Validate the optional structural census fields as one complete version group. */
-function hasValidStructuralFields(profile, countFields, rateFields) {
-    const introducedFields = [
-        ...countFields,
-        ...rateFields,
-        "finding_subjects_by_code",
-    ];
-    const presentCount = introducedFields.filter((field) => profile[field] !== undefined).length;
-    if (presentCount !== 0 && presentCount !== introducedFields.length)
-        return false;
-    return (countFields.every((field) => isOptionalValid(profile[field], isNonnegativeInteger)) &&
-        rateFields.every((field) => isOptionalValid(profile[field], isNonnegativeInteger) &&
-            (profile[field] === undefined || Number(profile[field]) <= 10_000)) &&
-        isOptionalValid(profile.finding_subjects_by_code, isNonnegativeCountRecord));
-}
-/** Decode optional structural fields while normalizing pre-structure baselines. */
-function decodeStructuralProfile(profile, affectedSubjectsByCode, nodes, edges) {
-    const informative = decodeInformativeProfile(profile, nodes, edges);
-    if (informative === undefined)
-        return undefined;
-    const countFields = [
-        "articulation_points",
-        "bridge_edges",
-        "outcome_nodes",
-        "active_outcome_reachable_nodes",
-        "active_outcome_unreachable_nodes",
-        "terminal_nodes",
-        "terminal_outcome_reachable_nodes",
-        "terminal_outcome_unreachable_nodes",
-        "outcome_reachable_nodes",
-        "outcome_unreachable_nodes",
-    ];
-    const rateFields = [
-        "active_outcome_reachability_basis_points",
-        "terminal_outcome_reachability_basis_points",
-        "outcome_reachability_basis_points",
-    ];
-    if (!hasValidStructuralFields(profile, countFields, rateFields))
-        return undefined;
-    if (profile.edge_basis !== undefined &&
-        profile.edge_basis !== "deduplicated_directed")
-        return undefined;
-    const findingSubjects = isNonnegativeCountRecord(profile.finding_subjects_by_code)
-        ? profile.finding_subjects_by_code
-        : {};
-    return {
-        edge_basis: "deduplicated_directed",
-        ...informative,
-        ...Object.fromEntries(countFields.map((field) => [field, profile[field] ?? 0])),
-        ...Object.fromEntries(rateFields.map((field) => [field, profile[field] ?? 0])),
-        finding_subjects_by_code: Object.fromEntries(RELATIONSHIP_AUDIT_FINDING_CODES.map((code) => [
-            code,
-            findingSubjects[code] ?? affectedSubjectsByCode[code] ?? 0,
-        ])),
-    };
-}
-/** Decode and cross-check optional graph-composition fields as one coherent unit. */
-function decodeGraphComposition(edges, edgesByKind, edgeShareByKind, semanticEdgesValue, semanticEdgeShareValue) {
-    const values = [
-        edgeShareByKind,
-        semanticEdgesValue,
-        semanticEdgeShareValue,
-    ];
-    const presentCount = values.filter((value) => value !== undefined).length;
-    if (presentCount === 0) {
-        return {
-            edge_share_by_kind: {},
-            semantic_edges: 0,
-            semantic_edge_share: 0,
-        };
-    }
-    if (presentCount !== values.length ||
-        !isUnitShareRecord(edgeShareByKind) ||
-        !isNonnegativeInteger(semanticEdgesValue) ||
-        !isUnitShare(semanticEdgeShareValue)) {
-        return undefined;
-    }
-    const edgeEntries = Object.entries(edgesByKind);
-    if (edgeEntries.reduce((sum, [, count]) => sum + count, 0) !== edges ||
-        Object.keys(edgeShareByKind).length !== edgeEntries.length ||
-        edgeEntries.some(([kind, count]) => edgeShareByKind[kind] !== (edges === 0 ? 0 : count / edges))) {
-        return undefined;
-    }
-    const semanticEdges = edgeEntries.reduce((sum, [kind, count]) => sum + (isSemanticContextKind(kind) ? count : 0), 0);
-    if (semanticEdgesValue !== semanticEdges ||
-        semanticEdgeShareValue !== (edges === 0 ? 0 : semanticEdges / edges)) {
-        return undefined;
-    }
-    return {
-        edge_share_by_kind: edgeShareByKind,
-        semantic_edges: semanticEdgesValue,
-        semantic_edge_share: semanticEdgeShareValue,
-    };
-}
-/** 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 (!isRecord(parsed))
-            return undefined;
-        const snapshot = parsed;
-        const profile = snapshot.profile;
-        if (typeof snapshot.saved_at !== "string")
-            return undefined;
-        if (typeof snapshot.fingerprint !== "string")
-            return undefined;
-        const affectedSubjectsByCode = snapshot.affected_subjects_by_code;
-        if (!isNonnegativeCountRecord(affectedSubjectsByCode)) {
-            return undefined;
-        }
-        if (!isRecord(profile))
-            return undefined;
-        if (![
-            profile.nodes,
-            profile.edges,
-            profile.active_nodes,
-            profile.missing_nodes,
-            profile.isolated_active_nodes,
-            profile.degree_leq_one_active_nodes,
-        ].every(isNonnegativeInteger)) {
-            return undefined;
-        }
-        if (!isNonnegativeCountRecord(profile.edges_by_kind))
-            return undefined;
-        if (!isOptionalValid(profile.coverage_by_type, isNonnegativeCoverageByTypeRecord)) {
-            return undefined;
-        }
-        const composition = decodeGraphComposition(profile.edges, profile.edges_by_kind, profile.edge_share_by_kind, profile.semantic_edges, profile.semantic_edge_share);
-        if (composition === undefined)
-            return undefined;
-        const structural = decodeStructuralProfile(profile, affectedSubjectsByCode, profile.nodes, profile.edges);
-        if (structural === undefined)
-            return undefined;
-        const { coverage_by_type = {} } = profile;
-        return {
-            ...snapshot,
-            profile: {
-                ...profile,
-                ...composition,
-                ...structural,
-                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));
-}
+!(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]="19264e42-25fa-5c93-9b0d-3b18a1ab9783")}catch(e2){}})();import path from"node:path";import{readFileIfExists,removeFileIfExists,writeFileAtomic}from"../../core/fs/fs-utils.js";import{acquireLock}from"../../core/lock/lock.js";import{isSemanticContextKind}from"./governance.js";import{RELATIONSHIP_AUDIT_FINDING_CODES}from"./governance-contracts.js";import{validLifecycleSnapshot}from"./lifecycle-coverage.js";const GRAPH_DURABLE_CACHE_VERSION=2;const GRAPH_DURABLE_CACHE_MIN_ITEMS=500;const MAX_DURABLE_RESULTS=64;const DURABLE_GRAPH_CACHE_LOCK_ID="graph-durable-cache";function acquireDurableGraphCacheLock(pmRoot){return acquireLock(pmRoot,DURABLE_GRAPH_CACHE_LOCK_ID,30,`graph-cache:${process.pid}`,false,false,3e3)}function durableGraphCachePath(pmRoot){return path.join(pmRoot,"runtime","graph-cache.json")}function graphAuditBaselinePath(pmRoot){return path.join(pmRoot,"runtime","graph-audit-baseline.json")}function decodeEnvelope(raw){if(raw===null)return void 0;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 void 0;return parsed}catch{return void 0}}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:{}}}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()}}async function clearDurableGraphCache(pmRoot){const release=await acquireDurableGraphCacheLock(pmRoot);try{await removeFileIfExists(durableGraphCachePath(pmRoot))}finally{await release()}}async function durableGraphCacheStatus(pmRoot,fingerprint){const cachePath=durableGraphCachePath(pmRoot);const raw=await readFileIfExists(cachePath);const envelope=decodeEnvelope(raw);if(envelope===void 0)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")}}function shouldPersistDurableGraphCache(itemCount,envelopeExists){return envelopeExists||itemCount>=GRAPH_DURABLE_CACHE_MIN_ITEMS}function isNonnegativeCountRecord(value){return isRecord(value)&&Object.values(value).every(isNonnegativeInteger)}function isRecord(value){return typeof value==="object"&&value!==null&&!Array.isArray(value)}function isNonnegativeInteger(value){return Number.isInteger(value)&&Number(value)>=0}function isUnitShare(value){return typeof value==="number"&&Number.isFinite(value)&&value>=0&&value<=1}function isOptionalValid(value,validate){return value===void 0||validate(value)}function isUnitShareRecord(value){return isRecord(value)&&Object.values(value).every(isUnitShare)}function isNonnegativeCoverageByTypeRecord(value){if(!isRecord(value))return false;return Object.values(value).every(entry=>isRecord(entry)&&[entry.active,entry.isolated,entry.degree_leq_one].every(isNonnegativeInteger))}function decodeInformativeProfile(profile,nodes,edges){const fields=["recorded_nodes","informative_edges","redundant_edges","ordering_contradiction_edges"];const presentCount=fields.filter(field=>profile[field]!==void 0).length;if(presentCount!==0&&presentCount!==fields.length)return void 0;if(!fields.every(field=>isOptionalValid(profile[field],isNonnegativeInteger)))return void 0;const decoded={recorded_nodes:profile.recorded_nodes??nodes,informative_edges:profile.informative_edges??edges,redundant_edges:profile.redundant_edges??0,ordering_contradiction_edges:profile.ordering_contradiction_edges??0};return decoded.recorded_nodes<=nodes&&decoded.informative_edges<=edges&&decoded.redundant_edges<=edges&&decoded.ordering_contradiction_edges<=edges?decoded:void 0}function hasValidStructuralFields(profile,countFields,rateFields){const introducedFields=[...countFields,...rateFields,"finding_subjects_by_code"];const presentCount=introducedFields.filter(field=>profile[field]!==void 0).length;if(presentCount!==0&&presentCount!==introducedFields.length)return false;return countFields.every(field=>isOptionalValid(profile[field],isNonnegativeInteger))&&rateFields.every(field=>isOptionalValid(profile[field],isNonnegativeInteger)&&(profile[field]===void 0||Number(profile[field])<=1e4))&&isOptionalValid(profile.finding_subjects_by_code,isNonnegativeCountRecord)}function decodeStructuralProfile(profile,affectedSubjectsByCode,nodes,edges){const informative=decodeInformativeProfile(profile,nodes,edges);if(informative===void 0)return void 0;const countFields=["articulation_points","bridge_edges","outcome_nodes","active_outcome_reachable_nodes","active_outcome_unreachable_nodes","terminal_nodes","terminal_outcome_reachable_nodes","terminal_outcome_unreachable_nodes","outcome_reachable_nodes","outcome_unreachable_nodes"];const rateFields=["active_outcome_reachability_basis_points","terminal_outcome_reachability_basis_points","outcome_reachability_basis_points"];if(!hasValidStructuralFields(profile,countFields,rateFields))return void 0;if(profile.edge_basis!==void 0&&profile.edge_basis!=="deduplicated_directed")return void 0;const findingSubjects=isNonnegativeCountRecord(profile.finding_subjects_by_code)?profile.finding_subjects_by_code:{};return{edge_basis:"deduplicated_directed",...informative,...Object.fromEntries(countFields.map(field=>[field,profile[field]??0])),...Object.fromEntries(rateFields.map(field=>[field,profile[field]??0])),finding_subjects_by_code:Object.fromEntries(RELATIONSHIP_AUDIT_FINDING_CODES.map(code=>[code,findingSubjects[code]??affectedSubjectsByCode[code]??0]))}}function decodeGraphComposition(edges,edgesByKind,edgeShareByKind,semanticEdgesValue,semanticEdgeShareValue){const values=[edgeShareByKind,semanticEdgesValue,semanticEdgeShareValue];const presentCount=values.filter(value=>value!==void 0).length;if(presentCount===0){return{edge_share_by_kind:{},semantic_edges:0,semantic_edge_share:0}}if(presentCount!==values.length||!isUnitShareRecord(edgeShareByKind)||!isNonnegativeInteger(semanticEdgesValue)||!isUnitShare(semanticEdgeShareValue)){return void 0}const edgeEntries=Object.entries(edgesByKind);if(edgeEntries.reduce((sum,[,count])=>sum+count,0)!==edges||Object.keys(edgeShareByKind).length!==edgeEntries.length||edgeEntries.some(([kind,count])=>edgeShareByKind[kind]!==(edges===0?0:count/edges))){return void 0}const semanticEdges=edgeEntries.reduce((sum,[kind,count])=>sum+(isSemanticContextKind(kind)?count:0),0);if(semanticEdgesValue!==semanticEdges||semanticEdgeShareValue!==(edges===0?0:semanticEdges/edges)){return void 0}return{edge_share_by_kind:edgeShareByKind,semantic_edges:semanticEdgesValue,semantic_edge_share:semanticEdgeShareValue}}function decodeBaseline(raw){if(raw===null)return void 0;try{const parsed=JSON.parse(raw);if(!isRecord(parsed))return void 0;const snapshot=parsed;const profile=snapshot.profile;if(typeof snapshot.saved_at!=="string")return void 0;if(typeof snapshot.fingerprint!=="string")return void 0;const affectedSubjectsByCode=snapshot.affected_subjects_by_code;if(!isNonnegativeCountRecord(affectedSubjectsByCode)){return void 0}if(!isRecord(profile)||!validLifecycleSnapshot(profile))return void 0;if(![profile.nodes,profile.edges,profile.active_nodes,profile.missing_nodes,profile.isolated_active_nodes,profile.degree_leq_one_active_nodes].every(isNonnegativeInteger)){return void 0}if(!isNonnegativeCountRecord(profile.edges_by_kind))return void 0;if(!isOptionalValid(profile.coverage_by_type,isNonnegativeCoverageByTypeRecord)){return void 0}const composition=decodeGraphComposition(profile.edges,profile.edges_by_kind,profile.edge_share_by_kind,profile.semantic_edges,profile.semantic_edge_share);if(composition===void 0)return void 0;const structural=decodeStructuralProfile(profile,affectedSubjectsByCode,profile.nodes,profile.edges);if(structural===void 0)return void 0;const{coverage_by_type={}}=profile;return{...snapshot,profile:{...profile,...composition,...structural,coverage_by_type}}}catch{return void 0}}async function loadGraphAuditBaseline(pmRoot){return decodeBaseline(await readFileIfExists(graphAuditBaselinePath(pmRoot)))}async function saveGraphAuditBaseline(pmRoot,snapshot){await writeFileAtomic(graphAuditBaselinePath(pmRoot),JSON.stringify(snapshot))}export{GRAPH_DURABLE_CACHE_MIN_ITEMS,GRAPH_DURABLE_CACHE_VERSION,clearDurableGraphCache,durableGraphCachePath,durableGraphCacheStatus,graphAuditBaselinePath,loadGraphAuditBaseline,openDurableGraphCache,persistDurableGraphResult,saveGraphAuditBaseline,shouldPersistDurableGraphCache};
 //# sourceMappingURL=durable-cache.js.map
-//# debugId=9e4aa41d-fca4-5e55-ab2b-d99f06d90ae2

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

@@ -1,35 +1,2 @@
-/**
- * @module sdk/graph/governance-contracts
- *
- * Shared, runtime-visible relationship-audit finding identifiers used by the
- * live audit and backward-compatible durable baseline decoder. Keeping the
- * tuple authoritative prevents the public type and persisted zero census from
- * drifting when a finding family is added.
- */
-/** Stable machine-readable relationship audit finding families. */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a8bc0ebd-e5e4-57f3-8e6c-417f9809eb72")}catch(e){}}();
-export const RELATIONSHIP_AUDIT_FINDING_CODES = [
-    "missing_reference_active",
-    "missing_reference_terminal",
-    "legacy_no_blocker_sentinel",
-    "ordering_cycle",
-    "legacy_ordering_cycle",
-    "ordering_storage_contradiction",
-    "legacy_ordering_storage_contradiction",
-    "hierarchy_cycle",
-    "legacy_hierarchy_cycle",
-    "hierarchy_cardinality_violation",
-    "legacy_hierarchy_cardinality_violation",
-    "hierarchy_direction_violation",
-    "legacy_hierarchy_direction_violation",
-    "duplicate_edge",
-    "legacy_duplicate_edge",
-    "duplicate_dependency_row",
-    "legacy_duplicate_dependency_row",
-    "stale_lifecycle_block",
-    "isolated_active_node",
-    "sparse_active_node",
-];
+!(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]="896e1553-b127-532f-ac39-e0d47f29eebc")}catch(e2){}})();const RELATIONSHIP_AUDIT_FINDING_CODES=["missing_reference_active","missing_reference_terminal","legacy_no_blocker_sentinel","ordering_cycle","legacy_ordering_cycle","ordering_storage_contradiction","legacy_ordering_storage_contradiction","hierarchy_cycle","legacy_hierarchy_cycle","hierarchy_cardinality_violation","legacy_hierarchy_cardinality_violation","hierarchy_direction_violation","legacy_hierarchy_direction_violation","duplicate_edge","legacy_duplicate_edge","duplicate_dependency_row","legacy_duplicate_dependency_row","stale_lifecycle_block","isolated_active_node","sparse_active_node"];export{RELATIONSHIP_AUDIT_FINDING_CODES};
 //# sourceMappingURL=governance-contracts.js.map
-//# debugId=a8bc0ebd-e5e4-57f3-8e6c-417f9809eb72

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

@@ -14,6 +14,8 @@
  */
 import type { RelationshipEdge, RelationshipOutcomeTraversal } from "../relationships.js";
 import type { OrderingStorageContradiction, WorkspaceRelationshipAssembly } from "./assembly.js";
+import { type RelationshipLifecycleCoverage } from "./lifecycle-coverage.js";
+export type { RelationshipPopulationCoverage, RelationshipLifecycleCoverage } from "./lifecycle-coverage.js";
 import { type RelationshipAuditFindingCode } from "./governance-contracts.js";
 export type { RelationshipAuditFindingCode } from "./governance-contracts.js";
 /** Severity ladder shared by every relationship audit finding. */
@@ -49,7 +51,11 @@ export interface RelationshipCoverageTypeProfile {
     degree_leq_one: number;
 }
 /** Aggregate structural coverage metrics for one assembled workspace graph. */
-export interface RelationshipCoverageProfile {
+export interface RelationshipCoverageProfile extends RelationshipLifecycleCoverage {
+    /** Structural ordering acyclicity across all lifecycle states, independent of finding severity. */
+    ordering_acyclic: boolean;
+    /** Whether every ordering cycle is confined to terminal items. */
+    active_ordering_acyclic: boolean;
     /** Total indexed nodes including materialized missing placeholders. */
     nodes: number;
     /** Tracker-recorded nodes, excluding synthesized missing and external placeholders. */
@@ -201,6 +207,12 @@ export interface RelationshipAuditDelta {
     affected_subjects_by_code: Record<string, number>;
     /** Signed structural profile deltas. */
     profile: {
+        /** Whether both snapshots measured lifecycle census fields. */
+        lifecycle_comparable?: boolean;
+        /** Signed population deltas, absent for legacy baselines lacking this census. */
+        coverage_by_lifecycle?: RelationshipLifecycleCoverage["coverage_by_lifecycle"];
+        /** Signed raw-status population deltas, absent for legacy baselines. */
+        coverage_by_status?: RelationshipLifecycleCoverage["coverage_by_status"];
         /** Node-count change including missing placeholders. */
         nodes: number;
         /** Tracker-recorded node-count change excluding synthesized placeholders. */