@exellix/ai-tasks 10.0.9 → 10.0.11

package/documenations/web-scoping-in-ai-tasks.md

@@ -1,503 +1,163 @@
 ## Web scoping in `@exellix/ai-tasks`
 
-This document explains, in technical detail, **how web scoping is wired into ai-tasks**, how requests opt into it, what data flows through, and what guarantees / failure modes exist. It is intended for engineers integrating with ai-tasks (e.g. graph builders, skill authors) and for maintainers changing the web scoping plumbing.
+This document explains how web scoping is wired into ai-tasks, how requests opt in, what data flows through `@x12i/web-scoper`, and what guarantees / failure modes exist.
 
 ---
 
 ## 1. High-level overview
 
-- **Goal**: Enrich a NARRIX run with **external web context** (via `@exellix/narrix-web-scoper`) and expose that context to local tasks through `executionMemory.webContext`.
-- **Trigger**: A boolean flag on the task request:
+- **Goal**: Retrieve **external web context** for a search query (optionally enriched with record facts) and expose it on `executionMemory.webContext`.
+- **Package**: [`@x12i/web-scoper`](https://www.npmjs.com/package/@x12i/web-scoper) — planning, Tavily search via `@x12i/search-adapter`, normalized `WebContext`.
+- **Adapter layer**: `src/web-scope/` renders the unit's `webQueryTemplate` into `{ question, record?, options? }` (or a pack), then calls the scoper. No Graphenix, Activix, or NARRIX CNI fields are sent.
+- **Trigger** (single, explicit): an `externalPreUtility` execution unit with **`strategyKey: "webScope"`**. There is **no** NARRIX trigger and **no** implicit question fallback.
+- **Search query**: the **rendered `unitParams.webQueryTemplate`** (a Rendrix string, e.g. `"How to solve {{input.vulnerability}}?"`). The template is **required** when the unit is enabled.
+- **Result**:
 
   ```ts
-  RunTaskRequest.narrix = {
-    datasetId: "...",
-    enableWebScope: true,   // ← opt-in; default is false/absent
-  };
+  ctx.executionMemory.webContext: WebScopeResult | WebScopePackResult
   ```
 
-- **Where it runs**:
-  - After a NARRIX run completes successfully (CNI ingested + runner executed).
-  - Implemented in the **task SDK**, in the same flow that invokes the local NARRIX handler.
-- **Where the result lands**:
+  Always set when the unit runs, including miss/error shapes (`ok: false`).
 
-  ```ts
-  ctx.executionMemory.webContext: WebScoperResult
-  ```
-
-  where `WebScoperResult` is defined by `@exellix/narrix-web-scoper` and is always present when `enableWebScope === true`, even on miss/error.
-
-- **Failure stance**: **Lenient.** If web scoping fails or misses, the NARRIX task still runs and `_narrix` output is still attached. Web scoping only affects `executionMemory.webContext` and observability.
+- **Failure stance**: **Lenient at runtime** (web scoping failures do not abort MAIN execution), but **loud and early at validation**: a missing/unresolvable `webQueryTemplate` is a config error.
 
 ---
 
-## 2. Request contract: enabling web scoping
-
-### 2.1. Request shape
-
-ai-tasks exposes NARRIX as a **local task** in the task SDK. The entry-point for callers is a `RunTaskRequest` that may include a `narrix` section used by the NARRIX pre-processor.
-
-The relevant part of the request is:
-
-```ts
-// src/types/task-types.ts (conceptual)
-export interface NarrixPreProcessorConfig {
-  datasetId: string;
-  attachToField?: string;
-  enableWebScope?: boolean; // ← added for web scoping
-}
-
-export interface RunTaskRequest {
-  skillKey: string;
-  input: unknown;
-  narrix?: NarrixPreProcessorConfig;
-  // ... other fields: executionMemory, variables, etc.
-}
-```
-
-- **`narrix.datasetId`**: required; selects which NARRIX dataset / pack to run.
-- **`narrix.enableWebScope`**:
-  - **`true`** → ai-tasks will attempt a web scoping call after NARRIX completes.
-  - **absent / `false`** → web scoping is **completely skipped** for this request.
-
-### 2.2. Example from a graph builder (worox-graphs)
+## 2. Scoper contract (`@x12i/web-scoper`)
 
-Downstream (e.g. `worox-graphs`) forwards configuration from node metadata into the NARRIX config:
-
-```jsonc
-{
-  "metadata": {
-    "narrix": {
-      "datasetId": "network.vuln.instances",
-      "enableWebScope": true
-    }
-  }
-}
-```
-
-In TypeScript:
+### 2.1. Single search
 
 ```ts
-narrix: {
-  datasetId: node.taskConfiguration.narrix.datasetId,
-  attachToField: node.taskConfiguration.narrix.attachToField,
-  enableWebScope: node.taskConfiguration.narrix.enableWebScope ?? false,
-}
-```
-
-Only when that `enableWebScope` flag is `true` will ai-tasks invoke the web scoper.
-
----
-
-## 3. Execution flow inside ai-tasks
-
-### 3.1. NARRIX run
-
-The normal NARRIX pipeline in ai-tasks is:
-
-1. **Ingest** raw input into CNI via `@exellix/narrix-ingest`.
-2. **Run** the NARRIX runner (`@exellix/narrix-runner`) with the CNI and `datasetId`.
-3. **Attach** the NARRIX result to the task’s execution memory.
-
-This produces a **success result** with a shape similar to:
-
-```ts
-export interface NarrixRunOutputSuccess {
-  entity: unknown;
-  signals: unknown;
-  stories: unknown;
-  passes: unknown;
-  meta: unknown;
-  cni?: unknown; // raw CNI (typed more strictly by narrix packages)
-}
+await scoper.search({
+  question: "Is CVE-2021-44228 patched in OpenSSL 3.0?",
+  record?: { cveId: "CVE-2021-44228", product: "openssl" },
+  options?: { maxQueries?: 3, freshnessDays?: 30, /* … */ },
+});
+// → { ok: true, context?: WebContext } | { ok: false, error?: { reason, message? } }
 ```
 
-The success result is attached under `executionMemory._narrix` (or under `attachToField` when configured).
-
-### 3.2. Web scoping hook
-
-After a successful NARRIX run, the task SDK checks `narrix.enableWebScope`:
-
-1. If **absent/false**:
-   - **No web scoping call is made.**
-   - `executionMemory.webContext` remains `undefined`.
-2. If **true**:
-   - ai-tasks builds scope fields via **`resolveWebScopeQuestionAndTemplates`** in `src/narrix/buildWebScopeScopeInput.ts`, then either calls **`runWebScope()`** (`scopeGeneric` / `ScopeInput`) or **`runWebScopeQuestionPack()`** (`scopeQuestionPack` / explicit questions) from `src/narrix/webScoper.ts`.
-   - The result is normalized to **`WebScoperResult`** and written into `executionMemory.webContext` **regardless of hit/miss/error**.
-
-#### 3.2.1 Search question / templates / explicit questions (ISSUE-006, `@exellix/narrix-web-scoper` 1.2.0+)
-
-Optional fields on **`RunTaskRequest.narrix`**:
-
-| Field | Purpose |
-|--------|--------|
-| **`webScopeTemplates`** | Non-empty array → passed as `ScopeInput.webScopeTemplates`. Uses **athenix-parser** token syntax in the web-scoper; **replaces** normal query planning when set. |
-| **`webScopeObjects`** | Merged on top of an **auto-built** context (CNI `knownFacts`, common `entity.graphized.vulnerability.*` fields, `question` / `baseQuestion`, `entityKey` / `label`). |
-| **`webScopeQuestionTemplate`** | When **`webScopeTemplates` is not set**, optional **Handlebars** string to produce the search `question` from that context plus `input` (full task input). |
-| **`webScopeQuestions`** | When **`webScopeTemplates` is not set**, optional list of explicit scope questions. Non-empty after trim → **`scopeQuestionPack`** with `WebScopeQuestion[]` (`id` generated when omitted). Shape: `Array<{ id?: string; question: string; source?: "manual" \| "ai-driven" }>`. |
-| **`webScoping`** | Optional slice of **`WebScoperConfig.scoping`** from `@exellix/narrix-web-scoper` (snippets, caps, raw content, `maxQueries`, `freshnessDays`, etc.). When non-empty, ai-tasks builds a scoper for that request with `createWebScoper({ enabled: true, searchAdapter, scoping: narrix.webScoping })` so behavior matches upstream docs. Omit or leave empty to use the package default scoper (backward compatible). |
-
-**Precedence:**
-
-1. If **`webScopeTemplates`** is set (after trimming empty entries) → scoper receives **`webScopeTemplates`** + merged **`webScopeObjects`** only (no `question` / **`webScopeQuestions`** from this resolver).
-2. Else if **`webScopeQuestions`** is non-empty after normalization → **`runWebScopeQuestionPack`** with **`questions`** only (no single **`question`** / Handlebars path).
-3. Else if **`webScopeQuestionTemplate`** is set → **`question`** = Handlebars render; on template error, fall back to default enrichment.
-4. Else → **`question`** = `input.question` (or string `input`) **plus** appended **CVE / vendor / product** tokens from context when those tokens are **not** already contained in the base question (case-insensitive).
-
-When there is no base question and no enrichable facts, **`question`** may be omitted (empty resolver result).
-
-Conceptually, the call looks like:
+### 2.2. Question pack
 
 ```ts
-import type { ScopeInput, WebScoperResult } from "@exellix/narrix-web-scoper";
-import { runWebScope, runWebScopeQuestionPack } from "../narrix/webScoper.js";
-import { resolveWebScopeQuestionAndTemplates } from "../narrix/buildWebScopeScopeInput.js";
-
-const scopeFields = resolveWebScopeQuestionAndTemplates({
-  narrix: narrixConfig,
-  requestInput: request.input,
-  successResult,
-  entity: /* record medium only */,
+await scoper.searchMany({
+  questions: [{ id: "q1", question: "Patch status?" }, { id: "q2", question: "Workarounds?" }],
+  record?: { /* shared facts */ },
+  options?: { maxQueries?: 2 },
 });
-
-const base = {
-  datasetId: narrixConfig.datasetId,
-  subjectId: successResult.entity.entityKey,
-  entityKind: successResult.entity.entityKind,
-  entity: /* record */,
-  cni: successResult.cni,
-};
-
-const webResult: WebScoperResult = scopeFields.packQuestions?.length
-  ? await runWebScopeQuestionPack({ ...base, questions: scopeFields.packQuestions })
-  : await runWebScope({ ...base, ...scopeFields } as ScopeInput);
-
-ctx.executionMemory.webContext = webResult;
+// → WebScopePackResult with results + pack.scopes
 ```
 
-The **NARRIX output attachment** (`executionMemory._narrix` or the configured `attachToField`) happens independently of web scoping and is not affected by web scoping failures.
+### 2.3. WebContext shape
+
+- **`context.findings[]`**, **`context.sources[]`** (each source requires **`retrievalStage`**: `"discovered" | "fetched" | "extracted"`).
+- **`context.meta`**: `queriesUsed`, `retrievedAt`, `sourceCount`, `evidenceCount`, **`discoveredCount`**, optional intent/strategy/shape.
 
 ---
 
-## 4. `runWebScope` and `WebScoperResult`
+## 3. How ai-tasks compiles the payload
 
-### 4.1. The `runWebScope` helper
+Implementation: **`src/web-scope/buildSearchInput.ts`**, **`src/web-scope/renderWebQueryTemplate.ts`**, **`src/web-scope/applyWebScopeToRequest.ts`**, **`src/web-scope/client.ts`**.
 
-`src/narrix/webScoper.ts` provides a thin, testable wrapper around `@exellix/narrix-web-scoper`:
+### 3.1. Query resolution — rendered template only
 
-- Maintains a **singleton** `NarrixWebScoper` instance in production.
-- Allows tests to **inject** a fake scoper via `setWebScoperForTesting`.
-- Normalizes failures into a consistent `WebScoperResult`.
+The search query is the **rendered `unitParams.webQueryTemplate`**. There is **no** fallback to `input.question`, `taskVariable.question`, or `executionMemory.taskVariables.question`.
 
-The tests in `test/narrix/webScoper.test.ts` show its behavior:
+1. `webScopeInvokeConfigFromUnitParams(unitParams)` reads `webQueryTemplate` (single) and/or `webQueryTemplates` (pack).
+2. `renderWebQueryTemplate(template, request)` renders it with `@x12i/rendrix` `render()` against `buildTemplateContext(request)` — the same roots used by validation (`input`, `jobVariables`, `taskVariables`, `executionMemory`, …).
+3. An empty render (e.g. a template that is only an unresolved token) yields no query → `{ ok: false, error: { reason: "no_queries" } }`.
 
-- **Happy path**:
-  - When the injected scoper returns `{ available: true, context, cached: false }`,
-  - `runWebScope` forwards that as-is, and tests assert:
+### 3.2. Record resolution
 
-    ```ts
-    assert.strictEqual(result.available, true);
-    assert.deepStrictEqual(result.context, webContext);
-    ```
+Merged from (when present):
 
-- **Miss / ineligibility**:
-  - When scoper returns `{ available: false, reason: "notEligible" }`,
-  - `runWebScope` passes this through without throwing:
+- `input.record` or fields on object `input`
+- `executionMemory.input` / `executionMemory.input.raw`
+- CNI `knownFacts` (when facts are passed into the web-scope hop)
 
-    ```ts
-    assert.strictEqual(result.available, false);
-    assert.strictEqual(result.reason, "notEligible");
-    ```
+The record carries **facts only** — the query comes from the template, which references those facts via `{{input.*}}`.
 
-- **Error handling**:
-  - When the scoper throws (e.g. network error, adapter unavailable),
-  - `runWebScope` **catches** the error and returns:
+### 3.3. Options
 
-    ```ts
-    { available: false, reason: "error", error: "<message>" }
-    ```
+| Source | Maps to |
+|--------|---------|
+| `unitParams.options` | `WebScopeOptions` (`maxQueries`, `freshnessDays`, domain filters, `queryTemplates`, …) |
 
-  - Tests assert:
+There are no legacy `webScoping` / `webScopeOptions` / `webScopeQuestions` mappings and no NARRIX option sources.
 
-    ```ts
-    assert.strictEqual(result.available, false);
-    assert.strictEqual(result.reason, "error");
-    assert.ok(result.error?.includes("search timed out"));
-    ```
+### 3.4. Pack mode
 
-### 4.2. Result contract
+When `unitParams.webQueryTemplates` is a non-empty `string[]`, each template is rendered independently (`renderWebQueryTemplates`) into a `searchMany` question pack (UUID ids assigned per question). Otherwise a single `search` runs with the rendered `webQueryTemplate`.
 
-The effective contract, as used by ai-tasks, is:
+### 3.5. The web-scope unit
 
-```ts
-// Hit
-{
-  available: true;
-  context: WebContext; // rich object with findings, queriesUsed, sources, timestamps, ...
-  cached: boolean;
-}
+Graphenix / playground unit:
 
-// Miss or error
+```json
 {
-  available: false;
-  reason: WebScoperMissReason | "error";
-  error?: string; // present when reason === "error"
+  "unitKind": "externalPreUtility",
+  "strategyKey": "webScope",
+  "unitParams": {
+    "enableWebScope": true,
+    "webQueryTemplate": "How to solve {{input.vulnerability}}?",
+    "options": { "maxQueries": 3 }
+  }
 }
 ```
 
-This shape is **stable from the perspective of local tasks**: they only need to check `available` and, optionally, `reason`/`error`.
-
-### 4.3. Source bodies and snippets (`WebSource`)
-
-Upstream behavior is implemented in **`@exellix/narrix-web-scoper`** (and Tavily field mapping in **`@exellix/search-adapter`**). ai-tasks does not map provider JSON; it forwards **`RunTaskRequest.narrix.webScoping`** into the scoper factory when set. Field names and semantics follow the **`@exellix/narrix-web-scoper` README** (current releases use first-class **`providerContent`** / **`providerRawContent`**; **`content`** / **`rawContent`** are legacy mirrors for the same roles).
-
-When **`webScoping.includeSourceSnippets`** is **`true`**, each `WebContext.sources[]` entry may include:
-
-- **`providerContent`** / **`providerRawContent`**: bounded excerpt and optional raw payload from the adapter (when requested).
-- **`content`** / **`rawContent`**: deprecated mirrors of **`providerContent`** / **`providerRawContent`**.
-- **`snippet`**: primary excerpt for the source, chosen via **`webScoping.sourceExcerptFrom`** (default **`providerContent`**, or **`providerRawContent`**, with deprecated aliases **`content`** / **`rawContent`**).
-- **`snippetCharCount`**, **`contentOrigin`**, **`retrievalStage`**, **`contentSource`**, **`score`** / **`rank`**: provenance and metadata when the adapter supplies them (see web-scoper README).
-
-Defaults are backward compatible: **`includeSourceSnippets` defaults to false**, so these fields are omitted unless you opt in (via **`narrix.webScoping`** or the scoper’s own defaults when extended).
-
-Optional caps (only apply when snippets are enabled):
-
-- **`maxSnippetCharsPerSource`**: Unicode cap applied per source to **`providerContent`**, **`providerRawContent`** (and legacy mirrors), and the text chosen for **`snippet`**. When set to a positive number, it is also forwarded as **`snippetMaxChars`** on the shared search request so the adapter can normalize earlier.
-- **`maxTotalWebContextChars`**: additional budget applied **only** to **`WebSource.snippet`** across sources (after each snippet’s per-source cap). It does **not** shrink stored **`providerContent`** / **`providerRawContent`**.
-
-To request raw body text from the provider, set **`webScoping.snippetIncludeRawContent`** (e.g. **`true`** or **`"markdown"`**); it is forwarded as **`includeRawContent`** on search requests. Use **`@exellix/search-adapter`** and **`@exellix/narrix-web-scoper`** versions from the same release family as this repo’s dependencies.
-
-Example:
-
-```ts
-narrix: {
-  datasetId: "network.vuln.instances",
-  enableWebScope: true,
-  webScoping: {
-    includeSourceSnippets: true,
-    maxQueries: 2,
-    maxSnippetCharsPerSource: 4000,
-    snippetIncludeRawContent: false,
-  },
-},
-```
-
----
-
-## 5. How `executionMemory` is affected
-
-### 5.1. Baseline (without web scoping)
-
-Without web scoping, for a NARRIX task, `executionMemory` will generally contain:
-
-- `executionMemory._narrix` — NARRIX run result (entity, signals, stories, passes, meta, etc.).
-- Any initial `executionMemory` provided by the caller (e.g. `executionMemory.input.raw` for raw records).
-
-`executionMemory.webContext` is **undefined** and should not be relied on.
-
-### 5.2. With `enableWebScope: true`
-
-When `enableWebScope` is true:
+Playground input (record/facts only — referenced by the template):
 
-- **Always present**:
-
-  ```ts
-  ctx.executionMemory.webContext: WebScoperResult;
-  ```
-
-  even when the scoper returns a miss or throws an error.
-
-- **Never removed / mutated**:
-  - `_narrix` (or the configured attachment field) is **still present and unchanged**, even when web scoping fails.
-  - Tests explicitly assert that `_narrix` remains present in the error path.
-
-Key behaviors from `test/narrix/webScoper.test.ts`:
-
-- When scoper succeeds:
-  - `webContext.available === true`
-  - `_narrix` is still present.
-- When scoper fails:
-  - `_narrix` is **still present**.
-  - `webContext` exists with `available === false` and `reason === "error"`.
-
-### 5.3. Question forwarding and enrichment
-
-When the caller passes a **natural-language question** in `RunTaskRequest.input.question`, the NARRIX pre-processor derives **`ScopeInput.question`** via **`resolveWebScopeQuestionAndTemplates`** (see §3.2.1): the base string is usually that field, **optionally extended** with CVE / vendor / product from CNI `knownFacts` or common `entity.graphized` paths when those tokens are not already in the question. With **`narrix.webScopeTemplates`**, the scoper uses template-driven queries instead and **`question`** may be omitted.
-
-```ts
-await runTask({
-  skillKey: "skills/skill.local:webScopeTestQuestion",
-  narrix: { datasetId: "test.fixture", enableWebScope: true },
-  executionMemory: { input: { raw: { id: "v3" } } },
-  input: { question: "Is this vulnerability critical?" },
-});
+```json
+{
+  "vulnerability": "CVE-2021-44228",
+  "vendor": "apache"
+}
 ```
 
-Integration tests (with `USE_NARRIX_INGEST=1`) assert the captured `question` when the fixture does not add conflicting CNI facts. Unit tests in the same file cover template precedence, Handlebars `webScopeQuestionTemplate`, and default append behavior.
-
-This allows the scoper to tailor its search and context building to the actual question the LLM or downstream logic is trying to answer, with **entity-specific tokens** when available.
+`enableWebScope` (default `true`) is the on/off switch. When `false`, the unit is a no-op.
 
 ---
 
-## 6. Env and configuration
+## 4. NARRIX (no longer triggers web scope)
 
-### 6.1. Required env: Tavily API
-
-The web scoper uses `@exellix/search-adapter` backed by Tavily. It requires:
-
-- **`TAVILY_API_KEY`** — the API key for Tavily search.
-
-Behavior:
-
-- If `TAVILY_API_KEY` is **missing or invalid**:
-  - The scoper returns `available: false` with an appropriate `reason` (e.g. `"error"`).
-  - ai-tasks surfaces this as `executionMemory.webContext` with `available: false`.
-  - The task **continues** normally using NARRIX output only; `_narrix` is still present.
-
-### 6.2. Other relevant flags
-
-- `USE_NARRIX_INGEST`:
-  - When `"1"`, NARRIX ingest + runner are enabled and web scoping is meaningful.
-  - When not set, NARRIX-related flows (including web scoping) may be skipped or disabled in tests/playgrounds.
-
-Optional per-request **`narrix.webScoping`** forwards snippet/cap/raw-content and query limits into `@exellix/narrix-web-scoper` (see §4.3). The main on/off switch remains **`enableWebScope`**.
+Web scoping is **fully decoupled from NARRIX**. The NARRIX preprocessor/handler still builds its CNI attachment (`executionMemory._narrix` or `attachToField`), but it does **not** trigger or configure web search. To web-scope after NARRIX, add an explicit `webScope` unit to the node plan with its own `webQueryTemplate`.
 
 ---
 
-## 7. Error handling and observability
-
-Web scoping is explicitly designed to **never crash the task**:
+## 5. Environment
 
-- Any exception in the scoper is caught by `runWebScope`.
-- The task SDK:
-  - Continues to attach `_narrix` as usual.
-  - Stores a structured error in `executionMemory.webContext` for debugging.
+- **`TAVILY_API_KEY`** — required for live search. When missing, `webContext.ok === false` with an appropriate error; the task continues.
 
-This gives you:
+Optional:
 
-- Reliable signals in logs / memory:
-  - `webContext.available === false`
-  - `webContext.reason === "error"`
-  - `webContext.error` contains a human-readable message.
-- Freedom to treat web scoping as an **optional enhancement** while still observing its behavior in production.
+- **`WEB_CONTEXT_MARKDOWN_MAX_CHARS`** — caps markdown built from web hits for LLM context (`src/narrix/webContextMarkdown.ts`).
 
 ---
 
-## 8. How to consume web scoping from local tasks
-
-From the perspective of a **local task handler**, web scoping is just another field on `ctx.executionMemory`:
+## 6. Consuming `webContext` in tasks
 
 ```ts
-type LocalTaskHandler = (args: {
-  input: any;
-  ctx: {
-    executionMemory?: {
-      webContext?: WebScoperResult;
-      _narrix?: unknown;
-      // ...
-    };
-    // ...other context fields...
-  };
-}) => Promise<any>;
-```
-
-### 8.1. Recommended consumption pattern
-
-1. **Check for presence**:
-
-   ```ts
-   const webContext = ctx.executionMemory?.webContext;
-   if (!webContext) {
-     // web scoping was not enabled for this task
-   }
-   ```
-
-2. **Branch on `available`**:
-
-   ```ts
-   if (!webContext.available) {
-     // Option A: log / record reason and proceed without web data
-     // Option B: degrade gracefully (e.g. fallback to CNI-only reasoning)
-   } else {
-     // Safe to use webContext.context to enrich reasoning
-   }
-   ```
-
-3. **Do not rely on web scoping for correctness**:
-   - Handlers should behave sensibly even when `webContext` is absent or `available === false`.
-   - Web scoping is an **augmentation**, not a hard dependency.
-
-### 8.2. Example usage (pseudocode)
-
-```ts
-registerLocalTask("skills/skill.local:example", async ({ input, ctx }) => {
-  const narrix = ctx.executionMemory?._narrix;
-  const web = ctx.executionMemory?.webContext;
-
-  if (web?.available) {
-    // Combine NARRIX narrative with fresh web evidence
-    return buildExplanationWithWeb(narrix, web.context);
-  }
-
-  // Fallback: only NARRIX narrative
-  return buildExplanationFromNarrixOnly(narrix);
-});
+const web = ctx.executionMemory?.webContext;
+if (web && "ok" in web && web.ok === true && web.context) {
+  // use web.context.sources, findings, summary
+}
 ```
 
-### 8.3. LLM tasks (`runTask` DIRECT) and synthesized-context
-
-For skills executed through the task SDK with **`includeContextInPrompt: true`**, when NARRIX is in play ai-tasks appends a **Web sources (primary evidence)** markdown section derived from **`executionMemory.webContext`** (when **`available === true`**), using per-source **`providerRawContent`** → **`rawContent`** → **`providerContent`** → **`content`** → **`snippet`**, and labeling **`summary`** / **`findings`** as hints only. The same markdown is merged into source material for the **`synthesized-context`** PRE step under **`narrix-only`** / **`narrix+memory`** (with **`executionMemory.webContext`** stripped from the JSON memory slice when **`narrix+memory`** to avoid duplication). Implementation: **`src/narrix/webContextMarkdown.ts`**. Optional env **`WEB_CONTEXT_MARKDOWN_MAX_CHARS`** caps the size of that markdown string.
+For **`includeContextInPrompt`** / synthesis PRE, ai-tasks builds **Web sources (primary evidence)** markdown when `ok === true`, preferring source `snippet` / `title`. Raw `webContext` JSON is omitted from synthesized memory slices when markdown is included (see `resolveSourceMaterial` tests). Always check **`ok`** on `WebScopeResult` / `WebScopePackResult`.
 
 ---
 
-## 9. Testing strategy and guarantees
-
-ai-tasks contains tests that exercise both **unit-level** and **integration-level** web scoping behavior:
-
-- `test/narrix/webScoper.test.ts`:
-  - Unit-tests **`buildWebScopeTemplateContext`** / **`resolveWebScopeQuestionAndTemplates`** (question enrichment, Handlebars template, `webScopeTemplates` precedence).
-  - Unit-tests `runWebScope` with mocked `NarrixWebScoper`.
-  - Verifies:
-    - Pass-through of `available: true` and `context`.
-    - Stable miss handling (`available: false`, specific `reason`).
-    - Error → `available: false`, `reason: "error"`, populated `error`.
-    - Singleton reset behavior (`resetWebScoperSingleton`, `setWebScoperForTesting`).
-  - Integration with `runTask`:
-    - When `enableWebScope` is **absent**:
-      - `executionMemory.webContext` remains `undefined`.
-    - When `enableWebScope === true` and scoper returns success:
-      - `executionMemory.webContext.available === true`.
-      - `_narrix` is still present.
-    - When scoper throws:
-      - `_narrix` is still present.
-      - `webContext.available === false`, `webContext.reason === "error"`.
-    - When a question is provided (and `webScopeTemplates` is not set):
-      - `ScopeInput.question` equals `request.input.question` when there are no extra CNI/entity tokens to append; otherwise it is the **enriched** string (see §3.2.1).
-    - When `webScopeTemplates` is set:
-      - `ScopeInput.webScopeTemplates` / `webScopeObjects` are passed through as configured (merged with auto-built context).
-
-These tests define the **public contract** of web scoping within ai-tasks: any change that breaks their assertions is a breaking change to web scoping behavior.
+## 7. Testing
 
----
+- **`test/web-scope/buildSearchInput.test.ts`** — template rendering, payload compilation, client error handling, `applyWebScopeToRequest`
+- **`test/validation/validateWebScopeUnit.test.ts`** — required `webQueryTemplate` and token resolution checks
+- **`test/narrix/webContextMarkdown.test.ts`** — markdown from `{ ok, context }`
+- **`test/synthesis/resolveSourceMaterial.test.ts`** — web evidence in source material
+- **`test/utils/collectEvidence.test.ts`** — local handler uses web scoper for query discovery
 
-## 10. Summary of contracts
+Run targeted tests:
 
-- **Opt-in**:
-  - `RunTaskRequest.narrix.enableWebScope === true` is required to trigger web scoping.
-- **Data flow**:
-  - NARRIX → success result (`_narrix`) → web scoper via `ScopeInput` → `executionMemory.webContext`.
-- **Consumer surface**:
-  - Local tasks read `ctx.executionMemory.webContext` and `_narrix`.
-- **Failure behavior**:
-  - Web scoping is **non-fatal**.
-  - `_narrix` is always attached on success, independent of web scoping.
-  - `webContext` is always present when enabled, with `available` + `reason`/`error` for observability.
-- **Config**:
-  - Controlled by per-request `enableWebScope`, optional `webScopeTemplates` / `webScopeObjects` / `webScopeQuestionTemplate` / **`webScoping`** on `narrix`, and `TAVILY_API_KEY` env.
-
-With this, integrators should have enough detail to:
-
-- Correctly enable web scoping from graphs / callers.
-- Reliably consume `executionMemory.webContext` in local tasks.
-- Understand and debug web scoping behavior in logs and execution memory without diving into the entire codebase.
+```bash
+cd ai-tasks && npm run build && npx tsc -p tsconfig.test.json && node --test dist-test/test/web-scope/buildSearchInput.test.js dist-test/test/validation/validateWebScopeUnit.test.js
+```
 
+Live Tavily: **`npm run test:e2e:webScope`** (requires `TAVILY_API_KEY`).