@x12i/activix-contracts

Version 1.4.1

Shared TypeScript contracts for Activix activity records and client interfaces.

Part of the Activitix monorepo.

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

Install

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.

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):

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):

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

Spec: 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 | Persistence and lifecycle (8.x) | | @x12i/optimixer | Runtime optimization engine; first scenario ai.max_tokens.v1 (2.x) |

Consumer migration: ../../.docs/MIGRATION-CONSUMERS.md.