Module auto_push_record 

The per-branch last-pushed record: validation, tolerant reads and atomic publication. What: The per-branch last-pushed record that single-flight auto-push coordinates through. Why: The incumbent (src/auto-push-record.ts) and this wrapper must read each other’s records, because a commit waiting on a push made by the other wrapper decides from the same file. The record is a cache: an absent or unreadable record only costs an extra push, so only a read failure other than “absent” stops the caller.

In TS you’d write (pseudocode):

readLastPushedRecord(recordPath): Promise<LastPushedRecord | typeof LAST_PUSHED_ABSENT>;
writeLastPushedRecord({ recordPath, record }): Promise<void>;

Structs

LastPushedRecord

What: The most recent push attempt for one branch. Why: owner_token tells a waiting commit whether a push finished after it first read the record; output is the complete text of a failed push, which every joined commit surfaces.

Enums

LastPushedOutcome

What: Outcome of one recorded push attempt. Why: Only pushed and failed exist in the incumbent’s record.

LastPushedRead

What: What reading a branch’s record found. Why: Absence and an unreadable record both mean “no attempt”; they differ only in the diagnostic.

Constants

LAST_PUSHED_SCHEMA_VERSION

Record schema version the incumbent writes and reads.

LAST_PUSHED_SUFFIX

Record file name suffix after the encoded branch key.

Functions

encode_last_pushed_record

What: Serialize a record in the incumbent’s JSON.stringify key order, with its trailing newline. Why: The incumbent and this wrapper write the same bytes for the same record.

parse_last_pushed_record

What: Parse and validate record text. Option<A> is “a value or nothing”. Why: Every field the incumbent checks is checked, so a malformed record never drives a join.

read_last_pushed_record

What: Read a branch’s record, treating an absent or unreadable one as “no attempt”. Why: A missing file is the normal first push; any other read failure (permission denied, a directory in its place) must stop the caller, and a record that fails validation is replaced by the next push.

write_last_pushed_record

What: Publish a branch’s record by rename, so readers never see a partial record. Why: The candidate is written exclusively with mode 0600 beside the record and renamed over it; a failed publication removes the candidate and returns the error.