@exellix/graph-engine 6.0.0

package/README.md

@@ -0,0 +1,827 @@
+# `@exellix/graph-engine` — Clean Graph Executor SDK
+
+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.
+
+**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.
+
+## Core Responsibilities
+
+`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(...)`
+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(...)`
+   - Commit output into graphenix
+4. Repeat until done/fail
+
+**Nothing else** beyond orchestration, memory mapping, finalizers, and the small local-skill surface above — and **not** matrix/worker/queue ownership (see [above](#what-this-package-does-and-does-not)).
+
+### Specification & documentation
+
+| Topic | Document |
+|--------|----------|
+| **Object contracts** (model × runtime + per-call resolution view) | Index: [`formats-documentations/README.md`](formats-documentations/README.md) — [`graph-model`](formats-documentations/graph-model-object-format.md), [`graph-runtime`](formats-documentations/graph-runtime-object-format.md), [`task-node-model`](formats-documentations/task-node-model-object-format.md), [`task-node-runtime`](formats-documentations/task-node-runtime-object-format.md), [`ExellixRuntimeObject`](formats-documentations/exellix-runtime-object-format.md) |
+| **Ecosystem acceptance** (ai-tasks, studio, matrix parity) | [`.docs/ecosystem-acceptance-criteria.md`](.docs/ecosystem-acceptance-criteria.md) |
+| **Executable graph JSON** (top-level shape, task/finalizer nodes, edges, variables, `metadata.graphExecution`, canonical root enforcement, execution memory, local skills, Narrix / web scope (**forwarded `narrix` → `runTask`**), **graph JSON vs outbound `runTask`**) | **[`.docs/exellix-graph-engine-format.md`](.docs/exellix-graph-engine-format.md)** — start here for authors and schema tooling |
+| Task node bridge (shell, `metadata`, `executionPipeline`, `aiTaskProfile` → Narrix web merge, composer alignment) | [`.docs/task-node-exellix-graph-engine-and-graph-composer.md`](.docs/task-node-exellix-graph-engine-and-graph-composer.md) |
+| Layer 01 / 08 graph entry & response contracts | [`.docs/graph-io-visibility.md`](.docs/graph-io-visibility.md) |
+| Graph entry `dataFilters` v1 / public evaluator | [`.docs/data-filters-evaluation.md`](.docs/data-filters-evaluation.md) |
+| Task-node `conditions` + conditional `modelConfig.cases` (runx) | [`.docs/task-node-conditions-evaluation.md`](.docs/task-node-conditions-evaluation.md) |
+| Platform vs implementation (no domain operators in schema) | [`.docs/platform-generic-vs-implementation.md`](.docs/platform-generic-vs-implementation.md) |
+| Bundled graph examples & bundle README | [`graphs/README.md`](graphs/README.md) |
+
+The **`runTask`** wire contract (identity, canonical **`input`**, optional extra ai-tasks PRE/POST utility calls vs `executionPipeline`) is summarized later under **Run identity** and **`runTask` request contract**, and expanded in the graph format doc’s [**Graph JSON vs outbound `runTask`**](.docs/exellix-graph-engine-format.md#graph-json-vs-outbound-runtask) section. Graph-engine integrates with **`@exellix/ai-tasks`** at the semver range declared in **`package.json`** (currently **`^7.6.4`**); use your **lockfile** as the tested line. Variable buckets align with ai-tasks **≥ 7.6.2** (two-scope passthrough). There is **no** minimum graph-engine ↔ ai-tasks matrix published inside ai-tasks — follow dependency semver and upstream **`CHANGELOG.md`**. Graph-engine does **not** import or invoke the Xynthesis SDK directly.
+
+### Canonical executable graph document (strict boundary)
+
+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`, `aliasConfig`, runtime node overrides) belongs under the execution request’s **`runtime`** object and is rejected on the model.
+
+`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`.
+
+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.
+
+## Installation
+
+```bash
+npm install @exellix/graph-engine
+```
+
+**Upstream tasks SDK:** This package depends on **`@exellix/ai-tasks` ^7.4.0** (see **`package.json`**). Graph-engine emits **`RunTaskRequest`** shapes that match the v7 closed schema (mandatory **`executionStrategies`**, **`xynthesized`**, optional **`smartInput`**, no legacy root mirrors). Pin compatible versions in your app lockfile. Optional CI improvement: fail or warn when the resolved ai-tasks major/minor drifts outside an allowlist (not enforced in-repo today).
+
+### Execution matrix hosts (`@exellix/exellix-runtime`) — documentation only for the engine
+
+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.
+
+### Configuration (`.env`)
+
+- **Template:** [`.env.example`](.env.example) — copy to `.env` at the project root for local tests and scripts that load `dotenv`.
+- **Semantics:** [`.docs/environment-and-xmemory-databases.md`](.docs/environment-and-xmemory-databases.md) (must-have vs nice-to-have, Mongo / xmemory / Narrix / Activix).
+- **Resolvable path after install:** subpath export `@exellix/graph-engine/env.example` points at the same file (e.g. `require.resolve('@exellix/graph-engine/env.example')` in Node).
+
+### Package entrypoints
+
+- **`@exellix/graph-engine`** — Graph executor, types, loaders, integrations (platform).
+- **`@exellix/graph-engine/testkit`** — Harness helpers (`InMemoryGraphLoader`, `DepGraphEngineFactory`, `RealTasksClient`) and **sample** `registerNarrixGraphTasks` for repo graphs that still call `narrix/load-input`, `narrix/to-cni`, etc. This is not re-exported from the root entry.
+
+### Catalox and graph planning catalog IDs
+
+Skill templates and Catalox wiring for packaged runs live in **`@exellix/ai-tasks`** (and its upstream stack). This package only offers an optional **planning-descriptor** check when you already have a Catalox client:
+
+- **`validateGraphPlanningCatalogDescriptorsInCatalox(graph, catalox, ctx)`** — For every `catalogId` collected from `metadata.catalogBinding` / planning metadata (see [`getGraphCatalogs`](src/inspection/graphInspection.ts)), asserts `catalox.getCatalogDescriptor(ctx, catalogId)` is non-null.
+
+For Firebase Admin, `createCataloxFromEnv`, `listAiSkillsCatalogItems`, and related helpers, import from **`@exellix/ai-tasks`** or the graph-engine re-exports below instead of adding `@exellix/ai-skills` here.
+
+**`taskConfiguration.aiTasksOutputValidation`** (shape: `{ schema, mode?, validateWhenMissing? }`) is forwarded on `runTask` as `outputValidation` for server-side checks in `@exellix/ai-tasks`. The top-level node field **`outputValidation`** with **`rules`** remains a **local** post-check in `executeNode` only.
+
+### Task-node preflight (validation & analysis, no `runTask`)
+
+Graph-engine exposes the **`@exellix/ai-tasks` ≥ 7.6** preflight surface so studios and matrix hosts can validate a node **before** execution without a second dependency:
+
+| Export | Purpose |
+|--------|---------|
+| **`buildTaskNodeRunTaskRequest`** | Build the same outbound `RunTaskRequest` as `executeNode` (skips local skills and finalizers). |
+| **`validateTaskNodeRunTaskConfig`** | Static config checks (`agentId`, pipeline, `smartInput`, `llmCall`, …). |
+| **`validateTaskNodeRunTaskInvoke`** | Config + payload path resolution + optional template/smart-input render checks. |
+| **`analyzeTaskNodeRunTaskRequest`** | Catalox-backed skill request analysis (templates, gateway packet preview) plus optional config validation. |
+
+Lower-level helpers (`validateRunTaskConfig`, `validateRunTaskInvoke`, `analyzeRunTaskRequest`, `analyzeSkillRequest`, `formatSkillRequestAnalysisMarkdown`, Rendrix `listTokens` / `analyzeTemplateResolution`, …) are **re-exported** from the package root when you already have a `RunTaskRequest`.
+
+**Testing safety:** Default `npm test` uses **mocked** Catalox in catalog validation tests and does not open Firestore. Do **not** point `FIRESTORE_LIVE_TESTS` / integration flags at a **production** Firebase project; Catalox’s own docs recommend a dedicated test project for live integration runs.
+
+## Quick Start
+
+```typescript
+import { createExellixGraphRuntime } from '@exellix/graph-engine';
+
+const runtime = createExellixGraphRuntime({
+  graphLoader: myGraphLoader,
+  engineFactory: myEngineFactory, // GraphEngineFactory (e.g. DepGraphEngineFactory)
+  tasksClient: myTasksClient,     // TasksClientLike — responses may use `ok` or `success` (both accepted)
+});
+
+// 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' },
+    modelConfig: { xynthesisModel: 'xynth-default', skillModel: 'skill-default' },
+    aliasConfig: {
+      'xynth-default': 'openrouter/xynthesis-default',
+      'skill-default': 'openrouter/skill-default',
+    },
+  },
+});
+
+// Canonical business output + per-run ids:
+console.log(result.finalOutput, result.jobId, result.taskId);
+```
+
+## Public API
+
+### `runtime.executeGraph({ model, 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.
+
+```typescript
+import { createExellixGraphRuntime } from '@exellix/graph-engine';
+
+const runtime = createExellixGraphRuntime({
+  graphLoader,
+  engineFactory,
+  tasksClient,
+  modelConfig,            // optional explicit fallback: { xynthesisModel, skillModel }
+  eventEmitter,           // optional graph/node lifecycle events
+  playgroundReporter,     // optional
+  // …stepRetryPolicy, runLogMode, concurrency, runTaskDiagnostics, etc.
+});
+
+interface GraphExecutionRequest {
+  model: GraphModelObject;       // static graph definition
+  runtime: GraphRuntimeObject;   // dynamic run state
+}
+
+// 2x2 object split:
+// Graph model:       GraphModelObject
+// Graph runtime:     GraphRuntimeObject
+// Task-node model:   TaskNode
+// Task-node runtime: TaskNodeRuntimeObject at runtime.nodes[nodeId]
+
+interface GraphRuntimeObject {
+  jobId: string;                 // required: host correlation id
+  job: any;                      // host envelope: agentId, input, jobType, …
+  input?: Record<string, any>;   // active execution input
+  jobMemory?: any;
+  taskMemory?: any;
+  executionMemory?: any;
+  variables?: Record<string, any>;
+  modelConfig?: { xynthesisModel: string; skillModel: string };
+  aliasConfig?: Record<string, string>;
+  nodes?: Record<string, {
+    modelConfig?: { xynthesisModel: string; skillModel: string };
+    aliasConfig?: Record<string, string>;
+  }>;
+  mode?: 'forward' | 'backward' | 'hybrid';
+  goalNodeId?: string;           // required when mode === 'backward'
+  debugMode?: boolean;           // include per-node trace on result.debug
+  failFast?: boolean;            // default: false
+  // …llmCall, stepRetryPolicy, runLogMode, runtimeObjects, runTaskDiagnostics, etc.
+}
+```
+
+#### Return shape
+
+```typescript
+interface ExecuteGraphResult {
+  jobId: string;
+  taskId: string;
+  graphId: string;
+  status: 'completed' | 'failed';
+  finalOutput?: unknown;
+  finalizerNodeId?: string;
+  finalizerType?: string;
+  outputsByNodeId: Record<string, unknown>;
+  stepsResponses: Record<string, unknown>[];
+  engineSnapshot: unknown;
+  errors?: Array<{ nodeId?: string; error: unknown }>;
+  execution?: unknown;          // includes _trace.nodes
+  runLog?: RunLogEntry[];
+  runLogTruncated?: boolean;
+  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)
+  };
+}
+```
+
+Host HTTP handlers or workers should accept the same **`GraphExecutionRequest`** shape in the request body so payloads stay aligned with `runtime.executeGraph`.
+
+#### Memory-only playground reporter
+
+Use `createPlaygroundReporter()` when you want rich per-run debugging without filesystem output. The reporter is in-memory only: it does not accept an output directory, does not expose `writeReport`, and never writes request/response payloads to `playground/`, `reports/`, or any other path.
+
+```typescript
+import { createExellixGraphRuntime, createPlaygroundReporter } from '@exellix/graph-engine';
+
+const playgroundReporter = createPlaygroundReporter({ runId: 'local-debug-run' });
+const runtime = createExellixGraphRuntime({
+  graphLoader,
+  engineFactory,
+  tasksClient,
+  playgroundReporter,
+});
+
+await runtime.executeGraph({
+  model,
+  runtime: {
+    jobId: 'job-123',
+    job,
+    input,
+  },
+});
+
+// Inspect full node request/response payloads in memory.
+const artifacts = playgroundReporter.getArtifacts();
+const snapshot = playgroundReporter.getDebugSnapshot();
+const markdown = playgroundReporter.getMarkdown();
+```
+
+`getArtifacts()` returns entries such as `01-<nodeId>-request` and `01-<nodeId>-response` with the full payload attached as `payload`. Use `getDebugSnapshot()` when a UI, debugger panel, or test wants steps, artifacts, and rendered markdown as one object.
+
+**Removed in 5.0:** the legacy functional `executeGraph` from `runtime/executeGraph`, the `ExellixGraphClient` class, and their option/result types (`ExecuteGraphOptions`, `ExecuteGraphResponse`, `ExecuteGraphFinalizedResponse`, `ExecuteGraphDebugResponse`, `GraphExecutionResult`). Migrate to `createExellixGraphRuntime(...).executeGraph(...)` — the runtime now covers the same semantics and exposes the same diagnostics through `debugMode: true`. See [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md).
+
+### Run identity (host `jobId` and engine `taskId`)
+
+- **`jobId` (mandatory):** You must pass **`runtime.jobId: string`** on the `executeGraph` input. It must be non-empty after trim. If it is missing or blank, the call fails with **`ExellixGraphErrorCode.JOB_ID_REQUIRED`**. The runtime sets **`job.id`** and **`job.jobId`** to this value for the duration of the run (so templates, events, and memory see a consistent id even if **`job`** omitted **`id`** on input).
+
+- **`taskId` (mandatory on the wire, generated here):** At the start of each `executeGraph`, the engine allocates **`taskId = randomUUID()`**. The same value is attached to **every** `runTask` request in that run (including synthesize-finalizer paths) as **`taskId`**, and is returned on **`ExecuteGraphResult.taskId`**. This satisfies downstream expectations that each graph execution has a stable **per-run** task identity distinct from the host **`jobId`**.
+
+- **Results:** `ExecuteGraphResult` includes both **`jobId`** and **`taskId`** so callers and logs can correlate host scope vs engine run instance.
+
+- **Activix:** Graph-run integration persists **`jobId`**, **`taskId`**, and **`graphId`** on the record and in **`runContext`** (with **`sessionId`** still aligned to **`jobId`** for Activix v5). The in-memory correlation key for start → complete/fail is **`jobId:graphId:taskId`** so concurrent retries of the same host job against the same graph do not collide. Node activity integration keys rows by **`graphId:nodeId:taskId`** and includes **`taskId`** in **`runContext`** and top-level metadata.
+
+- **Helpers:** **`assertHostJobId`** and **`newGraphRunTaskId`** are exported from the package root for hosts/tests that build inputs outside `executeGraph`.
+
+**Standalone node debugging:** The runtime also exposes **`runtime.executeNode(...)`** for single-node test runs. Provide `node`, `job`, optional `graph` / `execution`, and (when continuing an existing run) `graphRunTaskId` from the parent `ExecuteGraphResult.taskId` so `runTask` and Activix stay aligned.
+
+### `runTask` request contract (`@exellix/ai-tasks` v7.x)
+
+Graph-engine builds a canonical `RunTaskRequest` for every outbound task call it owns: MAIN task-node invokes, engine PRE/POST utility invokes, and `synthesize` finalizer invokes. MAIN request assembly lives in [`src/runtime/buildAiTasksRunTaskRequest.ts`](src/runtime/buildAiTasksRunTaskRequest.ts); all paths follow **`RUNTASK_REQUEST.md`** in `@exellix/ai-tasks`. Types align with **`RunTaskRequest`** / **`ExellixGraphRunTaskRequest`** exported from this package.
+
+#### Identity and payload
+
+- **Required correlation:** `agentId`, **`jobTypeId`**, **`taskTypeId`** (in addition to `skillKey`, `input`). Defaults: `jobTypeId` ← `job.jobType` or `job.jobTypeId` or `exellix-graph-job`; `taskTypeId` ← `node.taskConfiguration.taskTypeId` or the node’s **`skillKey`**.
+- **Canonical task payload:** **`input`** object only (merged execution slice + **materialized** `node.inputs`). Root-level **`question`**, **`raw`**, **`jobInput`**, duplicate **`inputs`**, and legacy **`executionType`** are **not** sent on the request object.
+- **Graph telemetry:** `graphId`, **`nodeId`**, **`coreSkillId`** (node id), `masterSkillId`, `masterSkillActivityId`, `jobId`, `taskId`, optional `identity`.
+
+To build `RunTaskRequest` without fallback defaults, the execution request must provide both sides of the contract: `model.id`, `node.id`, `node.skillKey`, explicit `node.taskConfiguration.taskTypeId` (even when it matches `skillKey`), `node.taskConfiguration.executionStrategies` (use `[]` for plain MAIN), `runtime.jobId`, `runtime.job.agentId`, `runtime.job.jobTypeId` or `runtime.job.jobType`, active input/memory, and any model/LLM/diagnostic options needed by the task. Model selection uses the exact shape `{ xynthesisModel, skillModel }` from `runtime.nodes[nodeId].modelConfig`, `node.taskConfiguration.modelConfig`, `runtime.modelConfig`, or `model.modelConfig`; aliases are runtime-only and resolve through `runtime.aliasConfig` plus `runtime.nodes[nodeId].aliasConfig`. The resolved model config is forwarded to MAIN, engine PRE/POST utility calls, and `synthesize` finalizer calls. Graph-engine still derives correlation fields such as `graphId`, `nodeId`, `coreSkillId`, `masterSkillId`, `taskId`, and `masterSkillActivityId` from those authored values.
+
+#### Mandatory `executionStrategies` (breaking vs pre–v7 authoring)
+
+- Every MAIN (and engine PRE/POST utility) **`runTask`** includes **`executionStrategies`**: an array of **`ExecutionStrategyInvocation`** objects (semantics defined by **`@exellix/ai-tasks`** / `RUNTASK_REQUEST.md`).
+- **Plain MAIN** (no wrappers): graph-engine sends **`executionStrategies: []`**.
+- Optional task-node authoring: **`taskConfiguration.executionStrategies`** — when present and non-empty, it overrides the default **`[]`** for that node’s MAIN call.
+- Optional catalog metadata: **`taskConfiguration.executionStrategyCatalogItems`** is forwarded to `ai-tasks`; `ai-tasks` still validates the runtime invocation shape and consumes only safe catalog fields such as wrapper default function ids.
+- **Removed in 5.0:** `metadata.executionStrategyKey` typing and code branches. Configure planners/optimizers through **`executionStrategies`** per ai-tasks (see upstream docs / Catalox task-strategy catalogs).
+
+#### `xynthesized` and internal `execution.xynthesized`
+
+- **Outbound `runTask.xynthesized`:** `{ job, task }` snapshot from durable graph-engine memory — **`job`** = `execution.xynthesized.job`, **`task`** = `execution.xynthesized.taskByNode[nodeId]` (never another node’s task bucket).
+- **After a successful MAIN `runTask`**, graph-engine deep-merges **`response.xynthesizedPatch`** into **`execution.xynthesized`** (`patch.job` → `job`, `patch.task` → `taskByNode[nodeId]`).
+- On graph start, **`seedGraphRunExecutionState`** ensures **`execution.xynthesized`** exists with **`job`** and **`taskByNode`** objects.
+
+#### `smartInput`
+
+- Optional task-node field **`smartInput`** (`paths: string[]`, optional **`strict`**) is forwarded on **`RunTaskRequest.smartInput`** when set. Paths are validated against graph-engine allowlists (see catalog planning / `validateAiTasksNodeExtensions`).
+
+#### Optional `taskConfiguration` → `runTask` (strategy / Narrix)
+
+Forwarded from `taskConfiguration`: **`narrixMode`**, **`inputStrategyKey`**, **`narrixInput`**, and **`executionStrategyCatalogItems`**. If both **`taskConfiguration.narrix`** and **`taskConfiguration.narrixInput`** are set, set **`taskConfiguration.narrixMode`** to **`preprocessor`** or **`handler`** (see [format doc](.docs/exellix-graph-engine-format.md#metadataaitasks-runtime-strategy--narrix-wiring)).
+
+#### Input bindings before `runTask`
+
+Values in **`node.inputsConfig`** (or deprecated **`node.inputs`**) shaped as **`{ type: 'executionMemoryPath', path }`** (optional **`optional: true`**) or **`{ $path: '…' }`** are resolved against the live **`execution`** object **before** building **`runTask.input`**, so chained graphs see concrete values (e.g. **`graphOutputs.*`**) instead of binding objects.
+
+#### Graph-run execution seeding
+
+When **`executeGraph`** / **`createExellixGraphRuntime().executeGraph`** starts, graph-engine seeds **`runtime.executionMemory.xynthesized`** and mirrors **`runtime.input`** to **`runtime.executionMemory.input`** (flat fields on the object; no `input.raw` wrapper).
+
+**Where hosts put the record:** [`.docs/graph-execution-record-input.md`](.docs/graph-execution-record-input.md) — peer contract (`runtime.input` only, flat paths, matrix vs BFF).
+
+Model knowledge references are resolved inside graph-engine without changing the ai-tasks wire contract. The merge happens when graph-engine builds the outbound **`RunTaskRequest`**: **`model.jobKnowledge`** is applied to the request copy at **`jobMemory.knowledge`**, and **`node.taskKnowledge`** is applied to that task node's request copy at **`taskMemory.knowledge`**. The shared `runtime.jobMemory` / `runtime.taskMemory` objects are not rewritten just to attach model knowledge.
+
+Scope matters: **`jobKnowledge` is graph-run scoped** and is available to every task request through `jobMemory.knowledge`. **`taskKnowledge` is node/task scoped** and must be declared on the task node; root `model.taskKnowledge` is not part of the graph model contract.
+
+#### PRE `inputSynthesis` (authoring → pipeline)
+
+When **`taskConfiguration.aiTaskProfile.inputSynthesis`** is enabled, graph-engine may synthesize or merge a PRE **`synthesized-context`** step (still **one** outbound MAIN `runTask`). Conflicts with an explicit **`node.executionPipeline`** that already defines PRE synthesis are rejected at runtime / validation with **`INPUT_SYNTHESIS_PIPELINE_CONFLICT`**. Details: [.docs/exellix-graph-engine-format.md](.docs/exellix-graph-engine-format.md).
+
+#### Three layers (do not confuse)
+
+1. **Engine PRE/POST strategy utilities (ai-tasks only):** `taskConfiguration.aiTaskProfile.preStrategyKey` / `postStrategyKey` → extra **`runTask`** calls via **`@exellix/ai-tasks`** before/after MAIN; outputs stored at **`execution.xynthesis.pre`** / **`execution.xynthesis.post`** (historical slot names).
+2. **`executionPipeline` inside ai-tasks:** e.g. PRE **`synthesized-context`** + MAIN direct — still **one** outbound MAIN `runTask` handled inside `@exellix/ai-tasks`.
+3. **Narrix web scope inside ai-tasks:** when **`taskConfiguration.aiTaskProfile.webScoping.enabled`** is true, graph-engine forwards a `narrix` payload with `enableWebScope` / `webScopeQuestions`. The actual web fetch + skip rules run **inside `@exellix/ai-tasks`** (`@exellix/narrix-web-scoper`); graph-engine has **no local web phase** in 5.x.
+
+`synthesize` finalizers are a fourth outbound task-call shape: the finalizer is still a graph model node, but its terminal utility `runTask` uses the same run identity, diagnostics, `llmCall`, and resolved model config as the rest of the graph run.
+
+## Finalizer nodes & Final Response
+
+Executable graphs must include **exactly one** terminal **finalizer node** (`type: "finalizer"`) with **no outgoing edges**.
+
+Required finalizer reads must resolve from the selected memory lane. A non-optional `executionMemoryPath` read must either be seeded by `runtime.executionMemory` before the run starts or be written by a reachable upstream task node through `executionMapping.path`. A non-optional `outputsMemoryPath` read must either be seeded by `runtime.outputsMemory` or be written by a reachable upstream task node through `outputMapping.path`. If the value may be absent because a branch is conditional, mark that finalizer input, section, or item `optional: true`.
+
+The finalizer is a terminal computation or fan-in barrier. It does not own the returned API response. The returned `ExecuteGraphResult.finalOutput` is always resolved from root `model.response` after node `executionMapping`/`outputMapping` writes and finalizer/barrier execution complete:
+
+```ts
+type GraphResponseDefinition = {
+  missing?: 'omit' | 'null';
+  shape: unknown;
+};
+```
+
+Supported selectors are `outputsMemoryPath`, `executionMemoryPath`, `executionPath`, `nodeMetadata`, `nodeInputsConfig`, `literal`, and `firstPresent`. Legacy `nodeInputs` is still accepted. Missing selector values are omitted by default; `missing: "null"` returns `null` for missing mapped fields.
+
+Example:
+
+```json
+{
+  "response": {
+    "missing": "omit",
+    "shape": {
+      "answer": {
+        "type": "executionMemoryPath",
+        "path": "answers.q1.shortAnswer"
+      }
+    }
+  }
+}
+```
+
+`metadata.graphExecution.outputMode`, finalizer output, and legacy `metadata.graphResponse.responseMapping` are not final-output selectors for new graphs. Migrate legacy response mappings by copying `missing` and `shape` to root `response` and dropping `version`, `target`, `primaryResponsePaths`, `debugResponsePaths`, `notableExecutionPaths`, and `mappingPreset`.
+
+`coreObjective` is resolved once from graph/run context, not from each node response. Supported `sourcePath` roots are `input.*`, `execution.*`, `variables.*` / `jobVariables.*`, `taskVariables.*`, `jobMemory.*`, `taskMemory.*`, and `job.*`.
+
+The selected canonical business output is exposed as:
+
+- `ExecuteGraphResult.finalOutput` (the only API in 5.x).
+
+### Deterministic finalizers (runtime-owned)
+
+Implemented deterministic finalizer types:
+
+- `aggregate`
+- `bundle`
+- `select`
+
+#### `aggregate` — `strategy: "object-map"`
+
+Build an object by mapping named inputs (from `executionMemoryPath` or literals) into output keys.
+
+#### `aggregate` — `strategy: "report-schema"` (multi-section report from execution 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).
+
+- **`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.
+
+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).
+
+#### `aggregate` — `strategy: "question-driven"` (generic Q→A formatting)
+
+For “question-driven” graphs, `question-driven` formats the final output by pairing:
+
+- **question text** from the referenced node definition (default path: `inputs.question`)
+- **answer** from `executionMemory` at the referenced node’s `outputMapping.path` (or an explicit `answerPath`)
+
+Example:
+
+```json
+{
+  "id": "finalize",
+  "type": "finalizer",
+  "finalizerType": "aggregate",
+  "inputs": {},
+  "config": {
+    "strategy": "question-driven",
+    "contractVersion": "1",
+    "items": {
+      "exploitability": { "nodeId": "q2-exploitability" },
+      "exposure": { "nodeId": "q5-exposure" },
+      "posture": { "nodeId": "q6-posture" }
+    }
+  }
+}
+```
+
+Output shape (per item key):
+
+```json
+{
+  "exploitability": { "question": "...", "answer": { /* whatever the node mapped */ } }
+}
+```
+
+## Activix integration (graph run record)
+
+When using `createActivixGraphRunIntegration()` / `createActivixExellixIntegration()`:
+
+- **Canonical response** is stored at `outer.output.response` and is **only** the graph’s `finalOutput`.
+- **Detailed execution data** (nodes, execution memory, errors, etc.) is stored under `outer.output.data`.
+
+This keeps the “business output” clean while preserving full diagnostics.
+
+### Graph start — bounded input summaries (Activix)
+
+On `graph:start`, the graph-run integration **does not** persist raw `data.input` / `data.request` (no shallow copy of `variables`, full `GraphExecutionRequest`, or opaque host objects). Activix receives **JSON-serializable summaries** under `outer.input`:
+
+- `inputSummary` — bounded shape for the event’s `input` (e.g. `variables` / memory handles as key counts, shallow primitive previews, nested samples).
+- `requestSummary` — same for the merged `request` object emitted with the start event.
+
+Correlation fields (`jobId`, `graphId`, `agentId`, `jobType`, `inputVariableKeys`, `runContext`, etc.) are unchanged.
+
+**Recommended for `job` / `GraphExecutionRequest` / event `data` (Activix-safe):** JSON-like primitives, plain objects/arrays, string ids, `agentId`, `jobType`, and small metadata you are willing to see reflected in summaries.
+
+**Not suitable to rely on for Activix persistence at graph start:** functions, class instances, streams, Buffers, live clients (HTTP/DB), circular graphs, or very large nested payloads — they are summarized or typed (e.g. `shape: "function"`, `shape: "instance"`) and never passed through to `startRecord` as raw references. For large memory, use `includeMemorySnapshots: true` only when you explicitly accept storing `outer.memory.start` / `end`; that remains opt-in and separate from `outer.input`.
+
+### `runtime.executeNode(input)`
+
+Execute a single node — useful for tests and for stepping through a node in the context of an existing graph run. Pass `node`, `job`, optional `graph` / `execution`, and (when continuing a parent run) `graphRunTaskId` from the parent `ExecuteGraphResult.taskId` so `runTask` correlation, Activix records, and `runLog` lines stay aligned.
+
+### `loadGraph(graphId)`
+
+Load a graph through the injected loader and validate against the canonical document schema before returning.
+
+## Graph Entry Inputs
+
+Graph JSON can declare the semantic type of input it is designed to work with under `metadata.graphEntry.inputs`. This is part of the graph object itself and is intended for authors, catalogs, dashboards, and future validators; the runtime does not validate or coerce it today.
+
+```json
+{
+  "id": "network-vuln-triage.v1",
+  "metadata": {
+    "graphEntry": {
+      "summary": "Triage one vulnerability record with an optional caller query.",
+      "inputs": [
+        { "kind": "record", "path": "input", "required": true },
+        { "kind": "query", "path": "input.query", "required": false }
+      ],
+      "requiredExecutionPaths": ["input.subnetId"]
+    }
+  },
+  "nodes": []
+}
+```
+
+Standard `kind` values are `record`, `query`, `user-input`, `content`, `metadata`, and `execution`. Use multiple entries for combinations, for example a graph that needs both a raw record and a user question. Paths are relative to the merged `execution` object, so `input` maps to `GraphRuntimeObject.executionMemory.input` after `runtime.input` is mirrored.
+
+Use `kind: "execution"` when the graph is designed to consume a prior graph execution. The design contract names the source `graphId` and an optional `metadataFilter` for fields such as status values:
+
+```json
+{
+  "kind": "execution",
+  "graphId": "network-vuln-group-triage.v1",
+  "metadataFilter": { "status": "completed" },
+  "path": "input.upstreamExecution",
+  "required": true
+}
+```
+
+The runtime does not perform that lookup today; host tooling resolves it and passes the selected execution under the declared path.
+
+## Node Inputs
+
+All dynamic per-node values — including the question text sent to the template — must be defined under `node.inputs`. This is the single canonical location.
+
+```json
+{
+  "id": "q1-reachability",
+  "skillKey": "professional-answer",
+  "inputs": {
+    "question": "Is this asset reachable from outside the perimeter?",
+    "record": { "type": "executionMemoryPath", "path": "input" }
+  }
+}
+```
+
+**Execution-memory bindings (chaining):** Objects **`{ "type": "executionMemoryPath", "path": "graphOutputs.upstream.payload" }`** (and **`{ "$path": "executionMemory.…" }`** / **`input.…`** forms) are **resolved against the live `execution` object** before **`runTask`**. The outbound request carries **scalar/object values** under **`input`**, not the binding shape. Use **`optional: true`** on **`executionMemoryPath`** bindings if the path may be missing.
+
+**Optional `smartInput`:** Top-level on the task node (sibling to **`inputsConfig`**): **`{ "paths": ["input", "graphOutputs.prev"], "strict": true }`** — forwarded on **`RunTaskRequest.smartInput`**; paths must satisfy graph-engine allowlists.
+
+**Rules:**
+
+- `node.inputs.question` — the question text sent to the skill template as `{{question}}`. Always set it here.
+- Any other per-node dynamic value (e.g. `record`, `context`) also belongs in `inputs`.
+- Path references in `outputMapping` use `node.inputs.question` (e.g. `"question": "node.inputs.question"`).
+- `node.inputs` is the only place the runtime reads `question` from. There is no fallback to `node.question` or `node.data.question`.
+
+**What does NOT belong in `inputs`:**
+
+- `skillKey` — top-level node field.
+- `taskConfiguration.narrix` — NARRIX engine config (`datasetId`, `questionId`, `layer`, etc.). These are routing/filter fields consumed by the NARRIX pre-processor, not by the template.
+- `taskConfiguration.aiTaskProfile.webScoping` — opt-in web context. Graph-engine forwards web intent on the outbound `narrix` payload; actual web fetch and skip rules run inside `@exellix/ai-tasks`. See [.docs/exellix-graph-engine-format.md — Web scoping behavior](.docs/exellix-graph-engine-format.md#web-scoping-behavior).
+- Template variables — use `node.variables` + paths `taskVariables.*`, or `model.variables` + `jobVariables.*` (see [Variables (two buckets)](#variables-two-buckets--job--task)). Use `node.taskVariable` for prompts, not `inputs`.
+
+> `taskConfiguration.narrix.questionId` (e.g. `"q1"`, `"q6"`) is a NARRIX internal routing key that tells the pre-processor which framework question slot this node fills. It has nothing to do with `inputs.question` (the human-readable question text). Do not confuse them.
+
+**First-class: question and questionId.** For NARRIX nodes you can set `inputs.question`, or `taskConfiguration.narrix.questionId`, or both. Once NARRIX provides a question ↔ questionId resolver, the missing one can be filled automatically. See [.docs/question-questionId-first-class-experience.md](.docs/question-questionId-first-class-experience.md).
+
+## Skill Key Resolution
+
+Canonical graph models must specify `node.skillKey` for remote task nodes. Legacy aliases `node.data.skillKey` and `node.metadata.skillKey` are rejected by canonical validation. Optional fallback to `tasks/${node.id}` exists only when `allowFallbackToNodeId: true` is explicitly enabled (default: **disabled**).
+
+If `skillKey` is missing, `exellix-graph-engine` throws `NODE_SKILLKEY_MISSING` error **before** execution begins.
+
+### Configuration
+
+```typescript
+skillKeyResolution: {
+  allowFallbackToNodeId?: boolean; // default: false (strict mode)
+  fallbackPrefix?: string;         // default: "tasks/"
+  aliases?: Record<string, string>; // optional explicit remaps
+}
+```
+
+## Variables (two buckets — job + task)
+
+Template variables are **not** merged into one bag. Graph-engine mirrors two scopes on `executionMemory`:
+
+| Scope | Runtime inputs | Execution mirror | Memory paths |
+|-------|----------------|------------------|--------------|
+| **Job / graph** (whole run) | `model.variables`, `runtime.variables`, `runtime.jobVariables`, legacy `job.jobVariables` | `execution.jobVariables` | `jobVariables.*` (legacy alias `variables.*`) |
+| **Task / node** (current node) | `node.variables`, `runtime.taskVariables` | `execution.taskVariables` | `taskVariables.*` |
+
+Outbound `runTask` sends **`variables`** (ai-tasks field name) = job bucket only; node scope stays on **`executionMemory.taskVariables`**. Requires **graph-engine ≥ 5.13** and **@exellix/ai-tasks ≥ 7.6.2** (passthrough, no flattening).
+
+> **Important**: graph-engine does not define skill templates; it forwards buckets as-is. See [`formats-documentations/graph-runtime-object-format.md`](formats-documentations/graph-runtime-object-format.md).
+
+### Upstream template rendering (`ai-gateway` / `athenix-parser`)
+
+The stack that eventually renders skill prompts pulls in **`@athenices/ai-gateway`** (transitively via `@exellix/ai-tasks` / `@exellix/ai-skills`), which depends on **`@athenices/athenix-parser` v4+**. That parser implements the **v4 template protocol**: required `{{path}}` values throw **`TemplateResolutionError`** when missing; optional tokens use **`{{path |}}`** or **`{{path | fallback text}}`**; **`subPathSearch`** is opt-in for alternate root lookup. See the parser’s README under `node_modules/@athenices/ai-gateway/node_modules/@athenices/athenix-parser/` when debugging template failures.
+
+**Web research in prompts:** when this repo runs **local** question-driven web scope in `executeNode`, it still injects a flat **`webContextMarkdown`** string into `jobContext` so templates can use `{{#if webContextMarkdown}}` with a **bounded** markdown block. That remains the default pattern here even though deep `execution.*` paths are now supported upstream if you pass full context and configure the gateway/parser accordingly.
+
+Web scoping now runs inside `@exellix/ai-tasks`, not as a local graph-engine web-scoper phase. Author web intent under **`taskConfiguration.aiTaskProfile.webScoping`**; downstream ai-tasks controls source snippets, markdown, skip rules, and any enrichment from `execution.input`.
+
+## Memory Wiring
+
+Memory is passed through consistently:
+
+- `jobMemory = runtime.jobMemory`; model knowledge is added only to the outbound `RunTaskRequest.jobMemory.knowledge` copy.
+- `taskMemory = runtime.taskMemory`; node task knowledge is added only to that node's outbound `RunTaskRequest.taskMemory.knowledge` copy.
+
+Optional per-node memory overrides:
+- `node.memory?.taskMemory`
+- `node.memory?.jobMemory` (rare, but allowed)
+- `node.jobContextMapping` (see below)
+
+## Input Grouping (`inputs`)
+
+Nodes can group their dynamic inputs under an `inputs` object for better structure and to avoid conflicts with system fields.
+
+```json
+{
+  "id": "node-1",
+  "type": "task",
+  "skillKey": "my-skill",
+  "inputs": {
+    "question": "What is the capital of France?",
+    "detailed": true
+  }
+}
+```
+
+## Job Context Mapping (`jobContextMapping`)
+
+`jobContextMapping` allows a node to pull specific data from `jobMemory` into its local execution context (`jobContext`).
+
+```json
+"jobContextMapping": {
+  "map": {
+    "customer": "jobMemory.profiles.current",
+    "history": "jobMemory.activityLog"
+  }
+}
+```
+
+The runtime will resolve these paths from `jobMemory` and provide a `jobContext` object to the underlying task.
+
+Path expressions in `map` support:
+- **Dot paths**: `jobMemory.profiles.current`, `executionMemory.graphOutputs.vulnInstances.records`
+- **Array wildcard** `[*]`: e.g. `executionMemory.graphOutputs.vulnInstances.records[*]` — selects all array elements
+- **Object values** `{*}`: e.g. `recordsById{*}` — selects all values of an object (deterministic key order)
+
+Sources can be `jobMemory.*` or `executionMemory.*` (current execution state from previous nodes).
+
+## Execution Object & Trace
+
+### Execution Object
+
+The execution object is a shared state container that persists across all nodes in a graph execution. It stores:
+- **Output mappings**: Data written by nodes via `outputMapping`
+- **`xynthesized` memory**: **`execution.xynthesized.job`** (run-wide) and **`execution.xynthesized.taskByNode[nodeId]`** (per node). Outbound **`runTask.xynthesized`** exposes the current node’s slice; **`xynthesizedPatch`** on responses is merged after successful MAIN calls.
+- **Execution trace**: Per-node execution metadata (see below)
+- **Custom state**: Any application-specific data
+
+The execution object is passed to each node as `executionMemory` in the task request and updated through `outputMapping` configurations. Edge predicates may also read **`input.*`** and **`xynthesized.*`** roots via the same evaluation context (see [`src/runtime/predicates.ts`](src/runtime/predicates.ts)).
+
+### Execution Trace (FR-6)
+
+Each graph run records a **structured trace** per node in the execution object:
+
+- **Location**: `execution._trace.nodes[nodeId]`
+- **Shape**: `{ startedAt, endedAt, skillKey, ok, durationMs, activityId?, summary?, error? }`
+
+**Trace fields:**
+- `startedAt`: Unix timestamp (ms) when node execution started
+- `endedAt`: Unix timestamp (ms) when node execution ended
+- `skillKey`: The resolved skill key for this node
+- `ok`: `true` if successful, `false` if failed
+- `durationMs`: Execution duration in milliseconds
+- `activityId`: Optional activity/task identifier from ai-tasks
+- `summary`: Optional metadata from task response (on success)
+- `error`: Error details with `message`, optional `code`, and optional `stack` (on failure)
+
+Trace is written by the runtime for every node (both `executeGraph` and `createExellixGraphRuntime` flows), regardless of success or failure.
+
+### Execution Object in Events (FR-3)
+
+All node execution events include the execution object merged into `jobMemory`:
+
+- **Node Start Event**: `input.jobMemory.execution` contains the current execution state
+- **Node Complete Event**: `memoryAfter.jobMemory.execution` contains the updated execution state (after outputMapping)
+- **Node Fail Event**: `memoryAfter.jobMemory.execution` contains the execution state at the time of failure
+
+This ensures consistent tracking and allows activity tracking systems to access execution data for monitoring and debugging.
+
+### ai-tasks metadata for trace
+
+For rich structured trace, local tasks (ai-tasks) should return metadata in the response so the graph can store it in `execution._trace.nodes[nodeId].summary` and use it for `durationMs` / `activityId`:
+
+- **`response.parsed.meta.durationMs`** — task duration in milliseconds (otherwise the runtime uses `endedAt - startedAt`)
+- **`response.parsed.meta.localTaskId`** or **`response.parsed.meta.activityId`** — optional activity/handler identifier
+
+MAIN **`runTask`** traces may also include bounded summaries of **`smartInput.paths`** and keys touched by **`xynthesizedPatch`** (not full synthesized payloads).
+
+Any other fields in `response.parsed.meta` are stored in `summary`.
+
+## Contextual Knowledge Scope (`scope`)
+
+Nodes can define complex filtering rules to scope lists from memory into the node's context. This is useful for building localized knowledge for a task (e.g., "all assets in the same zone as the target").
+
+```json
+{
+  "scope": {
+    "contextualKnowledge": [
+      {
+        "list": "zonesEnriched",
+        "select": ["zone", "semantics.trust_level"],
+        "filter": {
+          "where": [
+            { "path": "virtual_router", "eq": "{{asset.virtual_router}}" },
+            { "path": "containsTargetIp", "eq": true }
+          ],
+          "limit": 10
+        }
+      }
+    ]
+  }
+}
+```
+
+**Features:**
+- **Dynamic Filtering**: Use placeholders like `{{asset.zone}}` to reference variables or memory.
+- **Operators**: `eq`, `eqAny` only (precompute domain-specific fields in the host when needed).
+- **Selection**: Pick specific fields using `select` to minimize context size.
+- **Integration**: The result is merged into `jobContext` alongside `jobContextMapping`.
+
+## Backward Planning
+
+When `mode === "backward"`:
+
+- `goalNodeId` is **required**
+- `goalNodeId` must exist in the graph
+
+If missing/invalid, `exellix-graph-engine` throws `BACKWARD_GOAL_REQUIRED` error **before** execution begins.
+
+## Error Handling
+
+All errors are structured **`ExellixGraphError`** instances with:
+
+- `code`: **`ExellixGraphErrorCode`** (e.g., `NODE_SKILLKEY_MISSING`, `TASK_NOT_FOUND`)
+- `message`: Human-readable message
+- `context`: Additional context (jobId, graphId, nodeId, etc.)
+
+### Task Not Found
+
+When `ai-tasks.runTask()` returns "not found":
+
+- Node is marked as `failed` with `reason: "TASK_NOT_FOUND"`
+- Includes `skillKey` and ai-tasks diagnostics payload **as-is**
+- Commits failure to graphenix (so history contains it)
+- Then:
+  - If `failFast=true` → abort graph
+  - Else continue if graph allows it
+
+## Understanding Task Content
+
+To avoid confusion across the stack:
+
+- **Node `skillKey`** identifies the **task** (ai-tasks layer)
+- The task will reference or embed a **skill** (ai-skills layer)
+- If content is missing, it's either:
+  - Missing `node.skillKey` → `exellix-graph-engine` error (`NODE_SKILLKEY_MISSING`)
+  - Task missing → `ai-tasks` not found (`TASK_NOT_FOUND`)
+  - Skill missing inside task → `ai-tasks`/`ai-skills` error
+
+`exellix-graph-engine` surfaces these errors; it doesn't decide what tasks/skills exist.
+
+## Types
+
+```typescript
+import type {
+  Graph,
+  GraphModelObject,
+  GraphAiModelConfig,
+  GraphModelAliasConfig,
+  GraphNode,
+  TaskNode,
+  TaskNodeRuntimeObject,
+  TaskNodeTaskConfiguration,
+  Job,
+  ExecuteGraphInput,
+  GraphExecutionRequest,
+  GraphRuntimeObject,
+  ExecuteGraphResult,
+  ExellixGraphRunTaskRequest,
+  ExellixGraphRunTaskResponse,
+  BuildAiTasksRunTaskRequestArgs,
+  ExecutionStepOption,
+  SmartInputConfig,
+  ExecutionStrategyInvocation,
+  XynthesizedMemory,
+} from '@exellix/graph-engine';
+```
+
+**`RunTask` wire:** `ExellixGraphRunTaskRequest` / `ExellixGraphRunTaskResponse` are aliases of `@exellix/ai-tasks` **`RunTaskRequest`** / **`RunTaskResponse`**. **`SmartInputConfig`**, **`ExecutionStrategyInvocation`**, **`XynthesizedMemory`**, and related strategy / xynthesized types are **re-exported from `@exellix/ai-tasks`** via [`src/types/aiTasksDerivedTypes.ts`](src/types/aiTasksDerivedTypes.ts) so you can import stable names from **`@exellix/graph-engine`** without duplicating `NonNullable<RunTaskRequest[…]>` aliases.
+
+## Error Codes
+
+Structured errors are **`ExellixGraphError`** with **`ExellixGraphErrorCode`**:
+
+```typescript
+import { ExellixGraphErrorCode } from '@exellix/graph-engine';
+
+// Examples: JOB_ID_REQUIRED, NODE_SKILLKEY_MISSING, BACKWARD_GOAL_REQUIRED,
+// GRAPH_LOAD_FAILED, GRAPH_EXECUTION_FAILED, NODE_EXECUTION_FAILED,
+// TASK_NOT_FOUND, INVALID_GRAPH, INVALID_NODE, NON_CANONICAL_GRAPH_DOCUMENT,
+// NON_CANONICAL_TASK_NODE
+```
+
+Validation issues for **`smartInput`** / **`inputSynthesis`** during catalog planning use string codes such as **`SMART_INPUT_PATHS_INVALID`**, **`INPUT_SYNTHESIS_PIPELINE_CONFLICT`**, **`INPUT_SYNTHESIS_DESTINATION_INVALID`** (see [`src/inspection/validateAiTasksNodeExtensions.ts`](src/inspection/validateAiTasksNodeExtensions.ts)).
+
+## Repository Structure
+
+```
+src/
+  index.ts
+  runtime/ExellixGraphRuntime.ts
+  runtime/buildAiTasksRunTaskRequest.ts
+  runtime/aiTasksStrategyPhases.ts
+  runtime/graphRunExecutionSeed.ts
+  runtime/resolveExecutionPipelineForTaskNode.ts
+  runtime/localSkills/
+  runtime/variables.ts
+  runtime/memory.ts
+  runtime/events.ts
+  loaders/FileGraphLoader.ts
+  types/refs.ts
+  types/options.ts
+  types/aiTasksDerivedTypes.ts
+  types/results.ts
+  errors/ExellixGraphError.ts
+  errors/exellixGraphErrorCodes.ts
+```
+
+## Testing
+
+- **`npm test`** — Generic SDK checks only: deterministic finalizers, graph inspection, contract inspection (`src/tests/run-tests.ts`). Does not run bundled graph JSON from `graphs/`.
+- **`npm run test:graphs`** — Question-breakdown sample graph (real `ai-tasks`).
+- **`npm run test:subnet`** — `narrix-subnet-egress-triage.v1` with sample data from `graphs/tests/examples/`.
+- **Other graph runners** (`dod`, `run:vuln-group:trace`, `test:web-scope-e2e`, …) live under **`graphs/tests/`**; see [graphs/tests/README.md](graphs/tests/README.md).
+
+Fixtures and DOD outputs for those graphs are under **`graphs/tests/`** (`examples/`, `realdata/`, `outputs/`). The top-level **`tests/`** folder only documents the move (see [tests/README.md](tests/README.md)).
+
+## Example graphs (`graphs/`)
+
+**Graph JSON shape:** [.docs/exellix-graph-engine-format.md](.docs/exellix-graph-engine-format.md).
+
+Bundled **graph definitions** (JSON DAGs) live in [`graphs/`](graphs/). **[graphs/README.md](graphs/README.md)** is the **bundle catalog** (graph IDs, product-specific notes, execution call grid, appendix for bundled v2 graphs, and **[Platform contract: respected target](graphs/README.md#platform-contract-respected-target-for-graphs-and-integrations)** for integration baseline and feature requests).
+
+To execute a graph, supply a `graphLoader` that resolves `graphId` to JSON, build a `job` with the input shape your graph expects (often `execution.input` with `raw` and optional `metadata`), and call `executeGraph`. Further integration notes may live under [.docs/](.docs/).
+
+**`taskConfiguration.aiTasksOutputValidation`** on task nodes is forwarded as **`outputValidation`** on the `runTask` request (**`@exellix/ai-tasks` v7+**). Root **`outputConstraints`** is not part of the closed schema.
+
+## Integration with Other Packages
+
+See `.reports/` directory for request documents:
+
+- `graphenix-request-node-contract.md` - Graph node contract
+- `ai-tasks-request-not-found-contract.md` - Task not found handling
+- `ai-tasks-request-variable-channels.md` - Variable flow documentation
+- `exellix-helpers-requests.md` - Helper utilities
+
+## License
+
+ISC