# Output Encoding Internals

## Scope and Ownership

`internal/core/outputschema` owns encoder registration and resolution. External
JSON envelopes and segment fields are defined by the
[output-file contract](../integrations/output-files.md#corrected-transcript);
selectable values and defaults belong to
[configuration](../config.md#settings).

## Resolution and Encoding

Configuration validation checks registry support. CLI orchestration resolves the
selected encoder, passes the final transcript to it, and routes the encoded bytes
to the destination defined by the [CLI contract](../cli.md#streams-and-exit-status).
An unsupported key fails validation or resolution rather than selecting an
implicit fallback.

The registry delegates bare segment serialization to the transcript schema
package and uses an envelope encoder for the versioned form. Report construction
receives the selected key separately; see [report assembly](diagnostics-reporting.md).

## Changing an Encoder

Update registration, configuration validation, and serialization together. Inspect
round-trip and shape tests, then update the external output-file contract if the
serialized form changes. Keep internal helper changes separate from decisions
about externally visible compatibility.

## Key Tests

- `internal/core/outputschema/registry_test.go`
- `internal/core/config/config_test.go`
- `internal/cli/run_test.go`