@exellix/graph-engine 6.0.0

package/dist/src/runtime/taskNodeRunTaskPreflight.js

@@ -0,0 +1,204 @@
+import { analyzeRunTaskRequest, validateRunTaskConfig, validateRunTaskInvoke, } from '@exellix/ai-tasks';
+import { resolveTaskKey } from './resolveTaskKey.js';
+import { isLocalSkillKey } from './localSkills/index.js';
+import { buildAiTasksRunTaskRequest, extractRunTaskStrategyOverrides, } from './buildAiTasksRunTaskRequest.js';
+import { resolveExecutionPipelineForTaskNode } from './resolveExecutionPipelineForTaskNode.js';
+import { resolveTaskNodeInputsForRunTask } from './resolveTaskNodeInputs.js';
+import { assertAiTasksNodeExtensionsValid } from '../inspection/validateAiTasksNodeExtensions.js';
+import { buildRunTaskMainInput, extractCallerInputsBag } from './resolveGraphEngineMemoryPaths.js';
+import { mirrorRuntimeInputRawOnExecutionMemory, mirrorStructuredInputOntoExecutionMemory, } from './materializeStructuredRunTaskInput.js';
+import { xynthesizedOutboundForNode } from './graphRunExecutionSeed.js';
+import { buildTaskNodeJobContext } from './buildTaskNodeJobContext.js';
+import { resolveNarrixForTaskNode } from './resolveNarrixForTaskNode.js';
+import { normalizeSynthesizedContextConfig } from './synthesizedContextPipeline.js';
+import { buildRunTaskIdentityEnvelope, mergeDefinedLlmCallParts, shouldForwardRunTaskTraceMode, } from './runTaskAugments.js';
+import { mirrorTaskVariablesOnExecution, readExecutionVariableBuckets, } from './executionVariableBuckets.js';
+import { newGraphRunTaskId } from './graphRunIdentity.js';
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function mergeKnowledgePatchIntoRunTaskMemory(memory, patch) {
+    if (patch == null)
+        return memory;
+    const base = isPlainRecord(memory) ? { ...memory } : {};
+    const existingKnowledge = isPlainRecord(base.knowledge) ? base.knowledge : {};
+    return {
+        ...base,
+        knowledge: {
+            ...existingKnowledge,
+            ...patch,
+        },
+    };
+}
+/**
+ * Materialize the outbound `RunTaskRequest` graph-engine would send for a task node
+ * (mirrors `executeNode` request assembly; does not run PRE strategy phases or `runTask`).
+ */
+export function buildTaskNodeRunTaskRequest(args) {
+    const node = args.node;
+    if (node.type === 'finalizer') {
+        return { runnable: false, skillKey: 'finalizer', reason: 'finalizer' };
+    }
+    const runTaskJobIdStr = String(args.runTaskJobId ?? args.job?.jobId ?? args.job?.id ?? '');
+    const lifecycleJobId = runTaskJobIdStr || 'standalone-job';
+    const graphRunTaskId = args.graphRunTaskId ?? newGraphRunTaskId();
+    const skillKey = resolveTaskKey(node, args.skillKeyResolution ?? {}, {
+        jobId: runTaskJobIdStr || undefined,
+        graphId: args.graphId,
+    });
+    if (isLocalSkillKey(skillKey)) {
+        return { runnable: false, skillKey, reason: 'local_skill' };
+    }
+    assertAiTasksNodeExtensionsValid(node, `nodes.${String(node.id)}`);
+    let execution = args.execution != null && typeof args.execution === 'object' && !Array.isArray(args.execution)
+        ? { ...args.execution }
+        : {};
+    mirrorTaskVariablesOnExecution({
+        execution,
+        node: node,
+        runtimeTaskVariables: args.taskVariables,
+    });
+    const executionPipeline = resolveExecutionPipelineForTaskNode({
+        node,
+        optionsExecutionPipeline: args.graphExecutionPipeline,
+        executionExecutionPipeline: execution.executionPipeline,
+    });
+    const hasSynthesizedContextPreStep = Array.isArray(executionPipeline) &&
+        executionPipeline.some((s) => s.phase === 'pre' && s.type === 'synthesized-context');
+    const preStepConfig = hasSynthesizedContextPreStep && Array.isArray(executionPipeline)
+        ? normalizeSynthesizedContextConfig(executionPipeline.find((s) => s.phase === 'pre' && s.type === 'synthesized-context')?.config)
+        : undefined;
+    const includeContextInPrompt = hasSynthesizedContextPreStep && preStepConfig?.autoEnableContext !== true;
+    const variableBuckets = readExecutionVariableBuckets(execution);
+    const jobVariables = variableBuckets.jobVariables;
+    const hasExistingSynthesizedContext = execution.synthesizedContext != null;
+    const clearSynthForTask = args.clearSynthesizedContextPerNode === true &&
+        hasSynthesizedContextPreStep &&
+        hasExistingSynthesizedContext;
+    mirrorRuntimeInputRawOnExecutionMemory(execution);
+    const nodeBindings = resolveTaskNodeInputsForRunTask({ node, execution });
+    const jobContext = buildTaskNodeJobContext({
+        node,
+        jobMemory: args.jobMemory,
+        executionMemory: execution,
+        variables: jobVariables,
+    });
+    const narrix = resolveNarrixForTaskNode({
+        nodeMetadataNarrix: node.taskConfiguration?.narrix != null
+            ? { ...node.taskConfiguration.narrix }
+            : undefined,
+        graphVariablesNarrix: jobVariables?.narrix,
+        aiTaskProfile: node.taskConfiguration?.aiTaskProfile,
+    });
+    const metaTk = node.taskConfiguration?.taskKind;
+    const taskKindForward = metaTk === 'decision' || metaTk === 'utility' || metaTk === 'content' ? metaTk : undefined;
+    const autoValDec = node.taskConfiguration?.autoValidateDecisionOutput;
+    const executionForTask = clearSynthForTask
+        ? (() => {
+            const c = { ...execution };
+            delete c.synthesizedContext;
+            return c;
+        })()
+        : execution;
+    const callerInputs = extractCallerInputsBag({
+        execution,
+        jobMemory: isPlainRecord(args.jobMemory) ? args.jobMemory : undefined,
+    });
+    const taskInput = buildRunTaskMainInput({
+        execution,
+        jobMemory: isPlainRecord(args.jobMemory) ? args.jobMemory : undefined,
+        nodeBindings: {
+            ...nodeBindings,
+            ...(node.data?.upstreamNodeIds !== undefined ? { upstreamNodeIds: node.data.upstreamNodeIds } : {}),
+        },
+    });
+    mirrorStructuredInputOntoExecutionMemory(executionForTask, taskInput);
+    const runTaskJobMemory = mergeKnowledgePatchIntoRunTaskMemory(args.jobMemory, args.jobKnowledgePatch);
+    const runTaskTaskMemory = mergeKnowledgePatchIntoRunTaskMemory(args.taskMemory, args.taskKnowledgePatch);
+    const effectiveLlmCall = mergeDefinedLlmCallParts(args.runtimeLlmCall, args.llmCall, node.taskConfiguration?.llmCall);
+    const forwardRunTaskTrace = shouldForwardRunTaskTraceMode({
+        runTaskExecutionMode: args.runTaskExecutionMode,
+    });
+    const metaStrats = node.taskConfiguration?.executionStrategies;
+    const ov = node.taskConfiguration?.aiTasksOutputValidation;
+    const request = buildAiTasksRunTaskRequest({
+        skillKey,
+        job: args.job,
+        nodeId: String(node.id),
+        taskConfiguration: node.taskConfiguration,
+        graphId: args.graphId,
+        taskId: graphRunTaskId,
+        runTaskJobId: lifecycleJobId,
+        taskInput,
+        callerInputs,
+        variables: jobVariables,
+        jobMemory: runTaskJobMemory,
+        taskMemory: runTaskTaskMemory,
+        executionMemory: executionForTask,
+        jobContext,
+        prevNodeId: args.prevNodeId,
+        executionPipeline: executionPipeline,
+        includeContextInPrompt: includeContextInPrompt === true ? true : undefined,
+        narrix: narrix ?? undefined,
+        ...extractRunTaskStrategyOverrides(node.taskConfiguration),
+        outputValidation: ov != null && typeof ov === 'object' && !Array.isArray(ov) && 'schema' in ov
+            ? ov
+            : undefined,
+        diagnostics: args.runTaskDiagnostics,
+        modelConfig: args.modelConfig ?? undefined,
+        llmCall: effectiveLlmCall,
+        identity: buildRunTaskIdentityEnvelope({
+            base: args.runTaskIdentity,
+            nodeMeta: node.taskConfiguration,
+            graphId: args.graphId,
+            nodeId: String(node.id),
+            taskId: graphRunTaskId,
+            jobId: lifecycleJobId,
+        }),
+        executionMode: forwardRunTaskTrace ? 'trace' : undefined,
+        taskKind: taskKindForward,
+        autoValidateDecisionOutput: typeof autoValDec === 'boolean' ? autoValDec : undefined,
+        executionStrategies: Array.isArray(metaStrats) ? metaStrats : [],
+        xynthesized: xynthesizedOutboundForNode(execution, String(node.id)),
+        smartInput: node.smartInput,
+    });
+    return { runnable: true, skillKey, request };
+}
+/** Static ai-tasks validation on the graph-built {@link RunTaskRequest}. */
+export function validateTaskNodeRunTaskConfig(args) {
+    const built = buildTaskNodeRunTaskRequest(args);
+    if (!built.runnable) {
+        return { skipped: true, skillKey: built.skillKey, reason: built.reason };
+    }
+    const validation = validateRunTaskConfig(built.request);
+    return { skipped: false, skillKey: built.skillKey, request: built.request, ...validation };
+}
+/** Config + payload + template path validation via ai-tasks {@link validateRunTaskInvoke}. */
+export async function validateTaskNodeRunTaskInvoke(args) {
+    const built = buildTaskNodeRunTaskRequest(args);
+    if (!built.runnable) {
+        return { skipped: true, skillKey: built.skillKey, reason: built.reason };
+    }
+    const invokeParams = {
+        analyzeTemplates: args.analyzeTemplates,
+        templateResolver: args.templateResolver,
+        instructions: args.instructions,
+        prompt: args.prompt,
+        checkTemplateResolution: args.checkTemplateResolution,
+        checkSmartInputRender: args.checkSmartInputRender,
+    };
+    const validation = await validateRunTaskInvoke({
+        request: built.request,
+        ...invokeParams,
+    });
+    return { skipped: false, skillKey: built.skillKey, request: built.request, ...validation };
+}
+/** Catalox-backed skill request analysis on the graph-built {@link RunTaskRequest}. */
+export async function analyzeTaskNodeRunTaskRequest(args) {
+    const built = buildTaskNodeRunTaskRequest(args);
+    if (!built.runnable) {
+        return { skipped: true, skillKey: built.skillKey, reason: built.reason };
+    }
+    const analysis = await analyzeRunTaskRequest(args.catalox, built.request, args.analyzeOptions);
+    return { ...analysis, skipped: false, skillKey: built.skillKey, request: built.request };
+}

package/dist/src/runtime/validateCanonicalGraphDocument.d.ts

@@ -0,0 +1,25 @@
+import type { Graph } from '../types/refs.js';
+/** Top-level keys permitted on a canonical exellix-graph executable graph JSON document. */
+export declare const CANONICAL_GRAPH_TOP_LEVEL_KEYS: readonly ["id", "version", "modelConfig", "jobKnowledge", "nodes", "edges", "variables", "response", "metadata"];
+/**
+ * Returns top-level keys on `graph` that are not part of the canonical executable document contract.
+ */
+export declare function getCanonicalGraphDocumentViolations(graph: unknown): string[];
+/** Single-node validation. Throws `NON_CANONICAL_TASK_NODE` on the first canonical violation. */
+export declare function assertCanonicalTaskNode(node: unknown, context?: {
+    jobId?: string;
+    graphId?: string;
+    nodeIndex?: number;
+}): void;
+/**
+ * Throws {@link ExellixGraphError} when the value is not a canonical graph document
+ * (forbidden top-level keys, record-keyed `nodes`, root `outputConstraints`, or any
+ * legacy task-node alias). Upstream producers must emit only model fields (`id`,
+ * optional `version`, `modelConfig`, `jobKnowledge`, `nodes`, `edges`,
+ * `variables`, required `response`, and `metadata`); runtime fields belong under the execution
+ * request `runtime` object.
+ */
+export declare function assertCanonicalGraphDocument(graph: Graph, context?: {
+    jobId?: string;
+    graphId?: string;
+}): void;