@gitkraken/core-gitlens 0.9.3 → 0.9.5

package/docs/integrations.md

@@ -135,8 +135,8 @@ it with `page` + `hasMore` + `cursor?`. **No read throws for a provider-side fai
 | `getCurrentAccount`          | `CurrentAccountResult`    | Who a git host connection is signed in as; trackers refuse.                                  |
 | `getSupportedFilters`        | filter capability table   | Static, connection-free. See §7.                                                             |
 
-A provider that cannot serve a surface says so explicitly — a warning explaining that the operation is
-unsupported plus `fetchFailed`, never a silent empty page. That distinction is the whole point of the result
+A provider that cannot serve a surface says so explicitly — a `kind: 'unsupported'` warning (§6) plus
+`fetchFailed`, never a silent empty page. That distinction is the whole point of the result
 shape: an empty `items` with no warning means "this account genuinely has nothing".
 
 `getIssuesBatch` takes the target form its provider addresses an issue by: `{ key, owner, repo, number, project? }` on
@@ -170,20 +170,93 @@ and it serves every git host. Azure DevOps also requires `project` on each targe
 targets per request; every other host costs one request per target, and GitLab a second one to confirm a miss. A
 target GitHub refuses on its own, e.g. in an org enforcing SAML SSO the token isn't authorized for, fails only that
 target. Its rows carry the same fields as the list reads' rows, except on Bitbucket Cloud — which has no single pull
-request read in provider-apis, so those rows come from GitLens' own REST read and lack `commentsCount`, `isDraft`
-and the clone URLs. On GitLab, a miss the confirming read then contradicts fails the target rather than answering
+request read in provider-apis, so those rows come from GitLens' own REST read and lack `commentsCount` and the clone
+URLs. On GitLab, a miss the confirming read then contradicts fails the target rather than answering
 with the confirming read's own, differently-identified row. It is uncached and bypasses the
 host's `IntegrationCacheProvider.getPullRequest`, so the caller owns caching the answer.
 
+Both batch reads detect change with **etags**. Every fully read row carries an opaque `etag`, whether or not the
+caller sent one; send it back as the target's `etag` on the next call. Compare etags for equality only and never
+parse one: core computes it from the item's change state — a pull request's state, draft flag, update time and head
+commit (plus, on Azure DevOps, a fingerprint of the fields it changes without an update time; see below); an issue's
+state and update time — and it is not the provider's HTTP ETag. A field the host changes without moving the update
+time is not an input unless `etagIncludes` names it. Reactions are such a field: GitHub adds a reaction without
+touching the update time, so an `unchanged` issue's `thumbsUpCount` can be stale unless the call listed `'reactions'`,
+and an `unchanged` pull request's always can. A row is in one of four states:
+
+- `{ key, pullRequest | issue, etag }` — read in full.
+- `{ key, unchanged: true, etag }` — a cheap check proved the caller's copy current and nothing else was fetched.
+  Only for a target that sent an `etag`, on a host with a cheap check.
+- `{ key }` — proven absent, as before.
+- no row, with `fetchFailed` and a warning — unknown, as before.
+
+The hosts with a cheap check select only the change state:
+
+- **GitHub/GHE:** one aliased document per 25 targets, like the full read.
+- **GitLab and GitLab self-managed:** one query per project per 100 iids. That drops to 10 iids when `etagIncludes`
+  has `'checks'`, because GitLab resolves every job of each head pipeline for that input. GitLab resets a merge
+  request's merge status whenever its target branch moves, so on a busy repository `'mergeable'` changes, and costs a
+  full read, more often than the merge request itself does.
+
+- **Azure DevOps and Azure DevOps Server:** work items in one batch request per project per 200 ids; an id the batch
+  leaves out falls through to its own full read. Pull requests can't be batched by id, so the check is one request
+  per pull request instead of the full read's two. Azure DevOps keeps no update time on a pull request, so its etag
+  also carries a revision: a 64-bit hash of the title, description, target branch and every reviewer with their vote,
+  read off the same response at no extra cost. It sees state, draft, closing, new pushes and those edits, including
+  a reviewer added or removed and an optional reviewer's vote (plus mergeability when included). It can't see a
+  comment or a label, which its full row doesn't carry either, or a vote that keeps the reviewer's state, such as an
+  approval becoming an approval with suggestions. A hash collision is the only way an edit it does see can hide,
+  at about 2^-64. An Azure DevOps pull request etag from before the revision existed compares unequal once and costs
+  one full read.
+- **Bitbucket Cloud:** one list request per repository per 50 pull requests, by id and in every state, where the
+  full read sends one request per pull request. A pull request missing from the list is proven absent, as the full
+  read's 404 would prove it. Bitbucket Cloud's rows carry no mergeability or check rollup, so its etag
+  sees state, draft, update time and head commit, plus the participants' review decision when `'reviewDecision'` is
+  included; `'mergeable'` and `'checks'` add nothing and cost nothing.
+- **Jira Cloud** (the tracker form of `getIssuesBatch`): one bulk fetch per site per 100 keys. Bulk fetch silently
+  leaves out a key it can't answer (deleted, not visible, malformed or moved), so such a key falls through to its own
+  full read, whose 404 is what proves an absence.
+- **Linear** (the tracker form of `getIssuesBatch`): one query per team per 50 issues, archived ones included, where
+  the full read sends one request per issue. The query matches the team's current key, while the full read may also
+  resolve an identifier the issue no longer carries (its team was renamed, or it moved), so an issue the query leaves
+  out, or an identifier that isn't a team key and a number, falls through to its own full read, which decides whether
+  it is absent.
+
+Every other host and tracker accepts the `etag`, reads the target in full, and etags the row. On a host with a cheap check, a call is up to three integration calls: the cheap check
+of the targets that sent an `etag`, a full read of the rest started alongside it, and a full read of the targets
+whose etag no longer matched once the check settles. A call in which no target sends an `etag` makes exactly the one
+full read it always made. `getPullRequestsBatch` also takes `etagIncludes`, a list drawn from `'mergeable'`,
+`'reviewDecision'` and `'checks'` (the check rollup). Each entry widens every etag to one input GitHub changes without
+moving the update time — without `'checks'` a red CI run goes unnoticed — and costs its own fields in the cheap
+check, so a caller lists only what it needs; on GitHub the review decision is the costliest
+(GitHub computes it per pull request), the rollup next, mergeability cheapest. `getIssuesBatch` takes `etagIncludes`
+too, drawn from `'reactions'`: the thumbs-up count, which costs one field in the cheap check on GitHub/GHE (the full
+read's own `reactions(content: THUMBS_UP)` selection) and GitLab (`upvotes`). Azure DevOps work items, Jira and Linear
+rows carry no real reaction count, so there it widens nothing and costs nothing. Order and repeats don't matter (core sorts and dedupes the list), and an unknown value refuses the whole
+call before any request, like a bad target. It changes only which etag is computed (and the cheap check's
+selection), and an etag from another set, or from an older scheme, simply compares unequal and costs a full read,
+never a false `unchanged`. A target the cheap check fails falls through to the full read, which has the final word and supplies
+the warning if it fails too — except on an `auth`, `rate-limit` or `no-connection` failure, which the full read
+would only hit again: those targets are dropped with that warning and `fetchFailed`, exactly as a failed full read
+drops them. Each target is judged by its own failure, so one target's rate limit never drops another the check only
+failed to answer. The cheap check counts toward the integration's disconnect budget only when the credential is
+refused; any other failure of it is left to the full reads, so a call counts at most twice, once per full read.
+
 `getPullRequestsForBranches` answers "which pull requests have this branch as their head" without the user's
 relationship to them, so unlike the sweeps it finds a teammate's pull request from the user's branch. A target names
 the repository the pull requests are opened against, the branch's short name and, for a branch in a fork,
 `headOwner`; one equal to the target's owner means the base repository. A pull request matches only when its head
 repository is that base repository or that fork, so a `main` never claims every fork's `main`. The match is on the
-head branch name in every state, so a merged pull request whose branch was deleted is still found. Each target
-returns up to 10, most recently updated first. An empty list without `truncated` is a proven none, a missing base
-repository included; `truncated` means more may match than were returned. GitHub/GHE answer up to 25 targets per
-request, and every other host costs one request per target. GitLab and Azure DevOps, where that request only finds
+head branch name in every state, so a merged pull request whose branch was deleted is still found, and a fork is
+matched by its owner, so a pull request whose fork was deleted still matches that `headOwner`. Each target returns up
+to 10, most recently updated first. An empty list without `truncated` is a proven none, a missing base repository included; `truncated` means a
+pull request that wasn't returned could still match. GitHub/GHE answer up to 25 targets per request, matching the
+branch name across every fork. A target whose name more forks share than that request returned (`main` or `patch-1`
+in a fork-heavy repository) costs one more REST request, which filters by head owner on the server; a match the first
+request missed is resolved through `getPullRequestsBatch`'s own read, the answer is the union of both requests'
+matches, and the target is `truncated` only when more than 10 truly match. The REST request can't see a pull request
+from a deleted fork, so on such a target one that the first request didn't return can't be found, and may be missing
+from an answer, even an empty one, that isn't `truncated`. Every other host costs one request per target. GitLab and Azure DevOps, where that request only finds
 the matching numbers, then resolve each match (typically 0–1 per branch) through `getPullRequestsBatch`'s own read,
 so their rows are exactly its rows; a match that read can't check fails its whole branch. Rows carry the list reads'
 fields on GitHub/GHE and Bitbucket DC and the by-id read's on Bitbucket Cloud. Bitbucket DC and Azure DevOps refuse a
@@ -195,6 +268,268 @@ than `items`, and `account` is never absent without a warning: no session, a fai
 which has only a per-resource account and refuses (see §8). It goes through the host-supplied
 `IntegrationManagerCacheProvider.getCurrentAccount` cache rather than adding a second one.
 
+That account is not always how a pull request names the same person. Azure DevOps Server gives one person a
+different identity id in each collection than at the server level, and a pull request's `author`, `reviewRequests`
+and `latestReviews` carry the collection's. So the pull request reads resolve the current account per row, and every
+row whose `authoredByMe` was resolved also carries `viewer`, the identity it was matched against: per collection on
+Azure DevOps Server, the account itself everywhere else. To tell whether a review was requested from the current
+user, or which review is theirs, compare the reviewer entries against `viewer`, not against `getCurrentAccount`. A row
+whose identity couldn't be resolved has neither field, and its authorship is unknown rather than `false`.
+
+### Field presence
+
+Every pull request and issue row carries `projection`, naming the read that produced it: `point` (a single-item
+read), `search` and `search-summary` (the filtered search, and on the host its "my pull requests" and issue searches),
+`text-search` (the host's free-text `searchPullRequests`), `account` and `account-summary` (the account-wide list and
+sweeps, `account` being a sweep's `includeReviews`, and a tracker's "my issues"), `repos` and `repos-summary` (the
+repository-scoped list and sweeps), `project` (a tracker project's issues: `listIssueTrackerIssuesPage`,
+`getIssuesForProject`), and `batch` (`getPullRequestsBatch`, `getPullRequestsForBranches`, `getIssuesBatch`). Issues
+have no `-summary` reads; `broadenIssues` rows carry the tag of the read that served each org. The tag names a read,
+not a field set: the same tag can carry different fields on different providers.
+
+Which fields a row carries depends on that read. A field it never fetched is `undefined`, but so is a fetched field that
+is empty, and provider-apis' converters still fill a few placeholders (see
+[Every other provider](#every-other-provider)), so neither a missing nor a present value says what the read fetched.
+`getPullRequestFieldPresence(row)` and `getIssueFieldPresence(row)` answer it per field group:
+
+- `fetched` — the read asked for it and surfaces it, so an empty value means "none".
+- `not-requested` — this read didn't ask for it, or doesn't surface it faithfully. **Ignore the value even when one is
+  present**; another read may supply it. When merging rows from several reads, take each group from a row that
+  fetched it.
+- `unavailable` — this host can't supply it on this read.
+
+Both return `undefined` for an untagged row, and for a tag the row's provider never produces. The serialized copies
+(`serializePullRequest`, `serializeIssue`) drop fields a table can call fetched, so they carry no tag.
+
+A group is `fetched` only if every field in it is. Pull request groups: `description` (`body`), `reviews`
+(`latestReviews`), `reviewRequests` (who is requested; each request's `isCodeOwner` is set only by GitLens' own GitHub
+reads, and is `undefined` elsewhere), `reviewDecision`, `assignees`, `checks` (`statusCheckRollupState`), `mergeable`
+(`mergeableState`), `diffStats` (`additions`, `deletions`, `filesChanged`), `commitCount`, `comments` (`commentsCount`),
+`reactions` (`thumbsUpCount`), `access` (`viewerCanUpdate` and `repository.accessLevel`), `authoredByMe` (with `viewer`,
+the identity it was matched against) and `stack`. `statusCheckRollupState`, `commitCount` and `viewerCanUpdate` live on
+the `PullRequest` class every row is, not on the `PullRequestShape` type. Issue groups: `description` (`body`),
+`assignees`, `labels`, `comments` (`commentsCount`), `reactions` (`thumbsUpCount`) and `access`
+(`repository.accessLevel`).
+
+Each table below covers a cloud host and its self-managed variant: where a cell reads `cloud / self-managed` the two
+differ, and `—` means that host never produces the tag.
+
+#### GitHub and GitHub Enterprise
+
+<!-- field-presence: pull-requests -->
+
+| Group          | point                 | search                | search-summary        | text-search           | account               | account-summary       | repos                   | repos-summary | batch                 |
+| -------------- | --------------------- | --------------------- | --------------------- | --------------------- | --------------------- | --------------------- | ----------------------- | ------------- | --------------------- |
+| description    | fetched               | fetched               | fetched               | fetched               | fetched               | fetched               | fetched                 | fetched       | fetched               |
+| reviews        | not-requested         | fetched               | not-requested         | fetched               | fetched               | not-requested         | not-requested           | not-requested | fetched               |
+| reviewRequests | not-requested         | fetched               | not-requested         | fetched               | fetched               | not-requested         | not-requested           | not-requested | fetched               |
+| reviewDecision | not-requested         | fetched               | not-requested         | fetched               | fetched               | not-requested         | not-requested           | not-requested | fetched               |
+| assignees      | not-requested         | fetched               | not-requested         | fetched               | fetched               | not-requested         | fetched                 | fetched       | fetched               |
+| checks         | not-requested         | fetched               | not-requested         | fetched               | fetched               | not-requested         | fetched / not-requested | not-requested | fetched               |
+| mergeable      | not-requested         | fetched               | not-requested         | fetched               | fetched               | not-requested         | fetched                 | fetched       | fetched               |
+| diffStats      | not-requested         | fetched               | not-requested         | fetched               | fetched               | not-requested         | fetched                 | fetched       | fetched               |
+| commitCount    | not-requested         | fetched               | not-requested         | fetched               | fetched               | not-requested         | fetched                 | not-requested | fetched               |
+| comments       | not-requested         | fetched               | not-requested         | fetched               | fetched               | not-requested         | fetched                 | fetched       | fetched               |
+| reactions      | not-requested         | not-requested         | not-requested         | not-requested         | not-requested         | not-requested         | fetched                 | fetched       | not-requested         |
+| access         | not-requested         | fetched               | not-requested         | fetched               | fetched               | not-requested         | not-requested           | not-requested | fetched               |
+| authoredByMe   | not-requested         | not-requested         | not-requested         | not-requested         | not-requested         | not-requested         | not-requested           | not-requested | not-requested         |
+| stack          | fetched / unavailable | fetched / unavailable | fetched / unavailable | fetched / unavailable | fetched / unavailable | fetched / unavailable | not-requested           | not-requested | fetched / unavailable |
+
+<!-- field-presence: issues -->
+
+| Group       | point   | search  | account | repos         | batch   |
+| ----------- | ------- | ------- | ------- | ------------- | ------- |
+| description | fetched | fetched | fetched | not-requested | fetched |
+| assignees   | fetched | fetched | fetched | fetched       | fetched |
+| labels      | fetched | fetched | fetched | fetched       | fetched |
+| comments    | fetched | fetched | fetched | fetched       | fetched |
+| reactions   | fetched | fetched | fetched | fetched       | fetched |
+| access      | fetched | fetched | fetched | not-requested | fetched |
+
+The cells that aren't obvious from the projection names:
+
+- `account`, `account-summary` and `batch` rows are GitLens' own, the same rows `search` and `search-summary` return,
+  so they read like them. That includes `reviewDecision`: where GitHub reports none (the repository requires no
+  review), the row has none either, even while a review is requested.
+- `repos` rows come from provider-apis, which drops dismissed reviews and code-owner review requests, derives the
+  review decision from what is left, and doesn't read `repository.accessLevel`. It does select reactions, which
+  GitLens' own reads don't. Its comment count is issue comments only, where `search` counts review
+  comments too. On GitHub Enterprise it reads check runs only from server 3.0 on, which the table can't see.
+- `authoredByMe` needs the current account, which a read may fail to resolve, so it is never `fetched`.
+- `stack` is selected only against github.com.
+
+#### Every other provider
+
+What holds for all of them:
+
+- **`summary` and `includeReviews` change nothing.** Only GitHub's reads have a lighter projection, so every other
+  provider answers a `-summary` read, or an account-wide sweep without `includeReviews`, with the same fields as the
+  full one. The rows still carry the tag of the read that was asked for, and the two tags have the same cells.
+- **`reviewDecision` is never `fetched`.** Only GitHub reports a review decision. Elsewhere the row's decision is
+  derived from its reviewers' states, which ignores the host's own approval rules (GitLab's approval rules, Azure
+  DevOps' branch policies, Bitbucket's merge checks), so derive one from `reviews` and `reviewRequests` instead.
+- **`access` and `authoredByMe` are never `fetched`**: no other host's read sets `repository.accessLevel`, and the
+  current account may not resolve. No other host has stacks.
+- **Substitutions.** Azure DevOps has no pull request assignees: both of its converters fill `assignees` with the
+  reviewers, which `reviews` and `reviewRequests` already hold, so `assignees` is `unavailable` there. Votes are not
+  reactions: a Jira issue's or Trello card's votes, and a Bitbucket issue's, land in `thumbsUpCount` (and read 0
+  where voting is off), so `reactions` is `unavailable` for them. A GitLab upvote is a thumbs-up award, so it counts.
+- **Placeholders.** GitLens' own reads leave a field they didn't fetch `undefined`, but provider-apis' converters,
+  which GitLens doesn't own, still fill some: Bitbucket's and Bitbucket Data Center's `mergeableState` is a literal
+  Mergeable, GitLab turns a null count into 0, Linear's `labels` is an empty list, and an Azure DevOps work item's
+  `thumbsUpCount` is 0 (GitLens' own batch read of one leaves it `undefined`). Each is `not-requested` or
+  `unavailable` in the tables.
+
+<!-- field-presence: gitlab-pull-requests -->
+
+| Group          | point         | search                  | text-search   | account                 | account-summary         | repos                   | repos-summary           | batch                   |
+| -------------- | ------------- | ----------------------- | ------------- | ----------------------- | ----------------------- | ----------------------- | ----------------------- | ----------------------- |
+| description    | not-requested | fetched                 | not-requested | fetched                 | fetched                 | fetched                 | fetched                 | fetched                 |
+| reviews        | not-requested | fetched                 | not-requested | fetched                 | fetched                 | fetched                 | fetched                 | fetched                 |
+| reviewRequests | not-requested | fetched                 | not-requested | fetched                 | fetched                 | fetched                 | fetched                 | fetched                 |
+| reviewDecision | not-requested | not-requested           | not-requested | not-requested           | not-requested           | not-requested           | not-requested           | not-requested           |
+| assignees      | not-requested | fetched                 | not-requested | fetched                 | fetched                 | fetched                 | fetched                 | fetched                 |
+| checks         | not-requested | fetched                 | not-requested | fetched                 | fetched                 | fetched                 | fetched                 | fetched                 |
+| mergeable      | not-requested | fetched                 | not-requested | fetched                 | fetched                 | fetched                 | fetched                 | fetched                 |
+| diffStats      | not-requested | not-requested           | not-requested | not-requested           | not-requested           | not-requested           | not-requested           | not-requested           |
+| commitCount    | not-requested | not-requested           | not-requested | not-requested           | not-requested           | not-requested           | not-requested           | not-requested           |
+| comments       | not-requested | fetched / not-requested | not-requested | fetched / not-requested | fetched / not-requested | fetched / not-requested | fetched / not-requested | fetched / not-requested |
+| reactions      | not-requested | fetched                 | not-requested | fetched                 | fetched                 | fetched                 | fetched                 | fetched                 |
+| access         | not-requested | not-requested           | not-requested | not-requested           | not-requested           | not-requested           | not-requested           | not-requested           |
+| authoredByMe   | not-requested | not-requested           | not-requested | not-requested           | not-requested           | not-requested           | not-requested           | not-requested           |
+| stack          | unavailable   | unavailable             | unavailable   | unavailable             | unavailable             | unavailable             | unavailable             | unavailable             |
+
+<!-- field-presence: gitlab-issues -->
+
+| Group       | point                   | account       | repos                   | batch                   |
+| ----------- | ----------------------- | ------------- | ----------------------- | ----------------------- |
+| description | fetched                 | fetched       | fetched                 | fetched                 |
+| assignees   | fetched                 | fetched       | fetched                 | fetched                 |
+| labels      | fetched                 | fetched       | fetched                 | fetched                 |
+| comments    | fetched / not-requested | fetched       | fetched / not-requested | fetched / not-requested |
+| reactions   | fetched                 | fetched       | fetched                 | fetched                 |
+| access      | not-requested           | not-requested | not-requested           | not-requested           |
+
+- The point reads and the free-text search are GitLens' own, and leave everything but the merge request's identity,
+  refs and dates off the row, including the description they select. Every other read is provider-apis'.
+- provider-apis turns a null count into 0. GitLab's schema makes the diff stats, the commit count and the comment
+  count nullable, so diff stats and commit counts are never `fetched`. GitLab.com's comment count resolver answers 0
+  rather than null, so its comment count is; a self-managed version's isn't known to. The account-wide issue read is
+  REST, whose comment count is always a number.
+
+<!-- field-presence: azure-pull-requests -->
+
+| Group          | point         | search        | search-summary    | text-search   | account       | account-summary | repos         | repos-summary | batch         |
+| -------------- | ------------- | ------------- | ----------------- | ------------- | ------------- | --------------- | ------------- | ------------- | ------------- |
+| description    | not-requested | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | fetched       |
+| reviews        | fetched       | fetched       | — / fetched       | fetched       | fetched       | fetched         | fetched       | fetched       | fetched       |
+| reviewRequests | fetched       | fetched       | — / fetched       | fetched       | fetched       | fetched         | fetched       | fetched       | fetched       |
+| reviewDecision | not-requested | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested |
+| assignees      | unavailable   | unavailable   | — / unavailable   | unavailable   | unavailable   | unavailable     | unavailable   | unavailable   | unavailable   |
+| checks         | not-requested | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested |
+| mergeable      | fetched       | fetched       | — / fetched       | fetched       | fetched       | fetched         | fetched       | fetched       | fetched       |
+| diffStats      | not-requested | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested |
+| commitCount    | not-requested | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested |
+| comments       | not-requested | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested |
+| reactions      | unavailable   | unavailable   | — / unavailable   | unavailable   | unavailable   | unavailable     | unavailable   | unavailable   | unavailable   |
+| access         | not-requested | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested |
+| authoredByMe   | not-requested | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested |
+| stack          | unavailable   | unavailable   | — / unavailable   | unavailable   | unavailable   | unavailable     | unavailable   | unavailable   | unavailable   |
+
+<!-- field-presence: azure-issues -->
+
+| Group       | point         | search            | account     | repos       | batch       |
+| ----------- | ------------- | ----------------- | ----------- | ----------- | ----------- |
+| description | fetched       | — / fetched       | fetched     | fetched     | fetched     |
+| assignees   | fetched       | — / fetched       | fetched     | fetched     | fetched     |
+| labels      | not-requested | — / not-requested | fetched     | fetched     | fetched     |
+| comments    | fetched       | — / fetched       | fetched     | fetched     | fetched     |
+| reactions   | unavailable   | — / unavailable   | unavailable | unavailable | unavailable |
+| access      | unavailable   | — / unavailable   | unavailable | unavailable | unavailable |
+
+- Azure truncates the description of a pull request it lists (to 400 characters), so only the batch reads, which
+  fetch each pull request by id, have it. GitLens' own point reads leave it off the row.
+- The point read and Azure DevOps Server's work item search use GitLens' own converter, which drops the tags.
+- Work items belong to a project, not a repository, so `access` is `unavailable`.
+
+<!-- field-presence: bitbucket-pull-requests -->
+
+| Group          | point                   | search        | search-summary    | text-search   | account       | account-summary | repos         | repos-summary | batch                   |
+| -------------- | ----------------------- | ------------- | ----------------- | ------------- | ------------- | --------------- | ------------- | ------------- | ----------------------- |
+| description    | fetched                 | fetched       | — / fetched       | fetched       | fetched       | fetched         | fetched       | fetched       | fetched                 |
+| reviews        | not-requested / fetched | fetched       | — / fetched       | fetched       | fetched       | fetched         | fetched       | fetched       | fetched                 |
+| reviewRequests | not-requested / fetched | fetched       | — / fetched       | fetched       | fetched       | fetched         | fetched       | fetched       | fetched                 |
+| reviewDecision | not-requested           | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested           |
+| assignees      | unavailable             | unavailable   | — / unavailable   | unavailable   | unavailable   | unavailable     | unavailable   | unavailable   | unavailable             |
+| checks         | not-requested           | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested           |
+| mergeable      | not-requested           | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested           |
+| diffStats      | not-requested           | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested           |
+| commitCount    | not-requested           | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested           |
+| comments       | not-requested / fetched | fetched       | — / fetched       | fetched       | fetched       | fetched         | fetched       | fetched       | not-requested / fetched |
+| reactions      | unavailable             | unavailable   | — / unavailable   | unavailable   | unavailable   | unavailable     | unavailable   | unavailable   | unavailable             |
+| access         | not-requested           | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested           |
+| authoredByMe   | not-requested           | not-requested | — / not-requested | not-requested | not-requested | not-requested   | not-requested | not-requested | not-requested           |
+| stack          | unavailable             | unavailable   | — / unavailable   | unavailable   | unavailable   | unavailable     | unavailable   | unavailable   | unavailable             |
+
+<!-- field-presence: bitbucket-issues -->
+
+| Group       | point         | account       |
+| ----------- | ------------- | ------------- |
+| description | fetched       | fetched       |
+| assignees   | fetched       | fetched       |
+| labels      | unavailable   | unavailable   |
+| comments    | not-requested | not-requested |
+| reactions   | unavailable   | unavailable   |
+| access      | not-requested | not-requested |
+
+- Bitbucket Cloud's point and batch reads are GitLens' own, which drop the comment count. The point read for a commit
+  selects `+values.*`, which isn't known to bring the participants the reviews come from as the other point reads'
+  selections do, so the point reads don't promise them.
+- Bitbucket Cloud's issues are its deprecated tracker, which the facade refuses; only the host's own `getIssue` and
+  `searchMyIssues` read them. Bitbucket Data Center has no issues.
+- Bitbucket Data Center reports a pull request's comment count in its `properties`; a pull request without one there
+  reads as having none.
+
+<!-- field-presence: jira-issues -->
+
+| Group       | point         | account       | project       | batch                   |
+| ----------- | ------------- | ------------- | ------------- | ----------------------- |
+| description | fetched       | fetched       | fetched       | fetched                 |
+| assignees   | fetched       | fetched       | fetched       | fetched                 |
+| labels      | fetched       | fetched       | fetched       | fetched                 |
+| comments    | not-requested | not-requested | not-requested | fetched / not-requested |
+| reactions   | unavailable   | unavailable   | unavailable   | unavailable             |
+| access      | unavailable   | unavailable   | unavailable   | unavailable             |
+
+<!-- field-presence: linear-issues -->
+
+| Group       | point         | account       | project       | batch         |
+| ----------- | ------------- | ------------- | ------------- | ------------- |
+| description | fetched       | fetched       | fetched       | fetched       |
+| assignees   | fetched       | fetched       | fetched       | fetched       |
+| labels      | not-requested | not-requested | not-requested | not-requested |
+| comments    | not-requested | not-requested | not-requested | not-requested |
+| reactions   | not-requested | not-requested | not-requested | not-requested |
+| access      | unavailable   | unavailable   | unavailable   | unavailable   |
+
+<!-- field-presence: trello-issues -->
+
+| Group       | point         | project       |
+| ----------- | ------------- | ------------- |
+| description | not-requested | not-requested |
+| assignees   | fetched       | fetched       |
+| labels      | fetched       | fetched       |
+| comments    | fetched       | fetched       |
+| reactions   | unavailable   | unavailable   |
+| access      | unavailable   | unavailable   |
+
+- Tracker issues belong to no repository, so `access` is `unavailable`.
+- provider-apis' Jira converter counts the comments embedded in the issue rather than reading their total, so only
+  Jira Cloud's batch read, which is GitLens' own by-key read, has a comment count. Jira Data Center's batch read goes
+  through provider-apis.
+- provider-apis' Linear fragment selects no labels (it fills an empty list), comments or reactions.
+- A Trello card's description is never read. Trello has no batch or account-wide read.
+
 ## 5. Paging
 
 Two mechanisms live behind one shape, and they are **not** interchangeable:
@@ -404,13 +739,14 @@ result** instead of rejecting the call. One provider's expired token never blank
 `ProviderWarning.kind` (also exported as `ProviderWarningKind`) carries the classifications the facade can
 prove from structured errors:
 
-| `kind`          | Meaning                                                                                                                                         | Reasonable response                                                                         |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `auth`          | Token rejected (401/403 that isn't a throttle).                                                                                                 | Prompt to reconnect that connection. A scoped one is narrower: see `scope` below.           |
-| `rate-limit`    | Throttled (429, or a 403 whose body says so).                                                                                                   | Back off and retry; keep the last snapshot.                                                 |
-| `not-found`     | 404/410/422 on the requested scope.                                                                                                             | Drop that scope; don't reconnect.                                                           |
-| `no-connection` | The requested `connectionId`/`domain` doesn't resolve.                                                                                          | Re-resolve the target or re-authenticate.                                                   |
-| `other`         | Catch-all: unsupported input, truncation, upstream/network failure, or an unclassified error. Read `omission` before treating one as a failure. | Preserve the warning and use the result flags; do not assume it is benign or non-retryable. |
+| `kind`          | Meaning                                                                                                                                                        | Reasonable response                                                                         |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `auth`          | Token rejected (401/403 that isn't a throttle).                                                                                                                | Prompt to reconnect that connection. A scoped one is narrower: see `scope` below.           |
+| `rate-limit`    | Throttled (429, or a 403 whose body says so).                                                                                                                  | Back off and retry; keep the last snapshot.                                                 |
+| `not-found`     | 404/410/422 on the requested scope.                                                                                                                            | Drop that scope; don't reconnect.                                                           |
+| `no-connection` | The requested `connectionId`/`domain` doesn't resolve.                                                                                                         | Re-resolve the target or re-authenticate.                                                   |
+| `unsupported`   | The provider can't serve this capability: a surface, filter, sort, state, search criterion or option combination it can't express.                             | Hide or disable the feature for that provider; don't retry or reconnect.                    |
+| `other`         | Catch-all: malformed or contradictory input, truncation, upstream/network failure, or an unclassified error. Read `omission` before treating one as a failure. | Preserve the warning and use the result flags; do not assume it is benign or non-retryable. |
 
 `isAuth` is a convenience mirror of `kind === 'auth'`. **Collapsing `kind` into that boolean loses the
 rate-limit and not-found distinctions**, which then have to be re-derived from raw provider prose.
@@ -651,6 +987,10 @@ const filters = wanted.filter(f => capability.includes(f));
   can't name. Reported as per-criterion flags rather than a list, and **always present** — a provider with no
   filtered issue search reports empty `relationships` and all-false flags, which is the signal to hide the
   surface rather than individual chips.
+- `issueStates` — whether the issue-tracker reads take a `state` other than open (`'closed'`, `'all'`). True for
+  Jira, Jira Data Center and Linear, which narrow server-side on every page of their drains; false for Trello,
+  which can only read open cards and refuses the other two (warning + `fetchFailed`). An omitted `state` reads
+  open issues on every tracker.
 
 It's a _capability_ table, not a recommendation: passing fewer filters than listed is fine.
 
@@ -679,6 +1019,24 @@ second is a PR you have already reviewed (so it is waiting on the author). A "ne
 both, as separate reads. The review row itself rides along only where the full projection does — the
 filtered search, or a sweep with `includeReviews` — not from `Reviewed` on its own.
 
+On Azure DevOps (+ Server), `ReviewRequested` and `Assignee` also find open pull requests whose reviewer is a group the
+user is a member of: a team (which is how a branch policy usually requires a review), a security group such as
+`[project]\Contributors`, a group reached through another, or a group of another project. Azure's reviewer filter only
+matches the identity it names, so these reads ask once per organization (collection) for every group the user is in
+(`_apis/identities` with expanded membership, then `_apis/identitybatch` per 100 groups; this needs the Identity read
+scope, `vso.identity`, which the connection declares), keep that set for five minutes, and read each project's open
+pull requests once without a reviewer filter. A pull request is kept when it names the user, or names one of the user's
+groups and the user didn't write it: a group asked to review the user's own pull request isn't asking the user. A
+group's request carries `isMyGroup: true` on its `reviewRequests` (or `latestReviews`) entry, while a request to the
+user by name does not.
+
+Closed and merged pull requests are every pull request a project ever had, so they are still read through Azure's
+filter for the user: a group's request is only followed while the pull request is open. The cost of an open read is the
+same number of pull request requests as before (one read of each project's open pull requests in place of the filtered
+one), plus the group read when the kept set has expired. When the groups can't be read, the reads keep what names the
+user and report the organization (collection) as a scoped failure: the account-wide read with a warning and
+`fetchFailed`, the Server filtered search with a warning and `page.truncated`, and its count as uncounted.
+
 `includeReviewRequested` is a legacy account-wide breadth option used only when no explicit `filters` are
 supplied. It remains useful for Bitbucket Cloud, where the reviewer slice requires an expensive
 O(workspaces × repos) fan-out; prefer `filters: [ReviewRequested]` when an exact relationship is required.
@@ -703,8 +1061,9 @@ either way), so the option is purely projection plus its page cost. What it does
 count, since one document holds every facet: five relationships × four states is 20 full-projection selections.
 
 `listPullRequestsPage` has no projection switch. Scoped to `repos` it goes through the provider's repo-scoped
-read, and GitHub's carries `latestReviews` natively; account-wide (no `repos`) it is always the lite shape and
-no option opts it back in. `commitOid` is absent from both: only the full projection populates it.
+read, which on GitHub selects `latestReviews` but drops dismissed reviews (see [Field presence](#field-presence));
+account-wide (no `repos`) it is always the lite shape and no option opts it back in. `commitOid` is absent from
+both: only the full projection populates it.
 
 The paginated read that does carry the full projection is `searchPullRequestsPage` with
 `criteria.relationships` on GitHub/GHE (Bitbucket Data Center also exposes the search, with its native row shape):
@@ -717,7 +1076,8 @@ reach for `includeReviews`, which only exists on the all-at-once sweep.
 ## 8. Provider capability matrix
 
 Derived from the provider models and `providersMetadata`. ✓ supported · ✗ reported unsupported
-(warning + `fetchFailed`) · — not applicable. Self-managed variants inherit their cloud family's hooks.
+(warning + `fetchFailed`) · — not applicable. Self-managed variants inherit their cloud family's hooks unless a
+footnote says otherwise.
 
 | Surface                      | GitHub / GHE | GitLab / self-hosted | Bitbucket | Bitbucket DC | Azure DevOps (+ Server) | Jira (+ DC) | Linear | Trello |
 | ---------------------------- | :----------: | :------------------: | :-------: | :----------: | :---------------------: | :---------: | :----: | :----: |
@@ -728,12 +1088,12 @@ Derived from the provider models and `providersMetadata`. ✓ supported · ✗ r
 | PRs, repo-scoped             |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✗      |   ✗    |   ✗    |
 | PRs, account-wide            |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✗      |   ✗    |   ✗    |
 | PR `states` account-wide     |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      —      |   —    |   —    |
-| `searchPullRequestsPage`     |      ✓       |          ✗           |     ✗     |      ✓       |            ✗            |      ✗      |   ✗    |   ✗    |
-| `countPullRequests`          |      ✓       |          ✗           |     ✗     |      ✓       |            ✗            |      ✗      |   ✗    |   ✗    |
+| `searchPullRequestsPage`     |      ✓       |          ✗           |     ✗     |      ✓       |           ✗²            |      ✗      |   ✗    |   ✗    |
+| `countPullRequests`          |      ✓       |          ✗           |     ✗     |      ✓       |           ✗²            |      ✗      |   ✗    |   ✗    |
 | Issues, repo-scoped          |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |      —      |   —    |   —    |
 | Issues, account-wide         |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |      —      |   —    |   —    |
-| `searchIssuesPage`           |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |      ✗      |   ✗    |   ✗    |
-| `countIssues`                |      ✓       |          ✓           |     ✗     |      ✗       |            ✗            |      ✗      |   ✗    |   ✗    |
+| `searchIssuesPage`           |      ✓       |          ✗           |     ✗     |      ✗       |           ✗²            |      ✗      |   ✗    |   ✗    |
+| `countIssues`                |      ✓       |          ✗           |     ✗     |      ✗       |           ✗²            |      ✗      |   ✗    |   ✗    |
 | `getIssuesBatch`             |      ✓       |          ✓           |     ✗     |      ✗       |            ✓            |      ✓      |   ✓    |   ✗    |
 | `getPullRequestsBatch`       |      ✓       |          ✓           |     ✓     |      ✓       |            ✓            |      ✗      |   ✗    |   ✗    |
 | `getPullRequestsForBranches` |      ✓       |          ✓           |     ✓     |      ✓¹      |           ✓¹            |      ✗      |   ✗    |   ✗    |
@@ -763,6 +1123,8 @@ autolinks are registered for the same reason: an autolink prefix has to be the p
 finds a branch's pull requests only through the repository the branch lives in, and an Azure DevOps fork shares its
 organization.
 
+² Refused by Azure DevOps (cloud) only: Azure DevOps Server serves the filtered searches and their counts.
+
 Repo-scoped PR filters: GitHub/GHE `Author, Assignee, ReviewRequested, Mention` · GitLab `Author, Assignee,
 ReviewRequested` · Bitbucket + Bitbucket DC `Author, ReviewRequested` · Azure `Author, Assignee,
 ReviewRequested`.
@@ -870,6 +1232,10 @@ while GitHub, GitLab, and Linear descriptions are Markdown. Jira issues therefor
 `bodyFormat: 'jira-wiki'`; an omitted `bodyFormat` means consumers should preserve the existing behavior and treat
 `body` as Markdown. The `'markdown'` value is reserved for providers that need to make that format explicit.
 
+Two exceptions carry HTML with `bodyFormat` omitted: Azure DevOps work items (`System.Description`) and Bitbucket
+Cloud issues (`content.html`). Their `bodyFormat` is left unset rather than changed, so check the provider before
+treating either as Markdown.
+
 Rendering and conversion remain consumer concerns. In particular, the Jira body is neither ADF nor converted to
 Markdown by this package.
 
@@ -1025,7 +1391,7 @@ and Azure DevOps (+ Server). **Not** Bitbucket Data Center. A self-managed id re
 2. Pick an auth strategy (§2) and verify `getConfigured()` reflects your connections.
 3. Thread `connectionId` through every read if you support multiple accounts per provider.
 4. Persist the **opaque `cursor`**, not just a page number (§5).
-5. Branch on specific `warning.kind` values, handle `other` conservatively, and gate caching on
+5. Branch on specific `warning.kind` values (`unsupported` means hide the feature, not retry), handle `other` conservatively, and gate caching on
    `fetchFailed` / `page.allPages` (§6).
 6. Intersect repo-scoped and account-wide `filters` against their distinct `getSupportedFilters` fields (§7).
 7. Treat "unsupported" as a first-class outcome per provider (§8) — don't render it as an error.

package/docs/kepler-read-api-parity.md

@@ -232,12 +232,24 @@ provider-apis' GitLab read reports a reply that carries only GraphQL errors the
 request, so its `null` alone does not prove absence; an Azure DevOps miss is trusted only when Azure's own error
 body names the pull request, repository or project as not found, not on any other 404 or a 410. Rows take the
 list reads' conversion on every host but Bitbucket Cloud, which has no single pull request read in provider-apis
-and so answers from GitLens' own REST read instead, missing `commentsCount`, `isDraft` and the clone URLs. On
+and so answers from GitLens' own REST read instead, missing `commentsCount` and the clone URLs. On
 GitLab, a miss the confirming read then contradicts fails the target rather than answering with the confirming
 read's own, differently-identified row. The read is uncached and does not go through
 `IntegrationCacheProvider.getPullRequest`, whose key carries no connection, so the consumer's cache is the only
 one holding the answer.
 
+**Change detection.** Kepler refreshes the pull requests and issues on screen every few minutes, and most refreshes
+find nothing changed, yet each re-read the full GitHub projection (2.6–3.7 s for ~50 pull requests). Both batch
+reads now hand back an opaque `etag` on every fully read row; a target that sends it back is first checked
+cheaply, and comes back `{ key, unchanged: true, etag }` when it still matches, so only what moved is read in full.
+One call still answers everything — known and new targets mix freely — and core alone defines "changed". The cheap
+check exists on GitHub/GHE, GitLab, Azure DevOps (self-managed too for both), Bitbucket Cloud, Jira Cloud and Linear; every other host reads in full and etags the row. `etagIncludes` (any of
+`'mergeable'`, `'reviewDecision'`, `'checks'`) widens the etag to those inputs, which GitHub changes without moving
+`updatedAt`; each costs its own fields in the cheap check, the review decision most. A cheap
+check that fails never answers `unchanged`: it falls through to the full read, or, on an auth, rate-limit or
+connection failure, drops its targets as a failed read does. See
+[`integrations.md` §4](./integrations.md#4-the-reads).
+
 **Pull requests by branch.** `getPullRequestsForBranches` answers "which pull requests have this branch as their
 head, in this repository" with no relationship to the user. Before it, Kepler correlated a local branch by matching
 the account-wide sweep, which holds only pull requests the user authored, is assigned or reviews — so a teammate's
@@ -247,7 +259,9 @@ still found, and on the head repository, the base one or the `headOwner` fork, s
 fork never correlates; a `headOwner` equal to the owner means the base repository, so Kepler can pass the owner of
 the remote the branch was pushed to. Up to 10 per branch; an empty list without `truncated` is a proven none a
 consumer can cache, and a failed target is dropped with `fetchFailed`. GitHub/GHE answer up to 25 branches per
-request, and every other host costs one request per branch. GitLab and Azure DevOps resolve each match (typically
+request, plus one REST request for each branch whose name more forks share than that request returned, so a fork's
+`main` settles instead of reading `truncated` on every refresh. That REST request can't see a pull request from a
+deleted fork, so on such a branch one the first request didn't return can be missing from a proven none; every other host costs one request per branch. GitLab and Azure DevOps resolve each match (typically
 0–1 per branch) through `getPullRequestsBatch`'s own read, so a pull request's `url`, and so its identity, is the
 same whichever read found it. Bitbucket DC and Azure DevOps serve base-repository branches only and refuse a
 `headOwner` naming another owner.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gitkraken/core-gitlens",
   "description": "GitLens core — shared Git / AI / GitHub primitives for internal GitKraken consumption",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "license": "SEE LICENSE IN LICENSE",
   "author": {
     "name": "GitKraken",
@@ -239,7 +239,7 @@
     }
   },
   "dependencies": {
-    "@gitkraken/provider-apis": "0.60.0",
+    "@gitkraken/provider-apis": "0.61.0",
     "@octokit/graphql": "9.0.4",
     "@octokit/request": "10.0.14",
     "@octokit/request-error": "7.1.1",