@davidvornholt/standards 0.17.2 → 0.18.0

package/src/poller-claim.ts

@@ -1,34 +1,33 @@
 import { randomUUID } from 'node:crypto';
 import { hasLabel } from './github-label-identity';
-import { isRecord } from './github-settings-parse';
 import { type ApprovalBinding, readApprovalBinding } from './poller-approval';
 import {
-  hiddenCommentMetadata,
-  parseHiddenCommentMetadata,
-} from './poller-comment-metadata';
+  type ClaimMarkerBinding,
+  reconcileTrustedClaimElection,
+  reconcileTrustedClaimHistory,
+} from './poller-claim-reconciliation';
+import { hiddenCommentMetadata } from './poller-comment-metadata';
+import { getIssue, lastLabelEvent } from './poller-github';
 import {
-  collaboratorRole,
-  getIssue,
-  type IssueComment,
-  lastLabelEvent,
-  listIssueComments,
-} from './poller-github';
-import { createComment, deleteComment } from './poller-github-write';
+  addLabels,
+  createComment,
+  deleteComment,
+  removeLabel,
+} from './poller-github-write';
+import type { JobDeps } from './poller-job-shared';
 import {
   CLAIM_METADATA_MARKER,
   FIX_IN_PROGRESS,
-  isTrustedRole,
   REVIEW_IN_PROGRESS,
 } from './poller-protocol';
+import { inProgressLabelFor, type PollerJobKind } from './poller-queue-marker';
+import { reconcileExistingQueuedJob } from './poller-status';
 
-export type ClaimBinding = {
-  readonly approval: ApprovalBinding;
-  readonly claimLabel: string;
-  readonly claimEpoch: string;
+export type ClaimBinding = ClaimMarkerBinding & {
   readonly markerId: number;
 };
 
-type ClaimMarker = Omit<ClaimBinding, 'markerId'> & {
+type ClaimMarker = ClaimMarkerBinding & {
   readonly nonce: string;
 };
 
@@ -54,73 +53,6 @@ const markerBody = (marker: ClaimMarker): string =>
     marker,
   )}`;
 
-const isApprovalBinding = (value: unknown): value is ApprovalBinding =>
-  isRecord(value) &&
-  typeof value.id === 'string' &&
-  typeof value.repo === 'string' &&
-  typeof value.issueNumber === 'number' &&
-  typeof value.eventId === 'number' &&
-  typeof value.label === 'string' &&
-  typeof value.actorLogin === 'string' &&
-  typeof value.approvedAt === 'string' &&
-  typeof value.target === 'string';
-
-const parseMarker = (comment: IssueComment): ClaimMarker | null => {
-  const payload = parseHiddenCommentMetadata(
-    comment.body,
-    CLAIM_METADATA_MARKER,
-  );
-  if (!isRecord(payload)) {
-    return null;
-  }
-  const raw = payload;
-  if (
-    typeof raw.claimLabel !== 'string' ||
-    typeof raw.claimEpoch !== 'string' ||
-    typeof raw.nonce !== 'string' ||
-    !isApprovalBinding(raw.approval)
-  ) {
-    return null;
-  }
-  return {
-    approval: raw.approval,
-    claimLabel: raw.claimLabel,
-    claimEpoch: raw.claimEpoch,
-    nonce: raw.nonce,
-  };
-};
-
-const winningMarkerId = async (
-  context: ClaimContext,
-  binding: Omit<ClaimBinding, 'markerId'>,
-): Promise<number | null> => {
-  const comments = await listIssueComments(
-    context.token,
-    context.repo,
-    context.issueNumber,
-  );
-  let winner: number | null = null;
-  for (const comment of comments) {
-    const marker = parseMarker(comment);
-    const differs =
-      marker?.approval.id !== binding.approval.id ||
-      marker.claimLabel !== binding.claimLabel ||
-      marker.claimEpoch !== binding.claimEpoch;
-    if (!differs) {
-      // biome-ignore lint/performance/noAwaitInLoops: claim authors must be checked against their current role; the usually-one-item list is deliberately fail-closed.
-      const role = await collaboratorRole(
-        context.token,
-        context.repo,
-        comment.authorLogin,
-      );
-      if (isTrustedRole(role) && (winner === null || comment.id < winner)) {
-        winner = comment.id;
-      }
-    }
-  }
-  return winner;
-};
-
 export const acquireClaim = async (
   context: ClaimContext,
   approval: ApprovalBinding,
@@ -147,14 +79,36 @@ export const acquireClaim = async (
     context.issueNumber,
     markerBody({ ...provisional, nonce }),
   );
-  const winner = await winningMarkerId(context, provisional);
-  if (winner !== markerId) {
-    await deleteComment(context.token, context.repo, markerId);
+  const election = await reconcileTrustedClaimElection(context, provisional);
+  if (election.retainedId !== markerId) {
+    if (!election.markerIds.includes(markerId)) {
+      await deleteComment(context.token, context.repo, markerId);
+    }
     return null;
   }
   return { ...provisional, markerId };
 };
 
+export const startClaim = async (
+  deps: JobDeps,
+  issueNumber: number,
+  approval: ApprovalBinding,
+  kind: PollerJobKind,
+): Promise<ClaimBinding | null> => {
+  await reconcileExistingQueuedJob(deps, issueNumber, approval, kind);
+  const claimLabel = inProgressLabelFor(kind);
+  await reconcileTrustedClaimHistory(
+    { token: deps.token, repo: deps.repo, issueNumber },
+    claimLabel,
+  );
+  await addLabels(deps.token, deps.repo, issueNumber, [claimLabel]);
+  return acquireClaim(
+    { token: deps.token, repo: deps.repo, issueNumber },
+    approval,
+    claimLabel,
+  );
+};
+
 export const validateClaim = async (
   context: ClaimContext,
   claim: ClaimBinding,
@@ -182,8 +136,57 @@ export const validateClaim = async (
   if (!hasLabel(issue.labels, claim.claimLabel)) {
     return `"${claim.claimLabel}" is no longer present`;
   }
-  const winner = await winningMarkerId(context, claim);
-  return winner === claim.markerId
+  const election = await reconcileTrustedClaimElection(context, claim);
+  return election.retainedId === claim.markerId
     ? null
     : 'claim ownership changed or could not be proven';
 };
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const releaseOwnedClaim = async (
+  deps: JobDeps,
+  issueNumber: number,
+  claim: ClaimBinding,
+): Promise<void> => {
+  const context = { token: deps.token, repo: deps.repo, issueNumber };
+  const election = await reconcileTrustedClaimElection(context, claim);
+  const issue = await getIssue(deps.token, deps.repo, issueNumber);
+  const event = await lastLabelEvent(
+    deps.token,
+    deps.repo,
+    issueNumber,
+    claim.claimLabel,
+  );
+  if (
+    election.retainedId === claim.markerId &&
+    hasLabel(issue.labels, claim.claimLabel) &&
+    String(event?.id) === claim.claimEpoch
+  ) {
+    await removeLabel(deps.token, deps.repo, issueNumber, claim.claimLabel);
+  }
+};
+
+export const withClaimReleasedOnFailure = async <Result>(
+  deps: JobDeps,
+  issueNumber: number,
+  claim: ClaimBinding,
+  operation: () => Promise<Result>,
+): Promise<Result> => {
+  try {
+    return await operation();
+  } catch (operationError) {
+    try {
+      await releaseOwnedClaim(deps, issueNumber, claim);
+    } catch (releaseError) {
+      throw new Error(
+        `${errorMessage(operationError)}; releasing the claim for an automatic retry also failed: ${errorMessage(releaseError)}`,
+        {
+          cause: releaseError,
+        },
+      );
+    }
+    throw operationError;
+  }
+};

package/src/poller-comment-reconciliation.ts

@@ -0,0 +1,29 @@
+import { deleteComment } from './poller-github-write';
+
+type CommentContext = {
+  readonly token: string | null;
+  readonly repo: string;
+};
+
+export const earliestCommentId = (
+  commentIds: ReadonlyArray<number>,
+): number | null =>
+  commentIds.reduce<number | null>(
+    (earliest, commentId) =>
+      earliest === null || commentId < earliest ? commentId : earliest,
+    null,
+  );
+
+export const retainEarliestComment = async (
+  context: CommentContext,
+  commentIds: ReadonlyArray<number>,
+): Promise<number | null> => {
+  const retainedId = earliestCommentId(commentIds);
+  for (const commentId of commentIds) {
+    if (commentId !== retainedId) {
+      // biome-ignore lint/performance/noAwaitInLoops: GitHub mutations are deliberately serialized to avoid secondary rate limits.
+      await deleteComment(context.token, context.repo, commentId);
+    }
+  }
+  return retainedId;
+};

package/src/poller-fix-run.ts

@@ -3,7 +3,7 @@
 import { join } from 'node:path';
 import { hasLabel } from './github-label-identity';
 import { approvalIsCurrent, issueRevision } from './poller-approval';
-import { acquireClaim } from './poller-claim';
+import { startClaim, withClaimReleasedOnFailure } from './poller-claim';
 import { runCodex } from './poller-codex';
 import { handleNonFixedOutcome } from './poller-fix-outcome';
 import { readSealedFixOutput } from './poller-fix-output';
@@ -14,7 +14,6 @@ import {
   validateFixClaim,
 } from './poller-fix-publication';
 import { getIssue, type IssueItem } from './poller-github';
-import { addLabels } from './poller-github-write';
 import {
   failJob,
   type JobDeps,
@@ -118,12 +117,7 @@ export const runFixJob = async (
     await acknowledgeQueuedJob(deps, issue.number, preamble.approval, 'fix');
     return result(issue.number, 'waiting for run capacity');
   }
-  await addLabels(token, repo, issue.number, [FIX_IN_PROGRESS]);
-  const claim = await acquireClaim(
-    { token, repo, issueNumber: issue.number },
-    preamble.approval,
-    FIX_IN_PROGRESS,
-  );
+  const claim = await startClaim(deps, issue.number, preamble.approval, 'fix');
   if (claim === null) {
     return result(issue.number, 'another poller owns the claim');
   }
@@ -138,7 +132,11 @@ export const runFixJob = async (
   if (sealed !== null) {
     assertSealedOwnership(sealed, issue.number, claim.approval.id, branch);
     return {
-      lines: [await publishFixedOutput(resumableJob, FIX_LABELS, sealed, null)],
+      lines: [
+        await withClaimReleasedOnFailure(deps, issue.number, claim, () =>
+          publishFixedOutput(resumableJob, FIX_LABELS, sealed, null),
+        ),
+      ],
       ranCodex: false,
     };
   }
@@ -186,8 +184,13 @@ export const runFixJob = async (
       };
     }
     const nonFixed = await handleNonFixedOutcome(job, FIX_LABELS, outcome);
+    const message =
+      nonFixed ??
+      (await withClaimReleasedOnFailure(deps, issue.number, claim, () =>
+        finishFixedJob(job, FIX_LABELS, outcome),
+      ));
     return {
-      lines: [nonFixed ?? (await finishFixedJob(job, FIX_LABELS, outcome))],
+      lines: [message],
       ranCodex: true,
     };
   } finally {

package/src/poller-queue-marker.ts

@@ -182,13 +182,14 @@ export const inspectQueuedAcknowledgement = async (options: {
     item.number,
     expectedLabel,
   );
-  return (
-    event !== null &&
-    checkpoints.some(
-      (checkpoint) =>
-        checkpoint.eventId === event.id &&
-        checkpoint.actorLogin === event.actorLogin &&
-        checkpoint.approvedAt === event.createdAt,
-    )
-  );
+  if (event === null) {
+    return false;
+  }
+  const currentCheckpointCount = checkpoints.filter(
+    (checkpoint) =>
+      checkpoint.eventId === event.id &&
+      checkpoint.actorLogin === event.actorLogin &&
+      checkpoint.approvedAt === event.createdAt,
+  ).length;
+  return currentCheckpointCount === 1;
 };

package/src/poller-review-execution.ts

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import type { ClaimBinding } from './poller-claim';
+import { type ClaimBinding, withClaimReleasedOnFailure } from './poller-claim';
 import type { runCodex } from './poller-codex';
 import type { PullRequest } from './poller-github-pulls';
 import {
@@ -95,14 +95,16 @@ export const executeReviewJob = async (options: {
     }
     return {
       lines: [
-        await finishReviewedJob({
-          deps,
-          labels,
-          pr,
-          claim,
-          workDir: workspace.dir,
-          outcome,
-        }),
+        await withClaimReleasedOnFailure(deps, pr.number, claim, () =>
+          finishReviewedJob({
+            deps,
+            labels,
+            pr,
+            claim,
+            workDir: workspace.dir,
+            outcome,
+          }),
+        ),
       ],
       ranCodex: true,
     };

package/src/poller-review-run.ts

@@ -6,11 +6,10 @@
 
 import { hasLabel } from './github-label-identity';
 import { approvalIsCurrent, prRevision } from './poller-approval';
-import { acquireClaim } from './poller-claim';
+import { startClaim, withClaimReleasedOnFailure } from './poller-claim';
 import { runCodex } from './poller-codex';
 import { getIssue, type IssueItem } from './poller-github';
 import { getPullRequest } from './poller-github-pulls';
-import { addLabels } from './poller-github-write';
 import {
   failJob,
   type JobDeps,
@@ -86,7 +85,7 @@ export const runReviewJob = async (
     };
   }
   const pr = await getPullRequest(token, repo, prItem.number);
-  let plan = await currentReviewPlan(deps, pr);
+  const plan = await currentReviewPlan(deps, pr);
   const readTarget = () => currentReviewTarget(token, repo, pr.number, plan);
   const preamble = await jobPreamble(deps, currentItem, REVIEW_LABELS, {
     approved: prRevision(
@@ -157,32 +156,29 @@ export const runReviewJob = async (
       ranCodex: false,
     };
   }
-  await addLabels(token, repo, prItem.number, [REVIEW_IN_PROGRESS]);
-  const claim = await acquireClaim(
-    { token, repo, issueNumber: pr.number },
-    preamble.approval,
-    REVIEW_IN_PROGRESS,
-  );
+  const claim = await startClaim(deps, pr.number, preamble.approval, 'review');
   if (claim === null) {
     return {
       lines: [`PR #${pr.number}: another poller owns the claim`],
       ranCodex: false,
     };
   }
-  if (plan === null && sealed !== null) {
-    await publishReviewPlan(deps, pr, claim, sealed);
-    plan = sealed;
-  }
-  if (plan !== null) {
+  const resumablePlan = plan ?? sealed;
+  if (resumablePlan !== null) {
     return {
       lines: [
-        await resumeReviewedJob({
-          deps,
-          labels: REVIEW_LABELS,
-          pr,
-          claim,
-          plan,
-          cloneDir: cacheClone,
+        await withClaimReleasedOnFailure(deps, pr.number, claim, async () => {
+          if (plan === null) {
+            await publishReviewPlan(deps, pr, claim, resumablePlan);
+          }
+          return resumeReviewedJob({
+            deps,
+            labels: REVIEW_LABELS,
+            pr,
+            claim,
+            plan: resumablePlan,
+            cloneDir: cacheClone,
+          });
         }),
       ],
       ranCodex: false,

package/src/poller-schedule.ts

@@ -1,4 +1,5 @@
 import { hasLabel } from './github-label-identity';
+import { reconcileTrustedClaimHistory } from './poller-claim-reconciliation';
 import {
   type IssueItem,
   lastLabelEvent,
@@ -47,6 +48,10 @@ const sweepStaleClaims = async (
         ? Number.POSITIVE_INFINITY
         : now - Date.parse(event.createdAt);
     if (ageMs > config.staleClaimHours * MS_PER_HOUR) {
+      await reconcileTrustedClaimHistory(
+        { token, repo, issueNumber: item.number },
+        claimLabel,
+      );
       await removeLabel(token, repo, item.number, claimLabel);
       await createComment(
         token,

package/src/poller-status.ts

@@ -6,6 +6,7 @@ import {
   readApprovalBinding,
 } from './poller-approval';
 import { hiddenCommentMetadata } from './poller-comment-metadata';
+import { retainEarliestComment } from './poller-comment-reconciliation';
 import { getIssue } from './poller-github';
 import { getPullRequest } from './poller-github-pulls';
 import { createComment, deleteComment } from './poller-github-write';
@@ -94,16 +95,14 @@ export const acknowledgeQueuedJob = async (
   ) {
     return false;
   }
-  if (
-    (
-      await matchingTrustedQueueCommentIds(
-        deps,
-        issueNumber,
-        expected.approvalId,
-        kind,
-      )
-    ).length > 0
-  ) {
+  const existingMarkerIds = await matchingTrustedQueueCommentIds(
+    deps,
+    issueNumber,
+    expected.approvalId,
+    kind,
+  );
+  if (existingMarkerIds.length > 0) {
+    await retainEarliestComment(deps, existingMarkerIds);
     return false;
   }
   const markerId = await createComment(
@@ -115,16 +114,17 @@ export const acknowledgeQueuedJob = async (
       expected,
     )}`,
   );
-  const [winner] = [
-    ...(await matchingTrustedQueueCommentIds(
-      deps,
-      issueNumber,
-      expected.approvalId,
-      kind,
-    )),
-  ].sort((left, right) => left - right);
+  const markerIds = await matchingTrustedQueueCommentIds(
+    deps,
+    issueNumber,
+    expected.approvalId,
+    kind,
+  );
+  const winner = await retainEarliestComment(deps, markerIds);
   if (winner !== markerId) {
-    await deleteComment(deps.token, deps.repo, markerId);
+    if (!markerIds.includes(markerId)) {
+      await deleteComment(deps.token, deps.repo, markerId);
+    }
     return false;
   }
   if (!(await isStillQueueable(deps, issueNumber, approval, kind))) {
@@ -133,3 +133,18 @@ export const acknowledgeQueuedJob = async (
   }
   return true;
 };
+
+export const reconcileExistingQueuedJob = async (
+  deps: JobDeps,
+  issueNumber: number,
+  approval: ApprovalBinding,
+  kind: PollerJobKind,
+): Promise<void> => {
+  const markerIds = await matchingTrustedQueueCommentIds(
+    deps,
+    issueNumber,
+    approval.id,
+    kind,
+  );
+  await retainEarliestComment(deps, markerIds);
+};