Follow up items for the week of August 15, 2026

[espg]

🤖 from Claude

Weekly sweep of PRs closed in englacial/zagg over the last 10 days (2026-08-05 through 2026-08-15): #421, #416, #412, #411, #403, #400, #397, #395, #391, #389, #380.

Two prior sweeps already exist for part of this window: #366 (week of Aug 1) and #409 (week of Aug 8). PRs #412, #416, #421, #400 postdate #409's window; items already covered by either sweep, or already tracked in a dedicated issue, are not repeated below — see "Already tracked / already resolved."

Follow-up items found

1. Flaky test: test_invoke_fault_burns_an_attempt_and_retries. tests/test_client_transport.py::TestStatusPoller. Reported independently failing on a clean main checkout by PRs parallel sweep: 2^n morton-subtree partitions with isolated workers (issue #377) #380, pyramid v2: leaf-worker column writes (issue #383) #391, leaf skip-if-current: input-identity no-op with lifecycle touch (issue #388) #397, batch mortie coverage in ShardMap.build (issue #396) #400, and state satisfied mortie minimums in arrival voice, guard the rest #412 (a fake-clock/poller race — "the clock bump races the poller's not_before stamp"). Never root-caused or filed despite 5+ independent reports.
2. backend="auto" default doesn't prefer the mortie index when one is already built. PR batch mortie coverage in ShardMap.build (issue #396) #400, Question 9: today auto always resolves to spherely unless the caller explicitly requests backend="mortie", even when the catalog already has a mortie MOC index built. Flagged as "ships conservative, can be ruled post-merge"; sibling questions Q2/Q4/Q10/Q11 from the same PR got tracking issues (Adopt batch mocs_to_orders on the geometry path's per-ring moc_to_order #427/prefilter_order= on ShardMap.build: benchmark against the batch path, ship only if it wins #428/index_footprints WKB screen: 1.8 GB shapely peak at clone scale #429/Split shardmap.py backend seam into catalog/footprints.py (post-#400 refactor) #430), Q9 did not.
3. N818 ruff lint on UnknownCapability — should be UnknownCapabilityError per PEP 8 exception naming (src/zagg/registry.py:64). Flagged as pre-existing/not-fixed-here in at least 9 of the 11 PRs in this window (batch mortie coverage in ShardMap.build (issue #396) #400, leaf_column rename, granule-id sibling objects, refusal manifest (issue #388 follow-up trio) #403, small fixes 2026-08-08: use mortie's flat exports instead of the tools submodule (issue #406) #411, state satisfied mortie minimums in arrival voice, guard the rest #412, pyramid v2: staged dense sweep on the partition machinery (issue #384) #416, pyramid v2: leaf-worker column writes (issue #383) #391, leaf skip-if-current: input-identity no-op with lifecycle touch (issue #388) #397, land the AOI/CONUS shardmap builders (issue #372) #395, small fixes: staged sweep skip key carries the run ids; bench object model gains the column term #421). Discussed with options in Follow up items for the week of August 1, 2026 #366 but never has its own dedicated fix issue despite the recurrence.
4. mortie-version drift-guard regex has false positives on forward-looking prose. PR state satisfied mortie minimums in arrival voice, guard the rest #412's new tests/test_mortie_versions.py guard reddens correct sentences like "gated on mortie 0.10.0" that use an explicit version number in forward-looking design-doc voice. Explicitly left standing on the review thread as a known tradeoff.
5. emit_multi_group_template duplication between column.py and sweep_overview.py. PR pyramid v2: leaf-worker column writes (issue #383) #391: the column writer duplicates HealpixGrid's wholesale-clear template-write logic already hardcoded in sweep_overview.py::_write_overview, rather than sharing one method. Reviewer flagged real duplication; response left it standing as "an @espg call" on where the consolidation belongs.
6. Two design-fork questions from PR parallel sweep: 2^n morton-subtree partitions with isolated workers (issue #377) #380 never actioned. (a) The 2^n Lambda partition fan-out has no production caller yet — all real call sites still pass partitions=1. (b) Whether the partition disjointness invariant deserves a formal §8.1 design-doc entry. Both flagged as owner-only decisions, never filed as a follow-up.

Priority ranking

#	Item	Source PR(s)	Severity	Why
1	Flaky StatusPoller retry test	#380, #391, #397, #400, #412	Medium	Genuine test-suite reliability gap recurring across 5+ independent runs, possibly masking a real retry-timing edge case
2	backend="auto" doesn't prefer a built mortie index	#400	Low-Medium	Current default is the conservative/safe one — no correctness risk, but a possible missed-optimization surprise for operators
3	N818 lint on UnknownCapability	#400, #403, #411, #412, #416, #391, #397, #395, #421	Low	Pure naming nit, blocked on an API-compat decision; flagged 15+ times with no fix issue
4	mortie-version regex false positives	#412	Low	CI/test-tooling nuisance risk, not a runtime bug
5	emit_multi_group_template duplication	#391	Low	Code-cleanliness/maintenance-burden item, not correctness
6	PR #380 design-fork questions unfiled	#380	Low	Architecture/documentation housekeeping; single-invoke path works correctly today

Already tracked / already resolved (not repeated above)

• PR batch mortie coverage in ShardMap.build (issue #396) #400: Q2 → Adopt batch mocs_to_orders on the geometry path's per-ring moc_to_order #427, Q4 → prefilter_order= on ShardMap.build: benchmark against the batch path, ship only if it wins #428, Q10 → index_footprints WKB screen: 1.8 GB shapely peak at clone scale #429, Q11 rider → Split shardmap.py backend seam into catalog/footprints.py (post-#400 refactor) #430; Q1/Q3/Q6/Q7/Q8 resolved in-thread.
• PR pyramid v2: staged dense sweep on the partition machinery (issue #384) #416: Q6 → staged sweep skip gate: same-second rewrite blind spot — close it with the run_id already in the stamps #417 (closed, fixed by small fixes: staged sweep skip key carries the run ids; bench object model gains the column term #421); Q7 → bench_objects.py object-count model needs a term for the leaf pyramid column (explicit .github change request) #418 (closed, fixed by small fixes: staged sweep skip key carries the run ids; bench object model gains the column term #421); Q2/Q3 → staged sweep graduations: Lambda stage transport and the chaining default flip #419.
• PR small fixes: staged sweep skip key carries the run ids; bench object model gains the column term #421: review findings folded; remaining item → small fixes: granule_count term in the staged-sweep skip key; objects_overviews → objects_sweep rename #433 (PR small fixes 2026-08-11: granule_count skip-key term; objects_overviews → objects_sweep rename #435 in flight).
• PR leaf_column rename, granule-id sibling objects, refusal manifest (issue #388 follow-up trio) #403: item (4) → Skip gate can pass on a torn rewrite: leaf stamped by run 2, sidecar still run 1's #407; refusal-manifest items → Follow up items for the week of August 8, 2026 #409.
• PR leaf skip-if-current: input-identity no-op with lifecycle touch (issue #388) #397: all 10 review questions → Tracker: PR #397 follow-ups — the ten review questions, rulings, and landing sites #402.
• PR pyramid v2: leaf-worker column writes (issue #383) #391: manifest-vs-config gate resolved by ruling; raster hive gap → raster hive under a /2 pyramid declaration: leaf columns are never written (rule PR #391 options (a)/(b)) #399.
• PR land the AOI/CONUS shardmap builders (issue #372) #395: three items already itemized in Follow up items for the week of August 8, 2026 #409 (item 5).
• PR pyramid v2: (node, cells) level grammar and zagg-pyramid/2 (issue #382) #389, small fixes 2026-08-08: use mortie's flat exports instead of the tools submodule (issue #406) #411: no outstanding items found — all resolved same-day or zero open questions.

Questions for review

None — this is a discussion/triage issue, not an implementation request.

[espg]

🤖 from Claude

Recommendation: file (1) and (3) as their own issues now — (1) is root-caused below and is a two-line test fix, (3) is one ruling away from being mechanical. Items (2), (4), (6) are ready to file as-is. Item (5) should NOT be filed until it is re-verified: the symbol it names no longer exists on main.

The one substantive correction to the triage is in (1)'s severity column.

---

(1) The StatusPoller flake is root-caused, and it is harness-only

The table prices this as "possibly masking a real retry-timing edge case." It is not — it is a race between the test's own spin loop and the poller thread, and no production configuration can reach it. That matters for how the item gets scheduled, so here is the mechanism with a reproduction rather than a hypothesis.

The mechanism. tests/test_client_transport.py:495 spins on calls["n"], which flaky() increments on its first line, before it raises:

def flaky():
    calls["n"] += 1              # <- the test's observable, emitted here
    if calls["n"] == 1:
        raise RuntimeError("TooManyRequestsException")

The backoff stamp is written much later, in the except handler — src/zagg/client_transport.py:1066:

with self._lock:
    entry.retry_not_before = self._clock() + delay

So the observable is emitted before the state the clock bump must not precede. If the main thread wins, now["t"] = 1002.0 (line 513) lands first and the stamp becomes 1002.0 + 2.0 == 1004.0. The test never advances the clock again, retry_not_before <= now at client_transport.py:889 is never satisfied, and assert calls["n"] == 2 fails after burning its 5 s deadline.

Reproduction (deterministic — forcing the losing interleaving by bumping the clock inside flaky(), which is exactly what the main thread does when it wins):

poller wins (stamp lands first):  calls=2 retry_not_before=0.0    clock=1002.0 retries=1 -> PASS
main thread wins (the flake):     calls=1 retry_not_before=1004.0 clock=1002.0 -> FAIL (assert calls['n'] == 2)

Why only this one test in the family flakes. Two siblings have the same clock-bump shape and are both safe, for two different reasons:

• test_drop_refire_consumes_a_late_status_object (line 487) bumps to 11.0 on the same kind of observable, but the drop path reads dispatched_at, stamped in _fire at client_transport.py:912 before dispatch() is called. The stamp precedes the observable, so the bump cannot get in front of it.
• test_throttled_invoke_backs_off_instead_of_bursting (line 542) is the same shape and is protected only accidentally, by the time.sleep(0.05) at line 546 — which is there to prove "several ticks INSIDE the backoff," not to order the stamp. It would flake too if that assertion were ever tightened away.

Three fixes, in the order I would rank them:

• (a) Spin on the stamp instead of the counter. Before bumping, wait for poller._entries[ct.shard_status_key(1)].retry_not_before != 0.0. Deterministic — it waits on precisely the state the bump must follow. The private-attribute reach is already an established idiom in this file (test_attempt_id_dedupe_acts_once_per_execution, line 463). Two lines. My pick.
• (b) Copy the sibling's time.sleep(0.05) barrier. One line, makes the two tests consistent. But it narrows the race rather than closing it, and a sleep-ordered test is the kind of thing that comes back under CI load.
• (c) A harness clock whose advance() blocks until the poller has quiesced. Retires the whole class, including the accidental protection in the sibling. Costs a new test helper and touching three tests for a bug that today affects one — worth doing only if a second test in this family flakes.

(3) N818 — the blocker is an export decision, not the rename

Worth stating why this has survived 15+ flags: UnknownCapability is in registry.py's __all__ (src/zagg/registry.py:431), imported across src/zagg/index/__init__.py and two test modules, and its docstring commits to it as "a clean error type for the MCP server to relay." So the rename is API-visible, and # noqa is off the table under CLAUDE.md §4. Three options: rename with a module-level UnknownCapability = UnknownCapabilityError alias; rename outright on the grounds that pre-1.0 has no compat promise (issue #58 is where the 1.0 gate lives); or rule it deliberately-kept and record that at the class so the next nine PRs stop re-flagging it. The third is a legitimate outcome — what is not working is leaving it unruled.

(5) Needs re-verification before it is filed

emit_multi_group_template does not exist anywhere under src/ on main at d35e576. What remains is _write_overview (src/zagg/sweep_overview.py:1762) and two comments in column.py (lines 406 and 524) that cite "_write_overview's posture" rather than duplicating its code. So the item is either already resolved by a rename in this window or it is now a different, smaller thing. Filing it as written would send someone after a symbol that is not there.

(2), (4), (6) — confirmed as filed

• (2) is exact. _resolve_backend (src/zagg/catalog/shardmap.py:892) returns "spherely" whenever _spherely_available(), and never consults whether a mortie MOC index exists. The one nuance for whoever picks it up: the function currently takes only (backend, grid), so "prefer a built index" needs the catalog threaded in — small, but it is a signature change, not a branch.
• (4) is a taxonomy gap rather than a regex bug. tests/test_mortie_versions.py names three voices (floor, arrival, requirement) and the pattern at line 76 deliberately treats a bare mortie 0.10.0 as requirement voice. Forward-looking design-doc voice is a fourth voice the taxonomy does not have, and no purely lexical rule separates it from the third. That probably makes it an allowlist question, not a pattern question.
• (6) is two owner-only design forks and reads correctly as filed.

Questions, each answerable in one pass

1. Item (1): fix (a), (b), or (c) above? And should it ride the next small-fix bundle, or get its own issue?
2. Item (3): rename-with-alias, rename outright, or rule it deliberately-kept and annotate the class?
3. Item (5): re-verify and refile against whatever the duplication is today, or drop it as resolved-by-rename?

Nothing here needs a decision to keep the sweep useful — (1)'s root cause stands on its own regardless of which fix is chosen.

---

Generated by Claude Code