Naly 엔지니어링 노트: 머신 cron과 flock로 구현한 결정론적 일일 발행

TL;DR2026년 6월 28일 기준으로 Naly는 머신 cron을 발행 가드레일로 취급합니다: 예약 스크립트는 flock필요 최소화된 부트스트랩 단계를 거쳐 실행되며, 출력물을 NALY_LOG_ROOT아래의 결정론적 아티팩트 디렉터리에 기록합니다. 이는 발행을 취약한 자동화에서 감사 가능한 파이프라인으로 전환합니다. 각 실행은 명시적 체크포인트를 생성하거나 조치 가능한 추적 로그와 함께 실패하고, 각 재시도는 임시 터미널 출력에서 추론하지 않고 결정론적 아티팩트를 통해 재구성됩니다.

개요

Naly의 워크플로우에서 발행 문제는 "매일 명령을 실행하는 방법"이 아니라 "발행 결과가 한 번 생성되어 완전하게 관측되었고 재실행될 수 있음을 입증하는 방법"입니다. 실용적 가설은 호스트 cron과 파일 단위 잠금이 내구성 있는 제어 평면이 된다는 점입니다. 작업이 flock에 의해 직렬화되고, 모든 가변적 부작용은 결정론적 실행 ID로 게이트되며, 로그가 저장소 외부에 기록되면, 프로세스가 재시작되거나 트리거가 중첩되어도 일일 파이프라인은 운영적으로 안정됩니다. 이는 획득과 유지 전략 모두에서 장기 신뢰를 가능하게 합니다. 발행 정합성은 암시가 아니라 증거로 보여주기 때문입니다.

Naly에서의 위치

Naly의 발행 경로는 애플리케이션 계층(Next.js + React 렌더링, Drizzle ORM + Neon, 아티팩트 업로드)에 크게 의존하지만, cron은 이 시스템들이 작업을 받기 전의 최상위 런타임 계약입니다. 이 경계가 중요한 이유는 발행된 예측 노트가 외부 호출, 데이터베이스 쓰기, 생성 파일에 의존하며, 이들은 부분적으로만 성공할 수 있기 때문입니다.

Naly에서 머신 cron 래퍼는 시간 의도(\"매일 실행\")와 관측 가능한 동작(\"기록 X를 발행하고, 파일 Y를 만들며, 결정론적 근거 Z를 노출\") 사이의 경계에 위치합니다.

이 설계는 획득/유지 전략의 핵심 전술(예: 정기적 기사 생성 및 정기 인사이트 배포 작업)을 지원하면서, 결정론적 보장이 검증되기 전 모든 워크플로를 더 큰 오케스트레이션 스택으로 옮겨 복잡도를 중복시키는 일을 피합니다.

기술적 메커니즘

Naly의 크론 안전 발행 흐름은 네 가지 계층으로 구성됩니다.

스케줄 계층: crontab은 분-시-일-월-요일 실행 의미론을 제공하고 매 분 스케줄 항목을 평가합니다. 문서에는 필드 매칭 규칙과 함께 타임존 및 DST 경계 동작이 정확성 가정의 일부로 명시되어 있습니다.
상호 배제 계층: 각 래퍼는 배타적 잠금을 획득하며, flock 를 임계 구간에 적용합니다. 일반적으로 비차단 방식으로 동작해 두 번째 호출이 중복 작업을 적재하는 대신 알려진 종료 코드로 종료되도록 합니다.
부트스트랩 계층: 런타임은 의도적으로 최소화되고 명시적입니다. 래퍼는 필수 환경값(이 프로젝트 맥락에서 .env.local )
실행을 정의하고, 실행 식별자를 지정한 다음, 영구 발행 대상에 쓰기 전에 스모크 모드에서 필수 사전 조건을 검증합니다.NALY_LOG_ROOT관측 계층: 로그와 아티팩트가 외부 루트(

)에 실행당( per-run ) 결정론적 디렉터리로 기록됩니다. 디렉터리명은 정식 타임스탬프 또는 실행 ID에서 파생되며, 이후 각 시도에 대한 추론에 필요한 충분한 메타데이터를 보존합니다.

권장 실행 패턴:
Cron이 발동됩니다.
래퍼가 잠금 획득을 시도합니다.
성공하면 부트스트랩 및 스모크 검사 실행 tsx 메인 발행 명령이
엔트리포인트로 실행됩니다.
매니페스트, 출력물, 구조화 로그가 고정된 위치로 출력됩니다.

프로세스 종료 시점에 디스크립터 닫기로 잠금이 해제됩니다.

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

예시 쉘 스켈레톤:

문헌은 다음에서 확인됩니다 crontab(5) 이 Linux 매뉴얼은 이 스택의 기반입니다: flock(1) 스케줄 의미론, 환경 변수 제어, DST 경계 사례를 포함한 미묘한 시간 동작을 정의합니다.

파일/디렉터리에서 잠금 생성, 비차단 의미론, 잠금 해제 동작을 정의합니다.

시스템 관점에서 스트림 결정론성에 대한 arXiv 연구는 배달 일관성과 결정론적 처리가 정확히 한 번 처리 가정보다 실용적일 수 있음을 뒷받침합니다. 이는 Naly가 임의 재시도보다 결정론적 재실행 가능성을 선호하는 방향과 일치합니다. 마찬가지로 분산 AI 추론 시스템에서 시간 인과성/가시성 실패에 관한 arXiv 연구는, 시간 순서가 약해지면 추적과 인과가 실패할 수 있음을 경고하므로, 실행 타임스탬프와 중앙 집중형 아티팩트 루트가 편의 기능이 아니라 정합성의 일부가 되는 이유를 설명합니다.

재현성 중심 작업은 재실행 가능한 파이프라인에 같은 방향을 제시합니다. 실용적 파이프라인은 재실행 가능한 버전 관리 아티팩트를 생성해 실패를 조치 가능하게 만들고, 증거를 이식 가능하게 해야 합니다. 에이전트형 시스템에서는 최근의 구조화된 가시성 프레임워크 연구도 운영 메타데이터를 배포 품질의 핵심으로 보며, 사후 정리용 사치가 아님을 강조합니다. flock결론은 출처 모두에서 일관됩니다:

상호 배제와 결정론적 아티팩트화는 낮은 비용으로 신뢰성을 실무화하는 구체적 원시 동작입니다.

설계 트레이드오프
잠금 세분화: 단일 글로벌 잠금은 추론이 쉽지만 서로 무관한 작업까지 직렬화할 수 있고, 워크플로별 잠금은 처리량을 높이지만 더 강한 잠금명 거버넌스가 필요합니다.
블로킹 대 비차단 잠금 획득: 비차단은 충돌 신호를 명시적으로 반환하며 깔끔하게 종료하고, 블로킹은 정지된 작업을 가리고 중복 오버랩 구간을 확대할 수 있습니다.
호스트 크론 단순성 대 중앙 스케줄러: cron은 인프라 복잡도와 영향 범위를 줄여주지만, 상태·재시도·중복 제거 거버넌스를 애플리케이션 코드로 밀어 넣어야 합니다.
가시성 깊이 대 비용: 구조화 로그를 상세하게 남기면 저장·분석 비용이 증가하지만, 장애 후 평균 복구 시간이 크게 줄어듭니다.

결정론적 아티팩트 보존 기간 대 저장소 압박: 보존 기간을 늘리면 재실행성과 감사 품질이 좋아지지만, 라이프사이클 정책이 없다면 비용이 커집니다.

실패 모드 flock 중첩 실행: 이전 실행이 아직 활성 상태이고 잠금이 늦게 해제될 때 발생합니다. 비차단 잠금과 명시적 충돌 종료 코드를 사용해 완화합니다.
잠금 백엔드 한계: flock 일부 파일시스템(NFS/CIFS)에서는 실패할 수 있으므로 잠금 경로는 가능하면 로컬 디스크에 두어야 합니다.
DST 전환 전후의 누락 또는 반복 호출: 크론 의미론이 창을 건너뛰거나 중복 생성할 수 있으므로, 실행 ID 기반의 멱등성 동작과 중복 제거 체크로 완화합니다.
부분 실패로 인한 잔존 프로세스 아티팩트: 원자적 쓰기 패턴과 실행별 매니페스트 체크포인트로 회피합니다.
비결정적 부작용: 고정 시간 재시도가 중복 점검 없이는 중복 발행으로 이어질 수 있으므로, 영속성 경계에서 멱등 쓰기와 고유 제약을 적용합니다.
로그의 불안정한 타이밍 가정: 동기화되지 않은 시계에서 오는 가시성 실패는 추적 순서를 뒤바꿀 수 있으므로 UTC 실행 타임스탬프와 안정적인 시퀀스 메타데이터로 완화합니다.

구현 메모

Naly에서의 실전 목표 상태는 다음과 같습니다:

머신 crontab의 cron 표현식 사용, 대화형 구성요소 없음.
flock 각 발행 작업 호출 주위의 잠금 적용.
의무 스모크 모드와 명시적 종료 코드.
tsc/tsx 래퍼의 엔트리포인트에서 실행, 암묵적 쉘 실행 경로 사용 금지.
실행 ID, 날짜, 작업 ID가 포함된 아티팩트 디렉터리 구조.
구조화 로그를 NALY_LOG_ROOT 결정론적 이름으로 기록.
영속성 경계에서 멱등성을 보장하도록 설계된 발행 작업.

운영적으로 이는 '자동화'가 '발행 인프라'로 전환되는 지점입니다. 안정적인 스케줄링, 보호된 동시성, 점검 가능한 출력이 신뢰 가능한 콘텐츠 공개의 최소 인터페이스가 됩니다.