livery.workshop._gate_record¶
livery.workshop._gate_record ¶
The local gate record: the chain of trees this checkout's green gates proved.
Every green local gate writes one row: the tree it proved, and the
proved tree it started from. A full gate proves a tree outright. A
narrowed gate proves the packages a delta can influence, so its row
names the tree the delta was taken from, and the tree is proved when
that one is: a package the delta did not touch keeps the earlier
proof, since affected is closed under dependents. A chain of such
rows is a proof of its newest tree once it reaches a root, a full row
or a tree CI's own workshop/verified record holds, which is what
the merge base with the base branch is after a merge.
Two readers use the chain. The reflex, fm check on a machine,
looks for the nearest proved tree in the checkout's history and gates
the delta from it to the working tree, so the tenth commit of a
branch pays for what the tenth commit touched; a working tree the
chain already proves pays nothing. fm submit walks the chain from
HEAD's tree and skips its gate when the chain reaches a root, saying
so. The rows key the working tree's id, which a commit that takes
everything shares, so a check before the commit proves the commit.
A CI check leg chooses where to measure from by the same rule
(leg_plan), over CI's own record alone, read for the leg's own
platform.
The record is a local series of the state store
(livery.git): it lives in the checkout's git
directory, shared by its worktrees, is written only by a green local
gate, and never leaves the machine. CI never reads or writes it. The
window keeps the newest KEEP rows, and a row older than MAX_AGE
proves nothing, since the tree id covers the pins in uv.lock but
not the machine's Python or tools, which drift under the same tree.
Classes:
| Name | Description |
|---|---|
Row |
One proved tree. |
Chain |
A proof of one tree: its steps back to a root. |
Plan |
What the reflex runs for the working tree. |
Functions:
| Name | Description |
|---|---|
rows |
Every row, newest first, or |
remember |
Record tree as proved green by the gate that just ran; the line to print. |
chain |
The chain proving tree, or |
verified_roots |
The trees CI's record holds that a chain may rest on, and why none when none. |
covering |
The chain proving HEAD's tree for the gate a submit would run, or why not. |
plan |
What the reflex runs for the working tree: nothing, a step, or everything. |
leg_plan |
Where a CI check leg measures its change from; the reflex's rule on CI's record. |
Attributes:
| Name | Type | Description |
|---|---|---|
KEEP |
|
|
MAX_AGE |
|
|
REACH |
|
|
NEAR |
|
|
MERGES |
|
|
SERIES |
|
|
FULL |
|
|
STEP |
|
|
MERGE_BASE |
|
SERIES
module-attribute
¶
Row
dataclass
¶
One proved tree.
Attributes:
| Name | Type | Description |
|---|---|---|
tree |
str
|
The git tree id the gate proved. |
scope |
str
|
|
packages |
tuple[str, ...]
|
The packages a step gated; empty for |
base_tree |
str
|
The proved tree a step's delta was taken from;
empty for |
when |
str
|
When the store wrote the row, ISO 8601 in UTC. |
root |
str
|
The checkout the gate ran in, for a reader. |
Chain
dataclass
¶
A proof of one tree: its steps back to a root.
Attributes:
| Name | Type | Description |
|---|---|---|
tree |
str
|
The tree the chain proves. |
steps |
tuple[Row, ...]
|
The rows walked, newest first; empty when CI's record holds the tree itself. |
root |
str
|
|
root_tree |
str
|
The tree the chain rests on. |
Methods:
| Name | Description |
|---|---|
describe |
One clause a line can carry: the steps and the root. |
describe ¶
describe() -> str
One clause a line can carry: the steps and the root.
Source code in packages/workshop/src/livery/workshop/_gate_record.py
Plan
dataclass
¶
What the reflex runs for the working tree.
Attributes:
| Name | Type | Description |
|---|---|---|
mode |
str
|
|
tree |
str
|
The working tree's id, the row a green run records. |
base_tree |
str
|
The tree a step builds on, proved but for a
|
paths |
tuple[str, ...]
|
The paths a step's delta touches. |
why |
str
|
The reason, for the line the gate prints. |
rows ¶
Every row, newest first, or ((), reason) when the record cannot be read.
A row without a tree is not a proof and is left out; the store already skipped what does not parse or is of another schema.
Source code in packages/workshop/src/livery/workshop/_gate_record.py
remember ¶
Record tree as proved green by the gate that just ran; the line to print.
packages is what a step gated, with base_tree the proved tree
its delta was taken from; None records a full gate. A row of
the same tree, scope, and base replaces its predecessor; the
window keeps the newest KEEP rows.
Never raises. The record only lets a later gate run less, so a row that is not written costs that gate time and changes no verdict: a write that fails, by its returned reason or by raising, comes back as the line that says so, and the gate that called it stays green.
Source code in packages/workshop/src/livery/workshop/_gate_record.py
chain ¶
chain(root: Path, tree: str, *, roots: set[str], now: datetime | None = None, found: tuple[Row, ...] | None = None) -> Chain | None
The chain proving tree, or None when the rows do not reach a root.
roots are the trees CI's record holds. Rows older than MAX_AGE
do not count. A cycle or a base no row proves ends the walk empty. found are the
rows already read, for a caller walking many trees; the record is
read once here otherwise.
Source code in packages/workshop/src/livery/workshop/_gate_record.py
verified_roots ¶
The trees CI's record holds that a chain may rest on, and why none when none.
The candidates are the merge base with base and HEAD's
first-parent history, REACH commits deep. After a merge, main's
run stamps its tree, so a branch cut from it starts proved; while
that run is still red or unfinished, the parent's tree carries the
chain and the merge's own changes ride in the first step. A record
the forge could not answer leaves the chain rootless, and the
reason is returned for the line.
Source code in packages/workshop/src/livery/workshop/_gate_record.py
covering ¶
covering(root: Path, *, base: str = 'main', now: datetime | None = None) -> tuple[Chain | None, str]
The chain proving HEAD's tree for the gate a submit would run, or why not.
Source code in packages/workshop/src/livery/workshop/_gate_record.py
plan ¶
What the reflex runs for the working tree: nothing, a step, or everything.
The working tree's own chain settles it first. Else the proved
tree with the fewest paths changed to the working tree becomes the
step's base, chosen among HEAD's first-parent history, REACH
commits deep, and the trees of the newest NEAR rows, so a green
check of a dirty tree is the base of the next check after one more
edit; a row's tree git no longer has is passed over. With none in
reach the whole gate runs and roots a new chain.
Source code in packages/workshop/src/livery/workshop/_gate_record.py
leg_plan ¶
leg_plan(root: Path, *, base: str, branch: str, leg: str = '', before: datetime | None = None) -> Plan
Where a CI check leg measures its change from; the reflex's rule on CI's record.
The candidates are the merge base with base, HEAD's first-parent
history REACH commits deep, and, on a merge checkout, the merges
branch's earlier runs proved. A pull request's run on GitHub
tests the merge of its head onto the base branch, a commit no later
clone holds, so its row names the two commits it merged; the merge
is rebuilt from them, MERGES rows deep, and counts only when it
yields the row's tree, which also puts that tree in this clone for
every reader of the step's base. Of the candidates the record
proves in full for leg's platform (any full row when leg is
empty), the one with the fewest paths changed to HEAD's tree is
the step's base: the earlier push's merge, when the base branch
has not moved far, or the base branch's tip. With none, or a
record that cannot be read, the step is taken from the merge base
(MERGE_BASE), and why says so, naming the leg. Without a merge
base the mode is full. With before, the record's rows count
only when the store stamped them before it
(livery.workshop._verified.written_before), so the shards of a
leg, which share the bound, measure from one tree.