j*dZddlmZddlZddlZddlZddlmZddlm Z dZ dZ dZ d Z ejZdddd  dd Zdd Z dd ZddZddZd dZddd d!dZd"dZedd#dZd$dZddd%dZd&dZd'dZy)(uWhat actually went to air, written down while it is still knowable. The as-run — which race was on screen, from when to when — is the one fact about a broadcast that exists **nowhere else**. `OnAirQueue` decides it, in memory, and forgets it; the race plane records that a race was sailed, not that anybody showed it; and the picture itself is not machine-readable. So a recipient asking "cut me race 1009 out of the day's recording" cannot be answered afterwards unless the producer says so at the time. Sibling of `recording_anchor.py`, and deliberately the same shape: an append-only JSONL file written beside the show. That is the cheapest possible thing to add to a live loop — one line, no network, no database, no schema migration — and if it fails it fails alone. **Two race-boundary rows, and the second one is optional.** `on_air` when a race takes the air; `off_air` when the producer drops back to the waiting picture. A race-to-race hand-over emits only `on_air`, because that is what the producer actually does — `take_next` swaps the race in place without releasing — so `segments()` below closes the previous race at the next one's start rather than expecting a matching close. Getting that wrong is how an as-run acquires gaps that were never off air. The same append-only evidence stream also carries `commentary_selected` when one wording variant crosses the producer seam and `commentary_started` when the programme renderer reports that its audio actually began. The separation is intentional: the microphone scheduler can discard a stale selected line. `segments()` ignores these audit rows when building the race partition. Read it back with `segments()`, which turns the rows into the gap-free partition the metadata contract publishes (`docs/broadcast-metadata.md` §4.2). ) annotationsN)Callable)Pathon_airoff_aircommentary_selectedcommentary_started) race_name gun_utc_msleaving_instance_idc`t|tt|||d|dSt||dS)unA race has taken the air. `leaving_instance_id` is the race this one displaced, and only the producer knows it — the queue hands over without either race being told. It is recorded rather than inferred so a reader can tell a hand-over (one race replacing another) from a fresh start after a gap, which look identical once you have only timestamps.N)tUtcMsevent instanceIdraceNamegunUtcMsleavingInstanceId)intON_AIRstr)now_ms instance_idr r r s z_text..~s=RBNN, :BB B B C%CCc|jsgSg}|jdjD]:}|j}|s |j t j |<|S#t j$rYTwxYw)uEvery row written so far. A truncated last line — the run was killed mid-write — is dropped rather than raising, exactly as `recording_anchor.read_samples` does: the file is an append log and its tail is the least valuable part of it.rnro)exists read_text splitlinesr[rrwloadsJSONDecodeError)r|rowslines r read_rowsrs ;;= D0;;=zz|   KK 4( )  K##   s $A44B  B )session_end_msc g}t|dD]}t|jdd|jd}}|tk(rW|r|dd||dd<|j |jd |jd |jd |dd |t k(s|s|dd|dd |jd k(s||dd<||r|ddt||dd<|S) u%The rows as `[{instanceId, raceName, gunUtcMs, fromUtcMs, toUtcMs}]`, in order. `toUtcMs` is EXCLUSIVE and is whichever comes first: an explicit `off_air`, or the next race taking the air. `None` on the last segment means it was still on air when the log ended — which is how "what is playing right now" falls out without a second endpoint. Pass `session_end_ms` to close it at a known end of transmission instead. Rows are sorted by time rather than trusted in file order: the log is appended from one loop so they arrive ordered, but a reader that assumed it would break silently on a concatenated file. An `off_air` for a race that is not the one on air is ignored — it cannot close anything, and treating it as a close would truncate the race that IS on air. c8t|jddS)Nrr)rr))xs rzsegments..sAEE(A,>(?r)keyrrrtoUtcMsNrrr)rrr fromUtcMsr)sortedrr)rrr)rrrbrtrs rsegmentsrsC D? @ 'quuXq)*AEE'N5 F?s2wy)1%&B " JJaeeL&9quuZGX$%EE*$5ARVX Y g s2wy)1c"gl6KquuUaOb6b%&B " '!cc"gi.@.H 0B  Jrc<|rt|jSdS)zEThe configured log path, or None when as-run logging is switched off.N)r expanduser)args r default_pathrs%(49   !2d2rcBttjdzS)Ni)rtimerr_now_msrs tyy{T! ""r) rrrrr str | Noner int | Noner rreturnr;)rrrrrr;) rrrrr rr*float | int | Noner+r;r dict | None)rrr>objectrr)rMr;rr)rMrr\rrr)rMrr9rrIrrr)rMrrr)r| Path | Noner}r;rizCallable[[str], None]rr_)r|rr list[dict])rrrrrr)rrrr)rr)__doc__ __future__rrw threadingrcollections.abcrpathlibrrrr&r<Lockrrrrr-rBr%r'r=r(printrrrrrrrrrs6#  $  +) y~~ JN(,PT 6% 6CM 6Y] 6U (:HLQ\&8P6:#'   ,6  ;MR&$@D:3 #r