Module stale_overlay 

STALE_OVERLAY pre-write policy.

When locks release at dk_submit (under DKOD_RELEASE_ON_SUBMIT=1), a waiting session can acquire a contested symbol seconds after the holder submits — far sooner than the old “locks release at merge” window. The recovery contract tells agents to re-read the file before writing, but if they skip that step their overlay is still pinned to base_commit and they will silently clobber the submitted (but not-yet-merged) overlay from the other session.

This module is the engine-side backstop. It is deliberately pure so it can be unit-tested without Postgres; the live handler is a thin wrapper around a ChangesetStore query and a call into is_stale.

Structs

CompetingChangeset

Minimal view of a submitted-but-not-merged changeset that touched the same file path as the write we’re about to perform.

Constants

LIVE_STATES

States treated as “live” — a changeset in any of these states may still affect an overlay this write is about to clobber.

Functions

is_stale

Return the first competitor that makes the session’s local view of the file stale, or None if the session is safe to write.