@exellix/ai-tasks 9.1.0 → 10.0.0

package/documenations/upstream-feature-requests/graph-engine-runtask-contract-alignment-investigation.md

@@ -0,0 +1,370 @@
+# Investigation: graph-engine `RunTaskRequest` alignment (taskVariables + flat `executionMemory.input`)
+
+**Status:** Draft v2 — **awaiting approval** (revised after graph-engine 8.1.x source audit)  
+**Date:** 2026-06-12 (v2 same day)  
+**Owners:** `@exellix/graph-engine` (implementation), `@exellix/ai-tasks` (contract + fixtures)  
+**Consumers:** `@exellix/ai-skills` (`professional-answer`), `@exellix/ai-tasks` `runTask()`  
+**graph-engine source:** `c:\prometheus\exellix\graph-engine` (audited separately from this mono-repo)  
+**Related:** [RUNTASK_REQUEST.md](../../RUNTASK_REQUEST.md), [record-and-template-variables.md](../record-and-template-variables.md), [graph-engine-task-pre-synthesis-compile.md](../../../archived/ai-tasks/reports/graph-engine-task-pre-synthesis-compile.md)
+
+---
+
+## 1. Purpose
+
+Subnet-style graphs (`graph-qcrbz6t`, web-scope variants) need a **shared target contract** between graph-engine, ai-tasks, and ai-skills — especially `taskVariables`, flat `executionMemory.input`, and PRE synthesis on the **nodePlan-only** wire (graph-engine **≥ 8.1**, ai-tasks **9.x**).
+
+This report:
+
+1. States the **normative target contract** (what we want on the wire).
+2. Records **graph-engine 8.1.x ground truth** (what is already implemented vs still missing).
+3. Proposes **remaining graph-engine changes** ranked P0–P2.
+4. Defines **acceptance criteria** for graph-engine CI (full compiled plan path, not preflight-only).
+
+**v1 correction:** The first draft read like a greenfield spec and recommended **`taskConfiguration` forward (P0-1)**. That is **wrong** for graph-engine **≥ 8.1** / ai-tasks **9** when `nodePlan` is present — PRE must be compiled into **`nodePlan.executionUnits`**, and `taskConfiguration` is **forbidden** on the outbound wire.
+
+**No graph-engine code should change until this revised report is approved.**
+
+---
+
+## 2. Scope
+
+| In scope | Out of scope |
+|----------|----------------|
+| Compile path: graph node → `RunTaskRequest` | ai-skills FlexMD frame parsing |
+| `executionMemory` seeding and per-node snapshots | FUNCX catalog hosting |
+| `taskVariables` / `jobVariables` buckets | graph-engine failure-phase attribution (separate FR) |
+| Flat `executionMemory.input` (MAIN record bucket) | Studio UX (P2 unless blocking) |
+| `professional-answer` wire shape | Changing `executionMapping` apply location (stays in graph-engine) |
+| PRE via **`nodePlan.executionUnits`** (not `taskConfiguration` on wire) | ai-tasks re-introducing legacy folding |
+
+---
+
+## 3. Evidence
+
+| Artifact | Role |
+|----------|------|
+| [`test/fixtures/run-task/graph-engine-pre-synthesis.json`](../../test/fixtures/run-task/graph-engine-pre-synthesis.json) | **Target wire shape** (partially updated in ai-tasks mono-repo; still missing `nodePlan`, still includes transitional `taskConfiguration` — see §3.1) |
+| [`test/fixtures/run-task/graph-engine-pre-synthesis-web-scope.json`](../../test/fixtures/run-task/graph-engine-pre-synthesis-web-scope.json) | Target + NARRIX/web-scope (ai-tasks mono-repo) |
+| [`test/fixtures/graphs/graph-qcrbz6t-pre-synthesis.json`](../../test/fixtures/graphs/graph-qcrbz6t-pre-synthesis.json) | Fixed graph JSON (authoring shape) |
+| [`test/fixtures/graphs/graph-qcrbz6t-format-2.1.0.json`](../../test/fixtures/graphs/graph-qcrbz6t-format-2.1.0.json) | Graphenix `formatVersion` 2.1.0 (studio) |
+| graph-engine repo tests | `executeGraph` + `compileExellixExecutablePlan` path — **authoritative** for what graph-engine actually emits today |
+| [`RUNTASK_REQUEST.md`](../../RUNTASK_REQUEST.md) | Normative field inventory (has known tension: §`taskConfiguration` lift vs graphenix v2.1 forbidden list) |
+
+### 3.1 Fixture honesty (ai-tasks mono-repo)
+
+The ai-tasks golden [`graph-engine-pre-synthesis.json`](../../test/fixtures/run-task/graph-engine-pre-synthesis.json) was updated toward the target (`taskVariables.question`, top-level `outputContract`, flat `executionMemory.input`) but is **not yet a complete graph-engine 8.1 wire exemplar**:
+
+| Field | Target | Current fixture |
+|-------|--------|-----------------|
+| `executionMemory.taskVariables.question` | Required | **Present** |
+| `outputContract` top-level | Required | **Present** |
+| `input.question` / `input.outputContract` | Absent | **Absent** |
+| `nodePlan` with PRE `executionUnits` | Required @ 8.1 | **Missing** |
+| `taskConfiguration` on wire | **Forbidden** with `nodePlan` | **Still present** (transitional / pre-8.1) |
+| `modelConfig` on wire | **Forbidden** with `nodePlan` (recipe in plan units) | **Still present** (transitional) |
+
+graph-engine parity tests today assert a **subset** (flat input, no `.raw`, `taskConfiguration === undefined`, `nodePlan` present) — not the full §4 contract. CI must be tightened after fixtures align.
+
+---
+
+## 4. Canonical contract (normative)
+
+### 4.1 Variable scopes
+
+| Scope | On `RunTaskRequest` | Template tokens |
+|-------|---------------------|-----------------|
+| Job / graph | `variables` **and** `executionMemory.jobVariables` (same bucket) | `{{jobVariables.*}}` |
+| Node / task | **`executionMemory.taskVariables` only** (no top-level field) | `{{taskVariables.*}}` |
+
+- **Invalid:** root `question`, `variables.question`, relying on `input.question` alone for `professional-answer`.
+- **Valid:** `executionMemory.taskVariables.question` (Catalox prompt `{{taskVariables.question}}`).
+
+### 4.2 MAIN input bucket
+
+| Surface | Shape |
+|---------|--------|
+| `RunTaskRequest.input` | Flat task payload (`record`, `graphIntent`, …) — compiled from `inputsConfig` + `taskVariable` literals |
+| `executionMemory.input` | **Same flat MAIN bucket** mirrored for PRE / NARRIX / synthesis — **not** nested under `input.raw` |
+
+Legacy `executionMemory.input.raw` is **deprecated**. ai-tasks **still reads** nested `raw` as a fallback (G1 fix), but graph-engine must **not** treat it as canonical.
+
+### 4.3 `professional-answer` specifics
+
+| Field | Wire location |
+|-------|----------------|
+| `question` | `executionMemory.taskVariables.question` |
+| `outputContract` | **Top-level** `RunTaskRequest.outputContract` |
+| Domain record | `input.record` (and mirrored flat `executionMemory.input` when graph seeds memory) |
+| `graphIntent` | `input.graphIntent` (or job-scope `jobVariables` when authored that way) |
+
+### 4.4 Response consumption (graph-engine)
+
+`executionMapping` must read structured skill output:
+
+```json
+"shortAnswer": "output.parsed.shortAnswer"
+```
+
+**Not** `flexMd.*` — FlexMD is ai-skills-internal; FUNCX / graph-engine consume `response.parsed`.
+
+### 4.5 PRE synthesis (graph-engine ≥ 8.1 / ai-tasks 9)
+
+**Wire rule:** When `nodePlan` is present, these are **forbidden** on `RunTaskRequest`:
+
+- `taskConfiguration`
+- `executionPipeline`
+- root `modelConfig` (recipe authority lives in plan units)
+
+PRE synthesis must be compiled **before invoke** into frozen `nodePlan.executionUnits` — typically `externalPreUtility` or `pipelinePhase` units with correct `invokeContract` (strategy, memory reads, `includeContextInPrompt`). graph-engine passes the **compiled plan** from `compileExellixExecutablePlan` / `compileExecutablePlanV2` (`@x12i/graphenix-plan-compiler`).
+
+ai-tasks executes PRE from plan units; it must **not** rely on a compile-time `taskConfiguration` blob on the wire.
+
+**Legacy path (no compiled plan):** `buildTaskNodeRunTaskRequest` without a compiled plan may use `minimalNodePlanForSkillKey` (MAIN only, **no PRE**). Preflight tests on that path **cannot** validate PRE wiring.
+
+### 4.6 Graphenix v2.1 strict path
+
+When using frozen `nodePlan` (`graphenix.node-plan/v2.1`):
+
+- `nodePlan.invokeContract.taskVariables` → must appear on wire as `executionMemory.taskVariables`.
+- `nodePlan.invokeContract.taskVariable` → must **not** re-place `question` / `outputContract` into `input` at runtime (coordination gap — see **P0-7**).
+- Forbidden on wire with `nodePlan`: `taskConfiguration`, `executionPipeline`, root `modelConfig`.
+
+---
+
+## 5. Reference: correct outbound shape (excerpt)
+
+From [`graph-engine-pre-synthesis.json`](../../test/fixtures/run-task/graph-engine-pre-synthesis.json):
+
+```json
+{
+  "skillKey": "professional-answer",
+  "outputContract": { "shortAnswer": "...", "fullAnswer": "..." },
+  "input": {
+    "graphIntent": "Understand the subnet role in the topology.",
+    "record": { "target_subnet_cidr": "192.168.10.0/24" }
+  },
+  "executionMemory": {
+    "taskVariables": {
+      "question": "What inbound routed-reachability candidates exist for this subnet?"
+    },
+    "input": {
+      "target_subnet_cidr": "192.168.10.0/24",
+      "topology": { }
+    }
+  },
+  "nodePlan": {
+    "planVersion": "graphenix.node-plan/v2.1",
+    "executionUnits": [ "/* PRE synthesis unit(s) + MAIN */" ]
+  }
+}
+```
+
+**Note:** `executionMemory.input` mirrors the graph record fields **flat** — no `.raw` wrapper. `question` is **not** on `input` or root. **No** `taskConfiguration` / root `modelConfig` on this wire.
+
+---
+
+## 6. graph-engine 8.1.x ground truth (audited)
+
+| Report item | Status in graph-engine | Notes |
+|-------------|------------------------|-------|
+| **P0-2** flat `executionMemory.input` | **Done** | `normalizeRuntimeExecutionMemory` seeds flat input; tests assert no `.raw` |
+| **P0-4** `inputsConfig.path: "input"` | **Done** | Graph fixture + tests |
+| **P0-6** `output.parsed.*` mapping | **Done** | `graph-qcrbz6t-pre-synthesis.json` |
+| Job vs task buckets | **Partial** | `jobVariables` / `taskVariables` exist; `node.variables` → `taskVariables` |
+| **P0-1** PRE enablement | **Different mechanism** | PRE via compiled `nodePlan.executionUnits`, **not** `taskConfiguration` on wire |
+| **P0-3 / P0-5** `taskVariable` → wire | **Gap** | `taskVariable` literals compile to **`input`**; `mirrorTaskVariablesOnExecution` copies **`node.variables` only**, not `taskVariable.question` |
+| **P0-1′** PRE in plan units | **Verify** | Tests expect `synthesisEnabled` via plan units; confirm `compileExecutablePlanV2` for all graph shapes |
+| Preflight without compiled plan | **Trap** | `minimalNodePlanForSkillKey` = MAIN only — cannot validate PRE |
+
+### Remaining gap IDs (still accurate)
+
+| ID | Behavior | Symptom |
+|----|----------|---------|
+| **GE-4** | `taskVariable.question` → `input.question` (not `taskVariables`) | Empty `{{taskVariables.question}}` / validation errors |
+| **GE-5** | `outputContract` stays in `input` | Wrong gateway contract |
+| **GE-6** | `node.taskVariables` / `taskVariable` not fully mirrored to `executionMemory.taskVariables` | Template scope wrong |
+| **GE-7** | `flexMd` mapping (older graphs) | Empty mapping writes |
+| **GE-8** | Stale `executionMemory` on parallel invokes | Downstream context wrong |
+| **GE-9** | PRE hints only in `metadata.graphConcept` | No PRE units in compiled plan |
+| ~~GE-1~~ | ~~Drops `taskConfiguration`~~ | **Not a bug @ 8.1** — forbidden by design |
+| ~~GE-2~~ | ~~Only `input.raw`~~ | **Fixed** in graph-engine |
+| ~~GE-3~~ | ~~`input.raw` path~~ | **Fixed** in fixtures |
+
+---
+
+## 7. Proposed graph-engine changes (requires approval)
+
+### P0 — Remaining work
+
+| # | Change | Status | Notes |
+|---|--------|--------|-------|
+| **P0-1′** | Compile PRE into `nodePlan.executionUnits` + correct `invokeContract` (strategy, memory paths, `includeContextInPrompt`) | **Verify / complete** | Replaces v1 **P0-1** (`taskConfiguration` forward) — **do not** forward `taskConfiguration` on wire |
+| **P0-2** | Flat `executionMemory.input` at graph run start | **Done** | Keep |
+| **P0-3′** | Mirror **`taskVariable` prompt fields** (at least `question`) → `executionMemory.taskVariables`; keep `node.variables` merge | **Todo** | Extend `mirrorTaskVariablesOnExecution` or compile step |
+| **P0-4** | `inputsConfig.path: "input"` | **Done** | Keep |
+| **P0-5′** | Lift `outputContract` → top-level `RunTaskRequest.outputContract`; exclude `question` from `input` | **Todo** | `resolveTaskNodeInputsForRunTask` today merges full `taskVariable` into `input` |
+| **P0-6** | `executionMapping` → `output.parsed.*` | **Done** in fixtures | Keep |
+| **P0-7** | Align `nodePlan.invokeContract` with wire contract; stop double-merging `taskVariable` into `input` at ai-tasks boundary | **Coordination** | graph-engine compile + ai-tasks `buildRequestFromNodePlan` + graphenix compiler |
+
+**P0-2 implementation sketch (approved direction):**
+
+```ts
+// At graph run init — flat MAIN bucket
+runtime.executionMemory.input = {
+  ...(runtime.executionMemory.input ?? {}),
+  ...(runtime.input ?? graphInvokePayload ?? {}),
+};
+// Do NOT wrap in { raw: ... } for new graphs
+```
+
+**P0-4 `inputsConfig` example (authoring):**
+
+```json
+"inputsConfig": {
+  "record": {
+    "type": "executionMemoryPath",
+    "path": "input"
+  }
+}
+```
+
+### P1 — Correctness under parallelism + strict plans
+
+| # | Change |
+|---|--------|
+| **P1-1** | Pass **current** shared `executionMemory` into every `runTask` invoke (parallel-safe) | GE-8 |
+| **P1-2** | Emit `nodePlan` v2.1 with `invokeContract.taskVariables` populated from node authoring | GE-6 |
+| **P1-3** | Lint: `pre: "synthesis"` requires resolvable `executionMemory.input` when record is required |
+| **P1-4** | Reject / warn `INPUT_SYNTHESIS_PIPELINE_CONFLICT` per RUNTASK_REQUEST |
+
+### P2 — Migration + studio
+
+| # | Change |
+|---|--------|
+| **P2-1** | Studio fields for `taskVariables`, `preInputStrategy`, `inputsConfig.path: input` |
+| **P2-2** | One-time migration: `input.raw` → flat `input`, `variables.question` → `taskVariables.question`, mapping paths → `output.parsed.*` |
+| **P2-3** | Update graph-engine docs that still prescribe `executionMemory.input.raw` |
+
+---
+
+## 8. ai-tasks: published vs mono-repo source
+
+| Behavior | `@exellix/ai-tasks` **9.1.0** (published) | **This mono-repo** (unreleased) |
+|----------|-------------------------------------------|----------------------------------|
+| Flat `executionMemory.input` for PRE record | Question-driven path still prefers **`input.raw`** | **`readExecutionMemoryInputRecord`** — flat first |
+| NARRIX `preferPaths` | `input.raw` before `input` | `input` before `input.raw` |
+| `professional-answer` overlay | `buildRequestFromNodePlan` merges `invokeContract.taskVariable` → **`input`** | **`compileProfessionalAnswerRequest`** lifts `question` → `taskVariables`, `outputContract` top-level |
+| Validation `taskVariables.question` | Not in 9.1.0 | **`validateProfessionalAnswerContract`** |
+| PRE from `nodePlan` units | Yes (graphenix v2.1) | Same |
+| PRE from `taskConfiguration` on wire | Legacy compile path when no forbidden fields | Stripped when `nodePlan` set |
+
+**Implication:** Approving §7 requires stating an **ai-tasks version pin** (e.g. next release containing G1–G4) before graph-engine can rely on flat-input PRE + strict `professional-answer` validation.
+
+ai-tasks **forwards** `executionMemory` **without** folding scopes into `variables`. It will **not** add graph-engine shims (e.g. re-nesting flat input under `.raw`).
+
+---
+
+## 9. Verification plan (graph-engine CI)
+
+### 9.1 Full plan compile test (required)
+
+1. Load [`graph-qcrbz6t-pre-synthesis.json`](../../test/fixtures/graphs/graph-qcrbz6t-pre-synthesis.json).
+2. Run **`compileExellixExecutablePlan`** (not preflight / `minimalNodePlanForSkillKey` only).
+3. Build `RunTaskRequest` via **`executeGraph`** path for node `step-1`.
+
+**Must hold:**
+
+- `nodePlan` present; `planVersion` = `graphenix.node-plan/v2.1`.
+- `nodePlan.executionUnits` contains PRE unit (`externalPreUtility` and/or `pipelinePhase`).
+- `taskConfiguration === undefined`, `executionPipeline === undefined`, root `modelConfig === undefined`.
+- `executionMemory.taskVariables.question` present and non-empty.
+- `outputContract` top-level; **absent** from `input`.
+- `input.question` and `input.outputContract` **absent**.
+- `executionMemory.input` flat; `'raw' in executionMemory.input === false`.
+
+Then diff against an updated golden fixture (target shape in §5).
+
+### 9.2 PRE integration smoke
+
+```ts
+import { runTask } from "@exellix/ai-tasks";
+
+// request must include compiled nodePlan from graph-engine — NOT taskConfiguration compile
+const res = await runTask(request, { catalox });
+assert(res.metadata?.synthesisEnabled === true);
+assert(String(res.parsed?.shortAnswer ?? "").trim().length > 0);
+```
+
+Use model triplet from plan units / fixture. Do **not** gate on `flexMd.frame`.
+
+### 9.3 Mapping round-trip
+
+After `runTask`, apply `executionMapping` and assert `executionMemory.answers.q1.shortAnswer` (or equivalent) is populated from `output.parsed`, not FlexMD.
+
+---
+
+## 10. Risk if graph-engine is not updated
+
+| Risk | Impact |
+|------|--------|
+| PRE enabled in graph JSON but never runs | Silent quality loss |
+| `professional-answer` with `input.question` only | Validation failure (ai-tasks 9.x+) or empty prompt |
+| Flat memory in studio / 2.1 graphs, engine still nests `.raw` | Duplicate or divergent record shapes |
+| `flexMd` mapping | Empty graph answers despite LLM success |
+| Parallel nodes | Stale memory → wrong downstream context |
+
+Backward compatibility in ai-tasks for `input.raw` is **temporary tolerance**, not a contract rollback.
+
+---
+
+## 11. Approval checklist
+
+Before graph-engine implementation, confirm:
+
+- [ ] **`nodePlan`-only wire** is canonical; **`taskConfiguration` forward is out of scope** for graph-engine ≥ 8.1 (P0-1′).
+- [ ] **Flat `executionMemory.input`** is the canonical seed path (P0-2 — already done).
+- [ ] **`taskVariable` → `taskVariables` / top-level `outputContract`** migration scoped across graph-engine compile, graphenix `invokeContract`, and ai-tasks `buildRequestFromNodePlan` (P0-3′, P0-5′, P0-7).
+- [ ] **`output.parsed.*`** is the mapping source of truth (P0-6).
+- [ ] Golden fixture updated to include `nodePlan` and **exclude** forbidden fields; §9.1 asserts **full** target shape.
+- [ ] **ai-tasks version pin** stated (9.1.0 vs next release with flat-input PRE + `professional-answer` validation).
+- [ ] P2 migration scope (auto-patch vs manual) is agreed with studio owners.
+
+**Approved by:** _pending_  
+**graph-engine tracking issue:** _TBD_
+
+---
+
+## 12. ai-tasks follow-ups (after graph-engine approval — separate PRs)
+
+These are **not** graph-engine work; listed for coordination only:
+
+1. Finish doc drift cleanup (`README.md` NARRIX path order, stale sections in `graph-engine-task-pre-synthesis-compile.md`).
+2. Default `compileTaskConfiguration` `memoryPaths` to `executionMemory.input` instead of `.raw`.
+3. Live smoke scripts: assert `response.parsed.*` instead of `flexMd.payloads`.
+
+---
+
+## Appendix A — Authoring → wire mapping (`professional-answer` node)
+
+| Graph node field | Compiled to |
+|------------------|-------------|
+| `taskVariables.question` | `executionMemory.taskVariables.question` |
+| `taskVariable.outputContract` | `RunTaskRequest.outputContract` |
+| `inputs.graphIntent` | `input.graphIntent` |
+| `inputsConfig.record` → `path: "input"` | `input.record` from flat `executionMemory.input` |
+| `taskConfiguration.aiTaskStrategies` | compiled into `nodePlan.executionUnits` (not on wire) |
+| `executionMapping.map.*` | `output.parsed.*` paths |
+
+## Appendix B — Deprecated patterns (do not emit from graph-engine)
+
+| Deprecated | Replacement |
+|------------|-------------|
+| `executionMemory.input.raw` as canonical record | flat `executionMemory.input` |
+| `inputsConfig.path: "input.raw"` | `path: "input"` |
+| `input.question` / root `question` | `executionMemory.taskVariables.question` |
+| `variables.question` (node scope) | `executionMemory.taskVariables.question` |
+| `input.outputContract` | top-level `outputContract` |
+| `executionMapping` → `flexMd.payloads.*` | `output.parsed.*` |
+| `invokeContract.variables` (node plan) | `invokeContract.taskVariables` |
+| `taskConfiguration` on wire with `nodePlan` | PRE units inside `nodePlan` only |
+| root `modelConfig` with `nodePlan` | per-unit `modelSelection` in plan |

package/documenations/upstream-feature-requests/xynthesis-ai-profiles-2.1-import-break.md

@@ -279,7 +279,7 @@ Run full suite with **`@x12i/ai-profiles@2.1.0`** installed (not 2.0.x).
 2. `npm install && npm run test`
 3. Patch release **8.4.x** updating README / BREAKING-CHANGES minimums
 
-See [`ai-tasks-wrap-up-after-upstream.md`](./ai-tasks-wrap-up-after-upstream.md).
+See [`ai-tasks-wrap-up-after-upstream.md`](../../../archived/ai-tasks/documenations/upstream-feature-requests/superseded/ai-tasks-wrap-up-after-upstream.md).
 
 ---
 
@@ -319,6 +319,6 @@ See [`ai-tasks-wrap-up-after-upstream.md`](./ai-tasks-wrap-up-after-upstream.md)
 ## Related
 
 - [`@exellix/ai-tasks` `src/utils/aiProfileModelFormat.ts`](../../src/utils/aiProfileModelFormat.ts) — reference implementation
-- [`.docs/ai-tasks-model-profile-aliases-7x.md`](../../.docs/ai-tasks-model-profile-aliases-7x.md) — wire shapes orchestrators send
+- [`.docs/ai-tasks-model-profile-aliases-7x.md`](../../../archived/ai-tasks/.docs/ai-tasks-model-profile-aliases-7x.md) — wire shapes orchestrators send
 - [`BREAKING-CHANGES.md`](../../BREAKING-CHANGES.md) — 8.4.x blocked subsection
 - [`xynthesis-orchestrator-invoke-contract-4.2.md`](./xynthesis-orchestrator-invoke-contract-4.2.md) — invoke contract (reasoningEffort shipped; import fix is separate P0)

package/documenations/upstream-feature-requests/xynthesis-openrouter-wire-model-double-prefix-bug.md

@@ -186,6 +186,6 @@ Skill phase (`phaseKind: "skill"`) should **keep** `openrouter/` gateway prefix
 
 ## Related
 
-- [`.docs/prefer-openrouter-routing-policy.md`](../../.docs/prefer-openrouter-routing-policy.md)
+- [`.docs/prefer-openrouter-routing-policy.md`](../../../archived/ai-tasks/.docs/prefer-openrouter-routing-policy.md)
 - [`funcx-openrouter-model-id-pass-through.md`](./funcx-openrouter-model-id-pass-through.md) — funcx is pass-through; no fix required there
 - [`xynthesis-upstream-fixes-checklist.md`](../xynthesis-upstream-fixes-checklist.md)

package/documenations/upstream-feature-requests/xynthesis-orchestrator-invoke-contract-4.2.md

@@ -179,7 +179,7 @@ ai-tasks will follow whichever contract is published; default integration is **n
 
 ## After this ships — ai-tasks follow-up
 
-See [`ai-tasks-wrap-up-after-upstream.md`](./ai-tasks-wrap-up-after-upstream.md):
+See [`ai-tasks-wrap-up-after-upstream.md`](../../../archived/ai-tasks/documenations/upstream-feature-requests/superseded/ai-tasks-wrap-up-after-upstream.md):
 
 - Remove `resolveMaxTokens` imports and `resolveLlmCallForXynthesis` token math.
 - Pass `outputExpectation` + `temperature` + `topP` + `reasoningEffort` into every `executeXynthesisAction` call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/ai-tasks",
-  "version": "9.1.0",
+  "version": "10.0.0",
   "description": "Task orchestration for the Exellix stack: runTask() with local handlers or LLM-backed execution, task-scoped memory/context enrichment, and executor dispatch via @exellix/ai-skills. ERC-compliant.",
   "type": "module",
   "main": "dist/index.js",
@@ -60,7 +60,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@exellix/ai-skills": "^6.9.0",
+    "@exellix/ai-skills": "^6.10.0",
     "@exellix/memorix-narrix-adapter": "^2.0.0",
     "@exellix/narrix-adapter-chat": "^2.0.0",
     "@exellix/narrix-adapter-docs": "^2.0.0",
@@ -72,16 +72,17 @@
     "@exellix/narrix-ingest": "^2.0.0",
     "@exellix/narrix-runner": "^2.0.0",
     "@exellix/narrix-web-scoper": "^2.0.0",
-    "@exellix/xynthesis": "^4.8.0",
+    "@exellix/xynthesis": "^4.8.2",
     "@x12i/activix": "^8.6.3",
     "@x12i/ai-profiles": "^3.4.0",
     "@x12i/catalox": "^5.2.0",
     "@x12i/env": "^4.0.1",
     "@x12i/execution-memory-manager": "^1.2.0",
-    "@x12i/funcx": "^4.9.6",
-    "@x12i/graphenix-executable-contracts": "^2.0.0",
-    "@x12i/graphenix-plan-format": "^2.0.0",
-    "@x12i/graphenix-trace-format": "^2.0.0",
+    "@x12i/funcx": "^4.9.13",
+    "@x12i/graphenix-core": "^2.0.1",
+    "@x12i/graphenix-executable-contracts": "^2.0.1",
+    "@x12i/graphenix-plan-format": "^2.0.1",
+    "@x12i/graphenix-trace-format": "^2.0.1",
     "@x12i/logxer": "^4.6.0",
     "@x12i/optimixer": "^3.5.2",
     "@x12i/rendrix": "^4.3.0",
@@ -91,8 +92,8 @@
   },
   "devDependencies": {
     "@types/node": "^18.0.0 || ^20.0.0",
-    "@x12i/graphenix-authoring-format": "^2.0.0",
-    "@x12i/graphenix-plan-compiler": "^2.0.0",
+    "@x12i/graphenix-authoring-format": "^2.0.1",
+    "@x12i/graphenix-plan-compiler": "^2.0.1",
     "dotenv": "^16.0.0",
     "ts-node": "^10.9.0",
     "tsx": "^4.0.0",

package/.docs/DOWNSTREAM_ENV.md

@@ -1,42 +0,0 @@
-# Downstream / upstream environment variables
-
-This document lists which env vars **ai-tasks** uses itself and which are consumed **downstream** (by @woroces/ai-skills, @athenices/ai-gateway, @athenices/ai-provider-router, @athenices/ai-activities-tracking). ai-tasks does **not** read router or Mongo collection env vars; they are used by dependencies. For full reference, see each package’s docs.
-
----
-
-## Env vars used by ai-tasks
-
-| Variable | Purpose | Default |
-|----------|---------|--------|
-| `MONGO_LOGS_DB` | Default database name for activity logs; passed as `bindingDefaultsDb` to the skills client and used downstream for routing. | `logs-db` |
-
----
-
-## Env vars consumed downstream (when using ai-tasks)
-
-These affect behavior when you run LLM-backed tasks or activity tracking but are **not** read by ai-tasks. They are used by ai-skills → ai-gateway → ai-provider-router and ai-activities-tracking.
-
-### Provider / router (ai-gateway, ai-provider-router)
-
-| Variable | Purpose |
-|----------|--------|
-| `OPEN_ROUTER_KEY` or `OPENROUTER_API_KEY` | Use OpenRouter for LLM calls; no need to register providers when set. |
-| `PREFER_OPENROUTER` | Prefer OpenRouter routing when an OpenRouter API key is present. |
-
-Other provider keys (e.g. `OPENAI_API_KEY`, `GROK_API_KEY`) are validated by **ai-skills** at init; for OpenRouter-only setups, ai-skills must accept `OPEN_ROUTER_KEY` / `OPENROUTER_API_KEY` in its provider check.
-
-### Activity tracking (ai-gateway → ai-activities-tracking)
-
-| Variable | Purpose | Default (in ai-activities-tracking) |
-|----------|---------|-------------------------------------|
-| `MONGO_LOGS_COLLECTION` | Main activities collection name. | `cognitive-activities` |
-| `MONGO_BAD_REQUESTS_COLLECTION` | Bad/validation-failure requests collection name. | `ai-bad-requests` |
-
-Both are **optional**; safe to leave unset. If unset or unresolved, ai-activities-tracking uses the defaults above and never uses the env var name as the collection name.
-
----
-
-## Summary
-
-- **ai-tasks** only reads `MONGO_LOGS_DB` (for `bindingDefaultsDb`). All other Mongo and router env vars are used by downstream packages.
-- For “No provider specified and no providers registered” and collection-name issues, fixes live in ai-provider-router, ai-gateway, and ai-activities-tracking. Ensure you use versions of `@athenices/ai-gateway` (and thus ai-activities-tracking) that include those fixes.

package/.docs/FEEDBACK_TO_CLIENT_DOWNSTREAM_FIXES.md

@@ -1,64 +0,0 @@
-# Feedback to client (worox-graphs): downstream fixes for the two reported issues
-
-**Audience:** Consumer of `@woroces/ai-tasks` (e.g. `@woroces/worox-graph`) who reported the router and Mongo collection-name issues.  
-**From:** ai-tasks maintainers  
-**Date:** 2026-02-23
-
----
-
-## Summary
-
-Both issues you reported were **downstream** of ai-tasks (in ai-provider-router, ai-gateway, and ai-activities-tracking). They are fixed in those packages. **No change is required in your application (worox-graphs).** After upgrading to versions that include the fixes, the problems should be resolved.
-
----
-
-## 1. “No provider specified and no providers registered”
-
-**What you saw:** The router threw this error even when `OPEN_ROUTER_KEY` was set; your app only calls `ai-tasks.runTask()` and does not register any provider.
-
-**Where it was fixed:** In `@athenices/ai-provider-router` and/or `@athenices/ai-gateway`:
-
-- OpenRouter is now considered (and can be used) **before** the “no providers registered” check, so when `OPEN_ROUTER_KEY` (or `OPENROUTER_API_KEY`) is set, the router can resolve a provider without your app registering anything.
-- Error messaging was improved to point to setting `OPEN_ROUTER_KEY` or registering a provider when no provider can be used.
-
-**What you should do:**
-
-- **Upgrade** so your resolved dependency stack includes the **fixed ai-gateway** (and thus the fixed ai-provider-router). That usually means upgrading `@woroces/ai-tasks` to a version that depends on the fixed ai-gateway (e.g. ai-tasks 2.8.x with ai-gateway ^7.3.1 or the version that includes the router fix), then run `npm install`.
-- Ensure **`OPEN_ROUTER_KEY`** (or `OPENROUTER_API_KEY`, depending on what the gateway reads) is set in your environment when you want to use OpenRouter. Load `.env` before the process starts (e.g. via dotenv/dotenvx) as you already do.
-- You do **not** need to create or configure the router or register any provider in your app.
-
----
-
-## 2. Mongo collection names (ENV.MONGO_BAD_REQUESTS_COLLECTION etc.)
-
-**What you saw:** When `MONGO_LOGS_COLLECTION` / `MONGO_BAD_REQUESTS_COLLECTION` were unset, the app used the env var name (or an `ENV.*` token) as the MongoDB collection name, creating collections like `ENV.MONGO_BAD_REQUESTS_COLLECTION`.
-
-**Where it was fixed:** In `@athenices/ai-activities-tracking`:
-
-- Defaults were added: **`cognitive-activities`** for the main logs collection and **`ai-bad-requests`** for the bad-requests collection.
-- Collection names are normalized so that unset or unresolved `ENV.*` tokens are never used as collection names; the default is used instead.
-
-**What you should do:**
-
-- **Upgrade** so your resolved stack includes the **fixed ai-activities-tracking** (typically by depending on a version of ai-gateway that depends on the fixed ai-activities-tracking). Upgrading ai-tasks (and ensuring ai-gateway is updated) will pull in the fixed version.
-- You **do not** need to set `MONGO_LOGS_COLLECTION` or `MONGO_BAD_REQUESTS_COLLECTION` unless you want to override the defaults. If they are unset or unresolved, the packages now use `cognitive-activities` and `ai-bad-requests` and never the env var name.
-
----
-
-## No changes required in your repo
-
-- **worox-graphs** does not need to create or configure the AI router, register providers, or read Mongo collection env vars. The fixes are entirely in the packages that implement that behavior (ai-provider-router, ai-gateway, ai-activities-tracking).
-- Your only required action is to **upgrade** to versions that include these fixes (via `@woroces/ai-tasks` and its dependency tree). Optional: ensure `OPEN_ROUTER_KEY` (or `OPENROUTER_API_KEY`) is set when using OpenRouter.
-
----
-
-## Upgrade checklist
-
-| Step | Action |
-|------|--------|
-| 1 | Upgrade `@woroces/ai-tasks` to a version that depends on the fixed ai-gateway (e.g. ^2.8.x with ai-gateway that includes the router fix). |
-| 2 | Run `npm install` (or your package manager’s equivalent) so the lockfile resolves to the fixed ai-gateway and its transitive deps (ai-provider-router, ai-activities-tracking). |
-| 3 | Ensure `.env` is loaded before the process starts and contains `OPEN_ROUTER_KEY` (or `OPENROUTER_API_KEY`) when using OpenRouter. |
-| 4 | Optionally leave `MONGO_LOGS_COLLECTION` and `MONGO_BAD_REQUESTS_COLLECTION` unset; they now default to `cognitive-activities` and `ai-bad-requests`. |
-
-If you still see “No provider specified and no providers registered” after upgrading, confirm that the resolved `@athenices/ai-gateway` (and `@athenices/ai-provider-router`) in your lockfile are the versions that include the OpenRouter fix, and that your env key (`OPEN_ROUTER_KEY` or `OPENROUTER_API_KEY`) is set before any gateway call.

package/.docs/INTERMEDIATE_STEPS.md

@@ -1,82 +0,0 @@
-# Structured intermediate results for combined / multi-step tasks
-
-When a task (or skill) runs multiple logical steps in one invocation (e.g. “to-cni + enrich + triage”), the response can include structured data for each sub-step so consumers can inspect and report what happened “in between” without extra round-trips.
-
-## Response shape
-
-Task responses may include an optional top-level **`intermediateSteps`** array. When present, it describes each step performed in order.
-
-### Type: `IntermediateStep`
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `step` | number | yes | 1-based order in the execution chain |
-| `id` | string | yes | Stable identifier (e.g. `"to-cni"`, `"engine-enrich"`, `"triage-q1-q6"`) |
-| `ok` | boolean | yes | Whether this step completed successfully |
-| `summary` | string | no | Short summary (e.g. `"cni built"`, `"enriched"`) |
-| `error` | string | no | Error message when `ok` is false |
-| `inputSummary` | object \| string | no | Summary input (e.g. keys/ids) for reporting |
-| `outputExcerpt` | object | no | Small excerpt of step output for debugging; keep small to avoid payload bloat |
-
-### Example response
-
-```json
-{
-  "success": true,
-  "output": { "answers": {}, "decision": {} },
-  "intermediateSteps": [
-    { "step": 1, "id": "to-cni", "summary": "cni built", "ok": true },
-    { "step": 2, "id": "engine-enrich", "summary": "enriched", "ok": true },
-    { "step": 3, "id": "triage-q1-q6", "summary": "answers Q1,Q6", "ok": true }
-  ]
-}
-```
-
-With optional excerpts for debugging:
-
-```json
-{
-  "intermediateSteps": [
-    { "step": 1, "id": "to-cni", "ok": true, "outputExcerpt": { "cni": { "subject": {} } } },
-    { "step": 2, "id": "engine-enrich", "ok": true, "outputExcerpt": { "record": {} } },
-    { "step": 3, "id": "triage-q1-q6", "ok": true }
-  ]
-}
-```
-
-## How it works in ai-tasks
-
-- **Skills/tasks** that perform multiple logical steps may return `intermediateSteps` either:
-  - **Top-level** on the response (if the executor passes it through), or
-  - **Inside `parsed`** as `parsed.intermediateSteps`.
-- **Task SDK** normalizes so that the **top-level** `response.intermediateSteps` is the canonical place:
-  - For **local tasks**: if the handler returns an object with `intermediateSteps`, they are lifted to the response and omitted from `parsed`.
-  - For **executor (DIRECT)** results: if `result.parsed.intermediateSteps` is present, it is lifted to `result.intermediateSteps` and removed from `parsed`.
-- **NARRIX_THEN_DIRECT**: the runtime prepends a step `{ step: 1, id: "narrix", ok: true, summary: "narrix run completed" }` and renumbers any steps from the direct phase (step 2, 3, …).
-
-## Consumer usage
-
-Consumers (e.g. worox-graphs playground reporter) can:
-
-1. **Persist or display** the chain (e.g. “Step 1: to-cni → Step 2: engine-enrich → Step 3: triage-q1-q6”).
-2. **Optionally link to or embed** excerpts of intermediate payloads when `outputExcerpt` is present.
-3. Use the list to get visibility equivalent to per-node request/response files, without requiring separate graph nodes for each step.
-
-## TypeScript
-
-```ts
-import type { RunTaskResponseWithSteps, IntermediateStep, IntermediateSteps } from "@woroces/ai-tasks";
-
-const res: RunTaskResponseWithSteps<MyOutput> = await runTask(request);
-if (res.intermediateSteps) {
-  for (const s of res.intermediateSteps) {
-    console.log(`Step ${s.step}: ${s.id} ${s.ok ? "ok" : s.error}`);
-  }
-}
-```
-
-## Acceptance criteria (reference)
-
-- A combined task can return an optional list of intermediate steps in execution order.
-- Each step has a stable identifier and success flag; optional summary or excerpt is supported.
-- Consumers can use this list to render a “chain” view (e.g. in reports or playground) equivalent to the current per-node visibility, without requiring separate graph nodes for each step.