@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/github-connector.js

@@ -0,0 +1,1398 @@
+// 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 { assertBudgetGuardIntact } from '@volter/world-core';
+import { observeResource, toEntry } from '@volter/world-core';
+import { twinResources, ownFields } from '@volter/world-core';
+import { GithubBudget, GithubBudgetError, githubCallWeight } from "./github-budget.js";
+import { githubState } from "./github-twin.js";
+const SERVICE = 'github';
+/**
+ * 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.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.github.com` request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the
+ * request goes out (`checkBudget`, which THROWS `GithubBudgetError` instead of returning when the
+ * ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a `Retry-After` /
+ * 403-or-429 / `x-ratelimit-remaining: 0` signal becomes a persisted cooldown that makes every
+ * later call fail fast WITHOUT touching GitHub. The weights ARE GitHub's own published point costs
+ * (1 for a read, 5 for a write) — see `github-budget.ts`. There is deliberately NO option to
+ * disable the guard, and no value a caller can pass for `budget` that yields an unguarded client —
+ * but NOT immunity from a caller who WANTS one (a fresh `budgetOptions.path` or an injected clock
+ * restores the allowance; the kernel header states that limit and this does not upgrade it).
+ */
+export function liveGithubExecute(token, baseUrl = 'https://api.github.com', opts = {}) {
+    // `null`/`undefined` (or omitting it) build the default budget. Anything else must be an
+    // UNMODIFIED GithubBudget: a duck-typed stand-in, a SUBCLASS that overrides `checkBudget`, and a
+    // Proxy that traps it are all refused, because all three are one-liners that would otherwise
+    // hand back a client with no ceiling at all (§9 finding, 2026-07-26 — `instanceof` alone was
+    // not a check). What this cannot stop is deliberate sabotage from inside the process (an
+    // injected clock, a throwaway ledger path); the kernel's header says so rather than pretending
+    // otherwise, and this guards the accident and the one-liner, which are the shapes that happen.
+    const doFetch = opts.fetchImpl ?? fetch;
+    // The default ledger is keyed by a hash of THIS PAT — GitHub's primary limit is per token, so a
+    // cwd-scoped ledger would hand it a fresh allowance per checkout/worktree/CI matrix leg.
+    // ONE expression decides which budget is used, so there is no second, weaker test that could
+    // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+    // must be an UNMODIFIED GithubBudget — a duck-typed stand-in, a SUBCLASS overriding
+    // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that
+    // would otherwise hand back a client with no ceiling (§9 finding, 2026-07-26: `instanceof`
+    // alone was not a check — a subclass satisfied it). What this cannot stop is deliberate
+    // sabotage from inside the process (an injected clock, a throwaway ledger path); the kernel
+    // header states that limit rather than pretending otherwise. This closes the accident and the
+    // one-liner, which are the shapes that actually happen.
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, GithubBudget, 'liveGithubExecute')
+        : new GithubBudget({ token, ...(opts.budgetOptions ?? {}) });
+    return {
+        async request(route, params = {}) {
+            const sp = route.indexOf(' ');
+            const method = route.slice(0, sp);
+            let path = route.slice(sp + 1);
+            const rest = {};
+            // 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()}`;
+            }
+            // Priced by the ROUTE (`"GET /repos/{owner}/{repo}/pulls"`), which is what GitHub's own docs
+            // and point table name endpoints by — stable across owners and repos.
+            const weight = githubCallWeight(route);
+            // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+            const reservation = budget.checkBudget(weight);
+            const res = await doFetch(`${baseUrl}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: 'application/vnd.github+json',
+                    'Content-Type': 'application/json',
+                },
+                ...(isRead ? {} : { body: JSON.stringify(rest) }),
+            });
+            const resHeaders = {};
+            res.headers.forEach((v, k) => { resHeaders[k.toLowerCase()] = v; });
+            const data = res.status === 204 ? undefined : await res.json();
+            // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+            // `Retry-After` beyond the cap is not something to sleep off) — the cooldown is persisted
+            // first either way, so the refusal survives the throw. GitHub answers a tripped SECONDARY
+            // limit with 403 + `Retry-After` rather than 429, which is why the header is read on every
+            // response and not only on a 429.
+            // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+            // call that louder refusal wins; an answer GitHub ACCEPTED is kept, so a write that landed is
+            // never recorded as failed and performed again on retry.
+            try {
+                budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+            }
+            catch (error) {
+                if (!(error instanceof GithubBudgetError) || !res.ok)
+                    throw error;
+            }
+            return { status: res.status, data };
+        },
+    };
+}
+// GitHub says a machine wrote something two ways: `user.type === 'Bot'` on the App-authored
+// row, and the `[bot]` login suffix every GitHub App account carries. A consumer triaging a
+// review feed sorts bot findings from human ones, so read both rather than trusting either.
+//
+// READ THE ASYMMETRY BEFORE YOU GATE ON THIS. `bot` ⇒ a machine wrote it is RELIABLE: only a
+// GitHub App account is typed `Bot` or suffixed `[bot]`. The converse is NOT: `user` does not
+// mean a human. A GitHub App acting through a USER token, a service/machine account, and an
+// Organization all come back typed `User` (or `Organization`) with an ordinary login — and a
+// review by a DELETED account answers `user: null`, so neither field exists and no author
+// type is emitted at all. So `authorType === 'bot'` is safe to act on; `authorType === 'user'`
+// is "not identified as a bot", never "a person did this".
+function authorTypeOf(user) {
+    const type = user?.type === undefined || user?.type === null ? '' : String(user.type);
+    const login = user?.login === undefined || user?.login === null ? '' : String(user.login);
+    return type.toLowerCase() === 'bot' || login.endsWith('[bot]') ? 'bot' : 'user';
+}
+// The author fields as they ride a review/comment subject: the login when GitHub gave one
+// (a deleted account answers `user: null`), and the human/bot split derived from it.
+function authorFields(user) {
+    if (user === undefined || user === null)
+        return {};
+    const login = user.login === undefined || user.login === null ? undefined : String(user.login);
+    return { ...(login === undefined ? {} : { authorLogin: login }), authorType: authorTypeOf(user) };
+}
+/**
+ * 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 + INLINE (diff-anchored) review comment. The ONLY thing not
+ * pulled is the Non-goal — actual repository file CONTENTS (per-file diffs/blob bytes are
+ * not fetched here).
+ *
+ * Three reads per PR buy the conversation: the reviews, the issue comments, and
+ * `/pulls/{n}/comments` — the inline comments, where every bot finding lives and which
+ * this pull never fetched before. They are fetched ONCE per PR and joined to their review
+ * by `pull_request_review_id` rather than per review, because GitHub has no
+ * comments-of-one-review route worth N more calls.
+ *
+ * `lastUpdatedAt` is the budget: a PR whose `updated_at` has not moved since the last
+ * observation has no new conversation to buy, so those three reads are skipped entirely
+ * (`detailsFetched: false`) and N unchanged PRs cost only the list call.
+ */
+/** The subject suffix for the PHANTOM review — the bucket an inline comment lands in when
+ *  nothing names the review that wrapped it. A fixed word, not a mint: it is the SAME
+ *  bucket every pull, so a consumer's feed sees one growing subject rather than a new one
+ *  per poll. */
+const UNATTACHED_REVIEW = 'unattached';
+/**
+ * The reviews that COUNT as reviews: submitted, and not a PENDING draft. GitHub returns a
+ * reviewer's unsubmitted draft on the reviews page with `state: 'PENDING'` and no
+ * `submitted_at` — nobody has said anything yet — and this pull also carries a PHANTOM
+ * review holding orphaned inline comments, which is a bucket, not a verdict. Both belong in
+ * the `reviews` list (they are real rows) and NEITHER may be the PR's "latest review" or be
+ * counted as one, so exactly one predicate decides both and they can never disagree.
+ */
+function submittedReviews(reviews) {
+    return reviews.filter((r) => r.submittedAt !== undefined && (r.state ?? '').toUpperCase() !== 'PENDING');
+}
+/** GitHub's page ceiling for these list reads. */
+const GITHUB_MAX_PER_PAGE = 100;
+/** How many pages one conversation read will walk before it stops asking. 100×10 = 1000
+ *  reviews or inline comments on a single PR — past that the pull is buying a pathological
+ *  outlier at real rate cost, and the bound is what keeps a poll's spend knowable. */
+const MAX_CONVERSATION_PAGES = 10;
+/**
+ * Read EVERY page of a list route, not just the first. GitHub's default page is 30 rows, so
+ * a busy PR's 31st review — or its 31st inline comment, where a scanner's findings pile up
+ * fastest — simply did not exist as far as the pull was concerned, and the missing rows read
+ * downstream as an absence rather than a page boundary. Asks for the vendor's maximum page
+ * (100, the same as `observeRepositoryAndBranches`) and stops on the first short page.
+ */
+async function readAllPages(execute, route, params) {
+    const out = [];
+    for (let page = 1; page <= MAX_CONVERSATION_PAGES; page++) {
+        const res = await execute.request(route, { ...params, per_page: GITHUB_MAX_PER_PAGE, page });
+        const rows = Array.isArray(res.data) ? res.data : [];
+        out.push(...rows);
+        if (rows.length < GITHUB_MAX_PER_PAGE)
+            break;
+    }
+    return out;
+}
+export async function pullGithubPrs(execute, opts) {
+    const { owner, repo } = opts;
+    const repository = `${owner}/${repo}`;
+    const state = opts.state ?? 'open';
+    // Same ordering as the closed sweep below: newest-updated first. The two pages are read
+    // against ONE budget of rows, so an open list that came back in the vendor's default order
+    // (by number, descending) would spend that budget on whatever happened to be numbered
+    // highest rather than on what actually moved since the last poll.
+    const list = await execute.request('GET /repos/{owner}/{repo}/pulls', {
+        owner, repo, state, sort: 'updated', direction: 'desc', per_page: opts.perPage ?? 30,
+    });
+    if (list.status >= 400)
+        throw new Error(`github pull failed (list pulls): HTTP ${list.status}`);
+    const nodes = Array.isArray(list.data) ? list.data : [];
+    // A MERGE IS A CLOSED PR: an open-only list never observes the event that ends a job —
+    // the PR simply vanishes from the next pull. `state: 'all'` (what syncGithubFromRemote
+    // asks for) already covers it; an open-only caller gets a BOUNDED second page of the
+    // most recently updated closed PRs instead, so the merge folds without a pull walking
+    // the repo's whole closed history.
+    const closedPerPage = opts.closedPerPage ?? 20;
+    if (state === 'open' && closedPerPage > 0) {
+        const closed = await execute.request('GET /repos/{owner}/{repo}/pulls', {
+            owner, repo, state: 'closed', sort: 'updated', direction: 'desc', per_page: closedPerPage,
+        });
+        if (closed.status < 400 && Array.isArray(closed.data))
+            nodes.push(...closed.data);
+    }
+    const out = [];
+    // The two list pages can name the same PR — one that closed BETWEEN the two reads appears
+    // open on the first page and closed on the second. Keeping the page that named it first
+    // kept the STALE row and reported a merged PR as still open. Keep the row whose
+    // `updated_at` is LATER instead (a stampless row never displaces a stamped one), which is
+    // the vendor's own answer to "which of these two observations is the newer".
+    const byNumber = new Map();
+    for (const n of nodes) {
+        const number = Number(n.number);
+        // A row with no usable number is not a PR we can address: `Number(undefined)` is NaN and
+        // every such row collapsed onto ONE key, so the second one silently replaced the first.
+        if (!Number.isFinite(number))
+            continue;
+        const prev = byNumber.get(number);
+        if (prev === undefined) {
+            byNumber.set(number, n);
+            continue;
+        }
+        const a = prev.updated_at === undefined || prev.updated_at === null ? '' : String(prev.updated_at);
+        const b = n.updated_at === undefined || n.updated_at === null ? '' : String(n.updated_at);
+        if (b > a)
+            byNumber.set(number, n);
+    }
+    for (const n of byNumber.values()) {
+        const number = Number(n.number);
+        const updatedAt = n.updated_at === undefined || n.updated_at === null ? undefined : String(n.updated_at);
+        // BUDGET: GitHub moves a PR's `updated_at` on every review, comment, edit and push, so
+        // an unmoved stamp means there is no conversation to buy. A PR that reports no stamp at
+        // all is always fetched — silence is not evidence of stillness.
+        const detailsFetched = updatedAt === undefined || opts.lastUpdatedAt?.[`${repository}#${number}`] !== updatedAt;
+        const pr = { id: `${repository}#${number}`, number, repository, detailsFetched };
+        if (updatedAt !== undefined)
+            pr.updatedAt = updatedAt;
+        if (detailsFetched) {
+            // ALL THREE conversation reads are PAGED (see readAllPages): a review page boundary
+            // orphaned inline comments from their reviews, an inline page boundary simply lost
+            // findings, and the issue-comment read — which `commentCount` publishes — stopped at
+            // the vendor's default 30, so a busy conversation reported a truncated count as if it
+            // were the whole tab.
+            const reviewNodes = await readAllPages(execute, 'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews', { owner, repo, pull_number: number });
+            const commentNodes = await readAllPages(execute, 'GET /repos/{owner}/{repo}/issues/{issue_number}/comments', { owner, repo, issue_number: number });
+            const inlineNodes = await readAllPages(execute, 'GET /repos/{owner}/{repo}/pulls/{pull_number}/comments', { owner, repo, pull_number: number });
+            // The review is the unit: every inline comment names the review that wrapped it.
+            const inlineByReview = new Map();
+            for (const c of inlineNodes) {
+                if (c.id === undefined || c.id === null)
+                    continue; // no id, no stable place in a thread
+                const reviewId = c.pull_request_review_id === undefined || c.pull_request_review_id === null ? '' : String(c.pull_request_review_id);
+                // The row's OWN author rides with it. The review is the join, never the byline.
+                const comment = { id: String(c.id), ...authorFields(c.user) };
+                if (c.path !== undefined && c.path !== null)
+                    comment.path = String(c.path);
+                if (c.line !== undefined && c.line !== null)
+                    comment.line = Number(c.line);
+                if (c.body !== undefined && c.body !== null)
+                    comment.body = String(c.body);
+                if (c.in_reply_to_id !== undefined && c.in_reply_to_id !== null)
+                    comment.inReplyTo = String(c.in_reply_to_id);
+                if (c.created_at !== undefined && c.created_at !== null)
+                    comment.createdAt = String(c.created_at);
+                const bucket = inlineByReview.get(reviewId);
+                if (bucket)
+                    bucket.push(comment);
+                else
+                    inlineByReview.set(reviewId, [comment]);
+            }
+            const reviews = reviewNodes.map((r) => {
+                const id = r.id === undefined || r.id === null ? undefined : String(r.id);
+                const review = { ...(id === undefined ? {} : { id }), ...authorFields(r.user), comments: id === undefined ? [] : (inlineByReview.get(id) ?? []) };
+                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);
+                if (r.commit_id !== undefined && r.commit_id !== null)
+                    review.commitId = String(r.commit_id);
+                if (id !== undefined)
+                    inlineByReview.delete(id);
+                return review;
+            });
+            // An inline comment whose review the reviews page did not name (a page boundary, a
+            // review deleted between the two reads) still EXISTS — it rides a review carrying its
+            // id, the `partial` flag and its comments, and nothing else, rather than being dropped.
+            // Inventing a state or an author for a review nobody showed us would be the worse lie.
+            const unattached = [];
+            for (const [reviewId, comments] of inlineByReview) {
+                // NO review id at all. This used to `continue` — the comment was OBSERVED and then
+                // silently discarded, which is the one thing a pull may never do with a fact it
+                // bought. It hangs off a fixed phantom subject per PR instead, flagged `partial` so
+                // nothing mistakes it for a review whose verdict simply has not arrived.
+                if (reviewId === '') {
+                    unattached.push(...comments);
+                    continue;
+                }
+                // A review whose id we know but whose ROW never arrived is just as unshown as the
+                // phantom: state, author and verdict are all absent because nobody sent them. It
+                // carries `partial` for the same reason the phantom does — without it a consumer
+                // reads a stateless orphan as a review whose fields merely have not landed yet.
+                reviews.push({ id: reviewId, partial: true, comments });
+            }
+            if (unattached.length > 0)
+                reviews.push({ id: UNATTACHED_REVIEW, partial: true, comments: unattached });
+            pr.reviews = reviews;
+            // Counted over the SAME set the newest verdict is drawn from — a raw row count included
+            // PENDING drafts and the phantom bucket, so `reviewCount` and `latestReview` described
+            // different populations of the same PR.
+            pr.reviewCount = submittedReviews(reviews).length;
+            pr.comments = commentNodes.map((c) => {
+                const comment = { ...(c.id === undefined || c.id === null ? {} : { id: String(c.id) }), ...authorFields(c.user) };
+                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);
+                if (c.updated_at !== undefined && c.updated_at !== null)
+                    comment.updatedAt = String(c.updated_at);
+                return comment;
+            });
+            pr.commentCount = commentNodes.length;
+        }
+        if (n.user === null)
+            pr.authorLogin = null;
+        else if (n.user?.login !== undefined && n.user?.login !== null)
+            pr.authorLogin = String(n.user.login);
+        if (n.user?.type !== undefined && n.user?.type !== null)
+            pr.authorType = String(n.user.type);
+        // 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, opts) {
+    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 = Array.isArray(list.data) ? list.data : [];
+    const out = [];
+    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 = { 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);
+        // the timestamps the write handler stores: shape parity between a written and an observed issue
+        if (typeof n.created_at === 'string')
+            iss.created_at = n.created_at;
+        if (typeof n.updated_at === 'string')
+            iss.updated_at = n.updated_at;
+        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.
+//
+// The PR is one subject and its CONVERSATION is many: each review (`…#<n>:review:<id>`,
+// carrying the inline comments it wrapped) and each issue comment (`…#<n>:ic:<id>`) rides
+// as its own resource, so two reviews between two polls are two deltas and a consumer can
+// say who reviewed. Each dates its own delta — a review by `submitted_at`, a comment by
+// `updated_at ?? created_at` — because a feed ordering a conversation wants the moment it
+// was said, not the moment the poll happened to look.
+export function observedPrsToResources(prs) {
+    return prs.flatMap((p) => {
+        const 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;
+        // WHO opened it, and when GitHub last saw it change — the stamp the next pull's budget
+        // compares against, kept on the subject rather than in a cache beside it.
+        if (p.authorLogin !== undefined)
+            fields.authorLogin = p.authorLogin;
+        if (p.authorType !== undefined)
+            fields.user_type = p.authorType;
+        if (p.updatedAt !== undefined) {
+            fields.updatedAt = p.updatedAt;
+            fields.observedUpdatedAt = p.updatedAt;
+        }
+        // The reviewers' WORDS ride the observation: how many reviews, and the newest one's
+        // verdict and body, so a delta on the feed says what a reviewer said (a consumer decides
+        // from the words, never from a bare count moving). The reviews themselves are subjects
+        // below; this summary stays for a consumer that reads only pull_request. A pull whose
+        // budget skipped the conversation OMITS both — the shadow keeps what it already holds,
+        // because not buying a fact is not observing its absence.
+        if (p.reviewCount !== undefined)
+            fields.reviewCount = p.reviewCount;
+        if (p.commentCount !== undefined)
+            fields.commentCount = p.commentCount;
+        if (p.reviews !== undefined) {
+            // THE NEWEST VERDICT, by the vendor's clock — not `reviews.at(-1)`, which was list
+            // ORDER with the phantom bucket appended after it: the last element was routinely a
+            // review with no state and no body at all (`{}` on the feed), and a reviewer's unsent
+            // PENDING draft could take the slot from the approval that actually landed. The latest
+            // review is the one with the greatest `submitted_at` among the reviews that HAVE one
+            // and are not PENDING — the same set `reviewCount` counts.
+            const submitted = submittedReviews(p.reviews);
+            const latest = submitted.reduce((best, r) => (best === undefined || r.submittedAt >= best.submittedAt ? r : best), undefined);
+            fields.latestReview = latest === undefined ? null : { ...(latest.state === undefined ? {} : { state: latest.state }), ...(latest.body === undefined ? {} : { body: latest.body }), ...(latest.submittedAt === undefined ? {} : { submittedAt: latest.submittedAt }) };
+        }
+        const out = [{ type: 'pull_request', id: p.id, fields, ...(p.updatedAt === undefined ? {} : { occurredAt: p.updatedAt }) }];
+        for (const r of p.reviews ?? []) {
+            // No review id, no subject: an id minted from a position would move under the next
+            // review and thread a consumer's feed onto the wrong conversation.
+            if (r.id === undefined)
+                continue;
+            const reviewFields = { pr: p.number, repository: p.repository };
+            if (r.authorLogin !== undefined)
+                reviewFields.authorLogin = r.authorLogin;
+            if (r.authorType !== undefined)
+                reviewFields.authorType = r.authorType;
+            if (r.state !== undefined)
+                reviewFields.state = r.state;
+            if (r.body !== undefined)
+                reviewFields.body = r.body;
+            if (r.submittedAt !== undefined)
+                reviewFields.submittedAt = r.submittedAt;
+            if (r.commitId !== undefined)
+                reviewFields.commitId = r.commitId;
+            // The PHANTOM bucket says so on the wire. It holds inline comments nothing named a
+            // review for, so it has no state, no author and no verdict — and without this flag a
+            // consumer could not tell it from a real review whose fields simply had not arrived.
+            if (r.partial === true)
+                reviewFields.partial = true;
+            // Always present, even empty: a review that later grows an inline comment is then a
+            // delta on THIS field rather than a field appearing from nowhere. SORTED BY ID, because
+            // the vendor is free to hand the same comments back in a different order and a
+            // reordered array is a field change — a delta on a conversation nobody touched.
+            reviewFields.comments = [...r.comments].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).map((c) => {
+                // EACH FINDING'S OWN AUTHOR rides with it, not the wrapping review's. A consumer
+                // grading a finding reads the FINDING's author: a scanner App's comment inside a
+                // human's review is a bot finding, and serving the wrapper's login called it a
+                // human's. The wrapper is the fallback only for a row that named nobody at all.
+                const authorLogin = c.authorLogin ?? r.authorLogin;
+                const authorType = c.authorType ?? r.authorType;
+                return {
+                    id: c.id,
+                    ...(authorLogin === undefined ? {} : { authorLogin }),
+                    ...(authorType === undefined ? {} : { authorType }),
+                    ...(c.path === undefined ? {} : { path: c.path }),
+                    ...(c.line === undefined ? {} : { line: c.line }),
+                    ...(c.body === undefined ? {} : { body: c.body }),
+                    ...(c.inReplyTo === undefined ? {} : { inReplyTo: c.inReplyTo }),
+                    ...(c.createdAt === undefined ? {} : { createdAt: c.createdAt }),
+                };
+            });
+            // WHEN it was said. A PENDING draft and the phantom bucket have no `submitted_at`, and
+            // with no occurredAt the delta falls back to the POLL clock — which dates a finding by
+            // when the poller happened to look. The earliest comment it carries is the closest
+            // thing the vendor actually told us about when this subject started existing.
+            const reviewAt = r.submittedAt ?? r.comments.map((c) => c.createdAt).filter((d) => d !== undefined).sort()[0];
+            out.push({ type: 'review', id: `${p.id}:review:${r.id}`, fields: reviewFields, ...(reviewAt === undefined ? {} : { occurredAt: reviewAt }) });
+        }
+        for (const c of p.comments ?? []) {
+            if (c.id === undefined)
+                continue; // same rule as a review: no id, no subject
+            const commentFields = { pr: p.number, repository: p.repository };
+            if (c.authorLogin !== undefined)
+                commentFields.authorLogin = c.authorLogin;
+            if (c.authorType !== undefined)
+                commentFields.authorType = c.authorType;
+            if (c.body !== undefined)
+                commentFields.body = c.body;
+            if (c.createdAt !== undefined)
+                commentFields.createdAt = c.createdAt;
+            if (c.updatedAt !== undefined)
+                commentFields.updatedAt = c.updatedAt;
+            // An EDIT moves `updated_at` and nothing else, so it dates the delta ahead of the
+            // moment the comment was first written.
+            const at = c.updatedAt ?? c.createdAt;
+            out.push({ type: 'issue_comment', id: `${p.id}:ic:${c.id}`, fields: commentFields, ...(at === undefined ? {} : { occurredAt: at }) });
+        }
+        return out;
+    });
+}
+/**
+ * The `updated_at` this world last observed per PR — the budget's memory, read from the
+ * SHADOW (the fold of the world's own event log) rather than a cache beside it, so it
+ * survives a restart, is per-world like every other pulled fact, and cannot disagree with
+ * what was actually folded. A PR nobody has pulled yet is simply absent, and its
+ * conversation gets bought.
+ */
+export function lastObservedPrUpdates(root) {
+    const out = {};
+    for (const resource of twinResources(SERVICE, root)) {
+        const subject = { subject: resource, fields: ownFields(resource) };
+        if (subject.subject.type !== 'pull_request')
+            continue;
+        const updatedAt = subject.fields.observedUpdatedAt ?? subject.fields.updatedAt;
+        if (typeof updatedAt === 'string' && updatedAt !== '')
+            out[subject.subject.id] = updatedAt;
+    }
+    return out;
+}
+// Map observed issues to SyncResource[] (content-bearing: title/body/state).
+export function observedIssuesToResources(issues) {
+    return issues.map((i) => {
+        const 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;
+        if (i.created_at !== undefined)
+            fields.created_at = i.created_at;
+        if (i.updated_at !== undefined)
+            fields.updated_at = i.updated_at;
+        return { type: 'issue', id: i.id, fields };
+    });
+}
+/**
+ * A push this connector DECLINES to make, as opposed to one the vendor rejected. It is
+ * raised when enacting the local write faithfully is impossible — the only case today is a
+ * threaded reply whose root has no id on the real repo — and the alternative (posting it
+ * somewhere else, or forwarding a twin-minted id) would write the wrong thing to a real
+ * account. A refusal is ledgered and the sweep continues; the action stays PENDING, so it
+ * pushes on a later sweep once the root is known.
+ */
+export class GithubPushRefused extends Error {
+    constructor(message) {
+        super(`github push refused: ${message}`);
+        this.name = 'GithubPushRefused';
+    }
+}
+// Append ONE folded event, tolerating a per-row `Conflicting duplicate` the way the slack
+// connector does (`slack-connector.ts` `fold`). `appendEventLocked` throws this when the
+// store already holds a row with the SAME id/idempotencyKey but DIVERGENT content — e.g.
+// a post-append line mutation raced the live writer (the peak-internal PH-216 incident).
+// That divergence is a single row's integrity question and says nothing about the other
+// resources in the same pull, so it must NOT abort the whole repo's fold: skip the row,
+// surface its stable id, keep folding. Every OTHER error stays fatal (re-thrown).
+function appendTolerant(event, root) {
+    // PROTOCOL 2: the pack OBSERVES a resource; the kernel diffs it against the tree and folds what
+    // changed onto the root's log (observe.ts). The v1 row shape is read for its subject and fields.
+    const entry = toEntry(event);
+    // Observations are field patches. Copying the pre-refresh tree here would reintroduce
+    // stale fields after earlier observations in the same collected batch update them.
+    const report = observeResource(event.service, { type: entry.subject.type, id: entry.subject.id, fields: entry.fields ?? {} }, { ...(root !== undefined ? { root } : {}), at: entry.occurredAt });
+    return { appended: report.appended > 0 || report.observed > 0 && report.unchanged === 0 && report.appended === 0 };
+}
+// 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) {
+    // 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, occurredAt, root) {
+    const data = {
+        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.authorLogin !== undefined)
+        data.user_login = pr.authorLogin;
+    if (pr.authorType !== undefined)
+        data.user_type = pr.authorType;
+    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, pr.authorLogin, pr.authorType]);
+    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,
+    };
+    return appendTolerant(event, root);
+}
+// 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, occurredAt, root) {
+    let appended = 0;
+    const conflictIds = [];
+    const emit = (type, key, extra) => {
+        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 },
+        };
+        const outcome = appendTolerant(event, root);
+        if (outcome.appended)
+            appended += 1;
+        else if (outcome.conflictId !== undefined)
+            conflictIds.push(outcome.conflictId);
+    };
+    // A PR whose conversation the budget did not buy emits nothing here: the events already
+    // in the log stand, and githubState keeps counting them. `reviews`/`comments` are absent
+    // in that case, NOT empty — the difference is exactly "unknown" versus "none".
+    if (!pr.detailsFetched)
+        return { appended, conflictIds };
+    // The review's key is the VENDOR's review id, not its index on the page: an index moves
+    // when a review is deleted, which re-keys every later review onto a subject that already
+    // means something else. The inline comments it wrapped name that same key, so the join
+    // the pull made survives into the twin's own state.
+    (pr.reviews ?? []).forEach((r, i) => {
+        const key = r.id === undefined ? `rev${i}` : `rev:${r.id}`;
+        emit('pull_request_review', key, {
+            ...(r.state !== undefined ? { state: r.state } : {}),
+            ...(r.body !== undefined ? { body: r.body } : {}),
+            ...(r.submittedAt !== undefined ? { submitted_at: r.submittedAt } : {}),
+            ...(r.authorLogin !== undefined ? { user_login: r.authorLogin } : {}),
+            ...(r.authorType !== undefined ? { user_type: r.authorType === 'bot' ? 'Bot' : 'User' } : {}),
+        });
+        // THE INLINE COMMENTS REACH THE TWIN'S OWN STATE. The pull bought them and the census
+        // claims `pull_request_review_comment` is pulled, but nothing was emitted for them — so
+        // `GET /pulls/:n/comments` on the twin answered [] for a PR whose findings the pull was
+        // holding. Each rides its own subject, keyed by the vendor's comment id, carrying its
+        // anchor, its thread position, and the review that wraps it.
+        for (const c of r.comments) {
+            // WHO WROTE THE FINDING is the comment's own `user`, not the review's. The review is
+            // the join (`pull_request_review_id`), never the byline: a scanner App's comment can
+            // ride a review a human submitted, and emitting the wrapper's login served that bot
+            // finding to the twin as the human's. The wrapper is the fallback ONLY when the
+            // comment row named nobody (`user: null`), and when neither names anyone the twin
+            // serves no author rather than guessing one.
+            const userLogin = c.authorLogin ?? r.authorLogin;
+            const userType = c.authorType ?? r.authorType;
+            emit('pull_request_review_comment', `rc:${c.id}`, {
+                external_id: c.id,
+                review_key: `${pr.id}:${key}`,
+                ...(c.body !== undefined ? { body: c.body } : {}),
+                ...(c.createdAt !== undefined ? { created_at: c.createdAt } : {}),
+                ...(c.path !== undefined ? { path: c.path } : {}),
+                ...(c.line !== undefined ? { line: c.line } : {}),
+                ...(c.inReplyTo !== undefined ? { in_reply_to: `${pr.id}:rc:${c.inReplyTo}` } : {}),
+                ...(userLogin !== undefined ? { user_login: userLogin } : {}),
+                ...(userType !== undefined ? { user_type: userType === 'bot' ? 'Bot' : 'User' } : {}),
+            });
+        }
+    });
+    (pr.comments ?? []).forEach((c, i) => emit('issue_comment', c.id === undefined ? `c${i}` : `ic:${c.id}`, {
+        ...(c.body !== undefined ? { body: c.body } : {}),
+        ...(c.createdAt !== undefined ? { created_at: c.createdAt } : {}),
+    }));
+    return { appended, conflictIds };
+}
+// 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, occurredAt, root) {
+    const data = { 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,
+    };
+    return appendTolerant(event, root);
+}
+/**
+ * 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.
+ *
+ * Per-row conflict tolerance: if a stored event has DIVERGED from what a resource now
+ * folds to (a `Conflicting duplicate` — e.g. a post-append line mutation raced the live
+ * writer), that ONE row is skipped and its stable id recorded, rather than aborting the
+ * whole repo's fold — one row's integrity question must not become a total observation
+ * outage for the ~dozens of other resources in the same pull (peak-internal PH-216). The
+ * result exposes `conflictsSkipped` + `conflictingIds` so a poller can log the integrity
+ * problem loudly instead of it being swallowed. Every OTHER append error stays fatal.
+ */
+export async function syncGithubFromReal(execute, opts) {
+    const pullOpts = {
+        owner: opts.owner,
+        repo: opts.repo,
+        ...(opts.state ? { state: opts.state } : {}),
+        ...(opts.perPage ? { perPage: opts.perPage } : {}),
+    };
+    // The budget's memory rides the world, not the process: the shadow already holds the
+    // `updated_at` of every PR this world has folded, so a poller restarted between two pulls
+    // still declines to re-buy a conversation nothing has touched.
+    const prs = await pullGithubPrs(execute, { ...pullOpts, lastUpdatedAt: lastObservedPrUpdates(opts.root) });
+    const issues = await pullGithubIssues(execute, pullOpts);
+    // Generic shadow-diff fold (content-bearing resources: title/body/state + refs).
+    // PROTOCOL 2: the pack OBSERVES each resource; the kernel diffs it against the tree and folds what
+    // changed onto the root's log (observe.ts) — inside a refresh, collected and folded as a batch.
+    const pull = { observed: 0, deltasAppended: 0, unchanged: 0 };
+    for (const r of [...observedPrsToResources(prs), ...observedIssuesToResources(issues), ...(await observeRepositoryAndBranches(execute, opts.owner, opts.repo))]) {
+        const report = observeResource(SERVICE, { type: r.type, id: r.id, fields: r.fields }, { ...(opts.root !== undefined ? { root: opts.root } : {}), at: r.occurredAt ?? opts.occurredAt });
+        pull.observed += 1;
+        pull.deltasAppended += report.appended;
+        pull.unchanged += report.unchanged;
+    }
+    // GitHub fold (carries counts + review/comment content the delta drops, plus issues).
+    // A per-row `Conflicting duplicate` is tolerated (skipped + recorded), never fatal, so a
+    // single diverged row can't stop later resources in the same pull from folding.
+    let eventsAppended = 0;
+    let conflictsSkipped = 0;
+    const conflictingIds = [];
+    const recordConflict = (id) => {
+        if (id === undefined)
+            return;
+        conflictsSkipped += 1;
+        conflictingIds.push(id);
+    };
+    for (const pr of prs) {
+        const prOutcome = foldObservedPr(pr, opts.occurredAt, opts.root);
+        if (prOutcome.appended)
+            eventsAppended += 1;
+        else
+            recordConflict(prOutcome.conflictId);
+        const existence = foldObservedExistence(pr, opts.occurredAt, opts.root);
+        eventsAppended += existence.appended;
+        for (const id of existence.conflictIds)
+            recordConflict(id);
+    }
+    for (const iss of issues) {
+        const issOutcome = foldObservedIssue(iss, opts.occurredAt, opts.root);
+        if (issOutcome.appended)
+            eventsAppended += 1;
+        else
+            recordConflict(issOutcome.conflictId);
+    }
+    return { observed: pull.observed, deltasAppended: pull.deltasAppended, eventsAppended, issues: issues.length, conflictsSkipped, conflictingIds };
+}
+// ---------------------------------------------------------------------------
+// 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, action, opts = {}) {
+    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, label) => {
+        if (res.status >= 400)
+            throw new Error(`github push failed (${label}): HTTP ${res.status}`);
+    };
+    if (op === 'pull_request.create') {
+        // A draft stays a draft on the remote: the flag rides the create.
+        const res = await execute.request('POST /repos/{owner}/{repo}/pulls', {
+            owner, repo, title: f.title, body: f.body, head: f.head_ref ?? f.head_sha, base: f.base_ref, ...(f.draft === undefined ? {} : { draft: Boolean(f.draft) }),
+        });
+        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 = { 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.
+        let externalId = String(number);
+        if (Object.keys(params).length > 3 || f.draft === undefined) {
+            const res = await execute.request('PATCH /repos/{owner}/{repo}/pulls/{pull_number}', params);
+            ensureOk(res, 'pulls.update');
+            externalId = String(res.data?.number ?? number);
+        }
+        if (f.labels !== undefined || f.assignees !== undefined || f.milestone !== undefined) {
+            const issueParams = { 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');
+        }
+        if (f.draft !== undefined) {
+            if (typeof f.draft !== 'boolean')
+                throw new Error('github push failed (pulls.draft): expected boolean');
+            // Resolve the vendor's node, never send the local twin's synthetic GraphQL ID.
+            const current = await execute.request('GET /repos/{owner}/{repo}/pulls/{pull_number}', { owner, repo, pull_number: number });
+            ensureOk(current, 'pulls.draft.read');
+            if (typeof current.data?.node_id !== 'string' || typeof current.data?.draft !== 'boolean')
+                throw new Error('github push failed (pulls.draft): vendor PR identity/state missing');
+            if (current.data.draft !== f.draft) {
+                const mutation = f.draft ? 'convertPullRequestToDraft' : 'markPullRequestReadyForReview';
+                const res = await execute.request('POST /graphql', {
+                    query: `mutation($id:ID!){${mutation}(input:{pullRequestId:$id}){pullRequest{id isDraft}}}`,
+                    variables: { id: current.data.node_id },
+                });
+                ensureOk(res, 'pulls.draft');
+                const changed = res.data?.data?.[mutation]?.pullRequest;
+                if (res.data?.errors?.length || changed?.id !== current.data.node_id || changed?.isDraft !== f.draft)
+                    throw new Error('github push failed (pulls.draft): GraphQL transition was not confirmed');
+            }
+        }
+        return { externalId };
+    }
+    if (op === 'pull_request.merge') {
+        const number = Number(f.number ?? action.subject.id.split('#').pop());
+        const params = { 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);
+        // A REPLY IS NOT A NEW ROOT COMMENT. `in_reply_to` says the local write answered an
+        // existing thread; POSTing it to `.../pulls/{n}/comments` started a SECOND thread on the
+        // real repo, unanchored to the finding it was answering. GitHub has a dedicated reply
+        // route, and it addresses the root by the VENDOR's comment id — which is never the id the
+        // twin minted for its own storage. Forwarding a minted id raw is how a push lands on a
+        // stranger's row (the groq incident, §9), so the root is resolved through the known
+        // external ids and the push REFUSES when there is no answer.
+        if (f.in_reply_to !== undefined && f.in_reply_to !== null) {
+            const rootKey = String(f.in_reply_to);
+            const rootExternal = opts.externalIds?.[rootKey];
+            if (rootExternal === undefined || rootExternal === '') {
+                throw new GithubPushRefused(`reply to comment ${rootKey}: the root comment has no known GitHub id (it was never pushed or pulled), and the twin's own id is not addressable on the real repo`);
+            }
+            const replyParams = { owner, repo, pull_number: number, comment_id: rootExternal, body: f.body };
+            const res = await execute.request('POST /repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies', replyParams);
+            ensureOk(res, 'pulls.review_comment.reply');
+            return { externalId: String(res.data?.id ?? '') };
+        }
+        const params = {
+            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;
+        // GitHub REFUSES a diff-anchored comment without the commit it anchors to. The local
+        // write carries the PR head it was authored against; fall back to the PR's head sha so an
+        // anchored comment authored without one is not rejected at the vendor.
+        const commitId = f.head_sha ?? f.commit_id;
+        if (commitId !== undefined)
+            params.commit_id = commitId;
+        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 = { 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 = { 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 = { 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 = { 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 = { 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) };
+    }
+    // A repository the working copy declared: reality already holds it (the link names it) —
+    // it is confirmed as-is, and created only where it truly is absent.
+    if (op === 'repository.create') {
+        // The record names owner and name as fields (its subject is a sequence id, not a slug).
+        const repoOwner = String(f.owner ?? owner);
+        const repoName = String(f.name ?? repo);
+        const probe = await execute.request('GET /repos/{owner}/{repo}', { owner: repoOwner, repo: repoName }).catch(() => undefined);
+        if (probe !== undefined && probe.status < 300)
+            return { externalId: `${repoOwner}/${repoName}` };
+        const res = await execute.request('POST /orgs/{org}/repos', { org: repoOwner, name: repoName, ...(f.private === undefined ? {} : { private: f.private }), ...(f.default_branch === undefined ? {} : { default_branch: f.default_branch }) });
+        ensureOk(res, 'repos.create');
+        return { externalId: `${repoOwner}/${repoName}` };
+    }
+    // THE BRANCH AND ITS FILES cross too (an API-plane implementation: a seat that writes through
+    // the Contents API, never git). A ref that already exists on the remote is the same ref.
+    const alreadyThere = (e) => /already exists/iu.test(e instanceof Error ? e.message : String(e));
+    if (op === 'git_ref.create' || op === 'branch.create') {
+        const ref = op === 'git_ref.create' ? String(f.ref) : `refs/heads/${String(f.name)}`;
+        const sha = String(op === 'git_ref.create' ? f.object_sha : f.commit_sha);
+        try {
+            const res = await execute.request('POST /repos/{owner}/{repo}/git/refs', { owner, repo, ref, sha });
+            ensureOk(res, 'git.refs.create');
+        }
+        catch (e) {
+            if (!alreadyThere(e))
+                throw e;
+        }
+        return { externalId: ref };
+    }
+    if (op === 'content_file.create' || op === 'content_file.update' || op === 'content_file.delete') {
+        const path = String(f.path);
+        const branch = f.branch === undefined ? undefined : String(f.branch);
+        // GitHub demands the current blob sha to update or delete; the remote is asked, not guessed.
+        let currentSha;
+        try {
+            const current = await execute.request('GET /repos/{owner}/{repo}/contents/{path}', { owner, repo, path, ...(branch === undefined ? {} : { ref: branch }) });
+            const data = current.data;
+            if (typeof data?.sha === 'string')
+                currentSha = data.sha;
+        }
+        catch {
+            currentSha = undefined;
+        }
+        if (op === 'content_file.delete') {
+            const res = await execute.request('DELETE /repos/{owner}/{repo}/contents/{path}', { owner, repo, path, message: `Delete ${path}`, ...(currentSha === undefined ? {} : { sha: currentSha }), ...(branch === undefined ? {} : { branch }) });
+            ensureOk(res, 'contents.delete');
+            return { externalId: path };
+        }
+        const res = await execute.request('PUT /repos/{owner}/{repo}/contents/{path}', { owner, repo, path, message: `${op === 'content_file.create' ? 'Add' : 'Update'} ${path}`, content: String(f.content_b64 ?? ''), ...(currentSha === undefined ? {} : { sha: currentSha }), ...(branch === undefined ? {} : { branch }) });
+        ensureOk(res, 'contents.put');
+        const data = res.data;
+        return { externalId: typeof data?.content?.sha === 'string' ? data.content.sha : path };
+    }
+    throw new Error(`github push: unsupported operation "${op}" for subject ${action.subject.type}`);
+}
+/**
+ * The REAL-GitHub id of every review comment this world can address: the vendor id a PULL
+ * observed for it. A locally-minted comment id means nothing on the real repo, so this is
+ * what a threaded reply resolves its root through — and a root that is absent here is a
+ * root the push must refuse rather than guess at.
+ */
+function knownReviewCommentExternalIds(root) {
+    const out = {};
+    for (const c of githubState(root).comments) {
+        if (c.kind === 'review' && c.external_id !== undefined && c.external_id !== '')
+            out[String(c.id)] = c.external_id;
+    }
+    return out;
+}
+/**
+ * THE R14 PUSH ADAPTER for github (jira's `pushJiraToRemote` is the reference; this
+ * transcribes its METHOD): pending local actions cross to the remote through the kernel's
+ * ONE RemoteExecute seam under a sealed credential the pack never sees, and each pushed
+ * action is confirmed in the local log. Anchored naming: `createGithubTwinFetch` pairs
+ * with `syncGithubFromRemote` and `pushGithubToRemote`. Push-plane only — a read refuses
+ * loudly. The route grammar is the one `pushGithubAction` speaks (`METHOD /path/{param}`,
+ * templated params in the path, the rest as the JSON body).
+ */
+/** This pack's vendor executor over the kernel's ONE RemoteExecute (push plane). */
+export function githubPushExecutor(execute) {
+    const executor = {
+        async request(route, params = {}) {
+            const sp = route.indexOf(' ');
+            const method = route.slice(0, sp);
+            // The push plane writes; the one read it makes is the current blob sha a Contents write
+            // needs (GitHub refuses an update without it) — a read that serves the push, never a pull.
+            let path = route.slice(sp + 1);
+            const body = {};
+            for (const [key, value] of Object.entries(params)) {
+                const token = `{${key}}`;
+                if (path.includes(token))
+                    path = path.replace(token, encodeURIComponent(String(value)));
+                else if (value !== undefined)
+                    body[key] = value;
+            }
+            const read = method === 'GET' || method === 'HEAD';
+            if (read && Object.keys(body).length > 0) {
+                const qs = new URLSearchParams();
+                for (const [key, value] of Object.entries(body))
+                    qs.set(key, String(value));
+                path += `${path.includes('?') ? '&' : '?'}${qs.toString()}`;
+            }
+            const res = await execute({
+                method,
+                path,
+                headers: { accept: 'application/vnd.github+json', 'user-agent': 'volter-twin-push', ...(read ? {} : { 'content-type': 'application/json' }) },
+                ...(read ? {} : { body: JSON.stringify(body) }),
+            });
+            // The vendor's own words ride the error: push health on the link must say WHY reality
+            // refused (a bare status is a guess), bounded so a page never lands in a ledger.
+            if (res.status >= 300)
+                throw new Error(`github remote push: ${route} answered ${res.status}${res.body === '' ? '' : ` — ${res.body.slice(0, 300)}`}`);
+            return { status: res.status, data: res.body === '' ? undefined : JSON.parse(res.body) };
+        },
+    };
+    return executor;
+}
+/** THE ANCHORED PUSH SEAM (contract "The push arm is the kernel's transaction; a pack performs one
+ *  action"): perform ONE pending action against GitHub over the kernel executor; the vendor's id comes back. */
+/** The vendor's id in the pack's own subject grammar: a number replaces the trailing number of the
+ *  local id (`acme/web#issue:1` → `acme/web#issue:57`, `acme/web#3` → `acme/web#9`, `comment:2` →
+ *  `comment:184`); anything else (a sha, a ref, a path, an owner/name) leaves the address as it is
+ *  and rides on the receipt as `vendorId`. The kernel rebinds the subject to what comes back
+ *  (contract "A pushed write adopts the vendor's id"). */
+export function adoptGithubId(localId, vendorId) {
+    if (!vendorId)
+        return localId;
+    if (/^\d+$/.test(vendorId) && /\d+$/.test(localId))
+        return localId.replace(/\d+$/, vendorId);
+    if (vendorId === localId || vendorId.includes('#') || vendorId.startsWith('comment:') || vendorId.startsWith('review:'))
+        return vendorId;
+    return localId;
+}
+export async function performGithubAction(execute, action, ctx) {
+    const externalIds = knownReviewCommentExternalIds(ctx.root);
+    const replyTo = action.fields?.in_reply_to;
+    if (replyTo !== undefined) {
+        const local = `comment:${replyTo}`;
+        const adopted = ctx.resolve('pull_request_review_comment', local);
+        if (adopted !== local && /^comment:\d+$/.test(adopted))
+            externalIds[String(replyTo)] = adopted.slice('comment:'.length);
+    }
+    const out = await pushGithubAction(githubPushExecutor(execute), action, { externalIds });
+    const adopted = adoptGithubId(action.subject.id, out.externalId);
+    // what the vendor minted rides on the receipt as fields: the number under which the row now lives
+    const numeric = out.externalId !== undefined && /^\d+$/.test(out.externalId) && adopted !== action.subject.id;
+    const data = { ...(numeric ? { number: Number(out.externalId) } : {}), ...(out.externalId && out.externalId !== adopted ? { vendorId: out.externalId } : {}) };
+    return { externalId: adopted, ...(Object.keys(data).length ? { data } : {}) };
+}
+/**
+ * THE REPOSITORY AND ITS BRANCHES are observed with the PRs and issues: a working copy's
+ * confirmed writes (a branch it cut, the repo it declared) survive only as what reality
+ * shows back, so the pull says what reality holds — the repo and every branch head.
+ */
+export async function observeRepositoryAndBranches(execute, owner, repo) {
+    const full = `${owner}/${repo}`;
+    const out = [];
+    const repoRes = await execute.request('GET /repos/{owner}/{repo}', { owner, repo }).catch(() => undefined);
+    const r = repoRes?.data;
+    if (repoRes !== undefined && repoRes.status < 300 && r !== undefined) {
+        out.push({ type: 'repository', id: `repo:${full}`, fields: { owner, name: repo, full_name: full, default_branch: String(r.default_branch ?? 'main'), private: r.private === true, description: r.description ?? null } });
+    }
+    const branchesRes = await execute.request('GET /repos/{owner}/{repo}/branches', { owner, repo, per_page: 100 }).catch(() => undefined);
+    const list = Array.isArray(branchesRes?.data) ? branchesRes.data : [];
+    for (const b of list) {
+        if (typeof b.name !== 'string')
+            continue;
+        out.push({ type: 'branch', id: `branch:${full}#${b.name}`, fields: { repository: full, name: b.name, commit_sha: String(b.commit?.sha ?? '') } });
+    }
+    return out;
+}
+/**
+ * THE R14 SCHEDULED-PULL ADAPTER (jira is the reference; this transcribes its METHOD):
+ * adapts this pack's executor onto the kernel's ONE RemoteExecute seam, so the twins
+ * service can schedule pulls with a sealed credential the pack never sees. Anchored
+ * naming: `createGithubTwinFetch` pairs with `syncGithubFromRemote`.
+ *
+ * The link's origin names the REPO, not just the API host — a link is a git remote:
+ *   https://api.github.com/repos/{owner}/{repo}
+ * Egress still anchors at the origin's HOST (the service's RemoteExecute discards the
+ * path when routing), so the path here is pure identity. Pull-plane only — every
+ * non-read request refuses loudly.
+ *
+ * Rate note, counted over the routes this pull actually calls: 2 list reads (the repo and
+ * its branches) + 1 PR list + 1 issue list, and then, per PR whose `updated_at` MOVED since
+ * the last pull, three PAGED conversation reads — the reviews, the issue comments and the
+ * inline comments — at 1 request each for a PR under 100 rows and up to 10 each beyond
+ * that. So a poll costs 4 + 3·CHANGED at the floor and 4 + 30·CHANGED at the ceiling; an
+ * unchanged PR costs nothing beyond the list. The link's sync interval still carries the
+ * budget — 60s at the default page floods a PAT's 5000/hr the first time it walks a busy
+ * repo; schedule github links at ≥120s.
+ */
+export async function syncGithubFromRemote(execute, opts = {}) {
+    // the repository is the end of the path: a served world's twin lives under /<org>/<world>/github
+    const match = /\/repos\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(opts.origin === undefined ? '' : new URL(opts.origin).pathname);
+    if (match === null) {
+        throw new Error('github remote pull: the link origin must name the repo — https://api.github.com/repos/{owner}/{repo}');
+    }
+    const [, owner, repo] = match;
+    const executor = {
+        async request(route, params = {}) {
+            const sp = route.indexOf(' ');
+            const method = route.slice(0, sp);
+            if (method !== 'GET' && method !== 'HEAD') {
+                throw new Error(`syncGithubFromRemote is the PULL plane: ${route} is a push-side operation and never runs here`);
+            }
+            // Same route grammar liveGithubExecute speaks: substitute {param} templates,
+            // remaining params become the query string (a read has no body).
+            let path = route.slice(sp + 1);
+            const rest = {};
+            for (const [key, value] of Object.entries(params)) {
+                const token = `{${key}}`;
+                if (path.includes(token))
+                    path = path.replace(token, encodeURIComponent(String(value)));
+                else
+                    rest[key] = value;
+            }
+            if (Object.keys(rest).length > 0) {
+                const qs = new URLSearchParams();
+                for (const [key, value] of Object.entries(rest))
+                    qs.set(key, String(value));
+                path += `${path.includes('?') ? '&' : '?'}${qs.toString()}`;
+            }
+            // GitHub answers 403 to any request without a User-Agent (its documented rule);
+            // workerd's fetch sends none, so the adapter names itself.
+            const res = await execute({ method, path, headers: { accept: 'application/vnd.github+json', 'user-agent': 'volter-twin-pull' } });
+            if (res.status >= 300)
+                throw new Error(`github remote pull: ${route} answered ${res.status}`);
+            return { status: res.status, data: res.body === '' ? undefined : JSON.parse(res.body) };
+        },
+    };
+    // The pull plane's instant is observation time — fetch metadata, never served content
+    // (R9 governs the serve path; this is the freshness half of the git model). `all`
+    // because the merge IS the observation that ends a job — closed PRs must fold.
+    return await syncGithubFromReal(executor, {
+        owner, repo,
+        occurredAt: new Date().toISOString(),
+        state: opts.state ?? 'all',
+        perPage: opts.perPage ?? 20,
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+}