@exellix/graph-engine 7.4.2 → 7.5.0

package/README.md

@@ -383,12 +383,25 @@ Implemented deterministic finalizer types:
 
 Build an object by mapping named inputs (from `executionMemoryPath` or literals) into output keys.
 
-#### `aggregate` — `strategy: "report-schema"` (multi-section report from execution memory)
+#### `aggregate` — `strategy: "report-schema"` (output object assembled from run memory)
 
-Builds a single object whose keys come from **`config.sections`**: each section specifies a **dot-path** into `executionMemory` (`path`), optional **`title`**, and **`optional`** (when `true`, missing values become `null` instead of throwing).
+Builds the finalizer output object: **`config.sections`** maps each **output field key** to a memory read, using the same `{ type, path }` idiom as finalizer `inputs` and `response.shape` selectors:
 
-- **`collect_tags`**: when `true`, walks all section values and collects unique epistemic strings among `CONFIRMED`, `INFERRED`, `ASSUMED`, `UNKNOWN` into **`collected_tags`** (array).
-- **`meta`**: optional literal key/value pairs merged at the top level of the parsed output.
+```jsonc
+"config": {
+  "strategy": "report-schema",
+  "sections": {
+    "q1": { "type": "executionMemoryPath", "path": "answers.q1", "optional": true },
+    "summary": { "type": "outputsMemoryPath", "path": "report.summary" }
+  },
+  "collectEpistemicTags": true
+}
+```
+
+- Each section: **`type`** (`executionMemoryPath` | `outputsMemoryPath`), **`path`**, and **`optional`** (when `true`, missing values become `null` instead of throwing).
+- **`collectEpistemicTags`**: when `true`, walks all section values and collects unique epistemic strings among `CONFIRMED`, `INFERRED`, `ASSUMED`, `UNKNOWN` into the **`collectedTags`** output field (array).
+
+> **Breaking (model v8):** `sections[].path: string` → `sections[].{ type, path }`; `collect_tags` → `collectEpistemicTags`; output `collected_tags` → `collectedTags`. Section `title` and the literal-merge `meta` block were **removed** — authoring titles and studio hints belong in the studio document, and literal output fields belong in `graph.response.shape`. The validator rejects the old keys with a migration message.
 
 Bundled graphs under [`graphs/`](graphs/) (see [graphs/README.md](graphs/README.md)) use this strategy for multi-section reports, sometimes after **`scoped-answer-assembler`** and **`scoped-answer-writer`** persistence (typical store: **`x-scoped-data`** in deployments that use that collection). The graph file shape is defined in [.docs/exellix-graph-engine-format.md](.docs/exellix-graph-engine-format.md).
 

package/dist/src/index.d.ts

@@ -80,6 +80,8 @@ export { buildExellixGraphRuntimeObjects, setRuntimeObjectsLastJobId, summarizeR
 export type { ActivixQueryableClient, LogxerQueryableClient, LogxerLogLine, PackageRuntimeObjects, RuntimeObjects, BuildExellixGraphRuntimeObjectsInput, RuntimeObjectsObservabilitySummary, } from './runtime/runtimeObjects.js';
 export type { GetJobLogsInput, GetJobLogsResult, QueryableLogLine } from '@x12i/logxer';
 export { assertCanonicalGraphDocument, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, } from './runtime/validateCanonicalGraphDocument.js';
+export { GRAPH_ENTRY_STUDIO_ONLY_KEYS, GRAPH_METADATA_STUDIO_ONLY_KEYS, stripGraphModelStudioFields, primaryRuntimeInputFromStudioDocument, getGraphEntryStudioOnlyKeyViolations, getGraphMetadataStudioOnlyKeyViolations, getGraphEntryEmptyInputPathViolations, } from './runtime/graphModelStudioSeparation.js';
+export type { GraphStudioDocument } from './runtime/graphModelStudioSeparation.js';
 export { computeGraphDocumentContentSha256, stableStringifyGraphDocument, } from './runtime/graphDocumentFingerprint.js';
 export { migrateLegacyGraphResponse, migrateLegacyGraphResponseDefinition, } from './runtime/graphResponseMigration.js';
 export type { MigrateGraphResponseResult } from './runtime/graphResponseMigration.js';
@@ -106,7 +108,7 @@ export type { GraphCatalogValidationIssue } from './integrations/cataloxGraphCat
 export { composeEventEmitters } from './runtime/events.js';
 export { createPlaygroundReporter } from './playground/index.js';
 export type { CreatePlaygroundReporterOptions, PlaygroundDebugArtifact, PlaygroundDebugArtifactKind, PlaygroundDebugSnapshot, PlaygroundReporter, PlaygroundStep, } from './playground/PlaygroundReporter.js';
-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, } from './inspection/index.js';
-export type { 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 { 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, WebScopeQuestion, LocalTaskHandler, LocalTaskContext } from './types/narrix.js';
 export type { ScopedDataReaderConfig, ScopedDataReaderOutput, ScopedDataReaderPackOutput, ScopedAnswerAssemblerConfig, ScopedAnswerAssemblerOutput, ScopedAnswerWriterConfig, ScopedAnswerWriterOutput, } from './runtime/localSkills/index.js';

package/dist/src/index.js

@@ -59,6 +59,7 @@ export { buildTaskNodeRunTaskRequest, validateTaskNodeRunTaskConfig, validateTas
 export { validateRunTaskConfig, validateRunTaskInvoke, analyzeExpectedRunTaskInput, checkExpectedInputAgainstRequest, collectSmartInputValidationIssues, buildRunTaskValidationContext, analyzeRunTaskRequest, validateParsedOutput, analyzeSkillRequest, buildSkillRequestAnalysisPacket, formatSkillRequestAnalysisMarkdown, 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 { assertCanonicalGraphDocument, getCanonicalGraphDocumentViolations, CANONICAL_GRAPH_TOP_LEVEL_KEYS, } from './runtime/validateCanonicalGraphDocument.js';
+export { GRAPH_ENTRY_STUDIO_ONLY_KEYS, GRAPH_METADATA_STUDIO_ONLY_KEYS, stripGraphModelStudioFields, primaryRuntimeInputFromStudioDocument, getGraphEntryStudioOnlyKeyViolations, getGraphMetadataStudioOnlyKeyViolations, getGraphEntryEmptyInputPathViolations, } from './runtime/graphModelStudioSeparation.js';
 export { computeGraphDocumentContentSha256, stableStringifyGraphDocument, } from './runtime/graphDocumentFingerprint.js';
 export { migrateLegacyGraphResponse, migrateLegacyGraphResponseDefinition, } from './runtime/graphResponseMigration.js';
 export { applyAiTaskProfileWebScopingToNarrix, mapAiTaskProfileQuestionsToWebScopeQuestions, } from './runtime/applyAiTaskProfileWebScopingToNarrix.js';
@@ -81,5 +82,5 @@ export { composeEventEmitters } from './runtime/events.js';
 // Playground (full-visibility MD report)
 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, } from './inspection/index.js';
+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';
 // Web context rendering — consume execution.webContext → markdown for prompts (Layer 04)

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

@@ -0,0 +1,33 @@
+import type { Graph, GraphAiModelConfig } from '../types/refs.js';
+/** Where the effective model-profile triplet for a node came from. */
+export type ModelSelectionSource = 'node' | 'graph' | 'default' | 'none';
+export type NodeModelSelection = {
+    nodeId: string;
+    kind: 'task' | 'finalizer';
+    /** False for deterministic finalizers (aggregate / select / bundle); those call no model. */
+    usesModel: boolean;
+    /** Effective default-case profile aliases for this node (undefined when `usesModel` is false). */
+    profiles?: GraphAiModelConfig;
+    source: ModelSelectionSource;
+    /** Count of conditional (`when`-gated) cases that may override the default at runtime. */
+    conditionalCaseCount: number;
+};
+export type GraphModelSelectionInspection = {
+    /** Graph-level default profile aliases (undefined when the graph declares none). */
+    graphDefaultProfiles?: GraphAiModelConfig;
+    nodes: NodeModelSelection[];
+    /** Distinct profile alias names referenced anywhere in the model (for `runtime.aliasConfig` wiring). */
+    aliasesUsed: string[];
+};
+/**
+ * Static, runtime-free view of which model-profile aliases each node would use.
+ *
+ * Answers "where are the models (aliases) that will be used?" without executing:
+ * - task nodes resolve `node.taskConfiguration.modelConfig` (override) → graph `modelConfig` → engine default;
+ * - `synthesize` finalizers use the graph default; other finalizers call no model.
+ *
+ * Only the unconditional (`when`-less) default case is reported per tier; `conditionalCaseCount`
+ * flags nodes whose effective model may change at runtime via gated cases. Alias → concrete
+ * provider id still happens at runtime through `runtime.aliasConfig`.
+ */
+export declare function inspectGraphModelSelection(graph: Graph): GraphModelSelectionInspection;

package/dist/src/inspection/graphModelSelection.js

@@ -0,0 +1,108 @@
+import { isEmptyConditionWhen, isModelConfigSelection } from '../runtime/modelConfigSelection.js';
+import { DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG } from '../runtime/graphAiModelConfig.js';
+function asArrayNodes(graph) {
+    return Array.isArray(graph.nodes) ? graph.nodes : Object.values(graph.nodes ?? {});
+}
+/** Returns the no-`when` default case profiles from a selection, if present and valid. */
+function defaultCaseProfiles(selection) {
+    if (!isModelConfigSelection(selection))
+        return undefined;
+    const sel = selection;
+    for (const c of sel.cases ?? []) {
+        if (isEmptyConditionWhen(c.when))
+            return c.modelConfig;
+    }
+    return undefined;
+}
+function conditionalCaseCount(selection) {
+    if (!isModelConfigSelection(selection))
+        return 0;
+    const sel = selection;
+    return (sel.cases ?? []).filter((c) => !isEmptyConditionWhen(c.when)).length;
+}
+/** True for finalizer types that invoke a model (`synthesize`); deterministic kinds do not. */
+function finalizerUsesModel(node) {
+    return node.finalizerType === 'synthesize';
+}
+/**
+ * Static, runtime-free view of which model-profile aliases each node would use.
+ *
+ * Answers "where are the models (aliases) that will be used?" without executing:
+ * - task nodes resolve `node.taskConfiguration.modelConfig` (override) → graph `modelConfig` → engine default;
+ * - `synthesize` finalizers use the graph default; other finalizers call no model.
+ *
+ * Only the unconditional (`when`-less) default case is reported per tier; `conditionalCaseCount`
+ * flags nodes whose effective model may change at runtime via gated cases. Alias → concrete
+ * provider id still happens at runtime through `runtime.aliasConfig`.
+ */
+export function inspectGraphModelSelection(graph) {
+    const graphDefaultProfiles = defaultCaseProfiles(graph.modelConfig);
+    const nodes = [];
+    const aliases = new Set();
+    const addAliases = (cfg) => {
+        if (cfg == null)
+            return;
+        aliases.add(cfg.preActionModel);
+        aliases.add(cfg.skillModel);
+        aliases.add(cfg.postActionModel);
+    };
+    for (const raw of asArrayNodes(graph)) {
+        const node = raw;
+        const isFinalizer = node.type === 'finalizer';
+        if (isFinalizer) {
+            const fin = raw;
+            if (!finalizerUsesModel(fin)) {
+                nodes.push({
+                    nodeId: String(fin.id),
+                    kind: 'finalizer',
+                    usesModel: false,
+                    source: 'none',
+                    conditionalCaseCount: 0,
+                });
+                continue;
+            }
+            const profiles = graphDefaultProfiles ?? DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG;
+            addAliases(profiles);
+            nodes.push({
+                nodeId: String(fin.id),
+                kind: 'finalizer',
+                usesModel: true,
+                profiles,
+                source: graphDefaultProfiles ? 'graph' : 'default',
+                conditionalCaseCount: 0,
+            });
+            continue;
+        }
+        const taskNode = raw;
+        const nodeSelection = taskNode.taskConfiguration?.modelConfig;
+        const nodeDefault = defaultCaseProfiles(nodeSelection);
+        let profiles;
+        let source;
+        if (nodeDefault) {
+            profiles = nodeDefault;
+            source = 'node';
+        }
+        else if (graphDefaultProfiles) {
+            profiles = graphDefaultProfiles;
+            source = 'graph';
+        }
+        else {
+            profiles = DEFAULT_GRAPH_AI_MODEL_PROFILE_CONFIG;
+            source = 'default';
+        }
+        addAliases(profiles);
+        nodes.push({
+            nodeId: String(taskNode.id),
+            kind: 'task',
+            usesModel: true,
+            profiles,
+            source,
+            conditionalCaseCount: conditionalCaseCount(nodeSelection) + conditionalCaseCount(graph.modelConfig),
+        });
+    }
+    return {
+        graphDefaultProfiles,
+        nodes,
+        aliasesUsed: [...aliases].sort(),
+    };
+}

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

@@ -15,6 +15,8 @@ export type { CatalogPlanningValidationIssue } from './validateCatalogPlanning.j
 export { collectPredicatePaths, executionMemoryPathTail, executionMemoryTailsMatch, getNodeExecutionMemoryWriteTails, getNodeControlDependencies, } from './controlInspection.js';
 export { getNodeSideEffects, inspectFinalizer, inspectNodeContract, inspectGraphContracts, } from './contractInspection.js';
 export type { InspectNodeContractOptions } from './contractInspection.js';
+export { inspectGraphModelSelection } from './graphModelSelection.js';
+export type { GraphModelSelectionInspection, NodeModelSelection, ModelSelectionSource, } from './graphModelSelection.js';
 export type { NodeScopingQuestion, NodeScopeSource, NodeScopeTarget, NodeScopingData, NodeMemoryShape, MemoryPath, NodeNarrixDiscovery, NodeInspection, GraphInspection, NodeIOEdge, GraphCatalogs, CatalogBindingSummary, GraphVirtualIO, GraphVirtualIONode, GraphVirtualIOEdge, GraphVirtualIONodeRole, VirtualGraphEntryLayer, VirtualGraphResponseLayer, MaterializeVirtualBoundaryDiagramOptions, MaterializedVirtualBoundaryDiagram, MaterializedVirtualBoundaryDiagramMeta, } from './types.js';
 export { EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID, EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID, EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY, EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY, } from './types.js';
 export type { GraphDocumentMetadata } from '../types/refs.js';

package/dist/src/inspection/index.js

@@ -14,4 +14,5 @@ export { getGraphNodes, getGraphCatalogs, inspectGraph, getVirtualGraphEntryLaye
 export { validateCatalogPlanning, isCatalogBinding, isCatalogRequestEntry, } from './validateCatalogPlanning.js';
 export { collectPredicatePaths, executionMemoryPathTail, executionMemoryTailsMatch, getNodeExecutionMemoryWriteTails, getNodeControlDependencies, } from './controlInspection.js';
 export { getNodeSideEffects, inspectFinalizer, inspectNodeContract, inspectGraphContracts, } from './contractInspection.js';
+export { inspectGraphModelSelection } from './graphModelSelection.js';
 export { EXELLIX_VIRTUAL_GRAPH_ENTRY_NODE_ID, EXELLIX_VIRTUAL_GRAPH_RESPONSE_NODE_ID, EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY, EXELLIX_VIRTUAL_BOUNDARY_EDGE_FLAG_KEY, } from './types.js';

package/dist/src/inspection/nodeInspection.js

@@ -52,7 +52,7 @@ function finalizerRuntimeReadSources(node, graph) {
         for (const [key, spec] of Object.entries(cfg.sections)) {
             if (!isPlainObject(spec))
                 continue;
-            pushDedupedRead(reads, spec.path, `config.sections.${key}`, 'executionMemory');
+            pushDedupedRead(reads, spec.path, `config.sections.${key}`, spec.type === 'outputsMemoryPath' ? 'outputsMemory' : 'executionMemory');
         }
         return reads;
     }

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

@@ -91,6 +91,8 @@ export interface GraphRuntimeObject extends HostExecuteGraphRunOptions {
     taskVariables?: Record<string, unknown>;
     /** Runtime default model selection (`cases`); overrides GraphModelObject.modelConfig. */
     modelConfig?: ModelConfigSelection;
+    /** Profile aliases for xynthesis when runtime.modelConfig is host-resolved concrete ids. */
+    aiProfiles?: GraphAiModelConfig;
     /**
      * @deprecated Unused since 7.1 — profile aliases pass through to downstream resolution.
      */
@@ -210,6 +212,8 @@ export declare function createExellixGraphRuntime(opts: ExellixGraphRuntimeOptio
         prevNodeId?: string;
         /** Overrides graph-level / runtime default for this node only. */
         modelConfig?: GraphAiModelConfig;
+        /** Profile aliases for xynthesis PRE/POST when modelConfig is host-resolved concrete ids. */
+        aiProfiles?: GraphAiModelConfig;
         llmCall?: Record<string, unknown>;
         runTaskIdentity?: Record<string, unknown>;
         runTaskExecutionMode?: "default" | "trace";

package/dist/src/runtime/ExellixGraphRuntime.js

@@ -397,7 +397,7 @@ export function createExellixGraphRuntime(opts) {
                             },
                             ...(input.modelConfig != null
                                 ? {
-                                    modelConfig: toRunTaskModelConfigForPhase(input.modelConfig, 'pre'),
+                                    modelConfig: toRunTaskModelConfigForPhase(input.modelConfig, 'pre', input.aiProfiles),
                                 }
                                 : {}),
                             ...(effectiveLlmCall != null ? { llmCall: effectiveLlmCall } : {}),
@@ -610,7 +610,7 @@ export function createExellixGraphRuntime(opts) {
         }
         const effectiveModelConfig = input.modelConfig;
         const mainRunTaskModelConfig = effectiveModelConfig != null
-            ? toRunTaskModelConfigForPhase(effectiveModelConfig, 'main')
+            ? toRunTaskModelConfigForPhase(effectiveModelConfig, 'main', input.aiProfiles)
             : undefined;
         // DEBUG: Verify execution object before sending
         traceExecutionMemory('executeNode', 'Node execution object before runTask', {
@@ -722,6 +722,7 @@ export function createExellixGraphRuntime(opts) {
                 jobContext,
                 prevNodeId: input.prevNodeId,
                 modelConfig: effectiveModelConfig,
+                aiProfiles: input.aiProfiles,
                 llmCall: effectiveLlmCall,
                 runTaskIdentity: runTaskIdentityBase,
                 nodeTaskConfiguration: input.node?.taskConfiguration,
@@ -1023,6 +1024,7 @@ export function createExellixGraphRuntime(opts) {
                 jobContext,
                 prevNodeId: input.prevNodeId,
                 modelConfig: effectiveModelConfig,
+                aiProfiles: input.aiProfiles,
                 llmCall: effectiveLlmCall,
                 runTaskIdentity: runTaskIdentityBase,
                 nodeTaskConfiguration: input.node?.taskConfiguration,
@@ -1616,6 +1618,7 @@ export function createExellixGraphRuntime(opts) {
                                 variables: runtime.variables,
                                 taskVariables: runtime.taskVariables,
                                 modelConfig: effectiveModelConfig,
+                                aiProfiles: merged.aiProfiles,
                                 llmCall: merged.llmCall,
                                 runTaskIdentity: merged.runTaskIdentity,
                                 runTaskExecutionMode: merged.runTaskExecutionMode,

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

@@ -27,6 +27,8 @@ export type RunEngineAiTasksStrategyPhaseArgs = {
     prevNodeId?: string;
     /** Resolved three-phase config; routed to the correct ai-tasks slot for this strategy phase. */
     modelConfig?: GraphAiModelConfig;
+    /** Profile aliases for xynthesis slots when modelConfig is host-resolved concrete ids. */
+    aiProfiles?: GraphAiModelConfig;
     llmCall?: RunTaskRequest['llmCall'];
     runTaskIdentity?: Record<string, unknown>;
     /** Task node `taskConfiguration` (identity envelope merge). */

package/dist/src/runtime/aiTasksStrategyPhases.js

@@ -55,7 +55,7 @@ export async function runEngineAiTasksStrategyPhase(args) {
         executionPipeline: [{ phase: 'main', type: 'direct' }],
         executionStrategies: [],
         modelConfig: args.modelConfig != null
-            ? toRunTaskModelConfigForPhase(args.modelConfig, args.phase)
+            ? toRunTaskModelConfigForPhase(args.modelConfig, args.phase, args.aiProfiles)
             : undefined,
         llmCall: args.llmCall ?? undefined,
         identity,

package/dist/src/runtime/finalizers/executeFinalizer.js

@@ -284,11 +284,12 @@ function collectEpistemicTags(value, found) {
     }
 }
 function executeReportSchema(args) {
-    const { cfg, executionMemory } = args;
+    const { cfg, executionMemory, outputsMemory } = args;
     const finalizerNodeId = String(args.finalizer.id);
     const out = {};
     for (const [key, spec] of Object.entries(cfg.sections ?? {})) {
-        let v = getByDotPath(executionMemory, spec.path);
+        const root = spec.type === 'outputsMemoryPath' ? outputsMemory : executionMemory;
+        let v = getByDotPath(root, spec.path);
         if (isNodeFailureMarker(v)) {
             if (spec.optional === true) {
                 out[key] = null;
@@ -296,7 +297,7 @@ function executeReportSchema(args) {
             }
             throw createFinalizerError({
                 code: 'GRAPH_FINALIZER_NODE_FAILED',
-                message: `report-schema: section "${key}" points at a failed graph node (path="${spec.path}")`,
+                message: `report-schema: section "${key}" points at a failed graph node (${spec.type}="${spec.path}")`,
                 finalizerNodeId,
                 path: `config.sections.${key}`,
                 details: { spec, marker: v },
@@ -305,7 +306,7 @@ function executeReportSchema(args) {
         if ((v === undefined || v === null) && spec.optional !== true) {
             throw createFinalizerError({
                 code: 'GRAPH_FINALIZER_INPUT_MISSING',
-                message: `report-schema: required section "${key}" not found at path "${spec.path}"`,
+                message: `report-schema: required section "${key}" not found at ${spec.type} "${spec.path}"`,
                 finalizerNodeId,
                 path: `config.sections.${key}`,
                 details: { spec },
@@ -313,16 +314,11 @@ function executeReportSchema(args) {
         }
         out[key] = v ?? null;
     }
-    if (cfg.collect_tags) {
+    if (cfg.collectEpistemicTags) {
         const tags = new Set();
         for (const v of Object.values(out))
             collectEpistemicTags(v, tags);
-        out.collected_tags = Array.from(tags);
-    }
-    if (cfg.meta) {
-        for (const [k, v] of Object.entries(cfg.meta)) {
-            out[k] = v;
-        }
+        out.collectedTags = Array.from(tags);
     }
     return out;
 }

package/dist/src/runtime/finalizers/validateFinalizer.js

@@ -55,7 +55,8 @@ export function collectRequiredFinalizerExecutionMemoryReads(finalizer, graph) {
         for (const [key, spec] of Object.entries(cfg.sections)) {
             if (!isPlainObject(spec))
                 continue;
-            pushRequiredRead(reads, 'execution', spec.path, `config.sections.${key}`, spec.optional);
+            const memory = spec.type === 'outputsMemoryPath' ? 'outputs' : 'execution';
+            pushRequiredRead(reads, memory, spec.path, `config.sections.${key}`, spec.optional);
         }
         return reads;
     }
@@ -180,6 +181,46 @@ export function assertFinalizerRequiredReadsResolvable(args) {
         }
     }
 }
+/** Validates a `{ type: executionMemoryPath | outputsMemoryPath, path, optional? }` memory read. */
+function validateMemoryRef(ref, path, finalizerNodeId, label) {
+    if (!isPlainObject(ref)) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `${label} at ${path} must be an object { type, path }`,
+            finalizerNodeId,
+            path,
+            details: { ref },
+        });
+    }
+    const type = ref.type;
+    if (type !== 'executionMemoryPath' && type !== 'outputsMemoryPath') {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `${label} at ${path} must declare type "executionMemoryPath" or "outputsMemoryPath" (got ${String(type)})`,
+            finalizerNodeId,
+            path: `${path}.type`,
+            details: { ref },
+        });
+    }
+    const p = ref.path;
+    if (typeof p !== 'string' || p.length === 0) {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `${label} at ${path} requires a non-empty path`,
+            finalizerNodeId,
+            path: `${path}.path`,
+        });
+    }
+    const optional = ref.optional;
+    if (optional !== undefined && typeof optional !== 'boolean') {
+        throw createFinalizerError({
+            code: 'GRAPH_FINALIZER_INVALID',
+            message: `${label} at ${path} optional must be boolean when provided`,
+            finalizerNodeId,
+            path: `${path}.optional`,
+        });
+    }
+}
 function validateBinding(name, b, finalizerNodeId) {
     if (!isPlainObject(b)) {
         throw createFinalizerError({
@@ -245,54 +286,57 @@ function validateAggregateConfig(cfg, finalizerNodeId) {
         return;
     }
     if (strategy === 'report-schema') {
-        const sections = cfg.sections;
-        if (sections !== undefined && !isPlainObject(sections)) {
+        const REPORT_SCHEMA_ALLOWED_KEYS = new Set(['strategy', 'sections', 'collectEpistemicTags']);
+        const REPORT_SCHEMA_REMOVED_KEYS = {
+            collect_tags: 'collectEpistemicTags (boolean)',
+            meta: 'removed — put literal output fields in graph.response.shape, and authoring titles in the studio document',
+            title: 'removed from sections — authoring titles belong in the studio document',
+            schemaVersion: 'removed — not part of the executable model',
+            skeletonFromConcept: 'removed — studio authoring hint, not part of the executable model',
+        };
+        for (const key of Object.keys(cfg)) {
+            if (REPORT_SCHEMA_ALLOWED_KEYS.has(key))
+                continue;
+            const migration = REPORT_SCHEMA_REMOVED_KEYS[key];
             throw createFinalizerError({
                 code: 'GRAPH_FINALIZER_INVALID',
-                message: `report-schema aggregate finalizer config.sections must be an object when provided`,
+                message: migration
+                    ? `report-schema finalizer config.${key} is no longer supported. Use: ${migration}.`
+                    : `report-schema finalizer has unknown config key "${key}". Allowed: ${[...REPORT_SCHEMA_ALLOWED_KEYS].join(', ')}.`,
                 finalizerNodeId,
-                path: 'config.sections',
+                path: `config.${key}`,
                 details: { config: cfg },
             });
         }
-        if (isPlainObject(sections)) {
-            for (const [k, spec] of Object.entries(sections)) {
-                if (!isPlainObject(spec) || typeof spec.path !== 'string' || spec.path.length === 0) {
-                    throw createFinalizerError({
-                        code: 'GRAPH_FINALIZER_INVALID',
-                        message: `report-schema section "${k}" must have a non-empty path`,
-                        finalizerNodeId,
-                        path: `config.sections.${k}.path`,
-                        details: { spec },
-                    });
-                }
-                const optional = spec.optional;
-                if (optional !== undefined && typeof optional !== 'boolean') {
-                    throw createFinalizerError({
-                        code: 'GRAPH_FINALIZER_INVALID',
-                        message: `report-schema section "${k}" optional must be boolean when provided`,
-                        finalizerNodeId,
-                        path: `config.sections.${k}.optional`,
-                    });
-                }
-            }
-        }
-        const collectTags = cfg.collect_tags;
-        if (collectTags !== undefined && typeof collectTags !== 'boolean') {
+        const sections = cfg.sections;
+        if (!isPlainObject(sections) || Object.keys(sections).length === 0) {
             throw createFinalizerError({
                 code: 'GRAPH_FINALIZER_INVALID',
-                message: `report-schema aggregate finalizer config.collect_tags must be boolean when provided`,
+                message: `report-schema aggregate finalizer requires a non-empty config.sections object (output key → { type, path }).`,
                 finalizerNodeId,
-                path: 'config.collect_tags',
+                path: 'config.sections',
+                details: { config: cfg },
             });
         }
-        const meta = cfg.meta;
-        if (meta !== undefined && !isPlainObject(meta)) {
+        for (const [k, spec] of Object.entries(sections)) {
+            validateMemoryRef(spec, `config.sections.${k}`, finalizerNodeId, 'report-schema section');
+            const title = spec.title;
+            if (title !== undefined) {
+                throw createFinalizerError({
+                    code: 'GRAPH_FINALIZER_INVALID',
+                    message: `report-schema section "${k}" no longer accepts "title"; move authoring titles to the studio document.`,
+                    finalizerNodeId,
+                    path: `config.sections.${k}.title`,
+                });
+            }
+        }
+        const collectTags = cfg.collectEpistemicTags;
+        if (collectTags !== undefined && typeof collectTags !== 'boolean') {
             throw createFinalizerError({
                 code: 'GRAPH_FINALIZER_INVALID',
-                message: `report-schema aggregate finalizer config.meta must be an object when provided`,
+                message: `report-schema aggregate finalizer config.collectEpistemicTags must be boolean when provided`,
                 finalizerNodeId,
-                path: 'config.meta',
+                path: 'config.collectEpistemicTags',
             });
         }
         return;

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

@@ -36,5 +36,9 @@ export type EngineModelPhase = 'pre' | 'main' | 'post';
 /**
  * Maps three-phase graph config to ai-tasks slot pair for a single runTask phase.
  * Values are forwarded as-is (profile aliases or concrete ids).
+ *
+ * When {@link aiProfiles} is set (studio/playground host pattern), xynthesis slots use profile
+ * aliases so PRE synthesis inside ai-tasks resolves via ai-profiles even when {@link config}
+ * carries host-resolved concrete provider ids on `runtime.modelConfig`.
  */
-export declare function toRunTaskModelConfigForPhase(config: GraphAiModelConfig, phase: EngineModelPhase): RunTaskModelConfigWire;
+export declare function toRunTaskModelConfigForPhase(config: GraphAiModelConfig, phase: EngineModelPhase, aiProfiles?: GraphAiModelConfig): RunTaskModelConfigWire;

package/dist/src/runtime/graphAiModelConfig.js

@@ -79,26 +79,37 @@ export async function resolveGraphAiModelConfig(modelConfig, context) {
         postActionModel: normalizeModelSlot(modelConfig.postActionModel, context),
     };
 }
+function xynthesisSlotForWire(config, phase, aiProfiles) {
+    if (aiProfiles != null) {
+        return phase === 'post' ? aiProfiles.postActionModel : aiProfiles.preActionModel;
+    }
+    return phase === 'post' ? config.postActionModel : config.preActionModel;
+}
 /**
  * Maps three-phase graph config to ai-tasks slot pair for a single runTask phase.
  * Values are forwarded as-is (profile aliases or concrete ids).
+ *
+ * When {@link aiProfiles} is set (studio/playground host pattern), xynthesis slots use profile
+ * aliases so PRE synthesis inside ai-tasks resolves via ai-profiles even when {@link config}
+ * carries host-resolved concrete provider ids on `runtime.modelConfig`.
  */
-export function toRunTaskModelConfigForPhase(config, phase) {
+export function toRunTaskModelConfigForPhase(config, phase, aiProfiles) {
+    const xynthesisModel = xynthesisSlotForWire(config, phase, aiProfiles);
     switch (phase) {
         case 'pre':
             return {
-                xynthesisModel: config.preActionModel,
-                skillModel: config.preActionModel,
+                xynthesisModel,
+                skillModel: xynthesisModel,
             };
         case 'main':
             return {
-                xynthesisModel: config.preActionModel,
+                xynthesisModel,
                 skillModel: config.skillModel,
             };
         case 'post':
             return {
-                xynthesisModel: config.postActionModel,
-                skillModel: config.postActionModel,
+                xynthesisModel,
+                skillModel: xynthesisModel,
             };
     }
 }

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

@@ -0,0 +1,43 @@
+import type { Graph } from '../types/refs.js';
+/** Example payloads and playground request samples — studio DB only, not graph model. */
+export declare const GRAPH_ENTRY_STUDIO_ONLY_KEYS: readonly ["exampleInput", "exampleInputs", "requestExample"];
+/** Planning / UI metadata — studio DB only, not versioned executable graph model. */
+export declare const GRAPH_METADATA_STUDIO_ONLY_KEYS: readonly ["requestId", "graphConcept", "graphsStudio"];
+export type GraphEntryStudioOnlyKey = (typeof GRAPH_ENTRY_STUDIO_ONLY_KEYS)[number];
+export type GraphMetadataStudioOnlyKey = (typeof GRAPH_METADATA_STUDIO_ONLY_KEYS)[number];
+/**
+ * Studio-side companion document keyed by graph id (graphs-studio database).
+ * Not part of {@link GraphModelObject} / canonical graph JSON.
+ */
+export type GraphStudioDocument = {
+    graphId: string;
+    graphConcept?: Record<string, unknown>;
+    graphsStudio?: Record<string, unknown>;
+    /** Flat {@link GraphRuntimeObject.input} examples for playground and tests. */
+    exampleInputs?: Array<{
+        title?: string;
+        runtimeInput: Record<string, unknown>;
+    }>;
+    [key: string]: unknown;
+};
+export declare function getGraphEntryStudioOnlyKeyViolations(graphEntry: unknown): GraphEntryStudioOnlyKey[];
+export declare function getGraphMetadataStudioOnlyKeyViolations(metadata: unknown): GraphMetadataStudioOnlyKey[];
+/** Returns dot-paths under graphEntry.inputs with empty `path` for value kinds. */
+export declare function getGraphEntryEmptyInputPathViolations(graphEntry: unknown): string[];
+/**
+ * Deep-clones a graph model and removes studio-only metadata and graphEntry example fields.
+ * Use at publish time when upstream serializers still attach playground artifacts.
+ */
+export declare function stripGraphModelStudioFields(graph: Graph): Graph;
+export declare function assertCanonicalGraphEntryContract(graphEntry: unknown, context: {
+    jobId?: string;
+    graphId?: string;
+    graphLabel?: string;
+}): void;
+export declare function assertCanonicalGraphDocumentMetadata(metadata: unknown, context: {
+    jobId?: string;
+    graphId?: string;
+    graphLabel?: string;
+}): void;
+/** Primary flat runtime input from a studio companion document. */
+export declare function primaryRuntimeInputFromStudioDocument(studio: GraphStudioDocument | undefined): Record<string, unknown> | undefined;

package/dist/src/runtime/graphModelStudioSeparation.js

@@ -0,0 +1,102 @@
+import { ExellixGraphError } from '../errors/ExellixGraphError.js';
+import { ExellixGraphErrorCode } from '../errors/exellixGraphErrorCodes.js';
+/** Example payloads and playground request samples — studio DB only, not graph model. */
+export const GRAPH_ENTRY_STUDIO_ONLY_KEYS = [
+    'exampleInput',
+    'exampleInputs',
+    'requestExample',
+];
+/** Planning / UI metadata — studio DB only, not versioned executable graph model. */
+export const GRAPH_METADATA_STUDIO_ONLY_KEYS = [
+    'requestId',
+    'graphConcept',
+    'graphsStudio',
+];
+function isPlainObject(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function isValueInputSpec(spec) {
+    return spec.kind !== 'execution';
+}
+export function getGraphEntryStudioOnlyKeyViolations(graphEntry) {
+    if (!isPlainObject(graphEntry))
+        return [];
+    return GRAPH_ENTRY_STUDIO_ONLY_KEYS.filter((key) => Object.prototype.hasOwnProperty.call(graphEntry, key));
+}
+export function getGraphMetadataStudioOnlyKeyViolations(metadata) {
+    if (!isPlainObject(metadata))
+        return [];
+    return GRAPH_METADATA_STUDIO_ONLY_KEYS.filter((key) => Object.prototype.hasOwnProperty.call(metadata, key));
+}
+/** Returns dot-paths under graphEntry.inputs with empty `path` for value kinds. */
+export function getGraphEntryEmptyInputPathViolations(graphEntry) {
+    if (!isPlainObject(graphEntry))
+        return [];
+    const inputs = graphEntry.inputs;
+    if (!Array.isArray(inputs))
+        return [];
+    const bad = [];
+    for (let i = 0; i < inputs.length; i++) {
+        const spec = inputs[i];
+        if (!isPlainObject(spec))
+            continue;
+        if (spec.kind === 'execution')
+            continue;
+        const path = typeof spec.path === 'string' ? spec.path.trim() : '';
+        if (!path)
+            bad.push(`metadata.graphEntry.inputs[${i}].path`);
+    }
+    return bad;
+}
+/**
+ * Deep-clones a graph model and removes studio-only metadata and graphEntry example fields.
+ * Use at publish time when upstream serializers still attach playground artifacts.
+ */
+export function stripGraphModelStudioFields(graph) {
+    const clone = structuredClone(graph);
+    if (isPlainObject(clone.metadata)) {
+        const meta = { ...clone.metadata };
+        for (const key of GRAPH_METADATA_STUDIO_ONLY_KEYS) {
+            delete meta[key];
+        }
+        if (isPlainObject(meta.graphEntry)) {
+            const ge = { ...meta.graphEntry };
+            for (const key of GRAPH_ENTRY_STUDIO_ONLY_KEYS) {
+                delete ge[key];
+            }
+            meta.graphEntry = ge;
+        }
+        clone.metadata = meta;
+    }
+    return clone;
+}
+export function assertCanonicalGraphEntryContract(graphEntry, context) {
+    const label = context.graphLabel ?? `Graph "${String(context.graphId ?? '?')}"`;
+    const studioKeys = getGraphEntryStudioOnlyKeyViolations(graphEntry);
+    if (studioKeys.length > 0) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${label}: metadata.graphEntry must not include studio-only example field(s): ${studioKeys.join(', ')}. Store example payloads in the graphs-studio database (GraphStudioDocument.exampleInputs), not in the executable graph model.`, { ...context, graphEntryStudioOnlyKeys: studioKeys });
+    }
+    const emptyPaths = getGraphEntryEmptyInputPathViolations(graphEntry);
+    if (emptyPaths.length > 0) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${label}: metadata.graphEntry.inputs must declare a non-empty dot-path under merged execution (e.g. "input" or "input.subnetId"); empty path at ${emptyPaths.join(', ')}.`, { ...context, graphEntryEmptyInputPaths: emptyPaths });
+    }
+}
+export function assertCanonicalGraphDocumentMetadata(metadata, context) {
+    const label = context.graphLabel ?? `Graph "${String(context.graphId ?? '?')}"`;
+    const studioKeys = getGraphMetadataStudioOnlyKeyViolations(metadata);
+    if (studioKeys.length > 0) {
+        throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `${label}: metadata must not include studio-only field(s): ${studioKeys.join(', ')}. Move planning and UI metadata to the graphs-studio database (GraphStudioDocument), not the executable graph model.`, { ...context, metadataStudioOnlyKeys: studioKeys });
+    }
+    if (isPlainObject(metadata) && metadata.graphEntry != null) {
+        assertCanonicalGraphEntryContract(metadata.graphEntry, context);
+    }
+}
+/** Primary flat runtime input from a studio companion document. */
+export function primaryRuntimeInputFromStudioDocument(studio) {
+    const first = studio?.exampleInputs?.[0];
+    const runtimeInput = first?.runtimeInput;
+    if (runtimeInput != null && isPlainObject(runtimeInput) && !Array.isArray(runtimeInput)) {
+        return runtimeInput;
+    }
+    return undefined;
+}

package/dist/src/runtime/mergeExellixGraphRuntimeInvocation.js

@@ -16,6 +16,7 @@ export function mergeExellixGraphRuntimeInvocation(input, opts) {
         playgroundMeta: input.playgroundMeta ?? opts.playgroundMeta,
         clearSynthesizedContextPerNode: input.clearSynthesizedContextPerNode ?? opts.clearSynthesizedContextPerNode,
         modelConfig: input.modelConfig ?? opts.modelConfig,
+        aiProfiles: input.aiProfiles ?? opts.aiProfiles,
         aliasConfig: input.aliasConfig ?? opts.aliasConfig,
         nodes: input.nodes ?? opts.nodes,
         llmCall: input.llmCall ?? opts.llmCall,

package/dist/src/runtime/validateCanonicalGraphDocument.js

@@ -5,6 +5,7 @@ import { EXELLIX_VIRTUAL_BOUNDARY_NODE_METADATA_KEY } from '../inspection/types.
 import { getStructuredDataFilterPathViolations } from './dataFiltersEvaluation.js';
 import { conditionWhenSignature, countDefaultModelConfigCases, isEmptyConditionWhen, isGraphAiModelConfig, isModelConfigSelection, } from './modelConfigSelection.js';
 import { assertGraphAiProfileNameString } from './graphAiModelConfig.js';
+import { assertCanonicalGraphDocumentMetadata } from './graphModelStudioSeparation.js';
 /** Top-level keys permitted on a canonical exellix-graph executable graph JSON document. */
 export const CANONICAL_GRAPH_TOP_LEVEL_KEYS = [
     'id',
@@ -548,6 +549,10 @@ export function assertCanonicalGraphDocument(graph, context) {
                 throw new ExellixGraphError(ExellixGraphErrorCode.NON_CANONICAL_GRAPH_DOCUMENT, `Graph "${String(resolvedGraphId ?? '?')}": metadata.${key} is not part of the static metadata block. Move this field to \`${target}\`.`, { jobId: context?.jobId, graphId: resolvedGraphId, metadataKey: key });
             }
         }
+        assertCanonicalGraphDocumentMetadata(metadata, {
+            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/options.d.ts

@@ -1,7 +1,7 @@
 import type { Activix } from '@x12i/activix';
 import type { StackLoggingOptions } from '@x12i/logxer';
 import type { LlmCallConfig, RunTaskRequest as AiTasksRunTaskRequest, RunTaskResponse as AiTasksRunTaskResponse } from '@exellix/ai-tasks';
-import type { GraphModelAliasConfig, ModelConfigSelection, TaskNodeRuntimeObject } from './refs.js';
+import type { GraphAiModelConfig, GraphModelAliasConfig, ModelConfigSelection, TaskNodeRuntimeObject } from './refs.js';
 import type { RuntimeObjects } from '../runtime/runtimeObjects.js';
 /**
  * NOTE: `@exellix/ai-tasks` 5.5+ removed the exported `RunTaskDiagnostics` type.
@@ -63,6 +63,11 @@ export interface HostExecuteGraphRunOptions {
     playgroundMeta?: Record<string, unknown>;
     clearSynthesizedContextPerNode?: boolean;
     modelConfig?: ModelConfigSelection;
+    /**
+     * Profile aliases for xynthesis PRE/POST when {@link modelConfig} carries host-resolved concrete ids.
+     * MAIN `skillModel` still comes from resolved `modelConfig`; xynthesis slots prefer these aliases.
+     */
+    aiProfiles?: GraphAiModelConfig;
     aliasConfig?: GraphModelAliasConfig;
     nodes?: Record<string, TaskNodeRuntimeObject>;
     llmCall?: LlmCallConfig;

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

@@ -207,14 +207,28 @@ export type QuestionDrivenItemSpec = {
      */
     optional?: boolean;
 };
-export type ReportSchemaSectionSpec = {
-    /** Dot-path in executionMemory to pull the section value from. */
+/**
+ * A single "read one value from run memory" reference. Same idiom as
+ * {@link FinalizerInputBinding} (minus `literal`) and {@link GraphResponseSelector}
+ * memory selectors — finalizer configs reuse it so every memory read in the model
+ * looks identical: `{ type, path }`.
+ */
+export type FinalizerMemoryRef = {
+    type: 'executionMemoryPath';
+    path: string;
+    optional?: boolean;
+} | {
+    type: 'outputsMemoryPath';
     path: string;
-    /** Human-readable title for this section. */
-    title?: string;
     optional?: boolean;
 };
+/**
+ * @deprecated Renamed and unified with {@link FinalizerMemoryRef}. Sections are now
+ * `Record<outputKey, FinalizerMemoryRef>` instead of `{ path, title }`.
+ */
+export type ReportSchemaSectionSpec = FinalizerMemoryRef;
 export type AggregateFinalizerConfig = {
+    /** Build the output object field-by-field from named finalizer `inputs`. */
     strategy: 'object-map';
     map: Record<string, AggregateExpr>;
     omitUndefined?: boolean;
@@ -228,25 +242,23 @@ export type AggregateFinalizerConfig = {
     contractVersion?: string;
     /** Map output keys → node specs. */
     items: Record<string, QuestionDrivenItemSpec>;
-    /** Optional extra metadata to include at top-level from executionMemory or outputsMemory. */
-    meta?: Record<string, {
-        type: 'executionMemoryPath' | 'outputsMemoryPath';
-        path: string;
-        optional?: boolean;
-    }>;
+    /** Optional extra top-level fields, each read from run memory. */
+    meta?: Record<string, FinalizerMemoryRef>;
 } | {
     /**
-     * Assemble a structured multi-section report from executionMemory.
-     * Each section key maps to a dot-path.  collect_tags gathers all
-     * epistemic tags across sections.
+     * Build the graph output object by reading one run-memory value per output key.
+     * This **is** the finalizer's output: `sections` maps each output field to the
+     * memory path it is read from. (Authoring titles belong in the studio document,
+     * not here.)
      */
     strategy: 'report-schema';
-    /** Map of output key → section spec (path + optional title). */
-    sections: Record<string, ReportSchemaSectionSpec>;
-    /** When true, scan all section values for CONFIRMED/INFERRED/ASSUMED/UNKNOWN and emit collected_tags. */
-    collect_tags?: boolean;
-    /** Optional literal fields merged at top level. */
-    meta?: Record<string, unknown>;
+    /** Output field key → where its value is read from in run memory. */
+    sections: Record<string, FinalizerMemoryRef>;
+    /**
+     * When true, scan all section values for CONFIRMED/INFERRED/ASSUMED/UNKNOWN
+     * and emit them under the `collectedTags` output field.
+     */
+    collectEpistemicTags?: boolean;
 };
 export type BundleFinalizerConfig = {
     strategy: 'bundle';
@@ -275,8 +287,8 @@ export interface FinalizerNode {
     type: 'finalizer';
     finalizerType: 'aggregate' | 'compose' | 'select' | 'bundle' | 'synthesize';
     inputs: Record<string, FinalizerInputBinding>;
-    /** Transitional: runtime validation narrows by finalizerType; implemented finalizers export typed configs. */
-    config: AggregateFinalizerConfig | BundleFinalizerConfig | SelectFinalizerConfig | SynthesizeFinalizerConfig | Record<string, unknown>;
+    /** Strict per-`finalizerType` config. The runtime validator rejects unknown keys and legacy field names. */
+    config: AggregateFinalizerConfig | BundleFinalizerConfig | SelectFinalizerConfig | SynthesizeFinalizerConfig;
     /** Writes selected finalizer result fields into graph-owned outputsMemory for final response assembly. */
     outputMapping?: TaskNodeResultMapping;
     outputSchema?: OutputSchema;
@@ -612,7 +624,6 @@ export type GraphEntryContract = {
      * Optional JSON Schema (e.g. draft 2020-12) for the merged `execution` object. Validators may use it; core runtime does not.
      */
     executionSchema?: Record<string, unknown>;
-    [key: string]: unknown;
 };
 /**
  * @deprecated Use root-level {@link GraphModelObject.response}. The final response shape is executable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-engine",
-  "version": "7.4.2",
+  "version": "7.5.0",
   "type": "module",
   "description": "Graph executor SDK",
   "main": "dist/src/index.js",
@@ -28,6 +28,8 @@
     "test": "npm run build && npm run check:no-legacy && tsx --test --test-force-exit tests/model-alias-contract.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 tests/graph-engine.test.ts tests/passthrough-parity.test.ts tests/task-node-run-task-preflight.test.ts tests/reports-fixtures-pre-synthesis.test.ts tests/model-alias-contract.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",
     "run:pre-synthesis": "npm run build && node --env-file=.env scripts/run-pre-synthesis-graph.mjs",
     "check:no-legacy": "node scripts/check-no-legacy.mjs",
     "lint": "eslint src testkit --ext .ts",