@volter/twin-github 0.1.2 → 2.0.1

package/src/github-journey.uitest.ts

@@ -27,7 +27,7 @@
 // journey `goto()`s a PR path directly (no clicking) and proves back/forward (popstate).
 import { describe, test } from 'bun:test';
 import type { Page } from 'playwright';
-import { requireBrowser, runUiJourney, JOURNEY_TIMEOUT_MS, visible, gone, atPath, waitForMount } from '@volter/twin-tooling';
+import { requireBrowser, runUiJourney, JOURNEY_TIMEOUT_MS, visible, gone, atPath, waitForMount } from '@volter/world-tooling';
 
 const JOURNEY_LABEL = 'github UI journey';
 import { applyGithubWrite } from './github-twin.ts';
@@ -79,8 +79,8 @@ describe('github UI journey (pilot, TWIN-47 dev/02)', () => {
           occurredAt: '2026-05-03T00:00:00Z',
         });
       },
-      serve: (root) => {
-        const server = createGithubMirrorServer({ root, port: 0 });
+      serve: async (root) => {
+        const server = await createGithubMirrorServer({ root, port: 0 });
         return { url: `http://127.0.0.1:${server.port}`, stop: () => server.stop() };
       },
       journey: async (page) => {
@@ -91,51 +91,35 @@ describe('github UI journey (pilot, TWIN-47 dev/02)', () => {
         await visible(page, 'Twin Journey Beta PR');
         await atPath(page, '/pulls');
 
-        // 2. Click the Issues TAB (a real <button>, role-reachable) → the seeded issue title
-        //    appears AND the pulls-only markers (the seeded PR titles) are gone — proves the
-        //    click handler fired and the view actually swapped (hydration is live, not SSR
-        //    residue left over from the initial HTML). URL: /issues (no issue opened yet).
-        await page.getByRole('button', { name: /^Issues/ }).click();
+        // 2. Open the Alpha PR from the list by its title link (GitHub's list rows are links) →
+        //    its body appears, content the list row never renders. Opening a PR routes to ITS
+        //    OWN repo's numbered path, even from the cross-repo list — /acme/twin-journey/pull/1.
+        await gone(page, 'alpha-pr-body-marker');
+        await page.getByRole('link', { name: 'Twin Journey Alpha PR' }).click();
+        await visible(page, 'alpha-pr-body-marker');
+        await atPath(page, '/acme/twin-journey/pull/1');
+
+        // 3. The pull request page carries its repository's navigation: its Issues tab swaps the
+        //    view (the PR's body is gone, the seeded issue shows). URL: /acme/twin-journey/issues.
+        await page.getByRole('link', { name: /^Issues/ }).click();
         await visible(page, 'Twin Journey Tracking Issue');
-        await gone(page, 'Twin Journey Alpha PR');
-        await gone(page, 'Twin Journey Beta PR');
-        await atPath(page, '/issues');
+        await gone(page, 'alpha-pr-body-marker');
+        await atPath(page, '/acme/twin-journey/issues');
 
-        // 2b. Click the seeded issue's row (dev/02: github.journey.issue_detail — the Issues
-        //     row is a role-reachable <button>, not a bare onClick <div>). With only one seeded
-        //     issue, its detail pane is already shown as the split-pane default (same
-        //     single-item fallback the PR view uses, so no "gone before click" assertion here
-        //     — that's covered by the multi-PR case below); the URL is what proves the click
-        //     actually navigated: it becomes the issue's own repo-scoped detail path — issues
-        //     and PRs share one number counter, so this repo's 3rd object (after the 2 seeded
-        //     PRs) is issue #3.
+        // 3b. Click the seeded issue's row (a role-reachable <button>): the URL becomes the
+        //     issue's own path — issues and PRs share one number counter, so it is #3.
         await visible(page, 'tracking-issue-body-marker');
         await page.getByRole('button', { name: /Twin Journey Tracking Issue/ }).click();
         await atPath(page, '/acme/twin-journey/issues/3');
 
-        // 3. Click back to Pull requests — the PR titles reappear (round-trip proves the tab
-        //    state, not a one-way navigation, actually drives the render). URL: back to /pulls
-        //    (no PR opened in this run yet, so no numbered path).
-        await page.getByRole('button', { name: /^Pull requests/ }).click();
-        await visible(page, 'Twin Journey Alpha PR');
-        await atPath(page, '/pulls');
-
-        // 4. Click the Alpha PR's row (a real <button>, role-reachable via its title text) →
-        //    its body appears in the detail pane — content the list row NEVER renders (the
-        //    list row only shows title/repo/state/meta, never pr.body). This proves selection
-        //    state flows PR-specific data through a live store-door fetch (`GET /twin/store/mirror`), not a static shell.
-        //    URL: opening a PR always routes to ITS OWN repo's numbered path, even from the
-        //    "all repos" list — /acme/twin-journey/pull/1.
-        await gone(page, 'alpha-pr-body-marker'); // not shown pre-selection (Beta sorts first)
-        await page.getByRole('button', { name: /Twin Journey Alpha PR/ }).click();
-        await visible(page, 'alpha-pr-body-marker');
-        await atPath(page, '/acme/twin-journey/pull/1');
+        // 4. Back to Pull requests through the repository tab: the list shows both PRs again.
+        await page.getByRole('link', { name: /^Pull requests/ }).click();
+        await visible(page, 'Twin Journey Beta PR');
+        await atPath(page, '/acme/twin-journey/pulls');
 
-        // 5. Click the Beta PR's row → its review body (seeded via a REAL review write)
-        //    becomes visible — proves the review data-coupling reaches the live DOM too, and
-        //    that switching selection re-renders (Alpha's body is no longer shown). URL moves
-        //    to PR #2's path.
-        await page.getByRole('button', { name: /Twin Journey Beta PR/ }).click();
+        // 5. Open the Beta PR → its review body (seeded via a REAL review write) renders in the
+        //    timeline, and Alpha's body is not shown. URL moves to PR #2's path.
+        await page.getByRole('link', { name: 'Twin Journey Beta PR' }).click();
         await visible(page, 'beta-review-body-marker');
         await gone(page, 'alpha-pr-body-marker');
         await atPath(page, '/acme/twin-journey/pull/2');
@@ -162,8 +146,8 @@ describe('github UI journey — deep link + back/forward (TWIN-49 / H3, dev/02)'
           occurredAt: '2026-05-10T01:00:00Z',
         });
       },
-      serve: (root) => {
-        const server = createGithubMirrorServer({ root, port: 0 });
+      serve: async (root) => {
+        const server = await createGithubMirrorServer({ root, port: 0 });
         return { url: `http://127.0.0.1:${server.port}`, stop: () => server.stop() };
       },
       journey: async (page) => {
@@ -179,7 +163,7 @@ describe('github UI journey — deep link + back/forward (TWIN-49 / H3, dev/02)'
 
         // Click to another view (real navigation, pushState) — proves the deep-linked page is
         // still live/interactive, not a dead static render.
-        await page.getByRole('button', { name: /^Issues/ }).click();
+        await page.getByRole('link', { name: /^Issues/ }).click();
         await atPath(page, '/acme/deep-link-journey/issues');
         await gone(page, 'deep-link-beta-body-marker');
 

package/src/github-mirror-state.ts

@@ -20,7 +20,12 @@ const OBSERVED = 'content not mirrored by the evidence twin';
 
 /** The `mirror` store: the whole console payload, projected from the twin's github world. */
 export function githubMirrorState(root?: string): Record<string, unknown> {
-  const { prs, issues, reviews: foldedReviews, comments: foldedComments, statuses, checkRuns, milestones, workflows: foldedWorkflows, workflowRuns, jobs, releases: foldedReleases, releaseAssets, tags, discussions: foldedDiscussions, discussionComments: foldedDiscussionComments, discussionCategories: customCategories, contents: foldedContents, notifications: foldedNotifications, deployments: foldedDeployments, deploymentStatuses: foldedDeploymentStatuses, environments: foldedEnvironments, projects: foldedProjects, projectFields: foldedProjectFields, projectItems: foldedProjectItems, projectViews: foldedProjectViews, repos: foldedRepos, collaborators: foldedCollaborators, webhooks: foldedWebhooks, branches: foldedBranches } = githubState(root);
+  const { prs: foldedPrs, issues, reviews: foldedReviews, comments: foldedComments, statuses, checkRuns, milestones, workflows: foldedWorkflows, workflowRuns, jobs, releases: foldedReleases, releaseAssets, tags, discussions: foldedDiscussions, discussionComments: foldedDiscussionComments, contents: foldedContents, notifications: foldedNotifications, deployments: foldedDeployments, deploymentStatuses: foldedDeploymentStatuses, environments: foldedEnvironments, projects: foldedProjects, projectFields: foldedProjectFields, projectItems: foldedProjectItems, projectViews: foldedProjectViews, repos: foldedRepos, collaborators: foldedCollaborators, webhooks: foldedWebhooks, branches: foldedBranches } = githubState(root);
+  // Only PULL REQUESTS are pull requests. The fold's `prs` map also holds the shells it
+  // materializes for the review/comment counters, which hang off issue numbers too — the
+  // mirror is a door onto the same world the REST list serves, and the two must agree about
+  // what a pull request is.
+  const prs = foldedPrs.filter((p) => p.is_pull_request);
   // CI rollup per PR head_sha from commit statuses + check runs (a LOCAL CI construct;
   // observed-only PRs carry no head_sha CI, so this stays null for them — honesty).
   // Precedence mirrors GitHub's rollup: any failure/error → 'failure'; any pending/queued/
@@ -75,35 +80,10 @@ export function githubMirrorState(root?: string): Record<string, unknown> {
       ciStatus: ciStatusFor(pr.repository, pr.head_sha),
     };
   });
-  // Per-commit detail + per-file diffs ride on LOCAL PR writes only (observed PR evidence
-  // carries COUNTS, never content) — so these lists are empty for observed-only PRs, keeping
-  // the mirror honest. Each entry is tagged with repo+number so the client can scope it to
-  // the selected PR, mirroring the GitHub conversation's Commits + Files-changed sections.
-  const commits = prs.flatMap((pr) =>
-    (pr.commits_list ?? []).map((c) => ({
-      repo: pr.repository,
-      number: pr.number,
-      sha: c.sha,
-      message: c.message,
-      author: c.author_name,
-      date: c.author_date,
-      url: `${GITHUB_WEB_ORIGIN}/${pr.repository}/commit/${c.sha}`,
-    })),
-  );
-  const files = prs.flatMap((pr) =>
-    (pr.files ?? []).map((f) => ({
-      repo: pr.repository,
-      number: pr.number,
-      filename: f.filename,
-      status: f.status,
-      additions: f.additions,
-      deletions: f.deletions,
-      changes: f.changes,
-      // patch: the unified-diff hunk text (LOCAL writes only) — the Files-changed diff view
-      // renders these as +/- lines; observed PRs carry no per-file diff so this is undefined.
-      patch: f.patch,
-    })),
-  );
+  // Per-commit detail and per-file diffs live in the git plane, which this projection does not read: the console
+  // reads them over REST (client/pulls-rest.ts).
+  const commits: never[] = [];
+  const files: never[] = [];
   // First-class issues (a LOCAL construct) grouped per repo via the `repo` field, like PRs.
   const issuesOut = issues.map((iss) => {
     const ms = iss.milestone !== undefined ? milestones.find((m) => m.repository === iss.repository && m.number === iss.milestone) : undefined;
@@ -121,14 +101,6 @@ export function githubMirrorState(root?: string): Record<string, unknown> {
       milestone: ms?.title,
       stateReason: iss.state_reason ?? undefined,
       locked: iss.locked ?? false,
-      // linked PRs/issues (a LOCAL relation): surface as typed references the client links.
-      linked: (iss.linked ?? []).map((l) => ({
-        type: l.type,
-        number: l.number,
-        url: l.type === 'pull_request'
-          ? `${GITHUB_WEB_ORIGIN}${githubPullPath(iss.repository, l.number)}`
-          : `${GITHUB_WEB_ORIGIN}${githubIssuePath(iss.repository, l.number)}`,
-      })),
       // issue comments (kind:'issue' on the shared comment space) — the detail page renders
       // these in its timeline; observed comments carry no body (labelled, never fabricated).
       comments: foldedComments
@@ -239,7 +211,7 @@ export function githubMirrorState(root?: string): Record<string, unknown> {
   // answer pointer, and its comments/replies (with the is_answer flag). Surfaced per-repo.
   const discussionRepos = new Set(foldedDiscussions.map((d) => d.repository));
   const categoryByRepoSlug = new Map<string, { name: string; emoji?: string; isAnswerable: boolean }>();
-  for (const r of discussionRepos) for (const c of discussionCategoriesFor(r, customCategories)) categoryByRepoSlug.set(`${r}#${c.slug}`, { name: c.name, emoji: c.emoji, isAnswerable: c.is_answerable ?? false });
+  for (const r of discussionRepos) for (const c of discussionCategoriesFor(r)) categoryByRepoSlug.set(`${r}#${c.slug}`, { name: c.name, emoji: c.emoji, isAnswerable: c.is_answerable ?? false });
   const discussions = foldedDiscussions.map((d) => {
     const cat = d.category_slug ? categoryByRepoSlug.get(`${d.repository}#${d.category_slug}`) : undefined;
     const threadComments = foldedDiscussionComments.filter((c) => c.repository === d.repository && c.discussion_number === d.number);
@@ -305,43 +277,32 @@ export function githubMirrorState(root?: string): Record<string, unknown> {
     reviewers: e.reviewers ?? [],
     protected: Boolean(e.wait_timer) || Boolean(e.reviewers?.length),
   }));
-  // ── Projects v2 board (a LOCAL construct) — the Project board screen. Each project carries
-  //   its views (board/table) + its Status field's options as COLUMNS, and its items grouped
-  //   into those columns by their Status field value (the board's swim-lanes). Data-coupled:
-  //   seeding a project + a Status field + items moves the column counts the board renders.
+  // ── Projects v2 boards — the Project board screen. Each project carries its views and its first single-select
+  //   field's options as COLUMNS, with its items grouped into them by that field's value; an item with none lands
+  //   in "No Status" (GitHub's board). Data-coupled: a field, an item or a value moves what the board renders.
   const projectBoards = foldedProjects.map((p) => {
     const fields = foldedProjectFields.filter((f) => f.project_id === p.id);
-    const statusField = fields.find((f) => f.data_type === 'single_select') ?? fields.find((f) => /status/i.test(f.name));
-    const columnNames = statusField?.options?.map((o) => o.name) ?? [];
+    const statusField = fields.find((f) => f.data_type === 'single_select');
     const items = foldedProjectItems.filter((i) => i.project_id === p.id);
-    const columns = columnNames.map((name) => ({
-      name,
-      cards: items
-        .filter((i) => String((i.field_values as Record<string, unknown>)[statusField!.name] ?? '') === name)
-        .map((i) => ({ id: i.id, title: i.title ?? `#${i.content_id ?? i.id}`, contentType: i.content_type })),
-    }));
-    // items with no (or an unrecognized) status land in a "No Status" lane (GitHub behavior).
-    const noStatus = items.filter((i) => !columnNames.includes(String((i.field_values as Record<string, unknown>)[statusField?.name ?? ''] ?? '')));
+    const card = (i: (typeof items)[number]) => ({ id: i.id, title: i.title ?? `#${i.content_number ?? i.id}`, contentType: i.content_type });
+    const optionOf = (i: (typeof items)[number]) => statusField?.options?.find((o) => o.id === i.field_values?.[statusField.id]);
     return {
       id: p.id, number: p.number, title: p.title, owner: p.owner, closed: p.closed ?? false,
       views: foldedProjectViews.filter((v) => v.project_id === p.id).map((v) => ({ number: v.number, name: v.name, layout: v.layout })),
       fields: fields.map((f) => ({ name: f.name, dataType: f.data_type })),
       itemCount: items.length,
-      columns,
-      noStatus: { name: 'No Status', cards: noStatus.map((i) => ({ id: i.id, title: i.title ?? `#${i.content_id ?? i.id}`, contentType: i.content_type })) },
+      columns: (statusField?.options ?? []).map((o) => ({ name: o.name, cards: items.filter((i) => optionOf(i)?.id === o.id).map(card) })),
+      noStatus: { name: 'No Status', cards: items.filter((i) => !optionOf(i)).map(card) },
       url: `${GITHUB_WEB_ORIGIN}/${p.owner_type === 'organization' ? 'orgs/' : 'users/'}${p.owner}/projects/${p.number}`,
     };
   });
   // ── Insights / Pulse / Contributors (DERIVED per repo from the modeled PRs/issues/commits) —
-  //   the Pulse screen's counts (merged/opened PRs, opened/closed issues) + a contributors
-  //   leaderboard from the per-commit authors the twin tracks. Data-coupled: each new PR/issue
-  //   moves a Pulse count; each new commit author moves a contributor's commit total.
+  //   the Pulse screen's counts (merged/opened PRs, opened/closed issues). Data-coupled: each new
+  //   PR/issue moves a Pulse count.
   const repoNames = new Set<string>([...prs.map((p) => p.repository), ...issues.map((i) => i.repository), ...foldedRepos.map((r) => r.full_name)]);
   const insights = [...repoNames].sort().map((repo) => {
     const repoPrs = prs.filter((p) => p.repository === repo);
     const repoIssues = issues.filter((i) => i.repository === repo);
-    const contribCounts = new Map<string, number>();
-    for (const pr of repoPrs) for (const c of pr.commits_list ?? []) { const a = c.author_name ?? '(unknown)'; contribCounts.set(a, (contribCounts.get(a) ?? 0) + 1); }
     return {
       repo,
       pulse: {
@@ -350,7 +311,8 @@ export function githubMirrorState(root?: string): Record<string, unknown> {
         openedIssues: repoIssues.filter((i) => (i.state ?? 'open') === 'open').length,
         closedIssues: repoIssues.filter((i) => i.state === 'closed').length,
       },
-      contributors: [...contribCounts.entries()].map(([login, commits]) => ({ login, commits })).sort((a, b) => b.commits - a.commits),
+      // commit authors live in the git plane, which this projection does not read
+      contributors: [],
     };
   });
   // ── Settings (DERIVED per repo from the modeled repo config + collaborators/webhooks/branches)

package/src/github-mirror-ui.ts

@@ -7,6 +7,9 @@
 // console makes goes through the vendor's own REST API on the same origin — the wire a
 // real GitHub client speaks, so the mirror renders a twin or a real account unchanged,
 // pointed at any origin by configuration. The client is the shared world UI-mirror design.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
 import { createGithubTwinFetch } from './github-server.ts';
 
 const CLIENT_ENTRY = () => new URL('../client/github-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
@@ -14,17 +17,15 @@ const CLIENT_CSS = () => new URL('../client/github-mirror.css', import.meta.url)
 
 const APP_SHELL = `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<title>GitHub UI mirror (twin)</title><link rel="stylesheet" href="/assets/styles.css"></head>
-<body><div id="root"></div><script type="module" src="/assets/app.js"></script></body></html>`;
+<base href="/"><title>GitHub UI mirror (twin)</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
 
+// cache: the built client bundle, memoized per process — a build artifact, never twin state (the tree
+// holds what this UI renders); cleared on a failed build so the next request rebuilds.
 let clientBundle: Promise<string> | null = null;
 export function buildGithubMirrorClient(): Promise<string> {
   if (!clientBundle) {
-    clientBundle = Bun.build({ entrypoints: [CLIENT_ENTRY()], target: 'browser', minify: true })
-      .then(async (result) => {
-        if (!result.success) throw new Error(result.logs.map((l) => l.message).join('\n') || 'github UI mirror client build failed');
-        return result.outputs[0]!.text();
-      })
+    clientBundle = bundleClient(CLIENT_ENTRY())
       .catch((error) => { clientBundle = null; throw error; });
   }
   return clientBundle;
@@ -56,9 +57,9 @@ function isGitSmartHttpPath(pathname: string): boolean {
  * drift. There is no mirror-private route: `/api/state` (the old fold) answers with the
  * vendor's own `Not Found` envelope, because GitHub has no such endpoint.
  */
-export function createGithubMirrorServer(options: { root?: string; port?: number }): { port: number; stop: () => void } {
+export async function createGithubMirrorServer(options: { root?: string; port?: number }): Promise<{ port: number; stop: () => void }> {
   const twin = createGithubTwinFetch({ ...(options.root !== undefined ? { root: options.root } : {}) });
-  const server = Bun.serve({
+  const server = await serveHttp({
     // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
     // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
     // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
@@ -76,7 +77,7 @@ export function createGithubMirrorServer(options: { root?: string; port?: number
         catch (error) { return new Response(String(error), { status: 500 }); }
       }
       if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
-        return new Response(Bun.file(CLIENT_CSS()), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+        return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
       }
       // The uniform doors (`/twin`, `/twin/store/<name>`) are the twin's, whoever asks.
       if (url.pathname === '/twin' || url.pathname.startsWith('/twin/')) return twin(request);
@@ -95,3 +96,8 @@ export function createGithubMirrorServer(options: { root?: string; port?: number
 export function githubMirrorHtml(): string {
   return APP_SHELL;
 }
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function githubMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}

package/src/github-server.ts

@@ -4,11 +4,25 @@
 // actions and fire GitHub webhooks (R17). Mirror mode rejects writes (R4).
 // The git SMART-HTTP protocol (clone/fetch/push by an unmodified `git` CLI) is served
 // FIRST — its routes (/:owner/:repo/info/refs, git-upload-pack, git-receive-pack) are
-// binary pkt-line streams bridged to real `git` subprocesses (github-git-http.ts); a
-// receive-pack push emits `push` webhooks through the same emitGithubEvent pipeline.
-import { applyGithubWrite, handleGithubRequest } from './github-twin.ts';
-import { worldNow, statefulTwinManifest} from '@volter/twin';
-import { emitGithubEvent } from './github-events.ts';
+// binary pkt-line streams over the kernel's git library (github-git-http.ts); a push is
+// announced as an API commit's is (semantics/shared.ts announce).
+import { bindSemantics, compileSurface, coreFor, createDerivedFetch, crossCutting, matchOperation, semanticsContext, serveHttp, vendorError } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest, spanning } from './manifest.ts';
+import { githubSemantics } from './semantics/index.ts';
+import { githubGraphql } from './semantics/graphql.ts';
+import { createGraphqlWire } from './graphql-wire.ts';
+import { githubState, handleGithubDoor, revokedToken } from './github-twin.ts';
+import { announce } from './semantics/shared.ts';
+import { answerVendorErrors, RefusedWriteError } from '@volter/world-core';
+import { worldNow, statefulTwinManifest} from '@volter/world-core';
+import { createHash } from 'node:crypto';
+import { githubOAuthFlow } from './screens/oauth.tsx';
+import { githubSessionFlow } from './screens/session.tsx';
+import { githubNpmRegistry } from './npm-registry.ts';
+import { githubAppInstallationFlow } from './screens/app-installation.tsx';
+import { githubAppManifestFlow } from './screens/app-manifest.tsx';
+import { assetUploads } from './semantics/releases.ts';
 import { handleGithubGitSmartHttp, parseGitSmartHttpPath } from './github-git-http.ts';
 import { githubMirrorState } from './github-mirror-state.ts';
 import { GITHUB_MIRROR_STORE } from './github-shared.ts';
@@ -27,7 +41,7 @@ const STORE_DOOR = '/twin/store/';
 /** Options shared by the fetch handler and the Bun.serve wrapper around it. `port` is a BIND
  *  concern the fetch ignores; it stays in one shape so a caller configures the twin once
  *  whichever way it is mounted. */
-export type GithubTwinOptions = { root?: string; port?: number; readOnly?: boolean };
+export type GithubTwinOptions = { root?: string; port?: number; readOnly?: boolean; clock?: () => string };
 
 /**
  * The whole GitHub serve path as a plain `(Request) => Response` — the `/twin` manifest, the
@@ -35,23 +49,37 @@ export type GithubTwinOptions = { root?: string; port?: number; readOnly?: boole
  * about it is port-bound, and `createGithubTwinServer` is one line of `Bun.serve` around it,
  * so the standalone (R1) and any in-process lane execute the SAME bytes of serving code.
  *
- * The GIT PLANE is a BUN-SHELL CAPABILITY, not a serve-path prerequisite: real bare repos
- * on a real filesystem driven by real `git` subprocesses (github-git-plane.ts —
- * `Bun.spawnSync(['git', …])` + `node:fs` under `worldPaths('github')`, bypassing the
- * WorldStore seam by design: "the bare repo IS the object store, one store not two").
- * Every plane touch on the REST read path is EXISTENCE-GUARDED (`hasBareRepo` →
- * `existsSync`), so on a shell with no plane (workerd: no `git`, empty virtual fs) the
- * plane is simply ABSENT — reads answer from the folded observed/action state alone, which
- * is exactly what a pull-fed remote mirror serves (R14: `syncGithubFromRemote` folds PRs,
- * reviews, comments and issues; none of that needs the plane). The git smart-HTTP branch
- * is the one route that cannot degrade: it refuses loudly where `git` cannot be spawned,
- * because a clone/push against a plane-less shell has no honest answer but no.
+ * The GIT PLANE is the KERNEL'S GIT LIBRARY (docs/contributing/architecture.md#the-engine-slot):
+ * one content-addressed object store per world over the blob seam, refs as world state, smart HTTP
+ * in pure JS — Bun and workerd alike, no `git` binary. Every plane touch on the REST read path is
+ * still existence-guarded (`hasBareRepo`), so a world with no repositories answers from the folded
+ * state alone, which is exactly what a pull-fed remote mirror serves (R14: `syncGithubFromRemote` folds PRs,
+ * reviews, comments and issues; none of that needs the plane).
  */
+/** A release asset's upload: its raw bytes and media type go to the upload operation beside a request with no body,
+ *  since the operation reads them as the file (semantics/releases.ts). */
+async function uploadingAsset(request: Request, inner: (request: Request) => Promise<Response>): Promise<Response> {
+  const bytes = new Uint8Array(await request.arrayBuffer());
+  const type = request.headers.get('content-type');
+  const headers = new Headers(request.headers);
+  headers.delete('content-type'); headers.delete('content-length');
+  return assetUploads.run({ bytes, type }, () => inner(new Request(request.url, { method: request.method, headers })));
+}
+
+/** GitHub's refusal of a request body that is not JSON. */
+function malformedJson(): Response {
+  return Response.json({ message: 'invalid JSON body' }, { status: 400 });
+}
+
 export function createGithubTwinFetch(options: GithubTwinOptions): (request: Request) => Promise<Response> {
   const readOnly = options.readOnly ?? false;
   const stores: Record<string, () => unknown> = { [GITHUB_MIRROR_STORE]: () => githubMirrorState(options.root) };
   const storeNames = Object.keys(stores).sort();
-  return async function githubTwinFetch(request: Request): Promise<Response> {
+  const now = options.clock ?? worldNow;
+  const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+  // The twin's doors, in front of GitHub's API: discovery, the store door, the git plane and the stand-ins for acts
+  // GitHub does in its web UI (github-twin.ts handleGithubDoor).
+  const doors = async (request: Request): Promise<Response | undefined> => {
     const url = new URL(request.url);
     const cleanPath = url.pathname.replace(/\/+$/, '') || '/';
     // GET /twin — the discovery manifest (education inside the twin). It EDUCATES the
@@ -68,16 +96,10 @@ export function createGithubTwinFetch(options: GithubTwinOptions): (request: Req
       if (store === undefined) return Response.json({ error: 'unknown store', store: name, stores: storeNames }, { status: 404 });
       return Response.json(store());
     }
-    const path = url.pathname + url.search;
-    // git smart-HTTP (binary protocol, not JSON) — try first; null means "not a git route".
-    // Route-parse BEFORE touching the body so ordinary REST POSTs are never double-buffered.
+    // git smart-HTTP (binary protocol, not JSON). Route-parse BEFORE touching the body so ordinary REST POSTs are
+    // never double-buffered.
     if ((request.method === 'GET' || request.method === 'POST') && parseGitSmartHttpPath(request.method, url.pathname)) {
-      // Plane-less shells (workerd) cannot spawn git: refuse the protocol loudly instead
-      // of dying mid-pkt-line. The REST evidence surface below still serves.
-      if (typeof Bun === 'undefined' || typeof Bun.spawnSync !== 'function') {
-        return Response.json({ message: 'git smart-HTTP is not served on this deployment (no git plane); the REST evidence surface is' }, { status: 501 });
-      }
-      const occurredAt = worldNow();
+      const occurredAt = now();
       const git = await handleGithubGitSmartHttp({
         method: request.method,
         pathname: url.pathname,
@@ -90,47 +112,123 @@ export function createGithubTwinFetch(options: GithubTwinOptions): (request: Req
         occurredAt,
       });
       if (git) {
-        // Webhook delivery is fire-and-forget (real GitHub: a delivery failure never fails
-        // the push) — a dead emit pipeline reddens the webhook verifies, not the protocol.
-        for (const webhook of git.webhooks) { try { await emitGithubEvent(webhook, { occurredAt }); } catch { /* fire-and-forget */ } }
+        // a push moves branches as an API commit does: GitHub's own processes read it (workflows, secret scanning,
+        // Dependabot, rulesets) and its webhooks are delivered (semantics/shared.ts announce)
+        if (git.webhooks.length) {
+          const ctx = await semanticsContext(manifest, new Request(request.url, { headers: request.headers }), GIT_OPERATION, { ...scope, clock: () => occurredAt });
+          await announce(ctx, git.webhooks);
+        }
         return new Response(git.body as BodyInit, { status: git.status, headers: { 'content-type': git.contentType, 'cache-control': 'no-cache' } });
       }
     }
-    if (request.method === 'GET') {
-      if (url.pathname === '/' || url.pathname === '') return Response.json({ service: 'github', readOnly, evidence_only: true });
-      const { status, body } = handleGithubRequest({ method: 'GET', path, ...(options.root !== undefined ? { root: options.root } : {}) });
-      // 204 (e.g. "check if PR merged") carries no body.
-      if (status === 204 || body === undefined) return new Response(null, { status });
-      return Response.json(body as Record<string, unknown>, { status });
+    return readOnly ? undefined : handleGithubDoor(request, { ...scope, now });
+  };
+  // An archived repository is read-only (docs.github.com/repositories/archiving-a-github-repository/archiving-repositories/
+  // about-archiving-repositories): GitHub refuses a write to it, except the repository's own edit (which unarchives it),
+  // deleting it, and a person's own watch of it.
+  const cross = crossCutting(manifest, { readOnly, ...scope });
+  const readOnlyWhenArchived = (request: Request, next: () => Promise<Response>): Promise<Response> => {
+    if (request.method === 'GET' || request.method === 'HEAD') return next();
+    const seg = new URL(request.url).pathname.split('/').filter(Boolean);
+    if (seg[0] !== 'repos' || !seg[2] || seg.length === 3 || (seg.length === 4 && seg[3] === 'subscription')) return next();
+    if (!githubState(scope.root).repos.find((r) => r.full_name === `${seg[1]}/${seg[2]}`)?.archived) return next();
+    return Promise.resolve(Response.json({ message: 'Repository was archived so is read-only.', documentation_url: 'https://docs.github.com/articles/about-archiving-repositories' }, { status: 403 }));
+  };
+  // a refused or failed write at the head (kernel head.ts) answers in the vendor's own error shape
+  // The derived dispatch owns the REST wire: semantics handlers, then the derived core; an operation neither
+  // serves answers GitHub's Not Found.
+  const inner = createDerivedFetch({
+    surface: githubSurface,
+    handlers: bindSemantics(manifest, githubSemantics({ readOnly }), scope),
+    core: coreFor(manifest, scope),
+    around: (call, next) => readOnlyWhenArchived(call.request, () => cross(call, next)),
+    gap: () => vendorError(manifest, manifest.notFound),
+  });
+  // GraphQL is a second wire over the same state: the vendor's schema and the pack's resolvers, which get
+  // the handler interface for their request (semanticsContext). A query selecting a field nothing models
+  // answers GitHub's undefinedField error; a read-only twin refuses a mutation as it refuses any write.
+  const graphqlSemantics = githubGraphql();
+  const graphqlWire = createGraphqlWire({
+    loadSdl: async () => ((await import('./generated/graphql-sdl.gen.json', { with: { type: 'json' } })).default as { sdl: string }).sdl,
+    resolvers: graphqlSemantics.resolvers,
+    stored: graphqlSemantics.stored,
+    context: async (request) => ({ ctx: await semanticsContext(manifest, request, GRAPHQL_OPERATION, { ...scope, clock: now }) }),
+    unmodeled: ({ type, field }) => Response.json({ errors: [{ message: `Field '${field}' doesn't exist on type '${type}' in the twin's modeled GraphQL subset`, type: 'undefinedField' }] }),
+  });
+  const graphql = async (request: Request): Promise<Response> => {
+    if (readOnly) {
+      const { query } = (await request.clone().json().catch(() => ({}))) as { query?: unknown };
+      if (typeof query === 'string' && /^\s*mutation\b/.test(query)) return Response.json({ message: 'twin is read-only (mirror mode); start in simulator/fork to write' }, { status: 403 });
     }
-    if (request.method === 'POST' || request.method === 'PATCH' || request.method === 'PUT' || request.method === 'DELETE') {
-      const text = await request.text();
-      // THE WORLD INSTANT, threaded into the write (R9). Without it `applyGithubWrite` falls back
-      // to `new Date().toISOString()`, and every wall-clock stamp it lands — `created_at`/
-      // `updated_at` on repos, issues, comments, reviews, statuses — differs between two
-      // identical worlds. The same instant then stamps the webhook deliveries below, so a write
-      // and its delivery can never disagree about when they happened.
-      const occurredAt = worldNow();
-      const outcome = await applyGithubWrite({ method: request.method, path, body: text, ...(options.root !== undefined ? { root: options.root } : {}), readOnly, occurredAt });
-      // Defensive 500 (never a thrown socket error) when a handler yields no response —
-      // real servers answer 500 to a handler fault; a throw here would surface as an
-      // unhandled rejection in embedding test runners instead of an HTTP status.
-      const response = outcome?.response;
-      if (!response) return Response.json({ message: 'twin handler returned no response' }, { status: 500 });
-      // Fire-and-forget, like real GitHub: a webhook delivery failure never fails the write.
-      for (const event of [...(outcome.webhook ? [outcome.webhook] : []), ...(outcome.webhooks ?? [])]) {
-        try { await emitGithubEvent(event, { occurredAt }); } catch { /* fire-and-forget */ }
-      }
-      // 204 (e.g. workflow_dispatch) carries no body.
-      if (response.status === 204 || response.body === undefined) return new Response(null, { status: response.status });
-      return Response.json(response.body as Record<string, unknown>, { status: response.status });
+    return graphqlWire(request);
+  };
+  // GitHub reads a write's body as JSON whatever its content type says (manifest.body.json), and
+  // answers 400 to one that does not parse.
+  const routes = compileSurface(githubSurface);
+  const rest = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const matched = readOnly || request.method === 'GET' || request.method === 'HEAD' ? undefined : matchOperation(routes, request.method, url.pathname, url.searchParams);
+    if (!matched) return inner(request);
+    // a release asset's body is the file itself, posted to the release's upload_url on uploads.github.com, not to the
+    // API host (docs.github.com/rest/releases/assets#upload-a-release-asset). Where the documentation stops and the
+    // twin decides: api.github.com answers the path as a route it does not serve, GitHub's 404; any other host is the
+    // twin's own address (a World's mount, a local port), where the two GitHub hosts cannot be told apart.
+    if (matched.operation.id === 'repos/upload-release-asset') {
+      if (url.hostname === 'api.github.com') return Response.json({ message: 'Not Found', documentation_url: 'https://docs.github.com/rest', status: '404' }, { status: 404 });
+      return uploadingAsset(request, inner);
     }
-    return Response.json({ message: `method ${request.method} not supported` }, { status: 405 });
+    const text = await request.clone().text();
+    if (!text) return inner(request);
+    try { JSON.parse(text); } catch { return malformedJson(); }
+    return inner(request);
   };
+  // github.com's OAuth web flow (a hosted flow: the consent screen and the code exchange) sits beside the API
+  // the sign-in every page sends a visitor to who is not signed in (src/screens/session.tsx)
+  const session = githubSessionFlow({ ...(options.root !== undefined ? { root: options.root } : {}), now });
+  const oauth = githubOAuthFlow({ ...(options.root !== undefined ? { root: options.root } : {}), now });
+  // and a GitHub App's installation page (src/screens/app-installation.tsx)
+  const appInstall = githubAppInstallationFlow({ ...(options.root !== undefined ? { root: options.root } : {}), now });
+  // and the page that registers a GitHub App from a manifest (src/screens/app-manifest.tsx)
+  const appManifest = githubAppManifestFlow({ ...(options.root !== undefined ? { root: options.root } : {}), now });
+  // and GitHub Packages' npm registry, where `npm publish` puts a package (src/npm-registry.ts)
+  const npmRegistry = githubNpmRegistry({ ...(options.root !== undefined ? { root: options.root } : {}), now });
+  const wires = async (request: Request): Promise<Response> => {
+    const path = new URL(request.url).pathname.replace(/\/+$/, '');
+    const flow = readOnly ? undefined : (await session(request)) ?? (await oauth(request)) ?? (await appInstall(request)) ?? (await appManifest(request)) ?? (await npmRegistry(request));
+    if (flow) return flow;
+    return request.method === 'POST' && (path === '/graphql' || path === '/api/graphql') ? graphql(request) : rest(request);
+  };
+  const served = async (request: Request): Promise<Response> => (await doors(request)) ?? wires(request);
+  const vended = answerVendorErrors(served, (error) => Response.json({ message: error instanceof RefusedWriteError ? `Validation Failed: ${error.message}` : error.message, errors: [{ resource: 'Write', code: error instanceof RefusedWriteError ? 'refused' : 'failed', message: error.message }], documentation_url: 'https://docs.github.com/rest' }, { status: 422 }));
+  // Every answer carries GitHub's own headers for when and which request it was: Date on the World's clock (a response
+  // dated by the host's clock contradicts the World's time) and an x-github-request-id in GitHub's colon-separated hex
+  // form, derived from the instant, the request and a counter so the same request twice gets two ids.
+  let answered = 0;
+  // which part serves each spec operation (the derived dispatch's owners), for the pack's report
+  return Object.assign(async (request: Request): Promise<Response> => {
+    const token = (request.headers.get('authorization') ?? '').replace(/^(?:bearer|token)\s+/i, '').trim() || undefined;
+    const res = revokedToken(token, options.root) ? vendorError(manifest, { status: 401, message: 'Bad credentials' }) : await vended(request);
+    const at = now();
+    const headers = new Headers(res.headers);
+    headers.set('date', new Date(at).toUTCString());
+    if (!headers.has('x-github-request-id')) {
+      const h = createHash('sha256').update(`${at}:${request.method}:${request.url}:${answered++}`).digest('hex').toUpperCase();
+      headers.set('x-github-request-id', `${h.slice(0, 4)}:${h.slice(4, 9)}:${h.slice(9, 15)}:${h.slice(15, 21)}:${h.slice(21, 29)}`);
+    }
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+  }, { owners: inner.owners });
 }
 
-export function createGithubTwinServer(options: GithubTwinOptions): { port: number; stop: () => void } {
-  const server = Bun.serve({
+/** The GraphQL wire's requests, as the handler interface names them. */
+const GRAPHQL_OPERATION = { id: 'graphql', method: 'POST', path: '/graphql', class: 'action' };
+/** A git push, as the handler interface names it. */
+const GIT_OPERATION = { id: 'git-receive-pack', method: 'POST', path: '/{owner}/{repo}.git/git-receive-pack', class: 'action' };
+
+// The REST surface, with the path parameters GitHub lets hold slashes (manifest.ts `spanning`).
+const githubSurface = { ...surface, spanning };
+
+export async function createGithubTwinServer(options: GithubTwinOptions): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
     port: options.port ?? 0,
     idleTimeout: 60,
     fetch: createGithubTwinFetch(options),

package/src/github-shared.ts

@@ -1,7 +1,7 @@
 // GitHub SHARED helpers — pure shape functions both sides of the wire need: the twin's
 // mirror-state projection (server side, `github-mirror-state.ts`) and the mirror's React
 // client (`client/github-mirror.tsx`). Plain data in → plain data out; no state access,
-// no `@volter/twin`, no Bun/node imports — this module rides into the browser bundle
+// no `@volter/world-core`, no Bun/node imports — this module rides into the browser bundle
 // unchanged.
 
 /** The ONE named store the mirror renders from: `GET /twin/store/${GITHUB_MIRROR_STORE}`