@exellix/graph-engine 6.0.0

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

@@ -0,0 +1,42 @@
+import type { Graph, GraphNode } from '../types/refs.js';
+import type { NodeScopingQuestion, NodeScopingData, NodeMemoryShape, NodeNarrixDiscovery, NodeInspection } from './types.js';
+/**
+ * Resolves the effective skillKey for a node. 5.x reads only the canonical `node.skillKey`.
+ * Returns undefined for finalizer nodes or task nodes that omit `skillKey`, so inspection stays non-throwing.
+ */
+export declare function resolveNodeSkillKey(node: GraphNode): string | undefined;
+/**
+ * Returns the scoping question, sources, and targets for a single node.
+ *
+ * All fields are derived statically from the node definition — no I/O.
+ */
+export declare function getNodeScopingQuestion(node: GraphNode): NodeScopingQuestion;
+/**
+ * Returns the conceptual execution-memory shape before and after a node runs.
+ *
+ * `upstreamWritePaths` should be the execution/output mapping paths of all upstream nodes.
+ * Pass `graph` when inspecting finalizers so question-driven item paths resolve the
+ * same way runtime resolves them.
+ */
+export declare function getNodeMemoryShape(node: GraphNode, upstreamWritePaths?: string[], graph?: Graph): NodeMemoryShape;
+/**
+ * Returns the Narrix discovery configuration for a node, or null if narrix
+ * is not configured on this node.
+ */
+export declare function getNodeNarrixDiscovery(node: GraphNode): NodeNarrixDiscovery | null;
+/**
+ * Fetches the actual x-scoped-data for the node's scoping question, given an entityId.
+ *
+ * Only meaningful for nodes with `skillKey: 'scoped-data-reader'`.
+ * For other nodes, `data` will be null and `error` will explain why.
+ */
+export declare function fetchNodeScopingData(node: GraphNode, entityId: string, options?: {
+    opDb?: string;
+}): Promise<NodeScopingData>;
+/**
+ * Full per-node inspection: scoping question, memory shape, and narrix discovery.
+ *
+ * For graph-level context (before.expects), use `inspectGraph` which computes
+ * upstream paths automatically.
+ */
+export declare function inspectNode(node: GraphNode, upstreamWritePaths?: string[], graph?: Graph): NodeInspection;

package/dist/src/inspection/nodeInspection.js

@@ -0,0 +1,474 @@
+import { mapAiTaskProfileQuestionsToWebScopeQuestions } from '../runtime/applyAiTaskProfileWebScopingToNarrix.js';
+import { readTaskNodeInputsConfig } from '../runtime/readTaskNodeInputsConfig.js';
+import { runScopedDataReader } from '../runtime/localSkills/scopedDataReader.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function isTaskNode(node) {
+    return node.type !== 'finalizer';
+}
+function isFinalizerNode(node) {
+    return node.type === 'finalizer';
+}
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function findGraphNodeById(graph, nodeId) {
+    return graph.nodes.find((n) => String(n.id) === String(nodeId));
+}
+function pushDedupedRead(reads, path, source, memory) {
+    if (typeof path !== 'string' || path.length === 0)
+        return;
+    const existing = reads.find((r) => r.path === path && r.memory === memory);
+    if (!existing) {
+        reads.push({ path, memory, source });
+        return;
+    }
+    if (!existing.source) {
+        existing.source = source;
+        return;
+    }
+    const sources = existing.source.split(', ').filter(Boolean);
+    if (!sources.includes(source)) {
+        existing.source = [...sources, source].join(', ');
+    }
+}
+function finalizerInputReads(node) {
+    const reads = [];
+    for (const [label, binding] of Object.entries((node.inputs ?? {}))) {
+        if (binding.type === 'executionMemoryPath' || binding.type === 'outputsMemoryPath') {
+            pushDedupedRead(reads, binding.path, `inputs.${label}`, binding.type === 'outputsMemoryPath' ? 'outputsMemory' : 'executionMemory');
+        }
+    }
+    return reads;
+}
+function finalizerRuntimeReadSources(node, graph) {
+    const reads = finalizerInputReads(node);
+    const cfg = node.config;
+    if (node.finalizerType !== 'aggregate' || !isPlainObject(cfg)) {
+        return reads;
+    }
+    if (cfg.strategy === 'report-schema' && isPlainObject(cfg.sections)) {
+        for (const [key, spec] of Object.entries(cfg.sections)) {
+            if (!isPlainObject(spec))
+                continue;
+            pushDedupedRead(reads, spec.path, `config.sections.${key}`, 'executionMemory');
+        }
+        return reads;
+    }
+    if (cfg.strategy === 'question-driven') {
+        if (isPlainObject(cfg.meta)) {
+            for (const [key, binding] of Object.entries(cfg.meta)) {
+                if (!isPlainObject(binding))
+                    continue;
+                pushDedupedRead(reads, binding.path, `config.meta.${key}`, binding.type === 'outputsMemoryPath' ? 'outputsMemory' : 'executionMemory');
+            }
+        }
+        if (isPlainObject(cfg.items)) {
+            for (const [key, spec] of Object.entries(cfg.items)) {
+                if (!isPlainObject(spec))
+                    continue;
+                if (typeof spec.answerPath === 'string' && spec.answerPath.length > 0) {
+                    pushDedupedRead(reads, spec.answerPath, `config.items.${key}.answerPath`, 'executionMemory');
+                    continue;
+                }
+                if (!graph)
+                    continue;
+                const nodeId = typeof spec.nodeId === 'string' ? spec.nodeId : undefined;
+                const referencedNode = nodeId ? findGraphNodeById(graph, nodeId) : undefined;
+                const fallbackPath = referencedNode?.executionMapping?.path;
+                pushDedupedRead(reads, fallbackPath, `config.items.${key}.node.executionMapping.path`, 'executionMemory');
+            }
+        }
+    }
+    return reads;
+}
+/**
+ * Resolves the effective skillKey for a node. 5.x reads only the canonical `node.skillKey`.
+ * Returns undefined for finalizer nodes or task nodes that omit `skillKey`, so inspection stays non-throwing.
+ */
+export function resolveNodeSkillKey(node) {
+    if (isFinalizerNode(node))
+        return undefined;
+    const n = node;
+    return typeof n.skillKey === 'string' ? n.skillKey : undefined;
+}
+/**
+ * Classifies a jobContextMapping / inputs value string reference into a source type.
+ * Handles prefixes: executionMemory.* | jobMemory.* | variables.* | input.* | node.* | output.*
+ */
+function classifyRefType(ref) {
+    if (ref.startsWith('jobMemory.'))
+        return 'jobMemory';
+    if (ref.startsWith('variables.'))
+        return 'variables';
+    // executionMemory.* is explicit; input.* and execution.* are shorthand execution memory paths
+    if (ref.startsWith('executionMemory.') ||
+        ref.startsWith('input.') ||
+        ref.startsWith('execution.') ||
+        ref.startsWith('node.') ||
+        ref.startsWith('output.')) {
+        return 'executionMemory';
+    }
+    return 'executionMemory';
+}
+/**
+ * Strip common prefixes to get the canonical dot-path used inside execution memory.
+ */
+function stripRefPrefix(ref) {
+    const prefixes = ['executionMemory.', 'jobMemory.', 'variables.'];
+    for (const p of prefixes) {
+        if (ref.startsWith(p))
+            return ref.slice(p.length);
+    }
+    return ref;
+}
+/**
+ * Extract sources from a node's jobContextMapping.
+ */
+function sourcesFromJobContextMapping(node) {
+    const mapping = node.jobContextMapping;
+    if (!mapping?.map)
+        return [];
+    return Object.entries(mapping.map).map(([label, ref]) => ({
+        type: classifyRefType(ref),
+        path: stripRefPrefix(ref),
+        label,
+    }));
+}
+/**
+ * Extract sources from runtime payload bindings (`inputsConfig`).
+ */
+function sourcesFromInputBindings(node) {
+    const recipe = readTaskNodeInputsConfig(node);
+    const sources = [];
+    for (const [key, val] of Object.entries(recipe)) {
+        if (val == null || typeof val === 'string')
+            continue;
+        if (typeof val === 'object') {
+            const v = val;
+            if (v.type === 'executionMemoryPath' && typeof v.path === 'string') {
+                sources.push({ type: 'executionMemory', path: v.path, label: key });
+                continue;
+            }
+            if (typeof v['$path'] === 'string') {
+                const raw = v['$path'];
+                if (raw.startsWith('variables.'))
+                    continue;
+                sources.push({ type: classifyRefType(raw), path: stripRefPrefix(raw), label: key });
+            }
+        }
+    }
+    return sources;
+}
+function variableRefsFromRecipe(recipe, labelPrefix) {
+    const sources = [];
+    for (const [key, val] of Object.entries(recipe)) {
+        if (val == null || typeof val !== 'object')
+            continue;
+        const raw = val['$path'];
+        if (typeof raw === 'string' && raw.startsWith('variables.')) {
+            sources.push({ type: 'variables', path: stripRefPrefix(raw), label: `${labelPrefix}.${key}` });
+        }
+    }
+    return sources;
+}
+/**
+ * Extract variable refs from `taskVariable` (and legacy `variables.*` refs still under `inputs`).
+ */
+function sourcesFromTaskVariable(node) {
+    const sources = [];
+    if (node.taskVariable && typeof node.taskVariable === 'object') {
+        sources.push(...variableRefsFromRecipe(node.taskVariable, 'taskVariable'));
+    }
+    sources.push(...variableRefsFromRecipe(readTaskNodeInputsConfig(node), 'inputsConfig'));
+    return sources;
+}
+/**
+ * Extract scoped-data source if the node uses the `scoped-data-reader` skill.
+ */
+function scopedDataSourceFromMetadata(node) {
+    const tc = node.taskConfiguration;
+    if (!tc)
+        return null;
+    const skillKey = resolveNodeSkillKey(node);
+    if (skillKey !== 'scoped-data-reader')
+        return null;
+    const { scopingMapId, entityIdPath, questionId, pack } = tc;
+    if (!scopingMapId && !questionId && !Array.isArray(pack))
+        return null;
+    const readability = node.metadata?.graphReadability;
+    return {
+        type: 'scopedData',
+        scopingMapId: typeof scopingMapId === 'string' ? scopingMapId : undefined,
+        entityIdPath: typeof entityIdPath === 'string' ? entityIdPath : undefined,
+        questionId: typeof questionId === 'string' ? questionId : undefined,
+        expectedKeys: Array.isArray(readability?.reads) ? readability.reads : undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Returns the scoping question, sources, and targets for a single node.
+ *
+ * All fields are derived statically from the node definition — no I/O.
+ */
+export function getNodeScopingQuestion(node) {
+    const nodeId = node.id;
+    if (isFinalizerNode(node)) {
+        // Finalizer: no question, inputs are memory bindings.
+        const sources = Object.entries((node.inputs ?? {})).map(([label, binding]) => {
+            if (binding.type === 'executionMemoryPath' || binding.type === 'outputsMemoryPath') {
+                return {
+                    type: binding.type === 'outputsMemoryPath' ? 'outputsMemory' : 'executionMemory',
+                    path: binding.path,
+                    label,
+                };
+            }
+            return { type: 'literal', label };
+        });
+        return {
+            nodeId,
+            name: undefined,
+            question: undefined,
+            kind: undefined,
+            sources,
+            targets: [],
+        };
+    }
+    const task = node;
+    const readability = task.metadata?.graphReadability;
+    const name = readability?.title;
+    const legacyInputsConfig = readTaskNodeInputsConfig(task);
+    const question = readability?.asks ??
+        (typeof task.taskVariable?.question === 'string' ? task.taskVariable.question : undefined) ??
+        (typeof legacyInputsConfig.question === 'string' ? legacyInputsConfig.question : undefined);
+    const kind = readability?.kind;
+    // Sources
+    const sources = [];
+    // 1. Scoped-data if applicable
+    const scopedSrc = scopedDataSourceFromMetadata(task);
+    if (scopedSrc) {
+        // Merge graphReadability.reads into expectedKeys if not already set
+        if (!scopedSrc.expectedKeys && Array.isArray(readability?.reads)) {
+            scopedSrc.expectedKeys = readability.reads;
+        }
+        sources.push(scopedSrc);
+    }
+    // 2. jobContextMapping map values
+    sources.push(...sourcesFromJobContextMapping(task));
+    // 3. input bindings + taskVariable variable refs
+    sources.push(...sourcesFromInputBindings(task));
+    sources.push(...sourcesFromTaskVariable(task));
+    // 4. smartInput.paths (graph-engine / ai-tasks 7.1+; legacy `paths: string[]` vs Rendrix-native SmartInputConfig)
+    const si = task.smartInput;
+    if (si && Array.isArray(si.paths)) {
+        for (const p of si.paths) {
+            if (typeof p === 'string' && p.length > 0) {
+                sources.push({ type: 'executionMemory', path: p, label: `smartInput:${p}` });
+            }
+        }
+    }
+    // 5. taskConfiguration.aiTaskProfile.inputSynthesis.sources when enabled
+    const isynth = task.taskConfiguration?.aiTaskProfile?.inputSynthesis;
+    if (isynth?.enabled && Array.isArray(isynth.sources)) {
+        for (const p of isynth.sources) {
+            if (typeof p === 'string' && p.length > 0) {
+                sources.push({ type: 'executionMemory', path: p, label: `inputSynthesis:${p}` });
+            }
+        }
+    }
+    // Targets
+    const targets = [];
+    if (task.executionMapping?.path) {
+        targets.push({
+            path: task.executionMapping.path,
+            memory: 'executionMemory',
+            mode: task.executionMapping.mode,
+            produces: Array.isArray(readability?.produces) ? readability.produces : undefined,
+        });
+    }
+    return { nodeId, name, question, kind, sources, targets };
+}
+/**
+ * Returns the conceptual execution-memory shape before and after a node runs.
+ *
+ * `upstreamWritePaths` should be the execution/output mapping paths of all upstream nodes.
+ * Pass `graph` when inspecting finalizers so question-driven item paths resolve the
+ * same way runtime resolves them.
+ */
+export function getNodeMemoryShape(node, upstreamWritePaths, graph) {
+    const nodeId = node.id;
+    if (isFinalizerNode(node)) {
+        const reads = finalizerRuntimeReadSources(node, graph);
+        const outputsMemoryWrites = [];
+        if (node.outputMapping?.path) {
+            outputsMemoryWrites.push({ path: node.outputMapping.path, memory: 'outputsMemory', source: 'outputMapping' });
+        }
+        return {
+            nodeId,
+            before: {
+                reads,
+                expects: (upstreamWritePaths ?? []).map((p) => ({ path: p })),
+            },
+            after: { writes: [], outputsMemoryWrites },
+        };
+    }
+    const task = node;
+    // before.reads — from jobContextMapping.map source values
+    const reads = [];
+    const mapping = task.jobContextMapping?.map;
+    if (mapping) {
+        for (const [label, ref] of Object.entries(mapping)) {
+            reads.push({ path: stripRefPrefix(ref), source: `jobContextMapping.map.${label}` });
+        }
+    }
+    const inputsConfig = readTaskNodeInputsConfig(task);
+    for (const [key, val] of Object.entries(inputsConfig)) {
+        if (!val || typeof val !== 'object')
+            continue;
+        const v = val;
+        if ((v.type === 'executionMemoryPath' || v.type === 'outputsMemoryPath') && typeof v.path === 'string') {
+            reads.push({
+                path: v.path,
+                memory: v.type === 'outputsMemoryPath' ? 'outputsMemory' : 'executionMemory',
+                source: `inputsConfig.${key}`,
+            });
+        }
+        else if (typeof v['$path'] === 'string') {
+            reads.push({ path: stripRefPrefix(v['$path']), source: `inputsConfig.${key}` });
+        }
+    }
+    // after.writes — from executionMapping
+    const writes = [];
+    if (task.executionMapping?.path) {
+        writes.push({ path: task.executionMapping.path, memory: 'executionMemory', source: 'executionMapping' });
+    }
+    return {
+        nodeId,
+        before: {
+            reads,
+            expects: (upstreamWritePaths ?? []).map((p) => ({ path: p })),
+        },
+        after: { writes, outputsMemoryWrites: [] },
+    };
+}
+/**
+ * Returns the Narrix discovery configuration for a node, or null if narrix
+ * is not configured on this node.
+ */
+export function getNodeNarrixDiscovery(node) {
+    if (isFinalizerNode(node))
+        return null;
+    const task = node;
+    const narrix = task.taskConfiguration?.narrix;
+    if (!narrix || typeof narrix !== 'object')
+        return null;
+    const n = narrix;
+    const web = task.taskConfiguration?.aiTaskProfile?.webScoping;
+    const enableWebScope = web?.enabled === true;
+    return {
+        nodeId: node.id,
+        enabled: true,
+        questionId: typeof n.questionId === 'string' ? n.questionId : undefined,
+        layer: typeof n.layer === 'string' ? n.layer : undefined,
+        narrativeTypeIds: Array.isArray(n.narrativeTypeIds) ? n.narrativeTypeIds : undefined,
+        webScope: {
+            enabled: enableWebScope,
+            forced: undefined,
+            questions: Array.isArray(web?.questions) && web.questions.length > 0
+                ? mapAiTaskProfileQuestionsToWebScopeQuestions(web.questions)
+                : undefined,
+            entityIdPath: undefined,
+            entityTypePath: undefined,
+            enrichFromRaw: undefined,
+        },
+        outputPaths: {
+            signals: 'executionMemory._narrix.scoping.signals',
+            stories: 'executionMemory._narrix.scoping.stories',
+        },
+    };
+}
+/**
+ * Fetches the actual x-scoped-data for the node's scoping question, given an entityId.
+ *
+ * Only meaningful for nodes with `skillKey: 'scoped-data-reader'`.
+ * For other nodes, `data` will be null and `error` will explain why.
+ */
+export async function fetchNodeScopingData(node, entityId, options) {
+    const base = getNodeScopingQuestion(node);
+    if (isFinalizerNode(node)) {
+        return { ...base, entityId, data: null, error: 'finalizer nodes do not read scoped data' };
+    }
+    const task = node;
+    const skillKey = resolveNodeSkillKey(task);
+    if (skillKey !== 'scoped-data-reader') {
+        return {
+            ...base,
+            entityId,
+            data: null,
+            error: `node skillKey is "${skillKey ?? 'unset'}" — only scoped-data-reader nodes fetch x-scoped-data`,
+        };
+    }
+    const tc = (task.taskConfiguration ?? {});
+    const entityIdPath = typeof tc.entityIdPath === 'string' ? tc.entityIdPath : '_entityId';
+    // Build a synthetic executionMemory so runScopedDataReader resolves the entityId
+    const syntheticMemory = {};
+    const parts = entityIdPath.split('.');
+    let cursor = syntheticMemory;
+    for (let i = 0; i < parts.length - 1; i++) {
+        cursor[parts[i]] = {};
+        cursor = cursor[parts[i]];
+    }
+    cursor[parts[parts.length - 1]] = entityId;
+    const cfg = {
+        scopingMapId: typeof tc.scopingMapId === 'string' ? tc.scopingMapId : undefined,
+        questionId: typeof tc.questionId === 'string' ? tc.questionId : undefined,
+        entityIdPath,
+        opDb: options?.opDb ?? (typeof tc.opDb === 'string' ? tc.opDb : undefined),
+        pack: Array.isArray(tc.pack) ? tc.pack : undefined,
+    };
+    try {
+        const data = await runScopedDataReader(cfg, syntheticMemory);
+        return { ...base, entityId, data };
+    }
+    catch (err) {
+        return {
+            ...base,
+            entityId,
+            data: null,
+            error: err?.message ?? String(err),
+        };
+    }
+}
+/**
+ * Full per-node inspection: scoping question, memory shape, and narrix discovery.
+ *
+ * For graph-level context (before.expects), use `inspectGraph` which computes
+ * upstream paths automatically.
+ */
+export function inspectNode(node, upstreamWritePaths, graph) {
+    const skillKey = resolveNodeSkillKey(node);
+    const readability = isTaskNode(node)
+        ? node.metadata?.graphReadability
+        : undefined;
+    let catalogBinding;
+    let catalogRequest;
+    if (isTaskNode(node)) {
+        const m = node.metadata;
+        catalogBinding = m?.catalogBinding;
+        catalogRequest = m?.catalogRequest;
+    }
+    return {
+        nodeId: node.id,
+        nodeType: node.type ?? 'task',
+        skillKey,
+        kind: readability?.kind,
+        scopingQuestion: getNodeScopingQuestion(node),
+        memoryShape: getNodeMemoryShape(node, upstreamWritePaths, graph),
+        narrixDiscovery: getNodeNarrixDiscovery(node),
+        catalogBinding,
+        catalogRequest,
+    };
+}