@exellix/graph-engine 6.0.0

package/.env.example

@@ -0,0 +1,3 @@
+# ============================================
+# nx-mongo Configuration
+# ============================================

package/CHANGELOG.md

@@ -0,0 +1,208 @@
+# Changelog
+
+## 5.16.0
+
+### Breaking
+
+- **Flat MAIN `input` only:** Removed automatic `execution.input.raw` / `jobMemory.raw` seeding from `job.raw` / `job.input.raw` in `seedGraphRunExecutionState`. Hosts must pass entity fields directly on `runtime.input` (no nested `input.raw` wrapper). In-repo graphs and docs migrated to `input` / `input.*` paths; use `inputsConfig` with `path: "input"` when aliasing the full MAIN bucket onto `runTask.input.record`.
+
+## 5.15.0
+
+### Added
+
+- **Task-node runTask preflight:** `buildTaskNodeRunTaskRequest`, `validateTaskNodeRunTaskConfig`, `validateTaskNodeRunTaskInvoke`, and `analyzeTaskNodeRunTaskRequest` build the same outbound `RunTaskRequest` as `executeNode` and delegate to `@exellix/ai-tasks` validation/analysis (no LLM invoke).
+- **Re-exports:** `validateRunTaskConfig`, `validateRunTaskInvoke`, `analyzeRunTaskRequest`, `analyzeSkillRequest`, `formatSkillRequestAnalysisMarkdown`, Rendrix template helpers, and related types from the package root so hosts can depend on graph-engine only.
+
+## 5.13.0
+
+### Breaking
+
+- **Two variable buckets only:** Graph and job scopes share `execution.jobVariables` (paths `jobVariables.*`; legacy alias `variables.*`). Removed separate `execution.variables`. Task/node scope remains `execution.taskVariables` (`taskVariables.*`). Outbound `runTask.variables` carries the job bucket (ai-tasks ≥ 7.6.2 passthrough).
+
+## 5.12.0
+
+### Breaking
+
+- **No merged variables bag:** Removed `mergeVariables` and `buildVariablesForTaskNode`. Graph/job/task scopes are mirrored separately on `executionMemory` as `variables`, `jobVariables`, and `taskVariables`. Memory paths `variables.*`, `jobVariables.*`, and `taskVariables.*` resolve against distinct buckets (no cross-bucket fallback). Outbound `runTask.variables` carries the graph bucket only; job/task scopes are on `executionMemory`.
+
+### Added
+
+- **Variable bucket helpers:** `readExecutionVariableBuckets`, `seedGraphVariableBucketsOnExecution`, `mirrorTaskVariablesOnExecution`, `buildMemoryResolutionRootFromExecution`, `buildPredicateEvalContextForNode`.
+- **`GraphRuntimeObject.jobVariables` / `taskVariables`** top-level runtime fields mirrored to execution.
+
+## 5.11.0
+
+### Added
+
+- **`inputsConfig` on task nodes:** Canonical name for runtime payload bindings (replaces confusing `node.inputs`). Dual read: `inputsConfig` → `inputBindings` → `inputs`. Export `readTaskNodeInputsConfig`.
+- **`nodeInputsConfig` response selector:** Replaces `nodeInputs`; reads `inputsConfig` + `taskVariable` on the referenced node. Legacy `nodeInputs` selector type still accepted.
+
+### Changed
+
+- Docs and inspection label bindings as `inputsConfig.*`. Finalizer nodes still use `inputs`.
+
+## 5.10.0
+
+### Added
+
+- **`taskVariable` on task nodes:** Dynamic task configuration (prompts, literals, `{ "$path": "variables.*" }`) is resolved separately from runtime payload bindings in `inputs` / `inputBindings`. `resolveTaskNodeInputsForRunTask` merges `taskVariable` + bindings into MAIN `input` (legacy literals and `variables.*` refs still under `inputs` are supported until graphs are composer-canonicalized).
+- **Exports:** `resolveTaskNodeTaskVariableForRunTask`, `resolveTaskNodeInputBindingsForRunTask`.
+
+### Changed
+
+- **Inspection:** `getNodeScopingQuestion` reads `taskVariable.question` and classifies input bindings vs variable refs separately.
+
+## 5.9.0
+
+### Breaking
+
+- **No legacy input shims:** Removed `coalesceRunTaskInputBucket`, `canonicalizeGraphEngineMemoryPath`, `mapInputsMemoryPathToInputRoot`, `mapSmartInputPathsInputsToInput`, `canonicalizeSmartInputConfig`, `normalizeNodeAiTasksMemoryPaths`, `materializeStructuredRunTaskInput`, `parseLooseJsonObject`, and `isDeprecatedGraphEngineMemoryPath`. `input.*` and `inputs.*` resolve as **distinct roots** (no cross-fallback). MAIN `input` must be a plain object (no stringified JSON blob promotion). `extractNonSystemFields` variable leak removed — use `node.variables` only.
+
+### Changed
+
+- **MAIN `input` vs caller `inputs`:** `buildRunTaskMainInput` builds outbound `RunTaskRequest.input` from runtime MAIN plus node bindings only; caller bag on `inputs` separately.
+
+## 5.8.0
+
+### Changed
+
+- **MAIN `input` vs caller `inputs`:** `buildRunTaskMainInput` builds outbound `RunTaskRequest.input` from runtime MAIN (`executionMemory.input`) plus materialized node bindings only. The caller bag (`runtime.inputs`) is forwarded separately on `inputs` and is no longer merged into `input`.
+
+### Added
+
+- **Smart-input / MAIN readiness (G1, G3, G4):** `materializeStructuredRunTaskInput` promotes fields from legacy string `input` blobs; `executionMemory.input` is mirrored before `runTask`. `input.*` paths alias to `inputs.*` via `resolveGraphEngineMemoryPathValue`. Configurable `mainReadinessPolicy` (`fail` | `warn` | `off`) with check ids `execution_input_empty` and `synthesis_context_empty` before MAIN `runTask`.
+- **Graph response mapping (G7):** `finalOutput` mapping snapshots full accumulated `executionMemory` / `outputsMemory` after parallel batches complete.
+- **Canonical model (G9):** `resolveCanonicalModelUsed` and `buildAiTasksObservabilityRecord` emit authoritative `modelUsed` from gateway metadata.
+
+## 5.7.0
+
+### Breaking
+
+- **Task-node `conditions`:** Removed `conditions.aiFilter` and structured `conditions.dataFilters` v1 on task nodes. Use `jsonConditions`, `jsConditionFunction`, and `aiCondition` (runx). Opaque `conditions.dataFilters: string[]` remains declarative only.
+- **`modelConfig`:** Flat `{ xynthesisModel, skillModel }` at graph root and `taskConfiguration` replaced by `{ cases: ModelConfigCase[] }` with exactly one no-`when` default case. Migrate: `{ cases: [{ modelConfig: { xynthesisModel, skillModel } }] }`.
+- **`scope.contextualKnowledge.filter.where`:** Removed `cidrContains`. Use `eq` / `eqAny` on host-prepared fields only.
+
+### Added
+
+- **runx integration:** `evaluateTaskNodeConditions`, `evaluateConditionWhen`, conditional `modelConfig` resolution via `resolveModelConfigForNode`.
+- **Runtime options:** `runx`, `runxCreateOptions` on `createExellixGraphRuntime`.
+- **Docs:** [`.docs/task-node-conditions-evaluation.md`](.docs/task-node-conditions-evaluation.md), [`.docs/platform-generic-vs-implementation.md`](.docs/platform-generic-vs-implementation.md).
+
+## 5.5.0
+
+### Changed
+
+- **Dual memory roots `input` and `inputs`:** Both are allowlisted for `smartInput.paths` and `inputSynthesis.sources`; paths are no longer rewritten to `input.*` at validation or runtime. Optional migration via `mapInputsMemoryPathToInputRoot` / `mapSmartInputPathsInputsToInput`.
+- **`runTask` wire:** Forwards `inputs` (caller bag) alongside coalesced `input` when present. See [CR-input-and-inputs-dual-root.md](.docs/CR-input-and-inputs-dual-root.md) for downstream `@exellix/ai-tasks` and graphs-studio work.
+
+## 5.4.0
+
+### Added
+
+- **`canonicalizeGraphEngineMemoryPath`** — maps legacy `inputs` / `inputs.*` smart-input and input-synthesis paths to canonical `input` / `input.*` without adding `inputs` as a public memory root.
+- **`coalesceRunTaskInputBucket`**, **`resolveGraphEngineMemoryPathValue`**, **`buildGraphEngineMemoryResolutionRootFromWorkingMemory`** — resolve smart-input paths against working-memory shapes (caller `inputs` bag, stringified `input` JSON, bare `input`, `xynthesized.job`); runtime `runTask` uses coalesced `input` for ai-tasks.
+- **`isAllowedGraphEngineMemoryPath`**, **`graphEngineMemoryPathValidationMessage`**, **`canonicalizeSmartInputConfig`**, **`normalizeNodeAiTasksMemoryPaths`**, **`collectAiTasksNodeExtensionIssues`**, and **`assertAiTasksNodeExtensionsValid`** exported from the package root for hosts (e.g. graphs-studio).
+
+### Fixed
+
+- **`validateCatalogPlanning`** now runs ai-tasks extension checks (`smartInput`, `inputSynthesis`) on all non-finalizer task nodes, not only nodes with `metadata`.
+- Runtime **`runTask`** forwards canonicalized `smartInput.paths`; input-synthesis PRE `memoryPaths` are canonicalized when the pipeline is built.
+
+## 5.0.3
+
+### Added
+
+- **`executeGraph` inline graph contract.** Optional **`ExecuteGraphInput.graph`** (canonical full document) skips **`graphLoader`** when validation succeeds. Callers may omit **`graphId`** / **`job.graphId`** when the document includes a non-empty **`id`**. If inline validation fails and **`graphId ?? job.graphId`** is set, the engine loads by that id instead.
+- **`ExecuteGraphResult.graphAudit`.** `{ source: 'inline' | 'loader', contentSha256 }` fingerprints the resolved graph (stable sorted JSON + SHA-256) for matrix / host persistence alongside catalog **`graphVersion`**.
+- **`computeGraphDocumentContentSha256`** and **`stableStringifyGraphDocument`** exported from the package root.
+
+## 5.0.0 — Canonical no-legacy
+
+> **Hard-break release.** Every legacy / dual-path surface is removed in one cut.
+> See [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) for the full migration matrix
+> (every deleted alias, every renamed key, before / after JSON snippets).
+
+### Breaking
+
+- **Single client surface.** `createExellixGraphRuntime` + `ExecuteGraphInput` is the only public executor. The functional `executeGraph` / `executeNode` and the `ExellixGraphClient` class are deleted; their re-exports and the `HYBRID_MODE_REQUIRES_INJECTED_RUNTIME` error code are gone.
+- **Canonical graph JSON.** [`assertCanonicalGraphDocument`](src/runtime/validateCanonicalGraphDocument.ts) now rejects every legacy alias at load time:
+  - `graph.nodes` must be a `GraphNode[]` (record-keyed `Record<string, GraphNode>` is rejected with `NON_CANONICAL_GRAPH_DOCUMENT`).
+  - Task nodes must use `node.skillKey` / `node.variables` only — `node.data.skillKey`, `node.data.variables`, `node.metadata.skillKey`, `node.metadata.variables` are rejected with `NON_CANONICAL_TASK_NODE`.
+  - `metadata.synthesizedContext`, `metadata.executionStrategyKey`, `metadata.outputConstraints`, and the web-scope keys on `metadata.narrix` (`enableWebScope`, `forceWebScope`, `webScopeQuestions`, `webScoping`, `webScopeTemplates`, `webScopeQuestionTemplate`, `webScopeObjects`, `webScopeEntityIdPath`, `webScopeEntityTypePath`, `enrichWebScopeQuestionFromExecutionRaw`) are rejected. Web scoping authoring lives only on `metadata.aiTaskProfile.webScoping`; structured output validation lives only on `metadata.aiTasksOutputValidation`.
+- **`RunTaskRequest` builder.** `metadata.executionStrategyKey` is no longer typed or forwarded; only `metadata.executionStrategies` is honored. `taskKind ∈ {decision, utility, content}`.
+- **Run-log metadata keys.** `EXELLIX_RUN_LOG_METADATA_KEY` (`exellixRunLog`) and `EXELLIX_LOGXER_CORRELATION_METADATA_KEY` (`logxerCorrelationId`) are removed from the public surface. Only `runLog` (`AI_TASKS_RUN_LOG_METADATA_KEY`) and `logxerRunId` (`AI_TASKS_LOGXER_RUN_ID_METADATA_KEY`) are read by `extractTaskRunLogFromMetadata` / `extractLogxerCorrelationFromMetadata`.
+- **Narrix authoring split.** `NarrixPreProcessorConfig` (graph JSON) no longer carries web-scope fields; the outbound wire payload (`RunTaskRequest.narrix`, type `ResolvedNarrixWirePayload`) is composed by [`applyAiTaskProfileWebScopingToNarrix`](src/runtime/applyAiTaskProfileWebScopingToNarrix.ts) from `metadata.aiTaskProfile.webScoping`. The `WOROX_LOCAL_WEB_SCOPE_*` and `WOROX_ENRICH_WEB_SCOPE_QUESTION_FROM_RAW` env vars no longer affect graph-engine.
+
+### Added
+
+- **Runtime parity ports.** Local-skill interception (`isLocalSkillKey` + `runScopedDataReader` / `runDeterministicRule` / `runScopedAnswerWriter` / `runScopedAnswerAssembler`), `evaluateGraphPredicate` conditional-edge filtering, `eventEmitter` lifecycle hooks, and `debugMode` per-node trace are now native to `ExellixGraphRuntime`. Local skills short-circuit `tasksClient.runTask`.
+- **`ExecuteGraphResult.debug`.** Populated only when `ExecuteGraphInput.debugMode === true`; surfaces `nodes: NodeTraceEntry[]` (sorted by `startedAt`).
+- **Compile-time `RunTaskRequest` parity test.** [`tests/passthrough-parity.test.ts`](tests/passthrough-parity.test.ts) classifies every `keyof RunTaskRequest` as REQUIRED / BUILT / STRATEGY / PASSTHROUGH / IGNORED via an exhaustive `Record<keyof RunTaskRequest, true>`. Adding a field upstream without classifying it breaks the build.
+- **`npm run check:no-legacy`.** Greps `src/`, `testkit/`, and `graphs/` for removed identifiers (`executeGraph`, `executeNode`, `ExellixGraphClient`, `EXELLIX_RUN_LOG_METADATA_KEY`, `EXELLIX_LOGXER_CORRELATION_METADATA_KEY`, `executionStrategyKey`, `synthesizedContext`, `outputConstraints`, `enableWebScope`) and fails on hits.
+
+### Removed
+
+- `src/client/ExellixGraphClient.ts`, `src/runtime/executeGraph.ts`, `src/runtime/executeNode.ts`, `src/loaders/GraphLoader.ts` (the wrapper class — `FileGraphLoader` and the runtime's `GraphLoader` interface stay).
+- Legacy types from [`src/types/options.ts`](src/types/options.ts) (`ExecuteGraphOptions`, `ExecuteNodeOptions`, `ExellixGraphClientConfig`, `GraphLoader`, `GraphenixEngine`, `AITasksClient`) and [`src/types/results.ts`](src/types/results.ts) (`ExecuteGraphResponse`, `ExecuteGraphFinalizedResponse`, `ExecuteGraphDebugResponse`, `GraphExecutionResult`).
+- `getGraphVariables`, `getNodeVariables`, `getGraphMemory`, `getNodeMemory` from `src/runtime/variables.ts` and `src/runtime/memory.ts`.
+- `HYBRID_MODE_REQUIRES_INJECTED_RUNTIME` from `exellixGraphErrorCodes.ts`.
+
+### Migration
+
+See [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) for before/after JSON snippets and code substitutions.
+
+## 4.7.1
+
+### Fixed
+
+- **`executeNode` vs `ExellixGraphRuntime` parity:** Shared [`buildTaskNodeJobContext`](src/runtime/buildTaskNodeJobContext.ts) (jobContextMapping + `scope.contextualKnowledge`) and [`resolveNarrixForTaskNode`](src/runtime/resolveNarrixForTaskNode.ts) (graph `variables.narrix` defaults + `aiTaskProfile` web merge). Injected runtime previously omitted contextual scope and graph-level Narrix defaults.
+- **`ExellixGraphRuntime` variables:** Merges `graph.variables` and `mergeGraphDocumentModel` → `variables.__graphModel` into the template `variables` bucket before `runTask`, matching functional `getNodeVariables` / `mergeVariables` precedence.
+- **MAIN `runTask`:** `node.data.upstreamNodeIds` is now forwarded into canonical `input` on the functional path (already present on `ExellixGraphRuntime`).
+
+### Documentation
+
+- **[`.docs/exellix-graph-engine-format.md`](.docs/exellix-graph-engine-format.md):** Align **Narrix / web scoping** with runtime (`executeNode` forwards **`narrix`** only; **`@exellix/ai-tasks`** owns internal web scoper). Replace stale "local web scoping" narrative; cite **`documenations/web-scoping-in-ai-tasks.md`**. Document **`@exellix/ai-tasks`** semver from **`package.json`** (^7.3.8) and **run-log** metadata keys (`runLog` / `exellixRunLog`, `logxerRunId` / `logxerCorrelationId`); note **`RunLogEntry`** has no **`schemaVersion`** yet.
+- **[`README.md`](README.md):** Same compatibility wording for ai-tasks and optional CI note.
+
+### Added
+
+- **Metadata passthrough:** [`extractRunTaskMetadataPassthrough`](src/runtime/buildAiTasksRunTaskRequest.ts) whitelists optional `@exellix/ai-tasks` **7.2.x** request fields from task-node `metadata` (`narrixScope`, `aiScoping`, `aiScopingOptions`, `timeoutMs`, template tokens/options, `aiEngineId`, `sessionId`, `agentType`, `gatewayDiagnostics`, `context`, `knowledge`), merged inside [`buildAiTasksRunTaskRequest`](src/runtime/buildAiTasksRunTaskRequest.ts).
+- **Exports:** `extractRunTaskMetadataPassthrough`, `RunTaskMetadataPassthrough`, `buildTaskNodeJobContext`, `resolveNarrixForTaskNode` from the package root.
+
+## 4.6.0
+
+### Changed
+
+- **Naming / docs:** Internal module `xynthesisStrategyPhases.ts` → **`aiTasksStrategyPhases.ts`**; **`runEngineAiTasksStrategyPhase`** replaces `runEngineXynthesisStrategyPhase`. Documentation states explicitly that PRE/POST strategy utilities call **`@exellix/ai-tasks` `runTask` only** — graph-engine does **not** import **`@exellix/xynthesis`**.
+- **`@exellix/ai-tasks`:** Dependency **`^7.1.2`**. **`src/types/aiTasksDerivedTypes.ts`** re-exports stable request subtree types from the ai-tasks package root (`XynthesizedMemory`, `SmartInputConfig`, `ExecutionStrategyInvocation`, …).
+
+## 4.4.0
+
+### Added
+
+- **Graph format / ai-tasks v7:** Task node `metadata` may include **`narrixMode`**, **`inputStrategyKey`**, and **`narrixInput`** — forwarded on MAIN `runTask` via **`extractRunTaskStrategyOverrides`** (classic `executeNode` + `ExellixGraphRuntime`). **`metadata.executionStrategies`** maps to **`RunTaskRequest.executionStrategies`** (engine sends **`[]`** when omitted). **`metadata.executionStrategyKey`** is **authoring-only** and is **not** forwarded (use **`executionStrategies`** per ai-tasks **7.1.x**). Root **`executionType`** is not forwarded.
+- **Docs:** [`.docs/exellix-graph-engine-format.md`](.docs/exellix-graph-engine-format.md) — “`metadata` — `@exellix/ai-tasks` runtime strategy & Narrix wiring”.
+
+## 4.0.0 (historical — pre-4.4.0 cutover to ai-tasks v6)
+
+> Note: this entry was previously labeled `5.0.0` in the changelog but
+> chronologically predates `4.4.0` / `4.6.0` / `4.7.1`. Renamed to `4.0.0` for
+> the canonical no-legacy 5.0 release; the real 5.0.0 entry is at the top of
+> this file.
+
+### Breaking
+
+- **`@exellix/ai-tasks` ≥ 6.0.1:** Every MAIN `runTask` now carries **`jobTypeId`**, **`taskTypeId`**, canonical **`input`**, and graph telemetry **`nodeId`** / **`coreSkillId`**. Graph-engine **no longer** spreads duplicate root-level task fields (`inputs`, root `question`, etc.). Stub clients that read **`req.skillId`** should use **`req.nodeId`** or **`req.coreSkillId`** (see `src/tests/test-finalizers-runtime.ts`).
+- **Public types:** `RunTaskRequest` / `RunTaskResponse` align with `@exellix/ai-tasks`; adapters may still add **`success`** / **`ok`** / **`output`** (e.g. `RealTasksClient`).
+
+### Added
+
+- **`buildAiTasksRunTaskRequest`** (`src/runtime/buildAiTasksRunTaskRequest.ts`): single canonical builder for MAIN node requests (classic `executeNode` + injected `ExellixGraphRuntime`).
+- **Engine PRE/POST strategy utilities:** `metadata.aiTaskProfile.preStrategyKey` / `postStrategyKey` → extra `@exellix/ai-tasks` **`runTask`** calls (no direct Xynthesis SDK in graph-engine); merge **`execution.xynthesis.pre`** / **`execution.xynthesis.post`**.
+- **`copyExecutionContextFields`** exported from `memory.ts`; runtime success path copies **`webContext`** / **`synthesizedContext`** like classic `executeNode`.
+- **`Job.jobTypeId`** optional field for explicit `runTask.jobTypeId`.
+
+### Changed
+
+- **`RealTasksClient`:** Forwards requests without pre-merging `variables` via `mergeSkillTemplateVariables` (ai-tasks owns merge order per `RUNTASK_REQUEST.md`).
+- **Finalizer synthesize `runTask`:** Supplies `jobTypeId`, `taskTypeId`, `coreSkillId`, `nodeId`, and non-empty `input`.