pr-shepherd 0.56.5 → 0.57.0

package/bin/github/stack-handoff-page.mjs

@@ -0,0 +1,306 @@
+/**
+ * A routed stack layer's `BatchPr` first page, rebuilt from the stack summary
+ * that routed it. See `stack-handoff.mts` for when a handoff is stored and read.
+ */
+const MAX_THREAD_COMMENTS = 5;
+const MAX_REVIEW_BUCKET = 50;
+const MAX_LATEST_REVIEWS = 50;
+const MAX_CONTEXTS = 100;
+const MAX_STACK_ENTRIES = 50;
+function headCommit(layer) {
+    return layer.commits.nodes[0]?.commit;
+}
+export function checkRunIds(layer) {
+    return (headCommit(layer)?.statusCheckRollup?.contexts.nodes ?? []).flatMap((node) => node.__typename === "CheckRun" && node.id ? [node.id] : []);
+}
+function reviewsIn(layer, state) {
+    return layer.reviews.nodes.filter((review) => review.state === state);
+}
+/** True when every window `BatchPr`'s first page reads is complete in this summary. */
+export function summaryComplete(layer, source) {
+    const { read } = source;
+    if (!read.stack || read.viewerPermission === undefined || !read.mergeSettings)
+        return false;
+    if (source.layers.length > MAX_STACK_ENTRIES || !layer.stack || !layer.stackEntry)
+        return false;
+    if (layer.state !== "OPEN" || layer.id === undefined || layer.viewerDidAuthor === undefined)
+        return false;
+    if (layer.isInMergeQueue || layer.mergeQueueEntry || layer.mergeQueueRemovals?.nodes.length)
+        return false;
+    if (layer.comments.pageInfo.hasPreviousPage ||
+        layer.reviews.pageInfo.hasPreviousPage ||
+        layer.reviewThreads.pageInfo.hasPreviousPage ||
+        layer.reviewThreads.nodes.some((thread) => thread.comments.pageInfo.hasPreviousPage ||
+            thread.comments.nodes.length > MAX_THREAD_COMMENTS))
+        return false;
+    if (["CHANGES_REQUESTED", "COMMENTED", "APPROVED"].some((state) => reviewsIn(layer, state).length > MAX_REVIEW_BUCKET))
+        return false;
+    if ((layer.latestReviews?.nodes.length ?? MAX_LATEST_REVIEWS) >= MAX_LATEST_REVIEWS)
+        return false;
+    if (!layer.reviewRequests || layer.commits.totalCount === undefined)
+        return false;
+    const commit = headCommit(layer);
+    if (!commit || commit.oid !== layer.headRefOid || !commit.checkSuites?.pageInfo)
+        return false;
+    const contexts = commit.statusCheckRollup?.contexts;
+    if (contexts &&
+        (contexts.pageInfo.hasPreviousPage ||
+            contexts.totalCount > MAX_CONTEXTS ||
+            contexts.nodes.length !== contexts.totalCount))
+        return false;
+    return true;
+}
+const firstPage = { hasPreviousPage: false, startCursor: null };
+const lastPage = { hasNextPage: false, endCursor: null };
+/** The `BatchPr` first page this layer's summary answers, field by field; null if incomplete. */
+export function batchResponseFromSummary(layer, source, runs) {
+    if (!summaryComplete(layer, source))
+        return null;
+    const commit = headCommit(layer);
+    const rollup = commit.statusCheckRollup;
+    const contexts = [];
+    for (const node of rollup?.contexts.nodes ?? []) {
+        if (node.__typename === "StatusContext") {
+            contexts.push({
+                __typename: "StatusContext",
+                context: node.context,
+                state: node.state,
+                ...(node.createdAt !== undefined && { createdAt: node.createdAt }),
+                targetUrl: node.targetUrl ?? null,
+                description: node.description ?? null,
+            });
+            continue;
+        }
+        const run = node.id ? runs.get(node.id) : undefined;
+        if (!run)
+            return null;
+        const suite = node.checkSuite;
+        const workflowRun = suite?.workflowRun;
+        contexts.push({
+            __typename: "CheckRun",
+            id: node.id,
+            name: node.name,
+            status: node.status,
+            conclusion: node.conclusion,
+            detailsUrl: node.detailsUrl ?? null,
+            completedAt: node.completedAt ?? null,
+            startedAt: node.startedAt ?? null,
+            title: run.title,
+            summary: run.summary,
+            ...(run.annotations && { annotations: run.annotations }),
+            checkSuite: suite
+                ? {
+                    ...(suite.createdAt && { createdAt: suite.createdAt }),
+                    ...(suite.updatedAt && { updatedAt: suite.updatedAt }),
+                    workflowRun: workflowRun
+                        ? {
+                            event: workflowRun.event,
+                            ...(workflowRun.createdAt && { createdAt: workflowRun.createdAt }),
+                            ...(workflowRun.updatedAt && { updatedAt: workflowRun.updatedAt }),
+                            workflow: workflowRun.workflow
+                                ? {
+                                    name: workflowRun.workflow.name,
+                                    databaseId: workflowRun.workflow.databaseId,
+                                }
+                                : null,
+                        }
+                        : null,
+                }
+                : null,
+        });
+    }
+    const { read } = source;
+    const stack = read.stack;
+    const bottom = source.layers[0];
+    const reviewSummary = (review) => ({
+        id: review.id,
+        isMinimized: review.isMinimized === true,
+        viewerCanMinimize: review.viewerCanMinimize === true,
+        authorAssociation: review.authorAssociation,
+        author: review.author,
+        body: review.body,
+        createdAt: review.createdAt,
+        url: review.url,
+    });
+    const pullRequest = {
+        id: layer.id,
+        number: layer.number,
+        updatedAt: layer.updatedAt,
+        state: layer.state,
+        isDraft: layer.isDraft,
+        viewerDidAuthor: layer.viewerDidAuthor === true,
+        viewerCanUpdate: layer.viewerCanUpdate === true,
+        viewerCanEnableAutoMerge: layer.viewerCanEnableAutoMerge === true,
+        viewerCanEditFiles: layer.viewerCanEditFiles === true,
+        mergeable: layer.mergeable,
+        mergeStateStatus: layer.mergeStateStatus,
+        reviewDecision: layer.reviewDecision,
+        headRefOid: layer.headRefOid,
+        headRefName: layer.headRefName,
+        headRepository: layer.headRepository ?? null,
+        baseRefName: layer.baseRefName,
+        baseRefOid: layer.baseRefOid,
+        baseRef: layer.baseRef ?? null,
+        isInMergeQueue: false,
+        isMergeQueueEnabled: layer.isMergeQueueEnabled === true,
+        autoMergeRequest: layer.batchAutoMergeRequest ?? null,
+        mergeQueueEntry: null,
+        mergeQueueAdditions: layer.mergeQueueAdditions ?? { nodes: [] },
+        mergeQueueRemovals: { nodes: [] },
+        mergeQueueRemovalTimes: { nodes: [] },
+        headRefForcePushes: layer.headRefForcePushes ?? { nodes: [] },
+        stack: {
+            id: stack.id,
+            number: layer.stack.number,
+            size: layer.stack.size,
+            baseRefName: layer.stack.baseRefName,
+            entries: {
+                pageInfo: lastPage,
+                nodes: source.layers.map((member, index) => ({
+                    position: stack.positions[index],
+                    pullRequest: {
+                        number: member.number,
+                        state: member.state,
+                        headRefName: member.headRefName,
+                        headRefOid: member.headRefOid,
+                        baseRefName: member.baseRefName,
+                        baseRefOid: member.baseRefOid,
+                    },
+                })),
+            },
+            trunkEntry: {
+                nodes: [
+                    { pullRequest: { baseRefName: bottom.baseRefName, baseRef: bottom.baseRef ?? null } },
+                ],
+            },
+        },
+        stackEntry: layer.stackEntry,
+        reviewRequests: {
+            nodes: layer.reviewRequests.nodes.map(({ requestedReviewer: reviewer }) => ({
+                requestedReviewer: !reviewer
+                    ? null
+                    : reviewer.__typename === "Team"
+                        ? { name: reviewer.name }
+                        : reviewer.__typename === "User" || reviewer.__typename === "Bot"
+                            ? { login: reviewer.login }
+                            : {},
+            })),
+        },
+        latestReviews: {
+            nodes: layer.latestReviews.nodes.map((review) => ({
+                author: review.author,
+                state: review.state,
+            })),
+        },
+        reviewThreads: {
+            totalCount: layer.reviewThreads.totalCount,
+            pageInfo: firstPage,
+            nodes: layer.reviewThreads.nodes.map((thread) => ({
+                id: thread.id,
+                isResolved: thread.isResolved,
+                isOutdated: thread.isOutdated,
+                viewerCanReply: thread.viewerCanReply,
+                viewerCanResolve: thread.viewerCanResolve,
+                path: thread.path,
+                line: thread.line ?? null,
+                startLine: thread.startLine ?? null,
+                comments: {
+                    pageInfo: lastPage,
+                    nodes: thread.comments.nodes.map((comment) => ({
+                        id: comment.id,
+                        isMinimized: comment.isMinimized,
+                        url: comment.url,
+                        authorAssociation: comment.authorAssociation,
+                        viewerDidAuthor: comment.viewerDidAuthor,
+                        author: comment.author,
+                        pullRequestReview: comment.pullRequestReview ?? null,
+                        body: comment.body,
+                        path: comment.path ?? null,
+                        line: comment.line ?? null,
+                        startLine: comment.startLine ?? null,
+                        createdAt: comment.createdAt,
+                        updatedAt: comment.updatedAt,
+                    })),
+                },
+            })),
+        },
+        comments: {
+            totalCount: layer.comments.totalCount,
+            pageInfo: firstPage,
+            nodes: layer.comments.nodes.map((comment) => ({
+                id: comment.id,
+                isMinimized: comment.isMinimized === true,
+                viewerCanMinimize: comment.viewerCanMinimize === true,
+                url: comment.url,
+                authorAssociation: comment.authorAssociation,
+                author: comment.author,
+                body: comment.body,
+                createdAt: comment.createdAt,
+                updatedAt: comment.updatedAt,
+            })),
+        },
+        changesRequestedReviews: {
+            pageInfo: firstPage,
+            nodes: reviewsIn(layer, "CHANGES_REQUESTED").map((review) => ({
+                id: review.id,
+                authorAssociation: review.authorAssociation,
+                author: review.author,
+                body: review.body,
+                createdAt: review.createdAt,
+                ...(review.commit && { commit: review.commit }),
+            })),
+        },
+        reviewSummaries: {
+            pageInfo: firstPage,
+            nodes: reviewsIn(layer, "COMMENTED").map(reviewSummary),
+        },
+        allReviews: {
+            totalCount: layer.reviews.totalCount,
+            nodes: layer.reviews.nodes.map((review) => ({ id: review.id, updatedAt: review.updatedAt })),
+        },
+        approvedReviews: {
+            pageInfo: firstPage,
+            nodes: reviewsIn(layer, "APPROVED").map(reviewSummary),
+        },
+        commits: {
+            totalCount: layer.commits.totalCount,
+            nodes: [
+                {
+                    commit: {
+                        oid: commit.oid,
+                        committedDate: commit.committedDate,
+                        checkSuites: {
+                            pageInfo: commit.checkSuites.pageInfo,
+                            nodes: commit.checkSuites.nodes.map((suite) => ({
+                                id: suite.id,
+                                status: suite.status,
+                                conclusion: suite.conclusion,
+                                workflowRun: suite.workflowRun
+                                    ? {
+                                        databaseId: suite.workflowRun.databaseId ?? null,
+                                        event: suite.workflowRun.event,
+                                        url: suite.workflowRun.url ?? null,
+                                        workflow: suite.workflowRun.workflow ?? null,
+                                    }
+                                    : null,
+                            })),
+                        },
+                        statusCheckRollup: rollup
+                            ? { state: rollup.state ?? null, contexts: { pageInfo: lastPage, nodes: contexts } }
+                            : null,
+                    },
+                },
+            ],
+        },
+    };
+    return {
+        viewer: { login: read.viewerLogin },
+        repository: {
+            viewerPermission: read.viewerPermission ?? null,
+            viewerCanAdminister: read.viewerCanAdminister === true,
+            ...read.mergeSettings,
+            pullRequest,
+            receiptSummary: structuredClone(layer),
+        },
+    };
+}

package/bin/github/stack-handoff.d.mts

@@ -0,0 +1,16 @@
+import { type RepoInfo } from "./client.mts";
+import type { RawBatchResponse } from "./batch-raw-types.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+import { type StackHandoffSource } from "./stack-handoff-page.mts";
+import type { StackRead } from "./stack-read.mts";
+/** Snapshot the summary read so later projection cannot change what a handoff carries. */
+export declare function stackHandoffSource(read: StackRead<RawSummaryPr>): StackHandoffSource;
+/**
+ * Store a handoff for each routed layer whose summary is complete, and clear any
+ * earlier handoff for every other layer this read covers. Check-run titles,
+ * summaries, and first annotations are not in the summary, so one `nodes(ids:)`
+ * read per 100 runs fills them in. Best effort: a failed read stores nothing.
+ */
+export declare function writeStackHandoffs(source: StackHandoffSource, routed: number[], repo: RepoInfo): Promise<void>;
+/** The stored first page for `pr`, once: the read deletes it. Null when absent or stale. */
+export declare function takeStackHandoff(repo: RepoInfo, pr: number, now?: number): Promise<RawBatchResponse | null>;

package/bin/github/stack-handoff.mjs

@@ -0,0 +1,115 @@
+import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
+import { graphqlWithRateLimit } from "./client.mjs";
+import { STACK_HANDOFF_CHECK_RUNS_QUERY } from "./queries.mjs";
+import { batchResponseFromSummary, checkRunIds, summaryComplete, } from "./stack-handoff-page.mjs";
+import { getGithubTransport } from "./transport.mjs";
+/**
+ * Routed stack layers reuse the stack summary's read.
+ *
+ * The stack tick that routes owned layers to their one-PR sessions already read
+ * each layer's head, reviews, threads, comments, and checks. It stores that
+ * read, reshaped into a `BatchPr` first page, under each routed layer. The
+ * layer's next `BatchPr` read consumes it once instead of asking GitHub again.
+ *
+ * Freshness: a handoff is the routing tick's own read of the layer's current
+ * head. It is consumed by the first read only, deleted on that read, and
+ * ignored once it is older than `HANDOFF_TTL_MS`. Every later read, including
+ * the one-PR poll's debounce re-read, asks GitHub.
+ *
+ * Completeness: a layer gets a handoff only when every window `BatchPr` reads
+ * on its first page is complete in the summary. Anything wider, queued, or
+ * removed from a queue reads `BatchPr` as before.
+ */
+const HANDOFF = "stack-handoff";
+const HANDOFF_TTL_MS = 2 * 60_000;
+const MAX_RUNS_PER_QUERY = 100;
+const stateKey = (repo, pr) => ({
+    owner: repo.owner,
+    repo: repo.name,
+    pr,
+});
+/** Snapshot the summary read so later projection cannot change what a handoff carries. */
+export function stackHandoffSource(read) {
+    const { ordered, ...rest } = read;
+    return { read: rest, layers: structuredClone(ordered), readAt: Date.now() };
+}
+/**
+ * Store a handoff for each routed layer whose summary is complete, and clear any
+ * earlier handoff for every other layer this read covers. Check-run titles,
+ * summaries, and first annotations are not in the summary, so one `nodes(ids:)`
+ * read per 100 runs fills them in. Best effort: a failed read stores nothing.
+ */
+export async function writeStackHandoffs(source, routed, repo) {
+    if (getGithubTransport() === "rest")
+        return;
+    const candidates = source.layers.filter((layer) => routed.includes(layer.number) && summaryComplete(layer, source));
+    // This read supersedes every earlier handoff, including for layers no longer routed.
+    for (const layer of source.layers) {
+        if (!candidates.includes(layer))
+            await clearStackHandoff(repo, layer.number);
+    }
+    if (candidates.length === 0)
+        return;
+    const runIds = [...new Set(candidates.flatMap(checkRunIds))];
+    let runs;
+    try {
+        runs = await readCheckRuns(runIds);
+    }
+    catch {
+        for (const layer of candidates)
+            await clearStackHandoff(repo, layer.number);
+        return;
+    }
+    for (const layer of candidates) {
+        const response = batchResponseFromSummary(layer, source, runs);
+        if (!response) {
+            await clearStackHandoff(repo, layer.number);
+            continue;
+        }
+        const stored = {
+            readAt: source.readAt,
+            headRefOid: layer.headRefOid,
+            response,
+        };
+        await storeDerived(stateKey(repo, layer.number), HANDOFF, stored, layer.headRefOid);
+    }
+}
+/** The stored first page for `pr`, once: the read deletes it. Null when absent or stale. */
+export async function takeStackHandoff(repo, pr, now = Date.now()) {
+    const entry = await loadDerived(stateKey(repo, pr), HANDOFF);
+    const stored = entry?.value;
+    if (!stored)
+        return null;
+    await clearStackHandoff(repo, pr);
+    const age = now - stored.readAt;
+    if (!(age >= 0 && age <= HANDOFF_TTL_MS))
+        return null;
+    const head = stored.response.repository?.pullRequest?.headRefOid;
+    if (!head || head !== stored.headRefOid)
+        return null;
+    return stored.response;
+}
+async function clearStackHandoff(repo, pr) {
+    const entry = await loadDerived(stateKey(repo, pr), HANDOFF);
+    if (entry?.value)
+        await storeDerived(stateKey(repo, pr), HANDOFF, null);
+}
+async function readCheckRuns(ids) {
+    const runs = new Map();
+    for (let offset = 0; offset < ids.length; offset += MAX_RUNS_PER_QUERY) {
+        const chunk = ids.slice(offset, offset + MAX_RUNS_PER_QUERY);
+        const result = await graphqlWithRateLimit(STACK_HANDOFF_CHECK_RUNS_QUERY, {
+            ids: chunk,
+        });
+        for (const node of result.data.nodes) {
+            if (node?.__typename !== "CheckRun" || !node.id || !node.annotations)
+                continue;
+            runs.set(node.id, {
+                title: node.title ?? null,
+                summary: node.summary ?? null,
+                annotations: node.annotations,
+            });
+        }
+    }
+    return runs;
+}

package/bin/github/stack-order.d.mts

@@ -0,0 +1,6 @@
+import type { StackMemberRefs } from "./stack-read.mts";
+/** Bottom-to-top members, or an error unless every member and the anchor were observed. */
+export declare function orderedStackMembers<Pr extends StackMemberRefs>(entries: ReadonlyArray<{
+    position: number;
+    pullRequest: Pr;
+}>, anchor: number, stackSize: number): Pr[];

package/bin/github/stack-order.mjs

@@ -0,0 +1,13 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+/** Bottom-to-top members, or an error unless every member and the anchor were observed. */
+export function orderedStackMembers(entries, anchor, stackSize) {
+    const unique = new Map();
+    for (const entry of entries)
+        unique.set(entry.pullRequest.number, entry);
+    if (!unique.has(anchor) || unique.size !== stackSize) {
+        throw new ShepherdError(`GitHub returned incomplete stack membership (${unique.size} of ${stackSize} entries)`, EXIT.TEMPFAIL);
+    }
+    return [...unique.values()]
+        .sort((left, right) => left.position - right.position)
+        .map((entry) => entry.pullRequest);
+}

package/bin/github/stack-read.d.mts

@@ -1,6 +1,8 @@
 import { type MergeMethod } from "../config/merge-method.mts";
 import type { PollSummaryStackAncestry } from "../types.mts";
 import { type RepoInfo } from "./client.mts";
+import { type StackHandoffContext } from "./stack-handoff-context.mts";
+export { verifiedBottomOpenLayer } from "./stack-bottom.mts";
 /** GitHub's `first` ceiling for one native-stack entries page. */
 export declare const MAX_STACK_ENTRIES_PER_PAGE = 50;
 /** Fields every native-stack read needs to validate membership and adjacent ancestry. */
@@ -13,11 +15,11 @@ export interface StackMemberRefs {
     baseRefOid: string;
 }
 /** One complete, validated native-stack membership read. */
-export interface StackRead<Pr extends StackMemberRefs> {
+export interface StackRead<Pr extends StackMemberRefs> extends StackHandoffContext {
     stackNumber: number;
     stackSize: number;
     viewerLogin: string | null;
-    viewerCanAdminister: boolean;
+    viewerCanAdminister?: boolean;
     /** Every member, bottom-to-top, each observed in the same paged read. */
     ordered: Pr[];
     /** Present when the query selected repository merge settings, including an empty list. */
@@ -28,7 +30,9 @@ export interface StackRead<Pr extends StackMemberRefs> {
  * membership: a missing repository, PR, or stack; a changed stack identity; a
  * null entry; a page without a cursor; or fewer unique members than `size`.
  */
-export declare function readStack<Pr extends StackMemberRefs>(query: string, anchor: number, repo: RepoInfo, variables?: Record<string, unknown>): Promise<StackRead<Pr>>;
+export declare function readStack<Pr extends StackMemberRefs>(query: string, anchor: number, repo: RepoInfo, initialVariables?: Record<string, unknown>, 
+/** Largest `first` a later page may request; defaults to the first page's `first`. */
+pageCeiling?: number): Promise<StackRead<Pr>>;
 /** Membership and linking refs only — no per-PR CI or review hydration. */
 export declare function readStackTopology(anchor: number, repo: RepoInfo): Promise<StackRead<StackMemberRefs>>;
 /**

package/bin/github/stack-read.mjs

@@ -1,8 +1,13 @@
+import { githubOperation } from "./transport.mjs";
+import { readRestStackTopology } from "./rest-stack-read.mjs";
 import { readAllowedMergeMethods } from "../config/merge-method.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { missingRepositoryError } from "./errors.mjs";
 import { POLL_STACK_TOPOLOGY_QUERY } from "./queries.mjs";
+import { orderedStackMembers } from "./stack-order.mjs";
+import { stackHandoffContext } from "./stack-handoff-context.mjs";
+export { verifiedBottomOpenLayer } from "./stack-bottom.mjs";
 /** GitHub's `first` ceiling for one native-stack entries page. */
 export const MAX_STACK_ENTRIES_PER_PAGE = 50;
 /**
@@ -10,13 +15,17 @@ export const MAX_STACK_ENTRIES_PER_PAGE = 50;
  * membership: a missing repository, PR, or stack; a changed stack identity; a
  * null entry; a page without a cursor; or fewer unique members than `size`.
  */
-export async function readStack(query, anchor, repo, variables = {}) {
+export async function readStack(query, anchor, repo, initialVariables = {}, 
+/** Largest `first` a later page may request; defaults to the first page's `first`. */
+pageCeiling) {
+    let variables = initialVariables;
     let after = null;
     let stackId = null;
     let stackNumber = 0;
     let stackSize = 0;
     let viewerCanAdminister = false;
     let viewerLogin = null;
+    let settings = null;
     let allowedMergeMethods;
     const entries = [];
     do {
@@ -26,6 +35,7 @@ export async function readStack(query, anchor, repo, variables = {}) {
         if (!repository)
             throw missingRepositoryError(repo);
         viewerCanAdminister = repository.viewerCanAdminister;
+        settings = repository;
         allowedMergeMethods = readAllowedMergeMethods(repository) ?? allowedMergeMethods;
         if (!repository.pullRequest) {
             throw new ShepherdError(`PR #${anchor} not found`, EXIT.UNAVAILABLE);
@@ -54,16 +64,16 @@ export async function readStack(query, anchor, repo, variables = {}) {
             throw new ShepherdError("GitHub stack pagination returned a repeated end cursor", EXIT.TEMPFAIL);
         }
         after = pageInfo.hasNextPage ? pageInfo.endCursor : null;
+        // A later page never asks for more slots than remain: GitHub prices `first`.
+        if (after !== null && typeof variables.first === "number") {
+            const ceiling = pageCeiling ?? variables.first;
+            variables = {
+                ...variables,
+                first: Math.max(1, Math.min(ceiling, stackSize - entries.length)),
+            };
+        }
     } while (after !== null);
-    const unique = new Map();
-    for (const entry of entries)
-        unique.set(entry.pullRequest.number, entry);
-    if (!unique.has(anchor) || unique.size !== stackSize) {
-        throw new ShepherdError(`GitHub returned incomplete stack membership (${unique.size} of ${stackSize} entries)`, EXIT.TEMPFAIL);
-    }
-    const ordered = [...unique.values()]
-        .sort((left, right) => left.position - right.position)
-        .map((entry) => entry.pullRequest);
+    const ordered = orderedStackMembers(entries, anchor, stackSize);
     return {
         stackNumber,
         stackSize,
@@ -71,11 +81,12 @@ export async function readStack(query, anchor, repo, variables = {}) {
         viewerCanAdminister,
         ordered,
         ...(allowedMergeMethods && { allowedMergeMethods }),
+        ...stackHandoffContext(settings, stackId, entries, ordered),
     };
 }
 /** Membership and linking refs only — no per-PR CI or review hydration. */
 export function readStackTopology(anchor, repo) {
-    return readStack(POLL_STACK_TOPOLOGY_QUERY, anchor, repo);
+    return githubOperation("PollStackTopology", () => readStack(POLL_STACK_TOPOLOGY_QUERY, anchor, repo), () => readRestStackTopology(anchor, repo));
 }
 /**
  * Adjacent entries, both open, whose child base no longer matches the parent

package/bin/github/stack-size-hint.d.mts

@@ -0,0 +1,3 @@
+import { type StateKey } from "../state/rest-cache.mts";
+export declare function loadStackSizeHint(key: StateKey): Promise<number>;
+export declare function storeStackSizeHint(key: StateKey, stackSize: number): Promise<void>;

package/bin/github/stack-size-hint.mjs

@@ -0,0 +1,14 @@
+import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
+/**
+ * The stack size the anchor's last summary observed. It only sizes the next
+ * summary page, so a stale value costs a page or a few unused slots, never a
+ * wrong answer: `readStack` still validates the full membership.
+ */
+const STACK_SIZE_HINT = "stack-size";
+export async function loadStackSizeHint(key) {
+    const value = (await loadDerived(key, STACK_SIZE_HINT))?.value;
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : 0;
+}
+export async function storeStackSizeHint(key, stackSize) {
+    await storeDerived(key, STACK_SIZE_HINT, stackSize);
+}

package/bin/github/suggestion-thread.mjs

@@ -1,7 +1,11 @@
+import { githubOperation } from "./transport.mjs";
+import { readRestFeedback } from "./rest-feedback-read.mjs";
+import { readRestPull } from "./rest-pr-core.mjs";
+import { resolveRestThreadRoot, restThreadId } from "./rest-identities.mjs";
 import { graphql } from "./client.mjs";
 import { SUGGESTION_THREADS_QUERY } from "./queries.mjs";
 import { mapAuthorType, parseCreatedAt } from "./batch-parser-helpers.mjs";
-export async function fetchSuggestionThreads(pr, repo, threadIds) {
+async function fetchGraphqlSuggestionThreads(pr, repo, threadIds) {
     const result = await graphql(SUGGESTION_THREADS_QUERY, {
         owner: repo.owner,
         repo: repo.name,
@@ -47,3 +51,25 @@ function parseThread(raw, pr, threadId) {
         createdAtUnix: comment?.createdAt ? parseCreatedAt(comment.createdAt) : 0,
     };
 }
+export function fetchSuggestionThreads(pr, repo, threadIds) {
+    return githubOperation("SuggestionThreads", () => fetchGraphqlSuggestionThreads(pr, repo, threadIds), async () => {
+        const pull = await readRestPull(pr, repo);
+        const feedback = await readRestFeedback(pr, repo);
+        const threads = await Promise.all(threadIds.map(async (id) => {
+            try {
+                const root = await resolveRestThreadRoot(repo, pr, id);
+                const found = feedback.threads.find((thread) => thread.id === restThreadId(root));
+                return found ? { ...found, id } : null;
+            }
+            catch {
+                return null;
+            }
+        }));
+        return {
+            headRefOid: pull.head.sha,
+            headRefName: pull.head.ref,
+            headRepoWithOwner: pull.head.repo?.full_name ?? null,
+            threads,
+        };
+    });
+}

package/bin/github/thread-comments.mjs

@@ -1,10 +1,12 @@
+import { githubOperation } from "./transport.mjs";
+import { readRestRawThread } from "./rest-thread-read.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 import { paginateForward } from "./pagination.mjs";
 import { REVIEW_THREAD_COMMENTS_QUERY } from "./queries.mjs";
 import { mapPool } from "../util/pool.mjs";
 const THREAD_COMMENT_PAGE_CONCURRENCY = 4;
-export async function hydrateThreadCommentPages(threads, initialRateLimit) {
+async function hydrateGraphqlThreadCommentPages(threads, initialRateLimit) {
     const gate = {
         rateLimit: initialRateLimit,
         exhausted: initialRateLimit?.remaining === 0,
@@ -60,3 +62,9 @@ async function hydrateThreadCommentPage(thread, gate) {
         },
     };
 }
+export function hydrateThreadCommentPages(threads, initialRateLimit) {
+    return githubOperation("ReviewThreadComments", () => hydrateGraphqlThreadCommentPages(threads, initialRateLimit), async () => ({
+        threads: await mapPool(threads, THREAD_COMMENT_PAGE_CONCURRENCY, async (thread) => thread.comments.pageInfo?.hasNextPage ? readRestRawThread(thread.id) : thread),
+        rateLimit: initialRateLimit,
+    }));
+}