Note di ingegneria Naly: pubblicazione giornaliera deterministica con machine cron e flock

TL;DRA partire dal 28 giugno 2026, Naly considera il machine cron una guardrail per la pubblicazione: gli script pianificati usano flock, passano attraverso passaggi di bootstrap semplificati e scrivono i risultati in directory di artefatti deterministici sotto NALY_LOG_ROOT. Questo sposta la pubblicazione da un'automazione fragile a una pipeline verificabile, in cui ogni esecuzione produce checkpoint espliciti o fallisce con tracce azionabili, e ogni ripetizione può essere ricostruita da artefatti deterministici invece di essere inferita dall'output del terminale ad hoc.

Abstract

Nel flusso di Naly, il problema della pubblicazione non è "come eseguire un comando ogni giorno" ma "come dimostrare che un risultato di pubblicazione sia stato prodotto una volta, osservato per intero ed è possibile riprodurlo." Una tesi pratica è che host cron più lock a livello di file sia un control plane durevole: se i job sono serializzati da flock, tutti gli effetti collaterali mutabili sono vincolati da run ID deterministici e i log sono scritti fuori dal repository, le pipeline giornaliere diventano operativamente stabili anche quando il processo viene riavviato o si verificano trigger sovrapposti. Questo abilita la costruzione di fiducia nel lungo periodo per acquisizione e retention perché la correttezza della pubblicazione è documentata, non implicita.

Dove si colloca in Naly

Il percorso di pubblicazione di Naly è fortemente application-layer (rendering Next.js + React, Drizzle ORM su Neon e upload degli artefatti), ma il cron è il contratto runtime più esterno prima che quei sistemi ricevano lavoro. Questo confine è importante perché ogni nota di previsione pubblicata dipende da chiamate esterne, scritture sul database e file generati che possono riuscire solo in parte.

Gli wrapper machine cron in Naly si trovano nella giunzione tra l'intento temporale ("esegui ogni giorno") e l'azione osservabile ("pubblica il record X, produce il file Y ed espone la prova deterministica Z").

Questo design supporta le tattiche attive nello stack acquisition/retention (ad esempio, generazione ricorrente di articoli e job ricorrenti di distribuzione degli insight) evitando di spostare ogni workflow in uno stack di orchestrazione più grande che duplicherebbe la complessità prima che vengano provate le garanzie deterministiche.

Meccanismo tecnico

Il flusso di pubblicazione cron-safe di Naly ha quattro livelli.

Livello di scheduling: la crontab fornisce la semantica di esecuzione per minuti-ore-giorni-mese-settimana e valuta le entry di schedule ogni minuto. La documentazione definisce esplicitamente le regole di matching dei campi, oltre al fuso orario e al comportamento del DST nei punti limite, che devono essere trattati come parte delle assunzioni di correttezza.
Livello di mutua esclusione: ogni wrapper acquisisce un lock esclusivo usando flock intorno alla sezione critica, tipicamente con comportamento non bloccante, così una seconda invocazione esce con un codice noto invece di impilare job duplicati.
Livello bootstrap: il runtime è intenzionalmente ridotto ed esplicito. Il wrapper carica i valori di ambiente richiesti (da .env.local in questo contesto di progetto), definisce un identificatore di run e valida i prerequisiti obbligatori in modalità smoke prima di scrivere verso destinazioni di pubblicazione persistenti.
Livello di osservazione: log e artefatti vengono scritti in una root esterna (NALY_LOG_ROOT) in directory deterministiche per run. Il nome della directory deriva da un timestamp canonico o da un run id e conserva sufficienti metadati per ragionare su ogni tentativo in seguito.

Modello di esecuzione consigliato:

Il cron scatta.
Il wrapper prova l'acquisizione del lock.
In caso di successo, bootstrap e controlli smoke vengono eseguiti.
Il comando principale di pubblicazione viene eseguito con tsx entrypoint.
Manifest, output e log strutturati vengono emessi in percorsi fissi.
Il lock viene rilasciato all'uscita del processo tramite la chiusura del descriptor.

Esempio di skeleton shell:

#!/usr/bin/env bash
set -euo pipefail

RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)"
LOCK_FILE=${NALY_LOCK:-/var/lock/naly-publish.lock}
ARTIFACT_DIR="${NALY_LOG_ROOT:-/tmp/logs}/publish/$RUN_ID"
SMOKE_MODE=${NALY_SMOKE:-0}

mkdir -p "$ARTIFACT_DIR"
exec 9>"$LOCK_FILE"
flock -n 9 || exit 75

set -a
. "/path/to/repo/.env.local"
set +a

if [ "${SMOKE_MODE}" = "1" ]; then
  echo "smoke ok"
fi

pnpm tsx scripts/publish.ts --run-id "$RUN_ID" --artifact-dir "$ARTIFACT_DIR"

Cosa dice la letteratura

Le pagine del manuale Linux sono lo strato fondante di questo stack: crontab(5) definisce le semantiche di scheduling, i controlli delle variabili d'ambiente e i comportamenti temporali sottili, inclusi i casi limite del DST; flock(1) definisce la creazione di lock su file/directory, la semantica non bloccante e il comportamento di rilascio.

Dal punto di vista dei sistemi, il lavoro su arXiv sulla stream determinism rafforza che la consistenza di consegna e l'elaborazione deterministica possano essere più pratiche dell'assunzione exactly-once. Questo si allinea alla preferenza di Naly per la rieseguibilità deterministica rispetto ai retry ad hoc. Allo stesso modo, la letteratura arXiv sull'osservabilità avverte che tracce e causalità possono fallire quando l'ordinamento temporale è debole, motivo per cui i timestamp di run e le root di artifact centralizzate fanno parte della correttezza, non della convenienza.

Il lavoro incentrato sulla riproducibilità nelle pipeline riproducibili supporta la stessa direzione: una pipeline pratica dovrebbe produrre artefatti versionati e rieseguibili in modo che i guasti siano risolvibili e le prove siano portabili. Per i sistemi agentici, lavori recenti su framework di osservabilità strutturata sottolineano che i metadati operativi sono parte della qualità del deployment, non un lusso post-mortem.

La tesi complessiva è coerente tra le fonti: flockla mutua esclusione in stile flock e la creazione di artefatti deterministici sono primitive concrete che rendono operativa l'affidabilità con basso costo.

Trade-off di design

Granularità del lock: un lock globale è facile da ragionare ma può serializzare job non correlati; lock per workflow aumentano la throughput ma richiedono una governance più forte sul nome dei lock.
Acquisizione lock bloccante vs non bloccante: il non bloccante esce pulitamente con segnali di conflitto espliciti; il bloccante può nascondere job bloccati e allungare le finestre di sovrapposizione.
Semplicità dell'host cron vs scheduler centralizzati: cron riduce la complessità infrastrutturale e il blast radius, ma sposta la governance (state, retry, dedupe) nel codice applicativo.
Profondità di osservabilità vs costo: log strutturati verbosi aumentano storage e sforzo di analisi, ma riducono in modo sostanziale il mean-time-to-triage dopo i guasti.
Retention degli artefatti deterministici vs pressione su storage: retention più lunga migliora la riproducibilità e la qualità degli audit, mentre retention troppo lunga aumenta i costi se non vengono aggiunte policy lifecycle.

Modalità di guasto

Esecuzioni sovrapposte: si verificano quando il run precedente è ancora attivo e il lock viene rilasciato in ritardo; mitigato da flock acquisizione non bloccante e codici di uscita di conflitto espliciti.
Limitazioni del backend del lock: flock può fallire su alcuni filesystem (avvertenze NFS/CIFS), quindi i percorsi dei lock dovrebbero restare su disco locale quando possibile.
Invocazioni mancanti o ripetute intorno alle transizioni DST: la semantica cron può saltare o duplicare finestre; si mitiga con comportamento idempotente del job e controlli dedupe basati su run ID.
Artefatti di processo obsoleti da failure parziali: evitati con pattern di scrittura atomica e checkpoint del manifest per run.
Effetti collaterali non deterministici: ritentativi a tempo fisso senza dedupe possono doppia-pubblicare contenuti; mitigato da scritture idempotenti e vincoli unici nei state store a valle.
Assunzioni temporali instabili nei log: guasti di osservabilità da clock non sincronizzati possono riordinare le tracce; mitigato con timestamp UTC dei run e metadati di sequenza stabili.

Note di implementazione

Per Naly, lo stato target pratico è:

Espressione cron in machine crontab, nessun componente interattivo.
flock lock attorno a ogni invocazione del task di pubblicazione.
Modalità smoke obbligatoria e codici di uscita espliciti.
tsc/tsx entrypoint dal wrapper, non percorsi di esecuzione impliciti della shell.
Struttura della directory degli artefatti che includa run id, data e job id.
Log strutturati scritti su NALY_LOG_ROOT con nomi deterministici.
Job di pubblicazione progettati per essere idempotenti al confine della persistenza.

Operativamente, qui "l'automazione" viene convertita in "infrastruttura di pubblicazione": scheduling stabile, concorrenza protetta e output ispezionabili diventano l'interfaccia minima per un rilascio di contenuti affidabile.