Repository navigation
Expand file tree
/
Copy pathops.mjs
More file actions
2687 lines (2559 loc) · 171 KB
/
Copy pathops.mjs
File metadata and controls
2687 lines (2559 loc) · 171 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
/**
* fleet-write/ops — the ONE frozen table of what a fleet-write relay may do.
*
* A cloud seat cannot hold the fleet App's identity (its egress proxy replaces
* every `Authorization` header and refuses the `/app/**` mint path), so a seat
* that must write as `objectstack-fleet[bot]` sends ONE `repository_dispatch`
* to the board repo and a workflow there executes the writes with a token the
* runner minted. Everything that crosses that boundary is spelled here, once:
*
* - `PAYLOAD_KEYS` the closed envelope a seat sends (`client_payload`);
* - `OPS` the closed op list, each with its REQUIRED keys, its
* OPTIONAL keys, the endpoint(s) it becomes and the App
* permission it spends;
* - `FIELDS` the typed vocabulary those keys draw from — integer
* numbers, byte-capped strings, capped string lists,
* closed enums;
* - the LIMITS the seat-side packer, the validator and the
* executor all read: action count, caps, and the
* platform's own `client_payload` ceilings.
*
* `validate.mjs` reads this table to REFUSE a payload; `execute.mjs` reads it
* to ISSUE the requests; `dispatch.mjs` reads it to PACK a stroke. None of the
* three restates a key, a cap or an endpoint, so the whitelist has exactly one
* spelling and a fourth op is one row here — reviewed as one row, with its
* permission beside it.
*
* ## What is refused BY CONSTRUCTION
*
* An op is only what this table names. There is no row for a merge of a pull,
* a review submission, a direct branch or ref write (`/git/**`, `/branches/**`,
* `/contents/**`) but one mailbox branch's DELETE (below), a workflow-file write, a run cancel or delete, a whole-run
* or single-job re-run, a cache or artifact write, a release, or any
* organization / administration endpoint, so a payload naming one is refused
* at the validator with zero writes — the `--self-test` of `validate.mjs` pins
* that every path spelled here stays clear of those families and that the
* table's one `PUT` (`pr_update_branch`, below) reaches no whole-set replace
* of labels or assignees. The one re-run the table has re-runs a run's FAILED
* jobs alone, once, on a closed list of workflows (`run_rerun_failed`, below).
*
* ## The one row that moves a branch — `pr_update_branch`
*
* `PUT /repos/{o}/{r}/pulls/{n}/update-branch` is GitHub's own base sync: the
* PLATFORM merges the pull's base into its head and authors that merge commit
* as the identity that asked — through the relay, `objectstack-fleet[bot]`;
* as bare REST under a seat's session token, the seat's personal account, the
* identity exchange every other relay write already refuses. The relay sends
* no ref write of its own. GitHub's permission ledger (the file cited below)
* lists the endpoint under `pull_requests: write`, server-to-server, with no
* additional permission, so the row spends `pull-requests` and the mint step
* widens nothing. `expected_head_sha` is REQUIRED and full-length (`FIELDS`,
* kind `sha`): a short or malformed sha is refused by the validator before the
* dispatch, never left to the platform's 422; a stale one IS the platform's
* 422. How the executor tells that 422 from the "nothing to merge" one, and
* how it confirms a 202, is `execute.mjs`'s (`confirmUpdateBranch`).
*
* ## The one row that deletes a ref — `mailbox_branch_delete`
*
* A cloud seat opens its mailbox on a branch it pushed (`mailbox-open.mjs
* --head`) and cannot delete it, so the relay does, by the maintainer's ruling
* (comment 6674408912, letter A), which opens this ONE row and nothing else.
* `DELETE /repos/{o}/{r}/git/refs/heads/{branch}` is `contents: write`,
* server-to-server, no additional permission (the ledger cited below): a
* grant every stroke already carries for the auto-merge rows, so the mint
* widens nothing. The row creates no ref and writes no content: the `/git/`
* family of `REFUSED_PATH_FAMILIES` refuses every path but exactly one
* `refs/heads/` ref of `MAILBOX_BRANCH_SHAPE` (`claude/mailbox-*`), held there
* before the dispatch too. The fences, listed HERE only, are facts about the
* pull and the ref, judged by the executor on the pull's own `GET`, the open
* pulls on that head and the ref, the last three reads before the DELETE
* (`mailboxBranchPreflight`): the pull is closed, carries `pm:mailbox`, its
* head is `branch` on this repository, no OPEN pull has that head (the DELETE
* would close it), and the ref points at the pull's `head.sha` (a commit pushed
* after the close is not the mailbox's; a ref already absent fences nothing).
* Anything else is refused, the DELETE not sent. It lands only when the ref
* reads back absent (`confirmMailboxBranch`): a ref already gone (the DELETE's
* 422) is an idempotent landing, one still there FAILED.
*
* ## The rows whose LATER requests read the FIRST's answer — `pr_create` with `assignees` or `labels`
*
* A pull request's assignees and labels are written on its issue endpoints,
* `POST /repos/{o}/{r}/issues/{n}/assignees` and `POST /repos/{o}/{r}/issues/{n}/labels`,
* and `{n}` exists only once the create has answered. So a `pr_create`
* carrying `assignees` or `labels` is TWO or THREE requests in one action:
* the draft create, then the assignee POST, then the label POST — each later
* leg's path spelled with the placeholder `answerPlaceholder('number')` and
* carrying `fromAnswer: 'number'`. The executor fills the placeholder from
* the CREATE's answer, the action's first (a positive integer at that field;
* ⛔ never from the request, never from a later leg's answer) and refuses to
* send the leg at all when that answer carries none, a FAILED action that
* says the leg was NOT SENT. Each leg also carries what its answer must
* list: `assigned`, the logins — GitHub's documentation of the endpoint says
* an assignee the caller cannot apply is "silently ignored", with the 201
* still answered; `labelled`, the names — the labels endpoint answers the
* pull's whole label set, so a name sent and not listed is a write that did
* not land. Either way a 2xx whose answer lacks one sent is a FAILED action
* naming it, never a quiet partial. Both legs are `issues: write`
* (`alsoSpends`), a grant every stroke's token carries as a literal mint
* input, so the row stays `pull-requests` and the mint widens nothing. Why
* the assignee and the label ride the create's stroke rather than a second
* write: a seat's second write is a second permission verdict in its own
* session, measured to vary on an identical command, and both are part of
* opening the pull, not a later act — a dev's `skip-changeset` is a
* declaration about the diff the pull opens with. `validate.mjs --self-test`
* pins that these are the TWO descriptors carrying `fromAnswer` and that
* neither is the first request of its action; `execute.mjs --self-test` pins
* the fill, the refusal to send and the landing.
*
* ## The governed-review follow-up — `pr_ready` on a Tier H diff, ⛔ never the draft open
*
* A Tier H governed surface (`GOVERNED_SURFACES` rows with tier `H` in
* `check-governed-merges.mjs`: `docs/adr/**`, `skills/**`, `AGENTS.md`,
* `CLAUDE.md`, `docs/NORTH-STAR.md`, `.github/workflows/**`) lands only on an
* APPROVED review by an account in `GOVERNED_APPROVERS`
* (`check-governed-queue-guard.mjs`, the ONE list of those accounts). WHEN a
* human is asked to look is the owning seat's act, never the relay's: a pull
* reaches an approver only once the seat's `## 席位核对` ACCEPT and a
* `## Contract review` PASS on the pull's CURRENT head are both on its thread,
* and then as the seat's own hand-off stroke — `pr_request_reviewers` below,
* naming the approvers it owes, and `assign` for an approver who is the pull's
* author (pm-dispatch SKILL.md, ACCEPT 之后的路径分叉 ③). The maintainer,
* verbatim: 「应该是开发完了你审核通过才会推送给我审核」. So the draft open
* summons nobody: a `pr_create` is the create plus the legs the caller spelled,
* nothing reads the pull's files there, and a dev's `pr_create` carries the
* claim's `Account:` as its `assignees` (ruling A on #29828, os-dev.md rule 2;
* hand-over is the seat's) — the seat's own account is never requested on a
* pull as a reviewer. The one follow-up left is `pr_ready`. The platform
* summons a code owner only when a pull is opened READY or marked ready for
* review — measured on this repository's own Tier H pulls, the CODEOWNERS
* request arrived at `ready_for_review` and never at the draft create — and a
* Tier H pull is readied only after an approver has already approved it, so
* the follow-up there costs zero writes when the hand-off was made and names
* the one approver still uncovered when it was not. The row `pr_ready`
* therefore carries `governedReview: true`, and the executor, once the row's own
* requests have landed, reads the pull's file list in full
* (`GOVERNED_REVIEW_FILES_PAGE_SIZE` per page, at most
* `GOVERNED_REVIEW_FILES_PAGE_CAP` pages — the endpoint's own ceiling; a walk
* that would need more is a truncated SUBSET and a FAILED action, never a
* quiet "not governed"), asks the register (`governedPathsIn` +
* `landingTierOf`, scoped to `payload.repo` through `repoIdForSlug`) and, on a
* Tier H hit, sends what `governedReviewRequests` spells: ONE
* `POST /repos/{o}/{r}/pulls/{n}/requested_reviewers` naming every
* `GOVERNED_APPROVERS` account not already requested, assigned or holding a
* submitted review (the union the H43 patrol reads as covered — so a re-run,
* a `pr_ready` after the seat's hand-off, or the platform's own CODEOWNERS
* request landing first costs zero writes), and — because GitHub answers 422 to a
* request naming the pull's own author — ONE
* `POST /repos/{o}/{r}/issues/{n}/assignees` for the author when the author is
* itself a missing approver. Each answer is judged as the legs above are:
* `requested` against the pull's pending requests, `assigned` against its
* assignees; a 2xx lacking a login sent is a FAILED action naming it. A Tier
* S diff (`.claude/**` alone — it lands on a seat's review of record) and an
* ungoverned diff send nothing, and the row says which. The reads are unpaced
* GETs; the writes are paced like every other write verb and are outside the
* rule ⑤ count (`strokePacing` counts a stroke's spelled requests; these two
* are conditional and at most two per pull). The row spends `issues: write`
* for the assignee fallback (`alsoSpends`), a literal grant on every stroke.
* `execute.mjs --self-test` pins the plan, the writes and both refusals, and
* that `pr_create` sends none of it; `validate.mjs --self-test` pins the one
* row and the two endpoints against the refused families. ⛔ This is an
* ACTION, not a judge: no gate, check-run or patrol row is added by it — the
* H43 row in `check-half-states.mjs` reads the gap left once the hand-off is
* due (ACCEPT and a same-head PASS on the thread, and nobody asked).
*
* ## The permissions the relay's token is narrowed to
*
* Read from GitHub's own permission ledger for server-to-server tokens
* (`github/docs`, `src/github-apps/data/fpt-2022-11-28/server-to-server-permissions.json`):
* every `/issues/**` write here is `issues: write` — `pr_create`'s assignees
* and labels legs and the governed-review follow-up's assignee fallback on
* `pr_ready` spend it as `alsoSpends`; `/pulls/**` and the
* ready / draft GraphQL mutations are `pull-requests: write`; the two
* auto-merge mutations (`enablePullRequestAutoMerge` /
* `disablePullRequestAutoMerge`) additionally require `contents: write` —
* measured on the first live use, where a token without it answered
* "Resource not accessible by integration" — and beside those two rows only
* `mailbox_branch_delete`'s one ref DELETE (above) spends it: no row writes a
* file or creates or moves a ref (`pr_update_branch` is the platform's own
* merge, `pull_requests: write` in that ledger); arming auto-merge on a pull that changes
* `.github/workflows/**` also requires `workflows: write` — measured: the
* relay's `automerge_enable` on such a pull answered "refusing to allow a
* GitHub App to create or update workflow … without `workflows` permission" —
* so that row spends it (`alsoSpends`), the one row that does; it is a
* literal grant on every stroke, and a seat may enqueue a pull that changes a
* workflow file. The human floor of pm-dispatch `SKILL.md` (security and
* permission boundaries stay a human's) is lowered for this ONE boundary by
* the maintainer's own ruling, comment 6104822731 (「22708 A」), so this grant
* is not a drift. The grant also reaches workflow-file writes through
* `/contents/**` and `/git/**`; `REFUSED_PATH_FAMILIES` refuses both for every
* row, the one mailbox ref DELETE aside (above). The workflow-run dispatch (`workflow_dispatch`) and the failed-jobs
* re-run (`run_rerun_failed`), both below, are `actions: write`, the two rows
* spending it; the five advisory rows that write (`advisory_report`,
* `advisory_create`, `advisory_collaborators_add`, `advisory_versions` and
* `advisory_state`, below) are `repository-advisories: write`, and the two
* that read (`advisory_read` and `advisory_list`, below) spend the same grant
* at `read` alone (each row's `grant`), the seven rows spending it; the sender gate's
* `GET /repos/{o}/{r}/collaborators/{login}/permission` is `metadata: read`.
* `PERMISSIONS` is that set and nothing wider. The workflow declares the five
* grants every stroke gets as literal `permission-*` inputs on
* `actions/create-github-app-token`, and the two grants a stroke gets only
* when it spends one (`STROKE_SCOPED_PERMISSIONS`) as inputs read from the
* validator's output; `validate.mjs --self-test` pins both spellings equal to
* this table.
*
* ## The one row whose token carries `actions: write` — `workflow_dispatch`
*
* `POST /repos/{repo}/actions/workflows/{file}/dispatches` starts a run of a
* workflow file at a ref and needs `actions: write` on the token — a grant that
* also reaches cancelling, re-running and deleting runs, and the cache,
* artifact, secret and variable endpoints. So the row is fenced five ways:
* `workflow` is a closed enum — `WORKFLOW_DISPATCH_ALLOWLIST`, one file name
* per entry, matched whole, joined only by a PR that adds the entry here and
* never at request time; its `inputs` are closed per file (below); `ref` is a
* closed enum of exactly `WORKFLOW_DISPATCH_REF`; a stroke carrying this op
* carries exactly that one action (`alone`), so the wider token serves one
* request and nothing beside it; and the grant is minted only for such a
* stroke — the validator writes `permission_actions=write` for it and an empty
* value for every other stroke, and the mint action skips an empty
* `permission-*` input, so every other stroke's token is what it was before
* this row. `REFUSED_PATH_FAMILIES` refuses every other `actions/*` path, and
* `validate.mjs --self-test` pins that the dispatch call and
* `run_rerun_failed`'s re-run call (below) are the only two the table reaches.
* The dispatch answers 204 with no body, so the run it starts
* is read back by the SEAT (`dispatch.mjs`): the newest `workflow_dispatch`
* run of that file created since the dispatch.
*
* ## The second row whose token carries `actions: write` — `run_rerun_failed`
*
* `POST /repos/{repo}/actions/runs/{run_id}/rerun-failed-jobs` starts a new
* ATTEMPT of a completed run in which the jobs that failed, and the jobs that
* need them, run again, and the jobs that passed are carried over as they
* were. Measured on run 39713789453's attempt 2: the passed jobs were listed
* in it at once as `completed`, keeping attempt 1's start times; the failed
* shard was listed at once and started two seconds later; and the aggregate
* job that needs every shard was listed only when its need finished, 16
* minutes later. It spends the `actions: write` `workflow_dispatch` spends, so
* it is fenced the same way. These are the seven fences:
*
* - the WORKFLOW: the run's `path` is one of `RERUN_FAILED_WORKFLOWS`, a
* reviewed allowlist matched whole and joined only by a PR that adds the
* path here, each entry after `ci.yml` a READ-ONLY check workflow (the
* definition sits on the list) — never a request-time input, since the
* payload carries no key that names a workflow;
* - the EVENT: the run's `event` is `pull_request` — a push, merge-group,
* schedule, release or `workflow_dispatch` run is refused;
* - ONCE: the run's `run_attempt` is 1. A second failure is real, and a
* re-send after a landing meets attempt 2 here and is refused;
* - FAILED: the run is `completed` with `conclusion` `failure`;
* - the HEAD: the run's `head_sha` is its pull request's CURRENT head. The
* pull is the run's `pull_requests[0].number`, and its head is read with
* the pull's own `GET /repos/{repo}/pulls/{n}`, never from the copy the
* run embeds. Each listed workflow's concurrency group is keyed by the
* pull number and cancels in progress on `pull_request`, so a stale
* head's re-run would cancel the current head's run. A run with no
* `pull_requests` entry (a fork pull request's run, or the field empty)
* is refused by name;
* - ALONE: a stroke carrying it carries exactly that one action (`alone`),
* so the wider token serves one request;
* - the GRANT: `actions: write` is minted for that stroke alone, through the
* `STROKE_SCOPED_PERMISSIONS` output `workflow_dispatch` already uses — the
* validator writes `permission_actions=write` for either op's stroke and an
* empty value for every other, so the workflow names neither op.
*
* The payload is `run_id` and nothing else: no workflow, attempt, job or
* debug-logging key exists for it, and the POST carries no body. The first
* five fences are facts about the RUN and its pull, not the request, so the
* EXECUTOR judges them (`RERUN_FAILED_FENCES`) on
* `GET /repos/{repo}/actions/runs/{run_id}` and then the pull's
* `GET /repos/{repo}/pulls/{n}`, the last two reads before the POST. A run
* that changed between the seat's request and the relay's run, for example
* re-run by a person meanwhile, or a pull that a push moved on, is refused
* THERE with zero writes. The seat's wrapper (`scripts/pm/rerun-failed.mjs`)
* reads the same five before it dispatches. That is an early refusal naming
* the fence that fails, and it never replaces the executor's.
*
* The 201 the POST answers is an acceptance, not a landing. The executor reads
* the run again until it shows `run_attempt` 2, then that attempt's job list,
* and the action LANDS only on what `rerunFailedReadBack` judges there. Every
* job that concluded `failure` in attempt 1 and is listed in attempt 2 must be
* `queued` or `in_progress`, and at least one must be. A failed job not yet
* listed is NAMED, not failed: a job is created when its needs finish
* (measured above). A read-back that never sees attempt 2 inside its window is
* a FAILED action, never a success. `REFUSED_PATH_FAMILIES` carves out exactly
* `runs/{digits}/rerun-failed-jobs`; the whole-run `rerun`, a job's `rerun`,
* cancel, delete, logs, caches, artifacts, secrets and variables all stay
* refused, and `validate.mjs --self-test` pins each.
*
* ## A workflow's inputs are CLOSED per file — `WORKFLOW_DISPATCH_INPUTS`
*
* An input picks which of a workflow's lanes the run takes, so the inputs are
* part of the allowlist, never a value a seat chooses: each allowlisted file
* carries its ONE inputs object beside its name, and a file joins the list by
* the PR that spells both here. `null` is a workflow that declares no inputs —
* the platform refuses inputs on such a workflow, so an action naming it
* carries no `inputs` key. An object is the exact `inputs` an action naming
* that file must carry: every key, every value, nothing beside it — a missing
* key, another value or any other key is refused by name with zero writes.
* The seat SPELLS the inputs rather than having them filled in, so a payload
* says which lane it starts and a stroke that does not say so is refused; the
* request body is built from this table, never from the action, so what
* leaves is this spelling even where the two would differ.
*
* `release.yml` is on the list for its bookkeeping lane alone (the maintainer's
* ruling, comment 6139629628, item 5: a seat refreshes the Version Packages PR
* through the relay after each fix lands on `main`). Its entry is
* `{ refresh_version_pr: true }`: the `version-pr` job runs on a dispatch
* carrying it, and `release-integrity`, `stale-prompts`, `full-battery` and
* `publish` refuse such a dispatch in their own `if:` (`docker` runs only on a
* publish `release-integrity` or `publish` reports). `force` is not in the
* entry and `refresh_version_pr: false` is not its value, so the
* publish-repair lane — a dispatch WITHOUT `refresh_version_pr` — is
* unreachable from the relay. `validate.mjs --self-test` reads the workflow
* from disk: it pins every input here declared there, and evaluates every
* job's `if:` for the relay's dispatch, so a guard edited there, or a job
* added there, that the dispatch would start reds that self-test.
*
* On the wire every value is a STRING (`dispatchInputsOnTheWire`): `"true"`
* is the spelling measured to start the bookkeeping lane alone (runs
* 38351525685 and 38357219168, each answering `Version PR maintenance` success
* and the other five jobs skipped). A JSON boolean on that endpoint is not
* measured, so it is never sent.
*
* ## The one row whose token reaches a SECOND repository — `transfer`
*
* GitHub's `transferIssue` mutation (GraphQL only; REST has no transfer
* endpoint) needs `issues: write` on the repository the card is in AND on the
* one it moves to, so a transfer stroke's token is minted for both. That is
* the only widening of the token's repository reach the relay makes (the one
* per-stroke widening of its permissions is the `actions` grant of
* `workflow_dispatch` and `run_rerun_failed`, above), and it is fenced four ways: the target is
* a closed enum — `TRANSFER_TARGETS`, the fleet's governed-repository roster
* reused from `check-governed-merges.mjs`, never a second roster and never
* free text; the target is never the source; a stroke carrying a transfer
* carries transfers alone, to ONE target; and the executor gates the sender on
* BOTH repositories before the first write. Every other op keeps the
* single-repository token — `validate.mjs` computes the list the workflow
* mints for (`tokenRepositoriesOf`) and its `--self-test` pins both halves.
* The mutation never sets `createLabelsIfMissing` (GitHub's default is false):
* a label with no same-named label on the target is dropped, never created
* there. Comments and assignees travel with the card and the old URL
* redirects — GitHub's documented transfer semantics.
*
* ## The two rows that write an issue's hierarchy — `sub_issue_add` and `sub_issue_remove`
*
* An epic's queue is its parent's open sub-issues, and the half-state patrol
* reads a parent's `sub_issues_summary`; the link both reads see is written by
* `POST /repos/{o}/{r}/issues/{parent}/sub_issues` and taken back by
* `DELETE /repos/{o}/{r}/issues/{parent}/sub_issue`, each with the body
* `{ sub_issue_id }` — the child's REST `id`, never its number (GitHub's REST
* OpenAPI description, operations `issues/add-sub-issue` and
* `issues/remove-sub-issue`, read 2026-10-29). GitHub's permission ledger (the
* file cited below) lists both under `issues: write`, server-to-server, with
* no additional permission, so both rows spend `issues`, a literal grant on
* every stroke: the mint widens nothing, and neither row travels `alone`.
*
* The payload carries two issue NUMBERS — `issue` the parent, `sub_issue` the
* child — and never an id: the executor resolves the child's `id` from the
* child's own `GET /repos/{o}/{r}/issues/{child}`, the read its fences need
* anyway, so the action speaks the vocabulary every other row speaks and a
* seat never hand-copies an opaque id. An action naming one issue as both is
* refused by the validator (`distinct`). `replace_parent`, the add endpoint's
* flag that moves a child off its current parent, is never sent: a move is a
* remove from the old parent and an add to the new one, two actions a seat
* names.
*
* The fences (`SUB_ISSUE_FENCES`) are facts about the two cards, so the
* EXECUTOR judges them on its own reads immediately before the write
* (`subIssuePreflight`, `execute.mjs`) — a card moved, or a link another actor
* wrote, between the seat's request and the run is refused there with zero
* writes:
*
* - PARENT and CHILD: each number answers `GET /repos/{o}/{r}/issues/{n}`
* as an issue — never a pull request — on the stroke's own repository (a
* transferred card answers from its new home and is refused by name), the
* child with an integer `id`;
* - FREE (`sub_issue_add`): the child's own
* `GET /repos/{o}/{r}/issues/{child}/parent` answers 404 (no parent —
* measured 2026-10-29: "No parent issue found"; the issue's own answer
* omits `parent_issue_url` then, so absence is read on this endpoint,
* never inferred from a missing field) or this parent. A child under
* ANOTHER parent is refused naming it; one under THIS parent is a measured
* no-op — nothing sent, landed only when the parent's list reads it back;
* - LISTED (`sub_issue_remove`): the parent's own sub-issue list
* (`GET /repos/{o}/{r}/issues/{parent}/sub_issues`, every page) lists the
* child's `id`. A child it does not list is refused, never sent as a
* DELETE the platform might answer either way.
*
* The write's answer is an acceptance, not a landing: the action LANDS only
* on `subIssueReadBack` — the parent's list, read whole after the write,
* lists the child's `id` (add) or no longer does (remove), re-read inside a
* bounded window. A list that never settles is a FAILED action saying
* UNCONFIRMED: read the parent, ⛔ never re-send. Neither row carries prose or
* creates or moves a card, so neither is content-creating for rule ⑤ nor
* annotated, and neither carries a `body` the seat reads back — the
* executor's read-back IS the confirmation, as for `pr_update_branch`.
* `validate.mjs --self-test` pins both rows, the fences and the read-back's
* judgment; `execute.mjs --self-test` pins the reads, the one write, every
* refusal and the landing.
*
* ## The rows that write a security advisory — no advisory text on a public surface
*
* Private vulnerability reporting is on for this repository, and GitHub lets
* only an administrator, a security manager or an advisory's own
* collaborators see an unpublished advisory. A seat account must not write to
* GitHub itself (the suspension `fleet-token.mjs` records), so a seat files a
* finding and moves its state through the relay, and reads the advisory under
* its own account once it is a collaborator — a read a cloud seat turned out
* unable to make, so it reads through the relay too, sealed (`advisory_read`,
* the next section). The maintainer's scope, verbatim
* as the body of issue 29160 (the card that filed these rows) records it:
* 「按这个范围更新 #29160:上报正文经中继并读事件文件,加人、接受、关闭只改状态,读取用席位自己的账号,发布留给我。先测令牌。」
* Its clause 「发布留给我」 is SUPERSEDED. Told that the relay did not let an
* advisory be set to published, so the seat had handed over a list to publish
* by hand, the maintainer ruled, verbatim as the body of issue 30110 records it:
* 「中继不允许把公告设为已发布 ,立卡解决」. WHAT is published is unchanged and
* stays the maintainer's, by the standing rule 「哪些高危要发布应该在我版本发布前决策吧」:
* the maintainer decides the list before each release, and the relay only
* carries out a list the maintainer approved — the seat's half of that lives
* in pm-dispatch's `references/security-findings.md`, never here.
*
* row request the payload carries
* `advisory_report` `POST …/security-advisories/reports` `summary`, `description`; optional `severity`, `cwe_ids`
* `advisory_create` `POST …/security-advisories` the report's keys, and `packages`
* `advisory_collaborators_add` `GET`, then `PATCH …/security-advisories/{id}` `ghsa_id` and logins
* `advisory_versions` `GET`, then `PATCH …/security-advisories/{id}` `ghsa_id` and `versions`: package, range, patched versions
* `advisory_state` `GET`, then `PATCH …/security-advisories/{id}` `ghsa_id` and `draft`, `closed` or `published`
*
* `advisory_create` is the maintainer's naming of a second way in, verbatim
* as the body of issue 29410 records it: 「立一张 skills 卡,我现在就派发,然后你再试」.
* GitHub caps the NEW private reports an account files per day, and every
* relay report is filed as the one App, so the whole fleet's reports share
* one quota. Creating an advisory is the repository's own act, not a report:
* the endpoint takes the same `repository-advisories: write` grant and
* creates the advisory in `draft` directly — the state a report reaches only
* once accepted. That the App's token may create one, and that the cap on
* reports does not reach it, are documentation readings the first live run
* confirms (below).
*
* Publishing a fixed advisory is three strokes, each alone. A fixed advisory
* here is `closed` once its fix merges, so `advisory_state` first moves it back
* to `draft` (the reopen); `advisory_versions` then sets each affected
* package's vulnerable range and patched versions; and `advisory_state` last
* moves it to `published`. The versions row carries NO prose: its one key
* beside the id is `versions`, a capped list of closed entries, each exactly
* `package` (`NPM_PACKAGE_SHAPE`), `vulnerable_version_range`
* (`ADVISORY_VERSION_RANGE_SHAPE`: one comparator, or a lower bound then an
* upper bound, each an operator, one space and a release version) and
* `patched_versions` (`ADVISORY_PATCHED_VERSIONS_SHAPE`: one to
* `MAX_ADVISORY_PATCHED_VERSIONS` release versions, a comma and a space
* between). `advisoryVersionEntryFailure` judges each, and also refuses a pair
* whose bounds do not rise and a patched version inside its own range. Its
* PATCH body is `{ vulnerabilities }` alone: per entry the npm ecosystem, the
* name and the two version strings, never a vulnerable function.
*
* `published` is reached by ONE row and ONE transition: `advisory_state`, from
* `draft` alone, and only once the executor's own GET reads at least one
* `vulnerabilities` entry, every one in the versions row's spelling (the
* `versions` fence, `ADVISORY_FENCES`) — the versions are set first. No other
* field takes it as a value, and no body but the executor's `{ state }` can
* carry it: the report's and the draft's bodies are the row's, holding no state
* (the endpoint creates a draft and takes none), the versions row's is its
* entries alone, and the other two PATCH bodies are the executor's
* (`validate.mjs --self-test` pins every one). Editing an advisory's summary or
* description, removing a collaborator, the CVE request and the temporary fork
* are out of reach of every row; reading an advisory's text is one row's alone,
* which seals it (`advisory_read`, the next section); and listing advisories is
* one row's alone too, narrowed to three states and five fields per advisory
* and sealed the same way (`advisory_list`, the section after it):
* `REFUSED_PATH_FAMILIES` refuses each `security-advisories` path but one
* advisory's (`ADVISORY_PATH_SHAPE`), the reports endpoint
* (`ADVISORY_REPORTS_PATH_SHAPE`), the bare collection
* (`ADVISORY_CREATE_PATH_SHAPE`) and the listing's own page of it
* (`ADVISORY_LIST_PAGE_PATH_SHAPE`), and the self-test pins that the
* collection is reached by `advisory_create`'s `POST` and `advisory_list`'s
* `GET` alone.
* A draft names its affected packages and nothing else of them: each is one
* `vulnerabilities` entry, the npm ecosystem and the name
* (`ADVISORY_CREATE_ECOSYSTEM`, `NPM_PACKAGE_SHAPE`), with no version range,
* vulnerable function, credit, CVSS vector, CVE id or private fork.
*
* What may NOT cross. The relay's run log and step summary are public, so:
*
* - the payload never rides a step's `env:` — GitHub prints a step's
* environment into the log — and `validate.mjs` and `execute.mjs` read
* `client_payload` from the event file (`$GITHUB_EVENT_PATH`) for EVERY
* op, so a report's or a draft's `summary` and `description` travel in the
* payload and are printed nowhere;
* - a refusal names the key and the byte count and ⛔ never echoes a value:
* `summary` and `description` are `str` fields, which never echo, and the
* other advisory fields are `quiet` (`FIELDS`), so a value that fails is
* described by its type and size alone — a value in the wrong key may be
* prose;
* - the executor prints no field of an advisory's answer but its id, its
* `state` and the logins `collaborating_users` names, each only in its own
* shape (`advisoryPrintable`), and the platform's `message` only when it
* is one the relay knows (`ADVISORY_PLATFORM_MESSAGES`) — never a
* summary, a description, a vulnerability, a credit, a CVE or CWE, a URL
* or the answer's body. Of the versions it prints COUNTS alone — entries
* and packages, never a name or a version, which are the unpublished
* advisory's until the publish. `advisoryReportLandedText`,
* `advisoryCreateLandedText`, `advisoryLandedText`,
* `advisoryVersionsLandedText`, `advisoryStateLandedText` and
* `advisoryFenceText` are the only spellings of an advisory row. An id
* exposes no content, but it is public in the log. A draft's package names
* and the versions row's entries are `quiet` too: a refusal never echoes one.
*
* The executor's five paths (`execute.mjs`, in the shape of the hierarchy rows'):
*
* - `advisory_report` is one POST of the row's body. It LANDS on a 2xx
* whose answer carries a `ghsa_id` (`advisoryReportReadBack`); the row and
* a notice annotation name that id, so the seat follows with
* `advisory_collaborators_add` — the App is the submitter, so the finding
* seat is not a collaborator on its own;
* - `advisory_create` is one POST of the row's body to the collection, and
* nothing is read first. It LANDS on a 2xx whose answer carries a
* `ghsa_id` and reads state `draft` (`advisoryCreateReadBack`); a 2xx
* without an id is UNCONFIRMED and one in another state FAILED, neither
* ever re-sent. The row and a notice annotation name the id, so the seat
* follows with `advisory_collaborators_add` exactly as after a report;
* - `advisory_collaborators_add` reads the advisory first (`ADVISORY_FENCES`,
* judged by `advisoryPreflight` on the executor's own `GET`) and refuses
* with nothing sent unless the read answers 200 with the advisory the
* action names in `triage` or `draft` (`ADVISORY_OPEN_STATES`). The logins
* are compared case-insensitively (`advisoryCollaboratorPlan`): nothing
* missing is a no-op with nothing sent; otherwise the PATCH sends the
* EXISTING logins plus the missing ones, so the merge holds whether the
* platform replaces the list or merges it. It LANDS only when the answer
* lists every login sent (`advisoryReadBack`);
* - `advisory_versions` reads the advisory the same way and refuses with
* nothing sent unless it reads `draft` (`ADVISORY_VERSIONS_STATES`) and the
* `versions` fence holds. The PATCH REPLACES the whole list — GitHub's own
* example of the call: "To add vulnerable versions, include existing
* versions in the array" — so every package the advisory already lists
* must be one the action names, and no listed entry may be another
* ecosystem's, nameless, or carry `vulnerable_functions`, which this row
* does not write and the PATCH would drop. It LANDS only when the answer,
* still `draft`, lists exactly the entries sent (`advisoryVersionsReadBack`);
* - `advisory_state` reads the advisory the same way and refuses an illegal
* transition with nothing sent (`ADVISORY_TRANSITIONS`: `draft` from
* `triage` — the accept — or from `closed` — the reopen; `closed` from
* `triage` or `draft`; `published` from `draft` alone, through the
* `versions` fence; nothing from `published` or `withdrawn`, and a state
* the table does not name fails closed). Its PATCH body is `{ state }` and
* nothing else, and it LANDS only when the answer shows that state
* (`advisoryStateReadBack`) — a publish only when the published answer
* also lists exactly the entries the preflight read: the advisory read back
* as `published`, with the versions it was sent. A landed publish alone
* earns a notice annotation naming the id (`relayAdvisoryAnnotationMessage`,
* `dispatch.mjs`): it is public once published, which is the point.
*
* Each row travels `alone` and spends `repository-advisories: write`, a grant
* minted only for its stroke (`STROKE_SCOPED_PERMISSIONS`), so every other
* stroke's token stays as it was. Measured on 2026-11-02 with the relay's own
* mint action against a control token minted without the grant (run
* 41415522766, recorded in the card's body): the narrowed mint succeeds, and
* the grant is what opens an advisory's read and its PATCH (200 with it, 403
* without). The action warns `Unexpected input(s)
* 'permission-repository-advisories'` on such a run, because its `action.yml`
* does not declare the input, and it still passes it to the mint
* (`lib/get-permissions-from-inputs.js`): the warning is expected, and not one
* to "fix" by removing the input. The first live run after merge decides the
* rest: a valid report filed by the App and whom it records as the reporter,
* a real account added and whether the PATCH replaces the list, the two
* transitions by the App, and whether a report needs the grant at all (both
* tokens reached the reports endpoint's 422); for `advisory_create`, whether
* the App's token creates a draft at all, whether one `vulnerabilities` entry
* of an ecosystem and a name is the least the endpoint accepts, and whether
* three drafts land in one hour where reports stop at one a day. A refusal
* on any of them is a FAILED action carrying `ADVISORY_ACCESS_REMEDY`, and ⛔
* never a retry under an un-narrowed token: the reading goes to the maintainer.
*
* What a publish needs on the platform, read 2026-11-04 from GitHub's REST
* description (`github/rest-api-description`, operation
* `security-advisories/update-repository-advisory`) and the permission ledger
* cited above: the one PATCH takes `state` (`published`, `closed` or `draft`)
* and `vulnerabilities` (per entry `package`, `vulnerable_version_range`,
* `patched_versions`, `vulnerable_functions`), under `repository_advisories:
* write` alone, server-to-server, with no additional permission; the
* description's own refused move is `published` → `draft` (422, "Invalid state
* transition"). The App's PATCH of `state` is measured: `triage` → `draft` and
* `draft` → `closed` landed on the live runs after these rows merged (runs
* 41443030055 and 41443112178). NOT measured, so the first live publish after
* merge confirms each: that the platform takes `closed` → `draft` (the
* description names that move neither way), that it takes `draft` →
* `published` and the versions from the App, that it answers the versions in
* the spelling sent, and whether it needs them before it publishes — the relay
* needs them either way. A refusal is a FAILED action carrying
* `ADVISORY_ACCESS_REMEDY`; a token that cannot reopen or publish is a fork for
* the maintainer, ⛔ never a widened grant.
*
* The sender gate does NOT change for these rows: write, maintain or admin on
* the target passes, by the maintainer's ruling, verbatim as the body of issue
* 29160 records it: 「所有车队账户都能发这个操作」. It is recorded here because
* of what it admits: any fleet account with write on the target can add
* itself to an advisory whose id it holds.
*
* ## The one row that READS an advisory — `advisory_read`, sealed to a key the seat alone holds
*
* The scope above has a seat read an advisory under its own account. The live
* run after 29160 merged showed a cloud seat cannot: its `gh` speaks with a
* token holding no repository-advisories permission (403, "Resource not
* accessible by integration"), and its egress proxy replaces every
* `Authorization` header. The App can read one, but only inside the relay's
* run, whose log, annotations and step summary anyone may read. So the read
* leaves the run as ciphertext alone, by the maintainer's naming, verbatim as
* the body of issue 29420 records it: 「按一次性密钥立卡」.
*
* row request the payload carries
* `advisory_read` `GET …/security-advisories/{id}`, and nothing else `ghsa_id` and `public_key`
*
* The seat (`dispatch.mjs`) generates an X25519 key pair in its own process
* for each read, puts the public half in the action, and keeps the private
* half in memory — never exported, never written, gone when the process
* exits. No key is stored anywhere: not in the repository, not as a secret.
* `public_key` is its own closed kind (`FIELDS`, kind `x25519`): base64 SPKI
* DER of exactly `ADVISORY_READ_PUBLIC_KEY_CHARS` characters in its one
* spelling, a key a shared secret can be derived with — judged by
* `advisoryReadKeyFailure` before any request, a refusal naming the key and
* the byte count alone.
*
* The executor reads the advisory, judges `ADVISORY_READ_FENCES` on that
* answer, and seals `ADVISORY_READ_FIELDS` of it as the platform answered
* them (`advisoryReadPlaintext`) with `sealAdvisoryRead`: a fresh X25519 key
* of its own, HKDF-SHA256 over the shared secret, AES-256-GCM under a random
* nonce, with the request id, the action's index and the id as associated
* data, so a sealed answer opens for the read that asked for it and no other.
* Node's own `crypto`, and nothing else. The sealed answer leaves the run on
* ONE channel, the one a seat container can read: notice annotations on the
* job's check run, at most `ADVISORY_READ_MAX_PARTS` of
* `ADVISORY_READ_PART_CHARS` characters (`advisoryReadParts`), inside the
* runner's measured caps — ten notices a step and a message cut at 4,096
* characters (`actions/runner`, `ExecutionContext.cs`). An answer too large
* for them is a FAILED action naming byte counts alone. The seat reassembles
* the parts, opens them with its private key (`openAdvisoryRead`), and prints
* the text to its own stdout, and only on `--reveal`.
*
* ⛔ What crosses the public run: the HTTP status, the byte and part counts,
* and the ciphertext. NOT the id — the row's call is `ADVISORY_READ_CALL`, a
* placeholder where every other row prints its path — nor the state, the
* platform's `message` unless `ADVISORY_PLATFORM_MESSAGES` names it, or any
* field of the answer. A seal that fails is a FAILED action that prints
* nothing of the answer and emits no part. The action LANDS only on a 200
* whose answer passes every fence and whose seal succeeded and fit. It writes
* nothing, so `dispatch.mjs` has no byte read-back for it: opening the parts
* IS its read-back.
*
* The grant: the row's `grant` is `read`, so its stroke's token carries
* `repository-advisories: read` and never write. GitHub documents this GET
* under a read grant; what was measured is the write grant's read (run
* 41415522766, above), so the first live read is the measurement of record.
* A refusal there is a FAILED action carrying `ADVISORY_READ_ACCESS_REMEDY`:
* raising the row to write is the maintainer's ruling, ⛔ never a retry under
* a wider token.
*
* The sender gate is `target-write`, by the maintainer's ruling, verbatim as
* the body of issue 29644 records it: 「同意改成对仓库有写权限,立卡派发修复」.
* Every stroke passes the target-write gate before its first request
* (`execute.mjs`, the sender gate), and the executor then holds a read to the
* row's `senderGate`, a key of `ADVISORY_READ_SENDER_GATES`; `target-write`
* asks nothing more: write, maintain or admin on the target, the gate the
* five rows above keep. The ruling settles the question this row landed
* with, whether a read should instead need the sender on the advisory's own
* `collaborating_users`. That gate excluded no one, since a sender with write
* on the target can add itself to any advisory whose id it holds (above), and
* the first live reads were each refused at it (runs 41545143476,
* 41545259848 and 41546082963) for a sender the advisory's write-grant GET
* already listed (run 41546190167). Why the fence refused them is
* unmeasured; one hypothesis is that the read-grant answer omits
* `collaborating_users`. The table holds that one value, and any other, the
* retired `collaborator` among them, fails closed with nothing sealed.
*
* ## The one row that LISTS advisories — `advisory_list`, sealed the same way
*
* Without it a seat learns an advisory's id only from the maintainer, a
* finder's doorbell or a relay run, and a draft no one rang for never reaches
* the seat's ledger. The maintainer's words, verbatim as the body of issue
* 31368 records them: 「你应该能自主读到所有的安全问题才是合理的」.
*
* row request the payload carries
* `advisory_list` `GET …/security-advisories?state=S&per_page=100[&after=C]`, and nothing else `public_key` alone
*
* The caller names NO state and NO query parameter: the row lists every state
* in `ADVISORY_LIST_STATES` (`triage`, `draft` and `closed`, every unpublished
* state the endpoint filters by) on every run, one walk each, and the executor
* spells every page's path (`advisoryListPagePath`, in
* `ADVISORY_LIST_PAGE_PATH_SHAPE`). The endpoint pages by CURSOR, not by page
* number: GitHub's REST description gives it `before`, `after`, `per_page` (at
* most 100), `state`, `sort` and `direction`, and no `page` (read 2026-11-08,
* operation `security-advisories/list-repository-advisories`). A walk asks
* `ADVISORY_LIST_PAGE_SIZE` a page and ends on a short page, or on a full page
* whose `Link` header names no `rel="next"` (matched without regard to case, as
* RFC 8288 has it); a short page whose `Link` still names a next page is FAILED,
* since the walk would end on a page the platform says is not the last. On a full page that names one it
* takes that link's `after` cursor and nothing else, and only when the link's
* origin and path are the relay's own API and this collection, its `state` the
* walk's own, and the cursor one value in `ADVISORY_LIST_CURSOR_SHAPE`
* (`advisoryListNextCursor`); the next path is the relay's own spelling with
* that cursor, never the link. A link that is none of these, a page that is not
* a list of advisories in the state asked for, an advisory whose `severity` is
* not one of `ADVISORY_LIST_SEVERITIES` or null or whose `created_at` or
* `updated_at` is not an ISO-8601 string (`ADVISORY_LIST_TIMESTAMP_SHAPE`), so
* nothing but those values is ever sealed, and an advisory listed twice are
* each a FAILED action. A walk still pending after `ADVISORY_LIST_PAGE_CAP`
* pages is FAILED too: a truncated listing is a SUBSET, never an answer. In
* each, nothing is sealed or emitted.
*
* Projected BEFORE the seal: each advisory crosses as `ADVISORY_LIST_FIELDS`
* (`ghsa_id`, `state`, `severity`, `created_at`, `updated_at`) as the platform
* answered them, and nothing else — no summary, description, vulnerability or
* credit, not even as ciphertext (`advisoryListPlaintext`: `{ count,
* advisories }`, in state order, then the platform's). The JSON is then padded
* with trailing spaces to exactly `ADVISORY_LIST_PADDED_BYTES`
* (`advisoryListPadded`), so every sealed listing is exactly
* `ADVISORY_READ_MAX_SEALED_CHARS` characters in `ADVISORY_READ_MAX_PARTS`
* parts, and the public ciphertext's length and part count say nothing of the
* count. The cap that binds first is that one: 29,939 bytes of JSON, measured
* with fake items at 206 advisories of `critical` severity (144 bytes each) up
* to 215 with no severity (138 bytes each; the self-test pins the edge), far under `ADVISORY_LIST_PAGE_CAP` pages of 100 for each of three
* states. A listing over it is FAILED with nothing emitted, ⛔ never a cut list.
*
* Sealed and emitted exactly as `advisory_read`'s answer: `sealAdvisoryRead` to
* the action's one-time `public_key`, notice parts the seat reassembles, opens
* (`openAdvisoryRead`) and prints on `--reveal` alone, its padding trimmed for
* that display only. The associated data is `advisorySealAad`'s, binding the
* request id, the action's index and the op; `advisory_read`'s is unchanged
* under that helper, byte for byte. It writes nothing, so `dispatch.mjs` has
* no byte read-back for it: opening the parts IS its read-back.
*
* ⛔ What crosses the public run: that the listing landed or failed, the HTTP
* status, `advisoryListCall` (the call, its states in braces) and the padded
* ciphertext. NEVER an id, a count, a state, a severity, a cursor, a page
* number, or a byte or part count of the listing.
*
* The grant and the gate are `advisory_read`'s. Its `grant` is `read` on the
* stroke-scoped `repository-advisories`, so the validator writes
* `permission_repository_advisories=read` for its stroke through the
* workflow's existing input; it travels `alone`; and its `senderGate` is
* `target-write` from `ADVISORY_READ_SENDER_GATES`: write, maintain or admin on
* the target, which every stroke passes before its first request. A row naming
* any other gate is refused before the first GET. The first live run measures
* what the read grant lists and the form of the `Link` cursor. A refusal there
* is a FAILED action carrying `ADVISORY_LIST_ACCESS_REMEDY`, ⛔ never a retry
* under a wider token.
*
* ## The platform's `client_payload` ceilings — pinned, with their source
*
* "The maximum number of top-level properties is 10. The total size of the
* JSON payload must be less than 64KB." — the `client_payload` parameter of
* `POST /repos/{owner}/{repo}/dispatches` in GitHub's REST OpenAPI description
* (`github/rest-api-description`, `descriptions/api.github.com/api.github.com.json`,
* read 2026-09-22; the rendered page is
* https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event).
* `event_type` is capped at 100 characters there too. The validator refuses at
* these ceilings BEFORE the dispatch leaves, so a payload the platform would
* reject with a 422 is refused locally with the reason.
*/
import { createCipheriv, createDecipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes } from 'node:crypto';
import { GOVERNED_REPOS } from '../check-governed-merges.mjs';
/**
* The relay's four files, repo-relative — the population a card touching any
* of them implicates (the dispatch derivation reads these literals as path
* leads, so a bare `fleet-write/…` spelling would name nothing from the repo
* root). `validate.mjs --self-test` checks each one is on disk.
*/
export const RELAY_FILES = Object.freeze([
'scripts/pm/fleet-write/ops.mjs',
'scripts/pm/fleet-write/validate.mjs',
'scripts/pm/fleet-write/execute.mjs',
'scripts/pm/fleet-write/dispatch.mjs',
]);
/** The board repository every relay lands on; `payload.repo` names the TARGET. */
export const RELAY_REPO = 'objectstack-ai/objectstack';
/** The `event_type` the relay workflow listens for — and nothing else. */
export const RELAY_EVENT_TYPE = 'fleet-write';
/** The one organization the App is installed on; a target outside it is refused. */
export const TARGET_OWNER = 'objectstack-ai';
/**
* The repositories a `transfer` may move a card to — the fleet's governed
* roster, reused, so a repository joins the fleet in ONE place and becomes a
* transfer target there. `validate.mjs --self-test` pins that every entry is
* in `TARGET_OWNER`.
*/
export const TRANSFER_TARGETS = Object.freeze(GOVERNED_REPOS.map((r) => r.slug));
/**
* The workflow files a `workflow_dispatch` may start, each with the ONE inputs
* object an action naming it carries (header: "A workflow's inputs are CLOSED
* per file"). `null`: the workflow declares no inputs, and the action carries
* no `inputs` key. An object: the action's `inputs`, spelled exactly.
* `validate.mjs --self-test` pins every key here to an input the file declares
* under its `workflow_dispatch` trigger, with the type the value has.
*/
export const WORKFLOW_DISPATCH_INPUTS = Object.freeze({
'shard-timings-refresh.yml': null,
// The bookkeeping lane alone — never `force`, never `refresh_version_pr: false` (the publish-repair lane).
'release.yml': Object.freeze({ refresh_version_pr: true }),
});
/**
* The workflow files a `workflow_dispatch` may start — one file name per
* entry, matched whole (never a path, never a glob), joined only by a PR that
* adds the entry, with its inputs, to `WORKFLOW_DISPATCH_INPUTS` above.
* `validate.mjs --self-test` pins that every entry is a file under
* `.github/workflows/` declaring a `workflow_dispatch` trigger.
*/
export const WORKFLOW_DISPATCH_ALLOWLIST = Object.freeze(Object.keys(WORKFLOW_DISPATCH_INPUTS));
/**
* The `inputs` object the dispatch request sends for a closed entry — every
* value as a string, the spelling measured on the dispatch endpoint (header).
* Pure; `null` for an entry that declares none.
*/
export function dispatchInputsOnTheWire(declared) {
if (declared === null || declared === undefined) return null;
return Object.fromEntries(Object.entries(declared).map(([name, value]) => [name, String(value)]));
}
/** The one ref a `workflow_dispatch` may start a run at. ⛔ Never a free string. */
export const WORKFLOW_DISPATCH_REF = 'main';
/** The shape of the dispatch call — one of the two `actions/*` paths the table reaches. */
export const WORKFLOW_DISPATCH_PATH_SHAPE = /\/actions\/workflows\/[^/]+\/dispatches$/;
/**
* The workflows a `run_rerun_failed` may re-run the failed jobs of — the run's
* own `path`, as `GET /actions/runs/{id}` answers it, matched WHOLE (measured
* on run 39713789453: `.github/workflows/ci.yml`, no ref suffix). Joined only
* by a PR that adds the path here; ⛔ never a key of the payload.
*
* A reviewed allowlist. `ci.yml` is the entry the op was made for. Every other
* entry is a READ-ONLY check workflow: it uses no `secrets.*` but
* `GITHUB_TOKEN`, deploys nothing (no `environment:`), and its token is read-only (a
* `permissions:` block covering every job, no `write` scope). A re-run of such a run
* can change nothing but its own check, so re-running it once costs only runner time.
* Each entry, and the reading that admitted it:
*
* - `.github/workflows/ci.yml` — the op's own workflow (the measured run above).
* - `.github/workflows/check-links.yml` — `Check Documentation Links`, advisory;
* `contents: read` on its one job, no secret, offline lychee. Its setup step
* can fail having checked ZERO links, and its log says so ("No links were
* checked"); that red is the one a seat re-runs once.
*
* `validate.mjs --self-test` pins the list exactly, every entry to a workflow on
* disk that runs on `pull_request`, and every entry after `ci.yml` to the
* read-only definition read from the file itself.
*/
export const RERUN_FAILED_WORKFLOWS = Object.freeze(['.github/workflows/ci.yml', '.github/workflows/check-links.yml']);
/** The one event whose run a `run_rerun_failed` may re-run: a pull request's. */
export const RERUN_FAILED_EVENT = 'pull_request';
/** The one attempt it may re-run — once: a second failure is real. The read-back wants the attempt after it. */
export const RERUN_FAILED_ATTEMPT = 1;
/** The state the run must be in: completed, and failed. */
export const RERUN_FAILED_STATUS = 'completed';
export const RERUN_FAILED_CONCLUSION = 'failure';
/** The job states the read-back accepts for a job attempt 1 failed — the ruling's two, nothing beside them. */
export const RERUN_FAILED_RERUN_STATES = Object.freeze(['queued', 'in_progress']);
/** The shape of the re-run call — the other `actions/*` path the table reaches; the run id is digits alone. */
export const RERUN_FAILED_PATH_SHAPE = /\/actions\/runs\/\d+\/rerun-failed-jobs$/;
/**
* The pull request a run's `head` fence reads: the run's `pull_requests[0].number`, or `null` when the run names
* none (a fork pull request's run, whose `pull_requests` the platform leaves empty, or a missing field). Pure.
*/
export function rerunFailedPullNumber(run) {
const n = Array.isArray(run?.pull_requests) ? run.pull_requests[0]?.number : undefined;
return Number.isSafeInteger(n) && n > 0 ? n : null;
}
const shortHead = (sha) => (typeof sha === 'string' ? sha.slice(0, 10) : null);
/**
* The five fences on the RUN and its pull (the header's `run_rerun_failed`
* section): `fence` its name, `wants` what the relay re-runs, `reads` the
* field(s) the failure sentence quotes, `holds` the predicate. Each takes
* `(run, pull)`: `run` the run's own answer, `pull` the answer of
* `GET /repos/{repo}/pulls/{n}` for the pull `rerunFailedPullNumber` names,
* or `null` when the run names none. ⛔ The `head` fence never reads the copy
* of the pull the run embeds. The other two fences — alone in its stroke, the
* stroke-scoped grant — are the validator's. The executor judges these on the
* two reads taken immediately before the POST; the seat's wrapper judges them
* earlier, as an advisory refusal.
*/
export const RERUN_FAILED_FENCES = Object.freeze([
Object.freeze({
fence: 'workflow',
wants: `a run whose path is one of ${RERUN_FAILED_WORKFLOWS.join(', ')} — a closed list, matched whole`,
reads: (run) => run?.path,
holds: (run) => typeof run?.path === 'string' && RERUN_FAILED_WORKFLOWS.includes(run.path),
}),
Object.freeze({
fence: 'event',
wants: `a ${RERUN_FAILED_EVENT} run — never a push, merge_group, schedule, release or workflow_dispatch one`,
reads: (run) => run?.event,
holds: (run) => run?.event === RERUN_FAILED_EVENT,
}),
Object.freeze({
fence: 'once',
wants: `run_attempt ${RERUN_FAILED_ATTEMPT} — a run is re-run at most once, and a second failure is real`,
reads: (run) => run?.run_attempt,
holds: (run) => run?.run_attempt === RERUN_FAILED_ATTEMPT,
}),
Object.freeze({
fence: 'failed',
wants: `status ${RERUN_FAILED_STATUS} with conclusion ${RERUN_FAILED_CONCLUSION}`,
reads: (run) => `status ${run?.status ?? null}, conclusion ${run?.conclusion ?? null}`,
holds: (run) => run?.status === RERUN_FAILED_STATUS && run?.conclusion === RERUN_FAILED_CONCLUSION,
}),
Object.freeze({
fence: 'head',
wants:
"a run whose head_sha is its pull request's CURRENT head (the pull named by pull_requests[0], read with its own GET, " +
"never the run's embedded copy), since each listed workflow's concurrency group is keyed by the pull number and a stale head's re-run cancels the current head's run",
reads: (run, pull) => {
const n = rerunFailedPullNumber(run);
if (n === null) return "no pull_requests entry — a fork pull request's run, or none";
return `head_sha ${shortHead(run?.head_sha)}, and pull #${n}'s own GET answers #${pull?.number ?? null} at head ${shortHead(pull?.head?.sha)}`;
},
holds: (run, pull) => {
const n = rerunFailedPullNumber(run);
return n !== null && typeof run?.head_sha === 'string' && run.head_sha !== '' && pull?.number === n && pull?.head?.sha === run.head_sha;
},
}),
]);
/**
* The fences a run's answer and its pull's fail: `[{ fence, wants, got }]`, in `RERUN_FAILED_FENCES` order; `[]`
* when all five hold. `pull` is the pull's own answer, or `null` when the run names no pull. Pure.
*/
export function rerunFailedFenceFailures(run, pull = null) {
return RERUN_FAILED_FENCES.filter((f) => !f.holds(run, pull)).map((f) => ({ fence: f.fence, wants: f.wants, got: f.reads(run, pull) ?? null }));
}
/** The sentence a fence refusal prints — every failing fence by name, what the run read and what the relay re-runs. Pure. */
export function rerunFailedFenceText(failures) {
return failures.map((f) => `fence \`${f.fence}\`: the run reads ${JSON.stringify(f.got)}, and the relay re-runs only ${f.wants}`).join('; ');
}
/** The names of the jobs that concluded `failure` in one attempt's job list — the jobs the read-back looks for. Pure. */
export function failedJobNames(jobs) {
const out = [];
for (const j of Array.isArray(jobs) ? jobs : []) {
if (j?.conclusion === RERUN_FAILED_CONCLUSION && typeof j.name === 'string' && !out.includes(j.name)) out.push(j.name);
}
return out;
}
/**
* What LANDED means for a `run_rerun_failed` (the header's section): `failed`
* the job names attempt 1 failed, `run` the run read again after the POST,
* `jobs` its attempt-2 job list. Answers `{ ok, pending, attempt, rerun,
* notListed, other, why }`:
*
* rerun `[{ name, id, status }]` — each failed job listed in attempt 2 `queued` or `in_progress`;
* notListed the failed names attempt 2 does not list yet — NAMED, never failed: a job is created when
* its needs finish (measured, header), so an aggregate job behind a re-running shard is absent;
* other `[{ name, id, status, conclusion }]` — a failed job listed in any other state;
* ok attempt 2, at least one `rerun`, and no `other`;
* pending not landed YET — attempt 2 not seen, nothing re-running listed, or a job still in a pre-queue
* state (`waiting`, `requested`, `pending`) — the executor re-reads inside its window;
* neither a FAILED action: a failed job listed `completed` in attempt 2 was not re-run as asked.
*
* Pure.
*/
export function rerunFailedReadBack({ failed = [], run = null, jobs = [] } = {}) {
const want = RERUN_FAILED_ATTEMPT + 1;
const attempt = run?.run_attempt ?? null;
if (attempt !== want) {
return { ok: false, pending: true, attempt, rerun: [], notListed: [...failed], other: [], why: `the run reads run_attempt ${JSON.stringify(attempt)}, not ${want} — the re-run has not shown as a new attempt` };
}
const listed = (Array.isArray(jobs) ? jobs : []).filter((j) => j && typeof j.name === 'string' && (j.run_attempt === undefined || j.run_attempt === want));
const rerun = [];
const notListed = [];
const other = [];
for (const name of failed) {
const named = listed.filter((j) => j.name === name);
if (named.length === 0) {
notListed.push(name);
continue;
}
const live = named.find((j) => RERUN_FAILED_RERUN_STATES.includes(j.status));
if (live) rerun.push({ name, id: live.id ?? null, status: live.status });
else other.push({ name, id: named[0].id ?? null, status: named[0].status ?? null, conclusion: named[0].conclusion ?? null });
}
const settled = other.filter((j) => j.status === RERUN_FAILED_STATUS);
if (settled.length) {
return { ok: false, pending: false, attempt, rerun, notListed, other, why: `attempt ${want} lists ${settled.map((j) => `\`${j.name}\` (job ${j.id}) ${j.status}${j.conclusion ? ` ${j.conclusion}` : ''}`).join(', ')} — a job attempt ${RERUN_FAILED_ATTEMPT} failed, not ${RERUN_FAILED_RERUN_STATES.join(' or ')}, so it was not re-run as asked` };
}
if (other.length) return { ok: false, pending: true, attempt, rerun, notListed, other, why: `attempt ${want} lists ${other.map((j) => `\`${j.name}\` (job ${j.id}) ${j.status}`).join(', ')} — not ${RERUN_FAILED_RERUN_STATES.join(' or ')} yet` };
if (rerun.length === 0) return { ok: false, pending: true, attempt, rerun, notListed, other, why: `attempt ${want} lists none of the ${failed.length} job(s) attempt ${RERUN_FAILED_ATTEMPT} failed yet` };
return { ok: true, pending: false, attempt, rerun, notListed, other, why: '' };
}
/** The read-back line a landing prints: the new attempt and its job ids, then what is not listed yet. Pure. */
export function rerunFailedLandedText(v) {
const jobs = v.rerun.map((j) => `\`${j.name}\` job ${j.id} ${j.status}`).join(', ');
const later = v.notListed.length ? ` · not listed yet: ${v.notListed.map((n) => `\`${n}\``).join(', ')} (a job is listed when its needs finish)` : '';