Questa pagina trasforma le note tecniche in un percorso di implementazione concreto. Non ripete tutti i documenti, ma aiuta un team a decidere dove essere rigoroso, dove restare tollerante e come mantenere allineati parsing, scrittura e validazione.
Il punto più importante della nota tecnica è la chiara separazione delle responsabilità.
L’importazione inizia rilevando se l’ingresso è testo canonico `.eev`, un `.eevz` compresso oppure un file `.eevc` / `.eevcz` già emesso che deve solo essere letto. La compressione non crea un altro dialetto. Trasporta soltanto testo canonico dentro un involucro binario.
Una volta decompresso se necessario, ogni variante passa dallo stesso parser testuale. Questa regola limita le derive di comportamento tra le forme di trasporto e conserva un unico nucleo logico per la lettura applicativa.
Il parser deve produrre un modello esplicito: libreria, voci, metadati, global, matrici, vettori, modi, peak tracks e blocchi opzionali. Questo modello interno serve per validazione, visualizzazione e riesportazione. Non deve ridursi a un semplice mucchio di righe grezze.
Il writer non deve improvvisare. Riemette in un ordine stabile, con i campi correnti al posto giusto, senza riprodurre ambiguità legacy tollerate solo in lettura.
Library
├─ header
├─ entries[]
│ ├─ entry
│ ├─ manufacturer?
│ ├─ reseller?
│ ├─ global
│ ├─ vectors?
│ ├─ matrix?
│ ├─ modes?
│ ├─ peakTracks?
│ └─ therapeuticProfile?
└─ diagnostics[]Il punto importante qui è la leggibilità del modello, non il linguaggio usato.
Un lettore può essere flessibile. Un writer canonico deve restare prevedibile e volutamente privo di sorprese.
Definire un unico ordine di emissione e mantenerlo. Questo semplifica diff, test, generazione dell’hash e manutenzione.
Stessa voce, stesso modello, stessa uscita. Una serializzazione deterministica evita falsi cambiamenti e rafforza la fiducia nel formato.
Il testo canonico resta la fonte funzionale di verità. La compressione `.eevz` arriva dopo come semplice fase di trasporto; un `.eevcz` esistente può essere riletto con la stessa logica di compatibilità.
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 textLa validazione non dovrebbe limitarsi a dire “file non valido”. Deve spiegare che cosa manca, che cosa è legacy, che cosa è contraddittorio e che cosa può essere riparato automaticamente senza tradire il contratto canonico.
L’hash funzionale si applica al testo canonico protetto, non all’involucro compresso. Questa regola evita di duplicare i sistemi di integrità e mantiene il baricentro sul documento realmente significativo.
Questa sintesi riprende lo spirito dei documenti QA e fallback per un team che implementa EEV in un prodotto.
Testare `.eev` e `.eevz`, più la compatibilità in sola lettura per file `.eevc` e `.eevcz` già emessi, voci vecchie, campi mancanti e sezioni sconosciute tollerate.
Verificare la stabilità delle uscite, l’emissione canonica dei campi moderni, l’ordine dei blocchi e l’assenza di deriva tra due esportazioni identiche.
Testare negli ambienti di runtime realmente mirati, compresi i casi degradati e le registrazioni sul campo, non solo esempi ideali.