fix(web): paginate change history beyond the demo scan budget

## Summary

### Why?

Change history failed once the receipt window contained more than 500 queue requests, even when the selected change had only one submission.

### What?

Return bounded history pages with gateway continuations rather than a resource-exhausted error. Keep page-scoped models, notices, empty states, and navigation in the reusable library; the Next host signs queue/change/version-scoped cursors, preserves snapshot bounds, and resets older pages to a live window on refresh. Preserve exact-version lookup and reject looping gateway cursors.

## Test Plan

Passed change-branch web checks, package-consumer checks, production Next standalone build, formatting, lint, module tidy, and Gazelle checks. Added loader/component/reader regression tests for partial history, empty chunks, continuation, and repeated cursors.

Author: behinddwalls

web/service/submitqueue/README.md

@@ -10,7 +10,7 @@ GitHub, Phabricator, and git change pages mirror the canonical change URI's auth
 
 The default queue and change views use a rolling 24-hour window recalculated on every refresh; there are no `from`/`to` URL parameters. Older queue pages carry the stable gateway window inside a signed, queue-scoped `page` cursor, and their Refresh button returns to the live first page.
 
-Pinned GitHub/Phabricator pages use exact-URI summary lookup. Across-version and git demo pages scan queue receipts in the displayed rolling window, up to ten gateway pages. An exhausted or looping scan fails rather than returning partial history. Git scans also match raw demo URIs carrying file hints without requiring those hints in the browser URL. This bounded adapter is not an unlimited logical-change history API.
+Pinned GitHub/Phabricator pages use exact-URI summary lookup. Across-version and git demo pages scan queue receipts in the displayed rolling window, up to ten gateway pages per history page. When more queue requests remain, the host marks the results as page-scoped and offers **Continue history scan** instead of failing or claiming complete history. Signed cursors bind the stable receipt window and gateway continuation to the queue, change, and pinned version. Older pages pause automatic refresh; Refresh and **Latest history** return to a fresh live window. A looping gateway cursor still fails. Git scans also match raw demo URIs carrying file hints without requiring those hints in the browser URL. This bounded adapter is not an unlimited logical-change history API.
 
 Required configuration:
 

web/service/submitqueue/src/app/(protected)/[queue]/change/[...reference]/page.tsx

@@ -10,14 +10,15 @@ import { readChangeSubmissions } from "../../../../../server/change-reader";
 import { resolveGatewayClient } from "../../../../../server/gateway";
 import { requireAuthorization } from "../../../../../server/request-auth";
 import { gatewayDiagnostics } from "../../../../../server/diagnostics";
-import { defaultRequestWindow } from "../../../../../server/window";
+import { loadAuthConfiguration } from "../../../../../server/auth";
+import { defaultRequestWindow, decodeRequestPage, encodeRequestPage } from "../../../../../server/window";
 
 export const dynamic = "force-dynamic";
 export const revalidate = 0;
 
 export default async function ChangePage({ params, searchParams }: {
   params: Promise<{ queue: string; reference: string[] }>;
-  searchParams: Promise<{ from?: string | string[]; to?: string | string[] }>;
+  searchParams: Promise<{ from?: string | string[]; to?: string | string[]; page?: string | string[] }>;
 }) {
   await connection();
   await requireAuthorization();
@@ -28,25 +29,44 @@ export default async function ChangePage({ params, searchParams }: {
     notFound();
   }
   const search = await searchParams;
-  if (search.from !== undefined || search.to !== undefined) {
-    redirect(changeHref(queue, reference, reference.version !== null));
+  const latestHref = changeHref(queue, reference, reference.version !== null);
+  const scansQueue = reference.version === null || reference.scheme === "git";
+  if (search.from !== undefined || search.to !== undefined ||
+    (search.page !== undefined && (typeof search.page !== "string" || !scansQueue))) {
+    redirect(latestHref);
   }
-  const requestWindow = defaultRequestWindow();
+  const secret = loadAuthConfiguration().token;
+  const cursorScope = JSON.stringify([queue, reference.logicalPath, reference.version]);
+  const pageWindow = typeof search.page === "string" ? decodeRequestPage(cursorScope, search.page, secret) : undefined;
+  if (search.page !== undefined && pageWindow === undefined) {
+    redirect(latestHref);
+  }
+  const requestWindow = pageWindow ?? defaultRequestWindow();
   const result = await loadChangeSubmissions(
-    () => readChangeSubmissions(resolveGatewayClient(), queue, reference, requestWindow),
+    async () => {
+      const page = await readChangeSubmissions(resolveGatewayClient(), queue, reference, requestWindow);
+      return {
+        submissions: page.submissions,
+        pagination: page.nextPageToken || pageWindow ? {
+          nextHref: page.nextPageToken
+            ? `${latestHref}?page=${encodeRequestPage(cursorScope, requestWindow, page.nextPageToken, secret)}` : null,
+          latestHref: pageWindow ? latestHref : null,
+        } : undefined,
+      };
+    },
     {
       queue, provider: reference.scheme === "github" ? "GitHub" : reference.scheme === "phab" ? "Phabricator" : "Git",
       host: reference.host, repository: reference.repository, review: reference.review,
       pinnedVersion: reference.version,
       logicalHref: changeHref(queue, reference),
-      window: reference.version === null || reference.scheme === "git" ? { fromMs: requestWindow.fromMs, toMs: requestWindow.toMs } : null,
+      window: scansQueue ? { fromMs: requestWindow.fromMs, toMs: requestWindow.toMs } : null,
     },
     { diagnostics: gatewayDiagnostics },
   );
   return <main className="shell">
     {result.ok ? <ChangeView model={result.data} /> : <ErrorState error={result.error} />}
-    <div className="page-actions"><NextRefresh
-      terminal={!result.ok && !result.error.retryable}
+    <div className="page-actions"><NextRefresh refreshHref={pageWindow ? latestHref : undefined}
+      terminal={pageWindow !== undefined || (!result.ok && !result.error.retryable)}
       transientFailureCount={!result.ok && result.error.retryable ? 1 : 0}
     /></div>
   </main>;

web/service/submitqueue/src/server/change-reader.test.ts

@@ -16,7 +16,8 @@ describe("demo bounded change reader", () => {
     const client = { list } as unknown as SubmitQueueGatewayClient;
     const reference = parseChangePath(["github", "github.com", "uber", "submitqueue", "pull", "123"])!;
     const result = await readChangeSubmissions(client, "demo-queue", reference, window);
-    expect(result.map(value => value.request.sqid)).toEqual(["42", "38"]);
+    expect(result.submissions.map(value => value.request.sqid)).toEqual(["42", "38"]);
+    expect(result.nextPageToken).toBeNull();
     expect(list).toHaveBeenLastCalledWith(expect.objectContaining({ pageToken: "next", receivedAtOrAfterMs: 100n, receivedBeforeMs: 200n }));
   });
 
@@ -35,12 +36,43 @@ describe("demo bounded change reader", () => {
     const getRequestSummaryByChangeURI = vi.fn();
     const client = { list, getRequestSummaryByChangeURI } as unknown as SubmitQueueGatewayClient;
     const result = await readChangeSubmissions(client, "demo-queue", parseChangeUri(uri)!, window);
-    expect(result[0]?.request.sqid).toBe("42");
-    expect(result[0]?.versionHref).not.toContain("?");
+    expect(result.submissions[0]?.request.sqid).toBe("42");
+    expect(result.submissions[0]?.versionHref).not.toContain("?");
     expect(getRequestSummaryByChangeURI).not.toHaveBeenCalled();
   });
 
-  it("fails a truncated or looping scan instead of presenting partial history", async () => {
+  it.each([true, false])("continues a bounded scan without losing older matches (first page has matches: %s)", async (hasMatches) => {
+    const list = vi.fn().mockImplementation(async ({ pageToken }: { pageToken: string }) => {
+      const page = pageToken ? Number(pageToken.slice(5)) : 0;
+      return {
+        requests: page === 10 ? [request("38")] : page === 0 && hasMatches ? [request("42")] : [],
+        nextPageToken: page < 10 ? `page-${page + 1}` : "",
+      };
+    });
+    const client = { list } as unknown as SubmitQueueGatewayClient;
+    const reference = parseChangePath(["github", "github.com", "uber", "submitqueue", "pull", "123"])!;
+    const first = await readChangeSubmissions(client, "demo-queue", reference, window);
+    expect(first.submissions.map(value => value.request.sqid)).toEqual(hasMatches ? ["42"] : []);
+    expect(first.nextPageToken).toBe("page-10");
+    expect(list).toHaveBeenCalledTimes(10);
+    const second = await readChangeSubmissions(client, "demo-queue", reference, { ...window, pageToken: first.nextPageToken! });
+    expect(second.submissions.map(value => value.request.sqid)).toEqual(["38"]);
+    expect(second.nextPageToken).toBeNull();
+    expect(list).toHaveBeenLastCalledWith(expect.objectContaining({
+      pageToken: "page-10", receivedAtOrAfterMs: 100n, receivedBeforeMs: 200n,
+    }));
+  });
+
+  it("rejects a cursor that loops back to the starting page", async () => {
+    const client = {
+      list: vi.fn().mockResolvedValue({ requests: [], nextPageToken: "start" }),
+    } as unknown as SubmitQueueGatewayClient;
+    const reference = parseChangePath(["github", "github.com", "uber", "submitqueue", "pull", "123"])!;
+    await expect(readChangeSubmissions(client, "demo-queue", reference, { ...window, pageToken: "start" }))
+      .rejects.toMatchObject({ code: Code.Internal });
+  });
+
+  it("fails a looping scan instead of presenting duplicate history", async () => {
     const client = {
       list: vi.fn().mockResolvedValue({ requests: [request("42")], nextPageToken: "repeated" }),
     } as unknown as SubmitQueueGatewayClient;

web/service/submitqueue/src/server/change-reader.ts

@@ -7,12 +7,17 @@ import { REQUEST_PAGE_SIZE, type RequestWindow } from "./window";
 
 const MAX_CHANGE_SCAN_PAGES = 10;
 
+export interface ChangeSubmissionPage {
+  submissions: GatewayChangeSubmission[];
+  nextPageToken: string | null;
+}
+
 export async function readChangeSubmissions(
   client: SubmitQueueGatewayClient,
   queue: string,
   reference: ChangeReference,
   window: RequestWindow,
-): Promise<GatewayChangeSubmission[]> {
+): Promise<ChangeSubmissionPage> {
   const submissions: GatewayChangeSubmission[] = [];
   const appendSubmissions = (requests: readonly GatewayRequestSummary[]) => {
     for (const request of requests) {
@@ -30,10 +35,10 @@ export async function readChangeSubmissions(
   if (reference.uri !== null && reference.scheme !== "git") {
     const response = await client.getRequestSummaryByChangeURI({ queue, changeUri: reference.uri });
     appendSubmissions(response.requests);
-    return submissions;
+    return { submissions, nextPageToken: null };
   }
-  let pageToken = "";
-  const seenTokens = new Set<string>();
+  let pageToken = window.pageToken ?? "";
+  const seenTokens = new Set<string>(pageToken ? [pageToken] : []);
   for (let page = 0; page < MAX_CHANGE_SCAN_PAGES; page += 1) {
     const response = await client.list({
       queue,
@@ -44,14 +49,13 @@ export async function readChangeSubmissions(
     });
     appendSubmissions(response.requests);
     if (!response.nextPageToken) {
-      return submissions;
+      return { submissions, nextPageToken: null };
     }
     if (seenTokens.has(response.nextPageToken)) {
       throw new ConnectError("Repeated queue page token", Code.Internal);
     }
     pageToken = response.nextPageToken;
     seenTokens.add(pageToken);
   }
-  // Never present a truncated queue scan as complete change history.
-  throw new ConnectError("Change receipt window exceeds demo scan budget", Code.ResourceExhausted);
+  return { submissions, nextPageToken: pageToken };
 }

web/submitqueue/src/components.test.tsx

@@ -170,6 +170,27 @@ describe("request components", () => {
     expect(screen.getByRole("link", { name: version }).getAttribute("href")).toBe(`/logical/${version}`);
   });
 
+  it.each([
+    { nextHref: "/change?page=next", latestHref: null },
+    { nextHref: null, latestHref: "/change" },
+  ])("renders page-scoped history and host-provided navigation: %j", pagination => {
+    render(<ChangeSubmissions model={{
+      queue: "demo-queue", provider: "Git", host: "git.example.com",
+      repository: "demo", review: "refs/heads/main", pinnedVersion: null,
+      window: { fromMs: 1, toMs: 2 }, submissions: [], pagination,
+    }} />);
+    expect(screen.getByText("No submissions were found on this page.")).toBeTruthy();
+    expect(screen.queryByText("No submissions were found in this scope.")).toBeNull();
+    expect(screen.getByRole("status").textContent).toContain("Showing matches from this page");
+    if (pagination.nextHref) {
+      expect(screen.getByRole("link", { name: "Continue history scan" }).getAttribute("href")).toBe(pagination.nextHref);
+      expect(screen.getByRole("status").textContent).toContain("More queue requests remain");
+    } else {
+      expect(screen.queryByRole("link", { name: "Continue history scan" })).toBeNull();
+      expect(screen.getByRole("link", { name: "Latest history" }).getAttribute("href")).toBe(pagination.latestHref);
+    }
+  });
+
   it("shows unknown statuses safely", () => {
     render(<RequestStatus status="new_pipeline_step" />);
     expect(screen.getByText("New Pipeline Step").getAttribute("data-tone")).toBe("neutral");

web/submitqueue/src/components.tsx

@@ -227,6 +227,10 @@ export function ChangeSubmissions({ model, basePath, onVersionChange }: ChangeSu
   return <section className="sq-change-detail">
     <nav className="sq-breadcrumb" aria-label="Breadcrumb"><a href={paths.directory()}>Queues</a><span>›</span><a href={paths.requests(model.queue)}>{model.queue}</a><span>› Change</span></nav>
     <h1>{model.review}</h1><p className="sq-secondary">{model.pinnedVersion ? `Submitted version: ${model.pinnedVersion}` : "Submissions across versions"}</p>
+    {model.pagination ? <p className="sq-secondary" role="status">
+      Showing matches from this page of queue requests only.
+      {model.pagination.nextHref ? " More queue requests remain to be searched." : " The history scan is complete for this receipt window."}
+    </p> : null}
     <dl className="sq-change-identity"><div><dt>Provider</dt><dd>{model.provider}</dd></div><div><dt>Host</dt><dd>{model.host}</dd></div><div><dt>Repository</dt><dd>{model.repository || "—"}</dd></div><div><dt>Queue</dt><dd>{model.queue}</dd></div></dl>
     <div className="sq-toolbar"><h2>Submission history</h2>
       {model.logicalHref && onVersionChange && versions.length > 0 ?
@@ -238,11 +242,15 @@ export function ChangeSubmissions({ model, basePath, onVersionChange }: ChangeSu
         model.pinnedVersion !== null && model.logicalHref ? <a href={model.logicalHref}>All submitted versions</a> : null}
     </div>
     {model.window ? <p className="sq-secondary">Receipt window: <Timestamp value={model.window.fromMs} /> — <Timestamp value={model.window.toMs} />. This is not unlimited retained history.</p> : <p className="sq-secondary">Retained submissions for this exact version</p>}
-    {model.submissions.length === 0 ? <p className="sq-empty">No submissions were found in this scope.</p> :
+    {model.submissions.length === 0 ? <p className="sq-empty">{model.pagination ? "No submissions were found on this page." : "No submissions were found in this scope."}</p> :
       <div className="sq-table-scroll"><table aria-label="Change submissions"><thead><tr><th>Request</th><th>Submitted version</th><th>Received · UTC</th><th>Status</th></tr></thead>
         <tbody>{model.submissions.map(item => <tr key={item.request.sqid}><td><a href={paths.request(model.queue, item.request.sqid)}>{item.request.sqid}</a></td>
           <td><a className="sq-version" aria-label={item.version} title={item.version} href={item.versionHref}>{item.version.length > 20 ? `${item.version.slice(0, 8)}…${item.version.slice(-4)}` : item.version}</a></td><td><Timestamp value={item.request.receivedAtMs} /></td>
           <td><RequestStatus status={item.request.status} />{item.request.lastError ? <p className="sq-row-error">{item.request.lastError}</p> : null}</td></tr>)}</tbody></table></div>}
-    <p className="sq-secondary">{model.submissions.length} requests · newest received first · repeated submissions remain separate</p>
+    <p className="sq-secondary">{model.submissions.length} requests{model.pagination ? " on this page" : ""} · newest received first · repeated submissions remain separate</p>
+    {model.pagination ? <nav className="page-actions" aria-label="Change history pagination">
+      {model.pagination.nextHref ? <a href={model.pagination.nextHref}>Continue history scan</a> : null}
+      {model.pagination.latestHref ? <a href={model.pagination.latestHref}>Latest history</a> : null}
+    </nav> : null}
   </section>;
 }

web/submitqueue/src/models.ts

@@ -64,6 +64,7 @@ export interface ChangeDetailModel {
   logicalHref?: string;
   submissions: ChangeSubmissionModel[];
   window: { fromMs: number; toMs: number } | null;
+  pagination?: { nextHref: string | null; latestHref: string | null };
 }
 
 export interface WebError {

web/submitqueue/src/server.test.ts

@@ -4,6 +4,7 @@ import { createFakeGatewayReader, gatewayHistoryFixture, gatewayRequestFixture }
 
 import {
   classifyGatewayError,
+  loadChangeSubmissions,
   loadRequestDetail,
   loadRequestList,
   requestDetailIsComplete,
@@ -14,6 +15,24 @@ import {
 describe("server presentation mapping", () => {
   beforeEach(() => vi.clearAllMocks());
 
+  it.each([false, true])("maps change submissions with optional host pagination (paged: %s)", async paged => {
+    const request = gatewayRequestFixture();
+    const submissions = [{
+      request, version: "sha", versionHref: "/change/sha",
+    }];
+    const pagination = { nextHref: "/change?page=next", latestHref: null };
+    const result = await loadChangeSubmissions(async () => paged ? { submissions, pagination } : submissions, {
+      queue: "demo-queue", provider: "Git", host: "git.example.com",
+      repository: "demo", review: "refs/heads/main", pinnedVersion: null, window: { fromMs: 100, toMs: 200 },
+    });
+    expect(result).toMatchObject({
+      ok: true, data: { submissions: [{ request: { sqid: request.sqid }, version: "sha" }] },
+    });
+    if (result.ok) {
+      expect(result.data.pagination).toEqual(paged ? pagination : undefined);
+    }
+  });
+
   it("converts int64 only within JavaScript's safe range", () => {
     expect(safeInt64ToNumber(1_700_000_000_000n)).toBe(1_700_000_000_000);
     expect(safeInt64ToNumber(BigInt(Number.MAX_SAFE_INTEGER) + 1n)).toBeNull();

web/submitqueue/src/server.ts

@@ -370,24 +370,31 @@ export interface GatewayChangeSubmission {
   versionHref: string;
 }
 
+export interface GatewayChangeSubmissionPage {
+  submissions: readonly GatewayChangeSubmission[];
+  pagination?: ChangeDetailModel["pagination"];
+}
+
 export async function loadChangeSubmissions(
-  read: () => Promise<readonly GatewayChangeSubmission[]>,
+  read: () => Promise<readonly GatewayChangeSubmission[] | GatewayChangeSubmissionPage>,
   context: Omit<ChangeDetailModel, "submissions">,
   options: GatewayLoadOptions = {},
 ): Promise<LoadResult<ChangeDetailModel>> {
   if (!context.queue) {
     return { ok: false, error: INVALID_INPUT };
   }
   try {
+    const response = await read();
+    const page: GatewayChangeSubmissionPage = "submissions" in response ? response : { submissions: response };
     const submissions: ChangeDetailModel["submissions"] = [];
-    for (const item of await read()) {
+    for (const item of page.submissions) {
       const request = mapRequestSummary(item.request);
       if (!request) {
         return { ok: false, error: INTERNAL_ERROR };
       }
       submissions.push({ request, version: item.version, versionHref: item.versionHref });
     }
-    return { ok: true, data: { ...context, submissions } };
+    return { ok: true, data: { ...context, submissions, ...(page.pagination ? { pagination: page.pagination } : {}) } };
   } catch (error) {
     reportGatewayError(options, "change", context.queue, null, error);
     return { ok: false, error: classifyGatewayError(error) };