Notatki inżynieryjne Naly: deterministyczne codzienne publikowanie przez machine cron i flock

TL;DRNa dzień 28 czerwca 2026 r. Naly traktuje machine cron jako barierę ochronną publikacji: zaplanowane skrypty używają flock, uruchamiają uproszczone kroki bootstrap i zapisują wyniki w deterministycznych katalogach artefaktów pod NALY_LOG_ROOT. To przesuwa publikowanie z kruchej automatyzacji do audytowalnego pipeline'u, w którym każde uruchomienie albo tworzy jawne punkty kontrolne, albo kończy się niepowodzeniem z użytecznymi śladami, a każde ponowne uruchomienie można odtworzyć na podstawie deterministycznych artefaktów zamiast domyślnie wnioskować z ad hocowego wyjścia terminala.

Streszczenie

W przepływie pracy Naly problem publikacji to nie „jak uruchomić polecenie codziennie”, ale „jak udowodnić, że wynik publikacji został wygenerowany jednokrotnie, w pełni zaobserwowany i można go odtworzyć.” Praktyczna teza brzmi, że host cron plus blokowanie na poziomie plików to trwała warstwa sterująca: jeśli zadania są serializowane przez flock, wszystkie mutowalne skutki uboczne są filtrowane przez deterministyczne identyfikatory uruchomień, a logi zapisywane są poza repozytorium, to codzienne pipeline’y stają się operacyjnie stabilne nawet wtedy, gdy proces zostanie zrestartowany albo wystąpią nakładające się wywołania. Dzięki temu możliwe jest budowanie zaufania długoterminowego zarówno dla zastosowań pozyskiwania, jak i retencji, ponieważ poprawność publikacji jest wykazana, a nie domyślna.

Miejsce w Naly

Ścieżka publikacji Naly jest mocno warstwą aplikacyjną (renderowanie Next.js + React, Drizzle ORM z Neon oraz przesyłanie artefaktów), ale cron jest najbardziej zewnętrzną umową wykonawczą zanim te systemy otrzymają pracę. Ta granica ma znaczenie, ponieważ każda opublikowana notatka predykcyjna opiera się na zewnętrznych wywołaniach, zapisach do bazy danych i plikach, które mogą zakończyć się częściowo pomyślnie.

Wrappery machine cron w Naly znajdują się na styku między intencją czasową („uruchom codziennie”) a obserwowalnym działaniem („opublikuj rekord X, wygeneruj plik Y i ujawnij deterministyczny dowód Z”).

Ten projekt wspiera aktywne taktyki w stacku pozyskiwania i retencji (np. cykliczne generowanie artykułów i cykliczne zadania dystrybucji insightów), jednocześnie unikając przenoszenia każdego workflow do większego stogu orkiestratora, który dublowałby złożoność zanim zostaną potwierdzone gwarancje deterministyczne.

Mechanizm techniczny

Cron-safe flow publikacji w Naly składa się z czterech warstw.

Warstwa harmonogramu: crontab zapewnia semantykę wykonania minute-hour-day-month-week i ocenia wpisy harmonogramu co minutę. Dokumentacja jednoznacznie definiuje zasady dopasowania pól, a także subtelne zachowanie czasu, w tym przypadki brzegowe DST, które trzeba traktować jako część założeń poprawności.
Warstwa wzajemnego wykluczania: każdy wrapper pobiera wyłączny lock przy użyciu flock na sekcji krytycznej, zwykle z zachowaniem non-blocking, aby drugie wywołanie kończyło się znanym kodem zamiast nakładania duplikatów zadań.
Warstwa bootstrapu: środowisko wykonawcze jest celowo uproszczone i jawne. Wrapper wczytuje wymagane wartości środowiskowe (z .env.local w kontekście projektu), definiuje identyfikator uruchomienia i waliduje obowiązkowe warunki wstępne w trybie smoke przed zapisem do trwałych celów publikacji.
Warstwa obserwacji: logi i artefakty zapisywane są w zewnętrznym katalogu głównym (NALY_LOG_ROOT), w deterministycznych katalogach per-run. Nazwa katalogu pochodzi z kanonicznego znacznika czasu albo run id i przechowuje wystarczającą metadane, aby później prześledzić każde uruchomienie.

Zalecany wzorzec wykonania:

Cron odpala się.
Wrapper próbuje przejąć lock.
Po sukcesie uruchamiany jest bootstrap i testy smoke.
Główne polecenie publikacji uruchamia się z tsx punktem wejścia.
Manifest, wyniki i logi strukturalne są emitowane do stałych lokalizacji.
Lock jest zwalniany przy zakończeniu procesu przez zamknięcie deskryptora.

Przykładowy szkielet powłoki:

#!/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"

Co mówi literatura

Podstawą dla tego stosu jest manpage Linuksa: crontab(5) definiuje semantykę harmonogramu, sterowanie zmiennymi środowiskowymi i subtelne zachowanie czasu, w tym przypadki brzegowe DST; flock(1) definiuje tworzenie locka na plikach/katalogach, semantykę non-blocking oraz zachowanie zwalniania locka.

Z perspektywy systemowej literatura arXiv o deterministyczności strumieni wzmacnia wniosek, że spójność dostarczania i deterministyczne przetwarzanie mogą być praktyczniejsze niż ścisłe założenie exactly-once. To wpisuje się w preferencję Naly do deterministycznej powtarzalności zamiast ad-hocowych retry. Podobnie literatura arXiv o observability ostrzega, że trace’i i kauzalność mogą zawieść, gdy porządek czasowy jest słaby, dlatego znaczniki czasu uruchomień i scentralizowane korzenie artefaktów są częścią poprawności, a nie wygodą.

Prace skupione na odtwarzalności pipeline’ów wzmacniają to samo podejście: praktyczny pipeline powinien generować artefakty, które można ponownie uruchomić i wersjonować, dzięki czemu awarie są możliwe do naprawienia, a dowód jest przenośny. W przypadku systemów agentowych, nowsze badania nad frameworkami strukturalnej observability podkreślają, że metadane operacyjne są częścią jakości wdrożenia, a nie luksusem po incidente.

Łączny wniosek jest spójny ze wszystkich źródeł: flockwzajemne wykluczanie i deterministyczna organizacja artefaktów w stylu POSIX to konkretne prymitywy, które wdrażają niezawodność przy niskim koszcie.

Kompromisy projektowe

Szczegółowość locka: jeden globalny lock jest łatwy do zweryfikowania, ale może serializować niezależne zadania; locki per workflow zwiększają przepustowość, ale wymagają silniejszego zarządzania nazwami locków.
Blokowanie blokujące vs nieblokujące: non-blocking kończy się czytelnie z jednoznacznym sygnałem konfliktu; blokujące może ukrywać zawieszone zadania i wydłużać okna nakładania się wywołań.
Prostota host cron vs scentralizowane schedulery: cron zmniejsza złożoność infrastruktury i promień oddziaływania, ale przesuwa zarządzanie stanem, retry, dedupe do kodu aplikacji.
Głębokość observability vs koszt: rozbudowane logi strukturalne zwiększają koszty storage i analizy, ale istotnie skracają średni czas triage po awarii.
Retencja deterministycznych artefaktów vs presja na storage: dłuższa retencja poprawia odtwarzalność i jakość audytu, podczas gdy zbyt długa retencja podnosi koszt, jeśli nie dodamy polityk lifecycle.

Tryby awarii

Nakładające się wykonania: pojawiają się, gdy poprzednie uruchomienie nadal działa, a lock zostaje zwolniony z opóźnieniem; ogranicza się to przez nieblokujące flock i jednoznaczne kody zakończenia konfliktu.
Ograniczenia backendu locka: flock może zawieść na niektórych systemach plików (ograniczenia NFS/CIFS), dlatego ścieżki locków powinny, o ile to możliwe, pozostawać na dysku lokalnym.
Brakujące lub powtarzające się wywołania wokół przejść DST: semantyka crona może pomijać albo powielać okna; ogranicza to zachowanie idempotentne zadań i kontrole dedupe oparte o run ID.
Przestarzałe artefakty procesów z częściowych awarii: zapobiega się temu przez wzorce atomowego zapisu i punkty kontrolne manifestu dla każdego uruchomienia.
Niedeterministyczne skutki uboczne: retry w stałym czasie bez dedupe mogą podwójnie opublikować treść; przeciwdziała się temu poprzez idempotentne zapisy i unikalne ograniczenia w magazynach stanu downstream.
Niestabilne założenia czasowe w logach: awarie observability wynikające z niesynchronizowanych zegarów mogą zmieniać kolejność śladów; ogranicza się to znacznikami czasu run w UTC i stabilnymi metadanymi sekwencji.

Uwagi implementacyjne

Dla Naly praktyczny stan docelowy to:

Wyrażenie crona w machine crontab, bez komponentów interaktywnych.
flock lock wokół każdego wywołania zadania publikacji.
Obowiązkowy tryb smoke i jednoznaczne kody zakończenia.
tsc/tsx entrypointy pochodzące z wrappera, a nie z niejawnych ścieżek wykonywania powłoki.
Struktura katalogów artefaktów obejmująca run id, datę i job id.
Logi strukturalne zapisywane w NALY_LOG_ROOT z deterministycznymi nazwami.
Zadania publikacyjne zaprojektowane jako idempotentne na granicy trwałości.

Operacyjnie to miejsce, gdzie „automatyzacja” zamienia się w „infrastrukturę publikacji”: stabilne harmonogramowanie, kontrolowana współbieżność i inspekcyjne wyniki stają się minimalnym interfejsem wiarygodnego wydawania treści.