@exellix/graph-engine 6.0.0

package/dist/src/runtime/validateCanonicalGraphDocument.js

@@ -0,0 +1,567 @@
+import { EXELLIX_STRUCTURED_DATA_FILTERS_V1 } from '../types/refs.js';
+import { ExellixGraphError } from '../errors/ExellixGraphError.js';
+import { ExellixGraphErrorCode } from '../errors/exellixGraphErrorCodes.js';
+import { EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY } from '../inspection/types.js';
+import { getStructuredDataFilterPathViolations } from './dataFiltersEvaluation.js';
+import { conditionWhenSignature, countDefaultModelConfigCases, isEmptyConditionWhen, isGraphAiModelConfig, isModelConfigSelection, } from './modelConfigSelection.js';
+/** Top-level keys permitted on a canonical exellix-graph executable graph JSON document. */
+export const CANONICAL_GRAPH_TOP_LEVEL_KEYS = [
+    'id',
+    'version',
+    'modelConfig',
+    'jobKnowledge',
+    'nodes',
+    'edges',
+    'variables',
+    'response',
+    'metadata',
+];
+const allowed = new Set(CANONICAL_GRAPH_TOP_LEVEL_KEYS);
+const MODEL_RUNTIME_FIELD_KEYS = new Set(['input', 'jobMemory', 'taskMemory', 'executionMemory', 'outputsMemory', 'aliasConfig']);
+const METADATA_FORBIDDEN_FIELD_TARGETS = {
+    modelConfig: 'graph.modelConfig',
+    aliasConfig: 'runtime.aliasConfig',
+    jobKnowledge: 'graph.jobKnowledge',
+    taskKnowledge: 'node.taskKnowledge',
+    graphResponse: 'graph.response',
+    jobMemory: 'runtime.jobMemory',
+    taskMemory: 'runtime.taskMemory',
+    executionMemory: 'runtime.executionMemory',
+    outputsMemory: 'runtime.outputsMemory',
+};
+const FORBIDDEN_GRAPH_RESPONSE_KEYS = [
+    'version',
+    'target',
+    'primaryResponsePaths',
+    'debugResponsePaths',
+    'notableExecutionPaths',
+    'mappingPreset',
+];
+/**
+ * Returns top-level keys on `graph` that are not part of the canonical executable document contract.
+ */
+export function getCanonicalGraphDocumentViolations(graph) {
+    if (graph == null || typeof graph !== 'object' || Array.isArray(graph)) {
+        return ['<not_a_plain_object>'];
+    }
+    const bad = [];
+    for (const key of Object.keys(graph)) {
+        if (!allowed.has(key))
+            bad.push(key);
+    }
+    return bad;
+}
+/** Pure-metadata keys permitted on task nodes (`metadata`). Execution config uses `taskConfiguration`. */
+const TASK_NODE_PURE_METADATA_KEYS = new Set([
+    'graphReadability',
+    'catalogBinding',
+    'catalogRequest',
+    'name',
+    'description',
+    'exellixContractTarget',
+    EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY,
+]);
+/** Hints when authors still place execution keys under `metadata`. */
+const LEGACY_METADATA_TO_TASK_CONFIGURATION = {
+    synthesizedContext: 'taskConfiguration.aiTaskProfile.inputSynthesis',
+    executionStrategyKey: 'taskConfiguration.executionStrategies',
+    outputConstraints: 'taskConfiguration.aiTasksOutputValidation',
+    narrix: 'taskConfiguration.narrix',
+    aiTaskProfile: 'taskConfiguration.aiTaskProfile',
+    narrixMode: 'taskConfiguration.narrixMode',
+    inputStrategyKey: 'taskConfiguration.inputStrategyKey',
+    narrixInput: 'taskConfiguration.narrixInput',
+    executionStrategies: 'taskConfiguration.executionStrategies',
+    aiTasksOutputValidation: 'taskConfiguration.aiTasksOutputValidation',
+    synthesizedInput: 'taskConfiguration.synthesizedInput',
+    modelConfig: 'taskConfiguration.modelConfig',
+    aliasConfig: 'runtime.aliasConfig',
+    llmCall: 'taskConfiguration.llmCall',
+    stepRetryPolicy: 'taskConfiguration.stepRetryPolicy',
+    concurrency: 'taskConfiguration.concurrency',
+    taskKind: 'taskConfiguration.taskKind',
+    autoValidateDecisionOutput: 'taskConfiguration.autoValidateDecisionOutput',
+    identity: 'taskConfiguration.identity',
+    runTaskIdentity: 'taskConfiguration.runTaskIdentity',
+    memoryKey: 'taskConfiguration.memoryKey',
+    taskTypeId: 'taskConfiguration.taskTypeId',
+    scopingMapId: 'taskConfiguration.scopingMapId',
+    entityIdPath: 'taskConfiguration.entityIdPath',
+    rules: 'taskConfiguration.rules',
+    taskKnowledge: 'node.taskKnowledge',
+    jobKnowledge: 'graph.jobKnowledge',
+    jobMemory: 'runtime.jobMemory',
+    taskMemory: 'runtime.taskMemory',
+    executionMemory: 'runtime.executionMemory',
+    outputsMemory: 'runtime.outputsMemory',
+};
+/** Web-scope keys are not allowed under `taskConfiguration.narrix` (use `taskConfiguration.aiTaskProfile.webScoping`). */
+const FORBIDDEN_NARRIX_WEB_KEYS = [
+    'enableWebScope',
+    'forceWebScope',
+    'webScopeQuestions',
+    'webScoping',
+    'webScopeTemplates',
+    'webScopeQuestionTemplate',
+    'webScopeObjects',
+    'webScopeEntityIdPath',
+    'webScopeEntityTypePath',
+    'enrichWebScopeQuestionFromExecutionRaw',
+];
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function assertOptionalStringArray(value, path, context, 
+/** Shown in the error message after "non-empty strings"; default describes taskKnowledge refs. */
+arrayRole) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item.trim() === '')) {
+        const role = arrayRole ?? 'knowledge references';
+        throw new ExellixGraphError(context?.nodeId
+            ? ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE
+            : ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path} must be an array of non-empty strings (${role}).`, context);
+    }
+}
+const TASK_NODE_CONDITIONS_KEYS = new Set([
+    'narratives',
+    'dataFilters',
+    'jsonConditions',
+    'jsConditionFunction',
+    'aiCondition',
+]);
+const TASK_NODE_CONDITION_WHEN_KEYS = new Set([
+    'jsonConditions',
+    'jsConditionFunction',
+    'aiCondition',
+]);
+const SCOPE_FILTER_WHERE_KEYS = new Set(['path', 'eq', 'eqAny']);
+function assertOptionalConditionsDataFiltersValue(value, path, context) {
+    if (value === undefined)
+        return;
+    if (Array.isArray(value)) {
+        assertOptionalStringArray(value, path, context, 'data filter ids');
+        return;
+    }
+    if (!isPlainObject(value)) {
+        throw new ExellixGraphError(context?.nodeId
+            ? ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE
+            : ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path} must be string[] (legacy ids), or structured { version: "${EXELLIX_STRUCTURED_DATA_FILTERS_V1}", when: predicate }.`, context);
+    }
+    if (value.version !== EXELLIX_STRUCTURED_DATA_FILTERS_V1) {
+        throw new ExellixGraphError(context?.nodeId
+            ? ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE
+            : ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path}.version must be "${EXELLIX_STRUCTURED_DATA_FILTERS_V1}" when structured dataFilters are used.`, { ...context, actualVersion: value.version });
+    }
+    if (!Object.prototype.hasOwnProperty.call(value, 'when')) {
+        throw new ExellixGraphError(context?.nodeId
+            ? ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE
+            : ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path}.when is required for structured dataFilters.`, context);
+    }
+    const when = value.when;
+    if (when == null || typeof when !== 'object' || Array.isArray(when)) {
+        throw new ExellixGraphError(context?.nodeId
+            ? ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE
+            : ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path}.when must be a graph predicate object.`, context);
+    }
+    const badPaths = getStructuredDataFilterPathViolations(when);
+    if (badPaths.length > 0) {
+        throw new ExellixGraphError(context?.nodeId
+            ? ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE
+            : ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path}.when uses paths outside the data record contract (only \`data\` and \`data.*\` are allowed). Offending paths: ${badPaths.join(', ')}.`, { ...context, badPaths });
+    }
+}
+function assertOptionalBoolean(value, path, ctx) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'boolean') {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path} must be a boolean when present.`, ctx);
+    }
+}
+function assertTaskNodeJsonCondition(value, path, ctx) {
+    if (value === undefined)
+        return;
+    if (!isPlainObject(value)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path} must be a plain object.`, ctx);
+    }
+    if (value.condition === undefined) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path}.condition is required.`, ctx);
+    }
+    assertOptionalBoolean(value.negate, `${path}.negate`, ctx);
+    if (value.parameters !== undefined && !isPlainObject(value.parameters)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path}.parameters must be a plain object when present.`, ctx);
+    }
+    if (value.options !== undefined && !isPlainObject(value.options)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path}.options must be a plain object when present.`, ctx);
+    }
+}
+function assertTaskNodeJsCondition(value, path, ctx) {
+    if (value === undefined)
+        return;
+    if (!isPlainObject(value)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path} must be a plain object.`, ctx);
+    }
+    if (typeof value.conditionFunctionId !== 'string' || value.conditionFunctionId.trim() === '') {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path}.conditionFunctionId must be a non-empty string.`, ctx);
+    }
+    assertOptionalBoolean(value.negate, `${path}.negate`, ctx);
+    if (value.parameters !== undefined && !isPlainObject(value.parameters)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path}.parameters must be a plain object when present.`, ctx);
+    }
+}
+function assertTaskNodeAiCondition(value, path, ctx) {
+    if (value === undefined)
+        return;
+    if (!isPlainObject(value)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path} must be a plain object.`, ctx);
+    }
+    if (typeof value.condition !== 'string' || value.condition.trim() === '') {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path}.condition must be a non-empty string.`, ctx);
+    }
+    assertOptionalBoolean(value.negate, `${path}.negate`, ctx);
+    if (value.mode !== undefined && value.mode !== 'hybrid' && value.mode !== 'model') {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path}.mode must be "hybrid" or "model" when present.`, ctx);
+    }
+    if (value.model !== undefined && typeof value.model !== 'string') {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path}.model must be a string when present.`, ctx);
+    }
+    if (value.parameters !== undefined && !isPlainObject(value.parameters)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path}.parameters must be a plain object when present.`, ctx);
+    }
+}
+function assertTaskNodeConditionWhen(value, path, ctx, options) {
+    if (value === undefined)
+        return;
+    if (!isPlainObject(value)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path} must be a plain object when present.`, ctx);
+    }
+    for (const key of Object.keys(value)) {
+        if (!TASK_NODE_CONDITION_WHEN_KEYS.has(key)) {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path}: unknown key \`${key}\` — only jsonConditions, jsConditionFunction, and aiCondition are allowed.`, { ...ctx, whenKey: key });
+        }
+    }
+    if (options?.requireNonEmpty && isEmptyConditionWhen(value)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path} must include at least one of jsonConditions, jsConditionFunction, or aiCondition.`, ctx);
+    }
+    assertTaskNodeJsonCondition(value.jsonConditions, `${path}.jsonConditions`, ctx);
+    assertTaskNodeJsCondition(value.jsConditionFunction, `${path}.jsConditionFunction`, ctx);
+    assertTaskNodeAiCondition(value.aiCondition, `${path}.aiCondition`, ctx);
+}
+function assertOptionalTaskNodeConditions(value, nodeId, context) {
+    if (value === undefined)
+        return;
+    if (!isPlainObject(value)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${nodeId}": conditions must be a plain object when present.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(nodeId) });
+    }
+    for (const key of Object.keys(value)) {
+        if (!TASK_NODE_CONDITIONS_KEYS.has(key)) {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${nodeId}": unknown key \`conditions.${key}\`.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(nodeId), conditionsKey: key });
+        }
+        if (key === 'aiFilter') {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${nodeId}": conditions.aiFilter was removed — use conditions.aiCondition.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(nodeId) });
+        }
+    }
+    const ctx = { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(nodeId) };
+    assertOptionalStringArray(value.narratives, `Task node "${nodeId}": conditions.narratives`, ctx, 'narrative ids');
+    if (value.dataFilters !== undefined) {
+        if (!Array.isArray(value.dataFilters) || !value.dataFilters.every((x) => typeof x === 'string' && x.trim() !== '')) {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${nodeId}": conditions.dataFilters must be string[] (catalog ids). Structured exellix.dataFilters.v1 is not supported on task nodes — use conditions.jsonConditions.`, ctx);
+        }
+    }
+    assertTaskNodeJsonCondition(value.jsonConditions, `Task node "${nodeId}": conditions.jsonConditions`, ctx);
+    assertTaskNodeJsCondition(value.jsConditionFunction, `Task node "${nodeId}": conditions.jsConditionFunction`, ctx);
+    assertTaskNodeAiCondition(value.aiCondition, `Task node "${nodeId}": conditions.aiCondition`, ctx);
+}
+function assertModelConfigSelection(value, path, context) {
+    if (value === undefined)
+        return;
+    const code = context?.nodeId
+        ? ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE
+        : ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT;
+    if (isGraphAiModelConfig(value)) {
+        throw new ExellixGraphError(code, `${path}: flat { xynthesisModel, skillModel } was removed. Use { cases: [{ modelConfig: { xynthesisModel, skillModel } }] } (one case with no \`when\` for a single default).`, context);
+    }
+    if (!isModelConfigSelection(value)) {
+        throw new ExellixGraphError(code, `${path} must be { cases: ModelConfigCase[] } where each case has modelConfig and optional when.`, context);
+    }
+    const cases = value.cases;
+    if (!Array.isArray(cases) || cases.length === 0) {
+        throw new ExellixGraphError(code, `${path}.cases must be a non-empty array.`, context);
+    }
+    const ctx = { jobId: context?.jobId, graphId: context?.graphId, nodeId: context?.nodeId };
+    const whenSigs = new Set();
+    for (let i = 0; i < cases.length; i++) {
+        const c = cases[i];
+        const casePath = `${path}.cases[${i}]`;
+        if (!isPlainObject(c)) {
+            throw new ExellixGraphError(code, `${casePath} must be a plain object.`, context);
+        }
+        if (!isGraphAiModelConfig(c.modelConfig)) {
+            throw new ExellixGraphError(code, `${casePath}.modelConfig must be { xynthesisModel: string, skillModel: string } with non-empty values.`, context);
+        }
+        if (isEmptyConditionWhen(c.when)) {
+            continue;
+        }
+        assertTaskNodeConditionWhen(c.when, `${casePath}.when`, ctx, { requireNonEmpty: true });
+        const sig = conditionWhenSignature(c.when);
+        if (whenSigs.has(sig)) {
+            throw new ExellixGraphError(code, `${path}: duplicate \`when\` condition — each conditioned case must be unique.`, { ...context, duplicateWhen: sig });
+        }
+        whenSigs.add(sig);
+    }
+    const defaultCount = countDefaultModelConfigCases(cases);
+    if (defaultCount !== 1) {
+        throw new ExellixGraphError(code, `${path}.cases must contain exactly one case with no \`when\` (the unconditional default); found ${defaultCount}.`, context);
+    }
+}
+/** Runtime host override: flat GraphAiModelConfig only. */
+function assertOptionalRuntimeFlatModelConfig(value, path, context) {
+    if (value === undefined)
+        return;
+    if (!isGraphAiModelConfig(value)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${path} must be exactly { xynthesisModel: string, skillModel: string } (runtime host override does not use cases).`, context);
+    }
+}
+function assertContextualKnowledgeScope(scope, nodeId, context) {
+    if (scope === undefined)
+        return;
+    if (!isPlainObject(scope))
+        return;
+    const items = scope.contextualKnowledge;
+    if (!Array.isArray(items))
+        return;
+    const ctx = { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(nodeId) };
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if (!isPlainObject(item))
+            continue;
+        const filter = item.filter;
+        if (!isPlainObject(filter))
+            continue;
+        const where = filter.where;
+        if (!Array.isArray(where))
+            continue;
+        for (let j = 0; j < where.length; j++) {
+            const leaf = where[j];
+            const leafPath = `Task node "${nodeId}": scope.contextualKnowledge[${i}].filter.where[${j}]`;
+            if (!isPlainObject(leaf)) {
+                throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${leafPath} must be a plain object.`, ctx);
+            }
+            if (typeof leaf.path !== 'string' || leaf.path.trim() === '') {
+                throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${leafPath}.path must be a non-empty string.`, ctx);
+            }
+            for (const key of Object.keys(leaf)) {
+                if (!SCOPE_FILTER_WHERE_KEYS.has(key)) {
+                    throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${leafPath}: unknown key \`${key}\` — only path, eq, and eqAny are allowed (cidrContains was removed).`, { ...ctx, scopeFilterKey: key });
+                }
+            }
+            const hasEq = Object.prototype.hasOwnProperty.call(leaf, 'eq');
+            const hasEqAny = Object.prototype.hasOwnProperty.call(leaf, 'eqAny');
+            if (!hasEq && !hasEqAny) {
+                throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `${leafPath} must include eq or eqAny.`, ctx);
+            }
+        }
+    }
+}
+function assertGraphResponseDefinition(value, path, context) {
+    if (!isPlainObject(value)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path} must be an object with optional missing and required shape fields.`, context);
+    }
+    for (const key of FORBIDDEN_GRAPH_RESPONSE_KEYS) {
+        if (key in value) {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path}.${key} is not part of the root response contract. Move only missing and shape to graph.response; keep editor-only fields outside the executable graph contract.`, { ...context, responseKey: key });
+        }
+    }
+    if (value.missing !== undefined && value.missing !== 'omit' && value.missing !== 'null') {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path}.missing must be "omit" or "null" when provided.`, { ...context, actual: value.missing });
+    }
+    if (!Object.prototype.hasOwnProperty.call(value, 'shape')) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path}.shape is required.`, context);
+    }
+}
+function findFinalizerType(node) {
+    if (!isPlainObject(node))
+        return undefined;
+    return typeof node.finalizerType === 'string' ? node.finalizerType : undefined;
+}
+function isTaskShape(node) {
+    if (!isPlainObject(node))
+        return false;
+    if (node.type === 'finalizer')
+        return false;
+    return true;
+}
+/** Single-node validation. Throws `NON_CANONICAL_TASK_NODE` on the first canonical violation. */
+export function assertCanonicalTaskNode(node, context) {
+    if (!isPlainObject(node)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Graph node at index ${context?.nodeIndex ?? '?'} is not a plain object.`, { jobId: context?.jobId, graphId: context?.graphId });
+    }
+    if (typeof node.id !== 'string' || node.id.length === 0) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Graph node at index ${context?.nodeIndex ?? '?'} is missing a string id.`, { jobId: context?.jobId, graphId: context?.graphId });
+    }
+    assertOptionalStringArray(node.taskKnowledge, `Task node "${String(node.id)}": taskKnowledge`, {
+        jobId: context?.jobId,
+        graphId: context?.graphId,
+        nodeId: String(node.id),
+    });
+    // Finalizer nodes only need to declare type=finalizer + finalizerType; nothing else is gated here.
+    if (node.type === 'finalizer') {
+        if (typeof findFinalizerType(node) !== 'string') {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Finalizer node "${String(node.id)}" must declare a string finalizerType.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+        }
+        return;
+    }
+    if (!isTaskShape(node))
+        return;
+    if ('outputMapping' in node) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": outputMapping belongs on the finalizer. Use executionMapping to write task results into executionMemory.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+    }
+    assertOptionalTaskNodeConditions(node.conditions, String(node.id), {
+        jobId: context?.jobId,
+        graphId: context?.graphId,
+        nodeId: String(node.id),
+    });
+    // skillKey: only on node.skillKey
+    const data = isPlainObject(node.data) ? node.data : undefined;
+    const meta = isPlainObject(node.metadata)
+        ? node.metadata
+        : undefined;
+    if (data && 'skillKey' in data) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": skillKey must be on node.skillKey, not node.data.skillKey.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+    }
+    if (meta && 'skillKey' in meta) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": skillKey must be on node.skillKey, not node.metadata.skillKey.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+    }
+    // variables: only on node.variables
+    if (data && 'variables' in data) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": node-level variables must be on node.variables, not node.data.variables.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+    }
+    if (meta && 'variables' in meta) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": node-level variables must be on node.variables, not node.metadata.variables.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+    }
+    const taskNode = node;
+    const tc = isPlainObject(taskNode.taskConfiguration)
+        ? taskNode.taskConfiguration
+        : undefined;
+    assertModelConfigSelection(tc?.modelConfig, `Task node "${String(node.id)}": taskConfiguration.modelConfig`, {
+        jobId: context?.jobId,
+        graphId: context?.graphId,
+        nodeId: String(node.id),
+    });
+    assertContextualKnowledgeScope(taskNode.scope, String(node.id), {
+        jobId: context?.jobId,
+        graphId: context?.graphId,
+        nodeId: String(node.id),
+    });
+    if (meta) {
+        for (const key of Object.keys(meta)) {
+            if (!TASK_NODE_PURE_METADATA_KEYS.has(key)) {
+                const redirect = LEGACY_METADATA_TO_TASK_CONFIGURATION[key];
+                const suffix = redirect
+                    ? ` Move this to \`${redirect}\`.`
+                    : ` Execution-related keys belong on taskConfiguration or node.variables — metadata is allowlisted to pure planning/description fields only.`;
+                throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": forbidden key \`metadata.${key}\`.${suffix}`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id), metadataKey: key });
+            }
+        }
+    }
+    const narrixTc = tc && isPlainObject(tc.narrix) ? tc.narrix : undefined;
+    if (narrixTc) {
+        for (const k of FORBIDDEN_NARRIX_WEB_KEYS) {
+            if (k in narrixTc) {
+                throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": taskConfiguration.narrix.${k} is forbidden — author web scope under taskConfiguration.aiTaskProfile.webScoping.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id), narrixWebKey: k });
+            }
+        }
+    }
+    const profile = tc && isPlainObject(tc.aiTaskProfile) ? tc.aiTaskProfile : undefined;
+    const inputSynthesis = profile && isPlainObject(profile.inputSynthesis) ? profile.inputSynthesis : undefined;
+    if (inputSynthesis && 'alsoWriteLegacySynthesizedContext' in inputSynthesis) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": taskConfiguration.aiTaskProfile.inputSynthesis.alsoWriteLegacySynthesizedContext is removed in 5.x.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+    }
+    if (inputSynthesis?.enabled === true &&
+        Array.isArray(taskNode.executionPipeline)) {
+        for (const step of taskNode.executionPipeline) {
+            if (step?.phase === 'pre' && step?.type === 'synthesized-context') {
+                throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": inputSynthesis.enabled is true but executionPipeline already declares a PRE synthesized-context step. Drop the manual step — graph-engine emits it from taskConfiguration.aiTaskProfile.inputSynthesis.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+            }
+        }
+    }
+}
+/**
+ * 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 function assertCanonicalGraphDocument(graph, context) {
+    const violations = getCanonicalGraphDocumentViolations(graph);
+    if (violations.length > 0) {
+        const graphId = context?.graphId ??
+            (graph != null && typeof graph === 'object' && !Array.isArray(graph) && typeof graph.id === 'string'
+                ? graph.id
+                : undefined);
+        const keys = violations.join(', ');
+        const runtimeKeys = violations.filter((key) => MODEL_RUNTIME_FIELD_KEYS.has(key));
+        const runtimeSuffix = runtimeKeys.length
+            ? ` Runtime state belongs under the execution request runtime object, not the graph model: ${runtimeKeys
+                .map((key) => `runtime.${key}`)
+                .join(', ')}.`
+            : '';
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `This is not a canonical exellix-graph executable graph document. Forbidden top-level key(s): ${keys}. ` +
+            `Only id, version, modelConfig, jobKnowledge, nodes, edges, variables, response, and metadata are allowed at the document root; ` +
+            `graph-document metadata (name, description, exellixContractTarget, graphEntry, catalogRequests, etc.) must live under metadata, while final response shaping belongs at graph.response. ` +
+            `The runtime does not normalize or relocate fields — fix the upstream serializer.` +
+            runtimeSuffix, {
+            jobId: context?.jobId,
+            graphId,
+            nonCanonicalTopLevelKeys: violations,
+        });
+    }
+    const resolvedGraphId = context?.graphId ??
+        (graph != null && typeof graph === 'object' && typeof graph.id === 'string'
+            ? graph.id
+            : undefined);
+    assertOptionalStringArray(graph.jobKnowledge, 'graph.jobKnowledge', {
+        jobId: context?.jobId,
+        graphId: resolvedGraphId,
+    });
+    assertModelConfigSelection(graph.modelConfig, 'graph.modelConfig', {
+        jobId: context?.jobId,
+        graphId: resolvedGraphId,
+    });
+    const metadata = isPlainObject(graph.metadata)
+        ? graph.metadata
+        : undefined;
+    if (metadata) {
+        for (const key of Object.keys(metadata)) {
+            const target = METADATA_FORBIDDEN_FIELD_TARGETS[key];
+            if (target) {
+                throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `Graph "${String(resolvedGraphId ?? '?')}": metadata.${key} is not part of the static metadata block. Move this field to \`${target}\`.`, { jobId: context?.jobId, graphId: resolvedGraphId, metadataKey: key });
+            }
+        }
+        const graphEntry = metadata.graphEntry;
+        if (graphEntry != null && typeof graphEntry === 'object' && !Array.isArray(graphEntry)) {
+            const ge = graphEntry;
+            if (Object.prototype.hasOwnProperty.call(ge, 'dataFilters')) {
+                assertOptionalConditionsDataFiltersValue(ge.dataFilters, `Graph "${String(resolvedGraphId ?? '?')}": metadata.graphEntry.dataFilters`, { jobId: context?.jobId, graphId: resolvedGraphId });
+            }
+        }
+    }
+    // 5.x: graph.nodes must be an array.
+    if (!Array.isArray(graph.nodes)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `Graph "${String(resolvedGraphId ?? '?')}" must declare nodes as an array. Record-keyed nodes (Record<string, GraphNode>) were removed in 5.x.`, { jobId: context?.jobId, graphId: resolvedGraphId });
+    }
+    // Per-node canonical checks.
+    const nodes = graph.nodes;
+    for (let i = 0; i < nodes.length; i++) {
+        assertCanonicalTaskNode(nodes[i], { jobId: context?.jobId, graphId: resolvedGraphId, nodeIndex: i });
+    }
+    if (!Object.prototype.hasOwnProperty.call(graph, 'response')) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `Graph "${String(resolvedGraphId ?? '?')}" must declare root graph.response. Final response shaping must not live under metadata.graphResponse.responseMapping or finalizer output selection.`, { jobId: context?.jobId, graphId: resolvedGraphId });
+    }
+    assertGraphResponseDefinition(graph.response, 'graph.response', {
+        jobId: context?.jobId,
+        graphId: resolvedGraphId,
+    });
+}

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

@@ -0,0 +1,2 @@
+export { readExecutionVariableBuckets, seedGraphVariableBucketsOnExecution, mirrorTaskVariablesOnExecution, seedGraphVariableBucketsFromRuntime, buildMemoryResolutionRootFromExecution, buildPredicateEvalContextForNode, } from './executionVariableBuckets.js';
+export type { ExecutionVariableBuckets } from './executionVariableBuckets.js';

package/dist/src/runtime/variables.js

@@ -0,0 +1 @@
+export { readExecutionVariableBuckets, seedGraphVariableBucketsOnExecution, mirrorTaskVariablesOnExecution, seedGraphVariableBucketsFromRuntime, buildMemoryResolutionRootFromExecution, buildPredicateEvalContextForNode, } from './executionVariableBuckets.js';

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

@@ -0,0 +1,5 @@
+/**
+ * Rejects with `errorFactory()` if `promise` does not settle within `ms`.
+ * No-op when `ms` is not a positive finite number.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, errorFactory: () => Error): Promise<T>;

package/dist/src/runtime/withTimeout.js

@@ -0,0 +1,20 @@
+/**
+ * Rejects with `errorFactory()` if `promise` does not settle within `ms`.
+ * No-op when `ms` is not a positive finite number.
+ */
+export function withTimeout(promise, ms, errorFactory) {
+    if (!(ms > 0) || !Number.isFinite(ms))
+        return promise;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(errorFactory());
+        }, ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}

package/dist/src/types/aiTaskProfile.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Optional task metadata aligned with `@x12i/graph-composer` authoring / `reportTaskNodeProtocolGaps`.
+ * Exellix-graph-engine merges {@link AiTaskProfileMetadata.webScoping} into `taskConfiguration.narrix` for execution
+ * when `enabled: true` and `questions` is non-empty (see `applyAiTaskProfileWebScopingToNarrix`).
+ */
+export type AiTaskProfileWebScoping = {
+    enabled: boolean;
+    /** When `enabled` is `true`, must be a non-empty array of non-empty strings (graph-composer contract). */
+    questions?: string[];
+};
+export type AiTaskProfileInputSynthesis = {
+    enabled: boolean;
+    /** Memory paths fed to PRE `synthesized-context` when `enabled` (validated against graph-engine allowlist). */
+    sources?: string[];
+    /** Xynthesized bucket for ai-tasks PRE `synthesized-context` `xynthesizedOutput.destination`. */
+    destination?: 'job' | 'task' | 'execution';
+    /** Required when `enabled` — key written under the destination scope. */
+    outputKey?: string;
+    /** Merge vs replace for xynthesized output (default **merge**). */
+    mode?: 'merge' | 'replace';
+    /** Catalox catalog id for synthesis mode rows (graph-composer contract). */
+    catalogId?: string;
+    strategyKey?: string;
+};
+/**
+ * PRE/POST strategies, optional web scoping, optional input synthesis for AI task nodes.
+ * `@x12i/graph-composer` requires `preStrategyKey` / `postStrategyKey` for validated AI nodes.
+ * Exellix-graph-engine merges `webScoping` into the resolved narrix payload for execution when active.
+ *
+ * **Runtime (graph-engine ≥5):** When `preStrategyKey` / `postStrategyKey` are non-empty strings, the executor issues
+ * additional `@exellix/ai-tasks` **`runTask`** calls (utility `skillKey`) **before** and **after** the MAIN node task — graph-engine does **not** call the Xynthesis package directly. Results are merged under **`execution.xynthesis.pre`** / **`execution.xynthesis.post`** (historical execution-memory slot names). This is separate from `executionPipeline` PRE `synthesized-context`, which still runs inside a single ai-tasks `runTask`.
+ *
+ * **`inputSynthesis` runtime:** When `enabled`, graph-engine translates this block into an ai-tasks PRE
+ * `synthesized-context` step inside the **same** `runTask` call (distinct from engine-level PRE/POST strategy utilities).
+ */
+export type AiTaskProfileMetadata = {
+    preStrategyKey?: string;
+    postStrategyKey?: string;
+    webScoping?: AiTaskProfileWebScoping;
+    inputSynthesis?: AiTaskProfileInputSynthesis;
+};

package/dist/src/types/aiTaskProfile.js

@@ -0,0 +1,6 @@
+/**
+ * Optional task metadata aligned with `@x12i/graph-composer` authoring / `reportTaskNodeProtocolGaps`.
+ * Exellix-graph-engine merges {@link AiTaskProfileMetadata.webScoping} into `taskConfiguration.narrix` for execution
+ * when `enabled: true` and `questions` is non-empty (see `applyAiTaskProfileWebScopingToNarrix`).
+ */
+export {};

package/dist/src/types/aiTasksDerivedTypes.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Stable `@exellix/ai-tasks` request subtree types (package root re-exports as of **7.1.1+**; aligns with **`^7.2.2`**).
+ * Graph-engine re-exports these for callers that should not depend on `NonNullable<RunTaskRequest[...]>` patterns.
+ */
+export type { ExecutionStrategyInvocation, SmartInputConfig, TaskStrategyItemData, XynthesizedMemory, XynthesizedDestinationScope, XynthesizedOutputConfig, ExecutionStrategyPhase, ExecutionStrategyWrapperKey, } from '@exellix/ai-tasks';

package/dist/src/types/aiTasksDerivedTypes.js

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