@runtime-digital-twin/core

Core contracts and types for the Runtime Digital Twin Platform.

Overview

This package defines the three core JSON contracts used throughout the platform:

• ReplayResult: Result of a single trace replay execution
• SuiteResult: Aggregated result of multiple trace replays
• TwinPlan: Plan for executing multiple trace replays

All contracts include:

• TypeScript type definitions
• Runtime validation using Zod schemas
• JSON schema documentation

Installation

npm install @runtime-digital-twin/core

Usage

ReplayResult

import { validateReplayResult, type ReplayResult } from "@runtime-digital-twin/core";

const result: ReplayResult = {
  success: true,
  exitCode: 0,
  traceId: "trace-123",
  replayedStatus: 200,
  recordedStatus: 200,
  statusMatch: true,
  bodyMatch: true,
  outboundCallsMatch: true,
  dbQueriesMatch: true,
  errors: [],
  artifacts: [],
};

// Validate at runtime
const validated = validateReplayResult(result);

SuiteResult

import { validateSuiteResult, type SuiteResult } from "@runtime-digital-twin/core";

const suite: SuiteResult = {
  suiteId: "suite-123",
  startedAt: Date.now(),
  completedAt: Date.now(),
  status: "pass",
  totalReplays: 5,
  passedReplays: 5,
  failedReplays: 0,
  errorReplays: 0,
  results: [/* ReplayResult[] */],
  summary: {
    durationMs: 1000,
    statusMatches: 5,
    bodyMatches: 5,
    outboundCallsMatches: 5,
    dbQueriesMatches: 5,
    totalErrors: 0,
    totalArtifacts: 0,
  },
};

const validated = validateSuiteResult(suite);

TwinPlan

import { validateTwinPlan, type TwinPlan } from "@runtime-digital-twin/core";

const plan: TwinPlan = {
  planId: "plan-123",
  name: "Test Plan",
  version: "1.0.0",
  createdAt: Date.now(),
  tasks: [
    {
      taskId: "task-1",
      traceId: "trace-123",
    },
  ],
};

const validated = validateTwinPlan(plan);

Type Guards

import { isReplayResult, isSuiteResult, isTwinPlan } from "@runtime-digital-twin/core";

if (isReplayResult(data)) {
  // TypeScript knows data is ReplayResult
  console.log(data.traceId);
}

Error Formatting

import { validateReplayResult, formatValidationError } from "@runtime-digital-twin/core";
import { z } from "zod";

try {
  validateReplayResult(invalidData);
} catch (error) {
  if (error instanceof z.ZodError) {
    console.error(formatValidationError(error));
  }
}

Documentation

See /docs/contracts.md for complete JSON schema documentation and examples.

Development

# Build
npm run build

# Test
npm test

# Watch mode
npm run dev