Team PR review protocol¶
Five commands record the review of a pull request as typed facts on a team
task, and one query reads whether the PR is ready at a head. This page is the
lookup surface for them. For why a team would record review on a task, and
what the chat is still for, see Team tasks.
The CLI's side is team pr.
Ready is a recorded fact, not a merge gate
Nothing here merges a PR, checks CI, or makes a merge wait for readiness.
pr.ready records that the current seats served one frozen head. Whether
to merge is still the team's call.
The contract comes from
hadron-server#3448,
merged in
hadron-server#3452
at 06f4b59c54a8e63b50c04d3f08c9d5d610acc25e. Every name below was read from
the GraphQL schema and the protocol resolver at that revision. The rules are
the platform specs
cor:agt:050:08,
:09,
:21,
:23
and
:28,
and
cor:agt:110:01
to
:03.
This page cites them and does not restate them; where the two differ, the
specs win.
The tasks¶
| Task | What it is |
|---|---|
| Build task | The task that carries the PR. It needs a task reference of kind pull_request (AgentTask.references); without one, freezing is refused. |
| Seat task | A direct child of the build task, one per review seat. A seat is bound to a slot at a head. |
A slot is a name the build's owner chain puts in the schedule, such as a local review or a blind review. A seat is the child task that fills it.
The commands¶
| GraphQL mutation | Who may call it | What it records |
|---|---|---|
setReviewSchedule(taskRef, slots) |
The build task's owner chain; the assignee alone may not | review.scheduled: the required slots. The latest event replaces the schedule. |
freezePullRequestHead(taskRef, head) |
The build task's assignee | pr.frozen: the head under review. |
assignReviewSeat(taskRef, slot, head, supersedes) |
The seat task's owner chain | review.seat.assigned: binds the seat to a slot at the frozen head. |
recordReviewVerdict(taskRef, head, verdict, node, receipt) |
The seat task's assignee, while the seat is STARTED |
review.verdict. It does not finish the seat task. |
recordReadyCall(taskRef, head) |
The build task's assignee | pr.ready, only when the readiness rule holds. |
Every command returns a PrProtocolResult: the task, and an action with
the event code, a register state and, when mapped, the taskLoc and
taskUrn (see the register). A caller
without an Agent gets the code and the state WITHHELD only.
All five refuse a finished or cancelled task with TASK_ENDED, after checking
authority. Writes are serialised on the App's task graph, so concurrent calls
do not interleave.
Values¶
| Value | Shape |
|---|---|
head |
A full 40-character hex SHA. Never inferred and never abbreviated. Stored lower-case. |
| slot id | Colon-separated atoms, at most 64 characters in total. An atom starts and ends with a letter or digit and may hold _, . and - between. Slots in a schedule are unique and non-empty. |
node, receipt |
Optional text, recorded and not fetched. Put no secrets in them. |
The verdict enum¶
ReviewVerdict is APPROVE, CHANGES_REQUESTED, PASS, FAIL, CARRY or
REFUSED. APPROVE, PASS and CARRY are positive. CHANGES_REQUESTED,
FAIL and REFUSED are negative.
The frozen head¶
The build assignee freezes one head at a time. Seats are assigned at it,
verdicts are recorded at it and readiness is read at it. A head that is not the
latest frozen head is PR_HEAD_NOT_FROZEN on the readiness query and
REVIEW_HEAD_MISMATCH when you assign a seat. A verdict is checked against
the head its seat was assigned, not against the build's latest frozen head:
a seat still STARTED after a newer freeze can record a verdict at its old
head, and that verdict does not count at the newer head.
Freezing a head that already carries a negative verdict from any child seat is
refused REVIEW_SEAT_NOT_SUPERSEDABLE, including a verdict from a superseded
seat or a dropped slot. Going back to an old head cannot erase a finding. Answer
it with a new head.
The seat rules¶
They apply in this order when you assign a seat.
REVIEW_SEAT_NOT_SUPERSEDABLE. A current seat whose verdict at this head is negative cannot be replaced, with or withoutsupersedes. A negative seat cannot move to another slot at the same head either. A schedule that drops a slot holding a negative verdict at the frozen head is refused for the same reason.REVIEW_SEAT_ALREADY_ASSIGNED. A seat task is assigned once. Use a new seat task to change anything.REVIEW_SEAT_SUPERSEDES_REQUIRED. A seat that replaces another in the same slot names the current one insupersedes.
supersedes that does not name the current sibling for the slot is
REVIEW_SEAT_SUPERSEDE_INVALID.
A different actor cannot overwrite a negative verdict at the same head; only
the actor who recorded it may re-rate it (REVIEW_SEAT_NOT_SUPERSEDABLE).
The readiness rule¶
The PR is ready at a head when, for every slot in the schedule, the current seat for that slot:
- is
FINISHED, - was assigned at that head and recorded its verdict at that head, in that slot,
- has a verdict of
APPROVE,PASSorCARRY, and - has a verdict whose actor is not the build's current assignee and not anyone who froze that exact head anywhere in the same App.
And one condition on the whole PR: no direct child's latest verdict at that head may be negative, including a child that is superseded or whose slot was dropped from the schedule. Such a verdict makes every slot not count, even when each current seat is positive.
Readiness is computed from event facts only. The pr.* and review.*
properties never decide it
(cor:agt:050:28).
recordReadyCall writes pr.ready only when this holds. Otherwise it is
refused PR_NOT_READY, and the refusal carries the slots that do not count.
Reading readiness¶
query {
pullRequestReadiness(taskRef: "AT0.12", head: "<40-hex head>") {
ready
head
slots { slot currentTaskId state verdict head counts }
}
}
slots has one row per scheduled slot. state is the seat task's status in
upper case, or MISSING when no seat fills the slot. counts is true when the
slot meets the rule above, including the whole-PR condition. A head that is not ready is a successful answer,
not an error.
The read gate¶
pullRequestReadiness uses the same read gate as the task itself, including
the App's own live key. It returns null for a task the caller cannot read, so
an unreadable task looks the same as a missing one. An unfrozen head is
PR_HEAD_NOT_FROZEN, and a build with no schedule is REVIEW_SCHEDULE_MISSING.
Refusal codes¶
| Code | When |
|---|---|
TASK_NOT_FOUND |
The task, or a seat's build task, is not found or not readable. |
TASK_NOT_OWNER |
The caller is not in the task's owner chain. The assignee alone has no standing. |
TASK_NOT_ASSIGNEE |
The caller is not the task's assignee. |
TASK_ENDED |
The task is finished or cancelled. |
TASK_INVALID_TRANSITION |
A verdict on a seat that is not STARTED. |
BAD_USER_INPUT |
A head, slot, schedule or verdict that is malformed. |
PR_REFERENCE_MISSING |
Freeze on a build task with no pull_request reference. |
PR_HEAD_NOT_FROZEN |
A readiness read at a head that is not frozen. |
REVIEW_SCHEDULE_MISSING |
A build task with no schedule. |
REVIEW_SLOT_UNKNOWN |
A seat names a slot that is not scheduled. |
REVIEW_HEAD_MISMATCH |
A seat or verdict names a head other than the frozen or assigned one. |
REVIEW_SEAT_UNASSIGNED |
The seat is not a child of a build task, or has no assigned seat. |
REVIEW_SEAT_ALREADY_ASSIGNED |
See the seat rules. |
REVIEW_SEAT_SUPERSEDES_REQUIRED |
See the seat rules. |
REVIEW_SEAT_SUPERSEDE_INVALID |
supersedes is not the current sibling for the slot. |
REVIEW_SEAT_NOT_SUPERSEDABLE |
See the seat rules. |
PR_NOT_READY |
A ready call while a slot does not count. Carries slots. |
The event codes¶
Each command appends one typed event, readable with hadron team events
(see the CLI reference).
| Event | Written by |
|---|---|
review.scheduled |
setReviewSchedule |
pr.frozen |
freezePullRequestHead |
review.seat.assigned |
assignReviewSeat |
review.verdict |
recordReviewVerdict |
pr.ready |
recordReadyCall |
Each code is looked up in the register
like any other, and the answer comes back as the command's action. The
lookup runs after the write has committed and never fails it.
Related¶
- Team tasks: why the review state can live on a task, and why the chat stays in use.
- CLI:
team pr: the commands and their--jsonshapes. - Team task properties: the mirrors the commands write.
- Team task warnings: the register.