Skip to content

livery.workshop._speed

livery.workshop._speed

The test speed marks: a package's suite time per check leg, and how it moves.

The gate job judges each check leg's summed test time per package, the packages field of the timing rows (livery.workshop._metrics), against a mark on the speed/marks series. The mark is the median of the leg's last five green runs for the package, recorded once five are seen; it ratchets down when that median beats it by more than five per cent, so a suite cannot regress slowly, and a person raises it with fm speed.accept, since a new heavy test is a cost someone chose.

A run over the mark by more than fifteen per cent and twenty seconds warns, naming the leg's slowest tests and the ones that grew most against their own medians; the second such run in a row on a reference leg (ubuntu) is red, and the other legs warn only until their variance is measured. A store that cannot be read falls open with its reason and writes nothing. The margins are constants here, chosen before the rows could set them; a reading of a month of rows may move them.

Reach for judge_run to judge the run the gate job is in, accept for the person's raise, render_marks for what fm ci.timings adds, and livery.workshop.speed_marks for the current marks. A test's package, which the speed plugin sums by and the timing rows key by, is what livery.workshop.package_of names.

Classes:

Name Description
SpeedMark

A package's mark on one check leg and the row that set it.

Sample

One package's time on one leg in this run, with the leg's history.

Verdict

One package on one leg, judged against its mark.

Functions:

Name Description
package_of

Name the workspace package a test belongs to, from its pytest node id.

enabled

The contract's [ci] speed-marks; false when undeclared.

drop_marks

Drop the marks series while the marks are off; the lines to print.

leg_label

The leg label of a matrix job's display name; a plain name stands.

display_shard

The shard a job's display name spells; ONE when it spells none.

platform_display

The display name of a shard's platform: display without its shard.

forge_shard_row

Whether job's row is the forge's own row of a shard: no scope, a shard named.

leg_of

The leg a run's job row measured: the row's own label, or the name's.

is_reference

Whether leg runs on the reference runner, the one whose red counts.

speed_marks

Read each package's current test-time mark on each check leg.

write_mark

Append one row setting package's mark on leg; "" or why not.

samples

This run's package times per check leg, with each leg's green history.

judge

Each sample against its mark; one verdict each.

render

The lines for verdict: the time, the mark, the state, the culprits.

judge_run

Judge the run's check legs; the verdicts and the lines for what could not be.

apply

Write the first marks and the ratchets among verdicts; the lines.

accept

Raise package's mark on leg to seconds deliberately; the lines.

render_marks

The marks beside the newest run's times, for fm ci.timings.

Attributes:

Name Type Description
SPEED_FILE_VARIABLE
PACKAGE_TREES
SERIES
SAMPLE
MARGIN
FLOOR_SECONDS
RATCHET
REFERENCE
ENABLED_KEY
SLOWEST
GROWN

SPEED_FILE_VARIABLE module-attribute

SPEED_FILE_VARIABLE = 'WORKSHOP_SPEED_FILE'

PACKAGE_TREES module-attribute

PACKAGE_TREES = frozenset({'tests', 'src', 'docs'})

SERIES module-attribute

SERIES = git.Series('speed/marks', window=400, ci_only=False)

SAMPLE module-attribute

SAMPLE = 5

MARGIN module-attribute

MARGIN = 0.15

FLOOR_SECONDS module-attribute

FLOOR_SECONDS = 20.0

RATCHET module-attribute

RATCHET = 0.05

REFERENCE module-attribute

REFERENCE = 'ubuntu'

ENABLED_KEY module-attribute

ENABLED_KEY = 'speed-marks'

SLOWEST module-attribute

SLOWEST = 10

GROWN module-attribute

GROWN = 5

SpeedMark dataclass

SpeedMark(package: str, leg: str, seconds: float, kind: str, by: str, reason: str, when: str)

A package's mark on one check leg and the row that set it.

The mark is the suite's summed test time the gate job judges the leg's runs against; livery.workshop.speed_marks reads the current mark of each package on each leg.

Attributes:

Name Type Description
package str

The package path (packages/forge).

leg str

The check leg (check-ubuntu-latest-3.14).

seconds float

The mark: the suite's summed test time.

kind str

first (a run recorded it), ratchet (a run moved it down), or accept (a person raised it).

by str

The run or the person that wrote the row.

reason str

The reason an accept gave; empty otherwise.

when str

When the row was written, ISO 8601.

package instance-attribute

package: str

leg instance-attribute

leg: str

seconds instance-attribute

seconds: float

kind instance-attribute

kind: str

by instance-attribute

by: str

reason instance-attribute

reason: str

when instance-attribute

when: str

Sample dataclass

Sample(package: str, leg: str, seconds: float, tests: int, previous: tuple[float, ...], slowest: tuple[tuple[str, float], ...] = (), grown: tuple[tuple[str, float, float], ...] = ())

One package's time on one leg in this run, with the leg's history.

Attributes:

Name Type Description
package str

The package path.

leg str

The check leg.

seconds float

This run's summed test time for the package.

tests int

How many tests ran.

previous tuple[float, ...]

The leg's earlier green runs' times for the package, newest first, at most one fewer than SAMPLE.

slowest tuple[tuple[str, float], ...]

This run's slowest tests, name and seconds, slowest first.

grown tuple[tuple[str, float, float], ...]

The tests that grew most against their median over the earlier runs: name, the median, this run's seconds.

package instance-attribute

package: str

leg instance-attribute

leg: str

seconds instance-attribute

seconds: float

tests instance-attribute

tests: int

previous instance-attribute

previous: tuple[float, ...]

slowest class-attribute instance-attribute

slowest: tuple[tuple[str, float], ...] = ()

grown class-attribute instance-attribute

grown: tuple[tuple[str, float, float], ...] = ()

Verdict dataclass

Verdict(sample: Sample, mark: SpeedMark | None)

One package on one leg, judged against its mark.

Attributes:

Name Type Description
sample Sample

The run's time and the leg's history.

mark SpeedMark | None

The current mark, or None when none is recorded.

sample instance-attribute

sample: Sample

mark instance-attribute

mark: SpeedMark | None

limit property

limit: float | None

The seconds above which a run is over; None without a mark.

over property

over: bool

Whether this run is over the mark by the margin.

previous_over property

previous_over: bool

Whether the leg's newest earlier green run was over too.

red property

red: bool

The second run over in a row, on a reference leg.

median property

median: float | None

The median of the sample, this run included; None short of one.

records property

records: bool

Whether this run records the first mark: no mark, a full sample.

ratchets property

ratchets: bool

Whether the sample's median beats the mark by more than RATCHET.

package_of

package_of(nodeid: str) -> str

Name the workspace package a test belongs to, from its pytest node id.

The package is the path before the first directory a package keeps its tests or sources in, tests, src or docs: packages/forge/tests/test_x.py::test_y belongs to packages/forge. A package in a group directory is one level deeper, and its own name may be one of those three: in packages/extensions/docs/tests/test_x.py::test_y the tests beneath docs says docs is the package, so the answer is packages/extensions/docs. Nothing is read from the disk.

Parameters:

Name Type Description Default
nodeid str

A test's node id, relative to the workspace root.

required

Returns:

Type Description
str

The package's path relative to the workspace root, or "" for

str

a node outside packages/, such as a workspace test under

str

tests/.

Source code in packages/workshop/src/livery/workshop/_speed.py
def package_of(nodeid: str) -> str:
    """Name the workspace package a test belongs to, from its pytest node id.

    The package is the path before the first directory a package keeps
    its tests or sources in, ``tests``, ``src`` or ``docs``:
    ``packages/forge/tests/test_x.py::test_y`` belongs to
    ``packages/forge``. A package in a group directory is one level
    deeper, and its own name may be one of those three: in
    ``packages/extensions/docs/tests/test_x.py::test_y`` the ``tests``
    beneath ``docs`` says ``docs`` is the package, so the answer is
    ``packages/extensions/docs``. Nothing is read from the disk.

    Args:
        nodeid: A test's node id, relative to the workspace root.

    Returns:
        The package's path relative to the workspace root, or ``""`` for
        a node outside ``packages/``, such as a workspace test under
        ``tests/``.
    """
    parts = nodeid.split("::", 1)[0].split("/")
    if len(parts) < 3 or parts[0] != "packages":
        return ""
    for index in range(2, len(parts) - 1):
        if parts[index] not in PACKAGE_TREES:
            continue
        if index == 2 and parts[3] in PACKAGE_TREES and len(parts) > 4:
            continue
        return "/".join(parts[:index])
    return "/".join(parts[:2])

enabled

enabled(root: Path) -> bool

The contract's [ci] speed-marks; false when undeclared.

Off by default: a hosted runner's test time varies by tens of seconds between two runs of one tree, and a mark taken from such runs says nothing about the suite. A workspace whose runners keep a steady clock declares the key, which the contract's judge holds to a boolean.

Source code in packages/workshop/src/livery/workshop/_speed.py
def enabled(root: Path) -> bool:
    """The contract's ``[ci] speed-marks``; false when undeclared.

    Off by default: a hosted runner's test time varies by tens of
    seconds between two runs of one tree, and a mark taken from such
    runs says nothing about the suite. A workspace whose runners keep
    a steady clock declares the key, which the contract's judge holds
    to a boolean.
    """
    from livery.workshop._contract import load_contract

    ci = load_contract(root / "workshop.toml").get("ci") or {}
    return bool(ci.get(ENABLED_KEY, False))

drop_marks

drop_marks(root: Path) -> list[str]

Drop the marks series while the marks are off; the lines to print.

Rows written before the switch went off would be the marks a later opt-in judges from, so the gate job drops the whole series when it finds any. Fails open: a store that cannot be read, or a delete the remote refuses, prints its reason and drops nothing. Nothing to print when the series is already gone.

Source code in packages/workshop/src/livery/workshop/_speed.py
def drop_marks(root: Path) -> list[str]:
    """Drop the marks series while the marks are off; the lines to print.

    Rows written before the switch went off would be the marks a
    later opt-in judges from, so the gate job drops the whole series
    when it finds any. Fails open: a store that cannot be read, or a
    delete the remote refuses, prints its reason and drops nothing.
    Nothing to print when the series is already gone.
    """
    from livery.git import drop

    found = SERIES.rows(state_store(root))
    if found.failed:
        return [f"  speed marks: not dropped: {found.reason}"]
    if not found.rows and not found.skipped:
        return []
    why = drop(state_store(root), SERIES.ref)
    if why:
        return [f"  speed marks: not dropped: {why}"]
    count = len(found.rows) + len(found.skipped)
    return [
        f"  speed marks: dropped {count} stale row(s) from {SERIES.ref};"
        f" the marks are off ([ci] {ENABLED_KEY})"
    ]

leg_label

leg_label(display: str) -> str

The leg label of a matrix job's display name; a plain name stands.

check (ubuntu-latest, 3.14) is the leg check-ubuntu-latest-3.14 and check (windows-latest, 3.14, 2of4) the shard leg check-windows-latest-3.14-2of4, the spelling the job runner gives every entry it spawns.

Source code in packages/workshop/src/livery/workshop/_speed.py
def leg_label(display: str) -> str:
    """The leg label of a matrix job's display name; a plain name stands.

    ``check (ubuntu-latest, 3.14)`` is the leg ``check-ubuntu-latest-3.14``
    and ``check (windows-latest, 3.14, 2of4)`` the shard leg
    ``check-windows-latest-3.14-2of4``, the spelling the job runner gives
    every entry it spawns.
    """
    match = _DISPLAY.match(display)
    if match is None:
        return display
    parts = (match["job"], match["os"], match["python"], match["shard"])
    return "-".join(part for part in parts if part)

display_shard

display_shard(display: str) -> Shard

The shard a job's display name spells; ONE when it spells none.

check (windows-latest, 3.14, 2of4) on GitHub and Gitea, check: [2of4] on GitLab. A tail that is not spelled <i>of<n> names no shard, so a matrix with another third value reads as one shard of one.

Source code in packages/workshop/src/livery/workshop/_speed.py
def display_shard(display: str) -> Shard:
    """The shard a job's display name spells; `ONE` when it spells none.

    ``check (windows-latest, 3.14, 2of4)`` on GitHub and Gitea,
    ``check: [2of4]`` on GitLab. A tail that is not spelled
    ``<i>of<n>`` names no shard, so a matrix with another third value
    reads as one shard of one.
    """
    match = _DISPLAY.match(display) or _GITLAB_DISPLAY.match(display)
    spelled = match["shard"] if match else None
    if not spelled:
        return ONE
    try:
        return Shard.parse(spelled)
    except ValueError:
        return ONE

platform_display

platform_display(display: str) -> str

The display name of a shard's platform: display without its shard.

check (windows-latest, 3.14, 2of4) gives check (windows-latest, 3.14) and check: [2of4] gives check; a name that spells no shard stands. The gate job's fold names a platform's folded row by it, and the collect joins that row with the forge's jobs.

Source code in packages/workshop/src/livery/workshop/_speed.py
def platform_display(display: str) -> str:
    """The display name of a shard's platform: *display* without its shard.

    ``check (windows-latest, 3.14, 2of4)`` gives ``check (windows-latest,
    3.14)`` and ``check: [2of4]`` gives ``check``; a name that spells no
    shard stands. The gate job's fold names a platform's folded row by
    it, and the collect joins that row with the forge's jobs.
    """
    if display_shard(display) == ONE:
        return display
    match = _DISPLAY.match(display)
    if match is not None:
        # The shard follows a comma and a space; what comes before is
        # the platform's own name, closed again.
        return f"{display[: match.start('shard') - 2]})"
    gitlab = _GITLAB_DISPLAY.match(display)
    return gitlab["job"] if gitlab is not None else display

forge_shard_row

forge_shard_row(job: str, row: Mapping[str, Any]) -> bool

Whether job's row is the forge's own row of a shard: no scope, a shard named.

The gate job folds a platform's shards into one row under the platform's display name, and the collect keeps the forge's rows of the shards beside it for fm ci.timings; those carry the forge's times and no scope. The stamp and the speed judge skip them, since the folded row carries what they read.

Source code in packages/workshop/src/livery/workshop/_speed.py
def forge_shard_row(job: str, row: Mapping[str, Any]) -> bool:
    """Whether *job*'s *row* is the forge's own row of a shard: no scope, a shard named.

    The gate job folds a platform's shards into one row under the
    platform's display name, and the collect keeps the forge's rows of
    the shards beside it for ``fm ci.timings``; those carry the forge's
    times and no scope. The stamp and the speed judge skip them, since
    the folded row carries what they read.
    """
    return "scope" not in row and display_shard(job) != ONE

leg_of

leg_of(job: str, row: Mapping[str, Any]) -> str

The leg a run's job row measured: the row's own label, or the name's.

A check leg writes its label (check-ubuntu-latest-3.14) into its row under scope.leg, and that spelling holds on every forge; the job's display name carries the matrix on GitHub and Gitea alone, and on GitLab is the bare check, which would name no runner and never count as the reference.

Source code in packages/workshop/src/livery/workshop/_speed.py
def leg_of(job: str, row: Mapping[str, Any]) -> str:
    """The leg a run's job row measured: the row's own label, or the name's.

    A check leg writes its label (``check-ubuntu-latest-3.14``) into
    its row under ``scope.leg``, and that spelling holds on every
    forge; the job's display name carries the matrix on GitHub and
    Gitea alone, and on GitLab is the bare ``check``, which would name
    no runner and never count as the reference.
    """
    scope = row.get("scope")
    label = str(scope.get("leg") or "") if isinstance(scope, Mapping) else ""
    return label or leg_label(job)

is_reference

is_reference(leg: str) -> bool

Whether leg runs on the reference runner, the one whose red counts.

Source code in packages/workshop/src/livery/workshop/_speed.py
def is_reference(leg: str) -> bool:
    """Whether *leg* runs on the reference runner, the one whose red counts."""
    return REFERENCE in leg

speed_marks

speed_marks(root: Path) -> tuple[dict[tuple[str, str], SpeedMark] | None, str]

Read each package's current test-time mark on each check leg.

The marks live on the checkout's state store (livery.workshop.state_store). The newest row per package and leg is its mark. A row that does not parse, is of another schema, or lacks a mark's fields is skipped, so one bad row disables nothing. A store that cannot be read falls open: the caller prints the reason and judges nothing.

Parameters:

Name Type Description Default
root Path

The checkout whose state store holds the marks.

required

Returns:

Type Description
dict[tuple[str, str], SpeedMark] | None

Each mark by its package's path and its leg, with an empty

str

reason; an empty store gives ({}, ""). When the store

tuple[dict[tuple[str, str], SpeedMark] | None, str]

cannot be read, None and the reason.

Source code in packages/workshop/src/livery/workshop/_speed.py
def speed_marks(root: Path) -> tuple[dict[tuple[str, str], SpeedMark] | None, str]:
    """Read each package's current test-time mark on each check leg.

    The marks live on the checkout's state store
    ([livery.workshop.state_store][]). The newest row per package and
    leg is its mark. A row that does not parse, is of another schema,
    or lacks a mark's fields is skipped, so one bad row disables
    nothing. A store that cannot be read falls open: the caller prints
    the reason and judges nothing.

    Args:
        root: The checkout whose state store holds the marks.

    Returns:
        Each mark by its package's path and its leg, with an empty
        reason; an empty store gives ``({}, "")``. When the store
        cannot be read, None and the reason.
    """
    found = SERIES.rows(state_store(root))
    if found.failed:
        return None, found.reason
    current: dict[tuple[str, str], SpeedMark] = {}
    for row in found.rows:
        mark = _mark(row.data)
        if mark is not None:
            current.setdefault((mark.package, mark.leg), mark)
    return current, ""

write_mark

write_mark(root: Path, *, package: str, leg: str, seconds: float, kind: str, by: str, reason: str = '') -> str

Append one row setting package's mark on leg; "" or why not.

Source code in packages/workshop/src/livery/workshop/_speed.py
def write_mark(
    root: Path,
    *,
    package: str,
    leg: str,
    seconds: float,
    kind: str,
    by: str,
    reason: str = "",
) -> str:
    """Append one row setting *package*'s mark on *leg*; ``""`` or why not."""
    row = {
        "package": package,
        "leg": leg,
        "seconds": round(seconds, 1),
        "kind": kind,
        "by": by,
        "reason": reason,
    }
    return SERIES.put(
        state_store(root),
        {_row_name(datetime.now(UTC), package, leg): row},
        message=f"speed mark: {package} on {leg} {kind} {seconds:.1f}s by {by}",
    )

samples

samples(entries: list[dict[str, Any]], run_id: str) -> list[Sample]

This run's package times per check leg, with each leg's green history.

entries are the timing rows newest first. The run's own entry is the one whose run is run_id; a check leg of it yields one sample per package whose tests ran, and the forge's own row of a shard (forge_shard_row) yields none. The history is the same leg's earlier entries that concluded green and ran the package's tests, newest first, up to one fewer than SAMPLE. Empty when the run has no entry.

Source code in packages/workshop/src/livery/workshop/_speed.py
def samples(entries: list[dict[str, Any]], run_id: str) -> list[Sample]:
    """This run's package times per check leg, with each leg's green history.

    *entries* are the timing rows newest first. The run's own entry
    is the one whose ``run`` is *run_id*; a check leg of it yields one
    sample per package whose tests ran, and the forge's own row of a
    shard (`forge_shard_row`) yields none. The history is the same leg's
    earlier entries that concluded green and ran the package's tests,
    newest first, up to one fewer than `SAMPLE`. Empty when the run
    has no entry.
    """
    current = next((e for e in entries if str(e.get("run", "")) == run_id), None)
    if current is None:
        return []
    earlier = [
        e for e in entries if e is not current and str(e.get("run", "")) != run_id
    ]
    out: list[Sample] = []
    for job, row in sorted((current.get("jobs") or {}).items()):
        if not job.startswith("check") or not isinstance(row, dict):
            continue
        if forge_shard_row(job, row):
            continue
        leg = leg_of(job, row)
        now_slowest = _slowest(row)
        for package, (seconds, tests) in sorted(_package_times(row).items()):
            previous: list[float] = []
            slow_rows: list[dict[str, float]] = []
            for entry in earlier:
                past = (entry.get("jobs") or {}).get(job)
                if not isinstance(past, dict) or past.get("conclusion") != "success":
                    continue
                times = _package_times(past)
                if package not in times:
                    continue
                previous.append(times[package][0])
                slow_rows.append(_slowest(past))
                if len(previous) >= SAMPLE - 1:
                    break
            slowest = tuple(
                sorted(
                    (
                        (t, s)
                        for t, s in now_slowest.items()
                        if package_of(t) == package
                    ),
                    key=lambda item: -item[1],
                )[:SLOWEST]
            )
            out.append(
                Sample(
                    package=package,
                    leg=leg,
                    seconds=seconds,
                    tests=tests,
                    previous=tuple(previous),
                    slowest=slowest,
                    grown=_grown(now_slowest, slow_rows, package),
                )
            )
    return out

judge

judge(found: list[Sample], current: dict[tuple[str, str], SpeedMark]) -> list[Verdict]

Each sample against its mark; one verdict each.

Source code in packages/workshop/src/livery/workshop/_speed.py
def judge(
    found: list[Sample], current: dict[tuple[str, str], SpeedMark]
) -> list[Verdict]:
    """Each sample against its mark; one verdict each."""
    return [
        Verdict(sample=sample, mark=current.get((sample.package, sample.leg)))
        for sample in found
    ]

render

render(verdict: Verdict) -> list[str]

The lines for verdict: the time, the mark, the state, the culprits.

Source code in packages/workshop/src/livery/workshop/_speed.py
def render(verdict: Verdict) -> list[str]:
    """The lines for *verdict*: the time, the mark, the state, the culprits."""
    sample, mark = verdict.sample, verdict.mark
    head = f"  speed {sample.package} on {sample.leg}: {sample.seconds:.1f}s"
    if mark is None:
        seen = len(sample.previous) + 1
        if verdict.records:
            return [f"{head}, no mark yet; this run records {verdict.median:.1f}s"]
        return [f"{head}, no mark yet ({seen}/{SAMPLE} green runs)"]
    limit = verdict.limit
    assert limit is not None
    state = ""
    if verdict.red:
        state = " OVER for the second run in a row: red"
    elif verdict.over and not is_reference(sample.leg):
        state = " OVER (this leg warns only)"
    elif verdict.over:
        state = " OVER (a second run over in a row is red)"
    lines = [
        f"{head} (mark {mark.seconds:.1f}s {mark.kind} by {mark.by},"
        f" limit {limit:.1f}s){state}"
    ]
    if mark.reason:
        lines.append(f"    accepted: {mark.reason}")
    if verdict.over:
        if sample.slowest:
            named = ", ".join(f"{test} {s:.1f}s" for test, s in sample.slowest)
            lines.append(f"    slowest: {named}")
        if sample.grown:
            named = ", ".join(
                f"{test} {before:.1f}s -> {now:.1f}s"
                for test, before, now in sample.grown
            )
            lines.append(f"    grew: {named}")
    if verdict.ratchets:
        lines.append(
            f"    new mark: {verdict.median:.1f}s (the median of {SAMPLE} beats"
            f" {mark.seconds:.1f}s by more than {RATCHET:.0%})"
        )
    return lines

judge_run

judge_run(root: Path, run: RunContext) -> tuple[list[Verdict], list[str]]

Judge the run's check legs; the verdicts and the lines for what could not be.

Reads the timing rows and the marks; either unreadable falls open with its reason and no verdict, so a store fault never reddens a run and never writes.

Source code in packages/workshop/src/livery/workshop/_speed.py
def judge_run(root: Path, run: RunContext) -> tuple[list[Verdict], list[str]]:
    """Judge the run's check legs; the verdicts and the lines for what could not be.

    Reads the timing rows and the marks; either unreadable falls open
    with its reason and no verdict, so a store fault never reddens a
    run and never writes.
    """
    from livery.workshop._metrics import SERIES as METRICS

    rows = METRICS.rows(state_store(root))
    if rows.failed:
        return [], [f"  speed: not judged ({rows.reason})"]
    current, why = speed_marks(root)
    if current is None:
        return [], [f"  speed: not judged ({why})"]
    found = samples([row.data for row in rows.rows], run.run_id)
    if not found:
        return [], [
            f"  speed: run {run.run_id} left no check leg with tests; nothing to judge"
        ]
    return judge(found, current), []

apply

apply(root: Path, verdicts: list[Verdict], *, by: str) -> list[str]

Write the first marks and the ratchets among verdicts; the lines.

Source code in packages/workshop/src/livery/workshop/_speed.py
def apply(root: Path, verdicts: list[Verdict], *, by: str) -> list[str]:
    """Write the first marks and the ratchets among *verdicts*; the lines."""
    lines: list[str] = []
    for verdict in verdicts:
        if not (verdict.records or verdict.ratchets):
            continue
        median = verdict.median
        assert median is not None
        kind = "first" if verdict.records else "ratchet"
        why = write_mark(
            root,
            package=verdict.sample.package,
            leg=verdict.sample.leg,
            seconds=median,
            kind=kind,
            by=by,
        )
        lines.append(
            f"    {'recorded' if not why else 'not recorded: ' + why}"
            f" ({verdict.sample.package} on {verdict.sample.leg}, {kind} {median:.1f}s)"
        )
    return lines

accept

accept(root: Path, *, package: str, leg: str, seconds: float, reason: str, by: str, packages: tuple[str, ...]) -> list[str]

Raise package's mark on leg to seconds deliberately; the lines.

Refuses without a reason, for a path not among packages, a time that is not positive, an unreadable store, and a value at or below the current mark: lowering is the ratchet's own move.

Source code in packages/workshop/src/livery/workshop/_speed.py
def accept(
    root: Path,
    *,
    package: str,
    leg: str,
    seconds: float,
    reason: str,
    by: str,
    packages: tuple[str, ...],
) -> list[str]:
    """Raise *package*'s mark on *leg* to *seconds* deliberately; the lines.

    Refuses without a reason, for a path not among *packages*, a time
    that is not positive, an unreadable store, and a value at or below
    the current mark: lowering is the ratchet's own move.
    """
    if not reason.strip():
        fail(
            "a reason is required: --reason=<why the suite may take longer> goes"
            " on the record beside the new mark"
        )
    if package not in packages:
        fail(f"no package at {package!r}; the packages are {', '.join(packages)}")
    if seconds <= 0:
        fail(f"the mark is a time in seconds; {seconds!r} is not")
    current, why = speed_marks(root)
    if current is None:
        fail(f"refusing: {why}; a write from an unread store would erase its rows")
    mark = current.get((package, leg))
    if mark is not None and seconds <= mark.seconds:
        fail(
            f"{package}'s mark on {leg} is {mark.seconds:.1f}s; {seconds:.1f}s does"
            " not raise it. Lowering is the ratchet's own move, when the runs beat"
            " the mark."
        )
    written = write_mark(
        root,
        package=package,
        leg=leg,
        seconds=seconds,
        kind="accept",
        by=by,
        reason=reason.strip(),
    )
    if written:
        fail(f"the mark was not written: {written}")
    was = f"{mark.seconds:.1f}s" if mark is not None else "none"
    return [
        f"  speed {package} on {leg}: mark {was} -> {seconds:.1f}s accepted by {by}",
        f"    reason: {reason.strip()}",
    ]

render_marks

render_marks(root: Path) -> list[str]

The marks beside the newest run's times, for fm ci.timings.

Source code in packages/workshop/src/livery/workshop/_speed.py
def render_marks(root: Path) -> list[str]:
    """The marks beside the newest run's times, for ``fm ci.timings``."""
    from livery.workshop._metrics import SERIES as METRICS

    current, why = speed_marks(root)
    if current is None:
        return [f"  speed marks: not read ({why})"]
    if not current:
        return ["  speed marks: none yet; the gate job records one per package and leg"]
    latest: dict[tuple[str, str], float] = {}
    rows = METRICS.rows(state_store(root))
    if not rows.failed and rows.rows:
        newest = rows.rows[0].data
        for job, row in (newest.get("jobs") or {}).items():
            if isinstance(row, dict):
                for package, (seconds, _tests) in _package_times(row).items():
                    latest[(package, leg_of(job, row))] = seconds
    lines = ["  speed marks", f"    {'package on leg':<52} {'mark':>8} {'latest':>8}"]
    for (package, leg), mark in sorted(current.items()):
        now = latest.get((package, leg))
        shown = f"{now:.1f}s" if now is not None else "-"
        lines.append(
            f"    {f'{package} on {leg}'[:52]:<52} {mark.seconds:7.1f}s {shown:>8}"
            f"  {mark.kind} by {mark.by}"
        )
    return lines