# Changelog

## 9.0.6 — 2026-07-12

### Changed

- **`@x12i/ai-tools@^5.1.0`** (catalog SoT via `@x12i/ai-profiles@^4.4.0`).

## 9.0.5 — 2026-07-10

### Changed

- **`@x12i/ai-tools@^5.0.1`** (catalog SoT via `@x12i/ai-profiles@^4.3.0`).

## 9.0.4 — 2026-07-10

### Changed

- **`@x12i/ai-tools@^5.0.0`** (catalog SoT via `@x12i/ai-profiles@^4.2.1`). Auto-cost `cheap/default` resolves to **`google/gemma-3-4b-it`**.
- **`@x12i/activix-contracts@^1.5.2`**.

## 9.0.3 — 2026-07-07

### Changed

- **`@x12i/ai-tools@^4.0.0`**.

## 9.0.2 — 2026-06-27

### Changed

- **`@x12i/ai-tools@^3.3.5`**.

## 9.0.1 — 2026-06-27

### Changed

- **`@x12i/ai-tools@^3.3.4`** — aligns with ai-profiles 3.4.x for cost/catalog resolution.

## 9.0.0 — 2026-06-26

### Changed (breaking)

- **Default `storageMode` when omitted** is now **context-aware** instead of **`automatic`**:
  - **`mongoUri`** (or env via **`resolveActivixMongoUriFromEnv()`**) present → **`database`** — no connectivity probe; **`init()`** fails if Mongo is unreachable (no silent fallback to playground).
  - No URI → **`local`** playground.
- **`storageMode: 'automatic'`** remains an **explicit** dev/CI opt-in (probe once on **`init()`**, fall back to playground when Mongo is down).

### Migration

| Before (8.x, omit mode) | After (9.x, omit mode) |
|-------------------------|-------------------------|
| URI + Mongo down → local playground | **`init()` throws** |
| URI + Mongo up → database | database (unchanged) |
| No URI → local playground | local playground (unchanged) |

Playground and dev hosts should pass **`storageMode: 'automatic'`** explicitly. See [../../.docs/MIGRATION-CONSUMERS.md](../../.docs/MIGRATION-CONSUMERS.md).

## 8.6.1 — 2026-06-05

### Fixed

- **Collection legend registry noise:** optional `activix-collections` legend reads are skipped when Mongo storage is used without a configured `xronox` engine or before the store is connected. Prevents `xronox-store: getByKey without xronox | collection: activix-collections` during graph simulate/dev runs; activity tracking defaults to `track`.

## 8.5.2 — 2026-06-05

### Changed

- Depends on **`@x12i/ai-tools@^3.0.0`** (aligned with **`@x12i/ai-profiles` v3** — strict `profile/choice` or concrete model ids only; no shortcuts, bare profiles, or legacy shorthands).
- Cost integration imports **`@x12i/ai-tools/cost`** and **`@x12i/ai-tools/catalog`** subpaths (no local resolution workarounds).
- **Node.js `>=20`** required (matches ai-tools).

## 8.5.0 — 2026-05-31

### Added

- **`createActivixTrackingManager(activix)`** — component-level `listTrackingTargets()` / `setTrackingState()` for runtime object trees (maps to legend `state` per collection).
- **`composeActivixTrackingManagers([...])`** — merge package-owned managers without crossing package boundaries.
- **`Activix.listTrackingManagedCollections()`** — configured activity collections that participate in tracking state.
- **`ActivixTrackingManagerError`** — `UNKNOWN_COMPONENT`, `NOT_CONFIGURABLE`, `TRACKING_CHANGES_LOCKED`.

### Changed

- Depends on **`@x12i/activix-contracts@^1.5.0`**.

## 8.4.1 — 2026-05-31

### Fixed

- **Missing legend `state`** — pre-existing **`activix-collections`** rows without a **`state`** field behave as **`track`** (activities persist). **`getCollectionLegend`** / **`listCollectionLegends`** return **`state: 'track'`** at read time.

### Changed

- Depends on **`@x12i/activix-contracts@^1.4.1`**.

## 8.4.0 — 2026-05-31

### Added

- **Collection tracking state** — legend rows in **`activix-collections`** may set **`state: 'track' | 'off'`**. When **`off`**, Activix skips Mongo writes for that collection; integrators should still call all Activix APIs unchanged.
- **`setCollectionTrackingState(collectionName, state)`** — toggle persistence; updates DB and in-process cache immediately.
- **`refreshCollectionTrackingStates({ collection? })`** — re-read legend **`state`** after external DB changes (bypasses TTL cache).
- **TTL cache** for legend **`state`** (default **600 s**): **`ACTIVIX_COLLECTION_TRACKING_STATE_TTL_SEC`** or **`collectionTrackingStateRefreshIntervalSec`** on the constructor. Use **`0`** to re-read on every write.
- Helpers: **`resolveActivixCollectionTrackingStateTtlSec()`**, **`DEFAULT_ACTIVIX_COLLECTION_TRACKING_STATE_TTL_SEC`**.

### Changed

- Depends on **`@x12i/activix-contracts@^1.4.0`**.

## 8.3.1 — 2026-05-28

### Changed

- **Removed `@x12i/logxer` dependency.** Internal diagnostics use built-in console logging with the same env contract (`ENABLE_ACTIVIX_LOGXER`, `ACTIVIX_LOGS_LEVEL`). Structured logging via logxer lives in **`@x12i/optimixer`** only.

## 8.0.6 — 2026-05-28

### Added

- **Directory export trace shape:** `exportRecordsToDirectory` / `exportAllRecordsToDirectory` attach a normalized **`trace`** block per row by default (`traceShape: true`; set `traceShape: false` for raw Mongo snapshots).
- Re-exports trace helpers from `@x12i/activix-contracts@^1.0.3`.
- Docs: [`.docs/activity-trace-schema.md`](./.docs/activity-trace-schema.md); README sections on `activityKind` vs `activityType`, observability fields, graph ↔ ai-tasks joins.

### Changed

- Depends on **`@x12i/activix-contracts@^1.0.3`**.

## 8.0.2 — 2026-05-27

### Fixed

- **`@x12i/activix-contracts@^1.0.1`** required (adds `mergeRecordConfig` / `resolveRecordConfig`). Fixes broken **8.0.1** publish that referenced exports not yet on registry contracts **1.0.0**.

## 8.0.1 — 2026-05-27

### Fixed

- **`config` shallow-merge** on `failRecord` / `completeRecord` / partial updates (preserves `model` / `provider` when fail payload only patches `maxTokens`).
- **Failure diagnostics**: `summarizeActivixActivityForDiagnostics` exposes `maxTokens`, `hasUsage`, `usageTotalTokens`, `costUsd`.

## 8.0.0 — 2026-05-27

### Added

- Depends on **`@x12i/activix-contracts`**; re-exports contract types (`ActivixActivityRecord`, `ActivixWriterClient`, `ActivixReaderClient`, etc.) for backward compatibility.
- **`Activix.create()`** — construct + `init()` in one call (already documented; now stable in monorepo v8).

### Changed

- Monorepo layout: package lives under `packages/activix/`.
- Pure structure/cost validation helpers sourced from `@x12i/activix-contracts`.

## Unreleased

### Fixed

- **Failure / bad-request persistence:** lifecycle writes now **materialize** merged routing into top-level **`config`** and mirror provider/model/maxTokens/cost onto **`outer.metadata`** (gateway-style billing mirror). Applies on `startRecord`, `completeRecord`, `failRecord` (including upsert), `markInProgress`, and `patchRecord`. Partial **usage** on failure still flows through `outer.output`; **auto-cost** continues to populate **`outer.cost`** and the mirror copies it to **`outer.metadata.cost`** when present.

### Changed

- **Internal diagnostics are now full-opt-in via `ENABLE_ACTIVIX_LOGXER=true`.** When unset, Activix runs error-only so routine info/warn/debug logs do not create feedback loops where logging reports on activity-log writes. `ACTIVIX_LOGS_LEVEL` only applies after the enable flag is set.

## 7.0.0

### Breaking

- **`ActivixMultiCollectionOptions.defaultCollection`** is **required** when using **`collections`** (no implicit default of the first entry).
- **`resolveActivixPersistenceTarget`** and **`countActivixActivitiesInMongo`**, **`getActivixLatestActivitySummariesInMongo`**, **`getActivixActivityPersistenceSnapshotInMongo`** require **`collection`** in options (no environment fallback).
- **`resolveActivixActivitiesCollectionName()`** throws if **`ACTIVIX_COLLECTION`** and **`MONGO_LOGS_COLLECTION`** are both unset (removed default **`"activities"`**).
- Job helpers (**`startJob`**, **`endJob`**, **`getJob`**, **`listJobs`**, **`getJobBundle`**) no longer default to collection **`"jobs"`**. Set **`jobsCollection`** on **`Activix`** options or pass **`{ collection }`** / **`{ jobsCollection }`** on each call.
- When Activix builds the store, **`activix-collections`** is registered by default unless **`collectionRegistry: false`**. After **`init()`**, missing legend rows are inserted for every configured collection unless **`skipAutoInsertForCollections`** opts out. Requires **`diagnostics.owner`** or **`collectionRegistry.owner`**.

### Added

- **`collectionRegistry`** option (**`ActivixCollectionRegistryOptions`**) and automatic collection-registry sync after **`init()`**.

## 6.0.1

### Changed

- **Phased I/O:** **`outer.output`** and **`inner.response`** may be **omitted** on early writes; they are normalized to **`null`** in **`validateActivityStructure`** (which **mutates** the document) and after **`mergeOuterTier`** / **`mergeInnerTier`**. Supports the usual order: **`outer.input`** (optionally with **`inner.request`**), then later **`inner.response`** and/or **`outer.output`**. New helpers **`ensureOuterTierShape`**, **`ensureInnerTierShape`**; **`mergeOuterTier`** / **`mergeInnerTier`** are exported. See [`.docs/activity-structure.md`](./.docs/activity-structure.md#phased-writes-typical-order).

## 6.0.0

### Breaking

- **Activity I/O is at the document root** — no nested **`structure`** object. Required **`outer`**: **`input`**, **`output`**, **`metadata`**. Optional **`inner`**: **`request`**, **`response`**, **`metadata`** (replaces `inner` using `input`/`output`).
- **Removed** collection option **`structureField`**.
- **Helpers:** prefer **`activixOuterTier`**, **`activixInnerTier`**, **`activixActivityIo`**, **`mergeActivixActivityIo`**. Deprecated aliases **`activixTier`** (= `activixOuterTier`), **`activixStructure`** (= `activixActivityIo`), **`mergeActivityStructureField`** (= `mergeActivixActivityIo`), **`DEFAULT_STRUCTURE_FIELD`** (legacy name only).
- **`validateActivityStructure(doc)`** — single argument; validates root **`outer`** / **`inner`**.
- **Persistence:** **`ActivixPersistenceTarget`** and options drop **`structureField`**; projections include **`outer`** / **`inner`**. **`summarizeActivixActivityForDiagnostics`** reads root **`outer`**, with a read-only fallback to legacy **`structure.outer`**.

### Docs

- [`.docs/MIGRATION-v6.md`](./.docs/MIGRATION-v6.md), updated [`.docs/activity-structure.md`](./.docs/activity-structure.md).

## 5.1.0

### Breaking

- **`runContext.sessionId` is no longer auto-generated.** If both `runContext.sessionId` and top-level `sessionId` are missing on `startRecord` / `failRecord` upsert paths, Activix emits a **warning** (via the package logger) and persists `runContext` **without** `sessionId`. Previously a new id was generated. Integrations that relied on the implicit value must pass `sessionId` explicitly.

## 5.0.0

### Breaking

- **Run context rename (default):** the per-run correlation BSON field is now **`runContext`** (was **`identity`**). Collection option **`identityField`** is **`runContextField`**. Pass **`runContext`** on **`startRecord`** and related payloads (unless **`runContextField`** overrides the stored key).
- **No API aliases:** the old names are **removed** from the default public surface—not deprecated alongside new ones. A stray **`identity`** key on writes is **not** treated as the correlation object when using defaults (see [`.docs/run-context-object.md`](./.docs/run-context-object.md)).
- **`findRecordsByIdentity`** → **`findRecordsByRunContext`**; **`FindByIdentityCriteria`** → **`FindByRunContextCriteria`** (criteria use **`runContext`** instead of **`identity`**).
- **Persistence verification** types/options: **`identityField`** → **`runContextField`** on **`ActivixPersistenceTarget`** and **`ActivixPersistenceVerificationOptions`**.

### Docs

- **Single run context doc:** [`.docs/run-context-object.md`](./.docs/run-context-object.md) (guide + v5 API + appendix). [`.docs/identity-object.md`](./.docs/identity-object.md) redirects. Migration: [`.docs/MIGRATION-v5.md`](./.docs/MIGRATION-v5.md). **Announcement helper:** [`.docs/COMMUNICATING-RUNCONTEXT-V5.md`](./.docs/COMMUNICATING-RUNCONTEXT-V5.md).
- **`package.json` `files`** includes **`.docs`** so consumers get the same markdown under **`node_modules/@x12i/activix/.docs/`** after install.

## 4.1.0

### Breaking

- **Internal logging** now follows **logs-gateway ≥ 3.6** per-package rules. **`ACTIVIX_LOGS_LEVEL`** is canonical; legacy **`ACTIVIX_LOG_LEVEL`** applies only when **`ACTIVIX_LOGS_LEVEL`** is unset. If **both** are unset, the effective level is **`warn`** (warn + error may emit)—**not** silent. Set **`ACTIVIX_LOGS_LEVEL=off`** (or **`none`** / **`silent`**) to disable Activix diagnostics.
- Removed Activix-specific opt-in flags for the default logger path: **`ACTIVIX_LOGS_ENABLED`**, **`ACTIVIX_LOGS`**, **`ACTIVIX_DEBUG`**, **`ACTIVIX_*_LOGS_ENABLED`**, and **`DEBUG=activix`** no longer gate whether the internal logger exists; **`DEBUG`** still affects verbosity **inside** logs-gateway when the package is not silenced (see [logs-gateway `docs/package-usage.md`](https://github.com/nx-intelligence/logs-gateway/blob/main/docs/package-usage.md)).

### Changed

- Dependency **`logs-gateway`** raised to **`^3.6.0`**.
- **`isActivixDiagnosticLoggingEnabled()`** now returns **`!packageLogsDisabled`** from the same resolution as **`createLogger`** (true when not fully silenced via **`ACTIVIX_LOGS_LEVEL`** / legacy level).

## 4.0.0

### Breaking

- **Console diagnostic output from Activix is no longer default-on**; internal messages are silent unless **`ACTIVIX_LOGS_ENABLED`** (or another **`ACTIVIX_…`** opt-in / **`DEBUG=activix`**) is set, or you pass **`options.logger`**.
- **Required `structure` field** (configurable via `structureField` on collection config, default `structure`) on every activity document. Each record must include `structure.outer` with **`input`**, **`output`** (may be `null` until completion), and **`metadata`** (plain object). Optional **`structure.inner`** uses the same three keys when present.
- **Integrator fields ignored** on incoming payloads: primary key, `status`, `startTime`, `endTime`, `duration`, `progressAt` (when configured), purge field, `createdAt`, `updatedAt`, and `error`. Activix sets lifecycle fields; times are **Unix ms numbers** only.
- **`completeRecord` / `failRecord`** always set **`endTime`** and **`duration`** from **`Date.now()`** (caller-supplied end times are stripped).
- **`patchRecord`** loads the row, deep-merges **`structure`**, validates, then **`update`**s (no longer **`patchByKey`** only).
- **In-memory and playground stores** no longer add **`createdAt`** / **`updatedAt`** to activity documents.
- **`structure`** deep-merge on partial updates: e.g. `completeRecord(id, { structure: { outer: { output: result } } })`.

### Added

- **Diagnostic logging** via **logs-gateway**, **off by default**. Set **`ACTIVIX_LOGS_ENABLED=true`** (or **`ACTIVIX_LOGS=1`**, **`ACTIVIX_DEBUG=1`**, **`DEBUG`** containing **`activix`**, or any **`ACTIVIX_*_LOGS_ENABLED`**) to enable. Export **`isActivixDiagnosticLoggingEnabled()`**. Injected **`options.logger`** still wins; **`XronoxStore`** receives the same resolved logger when you do not pass a custom one.
- Exports: **`activixTier`**, **`activixStructure`**, **`validateActivityStructure`**, **`mergeActivityStructureField`**, **`stripIntegratorControlledFields`**, **`DEFAULT_STRUCTURE_FIELD`**, and related types.
- Docs: [`.docs/activity-structure.md`](.docs/activity-structure.md), [`.docs/MIGRATION-v4.md`](.docs/MIGRATION-v4.md).
- Playground artifacts recognize v4 **`structure.outer`** for request/response sidecars.

## Prior releases

See git history for versions before 4.0.0.