@exellix/graph-engine 6.0.0

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

@@ -0,0 +1,18 @@
+import type { OutputSchema } from '../../types/refs.js';
+export type SchemaValidationError = {
+    path: string;
+    expected: string;
+    actual: string;
+};
+export declare function validateOutputSchemaShape(schema: unknown): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function validateAgainstOutputSchema(output: unknown, schema: OutputSchema): {
+    ok: true;
+} | {
+    ok: false;
+    errors: SchemaValidationError[];
+};

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

@@ -0,0 +1,63 @@
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+export function validateOutputSchemaShape(schema) {
+    if (schema == null)
+        return { ok: true };
+    if (!isPlainObject(schema))
+        return { ok: false, message: 'outputSchema must be an object schema' };
+    const s = schema;
+    if (s.type !== 'object')
+        return { ok: false, message: 'outputSchema.type must be "object"' };
+    if (s.required != null && !Array.isArray(s.required))
+        return { ok: false, message: 'outputSchema.required must be an array of strings' };
+    if (s.properties != null && !isPlainObject(s.properties))
+        return { ok: false, message: 'outputSchema.properties must be an object' };
+    if (s.additionalProperties != null && typeof s.additionalProperties !== 'boolean') {
+        return { ok: false, message: 'outputSchema.additionalProperties must be boolean' };
+    }
+    return { ok: true };
+}
+export function validateAgainstOutputSchema(output, schema) {
+    const errors = [];
+    if (!isPlainObject(output)) {
+        errors.push({
+            path: '$',
+            expected: 'object',
+            actual: Array.isArray(output) ? 'array' : output === null ? 'null' : typeof output,
+        });
+        return { ok: false, errors };
+    }
+    const out = output;
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const k of required) {
+        if (out[k] === undefined) {
+            errors.push({ path: `$.${k}`, expected: 'present', actual: 'missing' });
+        }
+    }
+    const props = schema.properties ?? {};
+    for (const [k, def] of Object.entries(props)) {
+        if (out[k] === undefined)
+            continue;
+        const expected = def?.type;
+        if (!expected)
+            continue;
+        const v = out[k];
+        const actual = Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v === 'object' ? 'object' : typeof v;
+        const ok = (expected === 'string' && typeof v === 'string') ||
+            (expected === 'number' && typeof v === 'number') ||
+            (expected === 'boolean' && typeof v === 'boolean') ||
+            (expected === 'array' && Array.isArray(v)) ||
+            (expected === 'object' && isPlainObject(v));
+        if (!ok)
+            errors.push({ path: `$.${k}`, expected, actual });
+    }
+    if (schema.additionalProperties === false) {
+        const allowed = new Set(Object.keys(props));
+        for (const k of Object.keys(out)) {
+            if (!allowed.has(k))
+                errors.push({ path: `$.${k}`, expected: 'not allowed', actual: 'present' });
+        }
+    }
+    return errors.length ? { ok: false, errors } : { ok: true };
+}

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

@@ -0,0 +1,16 @@
+import type { FinalizerNode, Graph } from '../../types/refs.js';
+export type RequiredFinalizerExecutionMemoryRead = {
+    memory: 'execution' | 'outputs';
+    path: string;
+    sources: string[];
+};
+export declare function collectRequiredFinalizerExecutionMemoryReads(finalizer: FinalizerNode, graph?: Graph): RequiredFinalizerExecutionMemoryRead[];
+export declare function assertFinalizerRequiredReadsResolvable(args: {
+    graph: Graph;
+    finalizer: FinalizerNode;
+    executionMemory: unknown;
+    outputsMemory?: unknown;
+}): void;
+export declare function validateGraphFinalizer(graph: Graph): {
+    finalizer: FinalizerNode;
+};

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

@@ -0,0 +1,534 @@
+import { createFinalizerError } from './errors.js';
+import { validateOutputSchemaShape } from './schema.js';
+function asArrayNodes(graph) {
+    return Array.isArray(graph.nodes) ? graph.nodes : Object.values(graph.nodes ?? {});
+}
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(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 memoryPathsMatch(a, b) {
+    return a === b || a.startsWith(b + '.') || b.startsWith(a + '.');
+}
+function pushRequiredRead(reads, memory, path, source, optional) {
+    if (optional === true || typeof path !== 'string' || path.length === 0)
+        return;
+    const existing = reads.find((read) => read.memory === memory && read.path === path);
+    if (existing) {
+        if (!existing.sources.includes(source))
+            existing.sources.push(source);
+        return;
+    }
+    reads.push({ memory, path, sources: [source] });
+}
+function getNodeById(graph, nodeId) {
+    return asArrayNodes(graph).find((n) => String(n?.id) === String(nodeId));
+}
+export function collectRequiredFinalizerExecutionMemoryReads(finalizer, graph) {
+    const reads = [];
+    for (const [name, binding] of Object.entries(finalizer.inputs ?? {})) {
+        if (binding.type === 'executionMemoryPath') {
+            pushRequiredRead(reads, 'execution', binding.path, `inputs.${name}`, binding.optional);
+        }
+        else if (binding.type === 'outputsMemoryPath') {
+            pushRequiredRead(reads, 'outputs', binding.path, `inputs.${name}`, binding.optional);
+        }
+    }
+    const cfg = finalizer.config;
+    if (finalizer.finalizerType !== 'aggregate' || !isPlainObject(cfg)) {
+        return reads;
+    }
+    if (cfg.strategy === 'report-schema' && isPlainObject(cfg.sections)) {
+        for (const [key, spec] of Object.entries(cfg.sections)) {
+            if (!isPlainObject(spec))
+                continue;
+            pushRequiredRead(reads, 'execution', spec.path, `config.sections.${key}`, spec.optional);
+        }
+        return reads;
+    }
+    if (cfg.strategy === 'question-driven') {
+        if (isPlainObject(cfg.meta)) {
+            for (const [key, binding] of Object.entries(cfg.meta)) {
+                if (!isPlainObject(binding))
+                    continue;
+                if (binding.type === 'executionMemoryPath') {
+                    pushRequiredRead(reads, 'execution', binding.path, `config.meta.${key}`, binding.optional);
+                }
+                else if (binding.type === 'outputsMemoryPath') {
+                    pushRequiredRead(reads, 'outputs', binding.path, `config.meta.${key}`, binding.optional);
+                }
+            }
+        }
+        if (isPlainObject(cfg.items)) {
+            for (const [key, spec] of Object.entries(cfg.items)) {
+                if (!isPlainObject(spec) || spec.optional === true)
+                    continue;
+                if (typeof spec.answerPath === 'string' && spec.answerPath.length > 0) {
+                    pushRequiredRead(reads, 'execution', spec.answerPath, `config.items.${key}.answerPath`, false);
+                    continue;
+                }
+                const nodeId = typeof spec.nodeId === 'string' ? spec.nodeId : undefined;
+                const node = nodeId && graph ? getNodeById(graph, nodeId) : undefined;
+                const defaultAnswerPath = node?.executionMapping?.path;
+                pushRequiredRead(reads, 'execution', defaultAnswerPath, `config.items.${key}.node.executionMapping.path`, false);
+            }
+        }
+    }
+    return reads;
+}
+function reachableFrom(from, to, outgoingByFrom) {
+    if (from === to)
+        return true;
+    const seen = new Set();
+    const q = [from];
+    while (q.length) {
+        const cur = q.shift();
+        if (cur === to)
+            return true;
+        if (seen.has(cur))
+            continue;
+        seen.add(cur);
+        for (const nxt of outgoingByFrom.get(cur) ?? []) {
+            if (!seen.has(nxt))
+                q.push(nxt);
+        }
+    }
+    return false;
+}
+export function assertFinalizerRequiredReadsResolvable(args) {
+    const { graph, finalizer, executionMemory, outputsMemory } = args;
+    const finalizerNodeId = String(finalizer.id);
+    const reads = collectRequiredFinalizerExecutionMemoryReads(finalizer, graph);
+    if (reads.length === 0)
+        return;
+    const outgoingByFrom = new Map();
+    const edges = Array.isArray(graph.edges) ? graph.edges : [];
+    for (const edge of edges) {
+        const from = edge?.from;
+        const to = edge?.to;
+        if (typeof from !== 'string' || typeof to !== 'string')
+            continue;
+        const list = outgoingByFrom.get(from) ?? [];
+        list.push(to);
+        outgoingByFrom.set(from, list);
+    }
+    const writers = asArrayNodes(graph)
+        .filter((node) => node?.type !== 'finalizer')
+        .map((node) => ({
+        nodeId: String(node.id),
+        executionPath: node?.executionMapping?.path,
+    }))
+        .flatMap((writer) => {
+        const out = [];
+        if (typeof writer.executionPath === 'string' && writer.executionPath.length > 0) {
+            out.push({ nodeId: writer.nodeId, memory: 'execution', path: writer.executionPath });
+        }
+        return out;
+    });
+    for (const read of reads) {
+        const seededValue = getByDotPath(read.memory === 'outputs' ? outputsMemory : executionMemory, read.path);
+        if (seededValue !== undefined && seededValue !== null)
+            continue;
+        const matchingWriters = writers.filter((writer) => writer.memory === read.memory && memoryPathsMatch(read.path, writer.path));
+        if (matchingWriters.length === 0) {
+            const selectorType = read.memory === 'outputs' ? 'outputsMemoryPath' : 'executionMemoryPath';
+            const writerField = read.memory === 'outputs' ? 'runtime.outputsMemory seed' : 'executionMapping.path';
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INPUT_MISSING',
+                message: `Finalizer required input has no ${read.memory} seed or upstream ${writerField} writer (${selectorType}="${read.path}")`,
+                finalizerNodeId,
+                path: read.sources[0],
+                details: {
+                    reason: 'missing-writer',
+                    read,
+                    graphId: graph.id,
+                },
+            });
+        }
+        const reachableWriters = matchingWriters.filter((writer) => reachableFrom(writer.nodeId, finalizerNodeId, outgoingByFrom));
+        if (reachableWriters.length === 0) {
+            const selectorType = read.memory === 'outputs' ? 'outputsMemoryPath' : 'executionMemoryPath';
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INPUT_MISSING',
+                message: `Finalizer required input writer is not ordered before finalizer (${selectorType}="${read.path}")`,
+                finalizerNodeId,
+                path: read.sources[0],
+                details: {
+                    reason: 'missing-dependency-edge',
+                    read,
+                    matchingWriters,
+                    expectedReachability: matchingWriters.map((writer) => ({
+                        from: writer.nodeId,
+                        to: finalizerNodeId,
+                    })),
+                    graphId: graph.id,
+                },
+            });
+        }
+    }
+}
+function validateBinding(name, b, finalizerNodeId) {
+    if (!isPlainObject(b)) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `Finalizer input "${name}" must be an object binding`,
+            finalizerNodeId,
+            path: `inputs.${name}`,
+            details: { binding: b },
+        });
+    }
+    const type = b.type;
+    if (type === 'executionMemoryPath' || type === 'outputsMemoryPath') {
+        const path = b.path;
+        if (typeof path !== 'string' || path.length === 0) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `Finalizer input "${name}" ${type} requires a non-empty path`,
+                finalizerNodeId,
+                path: `inputs.${name}.path`,
+            });
+        }
+        const optional = b.optional;
+        if (optional !== undefined && typeof optional !== 'boolean') {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `Finalizer input "${name}" optional must be boolean`,
+                finalizerNodeId,
+                path: `inputs.${name}.optional`,
+            });
+        }
+        return;
+    }
+    if (type === 'literal')
+        return;
+    throw createFinalizerError({
+        code: 'GRAPH_FINALIZER_INVALID',
+        message: `Finalizer input "${name}" has unsupported binding type "${String(type)}"`,
+        finalizerNodeId,
+        path: `inputs.${name}.type`,
+    });
+}
+function validateAggregateConfig(cfg, finalizerNodeId) {
+    if (!isPlainObject(cfg) || typeof cfg.strategy !== 'string') {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `Aggregate finalizer requires config.strategy`,
+            finalizerNodeId,
+            path: 'config.strategy',
+            details: { config: cfg },
+        });
+    }
+    const strategy = cfg.strategy;
+    if (strategy === 'object-map') {
+        if (!isPlainObject(cfg.map)) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `Aggregate finalizer requires config.map`,
+                finalizerNodeId,
+                path: 'config.map',
+                details: { config: cfg },
+            });
+        }
+        return;
+    }
+    if (strategy === 'report-schema') {
+        const sections = cfg.sections;
+        if (sections !== undefined && !isPlainObject(sections)) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `report-schema aggregate finalizer config.sections must be an object when provided`,
+                finalizerNodeId,
+                path: 'config.sections',
+                details: { config: cfg },
+            });
+        }
+        if (isPlainObject(sections)) {
+            for (const [k, spec] of Object.entries(sections)) {
+                if (!isPlainObject(spec) || typeof spec.path !== 'string' || spec.path.length === 0) {
+                    throw createFinalizerError({
+                        code: 'GRAPH_FINALIZER_INVALID',
+                        message: `report-schema section "${k}" must have a non-empty path`,
+                        finalizerNodeId,
+                        path: `config.sections.${k}.path`,
+                        details: { spec },
+                    });
+                }
+                const optional = spec.optional;
+                if (optional !== undefined && typeof optional !== 'boolean') {
+                    throw createFinalizerError({
+                        code: 'GRAPH_FINALIZER_INVALID',
+                        message: `report-schema section "${k}" optional must be boolean when provided`,
+                        finalizerNodeId,
+                        path: `config.sections.${k}.optional`,
+                    });
+                }
+            }
+        }
+        const collectTags = cfg.collect_tags;
+        if (collectTags !== undefined && typeof collectTags !== 'boolean') {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `report-schema aggregate finalizer config.collect_tags must be boolean when provided`,
+                finalizerNodeId,
+                path: 'config.collect_tags',
+            });
+        }
+        const meta = cfg.meta;
+        if (meta !== undefined && !isPlainObject(meta)) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `report-schema aggregate finalizer config.meta must be an object when provided`,
+                finalizerNodeId,
+                path: 'config.meta',
+            });
+        }
+        return;
+    }
+    if (strategy === 'question-driven') {
+        if (!isPlainObject(cfg.items)) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `question-driven aggregate finalizer requires config.items`,
+                finalizerNodeId,
+                path: 'config.items',
+                details: { config: cfg },
+            });
+        }
+        for (const [k, spec] of Object.entries(cfg.items)) {
+            if (!isPlainObject(spec) || typeof spec.nodeId !== 'string' || spec.nodeId.length === 0) {
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_INVALID',
+                    message: `question-driven item "${k}" must specify a non-empty nodeId`,
+                    finalizerNodeId,
+                    path: `config.items.${k}.nodeId`,
+                    details: { item: spec },
+                });
+            }
+            const qp = spec.questionPath;
+            if (qp !== undefined && (typeof qp !== 'string' || qp.length === 0)) {
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_INVALID',
+                    message: `question-driven item "${k}" questionPath must be a non-empty string when provided`,
+                    finalizerNodeId,
+                    path: `config.items.${k}.questionPath`,
+                });
+            }
+            const ap = spec.answerPath;
+            if (ap !== undefined && (typeof ap !== 'string' || ap.length === 0)) {
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_INVALID',
+                    message: `question-driven item "${k}" answerPath must be a non-empty string when provided`,
+                    finalizerNodeId,
+                    path: `config.items.${k}.answerPath`,
+                });
+            }
+        }
+        if (cfg.meta !== undefined && !isPlainObject(cfg.meta)) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `question-driven aggregate finalizer meta must be an object when provided`,
+                finalizerNodeId,
+                path: 'config.meta',
+            });
+        }
+        return;
+    }
+    throw createFinalizerError({
+        code: 'GRAPH_FINALIZER_INVALID',
+        message: `Unsupported aggregate config.strategy "${String(strategy)}"`,
+        finalizerNodeId,
+        path: 'config.strategy',
+        details: { config: cfg },
+    });
+}
+function validateBundleConfig(cfg, finalizerNodeId) {
+    if (!isPlainObject(cfg) || cfg.strategy !== 'bundle' || !Array.isArray(cfg.includeInputs)) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `Bundle finalizer requires config.strategy="bundle" and includeInputs[]`,
+            finalizerNodeId,
+            path: 'config',
+            details: { config: cfg },
+        });
+    }
+}
+function validateSelectConfig(cfg, finalizerNodeId) {
+    if (!isPlainObject(cfg) || cfg.strategy !== 'select' || !isPlainObject(cfg.selector)) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `Select finalizer requires config.strategy="select" and selector`,
+            finalizerNodeId,
+            path: 'config',
+            details: { config: cfg },
+        });
+    }
+}
+function validateSynthesizeConfig(cfg, finalizerNodeId) {
+    if (!isPlainObject(cfg) || cfg.strategy !== 'synthesize') {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `Synthesize finalizer requires config.strategy="synthesize"`,
+            finalizerNodeId,
+            path: 'config',
+            details: { config: cfg },
+        });
+    }
+    const utilityKey = cfg.utilityKey;
+    const templateId = cfg.templateId;
+    if (typeof utilityKey !== 'string' || utilityKey.length === 0) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `Synthesize finalizer requires a non-empty config.utilityKey`,
+            finalizerNodeId,
+            path: 'config.utilityKey',
+        });
+    }
+    if (typeof templateId !== 'string' || templateId.length === 0) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `Synthesize finalizer requires a non-empty config.templateId`,
+            finalizerNodeId,
+            path: 'config.templateId',
+        });
+    }
+}
+export function validateGraphFinalizer(graph) {
+    const nodes = asArrayNodes(graph);
+    const finalizers = nodes.filter((n) => n?.type === 'finalizer');
+    if (finalizers.length !== 1) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `Executable graph must have exactly one finalizer node (found ${finalizers.length})`,
+            finalizerNodeId: finalizers[0]?.id ?? '(none)',
+            details: { graphId: graph.id, finalizerCount: finalizers.length },
+        });
+    }
+    const finalizer = finalizers[0];
+    const finalizerNodeId = String(finalizer.id);
+    const ft = finalizer.finalizerType;
+    if (typeof ft !== 'string' || ft.length === 0) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: 'Finalizer must specify finalizerType',
+            finalizerNodeId,
+            path: 'finalizerType',
+        });
+    }
+    const edges = Array.isArray(graph.edges) ? graph.edges : [];
+    const out = edges.filter((e) => e && typeof e === 'object' && e.from === finalizerNodeId);
+    if (out.length > 0) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `Finalizer node "${finalizerNodeId}" must have no outgoing edges`,
+            finalizerNodeId,
+            details: { outgoingEdges: out.length },
+        });
+    }
+    // Reachability (conservative: treat all edges as potentially active).
+    const incomingByTo = new Map();
+    const outgoingByFrom = new Map();
+    for (const e of edges) {
+        const from = e?.from;
+        const to = e?.to;
+        if (typeof from !== 'string' || typeof to !== 'string')
+            continue;
+        (incomingByTo.get(to) ?? incomingByTo.set(to, []).get(to)).push(from);
+        (outgoingByFrom.get(from) ?? outgoingByFrom.set(from, []).get(from)).push(to);
+    }
+    const nodeIds = new Set(nodes.map((n) => String(n.id)));
+    const roots = Array.from(nodeIds).filter((id) => (incomingByTo.get(id) ?? []).length === 0);
+    const seen = new Set();
+    const q = [...roots];
+    while (q.length) {
+        const cur = q.shift();
+        if (seen.has(cur))
+            continue;
+        seen.add(cur);
+        for (const nxt of outgoingByFrom.get(cur) ?? [])
+            if (!seen.has(nxt))
+                q.push(nxt);
+    }
+    if (!seen.has(finalizerNodeId)) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_UNREACHABLE',
+            message: `Finalizer node "${finalizerNodeId}" must be reachable from at least one start path`,
+            finalizerNodeId,
+            details: { roots },
+        });
+    }
+    if (!isPlainObject(finalizer.inputs)) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: 'Finalizer must specify inputs as an object',
+            finalizerNodeId,
+            path: 'inputs',
+        });
+    }
+    for (const [name, b] of Object.entries(finalizer.inputs)) {
+        validateBinding(name, b, finalizerNodeId);
+    }
+    if (finalizer.config == null) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: 'Finalizer must specify config',
+            finalizerNodeId,
+            path: 'config',
+        });
+    }
+    // Validate outputSchema shape (type + basic fields)
+    if (finalizer.outputSchema != null) {
+        const shape = validateOutputSchemaShape(finalizer.outputSchema);
+        if (!shape.ok) {
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `Invalid outputSchema: ${shape.message}`,
+                finalizerNodeId,
+                path: 'outputSchema',
+            });
+        }
+    }
+    // Config shape by finalizerType (implemented now)
+    const cfg = finalizer.config;
+    switch (ft) {
+        case 'aggregate':
+            validateAggregateConfig(cfg, finalizerNodeId);
+            break;
+        case 'bundle':
+            validateBundleConfig(cfg, finalizerNodeId);
+            break;
+        case 'select':
+            validateSelectConfig(cfg, finalizerNodeId);
+            break;
+        case 'synthesize':
+            validateSynthesizeConfig(cfg, finalizerNodeId);
+            break;
+        case 'compose':
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `Finalizer type "compose" is not implemented in this runtime yet`,
+                finalizerNodeId,
+                path: 'finalizerType',
+            });
+        default:
+            throw createFinalizerError({
+                code: 'GRAPH_FINALIZER_INVALID',
+                message: `Unsupported finalizerType "${String(ft)}"`,
+                finalizerNodeId,
+                path: 'finalizerType',
+            });
+    }
+    return { finalizer };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * JSON.stringify with sorted object keys (recursive) so equivalent documents hash identically.
+ */
+export declare function stableStringifyGraphDocument(value: unknown): string;
+/**
+ * SHA-256 (hex) of the stable JSON encoding of `graph`, for audit trails and matrix persistence.
+ */
+export declare function computeGraphDocumentContentSha256(graph: unknown): string;

package/dist/src/runtime/graphDocumentFingerprint.js

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto';
+/**
+ * JSON.stringify with sorted object keys (recursive) so equivalent documents hash identically.
+ */
+export function stableStringifyGraphDocument(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => stableStringifyGraphDocument(v)).join(',')}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringifyGraphDocument(obj[k])}`).join(',')}}`;
+}
+/**
+ * SHA-256 (hex) of the stable JSON encoding of `graph`, for audit trails and matrix persistence.
+ */
+export function computeGraphDocumentContentSha256(graph) {
+    return createHash('sha256').update(stableStringifyGraphDocument(graph), 'utf8').digest('hex');
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Allowed memory-path roots for smartInput.paths and taskConfiguration.aiTaskProfile.inputSynthesis.sources.
+ * `input` and `inputs` are distinct roots (see `.docs/CR-input-and-inputs-dual-root.md`).
+ */
+export declare const GRAPH_ENGINE_MEMORY_PATH_ROOTS: readonly ["input", "inputs", "variables", "jobVariables", "taskVariables", "jobMemory", "taskMemory", "executionMemory", "xynthesized.job", "xynthesized.task", "xynthesized.execution"];
+/** Splits a path into allowlisted root + dot tail (longest root wins, e.g. `inputs` before `input`). */
+export declare function splitGraphEngineMemoryPath(path: string): {
+    root: string;
+    tail: string;
+};
+export declare function isAllowedGraphEngineMemoryPath(path: string): boolean;
+export declare function graphEngineMemoryPathValidationMessage(path: string): string;