Skip to content

livery.workshop._balance

livery.workshop._balance

Predict each check platform's wall at one to several shards, and propose the counts.

The reader behind fm ci.balance. It reads the timing rows the gate job writes (livery.workshop._metrics) per platform: the os and Python of a check job's display name, check (macos-latest, 3.14); check (macos-latest, 3.14, 2of4) is one shard of that platform, and a GitLab job's bare name reads its platform from the row's own leg label. Per platform it takes the newest ten rows whose jobs for it all ran the full gate and succeeded, folds the shards of one platform into one, and takes the medians of four measures:

  • F, the fixed setup: every step the forge timed except the Check call, from the first shard, in seconds.
  • O, the summed wall of the gate's steps that are not test steps, from the first shard. The gate's steps are the job's check/<phase>.<step> tasks, and the test steps are the test phase's, livery.workshop._metrics.TEST_PHASE.
  • S, the summed test time over every package and every shard.
  • p, the measured parallelism: a shard's S over its test steps' wall, the median over shards.

The wall at n shards is predicted as F + max(O, (S / p + O) / n). The first shard runs the unsplit steps, and its tests wait about their summed wall, so the partition starts the first shard's slice O p item seconds in (livery.workshop._metrics.first_shard_head): the S + O p item seconds split evenly over the n shards, and no count brings a platform under F + O, the first shard with no tests left. The runner seconds at n are about n F + S / p + O. The slowest platform, the one with the largest wall at one shard, takes the largest count within the cap whose every added shard saved at least F, so a shard that costs more setup than it saves is not proposed. Every other platform takes the smallest count whose wall is within livery.workshop._balance.TOLERANCE of the slowest platform's at its count; one that cannot get there at the cap takes the cap and is named. The pull request counts apply the same rule over a pull request's runners when they are fewer than [ci] runners names. A platform with fewer than livery.workshop._balance.ROWS_NEEDED readable rows keeps its count and takes no part. The cap is [ci] shards-max, which the verb reads and never writes.

The verb prints the table and the TOML the contract would hold. With --write it rewrites [ci] shards, and [ci] pull-request-shards when the pull request runners are fewer, in the root workshop.toml, keeping every comment and every other key: when a count differs from the contract's and the predicted wall at the proposed counts differs from the wall at the contract's by more than livery.workshop._balance.HYSTERESIS, so a count does not move back and forth between two readings that predict about the same wall. With --submit the change lands on the day's branch, chore/balance-<date>, rendered, committed and submitted unarmed for a person to merge; the nightly runs that once a day. The constants here were chosen before the rows could set them, as the speed marks' margins were (livery.workshop._speed).

Reach for render for what the verb prints, read for the same with the counts a write judges, judge for the write's decision, write and submit for the two acts, readings for the measures from rows already in hand, wall and runner_seconds for the prediction, and propose for the counts.

Classes:

Name Description
Reading

One platform's measures, medians over its readable rows.

Proposal

The counts a set of readings proposes.

Counts

One key's count per runner: the contract's, the proposal's, and both walls.

Balance

One reading of the record: the verb's lines and the counts a write judges.

Verdict

A write's decision on a Balance: the tables for the contract, or why none.

Functions:

Name Description
wall

The leg's predicted wall at shards, in seconds: F + max(O, (S / p + O) / n).

runner_seconds

About what shards runners spend together, in seconds: n F + S / p + O.

propose

The counts for readings within cap; a platform short of rows takes no part.

readings

Each platform's reading from rows, newest first; the platforms in name order.

spell

table as the contract spells an inline table; none when empty.

report

The lines the verb prints below the window line: the tables, then the proposal.

counts

One key's counts over runners: current, the proposal, and both walls.

read

Read the record and the contract: what fm ci.balance prints, and the counts.

render

What fm ci.balance prints: the window, the tables, the proposal.

judge

Decide what a write puts in the contract for balance, or why nothing.

holds_key

Whether text's [ci] table spells key as one of its own keys.

rewrite

text with [ci] <key> at table, every other line kept as written.

write

Rewrite the contract's counts when judge says to; the tables written, or None.

on_default_branch

Whether HEAD is on the history of origin's default branch.

submit

Land a due change on the day's branch and open its pull request, never armed.

Attributes:

Name Type Description
CALL_STEP
ROWS_READ
ROWS_NEEDED
TOLERANCE
HYSTERESIS
COMMENTS

CALL_STEP module-attribute

CALL_STEP = 'Check'

ROWS_READ module-attribute

ROWS_READ = 10

ROWS_NEEDED module-attribute

ROWS_NEEDED = 3

TOLERANCE module-attribute

TOLERANCE = 0.15

HYSTERESIS module-attribute

HYSTERESIS = 0.1

COMMENTS module-attribute

COMMENTS = {'shards': "# The shards each runner's check leg runs as; fm ci.balance --write sets them.", 'pull-request-shards': "# The shards a pull request's check legs run as; fm ci.balance --write sets them."}

Reading dataclass

Reading(os: str, python: str, seen: int, rows: int, fixed: float, other: float, tests: float, speed: float)

One platform's measures, medians over its readable rows.

Attributes:

Name Type Description
os str

The runner label (macos-latest).

python str

The leg's Python (3.14).

seen int

The full green rows the platform had among the newest livery.workshop._balance.ROWS_READ read.

rows int

Those among them that carry the test steps' wall in every shard; the medians are over these.

fixed float

F, the setup and teardown the forge timed around the call, in seconds.

other float

O, the summed wall of the gate steps that are not test steps, in seconds; zero when the rows name none.

tests float

S, the summed test time over every package and shard, in seconds.

speed float

p, the measured parallelism: a shard's S over its test steps' wall, the median over shards.

os instance-attribute

os: str

python instance-attribute

python: str

seen instance-attribute

seen: int

rows instance-attribute

rows: int

fixed instance-attribute

fixed: float

other instance-attribute

other: float

tests instance-attribute

tests: float

speed instance-attribute

speed: float

platform property

platform: str

The platform as the table names it: macos-latest, 3.14.

enough property

enough: bool

Whether the platform has the rows a proposal needs.

Proposal dataclass

Proposal(counts: dict[str, int], slowest: str = '', wall: float = 0.0, unsharded: float = 0.0, capped: tuple[str, ...] = ())

The counts a set of readings proposes.

Attributes:

Name Type Description
counts dict[str, int]

The count per runner label, one entry per runner with enough rows; a runner with two Pythons takes the larger.

slowest str

The slowest platform, as the table names it; empty when no platform had enough rows.

wall float

The slowest platform's predicted wall at its count, in seconds.

unsharded float

Its predicted wall at one shard.

capped tuple[str, ...]

The platforms that took the cap without reaching the tolerance, as the table names them.

counts instance-attribute

counts: dict[str, int]

slowest class-attribute instance-attribute

slowest: str = ''

wall class-attribute instance-attribute

wall: float = 0.0

unsharded class-attribute instance-attribute

unsharded: float = 0.0

capped class-attribute instance-attribute

capped: tuple[str, ...] = ()

Counts dataclass

Counts(key: str, runners: tuple[str, ...], current: dict[str, int], proposed: dict[str, int], before: float, after: float)

One key's count per runner: the contract's, the proposal's, and both walls.

Attributes:

Name Type Description
key str

shards or pull-request-shards.

runners tuple[str, ...]

The runners the key covers, in the contract's order.

current dict[str, int]

The count per runner the contract gives, one where it is silent.

proposed dict[str, int]

The count per runner the proposal gives; a runner whose platform keeps its count has its current one.

before float

The predicted wall of the slowest leg at the current counts, in seconds, over the platforms with enough rows.

after float

The same at the proposed counts.

key instance-attribute

key: str

runners instance-attribute

runners: tuple[str, ...]

current instance-attribute

current: dict[str, int]

proposed instance-attribute

proposed: dict[str, int]

before instance-attribute

before: float

after instance-attribute

after: float

changed property

changed: bool

Whether a count differs between the proposal and the contract.

moved property

moved: bool

Whether the wall moves by more than the hysteresis between the two.

table property

table: dict[str, int]

The proposed counts as the contract holds them: those above one, in order.

held property

held: dict[str, int]

The current counts as the contract holds them.

Balance dataclass

Balance(lines: list[str], shards: Counts | None = None, pull_request: Counts | None = None, reason: str = '')

One reading of the record: the verb's lines and the counts a write judges.

Attributes:

Name Type Description
lines list[str]

The window line, the tables and the proposal, as render prints them.

shards Counts | None

The counts of [ci] shards over [ci] runners; None when the record proposed nothing, and reason says why.

pull_request Counts | None

The counts of [ci] pull-request-shards over [ci] pull-request-runners when that list is shorter than [ci] runners; None otherwise, and a write leaves the key as it is.

reason str

Why the record proposed nothing; empty when it did.

lines instance-attribute

lines: list[str]

shards class-attribute instance-attribute

shards: Counts | None = None

pull_request class-attribute instance-attribute

pull_request: Counts | None = None

reason class-attribute instance-attribute

reason: str = ''

Verdict dataclass

Verdict(tables: dict[str, dict[str, int]] | None, why: str = '', what: str = '', before: float = 0.0, after: float = 0.0)

A write's decision on a Balance: the tables for the contract, or why none.

Attributes:

Name Type Description
tables dict[str, dict[str, int]] | None

The table per key the write puts in the contract, an empty one removing the key; None when nothing is written.

why str

Why nothing is written; empty when something is.

what str

The wall the decision read, run or pull request.

before float

That wall at the contract's counts, in seconds.

after float

That wall at the proposed counts.

tables instance-attribute

tables: dict[str, dict[str, int]] | None

why class-attribute instance-attribute

why: str = ''

what class-attribute instance-attribute

what: str = ''

before class-attribute instance-attribute

before: float = 0.0

after class-attribute instance-attribute

after: float = 0.0

wall

wall(reading: Reading, shards: int) -> float

The leg's predicted wall at shards, in seconds: F + max(O, (S / p + O) / n).

Source code in packages/workshop/src/livery/workshop/_balance.py
def wall(reading: Reading, shards: int) -> float:
    """The leg's predicted wall at *shards*, in seconds: F + max(O, (S / p + O) / n)."""
    spread = (reading.tests / reading.speed + reading.other) / shards
    return reading.fixed + max(reading.other, spread)

runner_seconds

runner_seconds(reading: Reading, shards: int) -> float

About what shards runners spend together, in seconds: n F + S / p + O.

Source code in packages/workshop/src/livery/workshop/_balance.py
def runner_seconds(reading: Reading, shards: int) -> float:
    """About what *shards* runners spend together, in seconds: n F + S / p + O."""
    return shards * reading.fixed + reading.tests / reading.speed + reading.other

propose

propose(readings: Sequence[Reading], *, cap: int) -> Proposal

The counts for readings within cap; a platform short of rows takes no part.

The slowest platform's count stops at the first added shard that saves less than its setup. Every other platform takes the smallest count within the tolerance of the slowest platform's wall, or the cap, named in capped.

Source code in packages/workshop/src/livery/workshop/_balance.py
def propose(readings: Sequence[Reading], *, cap: int) -> Proposal:
    """The counts for *readings* within *cap*; a platform short of rows takes no part.

    The slowest platform's count stops at the first added shard that
    saves less than its setup. Every other platform takes the smallest
    count within the tolerance of the slowest platform's wall, or the
    cap, named in ``capped``.
    """
    cap = max(1, cap)
    able = [reading for reading in readings if reading.enough]
    if not able:
        return Proposal({})
    slowest = max(able, key=_unsharded)
    count = 1
    while (
        count < cap and wall(slowest, count) - wall(slowest, count + 1) >= slowest.fixed
    ):
        count += 1
    target = wall(slowest, count) * (1 + TOLERANCE)
    counts: dict[str, int] = {}
    capped: list[str] = []
    for reading in able:
        if reading is slowest:
            chosen = count
        else:
            chosen = next(
                (n for n in range(1, cap + 1) if wall(reading, n) <= target), cap
            )
            if wall(reading, chosen) > target:
                capped.append(reading.platform)
        counts[reading.os] = max(counts.get(reading.os, 0), chosen)
    return Proposal(
        counts, slowest.platform, wall(slowest, count), wall(slowest, 1), tuple(capped)
    )

readings

readings(rows: Sequence[Mapping[str, Any]]) -> list[Reading]

Each platform's reading from rows, newest first; the platforms in name order.

A row counts for a platform when every job of that platform in it ran the full gate and succeeded, and the newest livery.workshop._balance.ROWS_READ such rows are read. Among them, a row whose shard carries no test step's wall is seen and not read. A job that is not a check leg is skipped.

Source code in packages/workshop/src/livery/workshop/_balance.py
def readings(rows: Sequence[Mapping[str, Any]]) -> list[Reading]:
    """Each platform's reading from *rows*, newest first; the platforms in name order.

    A row counts for a platform when every job of that platform in it
    ran the full gate and succeeded, and the newest
    [livery.workshop._balance.ROWS_READ][] such rows are read. Among
    them, a row whose shard carries no test step's wall is seen and
    not read. A job that is not a check leg is skipped.
    """
    seen: dict[tuple[str, str], int] = defaultdict(int)
    measures: dict[tuple[str, str], list[_Measures]] = defaultdict(list)
    for row in rows:
        jobs = row.get("jobs")
        if not isinstance(jobs, Mapping):
            continue
        by_platform: dict[tuple[str, str], list[tuple[int, Mapping[str, Any]]]] = (
            defaultdict(list)
        )
        for name, job in jobs.items():
            if not isinstance(job, Mapping):
                continue
            found = _platform(str(name), job)
            if found is not None:
                by_platform[found[:2]].append((found[2], job))
        for key, shards in by_platform.items():
            if seen[key] >= ROWS_READ:
                continue
            shards.sort(key=itemgetter(0))
            if not all(_full_green(job) for _, job in shards):
                continue
            seen[key] += 1
            measured = _measure([job for _, job in shards])
            if measured is not None:
                measures[key].append(measured)
    out: list[Reading] = []
    for key in sorted(seen):
        taken = measures.get(key, [])
        out.append(
            Reading(
                key[0],
                key[1],
                seen[key],
                len(taken),
                fixed=statistics.median([m.fixed for m in taken]) if taken else 0.0,
                other=statistics.median([m.other for m in taken]) if taken else 0.0,
                tests=statistics.median([m.tests for m in taken]) if taken else 0.0,
                speed=statistics.median([m.speed for m in taken]) if taken else 0.0,
            )
        )
    return out

spell

spell(table: Mapping[str, int]) -> str

table as the contract spells an inline table; none when empty.

Source code in packages/workshop/src/livery/workshop/_balance.py
def spell(table: Mapping[str, int]) -> str:
    """*table* as the contract spells an inline table; ``none`` when empty."""
    if not table:
        return "none"
    return "{ " + ", ".join(f'"{runner}" = {n}' for runner, n in table.items()) + " }"

report

report(readings: Sequence[Reading], *, cap: int, runners: Sequence[str], pull_request_runners: Sequence[str] | None = None) -> list[str]

The lines the verb prints below the window line: the tables, then the proposal.

Every reading gets its table or its reason; a runner in runners without a reading keeps its count and says so. The proposal is over the readings of runners; the pull request proposal over pull_request_runners when that list is shorter, else the counts are the same and say so.

Source code in packages/workshop/src/livery/workshop/_balance.py
def report(
    readings: Sequence[Reading],
    *,
    cap: int,
    runners: Sequence[str],
    pull_request_runners: Sequence[str] | None = None,
) -> list[str]:
    """The lines the verb prints below the window line: the tables, then the proposal.

    Every reading gets its table or its reason; a runner in *runners*
    without a reading keeps its count and says so. The proposal is
    over the readings of *runners*; the pull request proposal over
    *pull_request_runners* when that list is shorter, else the counts
    are the same and say so.
    """
    cap = max(1, cap)
    lines: list[str] = []
    for reading in readings:
        lines.extend(_platform_lines(reading, cap))
    present = {reading.os for reading in readings}
    lines.extend(
        f"  {runner}: keeps its count: 0 full green row(s), {ROWS_NEEDED} needed"
        for runner in runners
        if runner not in present
    )
    full = propose([r for r in readings if r.os in runners], cap=cap)
    lines.extend(_named_capped(readings, full, cap))
    lines.append(_toml_line("shards", full, runners))
    narrower = pull_request_runners is not None and len(pull_request_runners) < len(
        runners
    )
    pulls = (
        propose([r for r in readings if r.os in (pull_request_runners or ())], cap=cap)
        if narrower
        else None
    )
    if pulls is not None:
        lines.extend(_named_capped(readings, pulls, cap))
        lines.append(
            _toml_line("pull-request-shards", pulls, pull_request_runners or ())
        )
    elif full.counts:
        lines.append("  [ci] pull-request-shards: the same")
    lines.extend(_wall_line("run", full))
    if pulls is not None:
        lines.extend(_wall_line("pull request", pulls))
    return lines

counts

counts(readings: Sequence[Reading], *, key: str, runners: Sequence[str], current: Mapping[str, int], cap: int) -> Counts

One key's counts over runners: current, the proposal, and both walls.

A runner whose platform has too few rows keeps its current count. The walls are the slowest leg's among the platforms with enough rows, at the current counts and at the proposed ones.

Source code in packages/workshop/src/livery/workshop/_balance.py
def counts(
    readings: Sequence[Reading],
    *,
    key: str,
    runners: Sequence[str],
    current: Mapping[str, int],
    cap: int,
) -> Counts:
    """One key's counts over *runners*: *current*, the proposal, and both walls.

    A runner whose platform has too few rows keeps its current count.
    The walls are the slowest leg's among the platforms with enough
    rows, at the current counts and at the proposed ones.
    """
    proposal = propose([r for r in readings if r.os in runners], cap=cap)
    proposed = {
        runner: proposal.counts.get(runner, current[runner]) for runner in runners
    }
    able = [r for r in readings if r.os in runners and r.enough]
    return Counts(
        key,
        tuple(runners),
        dict(current),
        proposed,
        max((wall(r, current[r.os]) for r in able), default=0.0),
        max((wall(r, proposed[r.os]) for r in able), default=0.0),
    )

read

read(root: Path, *, cap: int = 0) -> Balance

Read the record and the contract: what fm ci.balance prints, and the counts.

Reads the metrics series and the root contract's [ci] runners, [ci] pull-request-runners, [ci] shards, [ci] pull-request-shards and [ci] shards-max. cap is --max, zero for the contract's cap. An unreadable series prints its reason and proposes nothing; an empty one says so.

Source code in packages/workshop/src/livery/workshop/_balance.py
def read(root: Path, *, cap: int = 0) -> Balance:
    """Read the record and the contract: what ``fm ci.balance`` prints, and the counts.

    Reads the metrics series and the root contract's ``[ci] runners``,
    ``[ci] pull-request-runners``, ``[ci] shards``, ``[ci]
    pull-request-shards`` and ``[ci] shards-max``. *cap* is ``--max``,
    zero for the contract's cap. An unreadable series prints its reason
    and proposes nothing; an empty one says so.
    """
    found = SERIES.rows(state_store(root))
    if found.failed:
        return Balance(
            [f"  {found.reason}", "  nothing proposed: the record could not be read"],
            reason="the record could not be read",
        )
    entries = [row.data for row in found.rows]
    if not entries:
        return Balance(
            [
                "  no timing rows yet: the gate job writes one per run",
                "  nothing proposed: the record holds no row",
            ],
            reason="the record holds no row",
        )
    lines = [f"  {line}" for line in found.skipped]
    lines.append(
        f"  {len(entries)} run(s) in the window, {_day(entries[-1])} to"
        f" {_day(entries[0])}; the newest {ROWS_READ} full green row(s) per platform"
        " are read"
    )
    ci = load_contract(root / "workshop.toml").get("ci") or {}
    runners = [str(runner) for runner in ci.get("runners") or ["ubuntu-latest"]]
    pulls = pull_request_runners(ci)
    cap = _cap(ci, cap)
    measured = readings(entries)
    lines.extend(report(measured, cap=cap, runners=runners, pull_request_runners=pulls))
    if not any(r.enough and r.os in runners for r in measured):
        return Balance(
            lines,
            reason=(
                f"no platform has {ROWS_NEEDED} full green rows with the test"
                " steps' wall"
            ),
        )
    current = shard_counts(ci, key="shards", runners=runners, listed="[ci] runners")
    shards = counts(measured, key="shards", runners=runners, current=current, cap=cap)
    pull_request = None
    if len(pulls) < len(runners):
        if ci.get("pull-request-shards") is None:
            held = {runner: current[runner] for runner in pulls}
        else:
            held = shard_counts(
                ci,
                key="pull-request-shards",
                runners=pulls,
                listed="[ci] pull-request-runners",
            )
        pull_request = counts(
            measured, key="pull-request-shards", runners=pulls, current=held, cap=cap
        )
    return Balance(lines, shards, pull_request)

render

render(root: Path, *, cap: int = 0) -> list[str]

What fm ci.balance prints: the window, the tables, the proposal.

read with the counts left out; cap means what it means there.

Source code in packages/workshop/src/livery/workshop/_balance.py
def render(root: Path, *, cap: int = 0) -> list[str]:
    """What ``fm ci.balance`` prints: the window, the tables, the proposal.

    `read` with the counts left out; *cap* means what it means there.
    """
    return read(root, cap=cap).lines

judge

judge(balance: Balance) -> Verdict

Decide what a write puts in the contract for balance, or why nothing.

Nothing is written when the record proposed nothing, when every count is the contract's, and when the predicted wall at the proposed counts is within the hysteresis of the wall at the contract's counts. The run wall decides, over [ci] runners; when the run's counts are the contract's and only the pull request's differ, the pull request wall decides. Otherwise the tables are [ci] shards and, when the pull request runners are fewer, [ci] pull-request-shards, both at the proposal.

Source code in packages/workshop/src/livery/workshop/_balance.py
def judge(balance: Balance) -> Verdict:
    """Decide what a write puts in the contract for *balance*, or why nothing.

    Nothing is written when the record proposed nothing, when every
    count is the contract's, and when the predicted wall at the
    proposed counts is within the hysteresis of the wall at the
    contract's counts. The run wall decides, over ``[ci] runners``;
    when the run's counts are the contract's and only the pull
    request's differ, the pull request wall decides. Otherwise the
    tables are ``[ci] shards`` and, when the pull request runners are
    fewer, ``[ci] pull-request-shards``, both at the proposal.
    """
    shards = balance.shards
    if shards is None:
        return Verdict(None, f"nothing written: {balance.reason}")
    pulls = balance.pull_request
    if shards.changed:
        judged, what = shards, "run"
    elif pulls is not None and pulls.changed:
        judged, what = pulls, "pull request"
    else:
        return Verdict(None, "nothing written: every count is the contract's")
    if not judged.moved:
        return Verdict(
            None,
            f"nothing written: the predicted {what} wall moves from"
            f" {judged.before:.0f} s to {judged.after:.0f} s, within"
            f" {round(HYSTERESIS * 100)}%",
        )
    tables = {"shards": shards.table}
    if pulls is not None:
        tables["pull-request-shards"] = pulls.table
    return Verdict(tables, "", what, judged.before, judged.after)

holds_key

holds_key(text: str, key: str) -> bool

Whether text's [ci] table spells key as one of its own keys.

Source code in packages/workshop/src/livery/workshop/_balance.py
def holds_key(text: str, key: str) -> bool:
    """Whether *text*'s ``[ci]`` table spells *key* as one of its own keys."""
    lines = text.split("\n")
    table = _ci_table(lines)
    if table is None:
        return False
    header, end = table
    return any(found.name == key for found in _keys(lines, header + 1, end))

rewrite

rewrite(text: str, key: str, table: Mapping[str, int]) -> str

text with [ci] <key> at table, every other line kept as written.

A key the table holds is rewritten in place as one inline table, its trailing comment kept, however many lines it spanned; an empty table removes the key with the comment lines directly above it, since a comment on a key that is gone misleads. A key the table lacks is added after its last key, under its own comment (livery.workshop._balance.COMMENTS), or under the header when the table has none; a contract without a [ci] table gains one at its end. An absent key with an empty table changes nothing.

Source code in packages/workshop/src/livery/workshop/_balance.py
def rewrite(text: str, key: str, table: Mapping[str, int]) -> str:
    """*text* with ``[ci] <key>`` at *table*, every other line kept as written.

    A key the table holds is rewritten in place as one inline table,
    its trailing comment kept, however many lines it spanned; an
    empty *table* removes the key with the comment lines directly
    above it, since a comment on a key that is gone misleads. A key
    the table lacks is added after its last key, under its own comment
    ([livery.workshop._balance.COMMENTS][]), or under the header when
    the table has none; a contract without a ``[ci]`` table gains one
    at its end. An absent key with an empty *table* changes nothing.
    """
    lines = text.split("\n")
    spelled = f"{key} = {spell(table)}"
    found = _ci_table(lines)
    if found is None:
        if not table:
            return text
        base = text.rstrip("\n")
        return (base + "\n\n" if base else "") + f"[ci]\n{COMMENTS[key]}\n{spelled}\n"
    header, end = found
    keys = _keys(lines, header + 1, end)
    for held in keys:
        if held.name != key:
            continue
        if table:
            after = f"  {held.comment}" if held.comment else ""
            lines[held.first : held.last + 1] = [held.indent + spelled + after]
        else:
            above = held.first
            while above > header + 1 and lines[above - 1].strip().startswith("#"):
                above -= 1
            del lines[above : held.last + 1]
        return "\n".join(lines)
    if not table:
        return text
    if keys:
        indent, at = keys[-1].indent, keys[-1].last + 1
    else:
        indent, at = "", header + 1
    lines[at:at] = [indent + COMMENTS[key], indent + spelled]
    return "\n".join(lines)

write

write(root: Path, balance: Balance) -> dict[str, dict[str, int]] | None

Rewrite the contract's counts when judge says to; the tables written, or None.

Prints what each key becomes and the wall the decision read, or why nothing is written. Refuses by name when a key the contract holds is not spelled as a key of the [ci] table, as a [ci.shards] table or a dotted key: the rewrite keeps the contract's text and cannot reach it there.

Source code in packages/workshop/src/livery/workshop/_balance.py
def write(root: Path, balance: Balance) -> dict[str, dict[str, int]] | None:
    """Rewrite the contract's counts when `judge` says to; the tables written, or None.

    Prints what each key becomes and the wall the decision read, or
    why nothing is written. Refuses by name when a key the contract
    holds is not spelled as a key of the ``[ci]`` table, as a
    ``[ci.shards]`` table or a dotted key: the rewrite keeps the
    contract's text and cannot reach it there.
    """
    verdict = judge(balance)
    if verdict.tables is None:
        print(f"  {verdict.why}")
        return None
    path = root / "workshop.toml"
    text = path.read_text(encoding="utf-8")
    ci = load_contract(path).get("ci") or {}
    for key, table in verdict.tables.items():
        if ci.get(key) is not None and not holds_key(text, key):
            fail(
                f"[ci] {key} is not a key of the [ci] table in {path.name} (a"
                f" [ci.{key}] table, or a dotted key): spell it `{key} = {{ ... }}`"
                " under [ci] for the balancer to rewrite it"
            )
        text = rewrite(text, key, table)
    path.write_text(text, encoding="utf-8")
    for found in (balance.shards, balance.pull_request):
        if found is not None and found.key in verdict.tables:
            print(
                f"  [ci] {found.key}: {spell(found.held)} becomes"
                f" {spell(verdict.tables[found.key])}"
            )
    print(
        f"  the predicted {verdict.what} wall moves from {verdict.before:.0f} s to"
        f" {verdict.after:.0f} s"
    )
    return verdict.tables

on_default_branch

on_default_branch(root: Path) -> bool

Whether HEAD is on the history of origin's default branch.

Origin's default branch is fetched as HEAD, so no branch name is needed and a checkout a merge moved on since still answers; a detached HEAD at a commit of that history answers True.

Raises:

Type Description
Failed

when origin cannot be fetched, in git's words.

Source code in packages/workshop/src/livery/workshop/_balance.py
def on_default_branch(root: Path) -> bool:
    """Whether HEAD is on the history of origin's default branch.

    Origin's default branch is fetched as ``HEAD``, so no branch name
    is needed and a checkout a merge moved on since still answers; a
    detached HEAD at a commit of that history answers True.

    Raises:
        Failed: when origin cannot be fetched, in git's words.
    """
    try:
        git.fetch(root, "HEAD")
    except git.GitError as error:
        fail(f"origin could not be fetched: {error}")
    answer = git.call(root, "merge-base", "--is-ancestor", "HEAD", "FETCH_HEAD")
    if answer.code not in (0, 1):
        said = (answer.stderr or answer.stdout).strip()
        fail(f"git merge-base exited {answer.code}: {said}")
    return answer.code == 0

submit

submit(root: Path, *, cap: int = 0, on: date | None = None) -> None

Land a due change on the day's branch and open its pull request, never armed.

The act, each step printed: off origin's default branch nothing is read or written, the line names the branch, and the verb exits green, so a nightly dispatched on another branch skips it. On it, the record is read and judged as write judges it; nothing due means no branch and no pull request. Otherwise origin is asked for the day's branch, chore/balance-<date>, before anything in the checkout changes: one holding these counts, from an earlier run of the day, means the day's balance is already submitted, and one holding other counts refuses by name, for a person to merge or close its pull request first. Then, from a clean tree, the branch is started in this checkout from a fetched origin/main (livery.workshop._issue_tasks.start_here), the contract is rewritten, the sync renders the workflows at the counts (livery.workshop._sync.sync_checkout), the change is committed as chore(ci): the check legs run as <counts> (livery.workshop._commit.commit_flow) and submitted unarmed (livery.workshop._submit.submit_flow), its gate run there and not twice, and the checkout returns to where it was. on is the day, today when None; cap is --max.

Raises:

Type Description
Failed

naming what stopped it, with nothing written when it stops before the write.

Source code in packages/workshop/src/livery/workshop/_balance.py
def submit(root: Path, *, cap: int = 0, on: date | None = None) -> None:
    """Land a due change on the day's branch and open its pull request, never armed.

    The act, each step printed: off origin's default branch nothing is
    read or written, the line names the branch, and the verb exits
    green, so a nightly dispatched on another branch skips it. On it,
    the record is read and judged as `write` judges it; nothing due
    means no branch and no pull request. Otherwise origin is asked for
    the day's branch, ``chore/balance-<date>``, before anything in the
    checkout changes: one holding these counts, from an earlier run of
    the day, means the day's balance is already submitted, and one
    holding other counts refuses by name, for a person to merge or
    close its pull request first. Then, from a clean tree, the branch
    is started in this checkout from a fetched ``origin/main``
    ([livery.workshop._issue_tasks.start_here][]), the contract is
    rewritten, the sync renders the workflows at the counts
    ([livery.workshop._sync.sync_checkout][]), the change is committed
    as ``chore(ci): the check legs run as <counts>``
    ([livery.workshop._commit.commit_flow][]) and submitted unarmed
    ([livery.workshop._submit.submit_flow][]), its gate run there and
    not twice, and the checkout returns to where it was. *on* is the
    day, today when None; *cap* is ``--max``.

    Raises:
        Failed: naming what stopped it, with nothing written when it
            stops before the write.
    """
    from livery.git import remote_snapshot

    if not on_default_branch(root):
        where = git.current_branch(root) or "(detached)"
        print(
            f"  not on origin's default branch (on {where}): nothing is written or"
            " submitted; the balancer submits from the default branch alone"
        )
        return
    with remote_snapshot(state_store(root), fetch=("metrics",)):
        balance = read(root, cap=cap)
    for line in balance.lines:
        print(line)
    verdict = judge(balance)
    if verdict.tables is None:
        print(f"  {verdict.why}")
        print("  no branch, no pull request")
        return
    day = on or date.today()
    branch = f"chore/balance-{day:%Y%m%d}"
    if _origin_holds(root, branch):
        held = _held(root, branch, verdict.tables)
        if held == verdict.tables:
            print(
                f"  the day's balance is already submitted: {branch} on origin holds"
                " these counts; nothing is written"
            )
            return
        fail(
            f"{branch} on origin holds other counts ({_spell_tables(held)}) than"
            f" this reading proposes ({_spell_tables(verdict.tables)}): merge or"
            " close its pull request, then run the balancer again; nothing is"
            " written"
        )
    if not git.is_clean(root):
        fail(
            "the working tree has uncommitted changes: commit or stash them, then"
            " run the balancer again; nothing is written"
        )
    from livery.workshop._commit import commit_flow
    from livery.workshop._forge_lane import this_repository
    from livery.workshop._issue_tasks import fetch_base, start_here
    from livery.workshop._submit import forge_failures_named, submit_flow
    from livery.workshop._sync import sync_checkout

    came_from = git.current_branch(root) or git.head_sha(root)
    repo = this_repository(root)
    fetch_base(root)
    start_here(root, repo, branch)
    write(root, balance)
    sync_checkout(root)
    subject = _subject(balance, verdict.tables)
    # The submit's gate judges this tree next; a gate at the commit
    # would judge the same tree twice.
    commit_flow(
        root,
        "chore",
        subject,
        scope="ci",
        body=(
            f"the predicted {verdict.what} wall moves from {verdict.before:.0f} s"
            f" to {verdict.after:.0f} s"
        ),
        check=False,
    )
    with forge_failures_named():
        number = submit_flow(
            repo,
            root,
            title=f"chore(ci): {subject}",
            armed=False,
            armed_reason="the balancer, which never arms",
            follow_to_verdict=False,
        )
    print(f"  submitted unarmed: PR #{number} waits for a person")
    if git.local_branch_exists(root, came_from):
        git.switch(root, came_from)
        print(f"  back on {came_from}")
    else:
        git.run(root, "checkout", "--detach", came_from)
        print(f"  back at {came_from[:12]}, detached as before")