@exellix/graph-engine 7.8.2 → 8.0.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 8.0.1
+
+### Changed
+
+- **Zero local compile workarounds:** removed local migration/finalizer patches; `compileExellixExecutablePlan` uses `@x12i/graphenix-authoring-format` ≥1.0.2 and `@x12i/graphenix-plan-compiler` ≥1.0.1 only.
+- Re-export `migrateLegacyGraphModelObjectToGraphenixExecutable` from authoring-format (upstream name; no exellix alias).
+- **Docs / layout:** compile helper lives under `src/compile/`; execute path no longer runs response migration (compile-only).
+
+## 8.0.0
+
+### Breaking
+
+- **`executeGraph({ plan, runtime })` only** — removed `ExecuteGraphInput.model`. Hosts compile with `compileExellixExecutablePlan` or `@x12i/graphenix-plan-compiler` before invoke.
+- **`ExecuteGraphResult.graphAudit` → `planAudit`** (`{ planHash, source }`).
+- Execute-time model case selection and `assertCanonicalGraphDocument` removed from the run path; frozen `plan.nodePlans` / `plan.finalizerPlans` drive model config and invoke contracts.
+
+### Added
+
+- **`@x12i/graphenix-*` integration:** plan validation, deferred gates, trace events (`ExecuteGraphResult.trace`), and exports for `ExecutableGraphPlanV2`.
+- **`compileExellixExecutablePlan`**, **`migrateLegacyGraphModelObjectToGraphenixExecutable`** (re-export from `@x12i/graphenix-authoring-format`) — host compile helpers for legacy exellix `GraphModelObject`.
+- **`buildAuthoringStudioGraphExecutionRequest`** re-export from `@x12i/graphenix-execute-envelope`.
+
+See [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) §8.0.0.
+
+## 7.8.3
+
+### Breaking
+
+- **Studio graph execute envelope:** `graphDefaultModel` removed with **no legacy reader**. Request-level model defaults duplicated `graph.modelConfig` and were never applied by graph-engine. Hosts (graphs-studio) must persist defaults on **`graph.modelConfig` only** and stop sending `graphDefaultModel`.
+- **Validation:** `assertCanonicalStudioGraphExecuteRequest` and `buildGraphExecutionRequestFromStudioExecute` reject the removed key (`NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST`).
+
+### Added
+
+- **Documentation:** [`formats-documentations/graph-format-boundaries.md`](formats-documentations/graph-format-boundaries.md) — four-layer model (graph / runtime / studio envelope / studio DB), field mapping from playground payloads, and explicit list of what is not on `GraphModelObject`.
+
 ## 7.8.2
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@ A minimal, focused SDK for executing graphs in the exellix ecosystem.
 
 ## What this package does and does not
 
-**In scope — what this package does:** On each **`createExellixGraphRuntime(...).executeGraph({ model, runtime })`** invocation, it runs **exactly one graph run** (validate model → plan → nodes → finalizer) until that run **completes or fails**, then returns the result. There is **no** batching, queueing, or multi-job orchestration inside this package — each call is one logical run. You supply the static **`model: GraphModelObject`**, planner (`GraphEngineFactory`), tasks client, and dynamic **`runtime: GraphRuntimeObject`** with the mandatory host `jobId`, `job` envelope, active `input`, memory, variables, and per-run options. The engine generates a fresh **`taskId`** (UUID) per invocation and sends it on **every** `runTask` request together with **`jobId`**. That is the **entire** product role of graph-engine.
+**In scope — what this package does:** On each **`createExellixGraphRuntime(...).executeGraph({ plan, runtime })`** invocation, it runs **exactly one graph run** (validate plan → schedule waves → nodes → finalizer) until that run **completes or fails**, then returns the result. There is **no** batching, queueing, or multi-job orchestration inside this package — each call is one logical run. You supply a compiled v2 **`plan: ExecutableGraphPlanV2`** (from `@x12i/graphenix-plan-compiler` or {@link compileExellixExecutablePlan}), planner (`GraphEngineFactory`), tasks client, and dynamic **`runtime: GraphRuntimeObject`** with the mandatory host `jobId`, `job` envelope, active `input`, memory, variables, and per-run options. The engine generates a fresh **`taskId`** (UUID) per invocation and sends it on **every** `runTask` request together with **`jobId`**. That is the **entire** product role of graph-engine.
 
 **Out of scope — what this package does not do:** It does **not** schedule work, own **execution matrices**, manage **claims** or **rows**, persist **job** lifecycle, implement **retry/requeue policy**, or **track** runs across tenants or sessions. Optional helpers and docs for matrix *hosts* only help **build arguments** for the same single-run API; they do **not** move orchestration into this package. Integrations (e.g. Activix graph-run events) emit data **for that call** when you wire an `eventEmitter` — they do not make graph-engine a workflow or matrix service.
 
@@ -12,8 +12,8 @@ A minimal, focused SDK for executing graphs in the exellix ecosystem.
 
 `exellix-graph-engine` does exactly this loop:
 
-1. **Validate graph model:** The caller supplies **`model: GraphModelObject`** directly in the execution request. The effective correlation **`graphId`** on the result and in telemetry is **`model.id`**.
-2. `plan = graphenix.plan(...)`
+1. **Validate executable plan:** The caller supplies **`plan: ExecutableGraphPlanV2`** (compiled upstream). The effective correlation **`graphId`** on the result and in telemetry is **`plan.source.graphId`**.
+2. `executeGraph({ plan, runtime })`
 3. For each runnable node:
    - Map node → `skillKey` (strict rules)
    - If `skillKey` is a **local skill** (`scoped-data-reader`, `deterministic-rule`, `scoped-answer-writer`, `scoped-answer-assembler`), run it in-process (no `ai-tasks` call); otherwise call `ai-tasks.runTask(...)`
@@ -43,7 +43,7 @@ The **`runTask`** wire contract (identity, canonical **`input`**, optional extra
 
 An executable graph model object may have **only** these **top-level** keys: `id`, `version`, `modelConfig`, `jobKnowledge`, `nodes`, `edges`, `variables`, `response`, `metadata`. The required root **`response`** is the single executable final response contract used to build `ExecuteGraphResult.finalOutput`. Document-model and authoring fields (`name`, `description`, `exellixContractTarget`, `graphExecution`, `graphEntry`, `catalogRequests`, and similar) belong **under `metadata`** only. Node-scoped `taskKnowledge` belongs under each task node, not at the model root. Runtime state (`input`, `jobMemory`, `taskMemory`, `executionMemory`, `outputsMemory`, per-run options) belongs under the execution request’s **`runtime`** object and is rejected on the model. **`runtime.modelConfig`**, **`runtime.aliasConfig`**, and **`runtime.nodes[id].modelConfig`** were removed in **7.7** — model profiles belong on the graph document only.
 
-`metadata.graphExecution` can document graph execution defaults and labels, including `mode: 'forward' | 'backward' | 'hybrid'`, optional `goalNodeId`, optional `dimension`, `outputMode: 'mappedAggregation' | 'lastExitNode'`, `coreObjective`, optional `nodesResponses`, and metadata-only `flowOutline: 'linearSequence' | 'convergingParallelFlow'`. Planner mode still comes from `executeGraph({ model, runtime }).runtime.mode`; `outputMode` does not decide the returned `finalOutput`.
+`metadata.graphExecution` can document graph execution defaults and labels, including `mode: 'forward' | 'backward' | 'hybrid'`, optional `goalNodeId`, optional `dimension`, `outputMode: 'mappedAggregation' | 'lastExitNode'`, `coreObjective`, optional `nodesResponses`, and metadata-only `flowOutline: 'linearSequence' | 'convergingParallelFlow'`. Planner mode comes from `plan.schedulingPolicy.mode` or `runtime.mode`; `outputMode` does not decide the returned `finalOutput`.
 
 Enforcement: `executeGraph`, `createExellixGraphRuntime().executeGraph`, `executeNode` when a graph is passed in context, `inspectGraph`, `inspectGraphContracts`, `validateCatalogPlanning`, and Catalox graph validators call this check. Failures throw `ExellixGraphError` with code `NON_CANONICAL_GRAPH_DOCUMENT`. For CI or custom loaders, call **`assertCanonicalGraphDocument`** (exported from the package root) on parsed JSON before execution. **`loadGraph`** returns whatever the loader parsed; validation runs when you execute or inspect, not necessarily on load.
 
@@ -57,7 +57,7 @@ npm install @exellix/graph-engine
 
 ### Execution matrix hosts (`@exellix/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`, resolve **`metadata.graphEntry` per model**, seed **`runtime.executionMemory`**, and pass **`runtime.jobId`** (see [Run identity](#run-identity-host-jobid-and-engine-taskid) below). Helpers such as **`buildMatrixJobForGraphRun`** align **`id`** and **`job.jobId`** on the `job` object so you can call **`runtime.executeGraph({ model, 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.
+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.
 
 ### Configuration (`.env`)
 
@@ -97,7 +97,7 @@ Lower-level helpers (`validateRunTaskConfig`, `validateRunTaskInvoke`, `analyzeE
 ## Quick Start
 
 ```typescript
-import { createExellixGraphRuntime } from '@exellix/graph-engine';
+import { compileExellixExecutablePlan, createExellixGraphRuntime } from '@exellix/graph-engine';
 
 const runtime = createExellixGraphRuntime({
   graphLoader: myGraphLoader,
@@ -121,15 +121,18 @@ const graphModel = {
   // …
 };
 
+const graphRuntime = {
+  jobId: 'job-123',
+  job: { agentId: 'agent-1', input: {} },
+  input: { question: 'Analyze this record' },
+};
+
+const plan = compileExellixExecutablePlan(graphModel, graphRuntime);
+
 // Host correlation id (required). Engine sets `job.id` / `job.jobId` from it and generates `result.taskId`.
 const result = await runtime.executeGraph({
-  model: graphModel,
-  runtime: {
-    jobId: 'job-123',
-    job: { agentId: 'agent-1', input: {} },
-    input: { question: 'Analyze this record' },
-    // no modelConfig or aliasConfig on runtime (removed in 7.7)
-  },
+  plan,
+  runtime: graphRuntime,
 });
 
 // Canonical business output + per-run ids:
@@ -138,11 +141,11 @@ console.log(result.finalOutput, result.jobId, result.taskId);
 
 ## Public API
 
-### `runtime.executeGraph({ model, runtime })`
+### `runtime.executeGraph({ plan, runtime })`
 
 Execute a complete graph through the **single canonical client API**: `createExellixGraphRuntime(...)`. The runtime owns local-skill interception, conditional edge filtering, optional `eventEmitter`, optional `debugMode`, and produces one `ExecuteGraphResult` shape.
 
-Every call requires a static **`model: GraphModelObject`** and a dynamic **`runtime: GraphRuntimeObject`**. `runtime.jobId` is mandatory and non-empty. The engine also generates a **`taskId`** (UUID) per invocation. Together they form the **identity** forwarded to **`@exellix/ai-tasks`** (`runTask({ jobId, taskId, … })`), graph/node **`eventEmitter`** payloads, structured **`runLog`**, and Activix **`runContext`** / record metadata.
+Every call requires a compiled v2 **`plan: ExecutableGraphPlanV2`** and a dynamic **`runtime: GraphRuntimeObject`**. Hosts compile authoring graphs with `@x12i/graphenix-plan-compiler` (or {@link compileExellixExecutablePlan} for legacy exellix `GraphModelObject`) before invoke. `runtime.jobId` is mandatory and non-empty. The engine also generates a **`taskId`** (UUID) per invocation. Together they form the **identity** forwarded to **`@exellix/ai-tasks`** (`runTask({ jobId, taskId, … })`), graph/node **`eventEmitter`** payloads, structured **`runLog`**, and Activix **`runContext`** / record metadata.
 
 ```typescript
 import { createExellixGraphRuntime } from '@exellix/graph-engine';
@@ -210,10 +213,11 @@ interface ExecuteGraphResult {
   runLogOmittedCount?: number;
   logxerCorrelationId?: string;
   debug?: { nodes: NodeTraceEntry[] }; // populated only when debugMode: true
-  graphAudit?: {
-    source: 'model';
-    contentSha256: string; // stable JSON + SHA-256 of supplied model (audit / matrix persistence)
+  planAudit?: {
+    planHash: string;
+    source: string;
   };
+  trace?: unknown;
 }
 ```
 
@@ -234,13 +238,11 @@ const runtime = createExellixGraphRuntime({
   playgroundReporter,
 });
 
+const plan = compileExellixExecutablePlan(graphModel, graphRuntime);
+
 await runtime.executeGraph({
-  model,
-  runtime: {
-    jobId: 'job-123',
-    job,
-    input,
-  },
+  plan,
+  runtime: graphRuntime,
 });
 
 // Inspect full node request/response payloads in memory.

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

@@ -0,0 +1,9 @@
+import type { CompileExecutablePlanV2Options, ExecutableGraphPlanV2 } from '@x12i/graphenix-executable-contracts';
+import type { Graph, GraphModelObject } from '../types/refs.js';
+import type { GraphRuntimeObject } from '../runtime/ExellixGraphRuntime.js';
+export type CompileExellixExecutablePlanOptions = CompileExecutablePlanV2Options;
+/**
+ * Host/test helper: exellix {@link GraphModelObject} + runtime → validated v2 executable plan.
+ * Migration and plan compilation live in `@x12i/graphenix-*`; graph-engine does not duplicate format logic.
+ */
+export declare function compileExellixExecutablePlan(model: Graph | GraphModelObject, runtime: GraphRuntimeObject, options?: CompileExellixExecutablePlanOptions): ExecutableGraphPlanV2;

package/dist/src/compile/compileExellixExecutablePlan.js

@@ -0,0 +1,24 @@
+import { migrateLegacyGraphModelObjectToGraphenixExecutable, } from '@x12i/graphenix-authoring-format';
+import { compileExecutablePlanV2 } from '@x12i/graphenix-plan-compiler';
+import { validateExecutablePlan } from '@x12i/graphenix-plan-format';
+import { EXELLIX_STRUCTURED_DATA_FILTERS_V1 } from '../types/refs.js';
+import { migrateLegacyGraphResponse } from '../runtime/graphResponseMigration.js';
+/** Exellix host hooks passed into upstream {@link migrateLegacyGraphModelObjectToGraphenixExecutable}. */
+const EXELLIX_LEGACY_MIGRATE_OPTIONS = {
+    preprocessLegacy: (legacy) => migrateLegacyGraphResponse(legacy).graph,
+    structuredDataFiltersVersion: EXELLIX_STRUCTURED_DATA_FILTERS_V1,
+};
+/**
+ * Host/test helper: exellix {@link GraphModelObject} + runtime → validated v2 executable plan.
+ * Migration and plan compilation live in `@x12i/graphenix-*`; graph-engine does not duplicate format logic.
+ */
+export function compileExellixExecutablePlan(model, runtime, options) {
+    const authoring = migrateLegacyGraphModelObjectToGraphenixExecutable(model, EXELLIX_LEGACY_MIGRATE_OPTIONS);
+    const plan = compileExecutablePlanV2(authoring, runtime, options);
+    const validation = validateExecutablePlan(plan);
+    if (!validation.valid) {
+        const summary = validation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
+        throw new Error(`compileExellixExecutablePlan: invalid plan: ${summary}`);
+    }
+    return plan;
+}

package/dist/src/errors/exellixGraphErrorCodes.d.ts

@@ -13,6 +13,11 @@ export declare enum ExellixGraphErrorCode {
     INVALID_GRAPH = "INVALID_GRAPH",
     /** Graph JSON has forbidden top-level keys; document metadata must be under `metadata` only. */
     NON_CANONICAL_GRAPH_DOCUMENT = "NON_CANONICAL_GRAPH_DOCUMENT",
+    /**
+     * Graphs-studio execute envelope carries a removed or forbidden key (e.g. request-level `graphDefaultModel`).
+     * Model defaults belong on `graph.modelConfig` only.
+     */
+    NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST = "NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST",
     /** Runtime object carries forbidden model / llmCall overrides (graph document only since 7.7). */
     NON_CANONICAL_GRAPH_RUNTIME = "NON_CANONICAL_GRAPH_RUNTIME",
     /**

package/dist/src/errors/exellixGraphErrorCodes.js

@@ -14,6 +14,11 @@ export var ExellixGraphErrorCode;
     ExellixGraphErrorCode["INVALID_GRAPH"] = "INVALID_GRAPH";
     /** Graph JSON has forbidden top-level keys; document metadata must be under `metadata` only. */
     ExellixGraphErrorCode["NON_CANONICAL_GRAPH_DOCUMENT"] = "NON_CANONICAL_GRAPH_DOCUMENT";
+    /**
+     * Graphs-studio execute envelope carries a removed or forbidden key (e.g. request-level `graphDefaultModel`).
+     * Model defaults belong on `graph.modelConfig` only.
+     */
+    ExellixGraphErrorCode["NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST"] = "NON_CANONICAL_STUDIO_GRAPH_EXECUTE_REQUEST";
     /** Runtime object carries forbidden model / llmCall overrides (graph document only since 7.7). */
     ExellixGraphErrorCode["NON_CANONICAL_GRAPH_RUNTIME"] = "NON_CANONICAL_GRAPH_RUNTIME";
     /**

package/dist/src/index.d.ts

@@ -9,8 +9,8 @@
  * 5. Repeat until done/fail
  *
  * Single canonical entry point: {@link createExellixGraphRuntime} returns
- * `{ executeGraph({ model, runtime }: GraphExecutionRequest) }`. The legacy functional `executeGraph`
- * and the `ExellixGraphClient` class were removed in 5.0.
+ * `{ executeGraph({ plan, runtime }: GraphExecutionRequest) }`. Hosts compile upstream via
+ * {@link compileExellixExecutablePlan} or `@x12i/graphenix-plan-compiler`.
  */
 export type { HostExecuteGraphRunOptions, MainReadinessPolicy, ExecutionStepOption, StepRetryPolicy, ActivixNodeActivityExellixConfig, SkillKeyResolutionOptions, RunTaskRequest as ExellixGraphRunTaskRequest, RunTaskResponse as ExellixGraphRunTaskResponse, } from './types/options.js';
 export type { AiTaskProfileMetadata, AiTaskProfileWebScoping, AiTaskProfileInputSynthesis, } from './types/aiTaskProfile.js';
@@ -83,11 +83,19 @@ export type { AssertCanonicalGraphDocumentOptions, CanonicalGraphDocumentValidat
 export { assertCanonicalGraphRuntimeObject } from './runtime/validateCanonicalGraphRuntime.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 { STUDIO_GRAPH_EXECUTE_REMOVED_KEYS, getStudioGraphExecuteRemovedKeyViolations, assertCanonicalStudioGraphExecuteRequest, buildGraphExecutionRequestFromStudioExecute, } from './runtime/studioGraphExecuteRequest.js';
+export type { StudioGraphExecuteRemovedKey, StudioGraphExecuteRequest, BuildGraphExecutionRequestFromStudioExecuteOptions, } from './runtime/studioGraphExecuteRequest.js';
 export { computeGraphDocumentContentSha256, stableStringifyGraphDocument, } from './runtime/graphDocumentFingerprint.js';
 export { migrateLegacyGraphResponse, migrateLegacyGraphResponseDefinition, } from './runtime/graphResponseMigration.js';
 export type { MigrateGraphResponseResult } from './runtime/graphResponseMigration.js';
 export { applyAiTaskProfileWebScopingToNarrix, mapAiTaskProfileQuestionsToWebScopeQuestions, } from './runtime/applyAiTaskProfileWebScopingToNarrix.js';
 export { createExellixGraphRuntime } from './runtime/ExellixGraphRuntime.js';
+export type { ExecutableGraphPlanV2, NodeExecutionPlan, ExecutionUnitPlanV2, } from '@x12i/graphenix-executable-contracts';
+export { compileExellixExecutablePlan } from './compile/compileExellixExecutablePlan.js';
+export type { CompileExellixExecutablePlanOptions } from './compile/compileExellixExecutablePlan.js';
+export { migrateLegacyGraphModelObjectToGraphenixExecutable, } from '@x12i/graphenix-authoring-format';
+export type { LegacyGraphModelObject, MigrateLegacyGraphModelOptions, } from '@x12i/graphenix-authoring-format';
+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';
 export { InMemoryGraphLoader, DepGraphEngineFactory } from '../testkit/index.js';

package/dist/src/index.js

@@ -9,8 +9,8 @@
  * 5. Repeat until done/fail
  *
  * Single canonical entry point: {@link createExellixGraphRuntime} returns
- * `{ executeGraph({ model, runtime }: GraphExecutionRequest) }`. The legacy functional `executeGraph`
- * and the `ExellixGraphClient` class were removed in 5.0.
+ * `{ executeGraph({ plan, runtime }: GraphExecutionRequest) }`. Hosts compile upstream via
+ * {@link compileExellixExecutablePlan} or `@x12i/graphenix-plan-compiler`.
  */
 export { mergeGraphDocumentModel, EXELLIX_GRAPH_MODEL_VARIABLE_KEY, EXELLIX_STRUCTURED_DATA_FILTERS_V1, } from './types/refs.js';
 export { getTaskConfiguration } from './types/taskNodeConfiguration.js';
@@ -61,11 +61,15 @@ export { buildExellixGraphRuntimeObjects, setRuntimeObjectsLastJobId, summarizeR
 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, getGraphEntryEmptyInputPathViolations, } from './runtime/graphModelStudioSeparation.js';
+export { STUDIO_GRAPH_EXECUTE_REMOVED_KEYS, getStudioGraphExecuteRemovedKeyViolations, assertCanonicalStudioGraphExecuteRequest, buildGraphExecutionRequestFromStudioExecute, } from './runtime/studioGraphExecuteRequest.js';
 export { computeGraphDocumentContentSha256, stableStringifyGraphDocument, } from './runtime/graphDocumentFingerprint.js';
 export { migrateLegacyGraphResponse, migrateLegacyGraphResponseDefinition, } from './runtime/graphResponseMigration.js';
 export { applyAiTaskProfileWebScopingToNarrix, mapAiTaskProfileQuestionsToWebScopeQuestions, } from './runtime/applyAiTaskProfileWebScopingToNarrix.js';
 // New runtime with injection seam
 export { createExellixGraphRuntime } from './runtime/ExellixGraphRuntime.js';
+export { compileExellixExecutablePlan } from './compile/compileExellixExecutablePlan.js';
+export { migrateLegacyGraphModelObjectToGraphenixExecutable, } from '@x12i/graphenix-authoring-format';
+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';
 // Graph loaders

package/dist/src/plan/aiModelSelectionWire.d.ts

@@ -0,0 +1,11 @@
+import type { AiModelSelection } from '@x12i/graphenix-executable-contracts';
+import type { ResolvedInvocationSnapshot } from '@x12i/graphenix-executable-contracts';
+/**
+ * Maps plan {@link AiModelSelection} to ai-tasks 8.4+ wire profile strings.
+ */
+export declare function aiModelSelectionToWireString(selection: AiModelSelection | undefined): string | undefined;
+export declare function resolvedSnapshotToWireString(snapshot: ResolvedInvocationSnapshot | undefined): string | undefined;
+export declare function unitModelWireString(args: {
+    modelSelection?: AiModelSelection;
+    resolvedInvocationSnapshot?: ResolvedInvocationSnapshot;
+}): string | undefined;

package/dist/src/plan/aiModelSelectionWire.js

@@ -0,0 +1,39 @@
+/**
+ * Maps plan {@link AiModelSelection} to ai-tasks 8.4+ wire profile strings.
+ */
+export function aiModelSelectionToWireString(selection) {
+    if (selection == null)
+        return undefined;
+    if (selection.kind === 'profileChoice')
+        return selection.key.trim();
+    if (selection.kind === 'profile') {
+        const profile = selection.profile.trim();
+        const choice = typeof selection.choice === 'string' ? selection.choice.trim() : '';
+        return choice ? `${profile}/${choice}` : profile;
+    }
+    if (selection.kind === 'model') {
+        const modelId = typeof selection.modelId === 'string'
+            ? selection.modelId
+            : typeof selection.model === 'string'
+                ? selection.model
+                : '';
+        return `${selection.provider}/${modelId}`.replace(/\/+/g, '/');
+    }
+    return undefined;
+}
+export function resolvedSnapshotToWireString(snapshot) {
+    if (snapshot == null)
+        return undefined;
+    if (snapshot.purpose === 'strictReplay' || snapshot.purpose === 'debugReplay') {
+        return `${snapshot.provider}/${snapshot.modelId}`;
+    }
+    if (snapshot.profileChoiceKey)
+        return snapshot.profileChoiceKey;
+    return undefined;
+}
+export function unitModelWireString(args) {
+    const fromSnapshot = resolvedSnapshotToWireString(args.resolvedInvocationSnapshot);
+    if (fromSnapshot)
+        return fromSnapshot;
+    return aiModelSelectionToWireString(args.modelSelection);
+}

package/dist/src/plan/applyNodePlanInvoke.d.ts

@@ -0,0 +1,10 @@
+import type { FinalizerExecutionPlan, NodeExecutionPlan } from '@x12i/graphenix-executable-contracts';
+import type { TaskNode } from '../types/refs.js';
+/** Merge frozen plan invoke contract onto exellix task node before execution. */
+export declare function applyNodePlanInvoke(node: TaskNode, nodePlan: NodeExecutionPlan): TaskNode;
+export declare function finalizerPlanForId(plan: {
+    finalizerPlans: Record<string, FinalizerExecutionPlan>;
+}, nodeId: string): FinalizerExecutionPlan | undefined;
+export declare function nodePlanForId(plan: {
+    nodePlans: Record<string, NodeExecutionPlan>;
+}, nodeId: string): NodeExecutionPlan | undefined;

package/dist/src/plan/applyNodePlanInvoke.js

@@ -0,0 +1,67 @@
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+/** Merge frozen plan invoke contract onto exellix task node before execution. */
+export function applyNodePlanInvoke(node, nodePlan) {
+    const patched = structuredClone(node);
+    const ic = nodePlan.invokeContract;
+    if (!ic)
+        return patched;
+    if (ic.taskVariable != null)
+        patched.taskVariable = structuredClone(ic.taskVariable);
+    if (ic.inputsConfig != null)
+        patched.inputsConfig = structuredClone(ic.inputsConfig);
+    if (ic.executionMapping != null)
+        patched.executionMapping = structuredClone(ic.executionMapping);
+    if (ic.jobContextMapping != null)
+        patched.jobContextMapping = structuredClone(ic.jobContextMapping);
+    if (ic.smartInput != null)
+        patched.smartInput = structuredClone(ic.smartInput);
+    if (ic.scope != null)
+        patched.scope = structuredClone(ic.scope);
+    if (ic.memory != null)
+        patched.memory = structuredClone(ic.memory);
+    if (Array.isArray(ic.knowledgeRefs?.taskKnowledge)) {
+        patched.taskKnowledge = ic.knowledgeRefs.taskKnowledge.map((ref) => {
+            if (typeof ref === 'string')
+                return ref;
+            if (isPlainRecord(ref) && typeof ref.id === 'string')
+                return ref.id;
+            return String(ref);
+        });
+    }
+    const tc = { ...(patched.taskConfiguration ?? {}) };
+    const pipeline = ic.pipeline;
+    if (isPlainRecord(pipeline)) {
+        if (pipeline.executionStrategies !== undefined)
+            tc.executionStrategies = pipeline.executionStrategies;
+        if (pipeline.aiTaskStrategies !== undefined)
+            tc.aiTaskStrategies = pipeline.aiTaskStrategies;
+        if (pipeline.aiTaskProfile !== undefined)
+            tc.aiTaskProfile = pipeline.aiTaskProfile;
+        if (pipeline.narrix !== undefined)
+            tc.narrix = pipeline.narrix;
+        if (pipeline.narrixInput !== undefined)
+            tc.narrixInput = pipeline.narrixInput;
+        if (pipeline.narrixMode !== undefined)
+            tc.narrixMode = pipeline.narrixMode;
+        if (pipeline.llmCall !== undefined)
+            tc.llmCall = pipeline.llmCall;
+    }
+    if (ic.validation?.aiTasksOutputValidation != null) {
+        tc.aiTasksOutputValidation = ic.validation.aiTasksOutputValidation;
+    }
+    if (ic.validation?.outputValidation != null) {
+        patched.outputValidation = ic.validation.outputValidation;
+    }
+    if (ic.localConfig != null)
+        Object.assign(tc, ic.localConfig);
+    patched.taskConfiguration = tc;
+    return patched;
+}
+export function finalizerPlanForId(plan, nodeId) {
+    return plan.finalizerPlans[nodeId];
+}
+export function nodePlanForId(plan, nodeId) {
+    return plan.nodePlans[nodeId];
+}

package/dist/src/plan/embeddedGraphToExellixGraph.d.ts

@@ -0,0 +1,5 @@
+import type { ExecutableGraphPlanV2, NormalizedExecutableGraphDocument } from '@x12i/graphenix-executable-contracts';
+import type { Graph } from '../types/refs.js';
+/** Materialize exellix {@link Graph} from plan embedded normalized authoring graph. */
+export declare function embeddedGraphToExellixGraph(plan: ExecutableGraphPlanV2): Graph;
+export declare function getEmbeddedExecutableDocument(plan: ExecutableGraphPlanV2): NormalizedExecutableGraphDocument;

package/dist/src/plan/embeddedGraphToExellixGraph.js

@@ -0,0 +1,131 @@
+import { getFinalizerNodeConfig, getTaskNodeConfig, isExecutableFinalizerNode, isExecutableTaskNode, } from '@x12i/graphenix-executable-contracts';
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+function taskNodeFromExecutableNode(node) {
+    const params = getTaskNodeConfig(node);
+    if (!params) {
+        throw new Error(`Expected executable task node "${node.id}"`);
+    }
+    const tc = isPlainRecord(params.taskConfiguration) ? { ...params.taskConfiguration } : {};
+    const out = {
+        id: node.id,
+        type: 'task',
+        skillKey: typeof params.skillKey === 'string' ? params.skillKey : undefined,
+    };
+    if (params.taskVariable !== undefined)
+        out.taskVariable = structuredClone(params.taskVariable);
+    if (params.inputsConfig !== undefined)
+        out.inputsConfig = structuredClone(params.inputsConfig);
+    if (params.executionMapping !== undefined) {
+        out.executionMapping = structuredClone(params.executionMapping);
+    }
+    if (Array.isArray(params.taskKnowledge)) {
+        out.taskKnowledge = params.taskKnowledge.map((ref) => {
+            if (typeof ref === 'string')
+                return ref;
+            if (isPlainRecord(ref) && typeof ref.id === 'string')
+                return ref.id;
+            return String(ref);
+        });
+    }
+    if (params.conditions !== undefined)
+        out.conditions = structuredClone(params.conditions);
+    if (isPlainRecord(params.variables))
+        out.variables = structuredClone(params.variables);
+    if (isPlainRecord(params.metadata))
+        out.metadata = structuredClone(params.metadata);
+    out.taskConfiguration = tc;
+    const pipeline = params.executionPipeline;
+    if (Array.isArray(pipeline))
+        out.executionPipeline = structuredClone(pipeline);
+    return out;
+}
+function finalizerNodeFromExecutableNode(node) {
+    const params = getFinalizerNodeConfig(node);
+    if (!params) {
+        throw new Error(`Expected executable finalizer node "${node.id}"`);
+    }
+    const paramsRecord = params;
+    return {
+        id: node.id,
+        type: 'finalizer',
+        finalizerType: params.finalizerType,
+        config: isPlainRecord(params.config) ? structuredClone(params.config) : {},
+        inputs: isPlainRecord(params.inputs) ? structuredClone(params.inputs) : undefined,
+        ...(isPlainRecord(paramsRecord.outputMapping)
+            ? { outputMapping: structuredClone(paramsRecord.outputMapping) }
+            : {}),
+    };
+}
+function knowledgeRefsToExellixStrings(refs) {
+    if (!Array.isArray(refs))
+        return undefined;
+    return refs.map((ref) => {
+        if (typeof ref === 'string')
+            return ref;
+        if (isPlainRecord(ref) && typeof ref.id === 'string')
+            return ref.id;
+        return String(ref);
+    });
+}
+function edgesFromPlan(plan) {
+    return plan.topology.edges.map((edgeRef) => {
+        const deferred = plan.deferredGates.edgeGates[edgeRef.edgeId];
+        const out = {
+            from: edgeRef.from.nodeId,
+            to: edgeRef.to.nodeId,
+        };
+        if (deferred?.when != null)
+            out.when = deferred.when;
+        return out;
+    });
+}
+function responseFromEmbedded(doc, plan) {
+    const metaResponse = doc.graph.metadata?.graphResponse;
+    if (isPlainRecord(metaResponse)) {
+        const out = {
+            shape: isPlainRecord(metaResponse.shape) ? structuredClone(metaResponse.shape) : {},
+        };
+        if (metaResponse.missing !== undefined) {
+            out.missing = metaResponse.missing;
+        }
+        if (metaResponse.version !== undefined) {
+            out.version = metaResponse.version;
+        }
+        return out;
+    }
+    if (isPlainRecord(plan.contracts?.response?.finalOutputSchema)) {
+        return { shape: { type: 'literal', value: {} } };
+    }
+    return { shape: {} };
+}
+/** Materialize exellix {@link Graph} from plan embedded normalized authoring graph. */
+export function embeddedGraphToExellixGraph(plan) {
+    if (plan.normalizedGraph.mode !== 'embedded') {
+        throw new Error('embeddedGraphToExellixGraph requires embedded normalizedGraph');
+    }
+    const doc = plan.normalizedGraph.graph;
+    const nodes = [];
+    for (const node of doc.graph.nodes) {
+        if (isExecutableTaskNode(node))
+            nodes.push(taskNodeFromExecutableNode(node));
+        else if (isExecutableFinalizerNode(node))
+            nodes.push(finalizerNodeFromExecutableNode(node));
+    }
+    return {
+        id: plan.source.graphId,
+        version: plan.source.graphRevision,
+        nodes,
+        edges: edgesFromPlan(plan),
+        response: responseFromEmbedded(doc, plan),
+        metadata: isPlainRecord(doc.graph.metadata) ? structuredClone(doc.graph.metadata) : undefined,
+        jobKnowledge: knowledgeRefsToExellixStrings(isPlainRecord(doc.graph.metadata) ? doc.graph.metadata.jobKnowledge : undefined),
+    };
+}
+export function getEmbeddedExecutableDocument(plan) {
+    if (plan.normalizedGraph.mode !== 'embedded') {
+        throw new Error('getEmbeddedExecutableDocument requires embedded normalizedGraph');
+    }
+    return plan.normalizedGraph.graph;
+}

package/dist/src/plan/planDeferredGates.d.ts

@@ -0,0 +1,16 @@
+import type { DeferredEdgeGate, DeferredGateSet, DeferredNodeGate, ExecutableGraphPlanV2 } from '@x12i/graphenix-executable-contracts';
+import type { RunxClient } from '@x12i/runx';
+import type { TaskNodeConditionEvalContext } from '../runtime/taskNodeConditionsEvaluation.js';
+export declare function evaluateDeferredNodeGate(gate: DeferredNodeGate | undefined, ctx: TaskNodeConditionEvalContext, executionInput: Record<string, unknown>, runx?: RunxClient): Promise<{
+    ok: boolean;
+    skipReason?: string;
+}>;
+export declare function evaluateDeferredEdgeGate(gate: DeferredEdgeGate | undefined, ctx: TaskNodeConditionEvalContext): boolean;
+export declare function buildIncomingEdgeGateMap(plan: ExecutableGraphPlanV2): Map<string, DeferredEdgeGate[]>;
+export declare function nodeDeferredGate(plan: ExecutableGraphPlanV2, nodeId: string): DeferredNodeGate | undefined;
+export declare function hasPlanConditionalEdges(plan: ExecutableGraphPlanV2): boolean;
+export declare function evaluatePlanEntryGates(gates: DeferredGateSet['entryGates'] | undefined, executionInput: Record<string, unknown>, ctx: TaskNodeConditionEvalContext, runx?: RunxClient): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+export declare function planNeedsRunx(plan: ExecutableGraphPlanV2): boolean;