@gitkraken/core-gitlens 0.9.3 → 0.9.5

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

@@ -1,11 +1,12 @@
 import { Event } from "../../utils/event.js";
-import { IssueSearchCriteria, IssueShape, IssueSorting } from "../../git/models/issue.js";
+import { IssueSearchCriteria, IssueShape, IssueSorting, IssueStateFilter } 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 { IssueFilter } from "./providerFilters.js";
+import { IssueEtagInclude, PullRequestEtagInclude } from "./models/integration.js";
 import { IssueCountResult, IssueCountScope, PullRequestCountResult, PullRequestCountScope } from "./reads/counts.js";
 import { CurrentAccountResult } from "./reads/currentAccount.js";
 import { SupportedFilters } from "./reads/filters.js";
@@ -156,6 +157,12 @@ type PullRequestSweepCommonOptions = {
    */
   includeReviews?: boolean;
   forceSync?: boolean;
+  /**
+   * Page budget per provider. A stop at this budget with a resumable cursor is reported as
+   * `pagination-incomplete` with `recovery: 'page-budget'`. A part no budget reaches is reported beside it
+   * with `recovery: 'none'`: a `provider-limit` omission when the reported match count exceeds the provider's
+   * known result limit.
+   */
   maxPages?: number;
   /**
    * Fired once per target as it settles, for host-side per-provider attribution.
@@ -623,6 +630,16 @@ export interface IntegrationManager {
    * outright — Bitbucket because it has no issues, Trello because its single-issue read can fall back to a capped
    * board scan, which cannot prove an absence.
    *
+   * Change detection: every found row carries an opaque `etag`; send it back on the target and, where the host has a
+   * cheap check (GitHub/GHE, GitLab, Azure DevOps, Jira Cloud and Linear so far), an issue whose etag still matches comes
+   * back `{ key, unchanged: true, etag }` without being read again. That costs up to three integration calls instead
+   * of one — the cheap check, a full read of the targets with no etag started alongside it, and a full read of the
+   * ones that changed — and still one when no target carries an etag. `etagIncludes: ['reactions']` widens the etag
+   * to the thumbs-up count, which a host changes without moving the update time; only GitHub/GHE and GitLab rows
+   * carry a real count, so it widens nothing elsewhere. A cheap check that fails falls through to the full read,
+   * except on an auth, rate-limit or connection failure, which drops its targets with that warning. See
+   * {@link IssueBatchResult}.
+   *
    * A self-managed tracker (Jira Data Center) never falls back to the primary connection, unlike the paged reads:
    * the call is refused unless `domain` names a host or `connectionId` a configured connection that has one, and
    * every target's `resourceId` must name the host the read resolved to. Two self-hosted instances routinely issue
@@ -638,6 +655,12 @@ export interface IntegrationManager {
      * for a self-managed tracker unless `connectionId` names a configured host — see above.
      */
     domain?: string;
+    /**
+     * Widens every etag to the listed inputs; order and repeats don't matter, and an unknown value refuses the
+     * whole call. `'reactions'` is the thumbs-up count, and costs its field in the cheap check on GitHub/GHE and
+     * GitLab. Changes only which etag is computed (and the cheap check's selection); the full read is the same.
+     */
+    etagIncludes?: readonly IssueEtagInclude[];
   }): Promise<ProviderResult<IssueBatchResult>>;
   /**
    * Resolves several pull requests BY COORDINATE — `(owner, repo, number)`, plus `project` on Azure DevOps — in
@@ -663,6 +686,19 @@ export interface IntegrationManager {
    * Request cost: GitHub/GHE resolve up to 25 targets per request (one aliased GraphQL document). Every other
    * host costs one request per target, run with bounded concurrency; GitLab spends a second request to confirm a
    * miss, and Azure DevOps one more per target (two for a fork) to fill clone URLs.
+   *
+   * Change detection: every found row carries an opaque `etag`; send it back on the target and, where the host has a
+   * cheap check (GitHub/GHE, a minimal aliased document; GitLab, one minimal request per project; Azure DevOps, one
+   * request per target without the clone URL reads, which fingerprints the title, description, target branch and
+   * reviewers as Azure DevOps reports no update time, but stays blind to comments; Bitbucket Cloud, one list request
+   * per repository per 50 pull requests), a pull request whose etag still matches comes back `{ key, unchanged: true,
+   * etag }` without being read again. That costs up to three integration calls instead of one — the cheap check, a
+   * full read of the targets with no etag started alongside it, and a full read of the ones that changed — and still
+   * one when no target carries an etag.
+   * `etagIncludes` widens the etag to the listed inputs (mergeability, review decision, check rollup), which a host
+   * changes without moving the update time and each of which costs its own fields in the cheap check (the review
+   * decision costs the most). A cheap check that fails falls through to the full read, except on an auth, rate-limit
+   * or connection failure, which drops its targets with that warning. See {@link PullRequestBatchResult}.
    */
   getPullRequestsBatch(options: {
     providerId: IntegrationIds;
@@ -671,6 +707,13 @@ export interface IntegrationManager {
     connectionId?: string;
     /** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
     domain?: string;
+    /**
+     * Widens every etag to the listed inputs; order and repeats don't matter, and an unknown value refuses the
+     * whole call. Each entry widens the etag to one input a host changes without moving the update time, and
+     * costs its own fields in the cheap check; `'checks'` is the check rollup. Changes only which etag is
+     * computed (and the cheap check's selection); the full read is the same.
+     */
+    etagIncludes?: readonly PullRequestEtagInclude[];
   }): Promise<ProviderResult<PullRequestBatchResult>>;
   /**
    * Finds, for each branch, every pull request whose head is that branch — in any state (open, closed or merged),
@@ -682,10 +725,14 @@ export interface IntegrationManager {
    * branch in a fork, `headOwner` (the base repository's own owner, or none, means the base repository). A pull
    * request matches only when its head repository is the right one — the base repository itself, or the fork
    * `headOwner` owns — so a `main` in the base repository never claims every fork's `main`. The match is on the
-   * head branch NAME, so a merged pull request whose branch was since deleted is still found.
+   * head branch NAME, so a merged pull request whose branch was since deleted is still found, and a fork is matched
+   * by its owner, so one whose fork was since deleted still matches that `headOwner`.
    *
    * Same result contract as {@link getPullRequestsBatch}, echoed under the caller's own `key`:
-   * - `{ key, pullRequests: [...] }` — found. `truncated` means more may match than were returned.
+   * - `{ key, pullRequests: [...] }` — found. `truncated` means a pull request that wasn't returned could still
+   *   match. One exception on GitHub/GHE: on a branch name more forks share than the first request returned, a
+   *   pull request from a since-deleted fork that request didn't return can't be found at all, so it can be
+   *   missing from an answer, even an empty one, that isn't `truncated`.
    * - `{ key, pullRequests: [] }` with no `truncated` — PROVEN NONE: the host answered and nothing matched, or the
    *   base repository doesn't exist or isn't visible to this connection. Safe to cache.
    * - No item for a key, with `fetchFailed` and a warning — the read could not check. Never treat that as none.
@@ -695,9 +742,12 @@ export interface IntegrationManager {
    * looks the branch ref up and so answers "none" once a merged branch is deleted. The caller owns caching.
    *
    * Request cost: GitHub/GHE answer up to 25 targets per request (one aliased GraphQL document, fetching up to 10
-   * full pull requests per target). Every other host costs one request per target, run with bounded concurrency;
-   * GitLab and Azure DevOps then resolve each matched pull request — typically 0–1 per branch — through
-   * {@link getPullRequestsBatch}'s own read, at that read's cost, so their rows are exactly its rows. Rows carry
+   * full pull requests per target). That document matches the branch name across every fork, so a target whose
+   * name more forks share than it returned costs one more REST request filtered by head owner, and a match only
+   * that request found is resolved through {@link getPullRequestsBatch}'s own read, so its row is identical to the
+   * others; the answer is the union of both requests' matches. Every other host costs one request per target, run
+   * with bounded concurrency; GitLab and Azure DevOps then resolve each matched pull request — typically 0–1 per
+   * branch — through {@link getPullRequestsBatch}'s own read, at that read's cost, so their rows are exactly its rows. Rows carry
    * the list reads' fields on GitHub/GHE and Bitbucket Data Center and Bitbucket Cloud's by-id read's on
    * Bitbucket Cloud. A `headOwner` naming another owner is refused on Bitbucket Data Center and Azure DevOps,
    * where a fork can't be found by its owner.
@@ -751,6 +801,11 @@ export interface IntegrationManager {
      * full, so which projects a round covers doesn't depend on how their issues are ordered.
      */
     sort?: IssueSorting;
+    /**
+     * Which issue states to read. Omitted reads open issues. `'closed'`/`'all'` need
+     * `getSupportedFilters().issueStates` and are refused otherwise (warning + `fetchFailed`).
+     */
+    state?: IssueStateFilter;
     forceSync?: boolean;
     page?: number;
     /**

package/dist/plus/integrations/models/gitHostIntegration.d.ts

@@ -12,9 +12,9 @@ import { IntegrationIds } from "../constants.js";
 import { ProviderOrganization } from "../results.js";
 import { ProviderScopeFailure } from "../collectionMetadata.js";
 import { ProviderPullRequestCount, ProviderPullRequestSearchPage } from "./pullRequestReads.js";
-import { MyIssuesForReposOptions, ProviderIssueSearchPage, ProviderSearchCount } from "./issueReads.js";
-import { BatchSlot, IntegrationBase, IntegrationResult, IntegrationType } from "./integration.js";
 import { ProviderApiPagedResult, ProviderHierarchyResult, ProviderIssue, ProviderPullRequest, ProviderRepoInput, ProviderReposInput, ProviderRepository } from "../providers/models.js";
+import { MyIssuesForReposOptions, ProviderIssueSearchPage, ProviderSearchCount } from "./issueReads.js";
+import { BatchSlot, IntegrationBase, IntegrationResult, IntegrationType, IssueEtagFields, IssueEtagInclude, PullRequestEtagFields, PullRequestEtagInclude } from "./integration.js";
 import { CollectionMetadata } from "@gitkraken/provider-apis";
 //#region ../plus/integrations/src/models/gitHostIntegration.d.ts
 /** Read options for {@link GitHostIntegration.searchMyPullRequests} and the provider hook behind it. */
@@ -132,6 +132,14 @@ export declare abstract class GitHostIntegration<ID extends IntegrationIds = Int
    * filters and no issue read is answering the same capability question twice, and the two must agree.
    */
   get supportsIssues(): boolean;
+  /**
+   * Whether this host has the cheap check behind the batch pull request read's etags
+   * ({@link getProviderPullRequestsEtagFields}). The read decides before calling anything, so a host without one
+   * full-reads every target in a single call.
+   */
+  get supportsPullRequestEtags(): boolean;
+  /** The issue twin of {@link supportsPullRequestEtags}: whether {@link getProviderIssuesEtagFields} exists. */
+  get supportsIssueEtags(): boolean;
   /**
    * Lists the organizations (orgs/workspaces/groups) the current user belongs to on this host.
    * `truncated === true` means the defensive page-drain backstop stopped before the upstream listing was
@@ -271,8 +279,9 @@ export declare abstract class GitHostIntegration<ID extends IntegrationIds = Int
     connectionId?: string;
   }): Promise<IntegrationResult<PullRequest[] | undefined>>;
   /**
-   * Account-wide, user-scoped counterpart of {@link getMyPullRequestsForReposResult} that returns the raw
-   * `ProviderPullRequest` shape (not the normalized model). Unlike the repo-scoped core, this needs no
+   * Account-wide, user-scoped counterpart of {@link getMyPullRequestsForReposResult} that returns each host's raw
+   * rows: provider-apis' `ProviderPullRequest`, or GitHub's own `PullRequest`, still to be tagged for the read
+   * (`toPullRequestRow`). Unlike the repo-scoped core, this needs no
    * `repos` — it reads the current user's pull requests across the account, so the ProviderBackend sweep
    * can drive its Kanban "done" column even when no repositories are supplied (where the repo-scoped core
    * rejects an empty `repos` input). Recovers thrown errors into `{ error }` so callers surface warnings.
@@ -285,10 +294,11 @@ export declare abstract class GitHostIntegration<ID extends IntegrationIds = Int
     filters?: PullRequestFilter[];
     /** Request only the stable list fields, omitting optional provider enrichments. */
     summary?: boolean;
-  }, connectionId?: string): Promise<IntegrationResult<ProviderApiPagedResult<ProviderPullRequest> | undefined>>;
+  }, connectionId?: string): Promise<IntegrationResult<ProviderApiPagedResult<ProviderPullRequest | PullRequest> | undefined>>;
   /**
    * Reads the current user's pull requests across the whole account using each provider's native "my PRs"
-   * query, returning the raw provider shape. Without `filters`, the exact user scopes depend on provider-native
+   * query, returning its raw rows (see {@link getMyPullRequestsForUserResult}). Without `filters`, the exact user
+   * scopes depend on provider-native
    * behavior and options like `includeReviewRequested`. With `filters`, each member is an exact account-wide OR
    * relationship validated by the facade before this provider hook is called. Optional: providers that can't
    * express an account-wide user query leave it undefined and the surface falls back to repo-scoped.
@@ -307,7 +317,17 @@ export declare abstract class GitHostIntegration<ID extends IntegrationIds = Int
     includeReviewRequested?: boolean;
     filters?: PullRequestFilter[];
     summary?: boolean;
-  }): Promise<ProviderApiPagedResult<ProviderPullRequest> | undefined>;
+  }): Promise<ProviderApiPagedResult<ProviderPullRequest | PullRequest> | undefined>;
+  /**
+   * The current account as each of `pullRequests` identifies its members, in order: what a raw row's
+   * `authoredByMe` and `viewer` are resolved against when it's mapped. Most hosts give a person one id, so every
+   * row gets the account itself; Azure DevOps Server answers per collection (see `AzureDevOpsServerIntegration`).
+   * Throws only when the account itself can't be read.
+   */
+  getPullRequestViewers(pullRequests: readonly (ProviderPullRequest | PullRequest)[], connectionId?: string): Promise<({
+    id: string;
+    username?: string;
+  } | undefined)[]>;
   /**
    * Parses a Repo/Project paging cursor into its `cursors` bundle. Guards against valid JSON whose
    * `cursors` is a truthy non-array (e.g. `{ "cursors": "..." }`), which would otherwise bypass the
@@ -423,7 +443,10 @@ export declare abstract class GitHostIntegration<ID extends IntegrationIds = Int
    * as a failure against the integration's request-exception budget only when EVERY slot rejected, and not even
    * then when a credential that checks out was refused by each target's own scope (`settleBatchRefusals`).
    * Server errors and timeouts on the targets show one notice however many hit one, and cost a strike only as
-   * part of that whole-call failure (`reportDeferredRequestFailures`), so a call never spends more than one.
+   * part of that whole-call failure (`reportDeferredRequestFailures`), so a call spends at most one. A batch read
+   * with etags makes up to two such calls (a full read of the targets without an etag, and a full read of the ones
+   * that changed), so it can spend two; its cheap check ({@link getIssuesEtagFieldsResult}) spends nothing unless
+   * the credential is refused.
    */
   getIssuesBatchResult(coordinates: readonly {
     owner: string;
@@ -458,7 +481,10 @@ export declare abstract class GitHostIntegration<ID extends IntegrationIds = Int
    * call counts as a failure against the integration's request-exception budget only when EVERY slot rejected,
    * and not even then when a credential that checks out was refused by each target's own scope
    * (`settleBatchRefusals`). Server errors and timeouts on the targets show one notice however many hit one, and
-   * cost a strike only as part of that whole-call failure (`reportDeferredRequestFailures`).
+   * cost a strike only as part of that whole-call failure (`reportDeferredRequestFailures`), so one call spends at
+   * most one. A batch read with etags makes up to two such calls (a full read of the targets without an etag, and a
+   * full read of the ones that changed), so it can spend two; its cheap check
+   * ({@link getPullRequestsEtagFieldsResult}) spends nothing unless the credential is refused.
    */
   getPullRequestsBatchResult(coordinates: readonly {
     owner: string;
@@ -492,6 +518,74 @@ export declare abstract class GitHostIntegration<ID extends IntegrationIds = Int
       username?: string;
     };
   } | undefined, cancellation?: AbortSignal): Promise<PromiseSettledResult<PullRequestShape | undefined>[] | undefined>;
+  /**
+   * Result-returning wrapper for the cheap check behind the batch issue read's etags: each coordinate's change
+   * state ({@link IssueEtagFields}), plus the inputs of each of `options.etagIncludes`, in ONE call to
+   * {@link getProviderIssuesEtagFields}. The slots mean what
+   * {@link getIssuesBatchResult}'s do — `fulfilled` with `undefined` is a PROVEN ABSENCE, `rejected` means that
+   * target could not be checked.
+   *
+   * Unlike there, failures other than a refused credential are never the call's: every slot comes back as it
+   * settled, even when none answered, so each failed target is judged by its own reason. Such failures spend no
+   * strike and show no notice, since the targets they touch fall through to the full read, which does both if the
+   * host really is failing, or are dropped as rate-limited or without a connection. Refusals are settled as there
+   * (`settleBatchRefusals` with `keepOtherFailures`), and only a refused credential fails the call, on the auth path
+   * (`handleEtagCheckException`). The failure budget is reset only when some target answered.
+   */
+  getIssuesEtagFieldsResult(coordinates: readonly {
+    owner: string;
+    repo: string;
+    number: number;
+    project?: string;
+  }[], options: {
+    etagIncludes?: readonly IssueEtagInclude[];
+  }, cancellation?: AbortSignal, connectionId?: string): Promise<IntegrationResult<BatchSlot<IssueEtagFields | undefined>[] | undefined>>;
+  /**
+   * OPTIONAL: the cheap check behind the batch issue read's etags — one settled slot per input coordinate, in
+   * order, holding the issue's change state in the vocabulary {@link getProviderIssuesBatch}'s rows end in, so
+   * both reads compute the same etag. Each include's inputs are read only when it is listed in
+   * `options.etagIncludes`, and only where a full row carries them. `fulfilled` with `undefined` is a PROVEN
+   * ABSENCE, as there. A host implements this only where it is cheaper than the full read.
+   */
+  protected getProviderIssuesEtagFields?(session: ProviderAuthenticationSession, coordinates: readonly {
+    owner: string;
+    repo: string;
+    number: number;
+    project?: string;
+  }[], options: {
+    etagIncludes?: readonly IssueEtagInclude[];
+  }, cancellation?: AbortSignal): Promise<PromiseSettledResult<IssueEtagFields | undefined>[] | undefined>;
+  /**
+   * Result-returning wrapper for the cheap check behind the batch pull request read's etags: each coordinate's
+   * change state ({@link PullRequestEtagFields}), plus the inputs of each of `options.etagIncludes`, in ONE call to
+   * {@link getProviderPullRequestsEtagFields}. The slots mean what {@link getPullRequestsBatchResult}'s do —
+   * `fulfilled` with `undefined` is a PROVEN ABSENCE, `rejected` means that target could not be checked. Failures
+   * are judged and budgeted as in {@link getIssuesEtagFieldsResult}: only a refused credential fails the call or
+   * spends a strike.
+   */
+  getPullRequestsEtagFieldsResult(coordinates: readonly {
+    owner: string;
+    repo: string;
+    number: number;
+    project?: string;
+  }[], options: {
+    etagIncludes?: readonly PullRequestEtagInclude[];
+  }, cancellation?: AbortSignal, connectionId?: string): Promise<IntegrationResult<BatchSlot<PullRequestEtagFields | undefined>[] | undefined>>;
+  /**
+   * OPTIONAL: the cheap check behind the batch pull request read's etags — one settled slot per input coordinate,
+   * in order, holding the pull request's change state in the vocabulary {@link getProviderPullRequestsBatch}'s
+   * rows end in, after their WHOLE conversion chain, so both reads compute the same etag. Each include's inputs are
+   * read only when it is listed in `options.etagIncludes`. `fulfilled` with `undefined` is a PROVEN ABSENCE, as
+   * there. A host implements this only where it is cheaper than the full read.
+   */
+  protected getProviderPullRequestsEtagFields?(session: ProviderAuthenticationSession, coordinates: readonly {
+    owner: string;
+    repo: string;
+    number: number;
+    project?: string;
+  }[], options: {
+    etagIncludes?: readonly PullRequestEtagInclude[];
+  }, cancellation?: AbortSignal): Promise<PromiseSettledResult<PullRequestEtagFields | undefined>[] | undefined>;
   /**
    * Result-returning wrapper for the pull-requests-by-branch read: for each target, every pull request whose head
    * is that branch, in any state, in ONE call to {@link getProviderPullRequestsForBranches}. One settled slot

package/dist/plus/integrations/models/gitHostIntegration.js

@@ -212,6 +212,18 @@ var GitHostIntegration = class extends IntegrationBase {
 		return true;
 	}
 	/**
+	* Whether this host has the cheap check behind the batch pull request read's etags
+	* ({@link getProviderPullRequestsEtagFields}). The read decides before calling anything, so a host without one
+	* full-reads every target in a single call.
+	*/
+	get supportsPullRequestEtags() {
+		return this.getProviderPullRequestsEtagFields != null;
+	}
+	/** The issue twin of {@link supportsPullRequestEtags}: whether {@link getProviderIssuesEtagFields} exists. */
+	get supportsIssueEtags() {
+		return this.getProviderIssuesEtagFields != null;
+	}
+	/**
 	* Lists the organizations (orgs/workspaces/groups) the current user belongs to on this host.
 	* `truncated === true` means the defensive page-drain backstop stopped before the upstream listing was
 	* exhausted.
@@ -760,7 +772,7 @@ var GitHostIntegration = class extends IntegrationBase {
 			value: void 0,
 			duration: result.duration
 		};
-		const values = result.value.values.map((issue) => toIssueShape(issue, this)).filter((issue) => issue != null);
+		const values = result.value.values.map((issue) => toIssueShape(issue, this, { projection: "repos" })).filter((issue) => issue != null);
 		return {
 			value: {
 				...result.value,
@@ -1012,8 +1024,9 @@ var GitHostIntegration = class extends IntegrationBase {
 		}
 	}
 	/**
-	* Account-wide, user-scoped counterpart of {@link getMyPullRequestsForReposResult} that returns the raw
-	* `ProviderPullRequest` shape (not the normalized model). Unlike the repo-scoped core, this needs no
+	* Account-wide, user-scoped counterpart of {@link getMyPullRequestsForReposResult} that returns each host's raw
+	* rows: provider-apis' `ProviderPullRequest`, or GitHub's own `PullRequest`, still to be tagged for the read
+	* (`toPullRequestRow`). Unlike the repo-scoped core, this needs no
 	* `repos` — it reads the current user's pull requests across the account, so the ProviderBackend sweep
 	* can drive its Kanban "done" column even when no repositories are supplied (where the repo-scoped core
 	* rejects an empty `repos` input). Recovers thrown errors into `{ error }` so callers surface warnings.
@@ -1044,6 +1057,20 @@ var GitHostIntegration = class extends IntegrationBase {
 		}
 	}
 	/**
+	* The current account as each of `pullRequests` identifies its members, in order: what a raw row's
+	* `authoredByMe` and `viewer` are resolved against when it's mapped. Most hosts give a person one id, so every
+	* row gets the account itself; Azure DevOps Server answers per collection (see `AzureDevOpsServerIntegration`).
+	* Throws only when the account itself can't be read.
+	*/
+	async getPullRequestViewers(pullRequests, connectionId) {
+		const account = await this.getCurrentAccount({ connectionId });
+		const viewer = account != null ? {
+			id: account.id,
+			username: account.username
+		} : void 0;
+		return pullRequests.map(() => viewer);
+	}
+	/**
 	* Parses a Repo/Project paging cursor into its `cursors` bundle. Guards against valid JSON whose
 	* `cursors` is a truthy non-array (e.g. `{ "cursors": "..." }`), which would otherwise bypass the
 	* `?? []` fallback at call sites and flow into `.map()` downstream, throwing instead of degrading to
@@ -1187,7 +1214,10 @@ var GitHostIntegration = class extends IntegrationBase {
 	* as a failure against the integration's request-exception budget only when EVERY slot rejected, and not even
 	* then when a credential that checks out was refused by each target's own scope (`settleBatchRefusals`).
 	* Server errors and timeouts on the targets show one notice however many hit one, and cost a strike only as
-	* part of that whole-call failure (`reportDeferredRequestFailures`), so a call never spends more than one.
+	* part of that whole-call failure (`reportDeferredRequestFailures`), so a call spends at most one. A batch read
+	* with etags makes up to two such calls (a full read of the targets without an etag, and a full read of the ones
+	* that changed), so it can spend two; its cheap check ({@link getIssuesEtagFieldsResult}) spends nothing unless
+	* the credential is refused.
 	*/
 	async getIssuesBatchResult(coordinates, cancellation, connectionId) {
 		const scope = getScopedLogger();
@@ -1235,7 +1265,10 @@ var GitHostIntegration = class extends IntegrationBase {
 	* call counts as a failure against the integration's request-exception budget only when EVERY slot rejected,
 	* and not even then when a credential that checks out was refused by each target's own scope
 	* (`settleBatchRefusals`). Server errors and timeouts on the targets show one notice however many hit one, and
-	* cost a strike only as part of that whole-call failure (`reportDeferredRequestFailures`).
+	* cost a strike only as part of that whole-call failure (`reportDeferredRequestFailures`), so one call spends at
+	* most one. A batch read with etags makes up to two such calls (a full read of the targets without an etag, and a
+	* full read of the ones that changed), so it can spend two; its cheap check
+	* ({@link getPullRequestsEtagFieldsResult}) spends nothing unless the credential is refused.
 	*/
 	async getPullRequestsBatchResult(coordinates, options, cancellation, connectionId) {
 		const scope = getScopedLogger();
@@ -1272,6 +1305,84 @@ var GitHostIntegration = class extends IntegrationBase {
 		}
 	}
 	/**
+	* Result-returning wrapper for the cheap check behind the batch issue read's etags: each coordinate's change
+	* state ({@link IssueEtagFields}), plus the inputs of each of `options.etagIncludes`, in ONE call to
+	* {@link getProviderIssuesEtagFields}. The slots mean what
+	* {@link getIssuesBatchResult}'s do — `fulfilled` with `undefined` is a PROVEN ABSENCE, `rejected` means that
+	* target could not be checked.
+	*
+	* Unlike there, failures other than a refused credential are never the call's: every slot comes back as it
+	* settled, even when none answered, so each failed target is judged by its own reason. Such failures spend no
+	* strike and show no notice, since the targets they touch fall through to the full read, which does both if the
+	* host really is failing, or are dropped as rate-limited or without a connection. Refusals are settled as there
+	* (`settleBatchRefusals` with `keepOtherFailures`), and only a refused credential fails the call, on the auth path
+	* (`handleEtagCheckException`). The failure budget is reset only when some target answered.
+	*/
+	async getIssuesEtagFieldsResult(coordinates, options, cancellation, connectionId) {
+		const scope = getScopedLogger();
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return void 0;
+		const start = performance.now();
+		try {
+			const slots = await this.getProviderIssuesEtagFields?.(session, coordinates, options, cancellation);
+			if (slots == null) return {
+				value: void 0,
+				duration: performance.now() - start
+			};
+			const settled = await this.settleBatchRefusals(session, coordinates, slots, { keepOtherFailures: true });
+			if (slots.some((slot) => slot.status === "fulfilled")) this.resetRequestExceptionCount("getIssuesEtagFields");
+			return {
+				value: settled,
+				duration: performance.now() - start
+			};
+		} catch (ex) {
+			this.handleEtagCheckException("getIssuesEtagFields", ex, {
+				scope,
+				connectionId
+			});
+			return {
+				error: toError(ex),
+				duration: performance.now() - start
+			};
+		}
+	}
+	/**
+	* Result-returning wrapper for the cheap check behind the batch pull request read's etags: each coordinate's
+	* change state ({@link PullRequestEtagFields}), plus the inputs of each of `options.etagIncludes`, in ONE call to
+	* {@link getProviderPullRequestsEtagFields}. The slots mean what {@link getPullRequestsBatchResult}'s do —
+	* `fulfilled` with `undefined` is a PROVEN ABSENCE, `rejected` means that target could not be checked. Failures
+	* are judged and budgeted as in {@link getIssuesEtagFieldsResult}: only a refused credential fails the call or
+	* spends a strike.
+	*/
+	async getPullRequestsEtagFieldsResult(coordinates, options, cancellation, connectionId) {
+		const scope = getScopedLogger();
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return void 0;
+		const start = performance.now();
+		try {
+			const slots = await this.getProviderPullRequestsEtagFields?.(session, coordinates, options, cancellation);
+			if (slots == null) return {
+				value: void 0,
+				duration: performance.now() - start
+			};
+			const settled = await this.settleBatchRefusals(session, coordinates, slots, { keepOtherFailures: true });
+			if (slots.some((slot) => slot.status === "fulfilled")) this.resetRequestExceptionCount("getPullRequestsEtagFields");
+			return {
+				value: settled,
+				duration: performance.now() - start
+			};
+		} catch (ex) {
+			this.handleEtagCheckException("getPullRequestsEtagFields", ex, {
+				scope,
+				connectionId
+			});
+			return {
+				error: toError(ex),
+				duration: performance.now() - start
+			};
+		}
+	}
+	/**
 	* Result-returning wrapper for the pull-requests-by-branch read: for each target, every pull request whose head
 	* is that branch, in any state, in ONE call to {@link getProviderPullRequestsForBranches}. One settled slot
 	* per target: `fulfilled` with an empty list means the host answered and nothing matched; `rejected` means