@exellix/graph-engine 6.0.0

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

@@ -0,0 +1,67 @@
+import type { Graph, GraphNode, Job } from '../types/refs.js';
+import { type GraphEngineMemoryResolutionRoot } from './resolveGraphEngineMemoryPaths.js';
+export type ExecutionVariableBuckets = {
+    /** Job / graph run scope: model + runtime + legacy job envelope. */
+    jobVariables: Record<string, unknown>;
+    /** Task / node scope: `node.variables` + runtime override. */
+    taskVariables: Record<string, unknown>;
+};
+/** Reads the two variable buckets from live execution memory. */
+export declare function readExecutionVariableBuckets(execution: Record<string, unknown>): ExecutionVariableBuckets;
+/**
+ * Seeds job-scoped template variables on `executionMemory` (mirrors runtime like `input` / `inputs`).
+ *
+ * Graph and job scopes share one bucket:
+ * `execution.jobVariables` ← `model.variables` + `variables.__graphModel` + `job.jobVariables`
+ *   + `runtime.jobVariables` + `runtime.variables` (later layers win).
+ */
+export declare function seedGraphVariableBucketsOnExecution(args: {
+    execution: Record<string, unknown>;
+    graph?: Graph;
+    job?: Job;
+    runtimeVariables?: Record<string, unknown>;
+    runtimeJobVariables?: Record<string, unknown>;
+}): void;
+/**
+ * Sets `execution.taskVariables` for the current node: `node.variables` + optional runtime override.
+ */
+export declare function mirrorTaskVariablesOnExecution(args: {
+    execution: Record<string, unknown>;
+    node?: GraphNode;
+    runtimeTaskVariables?: Record<string, unknown>;
+}): void;
+export declare function seedGraphVariableBucketsFromRuntime(args: {
+    execution: Record<string, unknown>;
+    graph: Graph;
+    runtime: {
+        variables?: Record<string, unknown>;
+        jobVariables?: Record<string, unknown>;
+        job?: Job;
+    };
+    job?: Job;
+}): void;
+/** Predicate / condition context: mirrored execution + job-scoped bucket. */
+export declare function buildPredicateEvalContextForNode(args: {
+    executionMemory: Record<string, unknown>;
+    jobMemory?: unknown;
+    taskMemory?: unknown;
+    node?: GraphNode;
+    runtimeTaskVariables?: Record<string, unknown>;
+}): {
+    executionMemory: Record<string, unknown>;
+    jobMemory?: unknown;
+    taskMemory?: unknown;
+    variables: Record<string, unknown>;
+};
+export declare function buildMemoryResolutionRootFromExecution(args: {
+    execution: Record<string, unknown>;
+    input: Record<string, unknown>;
+    inputs?: Record<string, unknown>;
+    jobMemory?: unknown;
+    taskMemory?: unknown;
+    xynthesized?: {
+        job: Record<string, unknown>;
+        task: Record<string, unknown>;
+        execution?: Record<string, unknown>;
+    };
+}): GraphEngineMemoryResolutionRoot;

package/dist/src/runtime/executionVariableBuckets.js

@@ -0,0 +1,96 @@
+import { EXELLIX_GRAPH_MODEL_VARIABLE_KEY, mergeGraphDocumentModel } from '../types/refs.js';
+import { buildGraphEngineMemoryResolutionRoot, } from './resolveGraphEngineMemoryPaths.js';
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+/** Reads the two variable buckets from live execution memory. */
+export function readExecutionVariableBuckets(execution) {
+    return {
+        jobVariables: isPlainObject(execution.jobVariables) ? { ...execution.jobVariables } : {},
+        taskVariables: isPlainObject(execution.taskVariables) ? { ...execution.taskVariables } : {},
+    };
+}
+/**
+ * Seeds job-scoped template variables on `executionMemory` (mirrors runtime like `input` / `inputs`).
+ *
+ * Graph and job scopes share one bucket:
+ * `execution.jobVariables` ← `model.variables` + `variables.__graphModel` + `job.jobVariables`
+ *   + `runtime.jobVariables` + `runtime.variables` (later layers win).
+ */
+export function seedGraphVariableBucketsOnExecution(args) {
+    const { execution, graph, job } = args;
+    const jobVars = {};
+    if (graph?.variables && typeof graph.variables === 'object') {
+        Object.assign(jobVars, graph.variables);
+    }
+    if (graph) {
+        const docModel = mergeGraphDocumentModel(graph);
+        if (Object.keys(docModel).length > 0) {
+            jobVars[EXELLIX_GRAPH_MODEL_VARIABLE_KEY] = docModel;
+        }
+    }
+    const legacyJob = job?.jobVariables;
+    if (legacyJob && typeof legacyJob === 'object') {
+        Object.assign(jobVars, legacyJob);
+    }
+    if (args.runtimeJobVariables) {
+        Object.assign(jobVars, args.runtimeJobVariables);
+    }
+    if (args.runtimeVariables) {
+        Object.assign(jobVars, args.runtimeVariables);
+    }
+    execution.jobVariables = jobVars;
+    delete execution.variables;
+}
+/**
+ * Sets `execution.taskVariables` for the current node: `node.variables` + optional runtime override.
+ */
+export function mirrorTaskVariablesOnExecution(args) {
+    const taskVars = {};
+    const node = args.node;
+    if (node?.variables && typeof node.variables === 'object') {
+        Object.assign(taskVars, node.variables);
+    }
+    if (args.runtimeTaskVariables) {
+        Object.assign(taskVars, args.runtimeTaskVariables);
+    }
+    args.execution.taskVariables = taskVars;
+}
+export function seedGraphVariableBucketsFromRuntime(args) {
+    seedGraphVariableBucketsOnExecution({
+        execution: args.execution,
+        graph: args.graph,
+        job: args.job ?? args.runtime.job,
+        runtimeVariables: args.runtime.variables,
+        runtimeJobVariables: args.runtime.jobVariables,
+    });
+}
+/** Predicate / condition context: mirrored execution + job-scoped bucket. */
+export function buildPredicateEvalContextForNode(args) {
+    const executionMemory = { ...args.executionMemory };
+    mirrorTaskVariablesOnExecution({
+        execution: executionMemory,
+        node: args.node,
+        runtimeTaskVariables: args.runtimeTaskVariables,
+    });
+    const buckets = readExecutionVariableBuckets(executionMemory);
+    return {
+        executionMemory,
+        jobMemory: args.jobMemory,
+        taskMemory: args.taskMemory,
+        variables: buckets.jobVariables,
+    };
+}
+export function buildMemoryResolutionRootFromExecution(args) {
+    const buckets = readExecutionVariableBuckets(args.execution);
+    return buildGraphEngineMemoryResolutionRoot({
+        input: args.input,
+        inputs: args.inputs,
+        jobVariables: buckets.jobVariables,
+        taskVariables: buckets.taskVariables,
+        jobMemory: args.jobMemory,
+        taskMemory: args.taskMemory,
+        executionMemory: args.execution,
+        xynthesized: args.xynthesized,
+    });
+}

package/dist/src/runtime/finalizers/errors.d.ts

@@ -0,0 +1,9 @@
+export type FinalizerErrorCode = 'GRAPH_FINALIZER_INVALID' | 'GRAPH_FINALIZER_UNREACHABLE' | 'GRAPH_FINALIZER_OUTPUT_INVALID' | 'GRAPH_FINALIZER_INPUT_MISSING' | 'GRAPH_FINALIZER_NODE_FAILED' | 'GRAPH_FINALIZER_SYNTHESIZE_NOT_IMPLEMENTED' | 'GRAPH_FINALIZER_SYNTHESIZE_FAILED';
+export type FinalizerErrorPayload = {
+    code: FinalizerErrorCode;
+    message: string;
+    finalizerNodeId: string;
+    path?: string;
+    details?: Record<string, unknown>;
+};
+export declare function createFinalizerError(payload: FinalizerErrorPayload): Error & FinalizerErrorPayload;

package/dist/src/runtime/finalizers/errors.js

@@ -0,0 +1,10 @@
+export function createFinalizerError(payload) {
+    const err = new Error(payload.message);
+    err.code = payload.code;
+    err.finalizerNodeId = payload.finalizerNodeId;
+    if (payload.path)
+        err.path = payload.path;
+    if (payload.details)
+        err.details = payload.details;
+    return err;
+}

package/dist/src/runtime/finalizers/executeFinalizer.d.ts

@@ -0,0 +1,40 @@
+import type { FinalizerInputBinding, FinalizerNode, Graph, SynthesizeFinalizerConfig } from '../../types/refs.js';
+export declare function resolveFinalizerInputs(args: {
+    finalizerNodeId: string;
+    bindings: Record<string, FinalizerInputBinding>;
+    executionMemory: unknown;
+    outputsMemory?: unknown;
+}): Record<string, unknown>;
+export declare function executeSynthesizeFinalizer(args: {
+    finalizer: FinalizerNode;
+    config: SynthesizeFinalizerConfig;
+    executionMemory: unknown;
+    outputsMemory?: unknown;
+    runTask: (req: {
+        skillKey: string;
+        input?: any;
+        jobId?: string;
+        taskId?: string;
+        agentId?: string;
+        skillId?: string;
+        masterSkillId?: string;
+    }) => Promise<any>;
+    context: {
+        graphId: string;
+        jobId?: string;
+        taskId?: string;
+        agentId?: string;
+    };
+}): Promise<{
+    parsed: any;
+    rawContent?: string;
+    diagnostics?: any;
+}>;
+export declare function executeDeterministicFinalizer(args: {
+    finalizer: FinalizerNode;
+    executionMemory: unknown;
+    outputsMemory?: unknown;
+    graph?: Graph;
+}): {
+    parsed: any;
+};

package/dist/src/runtime/finalizers/executeFinalizer.js

@@ -0,0 +1,471 @@
+import { createFinalizerError } from './errors.js';
+import { validateAgainstOutputSchema } from './schema.js';
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+/** Value written by graphenix when a task node fails (`{ failed: true, error, reason }`). */
+function isNodeFailureMarker(v) {
+    if (!isPlainObject(v))
+        return false;
+    return v.failed === true && ('error' in v || 'reason' in v);
+}
+function getByDotPath(root, path) {
+    if (!path)
+        return root;
+    const parts = path.split('.').filter(Boolean);
+    let cur = root;
+    for (const p of parts) {
+        if (cur == null)
+            return undefined;
+        if (typeof cur !== 'object')
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+function asArrayNodes(graph) {
+    return Array.isArray(graph.nodes) ? graph.nodes : Object.values(graph.nodes ?? {});
+}
+function getNodeById(graph, nodeId) {
+    return asArrayNodes(graph).find((n) => String(n?.id) === String(nodeId));
+}
+export function resolveFinalizerInputs(args) {
+    const out = {};
+    for (const [name, b] of Object.entries(args.bindings ?? {})) {
+        if (b.type === 'literal') {
+            out[name] = b.value;
+            continue;
+        }
+        if (b.type === 'executionMemoryPath') {
+            let v = getByDotPath(args.executionMemory, b.path);
+            if (isNodeFailureMarker(v)) {
+                if (b.optional === true) {
+                    out[name] = null;
+                    continue;
+                }
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_NODE_FAILED',
+                    message: `Finalizer input "${name}" points at a failed graph node (executionMemoryPath="${b.path}")`,
+                    finalizerNodeId: args.finalizerNodeId,
+                    path: `inputs.${name}`,
+                    details: { binding: b, marker: v },
+                });
+            }
+            if ((v === undefined || v === null) && b.optional !== true) {
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_INPUT_MISSING',
+                    message: `Finalizer input missing: "${name}" (executionMemoryPath="${b.path}")`,
+                    finalizerNodeId: args.finalizerNodeId,
+                    path: `inputs.${name}`,
+                    details: { binding: b },
+                });
+            }
+            out[name] = v;
+            continue;
+        }
+        if (b.type === 'outputsMemoryPath') {
+            let v = getByDotPath(args.outputsMemory, b.path);
+            if (isNodeFailureMarker(v)) {
+                if (b.optional === true) {
+                    out[name] = null;
+                    continue;
+                }
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_NODE_FAILED',
+                    message: `Finalizer input "${name}" points at a failed graph node (outputsMemoryPath="${b.path}")`,
+                    finalizerNodeId: args.finalizerNodeId,
+                    path: `inputs.${name}`,
+                    details: { binding: b, marker: v },
+                });
+            }
+            if ((v === undefined || v === null) && b.optional !== true) {
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_INPUT_MISSING',
+                    message: `Finalizer input missing: "${name}" (outputsMemoryPath="${b.path}")`,
+                    finalizerNodeId: args.finalizerNodeId,
+                    path: `inputs.${name}`,
+                    details: { binding: b },
+                });
+            }
+            out[name] = v;
+            continue;
+        }
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `Unsupported finalizer input binding type "${String(b.type)}"`,
+            finalizerNodeId: args.finalizerNodeId,
+            path: `inputs.${name}.type`,
+        });
+    }
+    return out;
+}
+function executeAggregate(finalizer, cfg, inputs) {
+    const out = {};
+    for (const [k, expr] of Object.entries(cfg.map ?? {})) {
+        if (expr.kind === 'literal')
+            out[k] = expr.value;
+        else if (expr.kind === 'input') {
+            if (!(expr.name in inputs)) {
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_INVALID',
+                    message: `Aggregate finalizer map references missing input name "${expr.name}"`,
+                    finalizerNodeId: String(finalizer.id),
+                    path: `config.map.${k}`,
+                    details: { mapKey: k, inputName: expr.name, availableInputs: Object.keys(inputs) },
+                });
+            }
+            out[k] = inputs[expr.name];
+        }
+    }
+    if (cfg.omitUndefined) {
+        for (const [k, v] of Object.entries(out))
+            if (v === undefined)
+                delete out[k];
+    }
+    return out;
+}
+function executeAggregateQuestionDriven(args) {
+    const finalizerNodeId = String(args.finalizer.id);
+    const out = {};
+    if (args.cfg.contractVersion !== undefined)
+        out.contractVersion = args.cfg.contractVersion;
+    if (args.cfg.meta) {
+        const metaOut = {};
+        for (const [k, b] of Object.entries(args.cfg.meta)) {
+            const root = b.type === 'outputsMemoryPath' ? args.outputsMemory : args.executionMemory;
+            let v = getByDotPath(root, b.path);
+            if (isNodeFailureMarker(v)) {
+                if (b.optional === true) {
+                    metaOut[k] = null;
+                    continue;
+                }
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_NODE_FAILED',
+                    message: `Finalizer meta "${k}" points at a failed graph node (${b.type}="${b.path}")`,
+                    finalizerNodeId,
+                    path: `config.meta.${k}`,
+                    details: { binding: b, marker: v },
+                });
+            }
+            if ((v === undefined || v === null) && b.optional !== true) {
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_INPUT_MISSING',
+                    message: `Finalizer meta missing: "${k}" (${b.type}="${b.path}")`,
+                    finalizerNodeId,
+                    path: `config.meta.${k}`,
+                    details: { binding: b },
+                });
+            }
+            metaOut[k] = v;
+        }
+        out.meta = metaOut;
+    }
+    for (const [outKey, spec] of Object.entries(args.cfg.items ?? {})) {
+        const nodeId = String(spec.nodeId);
+        const node = getNodeById(args.graph, nodeId);
+        if (!node) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `question-driven finalizer references missing nodeId "${nodeId}"`,
+                finalizerNodeId,
+                path: `config.items.${outKey}.nodeId`,
+            });
+        }
+        const questionPath = spec.questionPath ?? 'inputs.question';
+        const question = getByDotPath(node, questionPath);
+        if (typeof question !== 'string' || question.length === 0) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `question-driven finalizer could not read a non-empty question at ${questionPath} for node "${nodeId}"`,
+                finalizerNodeId,
+                path: `config.items.${outKey}.questionPath`,
+                details: { nodeId, questionPath, actual: question },
+            });
+        }
+        const defaultAnswerPath = node?.executionMapping?.path;
+        const answerPath = spec.answerPath ?? (typeof defaultAnswerPath === 'string' ? defaultAnswerPath : undefined);
+        if (!answerPath) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `question-driven finalizer needs answerPath or node.executionMapping.path for node "${nodeId}"`,
+                finalizerNodeId,
+                path: `config.items.${outKey}.answerPath`,
+                details: { nodeId },
+            });
+        }
+        const answer = getByDotPath(args.executionMemory, answerPath);
+        if (isNodeFailureMarker(answer)) {
+            if (spec.optional === true) {
+                out[outKey] = { question, answer: null };
+                continue;
+            }
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_NODE_FAILED',
+                message: `question-driven item "${outKey}": answer unavailable (upstream node "${nodeId}" failed)`,
+                finalizerNodeId,
+                path: `config.items.${outKey}`,
+                details: { nodeId, answerPath },
+            });
+        }
+        out[outKey] = { question, answer };
+    }
+    return out;
+}
+function executeBundle(finalizer, cfg, inputs) {
+    const out = {};
+    for (const name of cfg.includeInputs ?? [])
+        out[name] = inputs[name];
+    return out;
+}
+function executeSelect(finalizer, cfg, inputs) {
+    const sel = cfg.selector;
+    if (sel.type === 'firstPresent') {
+        const order = Array.isArray(sel.order) && sel.order.length ? sel.order : Object.keys(inputs);
+        for (const k of order) {
+            const v = inputs[k];
+            if (v !== undefined && v !== null && !isNodeFailureMarker(v))
+                return v;
+        }
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_OUTPUT_INVALID',
+            message: `Select finalizer: no present inputs for firstPresent`,
+            finalizerNodeId: String(finalizer.id),
+            details: { order },
+        });
+    }
+    if (sel.type === 'byInputValue') {
+        const selectorInput = sel.selectorInput;
+        if (!selectorInput) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `Select finalizer byInputValue requires selectorInput`,
+                finalizerNodeId: String(finalizer.id),
+                path: 'config.selector.selectorInput',
+            });
+        }
+        const v = inputs[selectorInput];
+        const key = typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' ? String(v) : undefined;
+        const targetName = key != null ? sel.cases?.[key] : undefined;
+        if (!targetName) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_OUTPUT_INVALID',
+                message: `Select finalizer: no case match for selector value`,
+                finalizerNodeId: String(finalizer.id),
+                path: `inputs.${selectorInput}`,
+                details: { selectorValue: v, cases: sel.cases ?? {} },
+            });
+        }
+        return inputs[targetName];
+    }
+    throw createFinalizerError({
+        code: 'GRAPH_FINALIZER_INVALID',
+        message: `Unsupported select selector type "${String(sel.type)}"`,
+        finalizerNodeId: String(finalizer.id),
+        path: 'config.selector.type',
+    });
+}
+const EPISTEMIC_TAGS = ['CONFIRMED', 'INFERRED', 'ASSUMED', 'UNKNOWN'];
+function collectEpistemicTags(value, found) {
+    if (value == null)
+        return;
+    if (typeof value === 'string' && EPISTEMIC_TAGS.includes(value)) {
+        found.add(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectEpistemicTags(item, found);
+        return;
+    }
+    if (typeof value === 'object') {
+        for (const v of Object.values(value)) {
+            collectEpistemicTags(v, found);
+        }
+    }
+}
+function executeReportSchema(args) {
+    const { cfg, executionMemory } = args;
+    const finalizerNodeId = String(args.finalizer.id);
+    const out = {};
+    for (const [key, spec] of Object.entries(cfg.sections ?? {})) {
+        let v = getByDotPath(executionMemory, spec.path);
+        if (isNodeFailureMarker(v)) {
+            if (spec.optional === true) {
+                out[key] = null;
+                continue;
+            }
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_NODE_FAILED',
+                message: `report-schema: section "${key}" points at a failed graph node (path="${spec.path}")`,
+                finalizerNodeId,
+                path: `config.sections.${key}`,
+                details: { spec, marker: v },
+            });
+        }
+        if ((v === undefined || v === null) && spec.optional !== true) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INPUT_MISSING',
+                message: `report-schema: required section "${key}" not found at path "${spec.path}"`,
+                finalizerNodeId,
+                path: `config.sections.${key}`,
+                details: { spec },
+            });
+        }
+        out[key] = v ?? null;
+    }
+    if (cfg.collect_tags) {
+        const tags = new Set();
+        for (const v of Object.values(out))
+            collectEpistemicTags(v, tags);
+        out.collected_tags = Array.from(tags);
+    }
+    if (cfg.meta) {
+        for (const [k, v] of Object.entries(cfg.meta)) {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function validateSchemaOrThrow(finalizer, parsed) {
+    if (finalizer.outputSchema == null)
+        return;
+    const schema = finalizer.outputSchema;
+    const res = validateAgainstOutputSchema(parsed, schema);
+    if (!res.ok) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_OUTPUT_INVALID',
+            message: `Finalizer output did not match outputSchema`,
+            finalizerNodeId: String(finalizer.id),
+            details: { errors: res.errors },
+        });
+    }
+}
+export async function executeSynthesizeFinalizer(args) {
+    const finalizer = args.finalizer;
+    const finalizerNodeId = String(finalizer.id);
+    const inputs = resolveFinalizerInputs({
+        finalizerNodeId,
+        bindings: finalizer.inputs ?? {},
+        executionMemory: args.executionMemory,
+        outputsMemory: args.outputsMemory,
+    });
+    const req = {
+        skillKey: args.config.utilityKey,
+        jobId: args.context.jobId,
+        taskId: args.context.taskId,
+        agentId: args.context.agentId,
+        skillId: finalizerNodeId,
+        masterSkillId: args.context.graphId,
+        input: {
+            templateId: args.config.templateId,
+            inputs,
+            ...(args.config.outputContractId ? { outputContractId: args.config.outputContractId } : {}),
+            ...(args.config.executionPolicy ? { executionPolicy: args.config.executionPolicy } : {}),
+            metadata: {
+                graphId: args.context.graphId,
+                finalizerNodeId,
+                ...(args.context.jobId ? { jobId: args.context.jobId } : {}),
+                ...(args.context.taskId ? { taskId: args.context.taskId } : {}),
+            },
+        },
+    };
+    let res;
+    try {
+        res = await args.runTask(req);
+    }
+    catch (e) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_SYNTHESIZE_FAILED',
+            message: e?.message ?? 'Synthesize finalizer runTask failed',
+            finalizerNodeId,
+            details: { error: e },
+        });
+    }
+    if (!res || res.ok !== true) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_SYNTHESIZE_FAILED',
+            message: res?.error?.message ?? 'Synthesize finalizer failed',
+            finalizerNodeId,
+            details: { error: res?.error, response: res },
+        });
+    }
+    const parsed = res.parsed;
+    if (parsed === undefined) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_SYNTHESIZE_FAILED',
+            message: 'Synthesize finalizer returned no parsed output',
+            finalizerNodeId,
+            details: { response: res },
+        });
+    }
+    validateSchemaOrThrow(finalizer, parsed);
+    return { parsed, rawContent: res.rawContent, diagnostics: res.diagnostics };
+}
+export function executeDeterministicFinalizer(args) {
+    const finalizer = args.finalizer;
+    const finalizerNodeId = String(finalizer.id);
+    const inputs = resolveFinalizerInputs({
+        finalizerNodeId,
+        bindings: finalizer.inputs ?? {},
+        executionMemory: args.executionMemory,
+        outputsMemory: args.outputsMemory,
+    });
+    const ft = finalizer.finalizerType;
+    const cfg = finalizer.config;
+    let parsed;
+    if (ft === 'aggregate') {
+        if (cfg?.strategy === 'question-driven') {
+            if (!args.graph) {
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_INVALID',
+                    message: `question-driven aggregate finalizer requires graph context`,
+                    finalizerNodeId,
+                    path: 'config.strategy',
+                });
+            }
+            parsed = executeAggregateQuestionDriven({
+                finalizer,
+                cfg: cfg,
+                executionMemory: args.executionMemory,
+                outputsMemory: args.outputsMemory,
+                graph: args.graph,
+            });
+        }
+        else if (cfg?.strategy === 'report-schema') {
+            parsed = executeReportSchema({
+                finalizer,
+                cfg: cfg,
+                executionMemory: args.executionMemory,
+                outputsMemory: args.outputsMemory,
+            });
+        }
+        else {
+            parsed = executeAggregate(finalizer, cfg, inputs);
+        }
+        validateSchemaOrThrow(finalizer, parsed);
+        return { parsed };
+    }
+    if (ft === 'bundle') {
+        parsed = executeBundle(finalizer, cfg, inputs);
+        validateSchemaOrThrow(finalizer, parsed);
+        return { parsed };
+    }
+    if (ft === 'select') {
+        parsed = executeSelect(finalizer, cfg, inputs);
+        validateSchemaOrThrow(finalizer, parsed);
+        return { parsed };
+    }
+    if (ft === 'synthesize') {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_SYNTHESIZE_NOT_IMPLEMENTED',
+            message: `Synthesize finalizer requires AI-backed execution`,
+            finalizerNodeId,
+            details: { config: cfg },
+        });
+    }
+    throw createFinalizerError({
+        code: 'GRAPH_FINALIZER_INVALID',
+        message: `Unsupported finalizerType "${String(ft)}"`,
+        finalizerNodeId,
+    });
+}