@volter/twin-github 0.1.1 → 2.0.0

package/dist/src/github-ui-conformance.d.ts

@@ -0,0 +1,4 @@
+import { type UiSurface, type UiCompletenessReport } from '@volter/world-tooling';
+/** What real GitHub shows on the PR list, PR conversation, and issues list — classified vs the twin. */
+export declare const GITHUB_UI_INVENTORY: UiSurface[];
+export declare function githubUiConformance(): UiCompletenessReport;

package/dist/src/github-ui-conformance.js

@@ -0,0 +1,105 @@
+// GitHub UI conformance (RUNG-5) — the declared UI surface inventory for a GitHub
+// pull-request / issue view, classified against THIS twin, and the read-only
+// completeness check over it.
+//
+// Honesty: `status` is the current truth, kept honest by github-ui-conformance.test.ts,
+// which cross-checks every 'rendered' claim against the actual mirror (the bundled
+// client + the `mirror` store payload). `rendered` = the UI mirror shows it today;
+// `modeled` = the twin has the data but the mirror doesn't render it (a UI gap to
+// close); `unmodeled` = real GitHub shows it but the EVIDENCE twin doesn't model it
+// (a twin-model gap). The github world is an evidence mirror — OBSERVED PRs carry
+// metadata + review/comment COUNTS but never titles, bodies, authors, diffs, or
+// per-commit/per-file content. LOCAL simulator/fork writes, however, DO carry content,
+// including per-file diffs, per-commit detail, and additions/deletions line counts —
+// so those are MODELED features and the mirror renders them (empty for observed-only
+// PRs, preserving honesty). What stays 'unmodeled' is what the twin models for NEITHER
+// observed nor local writes: PR author identity and the head branch NAME.
+import { checkUiCompleteness } from '@volter/world-tooling';
+/** What real GitHub shows on the PR list, PR conversation, and issues list — classified vs the twin. */
+export const GITHUB_UI_INVENTORY = [
+    // --- rendered: the mirror truly shows these today (proven in the test) ---
+    { key: 'prNumber', label: 'PR number (#123)', status: 'rendered' },
+    { key: 'title', label: 'PR title', status: 'rendered' },
+    { key: 'body', label: 'PR description / body', status: 'rendered' },
+    { key: 'stateBadge', label: 'State / merge badge (open/closed/merged)', status: 'rendered' },
+    { key: 'labels', label: 'Labels', status: 'rendered' },
+    { key: 'assignees', label: 'Assignees', status: 'rendered' },
+    { key: 'reviewers', label: 'Reviewers (state + login)', status: 'rendered' },
+    { key: 'reviewContent', label: 'Review submissions (body + state)', status: 'rendered' },
+    { key: 'comments', label: 'Issue comments / conversation', status: 'rendered' },
+    { key: 'reviewComments', label: 'Review (diff-thread) comments', status: 'rendered' },
+    { key: 'changedFilesCount', label: 'Changed-files count', status: 'rendered' },
+    { key: 'commitsCount', label: 'Commits count', status: 'rendered' },
+    { key: 'reviewCount', label: 'Review count', status: 'rendered' },
+    { key: 'commentsCount', label: 'Comment count', status: 'rendered' },
+    { key: 'baseBranch', label: 'Base branch ref', status: 'rendered' },
+    { key: 'headSha', label: 'Head commit sha', status: 'rendered' },
+    { key: 'mergeCommit', label: 'Merge commit sha', status: 'rendered' },
+    { key: 'mergedAt', label: 'Merged timestamp', status: 'rendered' },
+    { key: 'prUrl', label: 'Link to PR on GitHub', status: 'rendered' },
+    { key: 'issuesList', label: 'Issues list (first-class issues view)', status: 'rendered' },
+    { key: 'repoSelector', label: 'Per-repo selector (repo grouping)', status: 'rendered' },
+    // reviewCommentsCount counts into the pull request's Conversation tab, with its comments and reviews.
+    { key: 'reviewCommentsCount', label: 'Review-comment (diff-thread) count', status: 'rendered' },
+    // CI rollup (commit statuses + check-runs) over the PR head_sha — the twin now models
+    // statuses[]/checkRuns[]; the mirror renders a ✓/✗/● indicator, the merge box's checks and a Checks tab.
+    { key: 'checksStatus', label: 'CI / status checks', status: 'rendered' },
+    // milestone: the twin models milestone NUMBER + state.milestones; the mirror renders
+    // the milestone title as a badge on PR/issue rows + a Milestone side-section.
+    { key: 'milestone', label: 'Milestone', status: 'rendered' },
+    // linked PRs/issues: the twin models issue.linked[]; the mirror renders typed
+    // cross-reference links on the issue rows.
+    { key: 'linkedIssues', label: 'Linked / source issue', status: 'rendered' },
+    // requested reviewers (distinct from submitted reviews): the twin models
+    // requested_reviewers[]; the mirror lists them, awaiting review, in the Reviewers sidebar section.
+    { key: 'requestedReviewers', label: 'Requested reviewers', status: 'rendered' },
+    // per-file diffs: the twin models pr.files (GithubPullFile) on LOCAL writes; the mirror
+    // renders the Files changed tab (each file's path, +/- counts and unified diff).
+    // Empty for observed-only PRs (no per-file evidence) — honesty preserved.
+    { key: 'filesChangedContent', label: 'Per-file diff list (filenames + status + counts)', status: 'rendered' },
+    // additions/deletions: the twin rolls these up from the carried file list on LOCAL writes;
+    // the mirror renders them as the pull request's diffstat. Undefined for observed-only PRs.
+    { key: 'diffStats', label: 'Additions / deletions line counts', status: 'rendered' },
+    // per-commit detail: the twin models pr.commits_list (GithubPullCommit) on LOCAL writes;
+    // the mirror renders them in the timeline and the Commits tab (sha + message + author + date).
+    // Empty for observed-only PRs (only a commit COUNT is observed) — honesty preserved.
+    { key: 'commitsContent', label: 'Per-commit list (sha + message + author)', status: 'rendered' },
+    // --- Actions (workflows + runs + jobs) — a LOCAL construct (running real CI is the only
+    //     Actions non-goal; the run/job OBJECTS are modeled + rendered in the Actions view) ---
+    // the Actions tab lists workflow runs; each run row carries a status/conclusion badge.
+    { key: 'actionsRunsList', label: 'Workflow runs list (Actions view)', status: 'rendered' },
+    // the run badge reflects status (queued/in_progress/completed) + conclusion (success/
+    // failure/cancelled), rendered as a glyph + label on every run row + the detail header.
+    { key: 'runStatusBadge', label: 'Run status / conclusion badge', status: 'rendered' },
+    // selecting a run renders a detail pane with its jobs + each job's steps.
+    { key: 'runJobs', label: 'Run detail — jobs + steps', status: 'rendered' },
+    // --- Releases (workflows of the repo's release channel) — a LOCAL construct (no observed
+    //     release evidence; release ASSET binary BYTES are the only Releases non-goal) ---
+    // the Releases tab lists releases; each row carries tag + name + draft/prerelease badge.
+    { key: 'releasesList', label: 'Releases list (Releases view)', status: 'rendered' },
+    // the channel badge reflects draft / prerelease / published, rendered on every row + header.
+    { key: 'releaseChannelBadge', label: 'Release channel badge (draft/prerelease/release)', status: 'rendered' },
+    // selecting a release renders a detail pane with its notes + ASSET catalog (metadata only).
+    { key: 'releaseAssets', label: 'Release detail — asset catalog (name/type/size)', status: 'rendered' },
+    // --- Discussions (a LOCAL construct; modeled over REST — a declared deviation from
+    //     GitHub's GraphQL Discussions API. No observed discussion evidence) ---
+    // the Discussions tab lists discussions; each row carries title + category + answer badge.
+    { key: 'discussionsList', label: 'Discussions list (Discussions view)', status: 'rendered' },
+    // the category chip reflects the discussion's category (Q&A categories are answerable).
+    { key: 'discussionCategory', label: 'Discussion category chip (General/Q&A/…)', status: 'rendered' },
+    // an answerable (Q&A) discussion shows an answered/unanswered badge.
+    { key: 'discussionAnswerStatus', label: 'Discussion answered/unanswered status (Q&A)', status: 'rendered' },
+    // selecting a discussion renders a detail pane with the opening post + the comment/reply
+    // thread, highlighting the accepted answer.
+    { key: 'discussionThread', label: 'Discussion detail — comment/reply thread + accepted answer', status: 'rendered' },
+    // --- unmodeled: real GitHub shows it, the evidence twin models it for neither
+    //     observed nor local writes (a genuine twin-model gap) ---
+    // The twin never carries author identity on a PR (observed evidence has only repo/number/
+    // counts; local writes don't capture the acting login into the PR object either).
+    { key: 'author', label: 'PR author (login + avatar)', status: 'unmodeled' },
+    // The twin tracks base_ref + head_sha but not the head branch NAME (only the head sha).
+    { key: 'headBranch', label: 'Head branch ref name', status: 'unmodeled' },
+];
+export function githubUiConformance() {
+    return checkUiCompleteness('github', GITHUB_UI_INVENTORY);
+}

package/dist/src/github-ui-structure.d.ts

@@ -0,0 +1,18 @@
+import { type UiStructureCheck, type UiStructureReport } from '@volter/world-tooling';
+/** Render the exported presentational components to static HTML, once, deterministically. */
+export declare function renderGithubMirrorMarkup(): {
+    prList: string;
+    conversation: string;
+    aside: string;
+    files: string;
+    issues: string;
+    ciStatus: string;
+    actions: string;
+    releases: string;
+    discussions: string;
+    deployments: string;
+};
+/** The structural checklist: each `present` is derived from the rendered markup above. */
+export declare function githubUiStructureChecks(): UiStructureCheck[];
+/** RUNG-5 structural DOM report for the GitHub mirror. Read-only, deterministic. */
+export declare function githubUiStructure(): UiStructureReport;

package/dist/src/github-ui-structure.js

@@ -0,0 +1,251 @@
+// RUNG-5 STRUCTURAL DOM CHECKLIST for the GitHub mirror — the PROXIMITY half of the
+// UI rung. Completeness asks "does the mirror show the data?"; this asks "does the
+// mirror's rendered DOM look structurally like the real GitHub UI?" — the PR table
+// emits a row per PR, each row carries its state icon, the conversation pane has the
+// reviews/comments timeline, the Aside carries the reviewers/labels/assignees/milestone
+// sections, a CI status element renders, the issues view emits a row per issue.
+//
+// Each check's `present` is computed from the ACTUAL markup produced by
+// renderToStaticMarkup of the EXPORTED mirror components with seeded props — so a check
+// cannot pass unless the component truly emits that landmark. Not the bundle, not the
+// inventory: the real React render.
+import { renderToStaticMarkup } from 'react-dom/server';
+import { createElement } from 'react';
+import { checkUiStructure } from '@volter/world-tooling';
+import { PrList, Conversation, Aside, FilesDiff, IssuesTable, CiStatus, ActionsView, ReleasesView, DiscussionsView, DeploymentsView, } from "../client/github-mirror.js";
+// ── Seeded props: one rich PR (reviews/comments/labels/assignees/CI/milestone/files)
+//    plus a second PR so the list has more than one row, and one issue. ───────────────
+const PR = {
+    repo: 'o/r', number: 1, title: 'Add feature', body: 'why this PR', state: 'open',
+    author: 'octocat', baseBranch: 'main', headBranch: 'feat', headSha: 'abcdef1234567',
+    createdAt: '2026-04-01T00:00:00Z', updatedAt: '2026-04-02T00:00:00Z',
+    additions: 42, deletions: 7, changedFiles: 2, commitsCount: 3,
+    commentsCount: 1, reviewCount: 1, reviewCommentsCount: 1,
+    labels: [{ name: 'bug' }, { name: 'enhancement' }],
+    assignees: ['alice'], requestedReviewers: ['carol'], milestone: 'v1.0',
+    ciStatus: 'success',
+};
+const PR_TWO = {
+    repo: 'o/r', number: 2, title: 'Fix bug', state: 'open', author: 'hubot',
+    createdAt: '2026-03-01T00:00:00Z', updatedAt: '2026-03-02T00:00:00Z', ciStatus: 'failure',
+};
+const ISSUE = {
+    repo: 'o/web', number: 1, title: 'An issue', state: 'open',
+    createdAt: '2026-04-04T00:00:00Z', updatedAt: '2026-04-04T00:00:00Z',
+    labels: [{ name: 'triage' }], assignees: ['bob'], milestone: 'v1.0',
+};
+const ISSUE_TWO = {
+    repo: 'o/web', number: 2, title: 'Another issue', state: 'closed',
+    createdAt: '2026-04-05T00:00:00Z', updatedAt: '2026-04-05T00:00:00Z',
+};
+const REVIEWS = [{ repo: 'o/r', number: 1, reviewer: 'carol', state: 'approved', body: 'looks good', submittedAt: '2026-04-02T01:00:00Z' }];
+const COMMITS = [{ repo: 'o/r', number: 1, sha: 'abcdef1234567', message: 'do the thing', authorLogin: 'octocat', date: '2026-04-01T12:00:00Z' }];
+const COMMENTS = [{ repo: 'o/r', number: 1, author: 'dave', body: 'a note', createdAt: '2026-04-02T02:00:00Z' }];
+const REVIEW_COMMENTS = [{ repo: 'o/r', number: 1, author: 'erin', body: 'inline diff note', path: 'src/x.ts', createdAt: '2026-04-02T03:00:00Z' }];
+const FILES = [{ repo: 'o/r', number: 1, filename: 'src/x.ts', status: 'modified', additions: 1, deletions: 1, patch: '@@ -1,2 +1,2 @@\n-old line\n+new line\n context' }];
+// Actions: two runs (one completed/success, one cancelled) so the runs list has >1 row, plus
+// a job (with steps) for the first run so the run-detail jobs section renders.
+const RUNS = [
+    { repo: 'o/r', id: 101, workflowId: 1, workflowName: 'CI', runNumber: 1, event: 'workflow_dispatch', status: 'completed', conclusion: 'success', headSha: 'abcdef1234567', headBranch: 'main', jobCount: 1, url: 'https://github.com/o/r/actions/runs/101' },
+    { repo: 'o/r', id: 102, workflowId: 1, workflowName: 'CI', runNumber: 2, event: 'workflow_dispatch', status: 'completed', conclusion: 'cancelled', headSha: 'abcdef7654321', headBranch: 'dev', jobCount: 0 },
+];
+const JOBS = [{ repo: 'o/r', id: 201, runId: 101, name: 'build', status: 'completed', conclusion: 'success', steps: [{ name: 'set up job', status: 'completed', conclusion: 'success', number: 1 }] }];
+// Releases: two releases (one published with an asset, one draft) so the list has >1 row and
+// the detail pane renders the asset catalog (metadata only — bytes are the Non-goal).
+const RELEASES = [
+    { repo: 'o/r', id: 1, tagName: 'v1.0.0', name: 'First release', body: 'the notes', draft: false, prerelease: false, publishedAt: '2026-04-10T00:00:00Z', targetCommitish: 'main', url: 'https://github.com/o/r/releases/tag/v1.0.0', assets: [{ id: 11, name: 'app.zip', contentType: 'application/zip', size: 2048, downloadCount: 3 }] },
+    { repo: 'o/r', id: 2, tagName: 'v1.1.0-rc1', name: 'RC', draft: true, prerelease: true, createdAt: '2026-04-11T00:00:00Z', targetCommitish: 'main', assets: [] },
+];
+// Discussions: two discussions (one answerable Q&A with a chosen answer + a reply, one
+// General) so the list has >1 row and the detail pane renders the comment thread + the
+// accepted-answer landmark.
+const DISCUSSIONS = [
+    {
+        repo: 'o/r', number: 1, title: 'How do I configure X?', body: 'I am stuck on X.', state: 'open',
+        categorySlug: 'q-a', categoryName: 'Q&A', categoryEmoji: '🙏', isAnswerable: true,
+        answerCommentId: 101, isAnswered: true, commentsCount: 2, updatedAt: '2026-04-12T00:00:00Z',
+        url: 'https://github.com/o/r/discussions/1',
+        comments: [
+            { id: 101, parentId: null, body: 'Do it this way.', isAnswer: true, createdAt: '2026-04-12T01:00:00Z' },
+            { id: 102, parentId: 101, body: 'Thanks, that worked!', isAnswer: false, createdAt: '2026-04-12T02:00:00Z' },
+        ],
+    },
+    {
+        repo: 'o/r', number: 2, title: 'Welcome!', body: 'Say hi here.', state: 'open',
+        categorySlug: 'general', categoryName: 'General', categoryEmoji: '💬', isAnswerable: false,
+        answerCommentId: null, isAnswered: false, commentsCount: 0, updatedAt: '2026-04-13T00:00:00Z', comments: [],
+    },
+];
+// Deployments: two deployments (one success in production, one pending in staging) so the
+// list has >1 row, plus two environments (one protected with a wait timer + reviewers, one
+// unprotected) so the environments list renders with a protection summary.
+const DEPLOYMENTS = [
+    { repo: 'o/r', id: 1, ref: 'main', sha: 'abcdef1234567', environment: 'production', task: 'deploy', description: 'release v1', production: true, state: 'success', environmentUrl: 'https://app.example.com', createdAt: '2026-04-10T00:00:00Z', statuses: [{ id: 2, state: 'success' }, { id: 1, state: 'in_progress' }] },
+    { repo: 'o/r', id: 2, ref: 'dev', sha: 'fedcba7654321', environment: 'staging', task: 'deploy', state: 'pending', createdAt: '2026-04-11T00:00:00Z', statuses: [] },
+];
+const ENVIRONMENTS = [
+    { repo: 'o/r', name: 'production', waitTimer: 30, reviewers: ['alice', 'bob'], protected: true },
+    { repo: 'o/r', name: 'staging', reviewers: [], protected: false },
+];
+/** Count non-overlapping occurrences of a substring in `html`. */
+function count(html, marker) {
+    if (!marker)
+        return 0;
+    let n = 0;
+    let i = html.indexOf(marker);
+    while (i !== -1) {
+        n += 1;
+        i = html.indexOf(marker, i + marker.length);
+    }
+    return n;
+}
+/** Render the exported presentational components to static HTML, once, deterministically. */
+export function renderGithubMirrorMarkup() {
+    return {
+        prList: renderToStaticMarkup(createElement(PrList, { prs: [PR, PR_TWO], reviews: REVIEWS, selectedKey: 'o/r#1' })),
+        conversation: renderToStaticMarkup(createElement(Conversation, { pr: PR, reviews: REVIEWS, commits: COMMITS, comments: COMMENTS, reviewComments: REVIEW_COMMENTS, files: FILES })),
+        aside: renderToStaticMarkup(createElement(Aside, { pr: PR, reviews: REVIEWS, commits: COMMITS, files: FILES })),
+        files: renderToStaticMarkup(createElement(FilesDiff, { files: FILES })),
+        issues: renderToStaticMarkup(createElement(IssuesTable, { issues: [ISSUE, ISSUE_TWO] })),
+        ciStatus: renderToStaticMarkup(createElement(CiStatus, { status: 'success' })),
+        actions: renderToStaticMarkup(createElement(ActionsView, { runs: RUNS, jobs: JOBS, selectedRunId: 101 })),
+        releases: renderToStaticMarkup(createElement(ReleasesView, { releases: RELEASES, selectedReleaseId: 1 })),
+        discussions: renderToStaticMarkup(createElement(DiscussionsView, { discussions: DISCUSSIONS, selectedKey: 'o/r#1' })),
+        deployments: renderToStaticMarkup(createElement(DeploymentsView, { deployments: DEPLOYMENTS, environments: ENVIRONMENTS })),
+    };
+}
+/** The structural checklist: each `present` is derived from the rendered markup above. */
+export function githubUiStructureChecks() {
+    const dom = renderGithubMirrorMarkup();
+    return [
+        {
+            key: 'pr-list-row-per-pr',
+            label: 'the PR list emits a row (.pr-row) per pull request',
+            present: count(dom.prList, 'class="pr-row"') === 2,
+        },
+        {
+            key: 'pr-row-state-icon',
+            label: 'each PR row shows its open/merged/closed state icon (.pr-state-icon)',
+            present: count(dom.prList, 'class="pr-state-icon') === 2,
+        },
+        {
+            key: 'pr-row-ci-status',
+            label: 'a PR row renders a CI status indicator (.ci-status)',
+            present: dom.prList.includes('class="ci-status'),
+        },
+        {
+            key: 'conversation-detail-pane',
+            label: 'the conversation pane renders (section.conversation with the merge box)',
+            present: dom.conversation.includes('class="conversation') && dom.conversation.includes('class="gh-mergebox"'),
+        },
+        {
+            key: 'conversation-comments-timeline',
+            label: 'the conversation pane has a comments timeline (.timeline-item with a .comment)',
+            present: dom.conversation.includes('class="timeline-item') && dom.conversation.includes('class="comment'),
+        },
+        {
+            key: 'conversation-reviews-section',
+            label: 'the conversation pane has a reviews section (.review-card)',
+            present: dom.conversation.includes('class="review-card'),
+        },
+        {
+            key: 'files-changed-diff',
+            label: 'the Files changed tab renders each file with its diff rows (.gh-file with .gh-diff-add and .gh-diff-del)',
+            present: dom.files.includes('class="diff-file gh-file"') && dom.files.includes('class="gh-diff-add"') && dom.files.includes('class="gh-diff-del"'),
+        },
+        {
+            key: 'aside-sidebar',
+            label: 'the detail Aside renders as a sidebar landmark (aside.sidebar)',
+            present: dom.aside.includes('<aside class="sidebar'),
+        },
+        {
+            key: 'aside-reviewers-section',
+            label: 'the Aside has a Reviewers section',
+            present: dom.aside.includes('<h3>Reviewers<'),
+        },
+        {
+            key: 'aside-labels-assignees-milestone',
+            label: 'the Aside has Labels, Assignees and Milestone sections',
+            present: dom.aside.includes('<h3>Labels<') && dom.aside.includes('<h3>Assignees<') && dom.aside.includes('<h3>Milestone<'),
+        },
+        {
+            key: 'ci-status-element',
+            label: 'the CI status component renders a labelled status element (.ci-status.success)',
+            present: dom.ciStatus.includes('class="ci-status success"') && dom.ciStatus.includes('title="checks: success"'),
+        },
+        {
+            key: 'issues-row-per-issue',
+            label: 'the issues view emits a row (.issue-row) per issue',
+            present: count(dom.issues, 'issue-row') === 2,
+        },
+        {
+            key: 'actions-run-row-per-run',
+            label: 'the Actions view emits a run row (.run-row) per workflow run',
+            present: count(dom.actions, 'class="run-row') === 2,
+        },
+        {
+            key: 'actions-run-status-badge',
+            label: 'each run row shows a run status/conclusion badge (.run-badge)',
+            present: count(dom.actions, 'class="run-badge') >= 2,
+        },
+        {
+            key: 'actions-run-detail-jobs',
+            label: 'the run detail pane renders a jobs section (.job-list with a .job-row + .step-row)',
+            present: dom.actions.includes('class="job-list"') && dom.actions.includes('class="job-row"') && dom.actions.includes('class="step-row"'),
+        },
+        {
+            key: 'releases-row-per-release',
+            label: 'the Releases view emits a release row (.release-row) per release',
+            present: count(dom.releases, 'class="release-row') === 2,
+        },
+        {
+            key: 'releases-channel-badge',
+            label: 'each release row shows a draft/prerelease/release channel badge (.release-badge)',
+            present: count(dom.releases, 'class="release-badge') >= 2,
+        },
+        {
+            key: 'releases-detail-assets',
+            label: 'the release detail pane renders an asset catalog (.asset-list with an .asset-row)',
+            present: dom.releases.includes('class="asset-list"') && dom.releases.includes('class="asset-row"'),
+        },
+        {
+            key: 'discussions-row-per-discussion',
+            label: 'the Discussions view emits a discussion row (.discussion-row) per discussion',
+            present: count(dom.discussions, 'class="discussion-row') === 2,
+        },
+        {
+            key: 'discussions-category-badge',
+            label: 'each discussion row shows a category chip (.discussion-category)',
+            present: count(dom.discussions, 'class="discussion-category') >= 2,
+        },
+        {
+            key: 'discussions-answer-badge',
+            label: 'an answerable discussion shows an answered/unanswered badge (.answer-badge)',
+            present: dom.discussions.includes('class="answer-badge'),
+        },
+        {
+            key: 'discussions-detail-thread',
+            label: 'the discussion detail pane renders a comment thread (.comment-thread with a .thread-comment) + the accepted answer (.accepted-answer)',
+            present: dom.discussions.includes('class="comment-thread"') && dom.discussions.includes('class="thread-comment') && dom.discussions.includes('class="comment accepted-answer"'),
+        },
+        {
+            key: 'deployments-row-per-deployment',
+            label: 'the Deployments view emits a deployment row (.deployment-row) per deployment',
+            present: count(dom.deployments, 'class="deployment-row') === 2,
+        },
+        {
+            key: 'deployments-state-badge',
+            label: 'each deployment row shows a state badge (.deployment-state)',
+            present: count(dom.deployments, 'class="deployment-state') >= 2,
+        },
+        {
+            key: 'deployments-environments-list',
+            label: 'the Deployments view renders an environments list (.environments-list with an .environment-row + a protection summary)',
+            present: dom.deployments.includes('class="environments-list"') && dom.deployments.includes('class="environment-row"') && dom.deployments.includes('class="environment-protected'),
+        },
+    ];
+}
+/** RUNG-5 structural DOM report for the GitHub mirror. Read-only, deterministic. */
+export function githubUiStructure() {
+    return checkUiStructure('github', githubUiStructureChecks());
+}

package/dist/src/graphql-wire.d.ts

@@ -0,0 +1,22 @@
+export type GraphqlContext = Record<string, unknown> & {
+    request: Request;
+};
+export type FieldResolver = (source: Record<string, unknown>, args: Record<string, unknown>, context: GraphqlContext) => unknown;
+export type GraphqlWireOptions = {
+    /** the vendor's schema, loaded on the first GraphQL request */
+    loadSdl: () => Promise<string>;
+    /** resolvers by `Type.field` (`Query.repository`, `PullRequest.state`) */
+    resolvers: Record<string, FieldResolver>;
+    /** per type, a GraphQL field name → the stored field that holds it (`nameWithOwner` → `full_name`) */
+    aliases?: Record<string, Record<string, string>>;
+    /** per type, the stored fields the default resolver may read as they are */
+    stored?: Record<string, string[]>;
+    /** what every resolver of one request receives beside the request (a pack's handler interface) */
+    context: (request: Request) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /** the answer to a query that selects a field nothing models: the first such field and its type */
+    unmodeled: (field: {
+        type: string;
+        field: string;
+    }) => Response;
+};
+export declare function createGraphqlWire(options: GraphqlWireOptions): (request: Request) => Promise<Response>;

package/dist/src/graphql-wire.js

@@ -0,0 +1,89 @@
+// THE GRAPHQL WIRE — a vendor's GraphQL API served from its published schema over the pack's state
+// (docs/contributing/architecture.md, "Protocol 3"). A query is parsed and validated against
+// the vendor's own schema, so an unknown field is the GraphQL error the vendor gives. A field
+// resolves from its resolver when the pack writes one, else from the stored object: the field's own
+// name, its snake_case form, or the pack's alias for it. A list answering a `...Connection` field is
+// wrapped as a Relay connection, and an enum resolves case-insensitively. The wire takes a query
+// only when every field it selects is modeled; any other query is answered by the pack's `unmodeled`,
+// naming the first field nothing models. An error a resolver raises carries its `extensions.type` as
+// the error's `type`, as GitHub's GraphQL errors do.
+// Nothing here knows a vendor. It needs the `graphql` protocol library, which the kernel may not
+// carry, so it lives beside the packs that use it.
+import { execute, getNamedType, GraphQLError, isEnumType, isObjectType, parse, TypeInfo, validate, visit, visitWithTypeInfo, buildSchema, } from 'graphql';
+const snake = (s) => s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+function connection(items, args) {
+    const first = typeof args.first === 'number' ? args.first : undefined;
+    const last = typeof args.last === 'number' ? args.last : undefined;
+    const after = typeof args.after === 'string' ? Number(atob(args.after)) + 1 : 0;
+    let slice = items.slice(after);
+    if (first !== undefined)
+        slice = slice.slice(0, first);
+    if (last !== undefined)
+        slice = slice.slice(-last);
+    const start = after + (last !== undefined ? Math.max(0, items.slice(after).length - last) : 0);
+    const cursor = (i) => btoa(String(start + i));
+    return {
+        totalCount: items.length,
+        nodes: slice,
+        edges: slice.map((node, i) => ({ node, cursor: cursor(i) })),
+        pageInfo: { hasNextPage: start + slice.length < items.length, hasPreviousPage: start > 0, startCursor: slice.length ? cursor(0) : null, endCursor: slice.length ? cursor(slice.length - 1) : null },
+    };
+}
+/** A query GitHub cannot parse: its syntax error, as GraphQL answers it. */
+function syntaxError(error) {
+    return Response.json({ errors: [{ message: error instanceof GraphQLError ? error.message : String(error) }] });
+}
+export function createGraphqlWire(options) {
+    let schema;
+    const modeled = (type, field) => field === '__typename' ||
+        `${type}.${field}` in options.resolvers ||
+        !!options.aliases?.[type]?.[field] ||
+        !!options.stored?.[type]?.includes(field) ||
+        !!options.stored?.[type]?.includes(snake(field));
+    const fieldResolver = (source, args, context, info) => {
+        const own = options.resolvers[`${info.parentType.name}.${info.fieldName}`];
+        const obj = (source ?? {});
+        let value = own ? own(obj, args, context) : (obj[options.aliases?.[info.parentType.name]?.[info.fieldName] ?? info.fieldName] ?? obj[snake(info.fieldName)] ?? null);
+        const named = getNamedType(info.returnType);
+        if (Array.isArray(value) && isObjectType(named) && named.name.endsWith('Connection'))
+            value = connection(value, args);
+        if (typeof value === 'string' && isEnumType(named))
+            value = named.getValues().find((v) => v.name.toLowerCase() === value.toString().toLowerCase())?.name ?? value;
+        return value;
+    };
+    return async (request) => {
+        schema ??= buildSchema(await options.loadSdl(), { assumeValidSDL: true });
+        const payload = (await request.clone().json().catch(() => ({})));
+        let document;
+        try {
+            document = parse(payload.query ?? '');
+        }
+        catch (error) {
+            return syntaxError(error);
+        }
+        const invalid = validate(schema, document);
+        if (invalid.length)
+            return Response.json({ errors: invalid.map((e) => ({ message: e.message, locations: e.locations })) });
+        // every selected field modeled, or the existing resolver answers
+        const typeInfo = new TypeInfo(schema);
+        let unmodeled;
+        visit(document, visitWithTypeInfo(typeInfo, {
+            Field(node) {
+                const parent = typeInfo.getParentType();
+                if (!unmodeled && parent && isObjectType(parent) && !parent.name.endsWith('Connection') && !parent.name.endsWith('Edge') && parent.name !== 'PageInfo' && !modeled(parent.name, node.name.value))
+                    unmodeled = { type: parent.name, field: node.name.value };
+            },
+        }));
+        if (unmodeled)
+            return options.unmodeled(unmodeled);
+        const result = await execute({
+            schema,
+            document,
+            variableValues: payload.variables ?? {},
+            ...(payload.operationName ? { operationName: payload.operationName } : {}),
+            contextValue: { ...(await options.context(request)), request },
+            fieldResolver,
+        });
+        return Response.json({ ...(result.data !== undefined ? { data: result.data } : {}), ...(result.errors?.length ? { errors: result.errors.map((e) => ({ ...(typeof e.extensions?.type === 'string' ? { type: e.extensions.type } : {}), message: e.message, path: e.path })) } : {}) });
+    };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,17 @@
+export { applyGithubWrite, githubState, handleGithubRequest, syncPrHeadsToBranchTip, toGithubComment, toGithubIssue, toGithubRest, toGithubReview, toGithubReviewComment } from './github-twin.js';
+export { bareRepoDir, ensureBareRepo, hasBareRepo, listGitPlaneRefs, objectExistsInPlane, readGitBlobFromPlane, readGitCommitFromPlane, readGitTagFromPlane, readGitTreeFromPlane, updateGitRefInPlane, writeGitBlobToPlane, writeGitCommitToPlane, writeGitTagToPlane, writeGitTreeToPlane, } from './github-git-plane.js';
+export { handleGithubGitSmartHttp, parseGitSmartHttpPath, reconcileGitPlaneRefs } from './github-git-http.js';
+export type { GitSmartHttpResponse, GitSmartHttpRoute } from './github-git-http.js';
+export type { GithubComment, GithubIssue, GithubPr, GithubResponse, GithubReview, GithubState, GithubWriteEvent, GithubWriteOutcome } from './github-twin.js';
+export { createGithubTwinFetch, createGithubTwinServer } from './github-server.js';
+export { emitGithubEvent } from './github-events.js';
+export type { GithubWebhook, GithubWebhookDelivery } from './github-events.js';
+export { buildGithubMirrorClient, createGithubMirrorServer, githubMirrorHtml } from './github-mirror-ui.js';
+export { githubMirrorState } from './github-mirror-state.js';
+export { GITHUB_MIRROR_STORE, GITHUB_MIRROR_STORE_PATH, GITHUB_WEB_ORIGIN, githubIssuePath, githubPullPath } from './github-shared.js';
+export { githubPushExecutor, liveGithubExecute, observedPrsToResources, performGithubAction, pullGithubPrs, pushGithubAction, syncGithubFromReal, syncGithubFromRemote, } from './github-connector.js';
+export type { GithubExecute, LiveGithubOptions } from './github-connector.js';
+export { GITHUB_BUDGET_BURST_CEILING, GITHUB_BUDGET_CEILING, GITHUB_BUDGET_MAX_RETRY_AFTER_S, GITHUB_BUDGET_WINDOW_MS, GITHUB_CALL_WEIGHTS, GITHUB_RATE_BUDGET, GithubBudget, GithubBudgetError, githubBudgetPath, githubCallWeight, } from './github-budget.js';
+export type { GithubBudgetErrorKind, GithubBudgetOptions, GithubBudgetReservation, GithubBudgetSnapshot } from './github-budget.js';
+import type { TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,101 @@
+// @volter/twin-github — the GitHub PR-evidence twin (REST), on @volter/twin.
+export { applyGithubWrite, githubState, handleGithubRequest, syncPrHeadsToBranchTip, toGithubComment, toGithubIssue, toGithubRest, toGithubReview, toGithubReviewComment } from "./github-twin.js";
+// The REAL git plane: bare repos under the twin's state dir + the git smart-HTTP protocol
+// (clone/fetch/push by an unmodified `git` CLI), reconciled with the Git Data REST surface.
+export { bareRepoDir, ensureBareRepo, hasBareRepo, listGitPlaneRefs, objectExistsInPlane, readGitBlobFromPlane, readGitCommitFromPlane, readGitTagFromPlane, readGitTreeFromPlane, updateGitRefInPlane, writeGitBlobToPlane, writeGitCommitToPlane, writeGitTagToPlane, writeGitTreeToPlane, } from "./github-git-plane.js";
+export { handleGithubGitSmartHttp, parseGitSmartHttpPath, reconcileGitPlaneRefs } from "./github-git-http.js";
+export { createGithubTwinFetch, createGithubTwinServer } from "./github-server.js";
+export { emitGithubEvent } from "./github-events.js";
+// The mirror is a pure frontend (R3): shell + assets + the mounted adapter. Its state comes
+// from the twin's store door, whose projection lives server-side in github-mirror-state.ts.
+export { buildGithubMirrorClient, createGithubMirrorServer, githubMirrorHtml } from "./github-mirror-ui.js";
+export { githubMirrorState } from "./github-mirror-state.js";
+export { GITHUB_MIRROR_STORE, GITHUB_MIRROR_STORE_PATH, GITHUB_WEB_ORIGIN, githubIssuePath, githubPullPath } from "./github-shared.js";
+export { githubPushExecutor, liveGithubExecute, observedPrsToResources, performGithubAction, pullGithubPrs, pushGithubAction, syncGithubFromReal, syncGithubFromRemote, } from "./github-connector.js";
+// The client-side rate budget — the fail-closed backstop `liveGithubExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is GitHub's DECLARATION — and uniquely, its weights ARE GitHub's own published point costs
+// (1 for a read, 5 for a write). Exported so an operator can inspect spend (`snapshot`) and so a
+// caller can catch `GithubBudgetError` by type; there is deliberately no export that disables it.
+export { GITHUB_BUDGET_BURST_CEILING, GITHUB_BUDGET_CEILING, GITHUB_BUDGET_MAX_RETRY_AFTER_S, GITHUB_BUDGET_WINDOW_MS, GITHUB_CALL_WEIGHTS, GITHUB_RATE_BUDGET, GithubBudget, GithubBudgetError, githubBudgetPath, githubCallWeight, } from "./github-budget.js";
+import { registerPack } from '@volter/world-core';
+import { GITHUB_RATE_BUDGET as RATE_BUDGET } from "./github-budget.js";
+import { performGithubAction, syncGithubFromRemote } from "./github-connector.js";
+export const pack = {
+    vendor: 'github',
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+    // the real state system: perform one entry against GitHub, refresh the root from it.
+    protocol: '2',
+    refresh: { every: '5m', webhook: true, onDemand: { atMost: '30s' } },
+    stateSystem: { perform: performGithubAction, refresh: syncGithubFromRemote },
+    roundTrip: { method: 'POST', path: '/repos/acme/web/issues', body: { title: 'round trip' }, headers: { authorization: 'token round-trip' } },
+    // docs/contributing/architecture.md#alias-aware-lookup-at-the-request-boundary: a comment and a review name their issue or PR by `repository` + `number`
+    // (an issue and a PR share the `owner/repo#issue:number` id space); when the head adopts GitHub's
+    // number for the parent, the kernel resolves these before the comment is performed.
+    // shape parity refreshes the twin from itself: github's refresh needs the repo on its origin
+    parityOrigin: 'http://twin/repos/acme/web',
+    shapeParity: 'held',
+    referenceTrip: { method: 'POST', path: '/repos/acme/web/issues/{{number}}/comments', body: { body: 'a comment on the round trip' }, headers: { authorization: 'token round-trip' } },
+    references: ['issue_comment', 'review'].map((type) => ({
+        type, to: 'issue',
+        key: (f) => (f.repository === undefined || f.number === undefined ? undefined : `${String(f.repository)}#issue:${String(f.number)}`),
+        adopt: (_f, vendorId) => ({ number: Number(vendorId.split('#issue:').pop()) }),
+    })),
+    engine: { module: 'github-git-plane', note: 'real bare repositories: git objects live in the plane, the tree references them by sha' },
+    // The SAME object github-budget.ts declares at module load — one source of truth, so registering
+    // the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    pullPosture: 'continuous',
+    pullPostureReason: "GitHub REST is 5000 req/hour authenticated with X-RateLimit-* headers on every response, so a scheduled sync can measure its own headroom.",
+    transport: 'rest',
+    archetype: 'engine-control',
+    bin: 'world-github',
+    resources: ['pull_request', 'pull_request_review', 'pull_request_review_comment', 'issue', 'issue_comment', 'repository', 'branch', 'git_ref'],
+    specSource: 'test-fixtures/github-pull-schema.json (full GitHub OpenAPI PR schema)',
+    description: 'GitHub PR-evidence REST twin — writes, webhooks, UI mirror.',
+    // Adoption + interception, all in the pack's one home (descriptor-first back-migration, adding-a-twin.md §3,
+    // 2026-08-31; the eight SDK names, the `@octokit/` scope and the bare `github`/`gh` stems moved
+    // off the central maps unchanged). The two canonical Octokit clients plus the official
+    // auth/webhook companions — each battery-observed as a repo's ONLY GitHub dep — and the whole
+    // `@octokit/` scope so an unlisted satellite still detects. Stems: the bare GITHUB_*/GH_* pair
+    // and the credential-var shapes real apps use for their GitHub App / OAuth App connections
+    // (BACKEND_GITHUB_*, INF_APP_CONNECTION_GITHUB_APP_*, …_GITHUB_OAUTH_*, …_GITHUB_RADAR_APP_*).
+    adoption: {
+        // COMMUNITY: GitHub ships no official Python SDK (octokit is JS, go-github is Go), and `PyGithub`
+        // is the de-facto Python client of the same REST API.
+        pypi: ['pygithub'],
+        sdks: [
+            '@octokit/rest', '@octokit/core', 'octokit',
+            '@octokit/auth-app', '@octokit/auth-oauth-app', '@octokit/auth-oauth-device',
+            '@octokit/graphql', '@octokit/webhooks',
+        ],
+        scopes: ['@octokit/'],
+        envStems: [
+            'GITHUB', 'GH',
+            'BACKENDGITHUB', 'INFAPPCONNECTIONGITHUBAPP',
+            'INFAPPCONNECTIONGITHUBOAUTH', 'INFAPPCONNECTIONGITHUBRADARAPP',
+            // appsmith names its GitHub OAuth app APPSMITH_OAUTH2_GITHUB_CLIENT_ID/_SECRET — the same
+            // app-prefixed shape as the INFAPPCONNECTION* stems above (ladder classification 2026-09-02).
+            'APPSMITHOAUTH2GITHUB',
+        ],
+    },
+    // The REST API, and on github.com git's smart-HTTP paths (github-git-http.ts serves them: an unmodified
+    // `git clone https://github.com/o/r.git` lands in the twin) and the OAuth web flow (src/screens/oauth.tsx: an
+    // application's unmodified sign-in with GitHub), a GitHub App's installation page (src/screens/app-installation.tsx), the
+    // page that registers an app from its manifest (src/screens/app-manifest.tsx) and GitHub Packages' npm registry (src/npm-registry.ts), where `npm publish` lands;
+    // and on uploads.github.com a release asset's upload.
+    // Every other github.com page stays the real site's.
+    hosts: [
+        { host: 'api.github.com' },
+        // a release's upload_url: its assets are uploaded here (docs.github.com/rest/releases/assets#upload-a-release-asset)
+        { host: 'uploads.github.com', pathPattern: '^/repos/[^/]+/[^/]+/releases/\\d+/assets$' },
+        { host: 'github.com', pathPattern: '^/[^/]+/[^/]+/(info/refs|git-upload-pack|git-receive-pack)$' },
+        { host: 'github.com', pathPattern: '^/login/oauth/(authorize|access_token)$' },
+        { host: 'github.com', pathPattern: '^/apps/[^/]+/installations/new$' },
+        { host: 'github.com', pathPattern: '^/(organizations/[^/]+/)?settings/apps/new$' },
+        { host: 'npm.pkg.github.com', pathPattern: '^/@' },
+    ],
+};
+// PROTOCOL 2: the pack registers itself on load — its rate budget and its state system (the head
+// resolves `stateSystemFor(vendor)` in the process that serves the twin).
+registerPack(pack);