@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/graph/centrality.js

@@ -1,259 +1,2 @@
-
-!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]="348c9246-2fb9-529e-b627-f60c901a6cf2")}catch(e){}}();
-import { forEachMatchedRelationshipEdge } from "./analytics.js";
-import { orientOrderingEdge } from "./traversal.js";
-/** Round a centrality score to six decimals to suppress floating-point noise. */
-function roundScore(value) {
-    return Math.round(value * 1e6) / 1e6;
-}
-/** Add one value to a set-valued map entry, creating the set on demand. */
-function addToSetMap(map, key, value) {
-    const set = map.get(key);
-    if (set === undefined)
-        map.set(key, new Set([value]));
-    else
-        set.add(value);
-}
-/** Build the deterministic simple undirected adjacency over every node. */
-function buildSimpleUndirectedAdjacency(graph, kinds) {
-    const sets = new Map(graph.nodes().map((id) => [id, new Set()]));
-    forEachMatchedRelationshipEdge(graph, kinds, (edge) => {
-        sets.get(edge.source).add(edge.target);
-        sets.get(edge.target).add(edge.source);
-    });
-    const adjacency = new Map();
-    for (const [id, neighbors] of sets)
-        adjacency.set(id, [...neighbors].sort());
-    return adjacency;
-}
-/**
- * Collect distinct ordering predecessors and successors per node, oriented by
- * each kind's declared precedence so fan-in/fan-out match the SDK's
- * predecessor/successor traversal semantics rather than the stored edge
- * spelling (a `blocked_by` edge counts its target as the predecessor).
- */
-function collectOrderingDegrees(graph, kinds) {
-    const incoming = new Map();
-    const outgoing = new Map();
-    forEachMatchedRelationshipEdge(graph, kinds, (edge, definition) => {
-        if (!definition.ordering)
-            return;
-        const { predecessor, successor } = orientOrderingEdge(edge, definition);
-        // The predecessor gates the successor: predecessor -> successor.
-        addToSetMap(outgoing, predecessor, successor);
-        addToSetMap(incoming, successor, predecessor);
-    });
-    return { incoming, outgoing };
-}
-/** Run one breadth-first single-source shortest-path sweep for Brandes accumulation. */
-function brandesShortestPaths(source, adjacency, cost) {
-    const distance = new Map([[source, 0]]);
-    const sigma = new Map([[source, 1]]);
-    const predecessors = new Map();
-    const stack = [];
-    const queue = [source];
-    let reachableCount = 0;
-    let distanceSum = 0;
-    for (let index = 0; index < queue.length; index += 1) {
-        const node = queue[index];
-        cost.visitedNodes += 1;
-        stack.push(node);
-        const nodeDistance = distance.get(node);
-        if (node !== source) {
-            reachableCount += 1;
-            distanceSum += nodeDistance;
-        }
-        for (const neighbor of adjacency.get(node)) {
-            cost.inspectedEdges += 1;
-            if (!distance.has(neighbor)) {
-                distance.set(neighbor, nodeDistance + 1);
-                queue.push(neighbor);
-            }
-            if (distance.get(neighbor) === nodeDistance + 1) {
-                sigma.set(neighbor, (sigma.get(neighbor) ?? 0) + sigma.get(node));
-                const predecessorList = predecessors.get(neighbor);
-                if (predecessorList === undefined)
-                    predecessors.set(neighbor, [node]);
-                else
-                    predecessorList.push(node);
-            }
-        }
-    }
-    return { stack, sigma, predecessors, reachableCount, distanceSum };
-}
-/** Fold one completed sweep's dependencies back into the running betweenness totals. */
-function accumulateBetweenness(sweep, source, betweenness) {
-    const dependency = new Map();
-    for (let index = sweep.stack.length - 1; index >= 0; index -= 1) {
-        const node = sweep.stack[index];
-        const share = (1 + (dependency.get(node) ?? 0)) / sweep.sigma.get(node);
-        for (const predecessor of sweep.predecessors.get(node) ?? []) {
-            dependency.set(predecessor, (dependency.get(predecessor) ?? 0) + sweep.sigma.get(predecessor) * share);
-        }
-        if (node !== source)
-            betweenness.set(node, (betweenness.get(node) ?? 0) + (dependency.get(node) ?? 0));
-    }
-}
-/**
- * Wasserman–Faust closeness normalizes reachability so disconnected graphs
- * compare fairly. A reachable count above zero implies a positive distance sum
- * (every shortest distance is at least one), so those two guards suffice.
- */
-function wassermanFaustCloseness(sweep, nodeCount) {
-    if (nodeCount <= 1 || sweep.reachableCount === 0)
-        return 0;
-    return ((sweep.reachableCount / (nodeCount - 1)) *
-        (sweep.reachableCount / sweep.distanceSum));
-}
-/** Assemble one ranked centrality row from the accumulated scores. */
-function centralityRow(id, adjacency, directed, betweenness, closeness) {
-    return {
-        id,
-        degree: adjacency.get(id).length,
-        inDegree: directed.incoming.get(id)?.size ?? 0,
-        outDegree: directed.outgoing.get(id)?.size ?? 0,
-        // Undirected betweenness double-counts each ordered pair; halve it.
-        betweenness: roundScore((betweenness.get(id) ?? 0) / 2),
-        // Every node is a sweep source, so closeness is always populated.
-        closeness: roundScore(closeness.get(id)),
-    };
-}
-/**
- * Compute exact shortest-path betweenness (Brandes), Wasserman–Faust closeness,
- * undirected degree, and directed fan-in/fan-out for every node over the simple
- * undirected graph induced by the selected kinds. Rows rank by betweenness, then
- * degree, then id. The result is exact on the bounded workspace; callers bound
- * the returned rows for token-aware projection.
- */
-export function computeRelationshipCentrality(graph, options = {}) {
-    const adjacency = buildSimpleUndirectedAdjacency(graph, options.kinds);
-    const directed = collectOrderingDegrees(graph, options.kinds);
-    const nodes = graph.nodes();
-    const betweenness = new Map();
-    const closeness = new Map();
-    const cost = { visitedNodes: 0, inspectedEdges: 0 };
-    for (const source of nodes) {
-        options.signal?.throwIfAborted();
-        const sweep = brandesShortestPaths(source, adjacency, cost);
-        closeness.set(source, wassermanFaustCloseness(sweep, nodes.length));
-        accumulateBetweenness(sweep, source, betweenness);
-    }
-    let degreeSum = 0;
-    for (const neighbors of adjacency.values())
-        degreeSum += neighbors.length;
-    const rows = nodes
-        .map((id) => centralityRow(id, adjacency, directed, betweenness, closeness))
-        .sort((left, right) => right.betweenness - left.betweenness ||
-        right.degree - left.degree ||
-        left.id.localeCompare(right.id));
-    return {
-        value: { nodeCount: nodes.length, edgeCount: degreeSum / 2, rows },
-        meta: {
-            visitedNodes: cost.visitedNodes,
-            inspectedEdges: cost.inspectedEdges,
-            truncated: false,
-        },
-    };
-}
-/** Order one bridge endpoint pair deterministically. */
-function orderedBridge(left, right) {
-    return left <= right
-        ? { source: left, target: right }
-        : { source: right, target: left };
-}
-/**
- * Advance the top frame by one neighbor: descend into an undiscovered neighbor,
- * or relax the low-link against a back edge. Returns the discovered child frame
- * to push, or undefined when the step consumed a back edge or the tree parent.
- */
-function advanceCutFrame(frame, adjacency, state) {
-    const neighbors = adjacency.get(frame.node);
-    const neighbor = neighbors[frame.neighborIndex];
-    frame.neighborIndex += 1;
-    state.inspectedEdges += 1;
-    if (neighbor === frame.parent)
-        return undefined;
-    if (state.discovery.has(neighbor)) {
-        state.low.set(frame.node, Math.min(state.low.get(frame.node), state.discovery.get(neighbor)));
-        return undefined;
-    }
-    frame.children += 1;
-    state.discovery.set(neighbor, state.timer);
-    state.low.set(neighbor, state.timer);
-    state.timer += 1;
-    return { node: neighbor, parent: frame.node, neighborIndex: 0, children: 0 };
-}
-/** Retreat from a finished frame: fold its low-link into its parent and flag cuts. */
-function retreatCutFrame(frame, root, state) {
-    if (frame.parent === null) {
-        if (frame.children > 1)
-            state.articulation.add(frame.node);
-        return;
-    }
-    const parent = frame.parent;
-    const childLow = state.low.get(frame.node);
-    state.low.set(parent, Math.min(state.low.get(parent), childLow));
-    if (parent !== root && childLow >= state.discovery.get(parent))
-        state.articulation.add(parent);
-    if (childLow > state.discovery.get(parent))
-        state.bridges.push(orderedBridge(parent, frame.node));
-}
-/** Walk one connected component's depth-first tree, updating low-links and cuts. */
-function searchComponentCuts(root, adjacency, state, signal) {
-    state.discovery.set(root, state.timer);
-    state.low.set(root, state.timer);
-    state.timer += 1;
-    const stack = [
-        { node: root, parent: null, neighborIndex: 0, children: 0 },
-    ];
-    while (stack.length > 0) {
-        signal?.throwIfAborted();
-        const frame = stack.at(-1);
-        if (frame.neighborIndex < adjacency.get(frame.node).length) {
-            const child = advanceCutFrame(frame, adjacency, state);
-            if (child !== undefined)
-                stack.push(child);
-        }
-        else {
-            retreatCutFrame(frame, root, state);
-            stack.pop();
-        }
-    }
-}
-/**
- * Find articulation points and bridges of the undirected knowledge graph with
- * an iterative Tarjan low-link search over the simple adjacency. An articulation
- * point is a node whose removal increases the connected-component count; a bridge
- * is an edge whose removal does the same — both are single points of failure in
- * the relationship graph. Results are deterministic and exact.
- */
-export function findRelationshipCutStructure(graph, options = {}) {
-    const adjacency = buildSimpleUndirectedAdjacency(graph, options.kinds);
-    const state = {
-        discovery: new Map(),
-        low: new Map(),
-        timer: 0,
-        articulation: new Set(),
-        bridges: [],
-        inspectedEdges: 0,
-    };
-    for (const root of graph.nodes()) {
-        if (state.discovery.has(root))
-            continue;
-        searchComponentCuts(root, adjacency, state, options.signal);
-    }
-    return {
-        value: {
-            articulationPoints: [...state.articulation].sort(),
-            bridges: state.bridges.sort((left, right) => left.source.localeCompare(right.source) ||
-                left.target.localeCompare(right.target)),
-        },
-        meta: {
-            visitedNodes: state.discovery.size,
-            inspectedEdges: state.inspectedEdges,
-            truncated: false,
-        },
-    };
-}
+!(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]="aa8e4dc3-250e-50eb-b770-a11cbab6ebc3")}catch(e2){}})();import{forEachMatchedRelationshipEdge}from"./analytics.js";import{orientOrderingEdge}from"./traversal.js";function roundScore(value){return Math.round(value*1e6)/1e6}function addToSetMap(map,key,value){const set=map.get(key);if(set===void 0)map.set(key,new Set([value]));else set.add(value)}function buildSimpleUndirectedAdjacency(graph,kinds){const sets=new Map(graph.nodes().map(id=>[id,new Set]));forEachMatchedRelationshipEdge(graph,kinds,edge=>{sets.get(edge.source).add(edge.target);sets.get(edge.target).add(edge.source)});const adjacency=new Map;for(const[id,neighbors]of sets)adjacency.set(id,[...neighbors].sort());return adjacency}function collectOrderingDegrees(graph,kinds){const incoming=new Map;const outgoing=new Map;forEachMatchedRelationshipEdge(graph,kinds,(edge,definition)=>{if(!definition.ordering)return;const{predecessor,successor}=orientOrderingEdge(edge,definition);addToSetMap(outgoing,predecessor,successor);addToSetMap(incoming,successor,predecessor)});return{incoming,outgoing}}function brandesShortestPaths(source,adjacency,cost){const distance=new Map([[source,0]]);const sigma=new Map([[source,1]]);const predecessors=new Map;const stack=[];const queue=[source];let reachableCount=0;let distanceSum=0;for(let index=0;index<queue.length;index+=1){const node=queue[index];cost.visitedNodes+=1;stack.push(node);const nodeDistance=distance.get(node);if(node!==source){reachableCount+=1;distanceSum+=nodeDistance}for(const neighbor of adjacency.get(node)){cost.inspectedEdges+=1;if(!distance.has(neighbor)){distance.set(neighbor,nodeDistance+1);queue.push(neighbor)}if(distance.get(neighbor)===nodeDistance+1){sigma.set(neighbor,(sigma.get(neighbor)??0)+sigma.get(node));const predecessorList=predecessors.get(neighbor);if(predecessorList===void 0)predecessors.set(neighbor,[node]);else predecessorList.push(node)}}}return{stack,sigma,predecessors,reachableCount,distanceSum}}function accumulateBetweenness(sweep,source,betweenness){const dependency=new Map;for(let index=sweep.stack.length-1;index>=0;index-=1){const node=sweep.stack[index];const share=(1+(dependency.get(node)??0))/sweep.sigma.get(node);for(const predecessor of sweep.predecessors.get(node)??[]){dependency.set(predecessor,(dependency.get(predecessor)??0)+sweep.sigma.get(predecessor)*share)}if(node!==source)betweenness.set(node,(betweenness.get(node)??0)+(dependency.get(node)??0))}}function wassermanFaustCloseness(sweep,nodeCount){if(nodeCount<=1||sweep.reachableCount===0)return 0;return sweep.reachableCount/(nodeCount-1)*(sweep.reachableCount/sweep.distanceSum)}function centralityRow(id,adjacency,directed,betweenness,closeness){return{id,degree:adjacency.get(id).length,inDegree:directed.incoming.get(id)?.size??0,outDegree:directed.outgoing.get(id)?.size??0,betweenness:roundScore((betweenness.get(id)??0)/2),closeness:roundScore(closeness.get(id))}}function computeRelationshipCentrality(graph,options={}){const adjacency=buildSimpleUndirectedAdjacency(graph,options.kinds);const directed=collectOrderingDegrees(graph,options.kinds);const nodes=graph.nodes();const betweenness=new Map;const closeness=new Map;const cost={visitedNodes:0,inspectedEdges:0};for(const source of nodes){options.signal?.throwIfAborted();const sweep=brandesShortestPaths(source,adjacency,cost);closeness.set(source,wassermanFaustCloseness(sweep,nodes.length));accumulateBetweenness(sweep,source,betweenness)}let degreeSum=0;for(const neighbors of adjacency.values())degreeSum+=neighbors.length;const rows=nodes.map(id=>centralityRow(id,adjacency,directed,betweenness,closeness)).sort((left,right)=>right.betweenness-left.betweenness||right.degree-left.degree||left.id.localeCompare(right.id));return{value:{nodeCount:nodes.length,edgeCount:degreeSum/2,rows},meta:{visitedNodes:cost.visitedNodes,inspectedEdges:cost.inspectedEdges,truncated:false}}}function orderedBridge(left,right){return left<=right?{source:left,target:right}:{source:right,target:left}}function advanceCutFrame(frame,adjacency,state){const neighbors=adjacency.get(frame.node);const neighbor=neighbors[frame.neighborIndex];frame.neighborIndex+=1;state.inspectedEdges+=1;if(neighbor===frame.parent)return void 0;if(state.discovery.has(neighbor)){state.low.set(frame.node,Math.min(state.low.get(frame.node),state.discovery.get(neighbor)));return void 0}frame.children+=1;state.discovery.set(neighbor,state.timer);state.low.set(neighbor,state.timer);state.timer+=1;return{node:neighbor,parent:frame.node,neighborIndex:0,children:0}}function retreatCutFrame(frame,root,state){if(frame.parent===null){if(frame.children>1)state.articulation.add(frame.node);return}const parent=frame.parent;const childLow=state.low.get(frame.node);state.low.set(parent,Math.min(state.low.get(parent),childLow));if(parent!==root&&childLow>=state.discovery.get(parent))state.articulation.add(parent);if(childLow>state.discovery.get(parent))state.bridges.push(orderedBridge(parent,frame.node))}function searchComponentCuts(root,adjacency,state,signal){state.discovery.set(root,state.timer);state.low.set(root,state.timer);state.timer+=1;const stack=[{node:root,parent:null,neighborIndex:0,children:0}];while(stack.length>0){signal?.throwIfAborted();const frame=stack.at(-1);if(frame.neighborIndex<adjacency.get(frame.node).length){const child=advanceCutFrame(frame,adjacency,state);if(child!==void 0)stack.push(child)}else{retreatCutFrame(frame,root,state);stack.pop()}}}function findRelationshipCutStructure(graph,options={}){const adjacency=buildSimpleUndirectedAdjacency(graph,options.kinds);const state={discovery:new Map,low:new Map,timer:0,articulation:new Set,bridges:[],inspectedEdges:0};for(const root of graph.nodes()){if(state.discovery.has(root))continue;searchComponentCuts(root,adjacency,state,options.signal)}return{value:{articulationPoints:[...state.articulation].sort(),bridges:state.bridges.sort((left,right)=>left.source.localeCompare(right.source)||left.target.localeCompare(right.target))},meta:{visitedNodes:state.discovery.size,inspectedEdges:state.inspectedEdges,truncated:false}}}export{computeRelationshipCentrality,findRelationshipCutStructure};
 //# sourceMappingURL=centrality.js.map
-//# debugId=348c9246-2fb9-529e-b627-f60c901a6cf2

package/dist/sdk/graph/conformance.js

@@ -1,131 +1,2 @@
-/**
- * @module sdk/graph/conformance
- *
- * Public, sandbox-neutral fixtures and adapter conformance checks. Package
- * authors can run the same semantic contract against an in-memory adapter,
- * Neo4j, a remote service, or another durable graph backend.
- */
-
-!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]="423d6e5d-93e5-5f29-93e0-11ddca9c3156")}catch(e){}}();
-import { MemoryRelationshipGraphAdapter, createRelationshipGraphSnapshot, loadRelationshipGraphAdapter, syncRelationshipGraphAdapter, } from "./adapter.js";
-import { RelationshipGraph, createRelationshipKindRegistry, } from "../relationships.js";
-/** Validate a positive integer fixture bound. */
-function positiveInteger(value, field) {
-    if (!Number.isInteger(value) || value < 1)
-        throw new TypeError(`Relationship graph ${field} must be a positive integer`);
-    return value;
-}
-/** Create a lazy deterministic scale fixture without touching tracker storage. */
-export function createRelationshipGraphScaleFixture(options) {
-    const nodeCount = positiveInteger(options.nodeCount, "nodeCount");
-    const edgeStride = positiveInteger(options.edgeStride ?? 1, "edgeStride");
-    const topology = options.topology ?? "chain";
-    if (!["chain", "star", "disconnected"].includes(topology))
-        throw new TypeError(`Unsupported relationship graph topology: ${topology}`);
-    const kind = (options.kind ?? "related").trim();
-    const idPrefix = (options.idPrefix ?? "node").trim();
-    if (!kind || !idPrefix)
-        throw new TypeError("Relationship graph kind and idPrefix must be non-empty");
-    const edgeCount = topology === "disconnected" ? 0 : Math.floor((nodeCount - 1) / edgeStride);
-    return {
-        node_count: nodeCount,
-        edge_count: edgeCount,
-        edge_basis: "fixture_generated",
-        nodes: {
-            *[Symbol.iterator]() {
-                for (let index = 0; index < nodeCount; index += 1)
-                    yield `${idPrefix}-${index}`;
-            },
-        },
-        edges: {
-            *[Symbol.iterator]() {
-                if (topology === "disconnected")
-                    return;
-                for (let index = edgeStride; index < nodeCount; index += edgeStride)
-                    yield {
-                        source: `${idPrefix}-${topology === "star" ? 0 : index - edgeStride}`,
-                        target: `${idPrefix}-${index}`,
-                        kind,
-                    };
-            },
-        },
-    };
-}
-/** Throw a precise conformance failure. */
-function assertConformance(condition, message) {
-    if (!condition)
-        throw new Error(`Relationship graph adapter conformance: ${message}`);
-}
-/**
- * Exercise empty reads, atomic replacement, isolated reads, idempotent sync,
- * compare-and-swap conflicts, replacement visibility, and optional clearing.
- */
-export async function assertRelationshipGraphAdapterConformance(adapter, options = {}) {
-    const workspace = options.workspace?.trim() || "pm-graph-conformance";
-    const registry = createRelationshipKindRegistry();
-    const first = createRelationshipGraphSnapshot(new RelationshipGraph(["a", "b"], [{ source: "a", target: "b", kind: "related" }], registry), registry, { createdAt: "2026-01-01T00:00:00.000Z" });
-    const second = createRelationshipGraphSnapshot(new RelationshipGraph(["a", "b", "c"], [
-        { source: "a", target: "b", kind: "related" },
-        { source: "b", target: "c", kind: "blocked_by" },
-    ], registry), registry, { createdAt: "2026-01-02T00:00:00.000Z" });
-    const cases = [];
-    assertConformance((await loadRelationshipGraphAdapter(adapter, { workspace })) === null, "workspace must start empty");
-    cases.push({ name: "empty-read", passed: true });
-    const written = await syncRelationshipGraphAdapter(adapter, {
-        workspace,
-        snapshot: first,
-    });
-    assertConformance(written.disposition === "written", "first sync must write");
-    cases.push({ name: "atomic-replace", passed: true });
-    const isolated = (await adapter.read({ workspace }));
-    isolated.nodes.push("mutated-reader-copy");
-    assertConformance((await loadRelationshipGraphAdapter(adapter, { workspace }))?.snapshot.nodes
-        .length === 2, "reads must not mutate stored state");
-    cases.push({ name: "read-isolation", passed: true });
-    assertConformance((await syncRelationshipGraphAdapter(adapter, {
-        workspace,
-        snapshot: first,
-    })).disposition === "current", "identical sync must be idempotent");
-    cases.push({ name: "idempotent-sync", passed: true });
-    await adapter.replace({
-        workspace,
-        snapshot: second,
-        expected_fingerprint: first.fingerprint,
-    });
-    assertConformance((await loadRelationshipGraphAdapter(adapter, { workspace }))?.snapshot
-        .fingerprint === second.fingerprint, "replacement must become visible");
-    cases.push({ name: "replacement-visibility", passed: true });
-    let conflict = false;
-    try {
-        await adapter.replace({
-            workspace,
-            snapshot: first,
-            expected_fingerprint: first.fingerprint,
-        });
-    }
-    catch {
-        conflict = true;
-    }
-    assertConformance(conflict, "stale compare-and-swap must fail");
-    cases.push({ name: "stale-cas", passed: true });
-    if (adapter.clear) {
-        await adapter.clear({
-            workspace,
-            expected_fingerprint: second.fingerprint,
-        });
-        assertConformance((await loadRelationshipGraphAdapter(adapter, { workspace })) === null, "clear must remove the workspace");
-        cases.push({ name: "clear", passed: true });
-    }
-    return {
-        adapter: adapter.name,
-        workspace,
-        cases: Object.freeze(cases),
-        clear_supported: adapter.clear !== undefined,
-    };
-}
-/** Run the public conformance contract against the built-in reference adapter. */
-export function assertMemoryRelationshipGraphAdapterConformance(workspace) {
-    return assertRelationshipGraphAdapterConformance(new MemoryRelationshipGraphAdapter(), workspace ? { workspace } : {});
-}
+!(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]="9a60b8c0-37d1-5c04-a079-e1351caf6e09")}catch(e2){}})();import{MemoryRelationshipGraphAdapter,createRelationshipGraphSnapshot,loadRelationshipGraphAdapter,syncRelationshipGraphAdapter}from"./adapter.js";import{RelationshipGraph,createRelationshipKindRegistry}from"../relationships.js";function positiveInteger(value,field){if(!Number.isInteger(value)||value<1)throw new TypeError(`Relationship graph ${field} must be a positive integer`);return value}function createRelationshipGraphScaleFixture(options){const nodeCount=positiveInteger(options.nodeCount,"nodeCount");const edgeStride=positiveInteger(options.edgeStride??1,"edgeStride");const topology=options.topology??"chain";if(!["chain","star","disconnected"].includes(topology))throw new TypeError(`Unsupported relationship graph topology: ${topology}`);const kind=(options.kind??"related").trim();const idPrefix=(options.idPrefix??"node").trim();if(!kind||!idPrefix)throw new TypeError("Relationship graph kind and idPrefix must be non-empty");const edgeCount=topology==="disconnected"?0:Math.floor((nodeCount-1)/edgeStride);return{node_count:nodeCount,edge_count:edgeCount,edge_basis:"fixture_generated",nodes:{*[Symbol.iterator](){for(let index=0;index<nodeCount;index+=1)yield`${idPrefix}-${index}`}},edges:{*[Symbol.iterator](){if(topology==="disconnected")return;for(let index=edgeStride;index<nodeCount;index+=edgeStride)yield{source:`${idPrefix}-${topology==="star"?0:index-edgeStride}`,target:`${idPrefix}-${index}`,kind}}}}}function assertConformance(condition,message){if(!condition)throw new Error(`Relationship graph adapter conformance: ${message}`)}async function assertRelationshipGraphAdapterConformance(adapter,options={}){const workspace=options.workspace?.trim()||"pm-graph-conformance";const registry=createRelationshipKindRegistry();const first=createRelationshipGraphSnapshot(new RelationshipGraph(["a","b"],[{source:"a",target:"b",kind:"related"}],registry),registry,{createdAt:"2026-01-01T00:00:00.000Z"});const second=createRelationshipGraphSnapshot(new RelationshipGraph(["a","b","c"],[{source:"a",target:"b",kind:"related"},{source:"b",target:"c",kind:"blocked_by"}],registry),registry,{createdAt:"2026-01-02T00:00:00.000Z"});const cases=[];assertConformance(await loadRelationshipGraphAdapter(adapter,{workspace})===null,"workspace must start empty");cases.push({name:"empty-read",passed:true});const written=await syncRelationshipGraphAdapter(adapter,{workspace,snapshot:first});assertConformance(written.disposition==="written","first sync must write");cases.push({name:"atomic-replace",passed:true});const isolated=await adapter.read({workspace});isolated.nodes.push("mutated-reader-copy");assertConformance((await loadRelationshipGraphAdapter(adapter,{workspace}))?.snapshot.nodes.length===2,"reads must not mutate stored state");cases.push({name:"read-isolation",passed:true});assertConformance((await syncRelationshipGraphAdapter(adapter,{workspace,snapshot:first})).disposition==="current","identical sync must be idempotent");cases.push({name:"idempotent-sync",passed:true});await adapter.replace({workspace,snapshot:second,expected_fingerprint:first.fingerprint});assertConformance((await loadRelationshipGraphAdapter(adapter,{workspace}))?.snapshot.fingerprint===second.fingerprint,"replacement must become visible");cases.push({name:"replacement-visibility",passed:true});let conflict=false;try{await adapter.replace({workspace,snapshot:first,expected_fingerprint:first.fingerprint})}catch{conflict=true}assertConformance(conflict,"stale compare-and-swap must fail");cases.push({name:"stale-cas",passed:true});if(adapter.clear){await adapter.clear({workspace,expected_fingerprint:second.fingerprint});assertConformance(await loadRelationshipGraphAdapter(adapter,{workspace})===null,"clear must remove the workspace");cases.push({name:"clear",passed:true})}return{adapter:adapter.name,workspace,cases:Object.freeze(cases),clear_supported:adapter.clear!==void 0}}function assertMemoryRelationshipGraphAdapterConformance(workspace){return assertRelationshipGraphAdapterConformance(new MemoryRelationshipGraphAdapter,workspace?{workspace}:{})}export{assertMemoryRelationshipGraphAdapterConformance,assertRelationshipGraphAdapterConformance,createRelationshipGraphScaleFixture};
 //# sourceMappingURL=conformance.js.map
-//# debugId=423d6e5d-93e5-5f29-93e0-11ddca9c3156

package/dist/sdk/graph/deadline-scheduling.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @module sdk/graph/deadline-scheduling
+ * Read-only elapsed-minute scheduling. Independent tasks may execute in parallel;
+ * estimates are durations, not resource capacity or business-calendar promises.
+ * A bounded Kahn pass isolates cycles and propagates unknown durations explicitly.
+ */
+import type { RelationshipGraph } from "../relationships.js";
+/** Recorded inputs; absent estimates never imply zero duration. */
+export interface DeadlineScheduleItem {
+    /** Canonical graph identifier. */
+    id: string;
+    /** Recorded elapsed-minute duration. */
+    estimated_minutes?: number;
+    /** Authored ISO deadline interpreted as a finish constraint. */
+    deadline?: string;
+}
+/** Deterministic analysis controls and hard work/output bounds. */
+export interface DeadlineScheduleOptions {
+    /** Explicit clock instant; defaults to the invocation time. */
+    now?: string;
+    /** Input nodes plus edges plus items ceiling; also caps total retained path identifiers. */
+    maxWork?: number;
+    /** Maximum rows, residual samples, findings, and identifiers per finding path. */
+    limit?: number;
+    /** Cooperative cancellation checked during graph passes. */
+    signal?: AbortSignal;
+}
+/** One derived finish constraint and its estimated temporal slack. */
+export interface DeadlineScheduleRow {
+    /** Constrained item identifier. */
+    id: string;
+    /** Controlling authored deadline's item identifier. */
+    deadline_id: string;
+    /** Derived latest start; never written to the authored item. */
+    latest_start: string;
+    /** Latest start minus earliest possible start, or null for unknown prerequisites. */
+    slack_minutes: number | null;
+}
+/** Explicit evidence that this item's schedule could not be established. */
+export interface DeadlineScheduleResidual {
+    /** Unscheduled or incompletely scheduled item. */
+    id: string;
+    /** Why no feasibility assertion is possible. */
+    reason: "unknown_estimate" | "unknown_predecessor_estimate" | "cycle_or_gated_by_cycle" | "invalid_deadline" | "date_range_exceeded";
+}
+/** One authored deadline that cannot accommodate its longest prerequisite chain. */
+export interface DeadlineOvercommitment {
+    /** Item carrying the authored deadline. */
+    deadline_id: string;
+    /** Authored finish constraint. */
+    deadline: string;
+    /** Positive duration by which earliest finish exceeds the deadline. */
+    shortfall_minutes: number;
+    /** Bounded suffix of the controlling prerequisite chain, in execution order. */
+    path: string[];
+    /** Whether the chain exceeds the path output bound. */
+    path_truncated: boolean;
+}
+/** Bounded derived schedule, with completeness separate from output truncation. */
+export interface DeadlineScheduleResult {
+    /** Reproducible clock used for earliest starts. */
+    as_of: string;
+    /** Explicit provenance distinguishing computed constraints from authored dates. */
+    basis: "derived_elapsed_minutes";
+    /** Whether all inputs could be scheduled within the work bound. */
+    complete: boolean;
+    /** Whether output collections omit computed entries. */
+    truncated: boolean;
+    /** True when the work bound prevented the graph pass. */
+    work_limit_exceeded: boolean;
+    /** Number of derived rows before output bounding. */
+    scheduled_count: number;
+    /** Number of explicit residuals before output bounding. */
+    residual_count: number;
+    /** Number of infeasible authored deadlines before output bounding. */
+    overcommitted_count: number;
+    /** Derived latest starts in graph identifier order. */
+    rows: DeadlineScheduleRow[];
+    /** Bounded incomplete-input and cycle samples. */
+    residuals: DeadlineScheduleResidual[];
+    /** Bounded deadline shortfall evidence. */
+    overcommitted: DeadlineOvercommitment[];
+}
+/**
+ * Derive estimated latest starts and deadline shortfalls without mutating inputs.
+ * Work is O(V+E) plus at most maxWork total finding-path identifiers. Unknown predecessors
+ * invalidate earliest finish; unknown successors cannot transfer dated bounds.
+ * Date-only ISO values denote UTC midnight, consistently with Date.parse.
+ */
+export declare function deriveRelationshipDeadlines(graph: RelationshipGraph, items: readonly DeadlineScheduleItem[], options?: DeadlineScheduleOptions): DeadlineScheduleResult;

package/dist/sdk/graph/deadline-scheduling.js

@@ -0,0 +1,2 @@
+!(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]="6b2a7206-d480-51c1-9d46-4271bde24fa3")}catch(e2){}})();import{orientOrderingEdge}from"./traversal.js";function propagateLatest(order,states,signal){for(let index=order.length-1;index>=0;index-=1){signal?.throwIfAborted();const state=states.get(order[index]);for(const id of state.successors){signal?.throwIfAborted();const successor=states.get(id);if(successor.latest===void 0||successor.duration===void 0)continue;const finish=successor.latest-successor.duration;if(state.latest===void 0||finish<state.latest){state.latest=finish;state.anchor=successor.anchor}}}}function deadlinePath(id,states,limit,signal){const reverse=[];let current=id;while(current!==void 0&&reverse.length<limit){signal?.throwIfAborted();reverse.push(current);current=states.get(current).predecessor}reverse.reverse();return{path:reverse,path_truncated:current!==void 0}}function initializeStates(nodes,items,now,residual,signal){const inputs=new Map(items.map(item=>[item.id,item]));const states=new Map;for(const id of nodes){signal?.throwIfAborted();const item=inputs.get(id);const estimate=item?.estimated_minutes;const duration=typeof estimate==="number"&&Number.isFinite(estimate)&&estimate>=0?estimate:void 0;const state={item,duration,pending:0,successors:new Set,earliest:0};if(item?.deadline!==void 0){const date=Date.parse(item.deadline);if(Number.isFinite(date)){state.deadline=(date-now)/6e4;state.latest=state.deadline;state.anchor=id}else residual(id,"invalid_deadline")}states.set(id,state)}return states}function indexScheduleEdges(graph,states,signal){for(const edge of graph.edges()){signal?.throwIfAborted();const definition=graph.registry().require(edge.kind);if(!definition.ordering)continue;const{predecessor,successor}=orientOrderingEdge(edge,definition);const source=states.get(predecessor);if(source.successors.has(successor))continue;source.successors.add(successor);states.get(successor).pending+=1}}function propagateEarliest(nodes,states,signal){const order=nodes.filter(id=>states.get(id).pending===0);for(let index=0;index<order.length;index+=1){signal?.throwIfAborted();const id=order[index];const state=states.get(id);const finish=state.earliest===null||state.duration===void 0?null:state.earliest+state.duration;for(const next of state.successors){signal?.throwIfAborted();const target=states.get(next);if(finish===null)target.earliest=null;else if(target.earliest!==null&&(finish>target.earliest||finish===target.earliest&&(target.predecessor===void 0||id<target.predecessor))){target.earliest=finish;target.predecessor=id}target.pending-=1;if(target.pending===0)order.push(next)}}return order}function collectDatedState(id,state,states,result,now,limit,pathBudget,signal){const duration=state.duration;if(state.latest!==void 0){result.scheduled_count+=1;const latest=state.latest-duration;if(result.rows.length<limit)result.rows.push({id,deadline_id:state.anchor,latest_start:new Date(now+latest*6e4).toISOString(),slack_minutes:state.earliest===null?null:latest-state.earliest});else result.truncated=true}if(state.deadline!==void 0&&state.earliest!==null&&state.earliest+duration>state.deadline){result.overcommitted_count+=1;if(result.overcommitted.length<limit){const evidence=deadlinePath(id,states,Math.min(limit,pathBudget.remaining),signal);pathBudget.remaining-=evidence.path.length;if(evidence.path_truncated)result.truncated=true;result.overcommitted.push({deadline_id:id,deadline:state.item.deadline,shortfall_minutes:state.earliest+duration-state.deadline,...evidence})}else result.truncated=true}}function collectScheduleResult(nodes,states,result,now,limit,maxPathEntries,residual,signal){const pathBudget={remaining:maxPathEntries};for(const id of nodes){signal?.throwIfAborted();const state=states.get(id);if(state.pending>0){residual(id,"cycle_or_gated_by_cycle");continue}if(state.duration===void 0){residual(id,"unknown_estimate");continue}if(state.latest!==void 0&&!Number.isFinite(new Date(now+(state.latest-state.duration)*6e4).getTime())){residual(id,"date_range_exceeded");continue}if(state.earliest===null)residual(id,"unknown_predecessor_estimate");collectDatedState(id,state,states,result,now,limit,pathBudget,signal)}}function deriveRelationshipDeadlines(graph,items,options={}){options.signal?.throwIfAborted();const now=Date.parse(options.now??new Date().toISOString());if(!Number.isFinite(now))throw new TypeError("Invalid scheduling clock");const maxWork=options.maxWork??1e5;const limit=options.limit??10;for(const[name,value]of[["maxWork",maxWork],["limit",limit]]){if(!Number.isSafeInteger(value)||value<1)throw new TypeError(`Invalid scheduling ${name}`)}const result={as_of:new Date(now).toISOString(),basis:"derived_elapsed_minutes",complete:true,truncated:false,work_limit_exceeded:false,scheduled_count:0,residual_count:0,overcommitted_count:0,rows:[],residuals:[],overcommitted:[]};const nodes=graph.nodes();const edges=graph.edges();if(nodes.length+edges.length+items.length>maxWork){return{...result,complete:false,work_limit_exceeded:true}}const residual=(id,reason)=>{result.complete=false;result.residual_count+=1;if(result.residuals.length<limit)result.residuals.push({id,reason});else result.truncated=true};const states=initializeStates(nodes,items,now,residual,options.signal);indexScheduleEdges(graph,states,options.signal);const order=propagateEarliest(nodes,states,options.signal);propagateLatest(order,states,options.signal);collectScheduleResult(nodes,states,result,now,limit,maxWork,residual,options.signal);return result}export{deriveRelationshipDeadlines};
+//# sourceMappingURL=deadline-scheduling.js.map

package/dist/sdk/graph/durable-cache.d.ts

@@ -1,6 +1,6 @@
 import { type RelationshipAuditSnapshot } from "./governance.js";
 /** Envelope format version; any change invalidates persisted entries. */
-export declare const GRAPH_DURABLE_CACHE_VERSION = 1;
+export declare const GRAPH_DURABLE_CACHE_VERSION = 2;
 /** Workspaces below this item count skip implicit persistence. */
 export declare const GRAPH_DURABLE_CACHE_MIN_ITEMS = 500;
 /** Persisted durable graph cache envelope keyed by one workspace fingerprint. */