@exellix/graph-engine 8.6.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/README.md

@@ -55,7 +55,7 @@ npm install @exellix/graph-engine
 
 **Upstream tasks SDK:** This package depends on **`@exellix/ai-tasks` ^8.6.8** and **`@x12i/funcx` 4.4.4** (see **`package.json`**). Graph-engine emits **`RunTaskRequest`** shapes that match the ai-tasks **8.x** closed schema (mandatory **`executionStrategies`**, three-slot **`modelConfig`**, **`xynthesized`**, optional **`smartInput`**, no legacy root mirrors). Pin compatible versions in your app lockfile. Optional CI improvement: fail or warn when the resolved ai-tasks major/minor drifts outside an allowlist (not enforced in-repo today).
 
-### Execution matrix hosts (`@exellix/exellix-runtime`) — documentation only for the engine
+### Execution matrix hosts (`@x12i/exellix-runtime`) — documentation only for the engine
 
 Matrix **claim**, **rows**, and **retry policy** live outside this package. If your host wires **matrix → graph run**, see [.docs/execution-matrix-handoff.md](.docs/execution-matrix-handoff.md) for how **you** should inject `runtime.executeGraph`, compile **`GraphModelObject` → plan**, resolve **`metadata.graphEntry` per model**, seed **`runtime.executionMemory`**, and pass **`runtime.jobId`**. Helpers such as **`buildMatrixJobForGraphRun`** align **`id`** and **`job.jobId`** on the `job` object so you can call **`runtime.executeGraph({ plan, runtime: { jobId: job.jobId, job, … } })`**. Those exports are **optional helpers for callers**; they do **not** expand graph-engine’s role beyond **executing the single run** when invoked.
 
@@ -329,7 +329,7 @@ When **`taskConfiguration.aiTaskProfile.inputSynthesis`** is enabled, graph-engi
 
 1. **Engine PRE/POST strategy utilities (ai-tasks only):** `taskConfiguration.aiTaskProfile.preStrategyKey` / `postStrategyKey` → extra **`runTask`** calls via **`@exellix/ai-tasks`** before/after MAIN; outputs stored at **`execution.xynthesis.pre`** / **`execution.xynthesis.post`** (historical slot names).
 2. **`executionPipeline` inside ai-tasks:** e.g. PRE **`synthesized-context`** + MAIN direct — still **one** outbound MAIN `runTask` handled inside `@exellix/ai-tasks`.
-3. **Narrix web scope inside ai-tasks:** when **`taskConfiguration.aiTaskProfile.webScoping.enabled`** is true, graph-engine forwards a `narrix` payload with `enableWebScope` / `webScopeQuestions`. The actual web fetch + skip rules run **inside `@exellix/ai-tasks`** (`@exellix/narrix-web-scoper`); graph-engine has **no local web phase** in 5.x.
+3. **Narrix web scope inside ai-tasks:** when **`taskConfiguration.aiTaskProfile.webScoping.enabled`** is true, graph-engine forwards a `narrix` payload with `enableWebScope` / `webScopeQuestions`. The actual web fetch + skip rules run **inside `@exellix/ai-tasks`** (`@x12i/narrix-web-scoper`); graph-engine has **no local web phase** in 5.x.
 
 `synthesize` finalizers are a fourth outbound task-call shape: the finalizer is still a graph model node, but its terminal utility `runTask` uses the same run identity, diagnostics, `llmCall`, and resolved model config as the rest of the graph run.
 

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

@@ -0,0 +1,37 @@
+export type GraphRunPersistencyLink = {
+    /** Relation descriptor key (result entity → source entity). */
+    relationKey?: string;
+    /** Dot-path on the new record where the source recordId/entityId FK is written. */
+    fkPath?: string;
+    type?: 'oneToOne' | 'oneToMany' | 'manyToOne' | 'manyToMany';
+    /** Content type the relation targets on the source (default: source job contentType). */
+    targetContentType?: string;
+};
+export type GraphRunPersistency = {
+    /** Target object type; default `same-as-input`. */
+    entityId: string | 'same-as-input';
+    /** Result collection content type; default {@link DEFAULT_GRAPH_RUN_PERSISTENCY_CONTENT_TYPE}. */
+    contentType: string;
+    /** When true (default), always insert a new result record with a new recordId. */
+    newRecord?: boolean;
+    /** Cross-object link intent; auto-derived when {@link entityId} differs from the job source. */
+    link?: GraphRunPersistencyLink;
+};
+export type GraphRunContract = {
+    graphId: string;
+    persistency: GraphRunPersistency | null;
+    graphVersion?: string;
+};
+/** Parse a work/job/graph persistency object (partial fields allowed). */
+export declare function parseGraphRunPersistency(raw: unknown): GraphRunPersistency | null;
+/** Work/job overrides win over graph defaults; partial overrides merge field-by-field. */
+export declare function mergeGraphRunPersistency(base: GraphRunPersistency | null, override: GraphRunPersistency | null): GraphRunPersistency | null;
+/** Apply a run/work/job persistency override onto a resolved graph contract. */
+export declare function applyGraphRunContractOverride(contract: GraphRunContract, persistencyOverride: unknown): GraphRunContract;
+/** Read graph document version from published graph JSON (`version` or `metadata.version`). */
+export declare function readGraphDocumentVersion(graphDoc: unknown): string | undefined;
+/** Resolve graph-run contract from published graph JSON (GRX-NOTE-001). */
+export declare function resolveGraphRunContract(graphId: string, graphDoc: unknown): GraphRunContract;
+export declare function loadGraphRunContracts(graphIds: string[], graphLoader: {
+    loadGraph(graphId: string): Promise<unknown>;
+}): Promise<GraphRunContract[]>;

package/dist/src/contract/graphRunContract.js

@@ -0,0 +1,127 @@
+import { DEFAULT_GRAPH_RUN_PERSISTENCY_CONTENT_TYPE } from './persistencyDefaults.js';
+const RELATION_TYPES = new Set(['oneToOne', 'oneToMany', 'manyToOne', 'manyToMany']);
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+function readLink(raw) {
+    const link = asRecord(raw);
+    if (!link)
+        return undefined;
+    const out = {};
+    if (typeof link.relationKey === 'string' && link.relationKey.length > 0) {
+        out.relationKey = link.relationKey;
+    }
+    if (typeof link.fkPath === 'string' && link.fkPath.length > 0) {
+        out.fkPath = link.fkPath;
+    }
+    if (typeof link.type === 'string' && RELATION_TYPES.has(link.type)) {
+        out.type = link.type;
+    }
+    if (typeof link.targetContentType === 'string' && link.targetContentType.length > 0) {
+        out.targetContentType = link.targetContentType;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function normalizePersistency(raw) {
+    const entityIdRaw = raw.entityId;
+    const entityId = entityIdRaw === 'same-as-input'
+        ? 'same-as-input'
+        : typeof entityIdRaw === 'string' && entityIdRaw.length > 0
+            ? entityIdRaw
+            : 'same-as-input';
+    const contentTypeRaw = raw.contentType;
+    const contentType = typeof contentTypeRaw === 'string' && contentTypeRaw.length > 0
+        ? contentTypeRaw
+        : DEFAULT_GRAPH_RUN_PERSISTENCY_CONTENT_TYPE;
+    const newRecord = raw.newRecord === false ? false : true;
+    const link = readLink(raw.link);
+    return {
+        entityId,
+        contentType,
+        newRecord,
+        ...(link ? { link } : {}),
+    };
+}
+/** Parse a work/job/graph persistency object (partial fields allowed). */
+export function parseGraphRunPersistency(raw) {
+    const rec = asRecord(raw);
+    if (!rec)
+        return null;
+    return normalizePersistency(rec);
+}
+/** Work/job overrides win over graph defaults; partial overrides merge field-by-field. */
+export function mergeGraphRunPersistency(base, override) {
+    if (!override)
+        return base;
+    if (!base)
+        return override;
+    return {
+        entityId: override.entityId,
+        contentType: override.contentType,
+        newRecord: override.newRecord !== undefined ? override.newRecord : base.newRecord,
+        link: override.link ? { ...base.link, ...override.link } : base.link,
+    };
+}
+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;
+    const merged = {
+        ...(base
+            ? {
+                entityId: base.entityId,
+                contentType: base.contentType,
+                ...(base.newRecord === false ? { newRecord: false } : {}),
+                ...(base.link ? { link: { ...base.link } } : {}),
+            }
+            : {}),
+        ...overrideRec,
+    };
+    const overrideLink = asRecord(overrideRec.link);
+    if (base?.link && overrideLink) {
+        merged.link = { ...base.link, ...overrideLink };
+    }
+    return normalizePersistency(merged);
+}
+/** Apply a run/work/job persistency override onto a resolved graph contract. */
+export function applyGraphRunContractOverride(contract, persistencyOverride) {
+    return {
+        ...contract,
+        persistency: mergeRawPersistency(contract.persistency, persistencyOverride),
+    };
+}
+function readPersistency(graph) {
+    const response = asRecord(graph.response);
+    const fromResponse = asRecord(response?.persistency);
+    if (fromResponse) {
+        return normalizePersistency(fromResponse);
+    }
+    return null;
+}
+/** Read graph document version from published graph JSON (`version` or `metadata.version`). */
+export function readGraphDocumentVersion(graphDoc) {
+    const graph = asRecord(graphDoc) ?? {};
+    const metadata = asRecord(graph.metadata);
+    if (typeof graph.version === 'string')
+        return graph.version;
+    if (typeof metadata?.version === 'string')
+        return metadata.version;
+    return undefined;
+}
+/** Resolve graph-run contract from published graph JSON (GRX-NOTE-001). */
+export function resolveGraphRunContract(graphId, graphDoc) {
+    const graph = asRecord(graphDoc) ?? {};
+    return {
+        graphId,
+        persistency: readPersistency(graph),
+        graphVersion: readGraphDocumentVersion(graph),
+    };
+}
+export async function loadGraphRunContracts(graphIds, graphLoader) {
+    return Promise.all(graphIds.map(async (graphId) => resolveGraphRunContract(graphId, await graphLoader.loadGraph(graphId))));
+}

package/dist/src/contract/persistencyDefaults.d.ts

@@ -0,0 +1,2 @@
+/** Default result content type for graph-run persistency. */
+export declare const DEFAULT_GRAPH_RUN_PERSISTENCY_CONTENT_TYPE = "inferences";

package/dist/src/contract/persistencyDefaults.js

@@ -0,0 +1,2 @@
+/** Default result content type for graph-run persistency. */
+export const DEFAULT_GRAPH_RUN_PERSISTENCY_CONTENT_TYPE = 'inferences';

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';
@@ -79,7 +79,7 @@ export type { BuildTaskNodeRunTaskRequestArgs, BuildTaskNodeRunTaskRequestResult
 /** Re-exported from `@exellix/ai-tasks` — preflight validation without `runTask`. */
 export { validateRunTaskConfig, validateRunTaskInvoke, analyzeExpectedRunTaskInput, checkExpectedInputAgainstRequest, collectSmartInputValidationIssues, buildRunTaskValidationContext, validateParsedOutput, listTokens, analyzeTemplateResolution, renderSmartInput, extractTokenNamesFromStrings, getSkillTokens, getSkillContent, } from '@exellix/ai-tasks';
 export type { RunTaskValidationIssue, RunTaskValidationResult, RunTaskInvokeValidationResult, ExpectedRunTaskInputPath, AnalyzeExpectedRunTaskInputResult, ValidateRunTaskInvokeParams, RunTaskTemplateResolver, OutputValidationResult, } from '@exellix/ai-tasks';
-export { buildExellixGraphRuntimeObjects, setRuntimeObjectsLastJobId, summarizeRuntimeObjectsForPlayground, EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME, EXELLIX_AI_TASKS_PACKAGE_NAME, } from './runtime/runtimeObjects.js';
+export { buildExellixGraphRuntimeObjects, setRuntimeObjectsLastJobId, summarizeRuntimeObjectsForPlayground, X12I_GRAPH_RUNTIME_PACKAGE_NAME, X12I_AI_TASKS_PACKAGE_NAME, } from './runtime/runtimeObjects.js';
 export type { ActivixQueryableClient, LogxerQueryableClient, LogxerLogLine, PackageRuntimeObjects, RuntimeObjects, BuildExellixGraphRuntimeObjectsInput, RuntimeObjectsObservabilitySummary, } from './runtime/runtimeObjects.js';
 export type { GetJobLogsInput, GetJobLogsResult, QueryableLogLine } from '@x12i/logxer';
 export { assertCanonicalGraphDocument, assertCanonicalTaskNode, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, } from './runtime/validateCanonicalGraphDocument.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';
@@ -120,5 +127,7 @@ export type { CreatePlaygroundReporterOptions, PlaygroundDebugArtifact, Playgrou
 export { getNodeScopingQuestion, getNodeMemoryShape, getNodeNarrixDiscovery, fetchNodeScopingData, inspectNode, resolveNodeSkillKey, getGraphNodes, getGraphCatalogs, inspectGraph, collectPredicatePaths, executionMemoryPathTail, executionMemoryTailsMatch, getNodeExecutionMemoryWriteTails, getNodeControlDependencies, getNodeSideEffects, inspectFinalizer, inspectNodeContract, inspectGraphContracts, EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID, EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID, EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY, EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY, getVirtualGraphEntryLayer, getVirtualGraphResponseLayer, materializeVirtualBoundaryDiagram, stripMaterializedVirtualBoundaryDiagram, validateCatalogPlanning, isCatalogBinding, isCatalogRequestEntry, inspectGraphModelSelection, } from './inspection/index.js';
 export type { GraphModelSelectionInspection, NodeModelSelection, ModelSelectionSource, NodeScopingQuestion, NodeScopeSource, NodeScopeTarget, NodeScopingData, NodeMemoryShape, MemoryPath, NodeNarrixDiscovery, NodeInspection, GraphInspection, NodeIOEdge, GraphCatalogs, CatalogBindingSummary, CatalogPlanningValidationIssue, GraphVirtualIO, GraphVirtualIONode, GraphVirtualIOEdge, GraphVirtualIONodeRole, VirtualGraphEntryLayer, VirtualGraphResponseLayer, MaterializeVirtualBoundaryDiagramOptions, MaterializedVirtualBoundaryDiagram, MaterializedVirtualBoundaryDiagramMeta, InspectNodeContractOptions, LocalSkillKey, NodeExecutionType, FactProvenance, ProvenancedSection, NodeInputBindingEntry, ScopedDataDependency, NodeInputContract, ExecutionMemoryWriteSpec, NodeOutputContract, NodeSideEffects, ControlBranchEntry, NodeControlContract, NodeValidationContract, FinalizerContractInspection, NodeContractInspection, GraphContractsInspection, } from './inspection/index.js';
 export type { NarrixPreProcessorConfig, NarrixModeKey, NarrixRunInput, NarrixScope, ResolvedNarrixWirePayload, LocalTaskHandler, LocalTaskContext, } from './types/narrix.js';
+export { resolveGraphRunContract, loadGraphRunContracts, readGraphDocumentVersion, parseGraphRunPersistency, mergeGraphRunPersistency, applyGraphRunContractOverride, type GraphRunContract, type GraphRunPersistency, type GraphRunPersistencyLink, } from './contract/graphRunContract.js';
+export { DEFAULT_GRAPH_RUN_PERSISTENCY_CONTENT_TYPE } from './contract/persistencyDefaults.js';
 export { shutdownMemorixRuntime } from './runtime/localSkills/memorixRuntime.js';
 export type { ScopedDataReaderConfig, ScopedDataReaderOutput, ScopedDataReaderPackOutput, ScopedAnswerAssemblerConfig, ScopedAnswerAssemblerOutput, ScopedAnswerWriterConfig, ScopedAnswerWriterOutput, } from './runtime/localSkills/index.js';

package/dist/src/index.js

@@ -60,7 +60,7 @@ export { runTaskResponseSucceeded } from './runtime/runTaskResponse.js';
 export { buildTaskNodeRunTaskRequest, validateTaskNodeRunTaskConfig, validateTaskNodeRunTaskInvoke, } from './runtime/taskNodeRunTaskPreflight.js';
 /** Re-exported from `@exellix/ai-tasks` — preflight validation without `runTask`. */
 export { validateRunTaskConfig, validateRunTaskInvoke, analyzeExpectedRunTaskInput, checkExpectedInputAgainstRequest, collectSmartInputValidationIssues, buildRunTaskValidationContext, validateParsedOutput, listTokens, analyzeTemplateResolution, renderSmartInput, extractTokenNamesFromStrings, getSkillTokens, getSkillContent, } from '@exellix/ai-tasks';
-export { buildExellixGraphRuntimeObjects, setRuntimeObjectsLastJobId, summarizeRuntimeObjectsForPlayground, EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME, EXELLIX_AI_TASKS_PACKAGE_NAME, } from './runtime/runtimeObjects.js';
+export { buildExellixGraphRuntimeObjects, setRuntimeObjectsLastJobId, summarizeRuntimeObjectsForPlayground, X12I_GRAPH_RUNTIME_PACKAGE_NAME, X12I_AI_TASKS_PACKAGE_NAME, } from './runtime/runtimeObjects.js';
 export { assertCanonicalGraphDocument, assertCanonicalTaskNode, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, } from './runtime/validateCanonicalGraphDocument.js';
 export { assertCanonicalGraphRuntimeObject } from './runtime/validateCanonicalGraphRuntime.js';
 export { GRAPH_ENTRY_STUDIO_ONLY_KEYS, GRAPH_METADATA_STUDIO_ONLY_KEYS, stripGraphModelStudioFields, primaryRuntimeInputFromStudioDocument, getGraphEntryStudioOnlyKeyViolations, getGraphMetadataStudioOnlyKeyViolations, } from './runtime/graphModelStudioSeparation.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';
@@ -88,5 +92,8 @@ export { composeEventEmitters } from './runtime/events.js';
 export { createPlaygroundReporter } from './playground/index.js';
 // Graph Inspection API
 export { getNodeScopingQuestion, getNodeMemoryShape, getNodeNarrixDiscovery, fetchNodeScopingData, inspectNode, resolveNodeSkillKey, getGraphNodes, getGraphCatalogs, inspectGraph, collectPredicatePaths, executionMemoryPathTail, executionMemoryTailsMatch, getNodeExecutionMemoryWriteTails, getNodeControlDependencies, getNodeSideEffects, inspectFinalizer, inspectNodeContract, inspectGraphContracts, EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID, EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID, EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY, EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY, getVirtualGraphEntryLayer, getVirtualGraphResponseLayer, materializeVirtualBoundaryDiagram, stripMaterializedVirtualBoundaryDiagram, validateCatalogPlanning, isCatalogBinding, isCatalogRequestEntry, inspectGraphModelSelection, } from './inspection/index.js';
+// Graph-run contract (GRX-NOTE-001) — persistency intent from published graph JSON
+export { resolveGraphRunContract, loadGraphRunContracts, readGraphDocumentVersion, parseGraphRunPersistency, mergeGraphRunPersistency, applyGraphRunContractOverride, } from './contract/graphRunContract.js';
+export { DEFAULT_GRAPH_RUN_PERSISTENCY_CONTENT_TYPE } from './contract/persistencyDefaults.js';
 export { shutdownMemorixRuntime } from './runtime/localSkills/memorixRuntime.js';
 // Web context rendering — consume execution.webContext → markdown for prompts (Layer 04)

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/integrations/activixExellixShared.js

@@ -1,4 +1,4 @@
-import { EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME } from '../runtime/runtimeObjects.js';
+import { X12I_GRAPH_RUNTIME_PACKAGE_NAME } from '../runtime/runtimeObjects.js';
 /** Recommended Mongo indexes for exellix-graph Activix streams (see `@x12i/activix` README). */
 export const ACTIVIX_EXELLIX_RUN_CONTEXT_INDEXES = [
     { keys: { 'runContext.jobId': 1 } },
@@ -55,5 +55,5 @@ export function buildNodeActivixRunContext(args) {
     };
 }
 export function activixExellixCollectionRegistryOwner() {
-    return { package: EXELLIX_GRAPH_RUNTIME_PACKAGE_NAME };
+    return { package: X12I_GRAPH_RUNTIME_PACKAGE_NAME };
 }

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"),