Skip to content

FIX-1477 PR-A3: Roster and BoardColumns read every page - #2115

Merged
jhoffner merged 2 commits into
mainfrom
fix/FIX-1477-pr-a3-panel-paging
Sep 23, 2026
Merged

jhoffner merged 2 commits into
mainfrom
fix/FIX-1477-pr-a3-panel-paging

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

Roster and BoardColumns (packages/react/src/components/panels/) each read one page of their collection and stop. BUSINESS-RULES.md requires all of them: BR-19 for the roster, BR-21 for board columns — "not the first page — the list route pages, so a panel that reads page one and stops truncates silently." PR-A2 (#2036) shipped the one-page behaviour; this is the follow-up that closes it.

The list route (packages/engine/src/routes/resource-routes.ts) returns nextCursor while rows remain, with a default page of 50. A collection with 51+ rows — a roster past its first 50 seats, a board past its first 50 cards — silently lost its tail. No error, no truncation notice: the last rows were simply gone.

The fix

usePanelRows (packages/react/src/components/panels/reads.ts), the one read both panels share, now traverses nextCursor in a bounded loop (MAX_PAGES = 1000, a guard against a misbehaving transport rather than a limit any real collection is expected to hit) instead of making one request. The existing read-fence and abort semantics carry over unchanged: every page of one read is gated on the same identity via stillCurrent(), so a superseded or unmounted read stops mid-traversal rather than writing stale rows.

limit keeps its name and meaning as the page size each fetch requests — it is not a cap on what renders. Doc comments on both panels' limit prop, the usePanelRows header, and packages/react/README.md's "Transport and theming for both panels" section are updated to say so.

Public props are unchanged.

Red → green evidence

Red (packages/react/test/panels.test.ts, against the one-page reads.ts from PR-A2): two new tests, each seeding 51 rows through a fake paginated transport (default page 50, nextCursor while rows remain — mirroring the real route). Both timed out waiting for the 51st row:

❯ waitForWrapper .../wait-for.js:163:27
❯ test/panels.test.ts:194:11
   await waitFor(() => expect(screen.getByText("seat-050")).toBeTruthy());
...
 Test Files  1 failed | 24 passed (25)
      Tests  1 failed | 219 passed (220)
❯ waitForWrapper .../wait-for.js:163:27
❯ test/panels.test.ts:348:13
   await waitFor(() => expect(screen.getByText("task 50")).toBeTruthy());
...
 Test Files  1 failed | 24 passed (25)
      Tests  2 failed | 219 passed (221)

Green (after the reads.ts fix): both reach the last row in exactly two requests (page 1 + the cursor's page), and the BoardColumns test also seeds each row with envelope fields the projection withholds in production (claimedBy, lease, retryLedger, writeLog) and asserts none of them ever reach the DOM, even past the first page — covering V11's other half.

 Test Files  25 passed (25)
      Tests  221 passed (221)

Scope

packages/react only, per the assigned surfaces (S5, S6). No app or devtool changes.

Housekeeping cherry-pick

main (ffe2b6e26) does not build @flow-state-dev/workforce: #2091 (FIX-1529) changed hiredSeatManifest's return shape, and #2079, merged minutes later, added two call sites reading .manifest without narrowing against the new RowProblem case. This branch cherry-picks the fix already open at #2094 (db41f92, -x) so the branch builds; no new fix was written for it here.

Checks run

  • pnpm --filter @flow-state-dev/react test — 221/221 passing (25 files)
  • pnpm --filter @flow-state-dev/react typecheck — clean
  • node scripts/validate-changeset-refs.mjs — passes (new fragment names FIX-1477)

Closes BR-19, BR-21 and V11 for packages/react.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB


Generated by Claude Code


Note

Medium Risk
Panel reads now issue multiple sequential list calls per mount/refresh, which changes load behavior for large collections; workforce hire/manifest paths add error handling for a new union return shape.

Overview
Roster and BoardColumns no longer stop at the first list page. Shared hook usePanelRows now walks nextCursor until the route is done (with a MAX_PAGES safety cap), so rosters and boards past the default ~50-row page render every row instead of silently dropping the tail. limit is documented as per-request page size, not a render cap; panel props are unchanged.

Tests add a paginated fake transport and assert 51 rows need two fetches for both panels; the board test also checks withheld envelope fields stay out of the DOM across pages.

Build fix in @flow-state-dev/workforce: call sites guard hiredSeatManifest when it returns a problem before using .manifest (hire throws; manifest discovery skips bad rows).

Reviewed by Cursor Bugbot for commit 736e719. Configure here.

…call sites

main has been red since ffe2b6e. #2091 (FIX-1529) changed hiredSeatManifest
to return `{ manifest } | RowProblem`; #2079 (seat-hire catalog tools),
merged minutes later, added two call sites that read `.manifest` without
narrowing, so @flow-state-dev/workforce no longer compiles.

Both now handle the problem case the way roster/reload.ts already does:
- manifest-sources: a row owned by another org is skipped when listing
  seats, alongside the unparseable-row skip on the line above.
- seat-hire-capability: the hire refuses with the row's reason.

Verified: the workforce build fails on main with exactly CI's four TS2339
errors and passes with this change; workforce 755/755; pnpm typecheck
70/70.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014Zc4qjodAcrYK5kMfcrXS8
(cherry picked from commit db41f92)
…first

PR-A2 (#2036) shipped both panels reading exactly one page of their
collection through packages/react/src/components/panels/reads.ts, which
never followed the list route's nextCursor. BR-19 and BR-21 both require
every row; a collection past the route's default 50-row page (V11)
silently dropped its tail — the last seeded seat or board row went
missing with no error, no truncation notice.

usePanelRows now traverses nextCursor in a bounded loop (MAX_PAGES),
keeping the existing read-fence and abort semantics: every page of one
read is gated on the same identity, and a superseded or unmounted read
stops fetching mid-traversal. `limit` is now documented as the page
size the read requests each time, not a cap on what renders.

Red: a fake paginated transport seeded with 51 rows never rendered the
51st for either panel (`seat-050` never appeared for Roster; `task 50`
never appeared for BoardColumns), each timing out its waitFor.
Green: both traverse to the last row in two requests, and BoardColumns
renders only the projected fields (no claimedBy/lease/retryLedger/
writeLog leaking from the raw envelope) even past the first page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ANuyMVi3YS653fcghb9gtB
@vercel

vercel Bot commented Sep 23, 2026

Copy link
Copy Markdown

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

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 23, 2026 9:52pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 23, 2026 9:52pm UTC
flow-state-dev-ui Ignored Ignored Sep 23, 2026 9:52pm UTC

Request Review

@linear-code

linear-code Bot commented Sep 23, 2026

Copy link
Copy Markdown

FIX-1477

@jhoffner
jhoffner marked this pull request as ready for review September 23, 2026 23:18
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 23, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-23T23:22:00.016725Z 736e719 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@jhoffner
jhoffner merged commit 739341b into main Sep 23, 2026
15 checks passed

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Snob — already tight. No POC.

I read packages/react/src/components/panels/reads.ts, the limit docs on Roster.ts and BoardColumns.ts, pagedSource plus the two new cases in packages/react/test/panels.test.ts, listCollectionItems in packages/client/src/resource-client/resources.ts, and the other cursor walk in packages/devtool/src/react/hooks/use-debug-collection-items.ts. The workforce lines are a four-line cherry-pick of an existing "problem" in record narrow.

usePanelRows is the walk: a bounded for, omit limit/cursor when unset, fence after each page, one setRows. Passing { limit, cursor } is shorter and would change the call the existing roster test pins ({} when both are absent). The real client skips undefined keys; a host source might not. Sharing a pager with the devtool hook loses — that one is load-more, item-capped, and uses null cursors. The prop comments are the contract this change exists to state. A rewrite would not shrink it.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify review (PR-A3 / FIX-1477)

Problem this PR solves: one-page usePanelRows silently dropped row 51+ when the list route paginates at 50. BR-19/BR-21 require the full standing list.

Verdict: The cursor walk in usePanelRows is the right minimal fix. I would not swap in useResourceCollectionList (different transport, loadMore UX, session overlay) or a new npm paginator (none in the monorepo; the loop is ~15 lines). A default limit: 200 when the host omits limit would be a nice follow-up to cut round-trips for collections ≤200, but it does not replace pagination — raising the route default alone still truncates if the client never follows nextCursor.

What looks clean: single shared hook, fence/stillCurrent() preserved inside the loop, prop/README alignment on limit = page size, pagedSource tests that mirror route semantics (51 rows → 2 calls). Workforce cherry-pick is scoped and explained; not a smell.

Skipped (optional / follow-up): extracting listAllCollectionItems on ResourceClient for reuse; engine list route avoiding full re-scan per cursor page (large-board perf, pre-existing amplification); folding projection assertions into a separate test from the paging test.

Approval: Direction and implementation match the business rule without unnecessary abstraction. Inline notes are nits and one edge-case suggestion, not merge blockers.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

* `packages/engine/src/routes/resource-routes.ts`) this still covers 200,000
* rows before it gives up and shows what it has.
*/
const MAX_PAGES = 1000;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: MAX_PAGES, its block comment, and the usePanelRows JSDoc all say the same thing (scan-not-feed, misbehaving nextCursor, limit = page size). Consider trimming this block to one line + pointer to the hook doc — not blocking.

Also the "200,000 rows" math assumes each request uses STATE_LIST_MAX_LIMIT; when hosts pass a smaller limit, the ceiling is limit × 1000.

collected.push({ topic: item.topic, clientData: item.clientData as TClient });
}
if (page.nextCursor === undefined) break;
cursor = page.nextCursor;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the loop exits because pageCount hits MAX_PAGES while page.nextCursor is still set, we setRows(collected) with no error — another silent truncation, same class BR-19 fixed for "first page only." DevTool's use-debug-collection-items at least clears hasMore when its accumulation cap hits.

Suggestion (not required for merge): after the loop, if the last page still had nextCursor, call setError with a short message (or document in README that an internal page-count guard exists). Uncertain this ever fires in production; worth aligning UX with the "no silent tail drop" intent.

const collected: PanelRow<TClient>[] = [];
let cursor: string | undefined;
for (let pageCount = 0; pageCount < MAX_PAGES; pageCount++) {
const page = await source.listCollectionItems(sessionId, ref, {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional follow-up: when limit === undefined, default the request to 200 (STATE_LIST_MAX_LIMIT) so typical rosters/boards (≤200 rows) pay one round-trip instead of ⌈N/50⌉ sequential fetches. Keep this loop either way for correctness past 200.

* V11).
*/
function pagedSource(items: Array<{ topic: string; clientData: unknown }>, pageSize = 50) {
const listCollectionItems = vi.fn(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pagedSource is the right shape for this package — no shared helper elsewhere, and inlining would hurt readability. Fine to leave local unless integration tests start duplicating the same fake transport.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 736e719c19

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

);
const collected: PanelRow<TClient>[] = [];
let cursor: string | undefined;
for (let pageCount = 0; pageCount < MAX_PAGES; pageCount++) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Avoid silently truncating at the page safety ceiling

When the collection spans more than 1,000 pages, this loop exits while the last response still has a nextCursor, and setRows(collected) then presents the partial result as complete. This is reachable with valid inputs—for example, the engine accepts limit={1}, so a 1,001-row roster or board loses its final row—and recreates the silent truncation this change is intended to eliminate. Continue until the cursor is absent, or surface an error when the safety ceiling is reached with another page outstanding.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants