@gitkraken/core-gitlens 0.5.103 → 0.5.104

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

@@ -1,5 +1,12 @@
 import type { IntegrationIds } from '../constants.js';
-import type { IssueFilter, PullRequestFilter } from '../providerFilters.js';
+import type {
+	IssueFilter,
+	IssueSearchCapabilities,
+	IssueSearchCriteria,
+	IssueSearchRelationship,
+	PullRequestFilter,
+} from '../providerFilters.js';
+import type { ProviderRepoInput, ProviderReposInput } from '../providers/models.js';
 import { providersMetadata } from '../providers/models.js';
 
 /**
@@ -79,6 +86,139 @@ export function resolveAccountWideIssueFilters(
 	return { filters: filters, unsupported: false };
 }
 
+/** Why {@link resolveIssueSearchCriteria} refused a criteria set, so the caller can word the refusal exactly. */
+export type IssueSearchCriteriaRejection =
+	/** The provider has no filtered issue search at all. */
+	| { reason: 'unsupported-search' }
+	/** The provider has one, but can't express these criteria server-side. */
+	| { reason: 'unsupported-criteria'; criteria: string[] }
+	/** `any-assignee` and `unassigned` partition the scope between them; asking for both asks for nothing. */
+	| { reason: 'contradictory-relationships' };
+
+/**
+ * Validates a filtered issue search's criteria against {@link ProviderMetadata.supportedIssueSearch}.
+ *
+ * All-or-nothing like its three siblings above, and for the same reason: a criterion dropped because the
+ * provider can't express it would serve a WIDER result than was asked for, and narrowing the returned page
+ * afterward would leave `items` describing a different result set than the `hasMore`/`cursor` the provider
+ * produced with it. So an inexpressible set is refused whole and the caller surfaces a warning.
+ *
+ * Unlike the sibling validators this also rejects a set that is internally contradictory, because this criteria
+ * model is the only one with two members that partition the scope between them (`any-assignee` ∪ `unassigned` =
+ * everything, ∩ = nothing). Silently keeping one would answer a question the caller didn't ask.
+ *
+ * `undefined` (or an empty relationship list plus no other criterion) is a valid UNNARROWED search of the given
+ * scope, not an error — the caller's `repos`/`org` is what bounds it.
+ */
+export function resolveIssueSearchCriteria(
+	id: IntegrationIds,
+	criteria: IssueSearchCriteria | undefined,
+): { rejection?: IssueSearchCriteriaRejection } {
+	const supported = providersMetadata[id]?.supportedIssueSearch;
+	if (supported == null) return { rejection: { reason: 'unsupported-search' } };
+	if (criteria == null) return {};
+
+	const relationships = criteria.relationships;
+	if (relationships?.includes('any-assignee') && relationships.includes('unassigned')) {
+		return { rejection: { reason: 'contradictory-relationships' } };
+	}
+
+	const unsupported: string[] = [];
+	for (const relationship of relationships ?? []) {
+		if (!supported.relationships.includes(relationship)) {
+			unsupported.push(`relationships:${relationship}`);
+		}
+	}
+	// Only a criterion the caller actually SET can be unsupported. `false`/empty means "don't narrow on this",
+	// which every provider can honor by doing nothing, so it must not be validated as a request.
+	if (criteria.text != null && criteria.text.trim().length > 0 && !supported.text) {
+		unsupported.push('text');
+	}
+	if (criteria.labels?.length && !supported.labels) {
+		unsupported.push('labels');
+	}
+	if (criteria.milestone != null && !supported.milestone) {
+		unsupported.push('milestone');
+	}
+	if (criteria.updatedAfter != null && !supported.updatedAfter) {
+		unsupported.push('updatedAfter');
+	}
+	if (criteria.createdAfter != null && !supported.createdAfter) {
+		unsupported.push('createdAfter');
+	}
+	if (criteria.withoutLinkedPullRequest === true && !supported.withoutLinkedPullRequest) {
+		unsupported.push('withoutLinkedPullRequest');
+	}
+	// `'open'` is every provider's own default, so asking for it needs no state capability.
+	if (criteria.state != null && criteria.state !== 'open' && !supported.states) {
+		unsupported.push('state');
+	}
+
+	if (unsupported.length > 0) return { rejection: { reason: 'unsupported-criteria', criteria: unsupported } };
+
+	return {};
+}
+
+/**
+ * The relationships that bound a filtered issue search to the CURRENT USER, and so can stand in for a
+ * repository/org scope.
+ *
+ * Derived from the union rather than spelled out per call site, because the distinction it encodes is the whole
+ * reason the scope rule exists: `any-assignee` and `unassigned` are deliberately absent — they describe the
+ * ISSUE, not the caller, so neither reduces the search to anyone's own world (measured: unscoped `no:assignee`
+ * matches ~45 million issues on GitHub).
+ */
+const userScopingIssueSearchRelationships: readonly IssueSearchRelationship[] = ['authored', 'assigned', 'mentioned'];
+
+/** What a provider with NO filtered issue search reports: nothing expressible, spelled out rather than absent. */
+const unsupportedIssueSearchCapabilities: IssueSearchCapabilities = {
+	relationships: [],
+	text: false,
+	labels: false,
+	milestone: false,
+	updatedAfter: false,
+	createdAfter: false,
+	withoutLinkedPullRequest: false,
+	states: false,
+};
+
+/** Why a filtered issue search's scope was refused, or `undefined` when it is usable. */
+export type IssueSearchScopeRejection =
+	/** No repositories, no org, and no user-relative relationship: a search of the whole host. */
+	| 'unscoped'
+	/** Repositories given as ids. A search names repositories by PATH, so ids can't express a scope. */
+	| 'repo-ids';
+
+/**
+ * Validates that a filtered issue search is scoped at all, and narrows `repos` to the descriptor form the
+ * provider query needs.
+ *
+ * Shared by `searchIssuesPage` and `countIssues` because a count computed under different constraints than the
+ * read it previews is a WRONG number rather than a missing one. The rejection is returned as a reason code, not a
+ * warning: the two callers word it differently (whole-read vs naming the offending scope's key), and wording is
+ * the warning layer's business.
+ *
+ * The two rejections are mutually exclusive — `repo-ids` requires repositories and `unscoped` requires none — so
+ * the order they're checked in cannot change the outcome.
+ */
+export function resolveIssueSearchScope(
+	repos: ProviderReposInput | undefined,
+	org: string | undefined,
+	criteria: IssueSearchCriteria | undefined,
+): { rejection?: IssueSearchScopeRejection; repos?: ProviderRepoInput[] } {
+	if (repos?.length) {
+		// `ProviderReposInput` is a union of descriptor and id arrays; only the descriptor form is usable here.
+		if (repos.some(r => typeof r === 'string' || typeof r === 'number')) return { rejection: 'repo-ids' };
+
+		return { repos: repos as ProviderRepoInput[] };
+	}
+
+	if (org != null && org.length > 0) return {};
+	if (criteria?.relationships?.some(r => userScopingIssueSearchRelationships.includes(r)) === true) return {};
+
+	return { rejection: 'unscoped' };
+}
+
 /**
  * The filters `listPullRequestsPage`/`listIssuesPage` (and the sweeps) accept for a provider, so a caller can
  * narrow to what the provider can express BEFORE issuing the read.
@@ -103,6 +243,11 @@ export function resolveAccountWideIssueFilters(
  * {@link IntegrationService.listIssueTrackerIssuesPage} validates against, and leaves `issuesAccountWide`
  * empty. Reading a tracker's capability off `issuesAccountWide` therefore under-reports it.
  *
+ * `issueSearch` is a third, wider surface: the FILTERED issue search (`searchIssuesPage`, and the `countIssues`
+ * probe over the same criteria), which is not bound to the user at all. It is a record of per-criterion flags
+ * rather than a list, because its criteria aren't a single kind. An empty `relationships` means the provider has
+ * no filtered issue search — hide the surface, not just its chips.
+ *
  * Note this is a CAPABILITY table — "what the provider can express" — not a recommendation. A consumer
  * matching another tool's behavior may deliberately pass fewer filters than are listed here (or none, where an
  * already-scoped read would only be narrowed by them). Intersecting against this table is what keeps a
@@ -113,12 +258,28 @@ export function getSupportedFilters(providerId: IntegrationIds): {
 	pullRequestsAccountWide: PullRequestFilter[];
 	issues: IssueFilter[];
 	issuesAccountWide: IssueFilter[];
+	issueSearch: IssueSearchCapabilities;
 } {
 	const metadata = providersMetadata[providerId];
+	const issueSearch = metadata?.supportedIssueSearch;
 	return {
 		pullRequests: [...(metadata?.supportedPullRequestFilters ?? [])],
 		pullRequestsAccountWide: [...(metadata?.supportedAccountWidePullRequestFilters ?? [])],
 		issues: [...(metadata?.supportedIssueFilters ?? [])],
 		issuesAccountWide: [...(metadata?.supportedAccountWideIssueFilters ?? [])],
+		// Always an object, never `undefined`: a provider WITHOUT a filtered issue search reports one whose
+		// `relationships` is empty and whose flags are all false, so a consumer reads capabilities the same way
+		// for every provider (and an empty `relationships` is the signal to hide the surface itself).
+		//
+		// Spread over the all-false baseline rather than defaulting each flag: a criterion added to
+		// `IssueSearchCapabilities` then can't be forgotten here and silently reported as `undefined` (which a
+		// consumer's `if (caps.x)` would read as unsupported — right answer, wrong reason, and untyped).
+		// `supportedIssueSearch` is typed as the complete shape, so no member can arrive as an explicit undefined.
+		issueSearch: {
+			...unsupportedIssueSearchCapabilities,
+			...issueSearch,
+			// Copied, so mutating the result can't corrupt the metadata table.
+			relationships: [...(issueSearch?.relationships ?? [])],
+		},
 	};
 }

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

@@ -6,7 +6,7 @@ import type { IssueFilter, ProviderReposInput } from '../providers/models.js';
 import { PagingMode, providersMetadata } from '../providers/models.js';
 import { mergeCollectionMetadata } from '../providers/utils/providerPaging.js';
 import type { ProviderPagedResult, ProviderWarning } from '../results.js';
-import { appendDedupedWarning, reconcileOmissionsWithFailure } from '../results.js';
+import { reconcileOmissionsWithFailure } from '../results.js';
 import {
 	isGitHostIntegration,
 	isIssuesHostIntegrationId,
@@ -16,6 +16,7 @@ import type { ProviderReadContext } from './context.js';
 import { runCaptured } from './drains.js';
 import { resolveAccountWideIssueFilters } from './filters.js';
 import {
+	drainFlatPagesToRequestedPage,
 	drainToRequestedPage,
 	isPageNumberAdvanceable,
 	pageToCursor,
@@ -121,6 +122,11 @@ export async function listIssuesPage(
 			);
 		}
 
+		// GitHub expresses "any assignee" as `assignee:*`, which is meaningless without a scope: unscoped it
+		// matches millions of issues across all of GitHub instead of the user's own world. ANY scope makes it
+		// meaningful (one repository, several, or an org) — it is specifically THIS branch, the account-wide read,
+		// that has none to offer. Scope the read to repositories (or use `searchIssuesPage`, whose criteria model
+		// takes `any-assignee` alongside a `repos`/`org` scope) rather than reading unscoped.
 		if (
 			options.includeAllAssignees === true &&
 			(options.providerId === GitCloudHostIntegrationId.GitHub ||
@@ -185,51 +191,22 @@ export async function listIssuesPage(
 				{ warnOnMissingSession: warnOnMissingSession },
 			);
 		const first = await readAccountWidePage(options.cursor);
-		let value = first.value;
 		const warnings = first.warning != null ? [first.warning] : [];
-		let allMetadata = value?.metadata;
-		let pageFetchFailed = first.warning != null && value == null;
-		let currentPage = value?.page ?? 1;
-		let currentTruncated = value?.truncated ?? false;
-		let requestedPageMissing = false;
-		if (options.cursor == null && page > 1 && value != null) {
-			// Guard against the empty-cursor sentinel: a provider that claims another page without handing
-			// back a usable cursor would otherwise be re-read with `'{}'` and answer with page 1 again.
-			for (
-				let nextCursor = usableCursor(value.cursor);
-				currentPage < page && value.hasMore && nextCursor != null;
-				nextCursor = usableCursor(value.cursor)
-			) {
-				const next = await readAccountWidePage(nextCursor);
-				if (next.warning != null) {
-					appendDedupedWarning(warnings, next.warning);
-				}
-				if (next.value == null) {
-					pageFetchFailed = pageFetchFailed || next.warning != null;
-					value = undefined;
-					requestedPageMissing = true;
-					break;
-				}
-
-				value = next.value;
-				allMetadata = mergeCollectionMetadata(allMetadata, value.metadata);
-				currentTruncated = currentTruncated || value.truncated;
-				currentPage = value.page ?? currentPage + 1;
-				// A provider that hands back the same cursor isn't advancing; stop rather than loop forever.
-				if (usableCursor(value.cursor) === nextCursor) {
-					currentTruncated = true;
-					break;
-				}
-			}
-
-			// A numbered page beyond the provider's terminal cursor is genuinely empty. Never return or
-			// relabel the last available page as the requested one.
-			if (currentPage < page) {
-				requestedPageMissing = true;
-			}
-		} else if (options.cursor == null && page > 1) {
-			requestedPageMissing = true;
-		}
+		// Merged across the walked pages, so a per-scope failure reported on an earlier page isn't lost by
+		// paging past it — the one thing this read accumulates that the filtered search doesn't.
+		let allMetadata = first.value?.metadata;
+		const drained = await drainFlatPagesToRequestedPage(first, {
+			requestedPage: page,
+			suppliedCursor: options.cursor,
+			warnings: warnings,
+			readPage: readAccountWidePage,
+			fold: p => {
+				allMetadata = mergeCollectionMetadata(allMetadata, p.metadata);
+			},
+		});
+		const { value, currentPage, requestedPageMissing } = drained;
+		const currentTruncated = drained.truncated;
+		const pageFetchFailed = drained.fetchFailed;
 
 		// GitHub, GitLab, and Azure implement an account-wide issue search; a provider that doesn't (Bitbucket
 		// exposes no issues at all, and `supportsIssues` already short-circuits it above) returns `undefined`

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

@@ -180,6 +180,108 @@ export function resolveCurrentPage(options: {
 	return options.pageAdvanceable ? options.requestedPage : 1;
 }
 
+/**
+ * One page of a FLAT cursor-paged provider read — the shape both issue reads' providers return directly.
+ *
+ * `hasMore` is optional because one of the two providers leaves it off on a terminal page; absent reads as "no
+ * more", which is what a provider that reported no continuation means.
+ */
+export interface FlatPage {
+	cursor?: string;
+	hasMore?: boolean;
+	page?: number;
+	truncated: boolean;
+}
+
+/** What {@link drainFlatPagesToRequestedPage} established by walking. */
+export interface FlatDrainResult<T extends FlatPage> {
+	/** The requested page, or `undefined` when a page failed mid-walk (which also sets `fetchFailed`). */
+	value: T | undefined;
+	/** The position actually reached — 1 when nothing advanced. */
+	currentPage: number;
+	truncated: boolean;
+	/** True when the requested page is past the provider's last one, so it is genuinely EMPTY. */
+	requestedPageMissing: boolean;
+	fetchFailed: boolean;
+}
+
+/**
+ * Walks a FLAT cursor-paged read forward to a requested page number, for a provider whose pages are
+ * `{cursor, hasMore, page, truncated}` rather than the SDK's `PagedResult` wrapper.
+ *
+ * The sibling of {@link drainToRequestedPage}, not a replacement for it: that one normalizes SDK `paging` through
+ * {@link toProviderPageInfo}, which retains only cursors whose JSON declares `type`/`cursors` — and the composite
+ * cursor of a GitHub aliased search declares neither, so it would be dropped and the walk would never advance.
+ * Two shapes genuinely need two entry points; what they must NOT have is two copies of the rules below, which is
+ * what this exists to prevent (see this module's own note on drift).
+ *
+ * The rules, all of them subtle enough to be worth stating once:
+ * - The empty-cursor sentinel is filtered, so a provider claiming another page without handing back a usable
+ *   continuation is not re-read with `'{}'` (which it would answer with page 1 again).
+ * - A provider that returns the SAME cursor isn't advancing: stop, and report the read as truncated rather than
+ *   looping forever or publishing a short page as complete.
+ * - A page requested past the provider's terminal cursor is that EMPTY page N — never the last available page
+ *   relabeled, per {@link ProviderPageInfo.currentPage}.
+ * - A page that fails mid-walk latches `fetchFailed` and leaves no value, so the caller can tell "the read broke"
+ *   from "the page was genuinely empty".
+ *
+ * `fold` is the one thing the callers differ on — one merges SDK collection metadata across the walked pages, the
+ * other keeps the largest reported match count — so it is a callback rather than a branch.
+ */
+export async function drainFlatPagesToRequestedPage<T extends FlatPage>(
+	first: { value?: T; warning?: ProviderWarning },
+	options: {
+		requestedPage: number;
+		suppliedCursor: string | undefined;
+		warnings: ProviderWarning[];
+		readPage: (cursor: string) => Promise<{ value?: T; warning?: ProviderWarning }>;
+		fold?: (page: T) => void;
+	},
+): Promise<FlatDrainResult<T>> {
+	let value = first.value;
+	let fetchFailed = first.warning != null && value == null;
+	let currentPage = value?.page ?? 1;
+	let truncated = value?.truncated ?? false;
+
+	const walkable = options.suppliedCursor == null && options.requestedPage > 1;
+	if (walkable && value != null) {
+		for (
+			let nextCursor = usableCursor(value.cursor);
+			currentPage < options.requestedPage && value.hasMore === true && nextCursor != null;
+			nextCursor = usableCursor(value.cursor)
+		) {
+			const next = await options.readPage(nextCursor);
+			if (next.warning != null) {
+				appendDedupedWarning(options.warnings, next.warning);
+			}
+			if (next.value == null) {
+				fetchFailed = next.warning != null;
+				value = undefined;
+				break;
+			}
+
+			value = next.value;
+			truncated = truncated || value.truncated;
+			options.fold?.(value);
+			currentPage = value.page ?? currentPage + 1;
+			if (usableCursor(value.cursor) === nextCursor) {
+				truncated = true;
+				break;
+			}
+		}
+	}
+
+	return {
+		value: value,
+		currentPage: currentPage,
+		truncated: truncated,
+		// Every case reduces to "a page was asked for by number and the walk fell short", including the one where
+		// no walk ran at all because the first page was already terminal.
+		requestedPageMissing: walkable && currentPage < options.requestedPage,
+		fetchFailed: fetchFailed,
+	};
+}
+
 /** The mutable state {@link drainToRequestedPage} carries across the pages it walks. */
 export interface DrainState<T> {
 	items: T[];

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

@@ -0,0 +1,252 @@
+import type { IssueSearchCriteria, IssueShape } from '../../../git/models/issue.js';
+import type { IntegrationIds } from '../constants.js';
+import type { ProviderReposInput } from '../providers/models.js';
+import type { ProviderPagedResult, ProviderWarning } from '../results.js';
+import {
+	isGitHostIntegration,
+	isIssuesHostIntegrationId,
+	warnOnMissingSessionForDomain,
+} from '../utils/integration.utils.js';
+import type { ProviderReadContext } from './context.js';
+import { runCaptured } from './drains.js';
+import { resolveIssueSearchCriteria, resolveIssueSearchScope } from './filters.js';
+import {
+	drainFlatPagesToRequestedPage,
+	refusedPage,
+	resolveContinuation,
+	resolveCurrentPage,
+	usableCursor,
+} from './paging.js';
+import {
+	gitHostOnlySurfaceWarning,
+	issueSearchCapResultWarning,
+	issuesUnsupportedWarning,
+	otherWarning,
+	truncationWarning,
+	unsupportedIssueSearchCriteriaWarning,
+} from './warnings.js';
+
+/**
+ * The FILTERED issue search: issues matching structured criteria over a repository/org scope, with no forced
+ * relationship to the current user.
+ *
+ * A sibling of `listIssuesPage` rather than a mode of it, deliberately. That read is already two divergent
+ * branches (a cursor-composite account-wide path and a page-draining repo-scoped one) around a documented
+ * contract where `filters` REPLACES the provider's definition of "my issues". This search answers a different
+ * question — its relationships include two that are not about the user at all — and routes around the SDK's
+ * repo-scoped read entirely, whose over-limit recovery walk can spend up to 128 requests and still return an
+ * incomplete set. Folding the two together would multiply that branch matrix and put every existing consumer of
+ * `listIssuesPage` at risk; keeping them siblings shares the primitives below without sharing the branch space,
+ * for the same reason `broaden.ts`, `sweeps.ts` and `issueTracker.ts` are separate files.
+ *
+ * Contract details worth knowing before calling:
+ * - 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.
+ * - Paging is cursor-only. `page` alone walks 1..N internally (O(N) requests); a page past the last one is an
+ *   empty page N, never page N−1 relabeled.
+ * - At the provider's result ceiling the read SUCCEEDS and reports an omission carrying the total match count,
+ *   so a consumer can say how many were withheld. It never falls back to a per-repository recovery walk.
+ */
+export async function searchIssuesPage(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		/** Repositories to search. Combines with `org`; both become scope constraints on the same query. */
+		repos?: ProviderReposInput;
+		/** Organization/account to search. Combines with `repos`. */
+		org?: string;
+		/**
+		 * What to narrow on, validated against `getSupportedFilters().issueSearch` before the read runs. A
+		 * criterion the provider can't express server-side refuses the whole read (warning + `fetchFailed`)
+		 * rather than serving a list that was never narrowed.
+		 */
+		criteria?: IssueSearchCriteria;
+		page?: number;
+		cursor?: string;
+		/**
+		 * Page size PER RELATIONSHIP: each one is its own provider query, so a page of an N-relationship search
+		 * returns up to `N × itemsPerPage` items before the url dedupe, and fewer where they overlap.
+		 * `page.itemsPerPage` reports what actually came back.
+		 */
+		itemsPerPage?: number;
+		forceSync?: boolean;
+		connectionId?: string;
+		/**
+		 * Explicit self-managed host domain. Used only when the requested connection has no configured domain;
+		 * it must come from the trusted authentication configuration, not repository or remote data.
+		 */
+		domain?: string;
+	},
+): Promise<ProviderPagedResult<IssueShape>> {
+	const page = Math.max(1, Math.trunc(options.page ?? 1));
+	// Cursor-only, so a refusal can't claim the requested position — it reports page 1, per
+	// ProviderPageInfo.currentPage.
+	const refused = (warning: ProviderWarning) => refusedPage<IssueShape>(1, [warning], true);
+
+	if (isIssuesHostIntegrationId(options.providerId)) {
+		return refused(
+			gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'Filtered issue search'),
+		);
+	}
+
+	const integration = await ctx.getIntegrationForRead(options.providerId, options.connectionId, options.domain);
+	if (integration == null) {
+		// A supplied connection or domain that no longer resolves is a broken target, not an empty account —
+		// surface a no-connection warning + fetchFailed rather than a silent empty page.
+		const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId, options.domain);
+		return refusedPage(1, early.warnings, early.fetchFailed);
+	}
+	if (!isGitHostIntegration(integration)) {
+		return refused(
+			gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'Filtered issue search'),
+		);
+	}
+
+	await ctx.forceRefreshIfRequested(integration, options.forceSync, options.connectionId);
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId, options.domain);
+	const warnOnMissingSession = warnOnMissingSessionForDomain(options.providerId, options.domain);
+
+	if (!integration.supportsIssues) {
+		return refused(issuesUnsupportedWarning(options.providerId, domain, options.connectionId));
+	}
+
+	const scope = resolveIssueSearchScope(options.repos, options.org, options.criteria);
+	switch (scope.rejection) {
+		case 'unscoped':
+			return refused(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					'A filtered issue search must be scoped: pass `repos`, `org`, or a relationship to the current user (`authored`/`assigned`/`mentioned`). `any-assignee` and `unassigned` are not scopes — either one alone matches every such issue on the host.',
+				),
+			);
+		case 'repo-ids':
+			// A search query names repositories by PATH, so repository ids can't be expressed as a scope. Refusing
+			// is the only honest answer: dropping them would search the whole org (or the whole host) as if the
+			// caller had asked for that.
+			return refused(
+				otherWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					'A filtered issue search cannot be scoped by repository id; pass repository descriptors (namespace + name) instead.',
+				),
+			);
+	}
+
+	const resolved = resolveIssueSearchCriteria(options.providerId, options.criteria);
+	if (resolved.rejection != null) {
+		return refused(
+			unsupportedIssueSearchCriteriaWarning(options.providerId, domain, options.connectionId, resolved.rejection),
+		);
+	}
+
+	const readPage = (cursor: string | undefined) =>
+		runCaptured(
+			options.providerId,
+			domain,
+			options.connectionId,
+			() =>
+				integration.searchIssuesPageResult(
+					{
+						repos: scope.repos,
+						org: options.org,
+						criteria: options.criteria,
+						cursor: cursor,
+						pageSize: options.itemsPerPage,
+					},
+					undefined,
+					options.connectionId,
+				),
+			{ warnOnMissingSession: warnOnMissingSession },
+		);
+
+	const first = await readPage(options.cursor);
+	const warnings = first.warning != null ? [first.warning] : [];
+	// The largest total any page reported. Folded across the walk so a cap detected on page 1 is still reportable
+	// after paging on to page N — the one thing this read accumulates that its sibling doesn't.
+	let totalCount = first.value?.totalCount;
+	const drained = await drainFlatPagesToRequestedPage(first, {
+		requestedPage: page,
+		suppliedCursor: options.cursor,
+		warnings: warnings,
+		readPage: readPage,
+		fold: p => {
+			if (p.totalCount != null) {
+				totalCount = Math.max(totalCount ?? 0, p.totalCount);
+			}
+		},
+	});
+	const { value, currentPage, requestedPageMissing } = drained;
+	const pageFetchFailed = drained.fetchFailed;
+
+	// A provider that doesn't implement the search hook returns `undefined` with no error. Surface that as an
+	// explicit unsupported warning + fetchFailed rather than a silent empty success, so a caller isn't left
+	// unable to tell it apart from an account with no matching issues. `getSupportedFilters().issueSearch`
+	// declares this ahead of the read, so a consumer that checks it never reaches here.
+	if (value == null && warnings.length === 0) {
+		return refused(
+			unsupportedIssueSearchCriteriaWarning(options.providerId, domain, options.connectionId, {
+				reason: 'unsupported-search',
+			}),
+		);
+	}
+
+	const items = requestedPageMissing ? [] : (value?.values ?? []);
+	// Cursor-only: `hasMore` without a real cursor is a dead end, so report it as terminal-but-incomplete rather
+	// than inviting the caller to page forever.
+	const continuation = resolveContinuation(
+		{
+			hasMore: requestedPageMissing ? false : (value?.hasMore ?? false),
+			cursor: requestedPageMissing ? undefined : usableCursor(value?.cursor),
+			truncated: drained.truncated,
+		},
+		undefined,
+	);
+	const truncated = continuation.truncated;
+	// Only reachable when nothing else already explained the incompleteness — and a failed page always warns
+	// first, so a read that gets here SUCCEEDED. That is why the cause below is unconditionally `exhausted` and
+	// `fetchFailed` is never set from here.
+	if (truncated && warnings.length === 0) {
+		// The result ceiling is the one truncation cause this read can EXPLAIN with a number, so it gets its own
+		// warning carrying the total. Anything else truncated (an unusable continuation, a provider that stopped
+		// advancing) falls back to the generic wording.
+		warnings.push(
+			issueSearchCapResultWarning(options.providerId, domain, options.connectionId, totalCount) ??
+				truncationWarning(
+					options.providerId,
+					domain,
+					options.connectionId,
+					'Issue search',
+					// `exhausted`: this read exposes no budget the caller could raise, so nothing it could call
+					// would return the withheld items.
+					'exhausted',
+				),
+		);
+	}
+
+	return {
+		items: items,
+		warnings: warnings,
+		page: {
+			// Positional, per ProviderPageInfo.currentPage. A requested page past the terminal cursor is reported
+			// as that empty page N; otherwise this read is cursor-only, so a `page` the caller didn't pair with a
+			// cursor is never echoed.
+			currentPage: requestedPageMissing
+				? page
+				: resolveCurrentPage({
+						providerPage: currentPage,
+						requestedPage: page,
+						suppliedCursor: options.cursor,
+						pageAdvanceable: false,
+					}),
+			itemsPerPage: items.length,
+			truncated: truncated || undefined,
+		},
+		hasMore: continuation.hasMore,
+		cursor: continuation.cursor,
+		fetchFailed: pageFetchFailed || undefined,
+	};
+}