perf(realtime): read hooks answer the same object until what they show moved; where-readers hear only their keys; useRecords throttleMs; a per-type store index - #930

What changed

The page store's read hooks no longer make a consumer undo their work by hand. Measured against tesote/bank-integrations' panel on 29.1.0. That app had built three workarounds: throttle.ts, because a live board redrew on every record (ten a second, on a phone), and stableRuns / sameData, because new arrays of the same rows defeated Solid's ===.

1. The same answer back (record-answer.ts, keptAnswer). useQuery (live and non-live), useRecord and both useRecords forms now return the previous answer object while the status and every row object match. Across a ready ⇄ refreshing flip they keep at least the previous data array.
2. A where reader is told only of keys it shows or that where keeps now (moves in use-record.ts). An answer nobody has read since the last notification is always told. A where that throws inside the listener counts as a move: the read raises it, and a throwing listener would otherwise silence the store's other listeners.
3. useRecords(type, { throttleMs, schedule? }): opt-in and backward compatible. The first change is told at once, a burst becomes one notification at the end of the period, and the last change always lands. release() drops anything still owed. It reads no clock (the scheduler's timer is the period) and is validated by finiteCount (X_INVARIANT) before the type is held.
4. The synced layer indexes keys by type (#byType). keyed(type) and the replay's ofType used to scan every row on the page with startsWith.

Measurement: bun run scripts/bench/record-store-bench.ts

Decisions (made without the owner, recorded here)

• The wire is left as it is. Records frames already carry only the rows that moved. Resume already starts from the last contiguous seq per epoch. A gap already triggers one catch-up read and holds frames meanwhile. The store already sends one notification per frame. Nothing measured asked for more, so there is no protocol bump.
• Throttling belongs to the reader, not the store. Store notifications stay synchronous: an optimistic write is visible before push returns, and the settle rules depend on that.
• No new primitive and no new export. throttleMs / schedule are fields on the existing exported RecordSelection. No new error code.
• Not breaking. data is typed readonly R[]. Code that mutated it now mutates a shared array, and the CHANGELOG says so. This is a minor release.
• Budget, stated (axiom 9): examples/dummy /feed 166kb → 166.5kb. Measured 170,149 B against main's 169,509 B the same way (x build --target static): +640 B, page boot +359 and island +281, all of it the hooks above.
• The bench is a tested script: record-store-bench.test.ts asserts the counts in the table. It is a regression test for the claims and keeps scripts/ coverage at its pin (83.42% / 89.64% locally).
• Part of packages/realtime/CLAUDE.md (one bullet) moved to docs/history/realtime.md to stay under its size ceiling.

Checklist

• x verify is green
• Tier boundaries respected: realtime imports only @ultimat3/core/page
• Tests added (use-records-quiet.test.ts, record-answer.test.ts, record-synced.test.ts). 6 of 9 hook tests fail on main's hooks
• Errors are instructions: the only new throw is core's finiteCount (X_INVARIANT)
• --json: the bench takes --json
• i18n / colours / money / time: none touched
• No any, no default exports
• Public API documented: packages/realtime/README.md, wiki/Realtime.md, CHANGELOG.md [Unreleased]

Error codes

none

Verification

$ bun run verify   (local, no test services: live suites skip)
✓ typecheck ✓ lint ✓ boundaries ✓ filesize ✓ package-shape ✓ unit ✓ contract ✓ live ✓ job ✓ e2e ✓ eval ✓ manifest ✓ roadmap
✗ errors — X_TEST_BARE_ERROR at use-records-quiet.test.ts:99 (a throwing `where` predicate), fixed: the error is built once as the test's input
$ bun run scripts/verify.ts --only errors,lint
✓ lint ✓ errors
(drift, contract-diff, budgets, seo, i18n, policy: skipped at the repo root, as on main)

🤖 Generated with Claude Code