@volter/twin-github 0.1.0 → 0.1.1

package/README.md

@@ -4,26 +4,113 @@ The **GitHub twin** — a local replica of the GitHub **REST** pull-request API
 the shared [`@volter/twin`](../control-plane) kernel. The real `@octokit/rest` client
 works against it unmodified.
 
-> **Note:** local simulator/fork **writes** carry full content (a created PR has a
-> title/body/diffs). The connector's *pull* path currently folds observed events as
-> *metadata only* (counts/refs, `title: null`) — that is a **Planned** gap (full
-> content on pull), not an out-of-scope carve-out. The only deliberate GitHub
-> out-of-scope carve-out is actual repository **code/file contents** (see Coverage below).
+> **Note:** both planes carry content. Local simulator/fork **writes** carry full content
+> (a created PR has a title/body/diffs), and the connector's *pull* path folds the CONTENT
+> real GitHub returns — PR/issue title/body/state, review bodies, comment bodies, and the
+> inline diff findings. The only deliberate GitHub out-of-scope carve-out is bulk pull of
+> actual repository **code/file contents** (see Coverage below).
 
 ## Surface
 
 - **REST API** (`github-twin.ts`; HTTP wrapper `github-server.ts` →
   `createGithubTwinServer`): list/get PRs, issues, statuses/checks, milestones, and
-  **Actions** (workflows/runs/jobs; dispatch/rerun/cancel writes).
+  **Actions** (workflows/runs/jobs; dispatch/rerun/cancel writes), plus **Gists**
+  (create/edit/list/get/delete and comments).
 - **Writes** (`applyGithubWrite`): create PR, edit PR, submit review, issue comment
-  — local transactions (R3/R5/R18); the --read-only flag rejects writes.
+  — local transactions (R3/R5/R18); the --read-only flag rejects writes. A review or review
+  comment the twin authors is served with an author: the twin ledgers one caller identity
+  for a local write (`actor: { kind: 'agent' }`, which carries no login), so the login it
+  serves is the stable `twin` with `type: "User"` — the same name the jira twin gives a
+  local writer. A rehearsal reviewer's REAL login rides in the review or comment **body** by
+  convention; the twin invents no header for it and never guesses a human's account from an
+  unauthenticated write. (Making `review.user` reflect a genuinely *authenticated* actor is
+  still the open `github.pulls.review_actor_identity` todo.)
+- **Every review comment names its review.** Real GitHub wraps every inline comment in a
+  review, and so does the twin: a comment posted under a review (`POST .../pulls/:n/reviews`
+  with a `comments` array) carries that review's id, and a comment posted on its own carries
+  the PR's **implicit review** — one deterministic id per (repo, PR). It is synthesized on
+  `GET .../pulls/:n/reviews` *from the comments that name it* and never stored as a review of
+  its own; `_twin.review_count` counts it under exactly that condition, so the count and the
+  list describe one population (real GitHub serves the wrapper on `/reviews` and counts it
+  too). The point is that the join a consumer does (`pull_request_review_id` → the reviews
+  page) is live against the twin's own data; it used to be dead, because the twin answered
+  `pull_request_review_id: null` on every review comment it served. The wrapper's id band
+  (`0x80000000…`) separates it from the twin's own local-sequence and observed-hash id
+  spaces, and **that is all it does** — real GitHub's review ids reach that range too, so the
+  band is no argument about *vendor* ids. The invariant that actually holds is that a vendor
+  id is never a twin id: every pulled review and comment is rehashed before it is served, and
+  no review id is ever sent back out (a push addresses a vendor comment by the `external_id`
+  the pull recorded).
 - **Webhooks** (`github-events.ts`): `pull_request` / `pull_request_review` /
   `issue_comment` with the `X-GitHub-Event` header.
 - **Conformance** (`github-conformance.ts`): field-name subset vs the vendored
   GitHub REST PR schema (PR + nested base/head/repo; `_twin` extras excluded).
 - **UI mirror** (`github-mirror-ui.ts`): a GitHub-style PR browser (React) with a
-  per-repo selector ("multiple githubs"), over the twin's github world via
-  `/api/state`; observed review/comment counts are surfaced honestly.
+  per-repo selector ("multiple githubs"), a pure frontend (R3) — the shell + assets with
+  the twin's own fetch adapter mounted beside them. It reads the world through the twin's
+  store door `GET /twin/store/mirror` (the one named projection `github-mirror-state.ts`
+  builds server-side; observed review/comment counts are surfaced honestly), and any
+  console write goes through the REST API on the same origin. On that one host a document
+  navigation (`Accept: text/html`) is the console's deep link and everything else is the
+  vendor's wire; the git smart-HTTP plane is not carried there. Pure helpers both sides
+  share (the store path, the PR/issue route grammar) live in `github-shared.ts`.
+- **Connector** (`github-connector.ts`): the live-vendor lifecycle over an injected
+  octokit-like executor. `syncGithubFromReal` pulls a repo's PRs + issues and folds their
+  content; `pushPendingGithubActions` enacts local writes. Pull is **per-row conflict
+  tolerant**: if one 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 rather than aborting the whole repo's fold, so every other resource in
+  the same pull still folds. The result reports it — `{ observed, deltasAppended,
+  eventsAppended, issues, conflictsSkipped, conflictingIds }` — so a poller can log the
+  integrity problem loudly instead of it being swallowed. Every other append error stays fatal.
+  A PR's **conversation pulls as subjects, not as a summary**: each review is
+  `review` / `<owner/repo>#<n>:review:<reviewId>` (author login, human-or-bot, state, body,
+  submitted_at, commit_id, and the INLINE diff comments it wrapped — joined by each
+  `/pulls/{n}/comments` row's `pull_request_review_id`), and each issue comment is
+  `issue_comment` / `<owner/repo>#<n>:ic:<commentId>`. Two reviews between two polls are
+  therefore two deltas, and each is dated by the PROVIDER (a review by `submitted_at`, a
+  comment by `updated_at ?? created_at`), not by the poll clock. The PR keeps its own
+  summary fields, so a consumer reading only `pull_request` is unaffected. Budget: those
+  three per-PR reads are skipped for a PR whose `updated_at` has not moved since the last
+  observation (the stamp is read back from the shadow), so N unchanged PRs cost one list
+  call; an open-only pull also sweeps a bounded page (20) of recently-updated CLOSED PRs so
+  a merge is observed. All three conversation reads are PAGED at the vendor's maximum
+  (100/page, bounded at 10 pages), so a busy PR's 31st review, 31st finding or 31st issue
+  comment is observed rather than lost at a page boundary — the last of those is what
+  `commentCount` publishes, which used to report the truncated 30 as if it were the whole
+  conversation tab. `reviewCount` and `latestReview` are drawn from exactly one set —
+  reviews that are submitted and not `PENDING` — so a count and a verdict can never
+  describe different populations of the same PR.
+- **A review nobody showed us says so.** Two shapes of inline comment name no review this
+  pull can resolve, and NEITHER is dropped. A comment whose `pull_request_review_id` is
+  missing entirely (a row the vendor left unattached) rides one fixed bucket per PR,
+  `<owner/repo>#<n>:review:unattached`; a comment naming a review whose ROW never arrived (a
+  review deleted between the two reads, a page boundary) rides a subject keyed by that id.
+  Both carry `partial: true` and nothing else — no state, no author, no verdict, because
+  nobody showed us one. `partial` is what tells a consumer this is an unshown review rather
+  than one whose fields have not arrived yet, and neither is counted or eligible to be
+  `latestReview`.
+- **A finding is authored by whoever wrote it, not by the review that wraps it.** Every
+  inline comment carries its OWN `authorLogin`/`authorType`, read from that row's `user`:
+  a scanner App's finding inside a human's review reads as `bot`, a threaded reply reads as
+  its replier, and the unattached bucket's comments keep their authors although the bucket
+  itself has none. The wrapping review's author is the fallback only for a row that named
+  nobody (`user: null`); when neither names anyone, no author is served rather than a guess.
+- **`authorType` is a one-way signal.** `authorType: 'bot'` ⇒ a machine wrote it is
+  RELIABLE (only a GitHub App account is typed `Bot` or suffixed `[bot]`). The converse is
+  NOT: a GitHub App acting through a *user* token, a service/machine account, and an
+  Organization all come back typed `User` with an ordinary login, and a review by a deleted
+  account answers `user: null` (no login and no type at all). Gate on `bot`; never read
+  `user` as "a person did this".
+- **Push: a threaded reply is a reply.** A local `in_reply_to` write crosses on GitHub's own
+  reply route (`POST .../pulls/{n}/comments/{comment_id}/replies`), addressing the root by
+  the id the *vendor* gave it — resolved from what a pull observed, or from what an earlier
+  push in the same sweep returned. The connector NEVER forwards a twin-minted id to a real
+  account: a reply whose root has no known GitHub id is **refused**, ledgered in the push
+  result's `skipped` (action id, operation, reason) and left pending for a later sweep. That
+  per-action tolerance is the push-side twin of the pull's per-row conflict skip — one
+  refusal or one vendor rejection never aborts the other writes in the sweep, and nothing is
+  confirmed on a failure.
 
 ## CLI
 
@@ -35,14 +122,14 @@ world-github conformance [--root DIR]
 
 Point the real `@octokit/rest` `Octokit` at it via `baseUrl`.
 
-## Four ways to use it
+## Interaction surfaces
 
-1. **Mock SDK** — *zero edits (preferred):* `GITHUB_TWIN_URL=http://127.0.0.1:PORT node --require @volter/twin/inject your-app` redirects the real `@octokit/rest` from `api.github.com` to the twin. *Or* override directly: `new Octokit({ baseUrl: 'http://127.0.0.1:PORT', auth: 'twin' })`.
+1. **SDK/API** — *zero edits (preferred):* `GITHUB_TWIN_URL=http://127.0.0.1:PORT node --require @volter/twin/inject your-app` redirects the real `@octokit/rest` from `api.github.com` to the twin. *Or* override directly: `new Octokit({ baseUrl: 'http://127.0.0.1:PORT', auth: 'twin' })`.
 2. **API + CLI** — `world-github serve` (writable) + drive with `volter-twin status|plan|refs github`, then push.
 3. **Read-only** — `world-github serve --read-only`: unlimited local reads, no rate limits; writes refuse like GitHub (4xx).
 4. **UI mirror** — `world-github mirror` renders a GitHub-style view of the twin's state.
 
-(See the repo's GETTING-STARTED → "Four ways to use a twin", and `cookbook/zero-edit-inject`.)
+(See Getting Started → "Twin interaction surfaces", and `cookbook/zero-edit-inject`.)
 
 ## Coverage
 
@@ -53,8 +140,10 @@ done or carved out is a gap to close.
 **Done** — PRs (create/edit/merge/list/get; **full PR/issue content on pull** — title/body/state
 and review/comment bodies fold from real GitHub, plus full content on local writes), first-class
 issues (**pulled from real GitHub** via GET /issues, PRs excluded), **shared issue/PR number space**
-(one per-repo counter, real GitHub behavior), reviews + diff-anchored review comments, issue
-comments, commit statuses, check runs, requested reviewers, milestones, labels/assignees, PR
+(one per-repo counter, real GitHub behavior), reviews + diff-anchored review comments (write,
+list, and reply in a thread — `POST .../pulls/:n/comments/:cid/replies` inherits the root
+comment's anchor and answers with `in_reply_to_id`), issue comments, commit statuses,
+check runs, requested reviewers, milestones, labels/assignees, PR
 files/commits (local writes), **Actions** (workflows + workflow runs + jobs/steps — register/
 list/get workflows, workflow_dispatch → queued run, rerun/cancel transitions, run filters
 status/branch/event, run jobs; **rendered in the UI mirror** Actions view), **Actions
@@ -66,15 +155,68 @@ API** (refs create/get/update/delete, commits, trees, blobs *with content*, anno
 (create/update/delete + protection-rule summaries; **rendered in the UI mirror** Deployments
 view), **org repositories** (GET /orgs/:org/repos with type/sort filters), **issue pin/unpin**,
 pagination, webhooks, UI mirror (rung-5 ✅), connector (pull content+issues + push: create/edit/
-merge/review/comment/status/check/milestone/reviewers).
+merge/review/comment/status/check/milestone/reviewers), **Gists** (create/edit/list/get/delete +
+comments).
+
+**The REAL git plane (smart HTTP).** The twin is now *clonable and pushable by an unmodified
+`git` CLI*: per-repo **real bare repositories** live under the twin instance's state dir, and
+`GET /:owner/:repo/info/refs` + `POST .../git-upload-pack|git-receive-pack` bridge the wire to
+real `git upload-pack`/`receive-pack --stateless-rpc` subprocesses (git is its own reference
+implementation — see `src/github-git-plane.ts` / `src/github-git-http.ts`; supabase's
+real-engine doctrine applied to git). The Git Data REST endpoints are **re-backed by the same
+bare repos**: a REST blob/tree/commit/tag create writes a *real* git object (real sha, fetchable
+by ref), a `git push` folds its ref changes into the kernel log (visible to REST refs/branches,
+re-points open PR heads — GitHub's `synchronize` — and fires the `push` webhook through the
+existing pipeline). One object store, not two. Refs minted on shas no object backs (a legacy
+lenient surface some verifies pin) stay control-plane-only and are never advertised, so an
+advertised ref is always clonable. The fidelity oracle is the **real git CLI** —
+`src/github-git.integration.test.ts` clones, pushes, fetches REST-authored commits, and replays
+the OA loop's verified-api signing flow (`POST git/commits` + `PATCH git/refs/heads/:branch`).
+
+**SDLC control plane for merge gates** — commit statuses at a sha, check runs, branch
+protection that **persists** `required_status_checks` (contexts/strict) + `enforce_admins` and
+serves them back (`GET /branches/:b` summary with real `enforcement_level` semantics, `GET/PATCH
+.../protection/required_status_checks`, `POST/DELETE .../protection/enforce_admins`), PR reviews
+that **bind `commit_id` to the exact head sha at submission** (a later push moves the PR head,
+the review stays), and the GraphQL `repository.pullRequest(number)` fields `gh pr view --json`
+reads (headRefOid/state/baseRefName/statusCheckRollup/closingIssuesReferences/changedFiles/
+labels/body/comments/assignees/reviewRequests) — scoped to the exact calls this repo's own
+governance scripts make (human-approval-gate, break-glass-gate, agent-propose,
+finalize-agent-review, review-prerequisites), so the OA merge-gate logic can one day run
+hermetically against this twin.
 
 **Planned** (known-missing, will do) — **Projects v2**, **branch protection rulesets**,
-**orgs/teams/members** (membership), **issue types** (org-level) / **issue transfer**, the
-**GraphQL API** (only REST today), security (code-scanning/dependabot/secret-scanning),
-packages/pages/codespaces. (Actions **log bytes** stay out — CI-compute output, see Out of scope.)
+**orgs/teams/members** (membership), the rest of the
+**GraphQL API** (the modeled subset now includes the gh pr view merge-gate fields), security
+(code-scanning/dependabot/secret-scanning), packages/pages/codespaces, git-plane follow-ons
+(protection ENFORCED on receive-pack + PR merge, shallow/partial clone asserts, LFS, SSH
+transport). (Actions **log bytes** stay out — CI-compute output, see Out of scope.)
 
 **Out of scope** (deliberately not modeled, with reason) —
-- Actual repository **code / file contents** (git blob bytes, raw file bodies, packfiles): large
-  and redundant — the API *objects* (trees/blobs metadata, file lists, diff stats) are still covered.
+- ~~Actual repository code / file contents~~ **narrowed 2026-08-20**: the git plane now stores
+  REAL blob/tree/commit bytes for repos exercised through Git Data REST or `git push`. What
+  remains out of scope is bulk *pull* of a real remote repository's full object graph through
+  the connector (large + redundant for an evidence twin); the API objects AND locally-authored
+  bytes are covered.
 - Running real **CI compute** (executing Actions workflows): infra, not the API — the run/job
   *objects* are covered.
+
+## Rate budget — the fail-closed backstop on live calls
+
+`liveGithubExecute` is the **one place** this pack issues a live request, so every call it makes is charged
+against a persistent, fail-closed spend ledger **before** the request goes out. Past the ceiling, or
+while a `Retry-After`/429 cooldown is armed, it **throws instead of calling**. The ledger is keyed by
+vendor and a hash of the credential (limits are per credential, so it is deliberately *not*
+cwd-scoped) and persists across processes, so a fresh process does not get a fresh allowance; a
+corrupt ledger counts as a **full** window rather than zero spend. There is no option to disable it,
+and no value you can pass for `budget` that yields an unguarded client — an injected budget is
+validated by *method identity*, so a subclass or a `Proxy` that replaces `checkBudget` is refused.
+
+The declared numbers: **600 points / hour**, using GitHub's *own* published point scheme: a `GET`/`HEAD`/`OPTIONS` is 1 point. Bounded on every published axis at once — ≤12% of the 5,000 requests/hour primary limit; under the 900-points-per-**minute** secondary limit even if the whole hour were spent instantly. Writes are charged **8** rather than GitHub's own 5, the single departure from its table and a *tightening*: at 5 the hour-long window would admit 120 writes inside one minute, 1.5× the documented 80 content-generating requests/minute.
+
+The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/twin` →
+`control-plane/src/rateBudget.ts`); what lives here in [`src/github-budget.ts`](src/github-budget.ts) is this vendor's
+**declaration** (window, ceiling, per-endpoint weights, and a `reason` citing the limits above) plus
+the vendor-bound `GithubBudget`. The rule is ratified as
+[ARCHITECTURE.md](../../../ARCHITECTURE.md) **D8**, and the kernel module's header documents what the
+guard does *not* guarantee — read that before trusting it.

package/client/github-mirror.tsx

@@ -1,5 +1,6 @@
 import React, { useEffect, useMemo, useState } from "react";
 import { createRoot } from "react-dom/client";
+import { GITHUB_MIRROR_STORE_PATH, githubIssuePath, githubPullPath } from "../src/github-shared.ts";
 
 export type PullRequest = {
   repo: string;
@@ -220,7 +221,7 @@ type Payload = {
     insights?: RepoInsights[];
     settings?: RepoSettings[];
   };
-  fetchedAt: string;
+  fetchedAt?: string;
 };
 
 type ProjectCard = { id: number; title: string; contentType: string };
@@ -310,13 +311,15 @@ function pathFor(route: RouteState): string {
   // An opened PR/issue always routes to ITS OWN repo's path, regardless of the "all repos"
   // vs single-repo tab currently selected (mirrors real GitHub: /pulls can link out to any
   // repo's /owner/repo/pull/n).
+  // The route grammar is real GitHub's — the same one the twin's mirror store stamps on
+  // each PR/issue `url` (github-shared.ts), so a rendered link and the address bar agree.
   if (view === "pulls" && selectedKey) {
     const { repo: prRepo, number } = splitRepoScopedKey(selectedKey);
-    return `/${prRepo}/pull/${number}`;
+    return githubPullPath(prRepo, number);
   }
   if (view === "issues" && selectedIssueKey) {
     const { repo: issueRepo, number } = splitRepoScopedKey(selectedIssueKey);
-    return `/${issueRepo}/issues/${number}`;
+    return githubIssuePath(issueRepo, number);
   }
   if (repo === "all" || !repo) return `/${view}`;
   return `/${repo}/${view}`;
@@ -360,9 +363,12 @@ function App() {
   // to the same state) skips re-pushing the entry the browser just navigated to.
   const skipNextPush = React.useRef(false);
 
+  // The twin's store door (`GET /twin/store/mirror` — the ONE named projection the twin
+  // declares for this console) is the only read of twin state; it is the twin's own
+  // surface on this origin, never a mirror-private endpoint.
   async function refresh() {
     try {
-      const response = await fetch("/api/state");
+      const response = await fetch(GITHUB_MIRROR_STORE_PATH);
       const json = await response.json();
       if (!response.ok) throw new Error(json.error ?? "Failed to load GitHub state");
       setPayload(json);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-github",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local GitHub twin \u2014 PR-evidence REST; your real `@octokit/rest` talks to it unmodified. Mirror, simulate, and fork. Built on @volter/twin.",
   "keywords": [
     "twin",
@@ -54,7 +54,7 @@
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/twin": "0.1.0"
+    "@volter/twin": "0.1.1"
   },
   "devDependencies": {
     "@volter/twin": "0.1.0",

package/src/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { keepProcessAlive } from '@volter/twin/lifecycle';
 // world-github — the GitHub PR-evidence twin CLI (R14): serve | mirror | conformance.
 import { hasFlag, optionValue } from '@volter/twin/args';
 import { createGithubMirrorServer } from './github-mirror-ui.ts';
@@ -13,11 +14,11 @@ const readOnly = hasFlag(rest, "--read-only");
 if (cmd === 'serve') {
   const s = createGithubTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
   process.stdout.write(`github twin (GitHub REST) at http://127.0.0.1:${s.port}\n`);
-  await new Promise(() => {});
+  await keepProcessAlive();
 } else if (cmd === 'mirror') {
   const s = createGithubMirrorServer({ ...(root ? { root } : {}), ...(port ? { port } : {}) });
   process.stdout.write(`github mirror UI (PR evidence) at http://127.0.0.1:${s.port}\n`);
-  await new Promise(() => {});
+  await keepProcessAlive();
 } else if (cmd === 'conformance') {
   // dev-only; lazy so the bin runs without @volter/twin-tooling
   const {

package/src/github-a11y-snapshot.uitest.ts

@@ -0,0 +1,117 @@
+// GITHUB A11Y-CONGRUENCE MIRROR CAPTURE (TWIN-51 / H5, dev/01 + dev/02) — the mirror-capture
+// leg of the recorded-reality BONUS check. Captures a live body ariaSnapshot from the seeded
+// PR-list mirror, parses it, and asserts the parse produced a real, non-trivial tree
+// (harness-mechanics assertions — this file NEVER `expect()`s on congruence against the real
+// reference). Per the fidelity-without-recording doctrine, conformance is never counted from a
+// recording, and the a11y-congruence check is structurally bonus-only by design (see
+// packages/twin/tooling/src/a11ySnapshot.ts — `a11yBonusOutcome` is a hardcoded zero). Since
+// dev/02, a real-github reference fixture IS committed (see REFERENCE_PATH below), so this
+// file now diffs it against the mirror's own capture and PRINTS the report (console.log) on
+// every run; if the fixture were ever removed, it falls back to a loud advisory instead. This
+// is NOT a human-required file (unlike the tooling/** harness itself) and is NOT registered as
+// a ui-journeys.ts journey — it rides the existing github pack test sweep (twin-check.sh
+// [1/4]) like any other src/*.test.ts.
+//
+// dev/02 ADJUDICATION: the dev/01 tracker comment claimed dev/02 "requires a user-authorized
+// session." That premise is FALSE for this scenario — the reference is a repo-scoped PUBLIC
+// PR list (https://github.com/microsoft/vscode/pulls), reachable and capturable while fully
+// logged OUT (see scripts/capture/github-a11y.ts's no-auth default mode and
+// test-fixtures/github-a11y-reference.pr-list.SOURCE.md for the HTTP-200-logged-out proof).
+// No user step was needed.
+//
+// Skip convention copied from github-journey.uitest.ts:52-55 (loud console.warn, never a hard
+// fail on a browserless machine). Seed block copied verbatim from
+// github-journey.uitest.ts:58-86 (same PR-list scenario TWIN-47's pilot journey uses) so the
+// real-github reference recording (a DIFFERENT public repo/PR-list, not this mirror's fake
+// data — names are scrubbed and ignored by diffA11yShape anyway) is diffed against the SAME
+// seeded shape on the mirror side.
+import { describe, test, expect } from 'bun:test';
+import {
+  browserAvailable,
+  runUiJourney,
+  captureA11ySnapshot,
+  parseAriaSnapshot,
+  diffA11yShape,
+  renderCongruenceReport,
+} from '@volter/twin-tooling';
+import type { A11yNode } from '@volter/twin-tooling';
+import { applyGithubWrite } from './github-twin.ts';
+import { createGithubMirrorServer } from './github-mirror-ui.ts';
+
+// Committed real-github reference for the PR-list scenario (TWIN-51 dev/02 — captured
+// no-auth, logged out, from a public repo's PR list; see the SOURCE.md sibling next to the
+// fixture for full provenance).
+const REFERENCE_PATH = new URL('../test-fixtures/github-a11y-reference.pr-list.json', import.meta.url);
+
+describe('github a11y-congruence mirror capture (TWIN-51 / H5, dev/01 + dev/02)', () => {
+  test('captures + parses the mirror\'s body ariaSnapshot for the seeded PR-list scenario', async () => {
+    if (!(await browserAvailable())) {
+      console.warn('!! SKIP: github a11y-congruence capture — playwright chromium not installed on this machine (bunx playwright install chromium)');
+      return;
+    }
+
+    let captured: string | undefined;
+    let parsed: A11yNode | undefined;
+
+    await runUiJourney({
+      seed: async (root) => {
+        // Same PR-list seed as github-journey.uitest.ts:58-86 — real write path
+        // (applyGithubWrite), never hand-written events.jsonl.
+        await applyGithubWrite({
+          method: 'POST', path: '/repos/acme/twin-journey/pulls', root,
+          body: JSON.stringify({ title: 'Twin Journey Alpha PR', head: 'alpha', base: 'main', body: 'alpha-pr-body-marker' }),
+          occurredAt: '2026-05-01T00:00:00Z',
+        });
+        await applyGithubWrite({
+          method: 'POST', path: '/repos/acme/twin-journey/pulls', root,
+          body: JSON.stringify({ title: 'Twin Journey Beta PR', head: 'beta', base: 'main', body: 'beta-pr-body-marker' }),
+          occurredAt: '2026-05-02T00:00:00Z',
+        });
+        await applyGithubWrite({
+          method: 'POST', path: '/repos/acme/twin-journey/pulls/2/reviews', root,
+          body: JSON.stringify({ event: 'APPROVED', body: 'beta-review-body-marker' }),
+          occurredAt: '2026-05-02T01:00:00Z',
+        });
+        await applyGithubWrite({
+          method: 'POST', path: '/repos/acme/twin-journey/issues', root,
+          body: JSON.stringify({ title: 'Twin Journey Tracking Issue', body: 'tracking-issue-body-marker' }),
+          occurredAt: '2026-05-03T00:00:00Z',
+        });
+      },
+      serve: (root) => {
+        const server = createGithubMirrorServer({ root, port: 0 });
+        return { url: `http://127.0.0.1:${server.port}`, stop: () => server.stop() };
+      },
+      journey: async (page) => {
+        captured = await captureA11ySnapshot(page, 'body');
+        parsed = parseAriaSnapshot(captured);
+      },
+    });
+
+    // Harness-mechanics assertions ONLY — never congruence.
+    expect(captured).toBeDefined();
+    expect((captured ?? '').length).toBeGreaterThan(0);
+    expect(parsed).toBeDefined();
+    expect((parsed?.children.length ?? 0)).toBeGreaterThan(0);
+
+    const referenceFile = Bun.file(REFERENCE_PATH);
+    if (await referenceFile.exists()) {
+      // dev/02: a real-github reference is committed (no-auth capture, see the fixture's
+      // SOURCE.md). Diff + print the report — structural non-gating rule: NEVER expect() on
+      // congruence, only console.log it. The check's bonus-only-ness is enforced upstream in
+      // a11ySnapshot.ts (a11yBonusOutcome is a hardcoded zero), proven by a11ySnapshot.test.ts;
+      // this integration test only exercises the capture+diff+render plumbing end to end
+      // against the real reference. Divergences (e.g. real github wraps its PR list in an ARIA
+      // `group aria-label="Issues"` landmark the mirror's list-box has no equivalent for) are
+      // an HONEST, expected bonus signal, not a failure — never gates.
+      const reference = (await referenceFile.json()) as A11yNode;
+      const divergences = diffA11yShape(reference, parsed as A11yNode);
+      console.log(renderCongruenceReport(divergences, 'github PR-list (TWIN-51 dev/02)'));
+    } else {
+      // Fallback only — the reference IS committed as of dev/02. Kept in case it's ever
+      // regenerated/removed: no user-authorized session is required to redo the capture (see
+      // scripts/capture/github-a11y.ts's no-auth default mode).
+      console.warn('!! A11Y-CONGRUENCE (bonus-only, never gates): reference not committed — run scripts/capture/github-a11y.ts (no auth required, see its header) to record it.');
+    }
+  }, 30_000);
+});

package/src/github-budget.ts

@@ -0,0 +1,198 @@
+// GitHub's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveGithubExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/twin` → `rateBudget.ts`). Read that module's
+// header for the full rationale AND for the honest list of what the guard does not guarantee (an
+// injected clock or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not.
+//
+// ── HOW THE CEILING WAS CHOSEN: GITHUB'S OWN POINT SYSTEM ───────────────────────────────────
+// GitHub is the one vendor in this repo whose published scheme is ALREADY a weighted point budget,
+// so this declaration reproduces it rather than inventing a proxy for it. From
+// https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api (read 2026-07-26):
+//   • PRIMARY, per authenticated personal access token:  5,000 requests per HOUR
+//   • SECONDARY, points per minute:                        900 points per minute for REST endpoints
+//     — "most REST API GET, HEAD and OPTIONS requests"        = 1 point
+//     — "most REST API POST, PATCH, PUT or DELETE requests"   = 5 points
+//   • SECONDARY, concurrency:                              no more than 100 concurrent requests
+//   • SECONDARY, content creation:                          80 per minute and 500 per hour
+// The read weight IS GitHub's own number — 1 point. The write weight is deliberately DEARER than
+// GitHub's 5 (it is 8); see `GITHUB_CALL_WEIGHTS.write` for why that is what makes the
+// 80-content-creations-per-minute leg hold under an hour-long window. Nothing here is invented: the
+// only departure from the published table is in the tightening direction, and it is labelled.
+//
+// The window is an HOUR (the kernel's maximum, and the horizon of GitHub's primary limit) and the
+// ceiling is 600 points. That is bounded on BOTH published axes at once:
+//   • against the primary 5,000/hour: at most 600 requests can fit in 600 points, so ≤ 12% of it;
+//   • against the secondary 900 points/MINUTE: even spending the entire hour's allowance in a
+//     single instant is 600 points, still under 900 — the burst cannot breach it either;
+//   • against content creation (80/MINUTE and 500/hour): writes cost 8 rather than GitHub's own 5,
+//     because at 5 the hour-long window would admit 120 writes inside a single minute — 1.5x the
+//     80/minute leg. At 8, only 75 fit, so BOTH legs hold. See `GITHUB_CALL_WEIGHTS.write`.
+// A full PR pull of a busy repo is roughly 1 + 4 per PR ≈ 80 points for 20 PRs, so this admits
+// about seven complete pulls an hour — far more than an on-demand connector needs, and far below
+// the runaway shape.
+//
+// ⚠️ HONESTLY, ON THE COMPARISON WITH THE KERNEL FALLBACK. `DEFAULT_RATE_BUDGET` is 30 calls a
+// minute, i.e. 1,800 an hour sustained. This declaration is TIGHTER sustained (600/hour) but LOOSER
+// in a single minute — and that looseness is now BOUNDED AND ENFORCED rather than merely argued:
+// `burstCeiling` caps any 60-second sub-window at 300 points, which the kernel refuses against
+// independently of the hourly ceiling. 300 sits under both of GitHub's per-minute legs (the 900-
+// points/minute secondary limit, and 300/8 = 37 writes against the 80 content-generating requests
+// per minute), so the burst is inside the vendor's published contract by arithmetic, not by prose.
+// An hour-long window is the only way to bound GitHub's hourly PRIMARY limit at all; the burst bound
+// is what stops that from silently buying an instantaneous allowance nobody asked for.
+//
+// The window bounds spend, not PACE (the kernel refuses, it never sleeps — see its header). GitHub
+// also caps concurrency at 100, which a weighted ledger does not model at all; that is the caller's
+// job. The backstop for both is the cooldown, armed from `Retry-After` / a 403-or-429 /
+// `x-ratelimit-remaining: 0`.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/twin';
+
+const VENDOR = 'github';
+
+/** Rolling window, in ms. One HOUR — the horizon of GitHub's primary 5,000-requests limit. */
+export const GITHUB_BUDGET_WINDOW_MS = 60 * 60 * 1_000;
+
+/**
+ * Weighted POINTS allowed inside one window. 600 points/hour is ≤ 12% of the primary 5,000
+ * requests/hour AND stays under the secondary 900 points/minute even if spent all at once.
+ */
+export const GITHUB_BUDGET_CEILING = 600;
+
+/**
+ * Weighted points allowed in any 60-SECOND sub-window, enforced by the kernel independently of the
+ * hourly ceiling. Without it, an hour-long window admits its entire 600 points in one millisecond —
+ * twenty times what the austere fallback allows in a minute — and nothing in the kernel reached that
+ * (§9 round 2, 2026-07-26). 300 is deliberately HALF the hourly ceiling: a full PR pull of a busy
+ * repo is ~80 points and the largest realistic burst is well under it, while both of GitHub's
+ * per-minute legs are honoured with room to spare — 300 < the 900-points/minute secondary limit, and
+ * 300/8 = 37 writes < the 80 content-generating requests/minute.
+ */
+export const GITHUB_BUDGET_BURST_CEILING = 300;
+
+/** Seconds. A `Retry-After` above this means the token is throttled hard — fail loudly, don't sleep. */
+export const GITHUB_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** GitHub's OWN published point costs. Not a proxy for them — the numbers themselves. */
+export const GITHUB_CALL_WEIGHTS = {
+  /**
+   * GitHub's own table prices a `POST`/`PATCH`/`PUT`/`DELETE` at **5 points**. This charges **8**,
+   * and the extra 3 are not a re-transcription of the vendor — they are what makes the OTHER
+   * documented write limit hold. GitHub caps content creation at **80 per minute** as well as 500
+   * per hour, and with an hour-long window a 5-point price lets 600/5 = 120 writes land inside a
+   * single minute: 1.5x that 80. At 8 points only 75 fit, which is under it. (§9 finding,
+   * 2026-07-26: the declaration cited the 80/min limit in its own header and then checked only the
+   * hourly leg.) Reads are unaffected, and the ratio is still write-dearer-than-read as published.
+   */
+  write: 8,
+  /** "Most REST API GET, HEAD, and OPTIONS requests" — 1 point, per GitHub's own table. */
+  other: 1,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only GitHub-specific thing in the whole budget. */
+export const GITHUB_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: GITHUB_BUDGET_WINDOW_MS,
+  ceiling: GITHUB_BUDGET_CEILING,
+  burstCeiling: GITHUB_BUDGET_BURST_CEILING,
+  defaultWeight: GITHUB_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: GITHUB_BUDGET_MAX_RETRY_AFTER_S,
+  // Keyed by the octokit-style ROUTE (`"POST /repos/{owner}/{repo}/pulls"`), so the method is the
+  // first token and GitHub's own read/write split is expressible as one anchored rule.
+  rules: [
+    { match: '^(POST|PATCH|PUT|DELETE) ', weight: GITHUB_CALL_WEIGHTS.write },
+  ],
+  reason:
+    "GitHub's published scheme IS a weighted point budget, so these weights are its own numbers, not " +
+    'a proxy (docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api, read ' +
+    '2026-07-26): 5,000 requests/hour primary per PAT; secondary limits of 900 POINTS per minute ' +
+    'with GET/HEAD/OPTIONS = 1 point and POST/PATCH/PUT/DELETE = 5 points, 100 concurrent requests, ' +
+    'and 80 content-generating requests/minute / 500 per hour. 600 points per HOUR is bounded on ' +
+    'every axis at once: at most 600 requests fit in 600 points (≤12% of the 5,000/hour primary), and ' +
+    'spending the entire hour instantly is still 600 < the 900/minute secondary. Writes are charged 8 ' +
+    "rather than GitHub's own 5 — the only departure from its table, and a TIGHTENING: at 5 points the " +
+    'hour-long window would admit 120 writes inside one minute, 1.5x the documented 80/minute content-' +
+    'creation leg, while at 8 only 75 fit, so both the 80/minute and 500/hour legs hold. Versus the kernel fallback (30 ' +
+    'calls/min = 1,800/hour) this is TIGHTER sustained but LOOSER in one minute — and that looseness is ' +
+    'BOUNDED: burstCeiling caps any 60s sub-window at 300 points, which the kernel enforces separately, ' +
+    'and 300 sits under both per-minute legs (900 points/min, and 300/8 = 37 writes vs 80 content-' +
+    'generating requests/min). An hour-long window is the only way to bound ' +
+    "GitHub's hourly primary limit at all. It bounds spend, not pace, and does not model the " +
+    'concurrency cap; the Retry-After / 403-or-429 cooldown is the backstop for both.',
+};
+
+// Declared at module load, so merely importing this module (which `github-connector.ts` does) is
+// enough to arm the real ceiling. `RateBudget` reads its policy live precisely so this declaration
+// takes effect the moment it lands, and constructing through the subclass below (which imports this
+// module) is what makes the ordering a non-issue in practice.
+declareRateBudget(VENDOR, GITHUB_RATE_BUDGET);
+
+/**
+ * Price one call by its octokit-style ROUTE (`"GET /repos/{owner}/{repo}/pulls"`). The route, not
+ * the substituted path, is the key: it is what GitHub's docs name endpoints by, and it keeps the
+ * ledger's classification stable across owners and repos. A route nobody classified still costs
+ * `defaultWeight` — an unknown endpoint must never be free.
+ */
+export function githubCallWeight(route: string): number {
+  const at = route.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(route.slice(at + 1))) query[k] = v;
+  const raw = (at === -1 ? route : route.slice(0, at)).trim();
+  // NORMALIZED, because the method rule is otherwise trivially evaded (§9 finding, 2026-07-26):
+  // `fetch` upper-cases a known lowercase method before sending, so `'post /repos/…'` issues a real
+  // WRITE that a `^(POST|…) ` rule would price as a 1-point read; and a trailing slash makes a `$`
+  // anchor miss a route most routers treat as identical. Both are input variations, not attacks, and
+  // either one voids the read/write split that IS GitHub's own published point scheme.
+  const sp = raw.indexOf(' ');
+  const method = (sp === -1 ? raw : raw.slice(0, sp)).toUpperCase();
+  const path = sp === -1 ? '' : raw.slice(sp + 1);
+  const bare = path.length > 1 && path.endsWith('/') ? path.replace(/\/+$/, '') : path;
+  return rateBudgetWeight(VENDOR, bare === '' ? method : `${method} ${bare}`, query);
+}
+
+/** Where GitHub's ledger lives. Token-keyed and cwd-independent by default (the primary limit is
+ *  per token, so a cwd-scoped ledger would hand the same PAT a fresh allowance in every checkout,
+ *  worktree and CI matrix leg — precisely the shape a matrix build has); pass `root` to opt into
+ *  world-scoped accounting instead. */
+export function githubBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger to
+  // another vendor's file.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for GitHub's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type GithubBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * GitHub's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof GithubBudget` in `liveGithubExecute` means "a budget that
+ * accounts against GITHUB's ledger under GITHUB's ceiling": another vendor's `RateBudget` (with its
+ * own, possibly larger, ceiling) is NOT assignable there.
+ */
+export class GithubBudget extends RateBudget {
+  constructor(opts: GithubBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as GithubBudgetError } from '@volter/twin';
+export type { RateBudgetErrorKind as GithubBudgetErrorKind } from '@volter/twin';
+export type GithubBudgetReservation = RateBudgetReservation;
+export type GithubBudgetSnapshot = RateBudgetSnapshot;