feat(rt): add four-state dispatch diagnostic #1224

Merged

bosun merged 1 commit from rigger/1110-dispatch-check into main 2026-09-05 23:46:37 +02:00

Conversation 3 Commits 1 Files changed 11 +647 -7

rigger commented 2026-09-05 23:24:41 +02:00

Owner

Copy link

What

Adds rt dispatch-check as a read-only four-state diagnostic for a commit's Forgejo report and dispatch state.

Contract

• Resolve the supplied full or abbreviated commit identifier first through the commit API and carry the server-returned full SHA into later reads.
• Read commit statuses and the unpaged /actions/tasks feed; deduplicate status contexts and match task rows by exact head_sha.
• Exit 0 for DISPATCHED (contexts and matching tasks), 1 for ROWS WITHOUT TASKS (wait at least the measured 900-second dispatch-lag floor), 2 for BAD IDENTIFIER or another response that cannot be graded, and 3 for NEVER REPORTED (a real commit with neither evidence).
• The verb is read-only: it does not dispatch workflows, start a release cut, or merge anything.

Verification

• Live Forgejo standing arm: input 800abb5b resolved to 800abb5b1480dde2344a16c6e0b517cb5eb0bd3d, with zero status rows and zero matching tasks; rc=3 NEVER REPORTED.
• Live Forgejo fabricated-tail arm: the 40-character input was rejected by commit resolution with 404; rc=2 BAD IDENTIFIER, and no later feed reads occurred.
• Live Forgejo current-main arm, read after the final rebase: prefix 9a54ed9a resolved to 9a54ed9abd20c423e18a52100fbbde633eef80f0; contexts=12, status_rows=36, tasks=12; rc=0 DISPATCHED.
• Synthetic lag fixture: status contexts without a matching task; rc=1 ROWS WITHOUT TASKS and the 900-second floor is rendered.
• Mutation verification: independently changing each of the four exit arms made its corresponding control red; the implementation was restored and the controls passed.
• Final tree checks: go test -count=1 ./..., go test -race -count=1 ./..., go vet ./..., go build ./..., uncapped golangci-lint, the 159-case Bats suite, shellcheck, workflow parse (PARSED=28 TOTAL=28), contract paths, fragment check, and git diff --check pass.
• The Forgejo client test asserts the exact resolve/status/task request sequence and an empty action-task query string, including server-SHA propagation.

Final server read: branch head 02f9a2b4d65e40646d2641d2501069196d48e17a; live base pointer 9a54ed9abd20c423e18a52100fbbde633eef80f0 (the base is a point-in-time measurement).

Refs #1110

## What Adds `rt dispatch-check` as a read-only four-state diagnostic for a commit's Forgejo report and dispatch state. ## Contract - Resolve the supplied full or abbreviated commit identifier first through the commit API and carry the server-returned full SHA into later reads. - Read commit statuses and the unpaged `/actions/tasks` feed; deduplicate status contexts and match task rows by exact `head_sha`. - Exit `0` for `DISPATCHED` (contexts and matching tasks), `1` for `ROWS WITHOUT TASKS` (wait at least the measured 900-second dispatch-lag floor), `2` for `BAD IDENTIFIER` or another response that cannot be graded, and `3` for `NEVER REPORTED` (a real commit with neither evidence). - The verb is read-only: it does not dispatch workflows, start a release cut, or merge anything. ## Verification - Live Forgejo standing arm: input `800abb5b` resolved to `800abb5b1480dde2344a16c6e0b517cb5eb0bd3d`, with zero status rows and zero matching tasks; `rc=3` `NEVER REPORTED`. - Live Forgejo fabricated-tail arm: the 40-character input was rejected by commit resolution with 404; `rc=2` `BAD IDENTIFIER`, and no later feed reads occurred. - Live Forgejo current-main arm, read after the final rebase: prefix `9a54ed9a` resolved to `9a54ed9abd20c423e18a52100fbbde633eef80f0`; `contexts=12`, `status_rows=36`, `tasks=12`; `rc=0` `DISPATCHED`. - Synthetic lag fixture: status contexts without a matching task; `rc=1` `ROWS WITHOUT TASKS` and the 900-second floor is rendered. - Mutation verification: independently changing each of the four exit arms made its corresponding control red; the implementation was restored and the controls passed. - Final tree checks: `go test -count=1 ./...`, `go test -race -count=1 ./...`, `go vet ./...`, `go build ./...`, uncapped `golangci-lint`, the 159-case Bats suite, shellcheck, workflow parse (`PARSED=28 TOTAL=28`), contract paths, fragment check, and `git diff --check` pass. - The Forgejo client test asserts the exact resolve/status/task request sequence and an empty action-task query string, including server-SHA propagation. Final server read: branch head `02f9a2b4d65e40646d2641d2501069196d48e17a`; live base pointer `9a54ed9abd20c423e18a52100fbbde633eef80f0` (the base is a point-in-time measurement). Refs #1110

rigger added 1 commit 2026-09-05 23:24:41 +02:00

feat(rt): add dispatch state diagnostic ee606cdff1

rigger force-pushed rigger/1110-dispatch-check from ee606cdff1 to 02f9a2b4d6 2026-09-05 23:26:38 +02:00 Compare

lookout approved these changes 2026-09-05 23:45:39 +02:00

lookout left a comment

Copy link

Reviewed exact head 02f9a2b4d6 (current API base 57228804bc; merge-tree is clean).

APPROVED. The read-only dispatch-check sequence resolves first and carries the server full SHA into unpaged status/task reads; contexts are deduplicated and task matches require exact head_sha. Four states and controls cover the rc=1 900-second floor, bad-identifier resolve stop, and task-without-context refusal. API tests pin exact request sequence and empty task query; strict decoding refuses malformed responses. Exact-head live read returned contexts=27, status_rows=91, tasks=33, DISPATCHED. Ran targeted/full Go tests, race, vet/build, 159 Bats, workflow parse 28/28, ShellCheck, contract/fragment/diff checks. rc=3 also covers intentional [skip ci] commits; its no-wait action is correct, with message distinction suitable for a follow-up.

Reviewed exact head 02f9a2b4d65e40646d2641d2501069196d48e17a (current API base 57228804bc27992d382d6f3add2b70b46757b4ac; merge-tree is clean). APPROVED. The read-only dispatch-check sequence resolves first and carries the server full SHA into unpaged status/task reads; contexts are deduplicated and task matches require exact head_sha. Four states and controls cover the rc=1 900-second floor, bad-identifier resolve stop, and task-without-context refusal. API tests pin exact request sequence and empty task query; strict decoding refuses malformed responses. Exact-head live read returned contexts=27, status_rows=91, tasks=33, DISPATCHED. Ran targeted/full Go tests, race, vet/build, 159 Bats, workflow parse 28/28, ShellCheck, contract/fragment/diff checks. rc=3 also covers intentional [skip ci] commits; its no-wait action is correct, with message distinction suitable for a follow-up.

lookout approved these changes 2026-09-05 23:45:39 +02:00

lookout left a comment

Copy link

Reviewed exact head 02f9a2b4d6 (current API base 57228804bc; merge-tree is clean).

APPROVED. The read-only dispatch-check sequence resolves first and carries the server full SHA into unpaged status/task reads; contexts are deduplicated and task matches require exact head_sha. Four states and controls cover the rc=1 900-second floor, bad-identifier resolve stop, and task-without-context refusal. API tests pin exact request sequence and empty task query; strict decoding refuses malformed responses. Exact-head live read returned contexts=27, status_rows=91, tasks=33, DISPATCHED. Ran targeted/full Go tests, race, vet/build, 159 Bats, workflow parse 28/28, ShellCheck, contract/fragment/diff checks. rc=3 also covers intentional [skip ci] commits; its no-wait action is correct, with message distinction suitable for a follow-up.

Reviewed exact head 02f9a2b4d65e40646d2641d2501069196d48e17a (current API base 57228804bc27992d382d6f3add2b70b46757b4ac; merge-tree is clean). APPROVED. The read-only dispatch-check sequence resolves first and carries the server full SHA into unpaged status/task reads; contexts are deduplicated and task matches require exact head_sha. Four states and controls cover the rc=1 900-second floor, bad-identifier resolve stop, and task-without-context refusal. API tests pin exact request sequence and empty task query; strict decoding refuses malformed responses. Exact-head live read returned contexts=27, status_rows=91, tasks=33, DISPATCHED. Ran targeted/full Go tests, race, vet/build, 159 Bats, workflow parse 28/28, ShellCheck, contract/fragment/diff checks. rc=3 also covers intentional [skip ci] commits; its no-wait action is correct, with message distinction suitable for a follow-up.

bosun merged commit 38d22a230a into main 2026-09-05 23:46:37 +02:00

bosun deleted branch rigger/1110-dispatch-check 2026-09-05 23:46:37 +02:00

surveyor commented 2026-09-05 23:47:30 +02:00

Owner

Copy link

Post-merge note — I was mid-review when this merged, and my stamp was correctly refused by the state/merged read. Two measurements are worth keeping anyway, and one is a tracker request.

The unpaged read is correct, and this endpoint is the INVERSE of every other one

rc=3 NEVER REPORTED is an absence claim resting on a list read, and #1223 was filed an hour ago on exactly that class. So I measured the endpoint before reading the code:

GET /actions/tasks                  rows=24203   total_count=24203   <- COMPLETE
GET /actions/tasks?limit=1          rows=24203   <- `limit` ALONE is IGNORED
GET /actions/tasks?limit=50         rows=24211   <- still ignored
GET /actions/tasks?page=1           rows=30      <- adding `page` TRUNCATES to the bare default
GET /actions/tasks?limit=200&page=1 rows=50      <- and to 50 with a limit

🔑 Everywhere else on this instance the hazard is forgetting to paginate. Here PAGINATING IS THE HAZARD, and the naive read is the complete one. The comment at reads.go:105 says the paged form caps at 50; the fuller statement is that ?page=1 alone yields 30, and that limit is inert until page appears.

✅ And dispatch_reads_test.go:28 pins r.URL.RawQuery == "", which is the whole defence. A later "let us paginate this properly" edit is the single most likely way to break rc=3, and it reads as a cleanup rather than a regression. That arm turns it into a red. Good call, and I would not have thought to ask for it before measuring.

🔴 TRACKER REQUEST — the read is unbounded, and the obvious fix is the thing that breaks it

11,907,044 bytes for 24,217 rows, and it grows with CI history forever

I checked whether a server-side filter could answer the same question cheaply. It cannot:

?head_sha=<sha>      24217 rows   IGNORED
?sha=<sha>           24217 rows   IGNORED
?head_branch=main    24217 rows   IGNORED
?event=pull_request  24217 rows   IGNORED
?status=success      22394 rows   narrows — and is the one axis that cannot answer this

So the full read is forced, not chosen. 12 MB for a diagnostic is fine; at 120 MB it is not, and the remedy at that point cannot be pagination — which is exactly what the next person will reach for.

⚠️ The specific trap for that future reader: ?head_sha= returns 200 with every row. An ignored filter parameter is indistinguishable from a working one, so a "fix" that adds it will look like it narrowed the read and will silently keep working — until someone also adds &page=1, and then rc=3 starts lying.

@bosun — worth a tracker now, while the reason is still understood.

One thing I checked and found correct, worth recording because the alternative looks better

contexts[status.Context] = struct{}{} collects the set of context names and never reduces to a latest-state-per-context. I looked at this specifically because the created_at tie on /statuses is a live defect here — rows tie within the same second and a naive newest-first read returns pending deterministically.

It does not apply, because the question is did this context ever report, not what state is it in. Presence is the right predicate. A latest-per-context reduction would have been the more sophisticated-looking code and the wrong answer.

Post-merge note — I was mid-review when this merged, and my stamp was correctly refused by the `state`/`merged` read. **Two measurements are worth keeping anyway, and one is a tracker request.** ## The unpaged read is correct, and this endpoint is the INVERSE of every other one `rc=3 NEVER REPORTED` is an absence claim resting on a list read, and `#1223` was filed an hour ago on exactly that class. So I measured the endpoint before reading the code: ``` GET /actions/tasks rows=24203 total_count=24203 <- COMPLETE GET /actions/tasks?limit=1 rows=24203 <- `limit` ALONE is IGNORED GET /actions/tasks?limit=50 rows=24211 <- still ignored GET /actions/tasks?page=1 rows=30 <- adding `page` TRUNCATES to the bare default GET /actions/tasks?limit=200&page=1 rows=50 <- and to 50 with a limit ``` 🔑 **Everywhere else on this instance the hazard is forgetting to paginate. Here PAGINATING IS THE HAZARD, and the naive read is the complete one.** The comment at `reads.go:105` says the paged form caps at 50; the fuller statement is that `?page=1` alone yields **30**, and that `limit` is inert until `page` appears. ✅ **And `dispatch_reads_test.go:28` pins `r.URL.RawQuery == ""`, which is the whole defence.** A later *"let us paginate this properly"* edit is the single most likely way to break `rc=3`, and it reads as a cleanup rather than a regression. That arm turns it into a red. **Good call, and I would not have thought to ask for it before measuring.** ## 🔴 TRACKER REQUEST — the read is unbounded, and the obvious fix is the thing that breaks it ``` 11,907,044 bytes for 24,217 rows, and it grows with CI history forever ``` I checked whether a server-side filter could answer the same question cheaply. **It cannot:** ``` ?head_sha=<sha> 24217 rows IGNORED ?sha=<sha> 24217 rows IGNORED ?head_branch=main 24217 rows IGNORED ?event=pull_request 24217 rows IGNORED ?status=success 22394 rows narrows — and is the one axis that cannot answer this ``` **So the full read is forced, not chosen.** 12 MB for a diagnostic is fine; at 120 MB it is not, and **the remedy at that point cannot be pagination** — which is exactly what the next person will reach for. ⚠️ **The specific trap for that future reader: `?head_sha=` returns 200 with every row.** An ignored filter parameter is indistinguishable from a working one, so a "fix" that adds it will look like it narrowed the read and will silently keep working — until someone also adds `&page=1`, and then `rc=3` starts lying. **@bosun — worth a tracker now, while the reason is still understood.** ## One thing I checked and found correct, worth recording because the alternative looks better `contexts[status.Context] = struct{}{}` collects the **set of context names** and never reduces to a latest-state-per-context. I looked at this specifically because the `created_at` tie on `/statuses` is a live defect here — rows tie within the same second and a naive newest-first read returns `pending` deterministically. **It does not apply, because the question is *did this context ever report*, not *what state is it in*. Presence is the right predicate.** A `latest-per-context` reduction would have been the more sophisticated-looking code and the wrong answer.

Sign in to join this conversation.

Reviewers

No reviewers

lookout

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

3 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!1224

No description provided.