# Decision 0000: Trace Format

Status: `Locked`

## Context

Trace format is a required Phase 0 decision because every subsystem contract
already depends on debug visibility, and those traces are much more useful if
they share a known structure.

The project needs one format that is:

- simple enough to emit from early RTL stubs,
- simple enough to generate from emulator-side instrumentation,
- human-readable during bring-up,
- structured enough for automated diffs later.

## Options considered

1. One shared tabular text format for everything.
2. Subsystem-specific text formats with no shared envelope.
3. Binary trace format from day one.
4. Common text envelope plus subsystem-specific payload fields.

## Decision

Adopt a `common text envelope plus subsystem-specific payload fields` format for
Phase 0 and Phase 1.

The common envelope should include:

- cycle or monotonic timestamp,
- subsystem id,
- event type,
- schema/version id,
- payload fields encoded as self-describing key/value pairs or a stable
  column layout documented per subsystem.

Golden-reference traces should be normalized into the same envelope before
comparison. The trace files under `sim/traces/` remain text during early bring-up.

Binary traces are deferred unless text traces become a demonstrated bottleneck.

## Consequences

- Early traces stay readable in code review and terminal workflows.
- RTL stubs can emit useful traces before any heavy tooling exists.
- Emulator-side tooling has a clear normalization target.
- Different subsystems may still define different payload fields, but they must
  fit inside the same outer structure.
- If performance later requires binary traces, the project can add them behind
  the same logical schema rather than reinventing the event model.

## Inputs to use when locking

- `docs/contracts/validation.md`
- per-subsystem "required debug visibility" sections in `docs/contracts/`
- `sim/traces/README.md`

## Follow-up

- The stub-module plan should name the initial envelope fields explicitly.
- Subsystem contracts may later gain a short "trace payload schema" section once
  the first stubs are specified.