@exellix/ai-tasks 7.8.0

package/documenations/funcx-upstream-github-issues-draft.md

@@ -0,0 +1,153 @@
+# FuncX upstream — draft GitHub issues
+
+Use these as copy-paste bodies when filing against **`https://github.com/x12i/funcx`** (adjust labels: `bug`, `documentation`, `enhancement` as appropriate).
+
+**Update (@x12i/funcx ≥ 3.8.2):** Issue **#1** is largely addressed in-package via **`getRunJsonResult`**, **`isHttpRunSuccessBody`**, **`GenericExecutionEnvelope`**, **`genericExecutionEnvelopeJsonSchema`**, and **`buildAskAttribution`** exported from `@x12i/funcx/functions`. **`@exellix/ai-tasks`** depends on **`^3.8.2`** and delegates **`unwrapFuncxRunValue`** to **`getRunJsonResult`** (normalization fixes: **3.8.2**).
+
+---
+
+## Issue 1 — `run()` success value shape is not formally specified or normalized (Bug / API contract)
+
+**Status:** Superseded for normalization — use **`getRunJsonResult`** (**≥3.8.2** recommended). Remaining gap: ensure **README / migration** links every consumer to this API (Issue #5 overlap).
+
+**Title:** `run()`: document and export stable JSON extraction for function results
+
+**Type:** Bug (integration hazard) + Documentation
+
+### Summary
+
+Downstream packages (e.g. `@exellix/ai-tasks`) call `run(functionId, payload, { client })` from `@x12i/funcx/functions` and must pass the **parsed function JSON** into app-specific adapters. The **success return shape** of `run()` is not clearly guaranteed in public TypeScript types or docs: hosts may wrap the model/object as `output`, `data`, `result`, or return the object root directly.
+
+### Current behavior
+
+Integrators defensively unwrap multiple keys or treat the whole value as JSON, which is fragile and can silently feed adapters the wrong object.
+
+### Expected behavior
+
+1. **Document** the canonical success shape of `run()` for JSON-returning functions (one paragraph + example in package README or `run` JSDoc).
+2. **Export** a small helper, e.g. `getRunJsonResult(runResult: unknown): unknown` (name TBD), that implements the **supported** unwrapping rules so consumers do not duplicate heuristics.
+3. **Type** the resolved JSON result where possible (generic parameter or discriminated union), even if implementation stays dynamic internally.
+
+### Acceptance criteria
+
+- [ ] Public API + docs agree on one normalization path.
+- [ ] At least one unit test in `@x12i/funcx` locks the behavior for JSON-mode functions.
+- [ ] Changelog calls out any tightening if older hosts relied on ambiguous shapes.
+
+### References
+
+- Consumer workaround today: local `unwrapFuncxRunValue` heuristics in `@exellix/ai-tasks` (`genericExecutionFuncxEnvelope.ts`).
+
+---
+
+## Issue 2 — No published TypeScript / JSON Schema for generic execution envelope (Feature)
+
+**Title:** Publish shared types (and optional JSON Schema) for generic `goal` / `input` / `context` / `result` / `args` / `attribution` contracts
+
+**Type:** Feature request
+
+### Summary
+
+Multiple products want the same **generic FuncX envelope** for capabilities such as `execution/plan`, `execution/evaluate-result`, and `research/plan-questions`. Today each consumer re-declares structural types, which risks drift from FuncX’s actual validation and from other clients.
+
+### Request
+
+1. Export TypeScript types from `@x12i/funcx` (or a sibling package) for:
+   - Generic request envelope (`goal`, `input?`, `context?`, `result?`, `args?`, `attribution?`).
+   - Optional: per-function **response** types or Zod schemas where FuncX validates outputs.
+2. Optionally publish **JSON Schema** artifacts for the same contracts (for non-TS hosts and catalog tooling).
+
+### Acceptance criteria
+
+- [ ] Types are importable from a documented entrypoint (e.g. `@x12i/funcx` or `@x12i/funcx/contracts`).
+- [ ] Version SemVer policy documented (breaking changes to envelope bump major or explicit migration note).
+
+### References
+
+- Draft consumer types: `@exellix/ai-tasks` `genericExecutionFuncxEnvelope.ts`.
+
+---
+
+## Issue 3 — Canonical catalog functions for generic execution / research planning (Feature)
+
+**Title:** Ship and register `execution/plan`, `execution/evaluate-result`, `research/plan-questions` as first-class FuncX functions
+
+**Type:** Feature request (blocking for generic orchestration clients)
+
+### Summary
+
+Orchestrators are standardizing on **capability-based** ids (`execution/plan`, etc.) with a **single generic envelope**. Consumers call `run()` with that payload. Today, npm still emphasizes legacy **`aiTasksPlanTask` / `aiTasksOptimizerEvaluate`**-style entrypoints while the ecosystem moves away from product-prefixed ids and bespoke envelopes.
+
+### Request
+
+1. Implement the three functions with behavior matching the published generic contract (prompting, JSON mode, validation, retries as appropriate).
+2. Register them in the **content/catalog path** used by `run()` for typical deployments (document exact ids: slash + hyphen router forms).
+3. Forward **`attribution`** from the inbound envelope into **every** nested `client.ask()` / `askJson` call inside those functions (for billing/trace parity).
+4. Document migration for hosts that still register **`ai-tasks/plan-task`** (if aliases are supported, document explicitly; if not, document cutover).
+
+### Acceptance criteria
+
+- [ ] `run("execution/plan", payload, { client })` (and hyphen alias if applicable) returns validated JSON per spec.
+- [ ] Same for `execution/evaluate-result` and `research/plan-questions`.
+- [ ] Live or CI-backed test that attribution tags survive to provider-facing calls where OpenRouter/Activix expect them.
+
+### References
+
+- Consumer defaults: `@exellix/ai-tasks` `constants.ts` (`FUNCX_EXECUTION_*`, `FUNCX_RESEARCH_PLAN_QUESTIONS_FUNCTION_ID`).
+
+---
+
+## Issue 4 — Document attribution forwarding contract for custom FuncX functions (Documentation)
+
+**Title:** Document: function implementations MUST propagate `payload.attribution` (or equivalent) to nested LLM calls
+
+**Type:** Documentation (severity: high for observability)
+
+### Summary
+
+Generic envelopes include **`attribution`** (`runId`, `subjectId`, `actorId`, `tags`, etc.). If implementers only log the outer HTTP boundary but omit attribution on internal `ask()` calls, **usage, cost, and trace correlation** break for nested completions.
+
+### Request
+
+1. Add a **short “FuncX function author checklist”** section: read `attribution` from input → merge with `functionId` / `traceId` as needed → pass on `AskOptions.attribution` for every LLM call.
+2. Reference existing helpers (`formatOpenRouterUserField`, `execAttribution`, etc.) if those are the supported path.
+3. Optionally add a **lint or runtime warning** in dev mode when `ask()` is invoked without attribution inside functions that received a populated envelope (stretch goal).
+
+### Acceptance criteria
+
+- [ ] Public docs linked from `run()` / “authoring functions” guide.
+- [ ] Example function in repo demonstrates nested attribution.
+
+---
+
+## Issue 5 — Clarify relationship between direct TS exports (`aiTasksPlanTask`) and `run()` generic functions (Documentation / Deprecation)
+
+**Title:** Migration guide: `aiTasksPlanTask` / `aiTasksOptimizerEvaluate` vs `run("execution/plan", …)` generic envelope
+
+**Type:** Documentation + Deprecation policy (could start as docs-only)
+
+### Summary
+
+`@x12i/funcx/functions` still exports **direct** helpers for legacy ai-tasks-shaped payloads while new integrators use **`run()`** + generic envelope + new ids. Without an explicit migration table, teams duplicate behavior or pick the wrong integration path.
+
+### Request
+
+1. Document **one recommended path** for new code (generic ids + `run()` + shared types).
+2. State whether **`aiTasksPlanTask`** / **`aiTasksOptimizerEvaluate`** are **deprecated**, **supported aliases**, or **frozen** — with semver expectations.
+3. If generic functions supersede them, provide a **payload mapping table** (old `kind` + `request` → new `goal` + `input` + `context` + `attribution`).
+
+### Acceptance criteria
+
+- [ ] README or `docs/migration-generic-execution.md` committed and linked from changelog when generic functions ship.
+
+---
+
+### Filing checklist
+
+| Draft # | Suggested GitHub label        | Blocking `@exellix/ai-tasks`?      |
+|---------|-------------------------------|-----------------------------------|
+| 1       | `bug`, `documentation`, `api` | Yes (correctness of parsing)      |
+| 2       | `enhancement`                 | No (quality / drift reduction)    |
+| 3       | `enhancement`                 | Yes (runtime unless content-only) |
+| 4       | `documentation`               | Yes (observability parity)        |
+| 5       | `documentation`               | No (clarity / migration)         |

package/documenations/identity-metadata-contract.md

@@ -0,0 +1,165 @@
+# Feature request: `identity` propagation + Activix identity
+
+## Goal
+
+Add a generic, end-to-end **identity envelope** to each task run so that:
+
+- Upstream callers can describe *what this task instance is* (domain identity, purpose, correlation).
+- Runtime can add a **unique per-run `taskId`** and the **`skillId` used**.
+- Downstream components that support Activix receive this identity as a **first-class Activix field**: `identity`.
+
+This is a contract-level feature request for **`ai-gateway`** and **`ai-skills`** integrations, expressed generically so it applies to any task/skill combination.
+
+---
+
+## Terminology
+
+- **Upstream**: The caller that initiates a `runTask` request (product/app/service).
+- **Gateway**: The LLM gateway layer (`ai-gateway`) used for model/tool calls.
+- **Skills**: Skill resolver/executor layer (`ai-skills`) used by task execution.
+- **Downstream**: Any component invoked during execution (LLM calls, tools, connectors). This doc focuses on **Activix-capable** downstreams.
+- **Activix-capable**: A downstream path that records execution via Activix and can attach first-class `identity`.
+
+---
+
+## API shape (high-level)
+
+### Upstream request addition
+
+Task-run requests should allow an optional field:
+
+- `identity?: object`
+
+Constraints:
+
+- Treat as an **opaque JSON object** (no strict schema required at first).
+- Must be safe for logging/tracing (no secrets). If secrets are possible, either upstream must redact or the runtime must enforce redaction policy before emitting observability.
+
+### Runtime enrichment (per execution instance)
+
+For every execution instance, runtime must produce an **effective identity**:
+
+- `effectiveIdentity = identity (from upstream, if present) + { taskId, skillId }`
+
+Where:
+
+- `taskId`: **required**, generated by runtime, unique per task-run instance.
+- `skillId`: **required when a skill is selected/resolved**, set to the skill used for this run.
+
+Notes:
+
+- `identity` from upstream is **never dropped** when present.
+- `taskId` and `skillId` **must not** be accepted from upstream as authoritative values if they are provided there; runtime-generated/selected values win.
+
+---
+
+## Behavior contract
+
+### 1) Preserve upstream identity
+
+- If upstream sends `identity`, keep it attached to the run for the full lifecycle.
+- If upstream does not send it, initialize identity as an empty object for the purpose of downstream propagation and enrichment.
+
+### 2) Create a per-run `taskId`
+
+- Create `taskId` once per `runTask` invocation.
+- The ID must be stable across the entire run (pre/main/post steps, retries within the run, and all downstream calls spawned by this run).
+- The ID must be unique across runs (collision-resistant).
+
+### 3) Attach `skillId` when known
+
+- When the runtime resolves the skill used for this run, attach `skillId` to the effective identity.
+- If the run is “direct” (no skills), either:
+  - omit `skillId`, or
+  - set `skillId` to a documented sentinel (only if that’s already a platform convention).
+
+### 4) Forward to all Activix-capable downstream calls
+
+When creating Activix records, attach identity as a first-class field:
+
+- `activixRecord.identity = effectiveIdentity`
+
+This requires Activix to treat `identity` as a first-class, supported object field (preserved end-to-end on start/complete/fail and queryable in stored records). This is intentional: identity is part of the methodology/contract, not an ad-hoc blob nested under arbitrary meta.
+
+This identity must be included for:
+
+- MAIN execution calls
+- PRE steps that call downstream (e.g., synthesis)
+- POST steps that call downstream
+
+If a downstream path is not Activix-capable, the runtime should still retain the identity in memory/metadata so it can be used when a later step *is* Activix-capable.
+
+---
+
+## Ownership and responsibilities
+
+### Upstream (product/service calling `runTask`)
+
+- Provide `identity` describing the task instance in domain terms.
+- Do not include secrets.
+- Do not attempt to control `taskId` generation; treat `taskId` as runtime-owned.
+
+Examples of useful upstream fields (non-prescriptive):
+
+- `source`: service/app identifier
+- `purpose`: why the task was launched
+- `correlationId`: upstream correlation ID (if already present)
+- `user`: stable user/account identity (non-secret)
+- `entity`: domain object reference (e.g., `{ type: "...", id: "..." }`)
+
+### ai-skills (skill resolution/execution)
+
+- Ensure `skillId` for the selected skill is available to the runtime and included in the effective identity.
+- Ensure any skill-spawned downstream calls that record to Activix also receive the effective identity in Activix record `identity`.
+
+### ai-gateway (gateway for LLM/tool calls)
+
+- Accept and preserve an identity object on calls originating from task execution.
+- When the gateway records to Activix, place the effective identity under top-level `identity` (do not rename/flatten fields).
+- Do not mutate upstream identity fields except for the controlled addition/override of `taskId` and `skillId` as defined in this contract.
+
+---
+
+## Activix mapping (required)
+
+When an execution path uses Activix:
+
+- **Input**: Upstream `identity` + runtime `{ taskId, skillId }`
+- **Output**: `identity` equals the merged object
+
+Merging rules:
+
+- Start with upstream `identity` (or `{}` if missing)
+- Add/overwrite:
+  - `taskId` (runtime generated)
+  - `skillId` (runtime resolved)
+
+---
+
+## Observability and debugging (recommended)
+
+Expose minimal, non-sensitive observability so runs can be traced:
+
+- `metadata.taskId` (top-level convenience mirror)
+- `metadata.skillId` (top-level convenience mirror when present)
+- `metadata.identityPresent: boolean`
+
+If the full `identity` is logged, enforce redaction policy; otherwise log only safe subsets or presence flags.
+
+---
+
+## Backward compatibility stance
+
+- New field is additive: existing callers continue to work with `identity` absent.
+- Downstream Activix paths should be tolerant to missing identity fields (but runtime should always generate `taskId` once this feature is implemented).
+
+---
+
+## Acceptance criteria
+
+- A `runTask` request may include `identity` and it is preserved for the full run.
+- Each run results in a unique runtime-generated `taskId` that is stable across all downstream calls for that run.
+- When a skill is used, the effective identity includes `skillId`.
+- Any Activix record created by the system includes first-class `identity` populated with the effective identity.
+- Minimal observability surfaces `taskId` (and `skillId` when applicable) so traces/logs can correlate all calls to a single run.
+

package/documenations/intermediate-steps.md

@@ -0,0 +1,33 @@
+# Intermediate Steps
+
+This appendix explains how `intermediateSteps` are exposed in `@exellix/ai-tasks` responses.
+
+## Purpose
+
+`intermediateSteps` provides a normalized, ordered trace of multi-step execution inside a single `runTask()` call.
+
+## Response shape
+
+Each step includes:
+
+- `step` (number, 1-based order)
+- `id` (stable identifier, for example: `narrix`, `synthesis`, `audit-cycle-1`)
+- `ok` (boolean)
+- Optional fields: `summary`, `error`, `inputSummary`, `outputExcerpt`
+
+## Where steps come from
+
+- Local task handlers that return `intermediateSteps`
+- `narrix-then-direct` path (prepends a `narrix` step)
+- `executionPipeline` PRE/POST behavior (for example `synthesis`, `audit`, `polish`)
+
+## Runtime behavior
+
+- Runtime may lift `parsed.intermediateSteps` to top-level `response.intermediateSteps`.
+- Step numbering is normalized and continuous after runtime-inserted steps.
+- Consumers should read steps from top-level `response.intermediateSteps`.
+
+## Related appendices
+
+- `documenations/run-task-execution-flow.md`
+- `documenations/core-runtime-tokens-and-strategies.md`

package/documenations/record-and-template-variables.md

@@ -0,0 +1,32 @@
+# Record fields and template variables (`runTask`)
+
+This document describes how **task input** and **record-shaped** payloads reach gateway templates and skills, and how that relates to NARRIX pre-processing.
+
+## Default: forward opaque fields (no allowlist)
+
+For the **MAIN** LLM path, `mergeSkillTemplateVariables` builds the `variables` object sent to the executor / gateway:
+
+- **`jobContext`** is merged first (lowest precedence).
+- Explicit **`variables`** are merged on top.
+- When **`input`** is a plain object, **every enumerable key** on `input` is copied into **`variables.inputs`** (merged with any existing `variables.inputs`). If `input.question` is a string and `variables.question` is unset, it is also copied to **`variables.question`**.
+
+There is **no** stripping of unknown or “enrichment” keys such as **`mitreAttack`**, nested blobs, or vendor-specific fields, as long as they live on the **`input`** object (or on nested objects under `input`, e.g. `input.record.mitreAttack`).
+
+**Implication:** templates that reference `inputs.record.mitreAttack`, `inputs.mitreAttack`, etc. receive the same JSON shape the caller passed on `RunTaskRequest.input`, unless a **future** explicit blocklist is added (none by default).
+
+## Reserved / runtime-owned names (conventions)
+
+These are **not** automatically stripped today, but **callers should avoid** using them on `input` for domain data if they conflict with runtime-injected fields:
+
+- **`aiScoped`** — may be injected by the AI scoping pre-step when `aiScoping` is configured.
+- **`question`** — special-cased for template convenience (`variables.question`).
+
+Memory surfaces (**`jobMemory`**, **`taskMemory`**, **`executionMemory`**) use their own keys (`_narrix`, `webContext`, `synthesizedContext`, `synthesizedInput`, `webContextMarkdown`, etc.). Domain records are usually under **`input`**, **`jobMemory.record`**, **`jobMemory.currentRecord`**, or **`executionMemory.input.raw`** / **`executionMemory.input.record`** depending on orchestration; see NARRIX adapter tests and [run-task-execution-flow.md](./run-task-execution-flow.md).
+
+## NARRIX `record` medium
+
+For **`medium: "record"`**, the object passed to Narrix is produced by **`@woroces/memory-narrix-adapter`** from configured memory paths. That adapter returns the **resolved record object**; enrichment fields on that object are preserved **unless** a future blocklist is introduced in the adapter or caller.
+
+## Regression expectation
+
+A record that includes **`mitreAttack`** on the task **`input`** (e.g. under **`input.record`**) is reflected unchanged under **`variables.inputs`** for the MAIN skill invocation.

package/documenations/run-task-execution-flow.md

@@ -0,0 +1,153 @@
+# Current Behavior Flow (`runTask`)
+
+This document describes the **current** end-to-end behavior of `@exellix/ai-tasks` when `runTask()` is called.
+
+## Flow Diagram
+
+```mermaid
+flowchart TD
+    A[Start: runTask] --> R0[resolveRunTaskRuntimeKnobs]
+    R0 --> B{narrixMode preprocessor + request.narrix?}
+    B -- No --> B2{narrixMode handler?}
+
+    B -- Yes --> N1[Resolve raw record]
+    N1 --> N2[Run Narrix pre-processor]
+    N2 --> N3[Attach _narrix to executionMemory and jobMemory]
+    N3 --> N4{narrix.enableWebScope === true?}
+    N4 -- Yes --> N5[Run web scoper]
+    N5 --> N6[Set executionMemory.webContext]
+    N4 -- No --> B2
+    N6 --> B2
+
+    B2 -- Yes --> H1[Resolve narrixInput]
+    H1 --> H2[Run structured Narrix handler]
+    H2 --> H3{ok?}
+    H3 -- No --> H4[Return early phase narrix]
+    H3 -- Yes --> H5[Merge taskMemory.narrix + input.narrixContext; force MAIN direct]
+    H5 --> C
+    B2 -- No --> C{Local task registered?}
+
+    C -- Yes --> L1[Local handler]
+    L1 --> L2[Return]
+    C -- No --> F[Inject bindingDefaultsDb + enrich memories]
+
+    F --> G{includeContextInPrompt === true?}
+    G -- No --> I[Context empty]
+    G -- Yes --> J[Build context markdown]
+    I --> P
+    J --> P{executionPipeline?}
+
+    P -- Yes --> P1[PRE: synthesized-context only]
+    P1 --> P2[MAIN]
+    P2 --> P3[POST optional]
+    P3 --> K[Gateway execute]
+    P -- No --> K
+
+    K --> M{Missing skill?}
+    M --> R[Response]
+    H4 --> R
+    L2 --> R
+```
+
+## Step-by-Step Behavior
+
+1. Receive `runTask` request with `skillKey`, `input`, memory fields, and optional execution settings.
+2. Resolve **`narrixMode`**, **`inputStrategyKey`**, and **`executionStrategies`** (`resolveRunTaskRuntimeKnobs` / `resolveExecutionStrategies`) — independent dimensions; legacy wiring maps into `narrixMode`.
+3. If **`narrixMode === "preprocessor"`** and `request.narrix` is set, run the task-level Narrix pre-processor:
+   - Resolve the raw record from `executionMemory`, `jobMemory`, or `input`.
+   - Run Narrix (ingest + runner).
+   - Attach result to `executionMemory._narrix` (or configured field) and mirror to `jobMemory._narrix`.
+   - If `narrix.enableWebScope` is `true`, run web scoping and store result in `executionMemory.webContext`.
+4. Else if **`narrixMode === "handler"`**, run structured Narrix from `narrixInput` (same behavior as legacy `narrix-then-direct` Narrix phase), **before** local tasks and pipeline PRE.
+5. Check local task registry for `skillKey`.
+6. If local handler exists, execute it and return immediately (skip enrichment/LLM path).
+7. Inject `bindingDefaultsDb` routing default.
+8. Enrich memory bundle with task-scoped enrichment.
+9. Build prompt context only when `includeContextInPrompt === true`:
+   - With Narrix in play: use Narrix context markdown and optional web evidence markdown.
+   - Without Narrix in play: use generated context markdown plus any `taskMemory.narrix` section.
+10. Build enriched executor input.
+11. Execute:
+    - If `executionPipeline` exists: run PRE steps, one MAIN step, then POST steps.
+    - Otherwise run direct MAIN execution path.
+12. If content/skill is missing, invoke registry diagnostics via not-found handler.
+13. Return final response (`rawText`, `parsed`, `metadata`, optional `intermediateSteps`).
+
+## Notes
+
+- Default execution is effectively direct when no pipeline is provided.
+- Local tasks are deterministic and bypass LLM execution.
+- Web scoping is non-fatal: Narrix attachment can still succeed when web scope misses/fails.
+- POST steps (`audit`, `polish`) run only when declared in `executionPipeline`.
+- For PRE `synthesized-context`, structured mode is additive and template-core-aware (`templateCores` + question), while markdown mode remains available for backward compatibility.
+- Structured core discovery is pre-render from raw instructions/prompt templates and expects core directives in `{{core:...}}` form.
+- PRE `synthesized-context` can control synthesizer input via `SynthesisConfig.synthesisInputStrategy` (`policy`, `execution-memory-only`, `job-memory-only`, `task-memory-only`, `full-memory-bundle`).
+- Pipeline responses expose synthesis audit metadata (`synthesisEnabled`, `effectiveExecutionPipeline`, `synthesizedContextPresent`, `mainContextSource`, `detectedTemplateCores`) and normalized execution state (`executionMemory`, `executionState.executionMemory`).
+
+## Pipeline semantics (context vs input, PRE/POST, and response shape)
+
+These details matter for orchestrators and for debugging “why doesn’t my synthesis show up in `input`?”
+
+### Supported `executionPipeline` step types (runtime)
+
+- **PRE:** Only `synthesized-context` (`SYNTHESIZED_CONTEXT`) is executed. The runner processes PRE steps in order but **stops after the first** matching synthesized-context step (`break`). Other `phase: "pre"` step types **throw** at runtime.
+- **MAIN:** Exactly one step with `phase: "main"` — otherwise `runTask` **throws** (existing rule).
+- **POST:** Only `audit` and `polish` are executed when their `type` matches. Other `phase: "post"` types are **not executed** (no error today).
+
+If you need a new PRE/POST kind, extend `runTask` in `task-sdk.ts`.
+
+### Catalox, Xynthesis, and pipeline metadata (no extra logic in ai-tasks)
+
+PRE/POST step identifiers and related configuration are expected to stay **aligned with Catalox content** that owns that metadata. Xynthesis and the catalog layer keep that data consistent; callers and upper layers that build `executionPipeline` from the **same shared metadata** should already see the correct step list. **`@exellix/ai-tasks` does not re-validate or re-sync Catalox IDs** here — it only implements the execution paths above. Use tests or upstream tooling if you need to assert catalog shape beyond what `runTask` runs.
+
+### Synthesis output vs skill `input`
+
+When a PRE `synthesized-context` step runs, its markdown (or structured artifact rendered to markdown) becomes **`overrideContext`** for the MAIN pass. In `_executeDirect`, that value is assigned to **`context`** on the object passed to the executor — **not** to `input`.
+
+- **`input`:** Still the task request’s payload (plus optional `aiScoped` merges when AI scoping is enabled).
+- **`context`:** Prompt context markdown (synthesis when configured, otherwise legacy/Narrix/scoping-generated context). After synthesis, `appendExternalWebContextMarkdown` may **append** additional web context, so the string MAIN sees can be **synthesis + web**, not necessarily identical to `executionMemory.synthesizedContext.contextMarkdown` alone.
+
+### POST steps and captured context
+
+- **Audit** always receives the **same** context string that was captured for MAIN (`capture.contextMarkdown` after MAIN context preparation), and on **audit re-run cycles** the evaluator’s `promptContext` tracks the **effective** context MAIN used for the candidate being scored (including feedback-injected re-runs).
+- **Polish** receives `currentOutput` (MAIN output or output after prior POST steps). It only receives that captured context as `promptContext` when polish config sets **`includeOriginalContext: true`**; otherwise polish does not see synthesis/context markdown.
+
+### Response after POST steps
+
+When any POST step runs, the SDK sets both **`rawText`** and **`parsed`** to the final string pipeline output (`currentOutput`). If MAIN returned structured **`parsed`** (e.g. JSON object), that object is **replaced** by the POST text output. Consumers that need the original structured MAIN result must retain it from an earlier response or store it outside this final shape.
+
+### PRE Xynthesis only with a pipeline
+
+Without an `executionPipeline` that includes PRE `synthesized-context`, **no** PRE synthesis path runs; MAIN uses the normal direct context path (legacy context markdown, Narrix, etc.). The same `skillKey` can therefore behave differently depending only on whether a pipeline is present.
+
+### Diagram: pipeline data flow (actual)
+
+```mermaid
+flowchart LR
+  subgraph pre [PRE]
+    SC[synthesized-context]
+    SC --> CM[contextMarkdown]
+  end
+  subgraph main [MAIN]
+    S[executor.execute]
+  end
+  subgraph post [POST]
+    A[audit / polish]
+  end
+  CM -->|"overrideContext + optional web append"| CTX[context]
+  CTX --> S
+  INP[input] --> S
+  CTX -->|"capture.contextMarkdown"| A
+  S -->|"rawText / parsed"| A
+  A -->|"final string"| OUT[rawText and parsed]
+```
+
+## Diagnostics, trace mode, and observability digest
+
+**Current `runTask` implementation (`task-sdk.ts`)** does **not** implement **`request.diagnostics`**, **`appendRunLog`**, **`RunLogEntry` buffering**, or a Logxer-shaped sink on the request. Orchestrators that merge **`runLog`** / **`exellixRunLog`** / **`logxerRunId`** / **`logxerCorrelationId`** into **`response.metadata`** own that contract — see [.docs/investigation/external-packages-assignments.md](../.docs/investigation/external-packages-assignments.md).
+
+- **`executionMode: "trace"`**: forwards trace-related flags to **`@exellix/ai-skills`** `runSkill`; see **`RunSkillDiagnostics`** / **`SkillDiagnosticsTrace`** on that package. Structured **SDK log lines** use **`@x12i/logxer`** from ai-skills execution — not the orchestrator run-log row shape.
+- **`extractAiTasksObservabilityFromRunTaskResponse`**: builds a versioned **`AiTasksObservabilityDigest`** from `metadata` + execution memory for graph UIs (optional attachment).
+- **`response.aiTasksObservability`**: not set by the SDK by default; orchestrators may attach the digest from the extractor.
+
+**Future:** if **`request.diagnostics` / `appendRunLog`** are added to **`@exellix/ai-tasks`**, update this section and **`RUNTASK_REQUEST.md`** together.

package/documenations/run-task-single-run-checklist.md

@@ -0,0 +1,109 @@
+# Checklist: `@exellix/ai-tasks` — single `runTask` validation
+
+**Scope:** One task node, end-to-end: validate a single `runTask` execution with structured synthesis and MAIN consumption.
+
+**Package context:** PRE steps can include `synthesized-context`; MAIN runs after PRE. Observability is attached on the response as `metadata` (and `meta` alias), including flags such as `synthesizedContextPresent`, `mainContextSource`, and `detectedTemplateCores`.
+
+## Design stance: no backward compatibility
+
+**Backward compatibility with legacy context assembly is not a goal for this stack.** The checklist assumes structured synthesis and MAIN consumption of `executionMemory.synthesizedContext` as the normal, required path.
+
+Today **only one package upstream** still relies on legacy behavior; that integration is expected to be corrected there using this document as the contract for what “good” looks like. Do not preserve or design around legacy paths for other callers—there are none.
+
+Legacy signals in code or metadata (for example `mainContextSource === "legacy"`, primary `webContextMarkdown`, raw Narrix-as-context) are **diagnostics only** (misconfiguration or upstream not yet aligned with this checklist). They are **not** pass criteria and **not** a surface we commit to keeping stable.
+
+---
+
+## 1. Template core detection
+
+| # | Check | How to validate | Pass |
+|---|--------|-----------------|------|
+| 1.1 | Resolved template is the real source of task semantics | Trace which template/skill resolved for the run; confirm it matches the intended task definition (not a stale or default template). | |
+| 1.2 | Core tokens come from the **template**, not from free-form request input | Inspect core discovery path: cores should be derived from rendered template content (e.g. `discoverTemplateCores`), not from arbitrary client fields unless explicitly documented. | |
+| 1.3 | Detected core set is visible in logs, traces, or debug output | Confirm `detectedTemplateCores` (or equivalent) appears in tracing/phase metadata or debug logs for the PRE step. | |
+| 1.4 | Behavior when **no** core tokens are found | Run a template with no detectable cores; document expected behavior (empty `templateCores`, synthesis contract, warnings). No silent mis-assumption that cores exist. | |
+| 1.5 | **Multiple** cores preserved | Template with several cores → artifact / observability lists all distinct cores, order stable or documented. | |
+
+---
+
+## 2. Structured synthesis execution
+
+| # | Check | How to validate | Pass |
+|---|--------|-----------------|------|
+| 2.1 | PRE synthesized-context **actually runs** | Trace `phase: pipeline_pre`, `preStepType: synthesized-context` (or equivalent) completes without skip. | |
+| 2.2 | Synthesis runs **before** MAIN | Ordering: PRE steps complete, `executionMemory` updated, then MAIN step executes. | |
+| 2.3 | Synthesis input includes | Verify synthesizer payload / source material includes: **resolved question**; **detected template core set**; **raw/enriched local context**; **raw/enriched supporting context** (per `contextSourcePolicy` / `synthesisInputStrategy`). | |
+| 2.4 | Synthesis goes through **ai-gateway** | Network/trace shows gateway route for the synthesis model call, not a bypass. | |
+| 2.5 | Effective mode is **structured**, not fallback markdown assembly | `synthesisMode` / `synthesisOutputFormat` resolves to structured path; response parses as structured payload (e.g. validated JSON contract), not only legacy section markdown. | |
+
+---
+
+## 3. Synthesized artifact creation
+
+| # | Check | How to validate | Pass |
+|---|--------|-----------------|------|
+| 3.1 | `executionMemory.synthesizedContext` is produced | Inspect `request`/`result` execution memory after PRE. | |
+| 3.2 | Exists **after PRE** and **before MAIN** | Breakpoint or ordered logs: artifact present when MAIN starts. | |
+| 3.3 | Shape is **structured** (not “only markdown”) | Artifact has structured fields (e.g. validated `payload`, `templateCores`), not solely a prose blob. | |
+| 3.4 | Meaningful **synthesized** local/supporting outputs | Content is distilled/structured per contract, not a verbatim dump of raw Narrix/web/memory. | |
+| 3.5 | **Canonical** key; no duplicate competing keys | Single authoritative `synthesizedContext` on `executionMemory`; no shadow copies under undocumented alternate paths. | |
+
+---
+
+## 4. MAIN input path
+
+| # | Check | How to validate | Pass |
+|---|--------|-----------------|------|
+| 4.1 | MAIN consumes `executionMemory.synthesizedContext` | Code path / logs: MAIN context build reads the artifact. | |
+| 4.2 | MAIN does **not** primarily rely on legacy assembled context | When structured path is active, dominance is not `webContextMarkdown`, raw Narrix markdown, or raw dumps alone. | |
+| 4.3 | Final prompt/messages to MAIN **reflect** synthesized payload | Diff or capture: sections/content align with structured synthesis output (e.g. built markdown from structured payload if that’s the bridge). | |
+| 4.4 | No **silent** fallback to old prompt construction | For runs that should pass this checklist, `mainContextSource === "legacy"` means the integration is wrong—fix upstream (request shape, pipeline, flags), not paper over it. Silent degradation without observable flags is unacceptable. | |
+
+---
+
+## 5. Local-first behavior
+
+| # | Check | How to validate | Pass |
+|---|--------|-----------------|------|
+| 5.1 | Synthesized output **prioritizes** task/local/runtime facts over supporting web | Ordering and emphasis in structured local vs supporting sides; policy matches product intent. | |
+| 5.2 | Final answer **reflects** runtime-grounded facts first | Answer cites or follows execution/task memory before generic web summaries when both exist. | |
+| 5.3 | Not generic “public summary” when local should dominate | Deliberate fixture: strong local signal + web noise → answer anchored locally. | |
+| 5.4 | Supporting context stays **supportive** | Web/supporting material does not override or swamp local conclusions. | |
+
+---
+
+## 6. Reporting and observability
+
+| # | Check | How to validate | Pass |
+|---|--------|-----------------|------|
+| 6.1 | Reports show whether **synthesis ran** | e.g. `synthesisEnabled`, pipeline/effective pipeline, or PRE phase completion in report payload. | |
+| 6.2 | Reports expose **detected template cores** | e.g. `detectedTemplateCores` in `metadata` / report mirror. | |
+| 6.3 | Reports show **`synthesizedContext` created** | e.g. `synthesizedContextPresent`. | |
+| 6.4 | Reports show **MAIN used synthesized input** | e.g. `mainContextSource === "synthesizedContext"` (and related flags if any). | |
+| 6.5 | If missing in reports, classify **reporting gap vs runtime failure** | Compare raw trace/logs to report: runtime correct but UI/report omits field → omission only; no artifact in memory but report says OK → failure. | |
+
+---
+
+## 7. Pass criteria (single `runTask`)
+
+A single run **passes** only if **all** are true:
+
+1. **PRE synthesis ran** — synthesized-context PRE completed as intended.
+2. **Template cores were detected** — non-empty when the template defines detectable cores; empty case matches documented behavior for that template.
+3. **`executionMemory.synthesizedContext` exists** — structured artifact present before MAIN.
+4. **MAIN used synthesized payload** — `mainContextSource` (or equivalent) indicates synthesized path, not unintended legacy.
+5. **Observability shows that clearly** — synthesis, cores, artifact presence, and MAIN source are visible in metadata/traces/reports.
+6. **Final output is task-grounded and local-first** — answer quality matches sections 4–5 for the fixture used.
+
+---
+
+## Quick reference (response `metadata`)
+
+When validating, confirm at least:
+
+- `detectedTemplateCores`
+- `synthesizedContextPresent`
+- `mainContextSource` (`"synthesizedContext"` vs `"legacy"`)
+- `synthesisEnabled` / `effectiveExecutionPipeline` as appropriate for your environment
+
+Treat `"legacy"` `mainContextSource` when a synthesized PRE ran and an artifact exists as a **red flag**: fix the caller (the remaining upstream package should converge on this checklist), not `ai-tasks`.