@gitkraken/core-gitlens 0.5.101 → 0.5.103

package/src/plus/integrations/reads/drains.ts

@@ -9,7 +9,7 @@ import type { PullRequestFilter } from '../providerFilters.js';
 import type { ProviderPullRequest, ProviderReposInput, ProviderRepository } from '../providers/models.js';
 import { getProviderPullRequestIdentity } from '../providers/models.js';
 import type { ProviderWarning } from '../results.js';
-import { appendDedupedWarning, toProviderWarning } from '../results.js';
+import { appendDedupedWarning, reconcileOmissionsWithFailure, toProviderWarning } from '../results.js';
 import { isIssuesHostIntegrationId } from '../utils/integration.utils.js';
 import { noConnectionWarning, truncationWarning } from './warnings.js';
 
@@ -90,10 +90,18 @@ export async function drainPullRequests(
 	// this through the terminal returns instead of resetting it to false at the last page.
 	let fetchFailed = false;
 	let truncated = false;
+	// A page the provider capped or couldn't vouch for. Decides the CAUSE the terminal warning reports: a cap
+	// outranks a budget stop, because raising a budget cannot un-cap a page.
+	let providerTruncated = false;
+	// The subset of that which no other warning already explains — decides whether this drain raises one of
+	// its own on an otherwise clean exit.
+	let unexplainedTruncation = false;
 
 	// With no repos this is an account-wide "my PRs" sweep. The repo-scoped core rejects an empty `repos`
 	// input, so read the provider-native account-wide core instead.
 	const accountWide = repos.length === 0;
+	/** Every cursor already followed, so a provider that cycles them can't keep the drain walking in circles. */
+	const seenCursors = new Set<string>();
 
 	for (;;) {
 		page++;
@@ -130,10 +138,23 @@ export async function drainPullRequests(
 				appendDedupedWarning(warnings, noConnectionWarning(id, domain, connectionId));
 			}
 			// `warning` set → a hard read failure (incomplete items); otherwise not connected / no session.
+			const failed = fetchFailed || warning != null || unavailable;
+			// A cap seen on an earlier page still left results out, so it is still worth saying — but as part
+			// of a read that failed, never as an omission. (`failed` is always true here when anything was
+			// latched: reaching this exit past page 1 means a later page was lost.)
+			if (unexplainedTruncation) {
+				appendDedupedWarning(
+					warnings,
+					truncationWarning(id, domain, connectionId, 'Pull request', failed ? 'interrupted' : 'exhausted'),
+				);
+			}
+			// An earlier page may already have emitted an omission before this one died; it asserts the read
+			// succeeded, which is no longer true.
+			reconcileOmissionsWithFailure(warnings, failed);
 			return {
 				items: items,
 				warnings: warnings,
-				fetchFailed: fetchFailed || warning != null || unavailable,
+				fetchFailed: failed,
 				truncated: truncated || sessionLostAfterProgress,
 				// Only a top-level first-page rejection means the provider itself failed. A later-page or
 				// per-scope failure still yielded a usable provider slice and stays represented separately.
@@ -171,14 +192,31 @@ export async function drainPullRequests(
 			value.paging?.truncated === true ||
 			assessment.truncated;
 		truncated = truncated || pageTruncated;
-		if (pageTruncated && !assessment.truncated) {
-			appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Pull request'));
-		}
+		// A page the provider itself capped, or one whose completeness it couldn't confirm. Latched from ANY
+		// source, SDK metadata included: no budget of ours un-caps a page, so a later `maxPages` hit must not
+		// claim raising it would help.
+		providerTruncated = providerTruncated || pageTruncated;
+		// Whether this drain owes its OWN warning for that is a separate question — `mergeAssessmentInto` has
+		// already appended one when the fact came from SDK metadata, and repeating it would be noise.
+		unexplainedTruncation = unexplainedTruncation || (pageTruncated && !assessment.truncated);
 
 		if (!(value.paging?.more ?? false)) {
 			// A read that can't confirm completeness (single-page provider reads with no `hasNextPage`)
 			// sets `paging.truncated`; propagate it (and any top-level `truncated` and SDK incompleteness)
 			// so the sweep doesn't claim an all-pages result.
+			if (unexplainedTruncation) {
+				appendDedupedWarning(
+					warnings,
+					truncationWarning(
+						id,
+						domain,
+						connectionId,
+						'Pull request',
+						fetchFailed ? 'interrupted' : 'exhausted',
+					),
+				);
+			}
+			reconcileOmissionsWithFailure(warnings, fetchFailed);
 			return {
 				items: items,
 				warnings: warnings,
@@ -187,21 +225,34 @@ export async function drainPullRequests(
 				failedProvider: false,
 			};
 		}
-		if (page >= maxPages) {
-			appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Pull request'));
-			return {
-				items: items,
-				warnings: warnings,
-				fetchFailed: fetchFailed,
-				truncated: true,
-				failedProvider: false,
-			};
-		}
 
+		// Resolve the continuation BEFORE deciding why the drain stops. `page-budget` claims the missing items
+		// are reachable, which is only true with a usable cursor in hand — and a provider can report another
+		// page while handing back none (Bitbucket Server does, when it omits `nextPageStart`). Checking the
+		// budget first would label that unreachable tail as merely unfetched, so raising `maxPages` would
+		// return the identical set.
 		const nextCursor = value.paging?.cursor;
-		if (nextCursor == null || nextCursor === '{}') {
-			// Provider says there is more but didn't return a usable cursor; stop rather than refetch the same page.
-			appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Pull request'));
+		// A cursor already used isn't a continuation either — following it refetches a page we have, and a
+		// provider that cycles (A→B→A) would otherwise burn the whole budget and then be reported as merely
+		// out of budget. Tracked as a SET rather than compared one-back, matching the SDK's own `followCursors`:
+		// `drainToRequestedPage` and `collectProviderPagedResult` compare only the previous cursor, which a
+		// cycle slips past. That is tolerable there and not here, because only this drain reports `page-budget`.
+		const continuable = nextCursor != null && nextCursor !== '{}' && !seenCursors.has(nextCursor);
+		if (!continuable || page >= maxPages) {
+			// `providerTruncated` outranks the budget: a page the provider capped stays capped however many
+			// pages we are allowed to read, so promising `page-budget` on top of it would be a load-more that
+			// cannot deliver the capped part.
+			appendDedupedWarning(
+				warnings,
+				truncationWarning(
+					id,
+					domain,
+					connectionId,
+					'Pull request',
+					fetchFailed ? 'interrupted' : continuable && !providerTruncated ? 'page-budget' : 'exhausted',
+				),
+			);
+			reconcileOmissionsWithFailure(warnings, fetchFailed);
 			return {
 				items: items,
 				warnings: warnings,
@@ -211,6 +262,7 @@ export async function drainPullRequests(
 			};
 		}
 
+		seenCursors.add(nextCursor);
 		cursor = nextCursor;
 	}
 }
@@ -262,12 +314,20 @@ export async function drainRepositories(
 		if (value == null) {
 			const interruptedAfterProgress = page > 1;
 			if (interruptedAfterProgress && warning == null) {
-				appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, 'Repository'));
+				// Not a backstop: the read was cut short mid-drain, which is why it also sets `fetchFailed`
+				// below. A retry may complete it, so this must not claim the succeeded-but-capped omission.
+				appendDedupedWarning(
+					warnings,
+					truncationWarning(id, domain, connectionId, 'Repository', 'interrupted'),
+				);
 			}
+			const failed = fetchFailed || warning != null || interruptedAfterProgress;
+			// An SDK omission from an earlier page asserts the read succeeded; this one didn't.
+			reconcileOmissionsWithFailure(warnings, failed);
 			return {
 				repos: repos,
 				warnings: warnings,
-				fetchFailed: fetchFailed || warning != null || interruptedAfterProgress,
+				fetchFailed: failed,
 				truncated: truncated || interruptedAfterProgress,
 			};
 		}
@@ -277,6 +337,7 @@ export async function drainRepositories(
 		fetchFailed = fetchFailed || assessment.fetchFailed;
 		truncated = truncated || value.truncated === true || value.paging?.truncated === true || assessment.truncated;
 		if (!(value.paging?.more ?? false)) {
+			reconcileOmissionsWithFailure(warnings, fetchFailed);
 			return {
 				repos: repos,
 				warnings: warnings,
@@ -284,13 +345,16 @@ export async function drainRepositories(
 				truncated: truncated,
 			};
 		}
+
 		if (page >= maxPages) {
+			reconcileOmissionsWithFailure(warnings, fetchFailed);
 			return { repos: repos, warnings: warnings, fetchFailed: fetchFailed, truncated: true };
 		}
 
 		const nextCursor = value.paging?.cursor;
 		if (nextCursor == null || nextCursor === '{}') {
 			// Provider says there is more but didn't return a usable cursor; stop rather than refetch the same page.
+			reconcileOmissionsWithFailure(warnings, fetchFailed);
 			return { repos: repos, warnings: warnings, fetchFailed: fetchFailed, truncated: true };
 		}
 

package/src/plus/integrations/reads/hierarchy.ts

@@ -10,6 +10,7 @@ import {
 } from '../constants.js';
 import type { ListOrgsOptions, ListProjectsOptions } from '../manager.js';
 import { isIssuesIntegration } from '../models/issuesIntegration.js';
+import type { ProviderHierarchyResult } from '../providers/models.js';
 import { toProviderRepositoryShape } from '../providers/models.js';
 import type {
 	ProviderOrganization,
@@ -35,7 +36,46 @@ import {
 	withProviderContext,
 } from './hierarchy.utils.js';
 import { pageToCursor, refusedPage, resolveContinuation, resolveCurrentPage, toProviderPageInfo } from './paging.js';
-import { gitHostOnlySurfaceWarning, otherWarning } from './warnings.js';
+import { gitHostOnlySurfaceWarning, otherWarning, truncationWarning } from './warnings.js';
+
+/**
+ * Folds a flat hierarchy result's incompleteness into `warnings`, returning whether it leaves the read
+ * non-authoritative. The single funnel for both hierarchy reads, so neither can drift from the other on any of
+ * the four decisions it makes:
+ *
+ * - The metadata is assessed FIRST, so the truncation warning can tell whether it already explained this gap.
+ *   Ordered deliberately: emitting first meant an expired credential produced BOTH a typed `auth` warning and
+ *   an unclassifiable one for the same cause, and a consumer routing on classification showed the second as
+ *   "this provider failed to load", with a remedy that doesn't exist, next to the reconnect prompt that was the
+ *   actual fix.
+ * - The read states the truncation itself only when the metadata reported nothing — the rule
+ *   `assessCollectionMetadata` applies to its own generic fallback. Whatever the metadata reported already names
+ *   this provider and says something stronger, so restating it costs a false verdict and adds no information.
+ * - `'exhausted'`, never `'page-budget'`: `truncated` is one boolean here, so a drain that stopped at its page
+ *   budget is indistinguishable from one whose cursor stalled, and `IncompleteReadCause` makes `'exhausted'`
+ *   the default whenever a raisable budget is not demonstrably the cause.
+ * - A truncation counts as non-authoritative even though the omission above asserts the read succeeded. Unlike
+ *   paged repository reads, a flattened hierarchy result has no page object on which to carry incompleteness,
+ *   so `fetchFailed` is the only signal a consumer has that the list is short.
+ */
+function mergeHierarchyIncompleteness(
+	warnings: ProviderWarning[],
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	result: Pick<ProviderHierarchyResult<unknown>, 'truncated' | 'metadata'>,
+	readKind: 'Organization' | 'Project',
+): boolean {
+	const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, result.metadata);
+	if (!result.truncated) return assessment.fetchFailed || assessment.truncated;
+
+	if (!assessment.reported) {
+		// Deduped like every other `truncationWarning` emission (see `drains.ts`), not plain-pushed: no caller can
+		// collide with it today, but nothing about this funnel guarantees a third read won't.
+		appendDedupedWarning(warnings, truncationWarning(id, domain, connectionId, readKind, 'exhausted'));
+	}
+	return true;
+}
 
 export async function listOrgs(
 	ctx: ProviderReadContext,
@@ -103,22 +143,8 @@ export async function listOrgs(
 			);
 			if (value != null) {
 				items.push(...value.values.map(org => withProviderContext(id, org)));
-				if (value.truncated) {
-					warnings.push(
-						otherWarning(
-							id,
-							domain,
-							connectionId,
-							'Organization listing was truncated before the upstream results were exhausted.',
-						),
-					);
-					// `ProviderResult` has no page object on which to carry truncation. Mark the flat
-					// hierarchy result incomplete so consumers don't treat omitted orgs as authoritative.
-					fetchFailed = true;
-				}
 
-				const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, value.metadata);
-				if (assessment.fetchFailed || assessment.truncated) {
+				if (mergeHierarchyIncompleteness(warnings, id, domain, connectionId, value, 'Organization')) {
 					fetchFailed = true;
 				}
 			}
@@ -200,22 +226,7 @@ export async function listProjects(
 			if (projects != null) {
 				items.push(...projects.values.map(project => withProviderContext(id, project)));
 
-				if (projects.truncated) {
-					warnings.push(
-						otherWarning(
-							id,
-							domain,
-							connectionId,
-							'Project listing was truncated before the upstream results were exhausted.',
-						),
-					);
-					// Unlike paged repository reads, this flattened hierarchy result has no continuation
-					// or page metadata. `fetchFailed` is its structural non-authoritative signal.
-					fetchFailed = true;
-				}
-
-				const assessment = mergeAssessmentInto(warnings, id, domain, connectionId, projects.metadata);
-				if (assessment.fetchFailed || assessment.truncated) {
+				if (mergeHierarchyIncompleteness(warnings, id, domain, connectionId, projects, 'Project')) {
 					fetchFailed = true;
 				}
 			}

package/src/plus/integrations/reads/issueTracker.ts

@@ -9,12 +9,13 @@ import { isIssuesIntegration } from '../models/issuesIntegration.js';
 import { IssueFilter, providersMetadata } from '../providers/models.js';
 import { mergeCollectionMetadata, parsePageCursor } from '../providers/utils/providerPaging.js';
 import type { ProviderPagedResult, ProviderWarning } from '../results.js';
+import { reconcileOmissionsWithFailure } from '../results.js';
 import { isIssuesHostIntegrationId } from '../utils/integration.utils.js';
 import type { ProviderReadContext } from './context.js';
 import { parseIssueTrackerPageCursor, toIssueTrackerPageCursor } from './cursors.js';
 import { runCaptured } from './drains.js';
 import { projectKey, resourceIdForProject, resourceLabel, resourceMatchesOrg } from './hierarchy.utils.js';
-import { issueTrackerOnlySurfaceWarning, otherWarning } from './warnings.js';
+import { incompleteReadWarning, issueTrackerOnlySurfaceWarning, otherWarning } from './warnings.js';
 
 export async function listIssueTrackerIssuesPage(
 	ctx: ProviderReadContext,
@@ -431,14 +432,19 @@ export async function listIssueTrackerIssuesPage(
 	// the caller sees the truncation, but only when no warning already explains it (avoid duplicate noise).
 	if (projectTruncated && warnings.length === 0) {
 		warnings.push(
-			otherWarning(
+			incompleteReadWarning(
 				options.providerId,
 				domain,
 				options.connectionId,
 				'Some issues were omitted; the provider returned an incomplete result.',
+				// `exhausted`, not `page-budget`: the per-project drain's backstop is an internal constant
+				// (`maxPagesPerRequest`), not an option this read exposes, so no caller can raise it.
+				fetchFailed ? 'interrupted' : 'exhausted',
 			),
 		);
 	}
+	// A metadata omission from an earlier project asserts the read succeeded; a later one may since have failed.
+	reconcileOmissionsWithFailure(warnings, fetchFailed);
 
 	const retryPages = retryWindowPages();
 	const cursor = toIssueTrackerPageCursor({

package/src/plus/integrations/reads/issues.ts

@@ -6,7 +6,7 @@ import type { IssueFilter, ProviderReposInput } from '../providers/models.js';
 import { PagingMode, providersMetadata } from '../providers/models.js';
 import { mergeCollectionMetadata } from '../providers/utils/providerPaging.js';
 import type { ProviderPagedResult, ProviderWarning } from '../results.js';
-import { appendDedupedWarning } from '../results.js';
+import { appendDedupedWarning, reconcileOmissionsWithFailure } from '../results.js';
 import {
 	isGitHostIntegration,
 	isIssuesHostIntegrationId,
@@ -269,14 +269,19 @@ export async function listIssuesPage(
 		const truncated = continuation.truncated || assessment.truncated;
 		if (truncated && warnings.length === 0) {
 			warnings.push(
-				otherWarning(
+				truncationWarning(
 					options.providerId,
 					domain,
 					options.connectionId,
-					`Account-wide issue search for '${options.providerId}' was truncated; results may be incomplete.`,
+					'Account-wide issue search',
+					// `exhausted`: this composite read exposes no budget the caller can raise, so nothing it
+					// could call would return the withheld items.
+					assessment.fetchFailed || pageFetchFailed ? 'interrupted' : 'exhausted',
 				),
 			);
 		}
+		// A metadata omission from an earlier page asserts the read succeeded; a later page may since have failed.
+		reconcileOmissionsWithFailure(warnings, assessment.fetchFailed || pageFetchFailed);
 		return {
 			items: items,
 			warnings: warnings,
@@ -385,8 +390,20 @@ export async function listIssuesPage(
 	// page isn't published as complete. Metadata incompleteness is an independent source of the same signal.
 	const truncated = continuation.truncated || assessment.truncated;
 	if (truncated && warnings.length === 0) {
-		warnings.push(truncationWarning(options.providerId, domain, options.connectionId, 'Issue'));
+		warnings.push(
+			truncationWarning(
+				options.providerId,
+				domain,
+				options.connectionId,
+				'Issue',
+				// `exhausted`, never `page-budget`: a paged read has no budget the caller can raise, and
+				// ordinary continuation is already expressed by `hasMore`/`cursor`.
+				assessment.fetchFailed || pageFetchFailed ? 'interrupted' : 'exhausted',
+			),
+		);
 	}
+	// A metadata omission from an earlier page asserts the read succeeded; a later page may since have failed.
+	reconcileOmissionsWithFailure(warnings, assessment.fetchFailed || pageFetchFailed);
 	return {
 		items: items,
 		warnings: warnings,

package/src/plus/integrations/reads/pullRequests.ts

@@ -4,6 +4,7 @@ import type { IntegrationIds } from '../constants.js';
 import type { ProviderPullRequest, ProviderReposInput, PullRequestFilter } from '../providers/models.js';
 import { fromProviderPullRequest, PagingMode, providersMetadata } from '../providers/models.js';
 import type { ProviderPagedResult } from '../results.js';
+import { reconcileOmissionsWithFailure } from '../results.js';
 import {
 	isGitHostIntegration,
 	isIssuesHostIntegrationId,
@@ -226,8 +227,21 @@ export async function listPullRequestsPage(
 	// the page may be incomplete. Metadata incompleteness is an independent source of the same signal.
 	const truncated = continuation.truncated || assessment.truncated;
 	if (truncated && warnings.length === 0) {
-		warnings.push(truncationWarning(options.providerId, domain, options.connectionId, 'Pull request'));
+		// `exhausted`, never `page-budget`: a paged read has no budget the caller can raise. Ordinary
+		// continuation is already expressed by `hasMore`/`cursor`, so reaching here means this page itself
+		// couldn't be completed — raising anything would return the same page.
+		warnings.push(
+			truncationWarning(
+				options.providerId,
+				domain,
+				options.connectionId,
+				'Pull request',
+				assessment.fetchFailed || pageFetchFailed ? 'interrupted' : 'exhausted',
+			),
+		);
 	}
+	// A metadata omission from an earlier page asserts the read succeeded; a later page may since have failed.
+	reconcileOmissionsWithFailure(warnings, assessment.fetchFailed || pageFetchFailed);
 	const currentAccountId = items.some(pr => pr.author != null)
 		? await getCurrentAccountId(integration, options.connectionId)
 		: undefined;

package/src/plus/integrations/reads/warnings.ts

@@ -93,22 +93,98 @@ export function issueTrackerOnlySurfaceWarning(
 }
 
 /**
- * Builds a warning for a drain that stopped short of completeness (hit a page backstop, or a single-page read
- * that couldn't confirm it drained everything). `truncated`/`allPages` already carry this on the result, but
- * consumers that only inspect `warnings` would otherwise see no signal the read is partial.
+ * Why a read the facade drove itself returned less than everything. The two questions a consumer cannot
+ * answer from `truncated` or from the message, kept together because they are decided together:
+ *
+ * - `interrupted`: the read did NOT succeed — the session went away, a later page failed. It leaves an unread
+ *   tail like the others, but it is a failure: it sets `fetchFailed`, and a retry is exactly the right move.
+ *   Gets no omission at all, since the omission asserts the opposite.
+ * - `page-budget`: the drain stopped at its own `maxPages`, with a usable cursor still in hand. The items ARE
+ *   reachable and were simply not fetched, so re-running with a higher budget returns them.
+ * - `exhausted`: everything else that succeeded and came back short — the provider capped the page it served,
+ *   advertised another page without a usable cursor (or with one it had already handed out), or a read could
+ *   not confirm it had drained everything. The default of the three: choose it whenever a raisable budget is
+ *   not demonstrably what stopped the read, so a consumer is never offered a fetch that cannot deliver.
  */
+export type IncompleteReadCause = 'interrupted' | 'page-budget' | 'exhausted';
+
+/**
+ * Builds the warning for a read that returned less than everything, carrying the two facts a consumer cannot
+ * recover on its own: did the request succeed, and would anything fetch the rest?
+ *
+ * Every incompleteness warning the facade raises on its own terms goes through here, so no read can drift
+ * into claiming success on a failure or offering a "load more" that cannot deliver. The omission it attaches
+ * is the same shape `assessCollectionMetadata` derives from SDK metadata, so a consumer never has to care
+ * which layer noticed the gap.
+ *
+ * No `scope`: this applies to the whole read, not to one repository or project the way an SDK-attributed
+ * omission can, so a consumer acting on `recovery` re-runs the read itself.
+ */
+export function incompleteReadWarning(
+	id: IntegrationIds,
+	domain: string | undefined,
+	connectionId: string | undefined,
+	message: string,
+	cause: IncompleteReadCause,
+): ProviderWarning {
+	const warning = otherWarning(id, domain, connectionId, message);
+	if (cause === 'interrupted') return warning;
+
+	return {
+		...warning,
+		omission: {
+			kind: 'pagination-incomplete',
+			recovery: cause === 'page-budget' ? 'page-budget' : 'none',
+		},
+	};
+}
+
+/**
+ * The read surfaces {@link truncationWarning} phrases for. `'Account-wide issue search'` names the composite
+ * read that spans several provider searches rather than one surface.
+ *
+ * Deliberately not exported: every caller passes a literal, and publishing it would invite a consumer to switch
+ * on a set that exists only to word a message.
+ */
+type TruncatedReadKind =
+	| 'Pull request'
+	| 'Issue'
+	| 'Repository'
+	| 'Organization'
+	| 'Project'
+	| 'Account-wide issue search';
+
+/** {@link incompleteReadWarning} for a paged or drained read, phrased per surface. */
 export function truncationWarning(
 	id: IntegrationIds,
 	domain: string | undefined,
 	connectionId: string | undefined,
-	readKind: 'Pull request' | 'Issue' | 'Repository',
+	readKind: TruncatedReadKind,
+	/**
+	 * Deliberately REQUIRED and not defaulted: a default would make one of these the silent fallback at any
+	 * call site that forgot it, and both of the claims it carries — "the request succeeded" and "more can be
+	 * fetched" — are ones this warning must never make by accident.
+	 */
+	cause: IncompleteReadCause,
 ): ProviderWarning {
-	return otherWarning(
-		id,
-		domain,
-		connectionId,
-		`${readKind} read for '${id}' was truncated (a page backstop was reached); results may be incomplete.`,
-	);
+	return incompleteReadWarning(id, domain, connectionId, truncationMessage(id, readKind, cause), cause);
+}
+
+function truncationMessage(id: IntegrationIds, readKind: TruncatedReadKind, cause: IncompleteReadCause): string {
+	switch (cause) {
+		case 'interrupted':
+			// Deliberately does not name a mechanism. This fires both when a page was lost mid-drain and when a
+			// drain that latched an earlier scope failure later stopped for its own reasons; "was interrupted"
+			// would be false in the second. What is true in both is that something failed and results are gone.
+			return `${readKind} read for '${id}' did not complete; some results are missing and the read reported a failure.`;
+		case 'page-budget':
+			return `${readKind} read for '${id}' stopped at its page budget; more results can be read by raising it.`;
+		case 'exhausted':
+			return `${readKind} read for '${id}' was truncated and cannot be continued; results may be incomplete.`;
+	}
+	// No `default`: `IncompleteReadCause` is declared in this file, so `noImplicitReturns` already fails the
+	// build here if a cause is added without its own wording. (`collectionOmissionMessage`'s `satisfies never`
+	// is not the same case — that union is the SDK's, and can widen under a dependency bump.)
 }
 
 /** Warning for an account-wide issue read whose requested filters the provider can't express server-side. */