@exellix/graph-engine 6.0.0

package/dist/src/inspection/contractInspection.js

@@ -0,0 +1,526 @@
+import { isLocalSkillKey } from '../runtime/localSkills/index.js';
+import { readTaskNodeInputsConfig } from '../runtime/readTaskNodeInputsConfig.js';
+import { getNodeMemoryShape, getNodeNarrixDiscovery, inspectNode, resolveNodeSkillKey, } from './nodeInspection.js';
+import { getGraphNodes } from './graphInspection.js';
+import { getNodeControlDependencies } from './controlInspection.js';
+import { inspectGraph } from './graphInspection.js';
+import { assertCanonicalGraphDocument } from '../runtime/validateCanonicalGraphDocument.js';
+function isFinalizerNode(node) {
+    return node.type === 'finalizer';
+}
+function isTaskNode(node) {
+    return !isFinalizerNode(node);
+}
+function stripRefPrefix(ref) {
+    const prefixes = [
+        'executionMemory.',
+        'jobMemory.',
+        'variables.',
+        'taskMemory.',
+        'input.',
+        'xynthesized.job.',
+        'xynthesized.task.',
+    ];
+    for (const p of prefixes) {
+        if (ref.startsWith(p))
+            return ref.slice(p.length);
+    }
+    return ref;
+}
+function classifyMappingRef(ref) {
+    if (ref.startsWith('jobMemory.'))
+        return 'jobMemory';
+    if (ref.startsWith('variables.'))
+        return 'variables';
+    if (ref.startsWith('taskMemory.'))
+        return 'taskMemory';
+    if (ref.startsWith('executionMemory.') ||
+        ref.startsWith('input.') ||
+        ref.startsWith('execution.') ||
+        ref.startsWith('node.') ||
+        ref.startsWith('output.')) {
+        return 'executionMemory';
+    }
+    return 'other';
+}
+function deriveExecutionType(node) {
+    if (isFinalizerNode(node)) {
+        return { executionType: 'finalizer', localSkillKind: undefined, skillKey: undefined };
+    }
+    const skillKey = resolveNodeSkillKey(node);
+    if (!skillKey) {
+        return { executionType: undefined, localSkillKind: undefined, skillKey: undefined };
+    }
+    if (isLocalSkillKey(skillKey)) {
+        return {
+            executionType: 'local-skill',
+            localSkillKind: skillKey,
+            skillKey,
+        };
+    }
+    return { executionType: 'ai-task', localSkillKind: undefined, skillKey };
+}
+function buildInputsBindings(task) {
+    const inputs = readTaskNodeInputsConfig(task);
+    if (Object.keys(inputs).length === 0)
+        return [];
+    const out = [];
+    for (const [key, val] of Object.entries(inputs)) {
+        if (val == null) {
+            out.push({ key, kind: 'literal' });
+            continue;
+        }
+        if (typeof val === 'string') {
+            out.push({ key, kind: 'literal' });
+            continue;
+        }
+        if (typeof val === 'object') {
+            const v = val;
+            if (v.type === 'executionMemoryPath' && typeof v.path === 'string') {
+                out.push({ key, kind: 'executionMemoryPath', path: v.path });
+                continue;
+            }
+            if (typeof v['$path'] === 'string') {
+                const raw = v['$path'];
+                out.push({ key, kind: 'pathRef', path: stripRefPrefix(raw), rawRef: raw });
+                continue;
+            }
+            out.push({ key, kind: 'other' });
+            continue;
+        }
+        out.push({ key, kind: 'other' });
+    }
+    return out;
+}
+function partitionMappingRefs(map) {
+    const executionMemory = [];
+    const jobMemory = [];
+    const variables = [];
+    const taskMemory = [];
+    if (!map)
+        return { executionMemory, jobMemory, variables, taskMemory };
+    for (const [label, ref] of Object.entries(map)) {
+        const kind = classifyMappingRef(ref);
+        const path = stripRefPrefix(ref);
+        const mp = { path, source: `jobContextMapping.map.${label}` };
+        if (kind === 'jobMemory')
+            jobMemory.push(mp);
+        else if (kind === 'variables')
+            variables.push(mp);
+        else if (kind === 'taskMemory')
+            taskMemory.push(mp);
+        else
+            executionMemory.push(mp);
+    }
+    return { executionMemory, jobMemory, variables, taskMemory };
+}
+function mappingSourceReads(task, mappingKey) {
+    const mapping = task[mappingKey]?.map;
+    if (!mapping)
+        return [];
+    const reads = [];
+    for (const [targetKey, ref] of Object.entries(mapping)) {
+        const kind = classifyMappingRef(ref);
+        if (kind === 'executionMemory' || kind === 'jobMemory' || kind === 'variables' || kind === 'taskMemory') {
+            reads.push({
+                path: stripRefPrefix(ref),
+                source: `${mappingKey}.map.${targetKey}`,
+            });
+        }
+    }
+    return reads;
+}
+function inputsObjectReads(task) {
+    const reads = [];
+    const inputs = readTaskNodeInputsConfig(task);
+    for (const [key, val] of Object.entries(inputs)) {
+        if (!val || typeof val !== 'object')
+            continue;
+        const v = val;
+        if (v.type === 'executionMemoryPath' && typeof v.path === 'string') {
+            reads.push({ path: v.path, source: `inputsConfig.${key}` });
+        }
+        else if (typeof v['$path'] === 'string') {
+            reads.push({
+                path: stripRefPrefix(v['$path']),
+                source: `inputsConfig.${key}`,
+            });
+        }
+    }
+    return reads;
+}
+function scopedDataDeps(task) {
+    const tc = task.taskConfiguration;
+    if (!tc)
+        return [];
+    const sk = resolveNodeSkillKey(task);
+    if (sk !== 'scoped-data-reader')
+        return [];
+    const { scopingMapId, entityIdPath, questionId, pack } = tc;
+    if (!scopingMapId && !questionId && !Array.isArray(pack))
+        return [];
+    return [
+        {
+            scopingMapId: typeof scopingMapId === 'string' ? scopingMapId : undefined,
+            entityIdPath: typeof entityIdPath === 'string' ? entityIdPath : undefined,
+            questionId: typeof questionId === 'string' ? questionId : undefined,
+            pack: Array.isArray(pack) ? pack : undefined,
+        },
+    ];
+}
+function finalizerInputBindings(fn) {
+    const out = [];
+    for (const [key, binding] of Object.entries(fn.inputs ?? {})) {
+        if (binding.type === 'executionMemoryPath' || binding.type === 'outputsMemoryPath') {
+            out.push({
+                key,
+                kind: binding.type,
+                path: binding.path,
+            });
+        }
+        else if (binding.type === 'literal') {
+            out.push({ key, kind: 'literal' });
+        }
+        else {
+            out.push({ key, kind: 'other' });
+        }
+    }
+    return out;
+}
+function buildInputContract(node, memoryShape) {
+    if (isFinalizerNode(node)) {
+        const fn = node;
+        const reads = memoryShape.before.reads;
+        return {
+            inputsBindings: { items: finalizerInputBindings(fn), provenance: 'declared' },
+            executionMemoryReads: { items: reads, provenance: 'declared' },
+            jobContextReads: { items: [], provenance: 'declared' },
+            variableReads: { items: [], provenance: 'declared' },
+            taskMemoryReads: { items: [], provenance: 'declared' },
+            outputMappingReads: { items: [], provenance: 'declared' },
+            executionMappingReads: { items: [], provenance: 'declared' },
+            scopedDataDependencies: { items: [], provenance: 'declared' },
+            narrixDependencies: { items: [], provenance: 'declared' },
+            webScopeDependencies: { items: [], provenance: 'declared' },
+            upstreamExpectedWrites: {
+                items: memoryShape.before.expects,
+                provenance: 'derived',
+            },
+        };
+    }
+    const task = node;
+    const jm = partitionMappingRefs(task.jobContextMapping?.map);
+    const inputObjReads = inputsObjectReads(task);
+    const execReads = [...jm.executionMemory, ...inputObjReads];
+    const narrixDisc = getNodeNarrixDiscovery(node);
+    const webScopeItems = narrixDisc?.webScope.enabled && narrixDisc.enabled
+        ? [
+            {
+                enabled: true,
+                entityIdPath: narrixDisc.webScope.entityIdPath,
+                entityTypePath: narrixDisc.webScope.entityTypePath,
+                questions: narrixDisc.webScope.questions,
+            },
+        ]
+        : [];
+    return {
+        inputsBindings: { items: buildInputsBindings(task), provenance: 'declared' },
+        executionMemoryReads: { items: execReads, provenance: 'derived' },
+        jobContextReads: { items: jm.jobMemory, provenance: 'derived' },
+        variableReads: { items: jm.variables, provenance: 'derived' },
+        taskMemoryReads: { items: jm.taskMemory, provenance: 'derived' },
+        outputMappingReads: { items: [], provenance: 'declared' },
+        executionMappingReads: { items: mappingSourceReads(task, 'executionMapping'), provenance: 'declared' },
+        scopedDataDependencies: { items: scopedDataDeps(task), provenance: 'declared' },
+        narrixDependencies: {
+            items: narrixDisc ? [narrixDisc] : [],
+            provenance: narrixDisc ? 'declared' : 'declared',
+        },
+        webScopeDependencies: {
+            items: webScopeItems,
+            provenance: webScopeItems.length ? 'declared' : 'declared',
+        },
+        upstreamExpectedWrites: {
+            items: memoryShape.before.expects,
+            provenance: 'derived',
+        },
+    };
+}
+function buildOutputContract(node) {
+    if (isFinalizerNode(node)) {
+        const fn = node;
+        const desc = fn.finalizerType === 'synthesize'
+            ? 'Graph final output via synthesize utility (AI) + optional outputSchema validation'
+            : `Graph final output via ${fn.finalizerType} finalizer (deterministic assembly)`;
+        const outputsWrites = [];
+        if (fn.outputMapping?.path) {
+            outputsWrites.push({
+                path: fn.outputMapping.path,
+                mode: fn.outputMapping.mode,
+                source: 'outputMapping.path',
+            });
+        }
+        return {
+            executionMemoryWrites: { items: [], provenance: 'declared' },
+            outputsMemoryWrites: { items: outputsWrites, provenance: 'declared' },
+            storageReads: { items: [], provenance: 'runtime-known' },
+            storageWrites: { items: [], provenance: 'runtime-known' },
+            webContextWrites: { items: [], provenance: 'runtime-known' },
+            narrixWrites: { items: [], provenance: 'runtime-known' },
+            synthesizedContextWrites: { items: [], provenance: 'runtime-known' },
+            finalOutputWrites: { items: [{ description: desc }], provenance: 'declared' },
+            produces: { items: [], provenance: 'declared' },
+            routingOutputs: { items: [], provenance: 'declared' },
+        };
+    }
+    const task = node;
+    const readability = task.metadata?.graphReadability;
+    const produces = Array.isArray(readability?.produces) ? readability.produces : [];
+    const routingOutputs = readability?.kind === 'routing' ? produces : [];
+    const execWrites = [];
+    if (task.executionMapping?.path) {
+        execWrites.push({
+            path: task.executionMapping.path,
+            mode: task.executionMapping.mode,
+            source: 'executionMapping.path',
+        });
+    }
+    const narrixDisc = getNodeNarrixDiscovery(node);
+    const narrixWrites = [];
+    if (narrixDisc?.enabled) {
+        narrixWrites.push({ path: '_narrix.scoping.signals', source: 'narrix (runtime-known)' }, { path: '_narrix.scoping.stories', source: 'narrix (runtime-known)' });
+    }
+    const tc = task.taskConfiguration;
+    const webCfg = tc?.aiTaskProfile;
+    const webScoping = webCfg?.webScoping;
+    const webWrites = [];
+    if (webScoping && webScoping.enabled === true) {
+        webWrites.push({ path: 'webContext', source: 'taskConfiguration.aiTaskProfile.webScoping → executeNode (runtime-known)' });
+    }
+    const synthWrites = [];
+    const inputSynth = webCfg?.inputSynthesis;
+    if (inputSynth?.enabled === true) {
+        synthWrites.push({
+            path: 'synthesizedContext',
+            source: 'taskConfiguration.aiTaskProfile.inputSynthesis PRE (runtime-known)',
+        });
+    }
+    const sk = resolveNodeSkillKey(task);
+    const storageReads = [];
+    const storageWrites = [];
+    if (sk === 'scoped-data-reader') {
+        storageReads.push({ note: 'Reads Memorix entity item via scoped-data-reader (fetchMemorixItem)' });
+    }
+    if (sk === 'scoped-answer-writer') {
+        storageWrites.push({ note: 'Persists inferences/decisions content types via scoped-answer-writer (writeMemorixRecord)' });
+    }
+    if (sk === 'scoped-answer-assembler') {
+        storageWrites.push({
+            note: 'Prepares persistence payload (typically consumed by scoped-answer-writer)',
+        });
+    }
+    return {
+        executionMemoryWrites: { items: execWrites, provenance: 'declared' },
+        outputsMemoryWrites: { items: [], provenance: 'declared' },
+        storageReads: { items: storageReads, provenance: 'runtime-known' },
+        storageWrites: { items: storageWrites, provenance: 'runtime-known' },
+        webContextWrites: { items: webWrites, provenance: 'runtime-known' },
+        narrixWrites: { items: narrixWrites, provenance: 'runtime-known' },
+        synthesizedContextWrites: { items: synthWrites, provenance: 'runtime-known' },
+        finalOutputWrites: { items: [], provenance: 'declared' },
+        produces: { items: produces, provenance: 'declared' },
+        routingOutputs: { items: routingOutputs, provenance: 'declared' },
+    };
+}
+export function getNodeSideEffects(node) {
+    const { executionType, localSkillKind, skillKey } = deriveExecutionType(node);
+    const notes = [];
+    const readsScopedStorage = localSkillKind === 'scoped-data-reader';
+    const writesScopedStorage = localSkillKind === 'scoped-answer-writer' || localSkillKind === 'scoped-answer-assembler';
+    let callsAiTasks = executionType === 'ai-task';
+    let runsNarrix = false;
+    let runsLocalWebScope = false;
+    let runsPreSynthesis = false;
+    let producesFinalOutput = executionType === 'finalizer';
+    if (isTaskNode(node)) {
+        const tc = node.taskConfiguration;
+        runsNarrix = tc?.narrix != null && typeof tc.narrix === 'object';
+        const web = tc?.aiTaskProfile;
+        const ws = web?.webScoping;
+        runsLocalWebScope = ws?.enabled === true;
+        const inputSynth = web?.inputSynthesis;
+        runsPreSynthesis = inputSynth?.enabled === true;
+    }
+    if (isFinalizerNode(node) && node.finalizerType === 'synthesize') {
+        callsAiTasks = true;
+        notes.push('Synthesize finalizer invokes ai-tasks utility (runtime-known).');
+    }
+    if (executionType === undefined && skillKey === undefined) {
+        notes.push('No skillKey resolved; execution class unknown until graph validation.');
+    }
+    return {
+        readsScopedStorage,
+        writesScopedStorage,
+        callsAiTasks,
+        runsNarrix,
+        runsLocalWebScope,
+        runsPreSynthesis,
+        producesFinalOutput,
+        notes: notes.length ? notes : undefined,
+        provenance: 'derived',
+    };
+}
+function getNodeById(graph, id) {
+    return getGraphNodes(graph).find((n) => n.id === id);
+}
+function answerPathForQuestionDriven(graph, spec, itemKey) {
+    if (spec.answerPath) {
+        return { path: spec.answerPath, source: `config.items.${itemKey}.answerPath` };
+    }
+    if (!graph)
+        return undefined;
+    const n = getNodeById(graph, spec.nodeId);
+    if (!n || isFinalizerNode(n))
+        return undefined;
+    const path = n.executionMapping?.path;
+    return path ? { path, source: `config.items.${itemKey}.node.executionMapping.path` } : undefined;
+}
+/**
+ * Finalizer-only contract inspection. Returns null if the node is not a finalizer.
+ */
+export function inspectFinalizer(node, options) {
+    if (!isFinalizerNode(node))
+        return null;
+    const fn = node;
+    const graph = options?.graph;
+    const reads = [];
+    const metaReads = [];
+    for (const [name, binding] of Object.entries(fn.inputs ?? {})) {
+        if ((binding.type === 'executionMemoryPath' || binding.type === 'outputsMemoryPath') && binding.path) {
+            reads.push({ path: binding.path, source: `inputs.${name}` });
+        }
+    }
+    const cfg = fn.config;
+    if (cfg?.strategy === 'report-schema') {
+        const sections = cfg.sections;
+        if (sections) {
+            for (const [k, spec] of Object.entries(sections)) {
+                if (spec?.path) {
+                    reads.push({ path: spec.path, source: `config.sections.${k}` });
+                }
+            }
+        }
+    }
+    if (cfg?.strategy === 'question-driven') {
+        const items = cfg.items;
+        if (items) {
+            for (const [k, spec] of Object.entries(items)) {
+                const answerPath = answerPathForQuestionDriven(graph, spec, k);
+                if (answerPath) {
+                    reads.push(answerPath);
+                }
+            }
+        }
+        const meta = cfg.meta;
+        if (meta) {
+            for (const [k, b] of Object.entries(meta)) {
+                if ((b?.type === 'executionMemoryPath' || b?.type === 'outputsMemoryPath') && b.path) {
+                    metaReads.push({ path: b.path, source: `config.meta.${k}` });
+                }
+            }
+        }
+    }
+    const callsAiTasks = fn.finalizerType === 'synthesize';
+    const synthesizeUtilityKey = callsAiTasks && cfg && typeof cfg.utilityKey === 'string'
+        ? cfg.utilityKey
+        : undefined;
+    return {
+        nodeId: fn.id,
+        finalizerType: fn.finalizerType,
+        inputs: { ...fn.inputs },
+        config: fn.config,
+        outputSchema: fn.outputSchema,
+        executionMemoryReads: { items: reads, provenance: 'declared' },
+        metaExecutionMemoryReads: { items: metaReads, provenance: 'derived' },
+        callsAiTasks,
+        synthesizeUtilityKey,
+    };
+}
+function buildValidationContract(node) {
+    if (isFinalizerNode(node)) {
+        const fn = node;
+        return {
+            outputValidation: { items: null, provenance: 'declared' },
+            outputSchema: {
+                items: fn.outputSchema ?? null,
+                provenance: 'declared',
+            },
+            validatedBeforeMapping: { items: false, provenance: 'runtime-known' },
+            metadataConstraints: { items: {}, provenance: 'declared' },
+        };
+    }
+    const task = node;
+    const ov = task.outputValidation ?? null;
+    return {
+        outputValidation: { items: ov, provenance: 'declared' },
+        outputSchema: { items: null, provenance: 'declared' },
+        validatedBeforeMapping: {
+            items: Boolean(ov?.rules && ov.rules.length > 0),
+            provenance: 'runtime-known',
+        },
+        metadataConstraints: { items: {}, provenance: 'declared' },
+    };
+}
+/**
+ * Unified per-node contract: execution class, grouped I/O, side effects, validation, optional control graph.
+ */
+export function inspectNodeContract(node, options) {
+    const upstream = options?.upstreamWritePaths;
+    const graph = options?.graph;
+    const base = inspectNode(node, upstream, graph);
+    const memoryShape = getNodeMemoryShape(node, upstream, graph);
+    const { executionType, localSkillKind, skillKey } = deriveExecutionType(node);
+    const inputs = buildInputContract(node, memoryShape);
+    const outputs = buildOutputContract(node);
+    const sideEffects = getNodeSideEffects(node);
+    const validation = buildValidationContract(node);
+    const control = graph != null ? getNodeControlDependencies(graph, node.id) : null;
+    const finalizerDetail = inspectFinalizer(node, { graph });
+    return {
+        nodeId: node.id,
+        executionType,
+        localSkillKind,
+        skillKey,
+        nodeType: node.type ?? 'task',
+        base,
+        inputs,
+        outputs,
+        sideEffects,
+        control,
+        validation,
+        finalizerDetail,
+    };
+}
+/**
+ * Graph-level contract view: full node contracts plus execution order and I/O edges.
+ */
+export function inspectGraphContracts(graph) {
+    assertCanonicalGraphDocument(graph, { graphId: graph?.id });
+    const gi = inspectGraph(graph);
+    const nodes = {};
+    for (const id of Object.keys(gi.nodes)) {
+        const n = getGraphNodes(graph).find((x) => x.id === id);
+        if (!n)
+            continue;
+        const upstream = gi.nodes[id].memoryShape.before.expects.map((e) => e.path);
+        nodes[id] = inspectNodeContract(n, { upstreamWritePaths: upstream, graph });
+    }
+    return {
+        graphId: gi.graphId,
+        executionOrder: gi.executionOrder,
+        nodes,
+        edges: gi.edges,
+        ioEdges: gi.ioEdges,
+        virtualIO: gi.virtualIO,
+    };
+}

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

@@ -0,0 +1,137 @@
+import type { GraphEdge, GraphPredicate, OutputSchema, TaskOutputValidation } from '../types/refs.js';
+import type { LocalSkillKey } from '../runtime/localSkills/index.js';
+import type { MemoryPath, NodeInspection, NodeNarrixDiscovery } from './types.js';
+export type { LocalSkillKey };
+/** Normalized runtime operation class for a node (derived from graph + known intercepts). */
+export type NodeExecutionType = 'ai-task' | 'local-skill' | 'finalizer';
+export type FactProvenance = 'declared' | 'derived' | 'runtime-known';
+export type ProvenancedSection<T> = {
+    items: T;
+    provenance: FactProvenance;
+};
+/** Single binding from `inputs` (declarative). */
+export type NodeInputBindingEntry = {
+    key: string;
+    kind: 'literal' | 'executionMemoryPath' | 'outputsMemoryPath' | 'pathRef' | 'other';
+    /** Execution-memory-relative path when applicable. */
+    path?: string;
+    /** Original $path / mapping string when applicable. */
+    rawRef?: string;
+};
+export type ScopedDataDependency = {
+    scopingMapId?: string;
+    entityIdPath?: string;
+    questionId?: string;
+    pack?: unknown[];
+};
+export type NodeInputContract = {
+    inputsBindings: ProvenancedSection<NodeInputBindingEntry[]>;
+    executionMemoryReads: ProvenancedSection<MemoryPath[]>;
+    jobContextReads: ProvenancedSection<MemoryPath[]>;
+    variableReads: ProvenancedSection<MemoryPath[]>;
+    taskMemoryReads: ProvenancedSection<MemoryPath[]>;
+    outputMappingReads: ProvenancedSection<MemoryPath[]>;
+    executionMappingReads: ProvenancedSection<MemoryPath[]>;
+    scopedDataDependencies: ProvenancedSection<ScopedDataDependency[]>;
+    /** Empty when narrix is not configured on the node. */
+    narrixDependencies: ProvenancedSection<NodeNarrixDiscovery[]>;
+    /** Empty when narrix web scope is off or narrix absent. */
+    webScopeDependencies: ProvenancedSection<{
+        enabled: boolean;
+        entityIdPath?: string;
+        entityTypePath?: string;
+        questions?: unknown;
+    }[]>;
+    upstreamExpectedWrites: ProvenancedSection<MemoryPath[]>;
+};
+export type ExecutionMemoryWriteSpec = {
+    path: string;
+    mode?: string;
+    source?: string;
+};
+export type NodeOutputContract = {
+    executionMemoryWrites: ProvenancedSection<ExecutionMemoryWriteSpec[]>;
+    outputsMemoryWrites: ProvenancedSection<ExecutionMemoryWriteSpec[]>;
+    storageReads: ProvenancedSection<{
+        note?: string;
+    }[]>;
+    storageWrites: ProvenancedSection<{
+        note?: string;
+    }[]>;
+    webContextWrites: ProvenancedSection<ExecutionMemoryWriteSpec[]>;
+    narrixWrites: ProvenancedSection<ExecutionMemoryWriteSpec[]>;
+    synthesizedContextWrites: ProvenancedSection<ExecutionMemoryWriteSpec[]>;
+    finalOutputWrites: ProvenancedSection<{
+        description: string;
+    }[]>;
+    produces: ProvenancedSection<string[]>;
+    routingOutputs: ProvenancedSection<string[]>;
+};
+export type NodeSideEffects = {
+    readsScopedStorage: boolean;
+    writesScopedStorage: boolean;
+    callsAiTasks: boolean;
+    runsNarrix: boolean;
+    runsLocalWebScope: boolean;
+    runsPreSynthesis: boolean;
+    producesFinalOutput: boolean;
+    /** Human-readable notes where classification mixes declared and runtime-known. */
+    notes?: string[];
+    provenance: FactProvenance;
+};
+export type ControlBranchEntry = {
+    to: string;
+    from: string;
+    when?: GraphPredicate;
+    matchedExecutionMemoryPaths: string[];
+};
+export type NodeControlContract = {
+    isRoutingNode: boolean;
+    routingHintFromReadability: boolean;
+    edgesConditionalOnThisWriter: ControlBranchEntry[];
+    /** All predicate leaf paths from edges gated by this node's writes (executionMemory roots). */
+    predicatePathsThatMatchedWrites: string[];
+    downstreamBranchMap: ControlBranchEntry[];
+    provenance: FactProvenance;
+};
+export type NodeValidationContract = {
+    outputValidation: ProvenancedSection<TaskOutputValidation | null>;
+    outputSchema: ProvenancedSection<OutputSchema | null>;
+    /** Exellix runs outputValidation before executionMapping when rules are present (executeNode). */
+    validatedBeforeMapping: ProvenancedSection<boolean>;
+    metadataConstraints: ProvenancedSection<Record<string, unknown>>;
+};
+export type FinalizerContractInspection = {
+    nodeId: string;
+    finalizerType: string;
+    inputs: Record<string, unknown>;
+    config: unknown;
+    outputSchema: OutputSchema | undefined;
+    executionMemoryReads: ProvenancedSection<MemoryPath[]>;
+    metaExecutionMemoryReads: ProvenancedSection<MemoryPath[]>;
+    callsAiTasks: boolean;
+    synthesizeUtilityKey?: string;
+};
+export type NodeContractInspection = {
+    nodeId: string;
+    executionType: NodeExecutionType | undefined;
+    localSkillKind: LocalSkillKey | undefined;
+    skillKey: string | undefined;
+    nodeType: string;
+    base: NodeInspection;
+    inputs: NodeInputContract;
+    outputs: NodeOutputContract;
+    sideEffects: NodeSideEffects;
+    control: NodeControlContract | null;
+    validation: NodeValidationContract;
+    finalizerDetail: FinalizerContractInspection | null;
+};
+export type GraphContractsInspection = {
+    graphId: string;
+    executionOrder: string[];
+    nodes: Record<string, NodeContractInspection>;
+    edges: GraphEdge[];
+    ioEdges: import('./types.js').NodeIOEdge[];
+    /** Same virtual Layer 01/08 boundaries as `inspectGraph` (not executable DAG nodes). */
+    virtualIO: import('./types.js').GraphVirtualIO;
+};

package/dist/src/inspection/contractTypes.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,22 @@
+import type { Graph, GraphNode, GraphPredicate } from '../types/refs.js';
+import type { NodeControlContract } from './contractTypes.js';
+/**
+ * Recursively collects leaf `path` strings from a graph edge predicate.
+ */
+export declare function collectPredicatePaths(predicate: GraphPredicate | undefined): string[];
+/** Execution-memory dot-tail (no `executionMemory.` prefix). */
+export declare function executionMemoryPathTail(fullPath: string): string | null;
+/**
+ * Same prefix semantics as io edge intersection: exact or parent/child path match.
+ */
+export declare function executionMemoryTailsMatch(a: string, b: string): boolean;
+/**
+ * All execution-memory write tails this node contributes (for control-flow matching).
+ * Includes executionMapping, narrix slots, webContext, synthesizedContext when applicable.
+ */
+export declare function getNodeExecutionMemoryWriteTails(node: GraphNode): string[];
+/**
+ * Lists edges whose `when` predicates read execution-memory paths produced by `nodeId`,
+ * and routing hints from graphReadability.
+ */
+export declare function getNodeControlDependencies(graph: Graph, nodeId: string): NodeControlContract;