@exellix/ai-tasks 9.1.0 → 10.0.0

package/documenations/upstream-feedback-request-shape-clarification.md

@@ -1,101 +0,0 @@
-# Upstream Feedback Response: `runTask` Request Shape and Runtime Model
-
-## Context
-
-Feedback received:
-
-> The `runTask` request still looks old-shaped.
-> In all 3 request files, top-level shape is still basically:
-> `question`, `record`, `inputs`, `narrix`, `executionMemory`, `variables`.
-> I do not see new explicit runtime concepts reflected in request shape:
-> - no `taskCore`
-> - no detected template core set
-> - no `synthesizedContext` being carried into MAIN
-> - no sign that template analysis is driving execution
->
-> So request contract still looks like old model.
-
-This document is the formal response and clarification.
-
----
-
-## Short Answer
-
-The request contract is **intentionally minimal and mostly unchanged at top-level**.
-The new model is a **runtime-orchestration contract**, not a request-field expansion.
-
-So the absence of new top-level fields is expected and correct.
-
----
-
-## What Changed (and Why It May Not Appear in Request Shape)
-
-### 1) `taskCore` removed from request (intentional)
-
-- The old request-level `taskCore` is removed as source of truth.
-- Runtime now derives task semantics from template declarations.
-- This is a deliberate shift away from user-supplied task core metadata.
-
-### 2) Core detection is runtime-derived, not caller-supplied
-
-- `templateCores` are discovered pre-render from raw instructions/prompt templates.
-- Discovery is done by runtime internals (not by request payload).
-- Therefore `templateCores` does not need to be added as request input.
-
-### 3) `synthesizedContext` is execution memory artifact, not request input
-
-- In structured synthesis mode, runtime writes synthesized artifact to:
-  - `executionMemory.synthesizedContext`
-- This is generated during PRE step and then consumed by MAIN flow.
-- It is intentionally a runtime-produced artifact, not a required top-level request field.
-
-### 4) Template analysis drives execution internally
-
-- The execution decision path (for structured synthesis) is:
-  1. resolve raw templates,
-  2. detect `{{core:...}}` directives,
-  3. validate non-empty detected core set,
-  4. run structured synthesis with detected cores + resolved question,
-  5. materialize main context markdown and continue MAIN execution.
-- This orchestration is runtime behavior and does not require top-level request shape changes.
-
----
-
-## Why Keeping Request Shape Stable Is Correct
-
-- Backward compatibility for callers that already send existing fields.
-- Avoids duplicating runtime-derived data in user input.
-- Prevents conflicting sources of truth (caller-provided core vs template-declared core).
-- Keeps request API focused on inputs/config, while runtime computes orchestration artifacts.
-
----
-
-## Explicit Clarification to Upstream
-
-Please do **not** interpret the unchanged top-level request shape as "old model still active".
-
-The new model is active through runtime semantics:
-
-- no request-level `taskCore`,
-- template-driven core declaration (`{{core:...}}`),
-- pre-render core discovery from raw template content,
-- structured synthesis validation using detected `templateCores`,
-- synthesized artifact persisted to execution memory and used in MAIN flow.
-
-This is a contract change in **runtime behavior**, not a requirement to add more top-level request fields.
-
----
-
-## What Upstream Still Needs To Ensure
-
-1. `ai-skills.resolveRawTemplate(...)` remains stable/public for pre-render analysis.
-2. `athenix-parser` keeps `core:` directives as first-class non-path tokens.
-3. Lifecycle cleanup/shutdown exists for test/runtime handle hygiene (non-functional hardening).
-
----
-
-## Final Position
-
-The current request shape is acceptable and intentional.
-No additional top-level request fields are required to represent the new core-aware runtime model.
-

package/documenations/web-context-precedence.md

@@ -1,33 +0,0 @@
-# Web context precedence: structured scoping vs caller markdown
-
-This document describes how **web evidence** reaches MAIN context and the **synthesized-context** PRE step, and how to avoid **duplicate** web retrieval.
-
-## Sources
-
-1. **Internal structured web context** — When NARRIX pre-processor runs with **`narrix.enableWebScope: true`**, ai-tasks calls the Narrix web scoper and stores the result on **`executionMemory.webContext`**. Markdown for prompts is derived via **`buildWebContextEvidenceMarkdown`** (`src/narrix/webContextMarkdown.ts`).
-
-2. **Caller-provided markdown** — Orchestrators may attach a pre-rendered string on **`executionMemory.webContextMarkdown`**. When MAIN context is built (`_executeDirect`), if that string is non-empty and context assembly is active (see below), it is appended **after** Narrix narrative and internal web markdown as a section:
-
-   **`## Supplementary web context (caller-provided)`**
-
-## Precedence (MAIN `context` markdown)
-
-When **`includeContextInPrompt`** is true, or NARRIX narrative is in play, or MAIN runs with a **synthesized** override from the pipeline:
-
-1. Narrix attachment markdown (when present).
-2. Markdown built from **`executionMemory.webContext`** (when available).
-3. **`executionMemory.webContextMarkdown`** (caller supplementary), if non-empty.
-
-Synthesis PRE source material uses **`resolveSourceMaterial`** / **`resolveSourceMaterialParts`**, which serialize web as dedicated markdown and may **omit** raw `webContext` from JSON memory slices for specific policies (see [web-scoping-in-ai-tasks.md](./web-scoping-in-ai-tasks.md)).
-
-## Avoiding duplicate search
-
-- **Do not** set **`narrix.enableWebScope: true`** if the gateway already ran web search and you only persist results into **`executionMemory.webContext`** or **`webContextMarkdown`**.
-- Use **`narrix.skipWebScopeWhenExternalWebMarkdownPresent: true`** when **`executionMemory.webContextMarkdown`** is already set before the NARRIX pre-processor runs: internal Tavily/web-scoper **will not** run for that invocation (Narrix narrative still runs as usual).
-
-Optional environment knobs (existing) include caps on generated web markdown (e.g. **`WEB_CONTEXT_MARKDOWN_MAX_CHARS`** in web-scoping docs).
-
-## Related
-
-- [web-scoping-in-ai-tasks.md](./web-scoping-in-ai-tasks.md)
-- [synthesized-context-guide.md](./synthesized-context-guide.md)

package/documenations/xynthesis-activix-telemetry.md

@@ -1,28 +0,0 @@
-# Xynthesis Activix telemetry (Mongo)
-
-For **hosts** of `@exellix/ai-tasks` and other orchestrators using **`@exellix/xynthesis`**.
-
-## Symptom
-
-With **`MONGO_URI`** or **`MONGO_LOGS_URI`** set, logs may show Activix init failures mentioning **`activix-collections`**, **`diagnostics.owner`**, or **`collectionRegistry.owner`**. Synthesis calls might still return text while **Mongo telemetry** for xynthesis does not initialize.
-
-## Root cause
-
-**`@x12i/activix`** enables the collection registry by default; that path requires **`diagnostics.owner`** (or **`collectionRegistry.owner`**) on the **`Activix`** constructor. If xynthesis builds Activix **without** `diagnostics`, **`init()`** fails in database mode.
-
-## Required upstream change
-
-In **`exellix/xynthesis`** (`src/activix.ts`, `getActivix`), pass **`diagnostics`** with at least **`owner: "@exellix/xynthesis"`** (and optional **`XYNTHESIS_ACTIVIX_DIAGNOSTICS_OWNER`** override). Details and test ideas: **[`xynthesis-upstream-fixes-checklist.md`](./xynthesis-upstream-fixes-checklist.md)** §1.
-
-## Operational knobs
-
-| Env | Effect |
-|-----|--------|
-| **`XYNTHESIS_ACTIVIX=FALSE`** | Disable xynthesis Mongo telemetry. |
-| **`XYNTHESIS_ACTIVIX_DIAGNOSTICS_OWNER`** | Override **`diagnostics.owner`**. |
-| **`XYNTHESIS_ACTIVIX_COLLECTION`** | Override default collection **`xynthesis-actions`**. |
-
-## Related
-
-- Gateway-side Activix (**`@x12i/ai-gateway`**) is separate from xynthesis’ singleton.
-- ai-tasks Activix wiring: **`src/activix/activixClient.ts`** — constructs when Mongo is configured; persistence toggled via **`activix-collections`** legend `state` (Activix 8.4+), not `ACTIVIX_ENABLED=true`.