@volter/twin-github 0.1.0

package/src/github-connector.ts

@@ -0,0 +1,644 @@
+// GitHub CONNECTOR — the live-vendor pull/push lifecycle for the GitHub twin.
+//
+// This is the missing category: code that talks to REAL GitHub (pull) and pushes a
+// twin change back (push), with the same code path exercised offline. The vendor I/O
+// is an INJECTED octokit-like executor (the auth-boundary, hard-problem #6): the
+// kernel and twin hold NO token.
+//   - offline/tests pass a fake executor (deterministic, no network),
+//   - live runs pass `liveGithubExecute(token)` (the user's own PAT, via the real
+//     @octokit/rest REST client) — NEVER imported here, so this pack takes no SDK
+//     dependency and never opens a socket on its own.
+// Mirrors the Linear/Slack connector pattern: pull → fold evidence; push pending
+// actions → injected executor → confirmAction (suppress the local projection).
+//
+// CONTENT ON PULL (the GitHub-specific contract): the `github` world is a CONTENT
+// mirror for the text GitHub's REST API actually returns. An OBSERVED pull folds the
+// PR/issue title, body, state and the BODIES of reviews/comments — alongside the
+// metadata (number, repo, base ref, head sha, file/commit COUNTS). Pull NEVER fabricates
+// text it didn't receive; the one excluded thing is the Non-goal — actual repository
+// file CONTENTS (git blob bytes) — which the pull does not fetch. Content-bearing twin
+// state thus comes from BOTH the observed fold and LOCAL writes, which push reconciles.
+import { appendEvent, confirmAction, pendingActions, syncPull } from '@volter/twin';
+import type { SyncResource, WorldServiceEvent } from '@volter/twin';
+
+const SERVICE = 'github';
+
+// ---------------------------------------------------------------------------
+// The injected executor (auth-boundary).
+// ---------------------------------------------------------------------------
+
+/**
+ * The minimal real-GitHub REST surface the connector needs. A real `@octokit/rest`
+ * client is structurally adaptable to this (its `request(route, params)` returns
+ * `{ status, data }`) — the consumer wires it; this pack never imports it. `request`
+ * is the single credentialed boundary: in tests it's a fake, live it's the user's
+ * token-bound octokit. It maps a REST `route` ("METHOD /path") + params to a result.
+ */
+export interface GithubExecute {
+  request(
+    route: string,
+    params?: Record<string, unknown>,
+  ): Promise<{ status: number; data: any }>;
+}
+
+/**
+ * A live executor against the real GitHub REST API (token = the user's own PAT).
+ * Constructed with the real @octokit/rest in PROD by the CALLER and passed in; this
+ * helper shows the shape without importing the SDK. Kept tiny + dependency-free: it
+ * uses `fetch`, so the pack pulls in no network client. Live runs may instead pass a
+ * real `new Octokit({ auth }).request` bound into a `{ request }` object.
+ */
+export function liveGithubExecute(token: string, baseUrl = 'https://api.github.com'): GithubExecute {
+  return {
+    async request(route, params = {}) {
+      const sp = route.indexOf(' ');
+      const method = route.slice(0, sp);
+      let path = route.slice(sp + 1);
+      const rest: Record<string, unknown> = {};
+      // Substitute {param} path templates; remaining params become the QUERY STRING on
+      // GET/HEAD and the JSON body otherwise. (GET has no body, so leftover params were
+      // silently DROPPED before — every list read got GitHub's defaults, state=open
+      // per_page=30, which is how merged PRs froze out of observation: the poll's
+      // state:'closed' never reached the API. octokit does this same split.)
+      for (const [k, v] of Object.entries(params)) {
+        const token = `{${k}}`;
+        if (path.includes(token)) path = path.replace(token, encodeURIComponent(String(v)));
+        else rest[k] = v;
+      }
+      const isRead = method === 'GET' || method === 'HEAD';
+      if (isRead && Object.keys(rest).length > 0) {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(rest)) qs.set(k, String(v));
+        path += `${path.includes('?') ? '&' : '?'}${qs.toString()}`;
+      }
+      const res = await fetch(`${baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: 'application/vnd.github+json',
+          'Content-Type': 'application/json',
+        },
+        ...(isRead ? {} : { body: JSON.stringify(rest) }),
+      });
+      return { status: res.status, data: res.status === 204 ? undefined : await res.json() };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// PULL (real → twin): fold OBSERVED content + metadata.
+// ---------------------------------------------------------------------------
+
+// The shape of an observed PR. Carries the CONTENT the REST PR object returns (title/
+// body/state) plus metadata (counts + refs) and the BODIES of reviews/comments. The
+// only excluded thing is the Non-goal: actual repository file CONTENTS are never pulled.
+type ObservedReview = { state?: string; body?: string; submittedAt?: string };
+type ObservedComment = { body?: string; createdAt?: string };
+type ObservedPr = {
+  id: string; // owner/repo#number
+  number: number;
+  repository: string;
+  title?: string;
+  body?: string;
+  state?: string;
+  draft?: boolean;
+  merged?: boolean;
+  mergeCommit?: string;
+  baseRef?: string;
+  headSha?: string;
+  changedFiles?: number;
+  commitsCount?: number;
+  reviewCount: number;
+  commentCount: number;
+  reviews: ObservedReview[];
+  comments: ObservedComment[];
+};
+
+// The shape of an observed ISSUE (GET .../issues with PRs excluded). Carries content
+// (title/body/state) — issues exist on pull as first-class objects, not just via local
+// writes. Numbers share the per-repo PR/issue space (real GitHub).
+type ObservedIssue = {
+  id: string; // owner/repo#issue:number
+  number: number;
+  repository: string;
+  title?: string;
+  body?: string;
+  state?: string;
+};
+
+/**
+ * Pull OBSERVED PRs for a repo via the injected executor. Folds the CONTENT the REST
+ * PR object returns (title/body/state) plus metadata (counts/refs) and the BODIES of
+ * each review + issue comment. The ONLY thing not pulled is the Non-goal — actual
+ * repository file CONTENTS (per-file diffs/blob bytes are not fetched here).
+ */
+export async function pullGithubPrs(
+  execute: GithubExecute,
+  opts: { owner: string; repo: string; state?: 'open' | 'closed' | 'all'; perPage?: number },
+): Promise<ObservedPr[]> {
+  const { owner, repo } = opts;
+  const repository = `${owner}/${repo}`;
+  const list = await execute.request('GET /repos/{owner}/{repo}/pulls', {
+    owner, repo, state: opts.state ?? 'open', per_page: opts.perPage ?? 30,
+  });
+  if (list.status >= 400) throw new Error(`github pull failed (list pulls): HTTP ${list.status}`);
+  const nodes: any[] = Array.isArray(list.data) ? list.data : [];
+  const out: ObservedPr[] = [];
+  for (const n of nodes) {
+    const number = Number(n.number);
+    // Reviews + comments: fold the BODIES (content) and count. A real connector would
+    // page these; the fake returns the list, which we map to body-bearing entries.
+    const reviewsRes = await execute.request('GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews', { owner, repo, pull_number: number });
+    const commentsRes = await execute.request('GET /repos/{owner}/{repo}/issues/{issue_number}/comments', { owner, repo, issue_number: number });
+    const reviewNodes: any[] = Array.isArray(reviewsRes.data) ? reviewsRes.data : [];
+    const commentNodes: any[] = Array.isArray(commentsRes.data) ? commentsRes.data : [];
+    const pr: ObservedPr = {
+      id: `${repository}#${number}`,
+      number,
+      repository,
+      reviewCount: reviewNodes.length,
+      commentCount: commentNodes.length,
+      reviews: reviewNodes.map((r) => {
+        const review: ObservedReview = {};
+        if (r.state !== undefined && r.state !== null) review.state = String(r.state);
+        if (r.body !== undefined && r.body !== null) review.body = String(r.body);
+        if (r.submitted_at !== undefined && r.submitted_at !== null) review.submittedAt = String(r.submitted_at);
+        return review;
+      }),
+      comments: commentNodes.map((c) => {
+        const comment: ObservedComment = {};
+        if (c.body !== undefined && c.body !== null) comment.body = String(c.body);
+        if (c.created_at !== undefined && c.created_at !== null) comment.createdAt = String(c.created_at);
+        return comment;
+      }),
+    };
+    // CONTENT: title/body/state are real text the REST PR object returns — fold them.
+    if (n.title !== undefined && n.title !== null) pr.title = String(n.title);
+    if (n.body !== undefined && n.body !== null) pr.body = String(n.body);
+    if (n.state !== undefined && n.state !== null) pr.state = String(n.state);
+    // draft + merge state: the REST PR object's `draft` flag and merge status are
+    // first-class forge facts (a validator gates delivery on them), so fold them like
+    // state. GitHub marks a merged PR as state:closed with merged_at set, so derive
+    // `merged` from merged_at (or the explicit `merged` on the single-PR GET).
+    if (n.draft !== undefined && n.draft !== null) pr.draft = Boolean(n.draft);
+    if (n.merged !== undefined || n.merged_at !== undefined) pr.merged = Boolean(n.merged ?? n.merged_at);
+    if (pr.merged && n.merge_commit_sha !== undefined && n.merge_commit_sha !== null) pr.mergeCommit = String(n.merge_commit_sha);
+    // base/head refs ride along when present.
+    if (n.base?.ref !== undefined) pr.baseRef = String(n.base.ref);
+    if (n.head?.sha !== undefined) pr.headSha = String(n.head.sha);
+    // changed-files / commits COUNTS are metadata; per-file diffs are NOT pulled (Non-goal).
+    if (n.changed_files !== undefined) pr.changedFiles = Number(n.changed_files);
+    if (n.commits !== undefined) pr.commitsCount = Number(n.commits);
+    out.push(pr);
+  }
+  return out;
+}
+
+/**
+ * Pull OBSERVED ISSUES for a repo via the injected executor (GET /repos/:o/:r/issues),
+ * EXCLUDING pull requests — the issues endpoint returns PRs too (each PR is an issue),
+ * distinguished by a `pull_request` field, which we filter out so PRs only flow through
+ * pullGithubPrs. Folds each issue's content (title/body/state). Numbers share the
+ * per-repo PR/issue space (real GitHub).
+ */
+export async function pullGithubIssues(
+  execute: GithubExecute,
+  opts: { owner: string; repo: string; state?: 'open' | 'closed' | 'all'; perPage?: number },
+): Promise<ObservedIssue[]> {
+  const { owner, repo } = opts;
+  const repository = `${owner}/${repo}`;
+  const list = await execute.request('GET /repos/{owner}/{repo}/issues', {
+    owner, repo, state: opts.state ?? 'open', per_page: opts.perPage ?? 30,
+  });
+  if (list.status >= 400) throw new Error(`github pull failed (list issues): HTTP ${list.status}`);
+  const nodes: any[] = Array.isArray(list.data) ? list.data : [];
+  const out: ObservedIssue[] = [];
+  for (const n of nodes) {
+    // The issues endpoint includes PRs (they carry a `pull_request` object) — exclude them.
+    if (n.pull_request !== undefined && n.pull_request !== null) continue;
+    const number = Number(n.number);
+    const iss: ObservedIssue = { id: `${repository}#issue:${number}`, number, repository };
+    if (n.title !== undefined && n.title !== null) iss.title = String(n.title);
+    if (n.body !== undefined && n.body !== null) iss.body = String(n.body);
+    if (n.state !== undefined && n.state !== null) iss.state = String(n.state);
+    out.push(iss);
+  }
+  return out;
+}
+
+// Map observed PRs to the generic SyncResource[] shape (the Linear/Slack-shared pull
+// contract). Carries CONTENT (title/body/state) now that pull is a content mirror, plus
+// the refs. baseRef/headSha ride under their twin names so the github fold (which reads
+// data.changed.baseRef.after / .headSha.after) picks them up.
+export function observedPrsToResources(prs: ObservedPr[]): SyncResource[] {
+  return prs.map((p) => {
+    const fields: SyncResource['fields'] = { number: p.number, repository: p.repository };
+    if (p.title !== undefined) fields.title = p.title;
+    if (p.body !== undefined) fields.body = p.body;
+    if (p.state !== undefined) fields.state = p.state;
+    // draft + merge state ride along so the generic delta connector (which diffs these
+    // SyncResources) captures a draft→ready or open→merged transition — and the github
+    // fold reads f.draft / f.merged / f.mergeCommit back onto the materialized PR.
+    if (p.draft !== undefined) fields.draft = p.draft;
+    if (p.merged !== undefined) fields.merged = p.merged;
+    if (p.mergeCommit !== undefined) fields.mergeCommit = p.mergeCommit;
+    if (p.baseRef !== undefined) fields.baseRef = p.baseRef;
+    if (p.headSha !== undefined) fields.headSha = p.headSha;
+    return { type: 'pull_request', id: p.id, fields };
+  });
+}
+
+// Map observed issues to SyncResource[] (content-bearing: title/body/state).
+export function observedIssuesToResources(issues: ObservedIssue[]): SyncResource[] {
+  return issues.map((i) => {
+    const fields: SyncResource['fields'] = { number: i.number, repository: i.repository };
+    if (i.title !== undefined) fields.title = i.title;
+    if (i.body !== undefined) fields.body = i.body;
+    if (i.state !== undefined) fields.state = i.state;
+    return { type: 'issue', id: i.id, fields };
+  });
+}
+
+// A content-hashed, deterministic id for a folded evidence snapshot — never random,
+// never Date.now. Re-folding the SAME observed evidence yields the same id, so
+// appendEvent dedups it (idempotent pull). A changed observation yields a new id.
+function evidenceHash(parts: unknown[]): string {
+  // Reuse the kernel's hashing via a stable JSON of the parts; createHash isn't
+  // re-exported, so use a small FNV-1a over the canonical string (deterministic).
+  const s = JSON.stringify(parts);
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+// Fold ONE observed PR as a `github.pull_request` event — the exact shape githubState()
+// reads (content + metadata top-level + base/head under `changed`). This carries the
+// COUNTS the generic delta path can't (githubState reads changedFiles/commitsCount
+// top-level) and the CONTENT (title/body/state) the pull now mirrors. Idempotent via a
+// content hash in the event id + idempotencyKey: a re-pull of identical observation
+// appends nothing; a changed observation appends a new event.
+function foldObservedPr(pr: ObservedPr, occurredAt: string, root?: string): boolean {
+  const data: Record<string, unknown> = {
+    number: pr.number,
+    repository: pr.repository,
+    changed: {
+      ...(pr.baseRef !== undefined ? { baseRef: { after: pr.baseRef } } : {}),
+      ...(pr.headSha !== undefined ? { headSha: { after: pr.headSha } } : {}),
+    },
+  };
+  if (pr.title !== undefined) data.title = pr.title;
+  if (pr.body !== undefined) data.body = pr.body;
+  if (pr.state !== undefined) data.state = pr.state;
+  if (pr.draft !== undefined) data.draft = pr.draft;
+  if (pr.merged !== undefined) data.merged = pr.merged;
+  if (pr.mergeCommit !== undefined) data.mergeCommit = pr.mergeCommit;
+  if (pr.changedFiles !== undefined) data.changedFiles = pr.changedFiles;
+  if (pr.commitsCount !== undefined) data.commitsCount = pr.commitsCount;
+  // draft/merged/mergeCommit are in the hash so a draft→ready or open→merged transition
+  // re-folds (a new event) rather than being deduped away as an unchanged observation.
+  const hash = evidenceHash([pr.number, pr.repository, pr.title, pr.body, pr.state, pr.draft, pr.merged, pr.mergeCommit, pr.baseRef, pr.headSha, pr.changedFiles, pr.commitsCount]);
+  const id = `github:pull_request:${pr.id}:${hash}`;
+  const event = {
+    id,
+    service: SERVICE,
+    type: 'github.pull_request',
+    schemaVersion: 1,
+    idempotencyKey: id,
+    occurredAt,
+    observedAt: occurredAt,
+    origin: 'connector',
+    subject: { type: 'pull_request', id: pr.id },
+    data,
+  } as unknown as WorldServiceEvent;
+  return appendEvent(event, root).appended;
+}
+
+// Fold each review/comment as its own event, now CARRYING CONTENT (review state/body,
+// comment body) — githubState() reads these to derive review_count/comment_count AND to
+// surface the real text. The event id hashes the content so a changed body re-folds and
+// an unchanged one is idempotent (a deterministic id per (pr, kind, index, content)).
+function foldObservedExistence(pr: ObservedPr, occurredAt: string, root?: string): number {
+  let appended = 0;
+  const emit = (type: string, key: string, extra: Record<string, unknown>): void => {
+    const hash = evidenceHash([type, key, extra]);
+    const id = `github:${type}:${pr.id}:${key}:${hash}`;
+    const event = {
+      id,
+      service: SERVICE,
+      type: `github.${type}`,
+      schemaVersion: 1,
+      idempotencyKey: id,
+      occurredAt,
+      observedAt: occurredAt,
+      origin: 'connector',
+      subject: { type, id: `${pr.id}:${key}` },
+      data: { repository: pr.repository, number: pr.number, ...extra },
+    } as unknown as WorldServiceEvent;
+    if (appendEvent(event, root).appended) appended += 1;
+  };
+  pr.reviews.forEach((r, i) => emit('pull_request_review', `rev${i}`, {
+    ...(r.state !== undefined ? { state: r.state } : {}),
+    ...(r.body !== undefined ? { body: r.body } : {}),
+    ...(r.submittedAt !== undefined ? { submitted_at: r.submittedAt } : {}),
+  }));
+  pr.comments.forEach((c, i) => emit('issue_comment', `c${i}`, {
+    ...(c.body !== undefined ? { body: c.body } : {}),
+    ...(c.createdAt !== undefined ? { created_at: c.createdAt } : {}),
+  }));
+  return appended;
+}
+
+// Fold ONE observed issue as a `github.issue` event carrying its content (title/body/
+// state). githubState()'s observed fold reads these into a first-class issue. Idempotent
+// via a content hash in the id: a re-pull of identical content appends nothing.
+function foldObservedIssue(iss: ObservedIssue, occurredAt: string, root?: string): boolean {
+  const data: Record<string, unknown> = { number: iss.number, repository: iss.repository };
+  if (iss.title !== undefined) data.title = iss.title;
+  if (iss.body !== undefined) data.body = iss.body;
+  if (iss.state !== undefined) data.state = iss.state;
+  const hash = evidenceHash([iss.number, iss.repository, iss.title, iss.body, iss.state]);
+  const id = `github:issue:${iss.id}:${hash}`;
+  const event = {
+    id,
+    service: SERVICE,
+    type: 'github.issue',
+    schemaVersion: 1,
+    idempotencyKey: id,
+    occurredAt,
+    observedAt: occurredAt,
+    origin: 'connector',
+    subject: { type: 'issue', id: iss.id },
+    data,
+  } as unknown as WorldServiceEvent;
+  return appendEvent(event, root).appended;
+}
+
+/**
+ * PULL + FOLD: pull a repo's OBSERVED PRs AND issues and fold them into the twin (mirror
+ * seeding). Folds CONTENT (PR/issue title/body/state, review state/body, comment body)
+ * plus metadata (counts/refs + review/comment existence) — only the Non-goal (repo file
+ * CONTENTS) is excluded. Also threads the same resources through `syncPull` so the generic
+ * shadow-diff dedup path is exercised (the Linear/Slack-shared contract); the github fold
+ * carries the counts/content the generic delta path drops. PRs and issues share ONE
+ * per-repo number space (real GitHub). Re-pulling identical observations appends nothing.
+ */
+export async function syncGithubFromReal(
+  execute: GithubExecute,
+  opts: { owner: string; repo: string; root?: string; occurredAt: string; state?: 'open' | 'closed' | 'all'; perPage?: number },
+): Promise<{ observed: number; deltasAppended: number; eventsAppended: number; issues: number }> {
+  const pullOpts = {
+    owner: opts.owner,
+    repo: opts.repo,
+    ...(opts.state ? { state: opts.state } : {}),
+    ...(opts.perPage ? { perPage: opts.perPage } : {}),
+  };
+  const prs = await pullGithubPrs(execute, pullOpts);
+  const issues = await pullGithubIssues(execute, pullOpts);
+  // Generic shadow-diff fold (content-bearing resources: title/body/state + refs).
+  const pull = syncPull({
+    service: SERVICE,
+    resources: [...observedPrsToResources(prs), ...observedIssuesToResources(issues)],
+    occurredAt: opts.occurredAt,
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+  });
+  // GitHub fold (carries counts + review/comment content the delta drops, plus issues).
+  let eventsAppended = 0;
+  for (const pr of prs) {
+    if (foldObservedPr(pr, opts.occurredAt, opts.root)) eventsAppended += 1;
+    eventsAppended += foldObservedExistence(pr, opts.occurredAt, opts.root);
+  }
+  for (const iss of issues) {
+    if (foldObservedIssue(iss, opts.occurredAt, opts.root)) eventsAppended += 1;
+  }
+  return { observed: pull.observed, deltasAppended: pull.deltasAppended, eventsAppended, issues: issues.length };
+}
+
+// ---------------------------------------------------------------------------
+// PUSH (twin → real): enact pending LOCAL writes, then confirm.
+// ---------------------------------------------------------------------------
+
+/**
+ * Push ONE pending GitHub action to the real vendor via the injected executor. Maps
+ * the twin's local write (recorded by applyGithubWrite as an action with an
+ * `operation` + `fields`) to the matching REST call. The injected `execute.request`
+ * is the SOLE credentialed boundary. Returns the real external id when the API gives
+ * one (PR/issue/milestone number, review/comment/status/check id, merge sha). Throws
+ * on a non-2xx so a failure is never silent.
+ *
+ * Covers EVERY write operation applyGithubWrite emits, each faithfully mapped to its
+ * GitHub REST call (method/path/body):
+ *   pull_request.create                       POST   .../pulls
+ *   pull_request.update                       PATCH  .../pulls/:n (+ PATCH .../issues/:n
+ *                                             for label/assignee/milestone fields)
+ *   pull_request.merge                        PUT    .../pulls/:n/merge
+ *   pull_request.request_reviewers            POST   .../pulls/:n/requested_reviewers
+ *   pull_request.remove_requested_reviewers   DELETE .../pulls/:n/requested_reviewers
+ *   pull_request_review.submit                POST   .../pulls/:n/reviews
+ *   pull_request_review_comment.create        POST   .../pulls/:n/comments
+ *   issue.create                              POST   .../issues
+ *   issue.update                              PATCH  .../issues/:n
+ *   issue_comment.create                      POST   .../issues/:n/comments
+ *   commit_status.create                      POST   .../statuses/:sha
+ *   check_run.create                          POST   .../check-runs
+ *   milestone.create                          POST   .../milestones
+ *   milestone.update                          PATCH  .../milestones/:n
+ * Pushing sends the LOCAL content (titles/bodies/diffs the fork authored) — that is
+ * legitimate (only PULL must not fabricate content). Unknown ops FAIL LOUDLY (throw).
+ */
+export async function pushGithubAction(
+  execute: GithubExecute,
+  action: { operation?: string; subject: { type: string; id: string }; fields?: Record<string, unknown> },
+): Promise<{ externalId: string }> {
+  const f = action.fields ?? {};
+  const repository = String(f.repository ?? action.subject.id.split('#')[0]);
+  const [owner, repo] = repository.split('/');
+  const op = action.operation ?? '';
+
+  const ensureOk = (res: { status: number }, label: string): void => {
+    if (res.status >= 400) throw new Error(`github push failed (${label}): HTTP ${res.status}`);
+  };
+
+  if (op === 'pull_request.create') {
+    const res = await execute.request('POST /repos/{owner}/{repo}/pulls', {
+      owner, repo, title: f.title, body: f.body, head: f.head_sha, base: f.base_ref,
+    });
+    ensureOk(res, 'pulls.create');
+    return { externalId: String(res.data?.number ?? '') };
+  }
+  if (op === 'pull_request.update') {
+    const number = Number(f.number ?? action.subject.id.split('#').pop());
+    const params: Record<string, unknown> = { owner, repo, pull_number: number };
+    if (f.title !== undefined) params.title = f.title;
+    if (f.body !== undefined) params.body = f.body;
+    if (f.base_ref !== undefined) params.base = f.base_ref;
+    if (f.state !== undefined) params.state = f.state;
+    // labels/assignees/milestone live on the issue resource, but PATCH .../pulls/:n is the
+    // endpoint applyGithubWrite routes a PR edit through; GitHub accepts these on the issue
+    // PATCH. The PR PATCH itself ignores labels/assignees/milestone, so route those on the
+    // matching issue PATCH (PRs ARE issues for that endpoint) to faithfully persist them.
+    const res = await execute.request('PATCH /repos/{owner}/{repo}/pulls/{pull_number}', params);
+    ensureOk(res, 'pulls.update');
+    if (f.labels !== undefined || f.assignees !== undefined || f.milestone !== undefined) {
+      const issueParams: Record<string, unknown> = { owner, repo, issue_number: number };
+      if (f.labels !== undefined) issueParams.labels = f.labels;
+      if (f.assignees !== undefined) issueParams.assignees = f.assignees;
+      if (f.milestone !== undefined) issueParams.milestone = f.milestone;
+      const issueRes = await execute.request('PATCH /repos/{owner}/{repo}/issues/{issue_number}', issueParams);
+      ensureOk(issueRes, 'pulls.update.issue_fields');
+    }
+    return { externalId: String(res.data?.number ?? number) };
+  }
+  if (op === 'pull_request.merge') {
+    const number = Number(f.number ?? action.subject.id.split('#').pop());
+    const params: Record<string, unknown> = { owner, repo, pull_number: number };
+    // The twin merges with the default (merge) method; pass through any supplied detail.
+    if (f.commit_title !== undefined) params.commit_title = f.commit_title;
+    if (f.commit_message !== undefined) params.commit_message = f.commit_message;
+    if (f.merge_method !== undefined) params.merge_method = f.merge_method;
+    if (f.head_sha !== undefined) params.sha = f.head_sha;
+    const res = await execute.request('PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge', params);
+    ensureOk(res, 'pulls.merge');
+    // The merge endpoint returns the merge commit sha (not the PR number).
+    return { externalId: String(res.data?.sha ?? f.merge_commit_sha ?? '') };
+  }
+  if (op === 'pull_request.request_reviewers') {
+    const number = Number(f.number ?? action.subject.id.split('#').pop());
+    const res = await execute.request('POST /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers', {
+      owner, repo, pull_number: number, reviewers: f.requested_reviewers ?? [],
+    });
+    ensureOk(res, 'pulls.request_reviewers');
+    return { externalId: String(res.data?.number ?? number) };
+  }
+  if (op === 'pull_request.remove_requested_reviewers') {
+    const number = Number(f.number ?? action.subject.id.split('#').pop());
+    const res = await execute.request('DELETE /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers', {
+      owner, repo, pull_number: number, reviewers: f.requested_reviewers ?? [],
+    });
+    ensureOk(res, 'pulls.remove_requested_reviewers');
+    return { externalId: String(res.data?.number ?? number) };
+  }
+  if (op === 'pull_request_review.submit') {
+    const number = Number(f.number);
+    const res = await execute.request('POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews', {
+      owner, repo, pull_number: number, event: f.state, body: f.body,
+    });
+    ensureOk(res, 'reviews.submit');
+    return { externalId: String(res.data?.id ?? '') };
+  }
+  if (op === 'pull_request_review_comment.create') {
+    const number = Number(f.number);
+    const params: Record<string, unknown> = {
+      owner, repo, pull_number: number, body: f.body,
+    };
+    // Diff-anchoring fields ride along when the local write set them (the real REST API
+    // needs path + line/side + commit_id to anchor a review comment to the diff).
+    if (f.path !== undefined) params.path = f.path;
+    if (f.line !== undefined) params.line = f.line;
+    if (f.side !== undefined) params.side = f.side;
+    if (f.start_line !== undefined) params.start_line = f.start_line;
+    if (f.head_sha !== undefined) params.commit_id = f.head_sha;
+    const res = await execute.request('POST /repos/{owner}/{repo}/pulls/{pull_number}/comments', params);
+    ensureOk(res, 'pulls.review_comment.create');
+    return { externalId: String(res.data?.id ?? '') };
+  }
+  if (op === 'issue.create') {
+    const res = await execute.request('POST /repos/{owner}/{repo}/issues', {
+      owner, repo, title: f.title, body: f.body,
+    });
+    ensureOk(res, 'issues.create');
+    return { externalId: String(res.data?.number ?? '') };
+  }
+  if (op === 'issue.update') {
+    const number = Number(f.number ?? action.subject.id.split('#issue:').pop());
+    const params: Record<string, unknown> = { owner, repo, issue_number: number };
+    if (f.title !== undefined) params.title = f.title;
+    if (f.body !== undefined) params.body = f.body;
+    if (f.state !== undefined) params.state = f.state;
+    if (f.labels !== undefined) params.labels = f.labels;
+    if (f.assignees !== undefined) params.assignees = f.assignees;
+    if (f.milestone !== undefined) params.milestone = f.milestone;
+    const res = await execute.request('PATCH /repos/{owner}/{repo}/issues/{issue_number}', params);
+    ensureOk(res, 'issues.update');
+    return { externalId: String(res.data?.number ?? number) };
+  }
+  if (op === 'issue_comment.create') {
+    const number = Number(f.number);
+    const res = await execute.request('POST /repos/{owner}/{repo}/issues/{issue_number}/comments', {
+      owner, repo, issue_number: number, body: f.body,
+    });
+    ensureOk(res, 'issue_comment.create');
+    return { externalId: String(res.data?.id ?? '') };
+  }
+  if (op === 'commit_status.create') {
+    const sha = String(f.sha ?? '');
+    const params: Record<string, unknown> = { owner, repo, sha, state: f.state };
+    if (f.context !== undefined) params.context = f.context;
+    if (f.description !== undefined) params.description = f.description;
+    if (f.target_url !== undefined) params.target_url = f.target_url;
+    const res = await execute.request('POST /repos/{owner}/{repo}/statuses/{sha}', params);
+    ensureOk(res, 'statuses.create');
+    return { externalId: String(res.data?.id ?? '') };
+  }
+  if (op === 'check_run.create') {
+    const params: Record<string, unknown> = { owner, repo, name: f.name, head_sha: f.head_sha };
+    if (f.status !== undefined) params.status = f.status;
+    if (f.conclusion !== undefined) params.conclusion = f.conclusion;
+    if (f.details_url !== undefined) params.details_url = f.details_url;
+    if (f.started_at !== undefined) params.started_at = f.started_at;
+    if (f.completed_at !== undefined) params.completed_at = f.completed_at;
+    const res = await execute.request('POST /repos/{owner}/{repo}/check-runs', params);
+    ensureOk(res, 'check_runs.create');
+    return { externalId: String(res.data?.id ?? '') };
+  }
+  if (op === 'milestone.create') {
+    const params: Record<string, unknown> = { owner, repo, title: f.title };
+    if (f.description !== undefined) params.description = f.description;
+    if (f.state !== undefined) params.state = f.state;
+    if (f.due_on !== undefined) params.due_on = f.due_on;
+    const res = await execute.request('POST /repos/{owner}/{repo}/milestones', params);
+    ensureOk(res, 'milestones.create');
+    return { externalId: String(res.data?.number ?? '') };
+  }
+  if (op === 'milestone.update') {
+    const number = Number(f.number ?? action.subject.id.split('#milestone:').pop());
+    const params: Record<string, unknown> = { owner, repo, milestone_number: number };
+    if (f.title !== undefined) params.title = f.title;
+    if (f.description !== undefined) params.description = f.description;
+    if (f.state !== undefined) params.state = f.state;
+    if (f.due_on !== undefined) params.due_on = f.due_on;
+    const res = await execute.request('PATCH /repos/{owner}/{repo}/milestones/{milestone_number}', params);
+    ensureOk(res, 'milestones.update');
+    return { externalId: String(res.data?.number ?? number) };
+  }
+  throw new Error(`github push: unsupported operation "${op}" for subject ${action.subject.type}`);
+}
+
+/**
+ * PUSH (all): push every pending LOCAL GitHub action to real GitHub via the injected
+ * executor and CONFIRM each on success — `confirmAction` records the confirmed fields
+ * as an observed event and maps the action → that event, SUPPRESSING the local
+ * projection (the fact now lives in the observed log; counted exactly once). Closes
+ * the action → push → observed loop (R18). Idempotency: a confirmed action is no
+ * longer pending, so a re-push calls the executor for it again ZERO times.
+ */
+export async function pushPendingGithubActions(
+  execute: GithubExecute,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string> }> {
+  const confirmed: string[] = [];
+  const externalIds: Record<string, string> = {};
+  for (const action of pendingActions(SERVICE, opts.root)) {
+    const { externalId } = await pushGithubAction(execute, action);
+    confirmAction({
+      service: SERVICE,
+      actionId: action.id,
+      subject: action.subject,
+      fields: action.fields ?? {},
+      occurredAt: opts.occurredAt,
+      ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+    confirmed.push(action.id);
+    externalIds[action.id] = externalId;
+  }
+  return { pushed: confirmed.length, confirmed, externalIds };
+}