@gitkraken/core-gitlens 0.5.113 → 0.5.115

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

@@ -0,0 +1,197 @@
+import type { IssueShape } from '../../../git/models/issue.js';
+import { chunk } from '../../../utils/array.js';
+import { mapBounded } from '../../../utils/promise.js';
+import type { IntegrationIds } from '../constants.js';
+import { providerFanOutConcurrency } from '../constants.js';
+import type { ProviderResult, ProviderWarning } from '../results.js';
+import { appendDedupedWarning } from '../results.js';
+import {
+	isGitHostIntegration,
+	isIssuesHostIntegrationId,
+	warnOnMissingSessionForDomain,
+} from '../utils/integration.utils.js';
+import type { ProviderReadContext } from './context.js';
+import { runCaptured } from './drains.js';
+import { gitHostOnlySurfaceWarning, issuesUnsupportedWarning, otherWarning } from './warnings.js';
+
+/**
+ * The BATCH issue read: resolve N `(owner, repo, number)` coordinates in one request.
+ *
+ * A sibling of the issue searches rather than a mode of one, because it answers a different question. A search
+ * asks "what matches"; this asks "does this exact issue exist", which is what a caller correlating a branch name
+ * to the issue it references is actually asking. Three consequences follow, and they are the reason this exists:
+ *
+ * - It resolves by EXACT NUMBER, so relevance never enters into it.
+ * - No result ceiling applies, so there is no partial window to reason about and no omission to report.
+ * - An absent slot is a PROVEN ABSENCE, not "not found within a page budget". That is the property that matters
+ *   most: a caller can CACHE a miss. Emulating this with a paged list cannot prove absence without walking the
+ *   whole scope, so a miss stays unproven and the walk repeats on every pass, forever.
+ *
+ * Modeled on `countIssues` for its shape — caller-owned `key` echoed back, per-target isolation, chunked into as
+ * few requests as possible — because both take a set of independent questions and answer them together.
+ */
+
+/** One issue to resolve, identified by coordinate and echoed back under the caller's own `key`. */
+export interface IssueBatchTarget {
+	/** Caller-owned identifier, echoed on the result so no positional matching is needed. Must be unique. */
+	key: string;
+	owner: string;
+	repo: string;
+	number: number;
+}
+
+/** The answer for one {@link IssueBatchTarget}. */
+export interface IssueBatchResult {
+	key: string;
+	/**
+	 * The resolved issue, or `undefined` when it PROVABLY does not exist (or is not visible to this connection).
+	 *
+	 * Absent is an answer here, unlike every paged read on this facade: a target whose chunk FAILED is not
+	 * returned at all and sets `fetchFailed`, so a caller can tell "proven absent" from "unknown" and cache the
+	 * first without ever caching the second.
+	 */
+	issue?: IssueShape;
+}
+
+/**
+ * How many coordinates go into one upstream request.
+ *
+ * Measured rather than inherited from `issueCountChunkSize`, since that one rests on a zero-node selection and
+ * this carries the full issue projection per alias. Against the live API on all-resolving coordinates: 10 took
+ * 875ms, 25 took 890ms — so up to 25 is effectively free — 50 took 1.3s, and 75 took 2.7s. No complexity refusal
+ * appeared up to 100.
+ *
+ * 25 is where latency is still flat, with room before it degrades. It also puts any realistic correlation batch
+ * in ONE request, which is the whole point of the read.
+ */
+const issueBatchChunkSize = 25;
+
+export async function getIssuesBatch(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		targets: readonly IssueBatchTarget[];
+		connectionId?: string;
+		/**
+		 * Explicit self-managed host domain. Used only when the requested connection has no configured domain;
+		 * it must come from the trusted authentication configuration, not repository or remote data.
+		 */
+		domain?: string;
+	},
+): Promise<ProviderResult<IssueBatchResult>> {
+	const refused = (warning: ProviderWarning): ProviderResult<IssueBatchResult> => ({
+		items: [],
+		warnings: [warning],
+		fetchFailed: true,
+	});
+
+	if (isIssuesHostIntegrationId(options.providerId)) {
+		return refused(
+			gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'Batch issue resolution'),
+		);
+	}
+
+	// Nothing was asked for, so nothing is missing: an empty success, not a refusal.
+	if (options.targets.length === 0) return { items: [], warnings: [] };
+
+	const duplicateKey = findDuplicateKey(options.targets);
+	if (duplicateKey != null) {
+		// Refuses the whole call rather than deduping: `key` exists so the caller can match results without
+		// positional bookkeeping, and two results under one key make that ambiguous for EVERY target, not just
+		// the repeated one.
+		return refused(
+			otherWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				`Duplicate issue batch target key '${duplicateKey}'; keys identify results, so each must be unique.`,
+			),
+		);
+	}
+
+	const integration = await ctx.getIntegrationForRead(options.providerId, options.connectionId, options.domain);
+	if (integration == null) {
+		// A supplied connection or domain that no longer resolves is a broken target, not an empty account.
+		const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId, options.domain);
+		return { items: [], warnings: early.warnings, fetchFailed: early.fetchFailed || undefined };
+	}
+	if (!isGitHostIntegration(integration)) {
+		return refused(
+			gitHostOnlySurfaceWarning(options.providerId, undefined, options.connectionId, 'Batch issue resolution'),
+		);
+	}
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId, options.domain);
+	const warnOnMissingSession = warnOnMissingSessionForDomain(options.providerId, options.domain);
+
+	if (!integration.supportsIssues) {
+		return refused(issuesUnsupportedWarning(options.providerId, domain, options.connectionId));
+	}
+
+	const warnings: ProviderWarning[] = [];
+	let fetchFailed = false;
+
+	// Chunks are independent requests over their own slice of targets — nothing in one reads what another
+	// produced, and `runCaptured` never throws — so they run concurrently, bounded like every other fan-out here.
+	// `mapBounded` returns in input order, so `items` stays in target order.
+	const batches = await mapBounded(
+		chunk([...options.targets], issueBatchChunkSize),
+		providerFanOutConcurrency,
+		batch =>
+			runCaptured(
+				options.providerId,
+				domain,
+				options.connectionId,
+				() =>
+					integration.getIssuesBatchResult(
+						batch.map(t => ({ owner: t.owner, repo: t.repo, number: t.number })),
+						undefined,
+						options.connectionId,
+					),
+				{ warnOnMissingSession: warnOnMissingSession },
+			).then(result => ({ batch: batch, ...result })),
+	);
+
+	const items: IssueBatchResult[] = [];
+	for (const { batch, value, warning } of batches) {
+		if (warning != null) {
+			appendDedupedWarning(warnings, warning);
+		}
+		if (value == null) {
+			// A provider that doesn't implement the batch hook answers `undefined` with no error. Either way this
+			// chunk contributes nothing while the chunks around it still do, so its targets are DROPPED rather
+			// than reported as absent — the difference between "unknown" and "proven absent" is the read's whole
+			// value, and a failure must never be cached as an answer.
+			if (warning == null) {
+				appendDedupedWarning(
+					warnings,
+					otherWarning(
+						options.providerId,
+						domain,
+						options.connectionId,
+						`Batch issue resolution is not supported by '${options.providerId}'; resolve issues individually instead.`,
+					),
+				);
+			}
+			fetchFailed = true;
+			continue;
+		}
+
+		for (let i = 0; i < batch.length; i++) {
+			const issue = value[i];
+			items.push({ key: batch[i].key, ...(issue != null ? { issue: issue } : {}) });
+		}
+	}
+
+	return { items: items, warnings: warnings, fetchFailed: fetchFailed || undefined };
+}
+
+function findDuplicateKey(targets: readonly { key: string }[]): string | undefined {
+	const seen = new Set<string>();
+	for (const target of targets) {
+		if (seen.has(target.key)) return target.key;
+
+		seen.add(target.key);
+	}
+	return undefined;
+}

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

@@ -2,7 +2,7 @@ import type { CollectionMetadata } from '@gitkraken/provider-apis';
 import type { IssueShape, IssueSorting } from '../../../git/models/issue.js';
 import type { ResourceDescriptor } from '../../../git/models/resourceDescriptor.js';
 import { mapBounded } from '../../../utils/promise.js';
-import { mergeAssessmentInto } from '../collectionMetadata.js';
+import { assessCollectionMetadata, mergeAssessmentInto } from '../collectionMetadata.js';
 import type { IntegrationIds } from '../constants.js';
 import { providerFanOutConcurrency } from '../constants.js';
 import { isIssuesIntegration } from '../models/issuesIntegration.js';
@@ -452,10 +452,7 @@ export async function listIssueTrackerIssuesPage(
 	// Partial project discovery means some projects' issues are missing from this page; propagate it so the
 	// page reports fetchFailed even when every discovered project's own read succeeded.
 	let fetchFailed = projectDiscoveryFailed || accountLookupFailed;
-	// A project whose internal page-drain hit its backstop (Jira/Linear cap at maxPagesPerRequest) reports
-	// `truncated`; surface it as `page.truncated` so a windowed read isn't published as having drained each
-	// project completely.
-	let projectTruncated = projectDiscoveryTruncated;
+	let truncationRecovery: 'narrow-scope' | 'none' | undefined = projectDiscoveryTruncated ? 'none' : undefined;
 	let drainMetadata: CollectionMetadata | undefined;
 	for (const { project, value: result, warning } of perProject) {
 		const key = projectKey(project);
@@ -465,7 +462,7 @@ export async function listIssueTrackerIssuesPage(
 			// single failing token repeats verbatim once per project in the window.
 			appendDedupedWarning(warnings, warning);
 			fetchFailed = true;
-			projectTruncated = true;
+			truncationRecovery = 'none';
 		}
 		// A thrown/unsupported read (e.g. Linear not-implemented) surfaces as a warning with no value;
 		// mark the aggregate as fetchFailed so an empty result isn't mistaken for "no issues".
@@ -475,7 +472,8 @@ export async function listIssueTrackerIssuesPage(
 		if (result != null) {
 			items.push(...result.values);
 			if (result.truncated) {
-				projectTruncated = true;
+				const recovery = result.recovery;
+				truncationRecovery = truncationRecovery == null || truncationRecovery === recovery ? recovery : 'none';
 			}
 			if (result.metadata != null) {
 				drainMetadata = mergeCollectionMetadata(drainMetadata, result.metadata);
@@ -497,29 +495,33 @@ export async function listIssueTrackerIssuesPage(
 	// publishes. A no-op when nothing merged, since the tracker already ordered that single run.
 	const orderedItems = ordering.order(items);
 
-	const drainAssessment = mergeAssessmentInto(
-		warnings,
-		options.providerId,
-		domain,
-		options.connectionId,
-		drainMetadata,
-	);
+	const projectReadReportedTruncation = truncationRecovery != null;
+	const drainAssessment = assessCollectionMetadata(options.providerId, domain, options.connectionId, drainMetadata);
+	for (const warning of drainAssessment.warnings) {
+		// A project result already supplies the recovery semantics. Replace metadata's unstructured fallback with
+		// the structured warning below, while retaining specific failures and omissions.
+		if (projectReadReportedTruncation && !drainAssessment.fetchFailed && warning.omission == null) continue;
+
+		appendDedupedWarning(warnings, warning);
+	}
 	fetchFailed = fetchFailed || drainAssessment.fetchFailed;
-	projectTruncated = projectTruncated || drainAssessment.truncated;
+	if (drainAssessment.truncated) {
+		truncationRecovery = 'none';
+	}
 
-	// A per-project read that returned data but couldn't confirm completeness (e.g. Trello's provider-native
-	// cap) sets `truncated` without a structured failure. Add one provider-neutral incompleteness warning so
-	// the caller sees the truncation, but only when no warning already explains it (avoid duplicate noise).
-	if (projectTruncated && warnings.length === 0) {
-		warnings.push(
+	const projectTruncated = truncationRecovery != null;
+	const scopeTooLarge = !fetchFailed && truncationRecovery === 'narrow-scope';
+	if (scopeTooLarge || (!fetchFailed && projectTruncated && !warnings.some(warning => warning.omission != null))) {
+		appendDedupedWarning(
+			warnings,
 			incompleteReadWarning(
 				options.providerId,
 				domain,
 				options.connectionId,
-				'Some issues were omitted; the provider returned an incomplete result.',
-				// `exhausted`, not `page-budget`: the per-project drain's backstop is an internal constant
-				// (`maxPagesPerRequest`), not an option this read exposes, so no caller can raise it.
-				fetchFailed ? 'interrupted' : 'exhausted',
+				scopeTooLarge
+					? 'Some projects hold more issues than one read can return; narrow the scope to read the rest.'
+					: 'Some issues were omitted; the provider returned an incomplete result.',
+				scopeTooLarge ? 'scope-too-large' : 'exhausted',
 			),
 		);
 	}

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

@@ -151,13 +151,18 @@ function sliceOutcome(slice: SweepSlice | undefined): ProviderSweepTargetEvent['
  *
  * The try/catch is what makes the observer observation-only: called from the fan-out's success path, a throwing
  * callback would otherwise propagate out of the `mapBounded` task and reject the entire sweep — corrupting the
- * read, not just the metric. Swallowed silently; the consumer owns its own aggregation.
+ * read, not just the metric. Swallowed silently; the consumer owns its own aggregation. The `void`-typed
+ * callback also admits an `async` consumer, whose rejection is created only after `observe` returns — the
+ * `Promise.resolve(...).catch` swallows that too, so it cannot escape as an unhandled rejection.
  *
  * The domain is resolved here rather than carried out of {@link sweepTarget}, so every target reports it by the
  * same rule no matter how far it got. `resolveDomainForRead` needs no integration instance, which is what makes
  * that possible: a target rejected by the first guard resolves the same host a fully drained one does.
  */
-function startSweepReporting(ctx: ProviderReadContext, observe: (event: ProviderSweepTargetEvent) => void) {
+function startSweepReporting(
+	ctx: ProviderReadContext,
+	observe: (event: ProviderSweepTargetEvent) => void | PromiseLike<unknown>,
+) {
 	const fanOutStartedAt = performance.now();
 
 	return function beginTarget(target: ProviderSweepTarget) {
@@ -165,16 +170,18 @@ function startSweepReporting(ctx: ProviderReadContext, observe: (event: Provider
 
 		return function reportSettled(slice: SweepSlice | undefined) {
 			try {
-				observe({
-					providerId: target.providerId,
-					domain: ctx.resolveDomainForRead(target.providerId, target.connectionId, target.domain),
-					connectionId: target.connectionId,
-					count: slice?.items.length ?? 0,
-					durationMs: performance.now() - startedAt,
-					queueWaitMs: startedAt - fanOutStartedAt,
-					outcome: sliceOutcome(slice),
-					truncated: slice?.truncated ?? false,
-				});
+				void Promise.resolve(
+					observe({
+						providerId: target.providerId,
+						domain: ctx.resolveDomainForRead(target.providerId, target.connectionId, target.domain),
+						connectionId: target.connectionId,
+						count: slice?.items.length ?? 0,
+						durationMs: performance.now() - startedAt,
+						queueWaitMs: startedAt - fanOutStartedAt,
+						outcome: sliceOutcome(slice),
+						truncated: slice?.truncated ?? false,
+					}),
+				).catch(() => {});
 			} catch {}
 		};
 	};

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

@@ -0,0 +1,105 @@
+import type { IssueShape } from '../../../git/models/issue.js';
+import type { IntegrationIds } from '../constants.js';
+import { IssuesCloudHostIntegrationId } from '../constants.js';
+import { isIssuesIntegration } from '../models/issuesIntegration.js';
+import type { ProviderResult, ProviderWarning } from '../results.js';
+import { isIssuesHostIntegrationId } from '../utils/integration.utils.js';
+import type { ProviderReadContext } from './context.js';
+import { runCaptured } from './drains.js';
+import { issueTrackerOnlySurfaceWarning, otherWarning } from './warnings.js';
+
+export interface TrackerIssueResult {
+	key: string;
+	/**
+	 * The resolved issue, or `undefined` when it provably does not exist or is not visible to this connection.
+	 * A failed read returns no item and sets `fetchFailed`.
+	 */
+	issue?: IssueShape;
+}
+
+/** Issue trackers are cloud-only, so this read takes no `domain`. */
+export async function getTrackerIssue(
+	ctx: ProviderReadContext,
+	options: {
+		providerId: IntegrationIds;
+		resourceId: string;
+		resourceUrl?: string;
+		key: string;
+		connectionId?: string;
+	},
+): Promise<ProviderResult<TrackerIssueResult>> {
+	const refused = (warning: ProviderWarning): ProviderResult<TrackerIssueResult> => ({
+		items: [],
+		warnings: [warning],
+		fetchFailed: true,
+	});
+	const surface = 'Issue resolution by key';
+
+	if (!isIssuesHostIntegrationId(options.providerId)) {
+		return refused(issueTrackerOnlySurfaceWarning(options.providerId, options.connectionId, surface));
+	}
+
+	if (options.resourceId.trim().length === 0) {
+		return refused(
+			otherWarning(options.providerId, undefined, options.connectionId, `${surface} requires a resource id.`),
+		);
+	}
+
+	if (options.key.trim().length === 0) {
+		return refused(
+			otherWarning(options.providerId, undefined, options.connectionId, `${surface} requires an issue key.`),
+		);
+	}
+
+	const resourceUrl = options.resourceUrl?.trim() || undefined;
+	if (options.providerId === IssuesCloudHostIntegrationId.Jira && resourceUrl == null) {
+		return refused(
+			otherWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				`${surface} requires the Jira resource URL so the result contains a browser link without resource discovery.`,
+			),
+		);
+	}
+
+	const integration = await ctx.getIntegrationForRead(options.providerId, options.connectionId);
+	if (integration == null) {
+		const early = ctx.earlyReturnConnectionWarnings(options.providerId, options.connectionId);
+		return { items: [], warnings: early.warnings, fetchFailed: early.fetchFailed || undefined };
+	}
+	if (!isIssuesIntegration(integration)) {
+		return refused(issueTrackerOnlySurfaceWarning(options.providerId, options.connectionId, surface));
+	}
+	if (!integration.supportsIssueLookupByResourceId) {
+		return refused(
+			otherWarning(
+				options.providerId,
+				undefined,
+				options.connectionId,
+				`${surface} is not supported by '${options.providerId}'; its single-issue read cannot prove an absence, so a miss would not be safe to cache.`,
+			),
+		);
+	}
+
+	const domain = ctx.domainForRead(integration, options.providerId, options.connectionId);
+	const issue = await runCaptured(
+		options.providerId,
+		domain,
+		options.connectionId,
+		() =>
+			integration.getIssueByResourceIdResult(options.resourceId, options.key, {
+				connectionId: options.connectionId,
+				resourceUrl: resourceUrl,
+			}),
+		{ warnOnMissingSession: true },
+	);
+	if (issue.warning != null) {
+		return refused(issue.warning);
+	}
+
+	return {
+		items: [{ key: options.key, ...(issue.value != null ? { issue: issue.value } : {}) }],
+		warnings: [],
+	};
+}

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

@@ -8,7 +8,7 @@ import type {
 	PullRequestSorting,
 } from '../providerFilters.js';
 import { providersMetadata } from '../providers/models.js';
-import type { ProviderWarning } from '../results.js';
+import type { ProviderWarning, ProviderWarningOmissionRecovery } from '../results.js';
 import type { IssueSearchCriteriaRejection, PullRequestSearchCriteriaRejection } from './filters.js';
 import type { UnmergeableIssueSort, UnsupportedIssueSortRejection } from './ordering.js';
 
@@ -101,21 +101,23 @@ export function issueTrackerOnlySurfaceWarning(
 	);
 }
 
-/**
- * Why a read the facade drove itself returned less than everything. The two questions a consumer cannot
- * answer from `truncated` or from the message, kept together because they are decided together:
- *
- * - `interrupted`: the read did NOT succeed — the session went away, a later page failed. It leaves an unread
- *   tail like the others, but it is a failure: it sets `fetchFailed`, and a retry is exactly the right move.
- *   Gets no omission at all, since the omission asserts the opposite.
- * - `page-budget`: the drain stopped at its own `maxPages`, with a usable cursor still in hand. The items ARE
- *   reachable and were simply not fetched, so re-running with a higher budget returns them.
- * - `exhausted`: everything else that succeeded and came back short — the provider capped the page it served,
- *   advertised another page without a usable cursor (or with one it had already handed out), or a read could
- *   not confirm it had drained everything. The default of the three: choose it whenever a raisable budget is
- *   not demonstrably what stopped the read, so a consumer is never offered a fetch that cannot deliver.
- */
-export type IncompleteReadCause = 'interrupted' | 'page-budget' | 'exhausted';
+/** Why a facade-driven read returned fewer results than requested. */
+export type IncompleteReadCause = 'interrupted' | 'page-budget' | 'exhausted' | 'scope-too-large';
+
+function recoveryForIncompleteReadCause(cause: IncompleteReadCause): ProviderWarningOmissionRecovery {
+	switch (cause) {
+		case 'page-budget':
+			return 'page-budget';
+		case 'scope-too-large':
+			return 'narrow-scope';
+		case 'interrupted':
+		case 'exhausted':
+			return 'none';
+		default:
+			cause satisfies never;
+			return 'none';
+	}
+}
 
 /**
  * Builds the warning for a read that returned less than everything, carrying the two facts a consumer cannot
@@ -143,7 +145,7 @@ export function incompleteReadWarning(
 		...warning,
 		omission: {
 			kind: 'pagination-incomplete',
-			recovery: cause === 'page-budget' ? 'page-budget' : 'none',
+			recovery: recoveryForIncompleteReadCause(cause),
 		},
 	};
 }
@@ -192,6 +194,10 @@ function truncationMessage(id: IntegrationIds, readKind: TruncatedReadKind, caus
 			return `${readKind} read for '${id}' stopped at its page budget; more results can be read by raising it.`;
 		case 'exhausted':
 			return `${readKind} read for '${id}' was truncated and cannot be continued; results may be incomplete.`;
+		case 'scope-too-large':
+			// Says what is true — the scope is larger than a read of it — rather than blaming the provider for a
+			// ceiling that is ours, and names the remedy that exists, since no retry or budget has one.
+			return `${readKind} read for '${id}' covers more than one read can return; narrow the scope to read the rest.`;
 	}
 	// No `default`: `IncompleteReadCause` is declared in this file, so `noImplicitReturns` already fails the
 	// build here if a cause is added without its own wording. (`collectionOmissionMessage`'s `satisfies never`

package/src/plus/integrations/results.ts

@@ -35,27 +35,11 @@ export type ProviderWarningKind = 'auth' | 'rate-limit' | 'not-found' | 'no-conn
 export type ProviderWarningOmissionKind = 'provider-limit' | 'recovery-budget' | 'pagination-incomplete';
 
 /**
- * What, if anything, would fetch the withheld results — the question `kind` cannot answer.
- *
- * `kind` says WHY results are missing, and two omissions of the same kind can need opposite handling: a drain
- * that stopped at a caller-settable page budget and a provider that advertised another page without a usable
- * cursor are both `pagination-incomplete`, but only the first can be fetched. A consumer offering a "load
- * more" affordance gates it on this, never on `kind`.
- *
- * - `none`: nothing the consumer can call returns the missing items — a provider-enforced cap, an internal
- *   budget it does not control, or a continuation the provider refused to hand back. Say the results are
- *   capped; do not offer to fetch more.
- * - `page-budget`: re-run the SAME read with a higher page budget (`maxPages` on the sweep options). Note this
- *   re-reads from the start rather than continuing — a sweep exposes no cursor — so it is a deliberate,
- *   user-initiated action, not something to retry automatically.
- *
- * Required, not optional: an absent value would be indistinguishable from `none` while actually meaning "this
- * producer didn't say", which is the ambiguity {@link ProviderWarning.omission} exists to remove. And a
- * conservative union on purpose — it names only what a producer can PROVE. A value is added when some layer
- * can vouch for it, never so that a plausible-looking case has something to map to; see
- * `collectionMetadata.ts` for the SDK shape that looks recoverable and is not.
+ * How a consumer can recover omitted results. `page-budget` reruns with a larger budget; `narrow-scope`
+ * requests a smaller server-side scope; `none` promises neither. Switch on the exact value because only
+ * `page-budget` is a fetch-more action.
  */
-export type ProviderWarningOmissionRecovery = 'none' | 'page-budget';
+export type ProviderWarningOmissionRecovery = 'none' | 'page-budget' | 'narrow-scope';
 
 /** Which repository / project / resource an omission is attributed to. All fields optional; a scope may name none. */
 export interface ProviderWarningOmissionScope {

package/src/utils/promise.ts

@@ -121,6 +121,21 @@ export async function mapBounded<T, R>(
 	return results;
 }
 
+/** Settles each task without stopping the sliding window when one of them rejects. */
+export function mapSettledBounded<T, R>(
+	items: readonly T[],
+	concurrency: number,
+	task: (item: T, index: number) => Promise<R>,
+): Promise<PromiseSettledResult<Awaited<R>>[]> {
+	return mapBounded(items, concurrency, async (item, index): Promise<PromiseSettledResult<Awaited<R>>> => {
+		try {
+			return { status: 'fulfilled', value: await task(item, index) };
+		} catch (reason) {
+			return { status: 'rejected', reason: reason };
+		}
+	});
+}
+
 export class PromiseCancelledError<T extends Promise<any> = Promise<any>> extends Error {
 	constructor(
 		public readonly promise: T,

package/src/utils/promiseCache.ts

@@ -97,6 +97,14 @@ export class PromiseCache<K, V> {
 		return this.cache.keys();
 	}
 
+	/**
+	 * Returns the number of entries in the cache, including expired entries that haven't been evicted yet
+	 * (they are only evicted on access), so this reflects what's actually retained in memory.
+	 */
+	get size(): number {
+		return this.cache.size;
+	}
+
 	/**
 	 * Gets a promise from the cache without creating it and updates accessed time
 	 * @param key - The cache key
@@ -139,6 +147,11 @@ export class PromiseCache<K, V> {
 			accessTTL?: number;
 			/** Whether to expire the entry if the promise fails */
 			expireOnError?: boolean;
+			/**
+			 * Called after the factory resolves. If the predicate resolves to true, the entry is evicted while
+			 * the current caller still receives the resolved value.
+			 */
+			evictWhen?: (value: V) => boolean | Promise<boolean>;
 			/**
 			 * TTL (time-to-live) in milliseconds for caching errors. When the factory rejects and `errorTTL` is set,
 			 * the cache entry is replaced with `Promise.resolve(undefined)` for subsequent callers, and the error
@@ -282,6 +295,20 @@ export class PromiseCache<K, V> {
 			}
 		}
 
+		const evictWhen = options?.evictWhen;
+		if (evictWhen != null) {
+			const candidate = entry;
+			void candidate.promise
+				.then(value => evictWhen(value))
+				.then(evict => {
+					if (evict) {
+						deleteIfOwned(this.cache, key, candidate);
+					}
+				})
+				// A retention policy must not surface a rejection independently of the caller-facing operation.
+				.catch(() => {});
+		}
+
 		// Clean up expired entries and enforce capacity limit in one pass
 		if (this.cache.size > 1) {
 			queueMicrotask(() => this.cleanup());
@@ -609,6 +636,11 @@ export class RepoPromiseCacheMap<K, V> {
 			accessTTL?: number;
 			/** Whether to expire the entry if the promise fails */
 			expireOnError?: boolean;
+			/**
+			 * Called after the factory resolves. If the predicate resolves to true, the entry is evicted while
+			 * the current caller still receives the resolved value.
+			 */
+			evictWhen?: (value: V) => boolean | Promise<boolean>;
 			/**
 			 * TTL (time-to-live) in milliseconds for caching errors. When the factory rejects and `errorTTL` is set,
 			 * the cache entry is replaced with `Promise.resolve(undefined)` for subsequent callers, and the error
@@ -755,6 +787,17 @@ export class RepoPromiseCacheMap<K, V> {
 		this.cache.clear();
 	}
 
+	/**
+	 * Returns the total number of entries across all repository caches.
+	 */
+	get entryCount(): number {
+		let count = 0;
+		for (const repoCache of this.cache.values()) {
+			count += repoCache.size;
+		}
+		return count;
+	}
+
 	/**
 	 * Returns the number of repositories in the cache.
 	 */

package/src/utils/resourceUsage.ts

@@ -0,0 +1,5 @@
+export type ResourceUsageUnit = 'bytes' | 'count';
+export type ResourceUsageMetric = `${string}.${ResourceUsageUnit}`;
+
+/** A flat resource-usage snapshot whose metric names carry their units. */
+export type ResourceUsage = Partial<Record<ResourceUsageMetric, number>>;