Naly Engineering Notes: Deterministic Daily Publishing Through Machine Cron and Flock

TL;DRAs of June 28, 2026, Naly treats machine cron as a publishing guardrail: scheduled scripts use flock, run through stripped bootstrap steps, and write outputs into deterministic artifact directories under NALY_LOG_ROOT. This shifts publishing from brittle automation into an auditable pipeline where every run either produces explicit checkpoints or fails with actionable traces, and each retry can be reconstructed from deterministic artifacts rather than inferred from ad-hoc terminal output.

Abstract

In Naly’s workflow, the publication problem is not "how to run a command every day" but "how to prove a publishing outcome was produced once, observed fully, and can be replayed." A practical thesis is that host cron plus file-level locking is a durable control plane: if jobs are serialized by flock, all mutable side effects are gated by deterministic run IDs, and logs are written outside the repo, then daily pipelines become operationally stable even when the process is restarted or overlapping triggers occur. This enables long-horizon trust-building for both acquisition and retention use cases because publication correctness is evidenced, not implied.

Where it sits in Naly

Naly’s publication path is heavily application-layer (Next.js + React rendering, Drizzle ORM against Neon, and artifact uploads), but cron is the outermost runtime contract before those systems receive work. That boundary matters because every published prediction note depends on external calls, database writes, and generated files that can partially succeed.

Machine cron wrappers in Naly sit at the seam between time intent ("run daily") and observable action ("publish record X, produce file Y, and expose deterministic evidence Z").

This design supports active tactics in the acquisition/retention stack (e.g., recurring article generation and recurring insight distribution jobs) while avoiding moving every workflow into a larger orchestrator stack that would duplicate complexity before deterministic guarantees are proven.

Technical mechanism

Naly’s cron-safe publishing flow has four layers.

Schedule layer: crontab provides minute-hour-day-month-week execution semantics and evaluates schedule entries every minute. The docs explicitly define field matching rules, plus time-zone and DST edge behavior that must be treated as part of correctness assumptions.
Mutual exclusion layer: each wrapper acquires an exclusive lock using flock around the critical section, typically with non-blocking behavior so a second invocation exits with a known code instead of stacking duplicate jobs.
Bootstrap layer: runtime is intentionally stripped and explicit. The wrapper loads required environment values (from .env.local in this project context), defines a run identifier, and validates mandatory preconditions in smoke mode before writing to persistent publication targets.
Observation layer: logs and artifacts are written to an external root (NALY_LOG_ROOT) in deterministic per-run directories. The directory name is derived from a canonical timestamp or run id and persists enough metadata to reason about each attempt later.

Recommended execution pattern:

Cron fires.
Wrapper tries lock acquisition.
On success, bootstrap and smoke checks run.
Main publish command executes with tsx entrypoint.
Manifest, outputs, and structured logs are emitted to fixed locations.
Lock is released on process exit via descriptor close.

Example shell skeleton:

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

What the literature says

The Linux manual pages are the grounding layer for this stack: crontab(5) defines schedule semantics, environment variable controls, and subtle time behavior including DST edge cases; flock(1) defines lock creation on files/directories, non-blocking semantics, and lock release behavior.

From a systems perspective, arXiv work on stream determinism reinforces that delivery consistency and deterministic processing can be more practical than strict exactly-once assumptions. That aligns with Naly’s preference for deterministic rerunability over ad-hoc retries. Similarly, arXiv literature on observability warns that traces and causality can fail when time ordering is weak, which is why run timestamps and centralized artifact roots are part of correctness, not convenience.

Reproducibility-focused work on replayable pipelines supports the same direction: a practical pipeline should produce rerunnable, versioned artifacts so failures are actionable and evidence is portable. For agentic systems, recent work on structured observability frameworks emphasizes that operational metadata is part of deployment quality, not a postmortem luxury.

The net claim is consistent across sources: flock-style mutual exclusion and deterministic artifacting are concrete primitives that operationalize reliability at low cost.

Design trade-offs

Lock granularity: one global lock is easy to reason about but can serialize unrelated jobs; per-workflow locks increase throughput but require stronger lock-name governance.
Blocking vs non-blocking lock acquisition: non-blocking exits cleanly with explicit conflict signals; blocking can hide stuck jobs and extend overlap windows.
Host cron simplicity vs centralized schedulers: cron lowers infra complexity and blast radius, but pushes governance (state, retries, dedupe) into application code.
Observability depth vs cost: verbose structured logs increase storage and analysis effort, but they materially reduce mean-time-to-triage after failures.
Deterministic artifact retention vs storage pressure: longer retention improves replayability and audit quality, while too-long retention increases cost unless lifecycle policies are added.

Failure modes

Overlapping executions: occurs when previous run is still active and lock is released late; mitigated by non-blocking flock and explicit conflict exit codes.
Lock backend limitations: flock can fail on certain filesystems (NFS/CIFS caveats), so lock paths should stay on local disk where possible.
Missing or repeated invocations around DST transitions: cron semantics can skip or duplicate windows; mitigated by idempotent job behavior and dedupe checks based on run IDs.
Stale process artifacts from partial failures: avoided by atomic write patterns and manifest checkpoints per run.
Non-deterministic side effects: fixed-time retries without dedupe can double-publish content; mitigated by idempotent writes and unique constraints in downstream state stores.
Unstable timing assumptions in logs: observability failures from unsynchronized clocks can reorder traces; mitigated with UTC run timestamps and stable sequence metadata.

Implementation notes

For Naly, the practical target state is:

Cron expression in machine crontab, no interactive components.
flock lock around each publish task invocation.
Mandatory smoke mode and explicit exit codes.
tsc/tsx entrypoints from the wrapper, not implicit shell execution paths.
Artifact directory structure that includes run id, date, and job id.
Structured logs written to NALY_LOG_ROOT with deterministic names.
Publication jobs designed to be idempotent at the persistence boundary.

Operationally, this is where “automation” is converted into “publishing infrastructure”: stable scheduling, guarded concurrency, and inspectable outputs become the minimum interface for trustworthy content release.