@gitkraken/core-gitlens 0.5.100 → 0.5.101

package/src/plus/git-github/models.ts

@@ -2,7 +2,7 @@ import type { Endpoints } from '@octokit/types';
 import { GitFileIndexStatus } from '../../git/models/fileStatus.js';
 import type { IssueLabel } from '../../git/models/issue.js';
 import { Issue, RepositoryAccessLevel } from '../../git/models/issue.js';
-import type { PullRequestState } from '../../git/models/pullRequest.js';
+import type { PullRequestMember, PullRequestState } from '../../git/models/pullRequest.js';
 import {
 	PullRequest,
 	PullRequestMergeableState,
@@ -131,8 +131,9 @@ export type GitHubPullRequestState = 'OPEN' | 'CLOSED' | 'MERGED';
 export type GitHubIssueOrPullRequestState = GitHubIssueState | GitHubPullRequestState;
 
 export interface GitHubPullRequestLite extends Omit<GitHubIssueOrPullRequest, '__typename'> {
-	author: GitHubMember;
-	body: string;
+	/** `Actor` is nullable in GitHub's schema — `null` once the author's account is deleted */
+	author: GitHubMember | null;
+	body: string | null;
 
 	baseRefName: string;
 	baseRefOid: string;
@@ -167,7 +168,8 @@ export interface GitHubPullRequestLite extends Omit<GitHubIssueOrPullRequest, '_
 }
 
 export interface GitHubIssue extends Omit<GitHubIssueOrPullRequest, '__typename'> {
-	author: GitHubMember;
+	/** `Actor` is nullable in GitHub's schema — `null` once the author's account is deleted */
+	author: GitHubMember | null;
 	assignees: { nodes: GitHubMember[] };
 	comments?: {
 		totalCount: number;
@@ -203,7 +205,7 @@ export interface GitHubPullRequest extends GitHubPullRequestLite {
 	reviewDecision: GitHubPullRequestReviewDecision;
 	latestReviews: {
 		nodes: {
-			author: GitHubMember;
+			author: GitHubMember | null;
 			state: GitHubPullRequestReviewState;
 		}[];
 	};
@@ -234,15 +236,17 @@ export type GitHubViewerPermission =
 	| 'READ' // Can read and clone this repository. Can also open and comment on issues and pull requests
 	| 'NONE';
 
+/** `ghost` is how github.com renders an actor whose account was deleted */
+function fromGitHubMemberOrGhost(member: GitHubMember | null | undefined): PullRequestMember {
+	if (member == null) return { id: 'ghost', name: 'ghost' };
+
+	return { id: member.login, name: member.login, avatarUrl: member.avatarUrl, url: member.url };
+}
+
 export function fromGitHubPullRequestLite(pr: GitHubPullRequestLite, provider: Provider): PullRequest {
 	return new PullRequest(
 		provider,
-		{
-			id: pr.author.login,
-			name: pr.author.login,
-			avatarUrl: pr.author.avatarUrl,
-			url: pr.author.url,
-		},
+		fromGitHubMemberOrGhost(pr.author),
 		String(pr.number),
 		pr.id,
 		pr.title,
@@ -296,7 +300,7 @@ export function fromGitHubPullRequestLite(pr: GitHubPullRequestLite, provider: P
 		undefined, // statusCheckRollupState
 		undefined, // project
 		undefined, // version
-		pr.body,
+		pr.body ?? undefined,
 	);
 }
 
@@ -399,12 +403,7 @@ export function fromGitHubPullRequestStatusCheckRollupState(
 export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider): PullRequest {
 	return new PullRequest(
 		provider,
-		{
-			id: pr.author.login,
-			name: pr.author.login,
-			avatarUrl: pr.author.avatarUrl,
-			url: pr.author.url,
-		},
+		fromGitHubMemberOrGhost(pr.author),
 		String(pr.number),
 		pr.id,
 		pr.title,
@@ -469,12 +468,7 @@ export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider)
 			)
 			.filter(<T>(r?: T): r is T => Boolean(r)),
 		pr.latestReviews.nodes.map(r => ({
-			reviewer: {
-				id: r.author.login,
-				name: r.author.login,
-				avatarUrl: r.author.avatarUrl,
-				url: r.author.url,
-			},
+			reviewer: fromGitHubMemberOrGhost(r.author),
 			state: fromGitHubPullRequestReviewState(r.state),
 		})),
 		pr.assignees.nodes.map(r => ({
@@ -486,7 +480,7 @@ export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider)
 		fromGitHubPullRequestStatusCheckRollupState(pr.commits.nodes?.[0]?.commit.statusCheckRollup?.state),
 		undefined, // project
 		undefined, // version
-		pr.body,
+		pr.body ?? undefined,
 	);
 }
 
@@ -506,12 +500,14 @@ export function fromGitHubIssue(value: GitHubIssue, provider: Provider): Issue {
 		new Date(value.updatedAt),
 		value.closed,
 		fromGitHubIssueOrPullRequestState(value.state),
-		{
-			id: value.author.login,
-			name: value.author.login,
-			avatarUrl: value.author.avatarUrl,
-			url: value.author.url,
-		},
+		value.author == null
+			? undefined
+			: {
+					id: value.author.login,
+					name: value.author.login,
+					avatarUrl: value.author.avatarUrl,
+					url: value.author.url,
+				},
 		value.assignees.nodes.map(assignee => ({
 			id: assignee.login,
 			name: assignee.login,

package/src/plus/integrations/collectionMetadata.ts

@@ -1,4 +1,9 @@
-import type { CollectionMetadata, CollectionScopeFailure } from '@gitkraken/provider-apis';
+import type {
+	CollectionMetadata,
+	CollectionOmission,
+	CollectionScope,
+	CollectionScopeFailure,
+} from '@gitkraken/provider-apis';
 import { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '../../git/errors.js';
 import type { IntegrationIds } from './constants.js';
 import { isRateLimitResponse } from './errors.js';
@@ -68,8 +73,21 @@ function toCollectionFailureWarningKind(failure: CollectionScopeFailure): Provid
 	}
 }
 
-function collectionFailureMessage(failure: CollectionScopeFailure): string {
-	const scope = failure.scope;
+/**
+ * A scope's identity, as the stable string that keys it.
+ *
+ * The dedup keys in `providerPaging.ts` build on this, so failures and omissions can never disagree about
+ * what "the same scope" means. `providerId` is included: the same repository ID under two providers is two
+ * scopes.
+ */
+export function collectionScopeKey(scope: CollectionScope | undefined): string {
+	return [scope?.providerId ?? '', scope?.resourceId ?? '', scope?.projectId ?? '', scope?.repositoryId ?? ''].join(
+		' ',
+	);
+}
+
+/** ` (resource r, project p, repository o/n)` for the scope IDs present; empty when the scope names none. */
+function collectionScopeText(scope: CollectionScope | undefined): string {
 	const parts: string[] = [];
 	if (scope?.resourceId != null) {
 		parts.push(`resource ${scope.resourceId}`);
@@ -81,9 +99,64 @@ function collectionFailureMessage(failure: CollectionScopeFailure): string {
 		parts.push(`repository ${scope.repositoryId}`);
 	}
 
-	const scopeText = parts.length ? ` (${parts.join(', ')})` : '';
+	return parts.length ? ` (${parts.join(', ')})` : '';
+}
+
+function collectionFailureMessage(failure: CollectionScopeFailure): string {
 	const detail = failure.message != null ? `: ${failure.message}` : '';
-	return `Failed to read ${failure.kind} scope${scopeText}${detail}`;
+	return `Failed to read ${failure.kind} scope${collectionScopeText(failure.scope)}${detail}`;
+}
+
+/**
+ * Explains one omission in the consumer's terms — what was left out and, where the SDK reports it, how much.
+ *
+ * An omission is a completeness fact, never a failure: the read succeeded and the provider (or the SDK's own
+ * recovery budget) is what withheld results, so retrying the same request cannot recover them. That is why
+ * these never contribute to `fetchFailed`.
+ */
+function collectionOmissionMessage(omission: CollectionOmission): string {
+	const scopeText = collectionScopeText(omission.scope);
+	switch (omission.kind) {
+		case 'provider-limit':
+			// `totalCount` is the only figure saying how much was withheld; both fields are optional, so degrade
+			// through the shapes the SDK can actually emit rather than printing `undefined`.
+			if (omission.totalCount != null && omission.limit != null) {
+				return `Search${scopeText} matched ${omission.totalCount} results, but the provider exposes at most ${omission.limit}`;
+			}
+			if (omission.limit != null) {
+				return `Search${scopeText} exceeded the provider limit of ${omission.limit} results`;
+			}
+			return `Search${scopeText} exceeded the provider's result limit`;
+		case 'recovery-budget':
+			return `Stopped recovering omitted results${scopeText} after reaching the request budget${
+				omission.limit != null ? ` of ${omission.limit} requests` : ''
+			}`;
+		case 'pagination-incomplete':
+			return `More results are available${scopeText} than this read returned`;
+		default:
+			// `CollectionOmissionKind` is a closed union, so this is unreachable today. Kept as a compile-time
+			// guard rather than a silent fallback: an SDK bump that adds a kind breaks the build here instead
+			// of quietly degrading it to a vague message.
+			omission.kind satisfies never;
+			return `Some results were omitted${scopeText}; the read is incomplete`;
+	}
+}
+
+/**
+ * Whether SDK metadata describes a read that may be missing results.
+ *
+ * A reported omission counts on its own rather than deferring to `completeness`. The SDK does couple the
+ * two — every site that emits an omission degrades completeness in the same call — so today the omission
+ * clause changes no outcome. It is defensive: the two facts arrive as independent fields, and a read that
+ * names what it left out must not be publishable as whole if a future producer sets only one of them.
+ *
+ * This is the single definition of "may be missing results", shared with `getPagedResult`, so one metadata
+ * object cannot be truncated at one layer and complete at another.
+ */
+export function isIncompleteCollection(metadata: CollectionMetadata | undefined): boolean {
+	if (metadata == null) return false;
+
+	return metadata.completeness !== 'complete' || (metadata.omissions?.length ?? 0) > 0;
 }
 
 /** Converts internal SDK collection metadata into neutral provider facade signals. */
@@ -109,8 +182,25 @@ export function assessCollectionMetadata(
 		});
 	}
 
-	const incomplete = metadata.completeness !== 'complete';
-	if (incomplete && failures.length === 0) {
+	// Omissions explain WHY a read is incomplete when nothing failed — a provider cap, an exhausted recovery
+	// budget, an undrained scope. They classify as `other`, never `auth`, and are deliberately excluded from
+	// `fetchFailed` below: the request succeeded, so a retry would return the same truncated set.
+	const omissions = metadata.omissions ?? [];
+	for (const omission of omissions) {
+		appendDedupedWarning(warnings, {
+			providerId: providerId,
+			domain: domain,
+			connectionId: connectionId,
+			message: collectionOmissionMessage(omission),
+			kind: 'other',
+			isAuth: false,
+		});
+	}
+
+	const incomplete = isIncompleteCollection(metadata);
+	// Only fall back to the generic message when nothing more specific was reported; an omission already
+	// explains the incompleteness in the consumer's terms, so adding this on top would be noise.
+	if (incomplete && failures.length === 0 && omissions.length === 0) {
 		appendDedupedWarning(warnings, {
 			providerId: providerId,
 			domain: domain,

package/src/plus/integrations/integrationService.ts

@@ -555,7 +555,7 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 	async getMyIssues(
 		integrationIds?: (GitCloudHostIntegrationId | IssuesCloudHostIntegrationId | GitSelfManagedHostIntegrationId)[],
 		options?: { openRepositoriesOnly?: boolean; cancellation?: AbortSignal },
-	): Promise<IssueShape[] | undefined> {
+	): Promise<IntegrationResult<IssueShape[] | undefined>> {
 		const integrations: Map<Integration, ResourceDescriptor[] | undefined> = new Map();
 		const hostingIntegrationIds = integrationIds?.filter(
 			id => id in GitCloudHostIntegrationId || id in GitSelfManagedHostIntegrationId,
@@ -623,26 +623,54 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 	private async getMyIssuesCore(
 		integrations: Map<Integration, ResourceDescriptor[] | undefined>,
 		cancellation?: AbortSignal,
-	): Promise<IssueShape[] | undefined> {
-		const promises: Promise<IssueShape[] | undefined>[] = [];
+	): Promise<IntegrationResult<IssueShape[] | undefined>> {
+		const start = performance.now();
+
+		const promises: Promise<IntegrationResult<IssueShape[] | undefined>>[] = [];
 		for (const [integration, repos] of integrations) {
 			if (integration == null) continue;
 
-			promises.push(integration.searchMyIssues(repos, cancellation));
+			promises.push(integration.searchMyIssuesResult(repos, cancellation));
 		}
 
 		const results = await Promise.allSettled(promises);
-		return [...flatten(filterMap(results, r => (r.status === 'fulfilled' ? r.value : undefined)))];
+		const successfulResults = [
+			...flatten(
+				filterMap(results, r =>
+					r.status === 'fulfilled' && r.value?.value != null ? r.value.value : undefined,
+				),
+			),
+		];
+		const errors = [
+			...filterMap(results, r =>
+				r.status === 'fulfilled' && r.value?.error != null ? r.value.error : undefined,
+			),
+		];
+
+		const error =
+			errors.length === 0
+				? undefined
+				: errors.length === 1
+					? errors[0]
+					: new AggregateError(errors, 'Failed to get some issues');
+
+		return {
+			value: successfulResults,
+			error: error,
+			duration: performance.now() - start,
+		};
 	}
 
-	async getMyIssuesForRemotes(remote: GitRemote): Promise<IssueShape[] | undefined>;
-	async getMyIssuesForRemotes(remotes: GitRemote[]): Promise<IssueShape[] | undefined>;
+	async getMyIssuesForRemotes(remote: GitRemote): Promise<IntegrationResult<IssueShape[] | undefined>>;
+	async getMyIssuesForRemotes(remotes: GitRemote[]): Promise<IntegrationResult<IssueShape[] | undefined>>;
 	@trace({
 		args: (remoteOrRemotes: GitRemote | GitRemote[]) => ({
 			remoteOrRemotes: Array.isArray(remoteOrRemotes) ? remoteOrRemotes.map(rp => rp.name) : remoteOrRemotes.name,
 		}),
 	})
-	async getMyIssuesForRemotes(remoteOrRemotes: GitRemote | GitRemote[]): Promise<IssueShape[] | undefined> {
+	async getMyIssuesForRemotes(
+		remoteOrRemotes: GitRemote | GitRemote[],
+	): Promise<IntegrationResult<IssueShape[] | undefined>> {
 		if (!Array.isArray(remoteOrRemotes)) {
 			remoteOrRemotes = [remoteOrRemotes];
 		}
@@ -653,7 +681,7 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 			if (remote?.provider == null) return undefined;
 
 			const integration = await this.getByRemote(remote);
-			return integration?.searchMyIssues(remote.provider.repoDesc);
+			return integration?.searchMyIssuesResult(remote.provider.repoDesc);
 		}
 
 		const integrations = new Map<GitHostIntegration, ResourceDescriptor[]>();

package/src/plus/integrations/models/integration.ts

@@ -737,6 +737,7 @@ export abstract class IntegrationBase<
 		const session = await this.resolveReadSession(connectionId, scope);
 		if (session == null) return undefined;
 
+		const start = performance.now();
 		try {
 			const issues = await this.searchProviderMyIssues(
 				session,
@@ -744,10 +745,10 @@ export abstract class IntegrationBase<
 				cancellation,
 			);
 			this.resetRequestExceptionCount('searchMyIssues');
-			return { value: issues };
+			return { value: issues, duration: performance.now() - start };
 		} catch (ex) {
 			this.handleProviderException('searchMyIssues', ex, { scope: scope, connectionId: connectionId });
-			return { error: toError(ex) };
+			return { error: toError(ex), duration: performance.now() - start };
 		}
 	}
 

package/src/plus/integrations/providers/models.ts

@@ -470,7 +470,10 @@ export type GetIssueFn = (
 export type GetIssuesForReposFn = (
 	input: (GetIssuesForReposInput | GetIssuesForRepoIdsInput) & PagingInput,
 	options?: EnterpriseOptions,
-) => Promise<{ data: ProviderIssue[]; pageInfo?: PageInfo }>;
+	// GitHub's multi-repo issue search reports its 1,000-result cap — and, when it recovers past it by
+	// partitioning, what that recovery could not reach — through `metadata`. Documented on the contract for
+	// the reader; `getPagedResult` accepts and forwards `metadata` from any provider fn regardless.
+) => Promise<{ data: ProviderIssue[]; pageInfo?: PageInfo; metadata?: CollectionMetadata }>;
 
 export type GetIssuesForCurrentUserInput = PagingInput & {
 	// GitLab's account-wide REST read (`GET /issues`): `scope` controls breadth ('assigned_to_me' vs 'all') and

package/src/plus/integrations/providers/providersApi.ts

@@ -13,6 +13,7 @@ import type { PagedResult } from '../../../utils/paging.js';
 import type { IntegrationAuthenticationService } from '../authentication/integrationAuthenticationService.js';
 import type { TokenOptInfo, TokenWithInfo } from '../authentication/models.js';
 import { toTokenWithInfo } from '../authentication/models.js';
+import { isIncompleteCollection } from '../collectionMetadata.js';
 import type { IntegrationIds } from '../constants.js';
 import {
 	GitCloudHostIntegrationId,
@@ -32,7 +33,6 @@ import type {
 	GetIssueFn,
 	GetIssuesForReposFn,
 	GetIssuesOptions,
-	GetPullRequestsForRepoFn,
 	GetPullRequestsForReposFn,
 	GetPullRequestsForUserFn,
 	GetPullRequestsForUserOptions,
@@ -275,9 +275,7 @@ export class ProvidersApi {
 				getPullRequestsForReposFn: providerApis.gitlab.getPullRequestsForRepos.bind(
 					providerApis.gitlab,
 				) as GetPullRequestsForReposFn,
-				getPullRequestsForRepoFn: providerApis.gitlab.getPullRequestsForRepo.bind(
-					providerApis.gitlab,
-				) as GetPullRequestsForRepoFn,
+				getPullRequestsForRepoFn: providerApis.gitlab.getPullRequestsForRepo.bind(providerApis.gitlab),
 				getPullRequestsForUserFn: providerApis.gitlab.getPullRequestsAssociatedWithUser.bind(
 					providerApis.gitlab,
 				) as GetPullRequestsForUserFn,
@@ -302,9 +300,7 @@ export class ProvidersApi {
 				getPullRequestsForReposFn: providerApis.gitlab.getPullRequestsForRepos.bind(
 					providerApis.gitlab,
 				) as GetPullRequestsForReposFn,
-				getPullRequestsForRepoFn: providerApis.gitlab.getPullRequestsForRepo.bind(
-					providerApis.gitlab,
-				) as GetPullRequestsForRepoFn,
+				getPullRequestsForRepoFn: providerApis.gitlab.getPullRequestsForRepo.bind(providerApis.gitlab),
 				getPullRequestsForUserFn: providerApis.gitlab.getPullRequestsAssociatedWithUser.bind(
 					providerApis.gitlab,
 				) as GetPullRequestsForUserFn,
@@ -681,9 +677,9 @@ export class ProvidersApi {
 			// SDK collection completeness is independent from provider-native pagination: a result can expose a
 			// real next page (`more`) and still have a failed sibling scope (`partial`/`unknown`). Surface the
 			// latter as `truncated` so consumers treat the page as incomplete. Absent metadata (old providers,
-			// test doubles) leaves `truncated` unset for backward compatibility.
-			const truncated =
-				normalizedMetadata != null && normalizedMetadata.completeness !== 'complete' ? true : undefined;
+			// test doubles) leaves `truncated` unset for backward compatibility. Shares the incompleteness
+			// predicate with the facade assessment so one metadata object can't be truncated there and whole here.
+			const truncated = isIncompleteCollection(normalizedMetadata) ? true : undefined;
 
 			return {
 				values: result.data,

package/src/plus/integrations/providers/trello.ts

@@ -1,3 +1,4 @@
+import type { CollectionMetadata } from '@gitkraken/provider-apis';
 import type { Account } from '../../../git/models/author.js';
 import type { Issue, IssueShape } from '../../../git/models/issue.js';
 import type { IssueOrPullRequest, IssueOrPullRequestType } from '../../../git/models/issueOrPullRequest.js';
@@ -103,7 +104,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 		session: ProviderAuthenticationSession,
 		project: ResourceDescriptor,
 		options?: { user?: string; filters?: IssueFilter[] },
-	): Promise<{ values: IssueShape[]; truncated: boolean } | undefined> {
+	): Promise<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined> {
 		// A non-issue descriptor genuinely has nothing to read (empty), but a missing app key is a broken read.
 		if (!isIssueResourceDescriptor(project)) return undefined;
 
@@ -139,7 +140,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 		// never a cursor. Surface that as terminal truncation; there is no next page to fetch, so retrying the
 		// same read cannot recover the omitted cards (D11).
 		const truncated = result.metadata != null && result.metadata.completeness !== 'complete';
-		return { values: values, truncated: truncated };
+		return { values: values, truncated: truncated, metadata: result.metadata };
 	}
 
 	protected override searchProviderMyIssues(

package/src/plus/integrations/providers/utils/providerPaging.ts

@@ -1,6 +1,12 @@
-import type { CollectionCompleteness, CollectionMetadata, CollectionScopeFailure } from '@gitkraken/provider-apis';
+import type {
+	CollectionCompleteness,
+	CollectionMetadata,
+	CollectionOmission,
+	CollectionScopeFailure,
+} from '@gitkraken/provider-apis';
 import { isCancellationError } from '../../../../utils/cancellation.js';
-import { toCollectionScopeFailure } from '../../collectionMetadata.js';
+import { uniqueBy } from '../../../../utils/iterable.js';
+import { collectionScopeKey, toCollectionScopeFailure } from '../../collectionMetadata.js';
 import type { ProviderApiPagedResult, ProviderHierarchyResult } from '../models.js';
 
 /**
@@ -42,21 +48,29 @@ const completenessRank: Record<CollectionCompleteness, number> = { partial: 2, u
 
 /** A stable key for deduplicating structurally-identical scope failures accumulated across drained pages. */
 function collectionFailureKey(failure: CollectionScopeFailure): string {
-	const scope = failure.scope;
-	return [
-		failure.kind,
-		scope?.providerId ?? '',
-		scope?.resourceId ?? '',
-		scope?.projectId ?? '',
-		scope?.repositoryId ?? '',
-		failure.message ?? '',
-	].join(' ');
+	return [failure.kind, collectionScopeKey(failure.scope), failure.message ?? ''].join(' ');
+}
+
+/**
+ * A stable key for collapsing omissions accumulated across drained pages, matching the SDK's own
+ * `dedupeOmissions`: kind plus scope IDs, deliberately WITHOUT `limit`/`totalCount`.
+ *
+ * Those counts are a re-measurement, not an identity. GitHub recomputes the match total on every request, so
+ * one repository drained over several pages reports the same cap with a drifting total; keying on the total
+ * would emit a near-identical warning per page ("matched 1393…", "matched 1402…") that
+ * `appendDedupedWarning` cannot collapse, since the messages genuinely differ. Independently-scoped omissions
+ * still stay distinct, which is the case that carries information.
+ */
+function collectionOmissionKey(omission: CollectionOmission): string {
+	return [omission.kind, collectionScopeKey(omission.scope)].join(' ');
 }
 
 /**
  * Merges SDK collection metadata across drained pages. Completeness follows {@link completenessRank};
- * failures are concatenated and deduplicated by kind, scope IDs, and message. Returns `undefined` when no
- * page supplied metadata, so metadata-free providers and test doubles keep behaving as before.
+ * failures are deduplicated by kind, scope IDs, and message, and omissions are collapsed per kind and scope
+ * keeping the highest reported total ({@link collectionOmissionKey}). Both preserve first-reported order.
+ * Returns `undefined` when no page supplied metadata, so metadata-free providers and test doubles keep
+ * behaving as before.
  */
 export function mergeCollectionMetadata(
 	base: CollectionMetadata | undefined,
@@ -70,17 +84,25 @@ export function mergeCollectionMetadata(
 			? next.completeness
 			: base.completeness;
 
-	const failures: CollectionScopeFailure[] = [];
-	const seen = new Set<string>();
-	for (const failure of [...(base.failures ?? []), ...(next.failures ?? [])]) {
-		const key = collectionFailureKey(failure);
-		if (seen.has(key)) continue;
-
-		seen.add(key);
-		failures.push(failure);
-	}
-
-	return { completeness: completeness, ...(failures.length ? { failures: failures } : {}) };
+	// First occurrence wins: a repeated failure carries no new information, since the message is part of its key.
+	const failures = [
+		...uniqueBy([...(base.failures ?? []), ...(next.failures ?? [])], collectionFailureKey, original => original),
+	];
+	// Highest total wins, so re-measuring one cap across pages collapses to a single omission holding the
+	// largest figure reported for it — the same rule the SDK applies in `createCollectionMetadata`.
+	const omissions = [
+		...uniqueBy(
+			[...(base.omissions ?? []), ...(next.omissions ?? [])],
+			collectionOmissionKey,
+			(original, current) => ((current.totalCount ?? -1) > (original.totalCount ?? -1) ? current : undefined),
+		),
+	];
+
+	return {
+		completeness: completeness,
+		...(failures.length ? { failures: failures } : {}),
+		...(omissions.length ? { omissions: omissions } : {}),
+	};
 }
 
 /**

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

@@ -15,8 +15,10 @@ import type { ProviderWarning } from '../results.js';
 /**
  * The single builder for a provider-neutral, non-auth warning: an unsupported capability, a
  * contradictory/inexpressible request, or a read that couldn't confirm completeness. Every `kind: 'other'`
- * warning the facade emits goes through here (directly, or via one of the named builders below that pin a
- * recurring message), so the discriminant is assigned in exactly one place.
+ * warning the facade raises on its own terms goes through here (directly, or via one of the named builders
+ * below that pin a recurring message), so the discriminant is assigned in one place. The warnings mapped from
+ * SDK collection metadata are the documented exception — `collectionMetadata.ts` builds those from the
+ * structured failure/omission it is given.
  *
  * The kinds that carry a programmatic remedy — `auth`, `rate-limit`, `not-found`, `no-connection` — are derived
  * from the caught error's type instead and never come from here; see `ProviderWarningKind` and