Module summary 

What a hook needs to decide, folded from the outcome log once and cached, so no check parses the whole log: every graded apply with its route and what became of it, the delivery tallies, the pool’s yield and latency, the gate’s ledger, the monitor, the checks whose learned decision fell back to the fixed rule, the randomised question-count test’s checks, and the fit (select/policy.rs).

The cache <store>/select-summary.json sits beside the lessons file, local and never synced. load reads it and folds only the log’s new tail (from at); a missing, corrupt or older cache, or a log shorter than at (rewritten), is rebuilt from the whole log in memory; peek (an early or PostToolUse hook) never rebuilds: the prior instead. Neither writes: refresh (the live check and the stop) loads and saves what it folded, and refit (borg learn) fits and saves. Any error is the prior, never a panic in a hook.

The fold is pure over an append-only log: fold of a prefix, then of the rest, equals fold of the whole at every line boundary, and only whole lines fold (a line being written waits). A result joins the check that decided it by check id (outcome.rs check); a record from before check ids by the session’s last graded check before it that graded the lesson on the route its channel names, as attention.rs labels joins. A later verdict for the same check and lesson supersedes an earlier one and a censored mark, so nothing counts twice. Kinds it does not use skip serde: the kind is read off the line’s head first (12,577 regretted lines from one session cost a substring each).

Session ticks: a session’s tick is its place in the order sessions first appear in the folded log (memory.rs Clock’s idea, in line order so the fold stays incremental); ages are in ticks, never in wall time.

Session ends: a session’s delivery tallies (Session::tally) count at its end, whatever it logged: its end hook’s ended record (outcome.rs ENDED) or the never_delivered deliveries before it, or a settle (asked_not_corrected, which borg learn also writes for a session idle without its end hook). A delivery recorded after that (a resumed session) moves its apply’s count, so the tallies follow the latest record.

What a session had: a lesson shown to a session (asked, handed over free or delivered early; a placebo is judged, never shown) is in its Session::had from that delivery on in line order, or in Summary::fresh until a first graded check or settle gives the session a tick. An apply of a lesson its session had before its check (Apply::had: the record’s nofree, the hook’s view, or that set, the log’s) counts in no delivery tally, whose rates are those of a lesson the session lacks (select/policy.rs Rates): delivery drops a free one as given before, and a question once its lesson is done (hook.rs done_in: asked, or handed over and acted on, as the drone may before the question reaches it), drops that say nothing of whether a lesson the session lacks arrives. A lesson waiting in the session’s queue from another check is in the record’s nofree too, which delivery would drop as queued twice. A question of one handed over and not acted on is delivered and judged as any other: its verdict counts (top.rs label health), its delivery stays out of the tallies with the drops. Before 0.6.0 such an apply of a free lesson counted as undelivered and a question as delivered, so the learned free rate read low against asking.

The tail: a graded record’s tail holds lessons the pool’s budget dropped that a uniform sample showed the model anyway, each with the chance pt, and its fill holds, after the applies’ positions, each tail lesson’s position: shown plus its place among the dropped lessons in the fill order (whole.rs select_filled), where a budget that held them would have put it (tail_of). Each counts in the pool’s yield bins at its position as a shown lesson, applied when it is one of the applies, so the yield is learned past the budget. Unweighted: a uniform sample’s lesson at a position is one draw of that position’s yield, and a 1/pt weight would count it as 1/pt lessons, overstating the yield’s certainty. A bin the budget splits holds all its positions below the budget and a pt share of those above, so its yield leans to its lower positions.

Compaction bounds the cache: past MAX_APPLIES the oldest checks go, past MAX_SESSIONS the oldest sessions with their checks, and with either the sessions before the first kept check’s, but never one of the newest policy::FIT_SESSIONS (the sessions a fit reads). What the dropped sessions’ readers need stays in Past, and the kept ones’ ticks shift down by as many, so every age stays as it was. A session that logs again after its drop starts a new one.

The question-count test (select/policy.rs choose, rules v2): a graded record of the learned policy that logs k (outcome.rs xk) was considered by the test, and one that also logs s (xs) drew its count: played (source EXPERIMENT, or EXPERIMENT_CONTROL when s is the fixed rule’s own count), or refused by the gate (GATE), which then plays the fixed rule. Every drawn check is one of the test’s randomised checks: its routes, as played, and its propensities, over the k + 1 equally likely counts with the refused ones’ routes the fixed rule’s, are what the draw made them, so the readout reads refused draws too. The fold counts them all-time by k and s (Summary::experiment, which compaction keeps) and marks a drawn one’s check (Check::xk, xs), whose applies hold the verdicts of what it asked and handed over: what the readout reads (select/replay.rs test_readout), never a recount of the log. A record whose k or s cannot be its own (no s, s past k, k past its applies) counts nowhere. Like every learned check, a drawn one is on the gate’s ledger.

Structs

Apply

One graded apply: its lesson, grade and rank, the route its check decided with its propensities (logged p, pf; psi a placebo’s chance of the draw), and what came of it.

Check

One graded check with applies.

Early

Early deliveries the judge gave a verdict, and those that changed the work: shown; a learned early rule waits for each delivery’s relative score in the log (conscience.rs RELATIVE).

Experiment

The randomised question-count test’s checks (module doc), all-time: per (k, s) the checks the test ran, each having drawn count s of k, played or refused, sorted (ran); of them the control arm’s (EXPERIMENT_CONTROL: s the fixed rule’s own count) and, per k, those the gate refused (GATE), sorted, each also in ran; the sessions with a drawn check. What borg top and the readout count (select/replay.rs test_readout), never a recount of the log.

Fresh

What a session not in the table yet was shown (Summary::fresh), until its first graded check or settle makes it its Session::had; seq, the log offset after its first delivery, orders the guard’s drops (MAX_FRESH).

Gate

The conservative gate’s ledger over the learned policy’s checks under the current fit (select/policy.rs ledger_add_without): per joint draw, the replayed value of what the policy did minus the fixed rule’s for the lessons its session had (A); α × the fixed rule’s replayed value (B). A deviation passes while A + its own gain stays ≥ −B at the DELTA quantile. B is quality (mistakes avoided), not money.

Past

What compaction took off the session table (module doc), as the totals its readers need: those of the dropped sessions with graded checks and their checks (Summary::checked), and their delivery tallies as (delivered, not) per half-life of policy::HALF_LIVES (same order), each session’s weighted by its age at the first kept session (Summary::tallies ages them on from there).

Pool

The pool’s evidence: per log2 bin of fill position (positions 2^b − 1 to 2^(b+1) − 2), lessons shown and applied; tokens and lessons shown in all; the model calls’ (tokens, ms); and per harness, its stops’ model calls (ms, failed), what borg top shows against the harness’s stop budget (top.rs Latency).

Session

One session, in tick order.

Signals

Signals beside the judge, counted before (Summary::signals[0]) and after ([1]) the first check of the learned policy: sessions, corrections, vetoes, regrets, green test runs.

Spent

What the checks’ model calls spent, per channel (STOP, LIVE): calls, the extra rounds a stop’s block cost its session, and dollars as the CLIs reported them (outcome.rs usd; 0 before 0.6.0). Measured and shown, never a limit.

Summary

The selection state of one store (module doc).

Enums

Delivered

What delivery did with a decided apply (outcome.rs delivery, or an older asked record).

Label

What the judge made of an apply.

Constants

ASK_LIVE

CACHE

The cache beside the lessons file. Protocol.

FELL_BACK

Why a graded check’s learned decision fell back to the fixed rule, as its record’s reason names it (outcome.rs DECIDED_BUSY, DECIDED_NO_LOCK, DECIDED_NO_RECORD). Protocol: the indices of Summary::fell_back, part of the cache’s layout (SV).

FREE_LIVE

FREE_STOP

The delivery tallies of a session, (applies, delivered), counted when it ends (counted): a stop’s free lessons, a live check’s, a live check’s lessons left for later, and of a live check with a 3 its questions waiting for the stop and its questions delivered. Protocol: the indices of Session::tally, part of the cache’s layout (SV).

LATENCY_KEEP

Model calls whose latency the summary keeps, the newest: of all, and of each harness’s stops (Pool::stops). Guard: bounds the cache, which a long-lived store’s calls would grow without end.

LATER

LIVE

MAX_APPLIES

Graded applies a summary keeps at most. Guard: bounds the cache a hook reads; past it the oldest checks holding a quarter of them go (Summary::dropped counts their applies), whose labels the forgetting already weighs least.

MAX_FRESH

Sessions not in the table yet whose deliveries a summary keeps (Summary::fresh). Guard: bounds the cache against sessions shown lessons (an early delivery at a prompt) that never reach a graded check, which no other bound counts; far more than run at once, about 0.1 MB. Past it the oldest quarter go, and one of them graded after all counts its applies of lessons it had as a session without them.

MAX_SESSIONS

Sessions a summary keeps at most. Guard: bounds the session table, which MAX_APPLIES does not when sessions grade few applies (a session is about 100 bytes of cache, so 4,096 are 0.4 MB against the applies’ 5 MB); past it the oldest quarter go, with their checks, into Past.

REVERTED

The monitor’s auto-revert mark beside the lessons file: while it exists the store keeps the fixed rule, whatever the cache holds (sticky: removing it is the engineer’s call, and resumes learning until the monitor trips again). Protocol.

STOP

Summary::spend’s channels. Protocol: its indices, part of the cache’s layout (SV).

SV

The cache’s format. Protocol: a summary of another version is rebuilt, never read (2: spend; 3: Pool::stops, the monitor’s weights; 4: Past, LATER a live check’s, tallies at ENDED; 5: ASK_LIVE, what a session had (Session::had, Apply::had, Apply::nofree, Summary::fresh), tail yields and counts; 6: Summary::fell_back; 7: the question-count test, Summary::experiment, Check::xk, xs, Session::tested; 8: a stop’s results on a live check’s hand-overs it asked (stop_routes), a live question of a check without a 3 out of ASK_LIVE and WAIT, counted).

TALLIES

How many delivery tallies a session keeps, FREE_STOP to ASK_LIVE. Protocol: the width of Session::tally and Past::tally, part of the cache’s layout (SV).

WAIT

Functions

cache_path

The cache of the store whose lessons file is lessons.

fold

from with the outcome lines of text (appended after from.at) folded in; a last line without its newline is left for the next fold.

load

The summary of the store whose lessons file is lessons (module doc): the cache with the log’s new tail folded in, rebuilt in memory when it cannot be resumed. Never writes.

peek

load without a rebuild, for a hook that must stay cheap (an early delivery, PostToolUse): the prior when the cache cannot be resumed.

rebuild

The summary from the whole outcome log beside lessons (borg debug select --rebuild, a cache that cannot be resumed), folded from the prior: no fit.

refit

borg learn: the summary beside lessons refitted (with_fit, the collective’s budget from its config, select.rs budget_of), its revert mark written when the monitor tripped, and the cache saved.

refresh

The live check’s and the stop’s load: the summary, saved when it holds more than the cache did (a fold of a new tail, a rebuild). A failed save costs the next hook the same fold, nothing else.

reverted_path

The auto-revert mark of that store.

save

Writes s as the cache beside lessons: a temp file, then a rename, so a reader never sees half.

with_fit

s refitted (select/policy.rs fit) under an engineer’s budget (pool tokens per session), with the gate’s ledger replayed under the new fit and the monitor read; a revert stays.