@volter/twin-github 0.1.1 → 2.0.0

package/src/semantics/activity.ts

@@ -0,0 +1,171 @@
+// GitHub's activity family: the feeds catalog and event streams, the notifications inbox and its
+// threads, stars and repository watching. Each person stars and watches for themselves (the credential's
+// user, the World's own user for its shared token). A thread's subscription is apart from its unread flag: GitHub
+// subscribes a person to a conversation they take part in (docs.github.com/rest/activity/notifications#get-a-thread-
+// subscription-for-the-authenticated-user); ignoring it mutes the thread, unsubscribing mutes it until their next
+// @mention. Where the documentation stops and the twin decides: an unsubscribed thread reads as neither subscribed nor
+// ignored, and ignoring a thread also takes it out of the inbox, as muting does in GitHub's own inbox.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { GITHUB_WORLD_USER, githubActivityEvents, githubNotFound, paginate, seedUser, toGithubNotification, toGithubRepo, toGithubUser, type GithubNotification, type GithubRepo } from '../github-twin.ts';
+import { announce, asView, gh, put, send } from './shared.ts';
+
+/** Mark one notification thread read (or unread), keeping the fields it was stored with. */
+function markThread(ctx: SemanticsContext, n: GithubNotification, unread: boolean): Promise<Record<string, unknown>> {
+  return put(ctx, { operation: 'notification.read', subjectType: 'notification', subjectId: `notification:${n.id}`, fields: { id: n.id, repository: n.repository, subject_title: n.subject_title, subject_type: n.subject_type, reason: n.reason, unread, updated_at: ctx.occurredAt } });
+}
+
+/** The inbox as GitHub lists it: the most recently updated thread first. */
+const latestFirst = (threads: GithubNotification[]): GithubNotification[] => threads.map((n, i) => [n, i] as const).sort((a, b) => String(b[0].updated_at ?? '').localeCompare(String(a[0].updated_at ?? '')) || b[1] - a[1]).map(([n]) => n);
+
+/** A thread's subscription as GitHub answers it. */
+function subscriptionOf(n: GithubNotification): Record<string, unknown> {
+  const sub = n.subscription === null ? { subscribed: false, ignored: false, created_at: undefined } : (n.subscription ?? { subscribed: true, ignored: false, created_at: n.updated_at });
+  return { subscribed: sub.subscribed, ignored: sub.ignored, reason: null, created_at: sub.created_at ?? null, url: `https://api.github.com/notifications/threads/${n.id}/subscription`, thread_url: `https://api.github.com/notifications/threads/${n.id}` };
+}
+
+/** Who the credential names: its user, or the World's own for its shared token. */
+export const me = (ctx: SemanticsContext): string => gh(ctx).caller ?? GITHUB_WORLD_USER;
+
+/** GET .../stargazers and .../subscribers: everyone who stars or watches the repo. */
+const repoFans = (stars: boolean): Semantics => async (ctx) => {
+  const { repo, query, state } = gh(ctx);
+  const st = state();
+  const items = (stars ? st.starEdges : st.watchEdges).filter((e) => e.to === repo).map((e) => asView('simple-user', toGithubUser(seedUser(e.from))));
+  return ctx.reply(paginate(items, query));
+};
+
+const star = (starred: boolean): Semantics => async (ctx) => {
+  const { seg } = gh(ctx);
+  const repo = `${seg[2]}/${seg[3]}`;
+  await put(ctx, { operation: starred ? 'star.add' : 'star.remove', subjectType: 'star', subjectId: `star:${me(ctx)}:${repo}`, fields: { repository: repo, starred } });
+  await announce(ctx, [{ event: 'star', action: starred ? 'created' : 'deleted', repository: repo, number: 0 }]);
+  return send(ctx, { status: 204, body: undefined });
+};
+
+const watch = (subscribed: boolean): Semantics => async (ctx) => {
+  const { repo } = gh(ctx);
+  await put(ctx, { operation: subscribed ? 'repo_subscription.watch' : 'repo_subscription.unwatch', subjectType: 'repo_subscription', subjectId: `watch:${me(ctx)}:${repo}`, fields: { repository: repo, subscribed } });
+  if (!subscribed) return send(ctx, { status: 204, body: undefined });
+  return ctx.reply({ subscribed: true, ignored: false, reason: null, repository_url: `https://api.github.com/repos/${repo}` });
+};
+
+export function activitySemantics(): Record<string, Semantics> {
+  const activityGetFeeds: Semantics = async (ctx) => {
+    const api = 'https://github.com';
+    const link = (href: string) => ({ href, type: 'application/atom+xml' });
+    return ctx.reply({
+      timeline_url: `${api}/timeline`, user_url: `${api}/{user}`,
+      current_user_public_url: `${api}/octocat`, current_user_url: `${api}/octocat.private?token=t`,
+      current_user_actor_url: `${api}/octocat.private.actor?token=t`,
+      current_user_organization_url: '', current_user_organization_urls: [],
+      security_advisories_url: `${api}/security-advisories`,
+      _links: { timeline: link(`${api}/timeline`), user: link(`${api}/{user}`), current_user_public: link(`${api}/octocat`), security_advisories: link(`${api}/security-advisories`) },
+    });
+  };
+  const activityListPublicEvents: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    return ctx.reply(paginate(githubActivityEvents(state()), query));
+  };
+  const activityListRepoEvents: Semantics = async (ctx) => {
+    const { repo, query, state } = gh(ctx);
+    return ctx.reply(paginate(githubActivityEvents(state()).filter((e) => (e.repo as { name?: string }).name === repo), query));
+  };
+  const activityListNotificationsForAuthenticatedUser: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    const all = new URLSearchParams((query ?? '').replace(/^\?/, '')).get('all') === 'true';
+    return ctx.reply(paginate(latestFirst(state().notifications.filter((n) => all || n.unread)), query).map(toGithubNotification));
+  };
+  const activityListRepoNotificationsForAuthenticatedUser: Semantics = async (ctx) => {
+    const { repo, query, state } = gh(ctx);
+    const all = new URLSearchParams((query ?? '').replace(/^\?/, '')).get('all') === 'true';
+    return ctx.reply(paginate(latestFirst(state().notifications.filter((n) => n.repository === repo && (all || n.unread))), query).map(toGithubNotification));
+  };
+  const activityGetThread: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const n = state().notifications.find((x) => x.id === decodeURIComponent(seg[2]!));
+    return send(ctx, n ? { status: 200, body: toGithubNotification(n) } : githubNotFound());
+  };
+  const activityGetThreadSubscriptionForAuthenticatedUser: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const n = state().notifications.find((x) => x.id === decodeURIComponent(seg[2]!));
+    return send(ctx, n ? { status: 200, body: subscriptionOf(n) } : githubNotFound());
+  };
+  const activitySetThreadSubscription: Semantics = async (ctx) => {
+    const { seg, body, state, occurredAt } = gh(ctx);
+    const n = state().notifications.find((x) => x.id === decodeURIComponent(seg[2]!));
+    if (!n) return send(ctx, githubNotFound());
+    const subscription = { subscribed: body.ignored !== true, ignored: body.ignored === true, created_at: occurredAt };
+    await put(ctx, { operation: 'notification.subscribe', subjectType: 'notification', subjectId: `notification:${n.id}`, fields: { id: n.id, subscription, ...(subscription.ignored ? { unread: false } : {}) } });
+    return ctx.reply(subscriptionOf({ ...n, subscription }));
+  };
+  const activityDeleteThreadSubscription: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const n = state().notifications.find((x) => x.id === decodeURIComponent(seg[2]!));
+    if (!n) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'notification.unsubscribe', subjectType: 'notification', subjectId: `notification:${n.id}`, fields: { id: n.id, subscription: null } });
+    return send(ctx, { status: 204, body: undefined });
+  };
+  const activityMarkThreadAsRead: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const n = state().notifications.find((x) => x.id === decodeURIComponent(seg[2]!));
+    if (!n) return send(ctx, githubNotFound());
+    await markThread(ctx, n, false);
+    return send(ctx, { status: 205, body: undefined });
+  };
+  const activityMarkNotificationsAsRead: Semantics = async (ctx) => {
+    for (const n of gh(ctx).state().notifications.filter((x) => x.unread)) await markThread(ctx, n, false);
+    return send(ctx, { status: 205, body: undefined });
+  };
+  const activityMarkRepoNotificationsAsRead: Semantics = async (ctx) => {
+    const { repo, state } = gh(ctx);
+    for (const n of state().notifications.filter((x) => x.repository === repo && x.unread)) await markThread(ctx, n, false);
+    return send(ctx, { status: 205, body: undefined });
+  };
+  const activityListReposStarredByAuthenticatedUser: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    const st = state();
+    const mine = st.starEdges.filter((e) => e.from === me(ctx)).map((e) => e.to);
+    const items = mine.map((full) => st.repos.find((r) => r.full_name === full)).filter((r): r is GithubRepo => !!r).map((r) => asView('repository', toGithubRepo(r)));
+    return ctx.reply(paginate(items, query));
+  };
+  const activityCheckRepoIsStarredByAuthenticatedUser: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    return send(ctx, state().starEdges.some((e) => e.from === me(ctx) && e.to === `${seg[2]}/${seg[3]}`) ? { status: 204, body: undefined } : githubNotFound());
+  };
+  const activityGetRepoSubscription: Semantics = async (ctx) => {
+    const { repo, state } = gh(ctx);
+    return send(ctx, state().watchEdges.some((e) => e.from === me(ctx) && e.to === repo) ? { status: 200, body: { subscribed: true, ignored: false, reason: null, repository_url: `https://api.github.com/repos/${repo}` } } : githubNotFound());
+  };
+  return {
+    // the feed-URL catalog (timeline/user/security-advisories links); stateless
+    'activity/get-feeds': activityGetFeeds,
+    // the public timeline: every modeled event
+    'activity/list-public-events': activityListPublicEvents,
+    // the same projection scoped to one repo
+    'activity/list-repo-events': activityListRepoEvents,
+    // the inbox: unread threads, or every thread with `all=true`
+    'activity/list-notifications-for-authenticated-user': activityListNotificationsForAuthenticatedUser,
+    'activity/list-repo-notifications-for-authenticated-user': activityListRepoNotificationsForAuthenticatedUser,
+    'activity/get-thread': activityGetThread,
+    'activity/get-thread-subscription-for-authenticated-user': activityGetThreadSubscriptionForAuthenticatedUser,
+    // subscribe, or ignore (mute) the thread, which also takes it out of the inbox
+    'activity/set-thread-subscription': activitySetThreadSubscription,
+    // unsubscribe: muted until the person is next @mentioned
+    'activity/delete-thread-subscription': activityDeleteThreadSubscription,
+    // mark a thread read (205)
+    'activity/mark-thread-as-read': activityMarkThreadAsRead,
+    'activity/mark-notifications-as-read': activityMarkNotificationsAsRead,
+    'activity/mark-repo-notifications-as-read': activityMarkRepoNotificationsAsRead,
+    'activity/list-stargazers-for-repo': repoFans(true),
+    'activity/list-watchers-for-repo': repoFans(false),
+    // the authenticated user's starred repos, and the membership check (204 starred / 404 not)
+    'activity/list-repos-starred-by-authenticated-user': activityListReposStarredByAuthenticatedUser,
+    'activity/check-repo-is-starred-by-authenticated-user': activityCheckRepoIsStarredByAuthenticatedUser,
+    'activity/star-repo-for-authenticated-user': star(true),
+    'activity/unstar-repo-for-authenticated-user': star(false),
+    // the authenticated user's watch on a repo ({subscribed:true} or 404)
+    'activity/get-repo-subscription': activityGetRepoSubscription,
+    'activity/set-repo-subscription': watch(true),
+    'activity/delete-repo-subscription': watch(false),
+  };
+}

package/src/semantics/apps.ts

@@ -0,0 +1,133 @@
+// GitHub's Apps family: an app by its slug, the app's installations and installation access tokens. An app
+// is registered through the twin's door (GitHub's settings UI has no API) and installed by a person on its
+// page (src/screens/app-installation.tsx); a token is minted deterministically from its installation.
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { githubApps, githubNotFound, paginate, toGithubApp, toGithubAppInstallation, type GithubAppRegistration } from '../github-twin.ts';
+import { gh, put, send } from './shared.ts';
+import { emitGithubAppEvent, githubAppDeliveries, githubAppDelivery } from '../github-events.ts';
+
+// An app speaks for itself with a JSON Web Token it signs with its private key: its client ID (or app ID) as `iss`,
+// issued no later than now and expiring at most ten minutes after it was issued
+// (docs.github.com/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app).
+// The app's installations and their access tokens take only that token ("You must use a JWT to access this endpoint",
+// docs.github.com/rest/apps/apps). Where the evidence stops: the private key is generated on the app's settings page
+// and never leaves the app's server, so the twin holds no key to check the RS256 signature against; it reads the
+// token's claims, and a token whose claims do not name a registered app, or that is expired, is refused.
+const JWT_DOCS = 'https://docs.github.com/rest/apps/apps';
+type Claims = { iss?: unknown; iat?: unknown; exp?: unknown };
+const claimsOf = (token: string | undefined): Claims | undefined => {
+  const parts = (token ?? '').split('.');
+  try { return parts.length === 3 ? JSON.parse(Buffer.from(parts[1]!, 'base64url').toString('utf8')) as Claims : undefined; } catch { return undefined; }
+};
+/** The app a request's JWT authenticates, or nothing when the token is not a live JWT of a registered app. */
+function appOfJwt(ctx: SemanticsContext): GithubAppRegistration | undefined {
+  const claims = claimsOf(gh(ctx).token);
+  const now = Math.floor(Date.parse(ctx.occurredAt) / 1000);
+  const live = typeof claims?.iat === 'number' && typeof claims.exp === 'number' && claims.iat <= now + 60 && claims.exp > now && claims.exp - claims.iat <= 600;
+  return live ? githubApps(ctx.root).find((a) => String(claims!.iss) === a.client_id || String(claims!.iss) === String(a.id)) : undefined;
+}
+/** GitHub's answer to a call on an app's own endpoints without a live JWT of the app. */
+const jwtRefused = (ctx: SemanticsContext): Response => ctx.reply({ message: 'A JSON web token could not be decoded', documentation_url: JWT_DOCS }, 401);
+/** An installation of the app the request's JWT authenticates, by its id. */
+const ownInstallation = (ctx: SemanticsContext, app: GithubAppRegistration) =>
+  gh(ctx).state().appInstallations.find((x) => x.id === Number(decodeURIComponent(gh(ctx).seg[2]!)) && x.app_slug === app.slug);
+
+export function appsSemantics(): Record<string, Semantics> {
+  const appsGetBySlug: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const slug = decodeURIComponent(seg[1]!);
+    const app = githubApps(ctx.root).find((a) => a.slug === slug);
+    return send(ctx, app ? { status: 200, body: toGithubApp(app, state().appInstallations.filter((i) => i.app_slug === slug).length, state()) } : githubNotFound());
+  };
+  const appsGetAuthenticated: Semantics = async (ctx) => {
+    const app = appOfJwt(ctx);
+    if (!app) return jwtRefused(ctx);
+    const { state } = gh(ctx);
+    return ctx.reply(toGithubApp(app, state().appInstallations.filter((i) => i.app_slug === app.slug).length, state()));
+  };
+  const appsListInstallations: Semantics = async (ctx) => {
+    const app = appOfJwt(ctx);
+    if (!app) return jwtRefused(ctx);
+    const { query, state } = gh(ctx);
+    return ctx.reply(paginate(state().appInstallations.filter((i) => i.app_slug === app.slug), query).map(toGithubAppInstallation));
+  };
+  const appsGetInstallation: Semantics = async (ctx) => {
+    const app = appOfJwt(ctx);
+    if (!app) return jwtRefused(ctx);
+    const i = ownInstallation(ctx, app);
+    return send(ctx, i ? { status: 200, body: toGithubAppInstallation(i) } : githubNotFound());
+  };
+  return {
+    // a public app's page data, by its slug
+    'apps/get-by-slug': appsGetBySlug,
+    // The application that sent a person to register it from its manifest exchanges the temporary code GitHub
+    // redirected back with for the app's credentials: once, within an hour, with no other authentication (201)
+    // (docs.github.com/rest/apps/apps#create-a-github-app-from-a-manifest,
+    // docs.github.com/apps/sharing-github-apps/registering-a-github-app-from-a-manifest). A code used or expired is
+    // Not Found. Where the documentation stops and the twin decides: the private key is a stand-in of the PEM's shape
+    // that nothing verifies (a JWT's signature is not checked, see appOfJwt).
+    'apps/create-from-manifest': async (ctx) => {
+      const { seg, occurredAt, state } = gh(ctx);
+      const code = decodeURIComponent(seg[1]!);
+      const row = ctx.tree().find((r) => r.type === 'app_manifest_code' && r.code === code && r.deleted !== true);
+      const expired = row && Date.parse(occurredAt) - Date.parse(String(row.created_at)) > 60 * 60 * 1000;
+      const app = row && githubApps(ctx.root).find((a) => a.slug === row.app_slug);
+      if (!row || row.used === true || expired || !app) return send(ctx, githubNotFound());
+      await put(ctx, { operation: 'app_manifest_code.use', subjectType: 'app_manifest_code', subjectId: `manifestcode:${code}`, fields: { used: true } });
+      const secret = (what: string) => createHash('sha256').update(`app:${app.slug}:${what}`).digest('hex');
+      const pem = `-----BEGIN RSA PRIVATE KEY-----\n${Buffer.from(secret('key') + secret('key2')).toString('base64').match(/.{1,64}/g)!.join('\n')}\n-----END RSA PRIVATE KEY-----\n`;
+      return ctx.reply({ ...toGithubApp(app, 0, state()), client_secret: secret('client').slice(0, 40), webhook_secret: app.webhook_secret ?? null, pem }, 201);
+    },
+    // the app the JWT authenticates (docs.github.com/rest/apps/apps#get-the-authenticated-app)
+    'apps/get-authenticated': appsGetAuthenticated,
+    // the deliveries of the app's own webhook, and one in detail with the payload it carried
+    // (docs.github.com/rest/apps/webhooks#list-deliveries-for-an-app-webhook)
+    'apps/list-webhook-deliveries': async (ctx) => {
+      const app = appOfJwt(ctx);
+      if (!app) return jwtRefused(ctx);
+      return ctx.reply(paginate(githubAppDeliveries(app.id, ctx.root), gh(ctx).query));
+    },
+    'apps/get-webhook-delivery': async (ctx) => {
+      const app = appOfJwt(ctx);
+      if (!app) return jwtRefused(ctx);
+      const d = githubAppDelivery(app.id, Number(decodeURIComponent(gh(ctx).seg[3]!)), ctx.root);
+      return send(ctx, d ? { status: 200, body: d } : githubNotFound());
+    },
+    // the app uninstalls itself from an account: the installation and its tokens are gone (204)
+    // (docs.github.com/rest/apps/apps#delete-an-installation-for-the-authenticated-app)
+    'apps/delete-installation': async (ctx) => {
+      const app = appOfJwt(ctx);
+      if (!app) return jwtRefused(ctx);
+      const i = ownInstallation(ctx, app);
+      if (!i) return send(ctx, githubNotFound());
+      await put(ctx, { operation: 'app_installation.delete', subjectType: 'app_installation', subjectId: `installation:${i.id}`, fields: { deleted: true } });
+      for (const t of ctx.tree().filter((r) => r.type === 'app_token' && r.installation_id === i.id && r.deleted !== true)) {
+        await put(ctx, { operation: 'app_token.revoke', subjectType: 'app_token', subjectId: String(t.id), fields: { deleted: true } });
+      }
+      try {
+        await emitGithubAppEvent(app, 'installation', { action: 'deleted', installation: toGithubAppInstallation(i), sender: { login: `${app.slug}[bot]`, type: 'Bot' } }, { occurredAt: ctx.occurredAt, ...(ctx.root !== undefined ? { root: ctx.root } : {}) });
+      } catch { /* a delivery failure never fails the deletion */ }
+      return send(ctx, { status: 204, body: undefined });
+    },
+    // the installations of the app the JWT authenticates
+    'apps/list-installations': appsListInstallations,
+    'apps/get-installation': appsGetInstallation,
+    // A deterministic installation token (ghs_…) bound to the installation's permissions. Real tokens
+    // expire in about an hour; the twin answers a fixed far-future expiry (never the clock).
+    'apps/create-installation-access-token': async (ctx) => {
+      const app = appOfJwt(ctx);
+      if (!app) return jwtRefused(ctx);
+      const { body } = gh(ctx);
+      const i = ownInstallation(ctx, app);
+      if (!i) return send(ctx, githubNotFound());
+      const id = i.id;
+      const token = `ghs_${createHash('sha256').update(`insttoken:${id}`).digest('hex').slice(0, 36)}`;
+      const perms = (body.permissions as Record<string, string>) ?? i.permissions;
+      // the token is the app's credential for this installation: what it may do, and on which repositories
+      await put(ctx, { operation: 'app_token.create', subjectType: 'app_token', subjectId: `apptoken:${token}`, fields: { token, installation_id: id, app_slug: i.app_slug, account_login: i.account_login, permissions: perms, repository_selection: i.repository_selection, repositories: i.repositories ?? [] } });
+      return ctx.reply({ token, expires_at: '2100-01-01T00:00:00Z', permissions: perms, repository_selection: i.repository_selection }, 201);
+    },
+  };
+}

package/src/semantics/branches.ts

@@ -0,0 +1,133 @@
+// A repository's branches and their protection: the persisted protection config (required status
+// checks, admin enforcement, required reviews, restrictions) that merge gates read back. A branch is
+// created by a ref write (semantics/git.ts), a push, or its first protection write.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { githubNotFound, isAncestorInPlane, mergeIntoBranchInPlane, normalizeRequiredStatusChecks, paginate, resolvePlaneRef, toGithubBranch, toGithubBranchProtection, updateGitRefInPlane, type GithubBranch } from '../github-twin.ts';
+import { announce, gh, put, send } from './shared.ts';
+
+const SYNC_DOCS = 'https://docs.github.com/rest/branches/branches#sync-a-fork-branch-with-the-upstream-repository';
+/** A fork's branch brought up to date with the same branch of the repository it was forked from: fast-forwarded when
+ *  it has nothing of its own, merged when it has, 409 when the merge conflicts, 422 when the repository is no fork or
+ *  names no branch (docs.github.com/rest/branches/branches#sync-a-fork-branch-with-the-upstream-repository). */
+const syncFork: Semantics = async (ctx) => {
+  const { repo, body, root, occurredAt, state } = gh(ctx);
+  const fork = state().repos.find((r) => r.full_name === repo);
+  if (!fork) return send(ctx, githubNotFound());
+  const branch = typeof body.branch === 'string' ? body.branch : '';
+  const upstream = fork.parent_full_name;
+  const theirs = upstream && branch ? await resolvePlaneRef(upstream, `refs/heads/${branch}`, branch, root) : null;
+  const ours = branch ? await resolvePlaneRef(repo, `refs/heads/${branch}`, branch, root) : null;
+  if (!upstream || !theirs || !ours) return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Repository', field: 'branch', code: 'invalid' }], documentation_url: SYNC_DOCS }, 422);
+  const base_branch = `${upstream.split('/')[0]}:${branch}`;
+  if (ours === theirs || await isAncestorInPlane(repo, theirs, ours, root)) return ctx.reply({ message: `This branch is not behind the upstream ${base_branch}.`, merge_type: 'none', base_branch });
+  const forward = await isAncestorInPlane(repo, ours, theirs, root);
+  const landed = forward ? (await updateGitRefInPlane(repo, `refs/heads/${branch}`, theirs, root, ours) ? { sha: theirs } : null) : await mergeIntoBranchInPlane(repo, branch, theirs, `Merge branch '${branch}' of github.com:${upstream}`, 'merge', occurredAt, root);
+  if (!landed || 'conflict' in landed) return ctx.reply({ message: 'There are merge conflicts', documentation_url: SYNC_DOCS }, 409);
+  await put(ctx, { operation: 'git_ref.update', subjectType: 'git_ref', subjectId: `gitref:${repo}#refs/heads/${branch}`, fields: { repository: repo, ref: `refs/heads/${branch}`, object_sha: landed.sha, object_type: 'commit' } });
+  await put(ctx, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${repo}#${branch}`, fields: { repository: repo, name: branch, commit_sha: landed.sha } });
+  await announce(ctx, [{ event: 'push', action: '', repository: repo, number: 0, ref: `refs/heads/${branch}`, before: ours, after: landed.sha }]);
+  return ctx.reply({ message: forward ? `Successfully fetched and fast-forwarded from upstream ${base_branch}.` : `Successfully fetched and merged from upstream ${base_branch}.`, merge_type: forward ? 'fast-forward' : 'merge', base_branch });
+};
+
+const notProtected = { status: 404, body: { message: 'Branch not protected', documentation_url: 'https://docs.github.com/rest/branches/branch-protection' } };
+
+/** The branch a protection path names (a name may hold slashes). */
+function branchOf(ctx: SemanticsContext): { name: string; b: GithubBranch | undefined } {
+  const { repo, seg, state } = gh(ctx);
+  const name = decodeURIComponent(seg[4]!);
+  return { name, b: state().branches.find((x) => x.repository === repo && x.name === name) };
+}
+const protectionUrl = (repo: string, name: string): string => `https://api.github.com/repos/${repo}/branches/${encodeURIComponent(name)}/protection`;
+
+/** Write a protected branch's config. */
+const protect = (ctx: SemanticsContext, name: string, b: GithubBranch, protection_config: unknown): Promise<Record<string, unknown>> =>
+  put(ctx, { operation: 'branch.protect', subjectType: 'branch', subjectId: `branch:${gh(ctx).repo}#${name}`, fields: { repository: gh(ctx).repo, name, commit_sha: b.commit_sha, protected: true, protection_config } });
+
+export function branchesSemantics(): Record<string, Semantics> {
+  const reposListBranches: Semantics = async (ctx) => {
+    const { repo, query, state } = gh(ctx);
+    return ctx.reply(paginate(state().branches.filter((b) => b.repository === repo), query).map(toGithubBranch));
+  };
+  const reposGetBranchProtection: Semantics = async (ctx) => {
+    const { b } = branchOf(ctx);
+    return send(ctx, b?.protected ? { status: 200, body: toGithubBranchProtection(b) } : notProtected);
+  };
+  const reposGetStatusChecksProtection: Semantics = async (ctx) => {
+    const { repo } = gh(ctx);
+    const { name, b } = branchOf(ctx);
+    if (!b?.protected) return send(ctx, notProtected);
+    const rsc = b.protection_config?.required_status_checks;
+    if (!rsc) return ctx.reply({ message: 'Required status checks not enabled', documentation_url: 'https://docs.github.com/rest/branches/branch-protection' }, 404);
+    const base = protectionUrl(repo, name);
+    return ctx.reply({ url: `${base}/required_status_checks`, strict: rsc.strict, contexts: rsc.contexts, contexts_url: `${base}/required_status_checks/contexts`, checks: rsc.checks });
+  };
+  const reposGetAdminBranchProtection: Semantics = async (ctx) => {
+    const { repo } = gh(ctx);
+    const { name, b } = branchOf(ctx);
+    if (!b?.protected) return send(ctx, notProtected);
+    return ctx.reply({ url: `${protectionUrl(repo, name)}/enforce_admins`, enabled: b.protection_config?.enforce_admins ?? false });
+  };
+  const reposUpdateStatusCheckProtection: Semantics = async (ctx) => {
+    const { repo, body } = gh(ctx);
+    const { name, b } = branchOf(ctx);
+    if (!b?.protected) return send(ctx, githubNotFound());
+    const prev = b.protection_config?.required_status_checks ?? { strict: false, contexts: [], checks: [] };
+    const next = normalizeRequiredStatusChecks({ strict: body.strict ?? prev.strict, contexts: body.contexts ?? (body.checks === undefined ? prev.contexts : undefined), checks: body.checks })!; const base = protectionUrl(repo, name); await protect(ctx, name, b, { ...(b.protection_config ?? {}), required_status_checks: next });
+    return ctx.reply({ url: `${base}/required_status_checks`, strict: next.strict, contexts: next.contexts, contexts_url: `${base}/required_status_checks/contexts`, checks: next.checks });
+  };
+  return {
+    'repos/merge-upstream': syncFork,
+    'repos/list-branches': reposListBranches,
+    // a branch name may hold slashes
+    'repos/get-branch': async (ctx) => {
+      const { repo, seg, state } = gh(ctx);
+      const name = decodeURIComponent(seg.slice(4).join('/'));
+      const b = state().branches.find((x) => x.repository === repo && x.name === name);
+      return send(ctx, b ? { status: 200, body: toGithubBranch(b) } : githubNotFound());
+    },
+    // the persisted config back out; 404 "Branch not protected" when protection is off
+    'repos/get-branch-protection': reposGetBranchProtection,
+    'repos/get-status-checks-protection': reposGetStatusChecksProtection,
+    'repos/get-admin-branch-protection': reposGetAdminBranchProtection,
+    // Protect and persist the config. GitHub 422s unless all four keys are present (each nullable,
+    // never omittable). A branch the twin has not seen is created by its first protection write.
+    'repos/update-branch-protection': async (ctx) => protection(ctx, true),
+    'repos/delete-branch-protection': async (ctx) => protection(ctx, false),
+    // update the required checks of a protected branch (404 when not protected)
+    'repos/update-status-check-protection': reposUpdateStatusCheckProtection,
+    'repos/set-admin-branch-protection': async (ctx) => enforceAdmins(ctx, true),
+    'repos/delete-admin-branch-protection': async (ctx) => enforceAdmins(ctx, false),
+  };
+}
+
+async function protection(ctx: SemanticsContext, protecting: boolean): Promise<Response> {
+  const { repo, body, state } = gh(ctx);
+  const { name, b } = branchOf(ctx);
+  // a branch must exist to be protected (docs.github.com/rest/branches/branch-protection#update-branch-protection)
+  if (!b) return ctx.reply({ message: 'Branch not found', documentation_url: 'https://docs.github.com/rest/branches/branch-protection#update-branch-protection' }, 404);
+  if (protecting) {
+    const missingKeys = (['required_status_checks', 'enforce_admins', 'required_pull_request_reviews', 'restrictions'] as const).filter((k) => !(k in body));
+    if (missingKeys.length) return ctx.reply({ message: 'Validation Failed', errors: missingKeys.map((field) => ({ resource: 'BranchProtection', field, code: 'missing_field' })) }, 422);
+  }
+  const protection_config = protecting
+    ? {
+        required_status_checks: normalizeRequiredStatusChecks(body.required_status_checks),
+        enforce_admins: body.enforce_admins === true,
+        required_pull_request_reviews: body.required_pull_request_reviews && typeof body.required_pull_request_reviews === 'object' ? (body.required_pull_request_reviews as Record<string, unknown>) : null,
+        restrictions: body.restrictions && typeof body.restrictions === 'object' ? (body.restrictions as Record<string, unknown>) : null,
+      }
+    : null;
+  await put(ctx, { operation: protecting ? 'branch.protect' : 'branch.unprotect', subjectType: 'branch', subjectId: `branch:${repo}#${name}`, fields: { repository: repo, name, commit_sha: b.commit_sha, protected: protecting, protection_config } });
+  if (!protecting) return send(ctx, { status: 204, body: undefined });
+  return ctx.reply(toGithubBranchProtection(state().branches.find((x) => x.repository === repo && x.name === name)!));
+}
+
+/** Toggle admin enforcement on a protected branch (404 when not protected). */
+async function enforceAdmins(ctx: SemanticsContext, enabled: boolean): Promise<Response> {
+  const { repo } = gh(ctx);
+  const { name, b } = branchOf(ctx);
+  if (!b?.protected) return send(ctx, githubNotFound());
+  await protect(ctx, name, b, { ...(b.protection_config ?? {}), enforce_admins: enabled });
+  if (!enabled) return send(ctx, { status: 204, body: undefined });
+  return ctx.reply({ url: `${protectionUrl(repo, name)}/enforce_admins`, enabled });
+}

package/src/semantics/checks.ts

@@ -0,0 +1,163 @@
+// Commit statuses and check runs (the twin's CI surface: nothing runs; callers post the results) and
+// the check suite the twin groups a commit's runs into. A success that completes a pull request's
+// required checks lands it when auto-merge is armed. Anyone who can write the repository posts a commit
+// status, but only a GitHub App writes check runs, through an installation token that grants checks:write
+// on the repository (docs.github.com/rest/checks/runs#create-a-check-run: "OAuth apps and personal access
+// tokens (classic) cannot use this endpoint").
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import {
+  combineStatuses, githubNotFound, paginate, planeCommitBody, toGithubAnnotation, toGithubCheckRun, toGithubCheckSuite, toGithubStatus,
+} from '../github-twin.ts';
+import { gh, nextSeq, put, send } from './shared.ts';
+
+const refOf = (ctx: SemanticsContext): string => decodeURIComponent(gh(ctx).seg[4]!);
+
+/** The app a check-run write comes from, or GitHub's refusal when it is not an installed app allowed checks:write on
+ *  this repository. */
+function appWriting(ctx: SemanticsContext): { refused: Response } | { app: string } {
+  const { token, repo } = gh(ctx);
+  const docs = 'https://docs.github.com/rest/checks/runs#create-a-check-run';
+  const grant = token ? ctx.tree().find((r) => r.type === 'app_token' && r.token === token && r.deleted !== true) : undefined;
+  if (!grant) return { refused: ctx.reply({ message: 'You must authenticate via a GitHub App.', documentation_url: docs }, 403) };
+  const names = (grant.repositories as string[] | undefined) ?? [];
+  const covers = grant.repository_selection !== 'selected' ? repo.split('/')[0] === grant.account_login : names.some((n) => n === repo || `${String(grant.account_login)}/${n}` === repo);
+  if ((grant.permissions as Record<string, string> | undefined)?.checks !== 'write' || !covers) return { refused: ctx.reply({ message: 'Resource not accessible by integration', documentation_url: docs }, 403) };
+  return { app: String(grant.app_slug) };
+}
+/** The commit a suite checks, as GitHub's simple-commit, read from the repository's git plane when it holds it. */
+async function headCommit(repo: string, sha: string, root?: string): Promise<{ head_commit?: Record<string, unknown> }> {
+  const c = await planeCommitBody(repo, sha, root) as { commit?: { message?: string; author?: { name?: string; email?: string; date?: string }; committer?: { name?: string; email?: string }; tree?: { sha?: string } } } | null;
+  if (!c?.commit) return {};
+  const who = (p?: { name?: string; email?: string }) => ({ name: p?.name ?? '', email: p?.email ?? '' });
+  return { head_commit: { id: sha, tree_id: c.commit.tree?.sha ?? '', message: c.commit.message ?? '', timestamp: c.commit.author?.date ?? '', author: who(c.commit.author), committer: who(c.commit.committer) } };
+}
+
+export function checksSemantics(): Record<string, Semantics> {
+  const reposGetCombinedStatusForRef: Semantics = async (ctx) => {
+    const { repo, state } = gh(ctx);
+    return ctx.reply(combineStatuses(repo, refOf(ctx), state().statuses));
+  };
+  const reposListCommitStatusesForRef: Semantics = async (ctx) => {
+    const { repo, query, state } = gh(ctx);
+    const ref = refOf(ctx);
+    return ctx.reply(paginate(state().statuses.filter((s) => s.repository === repo && s.sha === ref).sort((a, b) => b.id - a.id), query).map(toGithubStatus));
+  };
+  const reposCreateCommitStatus: Semantics = async (ctx) => {
+    const { repo, body, occurredAt } = gh(ctx);
+    const sha = refOf(ctx);
+    if (!body.state) return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Status', field: 'state', code: 'missing_field' }] }, 422);
+    if (!['error', 'failure', 'pending', 'success'].includes(body.state)) return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Status', field: 'state', code: 'invalid' }] }, 422);
+    const seq = nextSeq(ctx, 'status');
+    const fields = { repository: repo, sha, state: body.state, context: body.context ?? 'default', description: body.description, target_url: body.target_url, created_at: occurredAt, updated_at: occurredAt };
+    await put(ctx, { operation: 'commit_status.create', subjectType: 'commit_status', subjectId: `status:${seq}`, fields });
+    return ctx.reply(toGithubStatus({ id: seq, ...fields }), 201);
+  };
+  const checksListSuitesForRef: Semantics = async (ctx) => {
+    const { repo, state, root } = gh(ctx);
+    const ref = refOf(ctx);
+    const st = state();
+    const apps = [...new Set(st.checkRuns.filter((c) => c.repository === repo && c.head_sha === ref).map((c) => c.app_slug))];
+    const head = await headCommit(repo, ref, root);
+    const suites = apps.map((app) => ({ ...toGithubCheckSuite(repo, ref, st.checkRuns, app, st), ...head }));
+    return ctx.reply({ total_count: suites.length, check_suites: suites });
+  };
+  const checksGet: Semantics = async (ctx) => {
+    const { repo, state } = gh(ctx);
+    const cr = state().checkRuns.find((c) => c.repository === repo && c.id === Number(refOf(ctx)));
+    return send(ctx, cr ? { status: 200, body: toGithubCheckRun(cr, state()) } : githubNotFound());
+  };
+  const checksListAnnotations: Semantics = async (ctx) => {
+    const { repo, query, state } = gh(ctx);
+    const cr = state().checkRuns.find((c) => c.repository === repo && c.id === Number(refOf(ctx)));
+    if (!cr) return send(ctx, githubNotFound());
+    return ctx.reply(paginate(cr.annotations ?? [], query).map((an) => toGithubAnnotation(cr, an)));
+  };
+  const checksGetSuite: Semantics = async (ctx) => {
+    const { repo, state, root } = gh(ctx);
+    const st = state();
+    const id = Number(refOf(ctx));
+    const cr = st.checkRuns.find((c) => c.repository === repo && (c.check_suite_id ?? 0) === id);
+    return send(ctx, cr ? { status: 200, body: { ...toGithubCheckSuite(repo, cr.head_sha, st.checkRuns, cr.app_slug, st), ...(await headCommit(repo, cr.head_sha, root)) } } : githubNotFound());
+  };
+  const checksListForSuite: Semantics = async (ctx) => {
+    const { repo, query, state } = gh(ctx);
+    const st = state();
+    const id = Number(refOf(ctx));
+    if (!st.checkRuns.find((c) => c.repository === repo && (c.check_suite_id ?? 0) === id)) return send(ctx, githubNotFound());
+    const items = st.checkRuns.filter((c) => c.repository === repo && (c.check_suite_id ?? 0) === id).sort((a, b) => a.id - b.id);
+    return ctx.reply({ total_count: items.length, check_runs: paginate(items, query).map((c) => toGithubCheckRun(c, state())) });
+  };
+  const checksUpdate: Semantics = async (ctx) => {
+    const writer = appWriting(ctx);
+    if ('refused' in writer) return writer.refused;
+    const { repo, body, occurredAt, state } = gh(ctx);
+    const id = Number(refOf(ctx));
+    const existing = state().checkRuns.find((c) => c.repository === repo && c.id === id);
+    if (!existing) return send(ctx, githubNotFound());
+    // an app updates only the check runs it created
+    if (existing.app_slug && existing.app_slug !== writer.app) return ctx.reply({ message: 'Resource not accessible by integration', documentation_url: 'https://docs.github.com/rest/checks/runs#update-a-check-run' }, 403);
+    const fields: Record<string, unknown> = { repository: repo, head_sha: existing.head_sha, name: existing.name, app_slug: existing.app_slug ?? writer.app };
+    if (body.status !== undefined) fields.status = String(body.status);
+    if (body.conclusion !== undefined) { fields.conclusion = String(body.conclusion); fields.status = body.status ?? 'completed'; fields.completed_at = body.completed_at ?? occurredAt; }
+    fields.started_at = existing.started_at;
+    const output = body.output as Record<string, any> | undefined;
+    if (output) {
+      if (output.title !== undefined) fields.output_title = String(output.title);
+      if (output.summary !== undefined) fields.output_summary = String(output.summary);
+      if (output.text !== undefined) fields.output_text = String(output.text);
+      const anns = Array.isArray(output.annotations) ? output.annotations : (existing.annotations ?? []);
+      fields.annotations = (anns as any[]).map((an) => ({
+        path: String(an.path), start_line: Number(an.start_line), end_line: Number(an.end_line),
+        annotation_level: String(an.annotation_level), message: String(an.message),
+        title: an.title, raw_details: an.raw_details, start_column: an.start_column, end_column: an.end_column,
+      }));
+    } else if (existing.annotations) { fields.annotations = existing.annotations; }
+    await put(ctx, { operation: 'check_run.update', subjectType: 'check_run', subjectId: `check:${id}`, fields });
+    return ctx.reply(toGithubCheckRun(state().checkRuns.find((c) => c.id === id)!, state()));
+  };
+  const checksRerequestSuite: Semantics = async (ctx) => {
+    const { repo, state } = gh(ctx);
+    const id = Number(refOf(ctx));
+    if (!state().checkRuns.find((c) => c.repository === repo && (c.check_suite_id ?? 0) === id)) return send(ctx, githubNotFound());
+    return ctx.reply({}, 201);
+  };
+  return {
+    'repos/get-combined-status-for-ref': reposGetCombinedStatusForRef,
+    // newest first
+    'repos/list-commit-statuses-for-ref': reposListCommitStatusesForRef,
+    // 422 without a state or with one outside the enum
+    'repos/create-commit-status': reposCreateCommitStatus,
+    // {total_count, check_runs}, paginated over check_runs
+    'checks/list-for-ref': async (ctx) => {
+      const { repo, query, state } = gh(ctx);
+      const ref = refOf(ctx);
+      const items = state().checkRuns.filter((c) => c.repository === repo && c.head_sha === ref).sort((a, b) => a.id - b.id);
+      return ctx.reply({ total_count: items.length, check_runs: paginate(items, query).map((c) => toGithubCheckRun(c, state())) });
+    },
+    // one suite per app that ran checks on the commit
+    'checks/list-suites-for-ref': checksListSuitesForRef,
+    'checks/get': checksGet,
+    'checks/list-annotations': checksListAnnotations,
+    'checks/get-suite': checksGetSuite,
+    'checks/list-for-suite': checksListForSuite,
+    // queued unless it carries a conclusion (then completed)
+    'checks/create': async (ctx) => {
+      const writer = appWriting(ctx);
+      if ('refused' in writer) return writer.refused;
+      const { repo, body, occurredAt, state } = gh(ctx);
+      const missing = (['name', 'head_sha'] as const).filter((k) => !body[k]);
+      if (missing.length) return ctx.reply({ message: 'Validation Failed', errors: missing.map((field) => ({ resource: 'CheckRun', field, code: 'missing_field' })) }, 422);
+      const seq = nextSeq(ctx, 'check');
+      const status = body.status ?? (body.conclusion ? 'completed' : 'queued');
+      const completed_at = body.conclusion ? (body.completed_at ?? occurredAt) : undefined;
+      const fields: Record<string, unknown> = { repository: repo, head_sha: body.head_sha, name: body.name, status, conclusion: body.conclusion, details_url: body.details_url, started_at: body.started_at ?? occurredAt, app_slug: writer.app, ...(body.external_id !== undefined ? { external_id: String(body.external_id) } : {}) };
+      if (completed_at !== undefined) fields.completed_at = completed_at;
+      await put(ctx, { operation: 'check_run.create', subjectType: 'check_run', subjectId: `check:${seq}`, fields });
+      return ctx.reply(toGithubCheckRun(state().checkRuns.find((c) => c.id === seq)!, state()), 201);
+    },
+    // status, conclusion (which completes the run), and output with its annotations
+    'checks/update': checksUpdate,
+    // 201; nothing reruns
+    'checks/rerequest-suite': checksRerequestSuite,
+  };
+}