@x12i/activix-contracts

@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.