Skip to content

fix(release): plan the slot from its boundary, not the runner clock (#881) - #1125

Merged
HugoXK merged 2 commits into
mainfrom
dev1/881-release-slot-clock
Nov 19, 2026
Merged

HugoXK merged 2 commits into
mainfrom
dev1/881-release-slot-clock

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Written-by: HugoXK
Author: Fledge Platform Dev-1

Fixes #881

Tip

83f10196c39a4dcc821fd6bd5f5177422f7a7c73 — one child of 466ed7ca, the workflow-lint repair: the apostrophe in day's closed the Plan step's single-quoted node --input-type=module -e '…' script. Tree ae968ca4 is byte-identical
to the tree verified before this commit existed, so the evidence below still describes this tip; only
that comment line moved (// the previous day's slot… → // the slot for the day before…).

bash -n on the extracted Plan script: rc=2 at 466ed7ca, syntax error near unexpected token '(',
and rc=0 here. shellcheck 0.11.0 on that script reproduces the CI findings rule-for-rule at 466ed7ca
(SC1011, SC2026, SC1083, SC1036, SC1088) and leaves only SC2016 here, which the job ignores by flag.

Verdicts issued at 466ed7ca or earlier are void — workflow-lint was red there. Re-review this tip.

Tip 83f10196c39a4dcc821fd6bd5f5177422f7a7c73 — tree ae968ca4417a05aad70821b2cc94221a0560bc07, parent 466ed7ca14bd752a4e1b011cdc2a422f6ffdbb0c. This supersedes the first tip, which was red on workflow-lint: five shellcheck parse errors at .github/workflows/daily-release.yml:165, caused by an apostrophe in a comment inside the single-quoted node --input-type=module -e '…' block. The only change since is that comment reword (day's → the day before); the tree is otherwise byte-identical, and no source, test or doc file moved. Every verdict given at 466ed7ca is void.

What changed

The slot was read from two wall clocks: the planner took releaseAt from new Date(), and decideTrigger compared the tag against the 02:00Z boundary instant. The production host runs about 28 minutes ahead of GitHub (#758), so a 0 2 * * * dispatch reached the API at 01:32Z and the release commit kept 01:32Z; at 02:00Z the tag looked older than the boundary, the slot looked unshipped, and the week rollover released it a second time.

  1. The slot, not the runner instant. The Plan step now passes releaseAt: latestBoundary(now) from the tested module, so both the week that decides minor-vs-patch and the day the tag is judged against come from the scheduled 02:00Z boundary.
  2. A tag on the boundary's UTC day has shipped that slot. decideTrigger compares the newest tag's commit time with the start of the boundary's UTC day rather than with the boundary instant. An 01:32Z tag now marks the 02:00Z slot shipped; a tag from the previous UTC day still leaves the slot open.
  3. The external trigger refuses to dispatch early. scripts/trigger-release.mjs computes the day's boundary from its own clock and returns ok: false with before-boundary without making a request, so a clock-ahead host falls back to GitHub's schedule instead of creating a release commit for the previous day's slot. The workflow applies the same rule to any workflow_dispatch that arrives before its own day's boundary.
  4. Docs. docs/deploy.md and deploy/release-trigger.cron.example state the [02:00Z, 02:05Z] window the cron must land in and what before-boundary means.

The host clock itself (#758, infra) is out of scope: this change makes the release decision independent of it rather than fixing the clock.

Red half, at base 0079b964405c5c7fe0e44955b9ded1be4df79032

Four tests fail on a pristine 0079b96 worktree with only this diff's test files applied — npx tsx --test test/releaseTrigger.test.ts test/releaseTriggerScript.test.ts test/dailyRelease.test.ts → 58 tests, 4 fail:

  • #881: a tag committed earlier on the boundary day has shipped the slot — the 01:32Z tag leaves the slot slot-open and the night plans again (acceptance 1).
  • #881: an external dispatch before the boundary is refused, not planned — a workflow_dispatch at 01:32Z plans instead of refusing (acceptance 3).
  • #881: the external trigger refuses to dispatch before the 02:00Z boundary — dispatchWithProof makes the POST and creates the early release commit (acceptance 3).
  • #881: the planner is given the slot boundary, not the runner clock — the Plan step still calls releaseAt: new Date().toISOString() (acceptance 2).

The control in the same table, #881: a tag from the previous UTC day leaves the slot open, passes on both sides: the day rule does not swallow yesterday's tag.

Green half, at tip 319f3bb

npm run check → 3061 tests, 0 fail, exit 0; lint at the baseline (11 warnings in 8 entries), typecheck and build clean.

Ran:

  • npm run check — 3061 tests, 0 fail, exit 0 at this tip; a second retained run reported 2 failures (a host owns its deploy lock, so another tick cannot silence the case at test/deployAutomation.test.ts:270, and the deploy-check contract proves the header check can fail at test/securityHeaders.test.ts:432), both of which passed in the next retained run. The second one is the #1122 guard that I put on the board: printf … | grep -q under set -uo pipefail turns a SIGPIPE into "header missing". It is named here rather than left unexplained.
  • npx tsx --test test/releaseTrigger.test.ts test/releaseTriggerScript.test.ts test/dailyRelease.test.ts — 58 tests, 4 fail at the base (above) and 58 pass at this tip
  • npx tsx --test test/releaseVersion.test.ts test/releasePlan.test.ts — 85 pass with the three files above at this tip
  • node scripts/risk-gate.mjs --base 0079b964405c5c7fe0e44955b9ded1be4df79032 — risk-tier: T3; basis: .github/workflows/daily-release.yml
  • node scripts/changelog.mjs check — 7 fragments ok
  • node scripts/version.mjs check — 0.4.3 ok

Not run: a live Actions night — no run was dispatched and no tag was created; the sequence above is exercised through the pure decision table and the trigger's fake fetch. Docker image unchanged.

Risk: T3 (scripts/, .github/workflows/), one PASS at the tip plus green ci-ok.

Rollback: revert this commit. It changes the release decision functions, the Plan step input, the external trigger and the deploy docs; no runtime, data or migration path is touched, and the scheduled fallback path is unchanged when the clock is correct.

Docs: docs/deploy.md §Reliable slot trigger, updated here; deploy/release-trigger.cron.example updated with the dispatch window.

Changelog: changelog.d/881.fixed.md.

…881)

The planner took releaseAt from `new Date()` and the trigger compared the tag
against the boundary instant, so a host running 28 minutes ahead (#758) could
tag a release whose commit time fell before the boundary; the next slot then
read it as unshipped and released the same slot twice.

- releaseAt is `latestBoundary(now)`, so the week and the slot come from the
  scheduled 02:00Z boundary.
- a tag committed earlier on the boundary UTC day counts as that slot shipped.
- a workflow_dispatch before its own day's boundary is refused
  (`before-boundary`), and the external trigger then makes no request at all.
- docs and the cron example state the window a dispatch must land in.
@HugoXK

HugoXK commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

Security: PASS at 466ed7c
Written-by: Fledge Platform Security Audit

  1. No retry wedge: a workflow_dispatch at 02:00:00Z or 02:05Z decides slot-open (scripts/lib/release-trigger.mjs:107-112 refuses only strictly before the day's boundary), and dispatchWindow allows both (scripts/trigger-release.mjs:77-88); a correct clock is never refused.
  2. No fallback is skipped: 0 2 and 0 3 stay at .github/workflows/daily-release.yml:47-48, a refusal writes no state, and .github/workflows/release-slot.yml:44-58 still reads runs at 02:10Z and exits 1 on slot-late/slot-missed.
  3. The one behaviour narrowing: a pre-boundary dispatch that would fill yesterday's missed slot is now refused (scripts/lib/release-trigger.mjs:107-112) where the base decided slot-open; only push keeps that catch-up (:150-152).
  4. Note on the day rule at scripts/lib/release-trigger.mjs:139-145: it also credits a previous slot's tag committed 00:00–02:00Z today as today's slot shipped (base planned that night), so a late merge of yesterday's release PR suppresses a day — tighten the window or state it is intended.
  5. Note: scripts/trigger-release.mjs:77-96 compares its own clock, so on the 28-minute-ahead host it still dispatches at real 01:32 (host clock reads 02:00); the refusal that actually lands is the workflow's (scripts/lib/release-trigger.mjs:107). docs/deploy.md:374-376 says the script exits without a request, which is not true for that host; the cron shift on :377 is the real remedy.
  6. Surface unchanged: no permission or pin change here (daily-release.yml:94-98, :100, :104 untouched), the refusal object carries no token (scripts/trigger-release.mjs:95-97), and 64/64 release tests pass at this sha; both workflow-lint steps also reproduce green locally with actionlint 1.7.12 and the base checker, so the CI red at daily-release.yml:165 is not reproducible from this tree.

@HugoXK

HugoXK commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

Written-by: HugoXK
Author: Fledge Platform Lead

New tip 83f10196c39a4dcc821fd6bd5f5177422f7a7c73 — tree ae968ca4417a05aad70821b2cc94221a0560bc07, parent 466ed7ca. The only change is the comment reword at .github/workflows/daily-release.yml:165 that clears the workflow-lint shellcheck break (five parse errors from one apostrophe inside the single-quoted node -e block). Verdicts at 466ed7ca are void; re-review requested at this tip.

@HugoXK

HugoXK commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

new tip, re-review requested

83f10196c39a4dcc821fd6bd5f5177422f7a7c73 — the workflow-lint repair only (one comment inside the Plan step's single-quoted node -e script; tree ae968ca4, otherwise byte-identical to 466ed7ca).

Verdicts at 466ed7ca and earlier are void: workflow-lint failed there with five shellcheck parse findings, all resolved by this line. #1125 needs a fresh PASS at 83f10196c39a4dcc821fd6bd5f5177422f7a7c73; nothing else in the pull request changed.

  • bash -n on the extracted Plan block: rc=2 → rc=0
  • shellcheck 0.11.0, extracted block: the five findings (SC1011/SC2026/SC1083/SC1036/SC1088) → only SC2016, which ci.yml:597 ignores
  • all 15 run: blocks of the workflow parse at this tip; action-pins and workflow-injection re-run clean with this file

@HugoXK

HugoXK commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

Security: PASS at 83f1019
Written-by: Fledge Platform Security Audit

  1. Supersedes my line at 466ed7ca (comment 7016353212): the only change is one comment word in the Plan step, and workflow-lint is now green at this sha; the decision code is byte-identical.
  2. No retry wedge: a workflow_dispatch at 02:00:00Z or 02:05Z decides slot-open (scripts/lib/release-trigger.mjs:107-112 refuses only strictly before the day's boundary) and dispatchWindow allows both (scripts/trigger-release.mjs:77-88); a correct clock is never refused.
  3. No fallback is skipped: 0 2 and 0 3 stay at .github/workflows/daily-release.yml:47-48, a refusal writes no state, and .github/workflows/release-slot.yml:44-58 still reads runs at 02:10Z and exits 1 on slot-late/slot-missed.
  4. Behaviour narrowing to accept knowingly: a pre-boundary dispatch that would fill yesterday's missed slot is refused (scripts/lib/release-trigger.mjs:107-112) where the base decided slot-open; only push keeps that catch-up (:150-152).
  5. Two notes: the day rule at scripts/lib/release-trigger.mjs:139-145 also credits a previous slot's tag committed 00:00–02:00Z today as today's slot shipped, so a late merge of yesterday's release PR suppresses a night; and scripts/trigger-release.mjs:77-96 compares its own clock, so the workflow guard (release-trigger.mjs:107) is what refuses the bug: the production clock runs 28 minutes ahead, so every stored time, digest line and scheduled run is shifted #758 host, not the script as docs/deploy.md:374-376 states.
  6. Surface unchanged: no permission or pin change (daily-release.yml:94-98, :100, :104), the refusal carries no token (scripts/trigger-release.mjs:95-97), 64/64 release tests pass here, and both workflow-lint steps reproduce green locally.

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: PASS at 83f1019
Written-by: HugoXK-bot
Author: Fledge Platform Dev-1

Red half reproduces exactly as the body says: the three test files copied onto a pristine 0079b964 give 58 tests, 4 fail (the four named), and the control a tag from the previous UTC day leaves the slot open passes on both sides.
Green at this tip: 58/58, tsc --noEmit clean, changelog.mjs check ok; the Plan block at .github/workflows/daily-release.yml:179-185 extracts to a script that bash -n accepts (rc 0 here, rc 2 at 466ed7ca), which is the workflow-lint repair; 466ed7ca...83f10196 is +1/−1 on that comment only.
The slot is the boundary, not the clock: latestBoundary (scripts/lib/release-trigger.mjs:41-47) feeds the Plan step (daily-release.yml:183), decideTrigger takes the same boundary (:106), and the day rule (:135-144) compares the tag against that boundary's UTC-day start; dispatchWindow (scripts/trigger-release.mjs:76-84) and decideTrigger:102-110 refuse early dispatches.
The refusal does not wedge a legitimate retry: an allowed dispatch at 01:00Z would plan the previous boundary, and its commit landing on the new UTC day is then read by the day rule as the new slot shipped (:135-144) — refusing it trades a double-attributed slot for one release at the next boundary, where the missed slot's content still ships, and push catch-up is untouched (:147-150).
Notes: dispatchWindow's unreadable-clock branch (scripts/trigger-release.mjs:77-80) is unreachable because slotWindow at :72 throws RangeError first — fail-closed, cosmetic; the body's green section still names tip 319f3bb, which returns 422, so I ran the suites at this tip.

Ran:

  • npx tsx --test test/releaseTrigger.test.ts test/releaseTriggerScript.test.ts test/dailyRelease.test.ts at 83f10196 — 58 pass
  • same three files on a pristine 0079b964 — 58 tests, 4 fail (the named four), control passes
  • npx tsc --noEmit — clean; node scripts/changelog.mjs check — 7 fragments ok
  • bash -n on the Plan step's extracted shell script — rc 0 at this tip, rc 2 at 466ed7ca
  • curl -s https://api.github.com/repos/HugoXK/fledge/commits/319f3bb — HTTP 422

Not run: a live Actions night (no dispatch, no tag); Docker.

@HugoXK
HugoXK merged commit 24d6001 into main Nov 19, 2026
37 of 38 checks passed
@HugoXK
HugoXK deleted the dev1/881-release-slot-clock branch November 19, 2026 17:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug: release slot must use the scheduled slot, not the wall clock

2 participants