@exellix/ai-tasks 7.8.0

package/dist/validation/validateRunTaskConfig.js

@@ -0,0 +1,158 @@
+import { SYNTHESIZED_CONTEXT } from "../types/task-types.js";
+import { compileTaskConfigurationOnRunTaskRequest } from "../compile/compileTaskConfiguration.js";
+import { isTaskConfigurationCompileError } from "../errors/taskConfigurationCompileError.js";
+import { collectExecutionPipelineWarnings } from "../utils/runTaskRequestShape.js";
+import { resolveRunTaskRuntimeKnobs } from "../internal/resolveRunTaskRuntimeKnobs.js";
+import { collectSmartInputValidationIssues } from "./collectSmartInputValidationIssues.js";
+import { finalizeValidationResult, isNonEmptyString, pushIssue, validateLlmCallFields, validateModelConfigFields, } from "./helpers.js";
+function validateExecutionPipeline(pipeline, issues) {
+    if (!pipeline?.length)
+        return;
+    const mainSteps = pipeline.filter((s) => s.phase === "main");
+    if (mainSteps.length !== 1) {
+        pushIssue(issues, {
+            code: "PIPELINE_MAIN_COUNT",
+            path: "executionPipeline",
+            message: `executionPipeline must contain exactly one step with phase "main"; got ${mainSteps.length}.`,
+        });
+    }
+    for (const w of collectExecutionPipelineWarnings(pipeline)) {
+        pushIssue(issues, {
+            code: "PIPELINE_UNSUPPORTED_STEP",
+            severity: "warning",
+            path: "executionPipeline",
+            message: w,
+        });
+    }
+    for (let i = 0; i < pipeline.length; i++) {
+        const step = pipeline[i];
+        if (step.phase === "pre" && step.type === SYNTHESIZED_CONTEXT) {
+            const cfg = (step.config ?? {});
+            validateModelConfigFields(cfg.modelConfig, `executionPipeline[${i}].config.modelConfig`, issues);
+            validateLlmCallFields(cfg.llmCall, `executionPipeline[${i}].config.llmCall`, issues);
+        }
+        if (step.phase === "post" && (step.type === "audit" || step.type === "polish")) {
+            const cfg = step.config;
+            if (cfg && typeof cfg === "object") {
+                validateModelConfigFields(cfg.modelConfig, `executionPipeline[${i}].config.modelConfig`, issues);
+                validateLlmCallFields(cfg.llmCall, `executionPipeline[${i}].config.llmCall`, issues);
+                const llm = cfg.llmCall;
+                if (llm && typeof llm === "object" && !Array.isArray(llm)) {
+                    const nested = llm;
+                    if (nested.audit) {
+                        validateLlmCallFields(nested.audit, `executionPipeline[${i}].config.llmCall.audit`, issues);
+                    }
+                    if (nested.synthesis) {
+                        validateLlmCallFields(nested.synthesis, `executionPipeline[${i}].config.llmCall.synthesis`, issues);
+                    }
+                }
+            }
+        }
+    }
+}
+function validateSynthesisPreRequirements(request, issues) {
+    const pipeline = request.executionPipeline;
+    if (!pipeline?.some((s) => s.phase === "pre" && s.type === SYNTHESIZED_CONTEXT))
+        return;
+    const hasContext = request.includeContextInPrompt === true ||
+        pipeline.some((s) => s.phase === "pre" &&
+            s.type === SYNTHESIZED_CONTEXT &&
+            s.config?.autoEnableContext === true);
+    if (!hasContext) {
+        pushIssue(issues, {
+            code: "SYNTHESIS_PRE_REQUIRES_CONTEXT",
+            path: "includeContextInPrompt",
+            message: 'PRE "synthesized-context" requires includeContextInPrompt: true or synthesisConfig.autoEnableContext: true on the PRE step.',
+        });
+    }
+}
+/**
+ * Validate **static** `RunTaskRequest` configuration (model, pipeline, correlation ids, smartInput shape).
+ * Does **not** check whether memory paths resolve — use {@link validateRunTaskInvoke} for that.
+ */
+export function validateRunTaskConfig(request) {
+    const issues = [];
+    let resolved = request;
+    try {
+        resolved = compileTaskConfigurationOnRunTaskRequest(request).request;
+    }
+    catch (e) {
+        if (isTaskConfigurationCompileError(e)) {
+            pushIssue(issues, {
+                code: e.code,
+                path: "taskConfiguration",
+                message: e.message,
+            });
+        }
+        else {
+            throw e;
+        }
+    }
+    const skillKey = String(resolved.skillKey ?? "");
+    if (!isNonEmptyString(resolved.skillKey)) {
+        pushIssue(issues, {
+            code: "MISSING_SKILL_KEY",
+            path: "skillKey",
+            message: "runTask requires a non-empty skillKey.",
+        });
+    }
+    if (!isNonEmptyString(resolved.agentId)) {
+        pushIssue(issues, {
+            code: "MISSING_AGENT_ID",
+            path: "agentId",
+            message: `runTask requires non-empty agentId (@exellix/ai-skills correlation). skillKey: ${skillKey}`,
+        });
+    }
+    if (!isNonEmptyString(resolved.jobTypeId)) {
+        pushIssue(issues, {
+            code: "MISSING_JOB_TYPE_ID",
+            path: "jobTypeId",
+            message: `runTask requires non-empty jobTypeId. skillKey: ${skillKey}`,
+        });
+    }
+    if (!isNonEmptyString(resolved.taskTypeId)) {
+        pushIssue(issues, {
+            code: "MISSING_TASK_TYPE_ID",
+            path: "taskTypeId",
+            message: `runTask requires non-empty taskTypeId. skillKey: ${skillKey}`,
+        });
+    }
+    if (!Array.isArray(resolved.executionStrategies)) {
+        pushIssue(issues, {
+            code: "MISSING_EXECUTION_STRATEGIES",
+            path: "executionStrategies",
+            message: "runTask requires executionStrategies array (use [] for plain MAIN). skillKey: " + skillKey,
+        });
+    }
+    else {
+        try {
+            resolveRunTaskRuntimeKnobs(resolved);
+        }
+        catch (e) {
+            pushIssue(issues, {
+                code: "RUNTIME_KNOBS_INVALID",
+                path: "executionStrategies",
+                message: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    issues.push(...collectSmartInputValidationIssues(resolved.smartInput, skillKey));
+    validateModelConfigFields(resolved.modelConfig, "modelConfig", issues);
+    validateLlmCallFields(resolved.llmCall, "llmCall", issues);
+    if (resolved.timeoutMs !== undefined) {
+        if (typeof resolved.timeoutMs !== "number" || !Number.isFinite(resolved.timeoutMs) || resolved.timeoutMs < 1) {
+            pushIssue(issues, {
+                code: "TIMEOUT_MS_INVALID",
+                path: "timeoutMs",
+                message: "timeoutMs must be a finite number >= 1 when set.",
+            });
+        }
+    }
+    validateExecutionPipeline(resolved.executionPipeline, issues);
+    validateSynthesisPreRequirements(resolved, issues);
+    if (resolved.aiScopingOptions?.llmCall) {
+        validateLlmCallFields(resolved.aiScopingOptions.llmCall, "aiScopingOptions.llmCall", issues);
+    }
+    return finalizeValidationResult(issues);
+}
+//# sourceMappingURL=validateRunTaskConfig.js.map

package/dist/validation/validateRunTaskConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateRunTaskConfig.js","sourceRoot":"","sources":["../../src/validation/validateRunTaskConfig.ts"],"names":[],"mappings":"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"}

package/dist/validation/validateRunTaskInvoke.d.ts

@@ -0,0 +1,30 @@
+import type { RunTaskRequest } from "../types/task-types.js";
+import { type RunTaskTemplateResolver } from "./analyzeExpectedRunTaskInput.js";
+import type { RunTaskInvokeValidationResult } from "./types.js";
+export type ValidateRunTaskInvokeParams = {
+    request: RunTaskRequest;
+    /**
+     * When true (default), resolve skill templates and check expected paths against the request payload.
+     * Set false for a fast config-only pass (same as {@link validateRunTaskConfig}).
+     */
+    analyzeTemplates?: boolean;
+    templateResolver?: RunTaskTemplateResolver;
+    instructions?: string;
+    prompt?: string;
+    /**
+     * When true, add errors for Rendrix `analyzeTemplateResolution` unparsed tokens
+     * (requires `instructions` / `prompt` text or resolver).
+     */
+    checkTemplateResolution?: boolean;
+    /**
+     * When true (default), run Rendrix `renderSmartInput` against the request context
+     * to catch required smart-input paths that are missing (after shape validation passes).
+     */
+    checkSmartInputRender?: boolean;
+};
+/**
+ * Validate **config + payload**: static request shape/model config, then whether expected
+ * smart-input / template paths resolve against `input`, memories, and `xynthesized`.
+ */
+export declare function validateRunTaskInvoke(params: ValidateRunTaskInvokeParams): Promise<RunTaskInvokeValidationResult>;
+//# sourceMappingURL=validateRunTaskInvoke.d.ts.map

package/dist/validation/validateRunTaskInvoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateRunTaskInvoke.d.ts","sourceRoot":"","sources":["../../src/validation/validateRunTaskInvoke.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,kCAAkC,CAAC;AAI1C,OAAO,KAAK,EAAE,6BAA6B,EAA0B,MAAM,YAAY,CAAC;AAExF,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,cAAc,CAAC;IACxB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,6BAA6B,CAAC,CA0GxC"}

package/dist/validation/validateRunTaskInvoke.js

@@ -0,0 +1,108 @@
+import { renderSmartInput, SmartInputRequiredPathMissingError } from "@x12i/rendrix";
+import { normalizeSmartInputConfig } from "../utils/normalizeSmartInputConfig.js";
+import { analyzeExpectedRunTaskInput, checkExpectedInputAgainstRequest, } from "./analyzeExpectedRunTaskInput.js";
+import { collectSmartInputValidationIssues } from "./collectSmartInputValidationIssues.js";
+import { validateRunTaskConfig } from "./validateRunTaskConfig.js";
+import { buildRunTaskValidationContext, finalizeValidationResult, pushIssue } from "./helpers.js";
+/**
+ * Validate **config + payload**: static request shape/model config, then whether expected
+ * smart-input / template paths resolve against `input`, memories, and `xynthesized`.
+ */
+export async function validateRunTaskInvoke(params) {
+    const { request } = params;
+    const configResult = validateRunTaskConfig(request);
+    const issues = [...configResult.issues];
+    const smartInputShapeOk = request.smartInput === undefined ||
+        request.smartInput === null ||
+        collectSmartInputValidationIssues(request.smartInput, request.skillKey).length === 0;
+    if (smartInputShapeOk && request.smartInput && params.checkSmartInputRender !== false) {
+        try {
+            const normalized = normalizeSmartInputConfig(request.smartInput);
+            renderSmartInput({
+                smartInput: normalized,
+                context: buildRunTaskValidationContext(request),
+            });
+        }
+        catch (e) {
+            if (e instanceof SmartInputRequiredPathMissingError) {
+                pushIssue(issues, {
+                    code: e.code,
+                    path: `smartInput.paths (${e.path})`,
+                    message: `${e.message} skillKey: ${request.skillKey}`,
+                });
+            }
+        }
+    }
+    const analyzeTemplates = params.analyzeTemplates !== false;
+    let expected = {
+        paths: [],
+        templateTokens: { instructions: [], prompt: [] },
+    };
+    let missingInputPaths = [];
+    let resolvedInputPaths = [];
+    if (analyzeTemplates) {
+        expected = await analyzeExpectedRunTaskInput({
+            skillKey: request.skillKey,
+            smartInput: request.smartInput,
+            instructions: params.instructions,
+            prompt: params.prompt,
+            templateResolver: params.templateResolver,
+        });
+        let instructionsText = params.instructions ?? "";
+        let promptText = params.prompt ?? "";
+        if (params.templateResolver) {
+            if (!instructionsText) {
+                instructionsText =
+                    (await params.templateResolver.resolveRawTemplate(request.skillKey, "instructions")) ?? "";
+            }
+            if (!promptText) {
+                promptText = (await params.templateResolver.resolveRawTemplate(request.skillKey, "prompt")) ?? "";
+            }
+        }
+        const check = checkExpectedInputAgainstRequest({
+            request,
+            expected,
+            templateTexts: params.checkTemplateResolution === true
+                ? { instructions: instructionsText, prompt: promptText }
+                : undefined,
+        });
+        missingInputPaths = check.missingInputPaths;
+        resolvedInputPaths = check.resolvedInputPaths;
+        for (const entry of check.missingInputPaths) {
+            pushIssue(issues, {
+                code: "REQUIRED_INPUT_PATH_MISSING",
+                path: entry.path,
+                message: `Required input path "${entry.path}" (${entry.source}) is missing or empty on the request. skillKey: ${request.skillKey}`,
+            });
+        }
+        for (const entry of expected.paths) {
+            if (entry.required === true)
+                continue;
+            const row = check.resolvedInputPaths.find((r) => r.path === entry.path);
+            if (row && !row.resolved && entry.source.startsWith("template-")) {
+                pushIssue(issues, {
+                    code: "TEMPLATE_INPUT_PATH_MISSING",
+                    severity: "warning",
+                    path: entry.path,
+                    message: `Template references path "${entry.path}" but it is undefined in the request payload (may be optional in template). skillKey: ${request.skillKey}`,
+                });
+            }
+        }
+        for (const unparsed of check.templateUnresolvedPaths) {
+            pushIssue(issues, {
+                code: "TEMPLATE_TOKEN_UNRESOLVED",
+                severity: "warning",
+                path: unparsed,
+                message: `Template token path not resolved in request context: ${unparsed}. skillKey: ${request.skillKey}`,
+            });
+        }
+    }
+    const finalized = finalizeValidationResult(issues);
+    return {
+        ...finalized,
+        expectedInput: expected,
+        missingInputPaths,
+        resolvedInputPaths,
+    };
+}
+//# sourceMappingURL=validateRunTaskInvoke.js.map

package/dist/validation/validateRunTaskInvoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateRunTaskInvoke.js","sourceRoot":"","sources":["../../src/validation/validateRunTaskInvoke.ts"],"names":[],"mappings":"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"}

package/documenations/activix-feature-request-identity.md

@@ -0,0 +1,123 @@
+# Feature request: Activix first-class `identity` object
+
+## Summary
+
+Extend `@xronoces/activix` to support a **first-class `identity` object** on activity records, so downstream systems can attach a stable identity envelope to every activity and query/group activities consistently.
+
+This request is driven by the task methodology used in `@exellix/ai-tasks` (and the wider stack via `ai-skills`/`ai-gateway`).
+
+---
+
+## Problem
+
+Today, many systems treat identity as “just more metadata” and bury it inside arbitrary blobs. That makes identity:
+
+- inconsistent across producers,
+- hard to query/index,
+- easy to accidentally rename/flatten,
+- easy to drop during updates,
+- hard to standardize across a multi-package pipeline.
+
+We want identity to be a **first-class citizen** in Activix, not an ad-hoc field hidden in random meta objects.
+
+---
+
+## Proposed behavior (contract)
+
+### 1) Record schema supports `identity`
+
+Every Activix record should support a top-level field:
+
+- `identity?: Record<string, unknown>`
+
+Constraints:
+
+- Must be persisted on `startRecord(...)` creation.
+- Must remain intact across lifecycle operations (`completeRecord`, `failRecord`, `patchRecord`) unless explicitly changed.
+- Must be returned by read/query APIs (`getRecord`, `findRecords`, etc).
+
+### 2) Identity is preserved (no mutation by default)
+
+Activix must not:
+
+- rename keys inside `identity`,
+- flatten `identity` into other fields,
+- drop `identity` during updates.
+
+### 3) Query by identity fields must be supported
+
+Because `identity` is an object, querying by identity must be supported by the storage adapter. Minimum requirement:
+
+- `findRecords({ "identity.taskId": "<id>" })` works (Mongo-style dotted-path query)
+
+If Activix abstracts storage backends, the contract should specify which query patterns are supported (at least dotted-path equality for Mongo backend).
+
+### 4) Indexing support (recommended)
+
+To make querying scalable, Activix should support indexes over identity subfields (backend permitting). Recommended index patterns:
+
+- `identity.taskId`
+- optionally `identity.skillId`
+
+This can be implemented as:
+
+- a first-class `indexes` declaration (preferred), or
+- documented guidance for consumers who configure collection indexes.
+
+---
+
+## Required API / typing changes
+
+### `startRecord`
+
+Accept `identity` as a top-level field on the record meta payload:
+
+- `ax.startRecord({ ..., identity })`
+
+### `completeRecord` / `failRecord` / `patchRecord`
+
+Ensure identity is not lost:
+
+- If updates omit `identity`, the stored record keeps the previously set `identity`.
+- If updates include `identity`, treat it as a full replace (or document merge semantics explicitly; default to replace to avoid surprising partial merges).
+
+### Type exports
+
+Expose a stable type for records that includes:
+
+- `identity?: Record<string, unknown>`
+
+---
+
+## Interaction with `@exellix/ai-tasks`
+
+`@exellix/ai-tasks` generates a unique per-run `taskId` and uses it to:
+
+- attach `identity.taskId` to all activity records for that run, and
+- retrieve “activities for the task” by that `taskId`.
+
+Recommended alignment for the task methodology:
+
+- `correlationId` remains the primary “group a run” field, but we will also carry `identity.taskId`.
+- Optionally, stacks may choose to set `correlationId === identity.taskId` for convenience, but this should not be required by Activix.
+
+See also: `documenations/identity-metadata-contract.md`
+
+---
+
+## Backward compatibility
+
+- Records without `identity` remain valid.
+- Existing producers may continue to omit identity.
+- Query APIs should not require identity.
+
+---
+
+## Acceptance criteria
+
+- `identity` can be written on `startRecord`.
+- `identity` remains present after `completeRecord` / `failRecord` unless explicitly overwritten.
+- `identity` is returned by `getRecord` and `findRecords`.
+- Dotted-path queries against identity subfields work for Mongo backend (`"identity.taskId"` equality).
+- Index configuration supports `identity.taskId` (either natively or via documented index config).
+

package/documenations/activix.md

@@ -0,0 +1,175 @@
+# Activix Integration
+
+This packaged doc summarizes task-activity tracking via `@xronoces/activix`.
+
+## Activix Integration Best Practices Checklist
+
+Use this as the operational checklist for integrating `@xronoces/activix` correctly and consistently.
+
+### 1) Ownership and boundaries
+
+- Treat **Activix** as the activity-domain layer:
+  - lifecycle semantics (`start` / `in_progress` / `complete` / `fail`)
+  - activity contract validation
+  - run-context correlation persistence
+- Treat **xronox-store** as the data tier:
+  - cache, write mode, retry policy, Mongo persistence behavior
+  - collection/index management
+  - generic primary-key storage mechanics
+
+### 2) Construct once, reuse instance
+
+- Prefer one `Activix` instance per service process (or one shared `XronoxStore` with `skipStoreInit: true`).
+- Do not create a new `Activix` per tiny unit of work unless architecture requires it.
+- If multi-instance is expected, pass `diagnostics` metadata so logs are self-identifying.
+
+```ts
+const ax = new Activix({
+  storageMode: 'automatic', // or 'database'
+  mongoUri: process.env.MONGO_URI!,
+  collection: 'task-activities',
+  diagnostics: {
+    owner: '@your-org/your-service',
+    component: 'graph-executor',
+    instanceLabel: 'worker-main',
+    workerId: process.pid.toString(),
+  },
+});
+await ax.init();
+```
+
+### 3) Define collection contract explicitly
+
+- Set collection names in code (`collection` or `collections`).
+- Keep `primaryKey` and `primaryKeyPrefix` intentional.
+- If you index `activityId` uniquely, Activix must always persist a non-null `activityId` (current behavior).
+- Ensure store-side visibility matches `purgeAtField` if using soft purge.
+
+### 4) Always pass run context at write time
+
+- `runContext` is runtime context, not constructor config.
+- Always pass a real `sessionId` from true upstream when available.
+- Forward run context through layers; do not replace inherited correlation IDs.
+
+```ts
+const { activityId } = await ax.startRecord({
+  runContext: {
+    sessionId: request.sessionId,
+    jobId: request.jobId,
+    taskId: request.taskId,
+  },
+  outer: {
+    input: payload,
+    output: null,
+    metadata: { type: 'task' },
+  },
+});
+```
+
+### 5) Use lifecycle APIs as intended
+
+- `startRecord()` first; keep returned `activityId`.
+- Use the same `activityId` for all follow-ups:
+  - `markInProgress(activityId, ...)`
+  - `completeRecord(activityId, ...)`
+  - `failRecord(activityId, ...)`
+  - `patchRecord(activityId, ...)`
+  - `getRecord(activityId)`
+- Never pass empty IDs; treat missing ID as integration bug and fail fast.
+
+### 6) Respect payload ownership rules
+
+- Integrators should provide domain payload (`outer`/`inner`/`runContext`).
+- Do not provide lifecycle-owned fields manually:
+  - `activityId` / configured primary key
+  - `status`, `startTime`, `endTime`, `duration`
+  - `createdAt`, `updatedAt`
+  - `error` (except via `failRecord`)
+
+### 7) Validate shape and observability expectations
+
+- `outer` is required and must contain:
+  - `input`
+  - `output` (or omitted initially and normalized)
+  - `metadata` object
+- Optional `inner` must follow request/response/metadata shape.
+- Enable logs during rollout:
+  - `ACTIVIX_LOGS_LEVEL=debug`
+  - `XRONOX_STORE_LOG=1`
+
+### 8) Multi-instance init diagnostics
+
+If `storageMode: 'automatic'`, each Activix instance performs:
+
+1. one Mongo probe
+2. one store init
+
+Use these fields to distinguish healthy multi-instance behavior from bugs:
+
+- `activixInstanceId`
+- `alreadyInitialized`
+- `usingInitPromise`
+- `initCallCount`
+
+Expected pattern: one probe + one store init per `activixInstanceId`.
+
+### 9) Reliability and retry expectations
+
+- Retry/classification policy belongs to xronox-store.
+- For deterministic Mongo failures (e.g. duplicate key), rely on current store behavior/version policy.
+- Keep `@xronoces/xronox-store` up to date and pin known-good versions in CI.
+
+### 10) Minimum production readiness checklist
+
+- [ ] Single shared Activix instance (or intentional multi-instance with diagnostics metadata)
+- [ ] Stable collection configuration committed in code
+- [ ] `runContext.sessionId` passed from upstream for correlated runs
+- [ ] `startRecord` return value (`activityId`) propagated through full lifecycle
+- [ ] Logging flags documented for operations team
+- [ ] Integration test path covers start -> progress -> complete/fail
+- [ ] Dependency version policy defined for `@xronoces/xronox-store`
+
+---
+
+For deeper reference, see:
+
+- `README.md`
+- `.docs/run-context-object.md`
+- `.docs/session-id-usage.md`
+- `.docs/activity-structure.md`
+- `.docs/logging-stack.md`
+
+## What it tracks
+
+A single `runTask()` call can emit phase records such as:
+
+- `local`
+- `narrix`
+- `pipeline_pre`
+- `direct`
+- `audit`
+- `polish`
+- `narrix_then_direct`
+
+All records for a run share a correlation id for grouping.
+
+## Enablement
+
+- Controlled by `ACTIVIX_ENABLED` (default off in README guidance).
+- Activix failures are treated as non-fatal to task execution.
+
+## Typical metadata
+
+- `skillKey`, `executionStrategiesSummary`, `narrixMode`, `jobId`, `agentId`
+- graph/node identity fields
+- start/end/duration, status transitions
+- success metadata and error details
+
+## Stale cleanup
+
+Use stale-marking (for example periodic `markStaleRecords`) to convert stuck `started` records to `timeout`.
+
+## Related
+
+- `README.md` (Activix section)
+- `documenations/run-task-execution-flow.md`