Present Means Complete

"A file becomes a cache entry only after it validates and is atomically renamed. Until then, it isn't there."

The Half-Written File

Here's a failure that ruins caches quietly. You synthesize audio, start writing it to the cache path, and something interrupts — a crash, a full disk, a killed process. Now a truncated file sits at the exact path the next reader checks. It looks like a cache hit. It plays as a burst of static or three seconds of a ten-second sentence. The cache didn't just miss; it lied.

Two Steps Between Bytes and Cache Entry

Bellows never lets a reader observe an in-progress file. Fresh audio is written to a temporary file first — with a real media suffix, so a validator can actually decode it. Then it's validated: decode it, confirm it's real audio of the expected shape, reject anything truncated or silent. Only after it passes is it moved into place by an atomic rename. On a single filesystem, rename is atomic: a reader sees either the old state or the fully-complete new file, never the middle.

Why This Ordering Is the Whole Guarantee

Because publication is the last step and it's atomic, the presence of a cache entry is the proof that it's complete and valid. No reader needs to double-check; no request needs a "is this file done?" flag. "It's there" and "it's good" become the same fact. That's the payoff of validate-then-rename: you move the entire question of correctness to before the file is visible at all.

Code

Temp file, validate, atomic rename·python

import os, tempfile

def publish_cache_entry(identity: str, audio_bytes: bytes) -> str:
    final = cache_path(identity)                     # where readers will look

    # 1. Write to a temp file WITH a real media suffix (the validator needs it).
    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(final), suffix=".mp3")
    with os.fdopen(fd, "wb") as f:
        f.write(audio_bytes)

    # 2. VALIDATE: decode it. A truncated or silent file fails HERE, not on play.
    if not is_valid_audio(tmp):
        os.unlink(tmp)
        raise SynthesisInvalid(identity)

    # 3. ATOMIC RENAME: from here on, 'present' means 'complete and valid'.
    os.replace(tmp, final)                           # atomic on the same filesystem
    return final

Exercise

Find a place in a system you know where a reader could observe a half-written file or record — a log being appended, an image being uploaded, a config being rewritten in place. Describe what a reader sees if it arrives mid-write. Then rewrite the flow as write-temp, validate, atomic-rename, and state what 'the file exists' now guarantees.

Hint

The tell is any code that writes directly to the path readers use. If the write and the visibility are the same step, there's a window; the fix is to make visibility a separate, atomic, last step.