livery.workshop._verified¶
livery.workshop._verified ¶
The verified-tree record: which trees a green gate already proved, per platform.
A push to main reruns the gate on a squash that, for a branch that
sat on main's tip, is byte for byte the tree its pull request just
verified. The gate job stamps the tree id it proved green on the
workshop/verified series after its verdict, with the run, the
commit, the scope its check legs ran, and the legs' labels
(check-ubuntu-latest-3.14); every check leg reads the record
first and skips the gate when a full entry names its own tree for
its own platform leg. Tree identity, not merge shape, is the test,
so the skip reaches reverts and manual re-runs, and a squash of a
stale branch pays in full.
A row proves its tree for the legs it names and for no other
platform. After a pull request's run on one platform, the merge's
run on that platform ends its check at once, the other platforms run
the whole gate, and the stamp names every leg of the run, the
skipped one included, so the tree's row then names them all. The
machine's reflex (livery.workshop._gate_record.plan) is not a
leg: it roots on any row (held), since a machine is its own
platform and its gate is the reflex, not the verdict.
The record is advisory in the safe direction only: a missing entry,
an unreachable store, another tree, or a narrowed scope runs the
gate, and a stamp that cannot be written prints why. A leg leaves
its scope in a marker file beside its trace, with the tree its
narrowed gate measured from. The stamp says full when every
check leg ran the whole gate, and also when the legs ran narrowed
on top of a tree the record already names as full: every package a
narrowed leg skipped is byte for byte the base tree's, and so is
every root file the gate reads, so their verdicts carry over from
the base's run, and the row names that base. Without a full row for
the base, a narrowed run stamps nothing.
A pull request's run on GitHub tests the merge the forge made of the pull request's head onto its base branch, a commit no later clone holds. Its row names the two commits it merged, so the next run can rebuild that merge and measure from it (livery.workshop._gate_record.leg_plan).
Classes:
| Name | Description |
|---|---|
Verified |
One tree's entry: the run that proved it and what the legs ran. |
LegScope |
What the gate ran on one check leg, as the marker the leg left says. |
VerifiedBranch |
The branch whose run proved a tree, or why the record could not say. |
Functions:
| Name | Description |
|---|---|
tree_id |
The tree id ref points at. |
write_marker |
Leave the leg's scope, the suites it ran, and its label beside its trace. |
leg_scope |
Read what the gate ran on this leg from the marker it left at root. |
verified_branch |
Read which branch's run proved the tree checked out at root. |
record |
The entry for tree, or |
written_before |
Whether a row stamped when counts under the bound before. |
proves |
Whether row proves its tree for leg: a full row naming the leg's platform. |
proved |
The rows that prove their trees for leg, by tree, newest first, in one read. |
held |
The trees among trees the record holds, in one read, whatever legs they name. |
stamp |
Record tree as proved green by run; |
stamp_from_metrics |
Stamp the run's tree from what its check legs' rows say they ran. |
Attributes:
| Name | Type | Description |
|---|---|---|
SERIES |
|
|
MARKER |
|
|
FULL |
|
|
AFFECTED |
|
|
NOTHING |
|
|
VERIFIED |
|
|
KNOWN |
|
Verified
dataclass
¶
Verified(tree: str, run: str, sha: str, scope: str, legs: tuple[str, ...], base_tree: str = '', base_run: str = '', branch: str = '', head_sha: str = '', base_sha: str = '')
One tree's entry: the run that proved it and what the legs ran.
Attributes:
| Name | Type | Description |
|---|---|---|
tree |
str
|
The git tree id the gate proved. |
run |
str
|
The forge's run id. |
sha |
str
|
The commit the run checked out. |
scope |
str
|
|
legs |
tuple[str, ...]
|
The check legs' labels ( |
base_tree |
str
|
The tree a composed row rests on; empty otherwise. |
base_run |
str
|
The run that proved that base; empty otherwise. |
branch |
str
|
The pull request branch whose run proved the tree, whose records main's run reads at the merge; empty for main's own run and for a row that never said. |
head_sha |
str
|
On a run that tested a merge, the pull request's head it merged; empty otherwise. |
base_sha |
str
|
On a run that tested a merge, the base branch's commit it merged onto; empty otherwise. |
LegScope
dataclass
¶
What the gate ran on one check leg, as the marker the leg left says.
Attributes:
| Name | Type | Description |
|---|---|---|
scope |
str
|
What the gate ran. |
packages |
tuple[str, ...]
|
The paths of the suites a narrowed gate ran; empty for every other scope. |
leg |
str
|
The label the leg's rows are keyed by
( |
base_tree |
str
|
The tree a narrowed gate measured from; empty for every other scope. |
VerifiedBranch
dataclass
¶
The branch whose run proved a tree, or why the record could not say.
Attributes:
| Name | Type | Description |
|---|---|---|
branch |
str
|
The pull request branch whose run proved the tree; empty when no row names the tree, when the row names no branch, as main's own run's does, and when the row could not be read. |
reason |
str
|
Why the record decided nothing: the tree has no id, or its row could not be read; empty when the record was read. |
tree_id ¶
The tree id ref points at.
Source code in packages/workshop/src/livery/workshop/_verified.py
write_marker ¶
write_marker(root: Path, scope: str, packages: tuple[str, ...] = (), *, leg: str = '', base_tree: str = '') -> None
Leave the leg's scope, the suites it ran, and its label beside its trace.
The metrics row, the stamp, and the entries after the gate read it back: packages are the suites the leg ran under a narrowed scope, leg the label the leg's rows are keyed by, and base_tree the tree a narrowed gate measured from, which the stamp composes with.
Source code in packages/workshop/src/livery/workshop/_verified.py
leg_scope ¶
Read what the gate ran on this leg from the marker it left at root.
The gate leaves the marker on a CI run's check leg, so the leg's entries after the gate read it there. A gate outside CI leaves none.
Returns:
| Type | Description |
|---|---|
LegScope
|
The leg's scope; |
LegScope
|
marker is not a JSON object. |
Source code in packages/workshop/src/livery/workshop/_verified.py
verified_branch ¶
verified_branch(root: Path) -> VerifiedBranch
Read which branch's run proved the tree checked out at root.
Main's run after a squash merge reads it to find the branch whose records the tree carries. A row the store cannot read, and a tree git cannot name, decide nothing: the branch is empty and the reason says why, so the caller reads main's records alone.
Source code in packages/workshop/src/livery/workshop/_verified.py
record ¶
The entry for tree, or (None, reason); an absent entry has no reason.
A read the transport could not answer falls open with its words,
and so does an entry that is not a row of the record's schema:
the gate runs, and the line says why the record did not decide.
With before, an entry the store stamped at or after it, or never
stamped, reads as absent (written_before).
Source code in packages/workshop/src/livery/workshop/_verified.py
written_before ¶
Whether a row stamped when counts under the bound before.
Every row counts without a bound. With one, a row counts when the store stamped it before the bound; an unstamped row or a stamp that does not parse never does. The shards of a check leg read the record under one bound, the committer time of the commit they all checked out, so a row another run writes while they start counts for all of them or for none.
Source code in packages/workshop/src/livery/workshop/_verified.py
proves ¶
Whether row proves its tree for leg: a full row naming the leg's platform.
With leg empty, any full row does. Each stored name is read through livery.workshop._speed.leg_label, so a row written with the forge's display names counts for the leg it names, and the names and leg are compared as platform legs (livery.workshop.platform_leg), so a shard of a platform reads the row the fold stamped under the platform leg as its own.
Source code in packages/workshop/src/livery/workshop/_verified.py
proved ¶
proved(root: Path, leg: str = '', *, before: datetime | None = None) -> tuple[dict[str, Verified], str]
The rows that prove their trees for leg, by tree, newest first, in one read.
({}, reason) when the record could not be read. With a leg,
the full rows that name it (proves); without one, every full
row. A row of a narrowed scope proves nothing and is left out, as
a file that is not a row of the record's schema is. With before,
only the rows the store stamped before it (written_before).
Source code in packages/workshop/src/livery/workshop/_verified.py
held ¶
The trees among trees the record holds, in one read, whatever legs they name.
The machine's reflex roots its chain here and asks for no leg: a machine is its own platform, and its gate is the reflex, not the verdict, so any tree CI's record holds is a root.
(set(), reason) when the record could not be read. A file that
is not a row of the record's schema is skipped the way every read
skips it, so its tree reads as not held; an absent record holds
nothing, without a reason.
Source code in packages/workshop/src/livery/workshop/_verified.py
stamp ¶
stamp(root: Path, run: RunContext, *, tree: str, sha: str, legs: tuple[str, ...], base: Verified | None = None, branch: str = '', merged: tuple[str, str] | None = None) -> str
Record tree as proved green by run; "" or the reason.
Only a CI run writes. legs are the labels of the run's check legs: each ran the full gate, skipped on a full row that named it, or ran narrowed on top of base, a full row the caller read from the record; a composed row names that base and its run. branch is the pull request branch the run came from, so main's run after the squash knows whose records the tree carries. merged are the base branch's commit and the head a merge checkout joined, so the branch's next run can rebuild the merge.
Source code in packages/workshop/src/livery/workshop/_verified.py
stamp_from_metrics ¶
stamp_from_metrics(root: Path, run: RunContext, *, sha: str) -> str
Stamp the run's tree from what its check legs' rows say they ran.
Reads the run's file on the metrics series, which the collect
step put before the verdict; each check leg's row carries the
scope its marker named and the leg's label, which the stamp
names (livery.workshop._speed.leg_of), so GitLab's bare job
name records its platform too. A platform that ran as shards has
one row, folded under its own name before the collect, and the
forge's rows of its shards beside it, which carry no scope and are
skipped (livery.workshop._speed.forge_shard_row). Every leg
full, or skipped on the record: the tree is stamped naming every
leg, so after a pull
request's run on one platform the merge's run leaves a row naming
every platform. Legs narrowed (affected, or nothing for a prose-only
diff): the tree is stamped when every narrowed leg measured from
one tree and the record names that tree as full, and the row
names that base; otherwise nothing is written and the line says
which proof is missing. On a merge checkout the row also names
the two commits merged. Returns the line to print.
Source code in packages/workshop/src/livery/workshop/_verified.py
403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 | |