@volter/twin-github 0.1.1 → 2.0.0

package/src/semantics/graphql.ts

@@ -0,0 +1,505 @@
+// GitHub's GraphQL semantics on the GraphQL wire (../graphql-wire.ts): resolvers for what the stored
+// objects do not hold as the schema names it, and the stored fields each type reads as they are.
+// Every answer folds from the same projection the REST twin serves, over the request's handler
+// interface (`context.ctx`, semanticsContext()): its tree, its clock, its write path. A mutation GitHub
+// also publishes over REST writes through the REST twin's own path (in-process); the draft flag, which
+// REST cannot set, is written through the context after the machine allows it. A query selecting a
+// field nothing here models is answered with GitHub's undefinedField error by the wire's fallback.
+//
+// Global ids are the twin's: R_<owner>/<repo>, PR_<repo>#<n>, I_<repo>#<n>, IC_<repo>#<id> (an issue
+// comment), D_<repo>#<n> (a discussion), DC_<repo>#<id> (its comment), DIC_<repo>#<id> (a category),
+// LA_<repo>#<name> (a label), U_<login>.
+import { GraphQLError } from 'graphql';
+import type { SemanticsContext } from '@volter/world-core';
+import {
+  GITHUB_WORLD_USER, applyGithubWrite, discussionCategoriesFor, nextRepoNumber, prPlaneDiffFiles, toGithubRest,
+  type GithubState,
+} from '../github-twin.ts';
+import type { FieldResolver, GraphqlContext } from '../graphql-wire.ts';
+import { announce, gh, githubStateOf, nextSeq, put } from './shared.ts';
+
+type Obj = Record<string, unknown>;
+type Pr = GithubState['prs'][number];
+type Issue = GithubState['issues'][number];
+
+/** GitHub's GraphQL error: its message and its `type` (NOT_FOUND, UNPROCESSABLE). */
+const fail = (message: string, type: string): never => {
+  throw new GraphQLError(message, { extensions: { type } });
+};
+
+/** A connection as the twin answers one: every node, no further page. */
+function conn(nodes: unknown[]): Obj {
+  return { nodes, edges: nodes.map((node, i) => ({ node, cursor: btoa(String(i)) })), totalCount: nodes.length, pageInfo: { hasNextPage: false, hasPreviousPage: false, endCursor: null, startCursor: null } };
+}
+
+function pullRequestNode(repo: string, p: Pr): Obj {
+  // the head's owner: the fork's, for a pull request from a fork
+  const owner = (p.head_repo ?? repo).split('/')[0]!;
+  return {
+    __typename: 'PullRequest',
+    _repo: repo,
+    _pr: p,
+    number: p.number,
+    title: p.title ?? null,
+    state: p.merged ? 'MERGED' : (p.state ?? 'open'),
+    id: `PR_${repo}#${p.number}`,
+    url: `https://github.com/${repo}/pull/${p.number}`,
+    baseRefName: p.base_ref ?? null,
+    headRefName: p.head_ref ?? null,
+    isCrossRepository: p.head_repo !== undefined && p.head_repo !== repo,
+    headRepositoryOwner: { __typename: 'User', id: `U_${owner}`, login: owner, name: null },
+  };
+}
+
+function issueNode(repo: string, i: Issue): Obj {
+  return { __typename: 'Issue', _repo: repo, _issue: i, number: i.number, title: i.title ?? null, state: i.state ?? 'open', id: `I_${repo}#${i.number}` };
+}
+
+const prsOf = (state: GithubState, repo: string) => state.prs.filter((p) => p.repository === repo && p.is_pull_request);
+const issuesOf = (state: GithubState, repo: string) => state.issues.filter((i) => i.repository === repo);
+
+/** The issue comments on an issue or a pull request, as GitHub's GraphQL renders them. */
+function issueComments(state: GithubState, repo: string, number: number, kind: 'issues' | 'pull'): Obj[] {
+  return state.comments
+    .filter((c) => c.repository === repo && c.number === number && c.kind === 'issue')
+    .map((c) => ({
+      __typename: 'IssueComment', id: `IC_${repo}#${c.id}`, author: null, authorAssociation: 'NONE', body: c.body ?? '',
+      createdAt: c.created_at ?? null, includesCreatedEdit: false, isMinimized: false, minimizedReason: null,
+      reactionGroups: [], url: `https://github.com/${repo}/${kind}/${number}#issuecomment-${c.id}`, viewerDidAuthor: false,
+    }));
+}
+
+/** Labels by name, with the repository catalog's colour and description where it holds the label. */
+function labelNodes(state: GithubState, repo: string, names: string[] | undefined): Obj[] {
+  return (names ?? []).map((name) => {
+    const l = state.labels.find((x) => x.repository === repo && x.name === name);
+    return { __typename: 'Label', id: `LA_${repo}#${name}`, name, description: l?.description ?? null, color: l?.color ?? 'ededed' };
+  });
+}
+
+const userNodes = (logins: string[] | undefined): Obj[] => (logins ?? []).map((login) => ({ __typename: 'User', login, id: `U_${login}`, name: null }));
+
+// GitHub GraphQL enum spellings for the rollup (StatusState / CheckStatusState / CheckConclusionState).
+function statusStateEnum(s: string | undefined): string {
+  const v = (s ?? 'pending').toUpperCase();
+  return ['ERROR', 'EXPECTED', 'FAILURE', 'PENDING', 'SUCCESS'].includes(v) ? v : 'PENDING';
+}
+function checkStatusEnum(s: string | undefined): string {
+  const v = (s ?? 'queued').toUpperCase();
+  return ['QUEUED', 'IN_PROGRESS', 'COMPLETED', 'WAITING', 'PENDING', 'REQUESTED'].includes(v) ? v : 'QUEUED';
+}
+function checkConclusionEnum(s: string | undefined): string | null {
+  if (!s) return null;
+  const v = s.toUpperCase();
+  return ['ACTION_REQUIRED', 'TIMED_OUT', 'CANCELLED', 'FAILURE', 'SUCCESS', 'NEUTRAL', 'SKIPPED', 'STARTUP_FAILURE', 'STALE'].includes(v) ? v : null;
+}
+
+/** The closing-keyword issue linkage (Closes/Fixes/Resolves #n) real GitHub derives from the PR body. */
+export function closingIssueNumbersFromBody(body: string | undefined): number[] {
+  const out: number[] = [];
+  for (const m of (body ?? '').matchAll(/\b(?:clos(?:e[sd]?|ing)|fix(?:e[sd]|ing)?|resolv(?:e[sd]?|ing))\s*:?\s+#(\d+)/gi)) {
+    const n = Number(m[1]);
+    if (!out.includes(n)) out.push(n);
+  }
+  return out;
+}
+
+/** The head commit's status-check rollup: each check run, and each status context once (the most
+ *  recent wins), folded from the rows the REST checks surface reads. gh reads it as `commits(last: 1)`. */
+function headCommits(state: GithubState, repo: string, pr: Pr): Obj[] {
+  const headSha = pr.head_sha ?? '';
+  const latestByContext = new Map<string, GithubState['statuses'][number]>();
+  for (const s of state.statuses.filter((s) => s.repository === repo && s.sha === headSha).sort((a, b) => a.id - b.id)) latestByContext.set(s.context ?? 'default', s);
+  const runs = state.checkRuns.filter((c) => c.repository === repo && c.head_sha === headSha).sort((a, b) => a.id - b.id);
+  const contexts: Obj[] = [
+    ...runs.map((c) => ({
+      __typename: 'CheckRun', name: c.name, checkSuite: { __typename: 'CheckSuite', workflowRun: null },
+      status: checkStatusEnum(c.status), conclusion: checkConclusionEnum(c.conclusion),
+      startedAt: c.started_at ?? null, completedAt: c.completed_at ?? null, detailsUrl: c.details_url ?? null,
+    })),
+    ...[...latestByContext.values()].map((s) => ({
+      __typename: 'StatusContext', context: s.context, state: statusStateEnum(s.state),
+      targetUrl: s.target_url ?? null, description: s.description ?? null, createdAt: s.created_at ?? null,
+    })),
+  ];
+  const anyFailed = contexts.some((c) =>
+    (c.__typename === 'CheckRun' && ['FAILURE', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE'].includes(String(c.conclusion)))
+    || (c.__typename === 'StatusContext' && ['FAILURE', 'ERROR'].includes(String(c.state))));
+  const anyPending = contexts.some((c) =>
+    (c.__typename === 'CheckRun' && c.conclusion === null)
+    || (c.__typename === 'StatusContext' && ['PENDING', 'EXPECTED'].includes(String(c.state))));
+  const rollupState = contexts.length === 0 ? null : anyFailed ? 'FAILURE' : anyPending ? 'PENDING' : 'SUCCESS';
+  return [{ __typename: 'PullRequestCommit', commit: { __typename: 'Commit', statusCheckRollup: rollupState === null ? null : { state: rollupState, contexts: conn(contexts) } } }];
+}
+
+/** The handler interface of the request a resolver runs in. */
+const ctxOf = (c: GraphqlContext): SemanticsContext => c.ctx as SemanticsContext;
+
+/** An earlier answer of a discussion another comment is now marked as, unmarked. */
+async function unmarkAnswer(ctx: SemanticsContext, id: number): Promise<void> {
+  await put(ctx, { operation: 'discussion_comment.unmark_answer', subjectType: 'discussion_comment', subjectId: `discomment:${id}`, fields: { is_answer: false } });
+}
+
+export function githubGraphql(): { resolvers: Record<string, FieldResolver>; stored: Record<string, string[]> } {
+  const state = (c: GraphqlContext): GithubState => githubStateOf(ctxOf(c));
+  const pr = (s: Obj): Pr => s._pr as Pr;
+  const issue = (s: Obj): Issue => s._issue as Issue;
+  /** A write through the REST twin's own path (the fetch, in-process), at this request's root. */
+  const write = (c: GraphqlContext, method: string, path: string, body: unknown, occurredAt?: string) => {
+    const root = ctxOf(c).root;
+    return applyGithubWrite({ method, path, body: JSON.stringify(body), ...(root !== undefined ? { root } : {}), ...(occurredAt ? { occurredAt } : {}) });
+  };
+  /** markPullRequestReadyForReview / convertPullRequestToDraft: an open pull request's draft
+   *  flag, as the pull request's machines allow it (GraphQL is `external` to the REST operations). */
+  const readiness = (draft: boolean): FieldResolver => async (_s, args, c) => {
+    const ctx = ctxOf(c);
+    const input = (args.input ?? {}) as { pullRequestId?: string; clientMutationId?: string };
+    const match = /^PR_(.+)#(\d+)$/.exec(String(input.pullRequestId ?? ''));
+    const pull = match && state(c).prs.find((p) => p.is_pull_request && p.repository === match[1] && p.number === Number(match[2]));
+    if (!pull) return fail('Could not resolve to a PullRequest node', 'NOT_FOUND');
+    const op = draft ? 'graphql/convertPullRequestToDraft' : 'graphql/markPullRequestReadyForReview';
+    const refused = ctx.legal('pull-request', 'state', op, pull.state, undefined, pull.id, 'external')
+      ?? ctx.legal('pull-request', 'draft', op, pull.draft, String(draft), pull.id, 'external');
+    if (refused) return fail(refused.message, 'UNPROCESSABLE');
+    await put(ctx, { operation: 'pull_request.update', subjectType: 'pull_request', subjectId: pull.id, fields: { number: pull.number, repository: pull.repository, draft } });
+    const st = state(c);
+    const changed = st.prs.find((p) => p.id === pull.id);
+    if (!changed || changed.draft !== draft) return fail('Could not change pull request draft state', 'UNPROCESSABLE');
+    await announce(ctx, [{ event: 'pull_request', action: draft ? 'converted_to_draft' : 'ready_for_review', repository: pull.repository, number: pull.number, pr: toGithubRest(changed, st.milestones) }]);
+    return { clientMutationId: input.clientMutationId ?? null, pullRequest: pullRequestNode(pull.repository, changed) };
+  };
+  /** A stored project as GraphQL answers it: its node id, number, title and state. */
+  const projectNode = (p: Record<string, unknown>, owner: string) => ({
+    __typename: 'ProjectV2', id: `PVT_${String(p.id)}`, number: p.number, title: p.title, closed: p.closed === true, public: p.public === true,
+    url: `https://github.com/orgs/${owner}/projects/${String(p.number)}`, shortDescription: p.short_description ?? null, readme: p.readme ?? null,
+  });
+  const queryNode: FieldResolver = (_s, args, c) => {
+    const m = /^(PR|I)_(.+)#(\d+)$/.exec(String(args.id ?? ''));
+    if (!m) throw new Error(`Could not resolve to a node with the global id of '${String(args.id ?? '')}'`);
+    const repo = m[2]!;
+    const number = Number(m[3]);
+    const s = state(c);
+    const hit = m[1] === 'PR' ? prsOf(s, repo).find((p) => p.number === number) : issuesOf(s, repo).find((i) => i.number === number);
+    if (!hit) throw new Error(`Could not resolve to a node with the global id of '${String(args.id)}'`);
+    return m[1] === 'PR' ? pullRequestNode(repo, hit as Pr) : issueNode(repo, hit as Issue);
+  };
+  const repositoryPullRequests: FieldResolver = (r, args, c) => {
+    const repo = String(r._repo);
+    const states = Array.isArray(args.states) ? args.states.map((s) => String(s).toUpperCase()) : undefined;
+    return prsOf(state(c), repo)
+      .map((p) => pullRequestNode(repo, p))
+      .filter((p) => args.headRefName === undefined || p.headRefName === args.headRefName)
+      .filter((p) => states === undefined || states.includes(String(p.state).toUpperCase()));
+  };
+  const repositoryPullRequest: FieldResolver = (r, args, c) => {
+    const repo = String(r._repo);
+    const hit = prsOf(state(c), repo).find((p) => p.number === Number(args.number));
+    return hit ? pullRequestNode(repo, hit) : fail(`Could not resolve to a PullRequest with the number of ${String(args.number)}.`, 'NOT_FOUND');
+  };
+  const repositoryIssue: FieldResolver = (r, args, c) => {
+    const repo = String(r._repo);
+    const hit = issuesOf(state(c), repo).find((i) => i.number === Number(args.number));
+    return hit ? issueNode(repo, hit) : fail(`Could not resolve to an Issue with the number of ${String(args.number)}.`, 'NOT_FOUND');
+  };
+  const repositoryDiscussions: FieldResolver = (r, _args, c) => {
+    const repo = String(r._repo);
+    const st = state(c);
+    const categories = discussionCategoriesFor(repo);
+    return conn(st.discussions.filter((d) => d.repository === repo).map((d) => {
+      const cat = categories.find((c) => c.slug === d.category_slug);
+      const comments = st.discussionComments.filter((c) => c.repository === repo && c.discussion_number === d.number).map((c) => ({
+        __typename: 'DiscussionComment', id: `DC_${repo}#${c.id}`, body: c.body ?? '', createdAt: c.created_at ?? null, author: null, isAnswer: Boolean(c.is_answer),
+        url: `https://github.com/${repo}/discussions/${d.number}#discussioncomment-${c.id}`,
+        replyTo: c.parent_id ? { __typename: 'DiscussionComment', id: `DC_${repo}#${c.parent_id}` } : null,
+      }));
+      return {
+        __typename: 'Discussion', id: `D_${repo}#${d.number}`, number: d.number, title: d.title ?? null, body: d.body ?? '', url: `https://github.com/${repo}/discussions/${d.number}`,
+        createdAt: d.created_at ?? null, updatedAt: d.updated_at ?? null, author: null, closed: d.state === 'closed', locked: Boolean(d.locked),
+        isAnswered: d.answer_comment_id !== undefined && d.answer_comment_id !== null,
+        category: cat ? { __typename: 'DiscussionCategory', id: `DIC_${repo}#${cat.id}`, name: cat.name, slug: cat.slug, isAnswerable: Boolean(cat.is_answerable) } : null,
+        comments: conn(comments),
+      };
+    }));
+  };
+  const repositoryDiscussionCategories: FieldResolver = (r, args, c) => {
+    const repo = String(r._repo);
+    const st = state(c);
+    if (!st.repos.some((x) => x.full_name === repo)) return fail('Repository not found', 'NOT_FOUND');
+    const all = discussionCategoriesFor(repo).map((c) => ({ __typename: 'DiscussionCategory', id: `DIC_${repo}#${c.id}`, name: c.name, slug: c.slug, description: c.description, isAnswerable: Boolean(c.is_answerable) }));
+    const first = typeof args.first === 'number' ? args.first : all.length;
+    const after = typeof args.after === 'string' ? args.after : undefined;
+    const start = after ? all.findIndex((c) => c.id === after) + 1 : 0;
+    if (first < 0 || first > 100 || (after && start === 0)) return fail('Invalid discussion category pagination', 'UNPROCESSABLE');
+    const nodes = all.slice(start, start + first);
+    return { nodes, edges: nodes.map((node) => ({ cursor: node.id, node })), totalCount: all.length, pageInfo: { hasNextPage: start + nodes.length < all.length, hasPreviousPage: start > 0, endCursor: nodes.at(-1)?.id ?? null, startCursor: nodes[0]?.id ?? null } };
+  };
+  const pullRequestChangedFiles: FieldResolver = async (s, _args, c) => {
+    const p = pr(s);
+    const planeFiles = p.changed_files === undefined ? await prPlaneDiffFiles(state(c), String(s._repo), p, ctxOf(c).root) : null;
+    return p.changed_files ?? planeFiles?.length ?? 0;
+  };
+  const pullRequestClosingIssuesReferences: FieldResolver = (s, _args, c) => {
+    const repo = String(s._repo);
+    const st = state(c);
+    return conn(closingIssueNumbersFromBody(pr(s).body).map((n) => st.issues.find((i) => i.repository === repo && i.number === n)).filter((i): i is Issue => !!i).map((i) => issueNode(repo, i)));
+  };
+  const mutationAddComment: FieldResolver = async (_s, args, c) => {
+    const input = (args.input ?? {}) as { subjectId?: string; body?: string };
+    const subjectId = String(input.subjectId ?? '');
+    const body = String(input.body ?? '');
+    const m = /^(PR|I)_(.+)#(\d+)$/.exec(subjectId);
+    if (!m) return fail(`Could not resolve to a node with the global id of '${subjectId}'`, 'NOT_FOUND');
+    const repo = m[2]!;
+    const res = await write(c, 'POST', `/repos/${repo}/issues/${Number(m[3])}/comments`, { body });
+    if (res.response.status !== 201) return fail('addComment failed', 'UNPROCESSABLE');
+    const cid = (res.response.body as { id?: number }).id;
+    return { commentEdge: { cursor: btoa('0'), node: { __typename: 'IssueComment', id: `IC_${repo}#${cid}`, body } } };
+  };
+  const mutationCreatePullRequest: FieldResolver = async (_s, args, c) => {
+    const input = (args.input ?? {}) as Record<string, unknown>;
+    const m = /^R_(.+)$/.exec(String(input.repositoryId ?? ''));
+    if (!m) return fail(`Could not resolve to a Repository with the global id of '${String(input.repositoryId ?? '')}'`, 'NOT_FOUND');
+    const repo = m[1]!;
+    const res = await write(c, 'POST', `/repos/${repo}/pulls`, { title: input.title, head: input.headRefName, base: input.baseRefName, body: input.body, draft: input.draft === true });
+    if (res.response.status !== 201) return fail('createPullRequest failed', 'UNPROCESSABLE');
+    const number = (res.response.body as { number?: number }).number;
+    const made = prsOf(state(c), repo).find((p) => p.number === number);
+    return { clientMutationId: input.clientMutationId ?? null, pullRequest: made ? pullRequestNode(repo, made) : { __typename: 'PullRequest', id: `PR_${repo}#${number}`, url: `https://github.com/${repo}/pull/${number}` } };
+  };
+  const mutationUpdateProjectV2: FieldResolver = async (_s, args, c) => {
+    const ctx = ctxOf(c);
+    const input = (args.input ?? {}) as { projectId?: string; title?: string; closed?: boolean; public?: boolean; readme?: string; shortDescription?: string; clientMutationId?: string };
+    const id = /^PVT_(\d+)$/.exec(String(input.projectId ?? ''))?.[1];
+    const project = id ? state(c).projects.find((p) => p.id === Number(id)) : undefined;
+    if (!project) return fail(`Could not resolve to a node with the global id of '${String(input.projectId ?? '')}'`, 'NOT_FOUND');
+    // closing and reopening are the project's moves (manifest.ts), stored as its `closed` flag
+    if (input.closed !== undefined) {
+      const refused = ctx.legal('projects-v2', 'state', 'graphql/updateProjectV2', project.closed ? 'closed' : 'open', input.closed ? 'closed' : 'open', String(project.id), 'external');
+      if (refused) return fail(refused.message, 'UNPROCESSABLE');
+    }
+    const patch = { ...(input.title !== undefined ? { title: input.title } : {}), ...(input.closed !== undefined ? { closed: input.closed } : {}), ...(input.public !== undefined ? { public: input.public } : {}), ...(input.readme !== undefined ? { readme: input.readme } : {}), ...(input.shortDescription !== undefined ? { short_description: input.shortDescription } : {}) };
+    await put(ctx, { operation: 'project.update', subjectType: 'project', subjectId: `project:${project.id}`, fields: { ...patch, updated_at: ctx.occurredAt } });
+    const updated = state(c).projects.find((p) => p.id === project.id)!;
+    return { clientMutationId: input.clientMutationId ?? null, projectV2: projectNode(updated as unknown as Record<string, unknown>, project.owner) };
+  };
+  return {
+    resolvers: {
+      'Query.viewer': (_s, _args, c) => ({ __typename: 'User', login: 'octocat', name: state(c).userProfile.name ?? 'The Octocat' }),
+      'Query.node': queryNode,
+      'Query.repository': (_s, args, c) => {
+        const repo = `${String(args.owner)}/${String(args.name)}`;
+        return { _repo: repo, _known: state(c).repos.find((r) => r.full_name === repo) ?? null, name: args.name, owner: { __typename: 'User', login: args.owner } };
+      },
+      'Repository.id': (r, _args, c) => `R_${String(r._repo)}`,
+      'Repository.name': (r, _args, c) => r.name ?? String(r._repo).split('/')[1],
+      'Repository.owner': (r, _args, c) => r.owner ?? { __typename: 'User', id: `U_${String(r._repo).split('/')[0]}`, login: String(r._repo).split('/')[0] },
+      'Repository.nameWithOwner': (r, _args, c) => r._repo,
+      'Repository.isPrivate': (r, _args, c) => (r._known as Obj | null)?.private ?? false,
+      'Repository.description': (r, _args, c) => (r._known as Obj | null)?.description ?? null,
+      'Repository.hasIssuesEnabled': (r, _args, c) => (r._known as Obj | null)?.has_issues ?? true,
+      'Repository.hasWikiEnabled': (r, _args, c) => (r._known as Obj | null)?.has_wiki ?? true,
+      // the twin's loopback caller is the repository's unauthenticated owner
+      'Repository.viewerPermission': () => 'ADMIN',
+      'Repository.defaultBranchRef': (r, _args, c) => ({ name: (r._known as Obj | null)?.default_branch ?? 'main' }),
+      'Repository.parent': () => null,
+      'Repository.mergeCommitAllowed': () => true,
+      'Repository.rebaseMergeAllowed': () => true,
+      'Repository.squashMergeAllowed': () => true,
+      'Repository.pullRequests': repositoryPullRequests,
+      'Repository.issues': (r, _args, c) => issuesOf(state(c), String(r._repo)).map((i) => issueNode(String(r._repo), i)),
+      // ONE pull request by number: the read `gh pr view` sends
+      'Repository.pullRequest': repositoryPullRequest,
+      // ONE issue by number: `gh issue view`
+      'Repository.issue': repositoryIssue,
+      // Discussions: GitHub serves them over GraphQL alone. Every discussion, with its comments.
+      'Repository.discussions': repositoryDiscussions,
+      // One of a repository's discussion categories by its slug, or null (docs.github.com/graphql/reference/objects#repository)
+      'Repository.discussionCategory': (r, args, c) => {
+        const repo = String(r._repo);
+        if (!state(c).repos.some((x) => x.full_name === repo)) return fail('Repository not found', 'NOT_FOUND');
+        const cat = discussionCategoriesFor(repo).find((x) => x.slug === String(args.slug ?? ''));
+        return cat ? { __typename: 'DiscussionCategory', id: `DIC_${repo}#${cat.id}`, name: cat.name, slug: cat.slug, description: cat.description, isAnswerable: Boolean(cat.is_answerable) } : null;
+      },
+      // A repository's discussion categories, paged by category id; the repository must exist.
+      'Repository.discussionCategories': repositoryDiscussionCategories,
+      // A pull request's view, folded from the REST projection: the head is its resolved sha; the
+      // closing issues are the body's closing keywords (as GitHub derives them); changedFiles is the
+      // carried count, the carried file list, or the plane's real diff, 0 only without evidence.
+      'PullRequest.body': (s, _args, c) => pr(s).body ?? '',
+      'PullRequest.isDraft': (s, _args, c) => pr(s).draft ?? false,
+      'PullRequest.headRefOid': (s, _args, c) => pr(s).head_sha ?? '',
+      'PullRequest.changedFiles': pullRequestChangedFiles,
+      'PullRequest.additions': (s, _args, c) => pr(s).additions ?? 0,
+      'PullRequest.deletions': (s, _args, c) => pr(s).deletions ?? 0,
+      'PullRequest.createdAt': (s, _args, c) => pr(s).created_at ?? null,
+      'PullRequest.updatedAt': (s, _args, c) => pr(s).updated_at ?? pr(s).created_at ?? null,
+      'PullRequest.closedAt': () => null,
+      'PullRequest.mergedAt': (s, _args, c) => pr(s).merged_at ?? null,
+      'PullRequest.author': () => null,
+      'PullRequest.labels': (s, _args, c) => conn(labelNodes(state(c), String(s._repo), pr(s).labels)),
+      'PullRequest.assignees': (s, _args, c) => conn(userNodes(pr(s).assignees)),
+      'PullRequest.reviewRequests': (s, _args, c) => conn((pr(s).requested_reviewers ?? []).map((login) => ({ __typename: 'ReviewRequest', requestedReviewer: { __typename: 'User', login } }))),
+      'PullRequest.comments': (s, _args, c) => conn(issueComments(state(c), String(s._repo), pr(s).number, 'pull')),
+      'PullRequest.commits': (s, _args, c) => conn(headCommits(state(c), String(s._repo), pr(s))),
+      'PullRequest.closingIssuesReferences': pullRequestClosingIssuesReferences,
+      'Issue.url': (s, _args, c) => `https://github.com/${String(s._repo)}/issues/${issue(s).number}`,
+      'Issue.body': (s, _args, c) => issue(s).body ?? '',
+      'Issue.author': () => null,
+      'Issue.createdAt': (s, _args, c) => issue(s).created_at ?? null,
+      'Issue.updatedAt': (s, _args, c) => issue(s).updated_at ?? issue(s).created_at ?? null,
+      'Issue.closedAt': () => null,
+      'Issue.labels': (s, _args, c) => conn(labelNodes(state(c), String(s._repo), issue(s).labels)),
+      'Issue.assignees': (s, _args, c) => conn(userNodes(issue(s).assignees)),
+      'Issue.comments': (s, _args, c) => conn(issueComments(state(c), String(s._repo), issue(s).number, 'issues')),
+      'Issue.repository': (s, _args, c) => ({ _repo: s._repo, _known: state(c).repos.find((r) => r.full_name === s._repo) ?? null }),
+      // a comment on an issue or pull request, written through the REST twin's comment path
+      'Mutation.addComment': mutationAddComment,
+      // a comment on a discussion (or a reply, replyToId), written through the discussion comment path
+      'Mutation.addDiscussionComment': async (_s, args, c) => {
+        const input = (args.input ?? {}) as { discussionId?: string; body?: string; replyToId?: string };
+        const discussionId = String(input.discussionId ?? '');
+        const body = String(input.body ?? '');
+        const m = /^D_(.+)#(\d+)$/.exec(discussionId);
+        if (!m) return fail(`Could not resolve to a node with the global id of '${discussionId}'`, 'NOT_FOUND');
+        const repo = m[1]!;
+        const number = Number(m[2]);
+        const replyTo = /^DC_(.+)#(\d+)$/.exec(String(input.replyToId ?? ''));
+        if (!state(c).discussions.some((d) => d.repository === repo && d.number === number)) return fail(`Could not resolve to a node with the global id of '${discussionId}'`, 'NOT_FOUND');
+        if (!body) return fail('Body can\'t be blank', 'UNPROCESSABLE');
+        const ctx = ctxOf(c);
+        const cid = nextSeq(ctx, 'discomment');
+        await put(ctx, { operation: 'discussion_comment.create', subjectType: 'discussion_comment', subjectId: `discomment:${cid}`, fields: { repository: repo, discussion_number: number, parent_id: replyTo ? Number(replyTo[2]) : null, body, is_answer: false, created_at: ctx.occurredAt, updated_at: ctx.occurredAt } });
+        await announce(ctx, [{ event: 'discussion_comment', action: 'created', repository: repo, number }]);
+        return { comment: { __typename: 'DiscussionComment', id: `DC_${repo}#${cid}`, body, url: `https://github.com/${repo}/discussions/${number}#discussioncomment-${cid}` } };
+      },
+      // gh pr create's mutation, through the REST create path
+      'Mutation.createPullRequest': mutationCreatePullRequest,
+      // A discussion in an existing category, through the discussion create path.
+      'Mutation.createDiscussion': async (_s, args, c) => {
+        const input = (args.input ?? {}) as { repositoryId?: string; categoryId?: string; title?: string; body?: string; clientMutationId?: string };
+        const repo = /^R_(.+)$/.exec(String(input.repositoryId ?? ''))?.[1];
+        const st = state(c);
+        if (!repo || !st.repos.some((r) => r.full_name === repo)) return fail('Repository not found', 'NOT_FOUND');
+        const category = discussionCategoriesFor(repo).find((c) => `DIC_${repo}#${c.id}` === input.categoryId);
+        if (!category) return fail('Discussion category not found in repository', 'NOT_FOUND');
+        if (!input.title) return fail('Title can\'t be blank', 'UNPROCESSABLE');
+        const ctx = ctxOf(c);
+        const number = nextRepoNumber(st, repo);
+        await put(ctx, { operation: 'discussion.create', subjectType: 'discussion', subjectId: `discussion:${repo}#${number}`, fields: { number, repository: repo, title: String(input.title), body: input.body ?? '', category_slug: category.slug, state: 'open', locked: false, created_at: ctx.occurredAt, updated_at: ctx.occurredAt } });
+        await announce(ctx, [{ event: 'discussion', action: 'created', repository: repo, number }]);
+        const d = state(c).discussions.find((x) => x.repository === repo && x.number === number)!;
+        return {
+          clientMutationId: input.clientMutationId ?? null,
+          discussion: {
+            __typename: 'Discussion', id: `D_${repo}#${number}`, number, title: d.title, body: d.body, url: `https://github.com/${repo}/discussions/${number}`, createdAt: d.created_at, updatedAt: d.updated_at,
+            category: { __typename: 'DiscussionCategory', id: `DIC_${repo}#${category.id}`, name: category.name, slug: category.slug, description: category.description, isAnswerable: Boolean(category.is_answerable) },
+            closed: false, locked: false, isAnswered: false, comments: conn([]),
+          },
+        };
+      },
+      // the comment that answers a question, in a discussion whose category takes answers (Q&A); it replaces an earlier answer
+      'Mutation.markDiscussionCommentAsAnswer': async (_s, args, c) => {
+        const input = (args.input ?? {}) as { id?: string; clientMutationId?: string };
+        const m = /^DC_(.+)#(\d+)$/.exec(String(input.id ?? ''));
+        const st = state(c);
+        const comment = m ? st.discussionComments.find((x) => x.repository === m[1] && x.id === Number(m[2])) : undefined;
+        if (!m || !comment) return fail(`Could not resolve to a node with the global id of '${String(input.id ?? '')}'`, 'NOT_FOUND');
+        const repo = m[1]!;
+        const d = st.discussions.find((x) => x.repository === repo && x.number === comment.discussion_number)!;
+        if (!discussionCategoriesFor(repo).find((x) => x.slug === d.category_slug)?.is_answerable) return fail('Discussion is not answerable', 'UNPROCESSABLE');
+        const ctx = ctxOf(c);
+        for (const earlier of st.discussionComments.filter((x) => x.repository === repo && x.discussion_number === d.number && x.is_answer && x.id !== comment.id)) await unmarkAnswer(ctx, earlier.id);
+        await put(ctx, { operation: 'discussion_comment.mark_answer', subjectType: 'discussion_comment', subjectId: `discomment:${comment.id}`, fields: { is_answer: true } });
+        await announce(ctx, [{ event: 'discussion', action: 'answered', repository: repo, number: d.number }]);
+        return { clientMutationId: input.clientMutationId ?? null, discussion: { __typename: 'Discussion', id: `D_${repo}#${d.number}`, number: d.number, title: d.title, isAnswered: true } };
+      },
+      // an organization by its login: the owner a project is created under
+      // a person by their login (the id a project's collaborator is granted by)
+      'Query.user': (_s, args, c) => {
+        const login = String(args.login ?? '');
+        const st = state(c);
+        const known = login === GITHUB_WORLD_USER || st.oauthGrants.some((g) => g.login === login) || st.orgMembers.some((m) => m.login === login) || st.collaborators.some((x) => x.login === login) || st.repos.some((r) => r.owner === login);
+        return known ? { __typename: 'User', login, name: null, id: `U_${login}` } : fail(`Could not resolve to a User with the login of '${login}'.`, 'NOT_FOUND');
+      },
+      'Query.organization': (_s, args, c) => {
+        const org = state(c).orgs.find((o) => o.login === String(args.login ?? ''));
+        if (!org) return fail(`Could not resolve to an Organization with the login of '${String(args.login ?? '')}'.`, 'NOT_FOUND');
+        return { __typename: 'Organization', login: org.login, name: org.name ?? org.login, id: `O_${org.login}` };
+      },
+      // Projects are created and edited through GraphQL only (docs.github.com/issues/planning-and-tracking-with-projects/
+      // automating-your-project/using-the-api-to-manage-projects); the REST API reads them
+      'Mutation.createProjectV2': async (_s, args, c) => {
+        const ctx = ctxOf(c);
+        const input = (args.input ?? {}) as { ownerId?: string; title?: string; clientMutationId?: string };
+        const login = /^O_(.+)$/.exec(String(input.ownerId ?? ''))?.[1];
+        const st = state(c);
+        if (!login || !st.orgs.some((o) => o.login === login)) return fail(`Could not resolve to a node with the global id of '${String(input.ownerId ?? '')}'`, 'NOT_FOUND');
+        if (!input.title) return fail('Title can\'t be blank', 'UNPROCESSABLE');
+        const number = Math.max(0, ...st.projects.filter((p) => p.owner === login && p.owner_type === 'organization').map((p) => p.number)) + 1;
+        const id = nextSeq(ctx, 'project');
+        await put(ctx, { operation: 'project.create', subjectType: 'project', subjectId: `project:${id}`, fields: { owner: login, owner_type: 'organization', number, title: input.title, short_description: null, readme: null, public: false, closed: false, created_at: ctx.occurredAt, updated_at: ctx.occurredAt, creator_login: gh(ctx).caller ?? GITHUB_WORLD_USER } });
+        const made = state(c).projects.find((p) => p.id === id)!;
+        return { clientMutationId: input.clientMutationId ?? null, projectV2: projectNode(made as unknown as Record<string, unknown>, login) };
+      },
+      'Mutation.updateProjectV2': mutationUpdateProjectV2,
+      // A project's collaborators and their roles, which a project's admin grants (its Manage access settings, or this
+      // mutation): a person by their user id, ADMIN, WRITER or READER, or NONE to take their access away
+      // (docs.github.com/graphql/reference/mutations#updateprojectv2collaborators,
+      // docs.github.com/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects).
+      // Where the documentation stops and the twin decides: a team's id is not modeled, only a person's.
+      'Mutation.updateProjectV2Collaborators': async (_s, args, c) => {
+        const ctx = ctxOf(c);
+        const input = (args.input ?? {}) as { projectId?: string; collaborators?: Array<{ userId?: string; teamId?: string; role?: string }>; clientMutationId?: string };
+        const pid = Number(/^PVT_(\d+)$/.exec(String(input.projectId ?? ''))?.[1]);
+        const project = state(c).projects.find((p) => p.id === pid);
+        if (!project) return fail(`Could not resolve to a node with the global id of '${String(input.projectId ?? '')}'`, 'NOT_FOUND');
+        const granted: Obj[] = [];
+        for (const who of input.collaborators ?? []) {
+          const login = /^U_(.+)$/.exec(String(who.userId ?? ''))?.[1];
+          if (!login) return fail(`Could not resolve to a node with the global id of '${String(who.userId ?? who.teamId ?? '')}'`, 'NOT_FOUND');
+          const role = String(who.role ?? '').toUpperCase();
+          if (!['ADMIN', 'WRITER', 'READER', 'NONE'].includes(role)) return fail(`Argument 'role' on InputObject 'ProjectV2Collaborator' has an invalid value (${role}).`, 'UNPROCESSABLE');
+          await put(ctx, { operation: role === 'NONE' ? 'project_collaborator.remove' : 'project_collaborator.grant', subjectType: 'project_collaborator', subjectId: `projectcollab:${pid}:${login}`, fields: role === 'NONE' ? { deleted: true, project_id: pid, login } : { project_id: pid, login, role } });
+          granted.push({ __typename: 'User', login, id: `U_${login}` });
+        }
+        return { clientMutationId: input.clientMutationId ?? null, collaborators: granted };
+      },
+      // an open pull request's draft flag (GitHub's REST edit has no draft parameter)
+      'Mutation.markPullRequestReadyForReview': readiness(false),
+      'Mutation.convertPullRequestToDraft': readiness(true),
+    },
+    stored: {
+      User: ['login', 'name', 'id'],
+      Organization: ['login', 'name', 'id'],
+      ProjectV2: ['id', 'number', 'title', 'closed', 'public', 'url', 'shortDescription', 'readme'],
+      CreateProjectV2Payload: ['clientMutationId', 'projectV2'],
+      UpdateProjectV2Payload: ['clientMutationId', 'projectV2'],
+      UpdateProjectV2CollaboratorsPayload: ['clientMutationId', 'collaborators'],
+      Ref: ['name'],
+      PullRequest: ['number', 'title', 'state', 'id', 'url', 'baseRefName', 'headRefName', 'isCrossRepository', 'headRepositoryOwner'],
+      Issue: ['number', 'title', 'state', 'id'],
+      IssueComment: ['id', 'author', 'authorAssociation', 'body', 'createdAt', 'includesCreatedEdit', 'isMinimized', 'minimizedReason', 'reactionGroups', 'url', 'viewerDidAuthor'],
+      ReactionGroup: ['content', 'users'],
+      Label: ['id', 'name', 'description', 'color'],
+      ReviewRequest: ['requestedReviewer'],
+      PullRequestCommit: ['commit'],
+      Commit: ['statusCheckRollup'],
+      StatusCheckRollup: ['state', 'contexts'],
+      CheckRun: ['name', 'checkSuite', 'status', 'conclusion', 'startedAt', 'completedAt', 'detailsUrl'],
+      CheckSuite: ['workflowRun'],
+      WorkflowRun: ['workflow'],
+      Workflow: ['name'],
+      StatusContext: ['context', 'state', 'targetUrl', 'description', 'createdAt'],
+      MarkDiscussionCommentAsAnswerPayload: ['clientMutationId', 'discussion'],
+      Discussion: ['id', 'number', 'title', 'body', 'url', 'createdAt', 'updatedAt', 'author', 'closed', 'locked', 'isAnswered', 'category', 'comments'],
+      DiscussionComment: ['id', 'body', 'createdAt', 'author', 'isAnswer', 'replyTo', 'url'],
+      DiscussionCategory: ['id', 'name', 'slug', 'description', 'isAnswerable'],
+      AddCommentPayload: ['commentEdge'],
+      AddDiscussionCommentPayload: ['comment'],
+      CreatePullRequestPayload: ['clientMutationId', 'pullRequest'],
+      CreateDiscussionPayload: ['clientMutationId', 'discussion'],
+      MarkPullRequestReadyForReviewPayload: ['clientMutationId', 'pullRequest'],
+      ConvertPullRequestToDraftPayload: ['clientMutationId', 'pullRequest'],
+    },
+  };
+}

package/src/semantics/index.ts

@@ -0,0 +1,68 @@
+// GitHub semantics, by operationId. Families move here from github-twin.ts's hand-written read and
+// write switches; a write GitHub announces emits its webhook from its handler.
+import type { Semantics } from '@volter/world-core';
+import { actionsSemantics } from './actions.ts';
+import { activitySemantics } from './activity.ts';
+import { appsSemantics } from './apps.ts';
+import { branchesSemantics } from './branches.ts';
+import { checksSemantics } from './checks.ts';
+import { codespacesSemantics } from './codespaces.ts';
+import { commitsSemantics } from './commits.ts';
+import { contentsSemantics } from './contents.ts';
+import { deploymentsSemantics } from './deployments.ts';
+import { gistsSemantics } from './gists.ts';
+import { gitSemantics } from './git.ts';
+import { issuesSemantics } from './issues.ts';
+import { keysSemantics } from './keys.ts';
+import { labelsSemantics } from './labels.ts';
+import { metaSemantics } from './meta.ts';
+import { orgsSemantics } from './orgs.ts';
+import { packagesSemantics } from './packages.ts';
+import { pagesSemantics } from './pages.ts';
+import { projectsSemantics } from './projects.ts';
+import { pullsSemantics } from './pulls.ts';
+import { releasesSemantics } from './releases.ts';
+import { reposSemantics } from './repos.ts';
+import { rulesetsSemantics } from './rulesets.ts';
+import { searchSemantics } from './search.ts';
+import { codeScanningUpload } from './code-scanning-upload.ts';
+import { repoInvitationsSemantics } from './repo-invitations.ts';
+import { securitySemantics } from './security.ts';
+import { usersSemantics } from './users.ts';
+import { webhooksSemantics } from './webhooks.ts';
+
+export type GithubSemanticsOptions = { readOnly?: boolean };
+
+export function githubSemantics(opts: GithubSemanticsOptions = {}): Record<string, Semantics> {
+  return {
+    ...metaSemantics(opts),
+    ...usersSemantics(),
+    ...gistsSemantics(),
+    ...activitySemantics(),
+    ...searchSemantics(),
+    ...orgsSemantics(),
+    ...projectsSemantics(),
+    ...securitySemantics(),
+    ...codeScanningUpload,
+    ...repoInvitationsSemantics,
+    ...pagesSemantics(),
+    ...packagesSemantics(),
+    ...appsSemantics(),
+    ...codespacesSemantics(),
+    ...actionsSemantics(),
+    ...keysSemantics(),
+    ...rulesetsSemantics(),
+    ...deploymentsSemantics(),
+    ...releasesSemantics(),
+    ...webhooksSemantics(),
+    ...labelsSemantics(),
+    ...commitsSemantics(),
+    ...checksSemantics(),
+    ...gitSemantics(),
+    ...contentsSemantics(),
+    ...reposSemantics(),
+    ...branchesSemantics(),
+    ...issuesSemantics(),
+    ...pullsSemantics(),
+  };
+}