@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

``bash
npm install @runtime-digital-twin/core
`

Usage

$3

`typescript
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);
`

$3

`typescript
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);
`

$3

`typescript
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

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

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

Error Formatting

`typescript
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

`bash


Build

npm run build

Test

npm test

Watch mode

npm run dev
``