@volter/twin-github 0.1.2 → 2.0.1

package/src/github-ui-conformance.ts

@@ -14,7 +14,7 @@
 // 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, type UiSurface, type UiCompletenessReport } from '@volter/twin-tooling';
+import { checkUiCompleteness, 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 const GITHUB_UI_INVENTORY: UiSurface[] = [
@@ -40,11 +40,10 @@ export const GITHUB_UI_INVENTORY: UiSurface[] = [
   { 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 is computed + emitted in the mirror store and now rendered in the
-  // conversation header alongside reviewCount + commentsCount.
+  // 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 + a Checks side-section.
+  // 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.
@@ -53,17 +52,17 @@ export const GITHUB_UI_INVENTORY: UiSurface[] = [
   // 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 renders them as chips in the Reviewers side-section.
+  // 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 conversation's Files-changed section (filename + status + +/- counts).
+  // 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 in the Aside snapshot counts. Undefined for observed-only PRs.
+  // 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 the conversation's Commits section (sha + message + author + date).
+  // 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' },
 

package/src/github-ui-structure.ts

@@ -1,7 +1,7 @@
 // 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 a state badge, the conversation pane has the
+// 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.
 //
@@ -11,9 +11,9 @@
 // inventory: the real React render.
 import { renderToStaticMarkup } from 'react-dom/server';
 import { createElement } from 'react';
-import { checkUiStructure, type UiStructureCheck, type UiStructureReport } from '@volter/twin-tooling';
+import { checkUiStructure, type UiStructureCheck, type UiStructureReport } from '@volter/world-tooling';
 import {
-  PrList, Conversation, Aside, IssuesTable, CiStatus, ActionsView, ReleasesView, DiscussionsView, DeploymentsView,
+  PrList, Conversation, Aside, FilesDiff, IssuesTable, CiStatus, ActionsView, ReleasesView, DiscussionsView, DeploymentsView,
   type PullRequest, type Issue, type Review, type Commit, type Comment, type ChangedFile,
   type WorkflowRun, type Job, type Release, type Discussion, type Deployment, type Environment,
 } from '../client/github-mirror.tsx';
@@ -47,7 +47,7 @@ const REVIEWS: Review[] = [{ repo: 'o/r', number: 1, reviewer: 'carol', state: '
 const COMMITS: Commit[] = [{ repo: 'o/r', number: 1, sha: 'abcdef1234567', message: 'do the thing', authorLogin: 'octocat', date: '2026-04-01T12:00:00Z' }];
 const COMMENTS: Comment[] = [{ repo: 'o/r', number: 1, author: 'dave', body: 'a note', createdAt: '2026-04-02T02:00:00Z' }];
 const REVIEW_COMMENTS: Comment[] = [{ repo: 'o/r', number: 1, author: 'erin', body: 'inline diff note', path: 'src/x.ts', createdAt: '2026-04-02T03:00:00Z' }];
-const FILES: ChangedFile[] = [{ repo: 'o/r', number: 1, filename: 'src/x.ts', status: 'modified', additions: 42, deletions: 7 }];
+const FILES: ChangedFile[] = [{ 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: WorkflowRun[] = [
@@ -109,6 +109,7 @@ export function renderGithubMirrorMarkup() {
     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 })),
@@ -125,12 +126,12 @@ export function githubUiStructureChecks(): UiStructureCheck[] {
     {
       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,
+      present: count(dom.prList, 'class="pr-row"') === 2,
     },
     {
-      key: 'pr-row-state-badge',
-      label: 'each PR row shows a state badge element (.state-badge)',
-      present: count(dom.prList, 'class="state-badge') >= 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',
@@ -139,38 +140,38 @@ export function githubUiStructureChecks(): UiStructureCheck[] {
     },
     {
       key: 'conversation-detail-pane',
-      label: 'the conversation/detail pane renders (section.conversation with a heading + state line)',
-      present: dom.conversation.includes('class="conversation"') && dom.conversation.includes('class="state-line"'),
+      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"'),
+      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"'),
+      present: dom.conversation.includes('class="review-card'),
     },
     {
-      key: 'conversation-files-changed',
-      label: 'the conversation pane has a files-changed section (.file-list with a .file-row)',
-      present: dom.conversation.includes('class="file-list"') && dom.conversation.includes('class="file-row"'),
+      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"'),
+      present: dom.aside.includes('<aside class="sidebar'),
     },
     {
       key: 'aside-reviewers-section',
       label: 'the Aside has a Reviewers section',
-      present: dom.aside.includes('<h3>Reviewers</h3>'),
+      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</h3>') && dom.aside.includes('<h3>Assignees</h3>') && dom.aside.includes('<h3>Milestone</h3>'),
+      present: dom.aside.includes('<h3>Labels<') && dom.aside.includes('<h3>Assignees<') && dom.aside.includes('<h3>Milestone<'),
     },
     {
       key: 'ci-status-element',

package/src/graphql-wire.ts

@@ -0,0 +1,115 @@
+// 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,
+  type DocumentNode,
+  type GraphQLFieldResolver,
+  type GraphQLSchema,
+} from 'graphql';
+
+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;
+};
+
+const snake = (s: string): string => s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+
+function connection(items: unknown[], args: Record<string, unknown>): Record<string, unknown> {
+  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: number): string => 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: unknown): Response {
+  return Response.json({ errors: [{ message: error instanceof GraphQLError ? error.message : String(error) }] });
+}
+
+export function createGraphqlWire(options: GraphqlWireOptions): (request: Request) => Promise<Response> {
+  let schema: GraphQLSchema | undefined;
+  const modeled = (type: string, field: string): boolean =>
+    field === '__typename' ||
+    `${type}.${field}` in options.resolvers ||
+    !!options.aliases?.[type]?.[field] ||
+    !!options.stored?.[type]?.includes(field) ||
+    !!options.stored?.[type]?.includes(snake(field));
+  const fieldResolver: GraphQLFieldResolver<unknown, GraphqlContext> = (source, args, context, info) => {
+    const own = options.resolvers[`${info.parentType.name}.${info.fieldName}`];
+    const obj = (source ?? {}) as Record<string, unknown>;
+    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(() => ({}))) as { query?: string; variables?: Record<string, unknown>; operationName?: string };
+    let document: DocumentNode;
+    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: { type: string; field: string } | undefined;
+    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/src/index.ts

@@ -11,7 +11,7 @@ export { handleGithubGitSmartHttp, parseGitSmartHttpPath, reconcileGitPlaneRefs
 export type { GitSmartHttpResponse, GitSmartHttpRoute } from './github-git-http.ts';
 export type { GithubComment, GithubIssue, GithubPr, GithubResponse, GithubReview, GithubState, GithubWriteEvent, GithubWriteOutcome } from './github-twin.ts';
 export { createGithubTwinFetch, createGithubTwinServer } from './github-server.ts';
-export { clearGithubWebhooks, emitGithubEvent, listGithubWebhooks, registerGithubWebhook } from './github-events.ts';
+export { emitGithubEvent } from './github-events.ts';
 export type { GithubWebhook, GithubWebhookDelivery } from './github-events.ts';
 // 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.
@@ -19,8 +19,8 @@ export { buildGithubMirrorClient, createGithubMirrorServer, githubMirrorHtml } f
 export { githubMirrorState } from './github-mirror-state.ts';
 export { GITHUB_MIRROR_STORE, GITHUB_MIRROR_STORE_PATH, GITHUB_WEB_ORIGIN, githubIssuePath, githubPullPath } from './github-shared.ts';
 export {
-  liveGithubExecute, observedPrsToResources, pullGithubPrs, pushGithubAction,
-  pushGithubToRemote, pushPendingGithubActions, syncGithubFromReal, syncGithubFromRemote,
+  githubPushExecutor, liveGithubExecute, observedPrsToResources, performGithubAction, pullGithubPrs, pushGithubAction,
+  syncGithubFromReal, syncGithubFromRemote,
 } from './github-connector.ts';
 export type { GithubExecute, LiveGithubOptions } from './github-connector.ts';
 // The client-side rate budget — the fail-closed backstop `liveGithubExecute` routes every live
@@ -43,10 +43,31 @@ export {
 export type { GithubBudgetErrorKind, GithubBudgetOptions, GithubBudgetReservation, GithubBudgetSnapshot } from './github-budget.ts';
 
 // Registry descriptor (#1).
-import type { TwinPack } from '@volter/twin';
+import type { TwinPack } from '@volter/world-core';
+import { registerPack } from '@volter/world-core';
 import { GITHUB_RATE_BUDGET as RATE_BUDGET } from './github-budget.ts';
+import { performGithubAction, syncGithubFromRemote } from './github-connector.ts';
 export const pack: TwinPack = {
   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'] as const).map((type) => ({
+    type, to: 'issue',
+    key: (f: Record<string, unknown>) => (f.repository === undefined || f.number === undefined ? undefined : `${String(f.repository)}#issue:${String(f.number)}`),
+    adopt: (_f: Record<string, unknown>, vendorId: string) => ({ 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,
@@ -56,10 +77,10 @@ export const pack: TwinPack = {
   transport: 'rest',
   archetype: 'engine-control',
   bin: 'world-github',
-  resources: ['pull_request', 'pull_request_review', 'pull_request_review_comment', 'issue', 'issue_comment'],
+  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 (TWIN-PACK-CONTRACT back-migration
+  // 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
@@ -85,5 +106,27 @@ export const pack: TwinPack = {
       'APPSMITHOAUTH2GITHUB',
     ],
   },
-  hosts: [{ host: 'api.github.com' }],
+  // 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)$' },
+    // the sign-in the consent and the other pages send a visitor who is not signed in to, and its two-factor step
+    // (src/screens/session.tsx); without these a browser following the redirect leaves the World
+    { host: 'github.com', pathPattern: '^/(login|session|sessions/two-factor(/app)?)$' },
+    { 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);