From ae42a510546fbe70075667c194ff86401f477588 Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 07:12:43 -0600 Subject: [PATCH 01/14] 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 (#724, record 0193) The records port gains began_at, read from the jobs API under P-64's rule, kept by the pass records and capped at 50 Runs a read. started_at keeps its meaning. No rule of the Kernel reads the field yet. Co-Authored-By: Claude --- adapters/records.py | 105 ++++++++++- controller/__main__.py | 5 +- ...ess-or-ran-and-kept-by-the-pass-records.md | 30 ++++ .../run-record.a-beginning-in-words.json | 16 ++ examples/run-record.json | 3 +- schemas/run-record.schema.json | 8 + tests/test_adapters.py | 170 +++++++++++++++++- tests/test_controller.py | 9 + tools/mutants.py | 106 ++++++++++- 9 files changed, 441 insertions(+), 11 deletions(-) create mode 100644 docs/decisions/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.md create mode 100644 examples/invalid/run-record.a-beginning-in-words.json diff --git a/adapters/records.py b/adapters/records.py index b64d6dd3..b84c2f15 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -14,6 +14,13 @@ 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 (trials/P-44.json), and a job's `started_at` is its creation too 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. A start, once given, stands at every later read (P-64), so what the pass records before kept is not +asked again, and no more than `JOBS` Runs are asked in one read: what is left unasked leaves the list not whole. """ from __future__ import annotations @@ -29,6 +36,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. @@ -50,6 +58,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): @@ -187,6 +196,65 @@ 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(answer: dict, attempt, done: bool) -> tuple: + """`(found, whole)` from one read of a run's jobs: `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 of the attempt the list gave, 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.""" + 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 type(attempt) is not int or any(not isinstance(j, dict) or j.get("run_attempt") != attempt 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 + if not done: + return {}, True + return ({"began_at": None}, True) if all(j.get("status") == "completed" for j in jobs) else ({}, False) + + +def begun(previous: list) -> dict: + """When each Run began, as the pass records before this one read it from its jobs, by its Run id and when its + attempt started: the last two at most, the later's word where both give one. A time is kept for any Run, since a + job's start stands once given (P-64), and null for a completed Run alone, whose jobs change no more. A key a + record lists twice is kept from neither listing, and nothing is kept from a record that is not a `pass/1` + record's runs. A re-run starts again, at another time, and is asked afresh.""" + def read(record) -> dict: + runs_ = record.get("runs") if isinstance(record, dict) else None + if not isinstance(runs_, list): + return {} + found, listed = {}, [] + for r in runs_: + key = (r.get("run"), r.get("started_at")) if isinstance(r, dict) else (None, None) + if not all(isinstance(part, str) for part in key): + continue + listed.append(key) + if "began_at" in r and (_time(r["began_at"]) or (r["began_at"] is None and r.get("status") == "completed")): + found[key] = r["began_at"] + return {key: found[key] for key in found if listed.count(key) == 1} + kept = {} + for record in (list(previous[-2:]) if isinstance(previous, list) else []): + kept.update(read(record)) + return kept + + 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`, @@ -222,7 +290,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, on=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. @@ -234,12 +302,18 @@ 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 what `begun` read from the pass records before, 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; `on`, an item, asks only that item's + Runs, as a Run reading its own item does. 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) @@ -258,15 +332,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: @@ -276,4 +353,20 @@ 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 on is not None and record["item"] != on: + continue + if keyed and (record["run"], record["started_at"]) in began: + record["began_at"] = began[(record["run"], record["started_at"])] + continue + if asked == JOBS: + whole = False + continue + asked += 1 + found, answered = _began( + transport.send(request("GET", "/repos/%s/actions/runs/%d/jobs" % (repo, github_id), headers=FRESH)), + attempt, record["status"] == "completed") + record.update(found) + whole = whole and answered return {"runs": records, "unidentified": unnamed, "complete": whole, "reads": reads, "github_ids": ids} diff --git a/controller/__main__.py b/controller/__main__.py index 4fd3d8e0..6a8c986d 100644 --- a/controller/__main__.py +++ b/controller/__main__.py @@ -152,9 +152,10 @@ def read(transport, config: dict, run_id: str, previous, now: str, clock, starte """Everything the pass reads after the wait, as `pass_.run` takes it.""" controller = config["controller"] home, branch = controller["home"]["repo"], controller["home"]["branch"] - kept = records.known(pass_.earlier(reads_.previous_records(previous), now) or []) + earlier = pass_.earlier(reads_.previous_records(previous), now) or [] try: - runs = records.runs(transport, home, branch, run_files(controller), dispatcher(controller), kept=kept) + runs = records.runs(transport, home, branch, run_files(controller), dispatcher(controller), + kept=records.known(earlier), began=records.begun(earlier)) except Unanswered: runs = None try: diff --git a/docs/decisions/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.md b/docs/decisions/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.md new file mode 100644 index 00000000..7a51f86c --- /dev/null +++ b/docs/decisions/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.md @@ -0,0 +1,30 @@ +# 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 issue 724, "A record's start is read from its job's started_at, trusted only once the job is in progress or ran (P-64)". It adds one field to the run record and one read to the records port. 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 be recent at every pass, so an automatic pause it held would never lapse, and its key would move at every pass | +| What it says | The earliest `started_at` among the jobs of the run's latest attempt that are `in_progress`, or `completed` with a runner named. 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, uncached, for each Run in progress or completed, and only for a caller that asks (`began`). `on` names one item, whose Runs alone are asked | A queued Run has no job begun. A caller that does not ask reads as before. A Run that reads its own item needs that item's records alone | +| What is kept | `begun` reads the last two pass records, the later's word standing: 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; a job of another attempt than the list gave; a start that is no time; a job not yet completed of a run the list gave as completed. 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 | The Kernel, and the Harness's two reads of the records, which ask for no job. A pull request of its own, a person's to approve, has them ask for their item's; the Kernel's reading follows that | A Run reads its item as the pass does. Were the Kernel to read the field first, a Run's reading would lack what the pass's 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 | + +## 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 in progress does not say when its Run began", mutant: "a completed job no runner ran 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 still waiting of a completed run is read as never begun", 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: "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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | +| 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; `on` asks one item's Runs alone | `tests/test_adapters.py::test_when_a_run_began_is_asked_once_and_kept`, `adapters/records.py`, `tools/mutants.py`, mutant: "when a Run began is asked again though kept", mutant: "when a Run began is kept across attempts", 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", mutant: "the cap on jobs reads is another", mutant: "another item's Runs are asked for their jobs" | +| `begun` keeps a time for any Run and null for a completed one alone, from the last two records, the later's word standing, and nothing from a key listed twice or a record that names no Run or no start | `tests/test_adapters.py::test_when_a_run_began_is_asked_once_and_kept`, `adapters/records.py`, `tools/mutants.py`, mutant: "null is kept for a Run still in progress", mutant: "a beginning that is no time is kept", mutant: "a beginning a record lists twice is kept", mutant: "a beginning is kept for a record that names no Run or no start", mutant: "every record's beginnings are read, not the last two", mutant: "the earlier record's beginning stands over the later's" | +| The pass hands the records port what the records before kept | `tests/test_controller.py::test_the_entry_gathers_what_reconciliation_reads`, `controller/__main__.py`, `tools/mutants.py`, mutant: "the entry asks the records port no job" | diff --git a/examples/invalid/run-record.a-beginning-in-words.json b/examples/invalid/run-record.a-beginning-in-words.json new file mode 100644 index 00000000..cb981a33 --- /dev/null +++ b/examples/invalid/run-record.a-beginning-in-words.json @@ -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" +} diff --git a/examples/run-record.json b/examples/run-record.json index f5fc1953..acde864b 100644 --- a/examples/run-record.json +++ b/examples/run-record.json @@ -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" } diff --git a/schemas/run-record.schema.json b/schemas/run-record.schema.json index 45be4401..3c70c8f9 100644 --- a/schemas/run-record.schema.json +++ b/schemas/run-record.schema.json @@ -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 its latest attempt began: the earliest started_at among its jobs 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). 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$" + }, "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": [ diff --git a/tests/test_adapters.py b/tests/test_adapters.py index dc5125f4..21840a33 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1041,11 +1041,22 @@ def stored(repo: str, github_id: int, zipped, ident: int = 9, store: str = STORE return found +def jobs_read(name: str, at: int, github_id: int, **change) -> dict: + """A fixture's read of a run's jobs, asked of the run GitHub numbers `github_id`, each job changed as named.""" + found = copy.deepcopy(exchanges(name)[at]) + words = found["request"]["call"].split() + found["request"]["call"] = " ".join([words[0], "/repos/%s/actions/runs/%d/jobs" % (canary(), github_id)] + words[2:]) + for job in found["response"]["body"]["jobs"]: + job.update(change) + return found + + class Records(unittest.TestCase): def read(self, *found, **kw): slept = [] got = records.runs(github.Replay(list(found)), canary(), "main", [WORKFLOW], kw.get("dispatcher", DISPATCHER), - per_page=kw.get("per_page", 10), sleep=slept.append, kept=kw.get("kept")) + per_page=kw.get("per_page", 10), sleep=slept.append, kept=kw.get("kept"), + began=kw.get("began"), on=kw.get("on")) return got, slept def test_a_run_listed_under_its_workflows_name_is_unidentified_after_one_more_read(self): @@ -1290,6 +1301,163 @@ def record(got): self.assertEqual((records.known(None), records.known(record(first)), records.known([{"runs": None}]), records.known([{"runs": ["x"]}])), ({}, {}, {}, {})) + def began(self, status, *jobs, **kw): + """`(the one record, whether the list was whole)` of a Run GitHub lists with `status`, its jobs read as given.""" + row = listing("P-17", 3, rows=dict({"name": NAME, "status": status, "run_attempt": 1, + "conclusion": "success" if status == "completed" else None}, + **kw.get("rows", {}))) + got, _ = self.read(row, *jobs, began=kw.get("began", {})) + return got["runs"][0], got["complete"] + + def test_a_run_began_when_a_job_of_it_did(self): + # trials/P-64.json: the second run's job waited 53 s in its lane. While it waited, `pending`, the jobs API gave + # its `started_at` as its creation, as the run's `run_started_at` is at every read; once in progress, and + # completed, it gave 19:44:48Z. trials/P-44.json: a job cancelled while it waited ends completed with no + # runner, its `started_at` its creation still. So only a job in progress, or completed with a runner named, + # says when its Run began (decision 0193). + gid = exchanges("P-17")[3]["response"]["body"]["workflow_runs"][0]["id"] + waiting, running, ran = (exchanges("P-64")[at]["response"]["body"]["jobs"][0] for at in (9, 18, 33)) + gone = exchanges("P-44")[23]["response"]["body"]["jobs"][0] + self.assertEqual([(j["status"], j["started_at"] == j["created_at"], bool(j["runner_name"])) + for j in (waiting, running, ran, gone)], + [("pending", True, False), ("in_progress", False, True), ("completed", False, True), + ("completed", True, False)]) + self.assertEqual((running["started_at"], ran["started_at"]), ("2026-11-10T19:44:48Z",) * 2) + # The four sides: pending, nothing yet; in progress and completed with a runner, the job's start; completed + # with none, null, since it never began. `started_at` stays the run's own, as every other reader takes it. + record, whole = self.began("in_progress", jobs_read("P-64", 9, gid)) + self.assertEqual(("began_at" in record, whole), (False, True)) + for status, at in (("in_progress", 18), ("completed", 33)): + record, whole = self.began(status, jobs_read("P-64", at, gid)) + self.assertEqual((record["began_at"], record["started_at"], whole), + ("2026-11-10T19:44:48Z", "2026-10-18T01:29:07Z", True), status) + record, whole = self.began("completed", jobs_read("P-44", 23, gid)) + self.assertEqual((record["began_at"], whole), (None, True)) + # A runner's name alone tells a completed job that ran, and a job in progress needs none. + for name in ("", None, 7): + self.assertEqual(self.began("completed", jobs_read("P-64", 33, gid, runner_name=name)), (record, True), name) + self.assertEqual(self.began("in_progress", jobs_read("P-64", 18, gid, runner_name=None))[0]["began_at"], + "2026-11-10T19:44:48Z") + # Of several jobs, the earliest that began; one that waits beside it says nothing. + both = jobs_read("P-64", 33, gid) + both["response"]["body"].update(total_count=3, jobs=[ + dict(ran, started_at="2026-11-10T19:45:00Z"), ran, dict(waiting, started_at="2026-11-10T19:40:00Z")]) + self.assertEqual(self.began("in_progress", both)[0]["began_at"], "2026-11-10T19:44:48Z") + # A Run not yet started, or a caller that asks for none, has no job read: the replay holds no answer to one. + record, whole = self.began("queued") + self.assertEqual(("began_at" in record, whole), (False, True)) + record, whole = self.began("completed", began=None) + self.assertEqual(("began_at" in record, whole), (False, True)) + + def test_jobs_that_cannot_be_read_say_no_start(self): + gid = exchanges("P-17")[3]["response"]["body"]["workflow_runs"][0]["id"] + sent = Recording(github.Replay([listing("P-17", 3, rows={"name": NAME, "status": "in_progress"}), + jobs_read("P-64", 18, gid)])) + records.runs(sent, canary(), "main", [WORKFLOW], DISPATCHER, per_page=10, began={}) + self.assertEqual((sent.sent[1]["path"], sent.sent[1]["headers"]), + ("/repos/%s/actions/runs/%d/jobs" % (canary(), gid), {"Cache-Control": "no-cache"})) + + def changed(at, **change): + found = jobs_read("P-64", at, gid) + found["response"].update({k: v for k, v in change.items() if k in ("status",)}) + found["response"]["body"].update({k: v for k, v in change.items() if k != "status"}) + return found + # An answer that is no list of every job counted, a job of another attempt than the list gave or one that is + # no job, a start that is no time, and a job still waiting of a run the list gave as completed. + for status, found, rows in ( + ("in_progress", changed(18, status=404), {}), ("in_progress", changed(18, total_count=2), {}), + ("in_progress", changed(18, total_count=True), {}), ("in_progress", changed(18, jobs=None), {}), + ("in_progress", changed(18, jobs=["lane"], total_count=1), {}), + ("in_progress", jobs_read("P-64", 18, gid, run_attempt=2), {}), + ("in_progress", jobs_read("P-64", 18, gid), {"run_attempt": True}), + ("in_progress", jobs_read("P-64", 18, gid), {"run_attempt": None}), + ("in_progress", jobs_read("P-64", 18, gid, started_at="2026-11-10 19:44:48"), {}), + ("in_progress", jobs_read("P-64", 18, gid, started_at="2026-02-30T19:44:48Z"), {}), + ("completed", jobs_read("P-64", 33, gid, started_at=None), {}), + ("completed", jobs_read("P-64", 9, gid), {})): + record, whole = self.began(status, found, rows=rows) + self.assertEqual(("began_at" in record, whole), (False, False), (status, found["response"], rows)) + found = jobs_read("P-64", 18, gid) + found["response"]["body"] = ["lane"] + self.assertEqual(self.began("in_progress", found)[1], False) + # A completed run with no job at all never began; one in progress has not yet. + self.assertEqual(self.began("completed", changed(33, jobs=[], total_count=0)), (dict( + self.began("completed", jobs_read("P-44", 23, gid))[0]), True)) + record, whole = self.began("in_progress", changed(18, jobs=[], total_count=0)) + self.assertEqual(("began_at" in record, whole), (False, True)) + + def test_when_a_run_began_is_asked_once_and_kept(self): + # A job's start stands at every read after the first that gives it (P-64, part 3), and a completed run's + # jobs change no more: what a pass record holds is not asked again. A Run that has not begun is asked again. + rows = listing("P-17", 3, rows={"status": "completed", "conclusion": "success", "run_attempt": 1}) + template = rows["response"]["body"]["workflow_runs"][0] + names = [NAME.replace("r_01JA6Z", "r_%06dZ" % n) for n in range(4)] + rows["response"]["body"].update(total_count=4, workflow_runs=[ + dict(template, id=700 + n, name=names[n], run_started_at="2026-10-21T0%d:00:00Z" % n) for n in range(4)]) + rows["response"]["body"]["workflow_runs"][2].update(status="in_progress", conclusion=None) + rows["response"]["body"]["workflow_runs"][3].update(status="in_progress", conclusion=None) + jobs = [jobs_read("P-64", 33, 700), jobs_read("P-44", 23, 701), jobs_read("P-64", 18, 702), + jobs_read("P-64", 9, 703)] + began = ["2026-11-10T19:44:48Z", None, "2026-11-10T19:44:48Z"] + + def record(got): + return {"runs": got["runs"]} + + def read(*found, **kw): + """What a read gave, and the runs whose jobs it asked for, by GitHub's id, in order.""" + sent = Recording(github.Replay(list(found))) + got = records.runs(sent, canary(), "main", [WORKFLOW], DISPATCHER, per_page=10, **kw) + return got, [int(r["path"].split("/")[-2]) for r in sent.sent if r["path"].endswith("/jobs")] + first, asked = read(rows, *jobs, began={}) + self.assertEqual(([r.get("began_at", "none") for r in first["runs"]], first["complete"], asked), + (began + ["none"], True, [700, 701, 702, 703])) + kept = records.begun([record(first)]) + self.assertEqual(kept, {("r_%06dZ" % n, "2026-10-21T0%d:00:00Z" % n): began[n] for n in range(3)}) + second, asked = read(rows, jobs[3], began=kept) + self.assertEqual((second["runs"], asked), (first["runs"], [703])) + # A re-run starts again, at another time, and a row that names no start of its attempt, or a key listed twice, + # is asked whatever is kept. + rerun = copy.deepcopy(rows) + rerun["response"]["body"]["workflow_runs"][0]["run_started_at"] = "2026-10-21T09:00:00Z" + self.assertEqual(read(rerun, jobs[0], jobs[3], began=kept)[1], [700, 703]) + untimed = copy.deepcopy(rows) + untimed["response"]["body"]["workflow_runs"][0].update(run_started_at=None, created_at="2026-10-21T00:00:00Z") + self.assertEqual(read(untimed, jobs[0], jobs[3], began=kept)[1], [700, 703]) + twice = copy.deepcopy(rows) + twice["response"]["body"]["workflow_runs"][1] = dict(twice["response"]["body"]["workflow_runs"][0], id=799) + self.assertEqual(read(twice, jobs[0], jobs_read("P-64", 33, 799), jobs[3], began=kept)[1], [700, 799, 703]) + # No more than the cap are asked in one read: the rest say nothing, and the list is not whole until a later + # read, with what this one kept, has asked them. + with mock.patch.object(records, "JOBS", 2): + capped, asked = read(rows, jobs[0], jobs[1], began={}) + self.assertEqual(([r.get("began_at", "none") for r in capped["runs"]], capped["complete"], asked), + (began[:2] + ["none", "none"], False, [700, 701])) + rest, asked = read(rows, jobs[2], jobs[3], began=records.begun([record(capped)])) + self.assertEqual((rest["runs"], rest["complete"], asked), (first["runs"], True, [702, 703])) + self.assertEqual(records.JOBS, 50) + # Asked of one item's Runs alone, as a Run reading its own item asks: another item's say nothing, and are no + # part of the read. + other = copy.deepcopy(rows) + other["response"]["body"]["workflow_runs"][0]["name"] = names[0].replace("#264", "#265") + got, asked = read(other, jobs[1], jobs[2], jobs[3], began={}, on=first["runs"][1]["item"]) + self.assertEqual(([r.get("began_at", "none") for r in got["runs"]], got["complete"], asked), + (["none"] + began[1:] + ["none"], True, [701, 702, 703])) + # The last two records are read, the later's word standing; null is kept for a completed Run alone, and + # nothing from a key a record lists twice, a start that is no time, or what is no pass record's runs. + one = first["runs"][0] + older, newer = {"runs": [dict(one, began_at="2026-11-10T00:00:00Z")]}, {"runs": [one]} + key = (one["run"], one["started_at"]) + self.assertEqual((records.begun([older, newer])[key], records.begun([newer, older])[key], + records.begun([older, newer, {"runs": []}])), (began[0], "2026-11-10T00:00:00Z", {key: began[0]})) + self.assertEqual(records.begun([older, {"runs": []}, {"runs": []}]), {}) + for change in ({"began_at": None, "status": "in_progress"}, {"began_at": "soon"}, {"began_at": 7}, + {"began_at": "2026-02-30T00:00:00Z"}, {"run": None}, {"started_at": None}): + self.assertEqual(records.begun([{"runs": [dict(one, **change)]}]), {}, change) + self.assertEqual(records.begun([{"runs": [{k: v for k, v in one.items() if k != "began_at"}]}]), {}) + self.assertEqual(records.begun([{"runs": [one, dict(one, began_at=None)]}]), {}) + self.assertEqual((records.begun(None), records.begun(record(first)), records.begun([{"runs": None}]), + records.begun([{"runs": ["x"]}]), records.begun(["x"])), ({}, {}, {}, {}, {})) + def test_a_status_or_a_conclusion_github_would_not_give_a_run_makes_the_list_short(self): self.assertEqual(self.read(listing("P-17", 3, rows={"name": NAME, "status": "waiting"}))[0]["runs"][0]["status"], "queued") diff --git a/tests/test_controller.py b/tests/test_controller.py index 16f2bfe6..3fb9c241 100644 --- a/tests/test_controller.py +++ b/tests/test_controller.py @@ -1154,6 +1154,13 @@ def written_read(transport, repo, branch, poller, own, since, known): served = [dict(before["pull_requests"][0], facts=dict(before["pull_requests"][0]["facts"], item=dict( before["pull_requests"][0]["facts"]["item"], number=n))) for n in (7, 9)] before["pull_requests"] = served + # When a Run began, as the record before read it from its jobs, is handed to the records port (decision 0193). + before["runs"][0]["began_at"] = "2026-10-11T12:05:04Z" + listed = entry.records.runs + + def runs(*args, **kw): + efforts["began"] = kw["began"] + return listed(*args, **kw) before["reconciled"] = {"runs": [{"id": "r_01JA00", "at": "2026-10-12T11:00:00Z"}], "passes": [{"id": 40, "attempt": 1, "at": "2026-10-12T11:00:00Z"}], "keys": [], "items": [], "dispatched": [], "owed": [11]} @@ -1169,9 +1176,11 @@ def written_read(transport, repo, branch, poller, own, since, known): unittest.mock.patch.object(entry.passes, "records", lambda *a: [older, before]), \ unittest.mock.patch.object(entry.seen_, "read", read), unittest.mock.patch.object(entry.seen_, "pushes", pushes), \ unittest.mock.patch.object(entry.applied, "effects", applied_read), \ + unittest.mock.patch.object(entry.records, "runs", runs), \ unittest.mock.patch.object(entry.passes, "written", written_read): code, _, files, _ = self.run_entry(Hub(table)) self.assertEqual(code, 0) + self.assertEqual(efforts["began"], {("r_01JA6Z", "2026-10-11T12:05:00Z"): "2026-10-11T12:05:04Z"}) since = "2026-10-11T06:00:00Z" item = lambda n: {"repo": self.HOME, "type": "pull_request", "number": n} identities, apps = spied[0][2], spied[0][3] diff --git a/tools/mutants.py b/tools/mutants.py index b5bb5212..cd2da200 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -171,6 +171,9 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: STALE = "tests.test_decide.Staleness." SCHEMA_TESTS = "tests.test_tools.Validator." EDITS = "tests.test_adapters.DescriptionEdits." +BEGAN = ("tests.test_adapters.Records.test_a_run_began_when_a_job_of_it_did",) +UNREAD_JOBS = ("tests.test_adapters.Records.test_jobs_that_cannot_be_read_say_no_start",) +BEGUN = ("tests.test_adapters.Records.test_when_a_run_began_is_asked_once_and_kept",) CODES_TESTS = ("tests.test_tools.Examples.test_a_string_that_is_neither_a_code_nor_a_body_is_caught",) ENVELOPE_TESTS = ("tests.test_tools.Examples.test_a_schema_without_its_envelope_is_caught",) FEED_TESTS = ("tests.test_tools.Examples.test_every_reason_that_needs_a_person_says_what_is_asked",) @@ -3455,7 +3458,7 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ' if unnamed:\n sleep(WAIT)\n', ' if False:\n sleep(WAIT)\n', ('tests.test_adapters',)), ("the first read's unnamed runs stand after the second", 'adapters/records.py', - ' records, unnamed, again, whole, failed, ids = read()\n', + ' records, unnamed, again, whole, failed, ids, ran = read()\n', ' again = []\n', ('tests.test_adapters',)), ('a read of runs may be cached', 'adapters/records.py', 'FRESH = {"Cache-Control": "no-cache"}\n', @@ -4330,6 +4333,107 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ('an outcome read is not stamped', 'adapters/records.py', ' lambda answer: reads.append(dict(read_at(answer), read="outcome")))', ' lambda answer: None)', ('tests.test_adapters',)), + # Decision 0193: when a Run began is read from its jobs, under P-64's rule. + ('a job that waits says when its Run began', 'adapters/records.py', + 'if j.get("status") == "in_progress"\n', + 'if j.get("status") in ("in_progress", "pending")\n', BEGAN), + ('a job in progress does not say when its Run began', 'adapters/records.py', + 'if j.get("status") == "in_progress"\n or (', + 'if (', BEGAN), + ('a completed job no runner ran says when its Run began', 'adapters/records.py', + ' and isinstance(j.get("runner_name"), str) and j["runner_name"] != "")]', + ')]', BEGAN), + ('a runner with no name is a runner', 'adapters/records.py', + ' and j["runner_name"] != "")]', + ')]', BEGAN), + ('the last job to begin is when its Run began', 'adapters/records.py', + ' return {"began_at": min(starts)}, True\n', + ' return {"began_at": max(starts)}, True\n', BEGAN), + ('a completed Run no job of which began says nothing', 'adapters/records.py', + ' return ({"began_at": None}, True) if all(', + ' return ({}, True) if all(', BEGAN), + ('a Run in progress with no job begun never began', 'adapters/records.py', + ' if not done:\n return {}, True\n', + '', BEGAN), + ('a Run not yet started is asked for its jobs', 'adapters/records.py', + ' if record["status"] != "queued":\n', + ' if True:\n', BEGAN), + ('a caller that asked for no job is read them', 'adapters/records.py', + ' in ran if began is not None else []:', + ' in ran if began is not None else ran:', BEGAN), + ('a job still waiting of a completed run is read as never begun', 'adapters/records.py', + ' if all(j.get("status") == "completed" for j in jobs) else ({}, False)', + '', UNREAD_JOBS), + ('jobs GitHub did not answer are read', 'adapters/records.py', + ' body = answer["body"] if answer["status"] == 200 and isinstance(answer["body"], dict) else {}\n jobs', + ' body = answer["body"] if isinstance(answer["body"], dict) else {}\n jobs', UNREAD_JOBS), + ('jobs listed short of their count are read', 'adapters/records.py', + ' or body["total_count"] != len(jobs) \\\n', + ' \\\n', UNREAD_JOBS), + ('a count of jobs that is no number is read', 'adapters/records.py', + 'type(body.get("total_count")) is not int or body["total_count"] != len(jobs)', + 'body.get("total_count") != len(jobs)', UNREAD_JOBS), + ("another attempt's jobs are read", 'adapters/records.py', + 'not isinstance(j, dict) or j.get("run_attempt") != attempt for j in jobs', + 'not isinstance(j, dict) for j in jobs', UNREAD_JOBS), + ('jobs are read for an attempt that cannot be read', 'adapters/records.py', + ' or type(attempt) is not int or any(', + ' or any(', UNREAD_JOBS), + ("a job's start that is no time is a start", 'adapters/records.py', + ' if not all(_time(start) for start in starts):\n return {}, False\n', + '', UNREAD_JOBS), + ('a start on no day of the calendar is a time', 'adapters/records.py', + ' try:\n datetime.datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")\n except ValueError:\n return False\n return True\n', + ' return True\n', UNREAD_JOBS), + ('jobs that cannot be read leave the list whole', 'adapters/records.py', + ' record.update(found)\n whole = whole and answered\n', + ' record.update(found)\n', UNREAD_JOBS), + ('a read of jobs may be cached', 'adapters/records.py', + '/jobs" % (repo, github_id), headers=FRESH)),', + '/jobs" % (repo, github_id))),', UNREAD_JOBS), + ('when a Run began is asked again though kept', 'adapters/records.py', + ' if keyed and (record["run"], record["started_at"]) in began:\n', + ' if False:\n', BEGUN), + ('when a Run began is kept across attempts', 'adapters/records.py', + ' if keyed and (record["run"], record["started_at"]) in began:\n record["began_at"] = began[(record["run"], record["started_at"])]\n', + ' if keyed and any(k[0] == record["run"] for k in began):\n record["began_at"] = next(v for k, v in began.items() if k[0] == record["run"])\n', BEGUN), + ('a row that names no start of its attempt keeps when it began', 'adapters/records.py', + '(r, i, attempt, timed and attempts[(r["run"], r["started_at"])] == 1)', + '(r, i, attempt, attempts[(r["run"], r["started_at"])] == 1)', BEGUN), + ('a Run listed twice keeps when it began', 'adapters/records.py', + '(r, i, attempt, timed and attempts[(r["run"], r["started_at"])] == 1)', + '(r, i, attempt, timed)', BEGUN), + ('more Runs than the cap are asked for their jobs', 'adapters/records.py', + ' if asked == JOBS:\n', + ' if False:\n', BEGUN), + ('Runs past the cap leave the list whole', 'adapters/records.py', + ' if asked == JOBS:\n whole = False\n', + ' if asked == JOBS:\n', BEGUN), + ('the cap on jobs reads is another', 'adapters/records.py', + 'JOBS = 50 ', + 'JOBS = 500 ', BEGUN), + ("another item's Runs are asked for their jobs", 'adapters/records.py', + ' if on is not None and record["item"] != on:\n', + ' if False:\n', BEGUN), + ('null is kept for a Run still in progress', 'adapters/records.py', + ' or (r["began_at"] is None and r.get("status") == "completed")):', + ' or r["began_at"] is None):', BEGUN), + ('a beginning that is no time is kept', 'adapters/records.py', + 'if "began_at" in r and (_time(r["began_at"]) or ', + 'if "began_at" in r and (isinstance(r["began_at"], (str, int)) or ', BEGUN), + ('a beginning a record lists twice is kept', 'adapters/records.py', + ' return {key: found[key] for key in found if listed.count(key) == 1}\n', + ' return found\n', BEGUN), + ('a beginning is kept for a record that names no Run or no start', 'adapters/records.py', + ' if not all(isinstance(part, str) for part in key):\n continue\n', + '', BEGUN), + ("every record's beginnings are read, not the last two", 'adapters/records.py', + ' for record in (list(previous[-2:]) if isinstance(previous, list) else []):', + ' for record in (list(previous) if isinstance(previous, list) else []):', BEGUN), + ("the earlier record's beginning stands over the later's", 'adapters/records.py', + ' for record in (list(previous[-2:]) if isinstance(previous, list) else []):', + ' for record in (list(reversed(previous[-2:])) if isinstance(previous, list) else []):', BEGUN), + ('the entry asks the records port no job', 'controller/__main__.py', 'began=records.begun(earlier))', 'began=None)', WIRE_ENTRY), ('an outcome list that cannot be read is not stamped', 'adapters/artifacts.py', ' if seen is not None:\n seen(answer)\n listed, total = answer["body"].get("artifacts"), answer["body"].get("total_count")\n if not isinstance(listed, list) or not isinstance(total, int) or isinstance(total, bool) or total != len(listed):\n return False\n', ' listed, total = answer["body"].get("artifacts"), answer["body"].get("total_count")\n if not isinstance(listed, list) or not isinstance(total, int) or isinstance(total, bool) or total != len(listed):\n return False\n if seen is not None:\n seen(answer)\n', From cb01adbeb110c9ec2f3419bff1e6324fcaeac280 Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 07:37:20 -0600 Subject: [PATCH 02/14] The jobs read is its own function, classed for the token it needs, and the readers' findings are held (#724) Muse, the Claude review and the security pass on e63649f0: the form of a time, a job's own attempt, a runner named on a job that waits, a key the later record lists, the second read's rows, and a re-run's carried-over jobs, said as they are. Co-Authored-By: Claude --- adapters/records.py | 36 ++++++++++-------- ...ess-or-ran-and-kept-by-the-pass-records.md | 14 ++++--- schemas/run-record.schema.json | 2 +- tests/test_adapters.py | 37 ++++++++++++++++++- tests/test_token_needs.py | 3 ++ tools/mutants.py | 29 ++++++++++++--- 6 files changed, 91 insertions(+), 30 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index b84c2f15..f1b1541f 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -18,8 +18,9 @@ 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 (trials/P-44.json), and a job's `started_at` is its creation too 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. A start, once given, stands at every later read (P-64), so what the pass records before kept is not +among the jobs GitHub lists for the latest attempt, null for a completed Run none of whose jobs began, and absent where +it has not begun or was not read. A re-run may list a job an earlier attempt ran, with its start: that is a start of +the same run, and may be earlier than the record's `started_at`. A start, once given, stands at every later read (P-64), so what the pass records before kept is not asked again, and no more than `JOBS` Runs are asked in one read: what is left unasked leaves the list not whole. """ from __future__ import annotations @@ -207,17 +208,19 @@ def _time(value) -> bool: return True -def _began(answer: dict, attempt, done: bool) -> tuple: - """`(found, whole)` from one read of a run's jobs: `found` is `{"began_at": time}`, the earliest start among the jobs +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 of the attempt the list gave, 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" % (repo, github_id), headers=FRESH)) 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 type(attempt) is not int or any(not isinstance(j, dict) or j.get("run_attempt") != attempt for j in jobs): + or type(attempt) is not int or any(not isinstance(j, dict) or type(j.get("run_attempt")) is not int + or j["run_attempt"] != attempt 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"] != "")] @@ -232,14 +235,15 @@ def _began(answer: dict, attempt, done: bool) -> tuple: def begun(previous: list) -> dict: """When each Run began, as the pass records before this one read it from its jobs, by its Run id and when its - attempt started: the last two at most, the later's word where both give one. A time is kept for any Run, since a - job's start stands once given (P-64), and null for a completed Run alone, whose jobs change no more. A key a - record lists twice is kept from neither listing, and nothing is kept from a record that is not a `pass/1` - record's runs. A re-run starts again, at another time, and is asked afresh.""" - def read(record) -> dict: + attempt started: the last two at most, and the earlier's word only for a Run the later does not list. A time is + kept for any Run, since a job's start stands once given (P-64), and null for a completed Run alone, whose jobs + change no more. A key a record lists twice, with a beginning or without, is kept from neither listing, and + nothing is kept from a record that is not a `pass/1` record's runs. A re-run starts again, at another time, and + is asked afresh.""" + def read(record) -> tuple: runs_ = record.get("runs") if isinstance(record, dict) else None if not isinstance(runs_, list): - return {} + return {}, [] found, listed = {}, [] for r in runs_: key = (r.get("run"), r.get("started_at")) if isinstance(r, dict) else (None, None) @@ -248,10 +252,12 @@ def read(record) -> dict: listed.append(key) if "began_at" in r and (_time(r["began_at"]) or (r["began_at"] is None and r.get("status") == "completed")): found[key] = r["began_at"] - return {key: found[key] for key in found if listed.count(key) == 1} + return {key: found[key] for key in found if listed.count(key) == 1}, listed kept = {} for record in (list(previous[-2:]) if isinstance(previous, list) else []): - kept.update(read(record)) + found, listed = read(record) + kept = {key: kept[key] for key in kept if key not in listed} + kept.update(found) return kept @@ -364,9 +370,7 @@ def read() -> tuple: whole = False continue asked += 1 - found, answered = _began( - transport.send(request("GET", "/repos/%s/actions/runs/%d/jobs" % (repo, github_id), headers=FRESH)), - attempt, record["status"] == "completed") + 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} diff --git a/docs/decisions/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.md b/docs/decisions/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.md index 7a51f86c..58df3022 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -7,13 +7,15 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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 be recent at every pass, so an automatic pause it held would never lapse, and its key would move at every pass | -| What it says | The earliest `started_at` among the jobs of the run's latest attempt that are `in_progress`, or `completed` with a runner named. 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 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, so it may be earlier than `started_at`: it is a start of the same run all the same, and no job of a Run made while another of its item ran began before that one ended, at any attempt. 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, uncached, for each Run in progress or completed, and only for a caller that asks (`began`). `on` names one item, whose Runs alone are asked | A queued Run has no job begun. A caller that does not ask reads as before. A Run that reads its own item needs that item's records alone | -| What is kept | `begun` reads the last two pass records, the later's word standing: 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 | +| 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; a job of another attempt than the list gave; a start that is no time; a job not yet completed of a run the list gave as completed. 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 | The Kernel, and the Harness's two reads of the records, which ask for no job. A pull request of its own, a person's to approve, has them ask for their item's; the Kernel's reading follows that | A Run reads its item as the pass does. Were the Kernel to read the field first, a Run's reading would lack what the pass's 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, whatever it concluded | Read as unreadable, a Run GitHub never lists a job for would leave the list not whole at every pass. Null drops one record that could have dated an approval, and admits nothing | +| No stamp | A jobs read leaves no date and no age in the pass record | Nothing acts on a read's age. An answer older than the list reads as not begun yet or as unread, but for the row above | ## Why @@ -23,8 +25,8 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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 in progress does not say when its Run began", mutant: "a completed job no runner ran 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 still waiting of a completed run is read as never begun", 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: "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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | -| 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; `on` asks one item's Runs alone | `tests/test_adapters.py::test_when_a_run_began_is_asked_once_and_kept`, `adapters/records.py`, `tools/mutants.py`, mutant: "when a Run began is asked again though kept", mutant: "when a Run began is kept across attempts", 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", mutant: "the cap on jobs reads is another", mutant: "another item's Runs are asked for their jobs" | -| `begun` keeps a time for any Run and null for a completed one alone, from the last two records, the later's word standing, and nothing from a key listed twice or a record that names no Run or no start | `tests/test_adapters.py::test_when_a_run_began_is_asked_once_and_kept`, `adapters/records.py`, `tools/mutants.py`, mutant: "null is kept for a Run still in progress", mutant: "a beginning that is no time is kept", mutant: "a beginning a record lists twice is kept", mutant: "a beginning is kept for a record that names no Run or no start", mutant: "every record's beginnings are read, not the last two", mutant: "the earlier record's beginning stands over the later's" | +| 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 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 still waiting of a completed run is read as never begun", 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: "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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | +| 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; `on` asks one item's Runs alone | `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: "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", mutant: "the cap on jobs reads is another", mutant: "another item's Runs are asked for their jobs" | +| `begun` keeps a time for any Run and null for a completed one alone, from the last two records, the earlier's word only for a Run the later does not list, and nothing from a key listed twice or a record that names no Run or no start | `tests/test_adapters.py::test_when_a_run_began_is_asked_once_and_kept`, `adapters/records.py`, `tools/mutants.py`, mutant: "null is kept for a Run still in progress", mutant: "a beginning that is no time is kept", mutant: "a beginning a record lists twice is kept", mutant: "a beginning is kept for a record that names no Run or no start", mutant: "the earlier record's beginning stands for a Run the later lists", mutant: "a key listed twice counts only its listings that give a beginning", mutant: "every record's beginnings are read, not the last two", mutant: "the earlier record's beginning stands over the later's" | | The pass hands the records port what the records before kept | `tests/test_controller.py::test_the_entry_gathers_what_reconciliation_reads`, `controller/__main__.py`, `tools/mutants.py`, mutant: "the entry asks the records port no job" | diff --git a/schemas/run-record.schema.json b/schemas/run-record.schema.json index 3c70c8f9..b5ac8247 100644 --- a/schemas/run-record.schema.json +++ b/schemas/run-record.schema.json @@ -67,7 +67,7 @@ "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 its latest attempt began: the earliest started_at among its jobs 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). 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)", + "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" diff --git a/tests/test_adapters.py b/tests/test_adapters.py index 21840a33..182bc7eb 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1338,6 +1338,10 @@ def test_a_run_began_when_a_job_of_it_did(self): self.assertEqual(self.began("completed", jobs_read("P-64", 33, gid, runner_name=name)), (record, True), name) self.assertEqual(self.began("in_progress", jobs_read("P-64", 18, gid, runner_name=None))[0]["began_at"], "2026-11-10T19:44:48Z") + # A runner named on a job that still waits, which no trial has shown, is no start either. + for status in ("pending", "queued"): + record, whole = self.began("in_progress", jobs_read("P-64", 9, gid, status=status, runner_name="GitHub Actions 7")) + self.assertEqual(("began_at" in record, whole), (False, True), status) # Of several jobs, the earliest that began; one that waits beside it says nothing. both = jobs_read("P-64", 33, gid) both["response"]["body"].update(total_count=3, jobs=[ @@ -1369,10 +1373,13 @@ def changed(at, **change): ("in_progress", changed(18, total_count=True), {}), ("in_progress", changed(18, jobs=None), {}), ("in_progress", changed(18, jobs=["lane"], total_count=1), {}), ("in_progress", jobs_read("P-64", 18, gid, run_attempt=2), {}), + ("in_progress", jobs_read("P-64", 18, gid, run_attempt=True), {}), + ("in_progress", jobs_read("P-64", 18, gid, run_attempt=1.0), {}), ("in_progress", jobs_read("P-64", 18, gid), {"run_attempt": True}), ("in_progress", jobs_read("P-64", 18, gid), {"run_attempt": None}), ("in_progress", jobs_read("P-64", 18, gid, started_at="2026-11-10 19:44:48"), {}), ("in_progress", jobs_read("P-64", 18, gid, started_at="2026-02-30T19:44:48Z"), {}), + ("in_progress", jobs_read("P-64", 18, gid, started_at="2026-11-10T19:44:8Z"), {}), ("completed", jobs_read("P-64", 33, gid, started_at=None), {}), ("completed", jobs_read("P-64", 9, gid), {})): record, whole = self.began(status, found, rows=rows) @@ -1426,6 +1433,27 @@ def read(*found, **kw): twice = copy.deepcopy(rows) twice["response"]["body"]["workflow_runs"][1] = dict(twice["response"]["body"]["workflow_runs"][0], id=799) self.assertEqual(read(twice, jobs[0], jobs_read("P-64", 33, 799), jobs[3], began=kept)[1], [700, 799, 703]) + # A list read a second time, for a run not yet named, is asked by the second read's rows, whose records + # are the ones returned: a Run in progress only by then is asked, and says when it began. + early, late = copy.deepcopy(rows), copy.deepcopy(rows) + for found in (early, late): + found["response"]["body"]["workflow_runs"].append(dict(template, id=704, name="not yet named", status="queued", + conclusion=None)) + found["response"]["body"]["total_count"] = 5 + early["response"]["body"]["workflow_runs"][2].update(status="queued") + got, asked = read(early, late, *jobs, began={}, sleep=lambda s: None) + self.assertEqual(([r.get("began_at", "none") for r in got["runs"]], asked), + (began + ["none"], [700, 701, 702, 703])) + # A re-run of some jobs lists the others as an earlier attempt ran them, under the new attempt and with their + # old starts (seen on runs of this repo and the canary, in no trial): the earliest is a start of the same run, + # before the attempt's own, and is what the record says. + carried = jobs_read("P-64", 33, 700) + carried["response"]["body"].update(total_count=2, jobs=[ + dict(exchanges("P-64")[33]["response"]["body"]["jobs"][0], started_at="2026-10-20T23:50:00Z"), + dict(exchanges("P-64")[9]["response"]["body"]["jobs"][0])]) + got, _ = read(rows, carried, *jobs[1:], began={}) + self.assertEqual((got["runs"][0]["began_at"], got["runs"][0]["started_at"]), + ("2026-10-20T23:50:00Z", "2026-10-21T00:00:00Z")) # No more than the cap are asked in one read: the rest say nothing, and the list is not whole until a later # read, with what this one kept, has asked them. with mock.patch.object(records, "JOBS", 2): @@ -1450,8 +1478,15 @@ def read(*found, **kw): self.assertEqual((records.begun([older, newer])[key], records.begun([newer, older])[key], records.begun([older, newer, {"runs": []}])), (began[0], "2026-11-10T00:00:00Z", {key: began[0]})) self.assertEqual(records.begun([older, {"runs": []}, {"runs": []}]), {}) + # The earlier record's word stands only for a Run the later does not list: one the later lists with no + # beginning, or twice, is asked afresh. + bare = {k: v for k, v in one.items() if k != "began_at"} + self.assertEqual((records.begun([older, {"runs": []}]), records.begun([older, {"runs": [bare]}]), + records.begun([older, {"runs": [one, one]}]), records.begun([{"runs": [one, bare]}])), + ({key: "2026-11-10T00:00:00Z"}, {}, {}, {})) for change in ({"began_at": None, "status": "in_progress"}, {"began_at": "soon"}, {"began_at": 7}, - {"began_at": "2026-02-30T00:00:00Z"}, {"run": None}, {"started_at": None}): + {"began_at": "2026-02-30T00:00:00Z"}, {"began_at": "2026-2-3T1:2:3Z"}, {"run": None}, + {"started_at": None}): self.assertEqual(records.begun([{"runs": [dict(one, **change)]}]), {}, change) self.assertEqual(records.begun([{"runs": [{k: v for k, v in one.items() if k != "began_at"}]}]), {}) self.assertEqual(records.begun([{"runs": [one, dict(one, began_at=None)]}]), {}) diff --git a/tests/test_token_needs.py b/tests/test_token_needs.py index 2492134c..4d4fc740 100644 --- a/tests/test_token_needs.py +++ b/tests/test_token_needs.py @@ -53,6 +53,7 @@ class of `adapters/`, the Harness and the Controller that it calls, to each func "adapters.queue.pull": {"pull_requests": R}, "adapters.queue.threads": {"pull_requests": R}, "adapters.queue.queued": {"pull_requests": R}, "adapters.queue.enqueue": {"contents": W}, "adapters.queue.dequeue": {"contents": W}, "adapters.queue.resolve": {"contents": W}, + "adapters.records._began": {"actions": R}, # a run's jobs, for when it began (0193) "adapters.records._list": {"actions": R}, "adapters.rules._file_at": {"contents": R}, # a file at the base: what a push may not touch "adapters.seen._check_runs": {"pull_requests": R, "checks": R}, # the pull request's head, then its checks @@ -102,6 +103,7 @@ class of `adapters/`, the Harness and the Controller that it calls, to each func "adapters.queue.queued": 1, "adapters.queue.resolve": 1, "adapters.queue.threads": 1, + "adapters.records._began": 1, "adapters.records._list": 1, "adapters.rules._file_at": 1, "adapters.seen._check_runs": 2, @@ -137,6 +139,7 @@ class of `adapters/`, the Harness and the Controller that it calls, to each func "adapters.pull.diff", "adapters.pull.last_push", "adapters.pull.read", + "adapters.records._began", "adapters.records._list", "adapters.threads._read", "adapters.timeline.Accounts", diff --git a/tools/mutants.py b/tools/mutants.py index 0c4f7c5c..e4bf69c9 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -3457,6 +3457,9 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ('no second read waits on a run not yet named', 'adapters/records.py', ' if unnamed:\n sleep(WAIT)\n', ' if False:\n sleep(WAIT)\n', ('tests.test_adapters',)), + ("jobs are asked for the first read's rows after a second", 'adapters/records.py', + ' records, unnamed, again, whole, failed, ids, ran = read()\n', + ' records, unnamed, again, whole, failed, ids, _ = read()\n', BEGUN), ("the first read's unnamed runs stand after the second", 'adapters/records.py', ' records, unnamed, again, whole, failed, ids, ran = read()\n', ' again = []\n', ('tests.test_adapters',)), @@ -4343,6 +4346,9 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ('a completed job no runner ran says when its Run began', 'adapters/records.py', ' and isinstance(j.get("runner_name"), str) and j["runner_name"] != "")]', ')]', BEGAN), + ('a job that waits with a runner named says when its Run began', 'adapters/records.py', + ' or (j.get("status") == "completed" and isinstance(j.get("runner_name"), str)', + ' or (isinstance(j.get("runner_name"), str)', BEGAN), ('a runner with no name is a runner', 'adapters/records.py', ' and j["runner_name"] != "")]', ')]', BEGAN), @@ -4374,8 +4380,14 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: 'type(body.get("total_count")) is not int or body["total_count"] != len(jobs)', 'body.get("total_count") != len(jobs)', UNREAD_JOBS), ("another attempt's jobs are read", 'adapters/records.py', - 'not isinstance(j, dict) or j.get("run_attempt") != attempt for j in jobs', - 'not isinstance(j, dict) for j in jobs', UNREAD_JOBS), + '\n or j["run_attempt"] != attempt for j in jobs):', + ' for j in jobs):', UNREAD_JOBS), + ("a job whose attempt is no number is its run's", 'adapters/records.py', + 'not isinstance(j, dict) or type(j.get("run_attempt")) is not int\n', + 'not isinstance(j, dict)\n', UNREAD_JOBS), + ("a time in another form is a time", 'adapters/records.py', + ' if not (isinstance(value, str) and TIME.fullmatch(value)):\n return False\n try:\n datetime.datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")', + ' if not isinstance(value, str):\n return False\n try:\n datetime.datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")', UNREAD_JOBS), ('jobs are read for an attempt that cannot be read', 'adapters/records.py', ' or type(attempt) is not int or any(', ' or any(', UNREAD_JOBS), @@ -4389,8 +4401,8 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ' record.update(found)\n whole = whole and answered\n', ' record.update(found)\n', UNREAD_JOBS), ('a read of jobs may be cached', 'adapters/records.py', - '/jobs" % (repo, github_id), headers=FRESH)),', - '/jobs" % (repo, github_id))),', UNREAD_JOBS), + '/jobs" % (repo, github_id), headers=FRESH))', + '/jobs" % (repo, github_id)))', UNREAD_JOBS), ('when a Run began is asked again though kept', 'adapters/records.py', ' if keyed and (record["run"], record["started_at"]) in began:\n', ' if False:\n', BEGUN), @@ -4422,11 +4434,16 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: 'if "began_at" in r and (_time(r["began_at"]) or ', 'if "began_at" in r and (isinstance(r["began_at"], (str, int)) or ', BEGUN), ('a beginning a record lists twice is kept', 'adapters/records.py', - ' return {key: found[key] for key in found if listed.count(key) == 1}\n', - ' return found\n', BEGUN), + ' return {key: found[key] for key in found if listed.count(key) == 1}, listed\n', + ' return found, listed\n', BEGUN), ('a beginning is kept for a record that names no Run or no start', 'adapters/records.py', ' if not all(isinstance(part, str) for part in key):\n continue\n', '', BEGUN), + ("the earlier record's beginning stands for a Run the later lists", 'adapters/records.py', + ' kept = {key: kept[key] for key in kept if key not in listed}\n', '', BEGUN), + ('a key listed twice counts only its listings that give a beginning', 'adapters/records.py', + ' listed.append(key)\n if "began_at" in r and (_time(r["began_at"]) or (r["began_at"] is None and r.get("status") == "completed")):\n', + ' if "began_at" in r and (_time(r["began_at"]) or (r["began_at"] is None and r.get("status") == "completed")):\n listed.append(key)\n', BEGUN), ("every record's beginnings are read, not the last two", 'adapters/records.py', ' for record in (list(previous[-2:]) if isinstance(previous, list) else []):', ' for record in (list(previous) if isinstance(previous, list) else []):', BEGUN), From 9932fb38014570a97cd11c2999fd51ee664b92e5 Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 07:53:30 -0600 Subject: [PATCH 03/14] A read of one item's Runs is asked past the cap, since a Run keeps nothing to work it off (#724) Co-Authored-By: Claude --- adapters/records.py | 6 +++--- ...b-is-in-progress-or-ran-and-kept-by-the-pass-records.md | 4 ++-- tests/test_adapters.py | 5 +++++ tools/mutants.py | 7 +++++-- 4 files changed, 15 insertions(+), 7 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index f1b1541f..ba2e5050 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -313,8 +313,8 @@ def runs(transport, repo: str, branch: str, workflows: list, dispatcher: tuple, `began` is what `begun` read from the pass records before, 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; `on`, an item, asks only that item's - Runs, as a Run reading its own item does. A Run past the `JOBS` asked, or whose jobs cannot be read, has no - `began_at` and leaves the list not whole.""" + Runs, as a Run reading its own item does, and all of them: it keeps nothing, so a cap would never be worked + off. 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} @@ -366,7 +366,7 @@ def read() -> tuple: if keyed and (record["run"], record["started_at"]) in began: record["began_at"] = began[(record["run"], record["started_at"])] continue - if asked == JOBS: + if asked == JOBS and on is None: whole = False continue asked += 1 diff --git a/docs/decisions/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.md b/docs/decisions/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.md index 58df3022..69cd3233 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -10,7 +10,7 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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, so it may be earlier than `started_at`: it is a start of the same run all the same, and no job of a Run made while another of its item ran began before that one ended, at any attempt. 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, uncached, for each Run in progress or completed, and only for a caller that asks (`began`). `on` names one item, whose Runs alone are asked | A queued Run has no job begun. A caller that does not ask reads as before. A Run that reads its own item needs that item's records alone | | 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 | +| 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. A read of one item's Runs (`on`) is not capped | 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. A Run keeps nothing from one read to the next, so a cap on its item's Runs would never be worked off; an item's Runs are few, bounded by its Run ceiling and what a writer renews | | Jobs that cannot be read | An answer that is not 200, or no list of every job counted; a job of another attempt than the list gave; a start that is no time; a job not yet completed of a run the list gave as completed. 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 | The Kernel, and the Harness's two reads of the records, which ask for no job. A pull request of its own, a person's to approve, has them ask for their item's; the Kernel's reading follows that | A Run reads its item as the pass does. Were the Kernel to read the field first, a Run's reading would lack what the pass's 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 | @@ -27,6 +27,6 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re |---|---| | 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 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 still waiting of a completed run is read as never begun", 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: "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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | -| 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; `on` asks one item's Runs alone | `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: "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", mutant: "the cap on jobs reads is another", mutant: "another item's Runs are asked for their jobs" | +| 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; `on` asks one item's Runs alone | `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: "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", mutant: "one item's Runs are asked no further than the cap", mutant: "the cap on jobs reads is another", mutant: "another item's Runs are asked for their jobs" | | `begun` keeps a time for any Run and null for a completed one alone, from the last two records, the earlier's word only for a Run the later does not list, and nothing from a key listed twice or a record that names no Run or no start | `tests/test_adapters.py::test_when_a_run_began_is_asked_once_and_kept`, `adapters/records.py`, `tools/mutants.py`, mutant: "null is kept for a Run still in progress", mutant: "a beginning that is no time is kept", mutant: "a beginning a record lists twice is kept", mutant: "a beginning is kept for a record that names no Run or no start", mutant: "the earlier record's beginning stands for a Run the later lists", mutant: "a key listed twice counts only its listings that give a beginning", mutant: "every record's beginnings are read, not the last two", mutant: "the earlier record's beginning stands over the later's" | | The pass hands the records port what the records before kept | `tests/test_controller.py::test_the_entry_gathers_what_reconciliation_reads`, `controller/__main__.py`, `tools/mutants.py`, mutant: "the entry asks the records port no job" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index 182bc7eb..c401fe86 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1470,6 +1470,11 @@ def read(*found, **kw): got, asked = read(other, jobs[1], jobs[2], jobs[3], began={}, on=first["runs"][1]["item"]) self.assertEqual(([r.get("began_at", "none") for r in got["runs"]], got["complete"], asked), (["none"] + began[1:] + ["none"], True, [701, 702, 703])) + # And all of them, past the cap: a Run keeps nothing from one read to the next, so a cap on its item's + # Runs would never be worked off, and its item would never be read whole again. + with mock.patch.object(records, "JOBS", 2): + got, asked = read(rows, *jobs, began={}, on=first["runs"][0]["item"]) + self.assertEqual((got["runs"], got["complete"], asked), (first["runs"], True, [700, 701, 702, 703])) # The last two records are read, the later's word standing; null is kept for a completed Run alone, and # nothing from a key a record lists twice, a start that is no time, or what is no pass record's runs. one = first["runs"][0] diff --git a/tools/mutants.py b/tools/mutants.py index e4bf69c9..4f2d77e4 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4416,10 +4416,13 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: '(r, i, attempt, timed and attempts[(r["run"], r["started_at"])] == 1)', '(r, i, attempt, timed)', BEGUN), ('more Runs than the cap are asked for their jobs', 'adapters/records.py', - ' if asked == JOBS:\n', + ' if asked == JOBS and on is None:\n', ' if False:\n', BEGUN), ('Runs past the cap leave the list whole', 'adapters/records.py', - ' if asked == JOBS:\n whole = False\n', + ' if asked == JOBS and on is None:\n whole = False\n', + ' if asked == JOBS and on is None:\n', BEGUN), + ("one item's Runs are asked no further than the cap", 'adapters/records.py', + ' if asked == JOBS and on is None:\n', ' if asked == JOBS:\n', BEGUN), ('the cap on jobs reads is another', 'adapters/records.py', 'JOBS = 50 ', From ca4546d6f82bd72acbfefb9bf2a7634ae8958c63 Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 08:09:54 -0600 Subject: [PATCH 04/14] The record says when the Harness's reads begin to ask (#724) Co-Authored-By: Claude --- ...-a-job-is-in-progress-or-ran-and-kept-by-the-pass-records.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/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.md b/docs/decisions/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.md index 69cd3233..0f39563e 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -12,7 +12,7 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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. A read of one item's Runs (`on`) is not capped | 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. A Run keeps nothing from one read to the next, so a cap on its item's Runs would never be worked off; an item's Runs are few, bounded by its Run ceiling and what a writer renews | | Jobs that cannot be read | An answer that is not 200, or no list of every job counted; a job of another attempt than the list gave; a start that is no time; a job not yet completed of a run the list gave as completed. 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 | The Kernel, and the Harness's two reads of the records, which ask for no job. A pull request of its own, a person's to approve, has them ask for their item's; the Kernel's reading follows that | A Run reads its item as the pass does. Were the Kernel to read the field first, a Run's reading would lack what the pass's has | +| What does not read it yet | The Kernel. The Harness's two reads of the records ask for their own item's Runs (`on`) from the pull request that follows this one, a person's to approve, and for no job until it merges; the Kernel's reading follows that | A Run reads its item as the pass does. Were the Kernel to read the field first, a Run's reading would lack what the pass's 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, whatever it concluded | Read as unreadable, a Run GitHub never lists a job for would leave the list not whole at every pass. Null drops one record that could have dated an approval, and admits nothing | | No stamp | A jobs read leaves no date and no age in the pass record | Nothing acts on a read's age. An answer older than the list reads as not begun yet or as unread, but for the row above | From 5095b60ca79773534b06963d22a6203f09b21fae Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 08:27:39 -0600 Subject: [PATCH 05/14] A null kept for a completed Run is not said of one the list gives as running still (#724) Co-Authored-By: Claude --- adapters/records.py | 5 ++++- ...job-is-in-progress-or-ran-and-kept-by-the-pass-records.md | 2 +- tests/test_adapters.py | 5 +++++ tools/mutants.py | 3 +++ 4 files changed, 13 insertions(+), 2 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index ba2e5050..c2b80ae8 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -365,7 +365,10 @@ def read() -> tuple: continue if keyed and (record["run"], record["started_at"]) in began: record["began_at"] = began[(record["run"], record["started_at"])] - continue + # 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 and on is None: whole = False continue diff --git a/docs/decisions/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.md b/docs/decisions/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.md index 0f39563e..0ae57616 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -27,6 +27,6 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re |---|---| | 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 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 still waiting of a completed run is read as never begun", 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: "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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | -| 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; `on` asks one item's Runs alone | `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: "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", mutant: "one item's Runs are asked no further than the cap", mutant: "the cap on jobs reads is another", mutant: "another item's Runs are asked for their jobs" | +| 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; `on` asks one item's Runs alone | `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: "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", mutant: "one item's Runs are asked no further than the cap", mutant: "the cap on jobs reads is another", mutant: "another item's Runs are asked for their jobs" | | `begun` keeps a time for any Run and null for a completed one alone, from the last two records, the earlier's word only for a Run the later does not list, and nothing from a key listed twice or a record that names no Run or no start | `tests/test_adapters.py::test_when_a_run_began_is_asked_once_and_kept`, `adapters/records.py`, `tools/mutants.py`, mutant: "null is kept for a Run still in progress", mutant: "a beginning that is no time is kept", mutant: "a beginning a record lists twice is kept", mutant: "a beginning is kept for a record that names no Run or no start", mutant: "the earlier record's beginning stands for a Run the later lists", mutant: "a key listed twice counts only its listings that give a beginning", mutant: "every record's beginnings are read, not the last two", mutant: "the earlier record's beginning stands over the later's" | | The pass hands the records port what the records before kept | `tests/test_controller.py::test_the_entry_gathers_what_reconciliation_reads`, `controller/__main__.py`, `tools/mutants.py`, mutant: "the entry asks the records port no job" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index c401fe86..791b0d5b 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1422,6 +1422,11 @@ def read(*found, **kw): self.assertEqual(kept, {("r_%06dZ" % n, "2026-10-21T0%d:00:00Z" % n): began[n] for n in range(3)}) second, asked = read(rows, jobs[3], began=kept) self.assertEqual((second["runs"], asked), (first["runs"], [703])) + # Null kept for a completed Run is not said of one the list gives as running still: its jobs are asked. + stale = copy.deepcopy(rows) + stale["response"]["body"]["workflow_runs"][1].update(status="in_progress", conclusion=None) + got, asked = read(stale, jobs_read("P-64", 9, 701), jobs[3], began=kept) + self.assertEqual(("began_at" in got["runs"][1], asked), (False, [701, 703])) # A re-run starts again, at another time, and a row that names no start of its attempt, or a key listed twice, # is asked whatever is kept. rerun = copy.deepcopy(rows) diff --git a/tools/mutants.py b/tools/mutants.py index 4f2d77e4..e8619288 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4409,6 +4409,9 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ('when a Run began is kept across attempts', 'adapters/records.py', ' if keyed and (record["run"], record["started_at"]) in began:\n record["began_at"] = began[(record["run"], record["started_at"])]\n', ' if keyed and any(k[0] == record["run"] for k in began):\n record["began_at"] = next(v for k, v in began.items() if k[0] == record["run"])\n', BEGUN), + ('null kept is said of a Run the list gives as running still', 'adapters/records.py', + ' if record["began_at"] is not None or record["status"] == "completed":\n continue\n del record["began_at"]\n', + ' continue\n', BEGUN), ('a row that names no start of its attempt keeps when it began', 'adapters/records.py', '(r, i, attempt, timed and attempts[(r["run"], r["started_at"])] == 1)', '(r, i, attempt, attempts[(r["run"], r["started_at"])] == 1)', BEGUN), From 078c741ede73cfb1ee385f709858feb7db2fc2e4 Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 08:31:49 -0600 Subject: [PATCH 06/14] The read of one item's Runs moves to the pull request that asks for it, and the prose is cut to the review budget (#724) Co-Authored-By: Claude --- adapters/records.py | 20 ++++------- ...ess-or-ran-and-kept-by-the-pass-records.md | 18 +++++----- tests/test_adapters.py | 36 ++++++------------- tools/mutants.py | 16 ++------- 4 files changed, 28 insertions(+), 62 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index c2b80ae8..8522bdcd 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -16,12 +16,9 @@ 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 (trials/P-44.json), and a job's `started_at` is its creation too 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 jobs GitHub lists for the latest attempt, null for a completed Run none of whose jobs began, and absent where -it has not begun or was not read. A re-run may list a job an earlier attempt ran, with its start: that is a start of -the same run, and may be earlier than the record's `started_at`. A start, once given, stands at every later read (P-64), so what the pass records before kept is not -asked again, and no more than `JOBS` Runs are asked in one read: what is left unasked leaves the list not whole. +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 @@ -296,7 +293,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, began=None, on=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. @@ -312,9 +309,8 @@ def runs(transport, repo: str, branch: str, workflows: list, dispatcher: tuple, `began` is what `begun` read from the pass records before, 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; `on`, an item, asks only that item's - Runs, as a Run reading its own item does, and all of them: it keeps nothing, so a cap would never be worked - off. A Run past the `JOBS` asked, or whose jobs cannot be read, has no `began_at` and leaves the list not whole.""" + 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} @@ -361,15 +357,13 @@ def read() -> tuple: whole = whole and read_whole asked = 0 for record, github_id, attempt, keyed in ran if began is not None else []: - if on is not None and record["item"] != on: - continue 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 and on is None: + if asked == JOBS: whole = False continue asked += 1 diff --git a/docs/decisions/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.md b/docs/decisions/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.md index 0ae57616..6de762d3 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -6,16 +6,16 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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 be recent at every pass, so an automatic pause it held would never lapse, and its key would move at every pass | -| 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, so it may be earlier than `started_at`: it is a start of the same run all the same, and no job of a Run made while another of its item ran began before that one ended, at any attempt. 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, uncached, for each Run in progress or completed, and only for a caller that asks (`began`). `on` names one item, whose Runs alone are asked | A queued Run has no job begun. A caller that does not ask reads as before. A Run that reads its own item needs that item's records alone | +| 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, 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 | | 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. A read of one item's Runs (`on`) is not capped | 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. A Run keeps nothing from one read to the next, so a cap on its item's Runs would never be worked off; an item's Runs are few, bounded by its Run ceiling and what a writer renews | +| 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; a job of another attempt than the list gave; a start that is no time; a job not yet completed of a run the list gave as completed. 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 | The Kernel. The Harness's two reads of the records ask for their own item's Runs (`on`) from the pull request that follows this one, a person's to approve, and for no job until it merges; the Kernel's reading follows that | A Run reads its item as the pass does. Were the Kernel to read the field first, a Run's reading would lack what the pass's has | +| What does not read it yet | The Kernel, and the Harness's two reads of the records, until the pull request that follows this one, a person's to approve, has them ask for their own item's Runs; the Kernel's reading follows that | A Run reads its item as the pass does. Were the Kernel to read the field first, a Run's reading would lack what the pass's 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, whatever it concluded | Read as unreadable, a Run GitHub never lists a job for would leave the list not whole at every pass. Null drops one record that could have dated an approval, and admits nothing | -| No stamp | A jobs read leaves no date and no age in the pass record | Nothing acts on a read's age. An answer older than the list reads as not begun yet or as unread, but for the row above | +| 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 | +| No stamp | A jobs read leaves no date and no age in the pass record | Nothing acts on a read's age | ## Why @@ -26,7 +26,7 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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 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 still waiting of a completed run is read as never begun", 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: "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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | -| 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; `on` asks one item's Runs alone | `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: "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", mutant: "one item's Runs are asked no further than the cap", mutant: "the cap on jobs reads is another", mutant: "another item's Runs are asked for their jobs" | +| 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 still waiting of a completed run is read as never begun", mutant: "jobs GitHub did not answer are read", mutant: "jobs listed short of their count are read", mutant: "another attempt's jobs are read", mutant: "a job whose attempt is no number is its run's", 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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | +| 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: "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" | | `begun` keeps a time for any Run and null for a completed one alone, from the last two records, the earlier's word only for a Run the later does not list, and nothing from a key listed twice or a record that names no Run or no start | `tests/test_adapters.py::test_when_a_run_began_is_asked_once_and_kept`, `adapters/records.py`, `tools/mutants.py`, mutant: "null is kept for a Run still in progress", mutant: "a beginning that is no time is kept", mutant: "a beginning a record lists twice is kept", mutant: "a beginning is kept for a record that names no Run or no start", mutant: "the earlier record's beginning stands for a Run the later lists", mutant: "a key listed twice counts only its listings that give a beginning", mutant: "every record's beginnings are read, not the last two", mutant: "the earlier record's beginning stands over the later's" | | The pass hands the records port what the records before kept | `tests/test_controller.py::test_the_entry_gathers_what_reconciliation_reads`, `controller/__main__.py`, `tools/mutants.py`, mutant: "the entry asks the records port no job" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index 791b0d5b..9575940f 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1056,7 +1056,7 @@ def read(self, *found, **kw): slept = [] got = records.runs(github.Replay(list(found)), canary(), "main", [WORKFLOW], kw.get("dispatcher", DISPATCHER), per_page=kw.get("per_page", 10), sleep=slept.append, kept=kw.get("kept"), - began=kw.get("began"), on=kw.get("on")) + began=kw.get("began")) return got, slept def test_a_run_listed_under_its_workflows_name_is_unidentified_after_one_more_read(self): @@ -1310,11 +1310,9 @@ def began(self, status, *jobs, **kw): return got["runs"][0], got["complete"] def test_a_run_began_when_a_job_of_it_did(self): - # trials/P-64.json: the second run's job waited 53 s in its lane. While it waited, `pending`, the jobs API gave - # its `started_at` as its creation, as the run's `run_started_at` is at every read; once in progress, and - # completed, it gave 19:44:48Z. trials/P-44.json: a job cancelled while it waited ends completed with no - # runner, its `started_at` its creation still. So only a job in progress, or completed with a runner named, - # says when its Run began (decision 0193). + # trials/P-64.json: a job that waited 53 s in its lane gave its creation as its `started_at` while `pending`, + # and 19:44:48Z once in progress and completed. trials/P-44.json: one cancelled while it waited ends completed + # with no runner. So only a job in progress, or completed with a runner, says when its Run began (0193). gid = exchanges("P-17")[3]["response"]["body"]["workflow_runs"][0]["id"] waiting, running, ran = (exchanges("P-64")[at]["response"]["body"]["jobs"][0] for at in (9, 18, 33)) gone = exchanges("P-44")[23]["response"]["body"]["jobs"][0] @@ -1323,8 +1321,8 @@ def test_a_run_began_when_a_job_of_it_did(self): [("pending", True, False), ("in_progress", False, True), ("completed", False, True), ("completed", True, False)]) self.assertEqual((running["started_at"], ran["started_at"]), ("2026-11-10T19:44:48Z",) * 2) - # The four sides: pending, nothing yet; in progress and completed with a runner, the job's start; completed - # with none, null, since it never began. `started_at` stays the run's own, as every other reader takes it. + # Pending, nothing yet; in progress or completed with a runner, the job's start; completed with none, null. + # `started_at` stays the run's own. record, whole = self.began("in_progress", jobs_read("P-64", 9, gid)) self.assertEqual(("began_at" in record, whole), (False, True)) for status, at in (("in_progress", 18), ("completed", 33)): @@ -1394,8 +1392,8 @@ def changed(at, **change): self.assertEqual(("began_at" in record, whole), (False, True)) def test_when_a_run_began_is_asked_once_and_kept(self): - # A job's start stands at every read after the first that gives it (P-64, part 3), and a completed run's - # jobs change no more: what a pass record holds is not asked again. A Run that has not begun is asked again. + # A job's start stands once given (P-64), and a completed run's jobs change no more: what a pass record + # holds is not asked again. A Run that has not begun is. rows = listing("P-17", 3, rows={"status": "completed", "conclusion": "success", "run_attempt": 1}) template = rows["response"]["body"]["workflow_runs"][0] names = [NAME.replace("r_01JA6Z", "r_%06dZ" % n) for n in range(4)] @@ -1449,9 +1447,8 @@ def read(*found, **kw): got, asked = read(early, late, *jobs, began={}, sleep=lambda s: None) self.assertEqual(([r.get("began_at", "none") for r in got["runs"]], asked), (began + ["none"], [700, 701, 702, 703])) - # A re-run of some jobs lists the others as an earlier attempt ran them, under the new attempt and with their - # old starts (seen on runs of this repo and the canary, in no trial): the earliest is a start of the same run, - # before the attempt's own, and is what the record says. + # A re-run of some jobs lists the others with the starts an earlier attempt gave them (seen on this repo's + # runs, in no trial): the earliest, before the attempt's own start, is what the record says. carried = jobs_read("P-64", 33, 700) carried["response"]["body"].update(total_count=2, jobs=[ dict(exchanges("P-64")[33]["response"]["body"]["jobs"][0], started_at="2026-10-20T23:50:00Z"), @@ -1467,19 +1464,6 @@ def read(*found, **kw): (began[:2] + ["none", "none"], False, [700, 701])) rest, asked = read(rows, jobs[2], jobs[3], began=records.begun([record(capped)])) self.assertEqual((rest["runs"], rest["complete"], asked), (first["runs"], True, [702, 703])) - self.assertEqual(records.JOBS, 50) - # Asked of one item's Runs alone, as a Run reading its own item asks: another item's say nothing, and are no - # part of the read. - other = copy.deepcopy(rows) - other["response"]["body"]["workflow_runs"][0]["name"] = names[0].replace("#264", "#265") - got, asked = read(other, jobs[1], jobs[2], jobs[3], began={}, on=first["runs"][1]["item"]) - self.assertEqual(([r.get("began_at", "none") for r in got["runs"]], got["complete"], asked), - (["none"] + began[1:] + ["none"], True, [701, 702, 703])) - # And all of them, past the cap: a Run keeps nothing from one read to the next, so a cap on its item's - # Runs would never be worked off, and its item would never be read whole again. - with mock.patch.object(records, "JOBS", 2): - got, asked = read(rows, *jobs, began={}, on=first["runs"][0]["item"]) - self.assertEqual((got["runs"], got["complete"], asked), (first["runs"], True, [700, 701, 702, 703])) # The last two records are read, the later's word standing; null is kept for a completed Run alone, and # nothing from a key a record lists twice, a start that is no time, or what is no pass record's runs. one = first["runs"][0] diff --git a/tools/mutants.py b/tools/mutants.py index e8619288..bd825e3f 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4376,9 +4376,6 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ('jobs listed short of their count are read', 'adapters/records.py', ' or body["total_count"] != len(jobs) \\\n', ' \\\n', UNREAD_JOBS), - ('a count of jobs that is no number is read', 'adapters/records.py', - 'type(body.get("total_count")) is not int or body["total_count"] != len(jobs)', - 'body.get("total_count") != len(jobs)', UNREAD_JOBS), ("another attempt's jobs are read", 'adapters/records.py', '\n or j["run_attempt"] != attempt for j in jobs):', ' for j in jobs):', UNREAD_JOBS), @@ -4419,20 +4416,11 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: '(r, i, attempt, timed and attempts[(r["run"], r["started_at"])] == 1)', '(r, i, attempt, timed)', BEGUN), ('more Runs than the cap are asked for their jobs', 'adapters/records.py', - ' if asked == JOBS and on is None:\n', + ' if asked == JOBS:\n', ' if False:\n', BEGUN), ('Runs past the cap leave the list whole', 'adapters/records.py', - ' if asked == JOBS and on is None:\n whole = False\n', - ' if asked == JOBS and on is None:\n', BEGUN), - ("one item's Runs are asked no further than the cap", 'adapters/records.py', - ' if asked == JOBS and on is None:\n', + ' if asked == JOBS:\n whole = False\n', ' if asked == JOBS:\n', BEGUN), - ('the cap on jobs reads is another', 'adapters/records.py', - 'JOBS = 50 ', - 'JOBS = 500 ', BEGUN), - ("another item's Runs are asked for their jobs", 'adapters/records.py', - ' if on is not None and record["item"] != on:\n', - ' if False:\n', BEGUN), ('null is kept for a Run still in progress', 'adapters/records.py', ' or (r["began_at"] is None and r.get("status") == "completed")):', ' or r["began_at"] is None):', BEGUN), From d0ef97f3f8ae3c79c1947c3a259789af07a9950b Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 08:33:24 -0600 Subject: [PATCH 07/14] The pass's keeping of when a Run began moves to its own pull request (#724) Split for the review budget: this part holds the field and the port's read; begun and the Controller's hand-over follow. Co-Authored-By: Claude --- adapters/records.py | 32 ++----------------- controller/__main__.py | 5 ++- ...ess-or-ran-and-kept-by-the-pass-records.md | 4 +-- tests/test_adapters.py | 29 +++-------------- tests/test_controller.py | 9 ------ tools/mutants.py | 24 -------------- 6 files changed, 9 insertions(+), 94 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index 8522bdcd..73045e98 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -230,34 +230,6 @@ def _began(transport, repo: str, github_id: int, attempt, done: bool) -> tuple: return ({"began_at": None}, True) if all(j.get("status") == "completed" for j in jobs) else ({}, False) -def begun(previous: list) -> dict: - """When each Run began, as the pass records before this one read it from its jobs, by its Run id and when its - attempt started: the last two at most, and the earlier's word only for a Run the later does not list. A time is - kept for any Run, since a job's start stands once given (P-64), and null for a completed Run alone, whose jobs - change no more. A key a record lists twice, with a beginning or without, is kept from neither listing, and - nothing is kept from a record that is not a `pass/1` record's runs. A re-run starts again, at another time, and - is asked afresh.""" - def read(record) -> tuple: - runs_ = record.get("runs") if isinstance(record, dict) else None - if not isinstance(runs_, list): - return {}, [] - found, listed = {}, [] - for r in runs_: - key = (r.get("run"), r.get("started_at")) if isinstance(r, dict) else (None, None) - if not all(isinstance(part, str) for part in key): - continue - listed.append(key) - if "began_at" in r and (_time(r["began_at"]) or (r["began_at"] is None and r.get("status") == "completed")): - found[key] = r["began_at"] - return {key: found[key] for key in found if listed.count(key) == 1}, listed - kept = {} - for record in (list(previous[-2:]) if isinstance(previous, list) else []): - found, listed = read(record) - kept = {key: kept[key] for key in kept if key not in listed} - kept.update(found) - return kept - - 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`, @@ -307,8 +279,8 @@ def runs(transport, repo: str, branch: str, workflows: list, dispatcher: tuple, 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. - `began` is what `begun` read from the pass records before, 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` + `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 {} diff --git a/controller/__main__.py b/controller/__main__.py index 6a8c986d..4fd3d8e0 100644 --- a/controller/__main__.py +++ b/controller/__main__.py @@ -152,10 +152,9 @@ def read(transport, config: dict, run_id: str, previous, now: str, clock, starte """Everything the pass reads after the wait, as `pass_.run` takes it.""" controller = config["controller"] home, branch = controller["home"]["repo"], controller["home"]["branch"] - earlier = pass_.earlier(reads_.previous_records(previous), now) or [] + kept = records.known(pass_.earlier(reads_.previous_records(previous), now) or []) try: - runs = records.runs(transport, home, branch, run_files(controller), dispatcher(controller), - kept=records.known(earlier), began=records.begun(earlier)) + runs = records.runs(transport, home, branch, run_files(controller), dispatcher(controller), kept=kept) except Unanswered: runs = None try: diff --git a/docs/decisions/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.md b/docs/decisions/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.md index 6de762d3..347a8247 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -1,6 +1,6 @@ # 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 issue 724, "A record's start is read from its job's started_at, trusted only once the job is in progress or ran (P-64)". It adds one field to the run record and one read to the records port. 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. +Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A record's start is read from its job's started_at, trusted only once the job is in progress or ran (P-64)". 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 @@ -28,5 +28,3 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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 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 still waiting of a completed run is read as never begun", mutant: "jobs GitHub did not answer are read", mutant: "jobs listed short of their count are read", mutant: "another attempt's jobs are read", mutant: "a job whose attempt is no number is its run's", 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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | | 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: "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" | -| `begun` keeps a time for any Run and null for a completed one alone, from the last two records, the earlier's word only for a Run the later does not list, and nothing from a key listed twice or a record that names no Run or no start | `tests/test_adapters.py::test_when_a_run_began_is_asked_once_and_kept`, `adapters/records.py`, `tools/mutants.py`, mutant: "null is kept for a Run still in progress", mutant: "a beginning that is no time is kept", mutant: "a beginning a record lists twice is kept", mutant: "a beginning is kept for a record that names no Run or no start", mutant: "the earlier record's beginning stands for a Run the later lists", mutant: "a key listed twice counts only its listings that give a beginning", mutant: "every record's beginnings are read, not the last two", mutant: "the earlier record's beginning stands over the later's" | -| The pass hands the records port what the records before kept | `tests/test_controller.py::test_the_entry_gathers_what_reconciliation_reads`, `controller/__main__.py`, `tools/mutants.py`, mutant: "the entry asks the records port no job" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index 9575940f..0908ad59 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1406,7 +1406,8 @@ def test_when_a_run_began_is_asked_once_and_kept(self): began = ["2026-11-10T19:44:48Z", None, "2026-11-10T19:44:48Z"] def record(got): - return {"runs": got["runs"]} + # What a caller keeps of a read: when each Run began, by its Run id and when its attempt started. + return {(r["run"], r["started_at"]): r["began_at"] for r in got["runs"] if "began_at" in r} def read(*found, **kw): """What a read gave, and the runs whose jobs it asked for, by GitHub's id, in order.""" @@ -1416,7 +1417,7 @@ def read(*found, **kw): first, asked = read(rows, *jobs, began={}) self.assertEqual(([r.get("began_at", "none") for r in first["runs"]], first["complete"], asked), (began + ["none"], True, [700, 701, 702, 703])) - kept = records.begun([record(first)]) + kept = record(first) self.assertEqual(kept, {("r_%06dZ" % n, "2026-10-21T0%d:00:00Z" % n): began[n] for n in range(3)}) second, asked = read(rows, jobs[3], began=kept) self.assertEqual((second["runs"], asked), (first["runs"], [703])) @@ -1462,30 +1463,8 @@ def read(*found, **kw): capped, asked = read(rows, jobs[0], jobs[1], began={}) self.assertEqual(([r.get("began_at", "none") for r in capped["runs"]], capped["complete"], asked), (began[:2] + ["none", "none"], False, [700, 701])) - rest, asked = read(rows, jobs[2], jobs[3], began=records.begun([record(capped)])) + rest, asked = read(rows, jobs[2], jobs[3], began=record(capped)) self.assertEqual((rest["runs"], rest["complete"], asked), (first["runs"], True, [702, 703])) - # The last two records are read, the later's word standing; null is kept for a completed Run alone, and - # nothing from a key a record lists twice, a start that is no time, or what is no pass record's runs. - one = first["runs"][0] - older, newer = {"runs": [dict(one, began_at="2026-11-10T00:00:00Z")]}, {"runs": [one]} - key = (one["run"], one["started_at"]) - self.assertEqual((records.begun([older, newer])[key], records.begun([newer, older])[key], - records.begun([older, newer, {"runs": []}])), (began[0], "2026-11-10T00:00:00Z", {key: began[0]})) - self.assertEqual(records.begun([older, {"runs": []}, {"runs": []}]), {}) - # The earlier record's word stands only for a Run the later does not list: one the later lists with no - # beginning, or twice, is asked afresh. - bare = {k: v for k, v in one.items() if k != "began_at"} - self.assertEqual((records.begun([older, {"runs": []}]), records.begun([older, {"runs": [bare]}]), - records.begun([older, {"runs": [one, one]}]), records.begun([{"runs": [one, bare]}])), - ({key: "2026-11-10T00:00:00Z"}, {}, {}, {})) - for change in ({"began_at": None, "status": "in_progress"}, {"began_at": "soon"}, {"began_at": 7}, - {"began_at": "2026-02-30T00:00:00Z"}, {"began_at": "2026-2-3T1:2:3Z"}, {"run": None}, - {"started_at": None}): - self.assertEqual(records.begun([{"runs": [dict(one, **change)]}]), {}, change) - self.assertEqual(records.begun([{"runs": [{k: v for k, v in one.items() if k != "began_at"}]}]), {}) - self.assertEqual(records.begun([{"runs": [one, dict(one, began_at=None)]}]), {}) - self.assertEqual((records.begun(None), records.begun(record(first)), records.begun([{"runs": None}]), - records.begun([{"runs": ["x"]}]), records.begun(["x"])), ({}, {}, {}, {}, {})) def test_a_status_or_a_conclusion_github_would_not_give_a_run_makes_the_list_short(self): self.assertEqual(self.read(listing("P-17", 3, rows={"name": NAME, "status": "waiting"}))[0]["runs"][0]["status"], diff --git a/tests/test_controller.py b/tests/test_controller.py index 3fb9c241..16f2bfe6 100644 --- a/tests/test_controller.py +++ b/tests/test_controller.py @@ -1154,13 +1154,6 @@ def written_read(transport, repo, branch, poller, own, since, known): served = [dict(before["pull_requests"][0], facts=dict(before["pull_requests"][0]["facts"], item=dict( before["pull_requests"][0]["facts"]["item"], number=n))) for n in (7, 9)] before["pull_requests"] = served - # When a Run began, as the record before read it from its jobs, is handed to the records port (decision 0193). - before["runs"][0]["began_at"] = "2026-10-11T12:05:04Z" - listed = entry.records.runs - - def runs(*args, **kw): - efforts["began"] = kw["began"] - return listed(*args, **kw) before["reconciled"] = {"runs": [{"id": "r_01JA00", "at": "2026-10-12T11:00:00Z"}], "passes": [{"id": 40, "attempt": 1, "at": "2026-10-12T11:00:00Z"}], "keys": [], "items": [], "dispatched": [], "owed": [11]} @@ -1176,11 +1169,9 @@ def runs(*args, **kw): unittest.mock.patch.object(entry.passes, "records", lambda *a: [older, before]), \ unittest.mock.patch.object(entry.seen_, "read", read), unittest.mock.patch.object(entry.seen_, "pushes", pushes), \ unittest.mock.patch.object(entry.applied, "effects", applied_read), \ - unittest.mock.patch.object(entry.records, "runs", runs), \ unittest.mock.patch.object(entry.passes, "written", written_read): code, _, files, _ = self.run_entry(Hub(table)) self.assertEqual(code, 0) - self.assertEqual(efforts["began"], {("r_01JA6Z", "2026-10-11T12:05:00Z"): "2026-10-11T12:05:04Z"}) since = "2026-10-11T06:00:00Z" item = lambda n: {"repo": self.HOME, "type": "pull_request", "number": n} identities, apps = spied[0][2], spied[0][3] diff --git a/tools/mutants.py b/tools/mutants.py index bd825e3f..80f44f87 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4421,30 +4421,6 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ('Runs past the cap leave the list whole', 'adapters/records.py', ' if asked == JOBS:\n whole = False\n', ' if asked == JOBS:\n', BEGUN), - ('null is kept for a Run still in progress', 'adapters/records.py', - ' or (r["began_at"] is None and r.get("status") == "completed")):', - ' or r["began_at"] is None):', BEGUN), - ('a beginning that is no time is kept', 'adapters/records.py', - 'if "began_at" in r and (_time(r["began_at"]) or ', - 'if "began_at" in r and (isinstance(r["began_at"], (str, int)) or ', BEGUN), - ('a beginning a record lists twice is kept', 'adapters/records.py', - ' return {key: found[key] for key in found if listed.count(key) == 1}, listed\n', - ' return found, listed\n', BEGUN), - ('a beginning is kept for a record that names no Run or no start', 'adapters/records.py', - ' if not all(isinstance(part, str) for part in key):\n continue\n', - '', BEGUN), - ("the earlier record's beginning stands for a Run the later lists", 'adapters/records.py', - ' kept = {key: kept[key] for key in kept if key not in listed}\n', '', BEGUN), - ('a key listed twice counts only its listings that give a beginning', 'adapters/records.py', - ' listed.append(key)\n if "began_at" in r and (_time(r["began_at"]) or (r["began_at"] is None and r.get("status") == "completed")):\n', - ' if "began_at" in r and (_time(r["began_at"]) or (r["began_at"] is None and r.get("status") == "completed")):\n listed.append(key)\n', BEGUN), - ("every record's beginnings are read, not the last two", 'adapters/records.py', - ' for record in (list(previous[-2:]) if isinstance(previous, list) else []):', - ' for record in (list(previous) if isinstance(previous, list) else []):', BEGUN), - ("the earlier record's beginning stands over the later's", 'adapters/records.py', - ' for record in (list(previous[-2:]) if isinstance(previous, list) else []):', - ' for record in (list(reversed(previous[-2:])) if isinstance(previous, list) else []):', BEGUN), - ('the entry asks the records port no job', 'controller/__main__.py', 'began=records.begun(earlier))', 'began=None)', WIRE_ENTRY), ('an outcome list that cannot be read is not stamped', 'adapters/artifacts.py', ' if seen is not None:\n seen(answer)\n listed, total = answer["body"].get("artifacts"), answer["body"].get("total_count")\n if not isinstance(listed, list) or not isinstance(total, int) or isinstance(total, bool) or total != len(listed):\n return False\n', ' listed, total = answer["body"].get("artifacts"), answer["body"].get("total_count")\n if not isinstance(listed, list) or not isinstance(total, int) or isinstance(total, bool) or total != len(listed):\n return False\n if seen is not None:\n seen(answer)\n', From 338f7c45ed0d412532336307d7b85148babe4e7f Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 08:51:13 -0600 Subject: [PATCH 08/14] A job in a status GitHub gives none, or not yet completed of a completed run, is no read of its jobs (#724) Astra on d0ef97f3. Co-Authored-By: Claude --- adapters/records.py | 12 +++++++----- ...gress-or-ran-and-kept-by-the-pass-records.md | 4 ++-- tests/test_adapters.py | 9 ++++++--- tools/mutants.py | 17 ++++++++++------- 4 files changed, 25 insertions(+), 17 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index 73045e98..31a4b12c 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -48,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"} @@ -210,8 +211,9 @@ def _began(transport, repo: str, github_id: int, attempt, done: bool) -> tuple: 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 of the attempt the list gave, 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.""" + a start. Not whole: an answer that is no list of every job counted, each of the attempt the list gave 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" % (repo, github_id), headers=FRESH)) body = answer["body"] if answer["status"] == 200 and isinstance(answer["body"], dict) else {} jobs = body.get("jobs") @@ -219,15 +221,15 @@ def _began(transport, repo: str, github_id: int, attempt, done: bool) -> tuple: or type(attempt) is not int or any(not isinstance(j, dict) or type(j.get("run_attempt")) is not int or j["run_attempt"] != attempt for j in jobs): return {}, False + if any(j.get("status") not in JOB_STATUSES 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 - if not done: - return {}, True - return ({"began_at": None}, True) if all(j.get("status") == "completed" for j in jobs) else ({}, False) + return ({"began_at": None} if done else {}), True def known(previous: list) -> dict: diff --git a/docs/decisions/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.md b/docs/decisions/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.md index 347a8247..39c7d6c0 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -11,7 +11,7 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | What is asked | `GET /repos/{repo}/actions/runs/{id}/jobs`, as P-64 asked it, 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 | | 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; a job of another attempt than the list gave; a start that is no time; a job not yet completed of a run the list gave as completed. 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 | +| Jobs that cannot be read | An answer that is not 200, or no list of every job counted; a job of another attempt than the list gave; a job in a status GitHub gives 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 | The Kernel, and the Harness's two reads of the records, until the pull request that follows this one, a person's to approve, has them ask for their own item's Runs; the Kernel's reading follows that | A Run reads its item as the pass does. Were the Kernel to read the field first, a Run's reading would lack what the pass's 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 | @@ -26,5 +26,5 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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 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 still waiting of a completed run is read as never begun", mutant: "jobs GitHub did not answer are read", mutant: "jobs listed short of their count are read", mutant: "another attempt's jobs are read", mutant: "a job whose attempt is no number is its run's", 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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | +| 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: "jobs GitHub did not answer are read", mutant: "jobs listed short of their count are read", mutant: "another attempt's jobs are read", mutant: "a job whose attempt is no number is its run's", 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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | | 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: "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" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index 0908ad59..9e04440f 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1365,7 +1365,8 @@ def changed(at, **change): found["response"]["body"].update({k: v for k, v in change.items() if k != "status"}) return found # An answer that is no list of every job counted, a job of another attempt than the list gave or one that is - # no job, a start that is no time, and a job still waiting of a run the list gave as completed. + # no job, a start that is no time, a job not yet completed of a run the list gave as completed, begun or + # not, and a status GitHub gives no job. for status, found, rows in ( ("in_progress", changed(18, status=404), {}), ("in_progress", changed(18, total_count=2), {}), ("in_progress", changed(18, total_count=True), {}), ("in_progress", changed(18, jobs=None), {}), @@ -1379,7 +1380,9 @@ def changed(at, **change): ("in_progress", jobs_read("P-64", 18, gid, started_at="2026-02-30T19:44:48Z"), {}), ("in_progress", jobs_read("P-64", 18, gid, started_at="2026-11-10T19:44:8Z"), {}), ("completed", jobs_read("P-64", 33, gid, started_at=None), {}), - ("completed", jobs_read("P-64", 9, gid), {})): + ("completed", jobs_read("P-64", 9, gid), {}), ("completed", jobs_read("P-64", 18, gid), {}), + ("in_progress", jobs_read("P-64", 18, gid, status=None), {}), + ("in_progress", jobs_read("P-64", 9, gid, status="odd"), {})): record, whole = self.began(status, found, rows=rows) self.assertEqual(("began_at" in record, whole), (False, False), (status, found["response"], rows)) found = jobs_read("P-64", 18, gid) @@ -1453,7 +1456,7 @@ def read(*found, **kw): carried = jobs_read("P-64", 33, 700) carried["response"]["body"].update(total_count=2, jobs=[ dict(exchanges("P-64")[33]["response"]["body"]["jobs"][0], started_at="2026-10-20T23:50:00Z"), - dict(exchanges("P-64")[9]["response"]["body"]["jobs"][0])]) + dict(exchanges("P-64")[33]["response"]["body"]["jobs"][0], started_at="2026-10-21T00:00:05Z")]) got, _ = read(rows, carried, *jobs[1:], began={}) self.assertEqual((got["runs"][0]["began_at"], got["runs"][0]["started_at"]), ("2026-10-20T23:50:00Z", "2026-10-21T00:00:00Z")) diff --git a/tools/mutants.py b/tools/mutants.py index 80f44f87..c4a738c2 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4356,20 +4356,23 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ' return {"began_at": min(starts)}, True\n', ' return {"began_at": max(starts)}, True\n', BEGAN), ('a completed Run no job of which began says nothing', 'adapters/records.py', - ' return ({"began_at": None}, True) if all(', - ' return ({}, True) if all(', BEGAN), + ' return ({"began_at": None} if done else {}), True\n', + ' return {}, True\n', BEGAN), ('a Run in progress with no job begun never began', 'adapters/records.py', - ' if not done:\n return {}, True\n', - '', BEGAN), + ' return ({"began_at": None} if done else {}), True\n', + ' return {"began_at": None}, True\n', BEGAN), ('a Run not yet started is asked for its jobs', 'adapters/records.py', ' if record["status"] != "queued":\n', ' if True:\n', BEGAN), ('a caller that asked for no job is read them', 'adapters/records.py', ' in ran if began is not None else []:', ' in ran if began is not None else ran:', BEGAN), - ('a job still waiting of a completed run is read as never begun', 'adapters/records.py', - ' if all(j.get("status") == "completed" for j in jobs) else ({}, False)', - '', UNREAD_JOBS), + ('a job not yet completed of a completed run is read', 'adapters/records.py', + 'j.get("status") not in JOB_STATUSES or (done and j["status"] != "completed") for j in jobs', + 'j.get("status") not in JOB_STATUSES for j in jobs', UNREAD_JOBS), + ('a job in a status GitHub gives none is read as one that waits', 'adapters/records.py', + 'j.get("status") not in JOB_STATUSES or (done and j["status"] != "completed") for j in jobs', + 'done and j.get("status") != "completed" for j in jobs', UNREAD_JOBS), ('jobs GitHub did not answer are read', 'adapters/records.py', ' body = answer["body"] if answer["status"] == 200 and isinstance(answer["body"], dict) else {}\n jobs', ' body = answer["body"] if isinstance(answer["body"], dict) else {}\n jobs', UNREAD_JOBS), From a6306613ceba26373673b6ef3260431aea060b7c Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 10:46:48 -0600 Subject: [PATCH 09/14] Carbon's read of the port: what is kept is said past the cap and of no queued Run, and the record says who asks when (#724) Co-Authored-By: Claude --- ...-progress-or-ran-and-kept-by-the-pass-records.md | 7 +++---- tests/test_adapters.py | 10 ++++++++++ tools/mutants.py | 13 ++++++++++++- 3 files changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/decisions/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.md b/docs/decisions/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.md index 39c7d6c0..6001ddcd 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -12,10 +12,9 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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; a job of another attempt than the list gave; a job in a status GitHub gives 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 | The Kernel, and the Harness's two reads of the records, until the pull request that follows this one, a person's to approve, has them ask for their own item's Runs; the Kernel's reading follows that | A Run reads its item as the pass does. Were the Kernel to read the field first, a Run's reading would lack what the pass's has | +| 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 | -| No stamp | A jobs read leaves no date and no age in the pass record | Nothing acts on a read's age | ## Why @@ -26,5 +25,5 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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 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: "jobs GitHub did not answer are read", mutant: "jobs listed short of their count are read", mutant: "another attempt's jobs are read", mutant: "a job whose attempt is no number is its run's", 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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | -| 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: "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" | +| 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: "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: "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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | +| 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: "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" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index 9e04440f..fedd9ff1 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1429,6 +1429,11 @@ def read(*found, **kw): stale["response"]["body"]["workflow_runs"][1].update(status="in_progress", conclusion=None) got, asked = read(stale, jobs_read("P-64", 9, 701), jobs[3], began=kept) self.assertEqual(("began_at" in got["runs"][1], asked), (False, [701, 703])) + # What is kept is said of no Run the list gives as not yet started, which has no job asked either. + early = copy.deepcopy(rows) + early["response"]["body"]["workflow_runs"][0].update(status="queued", conclusion=None) + got, asked = read(early, jobs[3], began=kept) + self.assertEqual(("began_at" in got["runs"][0], asked), (False, [703])) # A re-run starts again, at another time, and a row that names no start of its attempt, or a key listed twice, # is asked whatever is kept. rerun = copy.deepcopy(rows) @@ -1468,6 +1473,11 @@ def read(*found, **kw): (began[:2] + ["none", "none"], False, [700, 701])) rest, asked = read(rows, jobs[2], jobs[3], began=record(capped)) self.assertEqual((rest["runs"], rest["complete"], asked), (first["runs"], True, [702, 703])) + # What is kept is still said of a Run listed after one the cap left unasked. + with mock.patch.object(records, "JOBS", 1): + got, asked = read(rows, jobs[0], began={k: v for k, v in kept.items() if k[0] == "r_000002Z"}) + self.assertEqual(([r.get("began_at", "none") for r in got["runs"]], got["complete"], asked), + ([began[0], "none", began[2], "none"], False, [700])) def test_a_status_or_a_conclusion_github_would_not_give_a_run_makes_the_list_short(self): self.assertEqual(self.read(listing("P-17", 3, rows={"name": NAME, "status": "waiting"}))[0]["runs"][0]["status"], diff --git a/tools/mutants.py b/tools/mutants.py index c4a738c2..1e249fb2 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4345,7 +4345,7 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: 'if (', BEGAN), ('a completed job no runner ran says when its Run began', 'adapters/records.py', ' and isinstance(j.get("runner_name"), str) and j["runner_name"] != "")]', - ')]', BEGAN), + ' and j.get("runner_name") != "")]', BEGAN), ('a job that waits with a runner named says when its Run began', 'adapters/records.py', ' or (j.get("status") == "completed" and isinstance(j.get("runner_name"), str)', ' or (isinstance(j.get("runner_name"), str)', BEGAN), @@ -4409,6 +4409,17 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ('when a Run began is kept across attempts', 'adapters/records.py', ' if keyed and (record["run"], record["started_at"]) in began:\n record["began_at"] = began[(record["run"], record["started_at"])]\n', ' if keyed and any(k[0] == record["run"] for k in began):\n record["began_at"] = next(v for k, v in began.items() if k[0] == record["run"])\n', BEGUN), + ('null kept stays on a Run the list gives as running still, if its jobs say nothing', 'adapters/records.py', + ' continue\n del record["began_at"]\n', ' continue\n', BEGUN), + ('a time kept for a Run in progress is asked again', 'adapters/records.py', + ' if record["began_at"] is not None or record["status"] == "completed":\n', + ' if record["status"] == "completed":\n', BEGUN), + ('the cap ends the saying of what was kept', 'adapters/records.py', + ' if asked == JOBS:\n whole = False\n continue\n', + ' if asked == JOBS:\n whole = False\n break\n', BEGUN), + ('a count of jobs that is no number is read', 'adapters/records.py', + 'type(body.get("total_count")) is not int or body["total_count"] != len(jobs)', + 'body.get("total_count") != len(jobs)', UNREAD_JOBS), ('null kept is said of a Run the list gives as running still', 'adapters/records.py', ' if record["began_at"] is not None or record["status"] == "completed":\n continue\n del record["began_at"]\n', ' continue\n', BEGUN), From b73c482d66cc621d2b0787cb77a0c7c4ddb1474d Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 11:02:57 -0600 Subject: [PATCH 10/14] Astra's second read of the port: a status that is no word, more jobs than their count, and a list that stays not whole (#724) Co-Authored-By: Claude --- adapters/records.py | 3 ++- ...n-progress-or-ran-and-kept-by-the-pass-records.md | 4 ++-- tests/test_adapters.py | 5 +++++ tools/mutants.py | 12 ++++++++---- 4 files changed, 17 insertions(+), 7 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index 31a4b12c..5e42d931 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -221,7 +221,8 @@ def _began(transport, repo: str, github_id: int, attempt, done: bool) -> tuple: or type(attempt) is not int or any(not isinstance(j, dict) or type(j.get("run_attempt")) is not int or j["run_attempt"] != attempt for j in jobs): return {}, False - if any(j.get("status") not in JOB_STATUSES or (done and j["status"] != "completed") for j in jobs): + if any(not isinstance(j.get("status"), str) or j["status"] not in JOB_STATUSES + 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"] != "")] diff --git a/docs/decisions/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.md b/docs/decisions/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.md index 6001ddcd..f3fac730 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -25,5 +25,5 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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 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: "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: "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: "jobs that cannot be read leave the list whole", mutant: "a read of jobs may be cached" | -| 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: "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" | +| 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: "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: "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" | +| 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: "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" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index fedd9ff1..7ba25852 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1382,6 +1382,8 @@ def changed(at, **change): ("completed", jobs_read("P-64", 33, gid, started_at=None), {}), ("completed", jobs_read("P-64", 9, gid), {}), ("completed", jobs_read("P-64", 18, gid), {}), ("in_progress", jobs_read("P-64", 18, gid, status=None), {}), + ("in_progress", jobs_read("P-64", 18, gid, status=[]), {}), + ("in_progress", changed(18, total_count=0), {}), ("in_progress", jobs_read("P-64", 9, gid, status="odd"), {})): record, whole = self.began(status, found, rows=rows) self.assertEqual(("began_at" in record, whole), (False, False), (status, found["response"], rows)) @@ -1473,6 +1475,9 @@ def read(*found, **kw): (began[:2] + ["none", "none"], False, [700, 701])) rest, asked = read(rows, jobs[2], jobs[3], began=record(capped)) self.assertEqual((rest["runs"], rest["complete"], asked), (first["runs"], True, [702, 703])) + # One Run's jobs that cannot be read leave the list not whole, whatever the Runs after it give. + got, asked = read(rows, dict(jobs[0], response=dict(jobs[0]["response"], status=404)), *jobs[1:], began={}) + self.assertEqual(([r.get("began_at", "none") for r in got["runs"]], got["complete"]), (["none"] + began[1:] + ["none"], False)) # What is kept is still said of a Run listed after one the cap left unasked. with mock.patch.object(records, "JOBS", 1): got, asked = read(rows, jobs[0], began={k: v for k, v in kept.items() if k[0] == "r_000002Z"}) diff --git a/tools/mutants.py b/tools/mutants.py index 1e249fb2..e39eff18 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4368,11 +4368,11 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ' in ran if began is not None else []:', ' in ran if began is not None else ran:', BEGAN), ('a job not yet completed of a completed run is read', 'adapters/records.py', - 'j.get("status") not in JOB_STATUSES or (done and j["status"] != "completed") for j in jobs', - 'j.get("status") not in JOB_STATUSES for j in jobs', UNREAD_JOBS), + '\n or (done and j["status"] != "completed") for j in jobs):', + ' for j in jobs):', UNREAD_JOBS), ('a job in a status GitHub gives none is read as one that waits', 'adapters/records.py', - 'j.get("status") not in JOB_STATUSES or (done and j["status"] != "completed") for j in jobs', - 'done and j.get("status") != "completed" for j in jobs', UNREAD_JOBS), + 'not isinstance(j.get("status"), str) or j["status"] not in JOB_STATUSES\n or (done', + '(done', UNREAD_JOBS), ('jobs GitHub did not answer are read', 'adapters/records.py', ' body = answer["body"] if answer["status"] == 200 and isinstance(answer["body"], dict) else {}\n jobs', ' body = answer["body"] if isinstance(answer["body"], dict) else {}\n jobs', UNREAD_JOBS), @@ -4397,6 +4397,10 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ('a start on no day of the calendar is a time', 'adapters/records.py', ' try:\n datetime.datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")\n except ValueError:\n return False\n return True\n', ' return True\n', UNREAD_JOBS), + ('a Run whose jobs are read makes the list whole again after one whose are not', 'adapters/records.py', + ' whole = whole and answered\n', ' whole = answered\n', BEGUN), + ('more jobs than their count are read', 'adapters/records.py', + ' or body["total_count"] != len(jobs) \\\n', ' or body["total_count"] > len(jobs) \\\n', UNREAD_JOBS), ('jobs that cannot be read leave the list whole', 'adapters/records.py', ' record.update(found)\n whole = whole and answered\n', ' record.update(found)\n', UNREAD_JOBS), From e7a1a563df48dc8a0d943c8c6f71e4ed8bd0295d Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 11:09:28 -0600 Subject: [PATCH 11/14] Astra's third read of the port: a job listed twice, the cap's number and a null beginning are held (#724) Co-Authored-By: Claude --- adapters/records.py | 3 ++- ...-in-progress-or-ran-and-kept-by-the-pass-records.md | 6 +++--- tests/test_adapters.py | 10 ++++++++-- tools/mutants.py | 5 +++++ 4 files changed, 18 insertions(+), 6 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index 5e42d931..486b96df 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -211,13 +211,14 @@ def _began(transport, repo: str, github_id: int, attempt, done: bool) -> tuple: 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 of the attempt the list gave and in a + a start. Not whole: an answer that is no list of every job counted, each once, of the attempt the list gave 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" % (repo, github_id), headers=FRESH)) 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({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 j["run_attempt"] != attempt for j in jobs): return {}, False diff --git a/docs/decisions/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.md b/docs/decisions/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.md index f3fac730..e1f1326c 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -11,7 +11,7 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | What is asked | `GET /repos/{repo}/actions/runs/{id}/jobs`, as P-64 asked it, 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 | | 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; a job of another attempt than the list gave; a job in a status GitHub gives 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 | +| 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; 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 | @@ -24,6 +24,6 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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 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" | +| 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: "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: "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: "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" | -| 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: "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" | +| 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" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index 7ba25852..ff5b1ad6 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -20,6 +20,7 @@ from adapters import acceptance, applied, artifacts, checks, edits, effects, facts, github, heldout, items, passes, pull, records, \ pause, rules, texts, threads, timeline +from controller import shared from harness import task from kernel import brakes from tests.support import pending @@ -1331,6 +1332,7 @@ def test_a_run_began_when_a_job_of_it_did(self): ("2026-11-10T19:44:48Z", "2026-10-18T01:29:07Z", True), status) record, whole = self.began("completed", jobs_read("P-44", 23, gid)) self.assertEqual((record["began_at"], whole), (None, True)) + self.assertEqual(shared.errors(record, "run-record"), []) # null is a run record's to hold # A runner's name alone tells a completed job that ran, and a job in progress needs none. for name in ("", None, 7): self.assertEqual(self.began("completed", jobs_read("P-64", 33, gid, runner_name=name)), (record, True), name) @@ -1343,8 +1345,11 @@ def test_a_run_began_when_a_job_of_it_did(self): # Of several jobs, the earliest that began; one that waits beside it says nothing. both = jobs_read("P-64", 33, gid) both["response"]["body"].update(total_count=3, jobs=[ - dict(ran, started_at="2026-11-10T19:45:00Z"), ran, dict(waiting, started_at="2026-11-10T19:40:00Z")]) + dict(ran, id=1, started_at="2026-11-10T19:45:00Z"), ran, dict(waiting, id=2, started_at="2026-11-10T19:40:00Z")]) self.assertEqual(self.began("in_progress", both)[0]["began_at"], "2026-11-10T19:44:48Z") + # A job listed twice may stand where another was left out: no read of the jobs. + both["response"]["body"]["jobs"][0]["id"] = ran["id"] + self.assertEqual(self.began("in_progress", both)[1], False) # A Run not yet started, or a caller that asks for none, has no job read: the replay holds no answer to one. record, whole = self.began("queued") self.assertEqual(("began_at" in record, whole), (False, True)) @@ -1462,7 +1467,7 @@ def read(*found, **kw): # runs, in no trial): the earliest, before the attempt's own start, is what the record says. carried = jobs_read("P-64", 33, 700) carried["response"]["body"].update(total_count=2, jobs=[ - dict(exchanges("P-64")[33]["response"]["body"]["jobs"][0], started_at="2026-10-20T23:50:00Z"), + dict(exchanges("P-64")[33]["response"]["body"]["jobs"][0], id=1, started_at="2026-10-20T23:50:00Z"), dict(exchanges("P-64")[33]["response"]["body"]["jobs"][0], started_at="2026-10-21T00:00:05Z")]) got, _ = read(rows, carried, *jobs[1:], began={}) self.assertEqual((got["runs"][0]["began_at"], got["runs"][0]["started_at"]), @@ -1478,6 +1483,7 @@ def read(*found, **kw): # One Run's jobs that cannot be read leave the list not whole, whatever the Runs after it give. got, asked = read(rows, dict(jobs[0], response=dict(jobs[0]["response"], status=404)), *jobs[1:], began={}) self.assertEqual(([r.get("began_at", "none") for r in got["runs"]], got["complete"]), (["none"] + began[1:] + ["none"], False)) + self.assertEqual(records.JOBS, 50) # What is kept is still said of a Run listed after one the cap left unasked. with mock.patch.object(records, "JOBS", 1): got, asked = read(rows, jobs[0], began={k: v for k, v in kept.items() if k[0] == "r_000002Z"}) diff --git a/tools/mutants.py b/tools/mutants.py index e39eff18..e8eb6d85 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4399,6 +4399,11 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ' return True\n', UNREAD_JOBS), ('a Run whose jobs are read makes the list whole again after one whose are not', 'adapters/records.py', ' whole = whole and answered\n', ' whole = answered\n', BEGUN), + ('a job listed twice is read as two', 'adapters/records.py', + ' or len({j.get("id") for j in jobs if isinstance(j, dict)}) != len(jobs) \\\n', '', BEGAN), + ('a run record may not say it never began', 'schemas/run-record.schema.json', + ' "string",\n "null"\n ],\n "pattern"', ' "string"\n ],\n "pattern"', BEGAN), + ('the cap on jobs reads is another', 'adapters/records.py', 'JOBS = 50 ', 'JOBS = 51 ', BEGUN), ('more jobs than their count are read', 'adapters/records.py', ' or body["total_count"] != len(jobs) \\\n', ' or body["total_count"] > len(jobs) \\\n', UNREAD_JOBS), ('jobs that cannot be read leave the list whole', 'adapters/records.py', From 35f22ea38001c86700c1639c3e8af1d16405eb24 Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 11:14:41 -0600 Subject: [PATCH 12/14] Astra's fourth read of the port: a job's id is a number, and every start is held to be a time (#724) Co-Authored-By: Claude --- adapters/records.py | 3 ++- ...ob-is-in-progress-or-ran-and-kept-by-the-pass-records.md | 4 ++-- tests/test_adapters.py | 6 +++++- tools/mutants.py | 6 +++++- 4 files changed, 14 insertions(+), 5 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index 486b96df..f0cc4569 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -218,8 +218,9 @@ def _began(transport, repo: str, github_id: int, attempt, done: bool) -> tuple: 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({j.get("id") for j in jobs if isinstance(j, dict)}) != 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 diff --git a/docs/decisions/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.md b/docs/decisions/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.md index e1f1326c..f2a8852f 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -24,6 +24,6 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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: "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: "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: "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" | +| 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: "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" | | 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" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index ff5b1ad6..d34fc611 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1347,9 +1347,12 @@ def test_a_run_began_when_a_job_of_it_did(self): both["response"]["body"].update(total_count=3, jobs=[ dict(ran, id=1, started_at="2026-11-10T19:45:00Z"), ran, dict(waiting, id=2, started_at="2026-11-10T19:40:00Z")]) self.assertEqual(self.began("in_progress", both)[0]["began_at"], "2026-11-10T19:44:48Z") - # A job listed twice may stand where another was left out: no read of the jobs. + # A job listed twice may stand where another was left out, and one start that is no time is no read of any. both["response"]["body"]["jobs"][0]["id"] = ran["id"] self.assertEqual(self.began("in_progress", both)[1], False) + both["response"]["body"]["jobs"][0].update(id=1, started_at="2026-02-30T19:45:00Z") + record, whole = self.began("in_progress", both) + self.assertEqual(("began_at" in record, whole), (False, False)) # A Run not yet started, or a caller that asks for none, has no job read: the replay holds no answer to one. record, whole = self.began("queued") self.assertEqual(("began_at" in record, whole), (False, True)) @@ -1378,6 +1381,7 @@ def changed(at, **change): ("in_progress", changed(18, jobs=["lane"], total_count=1), {}), ("in_progress", jobs_read("P-64", 18, gid, run_attempt=2), {}), ("in_progress", jobs_read("P-64", 18, gid, run_attempt=True), {}), + ("in_progress", jobs_read("P-64", 18, gid, id=[]), {}), ("in_progress", jobs_read("P-64", 18, gid, id="7"), {}), ("in_progress", jobs_read("P-64", 18, gid, run_attempt=1.0), {}), ("in_progress", jobs_read("P-64", 18, gid), {"run_attempt": True}), ("in_progress", jobs_read("P-64", 18, gid), {"run_attempt": None}), diff --git a/tools/mutants.py b/tools/mutants.py index e8eb6d85..156e534d 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4400,7 +4400,11 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ('a Run whose jobs are read makes the list whole again after one whose are not', 'adapters/records.py', ' whole = whole and answered\n', ' whole = answered\n', BEGUN), ('a job listed twice is read as two', 'adapters/records.py', - ' or len({j.get("id") for j in jobs if isinstance(j, dict)}) != len(jobs) \\\n', '', BEGAN), + ' or len({str(j.get("id")) for j in jobs if isinstance(j, dict)}) != len(jobs) \\\n', '', BEGAN), + ('a job whose id is no number is read', 'adapters/records.py', + ' or type(j.get("id")) is not int\n', '', UNREAD_JOBS), + ('only the first start is held to be a time', 'adapters/records.py', + ' if not all(_time(start) for start in starts):\n', ' if not all(_time(start) for start in starts[1:]):\n', BEGAN), ('a run record may not say it never began', 'schemas/run-record.schema.json', ' "string",\n "null"\n ],\n "pattern"', ' "string"\n ],\n "pattern"', BEGAN), ('the cap on jobs reads is another', 'adapters/records.py', 'JOBS = 50 ', 'JOBS = 51 ', BEGUN), From c37e2f8ad44e1f3fae99e86fa154f87803f571f0 Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 11:21:33 -0600 Subject: [PATCH 13/14] Astra's fifth read of the port: a runner that is neither a name nor none is no read, and a short list stays not whole (#724) Co-Authored-By: Claude --- adapters/records.py | 3 ++- ...-is-in-progress-or-ran-and-kept-by-the-pass-records.md | 4 ++-- tests/test_adapters.py | 8 +++++++- tools/mutants.py | 6 ++++-- 4 files changed, 15 insertions(+), 6 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index f0cc4569..108a197f 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -211,7 +211,7 @@ def _began(transport, repo: str, github_id: int, attempt, done: bool) -> tuple: 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 and in a + 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" % (repo, github_id), headers=FRESH)) @@ -224,6 +224,7 @@ def _began(transport, repo: str, github_id: int, attempt, done: bool) -> tuple: 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" diff --git a/docs/decisions/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.md b/docs/decisions/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.md index f2a8852f..a8dc303e 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -11,7 +11,7 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | What is asked | `GET /repos/{repo}/actions/runs/{id}/jobs`, as P-64 asked it, 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 | | 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; 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 | +| 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 | @@ -25,5 +25,5 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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: "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" | +| 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" | | 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" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index d34fc611..531311e9 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1146,6 +1146,11 @@ def test_a_list_read_short_is_not_whole(self): self.assertIs(got["complete"], False) got, _ = self.read(listing("P-17", 3, rows={"name": NAME}, total=2)) self.assertIs(got["complete"], False) + # A list read short stays not whole when the jobs of the Runs it did give are read whole (decision 0193). + gid = exchanges("P-17")[3]["response"]["body"]["workflow_runs"][0]["id"] + got, _ = self.read(listing("P-17", 3, rows={"name": NAME, "status": "in_progress"}, total=2), + jobs_read("P-64", 18, gid), began={}) + self.assertEqual((got["runs"][0]["began_at"], got["complete"]), ("2026-11-10T19:44:48Z", False)) broken = listing("P-17", 3) broken["response"]["body"]["workflow_runs"] = None self.assertIs(self.read(broken)[0]["complete"], False) @@ -1334,7 +1339,7 @@ def test_a_run_began_when_a_job_of_it_did(self): self.assertEqual((record["began_at"], whole), (None, True)) self.assertEqual(shared.errors(record, "run-record"), []) # null is a run record's to hold # A runner's name alone tells a completed job that ran, and a job in progress needs none. - for name in ("", None, 7): + for name in ("", None): self.assertEqual(self.began("completed", jobs_read("P-64", 33, gid, runner_name=name)), (record, True), name) self.assertEqual(self.began("in_progress", jobs_read("P-64", 18, gid, runner_name=None))[0]["began_at"], "2026-11-10T19:44:48Z") @@ -1392,6 +1397,7 @@ def changed(at, **change): ("completed", jobs_read("P-64", 9, gid), {}), ("completed", jobs_read("P-64", 18, gid), {}), ("in_progress", jobs_read("P-64", 18, gid, status=None), {}), ("in_progress", jobs_read("P-64", 18, gid, status=[]), {}), + ("completed", jobs_read("P-64", 33, gid, runner_name=7), {}), ("in_progress", changed(18, total_count=0), {}), ("in_progress", jobs_read("P-64", 9, gid, status="odd"), {})): record, whole = self.began(status, found, rows=rows) diff --git a/tools/mutants.py b/tools/mutants.py index cd7cc1dc..4376fd00 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4370,9 +4370,11 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ('a job not yet completed of a completed run is read', 'adapters/records.py', '\n or (done and j["status"] != "completed") for j in jobs):', ' for j in jobs):', UNREAD_JOBS), + ('a runner that is no name is no runner', 'adapters/records.py', + ' or not isinstance(j.get("runner_name"), (str, type(None)))\n', '', UNREAD_JOBS), ('a job in a status GitHub gives none is read as one that waits', 'adapters/records.py', - 'not isinstance(j.get("status"), str) or j["status"] not in JOB_STATUSES\n or (done', - '(done', UNREAD_JOBS), + 'not isinstance(j.get("status"), str) or j["status"] not in JOB_STATUSES\n', + 'False\n', UNREAD_JOBS), ('jobs GitHub did not answer are read', 'adapters/records.py', ' body = answer["body"] if answer["status"] == 200 and isinstance(answer["body"], dict) else {}\n jobs', ' body = answer["body"] if isinstance(answer["body"], dict) else {}\n jobs', UNREAD_JOBS), From 6286861f33915705076b48ffc36fcdf9086c38b1 Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Wed, 11 Nov 2026 11:23:34 -0600 Subject: [PATCH 14/14] A run's jobs are asked a hundred to a page, and the record cites its issue by title first (#724) cubic on #751: thirty to a page, a run with more jobs would never be read whole. Co-Authored-By: Claude --- adapters/records.py | 3 ++- ...b-is-in-progress-or-ran-and-kept-by-the-pass-records.md | 6 +++--- tests/test_adapters.py | 7 ++++--- tools/mutants.py | 6 ++++-- 4 files changed, 13 insertions(+), 9 deletions(-) diff --git a/adapters/records.py b/adapters/records.py index 108a197f..0a053134 100644 --- a/adapters/records.py +++ b/adapters/records.py @@ -214,7 +214,8 @@ def _began(transport, repo: str, github_id: int, attempt, done: bool) -> tuple: 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" % (repo, github_id), headers=FRESH)) + answer = transport.send(request("GET", "/repos/%s/actions/runs/%d/jobs?per_page=%d" % (repo, github_id, PAGE), + headers=FRESH)) 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) \ diff --git a/docs/decisions/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.md b/docs/decisions/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.md index a8dc303e..7be29891 100644 --- a/docs/decisions/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.md +++ b/docs/decisions/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.md @@ -1,6 +1,6 @@ # 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 issue 724, "A record's start is read from its job's started_at, trusted only once the job is in progress or ran (P-64)". 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. +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 @@ -8,7 +8,7 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re |---|---|---| | 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, 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 | +| 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 | | 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 | @@ -25,5 +25,5 @@ Status: accepted. The Factory Builder's ruling of 2026-11-11 on issue 724, "A re | 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" | +| 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" | diff --git a/tests/test_adapters.py b/tests/test_adapters.py index 531311e9..7dd58f11 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1046,7 +1046,8 @@ def jobs_read(name: str, at: int, github_id: int, **change) -> dict: """A fixture's read of a run's jobs, asked of the run GitHub numbers `github_id`, each job changed as named.""" found = copy.deepcopy(exchanges(name)[at]) words = found["request"]["call"].split() - found["request"]["call"] = " ".join([words[0], "/repos/%s/actions/runs/%d/jobs" % (canary(), github_id)] + words[2:]) + found["request"]["call"] = " ".join([words[0], "/repos/%s/actions/runs/%d/jobs?per_page=100" % (canary(), github_id)] + + words[2:]) for job in found["response"]["body"]["jobs"]: job.update(change) return found @@ -1370,7 +1371,7 @@ def test_jobs_that_cannot_be_read_say_no_start(self): jobs_read("P-64", 18, gid)])) records.runs(sent, canary(), "main", [WORKFLOW], DISPATCHER, per_page=10, began={}) self.assertEqual((sent.sent[1]["path"], sent.sent[1]["headers"]), - ("/repos/%s/actions/runs/%d/jobs" % (canary(), gid), {"Cache-Control": "no-cache"})) + ("/repos/%s/actions/runs/%d/jobs?per_page=100" % (canary(), gid), {"Cache-Control": "no-cache"})) def changed(at, **change): found = jobs_read("P-64", at, gid) @@ -1433,7 +1434,7 @@ def read(*found, **kw): """What a read gave, and the runs whose jobs it asked for, by GitHub's id, in order.""" sent = Recording(github.Replay(list(found))) got = records.runs(sent, canary(), "main", [WORKFLOW], DISPATCHER, per_page=10, **kw) - return got, [int(r["path"].split("/")[-2]) for r in sent.sent if r["path"].endswith("/jobs")] + return got, [int(r["path"].split("/")[-2]) for r in sent.sent if "/jobs?" in r["path"]] first, asked = read(rows, *jobs, began={}) self.assertEqual(([r.get("began_at", "none") for r in first["runs"]], first["complete"], asked), (began + ["none"], True, [700, 701, 702, 703])) diff --git a/tools/mutants.py b/tools/mutants.py index 4376fd00..4d715cde 100644 --- a/tools/mutants.py +++ b/tools/mutants.py @@ -4416,8 +4416,10 @@ def moved_before(rel: str, block: str, anchor: str) -> tuple: ' record.update(found)\n whole = whole and answered\n', ' record.update(found)\n', UNREAD_JOBS), ('a read of jobs may be cached', 'adapters/records.py', - '/jobs" % (repo, github_id), headers=FRESH))', - '/jobs" % (repo, github_id)))', UNREAD_JOBS), + ' headers=FRESH))\n body = answer', + ' ))\n body = answer', UNREAD_JOBS), + ('a run\'s jobs are asked thirty to a page', 'adapters/records.py', + '/jobs?per_page=%d" % (repo, github_id, PAGE),', '/jobs" % (repo, github_id),', UNREAD_JOBS), ('when a Run began is asked again though kept', 'adapters/records.py', ' if keyed and (record["run"], record["started_at"]) in began:\n', ' if False:\n', BEGUN),