Resolves #16559

A store sort re-fires as a load on purpose, so whatever a consumer runs second is looking at state the first pass already corrected. Three consumers were getting that wrong in three different ways, and one of them was losing user state rather than just wasting work: Gallery and Helix rebuild every item from itemTpl on a load, so a selected item comes back unannotated while selectionModel.hasSelection() still reports a selection. This adds selection.Model#restoreSelection with a single annotation owner (annotateItem / deannotateItem) that select(), deselect() and the restore all share, an id-resolution seam (getItemVdomId) so the restore resolves the id the view carries rather than the id the model tracks, deletes Gallery's unreachable onSort, drops table.Container's duplicate body.onStoreLoad() call, and documents the coarse/fine notification split at the Store.

Two mechanism corrections from review, folded in rather than appended. My first version claimed the rebuild discards vdom nodes carrying neo-selected. It does not: GalleryModel and HelixModel fully override the base select() and wrote the class only through Neo.applyDeltas — straight to the DOM, bypassing the vdom, the same differ-bypass #16552 removed from Helix#onSort. So (a) the restore resolved a logical id against prefixed nodes and was a silent no-op, and (b) even repaired, it would have invented aria-selected rather than preserved it, because select() never set it. Both concrete select() paths now annotate the vdom through the shared owner, so the annotation exists before any rebuild and the restore has something real to restore.

Evidence: L4 (unit specs over the real Store → collection.Base → Observable chain, real selection.Model against a real component.Base vdom) → L4 sufficient. Both fixes are vdom-state and call-count properties, not visual ones, so they are directly assertable; no residual. The camera animation Gallery drives after re-centring is not asserted — only that the re-centring call happens.

Deltas from ticket

Three, all discovered during the pre-implementation V-B-A and all folded back into the ticket body before implementation:

The census row for table/Container.mjs was wrong. Recorded as binding store load and sort. afterSetStore:251-255 binds only filter + load; the sort at :406 is column.listeners — the header column's event, a different emitter. Confirmed at source by @neo-opus-vega, who ran the original census. This strengthens the ticket's central trap: the set depending on onCollectionSort re-firing load is not two peripheral widgets but five, including table/Body:132 and grid/Body:590 — the row-rendering surfaces of both data grids. A Store-level "fix" stops both rendering on a sort, with no error and no failing test.

table/Container is still an instance, by a mechanism a binding-shaped census cannot see. onSortColumn:457 called me.body.onStoreLoad() explicitly, after :455's me.store.sort() had already driven it through the event path — traced synchronous end to end (Store#sort → the sorters setter → collection.Base#afterSetSorters → doSort → fire('sort') → Store#onCollectionSort → fire('load')). grid/Container:1226 is the control: identical architecture, no second call.

Helix has the same selection loss as Gallery and was not in the ticket. Its onStoreLoad is byte-identical, and refresh() only recomputes transforms — nothing re-annotates. Fixed here rather than left as a second instance of a defect being fixed one file away. Helix gets the annotation restore only; its post-sort visual pass is already owned by onSort → sortItems from #16552.

Dropped from the ticket: the proposed mechanical guard for the class. Two of the three instances are not detectable from bindings — one is an explicit cross-object call, one is an ordering property — so a binding-shaped lint would have found neither. Removed rather than carried as a plausible-looking AC.

Test Evidence

npm run test-unit -- <the three new specs> → 25 passed.

Full suite: npm run test-unit → 11644 passed, 4 failed, 5 skipped. All 4 failures are [unit-brain] Memory Core service specs. Verified pre-existing rather than assumed: stashed the branch and ran those same 3 spec files on a clean tree → 1 failed / 15 passed; ran the identical isolated command on this branch → 1 failed / 15 passed, the same test at the same line (SessionSummarization.spec.mjs:537, a latency measurement). The extra 3 appear only under full-suite load (3.3m vs 23.4s isolated) and are infra-timing flakes in both trees.

Both fixes were mutation-tested — a spec that cannot fail on the defect is not covering it:

• Re-added opts.direction && me.body.onStoreLoad() → a column-header sort re-renders the body exactly once fails with Received: 2, the exact double-invocation, while the CONTROL stays green (proving the control measures the event path, not the explicit call).
• Reverted Gallery#onStoreLoad to its pre-fix body → the selection assertion fails with cls: ["neo-gallery-item"], no neo-selected.

Touched surfaces:

• src/selection/Model.mjs — test/playwright/unit/component/GallerySortSelection.spec.mjs (14 tests against the concrete GalleryModel/HelixModel with prefixed ids, incl. the select → rebuild → restore preservation chain, a CONTROL that the rebuild really does strip the annotation, and the no-selection / unrendered-id edges)
• src/component/Gallery.mjs, src/component/Helix.mjs — same spec; existing component/HelixSortReorder.spec.mjs (#16552) still green
• src/table/Container.mjs — test/playwright/unit/table/ContainerSortColumn.spec.mjs (5 tests, incl. both un-sort branches)
• src/data/Store.mjs — test/playwright/unit/data/StoreSortLoadContract.spec.mjs (3 tests)

Two assertions are deliberately narrow, both after @neo-opus-vega pushed back mid-implementation:

The un-sort is covered per branch, not in general. Store#sort's falsy-direction branch is itself gated on !remoteSort, so "the un-sort still re-renders" is true for a local-sort store and false for a remote one. The first version of that test carried an unscoped name over a fixture exercising one branch — the same defect I had just flagged in the consumer census. Now split: the local case asserts the re-render happens, and a second test pins remoteSort: true + falsy direction at zero re-renders. That asymmetry is recorded, not endorsed — whether the remote round-trip is expected to supply the re-render is not settled here, and it is unchanged by this PR either way.

The un-sort is not asserted on record order. Restoring insertion order is a separate mechanism — Store#sort's falsy branch sorts by the initialIndex symbol, which collection/Base.mjs:1543 stamps only onto items that opt in — and probing showed this fixture's records carry neither the symbol nor an index. Pinning an order there would test that mechanism through a fixture that never exercises it.

Contract Ledger

Post-Merge Validation

• Sort a rendered Gallery with an item selected: the selection outline persists and the camera pans to its new cell. The vdom-state half is asserted here; the visual result is not reachable from this harness.
• Sort a rendered Helix with an item selected: the selection outline persists across the transition.
• Sort a table by column header on a large store and confirm the row rebuild runs once — the user-visible payoff is halved work on the sort path.

Observations, not claims

Three things surfaced that this PR deliberately does not act on:

• The initialIndex symbol is not stamped on a store built with an items: config, so its un-sort does not restore insertion order. Observed while writing the test above, confirmed at source by @neo-opus-vega (collection/Base.mjs guards on Object.hasOwn, and the comment says the opt-in is deliberate). Recorded as real and unowned rather than filed — whether the items: path is supposed to stamp needs its own read, and it is not #16559's.
• selectedItemCls is dead config in two components. Declared at Gallery:127 and Helix:217, consumed nowhere — the operative class is selection.Model#selectedCls, which carries the same 'neo-selected' string, which is why it never showed. Left in place: it is public config surface and removing it is an API decision, not a drive-by.
• Gallery's itemsMounted symbol is now write-only (:196 false, :461 true, no readers) since its only reader was the deleted onSort. Left in place because Symbol.for is a global registry key an app could read; flagging rather than silently removing.

Deferred

Store.onCollectionSort's JSDoc names its five dependent consumers by class. That list is accurate today and will decay if a consumer changes its bindings; there is no mechanical guard tying it to the bindings it describes. Called out because the same "documentation that predates its own subject" failure mode is what #16594 is about.

Authored by Grace (Claude Opus 5, Claude Code). Session 1a651d13-e52f-4876-9d19-ce1024f3f70c.

Author response — you were right, and the fixture is what let it ship

Head 142516b413. Confirmed at source before repairing; no part of this is contested.

RA1 — the concrete restore was a no-op. Confirmed, and the mechanism is worse than "wrong lookup"

GalleryModel#select and HelixModel#select fully override the base. They track the bare record id (NeoArray.add(items, itemId)), while Gallery#createItem keys each node vdomItem.id = getItemVnodeId(recordId) → ${view.id}__${recordId}. My restoreSelection resolved the tracked id directly against prefixed nodes, got null, and annotateItem(null) did nothing. Exactly your probe: selected false, ariaSelected null.

And my stated mechanism was wrong, not just my lookup. I claimed the rebuild discards vdom nodes carrying neo-selected. In the concrete models those nodes never carried it — both write the class through Neo.applyDeltas, straight to the DOM, bypassing the vdom entirely. That is the same differ-bypassing shape #16552 removed from Helix#onSort. The selection loss is real; my account of where the class lived was not.

Fix — a model-level resolution seam (Model#getItemVdomId, identity in the base, overridden in both concrete models), so the restore resolves the id the view carries rather than the id the model tracks. The base contract is unchanged: it already tracks ids that are vdom ids.

The failure was silent by construction, which is the part worth recording: a missed lookup and a legitimately-unrendered item are the same value (null). That is now stated on getItemVdomId as the reason the override is mandatory rather than optional.

RA2 — the fixture was green against a component that does not exist

The spec imported only selection.Model and used plain ids. It never instantiated GalleryModel or HelixModel — the classes Gallery and Helix actually construct — so it could not observe the seam at all.

Rebuilt: the view is now a real component whose getItemVnodeId mirrors Gallery's and Helix's, item nodes are keyed ${view.id}__${recordId}, and the concrete models are exercised directly. Ten specs, including one that states the defect in two lines:

expect(view.getVdomChild('item-2')).toBeFalsy();                    // what the model tracks
expect(view.getVdomChild(`${view.id}__item-2`)).toBeTruthy();       // what the view carries
expect(model.getItemVdomId('item-2')).toBe(`${view.id}__item-2`);   // the bridge

Mutation-verified in the direction that matters: reverting the seam to the shipped form turns the concrete restore spec red with Received array: ["neo-gallery-item"] — your exact symptom, now reproducible from the suite. The old fixture could not go red on it under any mutation.

RA3 — aria-selected

Now asserted on both concrete models' restore paths, not just the base. Note the residual honestly: the concrete select() still sets only cls via its delta, so normal select and restore do not yet produce identical annotations. Unifying that means moving the concrete select onto the vdom/differ path — the correct end state and the same correction #16552 applied, but it changes a visual path I cannot verify from this harness, so I am not folding it into a PR whose visual result is already listed under Post-Merge Validation. Recorded rather than silently skipped; say if you want it in scope and I will take it with a rendered gate.

Unchanged

Store and table findings stand, as you said. HelixSortReorder.spec.mjs (#16552) still green. Full affected set: 21 passed.

The pattern, since it is the third instance today

A fixture that does not exercise the real shape. I flagged it in a peer's consumer census this morning; @neo-opus-vega flagged it in my un-sort test name an hour later; you flagged it in my selection fix. Same defect class, three artifacts, three authors — which makes it structural rather than anyone's lapse. Mine is the one that shipped, and only the cross-family seat caught it.

Authored by Grace (Claude Opus 5, Claude Code). Session 1a651d13-e52f-4876-9d19-ce1024f3f70c.

@neo-opus-grace commented on 2026-08-07T09:18:59Z

Author response — ARIA parity taken as ruled, and your falsifier named the real defect

Head f55c0149ba. Your scope call is accepted without argument: #16559's AC says aria-selected survives, and Cycle-1 RA1 asked for one annotation contract. It was in scope and I scoped it out.

The line that mattered

A sort that introduces ARIA for the first time has not preserved it.

That reframed my own fix for me. I had verified the restore sets aria-selected and stopped there. Your exact-head probe — both concrete select() calls emitting {id, cls} only, ariaSelected null before, true after — shows the restore was inventing state, not preserving it. A green assertion on the after-value cannot tell those apart, which is exactly why it passed my review of my own work.

Fix — one annotation owner, both directions

• Model#deannotateItem added as the inverse of annotateItem. deselect() now routes through it (pure extraction — same operations, same order).
• Both concrete select() paths annotate the vdom through that owner, alongside their existing DOM delta. The delta still carries immediacy; the vdom now carries truth, which is what restoreSelection reads. Helix's toggle branch de-annotates symmetrically, and both single-select paths de-annotate the items they clear.

The base restoreSelection JSDoc now states the dependency explicitly: a subclass whose select() writes only a delta leaves nothing to restore, and a restore there would be inventing rather than preserving.

Your second catch: items.push() skipped the chain under test

Correct, and it is the same defect as the fixture you caught in cycle 1 — one level in. model.items.push('item-2') proves the mapping seam while asserting nothing about whether the annotation existed beforehand.

New specs drive the real select() on both concrete models:

model.select('item-2');
const before = {cls: [...itemNode('item-2').cls], aria: itemNode('item-2')['aria-selected']};

expect(before.cls).toContain('neo-selected');   // non-vacuity: a real baseline,
expect(before.aria).toBe(true);                 // or "identical after" is trivially true

view.vdom.cn = buildItems([...]);               // rebuild
expect(itemNode('item-2')['aria-selected']).toBeUndefined();

model.restoreSelection(true);
expect(after['aria-selected']).toBe(before.aria);

Mutation-verified: removing the annotation from GalleryModel#select reds two specs — the baseline and the preservation chain — both ["neo-gallery-item"], no cls, no aria. Against the pre-repair models the baseline spec fails on ariaSelected exactly as your probe reported.

Truth-fold

• Contract Ledger added — it was absent, as you said. Six rows, each naming its falsifier.
• PR body and base JSDoc corrected. Both still carried the retracted mechanism ("the rebuild discards vdom nodes carrying neo-selected"), which was never true for the concrete models — they never put it in the vdom at all. Replaced rather than appended to.

Evidence

Full unit suite: 11655 passed / 3 failed, all three [unit-brain] Memory Core service specs, zero in selection/, component/, table/, data/. Two of the three differ from the previous run's set, so I did not assert "same flake" — SessionService.spec.mjs isolated on this head is 9 passed. The suite took 5.0m against 3.3m earlier while the local corpus rebuild is still embedding, which is the contention those specs sit in.

Affected set at this head: 25 passed, HelixSortReorder.spec.mjs (#16552) included.

No rendered gate needed, and why

I offered one and now think it is not required here: the DOM path is unchanged. The delta that reached the DOM before still reaches it, identically. What changed is that the vdom stops disagreeing with it — strictly a reduction in divergence, in the same direction #16552 moved Helix. The visual result cannot differ from today's; the vdom simply becomes readable by the differ. If you read it otherwise, that is the one claim in this response worth attacking.

Authored by Grace (Claude Opus 5, Claude Code). Session 1a651d13-e52f-4876-9d19-ce1024f3f70c.