Build

Implementation guide

This page turns the technical notes into a practical implementation route. It does not repeat every document, but helps a team decide where to be strict, where to stay tolerant, and how to keep parsing, writing, and validation aligned.

Pipeline Model Writer Validation Tests

Suggested pipeline

The most important point in the technical note is the clear separation of responsibilities.

Detect the container

Import begins by detecting whether the input is canonical text `.eev`, compressed `.eevz`, or an already-issued `.eevc` / `.eevcz` file that must only be read. Compression does not create another dialect. It only transports canonical text inside a binary envelope.

Normalize toward the text parser

Once decompressed if necessary, every variant goes through the same text parser. This rule limits behaviour drift between transport forms and preserves a single logical core for application-level reading.

Build a clean internal model

The parser should produce an explicit model: library, entries, metadata, global, matrices, vectors, modes, peak tracks, and optional blocks. That internal model supports validation, display, and re-export. It should not collapse into a loose bag of raw lines.

Re-emit canonically

The writer must not improvise. It re-emits in a stable order, with current fields in the right places, without reproducing legacy ambiguities tolerated only during reading.

Recommended minimum internal model

Library
 ├─ header
 ├─ entries[]
 │   ├─ entry
 │   ├─ manufacturer?
 │   ├─ reseller?
 │   ├─ global
 │   ├─ vectors?
 │   ├─ matrix?
 │   ├─ modes?
 │   ├─ peakTracks?
 │   └─ therapeuticProfile?
 └─ diagnostics[]

The important point here is model readability, not the implementation language.

Placement rules worth enforcing

`quality_tier` belongs to the `@entry` block
library header fields must not describe one entry’s matrices
unknown sections may be tolerated during reading
tolerated on read does not mean re-emitted on write

Canonical writer

A reader can stay flexible. A canonical writer must stay predictable and boring in the best possible way.

Fixed order

Define a single emission order and keep it. This simplifies diffs, tests, hash generation, and maintenance.

Deterministic text

Same entry, same model, same output. Deterministic serialization avoids fake changes and strengthens trust in the format.

Compress after the text

Canonical text remains the business source of truth. `.eevz` or, in read-only compatibility, `.eevcz` compression comes afterwards as a transport step.

read(input):
  payload = detect_container_and_decode(input)
  model = parse_canonical_text(payload.text)
  diagnostics = validate(model)
  return { model, diagnostics }

write(model, targetStatus, compressed):
  normalized = normalize_for_canonical_output(model, targetStatus)
  text = serialize_canonical_text(normalized)
  if compressed:
    return wrap_eevz_container(text, normalized.containerType)
  return text

Useful validation

Validation should not merely say “invalid file.” It should explain what is missing, what is legacy, what is contradictory, and what can be repaired automatically without betraying the canonical contract.

blocking errors
legacy warnings
applied normalizations
possible round-trip loss

Hash and documentary trust

The business hash applies to protected canonical text, not the compressed envelope. This avoids duplicate integrity systems and keeps the center of gravity on the meaningful document itself.

Pre-release test checklist

This synthesis follows the spirit of the QA and fallback documents for a team implementing EEV inside a product.

Reading

Test `.eev` and `.eevz`, plus read-only compatibility for already-issued `.eevc` and `.eevcz` files, older entries, missing fields, and tolerated unknown sections.

Writing

Verify output stability, canonical emission of modern fields, block order, and the absence of drift between identical exports.

Real runtime

Test on the actually targeted runtimes, including degraded cases and field recordings, not only ideal examples.