@gitkraken/core-gitlens 0.6.0 → 0.7.1

package/dist/plus/integrations/manager.d.ts

@@ -1,21 +1,22 @@
-import type { IssueSearchCriteria, IssueShape } from '../../git/models/issue.js';
-import type { PullRequestSearchCriteria, PullRequestShape, PullRequestStateFilter } from '../../git/models/pullRequest.js';
-import type { Event } from '../../utils/event.js';
-import type { ConfiguredIntegrationsChangeEvent } from './authentication/configuredIntegrationService.js';
-import type { ConfiguredIntegrationDescriptor } from './authentication/models.js';
-import type { IntegrationIds } from './constants.js';
-import type { IssueFilter, IssueSorting, PullRequestFilter } from './providerFilters.js';
-import type { IssueCountResult, IssueCountScope, PullRequestCountResult, PullRequestCountScope } from './reads/counts.js';
-import type { SupportedFilters } from './reads/filters.js';
-import type { IssueBatchResult, IssueBatchTarget } from './reads/issueBatch.js';
-import type { TrackerIssueResult } from './reads/trackerIssue.js';
-import type { ConnectionStateChangeEvent, ProviderBroadenResult, ProviderOrganization, ProviderPagedResult, ProviderRepositoryShape, ProviderResult, ProviderSweepResult, ResolveRepositoryResult } from './results.js';
+import { Event } from "../../utils/event.js";
+import { IssueSearchCriteria, IssueShape, IssueSorting } from "../../git/models/issue.js";
+import { PullRequestFilter, PullRequestSearchCriteria, PullRequestShape, PullRequestStateFilter } from "../../git/models/pullRequest.js";
+import { ConfiguredIntegrationDescriptor } from "./authentication/models.js";
+import { IntegrationIds } from "./constants.js";
+import { ConfiguredIntegrationsChangeEvent } from "./authentication/configuredIntegrationService.js";
+import { IssueFilter } from "./providerFilters.js";
+import { ConnectionStateChangeEvent, ProviderBroadenResult, ProviderOrganization, ProviderPagedResult, ProviderRepositoryShape, ProviderResult, ProviderSweepResult, ResolveRepositoryResult } from "./results.js";
+import { IssueCountResult, IssueCountScope, PullRequestCountResult, PullRequestCountScope } from "./reads/counts.js";
+import { SupportedFilters } from "./reads/filters.js";
+import { IssueBatchResult, IssueBatchTarget } from "./reads/issueBatch.js";
+import { TrackerIssueResult } from "./reads/trackerIssue.js";
+//#region ../plus/integrations/src/manager.d.ts
 /** Neutral repository input accepted by repo-scoped provider reads. */
 export interface ProviderRepositoryInput {
-    namespace: string;
-    name: string;
-    project?: string;
-    id?: string;
+  namespace: string;
+  name: string;
+  project?: string;
+  id?: string;
 }
 export type ProviderRepositoriesInput = (string | number)[] | ProviderRepositoryInput[];
 /**
@@ -27,18 +28,18 @@ export type ProviderRepositoriesInput = (string | number)[] | ProviderRepository
  * the trusted authentication configuration, not repository or remote data.
  */
 export interface ProviderSweepTarget {
-    providerId: IntegrationIds;
-    connectionId?: string;
-    domain?: string;
-    /**
-     * Relationship filters for this provider slice. With sweep-level `repos`, members are provider query
-     * constraints; without `repos`, they form an exact OR union. The whole set is validated against the
-     * selected path's capabilities.
-     *
-     * This per-target form lets a cross-provider sweep preserve provider-specific semantics without leaking
-     * provider query details into the consumer. It overrides the sweep-level `filters` for this target.
-     */
-    filters?: PullRequestFilter[];
+  providerId: IntegrationIds;
+  connectionId?: string;
+  domain?: string;
+  /**
+   * Relationship filters for this provider slice. With sweep-level `repos`, members are provider query
+   * constraints; without `repos`, they form an exact OR union. The whole set is validated against the
+   * selected path's capabilities.
+   *
+   * This per-target form lets a cross-provider sweep preserve provider-specific semantics without leaking
+   * provider query details into the consumer. It overrides the sweep-level `filters` for this target.
+   */
+  filters?: PullRequestFilter[];
 }
 /**
  * One target's contribution to a pull-request sweep, reported as it settles.
@@ -58,56 +59,56 @@ export interface ProviderSweepTarget {
  * 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;
+  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[];
-    providerIds?: never;
-    connectionId?: never;
+  targets: readonly ProviderSweepTarget[];
+  providerIds?: never;
+  connectionId?: never;
 } | {
-    targets?: never;
-    providerIds?: IntegrationIds[];
-    /**
-     * Legacy single-provider selector. It is ignored when `providerIds` contains more than one provider;
-     * use `targets` to select connections independently in a multi-provider sweep.
-     */
-    connectionId?: string;
+  targets?: never;
+  providerIds?: IntegrationIds[];
+  /**
+   * Legacy single-provider selector. It is ignored when `providerIds` contains more than one provider;
+   * use `targets` to select connections independently in a multi-provider sweep.
+   */
+  connectionId?: string;
 };
 /**
  * One org slice in an issue-broadening fan-out. `domain` is a fallback for self-managed hosts whose
@@ -116,63 +117,63 @@ type ProviderSweepSelection = {
  * repository or remote data.
  */
 export interface ProviderBroadenOrg {
-    providerId: IntegrationIds;
-    name: string;
-    connectionId?: string;
-    domain?: string;
+  providerId: IntegrationIds;
+  name: string;
+  connectionId?: string;
+  domain?: string;
 }
 type PullRequestSweepCommonOptions = {
-    repos?: ProviderRepositoriesInput;
-    /** Named `states` to match {@link IntegrationManager.listPullRequestsPage}; a mismatch here read as silently ignored. */
-    states?: PullRequestStateFilter[];
-    /**
-     * Relationship filters applied to every target. Repo-scoped reads combine them as provider query
-     * constraints (normally an intersection); account-wide reads form an exact OR union. The set is validated
-     * against `pullRequests` or `pullRequestsAccountWide`, respectively. A target's own `filters` overrides this.
-     */
-    filters?: PullRequestFilter[];
-    /**
-     * Account-wide only: include review-requested PRs when the provider's native "my PRs" query omits them.
-     * This extends the provider-native result; it is not a narrowing filter.
-     */
-    includeReviewRequested?: boolean;
-    /**
-     * Account-wide only: fetch the full PR projection (review decision, review requests, latest reviews)
-     * instead of the default summary/lite one. Opt-in because it enlarges every account-wide page; callers
-     * that classify by review state (e.g. a "needs my review" surface) set it, others keep the lean read.
-     *
-     * GitHub/GHE only today — no other provider's account-wide read has a projection switch, so they return
-     * their native shape regardless. A cross-provider sweep therefore gets reviews from GitHub targets and
-     * whatever the others natively carry; it is a breadth request, not a guarantee, so it does not refuse
-     * (unlike `filters`, where dropping a member would change the requested set).
-     *
-     * Projection only: it cannot change which pull requests come back. Every GitHub account-wide read goes through
-     * the same search whether or not it is set, so the Launchpad ignored-repository and organization qualifiers
-     * (and the per-facet result ceiling) apply the same either way. What it costs is the reduced page size, and a
-     * document whose weight scales with the number of relationship × state facets in flight.
-     */
-    includeReviews?: boolean;
-    forceSync?: boolean;
-    maxPages?: number;
-    /**
-     * 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;
+  repos?: ProviderRepositoriesInput;
+  /** Named `states` to match {@link IntegrationManager.listPullRequestsPage}; a mismatch here read as silently ignored. */
+  states?: PullRequestStateFilter[];
+  /**
+   * Relationship filters applied to every target. Repo-scoped reads combine them as provider query
+   * constraints (normally an intersection); account-wide reads form an exact OR union. The set is validated
+   * against `pullRequests` or `pullRequestsAccountWide`, respectively. A target's own `filters` overrides this.
+   */
+  filters?: PullRequestFilter[];
+  /**
+   * Account-wide only: include review-requested PRs when the provider's native "my PRs" query omits them.
+   * This extends the provider-native result; it is not a narrowing filter.
+   */
+  includeReviewRequested?: boolean;
+  /**
+   * Account-wide only: fetch the full PR projection (review decision, review requests, latest reviews)
+   * instead of the default summary/lite one. Opt-in because it enlarges every account-wide page; callers
+   * that classify by review state (e.g. a "needs my review" surface) set it, others keep the lean read.
+   *
+   * GitHub/GHE only today — no other provider's account-wide read has a projection switch, so they return
+   * their native shape regardless. A cross-provider sweep therefore gets reviews from GitHub targets and
+   * whatever the others natively carry; it is a breadth request, not a guarantee, so it does not refuse
+   * (unlike `filters`, where dropping a member would change the requested set).
+   *
+   * Projection only: it cannot change which pull requests come back. Every GitHub account-wide read goes through
+   * the same search whether or not it is set, so the Launchpad ignored-repository and organization qualifiers
+   * (and the per-facet result ceiling) apply the same either way. What it costs is the reduced page size, and a
+   * document whose weight scales with the number of relationship × state facets in flight.
+   */
+  includeReviews?: boolean;
+  forceSync?: boolean;
+  maxPages?: number;
+  /**
+   * 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;
 export type ClosedPullRequestSweepOptions = Omit<PullRequestSweepCommonOptions, 'states'> & ProviderSweepSelection;
@@ -181,28 +182,28 @@ export type ClosedPullRequestSweepOptions = Omit<PullRequestSweepCommonOptions,
  * to one provider. A `connectionId`/`domain` without `providerId` is ambiguous and therefore unrepresentable.
  */
 export type ListOrgsOptions = {
-    providerId: IntegrationIds;
-    connectionId?: string;
-    domain?: string;
+  providerId: IntegrationIds;
+  connectionId?: string;
+  domain?: string;
 } | {
-    providerId?: never;
-    connectionId?: never;
-    domain?: never;
+  providerId?: never;
+  connectionId?: never;
+  domain?: never;
 };
 /**
  * Project discovery follows the same provider-targeting rule as {@link ListOrgsOptions}; `org` may still
  * narrow either a single-provider read or the unscoped fan-out.
  */
 export type ListProjectsOptions = {
-    providerId: IntegrationIds;
-    org?: string;
-    connectionId?: string;
-    domain?: string;
+  providerId: IntegrationIds;
+  org?: string;
+  connectionId?: string;
+  domain?: string;
 } | {
-    providerId?: never;
-    org?: string;
-    connectionId?: never;
-    domain?: never;
+  providerId?: never;
+  org?: string;
+  connectionId?: never;
+  domain?: never;
 };
 /**
  * Public, provider-neutral integration facade. Provider clients and integration model instances remain private
@@ -230,462 +231,518 @@ export type ListProjectsOptions = {
  *   `page.truncated`), never as a page that can't be requested.
  */
 export interface IntegrationManager {
-    readonly onDidChange: Event<ConfiguredIntegrationsChangeEvent>;
-    readonly onDidChangeConnectionState: Event<ConnectionStateChangeEvent>;
-    dispose(): void;
-    getConfigured(id?: IntegrationIds, options?: {
-        cloud?: boolean;
-        domain?: string;
-    }): ConfiguredIntegrationDescriptor[];
+  readonly onDidChange: Event<ConfiguredIntegrationsChangeEvent>;
+  readonly onDidChangeConnectionState: Event<ConnectionStateChangeEvent>;
+  dispose(): void;
+  getConfigured(id?: IntegrationIds, options?: {
+    cloud?: boolean;
+    domain?: string;
+  }): ConfiguredIntegrationDescriptor[];
+  /**
+   * The `filters` a provider accepts on `listPullRequestsPage`/`listIssuesPage` and the sweeps.
+   *
+   * The filter contract is all-or-nothing: a set containing even one unsupported filter is refused (empty
+   * `items` + a warning + `fetchFailed`) rather than narrowed, because falling through to an unfiltered read
+   * would return every pull request instead of the user's. Intersect against this before the read so a
+   * cross-provider filter set never turns into a failed page. Static per provider — no connection required.
+   *
+   * Empty means no filter of that kind is expressible (issue trackers have no pull requests; Bitbucket exposes
+   * no issues), which means "pass no filters", not "error".
+   *
+   * `pullRequests` covers repo-scoped PR reads; `pullRequestsAccountWide` covers account-wide PR reads.
+   * `issues` covers the repo-scoped issue read; `issuesAccountWide` covers the account-wide one (no `repos`).
+   * They differ because they are different provider queries — GitLab can express `Assignee` and `Author`
+   * account-wide, but not `Mention` — and `listIssuesPage` validates against whichever the read uses.
+   *
+   * An ISSUE TRACKER (Jira/Linear/Trello) reports its filters under `issues`, and
+   * {@link IntegrationManager.listIssueTrackerIssuesPage} validates against that field. Its
+   * `issuesAccountWide` is empty — those two fields split the git-host reads, and a tracker has neither of
+   * them (its issues live under resource → project) — so intersecting a tracker's filters against
+   * `issuesAccountWide` would read "cannot filter" for a provider that filters fine.
+   *
+   * 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): 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`. */
+  setPrimaryConnection(id: IntegrationIds, connectionId: string): Promise<void>;
+  /** Rejects unless `connectionId` is a configured cloud connection for `id`. */
+  deleteConnection(id: IntegrationIds, connectionId: string): Promise<void>;
+  listOrgs(options?: ListOrgsOptions): Promise<ProviderResult<ProviderOrganization>>;
+  listProjects(options?: ListProjectsOptions): Promise<ProviderResult<ProviderOrganization>>;
+  listRepos(options: {
+    providerId: IntegrationIds;
+    org?: string;
+    project?: string;
     /**
-     * The `filters` a provider accepts on `listPullRequestsPage`/`listIssuesPage` and the sweeps.
-     *
-     * The filter contract is all-or-nothing: a set containing even one unsupported filter is refused (empty
-     * `items` + a warning + `fetchFailed`) rather than narrowed, because falling through to an unfiltered read
-     * would return every pull request instead of the user's. Intersect against this before the read so a
-     * cross-provider filter set never turns into a failed page. Static per provider — no connection required.
-     *
-     * Empty means no filter of that kind is expressible (issue trackers have no pull requests; Bitbucket exposes
-     * no issues), which means "pass no filters", not "error".
-     *
-     * `pullRequests` covers repo-scoped PR reads; `pullRequestsAccountWide` covers account-wide PR reads.
-     * `issues` covers the repo-scoped issue read; `issuesAccountWide` covers the account-wide one (no `repos`).
-     * They differ because they are different provider queries — GitLab can express `Assignee` and `Author`
-     * account-wide, but not `Mention` — and `listIssuesPage` validates against whichever the read uses.
-     *
-     * An ISSUE TRACKER (Jira/Linear/Trello) reports its filters under `issues`, and
-     * {@link IntegrationManager.listIssueTrackerIssuesPage} validates against that field. Its
-     * `issuesAccountWide` is empty — those two fields split the git-host reads, and a tracker has neither of
-     * them (its issues live under resource → project) — so intersecting a tracker's filters against
-     * `issuesAccountWide` would read "cannot filter" for a provider that filters fine.
-     *
-     * 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.
+     * Requested 1-based page. Cursor-only providers are advanced internally when no `cursor` is supplied,
+     * so a direct page-N request can cost O(page) upstream calls.
      */
-    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`. */
-    setPrimaryConnection(id: IntegrationIds, connectionId: string): Promise<void>;
-    /** Rejects unless `connectionId` is a configured cloud connection for `id`. */
-    deleteConnection(id: IntegrationIds, connectionId: string): Promise<void>;
-    listOrgs(options?: ListOrgsOptions): Promise<ProviderResult<ProviderOrganization>>;
-    listProjects(options?: ListProjectsOptions): Promise<ProviderResult<ProviderOrganization>>;
-    listRepos(options: {
-        providerId: IntegrationIds;
-        org?: string;
-        project?: string;
-        /**
-         * Requested 1-based page. Cursor-only providers are advanced internally when no `cursor` is supplied,
-         * so a direct page-N request can cost O(page) upstream calls.
-         */
-        page?: number;
-        /** Continuation from a prior page's `cursor`; supplying it costs exactly one upstream request per scope. */
-        cursor?: string;
-        /**
-         * Requested page size. Advisory: the repos read core is cursor-only and takes no page size, so the
-         * provider's own size is what applies — `page.itemsPerPage` reports what was actually returned.
-         */
-        itemsPerPage?: number;
-        connectionId?: string;
-        /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
-        domain?: string;
-    }): Promise<ProviderPagedResult<ProviderRepositoryShape>>;
-    listPullRequestsPage(options: {
-        providerId: IntegrationIds;
-        repos?: ProviderRepositoriesInput;
-        states?: PullRequestStateFilter[];
-        /**
-         * Relationship filters. Repo-scoped reads combine members as provider query constraints (normally an
-         * intersection), so issue separate reads when the desired result is a union. Account-wide members form an
-         * exact OR union. Each path validates the whole set against its corresponding capability.
-         */
-        filters?: PullRequestFilter[];
-        /**
-         * Account-wide only: include review-requested PRs when the provider's native "my PRs" query omits them.
-         * This extends the provider-native result; it is not a narrowing filter.
-         */
-        includeReviewRequested?: boolean;
-        /**
-         * Requested 1-based page. Without a `cursor` this may cost O(page) upstream requests on a cursor-only
-         * read (repo-scoped GitHub/GHE and account-wide providers that return continuations), which the facade
-         * drains internally.
-         */
-        page?: number;
-        /** Continuation from a prior page's `cursor`; supplying it costs exactly one upstream request per scope. */
-        cursor?: string;
-        /**
-         * Requested page size, honored on the repo-scoped path. The provider-defined account-wide read (no
-         * `repos`) takes no page size, so it is ignored there — `page.itemsPerPage` reports what was actually
-         * returned rather than echoing the request.
-         */
-        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;
-        /**
-         * Requests the lightweight row shape: everything except the per-row build-status rollup
-         * (`statusCheckRollupState`) and `commitCount`, which share one provider selection and are therefore
-         * dropped together. Set it on list/aggregate surfaces that read neither.
-         *
-         * The account-wide branch already requests this shape. A provider without a lightweight projection
-         * ignores the option, so it is a hint rather than a guarantee about which fields are present.
-         */
-        summary?: boolean;
-    }): Promise<ProviderPagedResult<PullRequestShape>>;
+    page?: number;
+    /** Continuation from a prior page's `cursor`; supplying it costs exactly one upstream request per scope. */
+    cursor?: string;
     /**
-     * Pull requests matching structured criteria over a repository/organization or current-user relationship
-     * scope.
-     *
-     * This is a separate read from {@link listPullRequestsPage}: free text reaches the provider instead of filtering
-     * whichever rows happened to be loaded, and every cursor-threaded page costs exactly one upstream request.
-     * `criteria.relationships` and `criteria.states` are OR sets, so `[closed, merged]` expresses the complete
-     * terminal set and `[Author, Assignee, ReviewRequested]` matches the visible PR list without falling back to
-     * GitHub's mismatched `involves:@me`. Omit relationships only with a repository/organization scope to search
-     * every PR there.
-     *
-     * **Ordering is `criteria.sort`**, most-recently-updated-first when omitted. It is validated like every other
-     * criterion — a key not in `getSupportedFilters().pullRequestSearch.sorts` refuses the whole read rather than
-     * falling back, because at a bounded result window another order reaches another subset. The page is a union of
-     * the provider's relationship × state facets, so it is re-ordered as a whole rather than served as concatenated
-     * per-facet runs. Changing the sort invalidates a threaded cursor (it is part of the cursor's fingerprint,
-     * alongside the text and the scope); drop the cursor when you change the order.
-     *
-     * If the provider's result ceiling is reached, the request still succeeds and carries a warning omission with
-     * `totalCount`, `limit`, `sort`, and `recovery: 'none'`. `totalCount` is the largest provider-reported
-     * pre-ceiling facet count, not the reachable or returned row count; this mirrors the per-search ceiling's own
-     * unit.
-     *
-     * Check `getSupportedFilters().pullRequestSearch` before calling. A provider that reports no relationships
-     * refuses the read rather than returning a page that never honored the criteria or scope.
+     * Requested page size. Advisory: the repos read core is cursor-only and takes no page size, so the
+     * provider's own size is what applies — `page.itemsPerPage` reports what was actually returned.
      */
-    searchPullRequestsPage(options: {
-        providerId: IntegrationIds;
-        /**
-         * Repository descriptors that bound the search; ids cannot name provider search qualifiers.
-         *
-         * Both halves of a descriptor must reach the provider unchanged — see `org` — since a search names a
-         * repository by its `namespace/name` path.
-         */
-        repos?: ProviderRepositoriesInput;
-        /**
-         * Organization/account that bounds the search.
-         *
-         * Held to a STRICTER rule than the free-form `criteria.text`, which is sanitized: a scope name carrying a
-         * quote, or an inner space or control character, is REFUSED (warning + `fetchFailed`), and the refusal
-         * names the value. Leading and trailing whitespace and control characters are stripped and accepted,
-         * since removing them cannot change which scope the query names. Sanitizing a scope would answer the wrong question — the sanitized value may name a real but
-         * DIFFERENT organization, whose result looks entirely normal. Pass the name exactly as the provider spells
-         * it; `''` means "no org supplied" and falls through to the other scopes.
-         */
-        org?: string;
-        criteria?: PullRequestSearchCriteria;
-        /** Cursor-only: without a cursor, reaching page N costs O(N) upstream requests. */
-        page?: number;
-        cursor?: string;
-        /**
-         * Page size PER RELATIONSHIP × STATE facet, not per page. Each facet is its own aliased provider query —
-         * one axis more than {@link searchIssuesPage}'s per-relationship fan-out — so a page of a 3-relationship,
-         * 2-state search returns up to `6 × itemsPerPage` items before deduplication, and fewer than that where
-         * the facets overlap. Deduplication does NOT bring the page back to this size: it removes only the rows the
-         * facets share. `page.itemsPerPage` reports what actually came back, so size the UI off that rather than
-         * off this. A provider may also cap it below what is asked for.
-         */
-        itemsPerPage?: number;
-        forceSync?: boolean;
-        connectionId?: string;
-        /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
-        domain?: string;
-        /**
-         * Requests the lightweight row shape: identity, body, author, repository, branch refs and stack info,
-         * without review, check or diff statistics. It also replaces the flat per-facet default page size with a
-         * fixed budget shared across the search's ACTIVE facets, so with up to three of them it raises the page
-         * and from four on it LOWERS it — measured against GitHub, a 100-row budget versus a flat 30 each.
-         *
-         * A provider without a lightweight projection ignores it and returns its usual shape, so this is a hint
-         * rather than a contract about which fields are present.
-         */
-        summary?: boolean;
-    }): Promise<ProviderPagedResult<PullRequestShape>>;
-    listIssuesPage(options: {
-        providerId: IntegrationIds;
-        repos?: ProviderRepositoriesInput;
-        /**
-         * Narrows the account-wide read (no `repos`) to one org/account, and `project` to one project within it.
-         * Only a git host with a project tier (Azure DevOps) can scope this server-side; for any other provider
-         * either option is rejected with a warning + `fetchFailed` rather than silently returning an unscoped
-         * list. Ignored when `repos` is supplied, since those repos are already the scope.
-         */
-        org?: string;
-        project?: string;
-        /**
-         * Narrows to the requested relationship(s), validated against `getSupportedFilters().issues` on the
-         * repo-scoped path and `.issuesAccountWide` on the account-wide one.
-         *
-         * On the account-wide path this REPLACES the provider's own definition of "my issues" — GitHub/GHE
-         * authored + assigned + mentioned, Azure assigned + authored, and GitLab assigned-to-me — so
-         * `[Assignee]` gets `assignee:@me` semantics wherever it's expressible. Narrowing must happen here rather
-         * than on the returned page: the excluded items still counted toward the provider's paging, so filtering
-         * afterward leaves `items` describing a different result set than `hasMore`/`cursor`.
-         *
-         * A set the provider can't express server-side is refused whole (warning + `fetchFailed`), never widened.
-         */
-        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).
-         */
-        page?: number;
-        /** Continuation from a prior page's `cursor`; supplying it costs exactly one upstream request per scope. */
-        cursor?: string;
-        itemsPerPage?: number;
-        forceSync?: boolean;
-        connectionId?: string;
-        /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
-        domain?: string;
-    }): Promise<ProviderPagedResult<IssueShape>>;
+    itemsPerPage?: number;
+    connectionId?: string;
+    /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+    domain?: string;
+  }): Promise<ProviderPagedResult<ProviderRepositoryShape>>;
+  listPullRequestsPage(options: {
+    providerId: IntegrationIds;
+    repos?: ProviderRepositoriesInput;
+    states?: PullRequestStateFilter[];
     /**
-     * Issues matching structured criteria over a repository/org scope, with NO forced relationship to the current
-     * user — the issue counterpart of the PR search, and the read to use for "every issue in these repos matching
-     * X" rather than "my issues".
-     *
-     * Why this and not {@link listIssuesPage}: that read is either bound to the user's own relationships
-     * (account-wide) or routed through the SDK's repo-scoped read, whose over-limit recovery walk can spend up to
-     * 128 sequential requests and still return an incomplete set. This one is a single request per page.
-     *
-     * Three parts of the contract worth reading before calling:
-     *
-     * - **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 `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), `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 or sort key it can't express refuses the whole read
-     * rather than serving a wider or differently-ordered result than asked for.
+     * Relationship filters. Repo-scoped reads combine members as provider query constraints (normally an
+     * intersection), so issue separate reads when the desired result is a union. Account-wide members form an
+     * exact OR union. Each path validates the whole set against its corresponding capability.
      */
-    searchIssuesPage(options: {
-        providerId: IntegrationIds;
-        /**
-         * Repositories to search. Combines with `org`; both constrain the same query.
-         *
-         * Both halves of a descriptor must reach the provider unchanged — see `org` — since a search names a
-         * repository by its `namespace/name` path.
-         */
-        repos?: ProviderRepositoriesInput;
-        /**
-         * Organization/account to search. Combines with `repos`.
-         *
-         * Held to a STRICTER rule than the free-form criteria, which are sanitized: a scope name carrying a quote,
-         * or an inner space or control character, is REFUSED (warning + `fetchFailed`), and the refusal names the
-         * value. Leading and trailing whitespace and control characters are stripped and accepted, since removing
-         * them cannot change which scope the query names.
-         * The sanitized value may name a real but DIFFERENT org, whose result looks entirely normal. `''` means
-         * "no org supplied" and falls through to the other scopes.
-         */
-        org?: string;
-        criteria?: IssueSearchCriteria;
-        /**
-         * Requested 1-based page. This read is cursor-only, so without a `cursor` reaching page N costs O(N)
-         * upstream requests; pass the previous page's cursor to make it exactly one.
-         */
-        page?: number;
-        cursor?: string;
-        /**
-         * Page size PER RELATIONSHIP, not per page. Each requested relationship is its own provider query, so a
-         * page of a 2-relationship search returns up to `2 × itemsPerPage` items before deduplication — and fewer
-         * than that when the two overlap. `page.itemsPerPage` reports what actually came back, so size the UI off
-         * that rather than off this. A provider may also cap it below what is asked for.
-         */
-        itemsPerPage?: number;
-        forceSync?: boolean;
-        connectionId?: string;
-        /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
-        domain?: string;
-    }): Promise<ProviderPagedResult<IssueShape>>;
+    filters?: PullRequestFilter[];
     /**
-     * How many issues MATCH each scope, without fetching any of them — the probe behind a "this will fetch ~N
-     * issues" preview, and behind a live count next to a filter the user hasn't applied yet.
-     *
-     * Cheap by design: every scope that can share a request does, and no issue data crosses the wire (measured
-     * against GitHub, 30 counts are a single rate-limit point). Still a network request per batch, so debounce and
-     * cache it if it's driven from UI state.
-     *
-     * A separate method rather than a flag on {@link searchIssuesPage} because transferring zero issues is the
-     * whole point: a `countOnly` read would hand back a paged result whose `items`/`cursor`/`hasMore` are all
-     * meaningless.
+     * Account-wide only: include review-requested PRs when the provider's native "my PRs" query omits them.
+     * This extends the provider-native result; it is not a narrowing filter.
+     */
+    includeReviewRequested?: boolean;
+    /**
+     * Requested 1-based page. Without a `cursor` this may cost O(page) upstream requests on a cursor-only
+     * read (repo-scoped GitHub/GHE and account-wide providers that return continuations), which the facade
+     * drains internally.
+     */
+    page?: number;
+    /** Continuation from a prior page's `cursor`; supplying it costs exactly one upstream request per scope. */
+    cursor?: string;
+    /**
+     * Requested page size, honored on the repo-scoped path. The provider-defined account-wide read (no
+     * `repos`) takes no page size, so it is ignored there — `page.itemsPerPage` reports what was actually
+     * returned rather than echoing the request.
+     */
+    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;
+    /**
+     * Requests the lightweight row shape: everything except the per-row build-status rollup
+     * (`statusCheckRollupState`) and `commitCount`, which share one provider selection and are therefore
+     * dropped together. Set it on list/aggregate surfaces that read neither.
      *
-     * Results are echoed under the caller's own `key`, so no positional matching is needed. Per-scope isolation is
-     * the rule: a scope refused for its own reasons, or a batch that failed upstream, warns and drops only its own
-     * scopes (with `fetchFailed` set) while every other count still comes back.
+     * The account-wide branch already requests this shape. A provider without a lightweight projection
+     * ignores the option, so it is a hint rather than a guarantee about which fields are present.
+     */
+    summary?: boolean;
+  }): Promise<ProviderPagedResult<PullRequestShape>>;
+  /**
+   * Pull requests matching structured criteria over a repository/organization or current-user relationship
+   * scope.
+   *
+   * This is a separate read from {@link listPullRequestsPage}: free text reaches the provider instead of filtering
+   * whichever rows happened to be loaded, and on GitHub/GHE every cursor-threaded page costs exactly one upstream
+   * request (Bitbucket Data Center spends one per repository × relationship facet it is still reading).
+   * `criteria.relationships` and `criteria.states` are OR sets, so `[closed, merged]` expresses the complete
+   * terminal set and `[Author, Assignee, ReviewRequested]` matches the visible PR list without falling back to
+   * GitHub's mismatched `involves:@me`. Omit relationships only with a repository/organization scope to search
+   * every PR there.
+   *
+   * **Ordering is `criteria.sort`**, most-recently-updated-first when omitted. It is validated like every other
+   * criterion — a key not in `getSupportedFilters().pullRequestSearch.sorts` refuses the whole read rather than
+   * falling back, because at a bounded result window another order reaches another subset. The page is a union of
+   * the provider's relationship × state facets, so it is re-ordered as a whole rather than served as concatenated
+   * per-facet runs. The order holds within a page, not across pages: each facet advances by its own continuation, so
+   * a later page can hold a row that sorts before the last row of an earlier one — sort the accumulated rows when a
+   * surface shows several pages as one list. Changing the sort invalidates a threaded cursor (it is part of the
+   * cursor's fingerprint, alongside the text and the scope); drop the cursor when you change the order.
+   *
+   * If the provider's result ceiling is reached, the request still succeeds and carries a warning omission with
+   * `totalCount`, `limit`, `sort`, and `recovery: 'none'`. `totalCount` is the largest provider-reported
+   * pre-ceiling facet count, not the reachable or returned row count; this mirrors the per-search ceiling's own
+   * unit.
+   *
+   * **Azure DevOps Server** differs in how it gets there, because its pull request API can't filter by text, date or
+   * draft: the first page drains every facet (up to 1,000 rows each) and later pages are served from that drain,
+   * so a first page can cost many requests and a continuation none. A continuation whose drain expired is refused;
+   * restart without the cursor. `itemsPerPage` sizes the whole page, not a
+   * facet. Past a facet's drain bound the page is `truncated` with no `totalCount`. Scope names with spaces or
+   * quotes are accepted there, since they reach the provider as encoded URL segments. See
+   * `docs/integrations.md` §9.
+   *
+   * Check `getSupportedFilters().pullRequestSearch` before calling. A provider that reports no relationships
+   * refuses the read rather than returning a page that never honored the criteria or scope.
+   */
+  searchPullRequestsPage(options: {
+    providerId: IntegrationIds;
+    /**
+     * Repository descriptors that bound the search; ids cannot name provider search qualifiers.
      *
-     * `count: undefined` means the provider didn't report one — NOT zero, which is a real answer. Render the
-     * difference: showing an unknown count as 0 tells the user a filter matches nothing when it may match
-     * thousands. A provider that can't count at all (only GitHub/GHE can today) refuses the probe outright rather
-     * than returning fabricated numbers.
+     * Both halves of a descriptor must reach the provider unchanged — see `org` — since a search names a
+     * repository by its `namespace/name` path.
+     */
+    repos?: ProviderRepositoriesInput;
+    /**
+     * Organization/account that bounds the search.
+     *
+     * Held to a STRICTER rule than the free-form `criteria.text`, which is sanitized: a scope name carrying a
+     * quote, or an inner space or control character, is REFUSED (warning + `fetchFailed`), and the refusal
+     * names the value — except on a provider whose scope names never enter a query string (Azure DevOps
+     * Server), where only blank names and control characters are. Leading and trailing whitespace and control characters are stripped and accepted,
+     * since removing them cannot change which scope the query names. Sanitizing a scope would answer the wrong question — the sanitized value may name a real but
+     * DIFFERENT organization, whose result looks entirely normal. Pass the name exactly as the provider spells
+     * it; `''` means "no org supplied" and falls through to the other scopes.
      */
-    countIssues(options: {
-        providerId: IntegrationIds;
-        /** Each needs its own scope, and each requested relationship its own entry — see {@link IssueCountScope}. */
-        scopes: readonly IssueCountScope[];
-        connectionId?: string;
-        /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
-        domain?: string;
-    }): Promise<ProviderResult<IssueCountResult>>;
+    org?: string;
+    criteria?: PullRequestSearchCriteria;
+    /** Cursor-only: without a cursor, reaching page N costs O(N) upstream requests. */
+    page?: number;
+    cursor?: string;
     /**
-     * Resolves several issues BY COORDINATE — `(owner, repo, number)` — in one request.
+     * Page size PER RELATIONSHIP × STATE facet, not per page. Each facet is its own aliased provider query —
+     * one axis more than {@link searchIssuesPage}'s per-relationship fan-out — so a page of a 3-relationship,
+     * 2-state search returns up to `6 × itemsPerPage` items before deduplication, and fewer than that where
+     * the facets overlap. Deduplication does NOT bring the page back to this size: it removes only the rows the
+     * facets share. `page.itemsPerPage` reports what actually came back, so size the UI off that rather than
+     * off this. A provider may also cap it below what is asked for. Azure DevOps Server is the exception: it
+     * serves one merged page, so there this is the page size (at most 100).
+     */
+    itemsPerPage?: number;
+    forceSync?: boolean;
+    connectionId?: string;
+    /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+    domain?: string;
+    /**
+     * Requests the lightweight row shape: identity, body, author, repository, branch refs and stack info,
+     * without review, check or diff statistics. It also replaces the flat per-facet default page size with a
+     * fixed budget shared across the search's ACTIVE facets, so with up to three of them it raises the page
+     * and from four on it LOWERS it — measured against GitHub, a 100-row budget versus a flat 30 each.
      *
-     * The read for "which issue does this branch name reference", which is an IDENTITY question rather than a
-     * search. Emulating it by paging a scoped list and matching the identifier cannot prove absence without
-     * walking the whole scope, so a miss stays unproven, uncacheable, and repeats its whole budget on every pass.
-     * This answers it in one request per chunk, and a miss is final.
+     * A provider without a lightweight projection ignores it and returns its usual shape, so this is a hint
+     * rather than a contract about which fields are present.
+     */
+    summary?: boolean;
+  }): Promise<ProviderPagedResult<PullRequestShape>>;
+  listIssuesPage(options: {
+    providerId: IntegrationIds;
+    repos?: ProviderRepositoriesInput;
+    /**
+     * Narrows the account-wide read (no `repos`) to one org/account, and `project` to one project within it.
+     * Only a git host with a project tier (Azure DevOps) can scope this server-side; for any other provider
+     * either option is rejected with a warning + `fetchFailed` rather than silently returning an unscoped
+     * list. Ignored when `repos` is supplied, since those repos are already the scope.
+     */
+    org?: string;
+    project?: string;
+    /**
+     * Narrows to the requested relationship(s), validated against `getSupportedFilters().issues` on the
+     * repo-scoped path and `.issuesAccountWide` on the account-wide one.
      *
-     * Results are echoed under the caller's own `key`, so no positional matching is needed. Per-target isolation
-     * is the rule: a chunk that fails upstream warns and drops only its own targets (with `fetchFailed` set) while
-     * every other target still answers.
+     * On the account-wide path this REPLACES the provider's own definition of "my issues" — GitHub/GHE
+     * authored + assigned + mentioned, Azure assigned + authored, and GitLab assigned-to-me — so
+     * `[Assignee]` gets `assignee:@me` semantics wherever it's expressible. Narrowing must happen here rather
+     * than on the returned page: the excluded items still counted toward the provider's paging, so filtering
+     * afterward leaves `items` describing a different result set than `hasMore`/`cursor`.
      *
-     * `issue: undefined` means PROVEN ABSENT — the issue does not exist, or is not visible to this connection —
-     * and is safe to cache. A target whose chunk failed is NOT returned at all, so the two are distinguishable;
-     * caching a failure as an absence is exactly the bug this distinction prevents. GitHub/GHE only: a provider
-     * that cannot batch refuses outright rather than degrading into N requests behind the caller's back.
+     * A set the provider can't express server-side is refused whole (warning + `fetchFailed`), never widened.
      */
-    getIssuesBatch(options: {
-        providerId: IntegrationIds;
-        /** Each `key` must be unique — a duplicate refuses the whole call, since keys identify results. */
-        targets: readonly IssueBatchTarget[];
-        connectionId?: string;
-        /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
-        domain?: string;
-    }): Promise<ProviderResult<IssueBatchResult>>;
+    filters?: IssueFilter[];
+    /** Broadens to every assignee. On account-wide reads it contradicts `filters`, so passing both is refused. */
+    includeAllAssignees?: boolean;
     /**
-     * Resolves one issue-tracker issue by key within a resource — the tracker counterpart of
-     * {@link getIssuesBatch}, which cannot serve one.
-     *
-     * `issue: undefined` is a proven absence and may be cached. A failed read returns no item and sets
-     * `fetchFailed`. `resourceId` is required and trusted; Jira also requires the resource's site URL so the result
-     * retains its browser link. The read performs no resource discovery.
+     * 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).
+     */
+    page?: number;
+    /** Continuation from a prior page's `cursor`; supplying it costs exactly one upstream request per scope. */
+    cursor?: string;
+    /**
+     * Page size PER QUERY, not per page. A page is a merge of one query per scope (repo-scoped) or per
+     * relationship category (account-wide GitHub: authored/assigned/mentioned), so it can return up to
+     * `N × itemsPerPage` items before deduplication. `page.itemsPerPage` reports what actually came back, so
+     * size the UI off that rather than off this. Account-wide GitLab, Azure and Linear reads ignore it and
+     * drain with their own bounds.
+     */
+    itemsPerPage?: number;
+    forceSync?: boolean;
+    connectionId?: string;
+    /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+    domain?: string;
+  }): Promise<ProviderPagedResult<IssueShape>>;
+  /**
+   * Issues matching structured criteria over a repository/org scope, with NO forced relationship to the current
+   * user — the issue counterpart of the PR search, and the read to use for "every issue in these repos matching
+   * X" rather than "my issues".
+   *
+   * Why this and not {@link listIssuesPage}: that read is either bound to the user's own relationships
+   * (account-wide) or routed through the SDK's repo-scoped read, whose over-limit recovery walk can spend up to
+   * 128 sequential requests and still return an incomplete set. This one is a single request per page.
+   *
+   * Three parts of the contract worth reading before calling:
+   *
+   * - **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 `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), `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. A provider that can prove the ceiling was reached without counting
+   *   past it (Azure DevOps Server, at 20,000) omits `totalCount`, so render the limit alone. An Azure DevOps Server
+   *   that refuses the match set even with the bounded query fails the page instead (warning + `fetchFailed`),
+   *   while its count still reports `exceedsProviderLimit`; narrow the search.
+   *
+   * On **Azure DevOps Server** every relationship is one WIQL query over one collection (`org`, or the
+   * repositories' collection), so `itemsPerPage` sizes the whole page. Continuations page through the ids the
+   * first page queried while the pagination keeps reading; one whose ids have expired is refused, and the read
+   * must restart without the cursor. See `docs/integrations.md` §9.
+   *
+   * Check `getSupportedFilters().issueSearch` first: a provider with no filtered issue search reports empty
+   * 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;
+    /**
+     * Repositories to search. Combines with `org`; both constrain the same query.
      *
-     * Jira and Linear only. Trello refuses: its single-issue read falls back to a capped board scan for a numeric
-     * identifier, so it cannot prove absence.
+     * Both halves of a descriptor must reach the provider unchanged — see `org` — since a search names a
+     * repository by its `namespace/name` path.
+     */
+    repos?: ProviderRepositoriesInput;
+    /**
+     * Organization/account to search. Combines with `repos`.
+     *
+     * Held to a STRICTER rule than the free-form criteria, which are sanitized: a scope name carrying a quote,
+     * or an inner space or control character, is REFUSED (warning + `fetchFailed`), and the refusal names the
+     * value — except on Azure DevOps Server, whose scope names never enter a query string, where only blank
+     * names and control characters are. Leading and trailing whitespace and control characters are stripped and accepted, since removing
+     * them cannot change which scope the query names.
+     * The sanitized value may name a real but DIFFERENT org, whose result looks entirely normal. `''` means
+     * "no org supplied" and falls through to the other scopes.
+     */
+    org?: string;
+    criteria?: IssueSearchCriteria;
+    /**
+     * Requested 1-based page. This read is cursor-only, so without a `cursor` reaching page N costs O(N)
+     * upstream requests; pass the previous page's cursor to make it exactly one.
+     */
+    page?: number;
+    cursor?: string;
+    /**
+     * Page size PER RELATIONSHIP, not per page. Each requested relationship is its own provider query, so a
+     * page of a 2-relationship search returns up to `2 × itemsPerPage` items before deduplication — and fewer
+     * than that when the two overlap. `page.itemsPerPage` reports what actually came back, so size the UI off
+     * that rather than off this. A provider may also cap it below what is asked for.
+     */
+    itemsPerPage?: number;
+    forceSync?: boolean;
+    connectionId?: string;
+    /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+    domain?: string;
+  }): Promise<ProviderPagedResult<IssueShape>>;
+  /**
+   * How many issues MATCH each scope, without fetching any of them — the probe behind a "this will fetch ~N
+   * issues" preview, and behind a live count next to a filter the user hasn't applied yet.
+   *
+   * Cheap by design: every scope that can share a request does, and no issue data crosses the wire (measured
+   * against GitHub, 30 counts are a single rate-limit point). Still a network request per batch, so debounce and
+   * cache it if it's driven from UI state.
+   *
+   * A separate method rather than a flag on {@link searchIssuesPage} because transferring zero issues is the
+   * whole point: a `countOnly` read would hand back a paged result whose `items`/`cursor`/`hasMore` are all
+   * meaningless.
+   *
+   * Results are echoed under the caller's own `key`, so no positional matching is needed. Per-scope isolation is
+   * the rule: a scope refused for its own reasons, or a batch that failed upstream, warns and drops only its own
+   * scopes (with `fetchFailed` set) while every other count still comes back.
+   *
+   * `count: undefined` means the provider didn't report one — NOT zero, which is a real answer. Render the
+   * difference: showing an unknown count as 0 tells the user a filter matches nothing when it may match
+   * thousands. A provider that can't count at all (only GitHub/GHE and Azure DevOps Server can today) refuses the
+   * probe outright rather than returning fabricated numbers.
+   */
+  countIssues(options: {
+    providerId: IntegrationIds;
+    /** Each needs its own scope, and each requested relationship its own entry — see {@link IssueCountScope}. */
+    scopes: readonly IssueCountScope[];
+    connectionId?: string;
+    /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+    domain?: string;
+  }): Promise<ProviderResult<IssueCountResult>>;
+  /**
+   * Resolves several issues BY COORDINATE — `(owner, repo, number)` — in one request.
+   *
+   * The read for "which issue does this branch name reference", which is an IDENTITY question rather than a
+   * search. Emulating it by paging a scoped list and matching the identifier cannot prove absence without
+   * walking the whole scope, so a miss stays unproven, uncacheable, and repeats its whole budget on every pass.
+   * This answers it in one request per chunk, and a miss is final.
+   *
+   * Results are echoed under the caller's own `key`, so no positional matching is needed. Per-target isolation
+   * is the rule: a chunk that fails upstream warns and drops only its own targets (with `fetchFailed` set) while
+   * every other target still answers.
+   *
+   * `issue: undefined` means PROVEN ABSENT — the issue does not exist, or is not visible to this connection —
+   * and is safe to cache. A target whose chunk failed is NOT returned at all, so the two are distinguishable;
+   * caching a failure as an absence is exactly the bug this distinction prevents. GitHub/GHE only: a provider
+   * that cannot batch refuses outright rather than degrading into N requests behind the caller's back.
+   */
+  getIssuesBatch(options: {
+    providerId: IntegrationIds;
+    /** Each `key` must be unique — a duplicate refuses the whole call, since keys identify results. */
+    targets: readonly IssueBatchTarget[];
+    connectionId?: string;
+    /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+    domain?: string;
+  }): Promise<ProviderResult<IssueBatchResult>>;
+  /**
+   * Resolves one issue-tracker issue by key within a resource — the tracker counterpart of
+   * {@link getIssuesBatch}, which cannot serve one.
+   *
+   * `issue: undefined` is a proven absence and may be cached. A failed read returns no item and sets
+   * `fetchFailed`. `resourceId` is required and trusted; Jira Cloud also requires the resource's site URL so the
+   * result retains its browser link. The read performs no resource discovery.
+   *
+   * Jira (Cloud and Data Center) and Linear only. Trello refuses: its single-issue read falls back to a capped
+   * board scan for a numeric identifier, so it cannot prove absence.
+   *
+   * Jira Data Center is addressed per host and, unlike the paged reads, this one never falls back to the primary
+   * connection: it requires a `domain` or a `connectionId` with a configured host and refuses otherwise, since two
+   * self-hosted instances routinely issue the same keys and a cached absence must name the host it was proven on.
+   */
+  getTrackerIssue(options: {
+    providerId: IntegrationIds;
+    /**
+     * Provider resource ID for the Atlassian site or Linear workspace. For Jira Data Center it is the host, the
+     * instance's single resource as `listOrgs` reports it, and must name the host the read resolves to.
      */
-    getTrackerIssue(options: {
-        providerId: IntegrationIds;
-        /** Provider resource ID for the Atlassian site or Linear workspace. */
-        resourceId: string;
-        /** Jira site URL from resource discovery. Required for Jira so the result retains a browser link. */
-        resourceUrl?: string;
-        /** The provider's own key, e.g. `ABC-123`. Not a number. */
-        key: string;
-        connectionId?: string;
-    }): Promise<ProviderResult<TrackerIssueResult>>;
+    resourceId: string;
     /**
-     * How many pull requests match each scope, fetching none of them — the PR twin of {@link countIssues}, behind a
-     * "this will fetch ~N pull requests" preview and a live count next to an unapplied filter. Same cost model,
-     * per-scope isolation, `key`-echo, and `count: undefined` ≠ zero rule as the issue count; GitHub/GHE only.
+     * Jira site URL from resource discovery. Required for Jira Cloud so the result retains a browser link; Jira
+     * Data Center builds it from the connection's own base URL.
+     */
+    resourceUrl?: string;
+    /** The provider's own key, e.g. `ABC-123`. Not a number. */
+    key: string;
+    connectionId?: string;
+    /**
+     * Self-managed tracker host; see {@link ProviderSweepTarget.domain}. Ignored for the cloud trackers. Required
+     * for Jira Data Center unless `connectionId` names a configured host — see above.
+     */
+    domain?: string;
+  }): Promise<ProviderResult<TrackerIssueResult>>;
+  /**
+   * How many pull requests match each scope — the PR twin of {@link countIssues}, behind a "this will fetch ~N pull
+   * requests" preview and a live count next to an unapplied filter. Same per-scope isolation, `key`-echo, and
+   * `count: undefined` ≠ zero rule as the issue count; GitHub/GHE, Bitbucket Data Center and Azure DevOps Server.
+   *
+   * The one PR-specific difference: on GitHub/GHE a scope's `states` are counted as independent searches, so the
+   * reported count is the LARGEST of them (the same total {@link searchPullRequestsPage} surfaces), not their sum.
+   * Several states in one scope are therefore fine; only several relationships are refused — one relationship per
+   * scope, see {@link PullRequestCountScope}.
+   *
+   * Bitbucket Data Center has no count query: it counts by reading each facet's first page, so a count there costs
+   * requests rather than none, and one past that page comes back as a floor with `lowerBound: true`. Reading lets it
+   * deduplicate the rows, so it counts the exact union of the states AND of several relationships in one scope,
+   * matching what the search it previews returns.
+   *
+   * Azure DevOps Server counts from the same drain its search pages through (reusing one its search read in the
+   * last minute), so its count is the union of the states — for disjoint states their sum — and costs requests too.
+   */
+  countPullRequests(options: {
+    providerId: IntegrationIds;
+    scopes: readonly PullRequestCountScope[];
+    connectionId?: string;
+    /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+    domain?: string;
+  }): Promise<ProviderResult<PullRequestCountResult>>;
+  listIssueTrackerIssuesPage(options: {
+    providerId: IntegrationIds;
+    org?: string;
+    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.
      *
-     * The one PR-specific difference: a scope's `states` are counted as independent searches, so the reported count
-     * is the LARGEST of them (the same total {@link searchPullRequestsPage} surfaces), not their sum. Several states
-     * in one scope are therefore fine; only several relationships are refused — one relationship per scope, see
-     * {@link PullRequestCountScope}.
+     * 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.
      */
-    countPullRequests(options: {
-        providerId: IntegrationIds;
-        scopes: readonly PullRequestCountScope[];
-        connectionId?: string;
-        /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
-        domain?: string;
-    }): Promise<ProviderResult<PullRequestCountResult>>;
-    /** Issue trackers are cloud-only, so this read takes no `domain`. */
-    listIssueTrackerIssuesPage(options: {
-        providerId: IntegrationIds;
-        org?: string;
-        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;
-        /**
-         * Opaque continuation from a prior result. It can bundle the next untouched project window with failed
-         * discovery/project retries and already-emitted project identities, so it is not equivalent to `page`.
-         * Thread it back verbatim. A retry-only cursor can remain when `hasMore` is false; reusing that cursor is
-         * an explicit manual retry, while `hasMore` represents automatic forward progress only.
-         */
-        cursor?: string;
-        /**
-         * Page size in PROJECTS, not issues (default 20): these providers have no cross-project issue cursor, so
-         * a page is a window of projects, each drained in full. Supplying it (or `page`/`cursor`) opts into
-         * pagination; omitting all three aggregates every matched project in one page.
-         */
-        itemsPerPage?: number;
-        connectionId?: string;
-    }): Promise<ProviderPagedResult<IssueShape>>;
-    sweepPullRequests(options?: PullRequestSweepOptions): Promise<ProviderSweepResult<PullRequestShape>>;
-    sweepClosedPullRequests(options?: ClosedPullRequestSweepOptions): Promise<ProviderSweepResult<PullRequestShape>>;
-    broadenIssues(options: {
-        orgs: ProviderBroadenOrg[];
-        /**
-         * Requested 1-based page. Without a `cursor` the fan-out is re-run once per prior page (O(page) rounds),
-         * since a per-org cursor bundle is the only way to address a later page.
-         */
-        page?: number;
-        /** Continuation from a prior page's `cursor`; supplying it runs exactly one fan-out round. */
-        cursor?: string;
-        forceSync?: boolean;
-    }): Promise<ProviderBroadenResult<IssueShape>>;
-    resolveRepository(options: {
-        providerId?: IntegrationIds;
-        remoteUrl: string;
-        host?: string;
-        connectionId?: string;
-        /**
-         * Explicit self-managed host domain used to select the integration instance. It must come from trusted
-         * authentication configuration. Without it, the host parsed from `remoteUrl` is only a resolution
-         * candidate: the facade proceeds only when that host matches a configured integration, so repository
-         * data cannot select credentials for an arbitrary host.
-         */
-        domain?: string;
-    }): Promise<ResolveRepositoryResult>;
+    sort?: IssueSorting;
+    forceSync?: boolean;
+    page?: number;
+    /**
+     * Opaque continuation from a prior result. It can bundle the next untouched project window with failed
+     * discovery/project retries and already-emitted project identities, so it is not equivalent to `page`.
+     * Thread it back verbatim. A retry-only cursor can remain when `hasMore` is false; reusing that cursor is
+     * an explicit manual retry, while `hasMore` represents automatic forward progress only.
+     */
+    cursor?: string;
+    /**
+     * Page size in PROJECTS, not issues (default 20): these providers have no cross-project issue cursor, so
+     * a page is a window of projects, each drained in full. Supplying it (or `page`/`cursor`) opts into
+     * pagination; omitting all three aggregates every matched project in one page.
+     */
+    itemsPerPage?: number;
+    connectionId?: string;
+    /**
+     * Self-managed tracker host domain fallback; see {@link ProviderSweepTarget.domain}. Ignored for the
+     * cloud trackers, which have a single canonical host.
+     */
+    domain?: string;
+  }): Promise<ProviderPagedResult<IssueShape>>;
+  sweepPullRequests(options?: PullRequestSweepOptions): Promise<ProviderSweepResult<PullRequestShape>>;
+  sweepClosedPullRequests(options?: ClosedPullRequestSweepOptions): Promise<ProviderSweepResult<PullRequestShape>>;
+  broadenIssues(options: {
+    orgs: ProviderBroadenOrg[];
+    /**
+     * Requested 1-based page. Without a `cursor` the fan-out is re-run once per prior page (O(page) rounds),
+     * since a per-org cursor bundle is the only way to address a later page.
+     */
+    page?: number;
+    /** Continuation from a prior page's `cursor`; supplying it runs exactly one fan-out round. */
+    cursor?: string;
+    forceSync?: boolean;
+  }): Promise<ProviderBroadenResult<IssueShape>>;
+  resolveRepository(options: {
+    providerId?: IntegrationIds;
+    remoteUrl: string;
+    host?: string;
+    connectionId?: string;
+    /**
+     * Explicit self-managed host domain used to select the integration instance. It must come from trusted
+     * authentication configuration. Without it, the host parsed from `remoteUrl` is only a resolution
+     * candidate: the facade proceeds only when that host matches a configured integration, so repository
+     * data cannot select credentials for an arbitrary host.
+     */
+    domain?: string;
+  }): Promise<ResolveRepositoryResult>;
 }
-export {};
+//#endregion
 //# sourceMappingURL=manager.d.ts.map