Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
ae42a51
When a Run began is read from its jobs, trusted only once a job is in…
don-petry Nov 11, 2026
e63649f
Merge main into adapters/record-start-from-job-724
don-petry Nov 11, 2026
cb01adb
The jobs read is its own function, classed for the token it needs, an…
don-petry Nov 11, 2026
9932fb3
A read of one item's Runs is asked past the cap, since a Run keeps no…
don-petry Nov 11, 2026
ca4546d
The record says when the Harness's reads begin to ask (#724)
don-petry Nov 11, 2026
5095b60
A null kept for a completed Run is not said of one the list gives as …
don-petry Nov 11, 2026
078c741
The read of one item's Runs moves to the pull request that asks for i…
don-petry Nov 11, 2026
d0ef97f
The pass's keeping of when a Run began moves to its own pull request …
don-petry Nov 11, 2026
338f7c4
A job in a status GitHub gives none, or not yet completed of a comple…
don-petry Nov 11, 2026
a630661
Carbon's read of the port: what is kept is said past the cap and of n…
don-petry Nov 11, 2026
b73c482
Astra's second read of the port: a status that is no word, more jobs …
don-petry Nov 11, 2026
e7a1a56
Astra's third read of the port: a job listed twice, the cap's number …
don-petry Nov 11, 2026
35f22ea
Astra's fourth read of the port: a job's id is a number, and every st…
don-petry Nov 11, 2026
66ff40b
Merge main into adapters/record-start-from-job-724
don-petry Nov 11, 2026
c37e2f8
Astra's fifth read of the port: a runner that is neither a name nor n…
don-petry Nov 11, 2026
6286861
A run's jobs are asked a hundred to a page, and the record cites its …
don-petry Nov 11, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 79 additions & 6 deletions adapters/records.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,11 @@
counted run's outcome read (L-53). A Run that did not succeed has its outcome read from its artifact by
`adapters/artifacts.py`, once the list is final, and for no other Run (decisions 0039 and 0049): one it cannot read
leaves the list not whole, so that no failed Run is ever read as no attempt.

When a Run began is read from its jobs, for a caller that asks (decision 0193): `run_started_at` is the run's
creation even while it waits in its item's lane, and so is a job's `started_at` until the job is `in_progress`, or
`completed` with a runner named (trials/P-64.json). `began_at` is the earliest such start among the latest attempt's
jobs, null for a completed Run none of whose jobs began, and absent where it has not begun or was not read.
"""
from __future__ import annotations

Expand All @@ -29,6 +34,7 @@
PAGE = 100 # runs on one page of a workflow's list
SERVED = 1000 # the most of a list's runs GitHub serves, however many it counts (L-53)
WAIT = 5 # seconds before the one second read of a list holding an unidentified Run (decision 0036)
JOBS = 50 # the most Runs whose jobs one read of the records asks for (decision 0193)
NAME = re.compile(r"sf ([A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100})#([1-9][0-9]{0,8}) ([a-z][a-z-]{0,60}[a-z]) "
r"([a-z][a-z-]{0,60}[a-z]) (sha256:[0-9a-f]{4,64}) (r_[0-9A-Z]{6,26})")
# The Intents a pull request's Runs carry, as kernel/decide.py admits them, and an issue's, as kernel/issue.py does.
Expand All @@ -42,6 +48,7 @@
# attempt otherwise (decision 0111). A word not here would leave the list not whole for as long as GitHub serves the
# row, and admit nothing anywhere.
NOT_STARTED = {"queued", "waiting", "requested", "pending"}
JOB_STATUSES = NOT_STARTED | {"in_progress", "completed"} # a job's, as a run's: any other cannot be read
CONCLUSIONS = {"success": "success", "failure": "failure", "startup_failure": "cancelled", "cancelled": "cancelled",
"skipped": "cancelled", "timed_out": "timed_out"}
FRESH = {"Cache-Control": "no-cache"}
Expand All @@ -50,6 +57,7 @@
MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
HTTP_DATE = re.compile(r"(Mon|Tue|Wed|Thu|Fri|Sat|Sun), ([0-9]{2}) ([A-Z][a-z]{2}) ([0-9]{4}) "
r"([0-9]{2}:[0-9]{2}:[0-9]{2}) GMT")
TIME = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z")


def named(name: str):
Expand Down Expand Up @@ -187,6 +195,48 @@ def _record(row: dict, repo: str, branch: str, roles: set, dispatcher: tuple):
return (record, None)


def _time(value) -> bool:
"""Whether `value` is a UTC time to the second on a day the calendar has, as a run record holds one."""
if not (isinstance(value, str) and TIME.fullmatch(value)):
return False
try:
datetime.datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")
except ValueError:
return False
return True


def _began(transport, repo: str, github_id: int, attempt, done: bool) -> tuple:
"""`(found, whole)` from one read of a run's jobs, uncached: `found` is `{"began_at": time}`, the earliest start among the jobs
that are in progress, or completed with a runner named; `{"began_at": None}` for a run that is `done`, every job
of it completed and none begun; and `{}` where it has not begun yet or cannot be read. A job that waits gives its
creation as its start, and one cancelled or skipped while it waited ends with no runner (P-64, P-44): neither is
a start. Not whole: an answer that is no list of every job counted, each once, of the attempt the list gave, its runner a name or none, and in a
status GitHub gives a job, a start that is no time, or a job not yet completed of a run that is, which an answer
older than the list would give."""
answer = transport.send(request("GET", "/repos/%s/actions/runs/%d/jobs?per_page=%d" % (repo, github_id, PAGE),
headers=FRESH))
Comment thread
don-petry marked this conversation as resolved.
Resolved
body = answer["body"] if answer["status"] == 200 and isinstance(answer["body"], dict) else {}
jobs = body.get("jobs")
if not isinstance(jobs, list) or type(body.get("total_count")) is not int or body["total_count"] != len(jobs) \
or len({str(j.get("id")) for j in jobs if isinstance(j, dict)}) != len(jobs) \
or type(attempt) is not int or any(not isinstance(j, dict) or type(j.get("run_attempt")) is not int
or type(j.get("id")) is not int
or j["run_attempt"] != attempt for j in jobs):
return {}, False
if any(not isinstance(j.get("status"), str) or j["status"] not in JOB_STATUSES
or not isinstance(j.get("runner_name"), (str, type(None)))
or (done and j["status"] != "completed") for j in jobs):
return {}, False
starts = [j.get("started_at") for j in jobs if j.get("status") == "in_progress"
or (j.get("status") == "completed" and isinstance(j.get("runner_name"), str) and j["runner_name"] != "")]
if not all(_time(start) for start in starts):
return {}, False
if starts:
return {"began_at": min(starts)}, True
return ({"began_at": None} if done else {}), True


def known(previous: list) -> dict:
"""The outcomes the pass records before this one read, each by its Run id and when its attempt started, from the
records `controller/pass_.earlier` placed before the pass, held to `pass/1` by `controller/reads.previous_records`,
Expand Down Expand Up @@ -222,7 +272,7 @@ def read(record) -> dict:


def runs(transport, repo: str, branch: str, workflows: list, dispatcher: tuple, per_page: int = PAGE,
sleep=time.sleep, kept=None) -> dict:
sleep=time.sleep, kept=None, began=None) -> dict:
"""The run records of the Factory's Role workflows, the ids of counted Runs not yet named, whether the list was
read whole, and each read's date and age for the pass record. `dispatcher` is the pass job's own token's account,
by its id and type, `(id, "Bot")`: only a run it dispatched is a Run.
Expand All @@ -234,12 +284,17 @@ def runs(transport, repo: str, branch: str, workflows: list, dispatcher: tuple,
outcome is listed, downloaded, so the pass record says how many outcomes a pass read. `github_ids` names each Run
id's GitHub runs, which no run record holds, so that `adapters/applied.py` reads a Run's `applied/1` by the one
GitHub run its name names (issue 338). Nothing calls `known` until
the pass's entry, the effects port's next part (#193), hands it the records it placed."""
the pass's entry, the effects port's next part (#193), hands it the records it placed.

`began` is when each Run began as its caller kept it, by its Run id and when its attempt started, and None asks
no job: no record then says when it began. Given, each Run in progress or completed has its jobs read for `began_at` (`_began`), but one `began`
holds, for a row that names when its attempt started, once in this list. A Run past the `JOBS` asked, or whose
jobs cannot be read, has no `began_at` and leaves the list not whole."""
kept = kept or {}
roles = {".github/workflows/%s" % name for name in workflows}

def read() -> tuple:
records, unnamed, reads, whole, failed = [], [], [], True, []
records, unnamed, reads, whole, failed, ran = [], [], [], True, [], []
attempts, ids = {}, {}
for workflow in workflows:
rows, got, complete = _list(transport, repo, workflow, branch, per_page)
Expand All @@ -258,15 +313,18 @@ def read() -> tuple:
ids.setdefault(record["run"], []).append(row["id"])
if record["status"] == "completed" and record["conclusion"] != "success":
failed.append((record, row["id"], bool(row.get("run_started_at"))))
if record["status"] != "queued":
ran.append((record, row["id"], row.get("run_attempt"), bool(row.get("run_started_at"))))
if unidentified is not None:
unnamed.append(unidentified)
return records, unnamed, reads, whole, [(r, i, timed and attempts[(r["run"], r["started_at"])] == 1)
for r, i, timed in failed], ids
for r, i, timed in failed], ids, [
(r, i, attempt, timed and attempts[(r["run"], r["started_at"])] == 1) for r, i, attempt, timed in ran]

records, unnamed, reads, whole, failed, ids = read()
records, unnamed, reads, whole, failed, ids, ran = read()
if unnamed:
sleep(WAIT)
records, unnamed, again, whole, failed, ids = read()
records, unnamed, again, whole, failed, ids, ran = read()
reads += again
for record, github_id, keyed in failed:
if keyed and (record["run"], record["started_at"]) in kept:
Expand All @@ -276,4 +334,19 @@ def read() -> tuple:
transport, repo, github_id, record["run"],
lambda answer: reads.append(dict(read_at(answer), read="outcome")))
whole = whole and read_whole
asked = 0
for record, github_id, attempt, keyed in ran if began is not None else []:
if keyed and (record["run"], record["started_at"]) in began:
record["began_at"] = began[(record["run"], record["started_at"])]
# Null is a completed Run's alone: a list that gives the Run as running still asks its jobs again.
if record["began_at"] is not None or record["status"] == "completed":
continue
del record["began_at"]
if asked == JOBS:
whole = False
continue
asked += 1
found, answered = _began(transport, repo, github_id, attempt, record["status"] == "completed")
record.update(found)
whole = whole and answered
return {"runs": records, "unidentified": unnamed, "complete": whole, "reads": reads, "github_ids": ids}
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# 0193. When a Run began is read from its jobs, trusted only once a job is in progress or ran, and kept by the pass records

Status: accepted. The Factory Builder's ruling of 2026-11-11 on "A record's start is read from its job's started_at, trusted only once the job is in progress or ran (P-64)" (issue 724). It adds one field to the run record and one read to the records port. The pass's keeping of what it read, `begun` and its hand-over, is the pull request that follows this one, and adds its rows below. No rule of the Kernel reads the field yet: the record that has `approval_anchor` read it follows, and closes the residual `docs/decisions/0168-the-simulators-world-dates-an-approval-by-the-acts-run-and-the-kernels-anchor-takes-the-records-always.md` names.

## Decision

| What | Decided | Because |
|---|---|---|
| The field | `began_at`, optional on a run record. `started_at` keeps its meaning, the run's `run_started_at` | The issue asked that `started_at` become the job's start. `controller/pass_.py`'s windows and the kept outcomes' key read `started_at`: a Run that never began, read as starting now, would hold an automatic pause at every pass, and its outcome would never be kept |
| What it says | The earliest `started_at` among the jobs GitHub lists for the run's latest attempt that are `in_progress`, or `completed` with a runner named. A re-run may list a job an earlier attempt ran, with its start, earlier than `started_at`: a start of the same run, and no job of a Run made while another of its item ran began before that one ended. Null for a completed Run whose jobs are all completed and none began. Absent where it has not begun yet, or was not read | `trials/P-64.json`: while a job waits, `pending`, the jobs API gives its creation as its start, as `run_started_at` is the run's creation; in progress, the start is when it began. `trials/P-44.json`: a job cancelled while it waited ends completed with no runner. A Run's jobs stand behind one lane (`trials/P-55.json`), so the first to begin is when the Run left it |
| What is asked | `GET /repos/{repo}/actions/runs/{id}/jobs`, as P-64 asked it but a hundred to a page, uncached, for each Run in progress or completed, and only for a caller that asks (`began`) | A queued Run has no job begun. A caller that does not ask reads as before |
Comment thread
don-petry marked this conversation as resolved.
Resolved
| What is kept | `begun` reads the last two pass records, the earlier's word only for a Run the later does not list: a time for any Run, null for a completed one, by its Run id and when its attempt started, as outcomes are kept. A re-run, a row that names no start of its attempt and a key listed twice are asked afresh | A job's start stood at every read after the first that gave it (P-64), and a completed run's jobs change no more. So a Run is asked from when it is in progress until it has begun, and then no more |
| The cap | No more than 50 Runs are asked in one read (`JOBS`). A Run past the cap has no `began_at`, and the list is not whole | 50 is what a pass reads of passes and of Effects (decision 0190), inside its step's limit. With nothing kept, N Runs are read over N/50 passes, each of which defers every Run; on 2026-11-11 the Factory's repo held 27 |
| Jobs that cannot be read | An answer that is not 200, or no list of every job counted, each once; a job of another attempt than the list gave; a job in a status GitHub gives none, or whose runner is neither a name nor none; a start that is no time; a job not yet completed of a run the list gave as completed, begun or not. Each gives no `began_at` and leaves the list not whole | What cannot be read is said, never guessed. An answer older than the list would otherwise read a Run whose job began and ended inside it as never begun, for good |
| What does not read it yet | No caller asks yet. The pass asks, and keeps, from the pull request that follows this one; the Harness's two reads ask for their own item's Runs from the one after, a person's to approve; the Kernel's reading follows both | A Run reads its item as the pass does. Were the Kernel to read the field before both ask, one reading would lack what the other has |
| The residual | A job outside its item's lane that began before the lane's would give a start that is too early. The Run P-55 recorded has none | The jobs API does not say which jobs a concurrency group holds |
| A completed Run that lists no job | Null, kept for good | Read as unreadable, it would leave the list not whole at every pass. Null admits nothing |

## Why

`run_started_at` is when a run was made. A Run made while another of its item ran waits in the item's lane, and its record says it started when it was made. Decision 0168 names what that leaves open. P-64 asked GitHub when a job that waited began, and it answered: only once the job is in progress, or completed with a runner.

## Boundaries

| Boundary | Check |
|---|---|
| A job in progress, or completed with a runner named, says when its Run began, the earliest of several; one that waits says nothing, and a completed Run none of whose jobs began says null; `started_at` is unchanged; a queued Run, and a caller that asks for none, has no job read; a `began_at` that is no time and not null is no run record | `examples/invalid/run-record.a-beginning-in-words.json`, `schemas/run-record.schema.json`, `tests/test_adapters.py::test_a_run_began_when_a_job_of_it_did`, `adapters/records.py`, `tools/mutants.py`, mutant: "a job that waits says when its Run began", mutant: "a job listed twice is read as two", mutant: "only the first start is held to be a time", mutant: "a run record may not say it never began", mutant: "a job in progress does not say when its Run began", mutant: "a completed job no runner ran says when its Run began", mutant: "a job that waits with a runner named says when its Run began", mutant: "a runner with no name is a runner", mutant: "the last job to begin is when its Run began", mutant: "a completed Run no job of which began says nothing", mutant: "a Run in progress with no job begun never began", mutant: "a Run not yet started is asked for its jobs", mutant: "a caller that asked for no job is read them" |
| Jobs that cannot be read give no start and leave the list not whole, and each read is uncached | `tests/test_adapters.py::test_jobs_that_cannot_be_read_say_no_start`, `adapters/records.py`, `tools/mutants.py`, mutant: "a job not yet completed of a completed run is read", mutant: "a job in a status GitHub gives none is read as one that waits", mutant: "a runner that is no name is no runner", mutant: "jobs GitHub did not answer are read", mutant: "jobs listed short of their count are read", mutant: "a count of jobs that is no number is read", mutant: "another attempt's jobs are read", mutant: "a job whose attempt is no number is its run's", mutant: "a job whose id is no number is read", mutant: "jobs are read for an attempt that cannot be read", mutant: "a job's start that is no time is a start", mutant: "a start on no day of the calendar is a time", mutant: "a time in another form is a time", mutant: "more jobs than their count are read", mutant: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached", mutant: "a run's jobs are asked thirty to a page" |
| What a pass record holds is not asked again, but for a re-run, a row with no start of its attempt and a key listed twice; no more than the cap are asked, and the rest leave the list not whole | `tests/test_adapters.py::test_when_a_run_began_is_asked_once_and_kept`, `adapters/records.py`, `tools/mutants.py`, mutant: "jobs are asked for the first read's rows after a second", mutant: "when a Run began is asked again though kept", mutant: "when a Run began is kept across attempts", mutant: "null kept is said of a Run the list gives as running still", mutant: "null kept stays on a Run the list gives as running still, if its jobs say nothing", mutant: "a time kept for a Run in progress is asked again", mutant: "the cap ends the saying of what was kept", mutant: "the cap on jobs reads is another", mutant: "a Run whose jobs are read makes the list whole again after one whose are not", mutant: "a row that names no start of its attempt keeps when it began", mutant: "a Run listed twice keeps when it began", mutant: "more Runs than the cap are asked for their jobs", mutant: "Runs past the cap leave the list whole" |
16 changes: 16 additions & 0 deletions examples/invalid/run-record.a-beginning-in-words.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"run": "r_01JA6Z",
"item": {
"repo": "combsmith/software-factory",
"type": "pull_request",
"number": 42
},
"role": "pr-review",
"intent": "review-change",
"content_id": "sha256:5d0c",
"status": "completed",
"conclusion": "success",
"outcome": null,
"started_at": "2026-10-11T12:05:00Z",
"began_at": "once its lane was free"
}
3 changes: 2 additions & 1 deletion examples/run-record.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,5 +11,6 @@
"status": "completed",
"conclusion": "success",
"outcome": null,
"started_at": "2026-10-11T12:05:00Z"
"started_at": "2026-10-11T12:05:00Z",
"began_at": "2026-10-11T12:05:04Z"
}
8 changes: 8 additions & 0 deletions schemas/run-record.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,14 @@
"type": "string",
"pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]Z$"
},
"began_at": {
"description": "When it began: the earliest started_at among the jobs GitHub lists for its latest attempt that are in progress, or completed with a runner named, which a job that waits in its item's lane does not give (trials/P-64.json). A re-run may list a job an earlier attempt ran, so it may be earlier than started_at. Null for a completed Run none of whose jobs began. Absent where it has not begun yet or its jobs were not read: it is then no record that began before anything (decision 0193)",
"type": [
"string",
"null"
],
"pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]Z$"
Comment thread
don-petry marked this conversation as resolved.
Resolved
},
"never_ran": {
"description": "Present where GitHub started no job of this Run, in GitHub's word: `startup_failure`, or `skipped` on a first attempt. The conclusion is then `cancelled`, as a person's cancel is; this tells them apart. Such Runs count toward the automatic pause (decision 0116).",
"enum": [
Expand Down
Loading
Loading