pr-shepherd 0.46.8 → 0.48.0

package/bin/github/fingerprint.mjs

@@ -0,0 +1,67 @@
+import { graphqlWithRateLimit } from "./client.mjs";
+import { PR_FINGERPRINT_QUERY } from "./queries.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { commentRevisions, mergePolicyFingerprint, rulesComplete, stackKey, suiteFingerprint, hasMultiCommentThreads, threadCommentRevisions, } from "./fingerprint-fields.mjs";
+function coreFingerprint(raw, counts, viewer) {
+    return {
+        headRefOid: raw.headRefOid,
+        updatedAt: raw.updatedAt ?? "",
+        state: raw.state,
+        isDraft: raw.isDraft,
+        mergeable: raw.mergeable,
+        mergeStateStatus: raw.mergeStateStatus,
+        reviewDecision: raw.reviewDecision,
+        isInMergeQueue: Boolean(raw.isInMergeQueue),
+        isMergeQueueEnabled: Boolean(raw.isMergeQueueEnabled),
+        mergePolicy: mergePolicyFingerprint(raw),
+        commentCount: raw.comments.totalCount ?? raw.comments.nodes.length,
+        commentRevisions: commentRevisions(raw.comments.nodes),
+        threadCount: raw.reviewThreads.totalCount ?? raw.reviewThreads.nodes.length,
+        reviewCount: counts.reviewCount,
+        reviewRevisions: counts.reviewRevisions,
+        latestCommentId: raw.comments.nodes.at(-1)?.id ?? null,
+        latestThreadId: raw.reviewThreads.nodes.at(-1)?.id ?? null,
+        latestReviewId: counts.latestReviewId,
+        checkRollupState: raw.commits.nodes[0]?.commit.statusCheckRollup?.state ?? null,
+        ...suiteFingerprint(raw.commits.nodes[0]?.commit.checkSuites),
+        viewerCanUpdate: raw.viewerCanUpdate === true,
+        viewerPermission: viewer.permission,
+        viewerLogin: viewer.login,
+        stackKey: stackKey(raw),
+        threadCommentRevisions: threadCommentRevisions(raw.reviewThreads.nodes),
+        rulesComplete: rulesComplete(raw.baseRef),
+        hasMultiCommentThreads: hasMultiCommentThreads(raw.reviewThreads.nodes),
+    };
+}
+export function fingerprintFromRaw(raw, viewerPermission = null, viewerLogin = null) {
+    return coreFingerprint(raw, {
+        reviewCount: raw.allReviews?.totalCount ?? 0,
+        latestReviewId: raw.allReviews?.nodes?.at(-1)?.id ?? null,
+        reviewRevisions: commentRevisions(raw.allReviews?.nodes ?? []),
+    }, { permission: viewerPermission, login: viewerLogin });
+}
+export function fingerprintsEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export async function fetchPrFingerprint(pr, repo) {
+    const result = await graphqlWithRateLimit(PR_FINGERPRINT_QUERY, {
+        owner: repo.owner,
+        repo: repo.name,
+        pr,
+    });
+    if (!result.data.repository) {
+        throw new GitHubRequestError(`GitHub GraphQL response did not include repository ${repo.owner}/${repo.name} (not found or access denied)`, { status: 200 });
+    }
+    const raw = result.data.repository.pullRequest;
+    if (!raw)
+        throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
+    return coreFingerprint(raw, {
+        reviewCount: raw.reviews.totalCount,
+        latestReviewId: raw.reviews.nodes.at(-1)?.id ?? null,
+        reviewRevisions: commentRevisions(raw.reviews.nodes),
+    }, {
+        permission: result.data.repository.viewerPermission,
+        login: result.data.viewer?.login ?? null,
+    });
+}

package/bin/github/gql/batch-pr.gql

@@ -9,12 +9,16 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
     resetAt
     used
   }
+  viewer {
+    login
+  }
   repository(owner: $owner, name: $repo) {
     viewerPermission
     viewerCanAdminister
     pullRequest(number: $pr) {
       id
       number
+      updatedAt
       state
       isDraft
       viewerDidAuthor
@@ -32,7 +36,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
       }
       baseRefName
       isInMergeQueue
-      isMergeQueueEnabled
+      ...PrMergePolicy
       autoMergeRequest {
         enabledAt
         mergeMethod
@@ -49,7 +53,8 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           login
         }
         headCommit {
-          ...QueueCheckCommit
+          oid
+          committedDate
         }
       }
       mergeQueueAdditions: timelineItems(last: 1, itemTypes: [ADDED_TO_MERGE_QUEUE_EVENT]) {
@@ -68,7 +73,13 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
               login
             }
             beforeCommit {
-              ...QueueCheckCommit
+              oid
+              committedDate
+              parents(first: 100) {
+                nodes {
+                  oid
+                }
+              }
             }
           }
         }
@@ -81,49 +92,6 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
       stackEntry {
         position
       }
-      baseRef {
-        branchProtectionRule {
-          requiresApprovingReviews
-          requiredApprovingReviewCount
-          requiresConversationResolution
-          requiresCodeOwnerReviews
-          requireLastPushApproval
-          requiresCommitSignatures
-          requiresLinearHistory
-          requiresStatusChecks
-          requiredStatusCheckContexts
-          requiresStrictStatusChecks
-          requiresDeployments
-          requiredDeploymentEnvironments
-        }
-        rules(first: 100) {
-          nodes {
-            type
-            parameters {
-              ... on PullRequestParameters {
-                requiredApprovingReviewCount
-                requiredReviewThreadResolution
-                requireCodeOwnerReview
-                requireLastPushApproval
-              }
-              ... on RequiredStatusChecksParameters {
-                strictRequiredStatusChecksPolicy
-                requiredStatusChecks {
-                  context
-                }
-              }
-              ... on RequiredDeploymentsParameters {
-                requiredDeploymentEnvironments
-              }
-              ... on CodeScanningParameters {
-                codeScanningTools {
-                  tool
-                }
-              }
-            }
-          }
-        }
-      }
       # Not paginated — capped at 50; PRs with more pending reviewers truncate silently.
       reviewRequests(last: 50) {
         nodes {
@@ -153,6 +121,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
         }
       }
       reviewThreads(last: 100) {
+        totalCount
         pageInfo {
           hasPreviousPage
           startCursor
@@ -189,11 +158,13 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
               line
               startLine
               createdAt
+              updatedAt
             }
           }
         }
       }
       comments(last: 100) {
+        totalCount
         pageInfo {
           hasPreviousPage
           startCursor
@@ -210,6 +181,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           }
           body
           createdAt
+          updatedAt
         }
       }
       changesRequestedReviews: reviews(states: CHANGES_REQUESTED, last: 50) {
@@ -249,8 +221,12 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           createdAt
         }
       }
-      allReviews: reviews(last: 1) {
+      allReviews: reviews(last: 100) {
         totalCount
+        nodes {
+          id
+          updatedAt
+        }
       }
       approvedReviews: reviews(states: APPROVED, last: 50) {
         pageInfo {
@@ -276,23 +252,9 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           commit {
             oid
             committedDate
-            checkSuites(first: 50) {
-              pageInfo {
-                hasNextPage
-              }
-              nodes {
-                conclusion
-                workflowRun {
-                  databaseId
-                  event
-                  url
-                  workflow {
-                    name
-                  }
-                }
-              }
-            }
+            ...CommitCheckSuites
             statusCheckRollup {
+              state
               contexts(first: 100) {
                 pageInfo {
                   hasNextPage
@@ -345,60 +307,3 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
     }
   }
 }
-
-fragment QueueCheckCommit on Commit {
-  oid
-  committedDate
-  parents(first: 100) {
-    nodes {
-      oid
-    }
-  }
-  statusCheckRollup {
-    contexts(first: 100) {
-      pageInfo {
-        hasNextPage
-        endCursor
-      }
-      nodes {
-        __typename
-        ... on CheckRun {
-          id
-          name
-          status
-          conclusion
-          detailsUrl
-          completedAt
-          startedAt
-          title
-          summary
-          annotations(first: 1) {
-            nodes {
-              message
-            }
-          }
-          checkSuite {
-            createdAt
-            updatedAt
-            workflowRun {
-              event
-              createdAt
-              updatedAt
-              workflow {
-                name
-                databaseId
-              }
-            }
-          }
-        }
-        ... on StatusContext {
-          context
-          state
-          createdAt
-          targetUrl
-          description
-        }
-      }
-    }
-  }
-}

package/bin/github/gql/commit-check-suites.gql

@@ -0,0 +1,19 @@
+fragment CommitCheckSuites on Commit {
+  checkSuites(first: 50) {
+    pageInfo {
+      hasNextPage
+    }
+    nodes {
+      id
+      conclusion
+      workflowRun {
+        databaseId
+        event
+        url
+        workflow {
+          name
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/pr-fingerprint.gql

@@ -0,0 +1,75 @@
+# Cheap preflight. Cost is 1. Used to skip BatchPr when GitHub state is unchanged.
+query PrFingerprint($owner: String!, $repo: String!, $pr: Int!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  viewer {
+    login
+  }
+  repository(owner: $owner, name: $repo) {
+    viewerPermission
+    pullRequest(number: $pr) {
+      updatedAt
+      state
+      isDraft
+      viewerCanUpdate
+      headRefOid
+      mergeable
+      mergeStateStatus
+      reviewDecision
+      isInMergeQueue
+      stack {
+        number
+        size
+        baseRefName
+      }
+      stackEntry {
+        position
+      }
+      ...PrMergePolicy
+      comments(last: 100) {
+        totalCount
+        nodes {
+          id
+          updatedAt
+        }
+      }
+      reviewThreads(last: 20) {
+        totalCount
+        nodes {
+          id
+          comments(last: 1) {
+            totalCount
+            nodes {
+              id
+              updatedAt
+            }
+          }
+        }
+      }
+      reviews(last: 100) {
+        totalCount
+        nodes {
+          id
+          updatedAt
+        }
+      }
+      commits(last: 1) {
+        nodes {
+          commit {
+            oid
+            statusCheckRollup {
+              state
+            }
+            ...CommitCheckSuites
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/pr-merge-policy.gql

@@ -0,0 +1,49 @@
+fragment PrMergePolicy on PullRequest {
+  isMergeQueueEnabled
+  baseRef {
+    branchProtectionRule {
+      requiresApprovingReviews
+      requiredApprovingReviewCount
+      requiresConversationResolution
+      requiresCodeOwnerReviews
+      requireLastPushApproval
+      requiresCommitSignatures
+      requiresLinearHistory
+      requiresStatusChecks
+      requiredStatusCheckContexts
+      requiresStrictStatusChecks
+      requiresDeployments
+      requiredDeploymentEnvironments
+    }
+    rules(first: 100) {
+      pageInfo {
+        hasNextPage
+      }
+      nodes {
+        type
+        parameters {
+          ... on PullRequestParameters {
+            requiredApprovingReviewCount
+            requiredReviewThreadResolution
+            requireCodeOwnerReview
+            requireLastPushApproval
+          }
+          ... on RequiredStatusChecksParameters {
+            strictRequiredStatusChecksPolicy
+            requiredStatusChecks {
+              context
+            }
+          }
+          ... on RequiredDeploymentsParameters {
+            requiredDeploymentEnvironments
+          }
+          ... on CodeScanningParameters {
+            codeScanningTools {
+              tool
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/merge-queue-checks.mjs

@@ -1,46 +1,73 @@
 import { graphql } from "./client.mjs";
 import { requireContextNodes } from "./batch-response.mjs";
 import { COMMIT_CHECK_CONTEXTS_QUERY } from "./queries.mjs";
-async function hydrateCommitContexts(commit, repo) {
-    const contexts = commit.statusCheckRollup?.contexts;
-    if (!contexts)
-        return;
-    contexts.nodes = requireContextNodes(contexts.nodes);
-    if (contexts.pageInfo.hasNextPage && !contexts.pageInfo.endCursor) {
-        throw new Error(`Merge queue check pagination interrupted: GitHub omitted the next cursor for ${commit.oid}. Retry.`);
+function omittedCursorError(oid) {
+    return new Error(`Merge queue check pagination interrupted: GitHub omitted the next cursor for ${oid}. Retry.`);
+}
+function nextPageCursor(contexts, oid) {
+    if (!contexts.pageInfo.hasNextPage)
+        return undefined;
+    if (!contexts.pageInfo.endCursor)
+        throw omittedCursorError(oid);
+    return contexts.pageInfo.endCursor;
+}
+function initialQueueCursor(existing, oid) {
+    if (!existing)
+        return null;
+    return nextPageCursor(existing, oid);
+}
+async function fetchQueuePage(oid, repo, cursor) {
+    const result = await graphql(COMMIT_CHECK_CONTEXTS_QUERY, {
+        owner: repo.owner,
+        repo: repo.name,
+        oid,
+        ...(cursor !== null && { cursor }),
+    });
+    const object = result.data.repository?.object;
+    if (object?.__typename !== "Commit" || object.oid !== oid) {
+        if (cursor === null)
+            return null;
+        throw new Error(`Merge queue check pagination interrupted: commit ${oid} disappeared or changed. Retry.`);
     }
-    let cursor = contexts.pageInfo.hasNextPage ? contexts.pageInfo.endCursor : null;
-    while (cursor) {
+    return object.statusCheckRollup?.contexts ?? null;
+}
+async function hydrateCommitContexts(commit, repo) {
+    const existing = commit.statusCheckRollup?.contexts;
+    const nodes = existing ? [...requireContextNodes(existing.nodes)] : [];
+    let cursor = initialQueueCursor(existing, commit.oid);
+    while (cursor !== undefined) {
         // eslint-disable-next-line no-await-in-loop
-        const result = await graphql(COMMIT_CHECK_CONTEXTS_QUERY, {
-            owner: repo.owner,
-            repo: repo.name,
-            oid: commit.oid,
-            cursor,
-        });
-        const object = result.data.repository?.object;
-        if (object?.__typename !== "Commit" || object.oid !== commit.oid) {
-            throw new Error(`Merge queue check pagination interrupted: commit ${commit.oid} disappeared or changed. Retry.`);
-        }
-        const next = object.statusCheckRollup?.contexts;
+        const next = await fetchQueuePage(commit.oid, repo, cursor);
         if (!next) {
+            if (cursor === null) {
+                cursor = undefined;
+                continue;
+            }
             throw new Error(`Merge queue check pagination interrupted: statusCheckRollup disappeared for ${commit.oid}. Retry.`);
         }
-        contexts.nodes.push(...requireContextNodes(next.nodes));
-        contexts.pageInfo = next.pageInfo;
-        cursor = next.pageInfo.hasNextPage ? next.pageInfo.endCursor : null;
-        if (next.pageInfo.hasNextPage && !cursor) {
-            throw new Error(`Merge queue check pagination interrupted: GitHub omitted the next cursor for ${commit.oid}. Retry.`);
-        }
+        nodes.push(...requireContextNodes(next.nodes));
+        cursor = nextPageCursor(next, commit.oid);
     }
+    commit.statusCheckRollup = {
+        contexts: { pageInfo: { hasNextPage: false, endCursor: null }, nodes },
+    };
+}
+function currentRemovalCommit(raw) {
+    const removal = raw.mergeQueueRemovals?.nodes[0];
+    const addition = raw.mergeQueueAdditions?.nodes[0];
+    if (!removal?.beforeCommit)
+        return undefined;
+    if (addition && Date.parse(removal.createdAt) < Date.parse(addition.createdAt))
+        return undefined;
+    const parentOids = removal.beforeCommit.parents?.nodes.map((node) => node.oid);
+    if (!parentOids?.includes(raw.headRefOid))
+        return undefined;
+    return removal.beforeCommit;
 }
 /** Hydrate all status contexts for the active or most recently removed queue commit. */
 export async function hydrateMergeQueueChecks(raw, repo) {
     const active = raw.mergeQueueEntry?.headCommit;
-    const removal = raw.mergeQueueRemovals?.nodes[0];
-    const addition = raw.mergeQueueAdditions?.nodes[0];
-    const removalIsCurrent = Boolean(removal && (!addition || Date.parse(removal.createdAt) >= Date.parse(addition.createdAt)));
-    const removed = removalIsCurrent ? removal?.beforeCommit : undefined;
+    const removed = currentRemovalCommit(raw);
     if (active)
         await hydrateCommitContexts(active, repo);
     if (removed && removed.oid !== active?.oid)

package/bin/github/queries.d.mts

@@ -10,6 +10,8 @@
 export declare const BATCH_PR_QUERY: string;
 /** Slim @include follow-up for outstanding batch-query connections. */
 export declare const BATCH_PR_PAGE_QUERY: string;
+/** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
+export declare const PR_FINGERPRINT_QUERY: string;
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/github/queries.mjs

@@ -9,10 +9,13 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 const gql = (name) => readFileSync(join(import.meta.dirname, "gql", name), "utf8");
+const withSharedFragments = (query) => `${gql("pr-merge-policy.gql")}\n${gql("commit-check-suites.gql")}\n${query}`;
 /** The primary batch query that fetches CI + comments + merge status in one round-trip. */
-export const BATCH_PR_QUERY = gql("batch-pr.gql");
+export const BATCH_PR_QUERY = withSharedFragments(gql("batch-pr.gql"));
 /** Slim @include follow-up for outstanding batch-query connections. */
 export const BATCH_PR_PAGE_QUERY = gql("batch-pr-page.gql");
+/** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
+export const PR_FINGERPRINT_QUERY = withSharedFragments(gql("pr-fingerprint.gql"));
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/quota-warning.mjs

@@ -2,5 +2,5 @@ export function buildQuotaAwareContinuation(warning, prefix) {
     const interval = `${warning.pollIntervalMinutes}m`;
     const timeout = `${warning.pollTimeoutMinutes}m`;
     const resetTime = new Date(warning.resetAt * 1000).toISOString();
-    return `${prefix} GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool. Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, replace any existing interval and timeout flags with \`--interval ${interval} --timeout ${timeout}\`, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
+    return `${prefix} GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool. Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, raise any shorter interval and timeout flags to at least \`--interval ${interval} --timeout ${timeout}\`, keep any longer cadence, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
 }

package/bin/state/pr-fingerprint.d.mts

@@ -0,0 +1,20 @@
+import type { PrFingerprint } from "../github/fingerprint.mts";
+import type { PrShepherdConfig } from "../config/load.mts";
+import type { ShepherdReport } from "../types.mts";
+export interface StoredPrFingerprint {
+    version: number;
+    inputDigest: string;
+    fingerprint: PrFingerprint;
+    report: ShepherdReport;
+}
+export declare function fingerprintInputDigest(config: PrShepherdConfig): string;
+export declare function loadPrFingerprint(key: {
+    owner: string;
+    repo: string;
+    pr: number;
+}): Promise<StoredPrFingerprint | null>;
+export declare function storePrFingerprint(key: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, fingerprint: PrFingerprint, report: ShepherdReport, config: PrShepherdConfig): Promise<void>;

package/bin/state/pr-fingerprint.mjs

@@ -0,0 +1,90 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+import { discoverRuleFiles } from "../classify/loader.mjs";
+import { getEffectiveCwd } from "../execution-context.mjs";
+const VERSION = 3;
+export function fingerprintInputDigest(config) {
+    const hash = createHash("sha256");
+    hash.update(JSON.stringify({
+        ignoreChecks: config.ignoreChecks,
+        botUsernames: config.botUsernames,
+        iterate: config.iterate,
+        watch: { readyDelayMinutes: config.watch.readyDelayMinutes },
+        checks: config.checks,
+        mergeStatus: config.mergeStatus,
+        actions: {
+            autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
+            autoMarkReady: config.actions.autoMarkReady,
+            neverCancelRuns: config.actions.neverCancelRuns,
+            workWhileQueued: config.actions.workWhileQueued,
+        },
+    }));
+    for (const file of discoverRuleFiles(getEffectiveCwd())) {
+        hash.update("\0");
+        hash.update(file);
+        hash.update("\0");
+        try {
+            hash.update(readFileSync(file));
+        }
+        catch {
+            hash.update("missing");
+        }
+    }
+    return hash.digest("hex").slice(0, 16);
+}
+export async function loadPrFingerprint(key) {
+    const path = resolvePrStatePath(key, "fingerprint.json");
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (!isStoredFingerprint(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function storePrFingerprint(key, fingerprint, report, config) {
+    const path = resolvePrStatePath(key, "fingerprint.json");
+    let tmp;
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        tmp = `${path}.${randomUUID()}.tmp`;
+        const payload = {
+            version: VERSION,
+            inputDigest: fingerprintInputDigest(config),
+            fingerprint,
+            report,
+        };
+        await writeFile(tmp, `${JSON.stringify(payload)}\n`, "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+    }
+    catch {
+        // Fingerprint cache is an optimization; a failed write just means the next tick refetches.
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+function isStoredFingerprint(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return (record["version"] === VERSION &&
+        typeof record["inputDigest"] === "string" &&
+        record["fingerprint"] !== null &&
+        typeof record["fingerprint"] === "object" &&
+        record["report"] !== null &&
+        typeof record["report"] === "object");
+}