@volter/twin-github 0.1.2 → 2.0.0

package/src/semantics/pulls.ts

@@ -0,0 +1,421 @@
+// GitHub's pulls family: pull requests (create, read, list with GitHub's filters, edit), their
+// reviews (submit, dismiss, edit; the implicit review that wraps a standalone review comment), review
+// comments and replies, files and commits (carried by a local write, or read from the git plane),
+// requested reviewers, updating the branch, and merging through the gates (draft, required checks,
+// rulesets) into the plane. The pulls family answers for pull requests only: `state.prs` also holds
+// the counter shells the projection makes for issue numbers, so every door reads `is_pull_request`.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import {
+  authorAssociation,
+  applyTriageFields, GITHUB_WORLD_USER, githubNotFound, hasBareRepo, implicitReviewId, listGitPlaneRefs, mergePullRequest, nextRepoNumber,
+  mergeIntoBranchInPlane, normalizeLogins, paginate, planeAncestors, syncPrHeadsToBranchTip, planeCommitBody, prPlaneDiffFiles, readGitCommitFromPlane, resolvePlaneRef, reviewStateForEvent, serializeReviewComment,
+  toAssignees, toGithubIssue, toGithubPullFile, toGithubRest, toGithubReview, type GithubPr, type GithubReview, type GithubState,
+} from '../github-twin.ts';
+import { announce, asView, gh, nextSeq, put, send, writer, type Gh } from './shared.ts';
+import { assignable } from './repos.ts';
+import { closingIssueNumbers } from './push-reactions.ts';
+
+const numberOf = (g: Gh): number => Number(decodeURIComponent(g.seg[4]!));
+/** `owner`'s repository in `repo`'s network (the forks of one root, docs.github.com/pull-requests/collaborating-with-
+ *  pull-requests/working-with-forks/about-forks), or nothing. */
+function forkInNetwork(st: GithubState, repo: string, owner: string): string | undefined {
+  const rootOf = (name: string): string => {
+    let at = name;
+    for (let hops = 0; hops < 50; hops++) { const parent = st.repos.find((r) => r.full_name === at)?.parent_full_name; if (!parent) break; at = parent; }
+    return at;
+  };
+  const network = rootOf(repo);
+  return st.repos.find((r) => r.owner.toLowerCase() === owner.toLowerCase() && r.full_name !== repo && rootOf(r.full_name) === network)?.full_name;
+}
+/** The pull request a path names, as a pull request (never an issue's counter shell). */
+const pullOf = (g: Gh): GithubPr | undefined => {
+  const n = numberOf(g);
+  return g.state().prs.find((p) => p.repository === g.repo && p.number === n && p.is_pull_request);
+};
+/** A door INTO a pull request 404s when nobody opened it: an empty list would say it is real and quiet. */
+const intoPull = (serve: (ctx: SemanticsContext, g: Gh, pr: GithubPr, n: number) => Promise<Response>): Semantics => async (ctx) => {
+  const g = gh(ctx);
+  const pr = pullOf(g);
+  return pr ? serve(ctx, g, pr, pr.number) : send(ctx, githubNotFound());
+};
+
+/** A pull request as GitHub answers it whole: its fields, the counts GitHub computes (commits, changed files,
+ *  additions, deletions, issue comments and review comments) each from what the list endpoints answer unless
+ *  the stored pull request carries it (an observed one's pulled counts), and its mergeability. */
+async function fullPull(g: Gh, pr: GithubPr): Promise<Record<string, unknown>> {
+  const st = g.state();
+  const files = await filesOf(g, pr);
+  const commits = (await planeCommitsOf(g, pr))?.length ?? pr.commits ?? 0;
+  const on = (kind: string) => st.comments.filter((c) => c.repository === pr.repository && c.number === pr.number && c.kind === kind).length;
+  return {
+    ...toGithubRest(pr, st.milestones),
+    commits: pr.commits ?? commits,
+    changed_files: pr.changed_files ?? files.length,
+    additions: pr.additions ?? files.reduce((n, f) => n + (Number(f.additions) || 0), 0),
+    deletions: pr.deletions ?? files.reduce((n, f) => n + (Number(f.deletions) || 0), 0),
+    comments: on('issue'),
+    review_comments: on('review'),
+    ...(await mergeability(g, pr)),
+  };
+}
+
+/** Write a pull request's fields and answer it as GitHub renders it (whole, or as the operation's view), announcing `action`. */
+async function writePull(ctx: SemanticsContext, g: Gh, number: number, operation: string, fields: Record<string, unknown>, action: string, status = 200, view?: string): Promise<Response> {
+  const id = `${g.repo}#${number}`;
+  await put(ctx, { operation, subjectType: 'pull_request', subjectId: id, fields: { number, repository: g.repo, ...fields } });
+  const st = g.state();
+  const found = st.prs.find((p) => p.id === id);
+  const out = found ? toGithubRest(found, st.milestones) : { number };
+  await announce(ctx, [{ event: 'pull_request', action, repository: g.repo, number, pr: out }]);
+  return ctx.reply(view ? asView(view, out) : found ? await fullPull(g, found) : out, status);
+}
+
+export function pullsSemantics(): Record<string, Semantics> {
+  return {
+    // GitHub's filters: state (open|closed|all, default open), head (owner:branch or branch), base.
+    // The default order is newest first; a pull request's number is its creation order.
+    'pulls/list': async (ctx) => {
+      const { repo, query, state } = gh(ctx);
+      const st = state();
+      const lp = new URLSearchParams((query ?? '').replace(/^\?/, ''));
+      const stateF = (lp.get('state') ?? 'open').toLowerCase();
+      const headF = lp.get('head') ?? undefined;
+      const baseF = lp.get('base') ?? undefined;
+      const headBranch = headF !== undefined ? (headF.includes(':') ? headF.slice(headF.indexOf(':') + 1) : headF) : undefined;
+      // `head` is user:ref-name; the user is whoever holds the head branch (the fork's owner for a pull request from a fork)
+      const headUser = headF?.includes(':') ? headF.slice(0, headF.indexOf(':')).toLowerCase() : undefined;
+      const filtered = st.prs.filter((p) => p.repository === repo && p.is_pull_request).filter((p) => {
+        const prState = p.merged ? 'closed' : (p.state ?? 'open');
+        if (stateF !== 'all' && prState !== stateF) return false;
+        if (headBranch !== undefined && p.head_ref !== headBranch && p.head_sha !== headBranch) return false;
+        if (headUser !== undefined && (p.head_repo ?? p.repository).split('/')[0]!.toLowerCase() !== headUser) return false;
+        if (baseF !== undefined && p.base_ref !== baseF) return false;
+        return true;
+      });
+      const dirP = (lp.get('direction') ?? 'desc').toLowerCase() === 'asc' ? 1 : -1;
+      return ctx.reply(paginate([...filtered].sort((a, b) => (a.number - b.number) * dirP), query).map((p) => asView('pull-request-simple', toGithubRest(p, st.milestones))));
+    },
+    // GitHub's pull request carries its counts (commits, changed_files, additions, deletions, comments,
+    // review_comments; all required by the schema): each from what the list endpoints answer, unless the
+    // stored pull request already carries it (an observed one's pulled counts)
+    'pulls/get': async (ctx) => {
+      const g = gh(ctx);
+      const pr = pullOf(g);
+      if (!pr) return send(ctx, githubNotFound());
+      return send(ctx, { status: 200, body: await fullPull(g, pr) });
+    },
+    // 204 when merged, else 404
+    'pulls/check-if-merged': async (ctx) => send(ctx, pullOf(gh(ctx))?.merged ? { status: 204, body: undefined } : githubNotFound()),
+    // one review comment, addressed without its pull request
+    'pulls/get-review-comment': async (ctx) => {
+      const { repo, seg, state } = gh(ctx);
+      const cid = Number(decodeURIComponent(seg[5]!));
+      const c = state().comments.find((x) => x.repository === repo && x.kind === 'review' && x.id === cid);
+      return send(ctx, c ? { status: 200, body: serializeReviewComment(c) } : githubNotFound());
+    },
+    // The IMPLICIT REVIEW rides the list, as on GitHub: a review comment posted on its own is wrapped
+    // in a review, synthesized from the comments naming it (submitted at the earliest, authored by the
+    // first, COMMENTED), never stored; the projection counts it into the review count the same way.
+    'pulls/list-reviews': intoPull(async (ctx, g, _pr, n) => {
+      const st = g.state();
+      const items: GithubReview[] = st.reviews.filter((r) => r.repository === g.repo && r.number === n);
+      const wrapperId = implicitReviewId(g.repo, n);
+      const wrapped = st.comments.filter((c) => c.repository === g.repo && c.number === n && c.kind === 'review' && c.review_id === wrapperId);
+      if (wrapped.length > 0) {
+        const dated = wrapped.map((c) => c.created_at).filter((d): d is string => d !== undefined).sort();
+        const author = wrapped.find((c) => c.user_login !== undefined);
+        items.push({
+          id: wrapperId, repository: g.repo, number: n, state: 'COMMENTED', body: '',
+          ...(dated[0] !== undefined ? { submitted_at: dated[0] } : {}),
+          ...(author?.user_login !== undefined ? { user_login: author.user_login } : {}),
+          ...(author?.user_type !== undefined ? { user_type: author.user_type } : {}),
+        });
+      }
+      return ctx.reply(paginate(items, g.query).map(toGithubReview));
+    }),
+    // one review, on the (repo, number, id) the dismiss and edit writes use
+    'pulls/get-review': intoPull(async (ctx, g, _pr, n) => {
+      const rid = Number(decodeURIComponent(g.seg[6]!));
+      const r = g.state().reviews.find((x) => x.repository === g.repo && x.number === n && x.id === rid);
+      return send(ctx, r ? { status: 200, body: toGithubReview(r) } : githubNotFound());
+    }),
+    // the diff-thread comments (with their diff anchors when a local write set them)
+    'pulls/list-review-comments': intoPull(async (ctx, g, _pr, n) =>
+      ctx.reply(paginate(g.state().comments.filter((c) => c.repository === g.repo && c.number === n && c.kind === 'review'), g.query).map(serializeReviewComment))),
+    // The plane's real diff when the base and head both exist there (an observed pull request with a
+    // pulled count but no per-file evidence keeps none, so the list never contradicts its own count).
+    'pulls/list-files': intoPull(async (ctx, g, pr) => ctx.reply(paginate(await filesOf(g, pr), g.query).map((f) => toGithubPullFile(g.repo, pr.head_sha ?? '', f)))),
+    // In a repository with history, the plane's commits: those the head reaches that the base did not
+    // hold (a merged one's base is its merge commit's first parent), oldest first; none without history.
+    'pulls/list-commits': intoPull(async (ctx, g, pr) => {
+      const plane = await planeCommitsOf(g, pr);
+      if (plane) {
+        const bodies = [];
+        for (const sha of paginate(plane, g.query)) { const b = await planeCommitBody(g.repo, sha, g.root); if (b) bodies.push(b); }
+        return ctx.reply(bodies);
+      }
+      return ctx.reply([]);
+    }),
+    // {users, teams}: teams are not modeled
+    'pulls/list-requested-reviewers': intoPull(async (ctx, _g, pr) => ctx.reply({ users: toAssignees(pr.requested_reviewers), teams: [] })),
+    // 422 without title, head and base. `head` may be owner:branch, a branch, a ref or a sha: the branch
+    // is the head ref; its tip (a registered ref or branch) is head_sha. In a repository whose history
+    // is in the plane, a head branch that does not exist there is GitHub's 422. An `owner:branch` head whose owner
+    // is not this repository's names that owner's fork in the same network, and the branch is read there
+    // (docs.github.com/rest/pulls/pulls#create-a-pull-request: "For cross-repository pull requests in the same
+    // network, namespace head with a user like this: username:branch"); an owner with no fork in the network is 422.
+    'pulls/create': async (ctx) => {
+      const { repo, body, occurredAt, caller, root, state } = gh(ctx);
+      const missing = (['title', 'head', 'base'] as const).filter((k) => !body[k]);
+      if (missing.length) return ctx.reply({ message: 'Validation Failed', errors: missing.map((field) => ({ resource: 'PullRequest', field, code: 'missing_field' })) }, 422);
+      const number = nextRepoNumber(state(), repo);
+      const id = `${repo}#${number}`;
+      const headRaw = String(body.head);
+      const headRef = headRaw.includes(':') ? headRaw.slice(headRaw.indexOf(':') + 1) : headRaw;
+      const branchName = headRef.replace(/^refs\/heads\//, '');
+      const invalidHead = () => ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PullRequest', field: 'head', code: 'invalid' }], documentation_url: 'https://docs.github.com/rest/pulls/pulls#create-a-pull-request' }, 422);
+      const headOwner = headRaw.includes(':') ? headRaw.slice(0, headRaw.indexOf(':')) : undefined;
+      let headRepo = repo;
+      if (headOwner !== undefined && headOwner.toLowerCase() !== repo.split('/')[0]!.toLowerCase()) {
+        const fork = forkInNetwork(state(), repo, headOwner);
+        if (!fork) return invalidHead();
+        headRepo = fork;
+      }
+      let resolvedHeadSha = headRaw;
+      if (!/^[0-9a-f]{40}$/i.test(headRaw)) {
+        const st0 = state();
+        const tip = st0.gitRefs.find((x) => x.repository === headRepo && x.ref === `refs/heads/${branchName}`)?.object_sha
+          ?? st0.branches.find((b) => b.repository === headRepo && b.name === branchName)?.commit_sha;
+        if (tip) resolvedHeadSha = tip;
+        else if (headRepo !== repo || (hasBareRepo(repo, root) && !(await listGitPlaneRefs(repo, root)).some((r) => r.ref === `refs/heads/${branchName}`))) return invalidHead();
+      }
+      const fields: Record<string, unknown> = { number, repository: repo, ...(headRepo !== repo ? { head_repo: headRepo } : {}), title: body.title, body: body.body, base_ref: body.base, head_sha: resolvedHeadSha, head_ref: branchName, state: 'open', user_login: caller ?? 'octocat', user_type: 'User', created_at: occurredAt, author_association: authorAssociation(state(), repo, caller ?? 'octocat'), maintainer_can_modify: body.maintainer_can_modify === true };
+      if (body.draft !== undefined) fields.draft = body.draft === true;
+      await put(ctx, { operation: 'pull_request.create', subjectType: 'pull_request', subjectId: id, fields });
+      // read back through the projection, so the derived counts agree with the carried lists
+      const st = state();
+      const created = st.prs.find((p) => p.id === id) ?? { id, number, repository: repo, review_count: 0, comment_count: 0, title: body.title, body: body.body, base_ref: body.base, head_sha: resolvedHeadSha, head_ref: branchName, state: 'open' };
+      const out = toGithubRest(created, st.milestones);
+      await announce(ctx, [{ event: 'pull_request', action: 'opened', repository: repo, number, pr: out }]);
+      const stored = st.prs.find((p) => p.id === id);
+      return ctx.reply(stored ? await fullPull(gh(ctx), stored) : out, 201);
+    },
+    // REST has no draft parameter on an edit (draft transitions are GraphQL mutations)
+    'pulls/update': intoPull(async (ctx, g, pr, number) => {
+      const { body } = g;
+      const fields: Record<string, unknown> = {};
+      if (body.title !== undefined) fields.title = body.title;
+      if (body.body !== undefined) fields.body = body.body;
+      if (body.base !== undefined) fields.base_ref = body.base;
+      if (body.state !== undefined) fields.state = body.state;
+      applyTriageFields(fields, body);
+      const reopening = body.state === 'open' && (pr.state ?? 'open') === 'closed';
+      return writePull(ctx, g, number, 'pull_request.update', fields, body.state === 'closed' ? 'closed' : reopening ? 'reopened' : 'edited');
+    }),
+    // A review binds to the pull request's head at submission (its commit_id; a caller may pin one),
+    // which is the exact-head semantic merge gates rely on. Inline `comments` become review comments
+    // wrapped by THIS review.
+    'pulls/create-review': intoPull(async (ctx, g, pr, number) => {
+      const { repo, body, occurredAt, caller } = g;
+      const seq = nextSeq(ctx, 'review');
+      const commitId = body.commit_id !== undefined ? String(body.commit_id) : pr.head_sha;
+      const fields: Record<string, unknown> = { repository: repo, number, state: reviewStateForEvent(body.event), body: body.body, submitted_at: occurredAt, user_login: caller ?? GITHUB_WORLD_USER, author_association: authorAssociation(g.state(), repo, caller ?? GITHUB_WORLD_USER) };
+      if (commitId !== undefined) fields.commit_id = commitId;
+      await put(ctx, { operation: 'pull_request_review.submit', subjectType: 'pull_request_review', subjectId: `review:${seq}`, fields });
+      if (Array.isArray(body.comments)) {
+        for (const raw of body.comments as Array<Record<string, unknown>>) {
+          const cSeq = nextSeq(ctx, 'comment');
+          const cFields: Record<string, unknown> = { repository: repo, number, body: raw.body, created_at: occurredAt, updated_at: occurredAt, review_id: seq, user_login: caller ?? GITHUB_WORLD_USER, author_association: authorAssociation(g.state(), repo, caller ?? GITHUB_WORLD_USER), ...(commitId !== undefined ? { commit_id: commitId } : {}) };
+          if (raw.path !== undefined) cFields.path = String(raw.path);
+          if (raw.line !== undefined) cFields.line = Number(raw.line);
+          if (raw.side !== undefined) cFields.side = String(raw.side);
+          if (raw.start_line !== undefined) cFields.start_line = Number(raw.start_line);
+          await put(ctx, { operation: 'pull_request_review_comment.create', subjectType: 'pull_request_review_comment', subjectId: `comment:${cSeq}`, fields: cFields });
+        }
+      }
+      const review = toGithubReview(g.state().reviews.find((r) => r.repository === repo && r.number === number && r.id === seq)!);
+      await announce(ctx, [{ event: 'pull_request_review', action: 'submitted', repository: repo, number, review }]);
+      return ctx.reply(review);
+    }),
+    // dismiss (a message is required) or edit a submitted review's body: an overlay on the review
+    'pulls/dismiss-review': async (ctx) => reviewOverlay(ctx, 'dismiss'),
+    'pulls/update-review': async (ctx) => reviewOverlay(ctx, 'update'),
+    // A reply IN a review thread: it inherits the root comment's diff anchor and threads by
+    // in_reply_to; it rides the pull request's implicit review (a reply is not the reviewer's verdict).
+    'pulls/create-reply-for-review-comment': async (ctx) => {
+      const g = gh(ctx);
+      const { repo, seg, body, occurredAt, caller, state } = g;
+      const number = numberOf(g);
+      const rootId = Number(decodeURIComponent(seg[6]!));
+      const parent = state().comments.find((c) => c.repository === repo && c.number === number && c.kind === 'review' && c.id === rootId);
+      if (!parent) return send(ctx, githubNotFound());
+      // an empty body is refused as a missing one is
+      if (body.body === undefined || String(body.body) === '') return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PullRequestReviewComment', field: 'body', code: 'missing_field' }] }, 422);
+      const seq = nextSeq(ctx, 'comment');
+      const anchor: Record<string, unknown> = {};
+      if (parent.commit_id !== undefined) anchor.commit_id = parent.commit_id;
+      if (parent.path !== undefined) anchor.path = parent.path;
+      if (parent.line !== undefined) anchor.line = parent.line;
+      if (parent.side !== undefined) anchor.side = parent.side;
+      if (parent.diff_hunk !== undefined) anchor.diff_hunk = parent.diff_hunk;
+      const fields: Record<string, unknown> = { repository: repo, number, body: body.body, created_at: occurredAt, updated_at: occurredAt, in_reply_to: rootId, review_id: implicitReviewId(repo, number), user_login: caller ?? GITHUB_WORLD_USER, author_association: authorAssociation(state(), repo, caller ?? GITHUB_WORLD_USER), ...anchor };
+      await put(ctx, { operation: 'pull_request_review_comment.create', subjectType: 'pull_request_review_comment', subjectId: `comment:${seq}`, fields });
+      const comment = serializeReviewComment(state().comments.find((c) => c.repository === repo && c.kind === 'review' && c.id === seq)!);
+      await announce(ctx, [{ event: 'pull_request_review_comment', action: 'created', repository: repo, number, comment }]);
+      return ctx.reply(comment, 201);
+    },
+    // A review (diff-thread) comment, wrapped in the pull request's implicit review, bound to the head
+    // (or its parent's commit when it replies), with the diff anchor a local write gives it.
+    'pulls/create-review-comment': intoPull(async (ctx, g, _pr, number) => {
+      const { repo, body, occurredAt, caller, state } = g;
+      const seq = nextSeq(ctx, 'comment');
+      const fields: Record<string, unknown> = { repository: repo, number, body: body.body, created_at: occurredAt, updated_at: occurredAt, review_id: implicitReviewId(repo, number), user_login: caller ?? GITHUB_WORLD_USER, author_association: authorAssociation(state(), repo, caller ?? GITHUB_WORLD_USER) };
+      const parent = body.in_reply_to === undefined ? undefined : state().comments.find((c) => c.repository === repo && c.number === number && c.kind === 'review' && c.id === Number(body.in_reply_to));
+      const commitId = parent ? parent.commit_id : body.commit_id ?? state().prs.find((p) => p.repository === repo && p.number === number)?.head_sha;
+      if (commitId !== undefined) fields.commit_id = String(commitId);
+      if (body.path !== undefined) fields.path = String(body.path);
+      if (body.line !== undefined) fields.line = Number(body.line);
+      if (body.side !== undefined) fields.side = String(body.side);
+      if (body.start_line !== undefined) fields.start_line = Number(body.start_line);
+      if (body.diff_hunk !== undefined) fields.diff_hunk = String(body.diff_hunk);
+      if (body.in_reply_to !== undefined) fields.in_reply_to = Number(body.in_reply_to);
+      await put(ctx, { operation: 'pull_request_review_comment.create', subjectType: 'pull_request_review_comment', subjectId: `comment:${seq}`, fields });
+      const comment = serializeReviewComment(state().comments.find((c) => c.repository === repo && c.kind === 'review' && c.id === seq)!);
+      await announce(ctx, [{ event: 'pull_request_review_comment', action: 'created', repository: repo, number, comment }]);
+      return ctx.reply(comment, 201);
+    }),
+    // Merge through the gates: 405 when merged or closed or a draft; 409 when `sha` names a head the
+    // branch has moved from (the caller's optimistic precondition); then the required checks and the
+    // rulesets, and a real merge commit on the plane.
+    'pulls/merge': intoPull(async (ctx, g, pr, number) => {
+      const { repo, body, occurredAt, caller, root, state } = g;
+      const refused = ctx.legal('pull-request', 'merged', 'pulls/merge', pr.merged)
+        ?? ctx.legal('pull-request', 'state', 'pulls/merge', pr.state ?? 'open')
+        ?? ctx.legal('pull-request', 'draft', 'pulls/merge', pr.draft);
+      if (refused) return ctx.refuse(refused);
+      if (body.sha !== undefined && String(body.sha) !== pr.head_sha) return ctx.reply({ message: 'Head branch was modified. Review and try the merge again.' }, 409);
+      const method = body.merge_method ? String(body.merge_method) : 'merge';
+      if (!['merge', 'squash', 'rebase'].includes(method)) return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PullRequest', field: 'merge_method', code: 'invalid' }] }, 422);
+      const base = pr.base_ref ?? 'main';
+      const before = hasBareRepo(repo, root) ? await resolvePlaneRef(repo, base, base, root) : null;
+      // what the pull request says it closes, read before the merge moves its base: its body and its commits' messages
+      const messages: string[] = [];
+      for (const sha of (await planeCommitsOf(g, pr)) ?? []) messages.push(String(((await planeCommitBody(repo, sha, root)) as { commit?: { message?: string } } | null)?.commit?.message ?? ''));
+      const closes = closingIssueNumbers([pr.body ?? '', ...messages]);
+      const landed = await mergePullRequest(repo, pr, method as 'merge' | 'squash' | 'rebase', occurredAt, root, caller, writer(ctx));
+      if (!landed.ok) return ctx.reply({ message: landed.message }, landed.status);
+      const st = state();
+      const merged = st.prs.find((p) => p.id === `${repo}#${number}`)!;
+      await announce(ctx, [{ event: 'pull_request', action: 'closed', repository: repo, number, pr: toGithubRest(merged, st.milestones) }]);
+      // The merge moved the base branch: a push to it, which GitHub's processes read as any push (workflows on push,
+      // Dependabot's manifests, the branch's files) (docs.github.com/webhooks/webhook-events-and-payloads#push: "a
+      // commit or tag is pushed", as a merge's commit is to the base branch).
+      if (before && before !== landed.sha) await announce(ctx, [{ event: 'push', action: '', repository: repo, number: 0, ref: `refs/heads/${base}`, before, after: landed.sha }]);
+      // A pull request merged into the default branch closes the issues it links with a closing keyword
+      // (docs.github.com/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue).
+      if (base === (st.repos.find((r) => r.full_name === repo)?.default_branch ?? 'main')) {
+        for (const n of closes) {
+          const issue = state().issues.find((i) => i.repository === repo && i.number === n);
+          // the close is the issue's move by the merge (manifest.ts)
+          if (!issue || (issue.state ?? 'open') !== 'open' || ctx.legal('issue', 'state', 'pulls/merge', issue.state ?? 'open', 'closed', issue.id)) continue;
+          await put(ctx, { operation: 'issue.update', subjectType: 'issue', subjectId: issue.id, fields: { number: n, repository: repo, state: 'closed', state_reason: 'completed', updated_at: occurredAt } });
+          const now = state();
+          const closed = now.issues.find((i) => i.id === issue.id);
+          await announce(ctx, [{ event: 'issues', action: 'closed', repository: repo, number: n, ...(closed ? { issue: toGithubIssue(closed, now.milestones, undefined, now.comments) } : {}) }]);
+        }
+      }
+      return ctx.reply({ sha: landed.sha, merged: true, message: 'Pull Request successfully merged' });
+    }),
+    // a review is requested from someone with access to the repository, never from the pull request's author; a
+    // repository the twin knows only through its pull requests (an observed or seeded World) has no access list to check
+    'pulls/request-reviewers': intoPull(async (ctx, g, pr, number) => {
+      const asked = normalizeLogins(g.body.reviewers);
+      const docs = 'https://docs.github.com/rest/pulls/review-requests#request-reviewers-for-a-pull-request';
+      if (pr.user_login && asked.includes(pr.user_login)) return ctx.reply({ message: 'Review cannot be requested from pull request author.', documentation_url: docs }, 422);
+      const st = g.state();
+      const access = new Set(assignable(st, g.repo));
+      if (st.repos.some((r) => r.full_name === g.repo) && asked.some((login) => !access.has(login))) return ctx.reply({ message: `Reviews may only be requested from collaborators. One or more of the users or teams you specified is not a collaborator of the ${g.repo} repository.`, documentation_url: docs }, 422);
+      const merged = [...(pr.requested_reviewers ?? [])];
+      for (const login of asked) if (!merged.includes(login)) merged.push(login);
+      return writePull(ctx, g, number, 'pull_request.request_reviewers', { requested_reviewers: merged }, 'review_requested', 201, 'pull-request-simple');
+    }),
+    'pulls/remove-requested-reviewers': intoPull(async (ctx, g, pr, number) => {
+      const remove = new Set(normalizeLogins(g.body.reviewers));
+      return writePull(ctx, g, number, 'pull_request.remove_requested_reviewers', { requested_reviewers: (pr.requested_reviewers ?? []).filter((login) => !remove.has(login)) }, 'review_request_removed', 200, 'pull-request-simple');
+    }),
+    // brings the base's latest commits into the head branch with a merge commit, as GitHub's Update branch does (202);
+    // a head already up to date stays as it is, and one that conflicts is refused
+    // (the head branch is written where it lives: the fork, for a pull request from one)
+    'pulls/update-branch': intoPull(async (ctx, g, pr, number) => {
+      const headRef = pr.head_ref ?? '';
+      const headRepo = pr.head_repo ?? g.repo;
+      const baseTip = await resolvePlaneRef(g.repo, pr.base_ref ?? 'main', pr.base_ref ?? 'main', g.root);
+      if (baseTip && headRef) {
+        const merged = await mergeIntoBranchInPlane(headRepo, headRef, baseTip, `Merge branch '${pr.base_ref ?? 'main'}' into ${headRef}`, 'merge', g.occurredAt, g.root);
+        if (merged && 'conflict' in merged) return ctx.reply({ message: 'merge conflict between base and head', documentation_url: 'https://docs.github.com/rest/pulls/pulls#update-a-pull-request-branch' }, 422);
+        if (merged && merged.sha !== pr.head_sha) {
+          await put(ctx, { operation: 'git_ref.update', subjectType: 'git_ref', subjectId: `gitref:${headRepo}#refs/heads/${headRef}`, fields: { repository: headRepo, ref: `refs/heads/${headRef}`, object_sha: merged.sha, object_type: 'commit' } });
+          await put(ctx, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${headRepo}#${headRef}`, fields: { repository: headRepo, name: headRef, commit_sha: merged.sha } });
+          await syncPrHeadsToBranchTip(headRepo, headRef, merged.sha, g.root, g.occurredAt);
+        }
+      }
+      return ctx.reply({ message: 'Updating pull request branch.', url: `https://api.github.com/repos/${g.repo}/pulls/${number}` }, 202);
+    }),
+  };
+}
+
+/** Dismiss a review (PUT .../reviews/:rid/dismissals, a message required) or edit its body
+ *  (PUT .../reviews/:rid), as an overlay on the submitted review. */
+async function reviewOverlay(ctx: SemanticsContext, how: 'dismiss' | 'update'): Promise<Response> {
+  const g = gh(ctx);
+  const { repo, seg, body, state } = g;
+  const number = numberOf(g);
+  const rid = Number(decodeURIComponent(seg[6]!));
+  const submitted = state().reviews.find((r) => r.repository === repo && r.number === number && r.id === rid);
+  if (!submitted) return send(ctx, githubNotFound());
+  if (how === 'dismiss') {
+    if (!body.message) return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PullRequestReview', field: 'message', code: 'missing_field' }] }, 422);
+    // the dismissal is the review's move (manifest.ts), kept as an overlay on the submitted review
+    const refused = ctx.legal('pull-request-review', 'state', 'pulls/dismiss-review', submitted.state, 'DISMISSED', String(rid));
+    if (refused) return ctx.reply({ message: refused.message }, refused.status);
+    await put(ctx, { operation: 'pull_request_review_overlay.dismiss', subjectType: 'pull_request_review_overlay', subjectId: `reviewoverlay:${rid}`, fields: { review_id: rid, state: 'DISMISSED', dismissed_message: String(body.message) } });
+  } else {
+    if (body.body === undefined) return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PullRequestReview', field: 'body', code: 'missing_field' }] }, 422);
+    await put(ctx, { operation: 'pull_request_review_overlay.update', subjectType: 'pull_request_review_overlay', subjectId: `reviewoverlay:${rid}`, fields: { review_id: rid, body: String(body.body) } });
+  }
+  const review = toGithubReview(state().reviews.find((x) => x.id === rid)!);
+  await announce(ctx, [{ event: 'pull_request_review', action: how === 'dismiss' ? 'dismissed' : 'edited', repository: repo, number, review }]);
+  return ctx.reply(review);
+}
+
+/** A pull request's changed files: the plane's real diff when its base and head both exist there; never fabricated. */
+async function filesOf(g: ReturnType<typeof gh>, pr: NonNullable<ReturnType<typeof pullOf>>) {
+  return (await prPlaneDiffFiles(g.state(), g.repo, pr, g.root)) ?? [];
+}
+
+/** An open pull request's mergeability in a repository with history, as GitHub computes it when the pull request is
+ *  read (docs.github.com/rest/guides/using-the-rest-api-to-interact-with-your-git-database#checking-mergeability-of-pull-
+ *  requests): whether its head merges into its base without conflicts. Where the documentation stops and the twin
+ *  decides: a conflict-free merge reads `clean`, a conflicted one `dirty`; the computation is never pending. Nothing
+ *  when the pull request is closed or its repository has no history (what it carries stands). */
+async function mergeability(g: ReturnType<typeof gh>, pr: NonNullable<ReturnType<typeof pullOf>>): Promise<{ mergeable?: boolean; mergeable_state?: string }> {
+  const { repo, root } = g;
+  if (pr.merged || (pr.state ?? 'open') !== 'open' || !pr.head_sha || !hasBareRepo(repo, root)) return {};
+  const merged = await mergeIntoBranchInPlane(repo, pr.base_ref ?? 'main', pr.head_sha, '', 'merge', g.occurredAt, root, undefined, true);
+  if (!merged) return {};
+  return 'conflict' in merged ? { mergeable: false, mergeable_state: 'dirty' } : { mergeable: true, mergeable_state: 'clean' };
+}
+
+/** In a repository with history, the commits a pull request's head reaches that its base did not hold (a merged
+ *  one's base is its merge commit's first parent), oldest first; undefined in a repository without history. */
+async function planeCommitsOf(g: ReturnType<typeof gh>, pr: NonNullable<ReturnType<typeof pullOf>>): Promise<string[] | undefined> {
+  const { repo, root } = g;
+  if (!pr.head_sha || !hasBareRepo(repo, root)) return undefined;
+  const mergeCommit = pr.merge_commit_sha ? await readGitCommitFromPlane(repo, pr.merge_commit_sha, root) : null;
+  const base = mergeCommit?.parents[0] ?? await resolvePlaneRef(repo, pr.base_ref ?? 'main', pr.base_ref ?? 'main', root);
+  const held = base ? await planeAncestors(repo, base, root) : new Map<string, number>();
+  // oldest first: by commit time, and within one second (git's resolution) a parent before its child — the walk
+  // from the head meets a commit's parents after it, so a later walk position is the older commit
+  const walked = [...(await planeAncestors(repo, pr.head_sha, root))].map(([sha, at], i) => ({ sha, at, i }));
+  return walked.filter(({ sha }) => !held.has(sha)).sort((a, b) => (a.at - b.at) || (b.i - a.i)).map(({ sha }) => sha);
+}