Put a verdict out of date when its trunk moves, and refuse a merge on one

A merge check's verdict now names the trunk commit it judged (novox/hq ADR
0323, issue 341), but the forge kept it green after another merge moved the
trunk, the merge tool merged on it, and mesh-delivery kept the delivery ready.
The forge's holder puts both statuses of every open pull request into a moved
trunk back to pending with the reason and runs nothing; the merge tool compares
the verdict's trunk commit with the trunk's head, asks the check once and never
merges by itself; mesh-delivery sends a ready delivery back to proposed, counts
only a verdict for the trunk's head, and composes a group again for a rebased
member instead of holding it.

modules/gitea/tools/index.ts

@@ -13,6 +13,8 @@ import { emit } from "@novox/mesh-sdk/events";
 import { GiteaClient, type BranchProtection } from "../client.js";
 import { appendNote, run, viewBody, viewComment } from "../delivery.js";
 import { containedFrom, isCommit, mergeableUnder, newestByContext } from "../checks.js";
+import { CHECK_CONTEXT, REPO_CHECK_CONTEXT } from "../pulls.js";
+import { announcementOf, askedWords, outOfDateWords, tookFile, tookWords, twelve, verdictAtTrunk } from "../trunk.js";
 import {
   MERGE_METHODS, Refused, checkName, judgeApiCall, judgeContentsWrite, judgeDelete, judgeProtectionChange, pathSegments, routedPath, sentQuery,
   ruleCovers,
@@ -59,11 +61,19 @@ function namesChecked(tools: ToolDefinition[]): ToolDefinition[] {
   }));
 }
 
-export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] {
-  return namesChecked(allGiteaTools(gitea));
+/** What the tools reach beside the forge: how an event is said, the module's state directory, and the clock. */
+export interface ToolDeps {
+  emit?: (type: string, body: unknown) => Promise<void>;
+  stateDir?: string;
+  now?: () => Date;
 }
 
-function allGiteaTools(gitea: GiteaClient): ToolDefinition[] {
+export function getGiteaTools(gitea: GiteaClient, deps: ToolDeps = {}): ToolDefinition[] {
+  return namesChecked(allGiteaTools(gitea, { emit: deps.emit ?? emit, stateDir: deps.stateDir ?? process.env.MESH_GITEA_STATE_DIR,
+    now: deps.now ?? (() => new Date()) }));
+}
+
+function allGiteaTools(gitea: GiteaClient, deps: Required<Pick<ToolDeps, "emit" | "now">> & ToolDeps): ToolDefinition[] {
   return [
     // ---- Repositories ----
     {
@@ -267,8 +277,11 @@ function allGiteaTools(gitea: GiteaClient): ToolDefinition[] {
       name: "gitea_merge_pull_request",
       description: "Merge a pull request at the head you name — the commit you reviewed — when that is still its head " +
         "and every status its base branch's protection requires succeeded there (mesh/merge-gate, mesh/repo-check), " +
-        "optionally deleting the source branch afterwards. Refused otherwise, with nothing merged: no tool merges past " +
-        "a check, and none merges a head that moved after it was reviewed.",
+        "judged against the trunk's head as it is now, optionally deleting the source branch afterwards. Refused " +
+        "otherwise, with nothing merged: no tool merges past a check, and none merges a head that moved after it was " +
+        "reviewed. A verdict judged against an earlier trunk commit is refused, naming both, and the head's check against " +
+        "the trunk's head is asked once, with how long the last check of the repository took: ask again at the same head " +
+        "once it passes — the tool never merges by itself.",
       input: {
         owner: { type: "string", description: "the repository owner" },
         repo: { type: "string", description: "the repository name" },
@@ -319,6 +332,47 @@ function allGiteaTools(gitea: GiteaClient): ToolDefinition[] {
           throw new Refused(`${owner}/${repo}#${number} merges into ${pull.base}, which no protection rule requiring ` +
             `the checks guards: a tool merges only into such a branch (novox/hq ADR 0266). Nothing was merged`);
         }
+        // **The verdict must be judged against the trunk's head** (novox/hq ADR 0323 §5, issue 341): a check judges the
+        // head merged into a named trunk commit, and a merge of another trunk is not the one that check judged. Compared
+        // here at the moment the merge is asked, not left to the statuses the trunk's move resets a pass later. When they
+        // differ nothing is merged, and the head's check against the trunk's head is asked once — the announcement a new
+        // head makes — never again while one is on its way. The caller asks again at the reviewed head once it passes.
+        const trunkHead = await gitea.branchHead(owner, repo, pull.base);
+        const checks = await gitea.headChecks(owner, repo, pull.head_sha);
+        const at = verdictAtTrunk(checks, trunkHead);
+        if (!at.current) {
+          const judged = at.judged ? `was judged against trunk ${twelve(at.judged)}` : "names no trunk commit it was judged against";
+          const took = tookWords(tookFile(deps.stateDir), `${owner}/${repo}`);
+          const head = twelve(pull.head_sha), now = twelve(trunkHead);
+          if (at.onItsWay) {
+            throw new Refused(`${owner}/${repo}#${number} is not merged: its verdict ${judged}, and ${pull.base} is now ` +
+              `${now}. Its check is already asked and not yet answered (${checks[CHECK_CONTEXT]?.description}), so it is not ` +
+              `asked again; ${took}. Ask again at ${head} once both statuses pass: this tool never merges by itself ` +
+              `(novox/hq ADR 0323). Nothing was merged`);
+          }
+          // Pending first, so a second ask finds the check on its way; then the head is announced as a new head is. An
+          // announcement that cannot be made puts the statuses back to out of date, so the next ask asks again rather
+          // than wait for ever on a check nobody asked.
+          const contexts = [CHECK_CONTEXT, ...(checks[REPO_CHECK_CONTEXT] ? [REPO_CHECK_CONTEXT] : [])];
+          const say = async (description: string) => {
+            for (const context of contexts) {
+              await gitea.setCommitStatus(owner, repo, pull.head_sha, { state: "pending", context, description,
+                ...(pull.html_url ? { target_url: pull.html_url } : {}) });
+            }
+          };
+          await say(askedWords(deps.now(), trunkHead));
+          try {
+            const cloneURL = (await gitea.getRepo(owner, repo)).clone_url;
+            await deps.emit("pull.updated", await announcementOf(gitea, owner, repo, cloneURL, pull));
+          } catch (err) {
+            await say(outOfDateWords(at.judged, trunkHead)).catch(() => {});
+            throw new Error(`${owner}/${repo}#${number} is not merged: its verdict ${judged}, and ${pull.base} is now ` +
+              `${now}, and its check could not be asked: ${err instanceof Error ? err.message : err}. Nothing was merged`);
+          }
+          throw new Refused(`${owner}/${repo}#${number} is not merged: its verdict ${judged}, and ${pull.base} is now ` +
+            `${now}. The check of head ${head} merged into trunk ${now} was asked; ${took}. Ask again at ${head} once both ` +
+            `statuses pass: this tool never merges by itself (novox/hq ADR 0323). Nothing was merged`);
+        }
         const statuses = newestByContext((await gitea.combinedStatus(owner, repo, pull.head_sha)).statuses);
         const verdict = mergeableUnder(pull.base, rule, statuses);
         if (verdict.mergeable !== true) {
@@ -714,7 +768,7 @@ function allGiteaTools(gitea: GiteaClient): ToolDefinition[] {
 // way, gitea contributes none rather than failing the whole runtime, and says why.
 registerModuleTools("gitea", (env) => {
   try {
-    return getGiteaTools(GiteaClient.fromEnv(env));
+    return getGiteaTools(GiteaClient.fromEnv(env), { stateDir: env.MESH_GITEA_STATE_DIR });
   } catch (err) {
     console.log(`[gitea] no tools — ${err instanceof Error ? err.message : String(err)}`);
     return [];