OxyMake: A Formally-Specified, Content-Addressable Workflow Engine

OxyMake è un motore di workflow in Rust a binario singolo e formalmente specificato che sostituisce l'inaffidabile timestamp di modifica dei file con l'hashing BLAKE3 basato sul contenuto per garantire una cache robusta e cross-machine ed eliminare le ri-esecuzioni spurie, mantenendo al contempo la compatibilità con le pipeline esistenti in stile Make.

L'essenziale

Immagina di gestire una massiccia competizione culinaria che dura più giorni. Hai un libro di ricette (il workflow) che ti spiega come trasformare gli ingredienti grezzi in un banchetto finale.

Ai vecchi tempi, lo chef capo (motori di workflow come GNU Make o le prime versioni di Snakemake) decideva se ricucinare un piatto basandosi su una regola semplicissima: "L'orologio sul barattolo dell'ingrediente è cambiato?"

Questo è come controllare il timestamp "Ultima modifica" su un file. Ma questa regola è difettosa.

• Il Falso Allarme: Se sposti i tuoi ingredienti in una nuova cucina, o li ripristini da un backup, i barattoli ottengono nuovi timestamp anche se il cibo all'interno è identico. Il vecchio chef vede il nuovo orario, va nel panico e ricuce l'intero pasto da zero, sprecando ore di tempo ed energia.
• Il Fallimento Silenzioso: Al contrario, se scambi il cibo all'interno di un barattolo ma non cambi l'etichetta del barattolo (il timestamp), lo chef vede il vecchio orario, assume che tutto vada bene e ti serve cibo vecchio e avariato senza rendersene conto.

OxyMake è un nuovo motore di cucina super intelligente costruito per risolvere questo problema. Invece di guardare l'orologio sul barattolo, assaggia il cibo (controlla il contenuto effettivo).

Ecco come funziona OxyMake, suddiviso in concetti semplici:

1. Il "Test del Gusto" (Caching basato sul contenuto)

Inveza di chiedere "Quando è stato toccato l'ultima volta?", OxyMake chiede: "Di cosa è fatto?"
Crea un "impronta digitale" unica (un hash crittografico) per ogni singolo ingrediente, ogni passaggio della ricetta e ogni strumento utilizzato.

• Se copi i tuoi ingredienti in una nuova cucina, le impronte digitali rimangono le stesse. OxyMake vede che non sono cambiate e dice: "Non c'è bisogno di cucinare; abbiamo già il piatto perfetto".
• Se scambi un pomodoro con una patata, l'impronta digitale cambia istantaneamente. OxyMake lo sa immediatamente che il piatto è diverso e cucina solo la parte specifica che deve essere cambiata.

Questo elimina i "re-run fantasma" (sprecare tempo a cucinare ciò che hai già) e gli "output obsoleti silenziosi" (servire cibo cattivo perché l'etichetta sembrava vecchia).

2. "Il Progetto vs La Costruzione" (Architettura a tre grafi)

OxyMake pensa in tre livelli, come un architetto, un costruttore e un caposquadra:

• Il Progetto (RuleGraph): Questo è il tuo libro di ricette. È astratto. Dice: "Prepara una zuppa per ogni verdura". Non sa ancora quali verdure siano.
• Il Piano di Costruzione (JobGraph): OxyMake prende il progetto ed espande la ricetta. "Ok, abbiamo carote, patate e cipolle. Significa che dobbiamo preparare tre zuppe specifiche". Calcola esattamente cosa deve essere fatto prima di iniziare a cucinare.
• Il Cantiere (ExecGraph): Questa è la cucina vera e propria in corso. Traccia quale pentola sta bollendo, quale è finita e quale si è bruciata.

Poiché OxyMake pianifica tutto prima (in una frazione di secondo), può gestire ricette enormi con migliaia di passaggi molto più velocemente di altri motori che cercano di capire come procedere man mano che avanzano.

3. La Cucina "Senza Capo" (Esecuzione senza Daemon)

La maggior parte dei motori di workflow richiede un computer centrale "capo" (un daemon) che sorvegli la cucina 24 ore su 24, 7 giorni su 7. Se il capo crasha, la cucina si ferma.
OxyMake è diverso. È come una squadra di cuochi indipendenti che possono entrare e uscire dalla cucina in qualsiasi momento.

• Rivendicazione Cooperativa: Se due cuochi cercano di afferrare la stessa pentola, hanno un protocollo di stretta di mano educato per decidere chi cucina.
• Nessun Singolo Punto di Fallimento: Se un cuoco se ne va o il suo computer crasha, gli altri prendono il suo posto. Non hai bisogno di un gestore centrale per mantenere la cucina operativa.

4. Il "Traduttore Universale" (Esecuzione Poliglotta)

In una cucina normale, potresti essere costretto a usare un solo tipo di coltello o un solo linguaggio. OxyMake è un poliglotta.

• Puoi scrivere la ricetta in TOML (un formato di testo semplice e pulito), che è facile da leggere per gli umani e da comprendere istantaneamente per i computer.
• Ma la cucina vera e propria può avvenire in Python, R, Shell script o Julia. A OxyMake non importa quale lingua parli il cuoco; lui si limita a passare gli ingredienti e raccogliere il piatto finito.

5. Il "Registro Onesto" (Riproducibilità)

OxyMake tiene un diario rigoroso e immutabile (un file di lock chiamato ox.lock).

• Registra esattamente quali ingredienti sono stati usati, cosa diceva la ricetta e qual era il sapore del piatto finale.
• Anche se torni in questa cucina cinque anni dopo, su un computer completamente diverso, OxyMake può guardare il diario e dire: "Sì, se seguiamo esattamente questo percorso, otterremo lo stesso identico risultato".
• Utilizza persino la matematica formale (TLA+) per dimostrare che il suo "protocollo di stretta di mano" per i cuochi è sicuro, garantendo che due cuochi non cucinino mai accidentalmente lo stesso piatto o si intralcino a vicenda.

Il Compromesso: Velocità vs Sicurezza

L'articolo è molto onesto riguardo a un aspetto negativo:

• Partenza a Freddo (Cold Start): La primissima volta che esegui una ricetta, OxyMake è leggermente più lento degli old engine perché deve "assaggiare" (fare l'hash di) ogni singolo ingrediente per costruire le sue impronte digitali.
• Esecuzione a Caldo (Warm Run): Ma una volta fatto ciò, la seconda volta che esegui la ricetta (o se la esegui su un computer diverso), è molto più veloce e molto più affidabile. Salta completamente la cottura se le impronte digitali corrispondono, laddove i vecchi motori potrebbero confondersi con i timestamp e ricucinare tutto.

Riassunto

OxyMake è un motore di workflow che smette di tirare a indovinare basandosi sui timestamp e inizia a controllare il contenuto effettivo dei tuoi dati. È costruito con un linguaggio moderno e veloce (Rust), non ha bisogno di un capo centrale per funzionare e mantiene un registro perfetto e verificabile di tutto ciò che fa. Scambia un briciolo di tempo di configurazione iniziale per enormi guadagni in velocità, sicurezza e affidabilità quando esegui i tuoi workflow ripetutamente.

Sommario tecnico

Riepilogo Tecnico: OxyMake

Problema

I motori di workflow nel campo della "lineage di Make" (ad es. GNU Make, Snakemake, Nextflow) si affidano storicamente al tempo di modifica dei file (mtime) come proxy per rilevare i cambiamenti di contenuto. Il documento sostiene che questo sia un "proxy debole" (leaky proxy) che fallisce in due modi critici:

1. Re-run Fantasma: Operazioni come git checkout, copie di alberi di directory o ripristini di backup riscrivono l'mtime senza cambiare il contenuto dei file, forzando esecuzioni non necessarie.
2. Riutilizzo Obsoleto: Al contrario, se il contenuto di un file di output è obsoleto ma il suo mtime appare più recente rispetto ai suoi input (ad es. a causa di disallineamenti dell'orologio o ripristini), il motore riutilizza silenziosamente l'output errato.

Sebbene Snakemake 7 mitighi i re-run fantasma registrando la provenienza per output (codice, parametri, set di input), tale record è legato a un singolo albero di lavoro. Non può viaggiare tra macchine diverse, cache condivise o rilevare la corruzione su disco dove i byte cambiano senza aggiornamenti dei metadati.

Metodologia

OxyMake è un motore di workflow in Rust, un singolo binario, che sostituisce il proxy mtime con una cache basata sull'indirizzamento del contenuto (content-addressable caching).

Principi di Design Core

1. Chiavi Content-Addressable: La chiave di cache per un job è un hash BLAKE3 della sorgente della regola, degli hash del contenuto degli input, dei parametri, delle specifiche dell'ambiente e della piattaforma. Questa chiave è una funzione pura degli input dichiarati.
2. Architettura a Tre Grafi:
   • RuleGraph (Logico): Regole astratte con wildcard non risolte.
   • JobGraph (Fisico): DAG completamente risolto e ottimizzato con job concreti.
   • ExecGraph (Runtime): Annotato con stato live, metriche e log.
3. TOML Dichiarativo: I workflow sono definiti in TOML, garantendo la parsabilità statica ed evitando l'overhead di esecuzione dinamica dei DSL in Python (come Snakemake).
4. Esecuzione Senza Daemon: Il motore opera senza un daemon centrale. Utilizza un protocollo cooperativo di claim/reclaim per sessioni concorrenti, dove lo stato è persistito in un database SQLite locale (.oxymake/state.db).
5. Specifica Formale: Gli invarianti di sicurezza cross-session tra diverse sessioni (ad es. impedire a due sessioni di reclamare lo stesso job) sono specificati in TLA+ e verificati tramite il model checker TLC. Questo affronta la classe di pericolo "Concurrent State Transitions Across independently-Failing Peers" (CSTAFP).

Modello di Esecuzione

OxyMake supporta uno spettro di modalità di esecuzione:

• Shell/Run/Script: Standard I/O basato su file.
• Call: Riferimenti a funzioni pure (ad es. funzioni Python) dove OxyMake gestisce l'I/O, permettendo il passaggio di dati in memoria tra i job su executor supportati (ad es. Ray).

Il motore è "convergente": ox run assicura che gli output esistano piuttosto che limitarsi a lanciare i job. Gestisce l'invalidazione transitiva; se un file intermedio viene eliminato, la scansione preventiva della cache rileva l'assenza e innesca la ricostruzione di tutti i job dipendenti a valle.

Contributi Chiave

Il documento elenca sette contributi specifici:

1. Caching Content-Addressable: Elimina i re-run fantasma per gli input dichiarati e supporta la cascata transitiva in caso di cancellazione. Include una via rapida mtime+hash per le prestazioni.
2. Implementazione in Rust: Un singolo binario staticamente linkato (14.9 MB), con un risolutore backward-chaining tramite lookup di pattern precompilati, che raggiunge una risoluzione del DAG in frazioni di secondo.
3. Concorrenza Specificata Formalmente: Gli invarianti di sicurezza cross-session sono specificati in TLA+ e sottoposti a model-checking, anziché affidarsi esclusivamente ai test.
4. Architettura a Tre Grafi: Separa la definizione delle regole, i piani risolti e le tracce di esecuzione, allineandosi ai principi FAIR (Findable, Accessible, Interoperable, Reusable).
5. Lockfile di Riproducibilità (ox.lock): Un piano di record basato su hash del contenuto che consente la derivazione esatta dei grafi dei job anche anni dopo.
6. Interfaccia Leggibile dalle Macchine: Stream di eventi NDJSON strutturati e approvazione tramite gate programmatico per l'integrazione con altri strumenti.
7. Esecuzione Poliglotta: Supporta modalità shell, chiamate in-process e script con capacità di passaggio dati in memoria.

Risultati e Valutazione

Gli esperimenti sono stati condotti su un Apple M4 Max (16 core, 128 GB RAM).

• Velocità di Risoluzione del DAG: OxyMake risolve un DAG di 10.000 job in 69 ms, rispetto ai 2.31 s di Snakemake 7.32.4 (un incremento di velocità di 33.3×). Ciò è attribuito ai pattern regex precompilati e all'assenza di overhead dell'interprete Python.
• Prestazioni Cold End-to-End: In una corsa a freddo (prima esecuzione), OxyMake è più lento (1.25–2.3×) rispetto a Snakemake. Il documento attribuisce ciò al costo dell'hashing degli input e della scrittura degli store content-addressed.
• Prestazioni Warm Re-run: Nelle esecuzioni a cache calda (re-run no-op), OxyMake è 7.54× più veloce di Snakemake (372 ms contro 2.81 s per 10.000 job). Anche con verifica completa del contenuto (--cache-validation=hash), rimane 4.02× più veloce.
  *. Robustezza del Content-Addressing: In un test "git checkout" dove l''mtime' era stato perturbato ma il contenuto era rimasto identico:
  • Snakemake 7.32.4 ha ri-eseguito 0 job (grazie ai suoi record di provenienza).
  • Il precedente default mtime-puro di OxyMake ha ri-eseguito 6.667 job (l'intero raggio a valle).
  • L'attuale default mtime+hash e la modalità hash di OxyMake hanno ri-eseguito 0 job.
• Scalabilità: Il tempo di risoluzione scala quasi linearmente con il numero di job (circa 6.6 µs/job aggiunti per ogni aumento di 100x del numero di job).
• Impronta di Memoria: Il picco di memoria dell'orchestratore di OxyMake (90.7 MiB) è 2.04× più piccolo di quello di Snakemake (184.7 MiB) per grandi run.

Significato e Claim

Il documento posiziona OxyMake come un'evoluzione rigorosa del paradigma Make, privilegiando la correttezza e la riproducibilità rispetto alla pura velocità di esecuzione a freddo.

• Correttezza sopra le Euristiche: Sostituendo l' mtime con l'hashing del contenuto, OxyMake garantisce che la decisione di caching sia una funzione pura degli input dichiarati, sopravvivendo al churn del filesystem e consentendo la portabilità della cache tra macchine della stessa piattaforma.
• Rigore Formale: L'uso di TLA+ per specificare e verificare tramite model-check gli invarianti di sicurezza cross-session è una caratteristica distintiva, che affronta i rischi di concorrenza che i soli test non possono coprire.
• Conformità FAIR: OxyMake mira esplicitamente ai livelli di "Orchestrazione" (L2) e "Execution Trace" (L3/L4) della scala di riproducibilità FAIR, delegando il "Substrate" (L1) a gestori di pacchetti esterni (ad es. Guix, Nix) invece di tentare di assorbirne il contratto.
• Trade-off Onesti: Gli autori riconoscono esplicitamente che la contabilità content-addressed comporta una penalità sulle esecuzioni a freddo. Il motore scambia la pura velocità iniziale con la capacità di servire efficacementamente i re-run a cache calda e di fornire decisioni di rebuild audibili e portabili.

Il documento conclude che OxyMake è un "motore di workflow in Rust a singolo binario" che combina con successo il paradigma backward-chaining con l'ingegneria moderna, offrendo un'alternativa deterministica e ad alte prestazioni per i workflow scientifici dove la riproducibilità e la portabilità della cache sono fondamentali.