# Trace Parity

Trace parity exists to validate shared contract semantics, deterministic behavior where defined, and the canonical JSONL trace schema.

## Scope

- Text trace output is developer-facing and human-readable.
- JSONL trace output is the canonical parity target.
- Canonical parity checks shared event names, field names, signal-id shape, scenario construction, and event ordering where the contract requires it.

## Language Reference Policy

Parity must follow `docs/LANGUAGE_REFERENCE_POLICY.md`.

- Java is the core semantic and architectural reference.
- Python is the Pythonic reference implementation.
- Mojo should remain very close to Python.
- C++ should follow Java as much as practical while remaining idiomatic C++.

## Important Boundary

JSONL parity is not permission to Java-ize Python.

Python and Mojo internal readability, structure, and explicitness are first-class goals. A fixture mismatch must be analyzed before any runtime behavior changes are made.
Fixture mismatches must be analyzed rather than blindly "fixed" by aligning Python internals to Java.

## Mismatch Classification

When fixtures differ, classify the difference before changing code:

1. Contract-level semantic drift
2. Trace serialization mismatch
3. Allowed language-style difference
4. Genuine bug

Do not change Python runtime semantics solely to make fixtures match Java unless the mismatch is clearly contract-level or explicit approval has been given.

Use `docs/PARITY_DECISION_CHECKLIST.md` as the quick review path.
