@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/README.md +248 -213
  2. package/README.vi.md +252 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +7 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1902 -278
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +223 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +42 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +153 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +723 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +778 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +324 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +118 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/ship-human-door.js +76 -0
  65. package/tools/lib/stamp.js +7 -0
  66. package/tools/lib/tracker-fake.js +195 -0
  67. package/tools/lib/tracker-github.js +106 -0
  68. package/tools/lib/tracker-scenarios.json +206 -0
  69. package/tools/lib/tracker.js +64 -0
  70. package/tools/lib/tree-green.js +88 -0
  71. package/tools/lib/util.js +17 -1
  72. package/tools/lib/verify-runs.js +104 -0
  73. package/tools/lib/wake.js +8 -90
  74. package/tools/lib/workflow-triggers.js +48 -0
@@ -34,6 +34,13 @@
34
34
  * trailer scan that feeds this (tools/colab's computeAntiStacking) to recognise BOTH a
35
35
  * prior `CI-Grant:` trailer and a prior `CI-Cure:` trailer as "an exemption already merged
36
36
  * against this red" — a cure and a grant are both exemptions for this guard's purposes.
37
+ * ONE NARROW ADMISSION (#477): PROGRESS. When the guard refuses because a prior exemption
38
+ * already merged on this continuous red, a further cure is still admitted iff trunk's red-job
39
+ * set at the current red sha is a STRICT subset of the red-job set at the red sha the prior
40
+ * exemption was measured against (`redSetShrank`, below). A fix that repaired one of two red
41
+ * jobs, or two independent failures healed by two successive fixes, then needs no human step;
42
+ * a cure that left the set unchanged — or grew it — still stops the chain, which is the loop
43
+ * condition 3 exists to break. Every other condition still applies to the remaining set.
37
44
  * 4. NO WORKFLOW-FILE CHANGES — the branch diff must not touch `.github/workflows/**`. A
38
45
  * branch that edits the CI configuration doing the grading is not allowed to grade itself;
39
46
  * that door stays behind a human ci-grant (condition 4 in the original proposal, #281).
@@ -44,12 +51,29 @@
44
51
  * and test run at all, and a skipped step leaves the job `success` — so deleting
45
52
  * `scripts.test` weakens the instrument without touching a workflow file. No carve-out: see
46
53
  * below for why the #321 door cannot adjudicate it.
54
+ * ONE NARROW ADMISSION (#475): an ADD-ONLY scripts change — keys added, none removed or changed,
55
+ * no lifecycle hook — makes the template run MORE, so it passes condition 5 on step evidence
56
+ * (`manifestStepProof`, below) instead of refusing.
47
57
  * 6. NO PYTHON DEPENDENCY-MANIFEST CHANGES (#377) — the branch diff must not change a file the
48
58
  * Python CI template installs from (`pyproject.toml`/`setup.py`/`setup.cfg`, `requirements*`
49
59
  * files and what they include — tools/lib/cure-diff.js names the set). That template runs
50
60
  * ruff/mypy/pytest only when the tool is importable after install, so removing `pytest` from
51
61
  * `requirements-dev.txt` skips the Test step and leaves the job `success`. Same shape as 5, a
52
- * sibling door with no carve-out, for the same reason.
62
+ * sibling door with no carve-out, for the same reason. ONE NARROW ADMISSION (#476): a PIN-ONLY
63
+ * change — only the version specifier of requirements present on both sides — passes on step
64
+ * evidence plus the no-late-skip test (`manifestStepProof`, below).
65
+ *
66
+ * THE STEP PROOF BEHIND BOTH ADMISSIONS (#475, #476). Every step that RAN in each red job on trunk —
67
+ * the failing one included — ran on the branch and concluded `success`: the 4b read, applied here
68
+ * without the carve-out's duration floor (no workflow changed, so no `run:` body can have been
69
+ * gutted). Check-runs name steps, not commands, so "the step that runs the added script" is not
70
+ * measurable as such; "the step trunk failed in now passes" is, and it is the claim a cure makes.
71
+ * The pin admission adds one test (#476's open question, answered): a pin can drop a TRANSITIVELY
72
+ * installed tool, and the Python template then skips that tool's step with the job still `success`.
73
+ * Steps before trunk's failure point are covered by the superset; steps AFTER it were skipped on
74
+ * trunk and so say nothing. So no step after the last one that ran on trunk may be `skipped` on the
75
+ * branch. That refuses a repo that never had, say, mypy when its red came before the Typecheck step
76
+ * — a false refusal, falling through to the ci-grant, the safe direction.
53
77
  *
54
78
  * THE WORKFLOW CARVE-OUT (#321) — why condition 4 could not simply stay absolute. The repair for
55
79
  * a CI-INFRASTRUCTURE outage is, by construction, a workflow change: when trunk goes red because
@@ -126,6 +150,60 @@
126
150
  * is the obvious first follow-up the moment that refusal is observed in the field, but adding it
127
151
  * unmeasured is precisely the speculative loosening condition 4 exists to resist.
128
152
  *
153
+ * DRY-RUN EVIDENCE FOR A MAIN-ONLY WORKFLOW (#474). Some checks never run on a branch at all:
154
+ * `release-auto.yml` fires on `workflow_run` after trunk CI, or on a schedule. 2b then refuses every
155
+ * fix for a red in it (the job is absent on the branch), and a human ci-grant was the only door,
156
+ * even for a mechanical defect. The workflow template therefore offers a DRY RUN: dispatched on the
157
+ * fix branch, it runs the same job and the same steps, but with every external write turned off. Steps
158
+ * that would publish are skipped, and their names end in `PUBLISH_STEP_MARKER`. A sentinel step named
159
+ * `DRY_RUN_STEP` runs only in that mode, and is how a job instance is recognised as a dry run here.
160
+ * Such an instance counts as the job's evidence for 2b (and hence 4a) only when, on top of 2b:
161
+ *
162
+ * D1. both step lists are measurable — trunk's ran-steps and the dry run's steps;
163
+ * D2. every step that RAN on trunk, the failing one included, concluded `success` in the dry run.
164
+ * This is the not-a-back-door proof: a red INSIDE a publishing step can never be cured this way,
165
+ * because the dry run skips exactly that step. It is 4b, applied to dry-run instances on every
166
+ * path, not only the carve-out's;
167
+ * D3. every step the dry run did NOT run to success is a skipped publishing step. A dry run that
168
+ * also skipped some ordinary step past trunk's failure point has not run the job, it has run
169
+ * part of it.
170
+ *
171
+ * Why a NAME marker and not a list declared in the workflow: steps are matched by exact name (D2/4b),
172
+ * so marking the very step that failed on trunk renames it, and D2 then reads it as absent and
173
+ * refuses. A list inside the workflow would be read from the branch, which is the party being graded.
174
+ *
175
+ * Limit, stated: a red in a publishing step, or in a later job that only runs after a tag (npm,
176
+ * deploy), cannot be cured by a dry run. That stays a ci-grant. So does a red job that ran ZERO steps
177
+ * (a runner that never picked it up) on the carve-out path: 4c has no usable duration for it and
178
+ * refuses, which is the safe direction and a deliberately unmade loosening, like the timeout case.
179
+ *
180
+ * DISPATCH EVIDENCE FOR A JOB A BRANCH PUSH SKIPS (#510). One level below #474: the WORKFLOW runs on a
181
+ * branch push, but one of its JOBS is trunk-only by its own `if:` (true on trunk, on a schedule and on
182
+ * `workflow_dispatch`, false on a branch push) — an E2E suite moved off the branch path to keep branch CI
183
+ * short. A branch push then shows that job skipped (or, for an unexpanded matrix, absent), 2b refuses,
184
+ * and a human ci-grant was the only door. The same workflow dispatched on the branch runs the job. A
185
+ * DISPATCH INSTANCE — a job row from a run with `event: workflow_dispatch` that is not a #474 dry run —
186
+ * counts as the job's evidence only when, on top of 2b's own tests (completed `success`; no instance at
187
+ * the head red or pending — so `skipped`, `neutral`, `cancelled` or absent never counts, and a job that
188
+ * ran and FAILED on the push run is never rescued by a green dispatch):
189
+ *
190
+ * W1. SAME WORKFLOW — the dispatch run's workflow id equals the red run's. Ids are per file and the same
191
+ * on every ref; the display name is not, two files can share a `name:`. Either id missing refuses.
192
+ * W2. SAME HEAD — the dispatch run's head sha is the branch evidence sha. Rows at any other sha are
193
+ * dropped by `shapeJobEvidence`; the check is repeated here so it holds without the caller.
194
+ * W5. THE FAILING STEP RAN — every step that went red on trunk is present by exact name in the dispatch
195
+ * instance and concluded `success`. GitHub reports a job whose steps were all skipped as `success`,
196
+ * so job-level success alone cannot see a step whose own `if:` depends on the event. Deliberately
197
+ * NOT the full executed-step superset (4b/D2): a cache-conditional step that ran on trunk is skipped
198
+ * on a cache hit, which would refuse genuine cures. A trunk red with no red STEP (a timeout, a lost
199
+ * runner) leaves W5 nothing to check, and job-level success decides — a stated limit.
200
+ * W6. PER JOB, BY EXACT NAME — the existing `jobKey`; matrix shards match by expanded name, one green
201
+ * shard never covers another, and nothing is matched by prefix.
202
+ *
203
+ * W1 and W2 apply to a #474 dry-run instance too when its row says `workflow_dispatch` — the same
204
+ * same-name hole. A green ordinary instance outranks a green dispatch instance, which outranks a green
205
+ * dry run: each rule set applies only when that instance is the job's sole evidence.
206
+ *
129
207
  * PURE BY CONSTRUCTION, identical posture to ci-grant.js / migration-grant.js / readiness.js /
130
208
  * shipguard.js: signals in, verdict out. No git, no network, no `gh`. The caller (tools/colab)
131
209
  * measures containment, evidence, anti-stacking and the workflow-file diff, and hands them in.
@@ -177,6 +255,25 @@ const PYTHON_MANIFEST_REFUSAL =
177
255
  * never ran is not a job that failed. */
178
256
  const NOT_RED_CONCLUSIONS = new Set(['success', 'cancelled', 'skipped']);
179
257
 
258
+ /** The suffix a step name carries when the dry run skips it because it writes outside the run (#474).
259
+ * The template names its publishing steps with it; D3 admits no other skipped step. */
260
+ const PUBLISH_STEP_MARKER = '[publish]';
261
+
262
+ /** The sentinel step a dry-run job instance runs and an ordinary one skips (#474). Its successful
263
+ * presence is the only thing that marks an instance as a dry run here. Must match the template's
264
+ * step name byte for byte. */
265
+ const DRY_RUN_STEP = 'Dry run — nothing is tagged, released or published';
266
+
267
+ function isPublishStepName(name) {
268
+ return typeof name === 'string' && name.trimEnd().endsWith(PUBLISH_STEP_MARKER);
269
+ }
270
+
271
+ /** A job instance is a dry run iff its sentinel step concluded `success`. A skipped sentinel is an
272
+ * ordinary run (the template's `if:` was false), never a dry one. */
273
+ function isDryRunSteps(steps) {
274
+ return Array.isArray(steps) && steps.some((s) => s && s.name === DRY_RUN_STEP && s.conclusion === 'success');
275
+ }
276
+
180
277
  /** A step "ran" on trunk iff it reached a terminal conclusion that is not `skipped`/`cancelled`.
181
278
  * Steps after the failing one are skipped by GitHub, and a skipped step constrains nothing. */
182
279
  function stepRan(s) {
@@ -224,7 +321,7 @@ function usableMs(v) {
224
321
  * half-finished red run cannot be adjudicated: a job still in flight may yet become the red one
225
322
  * the branch would have to prove it repaired.
226
323
  */
227
- function shapeJobEvidence({ redRunJobs, branchRunJobs } = {}) {
324
+ function shapeJobEvidence({ redRunJobs, branchRunJobs, branchSha } = {}) {
228
325
  if (!Array.isArray(redRunJobs) || !Array.isArray(branchRunJobs)) return null;
229
326
  if (redRunJobs.some((j) => !j || j.status !== 'completed')) return null;
230
327
 
@@ -233,21 +330,41 @@ function shapeJobEvidence({ redRunJobs, branchRunJobs } = {}) {
233
330
  .map((j) => ({
234
331
  name: j.name,
235
332
  workflowName: j.workflowName || '',
333
+ workflowId: idOrNull(j.workflowId),
236
334
  conclusion: j.conclusion,
237
335
  durationMs: durationMs(j.startedAt, j.completedAt),
238
336
  ranSteps: Array.isArray(j.steps) ? j.steps.filter(stepRan).map((s) => s.name) : null,
337
+ // #510 W5: the steps that went red on trunk — the ones a dispatch instance must show passing.
338
+ failedSteps: Array.isArray(j.steps) ? j.steps.filter((s) => stepRan(s) && s.conclusion !== 'success').map((s) => s.name) : null,
239
339
  }));
240
340
 
241
- const branchJobs = branchRunJobs.map((j) => ({
242
- name: j && j.name,
243
- workflowName: (j && j.workflowName) || '',
244
- status: j && j.status,
245
- conclusion: j && j.conclusion,
246
- durationMs: j ? durationMs(j.startedAt, j.completedAt) : null,
247
- steps: j && Array.isArray(j.steps) ? j.steps.map((s) => ({ name: s && s.name, conclusion: s && s.conclusion })) : null,
248
- }));
341
+ const branchJobs = branchRunJobs
342
+ // #510 W2: a row at another sha is never evidence for this head — dropped when both shas are known.
343
+ .filter((j) => !(branchSha && j && j.headSha && j.headSha !== branchSha))
344
+ .map((j) => {
345
+ const dryRun = !!j && isDryRunSteps(j.steps);
346
+ const event = (j && j.event) || null;
347
+ return {
348
+ name: j && j.name,
349
+ workflowName: (j && j.workflowName) || '',
350
+ workflowId: j ? idOrNull(j.workflowId) : null,
351
+ event,
352
+ headSha: (j && j.headSha) || null,
353
+ status: j && j.status,
354
+ conclusion: j && j.conclusion,
355
+ durationMs: j ? durationMs(j.startedAt, j.completedAt) : null,
356
+ steps: j && Array.isArray(j.steps) ? j.steps.map((s) => ({ name: s && s.name, conclusion: s && s.conclusion })) : null,
357
+ dryRun,
358
+ dispatch: event === 'workflow_dispatch' && !dryRun,
359
+ };
360
+ });
249
361
 
250
- return { redJobs, branchJobs };
362
+ return { redJobs, branchJobs, branchSha: branchSha || null };
363
+ }
364
+
365
+ /** A workflow id as carried on a run row (#510 W1), or null — never `0`/`''` read as an id. */
366
+ function idOrNull(v) {
367
+ return (typeof v === 'number' && Number.isFinite(v) && v > 0) || (typeof v === 'string' && v !== '') ? v : null;
251
368
  }
252
369
 
253
370
  /** How a job is named in a reason string: `workflow / job` when the workflow is known. */
@@ -272,20 +389,107 @@ function jobKey(j) {
272
389
  */
273
390
  function indexBranchJobs(branchJobs) {
274
391
  const idx = new Map();
392
+ // A green ORDINARY instance outranks a green dispatch instance (#510), which outranks a green dry run
393
+ // (#474): each rule set applies only when that instance is the sole evidence the branch has for the job.
394
+ const rank = (x) => (x.status !== 'completed' || x.conclusion !== 'success' ? 0 : x.dryRun ? 1 : x.dispatch ? 2 : 3);
275
395
  for (const j of branchJobs) {
276
396
  if (!j || !j.name) continue;
277
397
  const k = jobKey(j);
278
398
  const prev = idx.get(k);
279
399
  const isRed = j.status === 'completed' && !NOT_RED_CONCLUSIONS.has(j.conclusion);
280
400
  const isPending = j.status !== 'completed';
281
- if (!prev) { idx.set(k, { job: j, hasRed: isRed, hasPending: isPending }); continue; }
282
- const better = j.status === 'completed' && j.conclusion === 'success'
283
- && !(prev.job.status === 'completed' && prev.job.conclusion === 'success');
284
- idx.set(k, { job: better ? j : prev.job, hasRed: prev.hasRed || isRed, hasPending: prev.hasPending || isPending });
401
+ // #510: every instance completed `skipped` — the shape a trunk-only job leaves on a branch push.
402
+ const isSkipped = j.status === 'completed' && j.conclusion === 'skipped';
403
+ if (!prev) { idx.set(k, { job: j, hasRed: isRed, hasPending: isPending, allSkipped: isSkipped }); continue; }
404
+ const better = rank(j) > rank(prev.job);
405
+ idx.set(k, { job: better ? j : prev.job, hasRed: prev.hasRed || isRed, hasPending: prev.hasPending || isPending,
406
+ allSkipped: prev.allSkipped && isSkipped });
285
407
  }
286
408
  return idx;
287
409
  }
288
410
 
411
+ /**
412
+ * The dry-run rules (#474), D1–D3 — see the module header. `red` is a trunk red job (with
413
+ * `ranSteps`), `mine` the branch's dry-run instance of the same job (with `steps`). Returns a refusal
414
+ * reason, or '' when the dry run is admissible evidence for this job.
415
+ */
416
+ function dryRunEvidence(red, mine) {
417
+ const label = jobLabel(red);
418
+ if (!Array.isArray(red.ranSteps) || !Array.isArray(mine.steps)) {
419
+ return `job \`${label}\` is proven only by a dry run, and its step lists could not be read — a dry run is admissible only step by step`;
420
+ }
421
+ const mySteps = new Map();
422
+ for (const s of mine.steps) if (s && s.name) mySteps.set(s.name, s);
423
+ for (const stepName of red.ranSteps) {
424
+ const s = mySteps.get(stepName);
425
+ if (!s) {
426
+ return `step \`${stepName}\` RAN in job \`${label}\` on trunk and is absent from the branch's dry run — a dry run proves only the steps it executes`;
427
+ }
428
+ if (s.conclusion !== 'success') {
429
+ return `step \`${stepName}\` RAN in job \`${label}\` on trunk and concluded \`${s.conclusion}\` in the branch's dry run — ` +
430
+ 'a dry run cannot cure a red in a step it does not execute (a red in a publishing step stays a ci-grant)';
431
+ }
432
+ }
433
+ for (const s of mine.steps) {
434
+ if (!s || s.conclusion === 'success') continue;
435
+ if (s.conclusion === 'skipped' && isPublishStepName(s.name)) continue;
436
+ return `step \`${s && s.name}\` concluded \`${s && s.conclusion}\` in the branch's dry run of job \`${label}\` and is not a publishing step ` +
437
+ `(name ending \`${PUBLISH_STEP_MARKER}\`) — a dry run may skip only the steps that write outside the run`;
438
+ }
439
+ return '';
440
+ }
441
+
442
+ /**
443
+ * W1/W2 (#510) for any instance whose run was a `workflow_dispatch` — a #510 dispatch instance or a
444
+ * #474 dry run. Returns a refusal reason, or ''.
445
+ */
446
+ function dispatchRunIdentity(red, mine, branchSha) {
447
+ const label = jobLabel(red);
448
+ if (red.workflowId === null || red.workflowId === undefined || mine.workflowId === null || mine.workflowId === undefined) {
449
+ return `job \`${label}\` is proven only by a workflow_dispatch run, and the workflow id of the red run or of that run could not be read — ` +
450
+ 'a dispatch run counts only as the SAME workflow file, and a display name is not proof of that';
451
+ }
452
+ if (String(red.workflowId) !== String(mine.workflowId)) {
453
+ return `job \`${label}\` is proven only by a workflow_dispatch run of a DIFFERENT workflow (id ${mine.workflowId}, trunk's red run is ${red.workflowId}) — ` +
454
+ 'a workflow that shares the display name is not the workflow that is red';
455
+ }
456
+ if (!branchSha || !mine.headSha || mine.headSha !== branchSha) {
457
+ return `job \`${label}\` is proven only by a workflow_dispatch run that is not at the branch's evidence head (\`${mine.headSha || '?'}\`) — ` +
458
+ 'evidence counts only at the head being shipped';
459
+ }
460
+ return '';
461
+ }
462
+
463
+ /**
464
+ * The dispatch rules (#510) — W1, W2 and W5; see the module header. `red` is a trunk red job (with
465
+ * `workflowId` and `failedSteps`), `mine` the branch's dispatch instance of the same job. Returns a
466
+ * refusal reason, or '' when the dispatch run is admissible evidence for this job. W4 (job success, no
467
+ * red or pending sibling) and W6 (the per-job key) are applied by `redJobsProvenOnBranch` before this.
468
+ */
469
+ function dispatchEvidence(red, mine, branchSha) {
470
+ const id = dispatchRunIdentity(red, mine, branchSha);
471
+ if (id) return id;
472
+ const label = jobLabel(red);
473
+ if (!Array.isArray(red.failedSteps) || !Array.isArray(mine.steps)) {
474
+ return `job \`${label}\` is proven only by a workflow_dispatch run, and the step lists could not be read — ` +
475
+ 'a dispatch run proves a cure only if the step that failed on trunk ran and passed in it';
476
+ }
477
+ const mySteps = new Map();
478
+ for (const s of mine.steps) if (s && s.name) mySteps.set(s.name, s);
479
+ for (const stepName of red.failedSteps) {
480
+ const s = mySteps.get(stepName);
481
+ if (!s) {
482
+ return `step \`${stepName}\` failed in job \`${label}\` on trunk and is absent from the branch's workflow_dispatch run — ` +
483
+ 'a dispatch run proves only the steps it executes';
484
+ }
485
+ if (s.conclusion !== 'success') {
486
+ return `step \`${stepName}\` failed in job \`${label}\` on trunk and concluded \`${s.conclusion}\` in the branch's workflow_dispatch run — ` +
487
+ 'a job that reports success with that step skipped has not run it';
488
+ }
489
+ }
490
+ return '';
491
+ }
492
+
289
493
  /**
290
494
  * Sub-test 4a (#321), and — since #297 — condition 2b of EVERY cure: every job RED on trunk exists
291
495
  * on the branch's runs at its own head, completed and successful.
@@ -299,7 +503,9 @@ function indexBranchJobs(branchJobs) {
299
503
  * that exists only on the branch: this certifies that the branch cures trunk's red, not that the
300
504
  * branch is spotless.
301
505
  *
302
- * Returns `{ok, reason, jobs}` — `jobs` is the list of red job names proven on the branch.
506
+ * Returns `{ok, reason, jobs, dryRunJobs, dispatchJobs}` — `jobs` is the list of red job names proven on
507
+ * the branch, `dryRunJobs` the subset proven only by a dry run (#474), each having passed D1–D3, and
508
+ * `dispatchJobs` the subset proven only by a workflow_dispatch run (#510), each having passed W1–W6.
303
509
  * Every unmeasurable input is a refusal, never a pass.
304
510
  */
305
511
  function redJobsProvenOnBranch(jobEvidence) {
@@ -317,6 +523,8 @@ function redJobsProvenOnBranch(jobEvidence) {
317
523
  return { ok: false, jobs: [], reason: "the branch's own run reported no jobs to compare against" };
318
524
  }
319
525
  const idx = indexBranchJobs(branchJobs);
526
+ const dryRunJobs = [];
527
+ const dispatchJobs = [];
320
528
 
321
529
  for (const red of redJobs) {
322
530
  if (!red || !red.name) {
@@ -341,8 +549,19 @@ function redJobsProvenOnBranch(jobEvidence) {
341
549
  return { ok: false, jobs: [],
342
550
  reason: `job \`${label}\` is red on trunk and failed in another run at the branch's own head — a job that both passed and failed at one sha has proven nothing` };
343
551
  }
552
+ if (mine.dryRun) {
553
+ const why = (mine.event === 'workflow_dispatch' ? dispatchRunIdentity(red, mine, jobEvidence.branchSha) : '')
554
+ || dryRunEvidence(red, mine);
555
+ if (why) return { ok: false, jobs: [], reason: why };
556
+ dryRunJobs.push(red.name);
557
+ } else if (mine.dispatch) {
558
+ const why = dispatchEvidence(red, mine, jobEvidence.branchSha);
559
+ if (why) return { ok: false, jobs: [], reason: why };
560
+ dispatchJobs.push(red.name);
561
+ }
344
562
  }
345
- return { ok: true, jobs: redJobs.map((r) => r.name), reason: '' };
563
+ return { ok: true, jobs: redJobs.map((r) => r.name), ...(dryRunJobs.length ? { dryRunJobs } : {}),
564
+ ...(dispatchJobs.length ? { dispatchJobs } : {}), reason: '' };
346
565
  }
347
566
 
348
567
  /**
@@ -402,6 +621,199 @@ function workflowCarveOut(jobEvidence) {
402
621
  return { ok: true, jobs, reason: '' };
403
622
  }
404
623
 
624
+ /**
625
+ * The step proof behind the #475/#476 manifest admissions — 4b without 4c, plus (for a pin) the
626
+ * no-late-skip test. See the module header. Returns `{ok, reason}`; every unmeasurable input refuses.
627
+ * Called only after `redJobsProvenOnBranch` passed, so every red job has a successful branch instance.
628
+ */
629
+ function manifestStepProof(jobEvidence, { noLateSkip = false } = {}) {
630
+ if (!jobEvidence || !Array.isArray(jobEvidence.redJobs) || !Array.isArray(jobEvidence.branchJobs)) {
631
+ return { ok: false, reason: 'the job-level evidence could not be measured' };
632
+ }
633
+ const idx = indexBranchJobs(jobEvidence.branchJobs);
634
+ for (const red of jobEvidence.redJobs) {
635
+ // A dry-run instance (#474) is the job's branch evidence like any other — redJobsProvenOnBranch
636
+ // already held it to D1–D3, which imply the superset below. See the late-skip note.
637
+ const entry = idx.get(jobKey(red));
638
+ if (!entry) return { ok: false, reason: `job \`${jobLabel(red)}\` is absent on the branch` };
639
+ const mine = entry.job;
640
+ if (!Array.isArray(red.ranSteps) || !red.ranSteps.length) {
641
+ return { ok: false, reason: `the steps that ran in job \`${jobLabel(red)}\` on trunk could not be read` };
642
+ }
643
+ if (!Array.isArray(mine.steps)) {
644
+ return { ok: false, reason: `the steps of job \`${jobLabel(red)}\` on the branch could not be read` };
645
+ }
646
+ let last = -1;
647
+ for (const stepName of red.ranSteps) {
648
+ const at = mine.steps.findIndex((s) => s && s.name === stepName);
649
+ if (at === -1) {
650
+ return { ok: false, reason: `step \`${stepName}\` ran in job \`${jobLabel(red)}\` on trunk and is absent on the branch` };
651
+ }
652
+ if (mine.steps[at].conclusion !== 'success') {
653
+ return { ok: false,
654
+ reason: `step \`${stepName}\` ran in job \`${jobLabel(red)}\` on trunk and concluded \`${mine.steps[at].conclusion}\` on the branch` };
655
+ }
656
+ if (at > last) last = at;
657
+ }
658
+ if (noLateSkip) {
659
+ // A dry run (#474) skips its `[publish]` steps by design, and D3 already refused any OTHER skip
660
+ // in it — so those, and only those, are not a dropped tool.
661
+ const late = mine.steps.slice(last + 1)
662
+ .find((s) => s && s.conclusion === 'skipped' && !(mine.dryRun && isPublishStepName(s.name)));
663
+ if (late) {
664
+ return { ok: false,
665
+ reason: `step \`${late.name}\` in job \`${jobLabel(red)}\` comes after trunk's failure point and was skipped on the branch — ` +
666
+ 'trunk never reached it, so whether the pin dropped the tool it needs is unmeasurable' };
667
+ }
668
+ }
669
+ }
670
+ return { ok: true, reason: '' };
671
+ }
672
+
673
+ /**
674
+ * Would a dry run on the branch supply the evidence 2b is missing (#474)? PURE. Returns the sorted
675
+ * workflow names to dispatch, or `[]`. Non-empty only when EVERY red job is either already passing
676
+ * on the branch (completed `success`, nothing red or pending beside it) or ABSENT from the branch's
677
+ * runs in a workflow listed in `dryRunCapable` — and at least one is absent. A red job that is
678
+ * present-but-failing, pending, or absent in a workflow without a dry-run mode means no dispatch
679
+ * would help, so none is asked for. Whether the dry run, once it exists, passes D1–D3 is decided
680
+ * then, not predicted now.
681
+ */
682
+ function dryRunDispatchPlan(jobEvidence, dryRunCapable) {
683
+ return cureDispatchPlan(jobEvidence, { dryRunCapable }).dryRun;
684
+ }
685
+
686
+ /**
687
+ * Which dispatch(es) would supply the evidence 2b is missing — a #474 dry run, or a #510 plain
688
+ * `workflow_dispatch` of a branch workflow whose red job a branch push skips. PURE. Returns
689
+ * `{dryRun: [workflow names], dispatch: [workflow names]}`, both sorted; both empty unless EVERY red job
690
+ * is either already passing on the branch, or missing in a way one of the two dispatches answers:
691
+ *
692
+ * - ABSENT from the branch's runs in a workflow listed in `dryRunCapable` → a dry run (#474, unchanged);
693
+ * - ABSENT, or present only as `skipped` instances, in a workflow listed in `dispatchable` → a dispatch
694
+ * (#510), and only when `branchRuns` shows that workflow has a completed, successful NON-dispatch run
695
+ * at the head (gate d: it is branch CI, not a main-only workflow a dispatch could publish from) and NO
696
+ * `workflow_dispatch` run there yet, whatever its status (gate e: a dispatch already made either is
697
+ * still running, or ran and did not supply the job — dispatching again would not help).
698
+ *
699
+ * A red job present-but-failing, pending, or missing in a workflow neither list names means no dispatch
700
+ * would help, so none is asked for. Whether the run, once it exists, passes D1–D3 or W1–W6 is decided
701
+ * then, not predicted now.
702
+ */
703
+ function cureDispatchPlan(jobEvidence, { dryRunCapable, dispatchable, branchRuns } = {}) {
704
+ const none = { dryRun: [], dispatch: [] };
705
+ const asSet = (x) => new Set(Array.isArray(x) ? x : x instanceof Set ? [...x] : []);
706
+ const capable = asSet(dryRunCapable);
707
+ const plain = asSet(dispatchable);
708
+ if ((!capable.size && !plain.size) || !jobEvidence || !Array.isArray(jobEvidence.redJobs) || !jobEvidence.redJobs.length) return none;
709
+ const idx = indexBranchJobs(Array.isArray(jobEvidence.branchJobs) ? jobEvidence.branchJobs : []);
710
+ const dry = new Set();
711
+ const disp = new Set();
712
+ for (const red of jobEvidence.redJobs) {
713
+ if (!red || !red.name) return none;
714
+ const entry = idx.get(jobKey(red));
715
+ const wf = red.workflowName;
716
+ if (!entry && wf && capable.has(wf)) { dry.add(wf); continue; }
717
+ if ((!entry || entry.allSkipped) && wf && plain.has(wf)) { disp.add(wf); continue; }
718
+ if (!entry) return none;
719
+ const mine = entry.job;
720
+ if (mine.status !== 'completed' || entry.hasPending || mine.conclusion !== 'success' || entry.hasRed) return none;
721
+ }
722
+ if (disp.size) {
723
+ if (!Array.isArray(branchRuns)) return none;
724
+ for (const wf of disp) {
725
+ const runs = branchRuns.filter((r) => r && r.workflowName === wf);
726
+ if (runs.some((r) => r.event === 'workflow_dispatch')) return none;
727
+ if (!runs.some((r) => r.event !== 'workflow_dispatch' && r.status === 'completed' && r.conclusion === 'success')) return none;
728
+ }
729
+ }
730
+ return { dryRun: [...dry].sort(), dispatch: [...disp].sort() };
731
+ }
732
+
733
+ /**
734
+ * The prior exemption's red sha (#477), read off its merge commit's message: both trailers carry
735
+ * `over-red <trunk>@<sha>` — `CI-Grant:` (#105) and `CI-Cure:` (#281) — and that sha is what the
736
+ * prior exemption was measured against. Returns the hex string as written (usually short) or `null`
737
+ * when no such trailer line is present. Only a line STARTING with one of the two prefixes counts,
738
+ * the same anchoring `computeAntiStacking`'s `--grep` uses, so prose quoting a trailer cannot feed it.
739
+ */
740
+ function priorRedShaFromMessage(message) {
741
+ if (typeof message !== 'string') return null;
742
+ for (const line of message.split('\n')) {
743
+ const m = /^CI-(?:Grant|Cure):.*\bover-red \S*@([0-9a-f]{7,40})\b/.exec(line.trim());
744
+ if (m) return m[1];
745
+ }
746
+ return null;
747
+ }
748
+
749
+ /**
750
+ * The red-job SET at one trunk sha (#477), from the raw job rows of every not-green run there —
751
+ * the same selection `shapeJobEvidence` makes (an incomplete job → `null`, unmeasurable), reduced
752
+ * to `{name, workflowName}` identities.
753
+ */
754
+ function redJobSet(redRunJobs) {
755
+ const shaped = shapeJobEvidence({ redRunJobs, branchRunJobs: [] });
756
+ if (!shaped) return null;
757
+ return shaped.redJobs.map((j) => ({ name: j.name, workflowName: j.workflowName }));
758
+ }
759
+
760
+ /**
761
+ * Progress past condition 3 (#477) — PURE. `prior` is the red-job set at the red sha the most recent
762
+ * exemption on this continuous red was measured against; `current` the red-job set at trunk's red
763
+ * sha now (the `redJobs` of `shapeJobEvidence`). Jobs are compared by `jobKey` — workflow AND name,
764
+ * the same identity 2b matches on.
765
+ *
766
+ * ok only when `current` is a STRICT subset of `prior`: every job red now was already red then, and
767
+ * at least one job red then is not red now. An equal set is no progress (the prior exemption fixed
768
+ * nothing that stayed fixed); a job red now that was not red then is a NEW failure and refuses even
769
+ * if another job was repaired — admitting it would let a chain of cures trade one red for another
770
+ * forever. Either set unmeasured (`null`, non-array) or empty refuses: an empty `prior` cannot have
771
+ * been the basis of an exemption, and an empty `current` on a red trunk is unmeasurable (same
772
+ * posture as 2b).
773
+ */
774
+ function redSetShrank(prior, current) {
775
+ if (!Array.isArray(prior) || !Array.isArray(current)) {
776
+ return { ok: false, reason: 'the red-job set at the prior exemption\'s red sha could not be measured' };
777
+ }
778
+ if (!prior.length || !current.length) {
779
+ return { ok: false, reason: 'a red-job set to compare was empty — an unmeasurable red set is never progress' };
780
+ }
781
+ const before = new Map(prior.map((j) => [jobKey(j), j]));
782
+ const now = new Map(current.map((j) => [jobKey(j), j]));
783
+ const added = [...now.keys()].filter((k) => !before.has(k)).map((k) => jobLabel(now.get(k)));
784
+ const healed = [...before.keys()].filter((k) => !now.has(k)).map((k) => jobLabel(before.get(k)));
785
+ const still = [...now.values()].map(jobLabel);
786
+ if (added.length) {
787
+ return { ok: false, added, healed, still,
788
+ reason: `trunk's red set did not shrink: ${added.map((n) => `\`${n}\``).join(', ')} is red now and was not at the prior exemption's red sha — a new failure is not progress` };
789
+ }
790
+ if (!healed.length) {
791
+ return { ok: false, added, healed, still,
792
+ reason: `trunk's red set is unchanged since the prior exemption (${still.map((n) => `\`${n}\``).join(', ')}) — no progress` };
793
+ }
794
+ return { ok: true, added, healed, still,
795
+ reason: `trunk's red set shrank since the prior exemption: ${healed.map((n) => `\`${n}\``).join(', ')} healed, ` +
796
+ `${still.map((n) => `\`${n}\``).join(', ')} still red` };
797
+ }
798
+
799
+ /**
800
+ * Condition 3 as `cureVerdict` applies it (#477): the caller's `stacking` verdict, widened ONLY on
801
+ * its stacked refusal (`stacking.stacked`, set by ci-grant.js's stackingVerdict) and only by
802
+ * measured progress. Returns `{ok, reason, progress}` — `progress` is the `redSetShrank` result
803
+ * whenever it was consulted, so the success path can carry it into the trailer.
804
+ */
805
+ function stackingWithProgress(stacking, priorRedJobs, jobEvidence) {
806
+ if (stacking && stacking.ok) return { ok: true, reason: '', progress: null };
807
+ const base = (stacking && stacking.reason) || 'anti-stacking verdict unavailable';
808
+ if (!stacking || !stacking.stacked) return { ok: false, reason: base, progress: null };
809
+ const current = jobEvidence && Array.isArray(jobEvidence.redJobs) ? jobEvidence.redJobs : null;
810
+ const progress = redSetShrank(priorRedJobs, current);
811
+ if (!progress.ok) {
812
+ return { ok: false, progress, reason: `${base} The progress admission (#477) does not admit it either: ${progress.reason}` };
813
+ }
814
+ return { ok: true, reason: '', progress };
815
+ }
816
+
405
817
  /**
406
818
  * The cure verdict for one branch's attempt to ship into a red trunk.
407
819
  *
@@ -418,7 +830,11 @@ function workflowCarveOut(jobEvidence) {
418
830
  * (the caller already used it to compute `containsRedSha` and `evidence`).
419
831
  *
420
832
  * `stacking` — `{ok, reason}`, the caller's `ciGrant.stackingVerdict(...)` result, reused
421
- * verbatim (condition 3) — this module never recomputes it.
833
+ * verbatim (condition 3) — this module never recomputes it. Its stacked refusal carries
834
+ * `stacked: true`; only that refusal can be lifted, by progress (#477).
835
+ *
836
+ * `priorRedJobs` (#477) — `redJobSet(...)` at the red sha the prior exemption named in its trailer,
837
+ * or `null` when unmeasured. Consulted only on a stacked refusal; compared with `jobEvidence.redJobs`.
422
838
  *
423
839
  * `workflowsTouched` — bool, whether the branch's diff against trunk touches any path under
424
840
  * `.github/workflows/` (condition 4 — tools/lib/cure-diff.js, `--no-renames`). `null` means the
@@ -429,10 +845,23 @@ function workflowCarveOut(jobEvidence) {
429
845
  * which refuses: a caller that did not measure it has not shown the instrument is intact.
430
846
  * `manifestPaths` — the manifests whose scripts changed, named in the refusal.
431
847
  *
848
+ * `manifestScriptsAddOnly` (#475) — cure-diff's classifier: `[{path, added}]` when every touched
849
+ * manifest's scripts change is add-only, anything else (null/undefined) when not. Only consulted when
850
+ * `manifestScriptsTouched` is true; a caller that does not pass it gets the pre-#475 refusal.
851
+ *
432
852
  * `pythonManifestTouched` — bool, whether the diff changes a Python dependency manifest the Python
433
853
  * template installs from (condition 6, #377). `null`/`undefined` = unmeasured, which refuses.
434
854
  * `pythonManifestPaths` — those files, named in the refusal.
435
855
  *
856
+ * `pythonPinOnly` (#476) — cure-diff's classifier: `[{path, pins}]` when every touched Python
857
+ * manifest changed only version specifiers. Same posture as `manifestScriptsAddOnly`.
858
+ *
859
+ * `dispatchable` / `branchRuns` (#510) — the branch workflows a plain workflow_dispatch can run (by
860
+ * name), and the run-level rows at the branch head (`{workflowName, workflowId, event, status,
861
+ * conclusion}`). Read only on a 2b refusal, by `cureDispatchPlan`, to set `dispatchWanted`; a caller that
862
+ * passes neither gets the pre-#510 refusal unchanged. A cure proven by a dispatch instance returns
863
+ * `dispatch: {jobs}`, the same way a dry-run-proven one returns `dryRun`.
864
+ *
436
865
  * `jobEvidence` — `shapeJobEvidence(...)`'s output, or `null`. Read on EVERY cure since #297 —
437
866
  * condition 2b (`redJobsProvenOnBranch`) — and again by the #321 carve-out when workflows were
438
867
  * touched. `null`, an empty `redJobs`, an empty `branchJobs`, an unreadable step list and an
@@ -448,12 +877,16 @@ function workflowCarveOut(jobEvidence) {
448
877
  * branch touching both — exactly the "two instrument paths, two doors" composition #321 asked for.
449
878
  *
450
879
  * Returns `{ok, reason}`; on success also `provenJobs` (the red job names 2b proved, additive,
451
- * #297) and — ONLY on a cure that went through the carve-out — `carveOut: {jobs}`. The ordinary
880
+ * #297), `admitted` (#475/#476 — `{scripts: [{path, added}], pins: [{path, pins}]}`, present only
881
+ * when a manifest admission was used), `progress` (#477 — `{healed, still}`, present only when condition 3
882
+ * was passed by progress past a prior exemption) and — ONLY on a cure that went through the carve-out —
883
+ * `carveOut: {jobs}`. The ordinary
452
884
  * cure's reason text is unchanged, which is what lets the caller answer "which door was this?" by
453
885
  * the presence of `carveOut` rather than by re-deriving it.
454
886
  */
455
887
  function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouched, jobEvidence,
456
- manifestScriptsTouched, manifestPaths, pythonManifestTouched, pythonManifestPaths }) {
888
+ manifestScriptsTouched, manifestPaths, manifestScriptsAddOnly, pythonManifestTouched, pythonManifestPaths,
889
+ pythonPinOnly, dryRunCapable, dispatchable, branchRuns, priorRedJobs }) {
457
890
  if (!containsRedSha) {
458
891
  return { ok: false,
459
892
  reason: `branch does not contain trunk's current red head \`${redSha}\` as an ancestor — ` +
@@ -472,41 +905,99 @@ function cureVerdict({ containsRedSha, evidence, redSha, stacking, workflowsTouc
472
905
  'a bystander\'s PR runs against a merge ref that includes the red trunk, so it waits for green instead (#353)' };
473
906
  }
474
907
  const proven = redJobsProvenOnBranch(jobEvidence);
908
+ const cond3 = stackingWithProgress(stacking, priorRedJobs, jobEvidence);
475
909
  if (!proven.ok) {
476
- return { ok: false,
910
+ const out = { ok: false,
477
911
  reason: `branch's run is green, but the check trunk is red on is not proven here: ${proven.reason} — ` +
478
912
  'a cure must pass the named failing job(s), not merely produce a green run (#297)' };
913
+ // #474: say which dry run would supply the missing evidence — only when every LATER condition
914
+ // already holds, so a dispatch is never asked for on a branch that would refuse anyway.
915
+ // #510: and which plain workflow_dispatch would supply a job a branch push skipped.
916
+ const plan = cureDispatchPlan(jobEvidence, { dryRunCapable, dispatchable, branchRuns });
917
+ // An admissible manifest change (#475/#476) does not suppress the ask: the admission is judged on
918
+ // the dry run's steps once it exists, exactly like any other branch instance.
919
+ const scriptsOk = manifestScriptsTouched === false
920
+ || (manifestScriptsTouched === true && Array.isArray(manifestScriptsAddOnly) && manifestScriptsAddOnly.length > 0);
921
+ const pythonOk = pythonManifestTouched === false
922
+ || (pythonManifestTouched === true && Array.isArray(pythonPinOnly) && pythonPinOnly.length > 0);
923
+ if (cond3.ok && scriptsOk && pythonOk && typeof workflowsTouched === 'boolean') {
924
+ if (plan.dryRun.length) out.dryRunWanted = plan.dryRun;
925
+ if (plan.dispatch.length) out.dispatchWanted = plan.dispatch;
926
+ }
927
+ return out;
479
928
  }
480
- if (!stacking || !stacking.ok) {
481
- return { ok: false, reason: (stacking && stacking.reason) || 'anti-stacking verdict unavailable' };
929
+ const dry = proven.dryRunJobs && proven.dryRunJobs.length ? { jobs: proven.dryRunJobs } : null;
930
+ const disp = proven.dispatchJobs && proven.dispatchJobs.length ? { jobs: proven.dispatchJobs } : null;
931
+ const drySuffix = (dry ? ` — the main-only job(s) ${dry.jobs.map((n) => `\`${n}\``).join(', ')} proven by a dry run on the branch (#474)` : '')
932
+ + (disp ? ` — the trunk-only job(s) ${disp.jobs.map((n) => `\`${n}\``).join(', ')} proven by a workflow_dispatch run at the branch head (#510)` : '');
933
+ if (!cond3.ok) {
934
+ return { ok: false, reason: cond3.reason };
482
935
  }
936
+ const prog = cond3.progress ? { progress: { healed: cond3.progress.healed, still: cond3.progress.still } } : {};
937
+ const progSuffix = cond3.progress ? `; past a prior exemption on this red because ${cond3.progress.reason} (#477)` : '';
483
938
  if (typeof workflowsTouched !== 'boolean' || typeof manifestScriptsTouched !== 'boolean'
484
939
  || typeof pythonManifestTouched !== 'boolean') {
485
940
  return { ok: false,
486
941
  reason: 'branch diff could not be measured (which CI files and manifests it touches) — an unmeasured diff is never a cure' };
487
942
  }
943
+ const admitted = {};
488
944
  if (manifestScriptsTouched) {
489
945
  const named = Array.isArray(manifestPaths) && manifestPaths.length ? manifestPaths.join(', ') : 'package.json';
490
- return { ok: false, reason: `${MANIFEST_SCRIPTS_REFUSAL} (changed: ${named})` };
946
+ if (!Array.isArray(manifestScriptsAddOnly) || !manifestScriptsAddOnly.length) {
947
+ return { ok: false, reason: `${MANIFEST_SCRIPTS_REFUSAL} (changed: ${named}; not add-only — a script removed, renamed, ` +
948
+ 'changed, or a lifecycle hook added)' };
949
+ }
950
+ const proof = manifestStepProof(jobEvidence);
951
+ if (!proof.ok) {
952
+ return { ok: false, reason: `${MANIFEST_SCRIPTS_REFUSAL} (changed: ${named}). The add-only admission (#475) does not ` +
953
+ `admit it either: ${proof.reason}` };
954
+ }
955
+ admitted.scripts = manifestScriptsAddOnly;
491
956
  }
492
957
  if (pythonManifestTouched) {
493
958
  const named = Array.isArray(pythonManifestPaths) && pythonManifestPaths.length
494
959
  ? pythonManifestPaths.join(', ') : 'a Python dependency manifest';
495
- return { ok: false, reason: `${PYTHON_MANIFEST_REFUSAL} (changed: ${named})` };
960
+ if (!Array.isArray(pythonPinOnly) || !pythonPinOnly.length) {
961
+ return { ok: false, reason: `${PYTHON_MANIFEST_REFUSAL} (changed: ${named}; not pin-only — a requirement, extra, ` +
962
+ 'marker, include or option changed, or the file is setup.py/setup.cfg)' };
963
+ }
964
+ const proof = manifestStepProof(jobEvidence, { noLateSkip: true });
965
+ if (!proof.ok) {
966
+ return { ok: false, reason: `${PYTHON_MANIFEST_REFUSAL} (changed: ${named}). The pin-only admission (#476) does not ` +
967
+ `admit it either: ${proof.reason}` };
968
+ }
969
+ admitted.pins = pythonPinOnly;
496
970
  }
971
+ const via = admittedText(admitted);
497
972
  if (workflowsTouched) {
498
973
  const carve = workflowCarveOut(jobEvidence);
499
974
  if (!carve.ok) {
500
975
  return { ok: false, reason: `${WORKFLOW_REFUSAL}. The #321 carve-out does not admit it either: ${carve.reason}` };
501
976
  }
502
977
  const detail = carve.jobs.map((j) => `\`${j.name}\` (${j.redMs}ms red on trunk, ${j.branchMs}ms passing here)`).join(', ');
503
- return { ok: true, provenJobs: proven.jobs, carveOut: { jobs: carve.jobs },
978
+ return { ok: true, provenJobs: proven.jobs, carveOut: { jobs: carve.jobs }, ...(dry ? { dryRun: dry } : {}), ...(disp ? { dispatch: disp } : {}),
979
+ ...(via ? { admitted } : {}), ...prog,
504
980
  reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure, ` +
505
- `admitted through the #321 workflow carve-out: every job red on trunk ran to success here with every step it took on trunk — ${detail}` };
981
+ `admitted through the #321 workflow carve-out: every job red on trunk ran to success here with every step it took on trunk — ${detail}${drySuffix}${via}${progSuffix}` };
982
+ }
983
+ return { ok: true, provenJobs: proven.jobs, ...(dry ? { dryRun: dry } : {}), ...(disp ? { dispatch: disp } : {}),
984
+ ...(via ? { admitted } : {}), ...prog,
985
+ reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure${drySuffix}${via}${progSuffix}` };
986
+ }
987
+
988
+ /** The reason-text suffix naming which manifest admission(s) a cure used (#475/#476), or ''. */
989
+ function admittedText(admitted) {
990
+ const parts = [];
991
+ if (admitted.scripts) {
992
+ parts.push(`add-only package.json scripts (${admitted.scripts.map((a) => `${a.path}: ${a.added.join(',')}`).join('; ')})`);
993
+ }
994
+ if (admitted.pins) {
995
+ parts.push(`pin-only Python requirements (${admitted.pins.map((a) => `${a.path}: ${a.pins.join(',')}`).join('; ')})`);
506
996
  }
507
- return { ok: true, provenJobs: proven.jobs,
508
- reason: `branch contains red \`${redSha}\` as an ancestor AND is green at its own current head (\`${evidence.sha}\`) — proven cure` };
997
+ return parts.length ? `; manifest change admitted as ${parts.join(' and ')}, every step trunk ran passing here` : '';
509
998
  }
510
999
 
511
- module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, shapeJobEvidence, WORKFLOW_REFUSAL, MANIFEST_SCRIPTS_REFUSAL,
512
- PYTHON_MANIFEST_REFUSAL };
1000
+ module.exports = { cureVerdict, redJobsProvenOnBranch, workflowCarveOut, manifestStepProof, shapeJobEvidence, dryRunDispatchPlan,
1001
+ cureDispatchPlan, dispatchEvidence,
1002
+ priorRedShaFromMessage, redJobSet, redSetShrank,
1003
+ WORKFLOW_REFUSAL, MANIFEST_SCRIPTS_REFUSAL, PYTHON_MANIFEST_REFUSAL, PUBLISH_STEP_MARKER, DRY_RUN_STEP };