Skip to content

refactor(update): make the still-latest verdict a pure function a quiet feed read can share - #17495

Closed
chenmingwei23 wants to merge 1 commit into
kirodotdev:mainfrom
chenmingwei23:fix/10333-still-latest-pure
Closed

chenmingwei23 wants to merge 1 commit into
kirodotdev:mainfrom
chenmingwei23:fix/10333-still-latest-pure

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

What broke / why

runtime/update/feed-lane.js answers one question — is the staged build still
the newest thing the followed channel serves?
— but it answered it inline in the
update-available / update-not-available handlers, in branches that also
mutated staged state and emitted renderer events. The three parts of the verdict
(direction gate, supersede/already-staged, retraction) were tangled with their
side effects, so the only way to ask the question was to run the stateful
autoUpdater.checkForUpdates() pipeline and suppress every effect it produced.
A caller that must not touch state — a quiet feed read for a freshness gate — had
no way to share the verdict.

What changed

  • New pure function runtime/update/still-latest.js →
    classifyFeedVerdict({ stagedVersion, candidate, followedChannel, runningVersion, defaultChannel, shouldAutoOffer }). It returns a tagged
    verdict — offer / suppress / still-latest / superseded / retracted /
    up-to-date — with no I/O, no mutation, no emit. candidate === null is
    the feed's "nothing newer" answer (update-not-available). The direction gate
    (shouldAutoOffer, the downgrade-nag suppressor) is passed in, not
    duplicated, so the one copy of that rule stays the one copy.
  • feed-lane.js maps the verdict onto its state transitions via a small
    feedVerdict() closure that only gathers the four facts from live lane state.
    The update-available handler switches on suppress / still-latest /
    superseded; the update-not-available handler uses the shared verdict
    (candidate = null) for the retraction decision. Behaviour is unchanged,
    including the feedChannel-vs-live-read channel pairing (the mid-check
    preference-flip TOCTOU guard) and the stage cleanup on a suppressed downgrade.
  • Side-effect-free consumer hook: the lane handle now exposes
    stillLatest(candidate), a query that returns the same verdict the live
    handlers act on, so a quiet feed read can share it without driving the real
    update lifecycle.

Why this scope (code on main, not the issue's verifyStageIsLatest)

The issue describes machinery — verifyStageIsLatest() and the abandonedCheck
/ verifyQuiet / inFlightCheckError / preparingDownload suppression flags —
that was introduced by the still-unmerged #9367 and never landed on main.
The update lifecycle was instead reorganised into website/electron/runtime/update/
(#14569), with the still-latest verdict living inline in feed-lane.js. This PR
factors that inline verdict out into the pure function the issue asks for, so the
quiet feed read has a function to call — the same architectural goal, against the
code that is actually on main.

Relation to #10282

The sibling #10282 (replace the boolean lattice with an explicit phase enum) has
no open PR yet. This change does not edit the boolean-lattice declarations that
refactor will touch; it adds a pure verdict function and routes the handlers
through it.

Tested

  • New unit tests for classifyFeedVerdict (test/still-latest.test.js), using
    the real shouldAutoOffer so the direction gate is exercised, not a
    stand-in.
  • The full website/electron node:test suite passes: 2444 pass / 0 fail /
    4 skipped
    (npm test, the command CI's Electron Shell Tests job runs).
  • The runtime-module load-time-effects contract and the lane-handle-shape
    contract in auto-update.test.js were updated to admit the new pure helper and
    the new handle key.

Fixes #10333

The still-latest question -- "is the staged build still the newest thing the
followed channel serves?" -- was spread across the update-available /
update-not-available handlers in runtime/update/feed-lane.js as inline branches
that also mutated staged state and emitted renderer events (direction gate,
supersede/already-staged, retraction). That meant the only way to ask the
question was to run the stateful autoUpdater.checkForUpdates() pipeline and
suppress every side effect it produced; nothing that must NOT touch state could
consult the verdict.

Extract the decision into a pure function, runtime/update/still-latest.js:
classifyFeedVerdict({ stagedVersion, candidate, followedChannel, runningVersion,
defaultChannel, shouldAutoOffer }) returns a tagged verdict (offer / suppress /
still-latest / superseded / retracted / up-to-date) with no I/O, no mutation and
no emit. candidate === null is the feed's "nothing newer" answer. The direction
gate (shouldAutoOffer) is PASSED IN, not duplicated, so the one copy of that rule
stays the one copy.

The feed-lane handlers now MAP the verdict onto their state transitions and
events via a small feedVerdict() closure that only gathers the four facts from
live lane state -- behaviour is unchanged, including the feedChannel-vs-live-read
channel pairing and the stage-cleanup on a suppressed downgrade. The lane handle
also exposes stillLatest(candidate): a side-effect-free query that returns the
same verdict the live handlers act on, so a quiet feed read can share it without
driving the real update lifecycle.

Context: the machinery the issue describes (verifyStageIsLatest and the
abandonedCheck / verifyQuiet / inFlightCheckError / preparingDownload suppression
flags) came from the still-unmerged kirodotdev#9367 and never landed; the update lifecycle
was reorganised into runtime/update/ (kirodotdev#14569) with the verdict inline in
feed-lane.js. This factors that inline verdict out so the quiet feed read the
issue asks for has a pure function to call.

Tested: new unit tests for classifyFeedVerdict (test/still-latest.test.js) using
the real shouldAutoOffer; the full website/electron node:test suite passes
(2444 pass / 0 fail / 4 skipped). The runtime-module load-time-effects contract
and the lane-handle-shape contract in auto-update.test.js were updated to admit
the new pure helper and the new handle key.

The sibling kirodotdev#10282 (phase-enum refactor) has no open PR yet; this change does not
edit the boolean-lattice declarations that refactor will touch.

Fixes kirodotdev#10333
@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 6, 2026 19:19
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 6, 2026
@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ✅ PASS

UX-level review of 6e7e05a416b723a5c48630c2a2a1f3fec9e3b829 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] 6e7e05a

Description read

[DESCRIPTION-READ] 3ef0ab2652fdd1e988edcefc2e6865845e377355184541fc1053ff69140f4663

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — 🟡 CONCERNS

Design-level review of 6e7e05a416b723a5c48630c2a2a1f3fec9e3b829 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

stillLatest is a new public lane-handle key with no caller, and its contract is only half-defined: the feed lane has it, the disabled stubs and managed lane don't.

Watch

  • Unused key that only some lanes return. The patch adds stillLatest: (candidate) => feedVerdict(candidate ?? null) to the feed lane only. The early-return stubs and createManagedLane in auto-update.js:1040-1137 return handles without it. So the first freshness gate to call handle.stillLatest(...) will throw TypeError on dev, externally-managed, unsupported-platform and wrong-bundle-location installs. Nothing in this PR exercises that path. handle-shape now pins the key for one lane only.
    Clears when: the key is dropped until a real consumer lands, or every handle returns it (or the facade documents it as optional) and a test covers a disabled lane.
  • Wrong channel for a quiet read. feedVerdict pairs the candidate with feedChannel || currentChannel(), which is the channel of the last live check. A quiet read made after the user changes channel preference would be matched against the old channel. That is the same mid-check TOCTOU problem the comment says this pairing guards against, and the gate would get a wrong suppress or offer. stillLatest(candidate) has no way to pass in the channel the quiet read actually used.
    Clears when: stillLatest accepts the channel the quiet read was made on, or the missing consumer is named as the remaining part of refactor(update): make the still-latest verdict a pure function a quiet feed read can share #10333 instead of "Fixes".

[DESIGN-REVIEWED] 6e7e05a

Description read

[DESCRIPTION-READ] bb3dd86c741efcc509f3095567268fd9473d593794f4b6bc5cae60ab42ca77ab

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 6e7e05a416b723a5c48630c2a2a1f3fec9e3b829 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 6e7e05a

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🔴 BLOCK

Premise-level review of 6e7e05a416b723a5c48630c2a2a1f3fec9e3b829 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: BLOCK

stillLatest(candidate) adds a lane-handle query that nothing calls; the quiet feed read it exists for isn't on main and isn't in this diff.

Not justified as shipped

  • Item 3 — zero consumers: the description says the handle "now exposes stillLatest(candidate) … so a quiet feed read can share it", but no such read exists on main or in this diff.
    Subtraction: delete stillLatest: (candidate) => feedVerdict(candidate ?? null) from the feed-lane.js return object, its @returns mention, and "stillLatest" from the handle-shape assertion in auto-update.test.js.
    Clears when: the key is deleted, or it lands in the same PR as the quiet-read caller that uses it.

What this change ships

Inventory (5 items) — 4 justified

Intent: give a side-effect-free feed read a way to ask whether the staged update is still the newest; an ADDITION framed as a refactor.

  1. The still-latest decision now lives in a pure classifyFeedVerdict in a new still-latest.js — justified
  2. The update-available / update-not-available handlers act on that verdict instead of inline branches — justified
  3. The feed lane's handle gains a stillLatest(candidate) query — zero consumers
  4. The packaged Electron file list includes still-latest.js — justified
  5. The load-time-effects test covers every runtime file, helpers included — justified

Blockers

stillLatest handle key has no caller
I searched website/ for stillLatest|still-latest|verifyStageIsLatest|quiet feed|freshness gate and got 0 hits on base. In the diff, the only reference outside the definition is the test's key-shape list. The disabled and managed lanes don't carry the key, so any future caller would need its own guard anyway. Without it, nobody is worse off.
Delete the handle key and its entry in the test's expected key list.
Clears when: the key is deleted, or a real caller lands alongside it.

[FIRST-PRINCIPLES-REVIEWED] 6e7e05a

Description read

[DESCRIPTION-READ] b319cf95d4fee89f2051299c3a6d5a7a3cdd7c288fe01066bb780032c04c8cd4

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 6e7e05a416b723a5c48630c2a2a1f3fec9e3b829 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6e7e05a

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 7, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Superseded by #17741; moved to a same-repo branch so CI runs on CodeBuild.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor(update): make the still-latest verdict a pure function a quiet feed read can share

1 participant