@exellix/graph-engine 8.7.0 → 9.0.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 9.0.0 — Response contract & finalOutput (FR-GE / CR-GE pack)
+
+### Breaking
+
+- **Single canonical response:** Executable mapping reads **`graph.response` only** (authoring: `graph.response`; flat model: root `response`). `metadata.graphResponse` is rejected as executable truth (`GRAPH_RESPONSE_LEGACY_SOURCE`).
+- **`validateGraphResponseWiring`** runs on compile by default (`strictResponseValidation !== false`): path writers, flat map targets, legacy paths/shapes, empty shape + finalizer.
+- **`GRAPH_RESPONSE_INCOMPLETE`** when non-empty `graph.response.shape` resolves empty on a completed run.
+- **Legacy removed:** `inference.conceptSketch.*` execution paths, `subnetAnalysis` / top-level `taskSections` shape keys, `metadata.responsePreset.id === 'subnetAnalysis'`, task `outputMapping`.
+- **`resolveGraphRunContract`** reads **`graph.response.persistency` only** (no `metadata.graphResponse.persistency` fallback).
+- **`ExecuteGraphResult.execution`** is always present on graph runs.
+
+### Added
+
+- **`coerce: 'stringArray'`** on response selectors; **`coerceStringArray`**, **`resolveGraphResponse`**, **`assessGraphResponseCompleteness`** exports.
+- **`migrateLegacyGraphResponseToAuthoring`** (import-only).
+- **`inspectGraph`**: `response.source === 'graph.response'`.
+
+### Downstream
+
+- **graphs-playground:** remove `normalizeQaAnswersArrayFinalOutput`, `normalizeTaskSectionsFinalOutput`, `coerceResponsePresetTaggedGraph`, `buildTaskSectionsFinalOutputFromAnswers`; add `coerce: 'stringArray'` in studio preset builders at save time.
+
 ## 8.6.0 — Graphenix 2.7.3 (no-legacy web + narrix pipeline)
 
 ### Breaking

package/dist/src/compile/compileExellixExecutablePlan.d.ts

@@ -1,6 +1,9 @@
 import type { AuthoringGraphDocument, CompileExecutablePlanV2Options, ExecutableGraphPlanV2 } from '@x12i/graphenix-executable-contracts';
 import type { GraphRuntimeObject } from '../runtime/ExellixGraphRuntime.js';
-export type CompileExellixExecutablePlanOptions = CompileExecutablePlanV2Options;
+export type CompileExellixExecutablePlanOptions = CompileExecutablePlanV2Options & {
+    /** When true (default in 9.x), reject unsatisfiable graph.response wiring before returning a plan. */
+    strictResponseValidation?: boolean;
+};
 /**
  * Host/test helper: canonical {@link AuthoringGraphDocument} + runtime → validated v2 executable plan.
  * No legacy migration — graphs must already be Graphenix 2.x authoring shape.

package/dist/src/compile/compileExellixExecutablePlan.js

@@ -3,6 +3,12 @@ import { compileExecutablePlanV2 } from '@x12i/graphenix-plan-compiler';
 import { validateExecutablePlanV2 } from '@x12i/graphenix-plan-format';
 import { resolveGraphEntryFromAuthoringDocument } from './authoringDocumentHelpers.js';
 import { EXELLIX_STRUCTURED_DATA_FILTERS_V1 } from '../types/refs.js';
+import { assertGraphResponseWiringOk, validateGraphResponseWiring, } from '../validation/validateGraphResponseWiring.js';
+import { resolveAuthoringGraphResponse } from '../validation/authoringGraphResponse.js';
+import { assertGraphResponseDefinition } from '../runtime/graphResponseMapping.js';
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
 function patchEntryGatesFromGraphEntryDataFilters(plan, doc) {
     const graphEntry = resolveGraphEntryFromAuthoringDocument(doc);
     const dataFilters = graphEntry?.dataFilters;
@@ -30,6 +36,14 @@ function patchEntryGatesFromGraphEntryDataFilters(plan, doc) {
  * No legacy migration — graphs must already be Graphenix 2.x authoring shape.
  */
 export function compileExellixExecutablePlan(doc, runtime, options) {
+    const strictResponseValidation = options?.strictResponseValidation !== false;
+    // Ensure canonical response is present on authoring graph before plan compile (FR-GE-001).
+    const resolvedResponse = resolveAuthoringGraphResponse(doc);
+    assertGraphResponseDefinition(resolvedResponse);
+    const graphRecord = doc.graph;
+    if (!isPlainRecord(graphRecord.response)) {
+        graphRecord.response = resolvedResponse;
+    }
     const authoringValidation = validateAuthoringGraph(doc);
     if (!authoringValidation.valid) {
         const summary = authoringValidation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
@@ -41,5 +55,9 @@ export function compileExellixExecutablePlan(doc, runtime, options) {
         const summary = planValidation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
         throw new Error(`compileExellixExecutablePlan: invalid plan: ${summary}`);
     }
+    if (strictResponseValidation) {
+        const planWiring = validateGraphResponseWiring(plan);
+        assertGraphResponseWiringOk(planWiring, { graphId: plan.source.graphId });
+    }
     return plan;
 }

package/dist/src/contract/graphRunContract.js

@@ -65,6 +65,9 @@ export function mergeGraphRunPersistency(base, override) {
     };
 }
 function mergeRawPersistency(base, rawOverride) {
+    // Explicit null on a run/work/job disables result writeback (simulation).
+    if (rawOverride === null)
+        return null;
     const overrideRec = asRecord(rawOverride);
     if (!overrideRec)
         return base;
@@ -98,12 +101,6 @@ function readPersistency(graph) {
     if (fromResponse) {
         return normalizePersistency(fromResponse);
     }
-    const metadata = asRecord(graph.metadata);
-    const graphResponse = asRecord(metadata?.graphResponse);
-    const legacy = asRecord(graphResponse?.persistency);
-    if (legacy) {
-        return normalizePersistency(legacy);
-    }
     return null;
 }
 /** Read graph document version from published graph JSON (`version` or `metadata.version`). */

package/dist/src/index.d.ts

@@ -16,7 +16,7 @@ export type { HostExecuteGraphRunOptions, MainReadinessPolicy, ExecutionStepOpti
 export type { AiTaskProfileMetadata, AiTaskProfileInputSynthesis, } from './types/aiTaskProfile.js';
 export { hasWebScopeAuthoring } from './types/aiTaskProfile.js';
 export type { ExecutionStrategyInvocation, ExecutionStrategyPhase, ExecutionStrategyWrapperKey, SmartInputConfig, TaskStrategyItemData, XynthesizedDestinationScope, XynthesizedMemory, XynthesizedOutputConfig, } from './types/aiTasksDerivedTypes.js';
-export type { Graph, GraphModelObject, GraphAiModelConfig, PartialGraphAiModelConfig, GraphModelAliasConfig, GraphRuntimeNodeConfig, TaskNodeRuntimeObject, GraphDocumentMetadata, GraphEntryContract, GraphResponseDefinition, GraphResponseMissingBehavior, GraphResponseSelector, GraphResponseShape, GraphResponseContract, GraphResponseMapping, GraphResponseMappingMissingBehavior, GraphResponseMappingSelector, GraphResponseMappingTarget, GraphExecutionDefaults, GraphExecutionMode, GraphOutputMode, GraphFlowOutline, GraphCoreObjective, GraphNodesResponses, GraphNode, TaskNode, TaskNodeConditions, TaskNodeConditionWhen, TaskNodeJsonCondition, TaskNodeJsConditionFunction, TaskNodeAiCondition, TaskNodeConditionParameters, ModelConfigSelection, ModelConfigCase, TaskNodePureMetadata, TaskNodeExecutionPipelineStep, TaskOutputValidation, FinalizerNode, FinalizerInputBinding, OutputSchema, AggregateFinalizerConfig, BundleFinalizerConfig, SelectFinalizerConfig, SynthesizeFinalizerConfig, UtilityExecutionPolicy, Job, CatalogPlanningKind, CatalogRequestStatus, CatalogBinding, ScopedQuestionCatalogRequestEntry, DiscoveryDefinitionCatalogRequestEntry, DiscoveryDefinitionCatalogRequest, DiscoveryDefinitionPlanningFields, CatalogRequestEntry, StructuredDataFiltersV1, ConditionsDataFilters, } from './types/refs.js';
+export type { Graph, GraphModelObject, GraphAiModelConfig, PartialGraphAiModelConfig, GraphModelAliasConfig, GraphRuntimeNodeConfig, TaskNodeRuntimeObject, GraphDocumentMetadata, GraphEntryContract, GraphResponseDefinition, GraphResponseMissingBehavior, GraphResponseSelector, GraphResponseCoercion, GraphResponseShape, GraphResponseContract, GraphResponseMapping, GraphResponseMappingMissingBehavior, GraphResponseMappingSelector, GraphResponseMappingTarget, GraphExecutionDefaults, GraphExecutionMode, GraphOutputMode, GraphFlowOutline, GraphCoreObjective, GraphNodesResponses, GraphNode, TaskNode, TaskNodeConditions, TaskNodeConditionWhen, TaskNodeJsonCondition, TaskNodeJsConditionFunction, TaskNodeAiCondition, TaskNodeConditionParameters, ModelConfigSelection, ModelConfigCase, TaskNodePureMetadata, TaskNodeExecutionPipelineStep, TaskOutputValidation, FinalizerNode, FinalizerInputBinding, OutputSchema, AggregateFinalizerConfig, BundleFinalizerConfig, SelectFinalizerConfig, SynthesizeFinalizerConfig, UtilityExecutionPolicy, Job, CatalogPlanningKind, CatalogRequestStatus, CatalogBinding, ScopedQuestionCatalogRequestEntry, DiscoveryDefinitionCatalogRequestEntry, DiscoveryDefinitionCatalogRequest, DiscoveryDefinitionPlanningFields, CatalogRequestEntry, StructuredDataFiltersV1, ConditionsDataFilters, } from './types/refs.js';
 export { mergeGraphDocumentModel, EXELLIX_GRAPH_MODEL_VARIABLE_KEY, EXELLIX_STRUCTURED_DATA_FILTERS_V1, } from './types/refs.js';
 export type { TaskNodeTaskConfiguration, TaskNodeScopedDataReaderPackSlot, } from './types/taskNodeConfiguration.js';
 export { getTaskConfiguration } from './types/taskNodeConfiguration.js';
@@ -95,6 +95,13 @@ export type { ExecutableGraphPlanV2, NodeExecutionPlan, ExecutionUnitPlanV2, } f
 export type { AuthoringGraphDocument } from '@x12i/graphenix-executable-contracts';
 export { compileExellixExecutablePlan } from './compile/compileExellixExecutablePlan.js';
 export type { CompileExellixExecutablePlanOptions } from './compile/compileExellixExecutablePlan.js';
+export { applyGraphResponseDefinition, resolveGraphResponse, assessGraphResponseCompleteness, GRAPH_RESPONSE_INCOMPLETE, } from './runtime/graphResponseMapping.js';
+export type { GraphResponseMappingContext, GraphResponseMappingError } from './runtime/graphResponseMapping.js';
+export { coerceStringArray } from './runtime/coerceStringArray.js';
+export { validateGraphResponseWiring, assertGraphResponseWiringOk, RESPONSE_PATH_NO_WRITER, TASK_MAP_TARGET_INVALID, TASK_MAP_SOURCE_INVALID, RESPONSE_LEGACY_SHAPE_KEY, EXECUTION_MAPPING_LEGACY_PATH, RESPONSE_EMPTY_SHAPE, RESPONSE_LEGACY_PRESET_ID, RESPONSE_COERCE_STRING_ARRAY_ON_SCALAR, } from './validation/validateGraphResponseWiring.js';
+export type { GraphResponseWiringIssue, GraphResponseWiringValidation, } from './validation/validateGraphResponseWiring.js';
+export { detectAuthoringResponseSourceIssues, resolveAuthoringGraphResponse, migrateLegacyGraphResponseToAuthoring, GRAPH_RESPONSE_LEGACY_SOURCE, GRAPH_RESPONSE_DUAL_SOURCE, } from './validation/authoringGraphResponse.js';
+export type { AuthoringResponseSourceIssue } from './validation/authoringGraphResponse.js';
 export { buildGraphExecutionRequestFromStudioExecute as buildAuthoringStudioGraphExecutionRequest } from '@x12i/graphenix-execute-envelope';
 export type { RunTaskRequest, RunTaskResponse, TasksClientLike, GraphLoader as RuntimeGraphLoader, ExecuteGraphInput, GraphExecutionRequest, GraphRuntimeObject, GraphKnowledgeResolver, GraphKnowledgeResolverContext, ExecuteGraphResult, ExellixGraphRuntimeOptions, } from './runtime/ExellixGraphRuntime.js';
 export type { PlanStatus, GraphPlan, GraphEngine, GraphEngineFactory, } from './runtime/GraphEngine.js';

package/dist/src/index.js

@@ -69,6 +69,10 @@ export { computeGraphDocumentContentSha256, stableStringifyGraphDocument, } from
 // New runtime with injection seam
 export { createExellixGraphRuntime } from './runtime/ExellixGraphRuntime.js';
 export { compileExellixExecutablePlan } from './compile/compileExellixExecutablePlan.js';
+export { applyGraphResponseDefinition, resolveGraphResponse, assessGraphResponseCompleteness, GRAPH_RESPONSE_INCOMPLETE, } from './runtime/graphResponseMapping.js';
+export { coerceStringArray } from './runtime/coerceStringArray.js';
+export { validateGraphResponseWiring, assertGraphResponseWiringOk, RESPONSE_PATH_NO_WRITER, TASK_MAP_TARGET_INVALID, TASK_MAP_SOURCE_INVALID, RESPONSE_LEGACY_SHAPE_KEY, EXECUTION_MAPPING_LEGACY_PATH, RESPONSE_EMPTY_SHAPE, RESPONSE_LEGACY_PRESET_ID, RESPONSE_COERCE_STRING_ARRAY_ON_SCALAR, } from './validation/validateGraphResponseWiring.js';
+export { detectAuthoringResponseSourceIssues, resolveAuthoringGraphResponse, migrateLegacyGraphResponseToAuthoring, GRAPH_RESPONSE_LEGACY_SOURCE, GRAPH_RESPONSE_DUAL_SOURCE, } from './validation/authoringGraphResponse.js';
 export { buildGraphExecutionRequestFromStudioExecute as buildAuthoringStudioGraphExecutionRequest } from '@x12i/graphenix-execute-envelope';
 // Testkit (in-memory loader, dep engine, recording client — sample NARRIX tasks: `@exellix/graph-engine/testkit`)
 export { InMemoryGraphLoader, DepGraphEngineFactory } from '../testkit/index.js';

package/dist/src/inspection/graphInspection.js

@@ -462,6 +462,10 @@ export function inspectGraph(graph) {
         ioEdges,
         catalogs,
         graphDocumentModel: mergeGraphDocumentModel(graph),
+        response: {
+            source: 'graph.response',
+            definition: graph.response,
+        },
         virtualIO,
     };
 }

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

@@ -264,6 +264,11 @@ export type GraphInspection = {
      * Graph `metadata` (same shape as `variables.__graphModel` during execution).
      */
     graphDocumentModel: GraphDocumentMetadata;
+    /** Executable response definition source — always `graph.response` in 9.x. */
+    response: {
+        source: 'graph.response';
+        definition: import('../types/refs.js').GraphResponseDefinition;
+    };
     /**
      * Virtual Layer 01 / 08 nodes and edges for visualization; not part of executable `nodes` / `edges`.
      */

package/dist/src/plan/embeddedGraphToExellixGraph.js

@@ -1,4 +1,5 @@
 import { getFinalizerNodeConfig, getTaskNodeConfig, isExecutableFinalizerNode, isExecutableTaskNode, } from '@x12i/graphenix-executable-contracts';
+import { GRAPH_RESPONSE_LEGACY_SOURCE } from '../validation/authoringGraphResponse.js';
 function isPlainRecord(v) {
     return v != null && typeof v === 'object' && !Array.isArray(v);
 }
@@ -82,24 +83,40 @@ function edgesFromPlan(plan) {
     });
 }
 function responseFromEmbedded(doc, plan) {
-    const metaResponse = doc.graph.metadata?.graphResponse;
-    if (isPlainRecord(metaResponse)) {
+    const graphRecord = doc.graph;
+    const graphLevel = graphRecord.response;
+    if (isPlainRecord(graphLevel) && 'shape' in graphLevel) {
         const out = {
-            shape: isPlainRecord(metaResponse.shape) ? structuredClone(metaResponse.shape) : {},
+            shape: isPlainRecord(graphLevel.shape) || Array.isArray(graphLevel.shape)
+                ? structuredClone(graphLevel.shape)
+                : graphLevel.shape ?? {},
         };
-        if (metaResponse.missing !== undefined) {
-            out.missing = metaResponse.missing;
-        }
-        if (metaResponse.version !== undefined) {
-            out.version = metaResponse.version;
+        if (graphLevel.missing !== undefined) {
+            out.missing = graphLevel.missing;
         }
         return out;
     }
+    const metaResponse = doc.graph.metadata?.graphResponse;
+    if (isPlainRecord(metaResponse) && hasExecutableMetadataResponse(metaResponse)) {
+        const err = new Error('Executable response mapping exists only under metadata.graphResponse. Move shape to graph.response — studio metadata is UI-only and is not read at compile or execute.');
+        err.code = GRAPH_RESPONSE_LEGACY_SOURCE;
+        throw err;
+    }
     if (isPlainRecord(plan.contracts?.response?.finalOutputSchema)) {
         return { shape: { type: 'literal', value: {} } };
     }
     return { shape: {} };
 }
+function hasExecutableMetadataResponse(metaResponse) {
+    const shape = metaResponse.shape;
+    if (shape === undefined)
+        return false;
+    if (isPlainRecord(shape))
+        return Object.keys(shape).length > 0;
+    if (Array.isArray(shape))
+        return shape.length > 0;
+    return true;
+}
 /** Materialize exellix {@link Graph} from plan embedded normalized authoring graph. */
 export function embeddedGraphToExellixGraph(plan) {
     if (plan.normalizedGraph.mode !== 'embedded') {

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

@@ -100,8 +100,8 @@ export interface ExecuteGraphResult {
         nodeId?: string;
         error: any;
     }>;
-    /** Final execution object (includes `_trace.nodes` for per-node timing). */
-    execution?: unknown;
+    /** Final execution object (includes `_trace.nodes` for per-node timing). Always present on graph runs (FR-GE-005). */
+    execution: Record<string, unknown>;
     /** Final graph-engine-owned output memory accumulated from finalizer `outputMapping` writes. */
     outputsMemory?: unknown;
     runLog?: RunLogEntry[];

package/dist/src/runtime/ExellixGraphRuntime.js

@@ -19,7 +19,7 @@ import { assertFinalizerRequiredReadsResolvable, validateGraphFinalizer, } from
 import { executeDeterministicFinalizer, executeSynthesizeFinalizer } from "./finalizers/executeFinalizer.js";
 import { createFinalizerError } from "./finalizers/errors.js";
 import { assertCanonicalGraphRuntimeObject } from "./validateCanonicalGraphRuntime.js";
-import { applyGraphResponseDefinition } from "./graphResponseMapping.js";
+import { applyGraphResponseDefinition, assessGraphResponseCompleteness, GRAPH_RESPONSE_INCOMPLETE } from "./graphResponseMapping.js";
 import { buildAiTasksObservabilityRecord } from "./aiTasksObservability.js";
 import { buildRunTaskIdentityEnvelope, shouldForwardRunTaskTraceMode, } from "./runTaskAugments.js";
 import { buildRunLog, extractLogxerCorrelationFromMetadata, extractTaskRunLogFromMetadata, resolveRunLogLimits, } from "./buildRunLog.js";
@@ -1172,7 +1172,7 @@ export function createExellixGraphRuntime(opts) {
                         logxerCorrelationId: logxerCorrelationIdLast,
                     });
                     return {
-                        execution: currentExecution,
+                        execution: (isPlainRecord(currentExecution) ? currentExecution : {}),
                         outputsMemory: currentOutputsMemory,
                         ...built,
                     };
@@ -1256,7 +1256,7 @@ export function createExellixGraphRuntime(opts) {
                     const executionMemoryForResponse = isPlainRecord(currentExecution)
                         ? structuredClone(currentExecution)
                         : currentExecution;
-                    return applyGraphResponseDefinition({
+                    const finalOutput = applyGraphResponseDefinition({
                         response: graph.response,
                         context: {
                             graph,
@@ -1268,6 +1268,38 @@ export function createExellixGraphRuntime(opts) {
                             stepsResponses,
                         },
                     });
+                    const completeness = assessGraphResponseCompleteness(graph.response, finalOutput);
+                    if (completeness.incomplete) {
+                        return {
+                            responseErrors: [
+                                {
+                                    code: completeness.code ?? GRAPH_RESPONSE_INCOMPLETE,
+                                    message: completeness.message ?? 'graph.response resolved empty.',
+                                },
+                            ],
+                        };
+                    }
+                    return finalOutput !== undefined ? { finalOutput } : {};
+                }
+                function resolveGraphRunFinalOutput(baseErrors = errors) {
+                    const resolved = buildFinalOutputFromGraphResponse();
+                    if (resolved.responseErrors?.length) {
+                        return {
+                            errors: [
+                                ...baseErrors,
+                                ...resolved.responseErrors.map((re) => {
+                                    const e = new Error(re.message);
+                                    e.code = re.code;
+                                    return { error: e };
+                                }),
+                            ],
+                            responseFailed: true,
+                        };
+                    }
+                    return {
+                        finalOutput: resolved.finalOutput,
+                        errors: baseErrors,
+                    };
                 }
                 const playgroundReporter = runtime.playgroundReporter ?? opts.playgroundReporter;
                 if (playgroundReporter) {
@@ -1314,7 +1346,7 @@ export function createExellixGraphRuntime(opts) {
                         taskId: graphTaskId,
                         error: err,
                     });
-                    const finalOutput = buildFinalOutputFromGraphResponse();
+                    const responseResolution = resolveGraphRunFinalOutput([...errors, { error: err }]);
                     appendExecutionEvent(executionTrace, {
                         id: `evt:${graphTaskId}:graph.failed`,
                         ts: new Date().toISOString(),
@@ -1330,8 +1362,8 @@ export function createExellixGraphRuntime(opts) {
                         outputsByNodeId,
                         stepsResponses,
                         engineSnapshot: engine.snapshot(),
-                        ...(finalOutput !== undefined ? { finalOutput } : {}),
-                        errors: [...errors, { error: err }],
+                        ...(responseResolution.finalOutput !== undefined ? { finalOutput: responseResolution.finalOutput } : {}),
+                        errors: responseResolution.errors,
                         planAudit,
                         trace: executionTrace,
                         ...finalizeGraphPayload("failed"),
@@ -1350,8 +1382,8 @@ export function createExellixGraphRuntime(opts) {
                 while (true) {
                     const wavePlan = engine.plan();
                     if (wavePlan.status === "completed") {
-                        const graphStatus = errors.length ? "failed" : "completed";
-                        const finalOutput = buildFinalOutputFromGraphResponse();
+                        const responseResolution = resolveGraphRunFinalOutput();
+                        const graphStatus = errors.length || responseResolution.responseFailed ? "failed" : "completed";
                         appendExecutionEvent(executionTrace, {
                             id: `evt:${graphTaskId}:graph.${graphStatus}`,
                             ts: new Date().toISOString(),
@@ -1360,6 +1392,7 @@ export function createExellixGraphRuntime(opts) {
                             message: `Graph execution ${graphStatus}.`,
                         });
                         validateExecutionTrace(executionTrace, plan);
+                        const resultErrors = responseResolution.errors.length ? responseResolution.errors : undefined;
                         const result = {
                             jobId,
                             taskId: graphTaskId,
@@ -1368,9 +1401,9 @@ export function createExellixGraphRuntime(opts) {
                             outputsByNodeId,
                             stepsResponses,
                             engineSnapshot: engine.snapshot(),
-                            ...(finalOutput !== undefined ? { finalOutput } : {}),
-                            ...(errors.length === 0 ? { finalizerNodeId, finalizerType: finalizer.finalizerType } : {}),
-                            errors: errors.length ? errors : undefined,
+                            ...(responseResolution.finalOutput !== undefined ? { finalOutput: responseResolution.finalOutput } : {}),
+                            ...(graphStatus === "completed" ? { finalizerNodeId, finalizerType: finalizer.finalizerType } : {}),
+                            errors: resultErrors,
                             planAudit,
                             trace: executionTrace,
                             ...finalizeGraphPayload(graphStatus),
@@ -1381,14 +1414,14 @@ export function createExellixGraphRuntime(opts) {
                         if (eventEmitter) {
                             if (graphStatus === "completed") {
                                 eventEmitter.emit(createGraphCompleteEvent(jobId, resolvedGraphId, graphTaskId, {
-                                    output: finalOutput,
+                                    output: responseResolution.finalOutput,
                                     nodesExecuted: Object.keys(outputsByNodeId).length,
                                     finalMemory: { jobMemory: currentJobMemory, taskMemory: currentTaskMemory, execution: currentExecution, outputsMemory: currentOutputsMemory },
                                     ...(jobCorrelation ?? {}),
                                 }));
                             }
                             else {
-                                eventEmitter.emit(createGraphFailEvent(jobId, resolvedGraphId, graphTaskId, errors[0]?.error, {
+                                eventEmitter.emit(createGraphFailEvent(jobId, resolvedGraphId, graphTaskId, responseResolution.errors[0]?.error ?? errors[0]?.error, {
                                     finalMemory: { jobMemory: currentJobMemory, taskMemory: currentTaskMemory, execution: currentExecution, outputsMemory: currentOutputsMemory },
                                     ...(jobCorrelation ?? {}),
                                 }));
@@ -1399,7 +1432,7 @@ export function createExellixGraphRuntime(opts) {
                     if (wavePlan.status !== "continue") {
                         const err = new Error(`GRAPH_BLOCKED: status=${wavePlan.status}`);
                         err.code = "GRAPH_BLOCKED";
-                        const finalOutput = buildFinalOutputFromGraphResponse();
+                        const responseResolution = resolveGraphRunFinalOutput([...errors, { error: err }]);
                         const result = {
                             jobId,
                             taskId: graphTaskId,
@@ -1408,8 +1441,8 @@ export function createExellixGraphRuntime(opts) {
                             outputsByNodeId,
                             stepsResponses,
                             engineSnapshot: engine.snapshot(),
-                            ...(finalOutput !== undefined ? { finalOutput } : {}),
-                            errors: [...errors, { error: err }],
+                            ...(responseResolution.finalOutput !== undefined ? { finalOutput: responseResolution.finalOutput } : {}),
+                            errors: responseResolution.errors,
                             planAudit,
                             trace: executionTrace,
                             ...finalizeGraphPayload("failed"),
@@ -1651,7 +1684,7 @@ export function createExellixGraphRuntime(opts) {
                             throw e;
                     });
                     if (failFast && errors.length) {
-                        const finalOutput = buildFinalOutputFromGraphResponse();
+                        const responseResolution = resolveGraphRunFinalOutput();
                         const result = {
                             jobId,
                             taskId: graphTaskId,
@@ -1660,8 +1693,8 @@ export function createExellixGraphRuntime(opts) {
                             outputsByNodeId,
                             stepsResponses,
                             engineSnapshot: engine.snapshot(),
-                            ...(finalOutput !== undefined ? { finalOutput } : {}),
-                            errors,
+                            ...(responseResolution.finalOutput !== undefined ? { finalOutput: responseResolution.finalOutput } : {}),
+                            errors: responseResolution.errors,
                             planAudit,
                             trace: executionTrace,
                             ...finalizeGraphPayload("failed"),

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

@@ -0,0 +1,5 @@
+/**
+ * Output-only coercion for graph.response selectors with `coerce: 'stringArray'`.
+ * Same semantics as graphs-playground normalizeQaAnswersArrayFinalOutput field rules.
+ */
+export declare function coerceStringArray(value: unknown): unknown;

package/dist/src/runtime/coerceStringArray.js

@@ -0,0 +1,34 @@
+/**
+ * Output-only coercion for graph.response selectors with `coerce: 'stringArray'`.
+ * Same semantics as graphs-playground normalizeQaAnswersArrayFinalOutput field rules.
+ */
+export function coerceStringArray(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (Array.isArray(value)) {
+        return value
+            .filter((item) => item != null)
+            .map((item) => String(item).trim())
+            .filter((item) => item.length > 0);
+    }
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return [];
+    if (trimmed.startsWith('[')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed)) {
+                return parsed
+                    .filter((item) => item != null)
+                    .map((item) => String(item).trim())
+                    .filter((item) => item.length > 0);
+            }
+        }
+        catch {
+            // fall through to single-element wrap
+        }
+    }
+    return [trimmed];
+}

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

@@ -18,6 +18,17 @@ export declare function applyGraphResponseDefinition(args: {
     response: GraphResponseDefinition;
     context: GraphResponseMappingContext;
 }): unknown;
+/** Resolves root `graph.response` against accumulated execution memory (FR-GE-002). */
+export declare const resolveGraphResponse: typeof applyGraphResponseDefinition;
 /** @deprecated Use applyGraphResponseDefinition with root-level graph.response. */
 export declare const applyGraphResponseMapping: typeof applyGraphResponseDefinition;
+export declare const GRAPH_RESPONSE_INCOMPLETE: "GRAPH_RESPONSE_INCOMPLETE";
+/**
+ * When graph.response.shape is non-empty but resolution yields an empty object, surface FR-GE-006.
+ */
+export declare function assessGraphResponseCompleteness(response: GraphResponseDefinition, finalOutput: unknown): {
+    incomplete: boolean;
+    code?: typeof GRAPH_RESPONSE_INCOMPLETE;
+    message?: string;
+};
 export {};

package/dist/src/runtime/graphResponseMapping.js

@@ -1,3 +1,4 @@
+import { coerceStringArray } from './coerceStringArray.js';
 import { selectByPath } from './pathExpr.js';
 import { readTaskNodeModelInputSurface, } from './readTaskNodeInputsConfig.js';
 const GRAPH_RESPONSE_MAPPING_ERROR_CODE = 'GRAPH_RESPONSE_MAPPING_INVALID';
@@ -69,20 +70,31 @@ function materializeMissing(missing) {
 function presentOrMissing(value, missing) {
     return value === undefined || value === null ? materializeMissing(missing) : value;
 }
+function applySelectorCoercion(value, selector, path) {
+    const coerce = selector.coerce;
+    if (coerce === undefined)
+        return value;
+    if (coerce !== 'stringArray') {
+        throw createGraphResponseMappingError(`Unsupported graph.response selector coercion "${String(coerce)}".`, path, { coerce });
+    }
+    return coerceStringArray(value);
+}
 function resolveSelector(selector, context, path, missing) {
     if (selector.type === 'literal') {
         if (!Object.prototype.hasOwnProperty.call(selector, 'value')) {
             throw createGraphResponseMappingError('literal selector requires a value field.', `${path}.value`);
         }
-        return selector.value;
+        return applySelectorCoercion(selector.value, selector, path);
     }
     if (selector.type === 'outputsMemoryPath') {
         const sourcePath = assertNonEmptyString(selector.path, `${path}.path`, `${selector.type}.path`);
-        return presentOrMissing(selectByPath(context.outputsMemory, sourcePath), missing);
+        const resolved = presentOrMissing(selectByPath(context.outputsMemory, sourcePath), missing);
+        return resolved === OMIT ? resolved : applySelectorCoercion(resolved, selector, path);
     }
     if (selector.type === 'executionMemoryPath' || selector.type === 'executionPath') {
         const sourcePath = assertNonEmptyString(selector.path, `${path}.path`, `${selector.type}.path`);
-        return presentOrMissing(selectByPath(context.executionMemory, sourcePath), missing);
+        const resolved = presentOrMissing(selectByPath(context.executionMemory, sourcePath), missing);
+        return resolved === OMIT ? resolved : applySelectorCoercion(resolved, selector, path);
     }
     if (selector.type === 'nodeMetadata') {
         const nodeId = assertNonEmptyString(selector.nodeId, `${path}.nodeId`, `${selector.type}.nodeId`);
@@ -91,7 +103,8 @@ function resolveSelector(selector, context, path, missing) {
         if (!node) {
             throw createGraphResponseMappingError(`${selector.type} selector references missing nodeId "${nodeId}".`, `${path}.nodeId`, { nodeId });
         }
-        return presentOrMissing(selectByPath(node.metadata, sourcePath), missing);
+        const resolved = presentOrMissing(selectByPath(node.metadata, sourcePath), missing);
+        return resolved === OMIT ? resolved : applySelectorCoercion(resolved, selector, path);
     }
     if (selector.type === 'nodeInputsConfig') {
         const inputSelector = selector;
@@ -102,7 +115,8 @@ function resolveSelector(selector, context, path, missing) {
             throw createGraphResponseMappingError(`${selector.type} selector references missing nodeId "${nodeId}".`, `${path}.nodeId`, { nodeId });
         }
         const root = readTaskNodeModelInputSurface(node);
-        return presentOrMissing(selectByPath(root, sourcePath), missing);
+        const resolved = presentOrMissing(selectByPath(root, sourcePath), missing);
+        return resolved === OMIT ? resolved : applySelectorCoercion(resolved, selector, path);
     }
     if (selector.type === 'firstPresent') {
         if (!Array.isArray(selector.sources) || selector.sources.length === 0) {
@@ -114,10 +128,12 @@ function resolveSelector(selector, context, path, missing) {
                 throw createGraphResponseMappingError('firstPresent.sources entries must be graph response mapping selectors.', `${path}.sources.${i}`);
             }
             const value = resolveSelector(source, context, `${path}.sources.${i}`, 'omit');
-            if (value !== OMIT && value !== null)
-                return value;
+            if (value !== OMIT && value !== null) {
+                return applySelectorCoercion(value, selector, path);
+            }
         }
-        return materializeMissing(missing);
+        const missingValue = materializeMissing(missing);
+        return missingValue === OMIT ? missingValue : applySelectorCoercion(missingValue, selector, path);
     }
     throw createGraphResponseMappingError(`Unsupported graph response mapping selector type "${String(selector.type)}".`, `${path}.type`);
 }
@@ -151,5 +167,42 @@ export function applyGraphResponseDefinition(args) {
     const mapped = resolveShape(args.response.shape, args.context, 'graph.response.shape', missing);
     return mapped === OMIT ? undefined : mapped;
 }
+/** Resolves root `graph.response` against accumulated execution memory (FR-GE-002). */
+export const resolveGraphResponse = applyGraphResponseDefinition;
 /** @deprecated Use applyGraphResponseDefinition with root-level graph.response. */
 export const applyGraphResponseMapping = applyGraphResponseDefinition;
+export const GRAPH_RESPONSE_INCOMPLETE = 'GRAPH_RESPONSE_INCOMPLETE';
+function isNonEmptyResponseShape(shape) {
+    if (shape == null)
+        return false;
+    if (Array.isArray(shape))
+        return shape.length > 0;
+    if (isPlainObject(shape))
+        return Object.keys(shape).length > 0;
+    return isSupportedSelector(shape);
+}
+function isEmptyResolvedOutput(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (isPlainObject(value))
+        return Object.keys(value).length === 0;
+    return false;
+}
+/**
+ * When graph.response.shape is non-empty but resolution yields an empty object, surface FR-GE-006.
+ */
+export function assessGraphResponseCompleteness(response, finalOutput) {
+    if (!isNonEmptyResponseShape(response.shape)) {
+        return { incomplete: false };
+    }
+    if (!isEmptyResolvedOutput(finalOutput)) {
+        return { incomplete: false };
+    }
+    return {
+        incomplete: true,
+        code: GRAPH_RESPONSE_INCOMPLETE,
+        message: 'graph.response.shape is non-empty but finalOutput resolved empty — check executionMapping paths and selectors.',
+    };
+}

package/dist/src/runtime/validateCanonicalGraphDocument.js

@@ -40,6 +40,8 @@ const FORBIDDEN_GRAPH_RESPONSE_KEYS = [
     'notableExecutionPaths',
     'mappingPreset',
 ];
+const LEGACY_RESPONSE_SHAPE_KEYS = new Set(['subnetAnalysis', 'taskSections']);
+const LEGACY_EXECUTION_MAPPING_PATH_RE = /^inference\.conceptSketch(\.|$)/;
 /**
  * Returns top-level keys on `graph` that are not part of the canonical executable document contract.
  */
@@ -431,6 +433,11 @@ function assertGraphResponseShapeNoLegacy(shape, path, context) {
     }
     if (!isPlainObject(shape))
         return;
+    for (const key of Object.keys(shape)) {
+        if (LEGACY_RESPONSE_SHAPE_KEYS.has(key)) {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path}.${key} is a removed legacy response shape key.`, { ...context, responseShapeKey: key });
+        }
+    }
     if (shape.type === 'nodeInputs') {
         throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${path}.type "nodeInputs" was removed; use nodeInputsConfig.`, context);
     }
@@ -478,7 +485,21 @@ export function assertCanonicalTaskNode(node, context, options) {
     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) });
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": TASK_OUTPUT_MAPPING_DEPRECATED — outputMapping belongs on the finalizer. Use executionMapping to write task results into executionMemory.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+    }
+    const executionMapping = node.executionMapping;
+    if (executionMapping?.path &&
+        typeof executionMapping.path === 'string' &&
+        LEGACY_EXECUTION_MAPPING_PATH_RE.test(executionMapping.path)) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": EXECUTION_MAPPING_LEGACY_PATH — use answers.qN instead of inference.conceptSketch.stepN.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+    }
+    const map = executionMapping?.map;
+    if (isPlainObject(map)) {
+        for (const targetKey of Object.keys(map)) {
+            if (targetKey.includes('.')) {
+                throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_TASK_NODE, `Task node "${String(node.id)}": TASK_MAP_TARGET_INVALID — executionMapping.map target "${targetKey}" must be flat.`, { jobId: context?.jobId, graphId: context?.graphId, nodeId: String(node.id) });
+            }
+        }
     }
     assertOptionalTaskNodeConditions(node.conditions, String(node.id), {
         jobId: context?.jobId,
@@ -670,6 +691,10 @@ export function assertCanonicalGraphDocument(graph, context, options) {
             jobId: context?.jobId,
             graphId: resolvedGraphId,
         });
+        const preset = metadata.responsePreset;
+        if (isPlainObject(preset) && preset.id === 'subnetAnalysis') {
+            throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, 'metadata.responsePreset.id "subnetAnalysis" was removed — migrate to graph.response.shape.', { jobId: context?.jobId, graphId: resolvedGraphId });
+        }
         const graphEntry = metadata.graphEntry;
         if (graphEntry != null && typeof graphEntry === 'object' && !Array.isArray(graphEntry)) {
             const ge = graphEntry;

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

@@ -133,30 +133,35 @@ export type FinalizerInputBinding = {
     value: unknown;
 };
 export type GraphResponseMissingBehavior = 'omit' | 'null';
-export type GraphResponseSelector = {
+/** Post-resolution output coercion (9.x). Only `stringArray` is supported in 9.0. */
+export type GraphResponseCoercion = 'stringArray';
+type GraphResponseSelectorBase = {
+    coerce?: GraphResponseCoercion;
+};
+export type GraphResponseSelector = (GraphResponseSelectorBase & {
     type: 'outputsMemoryPath';
     path: string;
-} | {
+}) | (GraphResponseSelectorBase & {
     type: 'executionMemoryPath';
     path: string;
-} | {
+}) | (GraphResponseSelectorBase & {
     type: 'executionPath';
     path: string;
-} | {
+}) | (GraphResponseSelectorBase & {
     type: 'nodeMetadata';
     nodeId: string;
     path: string;
-} | {
+}) | (GraphResponseSelectorBase & {
     type: 'nodeInputsConfig';
     nodeId: string;
     path: string;
-} | {
+}) | (GraphResponseSelectorBase & {
     type: 'literal';
     value: unknown;
-} | {
+}) | (GraphResponseSelectorBase & {
     type: 'firstPresent';
     sources: GraphResponseSelector[];
-};
+});
 export type GraphResponseShape = unknown;
 export type GraphResponseDefinition = {
     /** Default: "omit". When "null", missing selector values are materialized as null. */

package/dist/src/validation/authoringGraphResponse.d.ts

@@ -0,0 +1,21 @@
+import type { AuthoringGraphDocument } from '@x12i/graphenix-executable-contracts';
+import type { GraphResponseDefinition } from '../types/refs.js';
+export declare const GRAPH_RESPONSE_LEGACY_SOURCE: "GRAPH_RESPONSE_LEGACY_SOURCE";
+export declare const GRAPH_RESPONSE_DUAL_SOURCE: "GRAPH_RESPONSE_DUAL_SOURCE";
+export type AuthoringResponseSourceIssue = {
+    code: typeof GRAPH_RESPONSE_LEGACY_SOURCE | typeof GRAPH_RESPONSE_DUAL_SOURCE;
+    message: string;
+    path?: string;
+};
+/**
+ * Import-only helper: copy metadata.graphResponse → graph.response when graph.response is absent.
+ * Does not run on the execute hot path.
+ */
+export declare function migrateLegacyGraphResponseToAuthoring(doc: AuthoringGraphDocument): AuthoringGraphDocument;
+/** Detect legacy-only or dual authoring response sources (FR-GE-001 / CR-GE-001). */
+export declare function detectAuthoringResponseSourceIssues(doc: AuthoringGraphDocument): AuthoringResponseSourceIssue[];
+/**
+ * Resolves the single canonical authoring response definition.
+ * @throws Error with code GRAPH_RESPONSE_LEGACY_SOURCE when only legacy metadata carries the shape.
+ */
+export declare function resolveAuthoringGraphResponse(doc: AuthoringGraphDocument): GraphResponseDefinition;

package/dist/src/validation/authoringGraphResponse.js

@@ -0,0 +1,88 @@
+export const GRAPH_RESPONSE_LEGACY_SOURCE = 'GRAPH_RESPONSE_LEGACY_SOURCE';
+export const GRAPH_RESPONSE_DUAL_SOURCE = 'GRAPH_RESPONSE_DUAL_SOURCE';
+/**
+ * Import-only helper: copy metadata.graphResponse → graph.response when graph.response is absent.
+ * Does not run on the execute hot path.
+ */
+export function migrateLegacyGraphResponseToAuthoring(doc) {
+    const next = structuredClone(doc);
+    const graph = next.graph;
+    const hasGraphResponse = isPlainRecord(graph.response) && 'shape' in graph.response;
+    const metaResponse = next.graph.metadata?.graphResponse;
+    if (!hasGraphResponse && isPlainRecord(metaResponse) && 'shape' in metaResponse) {
+        graph.response = {
+            ...(metaResponse.missing !== undefined ? { missing: metaResponse.missing } : {}),
+            shape: structuredClone(metaResponse.shape),
+        };
+    }
+    return next;
+}
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function hasExecutableResponseShape(response) {
+    if (!isPlainRecord(response))
+        return false;
+    const shape = response.shape;
+    if (shape === undefined)
+        return false;
+    if (isPlainRecord(shape))
+        return Object.keys(shape).length > 0;
+    if (Array.isArray(shape))
+        return shape.length > 0;
+    return true;
+}
+function readGraphLevelResponse(doc) {
+    const graph = doc.graph;
+    const response = graph.response;
+    if (!isPlainRecord(response) || !('shape' in response))
+        return undefined;
+    return response;
+}
+function readMetadataGraphResponse(doc) {
+    const metaResponse = doc.graph.metadata?.graphResponse;
+    if (!isPlainRecord(metaResponse) || !('shape' in metaResponse))
+        return undefined;
+    return metaResponse;
+}
+/** Detect legacy-only or dual authoring response sources (FR-GE-001 / CR-GE-001). */
+export function detectAuthoringResponseSourceIssues(doc) {
+    const issues = [];
+    const graphResponse = readGraphLevelResponse(doc);
+    const metaResponse = readMetadataGraphResponse(doc);
+    const graphHasShape = graphResponse != null && hasExecutableResponseShape(graphResponse);
+    const metaHasShape = metaResponse != null && hasExecutableResponseShape(metaResponse);
+    if (!graphHasShape && metaHasShape) {
+        issues.push({
+            code: GRAPH_RESPONSE_LEGACY_SOURCE,
+            message: 'Executable response mapping exists only under metadata.graphResponse. Move shape to graph.response — studio metadata is UI-only and is not read at compile or execute.',
+            path: 'graph.metadata.graphResponse',
+        });
+    }
+    if (graphHasShape && metaHasShape) {
+        issues.push({
+            code: GRAPH_RESPONSE_DUAL_SOURCE,
+            message: 'Response mapping is declared on both graph.response and metadata.graphResponse. graph.response is authoritative; remove executable shape from metadata.graphResponse.',
+            path: 'graph.metadata.graphResponse',
+        });
+    }
+    return issues;
+}
+/**
+ * Resolves the single canonical authoring response definition.
+ * @throws Error with code GRAPH_RESPONSE_LEGACY_SOURCE when only legacy metadata carries the shape.
+ */
+export function resolveAuthoringGraphResponse(doc) {
+    const issues = detectAuthoringResponseSourceIssues(doc);
+    const blocking = issues.find((i) => i.code === GRAPH_RESPONSE_LEGACY_SOURCE);
+    if (blocking) {
+        const err = new Error(blocking.message);
+        err.code = GRAPH_RESPONSE_LEGACY_SOURCE;
+        err.path = blocking.path;
+        throw err;
+    }
+    const graphResponse = readGraphLevelResponse(doc);
+    if (graphResponse)
+        return graphResponse;
+    return { shape: {} };
+}

package/dist/src/validation/validateGraphResponseWiring.d.ts

@@ -0,0 +1,26 @@
+import type { AuthoringGraphDocument, ExecutableGraphPlanV2 } from '@x12i/graphenix-executable-contracts';
+import type { Graph } from '../types/refs.js';
+export declare const RESPONSE_PATH_NO_WRITER: "RESPONSE_PATH_NO_WRITER";
+export declare const TASK_MAP_TARGET_INVALID: "TASK_MAP_TARGET_INVALID";
+export declare const TASK_MAP_SOURCE_INVALID: "TASK_MAP_SOURCE_INVALID";
+export declare const RESPONSE_LEGACY_SHAPE_KEY: "RESPONSE_LEGACY_SHAPE_KEY";
+export declare const EXECUTION_MAPPING_LEGACY_PATH: "EXECUTION_MAPPING_LEGACY_PATH";
+export declare const RESPONSE_EMPTY_SHAPE: "RESPONSE_EMPTY_SHAPE";
+export declare const RESPONSE_LEGACY_PRESET_ID: "RESPONSE_LEGACY_PRESET_ID";
+export declare const RESPONSE_COERCE_STRING_ARRAY_ON_SCALAR: "RESPONSE_COERCE_STRING_ARRAY_ON_SCALAR";
+export type GraphResponseWiringIssue = {
+    code: string;
+    message: string;
+    nodeId?: string;
+    path?: string;
+};
+export type GraphResponseWiringValidation = {
+    ok: boolean;
+    errors: GraphResponseWiringIssue[];
+    warnings: GraphResponseWiringIssue[];
+};
+/** Validate response wiring for an authoring document, executable plan, or materialized graph. */
+export declare function validateGraphResponseWiring(input: AuthoringGraphDocument | ExecutableGraphPlanV2 | Graph): GraphResponseWiringValidation;
+export declare function assertGraphResponseWiringOk(validation: GraphResponseWiringValidation, context?: {
+    graphId?: string;
+}): void;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-engine",
-  "version": "8.7.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/graph-run-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: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",