# TDR-0003: Dual-Format Test Reporting (JSONL and YAML)

Status: Accepted  
Date: 2025-12-23  
Applies to: E27 backend testing (developer workflows)

## Context

Developers debugging E27 protocol issues benefit from
human-readable structured output, while CI systems require
machine-stable formats.

Using a single format for both purposes leads to compromises
in readability or reliability.

## Decision

- JSONL is the **source of truth** for all test output.
- YAML is an **optional, derived format** for human inspection.
- YAML generation is controlled via:
  - command-line option, or
  - environment variable (e.g. `ELK_E27_REPORT_FORMAT=yaml`)
- YAML output is generated from the same in-memory test record
  as JSONL to prevent divergence.

## Rationale

This approach:
- preserves CI stability
- provides readable artifacts during live protocol debugging
- avoids duplicated logic or mismatched outputs

JSONL and YAML are treated as:
- data layer (JSONL)
- presentation layer (YAML)

## Consequences

Positive:
- Best of both machine and human workflows
- No ambiguity about canonical data
- Easy toggling of verbosity during debugging

Tradeoffs:
- Slight additional implementation complexity

Explicitly not doing:
- Maintaining separate YAML-only test paths
- Allowing YAML output to diverge from JSONL content

## References

- TDR-0001: E27 Test Evidence Capture Contract
- TDR-0002: Test Artifact Formats and CI Integration
