@gitkraken/core-gitlens 0.5.107 → 0.5.109

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,
@@ -59,6 +55,63 @@ export interface ProviderSweepTarget {
 	filters?: PullRequestFilter[];
 }
 
+/**
+ * One target's contribution to a pull-request sweep, reported as it settles.
+ *
+ * A sweep makes a single call and distributes its targets internally, so its aggregate result carries no
+ * per-target timing at all and only derivable per-target counts. This is the boundary that exposes them, for a
+ * host attributing a slow or failing sweep to the provider responsible.
+ *
+ * `outcome` is reported as one value rather than the underlying booleans because a consumer buckets by it, and
+ * because "the whole target is unusable" and "the target returned a slice with a gap" are different facts:
+ * a `failed-provider` target contributes nothing, a `fetch-failed` one contributes `count` rows that are
+ * incomplete. `skipped` is a target that resolved to no reachable connection and is deliberately not
+ * attributed in the aggregate result — reported anyway so a consumer counting targets never loses one.
+ *
+ * A target that produced no slice at all reports `count: 0` and `truncated: false` — always for `skipped`, and
+ * for `failed-provider` as `drainPullRequests` reports it today. Read those fields rather than deriving them
+ * from `outcome`: they are the target's own values, not constants the outcome guarantees.
+ */
+export interface ProviderSweepTargetEvent {
+	providerId: IntegrationIds;
+	/**
+	 * The self-managed host this target selects, resolved from its configured connection, its explicit domain,
+	 * or the provider's primary configured host — the same rule the read itself uses, and the same one whether
+	 * the target drained fully or was rejected by the first guard.
+	 *
+	 * Always `undefined` for a cloud provider: it has a single host, so there is nothing to disambiguate. Group
+	 * by `providerId` and treat this as a label, not part of the key.
+	 */
+	domain: string | undefined;
+	connectionId: string | undefined;
+	/**
+	 * Rows this target contributed to the aggregate result. The sweep concatenates target slices without a
+	 * cross-target pass — duplicates are collapsed per target, across its own pages — so these sum to exactly
+	 * `items.length`, and a sum that disagrees means a target went unreported.
+	 */
+	count: number;
+	/**
+	 * Wall time from this target's worker picking it up to its slice being ready.
+	 *
+	 * Targets in the same sweep run concurrently, so these intervals OVERLAP and are not additive: summing them
+	 * across a sweep exceeds the sweep's own duration. Compare them against each other, not against a total.
+	 */
+	durationMs: number;
+	/**
+	 * Wall time between the fan-out starting and this target's worker picking the target up.
+	 *
+	 * Structurally 0 only while the target count fits the fan-out's concurrency limit, which a selection of a
+	 * few providers does and the default sweep does NOT: with no `targets`/`providerIds` it opens one target per
+	 * supported git host, more than the limit, so the last ones genuinely wait. A non-zero value there is the
+	 * normal case, not an anomaly — it is the cost of the bound, and only worth acting on if it rivals
+	 * `durationMs`.
+	 */
+	queueWaitMs: number;
+	outcome: 'ok' | 'failed-provider' | 'fetch-failed' | 'skipped';
+	/** Whether this target left pages unread. */
+	truncated: boolean;
+}
+
 type ProviderSweepSelection =
 	| {
 			targets: readonly ProviderSweepTarget[];
@@ -105,6 +158,25 @@ type PullRequestSweepCommonOptions = {
 	includeReviewRequested?: boolean;
 	forceSync?: boolean;
 	maxPages?: number;
+	/**
+	 * Fired once per target as it settles, for host-side per-provider attribution.
+	 *
+	 * Observation only: it cannot influence the sweep, and a SYNCHRONOUS throw is swallowed rather than allowed
+	 * to turn a successful target into a failed one. Return nothing and do no async work: the `void` return type
+	 * admits an `async` callback, but nothing awaits it, so a rejection from one escapes that guarantee as an
+	 * unhandled rejection. It is also invoked synchronously in the middle of the fan-out — do not re-enter the
+	 * manager from it.
+	 *
+	 * Omitting it costs nothing at all, not even a clock read, so a host that only measures behind a gate can
+	 * leave the gate off without paying for the option.
+	 *
+	 * It reports how a target SETTLED, not every way one can end, and **delivery does not stop when the sweep
+	 * fails**: if a target's read throws instead of reporting failure through its slice, the sweep rejects with
+	 * that error, but its sibling targets are already in flight and are not cancelled, so their events still
+	 * arrive — after the returned promise has rejected. Key the accumulator to the call rather than closing it
+	 * on rejection, or a late event lands in whatever bucket is current by then.
+	 */
+	onTargetSettled?: (event: ProviderSweepTargetEvent) => void;
 };
 
 export type PullRequestSweepOptions = PullRequestSweepCommonOptions & ProviderSweepSelection;
@@ -205,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`. */
@@ -351,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).
@@ -378,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;
@@ -450,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;
 		/**

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

@@ -1,7 +1,7 @@
 import type { CollectionMetadata, CollectionScopeFailure } from '@gitkraken/provider-apis';
 import type { Account, UnidentifiedAuthor } from '../../../git/models/author.js';
 import type { DefaultBranch } from '../../../git/models/defaultBranch.js';
-import type { IssueSearchCriteria, IssueShape, IssueStateFilter } from '../../../git/models/issue.js';
+import type { IssueSearchCriteria, IssueShape } from '../../../git/models/issue.js';
 import type { IssueOrPullRequestState as PullRequestState } from '../../../git/models/issueOrPullRequest.js';
 import type {
 	PullRequest,
@@ -20,7 +20,7 @@ import { getScopedLogger } from '../../../utils/logger.scoped.js';
 import type { PagedResult } from '../../../utils/paging.js';
 import type { ProviderAuthenticationSession } from '../authentication/models.js';
 import { toTokenWithInfo } from '../authentication/models.js';
-import { toCollectionScopeFailure } from '../collectionMetadata.js';
+import { throwIfCallerContractError, toCollectionScopeFailure } from '../collectionMetadata.js';
 import type { IntegrationIds } from '../constants.js';
 import { GitCloudHostIntegrationId, GitSelfManagedHostIntegrationId } from '../constants.js';
 import { toError } from '../errors.js';
@@ -56,6 +56,7 @@ import type {
 	ProviderPullRequestSearchPage,
 } from './integration.js';
 import { IntegrationBase } from './integration.js';
+import type { MyIssuesForReposOptions } from './issueReads.js';
 
 function isAzureDevOpsProvider(
 	providerId: IntegrationIds,
@@ -673,17 +674,7 @@ export abstract class GitHostIntegration<
 
 	async getMyIssuesForRepos(
 		reposOrRepoIds: ProviderReposInput,
-		options?: {
-			filters?: IssueFilter[];
-			cursor?: string;
-			customUrl?: string;
-			page?: number;
-			pageSize?: number;
-			/** When true, don't constrain to the current user's assigned issues even if the Assignee filter is set. */
-			includeAllAssignees?: boolean;
-			/** Issue states to include; when omitted the provider returns its default (open only). */
-			state?: IssueStateFilter;
-		},
+		options?: MyIssuesForReposOptions,
 		connectionId?: string,
 	): Promise<PagedResult<ProviderIssue> | undefined> {
 		return (await this.getMyIssuesForReposResult(reposOrRepoIds, options, connectionId))?.value;
@@ -697,15 +688,7 @@ export abstract class GitHostIntegration<
 	 */
 	async getMyIssuesForReposResult(
 		reposOrRepoIds: ProviderReposInput,
-		options?: {
-			filters?: IssueFilter[];
-			cursor?: string;
-			customUrl?: string;
-			page?: number;
-			pageSize?: number;
-			includeAllAssignees?: boolean;
-			state?: IssueStateFilter;
-		},
+		options?: MyIssuesForReposOptions,
 		connectionId?: string,
 	): Promise<IntegrationResult<(PagedResult<ProviderIssue> & { metadata?: CollectionMetadata }) | undefined>> {
 		const scope = getScopedLogger();
@@ -828,6 +811,7 @@ export abstract class GitHostIntegration<
 								page: projectInput.cursor == null ? options?.page : undefined,
 								pageSize: options?.pageSize,
 								states: states,
+								sort: options?.sort,
 							},
 						);
 						return { projectInput: projectInput, results: results };
@@ -838,6 +822,10 @@ export abstract class GitHostIntegration<
 					const outcome = settled[i];
 					const projectInput = projectInputs[i];
 					if (outcome.status !== 'fulfilled') {
+						// Errors that really are per-scope (auth, rate limit, a missing project) degrade below; one
+						// that is a fact about the call is re-thrown instead — see `throwIfCallerContractError`.
+						throwIfCallerContractError(outcome.reason);
+
 						truncated = true;
 						const failure = toCollectionScopeFailure(
 							{
@@ -963,6 +951,7 @@ export abstract class GitHostIntegration<
 								page: repoInput.cursor == null ? options?.page : undefined,
 								pageSize: options?.pageSize,
 								states: states,
+								sort: options?.sort,
 							},
 						);
 						return { repoInput: repoInput, results: results };
@@ -973,6 +962,11 @@ export abstract class GitHostIntegration<
 					const outcome = settled[i];
 					const repoInput = repoInputs[i];
 					if (outcome.status !== 'fulfilled') {
+						// See the project fan-out above. Reachable in practice even though the facade validates the
+						// key first — a self-managed GitLab can reject an `IssueSort` member the SDK declares, which
+						// is only discoverable from the response.
+						throwIfCallerContractError(outcome.reason);
+
 						truncated = true;
 						const failure = toCollectionScopeFailure(
 							{
@@ -1030,6 +1024,7 @@ export abstract class GitHostIntegration<
 				page: options?.page,
 				pageSize: options?.pageSize,
 				states: states,
+				sort: options?.sort,
 			});
 			return { value: result, duration: performance.now() - start };
 		} catch (ex) {
@@ -1050,15 +1045,7 @@ export abstract class GitHostIntegration<
 	 */
 	async getMyIssuesForReposAsShapesResult(
 		reposOrRepoIds: ProviderReposInput,
-		options?: {
-			filters?: IssueFilter[];
-			cursor?: string;
-			customUrl?: string;
-			page?: number;
-			pageSize?: number;
-			includeAllAssignees?: boolean;
-			state?: IssueStateFilter;
-		},
+		options?: MyIssuesForReposOptions,
 		connectionId?: string,
 	): Promise<IntegrationResult<(PagedResult<IssueShape> & { metadata?: CollectionMetadata }) | undefined>> {
 		const result = await this.getMyIssuesForReposResult(reposOrRepoIds, options, connectionId);

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

@@ -1,5 +1,5 @@
 import type { CollectionMetadata } from '@gitkraken/provider-apis';
-import type { IssueShape } from '../../../git/models/issue.js';
+import type { IssueShape, IssueSorting, IssueStateFilter } from '../../../git/models/issue.js';
 import type { IssueFilter } from '../providerFilters.js';
 
 /**
@@ -42,6 +42,58 @@ export type ProviderIssueSearchPage = {
 	totalCount?: number;
 };
 
+/**
+ * Options for an issue tracker's PROJECT-scoped read (`IssuesIntegration.getIssuesForProject*`), which is the
+ * only issue surface a tracker has — its issues live under resource -> project, so there is no account-wide read
+ * to pair this with.
+ *
+ * Named rather than repeated inline at each of the six declarations this shape appears in (the two public
+ * `Result` methods, the two protected provider cores, and their Jira/Linear/Trello overrides), so a field added
+ * here can't reach five of them and be forgotten in the sixth.
+ */
+export type IssuesForProjectOptions = {
+	/** The account handle to scope to, resolved per resource by the caller. Omitted reads every assignee. */
+	user?: string;
+	/** Validated by the caller against `ProviderMetadata.supportedIssueFilters`; unsupported refuses the read. */
+	filters?: IssueFilter[];
+	/**
+	 * How the provider should order the project's issues, as `field:direction`.
+	 *
+	 * Validated against `ProviderMetadata.supportedIssueSorts` — a tracker reports there, not under the
+	 * account-wide table. Note the caller reads MANY projects and merges them, so it additionally refuses a key
+	 * no normalized issue carries; this option orders one project's query.
+	 */
+	sort?: IssueSorting;
+};
+
+/**
+ * Options for the REPO-scoped issue read (`GitHostIntegration.getMyIssuesForRepos*`), the git-host counterpart of
+ * {@link IssuesForProjectOptions}.
+ *
+ * Named for the same reason that one is: the shape appears at three declarations — the public method, its
+ * result-returning core, and the shapes-returning core that maps it — and was previously spelled out inline at
+ * each, so `sort` had to be added three times and two of the copies grew a `See {@link getMyIssuesForRepos}`
+ * breadcrumb to admit they were the same contract. One name means a field added here reaches all three.
+ */
+export type MyIssuesForReposOptions = {
+	/** Validated by the caller against `ProviderMetadata.supportedIssueFilters`; unsupported refuses the read. */
+	filters?: IssueFilter[];
+	cursor?: string;
+	customUrl?: string;
+	page?: number;
+	pageSize?: number;
+	/** When true, don't constrain to the current user's assigned issues even if the Assignee filter is set. */
+	includeAllAssignees?: boolean;
+	/** Issue states to include; when omitted the provider returns its default (open only). */
+	state?: IssueStateFilter;
+	/**
+	 * How the provider should order the read. Forwarded to every query this read issues, so the ORDER WITHIN each
+	 * scope is the provider's; the union across scopes is not ordered here — the facade (`listIssuesPage`) owns
+	 * that, because it is also the layer that can refuse a key no merge can honor.
+	 */
+	sort?: IssueSorting;
+};
+
 /**
  * Options for the account-wide issue read. `includeAllAssignees` drops the "assigned to me" scoping so the
  * read broadens to issues assigned to anyone (the account-wide equivalent of the repo-scoped
@@ -70,4 +122,16 @@ export type SearchMyIssuesOptions = {
 	 */
 	org?: string;
 	project?: string;
+	/**
+	 * How the provider should order the read, as `field:direction`.
+	 *
+	 * Validated by the facade against `ProviderMetadata.supportedAccountWideIssueSorts` — a DIFFERENT table from
+	 * the repo-scoped one, because for GitLab the two reads are different APIs with different sort vocabularies —
+	 * and refused rather than downgraded when the provider can't express it.
+	 *
+	 * Supplied on every facade read, never omitted: an omitted sort leaves each provider's own default, which is
+	 * exactly the cross-provider incoherence this layer exists to remove. A provider that reaches this with
+	 * `undefined` was called directly, not through the facade, and keeps whatever order it had.
+	 */
+	sort?: IssueSorting;
 };

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

@@ -8,9 +8,10 @@ import { getScopedLogger } from '../../../utils/logger.scoped.js';
 import type { ProviderAuthenticationSession } from '../authentication/models.js';
 import type { IntegrationIds } from '../constants.js';
 import { toError } from '../errors.js';
-import type { IssueFilter, ProviderApiCollectionResult } from '../providers/models.js';
+import type { ProviderApiCollectionResult } from '../providers/models.js';
 import type { Integration, IntegrationResult, IntegrationType } from './integration.js';
 import { IntegrationBase } from './integration.js';
+import type { IssuesForProjectOptions } from './issueReads.js';
 
 export function isIssuesIntegration(integration: Integration): integration is IssuesIntegration {
 	return integration.type === 'issues';
@@ -135,7 +136,7 @@ export abstract class IssuesIntegration<
 	@trace()
 	async getIssuesForProject(
 		project: T,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 		connectionId?: string,
 	): Promise<IssueShape[] | undefined> {
 		return (await this.getIssuesForProjectResult(project, options, connectionId))?.value;
@@ -148,7 +149,7 @@ export abstract class IssuesIntegration<
 	 */
 	async getIssuesForProjectResult(
 		project: T,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 		connectionId?: string,
 	): Promise<IntegrationResult<IssueShape[] | undefined>> {
 		const scope = getScopedLogger();
@@ -174,7 +175,7 @@ export abstract class IssuesIntegration<
 	 */
 	async getIssuesForProjectWithTruncationResult(
 		project: T,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 		connectionId?: string,
 	): Promise<
 		IntegrationResult<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined>
@@ -196,7 +197,7 @@ export abstract class IssuesIntegration<
 	protected abstract getProviderIssuesForProject(
 		session: ProviderAuthenticationSession,
 		project: T,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 	): Promise<IssueShape[] | undefined>;
 
 	/**
@@ -208,7 +209,7 @@ export abstract class IssuesIntegration<
 	protected async getProviderIssuesForProjectWithTruncation(
 		session: ProviderAuthenticationSession,
 		project: T,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 	): Promise<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined> {
 		const values = await this.getProviderIssuesForProject(session, project, options);
 		if (values == null) return undefined;

package/src/plus/integrations/providerFilters.ts

@@ -19,6 +19,8 @@ export type {
 	IssueSearchCapabilities,
 	IssueSearchCriteria,
 	IssueSearchRelationship,
+	IssueSortField,
+	IssueSorting,
 } from '../../git/models/issue.js';
 
 /**

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

@@ -1057,6 +1057,7 @@ export abstract class AzureDevOpsIntegrationBase<
 						...options,
 						...filter,
 						cursor: cursor,
+						sort: searchOptions?.sort,
 					}),
 				20,
 				{ providerId: this.id, resourceId: p.resourceId, projectId: p.name },

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

@@ -618,6 +618,7 @@ abstract class GitHubIntegrationBase<ID extends GitHubIntegrationIds> extends Gi
 				includeBody: true,
 				includeAllAssignees: options?.includeAllAssignees,
 				cursor: options?.cursor,
+				sort: options?.sort,
 				categories: options?.filters?.length
 					? {
 							authored: options.filters.includes(IssueFilter.Author),

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

@@ -668,6 +668,7 @@ abstract class GitLabIntegrationBase<ID extends GitLabIntegrationIds> extends Gi
 						isPAT: this.isEnterprise,
 						baseUrl: baseUrl,
 						cursor: cursor,
+						sort: options?.sort,
 					});
 					if (cancellation?.aborted) throw new CancellationError();
 					return page;

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

@@ -0,0 +1,89 @@
+import { SUPPORTED_ISSUE_SORTS } from '@gitkraken/provider-apis';
+import { getIssueComparator } from '../../../git/utils/issue.utils.js';
+import type { IssueSorting } from '../providerFilters.js';
+
+/**
+ * The per-provider ordering vocabulary of the issue reads: which neutral `field:direction` keys each provider
+ * surface can express SERVER-SIDE.
+ *
+ * DERIVED from `@gitkraken/provider-apis`, not transcribed from it. The SDK is where a neutral key becomes a
+ * provider query, so it is the only place that can say what a provider accepts; a copy kept here would be a
+ * second hand-maintained table on a second release cadence, and the symptom of drift is not a failed build but a
+ * read this facade promised and the SDK then rejects at runtime — which is exactly what happened while these were
+ * transcribed, on the one key (`reactions`) whose meaning is narrower than its name.
+ *
+ * Why the asymmetries between surfaces exist (GitHub cannot order by close date, GitLab's two reads are different
+ * APIs with different vocabularies, Azure has no `dueDate` outside the Agile process, Trello has only its
+ * `sort:edited` modifier, Jira has votes rather than reactions) is documented on the SDK's own maps. This module
+ * adds exactly one rule of its own — {@link mergeableSorts} — and everything else is a rename from the SDK's
+ * surface names to the two fields `ProviderMetadata` publishes.
+ *
+ * A caveat for anything building ONE ordering control across providers: a neutral key does not always mean the
+ * same thing. `priority:desc` is most-important-first on Jira and Linear, and least-important-first on Azure
+ * DevOps, whose WIQL orders the raw numeric column where 1 is the highest priority — so no single direction
+ * means "highest priority first" everywhere, and a unified control has to pick the direction per provider.
+ * `title` likewise orders by each backing database's collation, never JavaScript's.
+ */
+
+/** One SDK read surface, widened to the union this package uses (structurally the same `field:direction` type). */
+const surface = (name: keyof typeof SUPPORTED_ISSUE_SORTS): IssueSorting[] => [...SUPPORTED_ISSUE_SORTS[name]];
+
+/**
+ * The subset a MERGED page can honor: the keys a normalized issue carries.
+ *
+ * Applied to the account-wide surfaces because every account-wide read is a union of several provider queries
+ * merged in this facade — GitHub's three `@me` searches, GitLab's one REST call per relationship, Azure's
+ * (project × relationship) drains — and the caller has no scope count to reduce, so it ALWAYS merges. GitLab's
+ * REST endpoint really does order by `priority` and `dueDate`, and Azure's WIQL by `resolved` and `priority`;
+ * none of them survive a merge, so the surface cannot honor them and must not advertise them.
+ *
+ * Expressed as the rule rather than as a hand-removed list, so a key the SDK adds later is classified by the same
+ * predicate that will decide at read time whether the merge can order by it, instead of by whoever last edited a
+ * literal here. The repo-scoped surfaces are NOT filtered: those merge only when the caller passes several
+ * scopes, which is a property of the call rather than of the provider (see `mergesProviderQueries`).
+ */
+const mergeableSorts = (sorts: readonly IssueSorting[]): IssueSorting[] =>
+	sorts.filter(sort => getIssueComparator(sort) != null);
+
+/** GitHub and GHE: one `search` channel serves all three issue reads, so all three order the same way. */
+export const githubIssueSorts: IssueSorting[] = surface('github');
+
+/**
+ * The same `search` channel, narrowed to what the three `@me` searches can order once this facade has merged them.
+ *
+ * Identical to {@link githubIssueSorts} today — every qualifier the SDK's GitHub surface carries is a field an
+ * `IssueShape` models — so this exists for the drift, not for a difference: `readAccountWideIssuesPage`
+ * deliberately runs no `unmergeable` check, on the stated grounds that an account-wide table only lists keys a
+ * merge can honor. Left as the raw surface, one qualifier added upstream (a `closed` or `interactions` sort) would
+ * make that assumption false for GitHub alone and publish three concatenated alias runs under it, unwarned.
+ */
+export const githubAccountWideIssueSorts: IssueSorting[] = mergeableSorts(surface('github'));
+
+/** GitLab's repository-scoped read, which goes through GraphQL `IssueSort`. */
+export const gitlabIssueSorts: IssueSorting[] = surface('gitlabRepository');
+
+/** GitLab's account-wide read: the REST `order_by`/`sort` pair, narrowed to what its merge can order. */
+export const gitlabAccountWideIssueSorts: IssueSorting[] = mergeableSorts(surface('gitlabAccountWide'));
+
+/** Azure DevOps, as WIQL `ORDER BY` columns. */
+export const azureIssueSorts: IssueSorting[] = surface('azureDevOps');
+
+/** The same WIQL, narrowed to what the per-project fan-out can order once it has merged. */
+export const azureAccountWideIssueSorts: IssueSorting[] = mergeableSorts(surface('azureDevOps'));
+
+/** Jira Cloud and Server, as JQL `ORDER BY` fields — one JQL builder, so one surface. */
+export const jiraIssueSorts: IssueSorting[] = surface('jira');
+
+/**
+ * Linear's one root `issues` query, which both of its reads share and which takes the same `sort` argument in
+ * either direction — so this is one surface, not a repo-scoped and an account-wide pair.
+ *
+ * NOT filtered by {@link mergeableSorts} even though the account-wide read is "my issues": that read is a
+ * single server-ordered query (one `or` filter over the four relationships), so nothing is merged in this
+ * facade and there is no comparator to satisfy. Filtering it would drop `priority` and `dueDate` — keys the
+ * server really does order by — for a merge that does not happen.
+ */
+export const linearIssueSorts: IssueSorting[] = surface('linear');
+
+/** Trello's search modifiers: `sort:edited` / `sort:-edited`, and nothing else usable for issues. */
+export const trelloIssueSorts: IssueSorting[] = surface('trello');

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

@@ -8,8 +8,9 @@ import { Logger } from '../../../utils/logger.js';
 import type { IntegrationAuthenticationProviderDescriptor } from '../authentication/integrationAuthenticationProvider.js';
 import type { ProviderAuthenticationSession } from '../authentication/models.js';
 import { toTokenWithInfo } from '../authentication/models.js';
-import { toCollectionScopeFailure } from '../collectionMetadata.js';
+import { throwIfCallerContractError, toCollectionScopeFailure } from '../collectionMetadata.js';
 import { IssuesCloudHostIntegrationId } from '../constants.js';
+import type { IssuesForProjectOptions } from '../models/issueReads.js';
 import { IssuesIntegration } from '../models/issuesIntegration.js';
 import type { ProviderApiCollectionResult, ProviderIssue } from './models.js';
 import { IssueFilter, providersMetadata, toAccount, toIssueShape } from './models.js';
@@ -234,7 +235,7 @@ export class JiraIntegration extends IssuesIntegration<IssuesCloudHostIntegratio
 	protected override async getProviderIssuesForProject(
 		session: ProviderAuthenticationSession,
 		project: JiraProjectDescriptor,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 	): Promise<IssueShape[] | undefined> {
 		return (await this.getProviderIssuesForProjectWithTruncation(session, project, options))?.values;
 	}
@@ -242,7 +243,7 @@ export class JiraIntegration extends IssuesIntegration<IssuesCloudHostIntegratio
 	protected override async getProviderIssuesForProjectWithTruncation(
 		session: ProviderAuthenticationSession,
 		project: JiraProjectDescriptor,
-		options?: { user?: string; filters?: IssueFilter[] },
+		options?: IssuesForProjectOptions,
 	): Promise<{ values: IssueShape[]; truncated: boolean; metadata?: CollectionMetadata } | undefined> {
 		const tokenWithInfo = toTokenWithInfo(this.id, session);
 
@@ -273,6 +274,7 @@ export class JiraIntegration extends IssuesIntegration<IssuesCloudHostIntegratio
 					result = await api.getIssuesForProjectPaged(tokenWithInfo, project.name, project.resourceId, {
 						...scope,
 						cursor: cursor,
+						sort: options?.sort,
 					});
 				} catch (ex) {
 					// A page failure after the first page leaves the already-drained prefix intact; record the
@@ -390,6 +392,10 @@ export class JiraIntegration extends IssuesIntegration<IssuesCloudHostIntegratio
 				// incomplete: keep the sibling results but record a structured failure so the facade can warn on
 				// the specific filter (auth/rate-limit) instead of just a generic truncation flag.
 				if (outcome.status !== 'fulfilled') {
+					// Identical for every filter branch, so degrading it would report one failure per branch for a
+					// single invalid call — see `throwIfCallerContractError`.
+					throwIfCallerContractError(outcome.reason);
+
 					truncated = true;
 					const failure = toCollectionScopeFailure(
 						{ providerId: this.id, resourceId: project.resourceId, projectId: project.name },