@oss-scout/core 0.11.0 → 1.1.0

package/dist/core/issue-eligibility.js

@@ -6,10 +6,10 @@
  * Extracted from issue-vetting.ts to isolate eligibility logic.
  */
 import { paginateAll } from "./pagination.js";
-import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
+import { errorMessage, rethrowIfFatal } from "./errors.js";
 import { warn } from "./logger.js";
-import { getHttpCache } from "./http-cache.js";
-import { getSearchBudgetTracker } from "./search-budget.js";
+import { getHttpCache, withInflightDedup, versionedCacheKey, } from "./http-cache.js";
+import { getSearchBudgetTracker, } from "./search-budget.js";
 function isLinkedPREvent(e) {
     return e.event === "cross-referenced" && !!e.source?.issue?.pull_request;
 }
@@ -50,24 +50,65 @@ function buildLinkedPRFromTimelineEvent(e, context) {
     };
 }
 const MODULE = "issue-eligibility";
-/** Phrases that indicate someone has already claimed an issue. */
-const CLAIM_PHRASES = [
-    "i'm working on this",
-    "i am working on this",
-    "i'll take this",
-    "i will take this",
-    "working on it",
-    "i'd like to work on",
-    "i would like to work on",
-    "can i work on",
-    "may i work on",
-    "assigned to me",
-    "i'm on it",
-    "i'll submit a pr",
-    "i will submit a pr",
-    "working on a fix",
-    "working on a pr",
+/**
+ * Claim detection, applied per clause (sentence). Plain substring matching
+ * flagged questions ("is anyone working on it?") and negations ("no one is
+ * working on this") as claims. Rules:
+ *
+ * - A clause ending in "?" is never a claim, EXCEPT a permission request
+ *   ("can I work on this?"), which is the author asking to take the issue.
+ * - A declarative clause with an indefinite or negated subject (anyone,
+ *   someone, nobody, not, ...) is never a claim.
+ * - Otherwise declarative claim patterns match, including third-person
+ *   ("Bob is working on it" means the issue is taken).
+ */
+/**
+ * Object that refers to the issue at hand: this/it/that, "the <thing>",
+ * "#123", "issue ...". Deliberately excludes "a <thing>" ("can I work on a
+ * repro?" introduces new work, it does not claim the issue). The numeric
+ * branch requires the # prefix: a bare number collides with quantity idioms
+ * ("can I take 5 minutes"). Residual misses: gerund objects ("work on
+ * fixing the bug") and bare numbers ("work on 126").
+ */
+const ISSUE_OBJECT = String.raw `(?:this\b|it\b|that\b|the\b|#\d+|issue\b)`;
+/** Explicit first-person claims; not subject to the subject guard. */
+const FIRST_PERSON_CLAIM_PATTERNS = [
+    new RegExp(String.raw `\bi\s*(?:'ll|will) take ${ISSUE_OBJECT}`),
+    new RegExp(String.raw `\bi\s*(?:'d|would) (?:like|love) to work on ${ISSUE_OBJECT}`),
+    /\bi\s*(?:'m|am) on it\b/,
+    /\bi\s*(?:'ll|will) submit a pr\b/,
+    /\bassigned to me\b/,
+];
+/**
+ * Generic "working on ..." phrasings. These also match third-person claims
+ * ("Bob is working on it"), so they need the subject guard below to avoid
+ * flagging indefinite or negated subjects.
+ */
+const GENERIC_WORKING_PATTERNS = [
+    /\bworking on (?:this|it)\b/,
+    /\bworking on a (?:fix|pr)\b/,
 ];
+/** Asking to take the issue counts as a claim even phrased as a question. */
+const PERMISSION_CLAIM_PATTERN = new RegExp(String.raw `\b(?:can|may|could) i (?:work on|take) ${ISSUE_OBJECT}`);
+/** Subjects/negations that make a "working on ..." clause a non-claim. */
+const NON_CLAIM_SUBJECTS = /\b(?:anyone|anybody|someone|somebody|who|whoever|nobody|no[- ]?one|not)\b/;
+/** True when a single comment body claims the issue. */
+export function commentClaimsIssue(body) {
+    const clauses = body.toLowerCase().split(/(?<=[.!?])|\n+/);
+    for (const clause of clauses) {
+        if (PERMISSION_CLAIM_PATTERN.test(clause))
+            return true;
+        if (clause.trimEnd().endsWith("?"))
+            continue;
+        if (FIRST_PERSON_CLAIM_PATTERNS.some((p) => p.test(clause)))
+            return true;
+        if (NON_CLAIM_SUBJECTS.test(clause))
+            continue;
+        if (GENERIC_WORKING_PATTERNS.some((p) => p.test(clause)))
+            return true;
+    }
+    return false;
+}
 /**
  * Check whether an open PR already exists for the given issue.
  * Uses the timeline API (REST) to detect cross-referenced PRs, avoiding
@@ -106,9 +147,7 @@ export async function checkNoExistingPR(octokit, owner, repo, issueNumber) {
         return { passed: linkedPRCount === 0, linkedPR };
     }
     catch (error) {
-        if (getHttpStatusCode(error) === 401 || isRateLimitError(error)) {
-            throw error;
-        }
+        rethrowIfFatal(error);
         const errMsg = errorMessage(error);
         warn(MODULE, `Failed to check for existing PRs on ${owner}/${repo}#${issueNumber}: ${errMsg}. Assuming no existing PR.`);
         return { passed: true, inconclusive: true, reason: errMsg, linkedPR: null };
@@ -122,42 +161,51 @@ const MERGED_PR_CACHE_TTL_MS = 15 * 60 * 1000;
  * Results are cached per-repo for 15 minutes to avoid redundant Search API
  * calls when multiple issues from the same repo are vetted.
  */
-export async function checkUserMergedPRsInRepo(octokit, owner, repo) {
+export async function checkUserMergedPRsInRepo(octokit, owner, repo, 
+// Optional injected budget tracker. Defaults to the shared singleton so
+// existing callers keep the same global budget accounting; a host wanting
+// per-search isolation threads its own tracker down from IssueVetter.
+tracker = getSearchBudgetTracker()) {
     const cache = getHttpCache();
-    const cacheKey = `merged-prs:${owner}/${repo}`;
-    // Manual cache check — do not use cachedTimeBased because we must NOT cache
-    // error-path fallback values (a transient failure returning 0 would poison the
-    // cache for 15 minutes, hiding that the user has merged PRs in the repo).
-    const cached = cache.getIfFresh(cacheKey, MERGED_PR_CACHE_TTL_MS);
-    if (cached != null && typeof cached === "number") {
-        return cached;
-    }
-    try {
-        const tracker = getSearchBudgetTracker();
-        await tracker.waitForBudget();
-        try {
-            // Use @me to search as the authenticated user
-            const { data } = await octokit.search.issuesAndPullRequests({
-                q: `repo:${owner}/${repo} is:pr is:merged author:@me`,
-                per_page: 1, // We only need total_count
-            });
-            // Only cache successful results
-            cache.set(cacheKey, "", data.total_count);
-            return data.total_count;
+    const cacheKey = versionedCacheKey(`merged-prs:${owner}/${repo}`);
+    // In-flight dedup: parallel vetting frequently hits several issues from
+    // one repo at once, and each used to pay a separate Search API call
+    // before the first populated the cache (#124).
+    return withInflightDedup(cache, cacheKey, async () => {
+        // Manual cache check — do not use cachedTimeBased because we must NOT
+        // cache error-path fallback values (a transient failure returning 0
+        // would poison the cache for 15 minutes, hiding that the user has
+        // merged PRs in the repo).
+        const cached = cache.getIfFresh(cacheKey, MERGED_PR_CACHE_TTL_MS);
+        if (cached != null && typeof cached === "number") {
+            return cached;
         }
-        finally {
-            // Always record the call — failed requests still consume GitHub rate limit points
-            tracker.recordCall();
+        try {
+            await tracker.waitForBudget();
+            try {
+                // Use @me to search as the authenticated user
+                const { data } = await octokit.search.issuesAndPullRequests({
+                    q: `repo:${owner}/${repo} is:pr is:merged author:@me`,
+                    per_page: 1, // We only need total_count
+                });
+                // Only cache successful results
+                cache.set(cacheKey, "", data.total_count);
+                return data.total_count;
+            }
+            finally {
+                // Always record the call — failed requests still consume GitHub rate limit points
+                tracker.recordCall();
+            }
         }
-    }
-    catch (error) {
-        if (getHttpStatusCode(error) === 401 || isRateLimitError(error)) {
-            throw error;
+        catch (error) {
+            rethrowIfFatal(error);
+            const errMsg = errorMessage(error);
+            warn(MODULE, `Could not check merged PRs in ${owner}/${repo}: ${errMsg}. Treating as unknown.`);
+            // null (not 0) so callers can tell a transient failure from a real zero
+            // and avoid caching verdicts built on it. Not cached — next call retries.
+            return null;
         }
-        const errMsg = errorMessage(error);
-        warn(MODULE, `Could not check merged PRs in ${owner}/${repo}: ${errMsg}. Defaulting to 0.`);
-        return 0; // Not cached — next call will retry
-    }
+    });
 }
 /**
  * Check whether an issue has been claimed by another contributor
@@ -167,27 +215,34 @@ export async function checkNotClaimed(octokit, owner, repo, issueNumber, comment
     if (commentCount === 0)
         return { passed: true };
     try {
-        // Paginate through all comments
-        const comments = await octokit.paginate(octokit.issues.listComments, {
-            owner,
-            repo,
-            issue_number: issueNumber,
-            per_page: 100,
-        }, (response) => response.data);
-        // Limit to last 100 comments to avoid excessive processing
-        const recentComments = comments.slice(-100);
+        // Fetch only the newest comments. Walking every page cost a
+        // 2,000-comment issue 20 list calls per vet, then discarded all but the
+        // tail anyway. Claims live in recent activity, so fetch the last page
+        // (plus its predecessor so a short last page still yields ~100+
+        // comments): at most 2 calls.
+        const PER_PAGE = 100;
+        const lastPage = Math.max(1, Math.ceil(commentCount / PER_PAGE));
+        const pagesToFetch = lastPage > 1 ? [lastPage - 1, lastPage] : [1];
+        const recentComments = [];
+        for (const page of pagesToFetch) {
+            const response = await octokit.issues.listComments({
+                owner,
+                repo,
+                issue_number: issueNumber,
+                per_page: PER_PAGE,
+                page,
+            });
+            recentComments.push(...response.data);
+        }
         for (const comment of recentComments) {
-            const body = (comment.body || "").toLowerCase();
-            if (CLAIM_PHRASES.some((phrase) => body.includes(phrase))) {
+            if (commentClaimsIssue(comment.body || "")) {
                 return { passed: false };
             }
         }
         return { passed: true };
     }
     catch (error) {
-        if (getHttpStatusCode(error) === 401 || isRateLimitError(error)) {
-            throw error;
-        }
+        rethrowIfFatal(error);
         const errMsg = errorMessage(error);
         warn(MODULE, `Failed to check claim status on ${owner}/${repo}#${issueNumber}: ${errMsg}. Assuming not claimed.`);
         return { passed: true, inconclusive: true, reason: errMsg };

package/dist/core/issue-graphql.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Batched GraphQL prefetch of issue "core" data (#169).
+ *
+ * `vetIssue` re-fetches each issue's basic fields (title, body, state, labels,
+ * timestamps, comment count) via a per-issue REST `issues.get`. When a search
+ * surfaces N issues that all need vetting, that is N separate REST calls before
+ * any of the deeper checks even start.
+ *
+ * `prefetchIssueCores` collapses those N calls into ONE aliased GraphQL query.
+ * The result is a map keyed by `owner/repo#number`; `vetIssue` consumes a hit
+ * instead of calling `issues.get`, and falls back to REST for any miss (a
+ * deleted issue, a permission error on one repo, or a non-fatal GraphQL blip).
+ *
+ * Scope is deliberately limited to the `issues.get` fields. The other vetting
+ * calls (timeline-based PR detection, claim scanning, project health,
+ * contribution guidelines) stay REST — batching those has pagination-semantics
+ * divergence risk and is left as a follow-up.
+ */
+import type { Octokit } from "@octokit/rest";
+/**
+ * Normalized issue fields equivalent to the subset of a REST `issues.get`
+ * response that `vetIssue` reads. Produced from either GraphQL (prefetch) or
+ * REST (fallback) so the two paths are interchangeable.
+ */
+export interface PrefetchedIssueCore {
+    /** GitHub numeric database id (REST `id` / GraphQL `databaseId`). */
+    id: number;
+    title: string;
+    /** Empty string when the issue has no body (matches REST `body || ""`). */
+    body: string;
+    state: "open" | "closed";
+    /** Label names, in declared order. */
+    labels: string[];
+    /** Total comment count (REST `comments` / GraphQL `comments.totalCount`). */
+    commentCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A single issue to prefetch. */
+export interface IssueRef {
+    owner: string;
+    repo: string;
+    number: number;
+}
+/** Map key for a prefetched core, also used by callers to look one up. */
+export declare function issueCoreKey(owner: string, repo: string, number: number): string;
+/**
+ * Batch-fetch issue core data with one aliased GraphQL query. Returns a map of
+ * `owner/repo#number` to the normalized core. Issues that the query could not
+ * resolve are simply absent — the caller is expected to fall back to REST for
+ * any key not in the map.
+ *
+ * Failure handling mirrors the rest of the vetter: fatal errors (401 / rate
+ * limit) propagate via `rethrowIfFatal`; a partial-data GraphQL error (one bad
+ * issue in the batch) keeps the aliases that did resolve; any other non-fatal
+ * error returns whatever resolved so the caller degrades to all-REST.
+ */
+export declare function prefetchIssueCores(octokit: Octokit, issues: IssueRef[]): Promise<Map<string, PrefetchedIssueCore>>;

package/dist/core/issue-graphql.js

@@ -0,0 +1,108 @@
+/**
+ * Batched GraphQL prefetch of issue "core" data (#169).
+ *
+ * `vetIssue` re-fetches each issue's basic fields (title, body, state, labels,
+ * timestamps, comment count) via a per-issue REST `issues.get`. When a search
+ * surfaces N issues that all need vetting, that is N separate REST calls before
+ * any of the deeper checks even start.
+ *
+ * `prefetchIssueCores` collapses those N calls into ONE aliased GraphQL query.
+ * The result is a map keyed by `owner/repo#number`; `vetIssue` consumes a hit
+ * instead of calling `issues.get`, and falls back to REST for any miss (a
+ * deleted issue, a permission error on one repo, or a non-fatal GraphQL blip).
+ *
+ * Scope is deliberately limited to the `issues.get` fields. The other vetting
+ * calls (timeline-based PR detection, claim scanning, project health,
+ * contribution guidelines) stay REST — batching those has pagination-semantics
+ * divergence risk and is left as a follow-up.
+ */
+import { rethrowIfFatal, errorMessage } from "./errors.js";
+import { warn } from "./logger.js";
+const MODULE = "issue-graphql";
+/** Map key for a prefetched core, also used by callers to look one up. */
+export function issueCoreKey(owner, repo, number) {
+    return `${owner}/${repo}#${number}`;
+}
+function normalizeNode(node) {
+    return {
+        id: node.databaseId,
+        title: node.title,
+        body: node.body ?? "",
+        state: node.state === "CLOSED" ? "closed" : "open",
+        labels: node.labels.nodes.map((l) => l.name),
+        commentCount: node.comments.totalCount,
+        createdAt: node.createdAt,
+        updatedAt: node.updatedAt,
+    };
+}
+/**
+ * Batch-fetch issue core data with one aliased GraphQL query. Returns a map of
+ * `owner/repo#number` to the normalized core. Issues that the query could not
+ * resolve are simply absent — the caller is expected to fall back to REST for
+ * any key not in the map.
+ *
+ * Failure handling mirrors the rest of the vetter: fatal errors (401 / rate
+ * limit) propagate via `rethrowIfFatal`; a partial-data GraphQL error (one bad
+ * issue in the batch) keeps the aliases that did resolve; any other non-fatal
+ * error returns whatever resolved so the caller degrades to all-REST.
+ */
+export async function prefetchIssueCores(octokit, issues) {
+    const result = new Map();
+    if (issues.length === 0)
+        return result;
+    // Dedup by key so a repeated issue does not allocate a redundant alias.
+    const unique = [
+        ...new Map(issues.map((i) => [issueCoreKey(i.owner, i.repo, i.number), i])).values(),
+    ];
+    // Build a parameterized query — owner/repo/number go through GraphQL
+    // variables, never string-interpolated into the query body, so there is no
+    // injection surface even though parseGitHubUrl already validates them.
+    const varDefs = [];
+    const selections = [];
+    const variables = {};
+    unique.forEach((iss, i) => {
+        varDefs.push(`$o${i}: String!, $n${i}: String!, $num${i}: Int!`);
+        variables[`o${i}`] = iss.owner;
+        variables[`n${i}`] = iss.repo;
+        variables[`num${i}`] = iss.number;
+        selections.push(`i${i}: repository(owner: $o${i}, name: $n${i}) {
+        issue(number: $num${i}) {
+          databaseId
+          title
+          body
+          state
+          labels(first: 100) { nodes { name } }
+          comments { totalCount }
+          createdAt
+          updatedAt
+        }
+      }`);
+    });
+    const query = `query batchIssueCores(${varDefs.join(", ")}) {\n${selections.join("\n")}\n}`;
+    let data;
+    try {
+        data = await octokit.graphql(query, variables);
+    }
+    catch (err) {
+        rethrowIfFatal(err);
+        // octokit's GraphqlResponseError attaches the resolved aliases to `.data`
+        // when only some issues in the batch errored (e.g. one was deleted).
+        const partial = err.data;
+        if (partial) {
+            data = partial;
+        }
+        else {
+            warn(MODULE, `GraphQL prefetch failed, falling back to REST: ${errorMessage(err)}`);
+            return result;
+        }
+    }
+    unique.forEach((iss, i) => {
+        const node = data?.[`i${i}`]?.issue;
+        // A null node (deleted/inaccessible) or a null databaseId leaves the key
+        // absent so the caller fetches it via REST.
+        if (!node || node.databaseId == null)
+            return;
+        result.set(issueCoreKey(iss.owner, iss.repo, iss.number), normalizeNode(node));
+    });
+    return result;
+}

package/dist/core/issue-vetting.d.ts

@@ -7,7 +7,9 @@
  * - repo-health.ts       — project health, contribution guidelines
  */
 import { Octokit } from "@octokit/rest";
-import { type SearchPriority, type IssueCandidate, type ProjectCategory } from "./types.js";
+import { type SearchPriority, type IssueCandidate, type ProjectCategory, type ScoutPreferences, type ScoutState, type MergedPRRecord, type ClosedPRRecord, type OpenPRRecord } from "./types.js";
+import { type PrefetchedIssueCore } from "./issue-graphql.js";
+import { type SearchBudgetTracker } from "./search-budget.js";
 /**
  * Feature-mode signals supplied by the caller (orchestrator) — the vetter
  * does NOT extract these from the GitHub issue itself. When passed, they
@@ -30,6 +32,15 @@ export type FeatureSignals = {
      */
     wontfixNoContributor?: boolean;
 };
+/**
+ * SLM pre-triage configuration (oss-autopilot#1122). `host` is the Ollama
+ * endpoint; an empty `host` means "use the triage default". A `null` config
+ * (not this shape) means SLM triage is disabled (#158).
+ */
+export interface SLMConfig {
+    model: string;
+    host: string;
+}
 /**
  * Read-only interface for accessing scout state during issue vetting.
  * Implementations may be backed by gist persistence, in-memory state, etc.
@@ -46,19 +57,101 @@ export interface ScoutStateReader {
     /** Numeric quality score for a repo, or null if not evaluated. */
     getRepoScore(repo: string): number | null;
     /**
-     * SLM pre-triage config (oss-autopilot#1122). Returns the configured
-     * model id and Ollama host, or empty strings when not configured —
-     * vetIssue treats either of these as "skip the SLM call".
+     * SLM pre-triage config (oss-autopilot#1122). Returns the configured model
+     * id and Ollama host, or `null` when SLM triage is not configured — vetIssue
+     * skips the SLM call on `null`. Required (#158): the old optional method with
+     * an empty-string sentinel could not distinguish "not configured" from "host
+     * defaulted"; `SLMConfig | null` makes the absence explicit.
+     */
+    getSLMTriageConfig(): SLMConfig | null;
+    /**
+     * Number of the user's PRs closed without merge in this repo (#125).
+     * Optional so existing implementations keep compiling; absent reads as 0.
+     */
+    getClosedWithoutMergeCount?(repo: string): number;
+    /**
+     * The configured GitHub username, used to tell the user's own in-flight PR
+     * apart from a competing one (#166). Optional; absent reads as "unknown".
+     */
+    getGitHubUsername?(): string;
+}
+/**
+ * Write side of the scout state, consumed by the bootstrap flow. Defined here
+ * next to ScoutStateReader so core/bootstrap.ts can depend on this contract
+ * instead of importing the OssScout facade from the package root (an upward
+ * dependency). OssScout implements it (#156).
+ */
+export interface ScoutStateWriter {
+    /** Read current preferences (bootstrap reads githubUsername). */
+    getPreferences(): Readonly<ScoutPreferences>;
+    /** Replace the cached starred-repo list. */
+    setStarredRepos(repos: string[]): void;
+    /** Record a merged PR (deduplicated by URL). */
+    recordMergedPR(pr: MergedPRRecord): void;
+    /** Record a PR closed without merge (deduplicated by URL). */
+    recordClosedPR(pr: ClosedPRRecord): void;
+    /** Record an open PR (deduplicated by URL). */
+    recordOpenPR(pr: OpenPRRecord): void;
+    /** Snapshot the current state (bootstrap reports counts from it). */
+    getState(): Readonly<ScoutState>;
+}
+/**
+ * Inputs to deriveRecommendation: the already-computed check results and
+ * affinity signals. Kept as a flat record of primitives so the derivation is a
+ * pure function, independently unit-testable (#157).
+ */
+export interface RecommendationInput {
+    noExistingPR: boolean;
+    /**
+     * The linked PR is the user's own open PR (#166). When true, the existing-PR
+     * block is reframed as "you're already on it" — a skip with a clear reason —
+     * instead of a competing-PR penalty.
      */
-    getSLMTriageConfig?(): {
-        model: string;
-        host: string;
-    };
+    ownPR: boolean;
+    notClaimed: boolean;
+    clearRequirements: boolean;
+    contributionGuidelinesFound: boolean;
+    projectIsActive: boolean;
+    projectCheckFailed: boolean;
+    projectFailureReason?: string;
+    existingPRInconclusive: boolean;
+    existingPRReason?: string;
+    claimInconclusive: boolean;
+    claimReason?: string;
+    mergedCountInconclusive: boolean;
+    effectiveMergedCount: number;
+    orgName: string;
+    orgHasMergedPRs: boolean;
+    matchesCategory: boolean;
+    issueClosed: boolean;
+    /** noExistingPR && notClaimed && projectActive && clearRequirements. */
+    passedAllChecks: boolean;
+}
+export interface RecommendationOutput {
+    notes: string[];
+    reasonsToApprove: string[];
+    reasonsToSkip: string[];
+    recommendation: "approve" | "skip" | "needs_review";
 }
+/**
+ * Derive the human-readable notes, approve/skip reasons, and the final
+ * recommendation from a vet's check results. Pure: no I/O, no state reads — the
+ * caller computes the inputs and threads them in. Extracted from vetIssue so
+ * the recommendation logic is testable in isolation (#157).
+ */
+export declare function deriveRecommendation(input: RecommendationInput): RecommendationOutput;
 export declare class IssueVetter {
     private octokit;
     private stateReader;
-    constructor(octokit: Octokit, stateReader: ScoutStateReader);
+    private budgetTracker;
+    /**
+     * @param octokit      - Authenticated Octokit instance
+     * @param stateReader  - Read-only scout state interface
+     * @param budgetTracker - Search budget tracker. Defaults to the shared
+     *   singleton so existing callers behave identically; inject a per-search
+     *   instance to isolate budget accounting in a long-lived concurrent host.
+     */
+    constructor(octokit: Octokit, stateReader: ScoutStateReader, budgetTracker?: SearchBudgetTracker);
     /**
      * Vet a specific issue — runs all checks and computes recommendation + viability score.
      * Results are cached for 15 minutes to avoid redundant API calls on repeated searches.
@@ -70,7 +163,20 @@ export declare class IssueVetter {
      */
     vetIssue(issueUrl: string, opts?: {
         featureSignals?: FeatureSignals;
+        /**
+         * Issue core data already fetched in a batch GraphQL query (#169). When
+         * present it replaces the per-issue REST `issues.get`; otherwise the
+         * core is fetched via REST. The two paths are normalized to the same
+         * shape so behaviour is identical either way.
+         */
+        prefetched?: PrefetchedIssueCore;
     }): Promise<IssueCandidate>;
+    /**
+     * Fetch a single issue's core fields via REST and normalize them to the same
+     * shape as a GraphQL prefetch (#169). The REST fallback path when no
+     * prefetched core was supplied.
+     */
+    private fetchIssueCore;
     /**
      * Vet multiple issues in parallel with concurrency limit
      */