@exellix/graph-engine 6.0.0

package/dist/src/inspection/controlInspection.js

@@ -0,0 +1,130 @@
+import { getGraphNodes } from './graphInspection.js';
+import { getNodeNarrixDiscovery } from './nodeInspection.js';
+/**
+ * Recursively collects leaf `path` strings from a graph edge predicate.
+ */
+export function collectPredicatePaths(predicate) {
+    if (predicate == null)
+        return [];
+    if (typeof predicate !== 'object')
+        return [];
+    if ('path' in predicate && typeof predicate.path === 'string') {
+        return [predicate.path];
+    }
+    if ('all' in predicate) {
+        const items = predicate.all;
+        if (!Array.isArray(items))
+            return [];
+        return items.flatMap((p) => collectPredicatePaths(p));
+    }
+    if ('any' in predicate) {
+        const items = predicate.any;
+        if (!Array.isArray(items))
+            return [];
+        return items.flatMap((p) => collectPredicatePaths(p));
+    }
+    if ('not' in predicate) {
+        return collectPredicatePaths(predicate.not);
+    }
+    return [];
+}
+/** Execution-memory dot-tail (no `executionMemory.` prefix). */
+export function executionMemoryPathTail(fullPath) {
+    const prefix = 'executionMemory.';
+    if (!fullPath.startsWith(prefix))
+        return null;
+    const tail = fullPath.slice(prefix.length);
+    return tail || null;
+}
+/**
+ * Same prefix semantics as io edge intersection: exact or parent/child path match.
+ */
+export function executionMemoryTailsMatch(a, b) {
+    if (a === b)
+        return true;
+    return a.startsWith(b + '.') || b.startsWith(a + '.');
+}
+/**
+ * All execution-memory write tails this node contributes (for control-flow matching).
+ * Includes executionMapping, narrix slots, webContext, synthesizedContext when applicable.
+ */
+export function getNodeExecutionMemoryWriteTails(node) {
+    const tails = new Set();
+    if (node.type === 'finalizer') {
+        return [];
+    }
+    const task = node;
+    if (task.executionMapping?.path) {
+        tails.add(task.executionMapping.path);
+    }
+    const narrix = getNodeNarrixDiscovery(node);
+    if (narrix?.enabled) {
+        tails.add('_narrix.scoping.signals');
+        tails.add('_narrix.scoping.stories');
+    }
+    const tc = task.taskConfiguration;
+    const profile = tc?.aiTaskProfile;
+    const ws = profile?.webScoping;
+    if (ws?.enabled === true) {
+        tails.add('webContext');
+    }
+    const inputSynth = profile?.inputSynthesis;
+    if (inputSynth?.enabled === true) {
+        tails.add('synthesizedContext');
+    }
+    return [...tails];
+}
+function getNodeById(graph, id) {
+    return getGraphNodes(graph).find((n) => n.id === id);
+}
+/**
+ * Lists edges whose `when` predicates read execution-memory paths produced by `nodeId`,
+ * and routing hints from graphReadability.
+ */
+export function getNodeControlDependencies(graph, nodeId) {
+    const node = getNodeById(graph, nodeId);
+    const writeTails = node ? getNodeExecutionMemoryWriteTails(node) : [];
+    const edges = graph.edges ?? [];
+    const branches = [];
+    const matchedFullPaths = new Set();
+    for (const edge of edges) {
+        if (edge.when == null)
+            continue;
+        const paths = collectPredicatePaths(edge.when);
+        const matched = [];
+        for (const full of paths) {
+            const tail = executionMemoryPathTail(full);
+            if (tail == null)
+                continue;
+            for (const w of writeTails) {
+                if (executionMemoryTailsMatch(tail, w)) {
+                    matched.push(full);
+                    matchedFullPaths.add(full);
+                    break;
+                }
+            }
+        }
+        if (matched.length > 0) {
+            branches.push({
+                from: edge.from,
+                to: edge.to,
+                when: edge.when,
+                matchedExecutionMemoryPaths: [...new Set(matched)],
+            });
+        }
+    }
+    const influencesPredicate = branches.length > 0;
+    const readabilityKind = node && node.type !== 'finalizer'
+        ? node.metadata?.graphReadability?.kind
+        : undefined;
+    const routingHintFromReadability = readabilityKind === 'routing';
+    const isRoutingNode = routingHintFromReadability || influencesPredicate;
+    return {
+        isRoutingNode,
+        routingHintFromReadability,
+        edgesConditionalOnThisWriter: branches,
+        predicatePathsThatMatchedWrites: [...matchedFullPaths],
+        downstreamBranchMap: branches,
+        provenance: 'derived',
+    };
+}

package/dist/src/inspection/graphInspection.d.ts

@@ -0,0 +1,51 @@
+import type { Graph, GraphNode, GraphEdge } from '../types/refs.js';
+import { type GraphInspection, type GraphCatalogs, type MaterializeVirtualBoundaryDiagramOptions, type MaterializedVirtualBoundaryDiagram, type VirtualGraphEntryLayer, type VirtualGraphResponseLayer } from './types.js';
+/**
+ * Returns `graph.nodes`. Canonical 5.x: `graph.nodes` is always a `GraphNode[]`.
+ * Record-keyed nodes are rejected by `assertCanonicalGraphDocument` at load time,
+ * so this helper is essentially an identity used by callers that still take a
+ * permissive `Graph` shape.
+ */
+export declare function getGraphNodes(graph: Graph): GraphNode[];
+/**
+ * Extracts all catalog references from a graph JSON, aggregated across all nodes.
+ */
+export declare function getGraphCatalogs(graph: Graph): GraphCatalogs;
+/**
+ * Layer 01 visualization anchor: **not** in `graph.nodes`. Use when building graph diagrams
+ * so callers see where `execution.input.*` is seeded before the first real nodes run.
+ */
+export declare function getVirtualGraphEntryLayer(graph: Graph): VirtualGraphEntryLayer;
+/**
+ * Layer 08 visualization anchor: **not** in `graph.nodes`. Use when building graph diagrams
+ * so callers see where `graph.response` / `finalOutput` conceptually leaves the DAG.
+ */
+export declare function getVirtualGraphResponseLayer(graph: Graph): VirtualGraphResponseLayer;
+/**
+ * Returns **copies** of the graph’s real `nodes` / `edges` plus synthetic Layer 01 / 08 boundary
+ * nodes and edges aligned with {@link inspectGraph}'s `virtualIO` field.
+ *
+ * **Not executable:** exellix-graph ignores these ids in authored JSON today; if you merge this blob
+ * back into a graph document, strip synthetic nodes and edges (see {@link stripMaterializedVirtualBoundaryDiagram})
+ * before calling {@link executeGraph}.
+ *
+ * @throws If a real node uses an id reserved for virtual boundaries.
+ */
+export declare function materializeVirtualBoundaryDiagram(graph: Graph, options?: MaterializeVirtualBoundaryDiagramOptions): MaterializedVirtualBoundaryDiagram;
+/**
+ * Removes synthetic boundary nodes and edges produced by {@link materializeVirtualBoundaryDiagram}.
+ * Also drops any edge incident to the reserved virtual ids. Safe on diagrams that only mark
+ * synthetic edges (flags) without markers on nodes, as long as ids match the stable virtual ids.
+ */
+export declare function stripMaterializedVirtualBoundaryDiagram(diagram: MaterializedVirtualBoundaryDiagram): {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+};
+/**
+ * Produces a complete planning-level inspection of the graph:
+ * - Per-node scoping questions, memory shapes, narrix discovery
+ * - Topological execution order
+ * - I/O connections between adjacent nodes
+ * - Aggregated catalog references
+ */
+export declare function inspectGraph(graph: Graph): GraphInspection;

package/dist/src/inspection/graphInspection.js

@@ -0,0 +1,467 @@
+import { mergeGraphDocumentModel } from '../types/refs.js';
+import { assertCanonicalGraphDocument } from '../runtime/validateCanonicalGraphDocument.js';
+import { isLocalSkillKey } from '../runtime/localSkills/index.js';
+import { inspectNode, resolveNodeSkillKey } from './nodeInspection.js';
+import { EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID, EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID, EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY, EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY, } from './types.js';
+// ---------------------------------------------------------------------------
+// Graph node normalization
+// ---------------------------------------------------------------------------
+/**
+ * Returns `graph.nodes`. Canonical 5.x: `graph.nodes` is always a `GraphNode[]`.
+ * Record-keyed nodes are rejected by `assertCanonicalGraphDocument` at load time,
+ * so this helper is essentially an identity used by callers that still take a
+ * permissive `Graph` shape.
+ */
+export function getGraphNodes(graph) {
+    if (Array.isArray(graph.nodes))
+        return graph.nodes;
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Topological sort (Kahn's algorithm)
+// ---------------------------------------------------------------------------
+function topoSort(nodeIds, edges) {
+    // Build adjacency: from → set of tos, and in-degree counts
+    const successors = new Map();
+    const inDegree = new Map();
+    for (const id of nodeIds) {
+        successors.set(id, new Set());
+        inDegree.set(id, 0);
+    }
+    for (const edge of edges) {
+        const { from, to } = edge;
+        if (!successors.has(from) || !inDegree.has(to))
+            continue;
+        successors.get(from).add(to);
+        inDegree.set(to, (inDegree.get(to) ?? 0) + 1);
+    }
+    const queue = [];
+    for (const id of nodeIds) {
+        if ((inDegree.get(id) ?? 0) === 0)
+            queue.push(id);
+    }
+    const order = [];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        order.push(id);
+        for (const succ of successors.get(id) ?? []) {
+            const deg = (inDegree.get(succ) ?? 1) - 1;
+            inDegree.set(succ, deg);
+            if (deg === 0)
+                queue.push(succ);
+        }
+    }
+    // Append any remaining nodes not reached (disconnected or cyclic) in original order
+    const seen = new Set(order);
+    for (const id of nodeIds) {
+        if (!seen.has(id))
+            order.push(id);
+    }
+    return order;
+}
+// ---------------------------------------------------------------------------
+// Catalog extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extracts all catalog references from a graph JSON, aggregated across all nodes.
+ */
+export function getGraphCatalogs(graph) {
+    const nodes = getGraphNodes(graph);
+    const scopingMapIds = new Set();
+    const narrixQuestionIds = new Set();
+    const narrixLayers = new Set();
+    const narrixNarrativeTypeIds = new Set();
+    const localSkillKeysSet = new Set();
+    const aiSkillKeys = new Set();
+    const readabilityKinds = new Set();
+    const scopedQuestionCatalogIds = new Set();
+    const discoveryDefinitionCatalogIds = new Set();
+    const catalogBindings = [];
+    let catalogRequestScoped = 0;
+    let catalogRequestDiscovery = 0;
+    let catalogRequestOther = 0;
+    const gm = graph.metadata;
+    if (gm?.catalogRequests != null && Array.isArray(gm.catalogRequests)) {
+        for (const req of gm.catalogRequests) {
+            const ct = req != null && typeof req === 'object' && !Array.isArray(req)
+                ? String(req.catalogType ?? '')
+                : '';
+            if (ct === 'scoped-question')
+                catalogRequestScoped += 1;
+            else if (ct === 'discovery-definition')
+                catalogRequestDiscovery += 1;
+            else if (ct)
+                catalogRequestOther += 1;
+        }
+    }
+    for (const node of nodes) {
+        if (node.type === 'finalizer')
+            continue;
+        const meta = node.metadata;
+        const tc = node.taskConfiguration;
+        const skillKey = resolveNodeSkillKey(node);
+        // Skill key classification
+        if (skillKey) {
+            if (isLocalSkillKey(skillKey)) {
+                localSkillKeysSet.add(skillKey);
+            }
+            else {
+                aiSkillKeys.add(skillKey);
+            }
+        }
+        if (meta) {
+            const cb = meta.catalogBinding;
+            if (cb && typeof cb === 'object' && typeof cb.catalogId === 'string' && cb.catalogId) {
+                const ct = typeof cb.catalogType === 'string' ? cb.catalogType : '';
+                if (ct === 'scoped-question')
+                    scopedQuestionCatalogIds.add(cb.catalogId);
+                if (ct === 'discovery-definition')
+                    discoveryDefinitionCatalogIds.add(cb.catalogId);
+                catalogBindings.push({
+                    nodeId: String(node.id),
+                    catalogType: ct || 'unknown',
+                    catalogId: cb.catalogId,
+                    version: typeof cb.version === 'string' ? cb.version : '',
+                });
+            }
+            // graphReadability.kind
+            if (typeof meta.graphReadability?.kind === 'string') {
+                readabilityKinds.add(meta.graphReadability.kind);
+            }
+        }
+        if (!tc)
+            continue;
+        // scopingMapId (scoped-data-reader config)
+        if (typeof tc.scopingMapId === 'string') {
+            scopingMapIds.add(tc.scopingMapId);
+        }
+        // Pack slots may also carry scopingMapIds
+        if (Array.isArray(tc.pack)) {
+            for (const slot of tc.pack) {
+                if (typeof slot.scopingMapId === 'string')
+                    scopingMapIds.add(slot.scopingMapId);
+            }
+        }
+        // narrix config
+        const narrix = tc.narrix;
+        if (narrix) {
+            if (typeof narrix.questionId === 'string')
+                narrixQuestionIds.add(narrix.questionId);
+            // Opaque graph/pack label — aggregate only for inspection UIs, no validation.
+            if (typeof narrix.layer === 'string')
+                narrixLayers.add(narrix.layer);
+            if (Array.isArray(narrix.narrativeTypeIds)) {
+                for (const id of narrix.narrativeTypeIds)
+                    narrixNarrativeTypeIds.add(id);
+            }
+        }
+    }
+    return {
+        scopingMapIds: [...scopingMapIds],
+        narrixQuestionIds: [...narrixQuestionIds],
+        narrixLayers: [...narrixLayers],
+        narrixNarrativeTypeIds: [...narrixNarrativeTypeIds],
+        localSkillKeys: [...localSkillKeysSet],
+        aiSkillKeys: [...aiSkillKeys],
+        graphReadabilityKinds: [...readabilityKinds],
+        scopedQuestionCatalogIds: [...scopedQuestionCatalogIds],
+        discoveryDefinitionCatalogIds: [...discoveryDefinitionCatalogIds],
+        catalogBindings,
+        catalogRequestCounts: {
+            scopedQuestion: catalogRequestScoped,
+            discoveryDefinition: catalogRequestDiscovery,
+            other: catalogRequestOther,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// I/O edge derivation
+// ---------------------------------------------------------------------------
+/**
+ * Builds an array of NodeIOEdge by cross-referencing what each `from` node writes
+ * with what each `to` node reads, for every edge in the graph.
+ */
+function buildIOEdges(edges, nodeInspections) {
+    return edges.map((edge) => {
+        const fromInspection = nodeInspections[edge.from];
+        const toInspection = nodeInspections[edge.to];
+        const executionWrittenPaths = fromInspection?.memoryShape.after.writes.map((w) => w.path) ?? [];
+        const outputsWrittenPaths = fromInspection?.memoryShape.after.outputsMemoryWrites?.map((w) => w.path) ?? [];
+        const writtenPaths = [...executionWrittenPaths, ...outputsWrittenPaths];
+        const toReads = toInspection?.memoryShape.before.reads ?? [];
+        const executionToReadPaths = new Set(toReads.filter((r) => r.memory !== 'outputsMemory').map((r) => r.path));
+        const outputsToReadPaths = new Set(toReads.filter((r) => r.memory === 'outputsMemory').map((r) => r.path));
+        // Intersection: paths that `from` writes and `to` reads
+        const pathMatches = (p, candidates) => {
+            // Exact match or prefix match (e.g. `scoped` covers `scoped.subnet.composition`)
+            return candidates.has(p) || [...candidates].some((rp) => rp.startsWith(p + '.') || p.startsWith(rp + '.'));
+        };
+        const executionReadPaths = executionWrittenPaths.filter((p) => pathMatches(p, executionToReadPaths));
+        const outputsReadPaths = outputsWrittenPaths.filter((p) => pathMatches(p, outputsToReadPaths));
+        const readPaths = [...executionReadPaths, ...outputsReadPaths];
+        return {
+            from: edge.from,
+            to: edge.to,
+            writtenPaths,
+            executionWrittenPaths,
+            outputsWrittenPaths,
+            readPaths,
+            executionReadPaths,
+            outputsReadPaths,
+            ...(edge.when != null ? { when: edge.when } : {}),
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// Virtual graph I/O (Layer 01 / 08) — inspection only
+// ---------------------------------------------------------------------------
+function findFirstWaveNodeIds(nodeIds, edges) {
+    const incoming = new Set();
+    for (const e of edges) {
+        if (e && typeof e.to === 'string')
+            incoming.add(e.to);
+    }
+    return nodeIds.filter((id) => !incoming.has(id));
+}
+/**
+ * When exactly one finalizer exists and it has no outgoing authored edges, returns its id.
+ * Otherwise null (invalid graph or cannot name a single canonical `finalOutput` producer).
+ */
+function findCanonicalFinalizerId(nodeIds, nodes, edges) {
+    const fins = nodes.filter((n) => n.type === 'finalizer');
+    if (fins.length !== 1)
+        return null;
+    const fid = String(fins[0].id);
+    if (!nodeIds.includes(fid))
+        return null;
+    const hasOut = edges.some((e) => e && e.from === fid);
+    if (hasOut)
+        return null;
+    return fid;
+}
+function buildVirtualIO(nodeIds, nodes, edges) {
+    const firstWaveNodeIds = findFirstWaveNodeIds(nodeIds, edges);
+    const canonicalFinalizerId = findCanonicalFinalizerId(nodeIds, nodes, edges);
+    const virtualNodes = [
+        {
+            id: EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID,
+            role: 'graph-entry',
+            layer: 1,
+            description: 'Layer 01 — Graph entry: caller-provided execution.input.* via ExecuteGraphOptions.execution (not a DAG node).',
+        },
+        {
+            id: EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID,
+            role: 'graph-response',
+            layer: 8,
+            description: 'Layer 08 — Final Response: ExecuteGraphResult.finalOutput resolved from root graph.response (not a DAG node).',
+        },
+    ];
+    const virtualEdges = firstWaveNodeIds.map((to) => ({
+        from: EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID,
+        to,
+    }));
+    if (canonicalFinalizerId != null) {
+        virtualEdges.push({
+            from: canonicalFinalizerId,
+            to: EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID,
+        });
+    }
+    return {
+        nodes: virtualNodes,
+        edges: virtualEdges,
+        firstWaveNodeIds,
+        canonicalFinalizerId,
+    };
+}
+/** Shared virtual I/O computation for `inspectGraph` and visualization helpers. */
+function computeVirtualIO(graph) {
+    const nodes = getGraphNodes(graph);
+    const edges = graph.edges ?? [];
+    return buildVirtualIO(nodes.map((n) => n.id), nodes, edges);
+}
+/**
+ * Layer 01 visualization anchor: **not** in `graph.nodes`. Use when building graph diagrams
+ * so callers see where `execution.input.*` is seeded before the first real nodes run.
+ */
+export function getVirtualGraphEntryLayer(graph) {
+    const v = computeVirtualIO(graph);
+    const virtualNode = v.nodes.find((n) => n.role === 'graph-entry');
+    if (!virtualNode) {
+        throw new Error('EXELLIX_VIRTUAL_IO_INVARIANT: missing graph-entry virtual node');
+    }
+    return {
+        virtualNode,
+        outgoingEdges: v.edges.filter((e) => e.from === EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID),
+        firstWaveNodeIds: v.firstWaveNodeIds,
+    };
+}
+/**
+ * Layer 08 visualization anchor: **not** in `graph.nodes`. Use when building graph diagrams
+ * so callers see where `graph.response` / `finalOutput` conceptually leaves the DAG.
+ */
+export function getVirtualGraphResponseLayer(graph) {
+    const v = computeVirtualIO(graph);
+    const virtualNode = v.nodes.find((n) => n.role === 'graph-response');
+    if (!virtualNode) {
+        throw new Error('EXELLIX_VIRTUAL_IO_INVARIANT: missing graph-response virtual node');
+    }
+    return {
+        virtualNode,
+        incomingEdges: v.edges.filter((e) => e.to === EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID),
+        canonicalFinalizerId: v.canonicalFinalizerId,
+    };
+}
+const RESERVED_VIRTUAL_BOUNDARY_NODE_IDS = new Set([
+    EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID,
+    EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID,
+]);
+function cloneGraphNode(node) {
+    return structuredClone(node);
+}
+function cloneGraphEdge(edge) {
+    return structuredClone(edge);
+}
+function virtualIONodeToMaterializedGraphNode(vn, markSynthetic) {
+    const metadata = {
+        woroxVirtualBoundary: {
+            role: vn.role,
+            layer: vn.layer,
+            description: vn.description,
+        },
+    };
+    if (markSynthetic) {
+        metadata[EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY] = true;
+    }
+    return {
+        id: vn.id,
+        type: '__exellixVirtualBoundary',
+        metadata,
+    };
+}
+/**
+ * Returns **copies** of the graph’s real `nodes` / `edges` plus synthetic Layer 01 / 08 boundary
+ * nodes and edges aligned with {@link inspectGraph}'s `virtualIO` field.
+ *
+ * **Not executable:** exellix-graph ignores these ids in authored JSON today; if you merge this blob
+ * back into a graph document, strip synthetic nodes and edges (see {@link stripMaterializedVirtualBoundaryDiagram})
+ * before calling {@link executeGraph}.
+ *
+ * @throws If a real node uses an id reserved for virtual boundaries.
+ */
+export function materializeVirtualBoundaryDiagram(graph, options) {
+    const markNodes = options?.markSyntheticNodes !== false;
+    const markEdges = options?.markSyntheticEdges !== false;
+    const v = computeVirtualIO(graph);
+    const realNodes = getGraphNodes(graph);
+    for (const n of realNodes) {
+        if (RESERVED_VIRTUAL_BOUNDARY_NODE_IDS.has(String(n.id))) {
+            throw new Error(`materializeVirtualBoundaryDiagram: node id "${n.id}" is reserved for Layer 01/08 virtual boundaries`);
+        }
+    }
+    const nodes = [...realNodes.map(cloneGraphNode), ...v.nodes.map((vn) => virtualIONodeToMaterializedGraphNode(vn, markNodes))];
+    const realEdges = graph.edges ?? [];
+    const syntheticEdges = v.edges.map((e) => {
+        const edge = { ...e };
+        if (markEdges) {
+            edge[EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY] = true;
+        }
+        return edge;
+    });
+    return {
+        nodes,
+        edges: [...realEdges.map(cloneGraphEdge), ...syntheticEdges],
+        virtualMeta: {
+            entryNodeId: EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID,
+            responseNodeId: EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID,
+            firstWaveNodeIds: [...v.firstWaveNodeIds],
+            canonicalFinalizerId: v.canonicalFinalizerId,
+            syntheticNodeIds: [EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID, EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID],
+            notExecutable: true,
+            nodeMarker: EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY,
+            edgeMarker: EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY,
+        },
+    };
+}
+/**
+ * Removes synthetic boundary nodes and edges produced by {@link materializeVirtualBoundaryDiagram}.
+ * Also drops any edge incident to the reserved virtual ids. Safe on diagrams that only mark
+ * synthetic edges (flags) without markers on nodes, as long as ids match the stable virtual ids.
+ */
+export function stripMaterializedVirtualBoundaryDiagram(diagram) {
+    const nodes = diagram.nodes.filter((n) => {
+        const id = String(n.id);
+        if (RESERVED_VIRTUAL_BOUNDARY_NODE_IDS.has(id))
+            return false;
+        const meta = n.metadata;
+        if (meta?.[EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY] === true)
+            return false;
+        return true;
+    });
+    const ids = new Set(nodes.map((n) => String(n.id)));
+    const edges = diagram.edges.filter((e) => {
+        if (e[EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY] === true)
+            return false;
+        if (RESERVED_VIRTUAL_BOUNDARY_NODE_IDS.has(e.from) || RESERVED_VIRTUAL_BOUNDARY_NODE_IDS.has(e.to)) {
+            return false;
+        }
+        return ids.has(e.from) && ids.has(e.to);
+    });
+    return { nodes, edges };
+}
+// ---------------------------------------------------------------------------
+// Full graph inspection
+// ---------------------------------------------------------------------------
+/**
+ * Produces a complete planning-level inspection of the graph:
+ * - Per-node scoping questions, memory shapes, narrix discovery
+ * - Topological execution order
+ * - I/O connections between adjacent nodes
+ * - Aggregated catalog references
+ */
+export function inspectGraph(graph) {
+    assertCanonicalGraphDocument(graph, { graphId: graph?.id });
+    const nodes = getGraphNodes(graph);
+    const edges = graph.edges ?? [];
+    const nodeIds = nodes.map((n) => n.id);
+    const executionOrder = topoSort(nodeIds, edges);
+    // Build a lookup from nodeId → list of upstream write paths
+    // We iterate in execution order, accumulating write paths as we go.
+    const accumulatedWritePaths = new Map();
+    const cumulativeWrites = [];
+    // First pass: resolve per-node write paths to populate the map
+    const nodeWritePathsMap = new Map();
+    for (const node of nodes) {
+        const writes = [];
+        if (node.type !== 'finalizer') {
+            const em = node.executionMapping;
+            if (em?.path)
+                writes.push(em.path);
+        }
+        nodeWritePathsMap.set(node.id, writes);
+    }
+    // Build upstream write paths per node (everything written before this node in topo order)
+    for (const nodeId of executionOrder) {
+        accumulatedWritePaths.set(nodeId, [...cumulativeWrites]);
+        const writes = nodeWritePathsMap.get(nodeId) ?? [];
+        cumulativeWrites.push(...writes);
+    }
+    // Build per-node inspections
+    const nodeInspections = {};
+    for (const node of nodes) {
+        const upstream = accumulatedWritePaths.get(node.id) ?? [];
+        nodeInspections[node.id] = inspectNode(node, upstream, graph);
+    }
+    const ioEdges = buildIOEdges(edges, nodeInspections);
+    const catalogs = getGraphCatalogs(graph);
+    const virtualIO = computeVirtualIO(graph);
+    return {
+        graphId: graph.id,
+        nodes: nodeInspections,
+        executionOrder,
+        edges,
+        ioEdges,
+        catalogs,
+        graphDocumentModel: mergeGraphDocumentModel(graph),
+        virtualIO,
+    };
+}

package/dist/src/inspection/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Graph Inspection API
+ *
+ * Planning-level visibility into any exellix-graph JSON:
+ * - Per-node scoping questions (what a node asks, where it reads, where it writes)
+ * - Live scoped-data fetch for a node given an entityId
+ * - Execution-memory shapes before and after each node
+ * - Narrix discovery configuration per node
+ * - Full graph inspection: execution order, I/O edges between nodes, catalog references
+ */
+export { getNodeScopingQuestion, getNodeMemoryShape, getNodeNarrixDiscovery, fetchNodeScopingData, inspectNode, resolveNodeSkillKey, } from './nodeInspection.js';
+export { getGraphNodes, getGraphCatalogs, inspectGraph, getVirtualGraphEntryLayer, getVirtualGraphResponseLayer, materializeVirtualBoundaryDiagram, stripMaterializedVirtualBoundaryDiagram, } from './graphInspection.js';
+export { validateCatalogPlanning, isCatalogBinding, isCatalogRequestEntry, } from './validateCatalogPlanning.js';
+export type { CatalogPlanningValidationIssue } from './validateCatalogPlanning.js';
+export { collectPredicatePaths, executionMemoryPathTail, executionMemoryTailsMatch, getNodeExecutionMemoryWriteTails, getNodeControlDependencies, } from './controlInspection.js';
+export { getNodeSideEffects, inspectFinalizer, inspectNodeContract, inspectGraphContracts, } from './contractInspection.js';
+export type { InspectNodeContractOptions } from './contractInspection.js';
+export type { NodeScopingQuestion, NodeScopeSource, NodeScopeTarget, NodeScopingData, NodeMemoryShape, MemoryPath, NodeNarrixDiscovery, NodeInspection, GraphInspection, NodeIOEdge, GraphCatalogs, CatalogBindingSummary, GraphVirtualIO, GraphVirtualIONode, GraphVirtualIOEdge, GraphVirtualIONodeRole, VirtualGraphEntryLayer, VirtualGraphResponseLayer, MaterializeVirtualBoundaryDiagramOptions, MaterializedVirtualBoundaryDiagram, MaterializedVirtualBoundaryDiagramMeta, } from './types.js';
+export { EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID, EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID, EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY, EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY, } from './types.js';
+export type { GraphDocumentMetadata } from '../types/refs.js';
+export type { LocalSkillKey, NodeExecutionType, FactProvenance, ProvenancedSection, NodeInputBindingEntry, ScopedDataDependency, NodeInputContract, ExecutionMemoryWriteSpec, NodeOutputContract, NodeSideEffects, ControlBranchEntry, NodeControlContract, NodeValidationContract, FinalizerContractInspection, NodeContractInspection, GraphContractsInspection, } from './contractTypes.js';

package/dist/src/inspection/index.js

@@ -0,0 +1,17 @@
+/**
+ * Graph Inspection API
+ *
+ * Planning-level visibility into any exellix-graph JSON:
+ * - Per-node scoping questions (what a node asks, where it reads, where it writes)
+ * - Live scoped-data fetch for a node given an entityId
+ * - Execution-memory shapes before and after each node
+ * - Narrix discovery configuration per node
+ * - Full graph inspection: execution order, I/O edges between nodes, catalog references
+ */
+// Functions
+export { getNodeScopingQuestion, getNodeMemoryShape, getNodeNarrixDiscovery, fetchNodeScopingData, inspectNode, resolveNodeSkillKey, } from './nodeInspection.js';
+export { getGraphNodes, getGraphCatalogs, inspectGraph, getVirtualGraphEntryLayer, getVirtualGraphResponseLayer, materializeVirtualBoundaryDiagram, stripMaterializedVirtualBoundaryDiagram, } from './graphInspection.js';
+export { validateCatalogPlanning, isCatalogBinding, isCatalogRequestEntry, } from './validateCatalogPlanning.js';
+export { collectPredicatePaths, executionMemoryPathTail, executionMemoryTailsMatch, getNodeExecutionMemoryWriteTails, getNodeControlDependencies, } from './controlInspection.js';
+export { getNodeSideEffects, inspectFinalizer, inspectNodeContract, inspectGraphContracts, } from './contractInspection.js';
+export { EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID, EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID, EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY, EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY, } from './types.js';