fix(grid-core): stop an evicted selection painting rows nobody selected

[blove]

Two publicly-reachable correctness bugs found by an adversarial audit of the eviction work. Both contradicted published promises.

Bug 1 — an evicted selection painted rows the reader never selected

Reproduced through <PretableSurface> with the full honesty gate passing. Select rows 1–8, evict both endpoints, the server prepends five rows under the same datasetKey — correct per our own docs, since the key identifies a query — then scroll back:

[{"rowId":"new-0","selected":false},{"rowId":"new-1","selected":true},
 {"rowId":"new-2","selected":true},{"rowId":"new-3","selected":true},
 {"rowId":"new-4","selected":true},{"rowId":"row-0","selected":true}]

Five rows painted selected; four did not exist when the user selected. The rows actually selected painted nothing.

datasetKey identifies the query, not the population. An insert or delete upstream silently re-fills the remembered positions with different rows.

The fix: a population fingerprint. resultMeta.total.count is stamped onto the span beside datasetKey, and onto the window as a required field — the gate cannot pass without an exact total, so making it optional would only be a way to fail open by omission. spanReadableInWindow now requires key match and size match, failing closed on either.

What it does not catch, stated plainly rather than papered over: a mutation leaving the size identical — an insert and a delete in the same revision, or an in-place replacement. Pinned as an explicit KNOWN GAP test so it goes red the day a consumer-supplied population token exists.

Containment in the residual case still answers from the remembered span, reporting verified: false. Refusing all remembered-endpoint painting was considered and rejected: it breaks the ordinary partial-return window — selection 1–8 with the window at [4,14) would stop painting rows 4–7 — converting an over-paint bug into an under-paint bug.

A silent regression this nearly caused: a deletion is a population change, so a strict comparison would have refused every span the instant narrowDeletedEndpoints had something to narrow. The comparison now allows a span whose total is short by exactly the deletions it has proven, and re-stamps at the post-deletion size. A revision that also inserted, or deleted a row it could not prove, does not add up and is refused.

Bug 2 — one closed-gate revision permanently destroyed the selection and the cursor

A single render where total is briefly {kind:"estimate"} — an in-flight count query — dropped the ranges irrecoverably and emptied the cursor. They did not return when the gate reopened. processing.sort: "engine" for one revision did the same.

Dropping a range because the gate closed is the engine asserting the rows are gone — precisely the claim it cannot make without a window. The project's own fail-closed logic says the opposite: absent proof of deletion, retain.

The fix: a new windowed fact on the eviction context — does the consumer publish resultMeta.window at all — derived per render and never latched. It deliberately does not ride the honesty gate: whether the consumer serves a window is a fact about the consumer, not about this render. Mutating it to windowSpacers !== null reddens the tests.

• windowed: false → local mode, prune, byte-for-byte as before
• windowed: true + window: null → cannot verify, retain

getSelectionWindow became getWindowing, returning both facts from one read so they cannot describe different instants — the same skew class the observed pairing already guards against. evictionWindowUnknown is shared by selection and focus so they cannot drift.

A real behaviour change worth knowing

windowed: true with a permanently shut gate — grouping always on, or a total that is never exact — now means selection and cursor never prune on absence. That is the fail-closed direction and no test regressed, but a genuine deletion in those grids will no longer clear from the selection. The engine cannot distinguish it from an eviction, and those consumers genuinely are windowing.

Docs corrected

• lifecycle.mdx — "What it buys is never painting a row the reader did not select" was false for datasetKey alone. Replaced with what the key does and does not answer, the total's role, and the residual gap.
• eviction.mdx — the exact total is now named as load-bearing for selection; a new "does not do" item states the same-size gap plainly, with verified: false as the signal; and a paragraph on gate closure holding rather than discarding.

Proven

Mutation	Reddened
spanReadableInWindow compares datasetKey only	react paints nothing rather than rows the reader never selected; grid-core an insert upstream of an evicted span refuses it, and recovers later
disable the selection retain-on-unknown guard	2 react tests (estimated total, engine sort) + grid-core a shut honesty gate retains, while local mode still prunes
disable the focus retain-on-unknown guard	same 2 react tests + grid-core a shut honesty gate holds the cursor, while local mode still re-seats
windowed: windowStart !== undefined → windowSpacers !== null	2 failed
datasetTotal: matchingTotal.count → 0	react paints nothing…

Local mode is proven unchanged by running one grid-core fixture both ways — windowed: true retains and returns the identical object; windowed: false and a context saying nothing both prune — plus a React control where rows genuinely vanish from an unwindowed grid and both selection and cursor go.

A vacuous fixture caught during the work: the first Bug-1 test read data-pretable-selected on the row element, which is only true for a range spanning every drawn column. It passed vacuously while the control failed. The tests now read the cell attribute and say why.

Verification, against baselines measured on origin/main first

	baseline	after
grid-core	120	124
layout-core	98	98
react	1208	1216
app-bench	—	155
playwright	—	28
website (docs guards)	—	554

typecheck, lint, prettier clean repo-wide. pnpm build → pnpm api → pnpm api:check in that order, all clean. Forgotten-exports guard 5/5.

Needs a human decision

1. Whether to add a consumer-supplied population token, which would close the equal-insert-and-delete gap that a size comparison cannot see.
2. Whether indexedRangeContainsCell should become tri-state, so an unconfirmed span paints distinctly rather than as ordinary selection. That has UI and aria consequences beyond this fix.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
pretable	Ignored		Aug 17, 2026 3:00am

[github-actions]

Vercel preview ready

Preview: https://pretable-bjzg9zjjl-cacheplane.vercel.app
Commit: c4334c62c62ddc5d2290430e3bef0607d474c662

_{Updated automatically by the deploy-preview job.}