@almadar/parity

Cross-implementation parity testing for Almadar. Ensures the Rust compiler (orbital-compiler) and TypeScript runtime (almadar-runtime) behave identically.

Integrates with: @almadar/core (types), @almadar/std (operators), @almadar/runtime (execution)

Purpose

Almadar has multiple implementations:

• orbital-compiler (Rust): Reference implementation, validation, code generation
• almadar-runtime (TypeScript): Builder IDE runtime, client-side execution
• orbital-server (Rust): Server-side runtime
• almadar-server (TypeScript): Firebase-based server runtime

This package ensures they all produce the same behavior for the same schemas.

Installation

pnpm install

Prerequisites

Build the Rust CLI:

cd orbital-rust
cargo build --release

Usage

CLI

# Check parity on a single schema
npx almadar-parity check 01-basic-entity.orb

# Check with detailed diffs
npx almadar-parity check 03-guards.orb --verbose

# Check with JSON output
npx almadar-parity check 04-effects.orb --format=json

# Validate a schema
npx almadar-parity validate schemas/03-guards.orb

# Check harness availability
npx almadar-parity status

Programmatic

import { createRustHarness, createTSHarness, validateParity } from '@almadar/parity';

const rust = createRustHarness({
  binaryPath: './orbital-rust/target/release/orbital'
});

const ts = createTSHarness();

// Execute with both implementations
const [rustResult, tsResult] = await Promise.all([
  rust.execute('schema.orb', 'INIT', { id: '123' }),
  ts.execute('schema.orb', 'INIT', { id: '123' }),
]);

// Compare results
const report = validateParity(rustResult, tsResult, {
  validateStdOperators: true  // Validate against @almadar/std
});

console.log('Parity:', report.isParity);
console.log('Errors:', report.errorCount);

Schema Loading (using @almadar/core)

import { loadSchema, extractGuards, extractEffects } from '@almadar/parity/utils';

// Load and validate schema using almadar-core
const { schema, raw } = await loadSchema('schema.orb');

// Extract components using core types
const guards = extractGuards(schema);
const effects = extractEffects(schema);
const transitions = extractTransitions(schema);

// Get schema metrics
const metrics = getSchemaMetrics(schema);
console.log(`Schema has ${metrics.transitions} transitions, ${metrics.guards} guards`);

Test Building (using @almadar/std)

import { guardTest, effectTest, generateCommonGuardTests } from '@almadar/parity/utils';

// Build guard test cases
const guardTestCase = guardTest()
  .withEntity({ balance: 100, isVerified: true })
  .withPayload({ amount: 50 })
  .expect(true)
  .description('Can withdraw when balance sufficient and verified')
  .build();

// Build effect test cases
const effectTestCase = effectTest()
  .fromState({ count: 0 })
  .withEffect('increment', '@entity.count', 1)
  .expectState({ count: 1 })
  .description('Increment count by 1')
  .build();

// Generate common test cases using std operators
const commonTests = generateCommonGuardTests();

Test Schemas

All test schemas are symlinked in schemas/:

• 01-basic-entity.orb through 10-kitchen-sink.orb: Core feature tests
• 11-uses-basic.orb through 13-uses-circular.orb: uses primitive tests
• trait-wars.orb: Complex integration test
• inspection-system.orb: Real-world workflow test

Architecture

Harness System

• RustHarness: Spawns orbital CLI process, parses output
• TSHarness: Uses @almadar/runtime directly
• Both implement ParityHarness interface for uniform execution

Validation System

Uses @almadar/std operator registry for validation:

• Validates operators against known std operators
• Reports unknown operators as warnings
• Supports effect and guard operator classification

Schema Loading

Uses @almadar/core types and validation:

• loadSchema() validates schemas using core Zod schemas
• extractGuards(), extractEffects() return core types
• getSchemaMetrics() analyzes schema complexity

ExecutionResult

Normalized result structure:

interface ExecutionResult {
  success: boolean;
  initialState: string;
  finalState: string;
  transitions: StateTransition[];
  effects: NormalizedEffect[];
  guardEvaluations: GuardResult[];
  implementation: 'rust' | 'typescript';
  executionTimeMs: number;
}

Development

# Build
pnpm build

# Test
pnpm test

# Type check
pnpm typecheck

# Run CLI locally
pnpm parity:check 01-basic-entity.orb

Package Structure

packages/almadar-parity/
├── src/
│   ├── cli.ts                 # CLI entry point
│   ├── index.ts               # Public API exports (re-exports core/std)
│   ├── harness/
│   │   ├── types.ts           # ExecutionResult, ParityHarness (uses core types)
│   │   ├── rust-harness.ts    # Rust CLI wrapper
│   │   └── ts-harness.ts      # TypeScript runtime wrapper
│   ├── validators/
│   │   ├── types.ts           # Validation types (uses core types)
│   │   ├── guard-validator.ts # Validates guards (uses std operators)
│   │   ├── effect-validator.ts # Validates effects (uses std operators)
│   │   ├── state-validator.ts # Validates state transitions
│   │   ├── snapshot-validator.ts # Golden master comparison
│   │   └── index.ts           # validateParity() orchestrator
│   ├── reporters/
│   │   ├── console-reporter.ts # Human-readable output
│   │   ├── json-reporter.ts   # JSON output for CI
│   │   └── index.ts
│   └── utils/
│       ├── schema-loader.ts   # Schema loading with almadar-core
│       ├── test-builder.ts    # Test utilities with almadar-std
│       └── index.ts
├── schemas/                   # 20 symlinks to test schemas
└── fixtures/                  # Golden master snapshots

Phases Status

• ✅ Phase 1: Foundation (package scaffolding, harnesses)
• ✅ Phase 2: Validators (guard, effect, state, snapshot validators)
• ✅ Phase 2.2: Package Integration (integrated with core/std)
• ⏳ Phase 3: CLI and Reporting (enhanced CLI, HTML reporter)
• ⏳ Phase 4: CI Integration (GitHub Actions)
• ⏳ Phase 5: Advanced Testing (property-based testing)

License

MIT