@exellix/ai-tasks 10.0.10 → 10.0.11

package/documenations/activix.md

@@ -1,187 +0,0 @@
-# Activix Integration
-
-This packaged doc summarizes task-activity tracking via `@x12i/activix`.
-
-## Activix Integration Best Practices Checklist
-
-Use this as the operational checklist for integrating `@x12i/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`)
-
-### 6b) Collection tracking state (Activix 8.4+) — always call, let Activix persist
-
-- **Always call** Activix lifecycle APIs on every AI activity phase (`startRecord`, `completeRecord`, `failRecord`, …).
-- **Do not** branch in ai-tasks (or other integrators) on whether to write to Mongo.
-- Activix reads the **`activix-collections`** legend row for your collection and its **`state`**:
-  - **`track`** (default) — rows are persisted
-  - **`off`** — same API and return shapes; Mongo writes are skipped
-- Toggle persistence at runtime: `setCollectionTrackingState('task-activities', 'off' | 'track')`.
-- ai-tasks constructs Activix when **`MONGO_URI`** or **`MONGO_LOGS_URI`** is set; set **`ACTIVIX_ENABLED=false`** only to skip client construction entirely (dev/CI zero-overhead escape hatch).
-- Package collection name is **`task-activities`** (hard-coded in `src/activix/activixClient.ts`).
-
-### 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
-
-- **Client wiring:** Activix is constructed when `MONGO_URI` or `MONGO_LOGS_URI` is set. Set `ACTIVIX_ENABLED=false` to opt out (no client, no lifecycle API calls).
-- **Mongo persistence:** Controlled by Activix collection legend **`state`** (`track` | `off`) in `activix-collections`, not by a required `ACTIVIX_ENABLED=true` flag. ai-tasks always calls lifecycle APIs when wired; Activix decides whether rows reach Mongo.
-- 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`