@exellix/ai-tasks 9.1.0 → 9.1.1

package/.docs/investigation/ai-skills.md

@@ -1,170 +0,0 @@
-since this workspace is @exellix/ai-skills@5.2.5 (the package you pin), I can answer authoritatively from the source. Below, citations point to the published surface so your @exellix/ai-tasks / orchestrator team can rely on them.
-
-1. agentId, jobTypeId, taskTypeId — semantics & format
-Required: all three are mandatory non-empty (post-trim) strings on every RunSkillRequest. The SDK rejects empty/whitespace and never substitutes a default:
-
-
-validate-mandatory-activix-invoke-fields.ts
-Lines 3-20
-function assertNonEmptyTrimmed(field: keyof Pick<RunSkillRequest, "agentId" | "jobTypeId" | "taskTypeId">, value: string): void {
-    const trimmed = value.trim();
-    if (!trimmed) {
-        throw new Error(
-            `[AI-SKILLS] RunSkillRequest.${String(field)} is mandatory for gateway.invoke / Activix: upstream must supply a non-empty string (no package defaults).`
-        );
-    }
-}
-...
-export function validateMandatoryActivixInvokeFields(skillRequest: RunSkillRequest): void {
-    assertNonEmptyTrimmed("agentId", skillRequest.agentId);
-    assertNonEmptyTrimmed("jobTypeId", skillRequest.jobTypeId);
-    assertNonEmptyTrimmed("taskTypeId", skillRequest.taskTypeId);
-}
-Format: opaque strings. The SDK only .trim()s and forwards verbatim — no shape, charset, or casing rules; no enum.
-
-Routing / quotas / billing alignment with skillKey: none. They are independent telemetry/correlation labels:
-
-The gateway’s skill-routing classification on invoke uses actionType: "skill" + actionRef: skillRequest.skillKey, set explicitly in buildSkillGatewayInvokePayload:
-
-build-gateway-invoke-request.ts
-Lines 117-122
-        agentId,
-        jobTypeId,
-        taskTypeId,
-        actionType: "skill",
-        actionRef: skillRequest.skillKey,
-agentId/jobTypeId/taskTypeId are forwarded as gateway top-level fields and also merged into identity for Activix linkage (top-level wins on conflict):
-
-build-gateway-invoke-request.ts
-Lines 51-64
-    const agentId = skillRequest.agentId.trim();
-    const jobTypeId = skillRequest.jobTypeId.trim();
-    const taskTypeId = skillRequest.taskTypeId.trim();
-    ...
-    return {
-        ...upstreamIdentityObj,
-        jobId,
-        taskId,
-        agentId,
-        jobTypeId,
-        taskTypeId,
-        aiEngineId,
-    } as unknown as ActivityIdentity & Record<string, unknown>;
-So:
-
-taskTypeId is strictly an opaque telemetry/catalog label — it does not need to equal skillKey, is not consulted for routing, and ai-skills imposes no quota/billing semantics on it. Same for jobTypeId (a recurring-job classifier) and agentId (Activix identity.agentId / gateway identity.instance source).
-skillKey is the only identifier used by this SDK for content lookup (Catalox ai-skills catalog) and as gateway actionRef.
-You can safely make taskTypeId === skillKey in your pipeline if it helps your dashboards, but it is not required and is not enforced by @exellix/ai-skills.
-
-2. RunSkillRequest vs nested authoring metadata — what is canonical
-Canonical = the top-level typed fields. There is no metadata envelope on RunSkillRequest.
-
-The shape is fully enumerated in src/types.ts (RunSkillRequest, lines 256–427) and the flat normalizer is deliberately closed:
-
-
-run-skill-request.ts
-Lines 3-11
-/**
- * Required fields for {@link RunSkillRequest} plus optional copies of every other key.
- * Does not accept arbitrary index signatures — avoids silently forwarding unknown props (e.g. obsolete `taskConfig`).
- */
-export type RunSkillRequestFlat = Pick<...> &
-    Partial<Omit<RunSkillRequest, ...>>;
-Concretely:
-
-If a host sends a generic metadata: { taskTypeId: "...", agentId: "..." } blob alongside top-level fields, ai-skills ignores the blob entirely when building the gateway payload. There is no merge, no warning, no error — buildSkillGatewayInvokePayload only reads the named fields.
-The one runtime envelope that is merged is identity. The shallow-merge rule is: upstream identity is cloned, then top-level jobId/taskId/agentId/jobTypeId/taskTypeId/aiEngineId overwrite anything supplied under identity:
-
-build-gateway-invoke-request.ts
-Lines 42-64
-    const upstreamIdentityObj: Record<string, any> =
-        upstreamIdentity && typeof upstreamIdentity === "object" && !Array.isArray(upstreamIdentity)
-            ? { ...(upstreamIdentity as Record<string, any>) }
-            : {};
-    enrichActivixIdentityForGateway(upstreamIdentityObj, { skillId: skillRequest.skillId });
-    ...
-    return {
-        ...upstreamIdentityObj,
-        jobId, taskId, agentId, jobTypeId, taskTypeId, aiEngineId,
-    } ...
-jobId/taskId may also be read from identity as a fallback when omitted at top-level (with a warn log), per resolveGatewayJobAndTaskIds:
-
-resolve-gateway-job-task-ids.ts
-Lines 26-32
-  const jobId = trimmedString(params.jobId) || trimmedString(id?.jobId);
-  const taskId = trimmedString(params.taskId) || trimmedString(id?.taskId);
-sessionId is the only field with a cross-field agreement check: top-level sessionId must equal identity.sessionId if both are set (validateSessionIdAgreement).
-Recommendation for your runTask layer: put correlation values on the top-level typed fields (and identity if you also need them for downstream packages). Avoid stuffing them into a generic metadata envelope passed to runSkill — they will not survive into the gateway invoke. If you want a stricter contract on your side, prefer runSkillRequestFromFlat(...) because it destructures explicitly and won’t silently forward strays.
-
-3. taskKind, outputValidation, autoValidateDecisionOutput on the wire to runSkill
-Confirmed orchestrator-only. A repo-wide search returned zero matches for any of those identifiers:
-
-They are not declared on RunSkillRequest / RunSkillResponse / gateway invoke payload types.
-They are not consulted for routing, validation, defaulting, or logging anywhere in @exellix/ai-skills (or in the @x12i/ai-gateway types this package depends on as far as ai-skills uses them).
-If they appear on a request object at runtime they are silently dropped (TypeScript structural typing accepts the cast; the executor only reads the typed fields). No warning is emitted.
-What this layer does do regarding output:
-
-FlexMD parsing of the gateway response (response.flexMd or fallback to parseFlexMd) — see SkillExecutor.execute.
-Optional outputSchema is exposed on SkillMetadata as a catalog descriptor (src/types.ts:52) but the SDK does not auto-validate against it; that is the caller’s responsibility.
-There is no autoValidate* flag, no decision-output special case, and no audit short-circuit (the README explicitly notes “audit is no longer a separate skill type” — src/types.ts:48).
-So your ai-tasks-side semantics for taskKind / outputValidation / autoValidateDecisionOutput are entirely safe to keep above runSkill.
-
-4. Diagnostics & run logs — stable schema, types, versioning
-The stable types are part of the package’s public TypeScript surface (re-exported via src/index.ts: export * from "./types.js"). Two layers:
-
-4a. Always-on RunSkillResponse.metadata (no opt-in needed)
-
-types.ts
-Lines 445-472
-  metadata: {
-    instructionVersion?: string;
-    activityId?: string;
-    costUsd?: number;
-    usage?: SkillTraceUsage;
-    modelUsed?: string;
-    provider?: string;
-    effectiveMaxTokens?: number;
-    region?: string;
-    requestedModelConfig?: ModelConfig;
-    effectiveModelConfig?: EffectiveModelConfigSlice;
-    invokeExec?: { timeoutMs?: number };
-  };
-activityId is the primary correlation id for the persisted Activix activity; usage follows SkillTraceUsage. Helpers re-exported for consumers: billingSnapshotFromGatewayMetadata, gatewayExecutionSummaryFromInvokeResponse, effectiveModelConfigFromGatewayMetadata.
-
-4b. Opt-in structured trace (gated by executionMode: "trace" or diagnostics.includeDebugTrace: true)
-
-types.ts
-Lines 221-250
-export interface SkillDiagnosticsTrace {
-  step: SkillTraceStepIdentity;
-  timing: { startedAt: string; endedAt: string; durationMs: number; };
-  routing: SkillTraceRouting;
-  usage: SkillTraceUsage;
-  costUsd?: number;
-  modelUsed: string;
-  ok: boolean;
-  error?: { name: string; message: string };
-  attempts: SkillTraceAttempt[];
-  tasks: SkillTraceAttempt[];           // alias of attempts (same array ref)
-  rawProviderPayload?: string;          // only when includeRawProviderPayload
-  invokeRequest?: SkillDiagnosticsInvokeRequest;
-  invokeRejection?: GatewayInvokeRejectionMetadata;
-}
-Surfaced on the response as both diagnostics.trace and the alias debugTrace (same reference). All sub-types are exported names you can import: RunSkillDiagnostics, SkillDiagnosticsTrace, SkillTraceAttempt, SkillTraceRouting (with requestIds.gatewayAiRequestId / routerRequestId / providerActivityRequestId), SkillTraceUsage, SkillTraceStepIdentity, SkillDiagnosticsInputOptions, SkillDiagnosticsInvokeRequest, ExecutionMode, plus the gateway type GatewayInvokeRejectionMetadata (re-exported from @x12i/ai-gateway).
-
-Production helpers exported for consumers building their own trace pipeline: mapGatewayInvokeToTrace, traceToDiagnostics, metadataFromInvokeError, isTraceExecutionMode, includeRawProviderPayload. Failure-path correlation: when an invoke rejects in trace mode, the SDK throws SkillExecutionTraceError with the same RunSkillDiagnostics shape attached.
-
-Run-log rows / milestones
-@exellix/ai-skills does not define a per-step run-log row schema. Structured logging is delegated to @x12i/logxer: every milestone in SkillExecutor.execute is emitted as logger.info/warn with a stable shape — { debugKind: DebugLogAbstract.<INTENT|EVENT|ANOMALY>, identity, jobId, taskId, skillKey, ... }. That contract belongs to @x12i/logxer, not this package; please bind your sink against that surface rather than scraping our log strings.
-
-The Activix-style nested billing snapshot for chaining is a stable SDK concept too — exposed via enrichIdentityWithAiSkillsLlmSnapshot and the constant AI_SKILLS_LLM_IDENTITY_KEY = "aiSkillsLlm". Forward RunSkillResponse.identity between steps to retain it.
-
-Versioning policy
-Types travel with the package semver (currently 5.2.5). There is no separate diagnostics version field on the wire.
-README pins compatibility: @x12i/ai-gateway ≥ 9.1.2 is recommended for routing metadata (≥9.1.1) and GatewayInvokeRejectionMetadata on error.metadata (≥9.1.2).
-Suggested coupling for your consumers: import the types by name from @exellix/ai-skills and treat unknown optional fields as additive (we add fields in minor versions; we do not rename existing ones without a major bump). The tasks alias of attempts is intentional and stable for orchestrators that look up debugTrace.tasks.
-Things I would still like you to confirm
-I answered all four from source, so nothing was guessed — but two product calls are yours, not mine:
-
-Do you want me to add a "unknown top-level key" warning in runSkill (e.g. surface a logxer warn when an orchestrator sends metadata, taskKind, outputValidation, autoValidateDecisionOutput)? Today they’re silently ignored.
-Do you want taskTypeId === skillKey enforced or merely recommended in your runTask layer? The skills package will accept any value.

package/.docs/investigation/external-packages-assignments.md

@@ -1,66 +0,0 @@
-# External package assignments (integration follow-ups)
-
-Tracker for work **outside `@exellix/ai-tasks`** that closes orchestrator / stack gaps.  
-**Reference:** answers and ai-tasks-owned behavior are normative in [`RUNTASK_REQUEST.md`](../../RUNTASK_REQUEST.md) § **Orchestrator integration**.
-
-**Created:** 2026-05-07  
-
----
-
-## Summary table
-
-| Due date | Package / repo | Assignment | Owner (fill) | Deliverable |
-|----------|----------------|------------|----------------|-------------|
-| **2026-05-14** | **`@exellix/graph-engine`** | Docs + deps clarity | Graph runtime team | Update format doc: remove or correct stale **“local web scoping”** if current code only **forwards `narrix`** (match `executeNode.ts`). Document pinned **`@exellix/ai-tasks`** range for **4.8.x** in package README or `.docs`. |
-| **2026-05-14** | **`@exellix/graph-engine`** | Compatibility discipline | Graph runtime team | Optional **CI** or Renovate policy: fail or warn when lockfile **`@exellix/ai-tasks`** major drifts outside supported range (define range in graph-engine). |
-| **2026-05-21** | **`@exellix/graph-engine`** | Passthrough whitelist | Graph runtime team | **`extractRunTaskMetadataPassthrough`**: process to update when schema grows — e.g. consume exported JSON Schema keys from ai-tasks **`scripts/export-run-task-request-keys.mjs`** once added (**optional ai-tasks P2**), or document manual review cadence on each ai-tasks **minor**. |
-| **2026-05-21** | **`@exellix/graph-engine`** | Run log contract | Graph runtime + observability | Document canonical **`runLog`** vs **`exellixRunLog`**, **`logxerRunId`** vs **`logxerCorrelationId`**; add **`schemaVersion`** on buffered **`RunLogEntry`** **or** explicitly state “unversioned, best-effort normalize”. |
-| **2026-05-28** | **`@x12i/logxer`** | Viewer alignment | Logging platform team | If graph-engine standardizes **`logxerRunId`**, document mapping to Logxer run/session viewers and stable field names. |
-| **2026-05-28** | **`@exellix/ai-skills`** | Optional strictness | AI gateway team | Product decision: **warn** on unknown top-level keys** toward invoke vs silent strip (see `.docs/investigation/ai-skills.md` open questions). |
-| **2026-05-14** | **`@exellix/narrix-catalox`** | Doc sync | Narrix tooling team | Confirm [**narrix-catalox.md**](./narrix-catalox.md) UX rule (**`ai-task-main-execution-wrappers` only**) is published in narrix-catalox repo if copied from here. |
-
----
-
-## By package (detail)
-
-### `@exellix/graph-engine`
-
-| ID | Target date | Task |
-|----|-------------|------|
-| GE-DOC-1 | 2026-05-14 | Align **web scoping** documentation with implementation: **Narrix / web scope owned by ai-tasks** when config is forwarded; no duplicate in-tree scoper unless a branch reintroduces it. |
-| GE-DEP-1 | 2026-05-14 | State **supported `@exellix/ai-tasks` semver** for **4.8.x** (e.g. `^7.3.8`) in repo docs; optional matrix table “engine release ↔ ai-tasks tested”. |
-| GE-CI-1 | 2026-05-21 | Optional: CI gate on dependency range or lockfile diff vs allowed ai-tasks versions. |
-| GE-PASS-1 | 2026-05-21 | Maintain **`extractRunTaskMetadataPassthrough`** when **`RunTaskRequest`** schema grows; link to **`RUNTASK_REQUEST.md`** as contract. |
-| GE-LOG-1 | 2026-05-21 | Publish **`RunLogEntry`** + metadata key deprecation policy (**`runLog`** preferred vs **`exellixRunLog`**, etc.). |
-
-### `@x12i/logxer`
-
-| ID | Target date | Task |
-|----|-------------|------|
-| LX-MAP-1 | 2026-05-28 | If orchestrator emits **`logxerRunId`**, document how it maps to Logxer dashboards / correlation with **`@exellix/ai-skills`** milestone logs. |
-
-### `@exellix/ai-skills`
-
-| ID | Target date | Task |
-|----|-------------|------|
-| SK-WARN-1 | 2026-05-28 | Decide whether unknown keys (`taskKind`, nested `metadata` blobs, etc.) should **log warn** at invoke build time; document outcome in ai-skills README. |
-
-### `@exellix/narrix-catalox`
-
-| ID | Target date | Task |
-|----|-------------|------|
-| NC-PUB-1 | 2026-05-14 | Ensure catalog UX policy (**canonical `ai-task-main-execution-wrappers`**) is the published narrix-catalox doc; legacy **`ai-task-execution-strategies`** noted as ai-tasks-seeded for old consoles only. |
-
----
-
-## Completed in `@exellix/ai-tasks` (2026-05-07)
-
-- **`RUNTASK_REQUEST.md`**: § Orchestrator integration (versioning, passthrough, **`taskTypeId`**, **`xynthesizedPatch`** × optimizer/retry, web scope, run-log keys, utilities, scope table); **`taskKind` row** clarified vs **`runSkill`**.
-- **`documenations/run-task-execution-flow.md`**: diagnostics section corrected vs **`task-sdk`** reality.
-- **`CHANGELOG.md`**: cross-package TBD replaced with pointer to orchestrator-owned versioning.
-
----
-
-## How to use dates
-
-Treat dates as **target completion** for the owning team. Slide **`2026-05-28`** items if product priority shifts; keep **GE-DOC-1** and **GE-DEP-1** high priority to match current **`executeNode`** behavior and dependency transparency.

package/.docs/investigation/integration-summary.md

@@ -1,20 +0,0 @@
-# Integration summary (`ai-tasks` ↔ graph-engine ↔ stack)
-
-One-page index for orchestrator and Catalox integration work.
-
-| Artifact | Purpose |
-|----------|---------|
-| [**workplan-close-graph-engine-gaps.md**](./workplan-close-graph-engine-gaps.md) | Actionable workplan: gap owners, priorities, definition of done, file checklist. |
-| [**external-packages-assignments.md**](./external-packages-assignments.md) | **Dated assignments** for graph-engine, logxer, ai-skills, narrix-catalox (outside this repo). |
-| [**narrix-catalox.md**](./narrix-catalox.md) | Canonical Catalox catalog id for **`RunTaskRequest.executionStrategies`** UX (`ai-task-main-execution-wrappers`). |
-| [**ai-skills.md**](./ai-skills.md) | **`agentId` / `jobTypeId` / `taskTypeId`**, wire vs **`taskKind`**, diagnostics/trace vs run-log rows. |
-
-**Normative contract (this package):**
-
-- `RUNTASK_REQUEST.md` — field inventory, `executionPipeline`, template merge.
-- `documenations/schemas/v1/run-task-request.json` — closed JSON shape.
-- `src/types/task-types.ts` — TypeScript `RunTaskRequest` / response patches.
-
-**Related deep dives:**
-
-- `documenations/web-scoping-in-ai-tasks.md` — Narrix web scope, skip flags, no cross-host dedupe.

package/.docs/investigation/narrix-catalox.md

@@ -1,29 +0,0 @@
-# `@exellix/ai-tasks` integration note: `executionStrategies`
-
-This repo (`@exellix/narrix-catalox`) seeds **Narrix** catalogs (e.g. `categories`, `signals`, `pipelines`) and does not seed the `ai-tasks` app’s catalogs. This document exists to make the **contract decision** explicit for downstream tooling that renders/authorizes `RunTaskRequest.executionStrategies`.
-
-## Canonical catalog identity (NO legacy)
-
-- **Canonical UX dropdown catalogId**: **`ai-task-main-execution-wrappers`**
-- **Runtime request field**: `RunTaskRequest.executionStrategies`
-- **Meaning**: optional FuncX wrappers immediately around the MAIN `runSkill` call (e.g. planner before MAIN, optimizer around/after MAIN attempts).
-
-There is **no legacy alias support** in narrix-catalox tooling: bind UX only to **`ai-task-main-execution-wrappers`**. Separately, **`@exellix/ai-tasks`** may still provision **`ai-task-execution-strategies`** in Catalox (same seeded rows) for older consoles — narrix-catalox does not use that catalog id.
-
-## Seed equality vs operational truth
-
-When seeds are produced by the official `@exellix/ai-tasks` publish script, items are expected to be stable and keyed by `strategyKey` (natural identity). However, Catalox/Firestore can be manually edited; operational truth is established by re-running the official publish script rather than assuming two catalogs remain in sync.
-
-## `taskTypeId` / `jobTypeId` (host-defined)
-
-`taskTypeId` / `jobTypeId` are treated as **host-defined opaque non-empty strings** (correlation / telemetry classification). They are **not** constrained by a Catalox catalog in this repo.
-
-Recommended convention (documentation-only): use stable, collision-resistant namespaced IDs (e.g. `exellix.task.<kind>` / `exellix.job.<kind>`).
-
-## Deprecation & drift policy (breaking allowed)
-
-If the runtime validation/wire contract changes (e.g. supported `strategyKey` set changes), treat it as **breaking**:
-
-- **Signal**: semver **major** for the runtime package that validates requests (e.g. `@exellix/ai-tasks`).
-- **Downstream behavior**: consoles should compare catalog `strategyKey` values to the runtime’s exported canonical key set and warn/error on divergence (drift is not assumed to be auto-detected at runtime).
-

package/.docs/investigation/workplan-close-graph-engine-gaps.md

@@ -1,101 +0,0 @@
-# Workplan: close integration gaps + graph-engine Q&A
-
-This plan closes gaps identified across **`@exellix/ai-tasks`**, **`@exellix/graph-engine`** (client/orchestrator), and optionally **`@exellix/ai-skills`** / **`@x12i/logxer`**.
-
-**Status (2026-05-07):** Sprint 1 **ai-tasks** doc items (**AI-T-1, AI-T-2, AI-T-5**, **`taskKind` row**) landed in **`RUNTASK_REQUEST.md`**, **`run-task-execution-flow.md`**, **`CHANGELOG.md`**. Dated tasks for other repos: [**external-packages-assignments.md**](./external-packages-assignments.md).  
-Priority order is **P0** (blocks correctness or contracts), **P1** (docs/tooling), **P2** (nice-to-have).
-
----
-
-## A. Answer key — original graph-engine questions (where truth lives)
-
-| Topic | Answer (authoritative) | Owner of normative doc |
-|-------|------------------------|-------------------------|
-| **Versioning** (`ai-tasks` min for graph-engine 4.8.x) | No matrix in **ai-tasks**. Declare **`package.json` / lockfile`** line on graph-engine; **`CHANGELOG.md` + `BREAKING-CHANGES.md`** for semver (majors = breaking `RunTaskRequest`). Joint **tested range** only after CI matrix exists. | graph-engine (deps + optional matrix); ai-tasks (changelog policy — already present). |
-| **`extractRunTaskMetadataPassthrough`** | **No** generated allowlist in ai-tasks; parity is **host** responsibility. Optional future: schema-driven export from ai-tasks. | graph-engine (whitelist / codegen consumer); ai-tasks (optional tooling — below). |
-| **`taskTypeId` vs `skillKey`** | **`@exellix/ai-skills`**: all three correlation ids required; **`taskTypeId` opaque**, not used for routing. **`taskTypeId === skillKey`** optional. Graph pattern `metadata.taskTypeId` → root normalize is fine. | `.docs/investigation/ai-skills.md`; graph-engine build layer. |
-| **`executionStrategies`** shape / errors | **`resolveExecutionStrategies`**: `planner`/`optimizer`, phases, `priority`, optimizer-only **`maxIterations`**; errors are **`Error` strings**. **`direct`** = **`[]`** on wire; Catalox **`direct`** row is UX-only. | `RUNTASK_REQUEST.md`, types, `src/execution-strategies/resolveExecutionStrategies.ts`. |
-| Catalog ids (`ai-task-execution-strategies` vs `ai-task-main-execution-wrappers`) | Same seed source in ai-tasks publish script; **`strategyKey`** identity. Narrix-catalox UX: **`ai-task-main-execution-wrappers`** only; legacy catalog may still exist in Firestore for old consoles. | `.docs/investigation/narrix-catalox.md`; ai-tasks constants + publish script. |
-| **`executionPipeline`** | Exactly **one** `main`; PRE only **`synthesized-context`** — **first** such PRE runs then **`break`** (extras skipped + warnings). POST **`audit`** / **`polish`** only; others ignored. | `RUNTASK_REQUEST.md` § `executionPipeline`. |
-| **Web scoping** | **`narrix.enableWebScope`** triggers internal **`@exellix/narrix-web-scoper`** after Narrix preprocessor. **`skipWebScopeWhenExternalWebMarkdownPresent`** + **`executionMemory.webContextMarkdown`** skips internal fetch. **No** URL-level dedupe across hosts. | `documenations/web-scoping-in-ai-tasks.md`, `task-sdk.ts`. |
-| **`runLog` / `exellixRunLog` / `logxerRunId` / `logxerCorrelationId`** | **Not set by `runTask`** in ai-tasks. Consumer contract on merged **`response.metadata`** (graph-engine today). Stable schema/version = **orchestrator + log stack**, not `RunSkillResponse` types. | graph-engine `runLog.ts`; optional **`@x12i/logxer`** alignment doc. |
-| **`taskKind` / `outputValidation` / defaults for MAIN** | Interpreted **only in ai-tasks** before **`runSkill`**. **`taskKind: "decision"`** + **`autoValidateDecisionOutput !== false`** injects default schema **`fail`**. Not on **`RunSkillRequest`**. | `RUNTASK_REQUEST.md`, `task-sdk.ts` (`withDefaultDecisionValidation`). |
-| **`xynthesized` / `xynthesizedPatch`** | **`applyXynthesizedOutputWrite`**: **`replace`** vs **`merge`** (deep-merge plain objects only). **`mergeXynthesizedPatchSlices`**: shallow merge **`job`/`task` buckets**. **`xynthesizedPatchAccumulator`** updated **only** on PRE **`xynthesizedOutput`** path — **not** per optimizer MAIN iteration. | `src/utils/xynthesizedWrite.ts`, `task-sdk.ts`; graph merges patches **per successful `runTask`**. |
-| **Optimizer × env × graph retry** | **`AI_TASKS_OPTIMIZER_MAX_ITERATIONS`** / request **`maxIterations`** bound **inner** loop inside **one** `runTask`. **Each graph-engine retry** = new `runTask` → optimizer state **resets** unless host replays memory/`xynthesized`. Upper bound ≈ **retries × inner iterations**. | `src/execution-strategies/constants.ts`, `resolveExecutionStrategies.ts`, `task-sdk.ts`. |
-| **Utility PRE/POST (`taskTypeIdOverride`, pipeline, strategies)** | **`runTask`** does **not** forbid **`executionStrategies`** / pipeline for **`taskKind: "utility"`**; graph-engine **policy** (fixed MAIN + `[]`) is isolation. Telemetry convention **`exellix-graph-xynthesis-pre/post:…`** is graph-engine choice — ai-skills accepts any non-empty **`taskTypeId`**. | graph-engine strategy phases; ai-tasks runtime permissive. |
-| **`scope` vs `aiScoping` vs `narrixScope`** | **`narrixScope`**: filters **`taskMemory.narrix`**. **`aiScoping`**: PRE-MAIN → **`input.aiScoped`**. Authoring **`scope`** compiles into **`input`/`variables`/`executionMemory`** — not a separate top-level field on **`RunTaskRequest`**. | `RUNTASK_REQUEST.md`, `task-types.ts` JSDoc. |
-
----
-
-## B. Work items by repo
-
-### B1. `@exellix/ai-tasks` (this repo)
-
-| ID | Priority | Work | Acceptance criteria |
-|----|----------|------|---------------------|
-| **AI-T-1** | P1 | **Extend `RUNTASK_REQUEST.md`** with a short **“Orchestrator integration”** subsection: (1) no formal graph-engine version matrix in-package; cite semver docs; (2) **`xynthesizedPatch`** only accumulates PRE **`xynthesizedOutput`** writes, not optimizer iterations; (3) optimizer vs **separate** `runTask` retries; (4) run-log metadata keys **not** emitted by `runTask` — graph/client owns buffering keys if present; (5) link to `documenations/web-scoping-in-ai-tasks.md` for web scope / dedupe. | Single source readers can resolve graph-engine threads without chat archaeology. |
-| **AI-T-2** | P1 | **Align `documenations/run-task-execution-flow.md`** with implementation: either remove or qualify **`request.diagnostics` / `appendRunLog` / Logxer sink** bullets unless/until implemented in `task-sdk.ts`, **or** track a GitHub issue “implement diagnostics sink”. | No doc claiming behavior that `grep` cannot find in `src/`. |
-| **AI-T-3** | P2 | **`RUNTASK_REQUEST.md`**: table row or § for **`taskKind` / `outputValidation`** — “not forwarded to `runSkill`; enforced in `runTask` only” + pointer to **`@exellix/ai-skills`** investigation note. | Matches `.docs/investigation/ai-skills.md`. |
-| **AI-T-4** | P2 | **Optional tooling**: script **`scripts/export-run-task-request-keys.mjs`** (or ts) that prints **top-level JSON Schema keys** from `documenations/schemas/v1/run-task-request.json` for graph-engine CI diff vs passthrough whitelist. | graph-engine can fail CI when schema adds keys not in allowlist (or forces explicit ignore list). |
-| **AI-T-5** | P2 | **Replace `TBD` minimum graph-engine** lines in `RUNTASK_REQUEST.md` / `CHANGELOG.md` with: *“Orchestrator minimum version is not declared here; follow consuming app’s `package.json` and joint CI when introduced.”* | Removes false expectation of an ai-tasks-owned engine floor. |
-| **AI-T-6** | P1 | **Keep `.docs/investigation/integration-summary.md`** (new): 1-page pointer to `narrix-catalox.md`, `ai-skills.md`, this workplan, `RUNTASK_REQUEST.md`. | Onboarding path for integrators. |
-
-### B2. `@exellix/graph-engine` (consumer repo — track as external tickets)
-
-| ID | Priority | Work | Acceptance criteria |
-|----|----------|------|---------------------|
-| **GE-1** | P1 | **Docs**: fix stale **“local web scoping”** language in format doc to match **`executeNode.ts`** (forward `narrix` only; ai-tasks owns internal scoper). | Matches runtime. |
-| **GE-2** | P1 | **Compatibility**: document **`@exellix/ai-tasks` pinned range** for 4.8.x; optional **CI** job: lockfile major/minor vs allowed range or Renovate policy. | Repeatable upgrade discipline. |
-| **GE-3** | P2 | **Passthrough**: adopt **AI-T-4** export in CI **or** widen whitelist strategy (explicit ignore vs full passthrough for unknown keys policy). | Fewer silent misses on new `RunTaskRequest` fields. |
-| **GE-4** | P2 | **`RunLogEntry`**: add **`schemaVersion`** (or document why omitted) + canonical key table **`runLog` vs `exellixRunLog`**, **`logxerRunId` vs `logxerCorrelationId`** — align **`@x12i/logxer`** viewers if applicable. | Single contract doc for log consumers. |
-
-### B3. `@exellix/ai-skills` / `@x12i/logxer` (optional follow-ups)
-
-| ID | Priority | Work | Acceptance criteria |
-|----|----------|------|---------------------|
-| **SK-1** | P2 | Product decision: **warn** on unknown keys** passed toward invoke (or strict strip list)** — only if graph-engine/ai-tasks want noise in logs. | Decision recorded; implement or explicitly decline. |
-| **LX-1** | P2 | Document **mapping** `logxerRunId` ↔ Logxer session/run viewers if graph-engine standardizes on those keys. | Reduces cross-package ambiguity. |
-
-### B4. `@exellix/narrix-catalox` (doc tweak)
-
-| ID | Priority | Work | Acceptance criteria |
-|----|----------|------|---------------------|
-| **NC-1** | P1 | **`narrix-catalox.md`**: one sentence — **`ai-task-execution-strategies` may still exist** for legacy UIs; narrix-catalox binds only **`ai-task-main-execution-wrappers`**. | No contradiction with ai-tasks publish script. |
-
----
-
-## C. Suggested execution order (2 short sprints)
-
-**Sprint 1 (close doc + Q&A surface — ~0.5–1 dev-day in ai-tasks)**  
-1. AI-T-1, AI-T-2, AI-T-5, AI-T-6  
-2. NC-1 (narrix-catalox repo or shared doc)  
-3. GE-1 (graph-engine) in parallel if someone has access  
-
-**Sprint 2 (tooling + contracts — ~1–2 dev-days cross-repo)**  
-4. AI-T-4 + GE-3  
-5. GE-2, GE-4  
-6. AI-T-3, SK-1, LX-1 as bandwidth allows  
-
----
-
-## D. Definition of done (for “gaps closed”)
-
-- [ ] Every row in **§A** has a **linked** normative location (markdown or exported types), not only Slack/chat.  
-- [ ] No ai-tasks markdown asserts **`appendRunLog`** / run-log injection **without** implementation or explicit “planned”.  
-- [ ] graph-engine format doc matches **forward-only Narrix / web scope** behavior.  
-- [ ] Optional: CI prevents passthrough drift (**AI-T-4** + **GE-3**).  
-- [ ] Optional: versioned or explicitly versionless **`RunLogEntry`** contract (**GE-4**).  
-
----
-
-## E. Files to touch in **this** repo (checklist)
-
-| File | Action |
-|------|--------|
-| `RUNTASK_REQUEST.md` | Add orchestrator subsection; replace graph-engine **TBD** with explicit non-ownership statement. |
-| `documenations/run-task-execution-flow.md` | Fix diagnostics/runLog claims vs code. |
-| `.docs/investigation/integration-summary.md` | **Create** — index + links. |
-| `.docs/investigation/narrix-catalox.md` | **NC-1** sentence (if maintained here). |
-| `CHANGELOG.md` | Optional note when docs land (doc-only release acceptable as **patch**). |
-
-No runtime behavior change is **required** to close documentation gaps; **AI-T-4** is the only new artifact that changes maintainer workflow.

package/.docs/logging-stack.md

@@ -1,30 +0,0 @@
-# Logging Stack (Activix + xronox-store)
-
-For initial rollout and integration debugging, enable logs at both layers:
-
-- **Activix**: `ACTIVIX_LOGS_LEVEL=debug`
-- **xronox-store**: `XRONOX_STORE_LOG=1`
-
-## What to expect
-
-- Activix logs should make it clear when lifecycle APIs are called (`start`/`complete`/`fail`/`patch`) and which instance is producing output (via `diagnostics` when provided).
-- Store logs should help diagnose Mongo connectivity, retries, and deterministic write failures (like duplicate keys).
-
-## Diagnostics metadata (recommended for multi-instance)
-
-If you expect more than one Activix instance in a process/fleet, pass `diagnostics` metadata at construction time so logs are self-identifying:
-
-```ts
-const ax = new Activix({
-  storageMode: 'automatic',
-  mongoUri: process.env.MONGO_URI!,
-  collection: 'task-activities',
-  diagnostics: {
-    owner: '@your-org/your-service',
-    component: 'graph-executor',
-    instanceLabel: 'worker-main',
-    workerId: process.pid.toString(),
-  },
-});
-```
-