@exellix/graph-engine 7.8.1 → 8.0.0

package/dist/src/plan/aiModelSelectionWire.js

@@ -0,0 +1,39 @@
+/**
+ * Maps plan {@link AiModelSelection} to ai-tasks 8.4+ wire profile strings.
+ */
+export function aiModelSelectionToWireString(selection) {
+    if (selection == null)
+        return undefined;
+    if (selection.kind === 'profileChoice')
+        return selection.key.trim();
+    if (selection.kind === 'profile') {
+        const profile = selection.profile.trim();
+        const choice = typeof selection.choice === 'string' ? selection.choice.trim() : '';
+        return choice ? `${profile}/${choice}` : profile;
+    }
+    if (selection.kind === 'model') {
+        const modelId = typeof selection.modelId === 'string'
+            ? selection.modelId
+            : typeof selection.model === 'string'
+                ? selection.model
+                : '';
+        return `${selection.provider}/${modelId}`.replace(/\/+/g, '/');
+    }
+    return undefined;
+}
+export function resolvedSnapshotToWireString(snapshot) {
+    if (snapshot == null)
+        return undefined;
+    if (snapshot.purpose === 'strictReplay' || snapshot.purpose === 'debugReplay') {
+        return `${snapshot.provider}/${snapshot.modelId}`;
+    }
+    if (snapshot.profileChoiceKey)
+        return snapshot.profileChoiceKey;
+    return undefined;
+}
+export function unitModelWireString(args) {
+    const fromSnapshot = resolvedSnapshotToWireString(args.resolvedInvocationSnapshot);
+    if (fromSnapshot)
+        return fromSnapshot;
+    return aiModelSelectionToWireString(args.modelSelection);
+}

package/dist/src/plan/applyNodePlanInvoke.d.ts

@@ -0,0 +1,10 @@
+import type { FinalizerExecutionPlan, NodeExecutionPlan } from '@x12i/graphenix-executable-contracts';
+import type { TaskNode } from '../types/refs.js';
+/** Merge frozen plan invoke contract onto exellix task node before execution. */
+export declare function applyNodePlanInvoke(node: TaskNode, nodePlan: NodeExecutionPlan): TaskNode;
+export declare function finalizerPlanForId(plan: {
+    finalizerPlans: Record<string, FinalizerExecutionPlan>;
+}, nodeId: string): FinalizerExecutionPlan | undefined;
+export declare function nodePlanForId(plan: {
+    nodePlans: Record<string, NodeExecutionPlan>;
+}, nodeId: string): NodeExecutionPlan | undefined;

package/dist/src/plan/applyNodePlanInvoke.js

@@ -0,0 +1,67 @@
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+/** Merge frozen plan invoke contract onto exellix task node before execution. */
+export function applyNodePlanInvoke(node, nodePlan) {
+    const patched = structuredClone(node);
+    const ic = nodePlan.invokeContract;
+    if (!ic)
+        return patched;
+    if (ic.taskVariable != null)
+        patched.taskVariable = structuredClone(ic.taskVariable);
+    if (ic.inputsConfig != null)
+        patched.inputsConfig = structuredClone(ic.inputsConfig);
+    if (ic.executionMapping != null)
+        patched.executionMapping = structuredClone(ic.executionMapping);
+    if (ic.jobContextMapping != null)
+        patched.jobContextMapping = structuredClone(ic.jobContextMapping);
+    if (ic.smartInput != null)
+        patched.smartInput = structuredClone(ic.smartInput);
+    if (ic.scope != null)
+        patched.scope = structuredClone(ic.scope);
+    if (ic.memory != null)
+        patched.memory = structuredClone(ic.memory);
+    if (Array.isArray(ic.knowledgeRefs?.taskKnowledge)) {
+        patched.taskKnowledge = ic.knowledgeRefs.taskKnowledge.map((ref) => {
+            if (typeof ref === 'string')
+                return ref;
+            if (isPlainRecord(ref) && typeof ref.id === 'string')
+                return ref.id;
+            return String(ref);
+        });
+    }
+    const tc = { ...(patched.taskConfiguration ?? {}) };
+    const pipeline = ic.pipeline;
+    if (isPlainRecord(pipeline)) {
+        if (pipeline.executionStrategies !== undefined)
+            tc.executionStrategies = pipeline.executionStrategies;
+        if (pipeline.aiTaskStrategies !== undefined)
+            tc.aiTaskStrategies = pipeline.aiTaskStrategies;
+        if (pipeline.aiTaskProfile !== undefined)
+            tc.aiTaskProfile = pipeline.aiTaskProfile;
+        if (pipeline.narrix !== undefined)
+            tc.narrix = pipeline.narrix;
+        if (pipeline.narrixInput !== undefined)
+            tc.narrixInput = pipeline.narrixInput;
+        if (pipeline.narrixMode !== undefined)
+            tc.narrixMode = pipeline.narrixMode;
+        if (pipeline.llmCall !== undefined)
+            tc.llmCall = pipeline.llmCall;
+    }
+    if (ic.validation?.aiTasksOutputValidation != null) {
+        tc.aiTasksOutputValidation = ic.validation.aiTasksOutputValidation;
+    }
+    if (ic.validation?.outputValidation != null) {
+        patched.outputValidation = ic.validation.outputValidation;
+    }
+    if (ic.localConfig != null)
+        Object.assign(tc, ic.localConfig);
+    patched.taskConfiguration = tc;
+    return patched;
+}
+export function finalizerPlanForId(plan, nodeId) {
+    return plan.finalizerPlans[nodeId];
+}
+export function nodePlanForId(plan, nodeId) {
+    return plan.nodePlans[nodeId];
+}

package/dist/src/plan/embeddedGraphToExellixGraph.d.ts

@@ -0,0 +1,5 @@
+import type { ExecutableGraphPlanV2, NormalizedExecutableGraphDocument } from '@x12i/graphenix-executable-contracts';
+import type { Graph } from '../types/refs.js';
+/** Materialize exellix {@link Graph} from plan embedded normalized authoring graph. */
+export declare function embeddedGraphToExellixGraph(plan: ExecutableGraphPlanV2): Graph;
+export declare function getEmbeddedExecutableDocument(plan: ExecutableGraphPlanV2): NormalizedExecutableGraphDocument;

package/dist/src/plan/embeddedGraphToExellixGraph.js

@@ -0,0 +1,131 @@
+import { getFinalizerNodeConfig, getTaskNodeConfig, isExecutableFinalizerNode, isExecutableTaskNode, } from '@x12i/graphenix-executable-contracts';
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function taskNodeFromExecutableNode(node) {
+    const params = getTaskNodeConfig(node);
+    if (!params) {
+        throw new Error(`Expected executable task node "${node.id}"`);
+    }
+    const tc = isPlainRecord(params.taskConfiguration) ? { ...params.taskConfiguration } : {};
+    const out = {
+        id: node.id,
+        type: 'task',
+        skillKey: typeof params.skillKey === 'string' ? params.skillKey : undefined,
+    };
+    if (params.taskVariable !== undefined)
+        out.taskVariable = structuredClone(params.taskVariable);
+    if (params.inputsConfig !== undefined)
+        out.inputsConfig = structuredClone(params.inputsConfig);
+    if (params.executionMapping !== undefined) {
+        out.executionMapping = structuredClone(params.executionMapping);
+    }
+    if (Array.isArray(params.taskKnowledge)) {
+        out.taskKnowledge = params.taskKnowledge.map((ref) => {
+            if (typeof ref === 'string')
+                return ref;
+            if (isPlainRecord(ref) && typeof ref.id === 'string')
+                return ref.id;
+            return String(ref);
+        });
+    }
+    if (params.conditions !== undefined)
+        out.conditions = structuredClone(params.conditions);
+    if (isPlainRecord(params.variables))
+        out.variables = structuredClone(params.variables);
+    if (isPlainRecord(params.metadata))
+        out.metadata = structuredClone(params.metadata);
+    out.taskConfiguration = tc;
+    const pipeline = params.executionPipeline;
+    if (Array.isArray(pipeline))
+        out.executionPipeline = structuredClone(pipeline);
+    return out;
+}
+function finalizerNodeFromExecutableNode(node) {
+    const params = getFinalizerNodeConfig(node);
+    if (!params) {
+        throw new Error(`Expected executable finalizer node "${node.id}"`);
+    }
+    const paramsRecord = params;
+    return {
+        id: node.id,
+        type: 'finalizer',
+        finalizerType: params.finalizerType,
+        config: isPlainRecord(params.config) ? structuredClone(params.config) : {},
+        inputs: isPlainRecord(params.inputs) ? structuredClone(params.inputs) : undefined,
+        ...(isPlainRecord(paramsRecord.outputMapping)
+            ? { outputMapping: structuredClone(paramsRecord.outputMapping) }
+            : {}),
+    };
+}
+function knowledgeRefsToExellixStrings(refs) {
+    if (!Array.isArray(refs))
+        return undefined;
+    return refs.map((ref) => {
+        if (typeof ref === 'string')
+            return ref;
+        if (isPlainRecord(ref) && typeof ref.id === 'string')
+            return ref.id;
+        return String(ref);
+    });
+}
+function edgesFromPlan(plan) {
+    return plan.topology.edges.map((edgeRef) => {
+        const deferred = plan.deferredGates.edgeGates[edgeRef.edgeId];
+        const out = {
+            from: edgeRef.from.nodeId,
+            to: edgeRef.to.nodeId,
+        };
+        if (deferred?.when != null)
+            out.when = deferred.when;
+        return out;
+    });
+}
+function responseFromEmbedded(doc, plan) {
+    const metaResponse = doc.graph.metadata?.graphResponse;
+    if (isPlainRecord(metaResponse)) {
+        const out = {
+            shape: isPlainRecord(metaResponse.shape) ? structuredClone(metaResponse.shape) : {},
+        };
+        if (metaResponse.missing !== undefined) {
+            out.missing = metaResponse.missing;
+        }
+        if (metaResponse.version !== undefined) {
+            out.version = metaResponse.version;
+        }
+        return out;
+    }
+    if (isPlainRecord(plan.contracts?.response?.finalOutputSchema)) {
+        return { shape: { type: 'literal', value: {} } };
+    }
+    return { shape: {} };
+}
+/** Materialize exellix {@link Graph} from plan embedded normalized authoring graph. */
+export function embeddedGraphToExellixGraph(plan) {
+    if (plan.normalizedGraph.mode !== 'embedded') {
+        throw new Error('embeddedGraphToExellixGraph requires embedded normalizedGraph');
+    }
+    const doc = plan.normalizedGraph.graph;
+    const nodes = [];
+    for (const node of doc.graph.nodes) {
+        if (isExecutableTaskNode(node))
+            nodes.push(taskNodeFromExecutableNode(node));
+        else if (isExecutableFinalizerNode(node))
+            nodes.push(finalizerNodeFromExecutableNode(node));
+    }
+    return {
+        id: plan.source.graphId,
+        version: plan.source.graphRevision,
+        nodes,
+        edges: edgesFromPlan(plan),
+        response: responseFromEmbedded(doc, plan),
+        metadata: isPlainRecord(doc.graph.metadata) ? structuredClone(doc.graph.metadata) : undefined,
+        jobKnowledge: knowledgeRefsToExellixStrings(isPlainRecord(doc.graph.metadata) ? doc.graph.metadata.jobKnowledge : undefined),
+    };
+}
+export function getEmbeddedExecutableDocument(plan) {
+    if (plan.normalizedGraph.mode !== 'embedded') {
+        throw new Error('getEmbeddedExecutableDocument requires embedded normalizedGraph');
+    }
+    return plan.normalizedGraph.graph;
+}

package/dist/src/plan/planDeferredGates.d.ts

@@ -0,0 +1,16 @@
+import type { DeferredEdgeGate, DeferredGateSet, DeferredNodeGate, ExecutableGraphPlanV2 } from '@x12i/graphenix-executable-contracts';
+import type { RunxClient } from '@x12i/runx';
+import type { TaskNodeConditionEvalContext } from '../runtime/taskNodeConditionsEvaluation.js';
+export declare function evaluateDeferredNodeGate(gate: DeferredNodeGate | undefined, ctx: TaskNodeConditionEvalContext, executionInput: Record<string, unknown>, runx?: RunxClient): Promise<{
+    ok: boolean;
+    skipReason?: string;
+}>;
+export declare function evaluateDeferredEdgeGate(gate: DeferredEdgeGate | undefined, ctx: TaskNodeConditionEvalContext): boolean;
+export declare function buildIncomingEdgeGateMap(plan: ExecutableGraphPlanV2): Map<string, DeferredEdgeGate[]>;
+export declare function nodeDeferredGate(plan: ExecutableGraphPlanV2, nodeId: string): DeferredNodeGate | undefined;
+export declare function hasPlanConditionalEdges(plan: ExecutableGraphPlanV2): boolean;
+export declare function evaluatePlanEntryGates(gates: DeferredGateSet['entryGates'] | undefined, executionInput: Record<string, unknown>, ctx: TaskNodeConditionEvalContext, runx?: RunxClient): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+export declare function planNeedsRunx(plan: ExecutableGraphPlanV2): boolean;

package/dist/src/plan/planDeferredGates.js

@@ -0,0 +1,118 @@
+import { evaluateGraphPredicate } from '../runtime/predicates.js';
+import { evaluateConditionWhen } from '../runtime/taskNodeConditionsEvaluation.js';
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function gateConditionToWhen(cond) {
+    if (!isPlainRecord(cond)) {
+        return { jsonConditions: { condition: cond, parameters: {} } };
+    }
+    if (cond.jsonConditions != null || cond.jsConditionFunction != null || cond.aiCondition != null) {
+        return cond;
+    }
+    if (cond.ai != null && isPlainRecord(cond.ai)) {
+        return { aiCondition: cond.ai };
+    }
+    if (typeof cond.js === 'string') {
+        return { jsConditionFunction: { conditionFunctionId: cond.js, parameters: {} } };
+    }
+    if (cond.condition != null) {
+        return {
+            jsonConditions: {
+                condition: cond.condition,
+                parameters: isPlainRecord(cond.parameters) ? cond.parameters : {},
+            },
+        };
+    }
+    return { jsonConditions: { condition: cond, parameters: {} } };
+}
+async function evalGateConditions(conditions, ctx, executionInput, runx, mode = 'runWhen') {
+    if (!conditions?.length)
+        return { ok: true };
+    for (const cond of conditions) {
+        const ev = await evaluateConditionWhen(gateConditionToWhen(cond), ctx, executionInput, { runx });
+        if (ev.error)
+            return { ok: false, skipReason: ev.skipReason ?? 'gate_eval_error' };
+        const pass = ev.ok === true;
+        if (mode === 'skipWhen' ? pass : !pass) {
+            return { ok: false, skipReason: ev.skipReason ?? 'gate_failed' };
+        }
+    }
+    return { ok: true };
+}
+export async function evaluateDeferredNodeGate(gate, ctx, executionInput, runx) {
+    if (!gate)
+        return { ok: true };
+    if (gate.skipWhen?.length) {
+        const skip = await evalGateConditions(gate.skipWhen, ctx, executionInput, runx, 'skipWhen');
+        if (!skip.ok)
+            return { ok: false, skipReason: skip.skipReason ?? 'skip_when' };
+    }
+    if (gate.runWhen?.length) {
+        return evalGateConditions(gate.runWhen, ctx, executionInput, runx, 'runWhen');
+    }
+    return { ok: true };
+}
+export function evaluateDeferredEdgeGate(gate, ctx) {
+    if (!gate?.when)
+        return true;
+    return evaluateGraphPredicate(gate.when, ctx);
+}
+export function buildIncomingEdgeGateMap(plan) {
+    const byTo = new Map();
+    for (const edgeRef of plan.topology.edges) {
+        if (!edgeRef.hasDeferredGate || !edgeRef.deferredGateId)
+            continue;
+        const gate = plan.deferredGates.edgeGates[edgeRef.edgeId];
+        if (!gate)
+            continue;
+        const to = edgeRef.to.nodeId;
+        const list = byTo.get(to) ?? [];
+        list.push(gate);
+        byTo.set(to, list);
+    }
+    return byTo;
+}
+export function nodeDeferredGate(plan, nodeId) {
+    return plan.deferredGates.nodeGates[nodeId];
+}
+export function hasPlanConditionalEdges(plan) {
+    return Object.keys(plan.deferredGates.edgeGates).length > 0;
+}
+export async function evaluatePlanEntryGates(gates, executionInput, ctx, runx) {
+    if (!gates?.length)
+        return { ok: true };
+    for (const gate of gates) {
+        const ev = await evaluateConditionWhen(gateConditionToWhen(gate.condition), ctx, executionInput, { runx });
+        if (ev.error || !ev.ok) {
+            return { ok: false, reason: ev.skipReason ?? 'entry_gate_rejected' };
+        }
+    }
+    return { ok: true };
+}
+export function planNeedsRunx(plan) {
+    const scan = (c) => {
+        if (!isPlainRecord(c))
+            return false;
+        if (c.js != null || c.ai != null)
+            return true;
+        if (c.jsConditionFunction != null || c.aiCondition != null)
+            return true;
+        return false;
+    };
+    for (const g of Object.values(plan.deferredGates.nodeGates)) {
+        for (const list of [g.runWhen, g.skipWhen]) {
+            if (list?.some((c) => scan(c)))
+                return true;
+        }
+    }
+    for (const g of Object.values(plan.deferredGates.edgeGates)) {
+        if (scan(g.when))
+            return true;
+    }
+    for (const g of plan.deferredGates.entryGates ?? []) {
+        if (scan(g.condition))
+            return true;
+    }
+    return false;
+}

package/dist/src/plan/planExecuteEntry.d.ts

@@ -0,0 +1,12 @@
+import type { ExecutableGraphPlanV2 } from '@x12i/graphenix-executable-contracts';
+import type { GraphRuntimeObject } from '../runtime/ExellixGraphRuntime.js';
+export type PlanExecuteEntryResult = {
+    plan: ExecutableGraphPlanV2;
+};
+export declare function requireEmbeddedNormalizedGraph(plan: ExecutableGraphPlanV2): void;
+export declare function assertRuntimeBinding(plan: ExecutableGraphPlanV2, runtime: GraphRuntimeObject): void;
+export declare function preparePlanExecuteEntry(planInput: unknown, runtime: GraphRuntimeObject): PlanExecuteEntryResult;
+export declare function computePlanAudit(plan: ExecutableGraphPlanV2): {
+    planHash: string;
+    source: ExecutableGraphPlanV2['source'];
+};

package/dist/src/plan/planExecuteEntry.js

@@ -0,0 +1,73 @@
+import { validateExecutablePlan } from '@x12i/graphenix-plan-format';
+import { defaultHashFunction } from '@x12i/graphenix-executable-contracts';
+import { ExellixGraphError } from '../errors/ExellixGraphError.js';
+import { ExellixGraphErrorCode } from '../errors/exellixGraphErrorCodes.js';
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+export function requireEmbeddedNormalizedGraph(plan) {
+    if (plan.normalizedGraph?.mode !== 'embedded') {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, 'ExecutableGraphPlan.normalizedGraph.mode must be "embedded" for graph-engine execution', { graphId: plan.source?.graphId });
+    }
+}
+export function assertRuntimeBinding(plan, runtime) {
+    const binding = plan.runtimeBinding;
+    const jobId = typeof runtime.jobId === 'string' ? runtime.jobId.trim() : '';
+    if (!jobId) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.JOB_ID_REQUIRED, 'runtime.jobId is required', {
+            graphId: plan.source?.graphId,
+        });
+    }
+    if (binding.jobId !== jobId) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_RUNTIME, `Plan runtimeBinding.jobId "${binding.jobId}" does not match runtime.jobId "${jobId}"`, { graphId: plan.source?.graphId, jobId });
+    }
+    const hash = defaultHashFunction;
+    if (binding.inputHash != null && runtime.input !== undefined) {
+        const actual = hash(runtime.input);
+        if (actual !== binding.inputHash) {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_RUNTIME, 'Plan runtimeBinding.inputHash does not match runtime.input', { graphId: plan.source?.graphId, jobId });
+        }
+    }
+    if (binding.variablesHash != null && runtime.variables !== undefined) {
+        const actual = hash(runtime.variables);
+        if (actual !== binding.variablesHash) {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_RUNTIME, 'Plan runtimeBinding.variablesHash does not match runtime.variables', { graphId: plan.source?.graphId, jobId });
+        }
+    }
+    if (binding.jobHash != null && isPlainRecord(runtime.job)) {
+        const actual = hash(runtime.job);
+        if (actual !== binding.jobHash) {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_RUNTIME, 'Plan runtimeBinding.jobHash does not match runtime.job', { graphId: plan.source?.graphId, jobId });
+        }
+    }
+    const expectations = plan.runtimeExpectations;
+    if (expectations?.requiresAgentId) {
+        const agentId = runtime.job?.agentId;
+        if (typeof agentId !== 'string' || agentId.trim() === '') {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_RUNTIME, 'Plan runtimeExpectations.requiresAgentId but runtime.job.agentId is missing', { graphId: plan.source?.graphId, jobId });
+        }
+    }
+    if (expectations?.requiresJobTypeId) {
+        const jt = runtime.job?.jobTypeId ?? runtime.job?.jobType;
+        if (typeof jt !== 'string' || jt.trim() === '') {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_RUNTIME, 'Plan runtimeExpectations.requiresJobTypeId but runtime.job.jobTypeId/jobType is missing', { graphId: plan.source?.graphId, jobId });
+        }
+    }
+}
+export function preparePlanExecuteEntry(planInput, runtime) {
+    const validation = validateExecutablePlan(planInput);
+    if (!validation.valid) {
+        const summary = validation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `Invalid ExecutableGraphPlan: ${summary}`, { jobId: runtime.jobId });
+    }
+    const plan = planInput;
+    requireEmbeddedNormalizedGraph(plan);
+    assertRuntimeBinding(plan, runtime);
+    return { plan };
+}
+export function computePlanAudit(plan) {
+    return {
+        planHash: defaultHashFunction(plan),
+        source: plan.source,
+    };
+}

package/dist/src/plan/planExecutionPipeline.d.ts

@@ -0,0 +1,11 @@
+import type { ExecutionUnitPlanV2, NodeExecutionPlan } from '@x12i/graphenix-executable-contracts';
+import type { ExecutionStepOption } from '../types/options.js';
+/**
+ * Build ai-tasks executionPipeline from plan units (pipelinePhase) merged with invoke contract.
+ */
+export declare function executionPipelineFromNodePlan(nodePlan: NodeExecutionPlan): ExecutionStepOption[] | undefined;
+export declare function externalUtilityUnits(nodePlan: NodeExecutionPlan): {
+    pre: ExecutionUnitPlanV2[];
+    post: ExecutionUnitPlanV2[];
+};
+export declare function isLocalSkillNodePlan(nodePlan: NodeExecutionPlan): boolean;

package/dist/src/plan/planExecutionPipeline.js

@@ -0,0 +1,54 @@
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Build ai-tasks executionPipeline from plan units (pipelinePhase) merged with invoke contract.
+ */
+export function executionPipelineFromNodePlan(nodePlan) {
+    const pipelineUnits = [...nodePlan.executionUnits]
+        .filter((u) => u.unitKind === 'pipelinePhase')
+        .sort((a, b) => a.order - b.order);
+    if (pipelineUnits.length === 0) {
+        const fromContract = nodePlan.invokeContract?.pipeline;
+        const synth = isPlainRecord(fromContract?.aiTaskProfile)
+            ? fromContract.aiTaskProfile.inputSynthesis
+            : undefined;
+        if (isPlainRecord(synth) && synth.enabled === true) {
+            return [{ phase: 'pre', type: 'synthesized-context', config: synth }];
+        }
+        return undefined;
+    }
+    const steps = [];
+    for (const unit of pipelineUnits) {
+        if (unit.strategyKey === 'inputSynthesis') {
+            const synth = nodePlan.invokeContract?.pipeline?.aiTaskProfile;
+            const cfg = isPlainRecord(synth) && isPlainRecord(synth.inputSynthesis)
+                ? synth.inputSynthesis
+                : isPlainRecord(unit.invokeContract)
+                    ? unit.invokeContract
+                    : {};
+            steps.push({ phase: 'pre', type: 'synthesized-context', config: cfg });
+            continue;
+        }
+        steps.push({
+            phase: 'pre',
+            type: unit.strategyKey ?? unit.actionKey ?? 'pipeline',
+            config: isPlainRecord(unit.invokeContract) ? unit.invokeContract : {},
+        });
+    }
+    const hasMain = nodePlan.executionUnits.some((u) => u.unitKind === 'mainSkill');
+    if (hasMain && !steps.some((s) => s.phase === 'main')) {
+        steps.push({ phase: 'main', type: 'direct' });
+    }
+    return steps.length ? steps : undefined;
+}
+export function externalUtilityUnits(nodePlan) {
+    const units = [...nodePlan.executionUnits].sort((a, b) => a.order - b.order);
+    return {
+        pre: units.filter((u) => u.unitKind === 'externalPreUtility'),
+        post: units.filter((u) => u.unitKind === 'externalPostUtility'),
+    };
+}
+export function isLocalSkillNodePlan(nodePlan) {
+    return nodePlan.executionClass === 'localTask' || nodePlan.executionUnits.some((u) => u.unitKind === 'localSkill');
+}

package/dist/src/plan/planModelConfig.d.ts

@@ -0,0 +1,10 @@
+import type { ExecutionUnitPlanV2, FinalizerExecutionPlan, NodeExecutionPlan, ResolvedModelSlots } from '@x12i/graphenix-executable-contracts';
+import type { GraphAiModelConfig } from '../types/refs.js';
+/** Effective triplet from frozen plan model slots (task node or AI finalizer). */
+export declare function graphAiModelConfigFromPlanSlots(slots: ResolvedModelSlots | null | undefined): GraphAiModelConfig;
+/** Effective triplet for a task node from frozen plan slots. */
+export declare function graphAiModelConfigFromNodePlan(nodePlan: NodeExecutionPlan): GraphAiModelConfig;
+/** Effective triplet for an AI finalizer from frozen plan slots. */
+export declare function graphAiModelConfigFromFinalizerPlan(finalizerPlan: FinalizerExecutionPlan): GraphAiModelConfig;
+/** Per-unit model override when the unit carries its own selection. */
+export declare function modelConfigForUnit(nodePlan: NodeExecutionPlan, unit: ExecutionUnitPlanV2): GraphAiModelConfig;

package/dist/src/plan/planModelConfig.js

@@ -0,0 +1,46 @@
+import { DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG } from '../runtime/graphAiModelConfig.js';
+import { unitModelWireString } from './aiModelSelectionWire.js';
+function slotWire(slots, slot, fallback) {
+    const entry = slots?.[slot];
+    if (entry?.selection) {
+        const wire = unitModelWireString({ modelSelection: entry.selection });
+        if (wire)
+            return wire;
+    }
+    return fallback;
+}
+/** Effective triplet from frozen plan model slots (task node or AI finalizer). */
+export function graphAiModelConfigFromPlanSlots(slots) {
+    const base = DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG;
+    return {
+        preActionModel: slotWire(slots, 'preActionModel', base.preActionModel),
+        skillModel: slotWire(slots, 'skillModel', base.skillModel),
+        postActionModel: slotWire(slots, 'postActionModel', base.postActionModel),
+    };
+}
+/** Effective triplet for a task node from frozen plan slots. */
+export function graphAiModelConfigFromNodePlan(nodePlan) {
+    return graphAiModelConfigFromPlanSlots(nodePlan.modelSlots);
+}
+/** Effective triplet for an AI finalizer from frozen plan slots. */
+export function graphAiModelConfigFromFinalizerPlan(finalizerPlan) {
+    return graphAiModelConfigFromPlanSlots(finalizerPlan.modelSlots);
+}
+/** Per-unit model override when the unit carries its own selection. */
+export function modelConfigForUnit(nodePlan, unit) {
+    const base = graphAiModelConfigFromNodePlan(nodePlan);
+    const slot = unit.modelSlot;
+    const unitWire = unitModelWireString({
+        modelSelection: unit.modelSelection,
+        resolvedInvocationSnapshot: unit.resolvedInvocationSnapshot,
+    });
+    if (!unitWire || !slot || slot === 'finalizerModel')
+        return base;
+    if (slot === 'preActionModel')
+        return { ...base, preActionModel: unitWire };
+    if (slot === 'skillModel')
+        return { ...base, skillModel: unitWire };
+    if (slot === 'postActionModel')
+        return { ...base, postActionModel: unitWire };
+    return base;
+}

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

@@ -1,5 +1,6 @@
 import type { GraphEngineFactory } from "./GraphEngine.js";
 import type { ExecutionStep } from "@exellix/ai-tasks";
+import type { ExecutableGraphPlanV2, GraphExecutionTrace } from "@x12i/graphenix-executable-contracts";
 import type { Graph, GraphModelObject, GraphNode, GraphAiModelConfig, TaskNodeRuntimeObject } from "../types/refs.js";
 import type { RunLogEntry } from "../types/runLog.js";
 import type { RunTaskDiagnostics } from "../types/options.js";
@@ -62,7 +63,7 @@ export interface GraphLoader {
 }
 /**
  * Dynamic state and run-scoped options for one graph execution.
- * Static graph shape belongs on {@link GraphExecutionRequest.model}; this object
+ * Static execution contract belongs on {@link GraphExecutionRequest.plan}; this object
  * is the per-run state that may be populated and mutated during execution.
  */
 export interface GraphRuntimeObject extends HostExecuteGraphRunOptions {
@@ -104,7 +105,7 @@ export interface GraphRuntimeObject extends HostExecuteGraphRunOptions {
 }
 /** Required public graph execution request shape. */
 export interface GraphExecutionRequest {
-    model: GraphModelObject;
+    plan: ExecutableGraphPlanV2;
     runtime: GraphRuntimeObject;
 }
 /** Canonical public execution request shape for `runtime.executeGraph(...)`. */
@@ -144,13 +145,15 @@ export interface ExecuteGraphResult {
         nodes: ExecuteGraphDebugNodeEntry[];
     };
     /**
-     * Audit fingerprint of the supplied graph model.
+     * Audit fingerprint of the supplied executable plan.
      * Hosts (e.g. execution matrix) may persist this with catalog `graphVersion` for replay forensics.
      */
-    graphAudit?: {
-        source: 'model';
-        contentSha256: string;
+    planAudit?: {
+        planHash: string;
+        source: ExecutableGraphPlanV2['source'];
     };
+    /** Append-only execution trace bound to the plan (when trace-format is used). */
+    trace?: GraphExecutionTrace;
 }
 export type GraphKnowledgeResolverContext = {
     model: GraphModelObject;