Notes d'ingénierie Naly : publication quotidienne déterministe via machine cron et flock

TL;DRAu 28 juin 2026, Naly considère le cron machine comme une barrière de publication : les scripts planifiés utilisent flock, passent par des étapes de bootstrap simplifiées, et écrivent les sorties dans des répertoires d’artefacts déterministes sous NALY_LOG_ROOT. Cela transforme la publication d'une automatisation fragile en un pipeline auditable où chaque exécution produit des points de contrôle explicites ou échoue avec des traces exploitables, et chaque nouvelle tentative peut être reconstruite à partir d’artefacts déterministes plutôt que déduite d’une sortie terminale ad hoc.

Résumé

Dans le flux de travail de Naly, le problème de la publication n’est pas « comment exécuter une commande chaque jour » mais « comment prouver qu’un résultat de publication a été produit une fois, observé pleinement et peut être rejoué ». Une thèse pratique est que le cron hôte associé au verrouillage au niveau fichier constitue une couche de contrôle durable : si les tâches sont sérialisées par flockverrou, que tous les effets de bord mutables sont régis par des identifiants d’exécution déterministes et que les journaux sont écrits en dehors du dépôt, alors les pipelines quotidiens deviennent opérationnellement stables même quand le processus est redémarré ou que des déclenchements se chevauchent. Cela permet de construire la confiance sur le long terme pour l’acquisition et la rétention, car la correction de la publication est prouvée, pas implicite.

Où cela se situe dans Naly

Le chemin de publication de Naly est majoritairement applicatif (rendu Next.js + React, Drizzle ORM avec Neon et uploads d’artefacts), mais le cron est le contrat d’exécution externe le plus externe avant que ces systèmes ne reçoivent du travail. Cette frontière est importante car chaque note de prédiction publiée dépend d’appels externes, d’écritures en base de données et de fichiers générés pouvant réussir partiellement.

Les wrappers de machine cron dans Naly se trouvent à la jonction entre l’intention temporelle (« exécuter quotidiennement ») et l’action observable (« publier l’enregistrement X, produire le fichier Y et exposer la preuve déterministe Z »).

Cette conception soutient les tactiques actives de la pile acquisition/rétention (par exemple la génération d’articles récurrents et la distribution d’insights récurrente) tout en évitant de déplacer chaque flux de travail vers une infrastructure d’orchestration plus large qui dupliquerait la complexité avant que les garanties déterministes ne soient démontrées.

Mécanisme technique

Le flux de publication sécurisé pour cron de Naly comporte quatre couches.

Couche de planification : crontab fournit une sémantique d’exécution minute-heure-jour-mois-semaine et évalue les entrées de planification chaque minute. La documentation définit explicitement les règles de correspondance des champs, ainsi que les comportements subtils liés au fuseau horaire et au passage horaire, qui doivent être considérés comme des hypothèses de correction.
Couche d’exclusion mutuelle : chaque wrapper acquiert un verrou exclusif à l’aide de flock autour de la section critique, généralement en mode non bloquant pour qu’un second appel se termine avec un code connu au lieu d’empiler des tâches en doublon.
Couche bootstrap : l’exécution est volontairement allégée et explicite. Le wrapper charge les variables d’environnement requises (depuis .env.local dans le contexte de ce projet), définit un identifiant d’exécution et valide les préconditions obligatoires en mode smoke avant d’écrire vers des cibles de publication persistantes.
Couche d’observation : les journaux et les artefacts sont écrits dans une racine externe (NALY_LOG_ROOT) dans des répertoires déterministes par exécution. Le nom du répertoire est dérivé d’un horodatage canonique ou d’un identifiant d’exécution et conserve suffisamment de métadonnées pour raisonner plus tard sur chaque tentative.

Modèle d’exécution recommandé :

Le cron se déclenche.
Le wrapper tente d’acquérir le verrou.
En cas de succès, le bootstrap et les contrôles smoke s’exécutent.
La commande principale de publication s’exécute avec tsx point d’entrée.
Le manifeste, les sorties et les journaux structurés sont produits dans des emplacements fixes.
Le verrou est libéré à la sortie du processus via la fermeture du descripteur.

Exemple de squelette 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"

Ce que dit la littérature

Les pages de manuel Linux constituent la couche fondamentale de cette architecture : crontab(5) définissent les règles de sémantique de planification, les contrôles des variables d’environnement et les comportements temporels subtils, y compris les cas limites de DST ; flock(1) définissent la création de verrous sur fichiers/répertoires, les sémantiques non bloquantes et le comportement de libération des verrous.

Du point de vue des systèmes, les travaux arXiv sur la déterminisme des flux confirment que la cohérence de livraison et le traitement déterministe peuvent être plus praticables que des hypothèses strictes d’exactement une fois. Cela correspond à la préférence de Naly pour la rejouabilité déterministe plutôt que pour des relances ad hoc. De même, la littérature arXiv sur l’observabilité avertit que les traces et la causalité peuvent échouer lorsque l’ordre temporel est faible, c’est pourquoi les horodatages d’exécution et les racines d’artefacts centralisées font partie de la correction, pas de la commodité.

Les travaux axés sur la reproductibilité des pipelines rejouables vont dans la même direction : un pipeline opérationnel doit produire des artefacts versionnés et rejouables afin que les erreurs soient exploitables et que les preuves restent transportables. Pour les systèmes agentiques, des travaux récents sur des cadres d’observabilité structurée soulignent que les métadonnées opérationnelles font partie de la qualité de déploiement, pas d’un luxe réservé aux post‑mortems.

La conclusion générale est cohérente entre les sources : flockl’exclusion mutuelle de style verrouillage et l’artefactation déterministe sont des primitives concrètes qui rendent la fiabilité opérationnelle à bas coût.

Arbitrages de conception

Granularité du verrou : un verrou global est simple à raisonner mais peut sérialiser des tâches non liées ; des verrous par flux augmentent le débit mais exigent une gouvernance plus stricte des noms de verrou.
Acquisition bloquante vs non bloquante : la non-bloquante se termine proprement avec des signaux de conflit explicites ; la bloquante peut masquer des tâches figées et prolonger les fenêtres de chevauchement.
Simplicité du cron hôte vs planificateurs centralisés : le cron réduit la complexité et l’ampleur de l’infrastructure, mais déplace la gouvernance (état, retries, déduplication) vers le code applicatif.
Profondeur d’observabilité vs coût : des journaux structurés verbeux augmentent le stockage et l’effort d’analyse, mais réduisent de manière significative le temps moyen de triage après incident.
Rétention d’artefacts déterministes vs pression de stockage : une rétention plus longue améliore la rejouabilité et la qualité d’audit, tandis qu’une rétention trop longue augmente les coûts si des politiques de cycle de vie ne sont pas ajoutées.

Modes de défaillance

Exécutions qui se chevauchent : cela se produit lorsque l’exécution précédente est encore active et que le verrou est libéré tardivement ; cela est atténué par la méthode flock et des codes de sortie de conflit explicites.
Limitations du backend de verrou : flock peuvent échouer sur certains systèmes de fichiers (précautions NFS/CIFS), il faut donc, quand c’est possible, garder les chemins de verrou sur disque local.
Invocations manquantes ou répétées autour des transitions DST : la sémantique cron peut sauter ou dupliquer des fenêtres ; cela est atténué par un comportement idempotent des tâches et des contrôles de déduplication fondés sur les identifiants d’exécution.
Artefacts de processus obsolètes issus d’échecs partiels : évités par des écritures atomiques et des points de contrôle du manifeste par exécution.
Effets de bord non déterministes : des relances à heure fixe sans déduplication peuvent double-publier du contenu ; cela est atténué par des écritures idempotentes et des contraintes d’unicité dans les magasins d’état aval.
Hypothèses de timing instables dans les journaux : des pannes d’observabilité dues à des horloges non synchronisées peuvent réordonner les traces ; cela est atténué par des horodatages d’exécution UTC et des métadonnées de séquence stables.

Notes d’implémentation

Pour Naly, l’état cible opérationnel est :

Expression cron dans le crontab machine, sans composants interactifs.
flock Verrou autour de chaque invocation de tâche de publication.
Mode smoke obligatoire et codes de sortie explicites.
tsc/tsx points d’entrée depuis le wrapper, et non des chemins d’exécution implicites du shell.
Structure des répertoires d’artefacts incluant l’ID d’exécution, la date et l’ID de tâche.
Journaux structurés écrits dans NALY_LOG_ROOT avec des noms déterministes.
Tâches de publication conçues pour être idempotentes à la frontière de la persistance.

Concrètement, c’est ici que l’« automatisation » est convertie en « infrastructure de publication » : une planification stable, une concurrence sécurisée et des sorties inspectables deviennent l’interface minimale d’un déploiement éditorial digne de confiance.