@exellix/graph-engine 8.6.0 → 9.0.0

package/dist/src/validation/validateGraphResponseWiring.js

@@ -0,0 +1,233 @@
+import { embeddedGraphToExellixGraph } from '../plan/embeddedGraphToExellixGraph.js';
+import { detectAuthoringResponseSourceIssues, GRAPH_RESPONSE_DUAL_SOURCE, GRAPH_RESPONSE_LEGACY_SOURCE, } from './authoringGraphResponse.js';
+export const RESPONSE_PATH_NO_WRITER = 'RESPONSE_PATH_NO_WRITER';
+export const TASK_MAP_TARGET_INVALID = 'TASK_MAP_TARGET_INVALID';
+export const TASK_MAP_SOURCE_INVALID = 'TASK_MAP_SOURCE_INVALID';
+export const RESPONSE_LEGACY_SHAPE_KEY = 'RESPONSE_LEGACY_SHAPE_KEY';
+export const EXECUTION_MAPPING_LEGACY_PATH = 'EXECUTION_MAPPING_LEGACY_PATH';
+export const RESPONSE_EMPTY_SHAPE = 'RESPONSE_EMPTY_SHAPE';
+export const RESPONSE_LEGACY_PRESET_ID = 'RESPONSE_LEGACY_PRESET_ID';
+export const RESPONSE_COERCE_STRING_ARRAY_ON_SCALAR = 'RESPONSE_COERCE_STRING_ARRAY_ON_SCALAR';
+const LEGACY_SHAPE_KEYS = new Set(['subnetAnalysis', 'taskSections']);
+const LEGACY_EXECUTION_PATH_RE = /^inference\.conceptSketch(\.|$)/;
+const KNOWN_MAP_SOURCE_PREFIXES = ['output.', 'parsed.', 'node.', 'variables.', 'jobMemory.'];
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function isSupportedSelector(v) {
+    return isPlainRecord(v) && typeof v.type === 'string';
+}
+function getGraphNodes(graph) {
+    return Array.isArray(graph.nodes) ? graph.nodes : [];
+}
+function isTaskNode(node) {
+    return node.type !== 'finalizer';
+}
+function isFinalizerNode(node) {
+    return node.type === 'finalizer';
+}
+function isShapeEmpty(shape) {
+    if (shape == null)
+        return true;
+    if (Array.isArray(shape))
+        return shape.length === 0;
+    if (isPlainRecord(shape))
+        return Object.keys(shape).length === 0;
+    return false;
+}
+function hasTerminalFinalizer(graph) {
+    const nodes = getGraphNodes(graph);
+    const finalizers = nodes.filter(isFinalizerNode);
+    if (finalizers.length === 0)
+        return false;
+    const edges = graph.edges ?? [];
+    const targeted = new Set(edges.map((e) => e.to));
+    return finalizers.some((f) => targeted.has(f.id) || edges.some((e) => e.to === f.id));
+}
+function collectTaskWritePaths(graph) {
+    const out = [];
+    for (const node of getGraphNodes(graph)) {
+        if (!isTaskNode(node))
+            continue;
+        const em = node.executionMapping;
+        if (em?.path && typeof em.path === 'string' && em.path.length > 0) {
+            out.push({ nodeId: String(node.id), path: em.path });
+        }
+    }
+    return out;
+}
+function pathHasWriter(selectorPath, writePaths) {
+    return writePaths.some(({ path }) => selectorPath === path || selectorPath.startsWith(`${path}.`));
+}
+function collectSelectors(shape, path, out, legacyKeys) {
+    if (isSupportedSelector(shape)) {
+        out.push({ selector: shape, path });
+        if (shape.type === 'firstPresent' && Array.isArray(shape.sources)) {
+            shape.sources.forEach((source, index) => collectSelectors(source, `${path}.sources[${index}]`, out, legacyKeys));
+        }
+        return;
+    }
+    if (Array.isArray(shape)) {
+        shape.forEach((item, index) => collectSelectors(item, `${path}[${index}]`, out, legacyKeys));
+        return;
+    }
+    if (isPlainRecord(shape)) {
+        for (const [key, val] of Object.entries(shape)) {
+            if (LEGACY_SHAPE_KEYS.has(key)) {
+                legacyKeys.push({
+                    code: RESPONSE_LEGACY_SHAPE_KEY,
+                    message: `graph.response.shape must not use legacy key "${key}".`,
+                    path: `${path}.${key}`,
+                });
+            }
+            collectSelectors(val, `${path}.${key}`, out, legacyKeys);
+        }
+    }
+}
+function isValidMapSource(source) {
+    if (source.startsWith('"') || source.startsWith('\\"'))
+        return true;
+    if (KNOWN_MAP_SOURCE_PREFIXES.some((prefix) => source.startsWith(prefix)))
+        return true;
+    // Shorthand leaf keys resolve against task output at runtime.
+    if (!source.includes('.'))
+        return true;
+    return false;
+}
+function validateTaskExecutionMapping(node, errors, warnings) {
+    const em = node.executionMapping;
+    if (!em?.path)
+        return;
+    const nodeId = String(node.id);
+    if (LEGACY_EXECUTION_PATH_RE.test(em.path)) {
+        errors.push({
+            code: EXECUTION_MAPPING_LEGACY_PATH,
+            message: `Task node "${nodeId}" uses legacy executionMapping.path "${em.path}". Use answers.qN (or another flat namespace) instead of inference.conceptSketch.stepN.`,
+            nodeId,
+            path: `nodes.${nodeId}.executionMapping.path`,
+        });
+    }
+    const map = em.map;
+    if (!isPlainRecord(map))
+        return;
+    for (const [targetKey, sourcePath] of Object.entries(map)) {
+        if (targetKey.includes('.')) {
+            errors.push({
+                code: TASK_MAP_TARGET_INVALID,
+                message: `Task node "${nodeId}" executionMapping.map target "${targetKey}" must be flat — use graph.response.shape for nesting.`,
+                nodeId,
+                path: `nodes.${nodeId}.executionMapping.map.${targetKey}`,
+            });
+        }
+        if (typeof sourcePath === 'string' && !isValidMapSource(sourcePath)) {
+            errors.push({
+                code: TASK_MAP_SOURCE_INVALID,
+                message: `Task node "${nodeId}" executionMapping.map source "${sourcePath}" is not under a known task output root (output., parsed., node., variables., jobMemory., or shorthand leaf).`,
+                nodeId,
+                path: `nodes.${nodeId}.executionMapping.map.${targetKey}`,
+            });
+        }
+    }
+}
+function validateResponseShape(graph, errors, warnings) {
+    const response = graph.response;
+    if (!isPlainRecord(response))
+        return;
+    const shape = response.shape;
+    if (isShapeEmpty(shape) && hasTerminalFinalizer(graph)) {
+        errors.push({
+            code: RESPONSE_EMPTY_SHAPE,
+            message: 'graph.response.shape is empty but the graph has a terminal finalizer — declare response selectors or remove the finalizer.',
+            path: 'graph.response.shape',
+        });
+    }
+    const writePaths = collectTaskWritePaths(graph);
+    const selectors = [];
+    const legacyShapeIssues = [];
+    collectSelectors(shape, 'graph.response.shape', selectors, legacyShapeIssues);
+    errors.push(...legacyShapeIssues);
+    for (const { selector, path } of selectors) {
+        if (selector.coerce === 'stringArray' && /shortAnswer/i.test(path)) {
+            warnings.push({
+                code: RESPONSE_COERCE_STRING_ARRAY_ON_SCALAR,
+                message: `coerce: "stringArray" on scalar field at ${path} is unusual — shortAnswer is string-typed by contract.`,
+                path,
+            });
+        }
+        const memoryPath = selector.type === 'executionMemoryPath' || selector.type === 'executionPath'
+            ? selector.path
+            : undefined;
+        if (memoryPath && !pathHasWriter(memoryPath, writePaths)) {
+            errors.push({
+                code: RESPONSE_PATH_NO_WRITER,
+                message: `graph.response selector path "${memoryPath}" has no upstream task executionMapping.path prefix.`,
+                path,
+            });
+        }
+    }
+}
+function validateMetadataLegacyPreset(graph, errors) {
+    const metadata = graph.metadata;
+    if (!isPlainRecord(metadata))
+        return;
+    const preset = isPlainRecord(metadata.responsePreset) ? metadata.responsePreset : undefined;
+    if (preset?.id === 'subnetAnalysis') {
+        errors.push({
+            code: RESPONSE_LEGACY_PRESET_ID,
+            message: 'metadata.responsePreset.id "subnetAnalysis" was removed — migrate to graph.response.shape.',
+            path: 'metadata.responsePreset.id',
+        });
+    }
+}
+function validateGraphModel(graph) {
+    const errors = [];
+    const warnings = [];
+    validateMetadataLegacyPreset(graph, errors);
+    for (const node of getGraphNodes(graph)) {
+        if (isTaskNode(node))
+            validateTaskExecutionMapping(node, errors, warnings);
+    }
+    validateResponseShape(graph, errors, warnings);
+    return { ok: errors.length === 0, errors, warnings };
+}
+function graphFromPlan(plan) {
+    return embeddedGraphToExellixGraph(plan);
+}
+/** Validate response wiring for an authoring document, executable plan, or materialized graph. */
+export function validateGraphResponseWiring(input) {
+    const errors = [];
+    const warnings = [];
+    if ('formatVersion' in input && 'graph' in input) {
+        const doc = input;
+        for (const issue of detectAuthoringResponseSourceIssues(doc)) {
+            if (issue.code === GRAPH_RESPONSE_LEGACY_SOURCE) {
+                errors.push({ code: issue.code, message: issue.message, path: issue.path });
+            }
+            else if (issue.code === GRAPH_RESPONSE_DUAL_SOURCE) {
+                warnings.push({ code: issue.code, message: issue.message, path: issue.path });
+            }
+        }
+        const stubGraph = {
+            id: doc.id,
+            nodes: [],
+            edges: [],
+            response: doc.graph.response ?? { shape: {} },
+            metadata: doc.graph.metadata,
+        };
+        validateMetadataLegacyPreset(stubGraph, errors);
+        return { ok: errors.length === 0, errors, warnings };
+    }
+    if ('normalizedGraph' in input && 'source' in input) {
+        return validateGraphModel(graphFromPlan(input));
+    }
+    return validateGraphModel(input);
+}
+export function assertGraphResponseWiringOk(validation, context) {
+    if (validation.ok)
+        return;
+    const summary = validation.errors.map((e) => `${e.code}: ${e.message}`).join('; ');
+    const err = new Error(`Graph response wiring validation failed${context?.graphId ? ` for "${context.graphId}"` : ''}: ${summary}`);
+    err.code = validation.errors[0]?.code ?? 'GRAPH_RESPONSE_WIRING_INVALID';
+    err.details = validation;
+    throw err;
+}

package/dist/testkit/authoringGraphFixtures.js

@@ -12,6 +12,7 @@ function authoringShell(graphId, nodes, edges, graphResponseShape, extra) {
         graph: {
             nodes,
             edges,
+            response: authoringResponseBlock(graphResponseShape),
             inputs: taskNodes.map((node) => ({
                 id: `graph-input:${node.id}`,
                 name: 'Input Record',
@@ -31,7 +32,6 @@ function authoringShell(graphId, nodes, edges, graphResponseShape, extra) {
                 ]
                 : [],
             metadata: {
-                graphResponse: { shape: graphResponseShape },
                 modelConfig: defaultExecutableModelConfig(),
                 ...extra,
             },
@@ -39,6 +39,9 @@ function authoringShell(graphId, nodes, edges, graphResponseShape, extra) {
         types: [],
     };
 }
+function authoringResponseBlock(graphResponseShape) {
+    return { shape: graphResponseShape };
+}
 /** Single ai-task + select finalizer — mirrors legacy flat `buildAiTaskGraph` tests. */
 export function buildAiTaskAuthoringGraph(graphId) {
     const taskId = 'ask-1';

package/dist/testkit/buildExecuteGraphInput.js

@@ -6,7 +6,9 @@ function normalizeAuthoringDocument(input) {
 /** Builds `{ plan, runtime }` for tests and hosts with a Graphenix 2.x {@link AuthoringGraphDocument}. */
 export function buildExecuteGraphInput(doc, runtime) {
     return {
-        plan: compileExellixExecutablePlan(normalizeAuthoringDocument(doc), runtime),
+        plan: compileExellixExecutablePlan(normalizeAuthoringDocument(doc), runtime, {
+            strictResponseValidation: false,
+        }),
         runtime,
     };
 }

package/dist/testkit/flatGraphToAuthoring.js

@@ -228,11 +228,6 @@ export function flatTestGraphToAuthoringDocument(flat) {
         metadata.jobKnowledge = normalizeKnowledgeRefs(flat.jobKnowledge);
     if (Array.isArray(flat.taskKnowledge))
         metadata.taskKnowledge = normalizeKnowledgeRefs(flat.taskKnowledge);
-    metadata.graphResponse = {
-        ...(flatResponse.missing != null ? { missing: flatResponse.missing } : {}),
-        ...(flatResponse.version != null ? { version: flatResponse.version } : {}),
-        shape: responseShape,
-    };
     metadata.modelConfig = flatModelConfigToAuthoring(flat.modelConfig) ?? defaultExecutableModelConfig();
     const taskNodes = nodes.filter((n) => n.kind === TASK_NODE_KIND);
     const finalizer = nodes.find((n) => n.kind === FINALIZER_NODE_KIND);
@@ -244,6 +239,11 @@ export function flatTestGraphToAuthoringDocument(flat) {
         graph: {
             nodes: nodes,
             edges,
+            response: {
+                ...(flatResponse.missing != null ? { missing: flatResponse.missing } : {}),
+                ...(flatResponse.version != null ? { version: flatResponse.version } : {}),
+                shape: responseShape,
+            },
             inputs: taskNodes.map((node) => ({
                 id: `graph-input:${node.id}`,
                 name: 'Input Record',

package/docs/handoff/graphs-studio-graphenix-2.7.3.md

@@ -1,13 +1,13 @@
-# graphs-studio — Graphenix 2.7.3 alignment handoff
-
-Shipped with **@exellix/graph-engine@8.6.0** / **@exellix/graph-composer@2.12.0**.
-
-Full checklist: see Exellix monorepo `docs/handoff/graphs-studio-graphenix-2.7.3.md` (canonical copy). Summary:
-
-1. **Web scope:** `taskConfiguration.aiTaskProfile.webQueryTemplate` — remove `webScoping` and narrix web keys.
-2. **Graph entry:** no `graphEntry.inputs` (CR-006); use `requiredExecutionPaths` + jobs-ui data sources.
-3. **Persistency:** `response.persistency` with `newRecord` + optional `link` (Graphenix 2.7.3).
-4. **Preflight:** show `nodePlan.invokeContract.pipeline`, not root `RunTaskRequest.narrix`.
-5. **CRS-FRS-005:** PRE synthesis export parity still pending in studio (separate track).
-
-Pin: `graph-engine ^8.6.0`, `graph-composer ^2.12.0`, `ai-tasks ^10.0.12+`, `graphenix ^2.7.3`.
+# graphs-studio — Graphenix 2.7.3 alignment handoff
+
+Shipped with **@exellix/graph-engine@8.6.0** / **@exellix/graph-composer@2.12.0**.
+
+Full checklist: see Exellix monorepo `docs/handoff/graphs-studio-graphenix-2.7.3.md` (canonical copy). Summary:
+
+1. **Web scope:** `taskConfiguration.aiTaskProfile.webQueryTemplate` — remove `webScoping` and narrix web keys.
+2. **Graph entry:** no `graphEntry.inputs` (CR-006); use `requiredExecutionPaths` + jobs-ui data sources.
+3. **Persistency:** `response.persistency` with `newRecord` + optional `link` (Graphenix 2.7.3).
+4. **Preflight:** show `nodePlan.invokeContract.pipeline`, not root `RunTaskRequest.narrix`.
+5. **CRS-FRS-005:** PRE synthesis export parity still pending in studio (separate track).
+
+Pin: `graph-engine ^8.6.0`, `graph-composer ^2.12.0`, `ai-tasks ^10.0.12+`, `graphenix ^2.7.3`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-engine",
-  "version": "8.6.0",
+  "version": "9.0.0",
   "type": "module",
   "description": "Graph executor SDK",
   "main": "dist/src/index.js",
@@ -27,7 +27,7 @@
     "prebuild": "node scripts/clean-dist.mjs",
     "build": "tsc",
     "test": "npm run build && npm run check:no-legacy && tsx --test --test-force-exit --test-timeout=180000 --test-concurrency=2 tests/model-alias-canonical.test.ts tests/model-alias-execute.test.ts tests/model-alias-strategy.test.ts tests/model-alias-subnets.test.ts tests/ai-tasks-error-propagation.test.ts tests/reports-fixtures-pre-synthesis.test.ts tests/passthrough-parity.test.ts tests/step-retry-llm-call.test.ts tests/run-log-diagnostics.test.ts",
-    "test:full": "npm run build && npm run check:no-legacy && tsx --test --test-force-exit --test-timeout=180000 --test-concurrency=2 tests/graph-engine.test.ts tests/passthrough-parity.test.ts tests/task-node-run-task-preflight.test.ts tests/reports-fixtures-pre-synthesis.test.ts tests/model-alias-canonical.test.ts tests/model-alias-execute.test.ts tests/model-alias-strategy.test.ts tests/model-alias-subnets.test.ts tests/compile-host-patches.test.ts tests/reference-fixtures-compile.test.ts tests/step-retry-llm-call.test.ts",
+    "test:full": "npm run build && npm run check:no-legacy && tsx --test --test-force-exit --test-timeout=180000 --test-concurrency=2 tests/graph-engine.test.ts tests/graph-run-contract.test.ts tests/graph-response-contract.test.ts tests/passthrough-parity.test.ts tests/task-node-run-task-preflight.test.ts tests/reports-fixtures-pre-synthesis.test.ts tests/model-alias-canonical.test.ts tests/model-alias-execute.test.ts tests/model-alias-strategy.test.ts tests/model-alias-subnets.test.ts tests/compile-host-patches.test.ts tests/reference-fixtures-compile.test.ts tests/step-retry-llm-call.test.ts",
     "test:live": "npm run run:pre-synthesis",
     "test:subnets-graph-fixture": "npm run build && node --test tests/subnets-graph.fixture.test.mjs",
     "test:subnets-graph-live": "npm run build && node --env-file=.env --test tests/subnets-graph.live.test.mjs",
@@ -46,7 +46,8 @@
   "license": "exellix-license",
   "repository": {
     "type": "git",
-    "url": "git@github.com:exellix/graph-engine.git"
+    "url": "git+ssh://git@github.com/exellix/exellix-engine-mono-repo.git",
+    "directory": "graph-engine"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -57,23 +58,23 @@
     "@exellix/ai-tasks": "^10.0.13",
     "@x12i/activix": "^8.6.3",
     "@x12i/catalox": "^5.9.8",
-    "@x12i/env": "^4.0.1",
+    "@x12i/env": "^4.0.3",
     "@x12i/funcx": "^4.9.13",
     "@x12i/graphenix": "^2.5.0",
-    "@x12i/graphenix-authoring-format": "^2.7.3",
-    "@x12i/graphenix-core": "^2.7.3",
-    "@x12i/graphenix-executable-contracts": "^2.7.3",
-    "@x12i/graphenix-executable-format": "^2.7.3",
-    "@x12i/graphenix-execute-envelope": "^2.7.3",
+    "@x12i/graphenix-authoring-format": "^2.8.1",
+    "@x12i/graphenix-core": "^2.8.1",
+    "@x12i/graphenix-executable-contracts": "^2.8.1",
+    "@x12i/graphenix-executable-format": "^2.8.1",
+    "@x12i/graphenix-execute-envelope": "^2.8.1",
     "@x12i/graphenix-format": "^2.0.0",
-    "@x12i/graphenix-plan-compiler": "^2.7.3",
-    "@x12i/graphenix-plan-format": "^2.7.3",
-    "@x12i/graphenix-task-node-format": "^2.7.3",
-    "@x12i/graphenix-trace-format": "^2.7.3",
+    "@x12i/graphenix-plan-compiler": "^2.8.1",
+    "@x12i/graphenix-plan-format": "^2.8.1",
+    "@x12i/graphenix-task-node-format": "^2.8.1",
+    "@x12i/graphenix-trace-format": "^2.8.1",
     "@x12i/logxer": "^4.6.0",
-    "@x12i/memorix-descriptors": "1.10.0",
-    "@x12i/memorix-retrieval": "1.14.0",
-    "@x12i/memorix-writer": "1.3.0",
+    "@x12i/memorix-descriptors": "^1.10.0",
+    "@x12i/memorix-retrieval": "^1.15.0",
+    "@x12i/memorix-writer": "^1.3.0",
     "@x12i/rendrix": "^4.3.0",
     "@x12i/runx": "^1.3.2"
   },