@exellix/ai-tasks 7.8.0

package/documenations/schemas/README.md

@@ -0,0 +1,40 @@
+# Integrator schema fragments (`@exellix/ai-tasks`)
+
+Versioned **JSON Schema (draft 2020-12)** and an **OpenAPI 3.1** component bundle for gateways and graph docs. They mirror TypeScript types in this package; source of truth remains `src/types/task-types.ts` and `src/utils/outputValidation.ts`.
+
+## Layout
+
+| File | Purpose |
+|------|---------|
+| [v1/output-schema.json](./v1/output-schema.json) | `RunTaskRequest.outputValidation.schema` (`OutputSchema`). Alias in specs: **outputConstraints** → same shape. |
+| [v1/output-validation-result.json](./v1/output-validation-result.json) | `response.metadata.outputValidation` (`OutputValidationResult`). |
+| [v1/synthesized-artifacts.json](./v1/synthesized-artifacts.json) | `executionMemory.synthesizedContext` / `synthesizedInput` after PRE `synthesized-context`. Root schema: `ExecutionMemorySynthesisFields`. |
+| [openapi-3.1-components.yaml](./openapi-3.1-components.yaml) | OpenAPI `components.schemas` embedding the JSON files (paths empty). |
+
+## Stable URLs
+
+Replace `<TAG>` with a release tag or commit SHA:
+
+- `https://raw.githubusercontent.com/woroces/ai-tasks/<TAG>/documenations/schemas/v1/output-schema.json`
+- `https://raw.githubusercontent.com/woroces/ai-tasks/<TAG>/documenations/schemas/v1/output-validation-result.json`
+- `https://raw.githubusercontent.com/woroces/ai-tasks/<TAG>/documenations/schemas/v1/synthesized-artifacts.json`
+
+## `correlationId` (output validation)
+
+`OutputValidationResult.correlationId` is **optional**. On `runTask()`, the runtime usually sets it from the same id as `metadata.taskId`. It may be **absent** when:
+
+- Only `validateParsedOutput()` is used (no response envelope), or
+- A consumer merges partial responses and drops `metadata.taskId`.
+
+Graph consumers should branch on `errors[]` / `ok`, not on `correlationId` being present.
+
+## Persistence (PRE artifacts)
+
+**Canonical response path for merged execution memory:** read **`response.executionMemory`**. The runtime sets **`response.executionState.executionMemory`** to the **same object** for nested execution-state patterns; prefer the top-level field for simple persistence.
+
+Align stored JSON with **`@xronoces/xmemory-contracts`** row shapes when mapping `executionMemory` columns (see that package for column names).
+
+## Related docs
+
+- [structured-decision-contract.md](../../docs/structured-decision-contract.md) — `outputValidation`, `parsed`
+- [synthesized-context-guide.md](../synthesized-context-guide.md) — PRE synthesis behavior

package/documenations/schemas/openapi-3.1-components.yaml

@@ -0,0 +1,24 @@
+# OpenAPI 3.1 component bundle for @exellix/ai-tasks integrators.
+# Embed `components.schemas` into your gateway or graph OpenAPI document.
+# JSON equivalents live alongside under v1/*.json (draft 2020-12).
+
+openapi: 3.1.0
+info:
+  title: "@exellix/ai-tasks — schema fragments"
+  version: "1.0.0"
+  description: |
+    Not a runnable API — reusable schemas only.
+    Paths are intentionally empty.
+
+paths: {}
+
+components:
+  schemas:
+    OutputSchema:
+      $ref: "./v1/output-schema.json"
+    OutputValidationResult:
+      $ref: "./v1/output-validation-result.json"
+    ExecutionMemorySynthesisFields:
+      $ref: "./v1/synthesized-artifacts.json#/$defs/ExecutionMemorySynthesisFields"
+    RunTaskRequestSubset:
+      $ref: "./v1/run-task-request.json"

package/documenations/schemas/v1/output-schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/woroces/ai-tasks/main/documenations/schemas/v1/output-schema.json",
+  "title": "OutputSchema",
+  "description": "Minimal recursive schema language for RunTaskRequest.outputValidation.schema. Matches TypeScript OutputSchema in @exellix/ai-tasks (not full JSON Schema).",
+  "$defs": {
+    "OutputSchema": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": { "type": { "const": "any" } },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": {
+            "type": { "enum": ["string", "number", "boolean", "null"] }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": {
+            "type": { "const": "array" },
+            "items": { "$ref": "#/$defs/OutputSchema" },
+            "minItems": { "type": "integer", "minimum": 0 },
+            "maxItems": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": {
+            "type": { "const": "object" },
+            "properties": {
+              "type": "object",
+              "additionalProperties": { "$ref": "#/$defs/OutputSchema" }
+            },
+            "required": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "additionalProperties": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  },
+  "$ref": "#/$defs/OutputSchema"
+}

package/documenations/schemas/v1/output-validation-result.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/woroces/ai-tasks/main/documenations/schemas/v1/output-validation-result.json",
+  "title": "OutputValidationResult",
+  "description": "Attached at response.metadata.outputValidation when output validation runs. correlationId is set by the runTask runtime when it attaches a task id; it may be absent when using validateParsedOutput() alone or in partial response merges.",
+  "type": "object",
+  "required": ["ok", "errors"],
+  "properties": {
+    "ok": { "type": "boolean" },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "message", "code"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Path under validated value, e.g. parsed.foo[0] (root label is parsed)."
+          },
+          "message": { "type": "string" },
+          "code": {
+            "type": "string",
+            "enum": [
+              "TYPE_MISMATCH",
+              "MISSING_REQUIRED",
+              "MIN_ITEMS",
+              "MAX_ITEMS",
+              "ADDITIONAL_PROPERTY"
+            ]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "correlationId": {
+      "type": "string",
+      "description": "When present on runTask responses, aligns with metadata.taskId for that invocation. Optional: may be omitted if the consumer only has validateParsedOutput output, or if metadata.taskId is not propagated."
+    }
+  },
+  "additionalProperties": false
+}

package/documenations/schemas/v1/run-task-request.json

@@ -0,0 +1,219 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/exellix/ai-tasks/main/documenations/schemas/v1/run-task-request.json",
+  "title": "RunTaskRequest",
+  "description": "Canonical wire/SDK shape for runTask(). Hosts compile TaskNode authoring (taskConfiguration, inputsConfig, taskVariable, jobVariables/taskVariables buckets) into these fields before invoke.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["skillKey", "agentId", "jobTypeId", "taskTypeId", "executionStrategies"],
+  "properties": {
+    "skillKey": { "type": "string", "minLength": 1 },
+    "agentId": { "type": "string", "minLength": 1 },
+    "jobTypeId": { "type": "string", "minLength": 1 },
+    "taskTypeId": { "type": "string", "minLength": 1 },
+
+    "jobId": { "type": "string" },
+    "taskId": { "type": "string" },
+    "identity": { "type": "object", "additionalProperties": true },
+
+    "executionMode": { "type": "string", "enum": ["default", "trace"] },
+
+    "executionPipeline": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ExecutionStep" }
+    },
+
+    "narrixMode": { "type": "string", "description": "Narrix invocation: off | preprocessor | handler (catalog keys)." },
+    "inputStrategyKey": { "type": "string" },
+
+    "executionStrategies": {
+      "type": "array",
+      "description": "Required. FuncX wrappers around MAIN: planner (before) and optimizer (after). Use [] for plain MAIN.",
+      "items": { "$ref": "#/$defs/ExecutionStrategyInvocation" }
+    },
+
+    "executionStrategyCatalogItems": {
+      "type": "array",
+      "description": "Optional Catalox catalog rows; runtime uses allowlisted fields after validation.",
+      "items": { "type": "object", "additionalProperties": true }
+    },
+
+    "executionMemory": {
+      "type": "object",
+      "description": "Execution-scoped blob including jobVariables (whole run) and taskVariables (current node) when graph-engine 5.13+ compiles the request.",
+      "additionalProperties": true
+    },
+    "narrix": { "type": "object", "additionalProperties": true },
+    "narrixInput": {
+      "description": "Structured Narrix input or jobMemory path wrapper.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "$path": { "type": "string", "minLength": 1 }
+          },
+          "required": ["$path"],
+          "additionalProperties": false
+        },
+        { "type": "object", "additionalProperties": true }
+      ]
+    },
+    "narrixScope": { "type": "object", "additionalProperties": true },
+
+    "input": {
+      "description": "Task payload (compiled from inputsConfig + taskVariable on graph nodes).",
+      "oneOf": [{ "type": "string" }, { "type": "object", "additionalProperties": true }]
+    },
+    "variables": {
+      "type": "object",
+      "description": "Job/graph template bucket only (mirrors executionMemory.jobVariables). Node scope uses executionMemory.taskVariables.",
+      "additionalProperties": true
+    },
+    "jobContext": { "type": "object", "additionalProperties": true },
+    "jobMemory": { "type": "object", "additionalProperties": true },
+    "taskMemory": { "type": "object", "additionalProperties": true },
+
+    "xynthesized": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "job": { "type": "object", "additionalProperties": true },
+        "task": { "type": "object", "additionalProperties": true },
+        "execution": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "smartInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["paths"],
+      "properties": {
+        "paths": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SmartInputPathEntry" }
+        },
+        "strict": { "type": "boolean" }
+      }
+    },
+    "smartInputRenderOptions": { "type": "object", "additionalProperties": true },
+
+    "modelConfig": { "type": "object", "additionalProperties": true },
+    "llmCall": { "type": "object", "additionalProperties": true },
+    "timeoutMs": { "type": "number" },
+
+    "includeContextInPrompt": { "type": "boolean" },
+
+    "taskConfiguration": {
+      "type": "object",
+      "description": "Graph node taskConfiguration blob (compile-only). Mapped to executionPipeline at runTask entry.",
+      "additionalProperties": true
+    },
+
+    "aiScoping": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": true }
+    },
+    "aiScopingOptions": { "type": "object", "additionalProperties": true },
+
+    "taskKind": { "type": "string", "enum": ["decision", "utility", "content"] },
+    "outputValidation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema"],
+      "properties": {
+        "schema": { "$ref": "#/$defs/OutputSchema" },
+        "mode": { "type": "string", "enum": ["fail", "warn"] },
+        "validateWhenMissing": { "type": "boolean" }
+      }
+    },
+    "autoValidateDecisionOutput": { "type": "boolean" },
+
+    "templateTokens": { "type": "object", "additionalProperties": true },
+    "templateRenderOptions": { "type": "object", "additionalProperties": true },
+
+    "coreSkillId": { "type": "string" },
+    "graphId": { "type": "string" },
+    "nodeId": { "type": "string" },
+    "prevNodeId": { "type": "string" },
+    "masterSkillId": { "type": "string" },
+    "masterSkillActivityId": { "type": "string" },
+
+    "diagnostics": { "type": "object", "additionalProperties": true }
+  },
+  "$defs": {
+    "SmartInputPathEntry": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["title", "path"],
+          "properties": {
+            "title": { "type": "string", "minLength": 1 },
+            "path": { "type": "string", "minLength": 1 },
+            "required": { "type": "boolean" }
+          }
+        }
+      ]
+    },
+    "ExecutionStrategyInvocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["strategyKey", "phase", "priority"],
+      "properties": {
+        "strategyKey": { "type": "string", "enum": ["planner", "optimizer"] },
+        "phase": { "type": "string", "enum": ["before", "after"] },
+        "priority": { "type": "number" },
+        "maxIterations": { "type": "integer", "minimum": 1, "description": "Optimizer only." },
+        "args": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "ExecutionPhase": { "type": "string", "enum": ["pre", "main", "post"] },
+    "ExecutionStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["phase", "type"],
+      "properties": {
+        "phase": { "$ref": "#/$defs/ExecutionPhase" },
+        "type": { "type": "string", "minLength": 1 },
+        "config": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "OutputSchema": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type"],
+          "properties": {
+            "type": { "type": "string", "enum": ["any", "string", "number", "boolean", "null"] }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type"],
+          "properties": {
+            "type": { "const": "array" },
+            "items": { "$ref": "#/$defs/OutputSchema" },
+            "minItems": { "type": "integer", "minimum": 0 },
+            "maxItems": { "type": "integer", "minimum": 0 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type"],
+          "properties": {
+            "type": { "const": "object" },
+            "properties": {
+              "type": "object",
+              "additionalProperties": { "$ref": "#/$defs/OutputSchema" }
+            },
+            "required": { "type": "array", "items": { "type": "string" } },
+            "additionalProperties": { "type": "boolean" }
+          }
+        }
+      ]
+    }
+  }
+}

package/documenations/schemas/v1/synthesized-artifacts.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/woroces/ai-tasks/main/documenations/schemas/v1/synthesized-artifacts.json",
+  "title": "PRE synthesis executionMemory artifacts",
+  "description": "Shapes stored at executionMemory.synthesizedContext and executionMemory.synthesizedInput after a synthesized-context PRE step. Align persisted JSON with @xronoces/xmemory-contracts row fields when mapping execution memory to storage.",
+  "$defs": {
+    "TaskCore": {
+      "type": "string",
+      "enum": [
+        "question",
+        "action",
+        "plan",
+        "objective",
+        "decision",
+        "comparison",
+        "classification",
+        "evaluation",
+        "analysis",
+        "summary",
+        "generation",
+        "extraction"
+      ]
+    },
+    "SynthesisMode": {
+      "type": "string",
+      "enum": ["markdown", "structured"]
+    },
+    "SynthesizedContextArtifact": {
+      "type": "object",
+      "required": ["templateCores", "question", "mode", "payload", "contextMarkdown"],
+      "properties": {
+        "templateCores": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/TaskCore" }
+        },
+        "question": { "type": "string" },
+        "mode": { "$ref": "#/$defs/SynthesisMode" },
+        "payload": { "description": "Structured payload or markdown marker object; runtime-defined." },
+        "contextMarkdown": {
+          "type": "string",
+          "description": "Markdown fed to MAIN when synthesis is authoritative."
+        }
+      },
+      "additionalProperties": false
+    },
+    "QuestionDrivenAnswer": {
+      "type": "object",
+      "required": ["question", "source", "synthesis"],
+      "properties": {
+        "question": { "type": "string" },
+        "source": { "enum": ["record", "web", "both"] },
+        "synthesis": { "type": "string" },
+        "evidence": {
+          "type": "object",
+          "properties": {
+            "recordPaths": { "type": "array", "items": { "type": "string" } },
+            "webScopeIds": { "type": "array", "items": { "type": "string" } },
+            "sources": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "url": { "type": "string" },
+                  "title": { "type": "string" }
+                },
+                "additionalProperties": true
+              }
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "QuestionDrivenSynthesizedContext": {
+      "type": "object",
+      "required": ["mode"],
+      "properties": {
+        "mode": { "const": "questionDriven" },
+        "contextMarkdown": {
+          "type": "string",
+          "description": "Same body MAIN uses; required for persistence and reuseCachedSynthesizedContext."
+        },
+        "record": { "type": "object", "additionalProperties": true },
+        "web": { "type": "object", "additionalProperties": true },
+        "answers": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/QuestionDrivenAnswer" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "AnySynthesizedContextArtifact": {
+      "oneOf": [
+        { "$ref": "#/$defs/SynthesizedContextArtifact" },
+        { "$ref": "#/$defs/QuestionDrivenSynthesizedContext" }
+      ]
+    },
+    "SynthesizedInputArtifact": {
+      "type": "object",
+      "required": ["synthesisMode", "sourceMaterial"],
+      "properties": {
+        "synthesisMode": {
+          "type": "string",
+          "enum": ["markdown", "structured", "questionDriven"]
+        },
+        "sourceMaterial": {
+          "type": "string",
+          "description": "Resolved PRE source material; may be truncated per SYNTHESIZED_INPUT_MAX_CHARS."
+        },
+        "localMarkdown": { "type": "string" },
+        "supportingMarkdown": { "type": "string" },
+        "question": { "type": "string" },
+        "templateCores": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/TaskCore" }
+        },
+        "truncated": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "ExecutionMemorySynthesisFields": {
+      "type": "object",
+      "description": "Typical keys on executionMemory after PRE synthesized-context. Map these to xmemory-contracts persistence columns as needed.",
+      "properties": {
+        "synthesizedContext": { "$ref": "#/$defs/AnySynthesizedContextArtifact" },
+        "synthesizedInput": { "$ref": "#/$defs/SynthesizedInputArtifact" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "$ref": "#/$defs/ExecutionMemorySynthesisFields"
+}

package/documenations/synthesis-invocation-notes.md

@@ -0,0 +1,26 @@
+# Synthesis Invocation Notes
+
+This appendix clarifies that synthesized-context uses a real model invocation.
+
+## Confirmed behavior
+
+- Source-material assembly is deterministic in runtime code.
+- The synthesis step then calls the model through gateway invocation.
+- This is not a pure string merge or template concatenation step.
+
+## Why this matters
+
+- Cost and latency include an additional LLM call before MAIN execution.
+- Reliability depends on synthesis model behavior and timeout settings.
+- Structured mode adds validation/parsing requirements.
+
+## Operational guidance
+
+- Tune synthesis model independently from MAIN model.
+- Use timeout/output-length caps to control risk.
+- Use `fallbackToDirect` when resiliency is preferred over strict synthesis dependency.
+
+## Related appendices
+
+- `documenations/synthesized-context-guide.md`
+- `documenations/run-task-execution-flow.md`

package/documenations/synthesized-context-guide.md

@@ -0,0 +1,84 @@
+# Synthesized Context Guide
+
+This appendix explains the `synthesized-context` PRE step in `executionPipeline`.
+
+## Goal
+
+Generate a synthesized `context` string (or structured output transformed to markdown) before the MAIN task step runs.
+
+## Pipeline placement
+
+- Phase: `pre`
+- Type: `synthesized-context`
+- Runs before MAIN (`direct`)
+
+## Inputs
+
+- `SynthesisConfig` on PRE-step `config`
+- Enriched memory bundle (job/task/execution) plus request-level **`xynthesized`** and **`smartInput`** for template rendering (same fields as MAIN). Template path prefixes **`jobVariables.*`** / **`taskVariables.*`** (on `executionMemory`) are preferred over legacy **`variables.*`** (job scope).
+- Optional Narrix attachment and web evidence
+- Rendered task templates/instructions
+
+## Key controls
+
+- `contextSourcePolicy`: `auto`, `narrix-web`, `narrix-web-memory`, `memory-web`, `memory-only`
+- `synthesisInputStrategy`: controls what raw input is fed into the synthesizer
+  - `policy` (default): use `contextSourcePolicy`
+  - `execution-memory-only`
+  - `job-memory-only`
+  - `task-memory-only`
+  - `full-memory-bundle`
+- `webEvidence`: web-evidence shaping/caps
+- `modelConfig`, `timeoutMs`, `maxOutputLength`
+- `synthesisMode`: `markdown` or `structured` (preferred additive selector)
+- `synthesisOutputFormat`: `markdown` or `structured`
+- `fallbackToDirect`: return empty synthesized context on synthesis failure when enabled
+- `questionDriven`: when `true`, runs multi-question synthesis and stores answers under `executionMemory.synthesizedContext.answers`
+- `questions`: array of `{ id, question, source?: "record" | "web" | "both" }` (effective only when `questionDriven: true`)
+- `reuseCachedSynthesizedContext`: when `true`, skips the PRE synthesis LLM call if `executionMemory.synthesizedContext` already has a valid `contextMarkdown` (including question-driven artifacts). Opt-in; callers must ensure cache validity.
+- `xynthesizedOutput` (optional): writes the synthesis result under `RunTaskRequest.xynthesized.job[outputKey]`, `.task[outputKey]`, or `.execution[outputKey]` and returns `RunTaskResponse.xynthesizedPatch` for graph-engine merge. Fields: `destination` (`job` | `task` | `execution`), `outputKey`, optional `mode` (`replace` | `merge`), optional `alsoWriteLegacySynthesizedContext` (omit or `true`: keep persisting `executionMemory.synthesizedContext` / `synthesizedInput`; `false`: skip that legacy persistence for this PRE step). Template/rendering bundle includes `xynthesized` and `smartInput` from the request. Smart-input paths may reference `xynthesized.execution.*` when the execution bucket is present on the request. See README **Xynthesized memory and smart input**.
+- Template core directives in instructions/prompt (`{{core:...}}`): structured synthesis derives task semantics from declared cores
+
+## Template cores
+
+Template core directives map to a closed-list task shape used by structured synthesis:
+
+- `question`, `action`, `plan`, `objective`, `decision`, `comparison`
+- `classification`, `evaluation`, `analysis`, `summary`, `generation`, `extraction`
+
+In structured mode, synthesis uses detected `templateCores` and resolved question to prioritize what is relevant for MAIN execution. Core discovery is pre-render and uses raw templates resolved through `ai-skills.resolveRawTemplate(...)`. If no core directives are declared in template content, synthesis is rejected as a template-definition error.
+`RunTaskRequest.taskCore` is intentionally not part of this flow.
+
+Core discovery runs against the **raw** (pre-render) template content in **both** `markdown` and `structured` modes. In structured mode, at least one core directive is required (synthesis is rejected as a template-definition error if none are found and the template is non-empty). In markdown mode, detected cores are reported in `metadata.detectedTemplateCores` and `executionMemory.synthesizedContext.templateCores` but do not alter synthesizer behaviour.
+
+## Output
+
+- Returns synthesized context markdown used as MAIN-step `context`.
+- In structured mode, output is validated then converted to markdown.
+- In **both** structured and markdown modes, runtime stores a synthesized artifact under `executionMemory.synthesizedContext` (markdown uses `mode: "markdown"` with a small `payload` marker; `templateCores` is populated from the raw template in both modes — it is `[]` only when the template contains no `{{core:...}}` directives or the template could not be resolved).
+- In **question-driven** mode, runtime stores a structured artifact under `executionMemory.synthesizedContext` with `mode: "questionDriven"` and `answers[questionId].synthesis` as the stable access path for templates and mappings. The artifact also includes `contextMarkdown` (same body MAIN uses) for persistence and cache reuse. Evidence fields are best-effort and may be omitted when inputs are unavailable.
+- After PRE, **`executionMemory.synthesizedInput`** holds resolved source material (`SynthesizedInputArtifact`: `synthesisMode`, `sourceMaterial`, `localMarkdown`, `supportingMarkdown`, etc.) for gateways that persist without log scraping. Env **`SYNTHESIZED_INPUT_MAX_CHARS`** (default `200000`) caps `sourceMaterial` size.
+- When MAIN runs from that artifact, empty synthesized context is kept empty (Narrix/web markdown is not substituted as a fallback).
+- Final response includes execution-state + synthesis observability fields for auditing:
+  - `metadata.synthesisEnabled` (and `meta` — same object reference as `metadata` for checklist-style consumers)
+  - `metadata.effectiveExecutionPipeline`
+  - `metadata.synthesizedContextPresent`
+  - `metadata.mainContextSource`
+  - `metadata.detectedTemplateCores`
+  - `metadata.synthesisMode` — `"markdown"` or `"structured"`; present when a PRE synthesis step ran
+  - `executionMemory` and `executionState.executionMemory`
+
+### Persistence path and schemas
+
+**Canonical JSON path for merged PRE artifacts:** **`response.executionMemory`** (same object as **`response.executionState.executionMemory`**; prefer the top-level field for gateways). Versioned JSON Schema for **`synthesizedContext`** / **`synthesizedInput`** lives in **[documenations/schemas/README.md](./schemas/README.md)** (`v1/synthesized-artifacts.json`). Align persisted rows with **`@xronoces/xmemory-contracts`** when mapping columns.
+
+## Failure behavior
+
+- If synthesis fails and `fallbackToDirect === true`, PRE step returns empty context and execution continues.
+- Otherwise the PRE step raises an error.
+
+## Related appendices
+
+- `documenations/synthesis-invocation-notes.md`
+- `documenations/run-task-execution-flow.md`
+- `documenations/task-core-and-core-aware-synthesis.md`