@exellix/ai-tasks 9.0.6 → 9.1.1

package/.docs/questions-for-ai-skills.md

@@ -1,123 +0,0 @@
-# Questions for @woroces/ai-skills Implementation
-
-## Context
-We are implementing `runTask` functionality in `@woroces/ai-tasks` package. The old code (from when `runTask` was in `@woroces/ai-skills`) had memory enrichment and context generation that we need to replicate.
-
-## Old Implementation Reference
-
-From `.docs/code-used-before/run-task.txt`:
-```typescript
-async runTask<TParsed = any>(input: RunTaskRequest): Promise<RunSkillResponse<TParsed>> {
-    // Extract taskId from skillKey (remove "tasks/" prefix if present, or use skillKey as-is)
-    const taskId = input.skillKey.replace(/^tasks\//, '');
-
-    // Build memory bundle
-    const memoryBundle = {
-        jobMemory: input.jobMemory,
-        taskMemory: input.taskMemory
-    };
-
-    // Step 1: Enrich memories with scoping data
-    const enrichedBundle = await this.enrichMemoriesWithScoping(taskId, 'task', memoryBundle);
-
-    // Step 2: Generate context markdown
-    const contextMarkdown = await this.generateContextMarkdown(taskId, 'task', enrichedBundle);
-
-    // Create enriched input
-    const enrichedInput: RunTaskRequest = {
-        ...input,
-        jobMemory: enrichedBundle.jobMemory,
-        taskMemory: enrichedBundle.taskMemory,
-        context: contextMarkdown
-    };
-
-    return this.taskExecutor.execute<TParsed>(enrichedInput, async (key) => {
-        await this.registry.diagnose(key);
-    });
-}
-```
-
-## Questions
-
-### 1. Memory Enrichment Methods
-**Question:** The old code used `this.enrichMemoriesWithScoping()` and `this.generateContextMarkdown()`. These are now private methods in `WorecesSkillsClient`. 
-
-- **Q1.1:** Are these methods exposed through any public API in `WorecesSkillsClient`?
-- **Q1.2:** If not, should we duplicate this logic in `@woroces/ai-tasks`, or is there a better approach?
-- **Q1.3:** The methods use `this.contextManager` - is `contextManager` accessible from outside the client?
-
-### 2. Context Manager Access
-**Question:** The memory enrichment requires a `contextManager` instance.
-
-- **Q2.1:** How do we access or initialize a `contextManager` in `@woroces/ai-tasks`?
-- **Q2.2:** Is `contextManager` part of `WorecesSkillsClient` initialization, or do we need to set it up separately?
-- **Q2.3:** What package provides `contextManager`? Is it `@athenices/execution-memory-manager`?
-
-### 3. Task Executor vs Skill Executor
-**Question:** The old code called `this.taskExecutor.execute()`, but we see that `WorecesSkillsClient` now has `this.executor.execute()` (for skills).
-
-- **Q3.1:** Is there still a `taskExecutor` in `WorecesSkillsClient`, or was it removed?
-- **Q3.2:** For `ExecutionType.DIRECT`, should we:
-  - Call `client.runSkill()` directly (which already does memory enrichment for skills)?
-  - Or do our own memory enrichment for tasks, then call `client.runSkill()`?
-- **Q3.3:** The old `TaskExecutor.execute()` handled `executionType` switching - should we replicate this in our strategy pattern?
-
-### 4. Memory Enrichment for Tasks vs Skills
-**Question:** Looking at `WorecesSkillsClient.runSkill()`, it already does memory enrichment for skills (level: 'skill').
-
-- **Q4.1:** For `runTask`, should we do the same enrichment but with level: 'task'?
-- **Q4.2:** Is the difference between 'skill' and 'task' levels significant, or can we use 'skill' for both?
-- **Q4.3:** The old code extracted `taskId` by removing "tasks/" prefix - should we still do this, or use the skillKey as-is?
-
-### 5. Registry Diagnosis
-**Question:** The old code had `await this.registry.diagnose(key)` as an error callback.
-
-- **Q5.1:** How do we access the registry from `WorecesSkillsClient`?
-- **Q5.2:** Is there a public method to call `diagnose()` on a skill key?
-
-### 6. Implementation Approach
-**Question:** What's the recommended approach for implementing `runTask` in `@woroces/ai-tasks`?
-
-- **Q6.1:** Should we:
-  - Option A: Duplicate the memory enrichment logic from `WorecesSkillsClient`?
-  - Option B: Access internal methods/properties of `WorecesSkillsClient` (if exposed)?
-  - Option C: Call `client.runSkill()` and handle task-specific logic separately?
-  - Option D: Something else?
-
-- **Q6.2:** The current implementation uses a strategy pattern - should memory enrichment happen:
-  - Before strategy selection?
-  - Inside each strategy?
-  - Not at all (if `runSkill` already handles it)?
-
-### 7. Task ID Extraction
-**Question:** The old code did `input.skillKey.replace(/^tasks\//, '')` to extract taskId.
-
-- **Q7.1:** Should we still do this transformation?
-- **Q7.2:** Or should we pass the skillKey as-is to the enrichment methods?
-
-### 8. Error Handling
-**Question:** The old code passed an `onNotFound` callback to `taskExecutor.execute()`.
-
-- **Q8.1:** Does `client.runSkill()` support an `onNotFound` callback?
-- **Q8.2:** How should we handle missing skills/tasks in the new implementation?
-
-## Current Implementation Status
-
-Our current `TaskSDK.runTask()` implementation:
-- ✅ Extracts executionType from request
-- ✅ Uses strategy pattern for execution
-- ❌ Missing: Memory enrichment with scoping
-- ❌ Missing: Context markdown generation
-- ❌ Missing: Task ID extraction (removing "tasks/" prefix)
-- ❌ Missing: Registry diagnosis callback
-
-## What We Need
-
-1. **Clarification** on how to access/use memory enrichment functionality
-2. **Guidance** on whether to duplicate logic or access it from the client
-3. **Confirmation** on the correct flow for task execution vs skill execution
-4. **Documentation** on any public APIs we should be using instead of duplicating code
-
----
-
-**Note:** We want to implement this correctly and avoid duplicating code if there's a better way. Please advise on the recommended approach.

package/.docs/realtime-narrixing-gap-analysis.md

@@ -1,40 +0,0 @@
-# Realtime System-2 Narrixing – Gap Analysis & Test Summary
-
-## Gap analysis (spec vs implementation)
-
-| Spec item | Status | Notes |
-|-----------|--------|--------|
-| **1. Types (types.ts)** | Done | `NarrixSystem2Mode`, `NarrixSmartScope`, `NarrixSystem2Options`, `NarrixRunInputWithOptions`; resolution order documented. |
-| **2. Env config (system2/config.ts)** | Done | All env vars from spec; `system2Env` exported. |
-| **3. Smart init (system2/smartInit.ts)** | Done | `ensureSmartModeInitialized`; dynamic import with cast (packs-library does not yet export smart APIs at compile time). |
-| **4. detectGaps (system2/detectGaps.ts)** | Done | Pure; ok:false and meta.errors/diagnostics/passes; keyword scan; unit tested. |
-| **5. resolveSmartScope (system2/resolveSmartScope.ts)** | Done | Order: smartScope → agentId → domainKey → null; unit tested. |
-| **6. Patch plan + LLM** | Done | `patchPlan.ts` (types + validate), `buildSystem2Input.ts`, `llmPlan.ts` (ai-gateway dynamic import). |
-| **7. applyPatchPlan (system2/applyPatchPlan.ts)** | Done | remember* via dynamic import; skippedWrite when !enableWrites or !scope. |
-| **8. runWithSystem2 (system2/runWithSystem2.ts)** | Done | Options resolution, loop, artifacts write once at end. |
-| **9. task.ts wiring** | Done | `resolveOptions` from raw input + ctx; `runWithSystem2(..., system1Runner)`; no system2 field when OFF. |
-| **10. artifacts (system2/artifacts.ts)** | Done | `writeArtifacts` under `artifactDir/datasetId/timestamp/`; all listed files. |
-| **11. Unit tests** | Done | detectGaps (5), resolveSmartScope (5), validatePatchPlan (6), OFF mode (2). |
-
-## External dependencies (not in this repo)
-
-- **@narrices/narrix-packs-library**: Smart mode APIs (`createXronoxFromEnv`, `configurePacksLibrarySmartMode`, `rememberDatasetPackRouting`, `rememberDatasetProcessorRouting`, `rememberRecordSchemaOverride`) are **not** in the current type definitions; code uses dynamic import and runtime checks. When the package adds these exports, no ai-tasks code change is needed.
-- **@athenices/ai-gateway**: Used in `llmPlan.ts` (dynamic import). Request shape may need to match your gateway’s actual API (jobId, agentId, instructions, config.model, response content).
-
-- **System-2 model**: Resolved from (1) `input.system2.model`, (2) env `NARRIX_SYSTEM2_MODEL`, (3) default **`gpt-5-mini`** (use gpt-5-nano or gpt-5-mini; override via env or input).
-
-## Tests run (for real)
-
-- **System-2 unit tests** (no narrix ingest, no LLM):
-  - `detectGaps.test.js`: 5/5 pass
-  - `resolveSmartScope.test.js`: 5/5 pass
-  - `patchPlan.test.js`: 6/6 pass
-  - `offMode.test.js`: 2/2 pass (handler returns no `system2` when mode OFF or omitted)
-- **System-2 E2E (real token + ai-gateway)**:
-  - `e2e-system2-real.test.ts`: Run with `RUN_SYSTEM2_E2E=1 USE_NARRIX_INGEST=1 NARRIX_SYSTEM2_MODEL=<model>` (and real API token in `.env`). Triggers a gap (unknown dataset), calls real ai-gateway, asserts `system2` metadata and `system2.llm` (real call). **Test passed** with `workingMemory.input` request shape; LLM returned valid PatchPlan JSON (`actions: [], rerun: false`).
-- **Full `npm test`**: Includes existing narrix and narrix-then-execute tests; some subtests are skipped when `USE_NARRIX_INGEST=1` is not set or when real LLM is not desired.
-
-## Acceptance criteria (spec)
-
-- **OFF mode**: Output unchanged, no `system2` field, no xronox init, no ai-gateway – verified by OFF mode tests.
-- **AUTO / scope / writes / artifacts**: Implemented as specified; full E2E depends on packs-library smart APIs and ai-gateway being available at runtime.

package/.docs/realtime-narrixing.md

@@ -1,433 +0,0 @@
-Below is  start→finish spec** for **`@woroces/ai-tasks`** to add **System-2 “real-time narrixing”** using:
-
-* **Narrix System-1** (existing: ingest + runner)
-* **System-2** (new: ai-gateway LLM that decides what to remember/do)
-* **Persistence** via the **new smart mode in `@narrices/narrix-packs-library`** (Xronox overlay; domain/agent scoping)
-
-This spec assumes your packs-library smart APIs exist exactly as described in your README summary.
-
----
-
-# 0) Goal (what this adds)
-
-When ai-tasks receives a Narrix input (record/text/docs/chat):
-
-1. Run Narrix normally (System-1).
-2. If it fails or attaches “missing mapping / processor not matched / schema missing” style errors, then:
-
-   * System-2 calls an LLM (via `@athenices/ai-gateway`) to produce a **Patch Plan** (JSON).
-   * Apply patch plan by calling packs-library smart “remember*” APIs (writes to Xronox overlay).
-   * Re-run Narrix (System-1) again (now with remembered routing/schema).
-3. Return final result plus **system2 metadata** (only when system2 ran).
-
-**Safety:** When System-2 mode is OFF, behavior is exactly as today.
-
----
-
-# 1) Add System-2 modes and input options
-
-## 1.1 Extend Narrix input types to accept System-2 options
-
-**Edit:** `src/narrix/types.ts`
-
-Add:
-
-```ts
-export type NarrixSystem2Mode = "OFF" | "AUTO" | "AUTO_HIGH" | "ALWAYS";
-
-export type NarrixSmartScope =
-  | { scopeType: "domain"; key: string }
-  | { scopeType: "agent"; key: string };
-
-export type NarrixSystem2Options = {
-  mode?: NarrixSystem2Mode;
-  force?: boolean;
-
-  // Smart overlay
-  smartScope?: NarrixSmartScope;
-  enableWrites?: boolean; // default false; must be true to remember
-
-  // LLM behavior (ai-gateway)
-  model?: string;         // required when mode != OFF
-  maxIterations?: number; // default 2 (patch + rerun; allow 2)
-  stakes?: "low" | "high";
-
-  // Artifacts (dev)
-  saveArtifacts?: boolean;
-  artifactDir?: string;
-};
-```
-
-Then add to your run input:
-
-* allow `input.system2?: NarrixSystem2Options`
-* and/or `input.options?.system2?: NarrixSystem2Options`
-
-**Resolution precedence in handler:**
-
-1. `input.system2`
-2. `input.options.system2`
-3. `ctx.variables.narrixSystem2`
-4. env defaults
-
----
-
-# 2) Add env defaults (consistent with current style)
-
-**Create:** `src/narrix/system2/config.ts`
-
-Env vars:
-
-* `NARRIX_SYSTEM2_MODE` default `OFF`
-* `NARRIX_SYSTEM2_ENABLE_WRITES` default `0`
-* `NARRIX_SYSTEM2_MAX_ITERATIONS` default `2`
-* `NARRIX_SYSTEM2_MODEL` (required if mode != OFF and not provided in input)
-* `NARRIX_SYSTEM2_SAVE_ARTIFACTS` default `0`
-* `NARRIX_SYSTEM2_ARTIFACT_DIR` default `.tests/test-output/narrix-system2`
-
-Smart overlay (packs-library):
-
-* `NARRIX_SMART_ROLE` default `"reader"` (or `"writer"` if you want; but safest default is reader)
-* No fixed domain: must come from input/ctx (see below)
-
----
-
-# 3) Configure packs-library smart mode in ai-tasks
-
-You’ll initialize Xronox and configure packs-library smart mode once.
-
-## 3.1 Add dependency imports
-
-**Edit:** `src/narrix/narrixClient.ts` (or a new `src/narrix/system2/smartInit.ts`)
-
-Add imports from `@narrices/narrix-packs-library`:
-
-* `configurePacksLibrarySmartMode`
-* `createXronoxFromEnv` (per your README update summary)
-* plus smart APIs will be called later by ai-tasks, not here.
-
-### Create a singleton init
-
-**Create:** `src/narrix/system2/smartInit.ts`
-
-```ts
-let smartInitPromise: Promise<void> | null = null;
-
-export function ensureSmartModeInitialized(opts: {
-  enableWrites: boolean;
-  role?: "reader" | "writer";
-}) {
-  if (smartInitPromise) return smartInitPromise;
-  smartInitPromise = (async () => {
-    const xronox = createXronoxFromEnv(); // uses MONGO_URI, MONGO_KNOWLEDGE_DB
-    configurePacksLibrarySmartMode({
-      xronox,
-      enableWrites: opts.enableWrites,
-      role: opts.role ?? (opts.enableWrites ? "writer" : "reader")
-      // NOTE: do not set domain here; domain comes via smartScope per call
-    });
-  })();
-  return smartInitPromise;
-}
-```
-
-**Important:** Initialize only when System-2 mode is not OFF OR when smart reads are enabled.
-
----
-
-# 4) Add error detection triggers (when System-2 should run)
-
-You said runner runtime is configured to attach errors for:
-
-* processor not matched
-* missing mapping
-
-We need a robust detector that doesn’t assume exact shape.
-
-**Create:** `src/narrix/system2/detectGaps.ts`
-
-Input: Narrix success output or failure output.
-
-Output:
-
-```ts
-{
-  hasGap: boolean;
-  reasons: string[];
-  gapHints: {
-    processorNotMatched?: boolean;
-    missingMapping?: boolean;
-    missingSchema?: boolean;
-    unknownDataset?: boolean;
-    details?: any; // extracted snippets to feed LLM
-  };
-}
-```
-
-Detection strategy (v1, pragmatic):
-
-* If `ok:false` → `hasGap=true`, reason includes `error`
-* Else if `meta` contains `errors` array → scan strings/objects for keywords:
-
-  * `"ProcessorNotMatched"` / `"processor not matched"`
-  * `"MissingMapping"` / `"missing mapping"`
-  * `"schema"` / `"record schema"` / `"roleMap"`
-* Also scan `passes` if present (many systems attach errors there).
-* Keep extraction generic:
-
-  * collect up to N error objects/strings to include in LLM input.
-
-This function should be pure and unit-tested.
-
----
-
-# 5) Resolve smart scope per request (domain/agent)
-
-System-2 memory must be scoped.
-
-**Create:** `src/narrix/system2/resolveSmartScope.ts`
-
-Resolution order:
-
-1. `system2.smartScope` if provided
-2. else if `ctx.agentId` exists → `{ scopeType:"agent", key: ctx.agentId }`
-3. else if `ctx.variables.domainKey` exists → `{ scopeType:"domain", key: ctx.variables.domainKey }`
-4. else → **no scope** (System-2 may still run, but cannot “remember”; it will return patch suggestions only)
-
-**Write gating:**
-
-* if no scope → do not call remember* even if enableWrites true (log reason)
-* if scope exists and enableWrites false → do not remember, only rerun if possible without writes
-
----
-
-# 6) System-2 Patch Plan: LLM via ai-gateway
-
-We add a new module that produces a patch plan JSON.
-This is the “thinking”.
-
-## 6.1 Patch plan schema (JSON-only)
-
-**Create:** `src/narrix/system2/patchPlan.ts`
-
-```ts
-export type PatchPlan = {
-  actions: Array<
-    | {
-        type: "rememberDatasetPackRouting";
-        datasetId: string;
-        packId: string;
-      }
-    | {
-        type: "rememberDatasetProcessorRouting";
-        datasetId: string;
-        packId: string;
-        processorId: string;
-        entityKind: string;
-      }
-    | {
-        type: "rememberRecordSchemaOverride";
-        packId: string;
-        entityKind: string;
-        mergeStrategy: "deepMerge";
-        schemaOverride: any; // json schema fragment
-      }
-  >;
-  rerun: boolean; // whether to rerun system-1 after actions
-  notes?: string[];
-  confidence?: number;
-};
-```
-
-## 6.2 Build the LLM prompt input (compact, deterministic)
-
-**Create:** `src/narrix/system2/buildSystem2Input.ts`
-
-Given:
-
-* original request input
-* narrix result
-* detected gap hints
-  Return a string that includes:
-* datasetId, medium
-* current chosen packId/entityKind if any
-* list of signals/stories (codes/ids)
-* extracted errors snippets
-* record signature: top-level keys + a few nested paths (no full dump)
-* strict instruction: “Return JSON only matching PatchPlan schema”
-
-Keep this under a size limit.
-
-## 6.3 Call ai-gateway and parse JSON
-
-**Create:** `src/narrix/system2/llmPlan.ts`
-
-Use `@athenices/ai-gateway` (same style as your platform uses). Requirements you previously noted:
-
-* need `jobId`, `agentId`, `instructions`, and `config.model` for request.
-
-Implementation:
-
-* `instructions`: a strict System-2 instruction:
-
-  * “You are System-2. Produce PatchPlan JSON only. No markdown.”
-  * include allowed actions list and schema
-* `input`: output of `buildSystem2Input`
-
-Return:
-
-* parsed PatchPlan (validate with runtime checks)
-* metadata (model, tokens, cost, latency, activityId if available)
-
----
-
-# 7) Apply Patch Plan (write through packs-library smart APIs)
-
-**Create:** `src/narrix/system2/applyPatchPlan.ts`
-
-Inputs:
-
-* `plan: PatchPlan`
-* `smartScope`
-* `enableWrites`
-
-Behavior:
-
-* For each action:
-
-  * call the corresponding packs-library function:
-
-    * `rememberDatasetPackRouting(scope, { datasetId, packId })`
-    * `rememberDatasetProcessorRouting(scope, { datasetId, packId, processorId, entityKind })`
-    * `rememberRecordSchemaOverride(scope, { packId, entityKind, schemaOverride, mergeStrategy })`
-* If writes are disabled → don’t call them; collect “skippedWrite” notes.
-* Return an `applied[]` list with status per action.
-
-**Important:** these functions should throw clear errors when writes disabled; catch and record in system2 meta.
-
----
-
-# 8) Rerun System-1 after patch (iteration control)
-
-**Create:** `src/narrix/system2/runWithSystem2.ts`
-
-Algorithm:
-
-1. Run System-1 (existing).
-2. If mode OFF → return.
-3. Detect gaps.
-4. If no gap and mode != ALWAYS → return.
-5. Ensure smart mode initialized:
-
-   * `ensureSmartModeInitialized({ enableWrites, role: enableWrites ? "writer" : "reader" })`
-6. Resolve smartScope.
-7. For `iter=1..maxIterations`:
-
-   * Call `llmPlan(...)` → PatchPlan
-   * Apply patch plan
-   * If plan.rerun is false → stop (return original result + meta)
-   * Rerun System-1
-   * Detect gaps again; if resolved → stop
-8. Return last result with `system2` metadata attached.
-
-Default `maxIterations=2` is enough:
-
-* Iter 1: propose and remember
-* Rerun
-* If still failing, iter 2 tries a smaller fix
-
----
-
-# 9) Wire it into `narrixRunHandler`
-
-**Edit:** `src/narrix/task.ts`
-
-After you normalize input and before returning:
-
-* Call `runWithSystem2({ input, ctx }, () => system1RunnerFn)`
-
-Where `system1RunnerFn` is the existing switch:
-
-* record/text/docs/chat
-
-**Behavior preservation:**
-
-* If mode OFF (default) → this wrapper returns exactly system1 output with no extra fields.
-
-**When system2 ran:**
-Add a top-level optional field (only then):
-
-```ts
-system2?: {
-  mode: NarrixSystem2Mode;
-  reasons: string[];
-  iterations: number;
-  appliedActions: Array<{ type: string; ok: boolean; error?: string }>;
-  llm?: { model?: string; tokens?: any; cost?: number; activityId?: string; latencyMs?: number };
-  scope?: { scopeType: "domain" | "agent"; key: string } | null;
-}
-```
-
----
-
-# 10) Artifacts (playground inspection)
-
-**Create:** `src/narrix/system2/artifacts.ts`
-
-If `saveArtifacts=true`:
-Write under:
-
-* `${artifactDir}/${datasetId}/${timestampOrHash}/`
-
-Files:
-
-* `input.json` (sanitized if needed)
-* `system1-result.json`
-* `gap-detect.json`
-* `system2-plan.json`
-* `system2-applied.json`
-* `system1-rerun-result.json`
-* `_summary.json`
-
-This is super useful for debugging System-2.
-
----
-
-# 11) Tests
-
-Add unit tests without private deps:
-
-1. `detectGaps` correctly flags simulated attachError structures
-2. `resolveSmartScope` chooses agent by default when present
-3. PatchPlan validation rejects invalid output
-4. OFF mode path does not initialize xronox and does not call ai-gateway
-
-For integration tests:
-
-* If `.env` provides `MONGO_URI` and `MONGO_KNOWLEDGE_DB` (as you described), you can run a real memory write+read test:
-
-  * apply patch plan
-  * verify record exists in Xronox knowledge DB
-
----
-
-# Acceptance criteria checklist
-
-✅ **OFF mode**: output unchanged, no new fields, no xronox init, no ai-gateway
-✅ **AUTO mode**: on missing mapping / processor mismatch, generates patch plan, writes remembered overrides, reruns, improves outcome
-✅ **Scope generic**: supports either `{scopeType:"agent"}` or `{scopeType:"domain"}`
-✅ **Writes gated**: no “remember” without `enableWrites=true` AND a scope
-✅ **Artifacts**: optional, in `.tests/test-output/narrix-system2/...`
-
----
-
-# What you need to pass in ai-tasks requests (minimum)
-
-For System-2 to actually “remember”:
-
-* `system2.mode = "AUTO" | "AUTO_HIGH" | "ALWAYS"`
-* `system2.smartScope = { scopeType:"agent"|"domain", key:"..." }`
-  (or rely on `ctx.agentId` auto-scope)
-* `system2.enableWrites = true`
-* `system2.model` (or `NARRIX_SYSTEM2_MODEL` env)
-

package/.docs/run-context-object.md

@@ -1,32 +0,0 @@
-# Run Context Object (Activix)
-
-`runContext` is the **runtime correlation envelope** written with each activity record. It is **not** constructor configuration and should be passed at write time (e.g. `startRecord`, `patchRecord`, `completeRecord`, `failRecord`).
-
-## Goals
-
-- Preserve upstream correlation identifiers end-to-end.
-- Make multi-phase / multi-step activity streams queryable by stable IDs.
-- Avoid re-inventing correlation fields ad-hoc in `outer.metadata`.
-
-## Recommended fields
-
-- `sessionId` (string, recommended): stable correlation id from the true upstream request/session when available.
-- `jobId` (string, optional): job/workflow run identifier.
-- `taskId` (string, optional): logical task identifier.
-- Any additional domain identifiers that are stable and queryable for your org.
-
-## Rules of thumb
-
-- Always pass a real upstream `sessionId` when available.
-- Forward `runContext` through layers; don’t overwrite inherited IDs.
-- Don’t embed large payloads in `runContext` (use `outer` for I/O payload).
-
-## Minimal example
-
-```ts
-await ax.startRecord({
-  runContext: { sessionId, jobId, taskId },
-  outer: { input, output: null, metadata: { type: 'task' } },
-});
-```
-

package/.docs/session-id-usage.md

@@ -1,26 +0,0 @@
-# Session ID Usage (Activix)
-
-`runContext.sessionId` is the **primary correlation id** you should carry from upstream into Activix writes whenever possible.
-
-## Why it matters
-
-- Groups multiple activity records into one logical run across phases/services.
-- Enables fast queries for “everything that happened for this run”.
-- Improves observability without requiring log-scraping or brittle heuristics.
-
-## Best practices
-
-- Prefer a true upstream `sessionId` (API gateway request id, workflow run id, user session id, etc.).
-- If you must generate one, generate it **once** at the edge of your workflow and propagate it.
-- Never “replace” an inherited `sessionId` in a lower layer.
-- If you use both `sessionId` and `jobId`, keep them consistent (session = correlation, job = orchestration).
-
-## Minimal example
-
-```ts
-await ax.startRecord({
-  runContext: { sessionId: request.sessionId, jobId: request.jobId },
-  outer: { input: payload, output: null, metadata: { type: 'task' } },
-});
-```
-