@gitkraken/core-gitlens 0.5.108 → 0.5.109

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

@@ -11,7 +11,8 @@ import {
 } from '../../../git/errors.js';
 import type { Account, UnidentifiedAuthor } from '../../../git/models/author.js';
 import type { DefaultBranch } from '../../../git/models/defaultBranch.js';
-import type { Issue, IssueSearchCriteria, IssueShape } from '../../../git/models/issue.js';
+import type { Issue, IssueSearchCriteria, IssueShape, IssueSorting } from '../../../git/models/issue.js';
+import { defaultIssueSort } from '../../../git/models/issue.js';
 import type { IssueOrPullRequest } from '../../../git/models/issueOrPullRequest.js';
 import type {
 	PullRequest,
@@ -27,6 +28,7 @@ import type { GitRevisionRange } from '../../../git/models/revision.js';
 import type { GitUser } from '../../../git/models/user.js';
 import type { RepositoryVisibility } from '../../../git/providers/types.js';
 import { getGitHubNoReplyAddressParts } from '../../../git/remotes/github.js';
+import { effectiveIssueSort, getIssueComparator } from '../../../git/utils/issue.utils.js';
 import {
 	createRevisionRange,
 	getRevisionRangeParts,
@@ -77,11 +79,21 @@ import {
 	gitHubIssueSearchRelationships,
 	toGitHubIssueSearchQualifiers,
 	toGitHubIssueSearchScopeQualifiers,
+	toGitHubIssueSortQualifier,
 } from './issueSearchQuery.js';
 import { toGitHubPullRequestSearchFacets } from './pullRequestSearchQuery.js';
 import type { GitHubTokenInfo } from './token.js';
 
 const emptyPagedResult: PagedResult<any> = Object.freeze({ values: [] });
+/**
+ * What an issue-search cursor records when the caller asked for no ordering at all.
+ *
+ * A sentinel rather than an omitted field, because omitted already means something else and more important: a
+ * cursor persisted before ordering existed. Distinguishing the two is what lets an old cursor keep resuming while
+ * a genuine change from unordered to ordered is still refused. Not an `IssueSorting`, so it can never collide
+ * with one.
+ */
+const unsortedCursorSort = 'unsorted' as const;
 const emptyBlameResult: GitHubBlame = Object.freeze({ ranges: [] });
 
 // Transient gateway/network failures (e.g. an upstream `502 Bad Gateway`) are worth a few quick
@@ -3672,6 +3684,16 @@ export class GitHubApi {
 		return (await this.searchMyPullRequestsPage(provider, token, options, cancellation)).values;
 	}
 
+	/**
+	 * The current user's issues: authored ∪ assigned ∪ mentioned, each its own aliased search behind one composite
+	 * cursor. Bound to `@me` by construction, unlike {@link searchIssuesPage}.
+	 *
+	 * Ordering is OPT-IN here, and that asymmetry with {@link searchIssuesPage} is deliberate: this read has never
+	 * requested a sort, so GitHub has always answered it in relevance order. Emitting a default would change which
+	 * issues its already-shipped consumers see, so an omitted `sort` still emits no `sort:` qualifier at all and
+	 * keeps today's result. Pass one to get a defined order — which is also what makes a page budget meaningful,
+	 * since relevance ranking can shift under an unchanged upstream.
+	 */
 	@trace({ args: (provider, token) => ({ provider: provider.name, token: `<token:${token.microHash}>` }) })
 	async searchMyIssues(
 		provider: Provider,
@@ -3685,6 +3707,8 @@ export class GitHubApi {
 			includeBody?: boolean;
 			includeAllAssignees?: boolean;
 			cursor?: string;
+			/** Requested order. Omitted leaves GitHub's relevance order, which is what this read has always served. */
+			sort?: IssueSorting;
 			/**
 			 * Which of the three "my issues" searches to run. Omitted runs all three (GitHub's own definition of
 			 * "mine": authored ∪ assigned ∪ mentioned). Supplied, only the `true` ones run — so a caller wanting
@@ -3710,7 +3734,10 @@ export class GitHubApi {
 			search += `${repo}${options.repos.join(repo)}`;
 		}
 
-		const baseFilters = 'type:issue is:open archived:false';
+		// A requested sort goes through the same table `searchIssuesPage` uses, so the two GitHub issue reads can't
+		// diverge the first time a key is added. Omitted appends nothing — see this method's contract above.
+		const sortQualifier = toGitHubIssueSortQualifier(options?.sort);
+		const baseFilters = ['type:issue is:open archived:false', sortQualifier].filter(Boolean).join(' ');
 		// `includeAllAssignees` broadens the assigned category from "assigned to me" to "assigned to anyone"
 		// (`assignee:*` is GitHub's has-any-assignee qualifier). Authored/mentioned stay bound to `@me` — they're
 		// user-relative by definition, so an all-assignees read still only surfaces the current user's authored
@@ -3748,7 +3775,24 @@ export class GitHubApi {
 			searches.push({ alias: 'authored', query: `${search} ${baseFilters} author:@me`.trim() });
 		}
 
-		return this.searchIssuesByAlias(provider, token, searches, options, cancellation);
+		// Field by field, like `searchIssuesPage`: `options` also carries `repos`/`includeAllAssignees`/`categories`,
+		// already folded into `searches[].query` above and undeclared by the callee.
+		return this.searchIssuesByAlias(
+			provider,
+			token,
+			searches,
+			{
+				baseUrl: options?.baseUrl,
+				avatarSize: options?.avatarSize,
+				includeBody: options?.includeBody,
+				cursor: options?.cursor,
+				sort: options?.sort,
+				// This read emitted no `sort:` qualifier at all before ordering existed, so a cursor with no
+				// recorded key came out of a relevance-ordered walk.
+				legacySort: unsortedCursorSort,
+			},
+			cancellation,
+		);
 	}
 
 	/**
@@ -3756,9 +3800,15 @@ export class GitHubApi {
 	 * relationship to the current user. The issue counterpart of {@link searchMyPullRequestsPage}, and distinct
 	 * from {@link searchMyIssues}, which is permanently bound to `@me`.
 	 *
-	 * Ordering is part of the contract, not an option: always `sort:updated` (most recently updated first). A
-	 * consumer's "show the N most recent" policy at GitHub's result ceiling is only correct under a guaranteed
-	 * order, and an option would let a caller pick relevance order and then truncate to an arbitrary subset.
+	 * Ordering is `criteria.sort`, defaulting to most-recently-updated-first — the order this read served before
+	 * ordering was an option, so an omitted `sort` emits the identical query. What is NOT optional is that SOME
+	 * order is always requested: without one GitHub answers in relevance order, and at the result ceiling that
+	 * makes which rows are reachable a function of GitHub's ranking rather than of the request. A key GitHub can't
+	 * express (`closed`, `priority`, …) is refused by the facade before the request, not silently downgraded.
+	 *
+	 * With more than one relationship the page is a UNION of several searches, each ordered by the provider; the
+	 * merged page is re-sorted here so the whole page honors the requested key. Across pages the order is still
+	 * per-alias — see {@link searchIssuesByAlias}.
 	 *
 	 * Each requested relationship becomes its own aliased search, unioned and deduped by url; with none, a single
 	 * search runs over the scope alone. `criteria.text` and the other free-form values are sanitized so user input
@@ -3780,9 +3830,12 @@ export class GitHubApi {
 		},
 		cancellation?: AbortSignal,
 	): Promise<AliasedIssueSearchResult | undefined> {
+		// Resolved once: the emitted qualifier, the merged page's comparator and the cursor's fingerprint must all
+		// be the same key, which is what `effectiveIssueSort` exists to guarantee.
+		const sort = effectiveIssueSort(options?.criteria?.sort);
 		const base = [
 			...toGitHubIssueSearchScopeQualifiers(options?.org, options?.repos),
-			...toGitHubIssueSearchQualifiers(options?.criteria),
+			...toGitHubIssueSearchQualifiers(options?.criteria, sort),
 		].join(' ');
 
 		// One aliased search per relationship, OR-ed by union. They can't be one query: GitHub AND-s qualifiers,
@@ -3796,7 +3849,27 @@ export class GitHubApi {
 				}))
 			: [{ alias: 'matched', query: base }];
 
-		return this.searchIssuesByAlias(provider, token, searches, options, cancellation);
+		// Forwarded field by field rather than spread: `options` also carries `repos`/`org`/`criteria`, which are
+		// already baked into `searches[].query` above and which the callee declares nothing about. `sort` is the
+		// EFFECTIVE key, since the merged page and the cursor's fingerprint must both use the one the query used.
+		return this.searchIssuesByAlias(
+			provider,
+			token,
+			searches,
+			{
+				baseUrl: options?.baseUrl,
+				avatarSize: options?.avatarSize,
+				includeBody: options?.includeBody,
+				cursor: options?.cursor,
+				pageSize: options?.pageSize,
+				sort: sort,
+				// This read has always emitted `sort:updated`, which is `defaultIssueSort` — so a cursor with no
+				// recorded key came out of a walk under exactly that key, and only a caller asking for a
+				// different one has to restart.
+				legacySort: defaultIssueSort,
+			},
+			cancellation,
+		);
 	}
 
 	/**
@@ -3823,9 +3896,12 @@ export class GitHubApi {
 		if (scopes.length === 0) return [];
 
 		const queries = scopes.map(s => {
+			// The same resolved key the search would use, so the count previews the query it previews. Ordering
+			// cannot change a total, but emitting a DIFFERENT qualifier string than the search does would break the
+			// parity this probe is for.
 			const qualifiers = [
 				...toGitHubIssueSearchScopeQualifiers(s.org, s.repos),
-				...toGitHubIssueSearchQualifiers(s.criteria),
+				...toGitHubIssueSearchQualifiers(s.criteria, effectiveIssueSort(s.criteria?.sort)),
 			];
 
 			// A relationship set is OR-ed across searches, which a single count can't express — the facade splits
@@ -3886,14 +3962,31 @@ export class GitHubApi {
 	 * {@link searchMyIssues} is one configuration of it (its three `@me` categories), and its alias names are
 	 * that read's published cursor keys.
 	 *
-	 * `searches` must have unique aliases, each a valid GraphQL name that is neither `page` nor `truncated` —
-	 * the composite cursor keys aliases at its top level, alongside those two reserved fields.
+	 * `searches` must have unique aliases, each a valid GraphQL name that is none of `page`, `truncated` or
+	 * `sort` — the composite cursor keys aliases at its top level, alongside those three reserved fields.
+	 *
+	 * `sort` is the order the caller asked for, which this does two things with. Each alias comes back ordered by
+	 * it (the qualifier is already in `searches[].query`), but the UNION of several aliases is not, so the merged
+	 * page is re-sorted here; and the key is recorded in the cursor, so a continuation that changed it THROWS
+	 * rather than serving a sequence with gaps and repeats. Omitted means the caller asked for no order at all
+	 * ({@link searchMyIssues}'s default), which re-sorts nothing and pins nothing.
+	 *
+	 * `legacySort` is the order the calling read produced BEFORE this field existed, and is what a cursor with no
+	 * recorded key is compared against — such a cursor is not of unknown order, it is of that read's old one.
 	 */
 	private async searchIssuesByAlias(
 		provider: Provider,
 		token: GitHubTokenInfo,
 		searches: readonly AliasedIssueSearch[],
-		options?: { baseUrl?: string; avatarSize?: number; includeBody?: boolean; cursor?: string; pageSize?: number },
+		options: {
+			baseUrl?: string;
+			avatarSize?: number;
+			includeBody?: boolean;
+			cursor?: string;
+			pageSize?: number;
+			sort?: IssueSorting;
+			legacySort: IssueSorting | typeof unsortedCursorSort;
+		},
 		cancellation?: AbortSignal,
 	): Promise<AliasedIssueSearchResult | undefined> {
 		const scope = getScopedLogger();
@@ -3914,6 +4007,16 @@ export class GitHubApi {
 		interface SearchCursor {
 			page?: number;
 			truncated?: boolean;
+			/**
+			 * The order this cursor's pages were produced under: an `IssueSorting`, or `unsortedCursorSort` when
+			 * the caller asked for none. Written as a value rather than left absent in the no-order case
+			 * specifically so that ABSENT keeps meaning "cursor from before ordering existed", which is accepted
+			 * and sealed instead of refused — a consumer's persisted cursor has to keep working across this change.
+			 *
+			 * Those three cases are the whole domain, so it is typed as them rather than as `string`: a foreign
+			 * cursor carrying something else is caught by the mismatch check either way.
+			 */
+			sort?: IssueSorting | typeof unsortedCursorSort;
 			[alias: string]: string | number | boolean | null | undefined;
 		}
 
@@ -3922,19 +4025,54 @@ export class GitHubApi {
 		// by a cursor string that reads back as page 1, restarting the walk with no error and no truncation flag.
 		// Cheap to check, and it fails at the one call that introduced the collision rather than in a consumer's
 		// persisted cursor.
-		const reserved = searches.filter(s => s.alias === 'page' || s.alias === 'truncated');
+		const reserved = searches.filter(s => s.alias === 'page' || s.alias === 'truncated' || s.alias === 'sort');
 		if (reserved.length > 0) {
 			throw new Error(
 				`Issue search alias(es) ${reserved.map(s => `'${s.alias}'`).join(', ')} collide with the composite cursor's reserved keys`,
 			);
 		}
 
+		// A key GitHub cannot express emits no `sort:` qualifier, so each alias would come back in RELEVANCE order
+		// while the union below is sorted by that key and the cursor sealed under it: an arbitrary subset,
+		// presented as ordered, resumable only into more of the same. Refused here rather than downgraded, which
+		// is the rule the whole feature is built on. Unreachable through the facade — no `supportedIssueSorts`
+		// table declares a key without a qualifier — so this guards the direct callers of the two public reads,
+		// where `title` is expressible enough to have a comparator and not enough to be a GitHub search qualifier.
+		if (options.sort != null && toGitHubIssueSortQualifier(options.sort) == null) {
+			throw new Error(`GitHub cannot order an issue search by '${options.sort}'`);
+		}
+
 		let cursor: SearchCursor | undefined;
 		if (options?.cursor != null) {
 			try {
 				cursor = JSON.parse(options.cursor) as SearchCursor;
 			} catch {}
 		}
+		// The order this request is being made under, as the cursor records it.
+		const requestedSort = options.sort ?? unsortedCursorSort;
+		// A cursor produced under a DIFFERENT order can't be resumed: every alias would continue from a position in
+		// a differently-ordered result set, so the continuation re-emits rows already seen and skips rows never
+		// seen. REFUSED rather than silently restarted from page 1, because a restart cannot be reported honestly
+		// from here: this read is cursor-only, so `resolveCurrentPage` has no page of its own to trust and echoes
+		// the `page` the caller supplied alongside the cursor — page 1's rows would be published as page N, which
+		// is the very confusion the fingerprint exists to prevent. Refusing surfaces a warning + `fetchFailed`, and
+		// the remedy ("drop the cursor") is the caller's to apply.
+		//
+		// A cursor with NO recorded sort predates this field — which is not the same as being of unknown order.
+		// Each read produced exactly one order before ordering was an option (`sort:updated` for the filtered
+		// search, relevance for `searchMyIssues`), so an absent key reads as THAT one, `legacySort`. Compared
+		// rather than waved through: the facade now resolves an omitted key to `defaultIssueSort`, so the
+		// account-wide read's query gained a `sort:updated` qualifier it did not have, and resuming a
+		// relevance-ordered cursor inside it advances each alias through a re-ordered result set — the gaps and
+		// repeats this check exists to prevent, arriving through the very case meant to keep working. A cursor
+		// whose implied key matches the request still resumes, and is sealed with the current one.
+		const cursorSort = cursor?.sort ?? options.legacySort;
+		if (cursor != null && cursorSort !== requestedSort) {
+			throw new Error(
+				`Issue search cursor was produced under sort '${cursorSort}' but '${requestedSort}' was requested; restart the read without a cursor`,
+			);
+		}
+
 		const page = Math.max(1, Math.trunc(cursor?.page ?? 1));
 		// A slot is a continuation string, `null` (exhausted), or absent. Anything else came from a malformed or
 		// foreign cursor, and is read as absent rather than threaded back into the request as a continuation.
@@ -4023,16 +4161,38 @@ export class GitHubApi {
 
 			// Dedupe by `url`, not `IssueShape.id`: for some providers `id` is a per-repository number, so an
 			// id-keyed map would collapse distinct issues across repositories.
-			const results: IterableIterator<IssueShape> = uniqueBy(
-				issues,
-				r => r.url,
-				(original, _current) => original,
-			);
+			const deduped = [
+				...uniqueBy(
+					issues,
+					r => r.url,
+					(original, _current) => original,
+				),
+			];
+
+			// Each alias arrived ordered by the server; their concatenation is not, so the merged page is ordered
+			// here. AFTER the dedupe, not before, and that ordering is load-bearing: the alias order is also the
+			// dedupe's precedence (an issue both assigned to and authored by the user surfaces as the assigned one,
+			// per `searchMyIssues`), and sorting first would hand `uniqueBy` a different first occurrence and
+			// silently change which copy wins. The pull-request path sorts BEFORE its dedupe because its facets
+			// carry no such precedence — the difference is deliberate, not an inconsistency to tidy up.
+			//
+			// A comparator is always available for a key GitHub declares (`created`/`updated`/`comments`/
+			// `reactions` are all on `IssueShape`), so `undefined` here means the capability table has outrun this
+			// read; leave the provider's per-alias order rather than inventing one.
+			//
+			// Counted over `active`, not `searches`: continuations exhaust aliases one at a time, so a later page of
+			// a three-category walk can come from ONE surviving search — already ordered by the server. Re-sorting
+			// it could only reproduce that order, while hiding a provider that ignored the qualifier.
+			const comparator = options?.sort != null ? getIssueComparator(options.sort) : undefined;
+			if (comparator != null && active.length > 1) {
+				deduped.sort(comparator);
+			}
 
 			// Every alias gets a slot, so an inactive one keeps its `null` and stays out of the next request. A
 			// missing slot would be read as "never requested", which for a `searches` set that still lists it
 			// would restart it from its first page.
-			const next: SearchCursor = { page: page + 1 };
+			// The order is pinned on the way out too, so the next round can refuse a changed key (see above).
+			const next: SearchCursor = { page: page + 1, sort: requestedSort };
 			let hasMore = false;
 			let continuationMissing = false;
 			let maxIssueCount = 0;
@@ -4057,7 +4217,7 @@ export class GitHubApi {
 				cursor?.truncated === true || maxIssueCount > githubSearchResultLimit || continuationMissing;
 			next.truncated = truncated || undefined;
 			return {
-				values: [...results],
+				values: deduped,
 				cursor: hasMore ? JSON.stringify(next) : undefined,
 				hasMore: hasMore,
 				page: page,

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/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,12 +67,11 @@ 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';
@@ -80,6 +79,7 @@ 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 { 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 +537,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 +1085,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;
@@ -1174,6 +1174,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,9 @@ 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,
-	IssueSearchCapabilities,
-	PullRequestFilter,
-	PullRequestSearchCapabilities,
-} from './providerFilters.js';
+import type { IssueFilter, IssueSorting, PullRequestFilter } from './providerFilters.js';
 import type { IssueCountResult, IssueCountScope } from './reads/counts.js';
+import type { SupportedFilters } from './reads/filters.js';
 import type {
 	ConnectionStateChangeEvent,
 	ProviderBroadenResult,
@@ -281,24 +277,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`. */
@@ -427,6 +406,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 +448,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;
@@ -526,6 +525,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;
 		/**