@gitkraken/core-gitlens 0.5.108 → 0.5.110

package/src/plus/git-github/api/issueSearchQuery.ts

@@ -1,4 +1,4 @@
-import type { IssueSearchCriteria, IssueSearchRelationship } from '../../../git/models/issue.js';
+import type { IssueSearchCriteria, IssueSearchRelationship, IssueSorting } from '../../../git/models/issue.js';
 
 /**
  * Translation of the provider-neutral issue-search criteria into GitHub search qualifiers, and the sanitizing
@@ -70,6 +70,56 @@ export const gitHubIssueSearchRelationships: Record<IssueSearchRelationship, { q
 	unassigned: { qualifier: 'no:assignee', alias: 'unassigned' },
 };
 
+/**
+ * How each orderable key becomes a GitHub `sort:` qualifier.
+ *
+ * A literal table rather than a derived transform, for the same reason {@link gitHubIssueSearchRelationships} is
+ * one: being a `Record` over the union means adding a sort field without deciding its qualifier FAILS THE BUILD,
+ * instead of quietly emitting a search with no ordering constraint at all — which is the one failure mode the
+ * ordering contract exists to prevent, and the one a caller cannot detect from the result.
+ *
+ * `updated:desc` maps to the bare `sort:updated`, not `sort:updated-desc`. The two are the same query to GitHub,
+ * but the bare form is what this read has always emitted, so keeping it makes the default byte-identical to
+ * today's query — and the exact-query tests and recorded fixtures stay valid. Do not "normalize" it.
+ *
+ * `reactions` maps to the per-emoji `sort:reactions-+1`, NOT the bare `sort:reactions`. GitHub's bare form orders
+ * by the total across every reaction type, but the only reaction count on an `IssueShape` is `thumbsUpCount`,
+ * which this client fills from `reactions(content: THUMBS_UP)`. Ordering by the total would rank the page by a
+ * number the caller cannot see — and would disagree with `getIssueComparator`, which re-sorts a merged page from
+ * `thumbsUpCount`, so the same request would order one way with a single relationship and another way with two.
+ * `@gitkraken/provider-apis` maps it the same way for the same reason.
+ *
+ * Absent keys are absent on purpose: `closed` is NOT here even though `IssueShape.closedDate` exists, because
+ * GitHub's search cannot order by close date and a client-side sort over a page cut off at the result ceiling is
+ * exactly the lie the contract avoids. `sorts` in `githubIssueSearchCapabilities` is the same set, and a parity
+ * test pins the two together.
+ */
+export const gitHubIssueSortQualifiers: Partial<Record<IssueSorting, string>> = {
+	'created:asc': 'sort:created-asc',
+	'created:desc': 'sort:created-desc',
+	'updated:asc': 'sort:updated-asc',
+	'updated:desc': 'sort:updated',
+	'comments:asc': 'sort:comments-asc',
+	'comments:desc': 'sort:comments-desc',
+	'reactions:asc': 'sort:reactions-+1-asc',
+	'reactions:desc': 'sort:reactions-+1-desc',
+};
+
+/**
+ * The `sort:` qualifier for a key, or `undefined` when there is no key or GitHub can't express it.
+ *
+ * Applies no default of its own: the two callers differ on whether they HAVE one — the filtered search always
+ * orders, and `searchMyIssues` has never requested an order at all — so the default belongs at the call site that
+ * has one rather than behind a guard at the one that doesn't.
+ *
+ * `undefined` for an inexpressible key rather than a fallback to something orderable: every caller validated
+ * against the declared capability first, so reaching that case means the capability table has outrun this one, and
+ * a silently unordered search would change which rows land inside the result ceiling.
+ */
+export function toGitHubIssueSortQualifier(sort: IssueSorting | undefined): string | undefined {
+	return sort != null ? gitHubIssueSortQualifiers[sort] : undefined;
+}
+
 /**
  * The scope half of an issue search query: `org:` plus one `repo:` per repository.
  *
@@ -106,11 +156,18 @@ export function toGitHubIssueSearchScopeQualifiers(
  * becomes its own aliased search, since GitHub AND-s qualifiers and relationships are OR-ed) and excluding the
  * repository/org scope (which {@link toGitHubIssueSearchScopeQualifiers} owns).
  *
- * `sort:updated` is always emitted: the read's contract is most-recently-updated-first, so a consumer's "show the
- * N most recent" policy at the result ceiling is correct. Free-form values go through the sanitizers above, and
- * one emptied by sanitizing is dropped rather than emitted as an empty qualifier.
+ * A `sort:` qualifier is ALWAYS emitted. Never none: the provider serves at most a bounded window of matches, and
+ * without an explicit order GitHub answers in relevance order, so which rows land inside that window would shift
+ * with GitHub's ranking even when nothing changed upstream. A key GitHub can't express is refused before this by
+ * the facade, so it cannot arrive here.
+ *
+ * `sort` is passed in rather than read off `criteria` so that the qualifier this emits and the key the caller
+ * records elsewhere cannot disagree — see `effectiveIssueSort`.
+ *
+ * Free-form values go through the sanitizers above, and one emptied by sanitizing is dropped rather than emitted
+ * as an empty qualifier.
  */
-export function toGitHubIssueSearchQualifiers(criteria: IssueSearchCriteria | undefined): string[] {
+export function toGitHubIssueSearchQualifiers(criteria: IssueSearchCriteria | undefined, sort: IssueSorting): string[] {
 	const qualifiers = ['type:issue'];
 
 	switch (criteria?.state) {
@@ -158,8 +215,11 @@ export function toGitHubIssueSearchQualifiers(criteria: IssueSearchCriteria | un
 		}
 	}
 
-	// Contract, not an option: see `GitHubApi.searchIssuesPage`.
-	qualifiers.push('sort:updated');
+	// Last, where it has always been: the exact-query tests pin the whole qualifier string, not a set.
+	const sortQualifier = toGitHubIssueSortQualifier(sort);
+	if (sortQualifier != null) {
+		qualifiers.push(sortQualifier);
+	}
 
 	return qualifiers;
 }

package/src/plus/git-github/api/pullRequestSearchQuery.ts

@@ -1,6 +1,10 @@
-import type { PullRequestSearchCriteria, PullRequestStateFilter } from '../../../git/models/pullRequest.js';
-import { PullRequestFilter } from '../../../git/models/pullRequest.js';
-import { sanitizeGitHubSearchText } from './issueSearchQuery.js';
+import type {
+	PullRequestSearchCriteria,
+	PullRequestSorting,
+	PullRequestStateFilter,
+} from '../../../git/models/pullRequest.js';
+import { defaultPullRequestSort, PullRequestFilter } from '../../../git/models/pullRequest.js';
+import { sanitizeGitHubQualifierValue, sanitizeGitHubSearchText } from './issueSearchQuery.js';
 
 export type GitHubPullRequestSearchFacet = {
 	/** Stable GraphQL alias and composite-cursor key. */
@@ -8,10 +12,20 @@ export type GitHubPullRequestSearchFacet = {
 	qualifiers: string[];
 };
 
-const relationshipQualifier: Record<PullRequestFilter, string> = {
+/**
+ * The GitHub search qualifier each relationship translates to. Exhaustive over `PullRequestFilter` so a new
+ * member can't be silently unmapped.
+ *
+ * Exported because the account-wide read builds its own facets from the same vocabulary (see
+ * `GitHubIntegrationBase.getProviderMyPullRequestsForUser`). Kept as ONE declaration rather than a copy per
+ * caller: the exhaustive `Record` makes a missing key a compile error, but nothing would catch two copies
+ * disagreeing on a qualifier STRING, and a wrong qualifier is a read that quietly answers a different question.
+ */
+export const gitHubPullRequestRelationshipQualifiers: Record<PullRequestFilter, string> = {
 	[PullRequestFilter.Author]: 'author:@me',
 	[PullRequestFilter.Assignee]: 'assignee:@me',
 	[PullRequestFilter.ReviewRequested]: 'review-requested:@me',
+	[PullRequestFilter.Reviewed]: 'reviewed-by:@me',
 	[PullRequestFilter.Mention]: 'mentions:@me',
 };
 
@@ -19,6 +33,7 @@ const relationshipAlias: Record<PullRequestFilter, string> = {
 	[PullRequestFilter.Author]: 'author',
 	[PullRequestFilter.Assignee]: 'assignee',
 	[PullRequestFilter.ReviewRequested]: 'reviewRequested',
+	[PullRequestFilter.Reviewed]: 'reviewed',
 	[PullRequestFilter.Mention]: 'mention',
 };
 
@@ -29,6 +44,30 @@ const stateAlias: Record<PullRequestStateFilter, string> = {
 	all: 'All',
 };
 
+/**
+ * How each orderable key becomes a GitHub `sort:` qualifier.
+ *
+ * A literal `Record` over the union rather than a derived transform, for the same reason the relationship tables
+ * are: adding a sort field without deciding its qualifier fails the build instead of quietly emitting a search
+ * with no ordering constraint — the one failure mode the ordering contract exists to prevent, and the one a
+ * caller cannot detect from the result.
+ *
+ * `updated:desc` maps to the bare `sort:updated`, not `sort:updated-desc`. The two are the same query to GitHub,
+ * but the bare form is what this read has always emitted, so keeping it makes the default byte-identical to
+ * today's query — matching `toGitHubIssueSortQualifier`. Do not "normalize" it.
+ */
+export const gitHubPullRequestSortQualifiers: Partial<Record<PullRequestSorting, string>> = {
+	'created:asc': 'sort:created-asc',
+	'created:desc': 'sort:created-desc',
+	'updated:asc': 'sort:updated-asc',
+	'updated:desc': 'sort:updated',
+};
+
+/** The `sort:` qualifier for a key, or `undefined` when there is no key or GitHub can't express it. */
+export function toGitHubPullRequestSortQualifier(sort: PullRequestSorting | undefined): string | undefined {
+	return sort != null ? gitHubPullRequestSortQualifiers[sort] : undefined;
+}
+
 function stateQualifiers(state: PullRequestStateFilter): string[] {
 	switch (state) {
 		case 'closed':
@@ -62,18 +101,53 @@ export function toGitHubPullRequestSearchFacets(
 		: ['open'];
 	const states: PullRequestStateFilter[] = requestedStates.includes('all') ? ['all'] : requestedStates;
 	const text = criteria?.text != null ? sanitizeGitHubSearchText(criteria.text) : '';
+	// Ordering is part of the contract, not an option: without an explicit `sort:` GitHub answers in relevance
+	// order, so which rows land inside the result ceiling would shift with its ranking even when nothing changed
+	// upstream. A key GitHub can't express is REFUSED here, not approximated with a fallback order — a silent
+	// `sort:updated` substitute would emit one order in the query while the merged-page comparator applied another
+	// (or none for an unknown field), which is exactly the "the N most recent are what you get" promise the ceiling
+	// contract cannot keep under a guessed order. Unreachable through the facade — every key is validated against
+	// `githubPullRequestSearchCapabilities.sorts` first — so this guards the direct callers of this exported builder
+	// and of `GitHubApi.searchPullRequestsPage`.
+	//
+	// Deliberately STRICTER than the issue path, which drops an inexpressible qualifier and searches on
+	// (`toGitHubIssueSearchQualifiers` pushes `toGitHubIssueSortQualifier`'s result only when it is non-null). The
+	// two reads differ in what that costs: an issue search is served by whichever facets the provider ordered, while
+	// this one hands its merged page to `getPullRequestComparator`, so a dropped qualifier here means the query and
+	// the comparator disagree about the order the ceiling was applied under. Refusing is the only answer that
+	// cannot lie about which rows were reachable.
+	const sort = criteria?.sort ?? defaultPullRequestSort;
+	const sortQualifier = toGitHubPullRequestSortQualifier(sort);
+	if (sortQualifier == null) {
+		throw new Error(`GitHub cannot order a pull request search by '${sort}'`);
+	}
+
+	// Facet-independent, unlike the relationship/state qualifiers below — build once and share.
+	const dateQualifiers: string[] = [];
+	const pushDate = (value: string | undefined, toQualifier: (sanitized: string) => string): void => {
+		if (value == null) return;
+
+		const sanitized = sanitizeGitHubQualifierValue(value);
+		if (sanitized.length > 0) {
+			dateQualifiers.push(toQualifier(sanitized));
+		}
+	};
+	pushDate(criteria?.updatedAfter, v => `updated:>=${v}`);
+	pushDate(criteria?.createdAfter, v => `created:>=${v}`);
 
 	return relationships.flatMap(relationship =>
 		states.map(state => ({
 			alias: `${relationship != null ? relationshipAlias[relationship] : 'scope'}${stateAlias[state]}`,
 			qualifiers: [
 				'is:pr',
-				...(relationship != null ? [relationshipQualifier[relationship]] : []),
+				...(relationship != null ? [gitHubPullRequestRelationshipQualifiers[relationship]] : []),
 				...stateQualifiers(state),
+				// `!= null`, not truthy: `draft:false` narrows to ready-for-review PRs just as `draft:true` narrows to drafts.
+				...(criteria?.draft != null ? [`draft:${criteria.draft}`] : []),
 				...(criteria?.includeArchived === true ? [] : ['archived:false']),
 				...(text.length > 0 ? [text] : []),
-				// Contract, not an option: a capped result is the N most recently updated only under this order.
-				'sort:updated',
+				...dateQualifiers,
+				sortQualifier,
 			],
 		})),
 	);

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

@@ -194,6 +194,13 @@ export type GitHubPullRequestMergeableState = 'MERGEABLE' | 'CONFLICTING' | 'UNK
 export type GitHubPullRequestStatusCheckRollupState = 'SUCCESS' | 'FAILURE' | 'PENDING' | 'EXPECTED' | 'ERROR';
 export type GitHubPullRequestReviewState = 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' | 'DISMISSED' | 'PENDING';
 
+type GitHubPullRequestReview = {
+	id: string;
+	author: GitHubMember | null;
+	state: GitHubPullRequestReviewState;
+	commit?: { oid: string } | null;
+};
+
 export interface GitHubPullRequest extends GitHubPullRequestLite {
 	additions: number;
 	assignees: {
@@ -204,11 +211,14 @@ export interface GitHubPullRequest extends GitHubPullRequestLite {
 	mergeable: GitHubPullRequestMergeableState;
 	reviewDecision: GitHubPullRequestReviewDecision;
 	latestReviews: {
-		nodes: {
-			author: GitHubMember | null;
-			state: GitHubPullRequestReviewState;
-		}[];
+		nodes: GitHubPullRequestReview[];
 	};
+	/**
+	 * The current user's own latest review. `latestReviews` is capped, so on a heavily-reviewed pull request
+	 * the viewer's own review can fall outside that window — which is exactly the row a "needs my review"
+	 * surface is asking about.
+	 */
+	viewerLatestReview: GitHubPullRequestReview | null;
 	reviewRequests: {
 		nodes: {
 			asCodeOwner: boolean;
@@ -401,6 +411,19 @@ export function fromGitHubPullRequestStatusCheckRollupState(
 }
 
 export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider): PullRequest {
+	// `latestReviews` is capped, so keep the viewer's own review even when it falls outside that window, deduped
+	// by review id since the two selections overlap. Unsubmitted drafts are dropped from the union rather than
+	// from the viewer's side alone: `PENDING` is in GitHub's review-state enum on both selections, and the field
+	// this feeds is documented as reviews already SUBMITTED — a draft there tells a "needs my review" consumer
+	// the review is done, and a reviewer with a submitted review plus a draft would get two conflicting rows.
+	const viewerLatestReview = pr.viewerLatestReview;
+	const latestReviews = [
+		...pr.latestReviews.nodes,
+		...(viewerLatestReview != null && !pr.latestReviews.nodes.some(r => r.id === viewerLatestReview.id)
+			? [viewerLatestReview]
+			: []),
+	].filter(review => review.state !== 'PENDING');
+
 	return new PullRequest(
 		provider,
 		fromGitHubMemberOrGhost(pr.author),
@@ -467,9 +490,10 @@ export function fromGitHubPullRequest(pr: GitHubPullRequest, provider: Provider)
 					: undefined,
 			)
 			.filter(<T>(r?: T): r is T => Boolean(r)),
-		pr.latestReviews.nodes.map(r => ({
+		latestReviews.map(r => ({
 			reviewer: fromGitHubMemberOrGhost(r.author),
 			state: fromGitHubPullRequestReviewState(r.state),
+			commitOid: r.commit?.oid,
 		})),
 		pr.assignees.nodes.map(r => ({
 			id: r.login,

package/src/plus/integrations/collectionMetadata.ts

@@ -4,12 +4,36 @@ import type {
 	CollectionScope,
 	CollectionScopeFailure,
 } from '@gitkraken/provider-apis';
+// Matched by its `code` discriminator rather than by `instanceof`: the SDK ships one bundle per entry point, so
+// the class reached through the root is not the same object as the one reached through `/providers`.
+import { isInvalidRequestError, isUnsupportedSortError } from '@gitkraken/provider-apis';
 import { AuthenticationError, RequestNotFoundError, RequestRateLimitError } from '../../git/errors.js';
 import type { IntegrationIds } from './constants.js';
 import { isRateLimitResponse } from './errors.js';
 import type { ProviderWarning, ProviderWarningOmission } from './results.js';
 import { appendDedupedWarning } from './results.js';
 
+/**
+ * Re-throws an error that is a fact about the CALL rather than about one scope of a fan-out.
+ *
+ * Every provider fan-out catches per-scope rejections and records them as {@link CollectionScopeFailure}s, which is
+ * right for auth, rate limits and a missing project: those really did happen to one scope, and the siblings that
+ * succeeded must survive. A caller-contract error is the opposite — it is identical for every scope and was decided
+ * before any request went out — so degrading it would hand back N indistinguishable failures and an empty `partial`
+ * page, describing an invalid call as an incomplete read.
+ *
+ * Today that means the SDK's `UnsupportedSortError` and `InvalidRequestError` — the two codes it lists in its own
+ * `CALLER_CONTRACT_ERROR_CODES`, both documented as "never degraded into a `CollectionScopeFailure` or an
+ * omission". The second covers arguments rejected before the first request goes out: a project key list longer
+ * than one Jira search can carry (or an empty one), a non-integer `pageSize`, an unknown current-user filter, or a
+ * Jira Server read with no `baseUrl` to address. Called from every fan-out rather than spelled out in each, so a
+ * fan-out added later inherits the rule instead of silently omitting it — which is exactly how Azure's
+ * account-wide drain came to degrade it while its three siblings did not.
+ */
+export function throwIfCallerContractError(ex: unknown): void {
+	if (isUnsupportedSortError(ex) || isInvalidRequestError(ex)) throw ex;
+}
+
 /**
  * Maps a caught GitLens request error to the SDK collection failure vocabulary used inside provider fan-outs.
  */

package/src/plus/integrations/integrationService.ts

@@ -67,19 +67,24 @@ import { createApiClients } from './providers/apiClients.js';
 import type { GitHubApi } from './providers/github/github.js';
 import type {
 	IssueFilter,
-	IssueSearchCapabilities,
+	IssueSorting,
 	ProviderOrganization,
 	ProviderReposInput,
 	ProviderRepositoryShape,
 	PullRequestFilter,
-	PullRequestSearchCapabilities,
 } from './providers/models.js';
 import { providersMetadata } from './providers/models.js';
 import type { ProvidersApi } from './providers/providersApi.js';
 import { broadenIssues } from './reads/broaden.js';
 import type { RepositoryResolutionContext } from './reads/context.js';
-import type { IssueCountResult, IssueCountScope } from './reads/counts.js';
-import { countIssues } from './reads/counts.js';
+import type {
+	IssueCountResult,
+	IssueCountScope,
+	PullRequestCountResult,
+	PullRequestCountScope,
+} from './reads/counts.js';
+import { countIssues, countPullRequests } from './reads/counts.js';
+import type { SupportedFilters } from './reads/filters.js';
 import { getSupportedFilters } from './reads/filters.js';
 import { listOrgs, listProjects, listRepos } from './reads/hierarchy.js';
 import { listIssuesPage } from './reads/issues.js';
@@ -537,14 +542,7 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 	 * stays a method here even though it needs no instance state; see {@link getSupportedFilters} for the
 	 * capability table itself and why a consumer should intersect against it before reading.
 	 */
-	getSupportedFilters(providerId: IntegrationIds): {
-		pullRequests: PullRequestFilter[];
-		pullRequestsAccountWide: PullRequestFilter[];
-		pullRequestSearch: PullRequestSearchCapabilities;
-		issues: IssueFilter[];
-		issuesAccountWide: IssueFilter[];
-		issueSearch: IssueSearchCapabilities;
-	} {
+	getSupportedFilters(providerId: IntegrationIds): SupportedFilters {
 		return getSupportedFilters(providerId);
 	}
 
@@ -1092,6 +1090,13 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		filters?: IssueFilter[];
 		/** Broadens the read to every assignee. Contradicts `filters`; passing both is refused. */
 		includeAllAssignees?: boolean;
+		/**
+		 * How to order the page, as `field:direction`. Omitted orders most-recently-updated-first wherever the
+		 * provider can express it. Validated against `getSupportedFilters().issueSorts` on the repo-scoped path and
+		 * `.issueSortsAccountWide` on the account-wide one, and refused rather than downgraded; a key no normalized
+		 * issue carries is additionally refused for a page spanning several repositories/projects, which is a merge.
+		 */
+		sort?: IssueSorting;
 		page?: number;
 		cursor?: string;
 		itemsPerPage?: number;
@@ -1147,6 +1152,24 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		return countIssues(this, options);
 	}
 
+	/**
+	 * How many pull requests match each scope, without fetching any — the PR twin of {@link countIssues}. See
+	 * {@link IntegrationManager.countPullRequests} for the cost model, the per-scope isolation rules, and why
+	 * `count: undefined` must not be rendered as zero.
+	 */
+	async countPullRequests(options: {
+		providerId: IntegrationIds;
+		scopes: readonly PullRequestCountScope[];
+		connectionId?: string;
+		/**
+		 * Explicit self-managed host domain. Used only when the requested connection has no configured domain;
+		 * it must come from the trusted authentication configuration, not repository or remote data.
+		 */
+		domain?: string;
+	}): Promise<ProviderResult<PullRequestCountResult>> {
+		return countPullRequests(this, options);
+	}
+
 	/**
 	 * Reads the user's issues from an issue-tracker provider (Jira/Linear/Trello), whose issues live under
 	 * resource → project (not repos), so they can't go through {@link listIssuesPage} (git-host, repo-scoped).
@@ -1174,6 +1197,11 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		project?: string;
 		filters?: IssueFilter[];
 		includeAllAssignees?: boolean;
+		/**
+		 * How to order the issues, as `field:direction`. Validated against `getSupportedFilters().issueSorts`, which
+		 * is where a tracker reports; a key no normalized issue carries is refused for a multi-project page.
+		 */
+		sort?: IssueSorting;
 		forceSync?: boolean;
 		page?: number;
 		cursor?: string;

package/src/plus/integrations/manager.ts

@@ -8,13 +8,14 @@ import type { Event } from '../../utils/event.js';
 import type { ConfiguredIntegrationsChangeEvent } from './authentication/configuredIntegrationService.js';
 import type { ConfiguredIntegrationDescriptor } from './authentication/models.js';
 import type { IntegrationIds } from './constants.js';
+import type { IssueFilter, IssueSorting, PullRequestFilter } from './providerFilters.js';
 import type {
-	IssueFilter,
-	IssueSearchCapabilities,
-	PullRequestFilter,
-	PullRequestSearchCapabilities,
-} from './providerFilters.js';
-import type { IssueCountResult, IssueCountScope } from './reads/counts.js';
+	IssueCountResult,
+	IssueCountScope,
+	PullRequestCountResult,
+	PullRequestCountScope,
+} from './reads/counts.js';
+import type { SupportedFilters } from './reads/filters.js';
 import type {
 	ConnectionStateChangeEvent,
 	ProviderBroadenResult,
@@ -160,6 +161,22 @@ type PullRequestSweepCommonOptions = {
 	 * This extends the provider-native result; it is not a narrowing filter.
 	 */
 	includeReviewRequested?: boolean;
+	/**
+	 * Account-wide only: fetch the full PR projection (review decision, review requests, latest reviews)
+	 * instead of the default summary/lite one. Opt-in because it enlarges every account-wide page; callers
+	 * that classify by review state (e.g. a "needs my review" surface) set it, others keep the lean read.
+	 *
+	 * GitHub/GHE only today — no other provider's account-wide read has a projection switch, so they return
+	 * their native shape regardless. A cross-provider sweep therefore gets reviews from GitHub targets and
+	 * whatever the others natively carry; it is a breadth request, not a guarantee, so it does not refuse
+	 * (unlike `filters`, where dropping a member would change the requested set).
+	 *
+	 * Projection only: it cannot change which pull requests come back. Every GitHub account-wide read goes through
+	 * the same search whether or not it is set, so the Launchpad ignored-repository and organization qualifiers
+	 * (and the per-facet result ceiling) apply the same either way. What it costs is the reduced page size, and a
+	 * document whose weight scales with the number of relationship × state facets in flight.
+	 */
+	includeReviews?: boolean;
 	forceSync?: boolean;
 	maxPages?: number;
 	/**
@@ -281,24 +298,7 @@ export interface IntegrationManager {
 	 * This is a capability table, not a recommendation: a consumer matching another tool's behavior may pass fewer
 	 * filters than are listed, or none where the underlying read is already scoped.
 	 */
-	getSupportedFilters(providerId: IntegrationIds): {
-		pullRequests: PullRequestFilter[];
-		/** Optional for structural compatibility; missing means no account-wide narrowing filters are supported. */
-		pullRequestsAccountWide?: PullRequestFilter[];
-		/**
-		 * Criteria and scopes {@link searchPullRequestsPage} can express. Always present; an empty relationship list
-		 * means the provider exposes no filtered pull-request search.
-		 */
-		pullRequestSearch: PullRequestSearchCapabilities;
-		issues: IssueFilter[];
-		issuesAccountWide: IssueFilter[];
-		/**
-		 * What {@link searchIssuesPage} (and {@link countIssues}, over the same criteria) can express for this
-		 * provider. Always present: a provider with no filtered issue search reports an empty `relationships` and
-		 * all-false flags, which is the signal to hide that surface rather than to hide individual chips.
-		 */
-		issueSearch: IssueSearchCapabilities;
-	};
+	getSupportedFilters(providerId: IntegrationIds): SupportedFilters;
 	/** Forces an authoritative cloud connection refresh. Rejects if the backend connection list cannot be read. */
 	refreshConnections(): Promise<void>;
 	/** Rejects unless `connectionId` is a configured cloud connection for `id`. */
@@ -376,10 +376,17 @@ export interface IntegrationManager {
 	 * GitHub's mismatched `involves:@me`. Omit relationships only with a repository/organization scope to search
 	 * every PR there.
 	 *
-	 * Results are always ordered most-recently-updated-first. If the provider's result ceiling is reached, the
-	 * request still succeeds and carries a warning omission with `totalCount`, `limit`, and `recovery: 'none'`.
-	 * `totalCount` is the largest provider-reported pre-ceiling facet count, not the reachable or returned row
-	 * count; this mirrors the per-search ceiling's own unit.
+	 * **Ordering is `criteria.sort`**, most-recently-updated-first when omitted. It is validated like every other
+	 * criterion — a key not in `getSupportedFilters().pullRequestSearch.sorts` refuses the whole read rather than
+	 * falling back, because at a bounded result window another order reaches another subset. The page is a union of
+	 * the provider's relationship × state facets, so it is re-ordered as a whole rather than served as concatenated
+	 * per-facet runs. Changing the sort invalidates a threaded cursor (it is part of the cursor's fingerprint,
+	 * alongside the text and the scope); drop the cursor when you change the order.
+	 *
+	 * If the provider's result ceiling is reached, the request still succeeds and carries a warning omission with
+	 * `totalCount`, `limit`, `sort`, and `recovery: 'none'`. `totalCount` is the largest provider-reported
+	 * pre-ceiling facet count, not the reachable or returned row count; this mirrors the per-search ceiling's own
+	 * unit.
 	 *
 	 * Check `getSupportedFilters().pullRequestSearch` before calling. A provider that reports no relationships
 	 * refuses the read rather than returning a page that never honored the criteria or scope.
@@ -427,6 +434,21 @@ export interface IntegrationManager {
 		filters?: IssueFilter[];
 		/** Broadens to every assignee. On account-wide reads it contradicts `filters`, so passing both is refused. */
 		includeAllAssignees?: boolean;
+		/**
+		 * How to order the page, as `field:direction` (e.g. `updated:desc`, `created:asc`). Omitted orders
+		 * most-recently-updated-first wherever the provider can express it — this facade's default, not the
+		 * provider's, which differ from each other.
+		 *
+		 * Validated against `getSupportedFilters().issueSorts` when `repos` is supplied and
+		 * `.issueSortsAccountWide` when it isn't, and refused (warning + `fetchFailed`) rather than downgraded: at
+		 * the provider's reachable window another order is another subset, so a silently different one is
+		 * indistinguishable from the one asked for. Keep it fixed across a pagination.
+		 *
+		 * With SEVERAL repositories/projects the page is a merge of one query each, so only a key a normalized
+		 * issue carries can be honored — `priority`, `dueDate` and `resolved` are refused there even where the
+		 * provider supports them on a single scope. The order applies within a page; across pages it is per scope.
+		 */
+		sort?: IssueSorting;
 		/**
 		 * Requested 1-based page. Without a `cursor` this may cost O(page) upstream requests on cursor-backed
 		 * reads such as repo-scoped GitHub/GHE; aggregate single-page account-wide reads remain O(1).
@@ -454,16 +476,21 @@ export interface IntegrationManager {
 	 * - **Scope is mandatory.** Pass `repos`, `org`, or a user relationship (`authored`/`assigned`/`mentioned`).
 	 *   `any-assignee`/`unassigned` do NOT scope anything — either alone matches every such issue on the host —
 	 *   so a call carrying only those is refused (warning + `fetchFailed`).
-	 * - **Ordering is always most-recently-updated-first**, not an option. A "show the N most recent" policy at
-	 *   the provider's result ceiling is only correct under a guaranteed order.
+	 * - **Ordering is `criteria.sort`**, most-recently-updated-first when omitted. It is validated like every other
+	 *   criterion (against `getSupportedFilters().issueSearch.sorts`) and refused rather than downgraded, and SOME
+	 *   order is always requested — a "show the N most recent" policy at the provider's result ceiling is only
+	 *   correct under a guaranteed one. Keep it fixed for the life of a pagination: a cursor is bound to the order
+	 *   that produced it, and threading it under a different key is REFUSED (warning + `fetchFailed`) rather than
+	 *   resumed into a differently-ordered set. To change the order, drop the cursor and read from the first page.
 	 * - **At the result ceiling the read SUCCEEDS.** It reports an omission carrying `totalCount` (how many
-	 *   matched) and `limit` (how many are reachable) with `recovery: 'none'`, so a consumer can say "19.240
-	 *   matched, showing the 1.000 most recent" and know not to offer a "load more". It never falls back to a
-	 *   per-repository recovery walk.
+	 *   matched), `limit` (how many are reachable) and `sort` (the order that window was selected under) with
+	 *   `recovery: 'none'`, so a consumer can say "19.240 matched, showing the 1.000 most recent" — naming the
+	 *   order, since which 1.000 are reachable depends on it — and know not to offer a "load more". It never falls
+	 *   back to a per-repository recovery walk.
 	 *
 	 * Check `getSupportedFilters().issueSearch` first: a provider with no filtered issue search reports empty
-	 * relationships (and this read refuses), and a criterion it can't express refuses the whole read rather than
-	 * serving a wider result than asked for.
+	 * relationships (and this read refuses), and a criterion or sort key it can't express refuses the whole read
+	 * rather than serving a wider or differently-ordered result than asked for.
 	 */
 	searchIssuesPage(options: {
 		providerId: IntegrationIds;
@@ -519,6 +546,23 @@ export interface IntegrationManager {
 		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
 		domain?: string;
 	}): Promise<ProviderResult<IssueCountResult>>;
+	/**
+	 * How many pull requests match each scope, fetching none of them — the PR twin of {@link countIssues}, behind a
+	 * "this will fetch ~N pull requests" preview and a live count next to an unapplied filter. Same cost model,
+	 * per-scope isolation, `key`-echo, and `count: undefined` ≠ zero rule as the issue count; GitHub/GHE only.
+	 *
+	 * The one PR-specific difference: a scope's `states` are counted as independent searches, so the reported count
+	 * is the LARGEST of them (the same total {@link searchPullRequestsPage} surfaces), not their sum. Several states
+	 * in one scope are therefore fine; only several relationships are refused — one relationship per scope, see
+	 * {@link PullRequestCountScope}.
+	 */
+	countPullRequests(options: {
+		providerId: IntegrationIds;
+		scopes: readonly PullRequestCountScope[];
+		connectionId?: string;
+		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+		domain?: string;
+	}): Promise<ProviderResult<PullRequestCountResult>>;
 	/** Issue trackers are cloud-only, so this read takes no `domain`. */
 	listIssueTrackerIssuesPage(options: {
 		providerId: IntegrationIds;
@@ -526,6 +570,16 @@ export interface IntegrationManager {
 		project?: string;
 		filters?: IssueFilter[];
 		includeAllAssignees?: boolean;
+		/**
+		 * How to order the issues, as `field:direction`. Omitted orders most-recently-updated-first where the
+		 * tracker can express it; validated against `getSupportedFilters().issueSorts` and refused rather than
+		 * downgraded. A page spanning several projects is a merge, so a key no normalized issue carries
+		 * (`priority`, `dueDate`, `resolved`) is refused there.
+		 *
+		 * Safe to change between pages, unlike the git-host reads: this cursor windows PROJECTS and drains each in
+		 * full, so which projects a round covers doesn't depend on how their issues are ordered.
+		 */
+		sort?: IssueSorting;
 		forceSync?: boolean;
 		page?: number;
 		/**