pr-shepherd 0.56.6 → 0.57.1

package/bin/github/api-telemetry-aggregate.mjs

@@ -1,9 +1,11 @@
+import { mostConservativeSample } from "./rate-limit-sample.mjs";
 export function emptyAggregate() {
     return {
         eventCount: 0,
         credentialSources: new Map(),
         graphql: { requestCount: 0, measuredQueryCost: 0, unmeasuredRequestCount: 0, nodeCount: 0 },
         rest: new Map(),
+        unmeteredRestRequestCount: 0,
     };
 }
 export function aggregateEvents(events) {
@@ -25,12 +27,19 @@ export function aggregateEvents(events) {
             }
             continue;
         }
-        const resource = event.rateLimit?.resource ?? "unknown";
-        const group = aggregate.rest.get(resource) ?? { requestCount: 0 };
-        group.requestCount += 1;
-        if (event.rateLimit !== undefined) {
-            group.rateLimit = selectAuthoritativeRateLimit(group.rateLimit, event.rateLimit);
+        if (event.rateLimit === undefined && !event.notModified) {
+            aggregate.unmeteredRestRequestCount += 1;
+            continue;
         }
+        const resource = event.rateLimit?.resource ?? (event.notModified ? "core" : "unknown");
+        const group = aggregate.rest.get(resource) ?? { requestCount: 0, notModifiedCount: 0 };
+        if (event.notModified)
+            group.notModifiedCount += 1;
+        else
+            group.requestCount += 1;
+        const sample = event.rateLimit;
+        if (sample)
+            adoptRestRateLimit(group, sample, event.credentialFingerprint, event.sequence);
         aggregate.rest.set(resource, group);
     }
     return aggregate;
@@ -47,14 +56,16 @@ export function mergeAggregate(target, source) {
     target.graphql.measuredQueryCost += source.graphql.measuredQueryCost;
     target.graphql.unmeasuredRequestCount += source.graphql.unmeasuredRequestCount;
     target.graphql.nodeCount += source.graphql.nodeCount;
+    target.unmeteredRestRequestCount += source.unmeteredRestRequestCount;
     if (source.graphql.rateLimit !== undefined) {
         adoptGraphqlRateLimit(target.graphql, source.graphql.rateLimit, source.graphql.credentialFingerprint);
     }
     for (const [resource, sourceGroup] of source.rest) {
-        const targetGroup = target.rest.get(resource) ?? { requestCount: 0 };
+        const targetGroup = target.rest.get(resource) ?? { requestCount: 0, notModifiedCount: 0 };
         targetGroup.requestCount += sourceGroup.requestCount;
+        targetGroup.notModifiedCount += sourceGroup.notModifiedCount;
         if (sourceGroup.rateLimit !== undefined) {
-            targetGroup.rateLimit = selectAuthoritativeRateLimit(targetGroup.rateLimit, sourceGroup.rateLimit);
+            adoptRestRateLimit(targetGroup, sourceGroup.rateLimit, sourceGroup.credentialFingerprint, sourceGroup.latestCredentialSequence, sourceGroup.latestCredentialFingerprint ?? sourceGroup.credentialFingerprint, sourceGroup.latestCredentialSequence);
         }
         target.rest.set(resource, targetGroup);
     }
@@ -66,25 +77,53 @@ export function aggregateStore(active) {
     return all;
 }
 function adoptGraphqlRateLimit(graphql, candidate, fingerprint) {
-    const next = selectAuthoritativeRateLimit(graphql.rateLimit, candidate);
+    // Two credentials' samples are compared whole, never mixed: a mixed sample would be
+    // attributed to whichever credential supplied the changed half.
+    const sameCredential = fingerprint === undefined ||
+        graphql.credentialFingerprint === undefined ||
+        fingerprint === graphql.credentialFingerprint;
+    const next = selectAuthoritativeRateLimit(graphql.rateLimit, candidate, sameCredential);
     if (next !== graphql.rateLimit)
         graphql.credentialFingerprint = fingerprint;
     graphql.rateLimit = next;
 }
-function selectAuthoritativeRateLimit(current, candidate) {
+function adoptRestRateLimit(group, candidate, fingerprint, sequence, latestCredentialFingerprint = fingerprint, latestCredentialSequence = sequence) {
+    const credentialChanged = group.latestCredentialFingerprint !== undefined &&
+        latestCredentialFingerprint !== undefined &&
+        group.latestCredentialFingerprint !== latestCredentialFingerprint;
+    const olderCredentialObservation = credentialChanged &&
+        group.latestCredentialSequence !== undefined &&
+        latestCredentialSequence !== undefined &&
+        latestCredentialSequence < group.latestCredentialSequence;
+    if (olderCredentialObservation)
+        return;
+    if (group.rateLimit === undefined || credentialChanged) {
+        group.rateLimit = { ...candidate };
+        group.credentialFingerprint = fingerprint;
+    }
+    else {
+        const next = selectAuthoritativeRateLimit(group.rateLimit, candidate);
+        if (next !== group.rateLimit) {
+            group.rateLimit = next;
+            group.credentialFingerprint = fingerprint;
+        }
+    }
+    if (latestCredentialFingerprint !== undefined &&
+        (group.latestCredentialSequence === undefined ||
+            latestCredentialSequence === undefined ||
+            latestCredentialSequence >= group.latestCredentialSequence)) {
+        group.latestCredentialFingerprint = latestCredentialFingerprint;
+        group.latestCredentialSequence = latestCredentialSequence;
+    }
+}
+function selectAuthoritativeRateLimit(current, candidate, sameCredential = true) {
     if (current === undefined)
         return { ...candidate };
     if (candidate.resetAt !== current.resetAt) {
         return candidate.resetAt > current.resetAt ? { ...candidate } : current;
     }
-    if (candidate.remaining !== current.remaining) {
+    if (!sameCredential)
         return candidate.remaining < current.remaining ? { ...candidate } : current;
-    }
-    if (candidate.used !== current.used) {
-        if (candidate.used === undefined)
-            return current;
-        if (current.used === undefined || candidate.used > current.used)
-            return { ...candidate };
-    }
-    return current;
+    const merged = mostConservativeSample(current, candidate);
+    return merged.remaining === current.remaining && merged.used === current.used ? current : merged;
 }

package/bin/github/api-telemetry.d.mts

@@ -7,6 +7,8 @@ export interface ApiTelemetryEvent {
     /** Truncated SHA-256 of the credential that produced this request. */
     credentialFingerprint?: string;
     rateLimit?: RateLimitInfo;
+    /** HTTP 304 to a conditional read: consumes no primary quota, so it is not a counted request. */
+    notModified?: boolean;
 }
 /** Isolates a top-level CLI/MCP command while allowing nested iterate ticks to aggregate. */
 export declare function withApiTelemetryScope<T>(fn: () => Promise<T>): Promise<T>;
@@ -14,4 +16,6 @@ export declare function recordApiTelemetry(event: ApiTelemetryEvent): void;
 export declare function mergeGraphqlRateLimit(headerRateLimit: RateLimitInfo | null, data: unknown): RateLimitInfo | null;
 /** Attach the credential fingerprint without adding it when this command has none. */
 export declare function withGraphqlCredentialFingerprint<T extends object>(sample: T): T;
+/** Attach the REST core credential fingerprint without exposing it in API usage output. */
+export declare function withRestCoreCredentialFingerprint<T extends object>(sample: T): T;
 export declare function summarizeApiTelemetry(): ApiUsage | undefined;

package/bin/github/api-telemetry.mjs

@@ -72,11 +72,23 @@ function graphqlQuotaCredentialFingerprint() {
         return undefined;
     return aggregateStore(active).graphql.credentialFingerprint;
 }
+/** Fingerprint of the credential that owns the authoritative REST core sample. */
+function restCoreQuotaCredentialFingerprint() {
+    const active = store();
+    if (active === undefined)
+        return undefined;
+    return aggregateStore(active).rest.get("core")?.credentialFingerprint;
+}
 /** Attach the credential fingerprint without adding it when this command has none. */
 export function withGraphqlCredentialFingerprint(sample) {
     const credentialFingerprint = graphqlQuotaCredentialFingerprint();
     return credentialFingerprint === undefined ? sample : { ...sample, credentialFingerprint };
 }
+/** Attach the REST core credential fingerprint without exposing it in API usage output. */
+export function withRestCoreCredentialFingerprint(sample) {
+    const credentialFingerprint = restCoreQuotaCredentialFingerprint();
+    return credentialFingerprint === undefined ? sample : { ...sample, credentialFingerprint };
+}
 export function summarizeApiTelemetry() {
     const active = store();
     if (active === undefined)
@@ -89,32 +101,34 @@ export function summarizeApiTelemetry() {
         .map(([source]) => source);
     const graphql = summarizeGraphql(selected.graphql);
     const rest = summarizeRest(selected.rest);
+    const unmeteredRestRequestCount = selected.unmeteredRestRequestCount;
     return {
         credentialSources,
         ...(graphql !== undefined && { graphql }),
         ...(rest.length > 0 && { rest }),
+        ...(unmeteredRestRequestCount > 0 && { unmeteredRestRequestCount }),
     };
 }
 function summarizeGraphql(selected) {
-    const rateLimit = selected.rateLimit;
-    if (rateLimit === undefined)
+    if (selected.rateLimit === undefined)
         return undefined;
     return {
-        ...resourceUsage(rateLimit, selected.requestCount, "graphql"),
+        ...resourceUsage(selected.rateLimit, selected.requestCount, "graphql"),
         measuredQueryCost: selected.measuredQueryCost,
         unmeasuredRequestCount: selected.unmeasuredRequestCount,
         nodeCount: selected.nodeCount,
     };
 }
 function summarizeRest(selected) {
-    return [...selected.entries()].flatMap(([resource, group]) => {
-        return group.rateLimit ? [resourceUsage(group.rateLimit, group.requestCount, resource)] : [];
-    });
+    return [...selected.entries()].flatMap(([resource, group]) => group.rateLimit
+        ? [resourceUsage(group.rateLimit, group.requestCount, resource, group.notModifiedCount)]
+        : []);
 }
-function resourceUsage(rateLimit, requestCount, fallbackResource) {
+function resourceUsage(rateLimit, requestCount, fallbackResource, notModified = 0) {
     return {
         resource: rateLimit.resource ?? fallbackResource,
-        requestCount,
+        ...(requestCount > 0 && { requestCount }),
+        ...(notModified > 0 && { notModified }),
         limit: rateLimit.limit,
         ...(rateLimit.used !== undefined && { used: rateLimit.used }),
         remaining: rateLimit.remaining,

package/bin/github/apply-review-preflight.d.mts

@@ -0,0 +1,20 @@
+import { type RepoInfo } from "./client.mts";
+import { type ReplyEvidence } from "./reply-recovery-read.mts";
+/**
+ * Reads, in one GraphQL request, what `apply review` with reply IDs otherwise reads three times:
+ * the PR head for `--require-sha`, the pre-reply transcripts for seen markers, and the reply
+ * recovery evidence for the first mutation batch. Every field is checked exactly as its
+ * standalone read checks it; anything missing is left to that read.
+ */
+export interface ApplyReviewPreflight {
+    headSha?: string;
+    /** Pre-reply transcripts for threads whose comments fit on the first page. */
+    transcripts: Map<string, string>;
+    /** Complete recovery evidence per requested thread. */
+    evidence: Map<string, ReplyEvidence>;
+}
+/**
+ * GraphQL-only; returns null when the preflight does not apply (REST transport, no reply IDs,
+ * more than one transcript batch, or REST thread handles). Request errors propagate.
+ */
+export declare function readApplyReviewPreflight(pr: number, repo: RepoInfo, replyIds: readonly string[]): Promise<ApplyReviewPreflight | null>;

package/bin/github/apply-review-preflight.mjs

@@ -0,0 +1,61 @@
+import { graphqlWithRateLimit } from "./client.mjs";
+import { githubOperation } from "./transport.mjs";
+import { REPLY_EVIDENCE_THREAD_SELECTION, threadReplyEvidence, } from "./reply-recovery-read.mjs";
+import { threadTranscriptBodies } from "../threads/transcript.mjs";
+import { mapPool } from "../util/pool.mjs";
+const MAX_IDS = 20;
+const QUERY = `query ApplyReviewPreflight($owner: String!, $repo: String!, $pr: Int!, $ids: [ID!]!, $cursor: String) {
+  _shepherdRateLimit: rateLimit { cost limit nodeCount remaining resetAt used }
+  repository(owner: $owner, name: $repo) { pullRequest(number: $pr) { headRefOid } }
+  viewer { login }
+  nodes(ids: $ids) { __typename ${REPLY_EVIDENCE_THREAD_SELECTION} }
+}`;
+/**
+ * GraphQL-only; returns null when the preflight does not apply (REST transport, no reply IDs,
+ * more than one transcript batch, or REST thread handles). Request errors propagate.
+ */
+export function readApplyReviewPreflight(pr, repo, replyIds) {
+    const ids = [...new Set(replyIds)];
+    if (ids.length === 0 || ids.length > MAX_IDS || ids.some((id) => id.startsWith("rest-thread-")))
+        return Promise.resolve(null);
+    return githubOperation("ApplyReviewPreflight", async () => {
+        const { data } = await graphqlWithRateLimit(QUERY, {
+            owner: repo.owner,
+            repo: repo.name,
+            pr,
+            ids,
+            cursor: null,
+        });
+        const headSha = data.repository?.pullRequest?.headRefOid;
+        const evidence = await mapPool(ids, 4, async (id) => {
+            try {
+                return [id, await threadReplyEvidence(repo, pr, id, data)];
+            }
+            catch {
+                return null;
+            }
+        });
+        return {
+            ...(typeof headSha === "string" && headSha && { headSha }),
+            transcripts: firstPageTranscripts(data, pr, repo, new Set(ids)),
+            evidence: new Map(evidence.filter((entry) => entry !== null)),
+        };
+    }, async () => null);
+}
+/** The same acceptance rules as `ReplyThreadTranscripts`, limited to single-page threads. */
+function firstPageTranscripts(data, pr, repo, requested) {
+    const expectedRepo = `${repo.owner}/${repo.name}`.toLowerCase();
+    const transcripts = new Map();
+    for (const node of data.nodes) {
+        if (node?.__typename !== "PullRequestReviewThread" ||
+            !requested.has(node.id) ||
+            node.pullRequest?.number !== pr ||
+            node.pullRequest.repository.nameWithOwner.toLowerCase() !== expectedRepo ||
+            !node.comments ||
+            node.comments.pageInfo.hasNextPage ||
+            node.comments.nodes.length === 0)
+            continue;
+        transcripts.set(node.id, threadTranscriptBodies(node.comments.nodes.map((c) => c.body)));
+    }
+    return transcripts;
+}

package/bin/github/base-behind-cache.d.mts

@@ -0,0 +1,15 @@
+import { type StateKey } from "../state/rest-cache.mts";
+/**
+ * Where a GraphQL BaseBehind result may be cached. The count is a pure function of two commits,
+ * so an entry keyed on the live base tip and the head commit never goes stale.
+ */
+export interface BaseBehindCacheOptions {
+    stateKey: StateKey;
+    /** Live base tip from the same tick's `BatchPr`; without it the cache is not read. */
+    baseTipOid?: string;
+    /** Derived-state slot; a stack layer keeps its trunk compare apart from its base compare. */
+    slot?: "base-behind" | "trunk-behind";
+}
+export declare function cachedBaseBehind(cache: BaseBehindCacheOptions | undefined, headOid: string): Promise<number | undefined>;
+/** Stores a compare under the base tip it actually used, which may be newer than BatchPr's. */
+export declare function storeBaseBehind(cache: BaseBehindCacheOptions | undefined, baseTipOid: string | undefined, headOid: string, behindBy: number): Promise<void>;

package/bin/github/base-behind-cache.mjs

@@ -0,0 +1,18 @@
+import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
+const COMMIT_OID = /^[0-9a-f]{40}$/;
+export async function cachedBaseBehind(cache, headOid) {
+    if (!cache?.baseTipOid || !COMMIT_OID.test(headOid))
+        return undefined;
+    const entry = await loadDerived(cache.stateKey, cache.slot ?? "base-behind");
+    const value = entry?.value;
+    if (value?.baseTipOid !== cache.baseTipOid || value.headOid !== headOid)
+        return undefined;
+    return Number.isSafeInteger(value.behindBy) && value.behindBy >= 0 ? value.behindBy : undefined;
+}
+/** Stores a compare under the base tip it actually used, which may be newer than BatchPr's. */
+export async function storeBaseBehind(cache, baseTipOid, headOid, behindBy) {
+    if (!cache || !baseTipOid || !COMMIT_OID.test(headOid))
+        return;
+    const entry = { baseTipOid, headOid, behindBy };
+    await storeDerived(cache.stateKey, cache.slot ?? "base-behind", entry);
+}

package/bin/github/batch-parse-suites.d.mts

@@ -4,6 +4,8 @@ import type { RawPr } from "./batch-raw-types.mts";
 export declare function parseCheckSuitesComplete(raw: RawPr): boolean;
 /** True only when the head commit's suite page finished and listed nothing. */
 export declare function parseHeadCheckSuitesEmpty(raw: RawPr): boolean;
-/** Actions suites on the head. Third-party suites with no workflow run are omitted. */
-export declare function parseHeadWorkflowSuites(raw: RawPr): WorkflowSuiteSnapshot[];
 export declare function parseSuiteStartupFailures(raw: RawPr): CheckRun[];
+/** `headWorkflowSuites`, omitted when the head has none. */
+export declare function workflowSuites(raw: RawPr): {
+    headWorkflowSuites?: WorkflowSuiteSnapshot[];
+};

package/bin/github/batch-parse-suites.mjs

@@ -7,7 +7,7 @@ export function parseHeadCheckSuitesEmpty(raw) {
     return suites?.pageInfo.hasNextPage === false && suites.nodes.length === 0;
 }
 /** Actions suites on the head. Third-party suites with no workflow run are omitted. */
-export function parseHeadWorkflowSuites(raw) {
+function parseHeadWorkflowSuites(raw) {
     const nodes = raw.commits.nodes[0]?.commit.checkSuites?.nodes ?? [];
     return nodes.flatMap((node) => {
         if (!node.workflowRun)
@@ -43,3 +43,8 @@ export function parseSuiteStartupFailures(raw) {
         ];
     });
 }
+/** `headWorkflowSuites`, omitted when the head has none. */
+export function workflowSuites(raw) {
+    const suites = parseHeadWorkflowSuites(raw);
+    return suites.length > 0 ? { headWorkflowSuites: suites } : {};
+}

package/bin/github/batch-parser-helpers.mjs

@@ -1,3 +1,4 @@
+import { toCheckAnnotation } from "./check-annotation-shape.mjs";
 import { normalizeAuthorType } from "../comments/authors.mjs";
 export function mapAuthorType(typeName, login) {
     return normalizeAuthorType(typeName, login);
@@ -21,7 +22,9 @@ export function mapCheckRunNode(node) {
     const event = node.checkSuite?.workflowRun?.event ?? null;
     const workflowName = node.checkSuite?.workflowRun?.workflow?.name?.trim() || undefined;
     const workflowId = resolveWorkflowId(node.checkSuite?.workflowRun?.workflow?.databaseId);
-    const runId = extractRunId(node.detailsUrl);
+    const runId = node.checkSuite?.workflowRun?.databaseId != null
+        ? String(node.checkSuite.workflowRun.databaseId)
+        : extractRunId(node.detailsUrl);
     const summary = extractCheckRunSummary(node.title, node.summary);
     const rawCreatedAt = node.checkSuite?.workflowRun?.createdAt ?? node.checkSuite?.createdAt;
     const rawUpdatedAt = node.checkSuite?.workflowRun?.updatedAt ?? node.checkSuite?.updatedAt;
@@ -45,7 +48,42 @@ export function mapCheckRunNode(node) {
         ...(completedAtUnix !== undefined && { completedAtUnix }),
         ...(updatedAtUnix !== undefined && { updatedAtUnix }),
         ...(summary !== undefined && { summary }),
-        ...((node.annotations?.nodes.length ?? 0) > 0 && { hasAnnotations: true }),
+        ...(((node.annotations?.totalCount ?? 0) > 0 || (node.annotations?.nodes.length ?? 0) > 0) && {
+            hasAnnotations: true,
+        }),
+        ...inlineAnnotationsField(node.id, node.annotations),
+    };
+}
+/**
+ * The complete annotation list when the first page already holds every annotation with its full
+ * selection. A partial page (more than one annotation, or a node without the full fields) yields
+ * nothing, so the caller still reads the run's annotations separately.
+ */
+function inlineAnnotationsField(checkRunId, annotations) {
+    const total = annotations?.totalCount;
+    if (total === undefined || total < 1 || annotations.nodes.length !== total)
+        return {};
+    const raws = annotations.nodes.map(fullRawAnnotation);
+    if (raws.some((raw) => raw === null))
+        return {};
+    return {
+        inlineAnnotations: raws.map((raw) => toCheckAnnotation(checkRunId, raw)),
+    };
+}
+function fullRawAnnotation(node) {
+    if (typeof node.path !== "string" || typeof node.annotationLevel !== "string")
+        return null;
+    if (node.location === undefined || node.fullDatabaseId === undefined)
+        return null;
+    return {
+        fullDatabaseId: node.fullDatabaseId,
+        path: node.path,
+        annotationLevel: node.annotationLevel,
+        title: node.title ?? null,
+        message: node.message,
+        rawDetails: node.rawDetails ?? null,
+        blobUrl: node.blobUrl ?? null,
+        location: node.location,
     };
 }
 function extractCheckRunSummary(title, summary) {

package/bin/github/batch-parsers.mjs

@@ -138,6 +138,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         },
         baseRefName: raw.baseRefName,
         ...(raw.baseRefOid && { baseRefOid: raw.baseRefOid }),
+        ...(raw.baseRef?.target?.oid && { baseTipOid: raw.baseRef.target.oid }),
         reviewRequests,
         latestReviews,
         reviewThreads,

package/bin/github/batch-raw-rules.d.mts

@@ -13,6 +13,7 @@ export interface RawBranchProtectionRule {
     requiredDeploymentEnvironments?: string[] | null;
 }
 import type { RawContextNode } from "./batch-raw-types.mts";
+import type { StackMemberRefs } from "./stack-read.mts";
 interface RawCheckCommit {
     oid: string;
     committedDate?: string;
@@ -60,6 +61,27 @@ interface RawStack {
     number: number;
     size: number;
     baseRefName: string;
+    /** Selected only by `BatchPr`: the topology `PollStackTopology` would otherwise read. */
+    id?: string;
+    entries?: {
+        pageInfo: {
+            hasNextPage: boolean;
+            endCursor: string | null;
+        };
+        nodes: Array<{
+            position: number;
+            pullRequest: StackMemberRefs | null;
+        } | null>;
+    };
+    /** Selected only by `BatchPr`: the bottom entry, whose base is normally the trunk. */
+    trunkEntry?: {
+        nodes: Array<{
+            pullRequest: {
+                baseRefName: string;
+                baseRef: RawBaseRef | null;
+            } | null;
+        } | null>;
+    };
 }
 export interface RawRepositoryRule {
     type: string;
@@ -87,6 +109,10 @@ export interface RawBaseRef {
         };
         nodes: RawRepositoryRule[];
     } | null;
+    /** Live base branch tip; selected only by `BatchPr`. */
+    target?: {
+        oid?: string;
+    } | null;
 }
 export interface RawPrMergeFields {
     isInMergeQueue?: boolean;

package/bin/github/batch-raw-types.d.mts

@@ -1,5 +1,6 @@
 import type { CommentAuthorAssociation } from "../types/github.mts";
 import type { RawPrMergeFields } from "./batch-raw-rules.mts";
+import type { RawCheckAnnotation } from "./check-annotation-shape.mts";
 export interface RawBatchResponse {
     viewer?: {
         login: string | null;
@@ -140,7 +141,7 @@ interface RawAuthor {
 }
 export interface RawThreadComment {
     id: string;
-    isMinimized: boolean;
+    isMinimized?: boolean;
     url: string;
     authorAssociation?: CommentAuthorAssociation;
     viewerDidAuthor?: boolean;
@@ -157,10 +158,10 @@ export interface RawThreadComment {
 }
 export interface RawThread {
     id: string;
-    isResolved: boolean;
-    isOutdated: boolean;
-    viewerCanReply: boolean;
-    viewerCanResolve: boolean;
+    isResolved?: boolean;
+    isOutdated?: boolean;
+    viewerCanReply?: boolean;
+    viewerCanResolve?: boolean;
     path?: string | null;
     line?: number | null;
     startLine?: number | null;
@@ -228,7 +229,7 @@ export type RawContextNode = {
     summary: string | null;
     annotations?: {
         totalCount?: number;
-        nodes: Array<{
+        nodes: Array<Partial<RawCheckAnnotation> & {
             message: string;
         }>;
     };
@@ -236,6 +237,7 @@ export type RawContextNode = {
         createdAt?: string;
         updatedAt?: string;
         workflowRun: {
+            databaseId?: number;
             event: string;
             createdAt?: string;
             updatedAt?: string;

package/bin/github/batch-stack-evidence.d.mts

@@ -0,0 +1,28 @@
+import type { RawPrMergeFields } from "./batch-raw-rules.mts";
+import type { StackMemberRefs, StackRead } from "./stack-read.mts";
+/** Required contexts and live tip of a native stack's trunk, read in `BatchPr`. */
+export interface TrunkRules {
+    refName: string;
+    contexts: string[];
+    tipOid?: string;
+}
+/**
+ * Stack reads that `BatchPr`'s first page already answered. Each part is present
+ * only when complete; a caller falls back to the standalone query otherwise.
+ */
+export interface BatchStackEvidence {
+    topology?: StackRead<StackMemberRefs>;
+    trunk?: TrunkRules;
+}
+/** Validate the embedded stack selections of one `BatchPr` first page. */
+export declare function stackEvidenceFromRaw(raw: RawPrMergeFields & {
+    number: number;
+    baseRefName: string;
+}, data: {
+    viewer?: {
+        login: string | null;
+    } | null;
+    repository?: {
+        viewerCanAdminister?: boolean;
+    } | null;
+}): BatchStackEvidence | undefined;

package/bin/github/batch-stack-evidence.mjs

@@ -0,0 +1,62 @@
+import { parseBranchRules } from "./batch-parsers-rules.mjs";
+import { orderedStackMembers } from "./stack-order.mjs";
+/** Validate the embedded stack selections of one `BatchPr` first page. */
+export function stackEvidenceFromRaw(raw, data) {
+    const stack = raw.stack;
+    if (!stack)
+        return undefined;
+    const viewer = {
+        login: data.viewer?.login ?? null,
+        canAdminister: data.repository?.viewerCanAdminister,
+    };
+    const topology = embeddedTopology(stack, raw.number, viewer);
+    const trunk = embeddedTrunkRules(stack, raw);
+    if (!topology && !trunk)
+        return undefined;
+    return { ...(topology && { topology }), ...(trunk && { trunk }) };
+}
+function embeddedTopology(stack, anchor, viewer) {
+    const entries = stack.entries;
+    // Past one page, PollStackTopology reads the full membership instead.
+    if (!entries || entries.pageInfo.hasNextPage)
+        return undefined;
+    const members = [];
+    for (const node of entries.nodes) {
+        if (!node?.pullRequest)
+            return undefined;
+        members.push({ position: node.position, pullRequest: node.pullRequest });
+    }
+    try {
+        return {
+            stackNumber: stack.number,
+            stackSize: stack.size,
+            viewerLogin: viewer.login,
+            ...(viewer.canAdminister !== undefined && { viewerCanAdminister: viewer.canAdminister }),
+            ordered: orderedStackMembers(members, anchor, stack.size),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The trunk's rules come from whichever ref in this page is the trunk itself:
+ * this PR's own base for the bottom layer, otherwise the first entry's base.
+ */
+function embeddedTrunkRules(stack, raw) {
+    const trunk = stack.baseRefName;
+    if (raw.baseRefName === trunk && raw.baseRef)
+        return trunkRules(trunk, raw.baseRef);
+    const bottom = stack.trunkEntry?.nodes[0]?.pullRequest;
+    if (bottom?.baseRefName !== trunk || !bottom.baseRef)
+        return undefined;
+    return trunkRules(trunk, bottom.baseRef);
+}
+function trunkRules(refName, ref) {
+    const tipOid = ref.target?.oid;
+    return {
+        refName,
+        contexts: parseBranchRules(ref).requiredStatusCheckContexts,
+        ...(tipOid && { tipOid }),
+    };
+}

package/bin/github/batch.d.mts

@@ -3,7 +3,8 @@ import type { WorkflowSuiteSnapshot } from "../checks/unreported-required.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
 import type { BatchPrData } from "../types.mts";
 import { type PrFingerprint } from "./fingerprint.mts";
-interface BatchResult {
+import { type BatchStackEvidence } from "./batch-stack-evidence.mts";
+export interface BatchResult {
     data: BatchPrData;
     fingerprint?: PrFingerprint;
     rateLimit?: RateLimitInfo;
@@ -15,7 +16,15 @@ interface BatchResult {
     headWorkflowSuites?: WorkflowSuiteSnapshot[];
     /** Internal READY-receipt evidence from the same request, if complete. */
     receiptSummary?: RawSummaryPr;
+    /** Native-stack topology and trunk rules from the same first page, if complete. */
+    stackEvidence?: BatchStackEvidence;
 }
+/** A fingerprint hit, plus the live base tip and stack evidence from the same first page. */
+type ReusedBatch<T> = {
+    reused: T;
+    baseTipOid?: string;
+    stackEvidence?: BatchStackEvidence;
+};
 interface FetchPrBatchOptions {
     /**
      * When false (default), the first-page approvedReviews are returned but
@@ -27,9 +36,13 @@ interface FetchPrBatchOptions {
      */
     paginateApprovedReviews?: boolean;
     includeReceiptSummary?: boolean;
+    terminalShortCircuit?: boolean;
 }
 /**
- * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
+ * With `reuse`, the GraphQL first page's fingerprint is offered to it before any supplement
+ * runs; a non-null answer is returned as `{ reused }` instead of a snapshot. REST snapshots never
+ * call `reuse`: they have their own conditional-read reuse.
  */
+export declare function fetchPrBatch<T>(pr: number, repo: RepoInfo, opts: FetchPrBatchOptions, reuse: (fingerprint: PrFingerprint) => Promise<T | null>): Promise<BatchResult | ReusedBatch<T>>;
 export declare function fetchPrBatch(pr: number, repo: RepoInfo, opts?: FetchPrBatchOptions): Promise<BatchResult>;
 export {};