Shift schema drift left: policy-aware compile-time contracts for typed JVM and Spark pipelines

Questo lavoro presenta un framework Scala 3 che riduce il rischio di deriva degli schemi nelle pipeline JVM e Spark spostando la verifica delle compatibilità strutturali e delle policy al momento della compilazione, integrando prove statiche con controlli runtime basati su contratti espliciti.

L'essenziale

Immagina di gestire un'enorme catena di montaggio per costruire automobili (i tuoi dati). Ogni auto che esce dalla linea di produzione deve rispettare un progetto preciso (lo schema).

Il problema che questo articolo affronta è il "drift dello schema": succede che qualcuno, nel frattempo, modifichi il progetto di un componente (ad esempio, cambia il nome di una porta, la rende opzionale o la sposta in un altro punto) senza avvisare. Spesso, questo errore viene scoperto solo quando l'auto è già assemblata e sta per essere consegnata al cliente, causando un disastro costoso.

Ecco come funziona la soluzione proposta dall'autore, spiegata con metafore semplici:

1. Il Problema: Troppo tardi per accorgersi degli errori

Oggi, molti sistemi di dati controllano se i pezzi sono giusti solo alla fine, quando i dati arrivano al magazzino (il momento in cui vengono scritti). È come controllare se le ruote sono quadrate solo dopo aver montato l'auto. Se c'è un errore, hai già sprecato tempo e risorse.

Altri sistemi provano a controllare tutto dall'inizio, ma richiedono di riscrivere l'intera catena di montaggio con nuovi attrezzi speciali, il che è troppo costoso e difficile da adottare.

2. La Soluzione: Due controlli, uno prima e uno dopo

L'autore propone un "sistema ibrido" che fa due cose diverse ma collegate:

A. Il Controllo in Tempo di Progettazione (Compile-Time)

Immagina di avere un architetto robot che legge i tuoi disegni tecnici (il codice Scala) prima ancora che tu inizi a costruire.

• Cosa fa: Confronta il disegno dell'auto che stai producendo con il progetto ufficiale richiesto dal cliente.
• La magia: Se il disegno non corrisponde (es. hai dimenticato un sedile o hai messo una ruota al posto sbagliato), il robot blocca tutto immediatamente e ti dice: "Ehi, non puoi costruire questa auto così! Manca questo pezzo".
• Il vantaggio: Non perdi tempo a costruire qualcosa che non funzionerà mai. L'errore viene catturato mentre scrivi il codice, non quando il programma è già in esecuzione.

B. Il Controllo di Sicurezza all'Uscita (Runtime Pin)

Anche se l'architetto robot ha dato l'ok, c'è un rischio: i materiali grezzi che arrivano dalla fabbrica esterna (i file CSV, JSON o altri dati) potrebbero essere diversi da quelli che hai disegnato.

• Cosa fa: Appena prima di caricare l'auto sul camion (scrivere i dati), un ispettore di sicurezza controlla fisicamente l'auto reale.
• La differenza: Questo ispettore è molto attento a dettagli specifici che gli altri ignorano. Mentre la maggior parte degli ispettori controlla solo il livello superiore, questo verifica se ogni "slot" all'interno di liste o map nidificate può essere vuoto o meno. Se il contratto dice "una scatola di mele dove ogni slot deve essere riempito" ma il camion invia "una scatola di mele dove alcuni slot sono vuoti", questo ispettore lo cattura. Gli strumenti standard spesso perdono questi errori di opzionalità nidificata.
• Il vantaggio: Se i dati reali non corrispondono al progetto, l'ispettore ferma il camion. Nessuno dato sbagliato esce dal magazzino.

3. Le Regole del Gioco (Le "Policy")

Il sistema è intelligente perché sa che non tutti i clienti vogliono le stesse cose. Puoi dire al sistema:

• Regola Rigida: "Deve essere identico al progetto, parola per parola."
• Regola Flessibile (Indietro): "Puoi aggiungere pezzi extra, ma non puoi togliere quelli obbligatori." (Come quando un cliente accetta un'auto con un tetto panoramico in più, ma non accetta che manchi il volante).
• Regola Flessibile (Avanti): "Puoi togliere pezzi che non servono, ma non puoi aggiungere cose strane."

4. Perché è importante?

Questo sistema è come avere un doppio assicurazione:

1. Prima: Il codice non si compila se i disegni non coincidono (risparmi tempo di sviluppo).
2. Dopo: Il dato reale viene controllato prima di essere salvato (proteggi i tuoi dati finali).

Non è una soluzione magica che risolve tutti i problemi (ad esempio, non controlla se l'età di una persona è positiva o se un prezzo è realistico, controlla solo la forma dei dati), ma è un passo enorme per evitare che i dati si "rompano" in modo silenzioso.

In sintesi:
L'autore ha creato un piccolo ma potente strumento che ti dice "Attenzione, il tuo progetto non corrisponde a quello richiesto" prima che tu perda tempo a costruire, e poi ti controlla di nuovo appena prima di consegnare il lavoro, assicurandosi che la realtà corrisponda alla teoria. È come avere un supervisore che ti ferma alla porta di casa se non hai le scarpe giuste, e un altro che ti controlla le scarpe prima di farti entrare in ufficio.

Sommario tecnico

1. Il Problema: Lo "Schema Drift" nei Pipeline Dati

Nei sistemi di dati moderni, lo schema drift (la divergenza non intenzionale tra la struttura dei dati prodotti e quella attesa dal consumatore) viene spesso rilevato troppo tardi, ovvero solo quando un job tocca i dati reali.

• Limiti delle soluzioni attuali:
  • I livelli Typed-Dataset (es. frameless, iskra) richiedono un'adozione massiva e la sostituzione del codice Spark grezzo, aumentando i costi di adozione.
  • I sistemi di enforcement a livello di tabella (es. Delta Lake, Apache Iceberg) operano al momento della scrittura contro uno schema memorizzato, non contro i tipi Scala dichiarati a compile-time.
  • Le verifiche runtime di Spark avvengono dopo che il programma è stato costruito e i dati hanno attraversato i confini esterni, lasciando un "seam" (giuntura) dove l'incompatibilità strutturale può passare inosservata fino all'esecuzione.

L'obiettivo del paper è colmare questa giuntura fornendo una prova di compatibilità strutturale al momento della compilazione (compile-time) per i pipeline JVM/Spark, mantenendo però una verifica di sicurezza al confine di runtime.

2. Metodologia e Architettura

Il framework proposto è un piccolo artefatto in Scala 3 che fonde due livelli di verifica:

A. Verifica Compile-Time (Proof)

• Meccanismo: Utilizza le quoted reflection di Scala 3 per ispezionare direttamente la struttura dei case class (produttore e contratto) senza introdurre layer di wrapper generici.
• Modello Normalizzato: Trasforma i tipi Scala in una rappresentazione interna normalizzata (TypeShape) che cattura nomi dei campi, annidamento, forme delle collezioni, opzionalità e valori di default.
• Evidence Materialization: Definisce un tipo classe SchemaConforms[Out, Contract, P]. Un macro inline genera la prova di compatibilità. Se la struttura non rispetta la policy, la compilazione fallisce con un report dettagliato sui percorsi di drift (campi mancanti, extra, o mismatch di opzionalità).

B. Verifica Runtime (Pin)

• Derivazione dello Schema: Lo stesso tipo di contratto Scala viene utilizzato per derivare dinamicamente lo schema Spark (StructType) al momento dell'esecuzione.
• Comparatore Policy-Aware: Prima della scrittura (sink), il framework confronta lo schema effettivo del DataFrame con quello derivato dal contratto.
• Miglioramenti rispetto a Spark: Il comparatore custom implementa due controlli che Spark ignora di default:
  1. Opzionalità delle collezioni annidate: Verifica se gli elementi all'interno di Array o Map sono nullabili o meno.
  2. Semantica di Sottogruppo: Implementa correttamente le policy di compatibilità "Backward" e "Forward" come relazioni di sottogruppo reali, non come semplici uguaglianze.

C. Il "Typed Builder"

Il punto di enforcement è un builder tipizzato (addSink[R, P]). Questo richiede che la prova compile-time esista per il tipo produttore corrente. Se la prova manca, il pipeline non compila. Se esiste, il pipeline compilato esegue comunque il controllo runtime prima della scrittura. Questo design unisce la garanzia statica alla sicurezza dinamica.

3. Famiglia di Policy Supportate

Il framework esplicita l'intento di compatibilità attraverso una famiglia di policy:

• Exact (e varianti): Matching esatto per nome (case-sensitive/insensitive) o per posizione.
• Backward: Il produttore può avere campi extra; i campi mancanti nel produttore sono permessi solo se opzionali o con default nel contratto.
• Forward: Il produttore deve avere tutti i campi del contratto; il contratto può avere campi extra.
• Full: Accetta tutte le combinazioni strutturali (usato per disabilitare l'enforcement).

4. Risultati e Valutazione

L'artefatto è stato valutato su un repository di riferimento minimale, concentrandosi sulla correttezza del meccanismo e non su metriche industriali su larga scala.

• Copertura: I test confermano che il macro accetta/rifiuta i casi strutturali previsti (inclusi campi di default, collezioni annidate e opzionalità).
• End-to-End: I test dimostrano che il builder enforce sia la prova compile-time che il controllo runtime, bloccando i drift che sfuggono a un singolo livello.
• Performance (Overhead):
  • Compile-time: L'overhead è misurabile ma accettabile (es. +0.27s a +1.88s per 10-50 coppie di schemi su diverse macchine), indicando che la generazione della prova non impedisce l'uso pratico.
  • Runtime: Il comparatore custom è più lento (circa 17-25x) rispetto ai comparatori nativi di Spark per il matching esatto unordered, ma rimane nell'ordine dei microsecondi per schema. Tuttavia, il costo assoluto rimane nell'ordine dei microsecondi (es. ~4.7μs per unordered exact matching su locale, ~8.1μs su Ubuntu) poiché il controllo viene eseguito una volta per scrittura del sink, non per riga.

5. Significato e Contributi Chiave

Il paper non rivendica di aver risolto il problema generale dei contratti software (che include semantica aziendale, vincoli temporali, ecc.), ma si concentra su un problema strutturale ben definito.

1. Spostamento a Sinistra (Shift Left): Sposta la rilevazione della maggior parte dei drift strutturali dalla fase di esecuzione (runtime) alla fase di compilazione e CI.
2. Ibridazione Compile/Runtime: Dimostra che la prova statica e il controllo dinamico non sono ridondanti ma complementari: la prima protegge il codice dichiarato, la seconda protegge i dati reali che attraversano i confini esterni (CSV, JSON, ecc.).
3. Potenziale Minor Costo di Adozione: Concentrando l'enforcement del contratto al confine del sink (dove il tipo Scala produttore dichiarato incontra il tipo contratto), l'autore sostiene che questo design possa ridurre i costi di adozione rispetto a una riscrittura completa con Typed-Dataset. Si tratta di un argomento di design; il paper non misura empiricamente il costo di adozione.
4. Trasparenza: L'artefatto è onesto nei suoi limiti (niente registri di schema esterni, niente metriche di produttività industriale) e si presenta come un "meccanismo" verificabile piuttosto che come una soluzione commerciale pronta all'uso.

In sintesi, il lavoro offre un meccanismo pratico e verificabile per garantire la compatibilità strutturale nei pipeline Spark/Scala, riducendo il rischio di fallimenti in produzione causati da modifiche non intenzionali agli schemi dei dati.