@gitkraken/core-gitlens 0.5.107 → 0.5.109

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

@@ -12,14 +12,30 @@ import { toTokenWithInfo } from '../authentication/models.js';
 import { toCollectionScopeFailure } from '../collectionMetadata.js';
 import { IssuesCloudHostIntegrationId } from '../constants.js';
 import { IntegrationReadUnavailableError } from '../errors.js';
+import type { AccountWideIssuesResult, IssuesForProjectOptions, SearchMyIssuesOptions } from '../models/issueReads.js';
 import { IssuesIntegration } from '../models/issuesIntegration.js';
-import type { IssueFilter, ProviderApiCollectionResult, ProviderIssue } from './models.js';
+import type { ProviderApiCollectionResult, ProviderIssue } from './models.js';
 import { fromProviderIssue, providersMetadata, toIssueShape } from './models.js';
 import { mergeCollectionMetadata } from './utils/providerPaging.js';
 
 const metadata = providersMetadata[IssuesCloudHostIntegrationId.Linear];
 const authProvider = Object.freeze({ id: metadata.id, scopes: metadata.scopes });
 const maxPagesPerRequest = 10;
+/**
+ * The account-wide drain's own backstop, separate from {@link maxPagesPerRequest}.
+ *
+ * Raised to 50 (5,000 issues at the SDK's 100-per-page) because 10 no longer means what it used to. That read
+ * once fanned out over four overlapping relationship queries and merged them, so most of what a page cost was
+ * rows already returned — a low budget capped the waste. It is now a single server-ordered query over an `or`
+ * filter, so every page is 100 issues the caller has not seen, and the same budget just truncates real results
+ * at 1,000.
+ *
+ * Reaching it is reported rather than silent: {@link LinearIntegration.searchProviderMyIssuesWithTruncation}
+ * returns `truncated`, so the facade can say the read was incomplete instead of publishing a capped list as a
+ * whole account. The bound stays — a runaway cursor must not spend requests forever — but it is now set where a
+ * real Linear account is unlikely to reach it rather than where the duplication used to hurt.
+ */
+const maxAccountWidePagesPerRequest = 50;
 const linearImplicitTeamsPageSize = 50;
 
 export interface LinearTeamDescriptor extends IssueResourceDescriptor {
@@ -194,7 +210,7 @@ export class LinearIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 	protected override async getProviderIssuesForProject(
 		session: ProviderAuthenticationSession,
 		project: ResourceDescriptor,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 	): Promise<IssueShape[] | undefined> {
 		return (await this.getProviderIssuesForProjectWithTruncation(session, project, options))?.values;
 	}
@@ -202,7 +218,7 @@ export class LinearIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 	protected override async getProviderIssuesForProjectWithTruncation(
 		session: ProviderAuthenticationSession,
 		project: ResourceDescriptor,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 	): Promise<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined> {
 		if (!isIssueResourceDescriptor(project)) return undefined;
 
@@ -222,7 +238,7 @@ export class LinearIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 				result = await api.getLinearIssues(
 					toTokenWithInfo(this.id, session),
 					{ teams: [project.id] },
-					{ cursor: cursor },
+					{ cursor: cursor, sort: options?.sort },
 				);
 			} catch (ex) {
 				// A page failure after the first page leaves the already-drained prefix intact; record the
@@ -305,14 +321,45 @@ export class LinearIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 		resources?: ResourceDescriptor[],
 		cancellation?: AbortSignal,
 	): Promise<IssueShape[] | undefined> {
+		return (await this.searchProviderMyIssuesWithTruncation(session, resources, cancellation))?.values;
+	}
+
+	/**
+	 * Account-wide "my issues" for Linear, drained to exhaustion and reporting whether it got there.
+	 *
+	 * The SDK read is one server-ordered query over an `or` filter across the four relationships (assigned,
+	 * created, named in an issue's content, named in a comment), so each page is 100 issues the caller has not
+	 * seen and the pages are ordered as one sequence. Draining it is therefore just following the cursor.
+	 *
+	 * Overridden rather than left to the base default because that default hardcodes `truncated: false`, and a
+	 * bounded drain that stops early is exactly the case a caller must be able to see. Three things end the
+	 * drain, and only one of them is completion:
+	 *
+	 * - the provider says there is no next page — complete;
+	 * - the backstop is reached — `truncated`, because issues beyond it exist and were not read;
+	 * - the provider claims a next page but hands back a cursor that does not advance — also `truncated`, since
+	 *   the read cannot continue and the remainder is unreachable rather than absent.
+	 *
+	 * Cancellation is deliberately NOT truncation: the caller asked for the read to stop, so the partial list is
+	 * what it asked for, and flagging it would surface an incompleteness warning for a user action.
+	 */
+	protected override async searchProviderMyIssuesWithTruncation(
+		session: ProviderAuthenticationSession,
+		resources?: ResourceDescriptor[],
+		cancellation?: AbortSignal,
+		options?: SearchMyIssuesOptions,
+	): Promise<AccountWideIssuesResult | undefined> {
 		if (resources != null) {
 			return undefined;
 		}
 
 		const api = await this.getProvidersApi();
 		let cursor = undefined;
-		let hasMore: boolean;
+		// Starts false so an immediate cancellation, which leaves the loop before the first response, reads as
+		// "no more pages known" rather than as an unfinished drain.
+		let hasMore = false;
 		let requestCount = 0;
+		let truncated = false;
 		const issues = [];
 		try {
 			do {
@@ -322,25 +369,47 @@ export class LinearIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 
 				const result = await api.getIssuesForCurrentUser(toTokenWithInfo(this.id, session), {
 					cursor: cursor,
+					sort: options?.sort,
 				});
 				requestCount += 1;
 				hasMore = result.paging?.more ?? false;
-				cursor = result.paging?.cursor;
+				const nextCursor = result.paging?.cursor;
+
+				// Keep this page before deciding whether to continue: the request is already paid for, so
+				// dropping its rows would lose real results to save nothing.
 				const formattedIssues = result.values
 					.map(issue => toIssueShape(issue, this))
 					.filter((result): result is IssueShape => result != null);
 				if (formattedIssues.length > 0) {
 					issues.push(...formattedIssues);
 				}
-			} while (requestCount < maxPagesPerRequest && hasMore);
+
+				// The provider claims more but hands back no advancing cursor: continuing would re-read the page
+				// just returned. `ProvidersApi.getPagedResult` already normalizes this into `more: false`, so
+				// this is a backstop for if that ever stops holding rather than a case seen today -- but the rest
+				// of the account is unreachable either way, which is what `truncated` says.
+				if (hasMore && (nextCursor == null || nextCursor === cursor)) {
+					truncated = true;
+					break;
+				}
+
+				cursor = nextCursor;
+			} while (requestCount < maxAccountWidePagesPerRequest && hasMore);
+
+			// Ran out of budget with pages still to come.
+			if (hasMore && requestCount >= maxAccountWidePagesPerRequest) {
+				truncated = true;
+			}
 		} catch (ex) {
 			if (issues.length === 0) {
 				throw ex;
 			}
 
+			// Kept what was already fetched, so the list is real but short of the account.
+			truncated = true;
 			Logger.error(ex, 'searchProviderMyIssues');
 		}
-		return issues;
+		return { values: issues, truncated: truncated };
 	}
 	protected override async getProviderLinkedIssueOrPullRequest(
 		session: ProviderAuthenticationSession,

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

@@ -75,7 +75,7 @@ import {
 	IssuesCloudHostIntegrationId,
 } from '../constants.js';
 import type { Integration, IntegrationType } from '../models/integration.js';
-import type { IssueSearchCapabilities, PullRequestSearchCapabilities } from '../providerFilters.js';
+import type { IssueSearchCapabilities, IssueSorting, PullRequestSearchCapabilities } from '../providerFilters.js';
 import { IssueFilter, PullRequestFilter } from '../providerFilters.js';
 
 export { IssueFilter, PullRequestFilter } from '../providerFilters.js';
@@ -83,12 +83,25 @@ export type {
 	IssueSearchCapabilities,
 	IssueSearchCriteria,
 	IssueSearchRelationship,
+	IssueSortField,
+	IssueSorting,
 	PullRequestSearchCapabilities,
 	PullRequestSearchCriteria,
 } from '../providerFilters.js';
 import type { ProviderRepositoryShape } from '../results.js';
 
 export type { ProviderOrganization, ProviderRepositoryShape } from '../results.js';
+import {
+	azureAccountWideIssueSorts,
+	azureIssueSorts,
+	githubAccountWideIssueSorts,
+	githubIssueSorts,
+	gitlabAccountWideIssueSorts,
+	gitlabIssueSorts,
+	jiraIssueSorts,
+	linearIssueSorts,
+	trelloIssueSorts,
+} from './issueSorts.js';
 import { getEntityIdentifierInput } from './utils.js';
 
 type GitBuildStatusState = GitBuildStatusStateType;
@@ -156,6 +169,28 @@ type EnrichableItem = any;
 export type ProviderAccount = Account;
 export type ProviderReposInput = (string | number)[] | GetRepoInput[];
 export type ProviderRepoInput = GetRepoInput;
+
+/**
+ * Which half of {@link ProviderReposInput} a caller supplied: repository IDS rather than descriptors.
+ *
+ * The union has no discriminant, so the answer is the element shape — and several layers need it for different
+ * reasons (`ProvidersApi` to pick `repoIds` vs `repos` in the SDK input, `GitHostIntegration` to refuse an
+ * id-based read a provider can't serve, `listIssuesPage` to know GitLab's id form takes the SDK's own merging
+ * aggregate). One predicate rather than one per layer, because each copy is free to disagree about the shape,
+ * and the symptom of disagreement is a read routed to the wrong provider query.
+ *
+ * Takes `unknown` rather than {@link ProviderReposInput} because `ProvidersApi.isRepoIdsInput` forwards here and
+ * is public with an unvalidated parameter, so the array check has to stay part of the rule rather than be assumed
+ * from the parameter type.
+ */
+export function isRepoIdsInput(input: unknown): input is (string | number)[] {
+	return (
+		input != null &&
+		Array.isArray(input) &&
+		input.every(repo => typeof repo === 'string' || typeof repo === 'number')
+	);
+}
+
 export type ProviderPullRequest = GitPullRequest;
 export type ProviderRepository = GitRepository;
 export type ProviderIssue = ProviderApiIssue;
@@ -331,6 +366,20 @@ export interface GetIssuesOptions {
 	page?: number;
 	// Items to request per page (numbered-page providers, plus GitHub's maxPageSize).
 	pageSize?: number;
+	/**
+	 * How the provider should order the result, as `field:direction`.
+	 *
+	 * Passed through to the SDK verbatim — the translation to each provider's own vocabulary lives THERE, next to
+	 * the capability map it validates against, so that the table this facade publishes and the table that does the
+	 * translating can't drift apart across two repositories. A key the provider can't express raises the SDK's
+	 * `UnsupportedSortError`, which is why the facade validates against `supportedIssueSorts` first: reaching that
+	 * error means this table has outrun the SDK's.
+	 *
+	 * Always supplied by the facade's reads, never omitted. Omitting it would delegate the order to each provider's
+	 * own default, which is the incoherence across providers the SDK deliberately preserves and this layer
+	 * deliberately does not.
+	 */
+	sort?: IssueSorting;
 }
 
 export interface GetIssuesForRepoInput extends GetIssuesOptions {
@@ -492,6 +541,8 @@ export type GetIssuesForCurrentUserInput = PagingInput & {
 	assigneeUsername?: string;
 	authorUsername?: string;
 	pageSize?: number;
+	/** See {@link GetIssuesOptions.sort}. */
+	sort?: IssueSorting;
 };
 
 export type GetIssuesForCurrentUserFn = (
@@ -624,10 +675,10 @@ export type GetBitbucketServerPullRequestsForCurrentUserFn = (
 	data: GitPullRequest[];
 }>;
 export type GetIssuesForProjectFn = Jira['getIssuesForProject'];
-export type GetIssuesForResourceForCurrentUserFn = (
-	input: { resourceId: string },
-	options?: EnterpriseOptions,
-) => Promise<{ data: ProviderIssue[] }>;
+// Derived from the client method rather than hand-declared, as its project-scoped sibling above already is: the
+// hand-written shape named only `resourceId`, so every other field the SDK accepts (the cursor, the sort, the
+// transitions switch) was invisible to the type system and had to be smuggled through `getPagedResult`'s `any`.
+export type GetIssuesForResourceForCurrentUserFn = Jira['getIssuesForResourceForCurrentUser'];
 
 // Trello reads (issues-capable provider). The Trello client is keyed by an `appKey` (the Trello app key from
 // the cloud token exchange) alongside the OAuth token, so these mirror the client method shapes directly.
@@ -729,6 +780,36 @@ export interface ProviderMetadata {
 	 * axes; it omits `Mention` because that REST read has no first-class mention filter.
 	 */
 	supportedAccountWideIssueFilters?: IssueFilter[];
+	/**
+	 * Sort keys the REPO-scoped issue read can express server-side — and, for an issue tracker (Jira/Linear/Trello),
+	 * its project-scoped read, which is the only issue surface a tracker has.
+	 *
+	 * Absent/empty means the read can't be ordered at all, so a request carrying `sort` is refused rather than
+	 * served in whatever order the provider felt like. Present, it is a promise: every key here reaches the
+	 * provider query.
+	 *
+	 * A key listed here is expressible on ONE provider query, which is what this read is when it is given ONE
+	 * scope. Given several (GitLab across repositories, Azure across projects, a tracker across projects) it merges
+	 * their results here and can only honor a key a normalized issue carries, so it additionally refuses
+	 * `priority`/`dueDate`/`resolved` — see `getIssueComparator`. That depends on the caller's scope count rather
+	 * than on the provider, which is why it is a runtime refusal and not a fourth table: encoding it here would
+	 * under-report the single-scope read, which really does support those keys.
+	 */
+	supportedIssueSorts?: IssueSorting[];
+	/**
+	 * Sort keys the ACCOUNT-WIDE issue read can express server-side, which is NOT the same set as
+	 * {@link ProviderMetadata.supportedIssueSorts} — for GitLab the two reads are different APIs (GraphQL vs REST)
+	 * with genuinely different vocabularies, not one narrowed twice.
+	 *
+	 * Absent means the account-wide read can't be ordered (or doesn't exist). An issue tracker leaves this empty
+	 * and reports under `supportedIssueSorts`, so reading a tracker's capability from here under-reports it.
+	 *
+	 * Unlike {@link ProviderMetadata.supportedIssueSorts} this needs no companion runtime refusal, because every
+	 * provider's account-wide read is a union of several queries with no scope count for a caller to reduce: it
+	 * ALWAYS merges. So the keys a merge can't order by are simply absent here — the table states what the read can
+	 * honor, which is what makes intersecting against it sufficient.
+	 */
+	supportedAccountWideIssueSorts?: IssueSorting[];
 	/**
 	 * What the provider's FILTERED issue search (`searchIssuesPage`, and the `countIssues` probe over the same
 	 * criteria) can express server-side. A third, wider surface than either filter set above: it is not bound to
@@ -774,6 +855,8 @@ const githubIssueSearchCapabilities: IssueSearchCapabilities = {
 	withoutLinkedPullRequest: true,
 	// `is:open` / `is:closed`, or neither for all states.
 	states: true,
+	// `sort:created-desc`, `sort:updated`, `sort:comments-asc`, … — see `githubIssueSorts`.
+	sorts: githubIssueSorts,
 };
 
 /** GitHub and GHE use the same filtered pull-request search syntax and result ceiling. */
@@ -820,6 +903,10 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read is three independent searches (`author:@me`, `assignee:@me`, `mentions:@me`) behind
 		// one composite cursor, so any subset of them is expressible.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
+		// One `search` field serves all three issue reads (repo-scoped, account-wide, filtered search), so the same
+		// qualifiers are expressible on each — the account-wide one narrowed to what its three-alias merge can order.
+		supportedIssueSorts: githubIssueSorts,
+		supportedAccountWideIssueSorts: githubAccountWideIssueSorts,
 		supportedIssueSearch: githubIssueSearchCapabilities,
 		issueSearchResultLimit: githubSearchResultLimit,
 		scopes: ['repo', 'read:user', 'user:email'],
@@ -852,6 +939,10 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read is three independent searches (`author:@me`, `assignee:@me`, `mentions:@me`) behind
 		// one composite cursor, so any subset of them is expressible.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
+		// One `search` field serves all three issue reads (repo-scoped, account-wide, filtered search), so the same
+		// qualifiers are expressible on each — the account-wide one narrowed to what its three-alias merge can order.
+		supportedIssueSorts: githubIssueSorts,
+		supportedAccountWideIssueSorts: githubAccountWideIssueSorts,
 		supportedIssueSearch: githubIssueSearchCapabilities,
 		issueSearchResultLimit: githubSearchResultLimit,
 		scopes: ['repo', 'read:user', 'user:email'],
@@ -881,6 +972,10 @@ export const providersMetadata: ProvidersMetadata = {
 		// unioned, so either axis is expressible on its own. Mention is absent because GitLab's REST issue read has
 		// no first-class mention filter to narrow with.
 		supportedAccountWideIssueFilters: [IssueFilter.Assignee, IssueFilter.Author],
+		// Two different surfaces, not one narrowed twice: the repository-scoped read is GraphQL and the
+		// account-wide one is REST, and REST has neither `title` nor `closed_at`.
+		supportedIssueSorts: gitlabIssueSorts,
+		supportedAccountWideIssueSorts: gitlabAccountWideIssueSorts,
 		scopes: ['api', 'read_user', 'read_repository'],
 	},
 	[GitSelfManagedHostIntegrationId.CloudGitLabSelfHosted]: {
@@ -908,6 +1003,10 @@ export const providersMetadata: ProvidersMetadata = {
 		// unioned, so either axis is expressible on its own. Mention is absent because GitLab's REST issue read has
 		// no first-class mention filter to narrow with.
 		supportedAccountWideIssueFilters: [IssueFilter.Assignee, IssueFilter.Author],
+		// Two different surfaces, not one narrowed twice: the repository-scoped read is GraphQL and the
+		// account-wide one is REST, and REST has neither `title` nor `closed_at`.
+		supportedIssueSorts: gitlabIssueSorts,
+		supportedAccountWideIssueSorts: gitlabAccountWideIssueSorts,
 		scopes: ['api', 'read_user', 'read_repository'],
 	},
 	[GitCloudHostIntegrationId.Bitbucket]: {
@@ -956,6 +1055,11 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read drains one (project × assignee) and one (project × author) query per project, so
 		// either axis is expressible on its own. There is no mention query to narrow to.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee],
+		// Both reads emit the same WIQL, but the account-wide one drains every (project x relationship) query and
+		// merges the results, so it can only honor keys a normalized issue carries — `resolved` and `priority` are
+		// dropped from that surface for the same reason they are dropped from GitLab's.
+		supportedIssueSorts: azureIssueSorts,
+		supportedAccountWideIssueSorts: azureAccountWideIssueSorts,
 		scopes: ['vso.code', 'vso.identity', 'vso.project', 'vso.profile', 'vso.work'],
 	},
 	[GitSelfManagedHostIntegrationId.AzureDevOpsServer]: {
@@ -982,6 +1086,11 @@ export const providersMetadata: ProvidersMetadata = {
 		// The account-wide read drains one (project × assignee) and one (project × author) query per project, so
 		// either axis is expressible on its own. There is no mention query to narrow to.
 		supportedAccountWideIssueFilters: [IssueFilter.Author, IssueFilter.Assignee],
+		// Both reads emit the same WIQL, but the account-wide one drains every (project x relationship) query and
+		// merges the results, so it can only honor keys a normalized issue carries — `resolved` and `priority` are
+		// dropped from that surface for the same reason they are dropped from GitLab's.
+		supportedIssueSorts: azureIssueSorts,
+		supportedAccountWideIssueSorts: azureAccountWideIssueSorts,
 		scopes: ['vso.code', 'vso.identity', 'vso.project', 'vso.profile', 'vso.work'],
 	},
 	[IssuesCloudHostIntegrationId.Jira]: {
@@ -1027,6 +1136,9 @@ export const providersMetadata: ProvidersMetadata = {
 			'read:project-version:jira',
 		],
 		supportedIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
+		// A tracker's issues live under resource -> project, so it has no account-wide surface to declare: its
+		// capability is reported under `issues`, which is what `listIssueTrackerIssuesPage` validates against.
+		supportedIssueSorts: jiraIssueSorts,
 	},
 	[IssuesCloudHostIntegrationId.Linear]: {
 		domain: 'linear.app',
@@ -1037,6 +1149,9 @@ export const providersMetadata: ProvidersMetadata = {
 		scopes: [],
 		// Linear scopes "my issues" client-side by the viewer's assignee id; author/mention aren't supported.
 		supportedIssueFilters: [IssueFilter.Assignee],
+		// Both directions, and one table for both reads: they are the same root `issues` query taking the same
+		// `sort` argument, so there is no account-wide narrowing to declare.
+		supportedIssueSorts: linearIssueSorts,
 	},
 	[IssuesCloudHostIntegrationId.Trello]: {
 		domain: 'trello.com',
@@ -1047,6 +1162,8 @@ export const providersMetadata: ProvidersMetadata = {
 		scopes: [],
 		// Trello cards are filtered by the assignee (member) only; author/mention have no Trello equivalent.
 		supportedIssueFilters: [IssueFilter.Assignee],
+		// `sort:edited` / `sort:-edited`. Trello's other search sorts (`created`, `due`) have no card-order effect.
+		supportedIssueSorts: trelloIssueSorts,
 	},
 };
 

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

@@ -39,6 +39,7 @@ import type {
 	GetPullRequestsOptions,
 	GetReposOptions,
 	IssueFilter,
+	IssueSorting,
 	PageInfo,
 	PagingInput,
 	PagingMode,
@@ -67,7 +68,7 @@ import type {
 	Providers,
 	PullRequestFilter,
 } from './models.js';
-import { providersMetadata } from './models.js';
+import { isRepoIdsInput, providersMetadata } from './models.js';
 import {
 	collectProviderPagedResult,
 	mergeCollectionMetadata,
@@ -132,6 +133,14 @@ function isGraphQLRepoNotFoundError(ex: unknown): boolean {
 
 const trelloBaseUrl = 'https://api.trello.com';
 
+/**
+ * Jira computes an issue's available transitions per issue, from the workflow and the reader's permissions, so a
+ * list read at a page size of 100 pays for 100 of those in both server work and response payload. Nothing in this
+ * package reads `statusTransitions` off a list — only the singular `getIssue` path exposes them, and it always
+ * expands them — so every list read opts out. Revisit the day a list row offers a status change straight off it.
+ */
+const jiraListIncludeTransitions = false;
+
 type TrelloMemberResponse = {
 	id: string;
 	username?: string | null;
@@ -479,12 +488,9 @@ export class ProvidersApi {
 		);
 	}
 
-	isRepoIdsInput(input: any): input is (string | number)[] {
-		return (
-			input != null &&
-			Array.isArray(input) &&
-			input.every((id: any) => typeof id === 'string' || typeof id === 'number')
-		);
+	/** See {@link isRepoIdsInput}, which owns the rule; kept as a method because callers reach it through the api. */
+	isRepoIdsInput(input: unknown): input is (string | number)[] {
+		return isRepoIdsInput(input);
 	}
 
 	private async getProviderToken<T extends IntegrationIds>(
@@ -868,7 +874,10 @@ export class ProvidersApi {
 	async getLinearIssues(
 		tokenOptInfo: TokenWithInfo<IssuesCloudHostIntegrationId.Linear>,
 		input: { teams?: string[]; projects?: string[]; labels?: string[] },
-		options?: PagingInput,
+		options?: PagingInput & {
+			/** See {@link GetIssuesOptions.sort}. Linear expresses `created`/`updated`, descending only. */
+			sort?: IssueSorting;
+		},
 	): Promise<PagedResult<ProviderIssue>> {
 		const { provider, tokenWithInfo } = await this.ensureProviderTokenAndFunction(
 			tokenOptInfo,
@@ -1565,6 +1574,8 @@ export class ProvidersApi {
 			 */
 			authorUsername?: string;
 			pageSize?: number;
+			/** See {@link GetIssuesOptions.sort}. Forwarded to the provider fn; ordering is translated in the SDK. */
+			sort?: IssueSorting;
 			isPAT?: boolean;
 			baseUrl?: string;
 		},
@@ -1580,6 +1591,7 @@ export class ProvidersApi {
 				authorUsername: options?.authorUsername,
 				page: options?.page,
 				pageSize: options?.pageSize,
+				sort: options?.sort,
 			},
 			provider.getIssuesForCurrentUserFn,
 			tokenWithInfo,
@@ -1626,7 +1638,12 @@ export class ProvidersApi {
 
 		try {
 			const result = await provider.getIssuesForProjectFn?.(
-				{ projectKey: project, resourceId: resourceId, ...options },
+				{
+					projectKey: project,
+					resourceId: resourceId,
+					...options,
+					includeTransitions: jiraListIncludeTransitions,
+				},
 				{ token: token },
 			);
 
@@ -1655,7 +1672,12 @@ export class ProvidersApi {
 
 		try {
 			const result = await provider.getIssuesForProjectFn?.(
-				{ projectKey: project, resourceId: resourceId, ...options },
+				{
+					projectKey: project,
+					resourceId: resourceId,
+					...options,
+					includeTransitions: jiraListIncludeTransitions,
+				},
 				{ token: token },
 			);
 			if (result == null) return undefined;
@@ -1760,7 +1782,12 @@ export class ProvidersApi {
 		tokenOptInfo: TokenWithInfo,
 		appKey: string,
 		boardId: string,
-		options?: { assigneeLogins?: string[]; trelloBoardListsById?: Record<string, { name: string }> },
+		options?: {
+			assigneeLogins?: string[];
+			trelloBoardListsById?: Record<string, { name: string }>;
+			/** See {@link GetIssuesOptions.sort}. Trello expresses only `updated`, in either direction. */
+			sort?: IssueSorting;
+		},
 	): Promise<ProviderApiCollectionResult<ProviderIssue>> {
 		const { provider, tokenWithInfo } = await this.ensureProviderTokenAndFunction(
 			tokenOptInfo,
@@ -1782,7 +1809,18 @@ export class ProvidersApi {
 	async getIssuesForResourceForCurrentUser(
 		tokenOptInfo: TokenWithInfo,
 		resourceId: string,
-		options?: { cursor?: string; isPAT?: boolean; baseUrl?: string },
+		options?: {
+			cursor?: string;
+			/**
+			 * See {@link GetIssuesOptions.sort}. Forwarded for the same reason as every sibling issue read, even
+			 * though nothing reaches this one with a sort today: `IssuesIntegration.searchProviderMyIssues` is the
+			 * only caller and takes no options. A wrapper that accepted the SDK's input and silently dropped one
+			 * field of it would give whoever adds that option no ordering and no error.
+			 */
+			sort?: IssueSorting;
+			isPAT?: boolean;
+			baseUrl?: string;
+		},
 	): Promise<PagedResult<ProviderIssue>> {
 		const { provider, tokenWithInfo } = await this.ensureProviderTokenAndFunction(
 			tokenOptInfo,
@@ -1790,7 +1828,7 @@ export class ProvidersApi {
 		);
 
 		return this.getPagedResult<ProviderIssue>(
-			{ resourceId: resourceId },
+			{ resourceId: resourceId, sort: options?.sort, includeTransitions: jiraListIncludeTransitions },
 			provider.getIssuesForResourceForCurrentUserFn,
 			tokenWithInfo,
 			options?.cursor,

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

@@ -9,8 +9,8 @@ import type { ProviderAuthenticationSession } from '../authentication/models.js'
 import { toTokenWithInfo } from '../authentication/models.js';
 import { IssuesCloudHostIntegrationId } from '../constants.js';
 import { IntegrationReadUnavailableError } from '../errors.js';
+import type { IssuesForProjectOptions } from '../models/issueReads.js';
 import { IssuesIntegration } from '../models/issuesIntegration.js';
-import type { IssueFilter } from './models.js';
 import { fromProviderIssue, providersMetadata, toIssueShape } from './models.js';
 
 const metadata = providersMetadata[IssuesCloudHostIntegrationId.Trello];
@@ -95,7 +95,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 	protected override async getProviderIssuesForProject(
 		session: ProviderAuthenticationSession,
 		project: ResourceDescriptor,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 	): Promise<IssueShape[] | undefined> {
 		return (await this.getProviderIssuesForProjectWithTruncation(session, project, options))?.values;
 	}
@@ -103,7 +103,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 	protected override async getProviderIssuesForProjectWithTruncation(
 		session: ProviderAuthenticationSession,
 		project: ResourceDescriptor,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 	): 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;
@@ -129,6 +129,7 @@ export class TrelloIntegration extends IssuesIntegration<IssuesCloudHostIntegrat
 		const result = await api.getTrelloIssuesForBoard(tokenWithInfo, appKey, project.id, {
 			assigneeLogins: options?.user != null ? [options.user] : undefined,
 			trelloBoardListsById: trelloBoardListsById,
+			sort: options?.sort,
 		});
 
 		const values = result.values.flatMap(issue => {

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

@@ -6,7 +6,7 @@ import type {
 } from '@gitkraken/provider-apis';
 import { isCancellationError } from '../../../../utils/cancellation.js';
 import { uniqueBy } from '../../../../utils/iterable.js';
-import { toCollectionScopeFailure } from '../../collectionMetadata.js';
+import { throwIfCallerContractError, toCollectionScopeFailure } from '../../collectionMetadata.js';
 import { collectionScopeKey } from '../../results.js';
 import type { ProviderApiPagedResult, ProviderHierarchyResult } from '../models.js';
 
@@ -144,6 +144,11 @@ export async function collectProviderPagedResult<T>(
 		} catch (ex) {
 			if (isCancellationError(ex)) throw ex;
 
+			// A caller-contract error is not a fact about this scope, so it is never recorded as one — see
+			// `throwIfCallerContractError`. Checked alongside cancellation because both are errors that a
+			// per-scope failure would misdescribe.
+			throwIfCallerContractError(ex);
+
 			// When the caller supplied a scope, preserve the items already fetched from that scope and record the
 			// failure in collection metadata rather than re-throwing and discarding the prefix. Callers without a
 			// scope keep the legacy throw behavior.

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

@@ -33,6 +33,12 @@ import { gitHostOnlySurfaceWarning, issuesUnsupportedWarning, noConnectionWarnin
  * `includeAllAssignees: true`, which resolves to no assignee constraint at all, so unassigned issues ARE
  * included. The equivalent is an OMITTED `relationships`, not `['any-assignee']`: `assignee:*` means "has some
  * assignee" and would silently exclude every unassigned issue, which is the opposite of broadening.
+ *
+ * Takes no `sort`, unlike `listIssuesPage` and `searchIssuesPage`. One logical page here spans several orgs, each
+ * at its own provider position in a cursor bundle, so honoring an order across them would need a k-way merge with
+ * a buffer per org rather than a sort of what arrived — the page is a slice of several independent walks, not a
+ * union of one round's results. `searchIssuesPage({ repos, criteria: { sort } })` answers the ordered version of
+ * this question for a caller that knows its repositories, and is already the recommended migration above.
  */
 
 export interface BroadenIssuesOptions {

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

@@ -44,7 +44,14 @@ export interface IssueCountScope {
 	/** Repositories to count over. Combines with `org`, exactly as in `searchIssuesPage`. */
 	repos?: ProviderReposInput;
 	org?: string;
-	/** Same criteria model as `searchIssuesPage`, validated against the same capability table. */
+	/**
+	 * Same criteria model as `searchIssuesPage`, validated against the same capability table.
+	 *
+	 * `criteria.sort` does not affect the count — a total is invariant under ordering — but it is still VALIDATED,
+	 * and an unsupported key refuses this scope exactly as it would refuse the read. That is the point of the
+	 * count: it previews the constraints the read will apply, so one that accepted what the read refuses would
+	 * promise a fetch that can't happen, which is worse than no preview at all.
+	 */
 	criteria?: IssueSearchCriteria;
 }