@exellix/graphs-studio-data-flow 0.1.0

package/src/informationFlowOutputSurface.js

@@ -0,0 +1,339 @@
+/**
+ * Scope-correct labels and path lists for the Information Flow "output" column and inspector.
+ */
+import { getGraphNodes } from '@exellix/graph-engine/dist/src/inspection/index.js';
+import { getResponseViewState } from './graphContractMetadata.js';
+import { classifyExecutionPath } from './pathClassification.js';
+import { downstreamReaders, upstreamWriters } from './ioLinking.js';
+import {
+  getResolvedWebScopingPlanning,
+  hasWebScopingPlanningIntent,
+  supportsWebScopingPlanning,
+} from './webScopingPlanning.js';
+import {
+  readNodeInputSynthesisEnabled,
+  readNodeWebScopeEnabled,
+} from './lib/nodeMetadataAccessors.js';
+
+/**
+ * @typedef {'graph' | 'scoping' | 'discovery' | 'selected-node'} InformationFlowFocus
+ */
+
+/**
+ * @typedef {{
+ *   columnTitle: string;
+ *   columnHint: string;
+ *   cardTitle: string;
+ *   cardSubtitle: string;
+ *   summary: string;
+ *   primaryPaths: string[];
+ *   debugPaths: string[];
+ *   canonicalFinalizerId: string | null;
+ *   emptyMessage: string | null;
+ *   showGraphResponseEditor: boolean;
+ * }} InformationFlowOutputSurface
+ */
+
+/**
+ * @param {string} path
+ */
+function pathIsDiscoveryRelated(path) {
+  const p = String(path || '');
+  if (p.includes('_narrix')) return true;
+  if (p.includes('webContext')) return true;
+  if (p.includes('synthesizedContext')) return true;
+  if (p.includes('jobContext.webContext')) return true;
+  return false;
+}
+
+/**
+ * @param {string} path
+ */
+function pathIsScopingSliceOutput(path) {
+  const { namespace, classification } = classifyExecutionPath(path);
+  if (namespace === 'scoped' || namespace === 'webContext') return true;
+  if (classification === 'scoped') return true;
+  return false;
+}
+
+/**
+ * @param {import('./types.js').ResolvedNodeIO|undefined} io
+ * @returns {string[]}
+ */
+function nonInspectorWritePaths(io) {
+  if (!io?.writes) return [];
+  return io.writes.filter((w) => !w._inspectorOnly).map((w) => w.path);
+}
+
+/**
+ * @param {string[]} paths
+ */
+function uniqueSorted(paths) {
+  return [...new Set(paths.filter(Boolean))].sort();
+}
+
+/**
+ * @param {object} rawNode
+ * @param {import('./types.js').ResolvedNodeIO|undefined} io
+ */
+function nodeIsDiscoverySeed(rawNode, io) {
+  if (supportsWebScopingPlanning(rawNode)) {
+    const { mode } = getResolvedWebScopingPlanning(rawNode);
+    if (mode === 'ai-decision' || mode === 'always') return true;
+  }
+  const m = rawNode.metadata?.narrix;
+  if (m && typeof m === 'object') {
+    if (m.datasetId || m.questionId || m.layer != null) return true;
+  }
+  if (readNodeWebScopeEnabled(rawNode)) return true;
+  if (readNodeInputSynthesisEnabled(rawNode)) return true;
+  if (!io) return false;
+  for (const r of io.reads || []) {
+    if (r._inspectorOnly) continue;
+    if (pathIsDiscoveryRelated(r.path)) return true;
+  }
+  for (const w of io.writes || []) {
+    if (w._inspectorOnly) continue;
+    if (pathIsDiscoveryRelated(w.path)) return true;
+  }
+  return false;
+}
+
+/**
+ * @param {Set<string>|Iterable<string>} seeds
+ * @param {object[]} ioLinks
+ */
+function expandOneHop(seeds, ioLinks) {
+  const out = new Set(seeds);
+  for (const id of seeds) {
+    for (const w of upstreamWriters(ioLinks, id)) out.add(w);
+    for (const r of downstreamReaders(ioLinks, id)) out.add(r);
+  }
+  return out;
+}
+
+function addDownstreamConsumers(ids, flowNodes) {
+  const flowById = new Map(flowNodes.map((n) => [n.id, n]));
+  for (const id of [...ids]) {
+    const fn = flowById.get(id);
+    const dc = fn?.downstreamConsumers || [];
+    for (const c of dc) ids.add(c);
+  }
+}
+
+/**
+ * @param {object} full - from buildPlanningInformationFlow
+ * @param {import('@exellix-refs').Graph} graph
+ * @param {import('./types.js').GraphAnalysisResult} graphAnalysis
+ * @param {{ focus: InformationFlowFocus, selectedNodeId?: string }} options
+ * @returns {InformationFlowOutputSurface}
+ */
+export function buildInformationFlowOutputSurface(full, graph, graphAnalysis, options) {
+  const { focus, selectedNodeId } = options;
+  if (!full || !graph || !graphAnalysis || graphAnalysis.status !== 'ok') {
+    return {
+      columnTitle: 'Outputs',
+      columnHint: '',
+      cardTitle: 'Outputs',
+      cardSubtitle: '',
+      summary: '',
+      primaryPaths: [],
+      debugPaths: [],
+      canonicalFinalizerId: null,
+      emptyMessage: 'Analysis unavailable.',
+      showGraphResponseEditor: false,
+    };
+  }
+  const rs = getResponseViewState(graph?.metadata);
+  const nodeIO = graphAnalysis?.nodeIO || {};
+  const ioLinks = graphAnalysis?.ioLinks || [];
+  const rawNodes = getGraphNodes(graph);
+  const flowNodes = full?.nodes || [];
+
+  if (focus === 'graph') {
+    const primary = full?.response?.primaryPaths || rs.primaryResponsePaths || [];
+    const debug = full?.response?.debugPaths || rs.debugResponsePaths || [];
+    return {
+      columnTitle: 'Graph response',
+      columnHint: 'Declared graph response mapping, examples, and response paths.',
+      cardTitle: 'Graph response',
+      cardSubtitle: 'Result boundary',
+      summary: full?.response?.summary || rs.summary || '',
+      primaryPaths: primary,
+      debugPaths: debug,
+      canonicalFinalizerId: full?.response?.canonicalFinalizerId ?? null,
+      emptyMessage:
+        primary.length === 0 && debug.length === 0 && !(full?.response?.canonicalFinalizerId)
+          ? 'No response paths declared in graph metadata.'
+          : null,
+      showGraphResponseEditor: true,
+    };
+  }
+
+  if (focus === 'selected-node') {
+    const rawById = new Map(rawNodes.map((n) => [n.id, n]));
+    if (!selectedNodeId || !rawById.has(selectedNodeId)) {
+      return {
+        columnTitle: 'Node outputs',
+        columnHint: 'Paths this node writes and downstream-visible outputs.',
+        cardTitle: 'Node outputs',
+        cardSubtitle: 'Selected node',
+        summary: '',
+        primaryPaths: [],
+        debugPaths: [],
+        canonicalFinalizerId: null,
+        emptyMessage: 'No node selected for this focus.',
+        showGraphResponseEditor: false,
+      };
+    }
+
+    const canonicalFinalizerId = full?.response?.canonicalFinalizerId ?? null;
+    const isFinalizer = canonicalFinalizerId === selectedNodeId;
+
+    let primaryPaths = uniqueSorted(nonInspectorWritePaths(nodeIO[selectedNodeId]));
+    let debugPaths = [];
+    let summary = '';
+
+    if (isFinalizer) {
+      summary = full?.response?.summary || rs.summary || '';
+      primaryPaths = uniqueSorted([
+        ...primaryPaths,
+        ...(rs.primaryResponsePaths || []),
+        ...(full?.response?.primaryPaths || []),
+      ]);
+      debugPaths = uniqueSorted([
+        ...(rs.debugResponsePaths || []),
+        ...(full?.response?.debugPaths || []),
+      ]);
+    }
+
+    const emptyMessage =
+      primaryPaths.length === 0 && debugPaths.length === 0
+        ? 'No node outputs declared for this node.'
+        : null;
+
+    return {
+      columnTitle: 'Node outputs',
+      columnHint: 'What this node emits — writes and declared response paths (finalizer only).',
+      cardTitle: 'Node outputs',
+      cardSubtitle: isFinalizer ? 'This node is the graph finalizer' : 'Produced paths',
+      summary,
+      primaryPaths,
+      debugPaths,
+      canonicalFinalizerId: isFinalizer ? canonicalFinalizerId : null,
+      emptyMessage,
+      showGraphResponseEditor: false,
+    };
+  }
+
+  if (focus === 'scoping') {
+    /** @type {Set<string>} */
+    const seeds = new Set();
+    for (const fn of flowNodes) {
+      if (fn.planningSourceFamily === 'scoped-read' || fn.planningSourceFamily === 'web-scope') {
+        seeds.add(fn.id);
+      }
+    }
+    for (const n of rawNodes) {
+      if (hasWebScopingPlanningIntent(n)) seeds.add(n.id);
+    }
+
+    if (seeds.size === 0) {
+      return {
+        columnTitle: 'Scoping outputs',
+        columnHint: 'Scoped paths and web-scoping writes from the scoping slice.',
+        cardTitle: 'Scoping outputs',
+        cardSubtitle: 'Slice boundary',
+        summary: '',
+        primaryPaths: [],
+        debugPaths: [],
+        canonicalFinalizerId: null,
+        emptyMessage: 'No scoping outputs in this focus — no scoped reads, web-scope sources, or web-scoping intent.',
+        showGraphResponseEditor: false,
+      };
+    }
+
+    const ids = expandOneHop(seeds, ioLinks);
+    addDownstreamConsumers(ids, flowNodes);
+
+    /** @type {string[]} */
+    const collected = [];
+    for (const id of ids) {
+      if (!seeds.has(id)) continue;
+      for (const p of nonInspectorWritePaths(nodeIO[id])) {
+        if (pathIsScopingSliceOutput(p)) collected.push(p);
+      }
+    }
+    if (collected.length === 0) {
+      for (const id of ids) {
+        for (const p of nonInspectorWritePaths(nodeIO[id])) {
+          if (pathIsScopingSliceOutput(p)) collected.push(p);
+        }
+      }
+    }
+
+    const primaryPaths = uniqueSorted(collected);
+    return {
+      columnTitle: 'Scoping outputs',
+      columnHint: 'Scoped and web-context paths produced in the scoping slice.',
+      cardTitle: 'Scoping outputs',
+      cardSubtitle: 'Slice boundary',
+      summary: '',
+      primaryPaths,
+      debugPaths: [],
+      canonicalFinalizerId: null,
+      emptyMessage: primaryPaths.length === 0 ? 'No scoping outputs in this focus (no matching writes yet).' : null,
+      showGraphResponseEditor: false,
+    };
+  }
+
+  if (focus === 'discovery') {
+    /** @type {Set<string>} */
+    const seeds = new Set();
+    for (const n of rawNodes) {
+      if (nodeIsDiscoverySeed(n, nodeIO[n.id])) seeds.add(n.id);
+    }
+
+    if (seeds.size === 0) {
+      return {
+        columnTitle: 'Discovery outputs',
+        columnHint: 'Narrix / webContext / synthesis paths from discovery-related nodes.',
+        cardTitle: 'Discovery outputs',
+        cardSubtitle: 'Slice boundary',
+        summary: '',
+        primaryPaths: [],
+        debugPaths: [],
+        canonicalFinalizerId: null,
+        emptyMessage: 'No discovery outputs in this view — add narrix metadata or discovery-related I/O.',
+        showGraphResponseEditor: false,
+      };
+    }
+
+    const ids = expandOneHop(seeds, ioLinks);
+    addDownstreamConsumers(ids, flowNodes);
+
+    /** @type {string[]} */
+    const collected = [];
+    for (const id of ids) {
+      for (const p of nonInspectorWritePaths(nodeIO[id])) {
+        if (pathIsDiscoveryRelated(p)) collected.push(p);
+      }
+    }
+
+    const primaryPaths = uniqueSorted(collected);
+    return {
+      columnTitle: 'Discovery outputs',
+      columnHint: 'Discovery-produced paths (web context, synthesis, narrix-related writes).',
+      cardTitle: 'Discovery outputs',
+      cardSubtitle: 'Slice boundary',
+      summary: '',
+      primaryPaths,
+      debugPaths: [],
+      canonicalFinalizerId: null,
+      emptyMessage: primaryPaths.length === 0 ? 'No discovery outputs in this view (no matching writes yet).' : null,
+      showGraphResponseEditor: false,
+    };
+  }
+
+  return buildInformationFlowOutputSurface(full, graph, graphAnalysis, { focus: 'graph' });
+}

package/src/ioLinking.js

@@ -0,0 +1,236 @@
+/**
+ * ioLinking — cross-node write-to-read path matching.
+ *
+ * After resolveNodeIO has been called for every node, this module
+ * builds the cross-reference map (IOLink[]), identifies dangling reads
+ * (reads with no upstream writer), and orphaned writes (writes no downstream
+ * node reads).
+ */
+
+/**
+ * Known graph-entry paths that are provided by ExecuteGraphOptions.execution.input.
+ * These are exempt from dangling-read warnings.
+ */
+const GRAPH_ENTRY_PREFIXES = [
+  'execution.input.raw',
+  'execution.input.entityId',
+  'execution.input.entityType',
+  'execution.input.vulnerabilityId',
+  'execution.input.metadata',
+];
+
+/**
+ * True when writePath satisfies readPath via prefix match.
+ * "execution.inference" satisfies "execution.inference.exploitability".
+ * "execution.inference.exploitability" also satisfies "execution.inference".
+ */
+function pathsMatch(writePath, readPath) {
+  if (writePath === readPath) return true;
+  // Wildcards: xmemory-op or external writes don't match internal reads
+  if (writePath.startsWith('xmemory-op:') || writePath.startsWith('xmemory-meta:')) return false;
+  if (writePath === 'finalOutput') return false;
+  // Wildcard read paths (e.g. jobMemory.*)
+  if (readPath.endsWith('.*')) {
+    const prefix = readPath.slice(0, -2);
+    return writePath === prefix || writePath.startsWith(prefix + '.');
+  }
+  // Prefix match in either direction
+  const wDot = writePath + '.';
+  const rDot = readPath + '.';
+  return readPath.startsWith(wDot) || writePath.startsWith(rDot);
+}
+
+function isGraphEntryPath(path) {
+  if (path.startsWith('execution.input.')) return true;
+  return GRAPH_ENTRY_PREFIXES.some(
+    (p) => path === p || path.startsWith(p + '.') || p.startsWith(path + '.')
+  );
+}
+
+/**
+ * Build a topological ordering of nodes from edges (best-effort; cycles are ignored).
+ * Returns an array of node IDs in execution order.
+ */
+function topoOrder(nodeIds, edges) {
+  const inDeg = new Map(nodeIds.map((id) => [id, 0]));
+  const adj = new Map(nodeIds.map((id) => [id, []]));
+  for (const e of edges) {
+    if (inDeg.has(e.to)) inDeg.set(e.to, inDeg.get(e.to) + 1);
+    if (adj.has(e.from)) adj.get(e.from).push(e.to);
+  }
+  const queue = nodeIds.filter((id) => inDeg.get(id) === 0);
+  const order = [];
+  const seen = new Set(queue);
+  while (queue.length) {
+    const n = queue.shift();
+    order.push(n);
+    for (const next of adj.get(n) || []) {
+      const d = inDeg.get(next) - 1;
+      inDeg.set(next, d);
+      if (d === 0 && !seen.has(next)) {
+        seen.add(next);
+        queue.push(next);
+      }
+    }
+  }
+  // Any nodes not reached (cycles) are appended
+  for (const id of nodeIds) {
+    if (!seen.has(id)) order.push(id);
+  }
+  return order;
+}
+
+/**
+ * Build IOLinks and identify dangling reads and orphaned writes.
+ *
+ * @param {Record<string, {layer: string, reads: object[], writes: object[]}>} nodeIOMap
+ * @param {Array<{from: string, to: string}>} edges
+ * @returns {{ ioLinks: object[], danglingReads: object[], orphanedWrites: object[] }}
+ */
+export function buildIOLinks(nodeIOMap, edges) {
+  const ioLinks = [];
+  const nodeIds = Object.keys(nodeIOMap);
+  const order = topoOrder(nodeIds, edges);
+
+  // Build a set of all reachable ancestors for each node (to restrict write-to-read to upstream only)
+  const ancestors = new Map();
+  for (const id of nodeIds) {
+    ancestors.set(id, new Set());
+  }
+  for (const id of order) {
+    const myAncestors = ancestors.get(id);
+    for (const e of edges) {
+      if (e.to === id) {
+        myAncestors.add(e.from);
+        // Propagate ancestors of e.from
+        for (const a of ancestors.get(e.from) || []) {
+          myAncestors.add(a);
+        }
+      }
+    }
+  }
+
+  // For each read on every node, find a write on an upstream node (or self for runtime phases)
+  const matchedReadKeys = new Set(); // "nodeId:readPath"
+  const matchedWriteKeys = new Set(); // "nodeId:writePath"
+
+  for (const readNodeId of nodeIds) {
+    const readIO = nodeIOMap[readNodeId];
+    const upstreamIds = ancestors.get(readNodeId);
+
+    for (const readEntry of readIO.reads) {
+      if (readEntry._inspectorOnly) continue;
+      const rPath = readEntry.path;
+
+      // Check self (runtime phase self-reads like PRE reading _narrix written by same node's narrix phase)
+      const selfIO = nodeIOMap[readNodeId];
+      for (const writeEntry of selfIO.writes) {
+        if (writeEntry._inspectorOnly) continue;
+        if (pathsMatch(writeEntry.path, rPath)) {
+          const link = {
+            writtenBy: readNodeId,
+            writePath: writeEntry.path,
+            readBy: readNodeId,
+            readPath: rPath,
+          };
+          ioLinks.push(link);
+          matchedReadKeys.add(`${readNodeId}:${rPath}`);
+          matchedWriteKeys.add(`${readNodeId}:${writeEntry.path}`);
+        }
+      }
+
+      // Check upstream nodes
+      for (const writeNodeId of upstreamIds) {
+        const writeIO = nodeIOMap[writeNodeId];
+        if (!writeIO) continue;
+        for (const writeEntry of writeIO.writes) {
+          if (writeEntry._inspectorOnly) continue;
+          if (pathsMatch(writeEntry.path, rPath)) {
+            const link = {
+              writtenBy: writeNodeId,
+              writePath: writeEntry.path,
+              readBy: readNodeId,
+              readPath: rPath,
+            };
+            ioLinks.push(link);
+            matchedReadKeys.add(`${readNodeId}:${rPath}`);
+            matchedWriteKeys.add(`${writeNodeId}:${writeEntry.path}`);
+          }
+        }
+      }
+    }
+  }
+
+  // Dangling reads: reads with no matched write and not a graph-entry path
+  const danglingReads = [];
+  for (const nodeId of nodeIds) {
+    const readIO = nodeIOMap[nodeId];
+    for (const readEntry of readIO.reads) {
+      if (readEntry._inspectorOnly) continue;
+      const rPath = readEntry.path;
+      const key = `${nodeId}:${rPath}`;
+      if (!matchedReadKeys.has(key) && !isGraphEntryPath(rPath)) {
+        danglingReads.push({ nodeId, path: rPath, tier: readEntry.tier, source: readEntry.source });
+      }
+    }
+  }
+
+  // Orphaned writes: writes that no downstream node reads, excluding finalOutput/_trace/xmemory-op
+  const orphanedWrites = [];
+  for (const nodeId of nodeIds) {
+    const writeIO = nodeIOMap[nodeId];
+    for (const writeEntry of writeIO.writes) {
+      if (writeEntry._inspectorOnly) continue;
+      const wPath = writeEntry.path;
+      if (
+        wPath === 'finalOutput' ||
+        wPath.startsWith('execution._trace') ||
+        wPath.startsWith('xmemory-op:') ||
+        wPath.startsWith('xmemory-meta:')
+      )
+        continue;
+      const key = `${nodeId}:${wPath}`;
+      if (!matchedWriteKeys.has(key)) {
+        orphanedWrites.push({
+          nodeId,
+          path: wPath,
+          tier: writeEntry.tier,
+          source: writeEntry.source,
+        });
+      }
+    }
+  }
+
+  return { ioLinks, danglingReads, orphanedWrites };
+}
+
+/**
+ * Get all IOLinks for a specific edge (from → to pair).
+ */
+export function ioLinksForEdge(ioLinks, fromNodeId, toNodeId) {
+  return ioLinks.filter(
+    (l) => l.writtenBy === fromNodeId && l.readBy === toNodeId
+  );
+}
+
+/**
+ * Get all upstream nodes (writers) for a given node's reads.
+ */
+export function upstreamWriters(ioLinks, nodeId) {
+  const ids = new Set();
+  for (const l of ioLinks) {
+    if (l.readBy === nodeId && l.writtenBy !== nodeId) ids.add(l.writtenBy);
+  }
+  return [...ids];
+}
+
+/**
+ * Get all downstream nodes (readers) for a given node's writes.
+ */
+export function downstreamReaders(ioLinks, nodeId) {
+  const ids = new Set();
+  for (const l of ioLinks) {
+    if (l.writtenBy === nodeId && l.readBy !== nodeId) ids.add(l.readBy);
+  }
+  return [...ids];
+}

package/src/lib/flatRuntimeInput.js

@@ -0,0 +1,38 @@
+/**
+ * Graph-engine ≥5.16: work-unit record on `runtime.input` with flat field names only.
+ * Legacy example/record shapes (`raw`, nested `input`) are normalized before simulate execute.
+ */
+
+/**
+ * @param {Record<string, unknown>} workUnit
+ * @returns {Record<string, unknown>}
+ */
+export function normalizeFlatRuntimeInput(workUnit) {
+  if (!workUnit || typeof workUnit !== 'object' || Array.isArray(workUnit)) return {};
+  /** @type {Record<string, unknown>} */
+  let out = { ...workUnit };
+
+  const innerInput = out.input;
+  if (innerInput != null && typeof innerInput === 'object' && !Array.isArray(innerInput)) {
+    const { input: _drop, ...rest } = out;
+    out = { .../** @type {Record<string, unknown>} */ (innerInput), ...rest };
+  }
+
+  if (Object.prototype.hasOwnProperty.call(out, 'raw')) {
+    const { raw, ...rest } = out;
+    if (raw != null && typeof raw === 'object' && !Array.isArray(raw)) {
+      out = { .../** @type {Record<string, unknown>} */ (raw), ...rest };
+    } else {
+      out = { ...rest };
+    }
+  }
+
+  return out;
+}
+
+/** @param {unknown} execution */
+export function runtimeInputsFromExecutionMemory(execution) {
+  if (!execution || typeof execution !== 'object' || Array.isArray(execution)) return undefined;
+  const ins = /** @type {Record<string, unknown>} */ (execution).inputs;
+  return Array.isArray(ins) && ins.length > 0 ? [...ins] : undefined;
+}