@exellix/graph-engine 8.6.0 → 9.0.0

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/executionMatrixHost.d.ts

@@ -1,5 +1,5 @@
 /**
- * Host helpers for execution-matrix style orchestrators (e.g. `@exellix/exellix-runtime`).
+ * Host helpers for execution-matrix style orchestrators (e.g. `@x12i/exellix-runtime`).
  *
  * Graph-engine does not call matrix claim APIs; the host injects `executeGraph` and supplies
  * a `{ plan, runtime }` request with per-graph `GraphEntryContract` + seeded
@@ -83,7 +83,7 @@ export declare function buildMatrixJobForGraphRun(input: {
 export declare function isExecuteGraphResultFailed(result: ExecuteGraphResult): boolean;
 /**
  * Creates a long-lived graph runtime and exposes `executeGraph` for injection into matrix claim
- * processors (`ProcessMatrixClaimDeps.executeGraph` in `@exellix/exellix-runtime`, etc.).
+ * processors (`ProcessMatrixClaimDeps.executeGraph` in `@x12i/exellix-runtime`, etc.).
  */
 export declare function createMatrixHostGraphExecutor(options: ExellixGraphRuntimeOptions): {
     executeGraph: (input: ExecuteGraphInput) => Promise<ExecuteGraphResult>;

package/dist/src/runtime/executionMatrixHost.js

@@ -1,5 +1,5 @@
 /**
- * Host helpers for execution-matrix style orchestrators (e.g. `@exellix/exellix-runtime`).
+ * Host helpers for execution-matrix style orchestrators (e.g. `@x12i/exellix-runtime`).
  *
  * Graph-engine does not call matrix claim APIs; the host injects `executeGraph` and supplies
  * a `{ plan, runtime }` request with per-graph `GraphEntryContract` + seeded
@@ -92,7 +92,7 @@ export function isExecuteGraphResultFailed(result) {
 }
 /**
  * Creates a long-lived graph runtime and exposes `executeGraph` for injection into matrix claim
- * processors (`ProcessMatrixClaimDeps.executeGraph` in `@exellix/exellix-runtime`, etc.).
+ * processors (`ProcessMatrixClaimDeps.executeGraph` in `@x12i/exellix-runtime`, etc.).
  */
 export function createMatrixHostGraphExecutor(options) {
     const { executeGraph } = createExellixGraphRuntime(options);

package/dist/src/runtime/graphEngineLogMeta.js

@@ -1,10 +1,10 @@
-import { EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME } from './runtimeObjects.js';
+import { X12I_GRAPH_RUNTIME_PACKAGE_NAME } from './runtimeObjects.js';
 /** Canonical filter key for graph-engine's own log lines. */
 export const GRAPH_ENGINE_RUNTIME_SERVICE = 'graph-engine';
 /** Wrapper attribution when graph-engine proxies a downstream Logxer record. */
 export const GRAPH_ENGINE_PROXY_RUNTIME_IDENTITY = {
     service: GRAPH_ENGINE_RUNTIME_SERVICE,
-    libraryPackage: EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME,
+    libraryPackage: X12I_GRAPH_RUNTIME_PACKAGE_NAME,
 };
 function isRecord(value) {
     return value != null && typeof value === 'object' && !Array.isArray(value);

package/dist/src/runtime/graphEngineLogxer.js

@@ -1,6 +1,6 @@
 const logxer = await import('@x12i/logxer');
 import { ExellixGraphErrorCode } from '../errors/exellixGraphErrorCodes.js';
-import { EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME } from './runtimeObjects.js';
+import { X12I_GRAPH_RUNTIME_PACKAGE_NAME } from './runtimeObjects.js';
 import { normalizeGraphEngineLogMeta, } from './graphEngineLogMeta.js';
 export { GRAPH_ENGINE_RUNTIME_SERVICE, GRAPH_ENGINE_PROXY_RUNTIME_IDENTITY, extractOriginRuntimeIdentity, normalizeGraphEngineLogMeta, } from './graphEngineLogMeta.js';
 /** Env prefix for package-level log level: `GRAPH_ENGINE_LOGS_LEVEL` (canonical). */
@@ -116,7 +116,7 @@ function wrapGraphEngineLogxer(inner) {
 /** Factory for a graph-engine Logxer instance (logxer 4.5+ stack pass-through). */
 export function createGraphEngineLogxer(options) {
     const inner = logxer.createLogxer({
-        packageName: EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME,
+        packageName: X12I_GRAPH_RUNTIME_PACKAGE_NAME,
         envPrefix: GRAPH_ENGINE_LOGXER_ENV_PREFIX,
         debugNamespace: 'graph-engine',
     }, buildGraphEngineLogxerConfig(options?.logging));

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/runtimeObjects.d.ts

@@ -4,9 +4,9 @@
  */
 import type { GetJobLogsInput, GetJobLogsResult, QueryableLogLine } from '@x12i/logxer';
 /** Published npm name of this package (root layer in composed observability). */
-export declare const EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME: "@exellix/graph-engine";
+export declare const X12I_GRAPH_RUNTIME_PACKAGE_NAME: "@exellix/graph-engine";
 /** Task layer package name in {@link RuntimeObjects.packagesRuntimeObjects}. */
-export declare const EXELLIX_AI_TASKS_PACKAGE_NAME: "@exellix/ai-tasks";
+export declare const X12I_AI_TASKS_PACKAGE_NAME: "@exellix/ai-tasks";
 export type ActivixQueryableClient = {
     getJobActivities(input: {
         jobId: string;
@@ -43,15 +43,15 @@ export type BuildExellixGraphRuntimeObjectsInput = {
     graphLogxerClient?: LogxerQueryableClient;
     /**
      * Partial subtree from `@exellix/ai-tasks` when that package exports `runtimeObjects`.
-     * Nested `packagesRuntimeObjects` are appended after the ai-tasks row without overwriting entries.
+     * Nested `packagesRuntimeObjects` are appended after the x12i-tasks row without overwriting entries.
      */
     aiTasksRuntimeObjects?: Pick<RuntimeObjects, 'activixClient' | 'logxerClient'> & {
         packagesRuntimeObjects?: PackageRuntimeObjects[];
     };
 };
 /**
- * Builds the composed {@link RuntimeObjects} for exellix-graph: graph-level clients at the root,
- * then an `@exellix/ai-tasks` package row plus any nested package rows from ai-tasks (flattened as siblings).
+ * Builds the composed {@link RuntimeObjects} for x12i-graph: graph-level clients at the root,
+ * then an `@exellix/ai-tasks` package row plus any nested package rows from x12i-tasks (flattened as siblings).
  */
 export declare function buildExellixGraphRuntimeObjects(input: BuildExellixGraphRuntimeObjectsInput): RuntimeObjects;
 /**

package/dist/src/runtime/runtimeObjects.js

@@ -1,17 +1,17 @@
 /** Published npm name of this package (root layer in composed observability). */
-export const EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME = '@exellix/graph-engine';
+export const X12I_GRAPH_RUNTIME_PACKAGE_NAME = '@exellix/graph-engine';
 /** Task layer package name in {@link RuntimeObjects.packagesRuntimeObjects}. */
-export const EXELLIX_AI_TASKS_PACKAGE_NAME = '@exellix/ai-tasks';
+export const X12I_AI_TASKS_PACKAGE_NAME = '@exellix/ai-tasks';
 /**
- * Builds the composed {@link RuntimeObjects} for exellix-graph: graph-level clients at the root,
- * then an `@exellix/ai-tasks` package row plus any nested package rows from ai-tasks (flattened as siblings).
+ * Builds the composed {@link RuntimeObjects} for x12i-graph: graph-level clients at the root,
+ * then an `@exellix/ai-tasks` package row plus any nested package rows from x12i-tasks (flattened as siblings).
  */
 export function buildExellixGraphRuntimeObjects(input) {
     const ai = input.aiTasksRuntimeObjects;
     const tail = [...(ai?.packagesRuntimeObjects ?? [])];
     const packagesRuntimeObjects = [
         {
-            name: EXELLIX_AI_TASKS_PACKAGE_NAME,
+            name: X12I_AI_TASKS_PACKAGE_NAME,
             activixClient: ai?.activixClient,
             logxerClient: ai?.logxerClient,
         },

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/aiTaskProfile.d.ts

@@ -1,5 +1,5 @@
 /**
- * Optional task metadata aligned with `@x12i/graph-composer` authoring / `reportTaskNodeProtocolGaps`.
+ * Optional task metadata aligned with `@exellix/graph-composer` authoring / `reportTaskNodeProtocolGaps`.
  * Web scope is authored via {@link AiTaskProfileMetadata.webQueryTemplate} (Graphenix 2.7.3+ PRE `webScope` unit).
  */
 export type AiTaskProfileInputSynthesis = {
@@ -18,7 +18,7 @@ export type AiTaskProfileInputSynthesis = {
 };
 /**
  * PRE/POST strategies, optional web query template, optional input synthesis for AI task nodes.
- * `@x12i/graph-composer` requires `preStrategyKey` / `postStrategyKey` for validated AI nodes.
+ * `@exellix/graph-composer` requires `preStrategyKey` / `postStrategyKey` for validated AI nodes.
  *
  * **Web scope (Graphenix 2.7.3+):** Non-empty `webQueryTemplate` (or `webQueryTemplates[]`) compiles to a PRE
  * `webScope` unit; graph-engine does not merge web intent into `taskConfiguration.narrix`.

package/dist/src/types/aiTaskProfile.js

@@ -1,5 +1,5 @@
 /**
- * Optional task metadata aligned with `@x12i/graph-composer` authoring / `reportTaskNodeProtocolGaps`.
+ * Optional task metadata aligned with `@exellix/graph-composer` authoring / `reportTaskNodeProtocolGaps`.
  * Web scope is authored via {@link AiTaskProfileMetadata.webQueryTemplate} (Graphenix 2.7.3+ PRE `webScope` unit).
  */
 export function hasWebScopeAuthoring(profile) {

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;