# @x12i/activix-contracts

> Shared TypeScript contracts for Activix activity records, run context, and client interfaces

Latest version **1.5.2** (published 2026-07-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install @x12i/activix-contracts
pnpm add @x12i/activix-contracts
yarn add @x12i/activix-contracts
bun add @x12i/activix-contracts
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.5.2 |
| Published | 2026-07-10 |
| First published | 2026-05-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16.0.0 |
| Dependencies | 0 |
| Unpacked size | 204.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | x12i |
| Maintainers | x12i |
| Keywords | activix, contracts, activity, types |

## Links

- npm: https://www.npmjs.com/package/@x12i/activix-contracts
- Repository: https://github.com/x12i/activix
- Homepage: https://github.com/x12i/activix#readme
- Issues: https://github.com/x12i/activix/issues
- npm.io page: https://npm.io/package/@x12i/activix-contracts

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.5.2 (latest) — 2026-07-10
- 1.5.1 — 2026-06-08
- 1.5.0 — 2026-05-31
- 1.4.1 — 2026-05-31
- 1.4.0 — 2026-05-31
- 1.3.1 — 2026-05-28
- 1.3.0 — 2026-05-28
- 1.2.0 — 2026-05-28
- 1.1.0 — 2026-05-28
- 1.0.5 — 2026-05-28
- 1.0.3 — 2026-05-28
- 1.0.2 — 2026-05-27
- 1.0.1 — 2026-05-27
- 1.0.0 — 2026-05-27

## README

# @x12i/activix-contracts

**Version 1.4.1**

Shared TypeScript contracts for Activix activity records and client interfaces.

Part of the [Activitix monorepo](../../README.md).

**No Mongo. No storage. No runtime.** Safe to import from any package (Optimixer, AI gateway, graph-engine, studio tooling).

## Install

```bash
npm install @x12i/activix-contracts
```

## Record shape (canonical)

**`ActivixActivityRecord`** — persisted row:

| Area | Fields | Role |
|------|--------|------|
| **Identity** | `activityId` (PK) | Activix-assigned on `startRecord`; use for cross-service joins |
| **Correlation** | `runContext` | `sessionId`, `jobId`, `graphId`, `nodeId`, product keys (`masterSkillActivityId`, …) |
| **I/O** | `outer`, optional `inner[]` | `input`, `output`, `metadata`, optional `cost` per tier |
| **Orchestrator** | top-level `metadata` | `modelUsed`, `synthesisEnabled`, product flags — **not** nested under `outer` |
| **Routing mirror** | top-level `config` | `provider`, `model`, `maxTokens` — gateway/billing mirror |
| **Lifecycle** | `status`, `startTime`, `endTime`, `duration` | Set by Activix only |

Full layout: `@x12i/activix` [activity-structure.md](../activix/.docs/activity-structure.md).

### Naming: do not confuse these

| Name | Meaning |
|------|---------|
| **Collection name** | Activix constructor `collection` / `collections[].name` (e.g. `'ai-gateway-activities'`) |
| **`activityKind`** | IO / lifecycle tag (`node:start`, `optimixer:prediction`) — see `resolveActivityKind()` |
| **`activityType`** | Domain label on **`outer.metadata.type`** (`synthesis`, `task`) — **not** legacy ActivityTracker routing |
| **`activixCollection` (Optimixer)** | Config option that must equal the Activix **collection name** when sharing a client |

### `metadata` tiers

- **`outer.metadata`** — IO-tier (phase, kind, provider, pipelineId). Optimixer writes here.
- **top-level `metadata`** — orchestrator / run observability (`modelUsed`, `synthesisEnabled`, …).

## Studio trace export

Helpers for directory export and studio report joins (no storage dependency):

```typescript
import {
  buildActivityTraceBlock,
  normalizeActivityTraceExport,
  resolveActivityKind,
  resolveActivityType,
} from '@x12i/activix-contracts';

const trace = buildActivityTraceBlock(doc, { activixCollection: 'ai-gateway-activities' });
// trace.activityKind, trace.activityType, trace.correlation, trace.join, trace.observability

const forFile = normalizeActivityTraceExport(doc, { activixCollection: 'ai-gateway-activities' });
// { ...doc, trace }
```

**Join convention (graph-engine ↔ ai-tasks):**

```text
graph_node.trace.join.activityId === ai_task.trace.join.parentActivityId
```

Spec: [activity-trace-schema.md](../activix/.docs/activity-trace-schema.md).

## Exports

### Types

- `ActivixActivityRecord`, `ActivixOuterTier`, `ActivixInnerTier`, `ActivixCost`
- `ActivixRunContext`, `ActivixRecordMetadata`
- `ActivixStartRecordInput`, `StartRecordResult`
- `ActivixActivityTraceBlock`, `ActivixActivityTraceCorrelation`, `ActivixActivityTraceJoin`, `ActivixActivityTraceObservability`
- `ActivixCollectionLegendRecord`, `ActivixCollectionLegendOwner`
- `ActivixCollectionTrackingState` — `'track' | 'off'` on legend rows (Activix gates persistence)
- `DEFAULT_ACTIVIX_COLLECTION_TRACKING_STATE`, `ACTIVIX_COLLECTION_TRACKING_STATES`
- `normalizeActivixCollectionTrackingState()` — missing/`null`/unknown → `'track'`
- `withActivixCollectionLegendDefaults()` — apply defaults when reading legend rows
- `DEFAULT_ACTIVIX_STATUS_VALUES`

Deprecated aliases: `ActivixRecord`, `ActivixActivityOuterTierShape`, `ActivixCostShape`, etc.

### Client interfaces

- `ActivixWriterClient` — `startRecord`, `completeRecord`, `failRecord`, optional `patchRecord` / `markInProgress`
- `ActivixReaderClient` — `getRecord`, optional `findRecords` / `findRecordsByRunContext`
- `ActivixActivityClient` — writer + reader
- `ActivixQueryableClient` — `getJobActivities`

All methods accept optional `{ collection?: string }`.

### Pure helpers

- Structure: `validateActivityStructure`, `activixOuterTier`, `activixInnerTier`, merge helpers
- Run context: `normalizeRunContext`, `assertMatchingSessionId`
- Routing: `resolveRecordConfig`, `materializeRecordRoutingAndBilling`, `mergeRecordConfig`, `mergeRecordMetadata`
- Cost: `isValidActivixCost`, `normalizeToActivixCostShape`
- Trace: `buildActivityTraceBlock`, `normalizeActivityTraceExport`, `resolveActivityKind`, `resolveActivityType`

### Metadata constants

- `ACTIVIX_METADATA_KIND_OPTIMIXER_PREDICTION` — `'optimixer:prediction'`
- `ACTIVIX_METADATA_OPTIMIZER_OPTIMIXER` — `'optimixer'`

## Suite dependencies

| Consumer | Contracts range |
|----------|-----------------|
| `@x12i/activix` | `^1.4.0` |
| `@x12i/optimixer` | `^1.3.1` |

Publish **contracts** first when types or constants change; then bump dependent packages.

## Versioning

Breaking type changes happen here first. Patch/minor on contracts; align **`@x12i/activix`** and **`@x12i/optimixer`** dependency ranges to match the published contracts version.

## Related packages

| Package | Role |
|---------|------|
| [`@x12i/activix`](../activix) | Persistence and lifecycle (8.x) |
| [`@x12i/optimixer`](../optimixer) | Runtime optimization engine; first scenario `ai.max_tokens.v1` (2.x) |

Consumer migration: [../../.docs/MIGRATION-CONSUMERS.md](../../.docs/MIGRATION-CONSUMERS.md).

---
_Source: https://npm.io/package/@x12i/activix-contracts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._