From 9abfa89d7dc23acbe5f2df1244860faa26422acb Mon Sep 17 00:00:00 2001 From: Raymond Yee Date: Sun, 10 May 2026 07:28:53 -0700 Subject: [PATCH 1/2] explorer: document loadRes-chase invariant on tryEnterPointModeIfNeeded (closes #194) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a load-bearing invariant block to the helper's doc comment plus a short pointer above the `!loading` short-circuit. Codifies the contract that every `loadRes` call site in the zoomWatcher cell must be followed by `await tryEnterPointModeIfNeeded()` (or be inside the helper itself, or in a path where the user can't be at point altitude). Without the chase, the helper's `!loading` bail-out can strand the user in cluster mode at point altitude — the exact bug round-3 of #191 fixed by adding the source-filter handler's chase call. Future contributors adding new `loadRes` sites need this invariant called out in the code, not buried in the PR thread. Doc-only change: no behavior change. Closes #194. Co-Authored-By: Claude Opus 4.7 (1M context) --- explorer.qmd | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/explorer.qmd b/explorer.qmd index 99b8c21..46f4534 100644 --- a/explorer.qmd +++ b/explorer.qmd @@ -1628,11 +1628,26 @@ zoomWatcher = { // long) `loadRes` await for the same reason: if the user zooms back out // or another path enters point mode during the wait, we must not force // entry afterwards. + // + // INVARIANT: every `loadRes` call site in this cell that could be in + // flight when the user crosses below `ENTER_POINT_ALT` MUST be followed + // by `await tryEnterPointModeIfNeeded()`. The `!loading` short-circuit + // below relies on this — when an unrelated `loadRes` is in flight we + // bail and leave recovery to that call site's own post-await chase. A + // new `loadRes` caller added without the chase would silently break + // supersession recovery and only surface as a rare liveness regression + // (see issue #194). Verify with: + // grep -nE "loadRes\(" explorer.qmd + // and check each match either lives inside `tryEnterPointModeIfNeeded` + // itself or is followed by a chase call. async function tryEnterPointModeIfNeeded() { if (mode === 'point') return; if (viewer.camera.positionCartographic.height >= ENTER_POINT_ALT) return; let res8Ready = currentRes === 8; + // See INVARIANT above: if an unrelated load is in flight, that + // call site is responsible for chasing with this helper when it + // settles. Don't second-guess it from here. if (!res8Ready && !loading) { res8Ready = await loadRes(8, h3_res8_url, { loadingMsg: 'Fetching sample index…', From b87cb49d4986abbbd437bfa2a6955cf03a08a061 Mon Sep 17 00:00:00 2001 From: Raymond Yee Date: Sun, 10 May 2026 07:33:46 -0700 Subject: [PATCH 2/2] explorer: tighten loadRes-chase invariant doc per Codex review - Switch verification grep from `loadRes\(` to `await[[:space:]]+loadRes\(` so it matches actual call sites (4 lines) instead of also matching the explanatory comments above the helper that mention `loadRes(...)` in prose. - Add "outside this helper" qualifier so the helper's own internal loadRes call is not visually flagged as an exception to the invariant. Doc-only refinement of #194 fix; no behavior change. --- explorer.qmd | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/explorer.qmd b/explorer.qmd index 46f4534..f6cbbce 100644 --- a/explorer.qmd +++ b/explorer.qmd @@ -1629,17 +1629,18 @@ zoomWatcher = { // or another path enters point mode during the wait, we must not force // entry afterwards. // - // INVARIANT: every `loadRes` call site in this cell that could be in - // flight when the user crosses below `ENTER_POINT_ALT` MUST be followed - // by `await tryEnterPointModeIfNeeded()`. The `!loading` short-circuit - // below relies on this — when an unrelated `loadRes` is in flight we - // bail and leave recovery to that call site's own post-await chase. A - // new `loadRes` caller added without the chase would silently break - // supersession recovery and only surface as a rare liveness regression - // (see issue #194). Verify with: - // grep -nE "loadRes\(" explorer.qmd - // and check each match either lives inside `tryEnterPointModeIfNeeded` - // itself or is followed by a chase call. + // INVARIANT: every `loadRes` call site in this cell *outside this + // helper* that could be in flight when the user crosses below + // `ENTER_POINT_ALT` MUST be followed by `await tryEnterPointModeIfNeeded()`. + // The `!loading` short-circuit below relies on this — when an unrelated + // `loadRes` is in flight we bail and leave recovery to that call site's + // own post-await chase. A new `loadRes` caller added without the chase + // would silently break supersession recovery and only surface as a rare + // liveness regression (see issue #194). Verify with: + // grep -nE "await[[:space:]]+loadRes\(" explorer.qmd + // which lists exactly the awaited call sites (one inside this helper, + // and one per external caller). For each external match, confirm it is + // immediately followed by `await tryEnterPointModeIfNeeded()`. async function tryEnterPointModeIfNeeded() { if (mode === 'point') return; if (viewer.camera.positionCartographic.height >= ENTER_POINT_ALT) return;