@volter/twin-github 0.1.1 → 2.0.0

package/src/manifest.ts

@@ -0,0 +1,605 @@
+// GitHub's manifest: the vendor facts its published description does not carry, and the resources
+// the derived core serves (docs/contributing/architecture.md, "Protocol 3"). The surfaces are
+// generated (./generated/surface.gen.json for REST, ./generated/graphql.gen.json for GraphQL, from
+// ../spec by scripts/derive-pack.ts).
+import type { DerivedManifest } from '@volter/world-core';
+import { callerLogin, GITHUB_WORLD_USER } from './github-twin.ts';
+
+/** Path parameters whose values GitHub lets hold slashes, which its OpenAPI description does not say:
+ *  a git ref (`heads/feature/x`, https://docs.github.com/rest/git/refs#get-a-reference), a file path
+ *  (https://docs.github.com/rest/repos/contents#get-repository-content), a release tag, a branch name
+ *  (https://docs.github.com/rest/branches/branches#get-a-branch), a label name, and a compare range
+ *  (`base...head` where either is a branch). The surface's `spanning` list (github-server.ts). */
+export const spanning = ['ref', 'path', 'tag', 'branch', 'name', 'basehead'];
+
+/** A resource that lives in a repository: named by `{owner}/{repo}` and stored with that value in its
+ *  `repository` field. Its `key`, where one is declared, is the subject id the twin mints for it from the
+ *  path (locally created subjects; an observed one keeps the id it was observed under). The core serves
+ *  none of these operations: the repository itself is stored under a sequence id (`repo:<n>`), so the
+ *  core's parent check, which looks the parent up by subject id, can never find `{owner}/{repo}`; and
+ *  every stored shape is the twin's (githubState folds and renames), not the answer. Handlers serve them. */
+// a repository is stored as repo:<n> with its owner and name, and addressed by both
+const inRepository = { params: ['owner', 'repo'], value: '{owner}/{repo}', field: 'repository', resource: 'full-repository', where: { owner: '{owner}', name: '{repo}' } };
+
+export const manifest: DerivedManifest = {
+  vendor: 'github',
+  service: 'github',
+  // GitHub reads a body as JSON whatever its content type says (curl's default is a form type)
+  body: { json: 'always' },
+  ids: { template: '{n}' },
+  time: 'iso',
+  error: { message: '{message}', documentation_url: 'https://docs.github.com/rest', status: '{statusText}' },
+  readOnly: { status: 403, message: 'twin is read-only (mirror mode); start in simulator/fork to write' },
+  notFound: { status: 404, message: 'Not Found' },
+  list: {
+    style: 'envelope',
+    envelope: '{data}',
+    limit: { param: 'per_page', default: 30, max: 100 },
+    page: { param: 'page', link: true },
+  },
+  deleted: null,
+  // a token minted at the twin's user door names its user; the World's shared token names no one
+  identity: (authorization, root) => callerLogin((authorization ?? '').replace(/^(?:bearer|token)\s+/i, '').trim() || undefined, root) ?? GITHUB_WORLD_USER,
+  // Operations on a declared resource the core must not claim: GitHub's stored subjects are the twin's
+  // own shape (a sequence id such as `sshkey:3`, fields folded by githubState), not the vendor's, so
+  // the core reproduces none of them; each is a handler, or unserved (the vendor's Not Found).
+  unmodeled: [
+    'actions/delete-environment-variable',
+    'actions/delete-workflow-run',
+    'actions/disable-workflow',
+    'actions/enable-workflow',
+    'actions/get-environment-variable',
+    'actions/get-workflow-run-attempt',
+    'actions/list-environment-variables',
+    'actions/list-jobs-for-workflow-run-attempt',
+    'actions/list-repo-organization-secrets',
+    'actions/list-repo-organization-variables',
+    'actions/list-workflow-run-artifacts',
+    'activity/mark-thread-as-done',
+    'agents/delete-org-secret',
+    'agents/delete-org-variable',
+    'agents/delete-repo-secret',
+    'agents/delete-repo-variable',
+    'agents/get-org-secret',
+    'agents/get-org-variable',
+    'agents/get-repo-secret',
+    'agents/get-repo-variable',
+    'agents/list-org-secrets',
+    'agents/list-org-variables',
+    'agents/list-repo-organization-secrets',
+    'agents/list-repo-organization-variables',
+    'agents/list-repo-secrets',
+    'agents/list-repo-variables',
+    'apps/delete-installation',
+    'apps/get-org-installation',
+    'apps/get-repo-installation',
+    'apps/get-user-installation',
+    'apps/list-installations-for-authenticated-user',
+    'codespaces/create-with-repo-for-authenticated-user',
+    'codespaces/get-codespaces-for-user-in-org',
+    'codespaces/list-in-organization',
+    'codespaces/list-in-repository-for-authenticated-user',
+    'codespaces/update-for-authenticated-user',
+    'gists/list-for-user',
+    'gists/list-forks',
+    'gists/list-public',
+    'gists/list-starred',
+    'git/list-matching-refs',
+    'issues/add-blocked-by-dependency',
+    'issues/delete-milestone',
+    'issues/get-parent',
+    'issues/list',
+    'issues/list-comments-for-repo',
+    'issues/list-dependencies-blocked-by',
+    'issues/list-dependencies-blocking',
+    'issues/list-for-authenticated-user',
+    'issues/list-for-org',
+    'issues/list-labels-for-milestone',
+    'issues/remove-dependency-blocked-by',
+    'orgs/delete',
+    'orgs/get-membership-for-authenticated-user',
+    'orgs/list-app-installations',
+    'orgs/list-invitation-teams',
+    'orgs/list-memberships-for-authenticated-user',
+    'orgs/update-membership-for-authenticated-user',
+    'packages/delete-package-for-org',
+    'packages/delete-package-for-user',
+    'packages/delete-package-version-for-org',
+    'packages/delete-package-version-for-user',
+    'packages/get-all-package-versions-for-package-owned-by-org',
+    'packages/get-all-package-versions-for-package-owned-by-user',
+    'packages/get-package-for-organization',
+    'packages/get-package-for-user',
+    'packages/get-package-version-for-organization',
+    'packages/get-package-version-for-user',
+    'packages/list-docker-migration-conflicting-packages-for-authenticated-user',
+    'packages/list-docker-migration-conflicting-packages-for-organization',
+    'packages/list-docker-migration-conflicting-packages-for-user',
+    'packages/list-packages-for-organization',
+    'packages/list-packages-for-user',
+    'projects/add-field-for-org',
+    'projects/add-field-for-user',
+    'projects/delete-item-for-org',
+    'projects/delete-item-for-user',
+    'projects/get-field-for-org',
+    'projects/get-field-for-user',
+    'projects/get-for-user',
+    'projects/get-org-item',
+    'projects/get-user-item',
+    'projects/list-fields-for-org',
+    'projects/list-fields-for-user',
+    'projects/list-for-user',
+    'projects/list-items-for-org',
+    'projects/list-items-for-user',
+    'projects/list-view-items-for-org',
+    'projects/list-view-items-for-user',
+    'projects/update-item-for-org',
+    'projects/update-item-for-user',
+    'pulls/delete-pending-review',
+    'pulls/list-review-comments-for-repo',
+    'reactions/create-for-commit-comment',
+    'reactions/create-for-release',
+    'reactions/list-for-commit-comment',
+    'reactions/list-for-release',
+    'repos/add-team-access-restrictions',
+    'repos/create-org-ruleset',
+    'repos/delete-deployment',
+    'repos/delete-org-ruleset',
+    'repos/delete-release-asset',
+    'repos/get-access-restrictions',
+    'repos/get-org-rule-suite',
+    'repos/get-org-ruleset',
+    'repos/get-org-rulesets',
+    'repos/get-teams-with-access-to-protected-branch',
+    'repos/list-issue-types',
+    'repos/list-teams',
+    'repos/update-org-ruleset',
+    'repos/update-release-asset',
+    'teams/check-permissions-for-repo-legacy',
+    'teams/delete-legacy',
+    'teams/get-legacy',
+    'teams/list-child-in-org',
+    'teams/list-child-legacy',
+    'teams/list-for-authenticated-user',
+    'teams/remove-repo-legacy',
+    'teams/update-legacy',
+    'users/list-gpg-keys-for-user',
+  ],
+  // Every declared resource's served operations are handlers (semantics/); the declarations name the
+  // stored type and rule on the spec's state candidates.
+  // The screens applications and people reach (docs/contributing/architecture.md, "Screens"). Demand is the
+  // ladder's 85 applications: the code that sends a user to the page.
+  screens: [
+    {
+      id: 'sign-in', kind: 'flow', host: 'github.com', path: '/login', status: 'done',
+      demand: 'every github.com page a person reaches: each asks who is signed in', controls: ['Username or email address', 'Password', 'Sign in'],
+      source: 'https://docs.github.com/authentication/keeping-your-account-and-data-secure/about-authentication-to-github',
+    },
+    {
+      id: 'two-factor', kind: 'flow', host: 'github.com', path: '/sessions/two-factor/app', status: 'done',
+      demand: 'every person with two-factor authentication signing in, as GitHub requires of contributors', controls: ['Authentication code', 'Verify'],
+      source: 'https://docs.github.com/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication',
+    },
+    {
+      id: 'oauth-consent', kind: 'flow', host: 'github.com', path: '/login/oauth/authorize', status: 'done',
+      demand: '35 of 85 applications sign users in with GitHub', controls: ['Authorize {login}', 'Cancel'],
+      source: 'https://docs.github.com/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps',
+    },
+    {
+      id: 'app-installation', kind: 'flow', host: 'github.com', path: '/apps/{slug}/installations/new', status: 'done',
+      demand: '10 of 85 applications send an owner to install their GitHub App', controls: ['Install', 'Install & Authorize', 'Cancel', 'All repositories', 'Only select repositories', 'Switch account'],
+      source: 'https://docs.github.com/apps/using-github-apps/installing-a-github-app-from-a-third-party',
+    },
+    {
+      id: 'pull-requests', kind: 'workspace', host: 'github.com', path: '/{owner}/{repo}/pulls', status: 'done',
+      demand: 'testers and agents review pull requests', source: 'https://docs.github.com/pull-requests',
+    },
+  ],
+  resources: {
+    // users and keys (semantics/users.ts)
+    email: { storedAs: 'user_email', idPrefix: 'useremail:' },
+    key: { storedAs: 'user_ssh_key', idPrefix: 'sshkey:' },
+    'gpg-key': { storedAs: 'user_gpg_key', idPrefix: 'gpgkey:' },
+    // gists (semantics/gists.ts): one stored gist answers both the full and the listed shape
+    'gist-simple': { storedAs: 'gist', idPrefix: 'gist:' },
+    'base-gist': { storedAs: 'gist', idPrefix: 'gist:' },
+    // notification threads (semantics/activity.ts)
+    thread: { storedAs: 'notification', idPrefix: 'notification:' },
+    // organizations and teams (semantics/orgs.ts)
+    // is_verified: GitHub verifies an organization's domain; no API moves it
+    'organization-full': { storedAs: 'organization', idPrefix: 'org:', notState: ['is_verified'] },
+    'org-membership': {
+      storedAs: 'org_membership',
+      idPrefix: 'orgmember:',
+      notState: ['role'],
+      state: {
+        // the twin confirms a membership as it sets it (no invitation to accept offline); GitHub starts
+        // one pending until the member accepts
+        state: { initial: 'active', vendorInitial: 'pending', transitions: [{ operation: 'orgs/update-membership-for-authenticated-user', from: ['pending'], to: 'active', source: 'https://docs.github.com/rest/orgs/members#update-an-organization-membership-for-the-authenticated-user' }] },
+      },
+    },
+    // active: a setting an edit names
+    'org-hook': { storedAs: 'org_webhook', idPrefix: 'orghook:', notState: ['active'] },
+    'issue-type': { storedAs: 'issue_type', idPrefix: 'issuetype:', notState: ['color', 'is_enabled'] },
+    'team-full': { storedAs: 'team', idPrefix: 'team:', notState: ['notification_setting', 'privacy', 'type'] },
+    team: { storedAs: 'team', idPrefix: 'team:', notState: ['access_source', 'type'] },
+    // archived, disabled, is_template: the repository's own, ruled on full-repository
+    'team-repository': { storedAs: 'team_repo', idPrefix: 'teamrepo:', notState: ['archived', 'disabled', 'is_template'], key: 'teamrepo:{org}#{team_slug}#{owner}/{repo}' },
+    // Projects v2 (semantics/projects.ts): GitHub moves a project's state by GraphQL's
+    // updateProjectV2 (closed), no REST operation: another wire's move (`external`); the twin stores
+    // it as `closed`. is_template: a setting (markProjectV2AsTemplate).
+    'projects-v2': {
+      storedAs: 'project',
+      idPrefix: 'project:',
+      notState: ['is_template'],
+      state: {
+        state: {
+          initial: 'open',
+          transitions: [
+            { actor: 'external', from: ['open'], to: 'closed', source: 'https://docs.github.com/graphql/reference/mutations#updateprojectv2' },
+            { actor: 'external', from: ['closed'], to: 'open', source: 'https://docs.github.com/graphql/reference/mutations#updateprojectv2' },
+          ],
+        },
+      },
+    },
+    'projects-v2-field': { storedAs: 'project_field', idPrefix: 'projectfield:', notState: ['data_type'] },
+    'projects-v2-item-with-content': { storedAs: 'project_item', idPrefix: 'projectitem:', notState: ['content_type'] },
+    // security alerts (semantics/security.ts): the twin accepts any requested state on an update, as
+    // it always has; GitHub's documented moves are the machines
+    'code-scanning-alert-items': {
+      storedAs: 'code_scanning_alert',
+      idPrefix: 'csalert:',
+      parent: inRepository,
+      key: 'csalert:{owner}/{repo}#{alert_number}',
+      notState: ['dismissed_reason'],
+      state: {
+        state: {
+          initial: 'open',
+          transitions: [
+            { operation: 'code-scanning/update-alert', from: '*', to: 'dismissed', source: 'https://docs.github.com/rest/code-scanning/code-scanning#update-a-code-scanning-alert' },
+            { operation: 'code-scanning/update-alert', from: '*', to: 'open', source: 'https://docs.github.com/rest/code-scanning/code-scanning#update-a-code-scanning-alert' },
+            // an analysis that no longer finds it fixes it (semantics/code-scanning-upload.ts)
+            { actor: 'vendor', from: ['open'], to: 'fixed', source: 'https://docs.github.com/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-details' },
+          ],
+        },
+      },
+    },
+    'code-scanning-analysis': { storedAs: 'code_scanning_analysis', idPrefix: 'csanalysis:', parent: inRepository, key: 'csanalysis:{analysis_id}' },
+    'dependabot-alert': {
+      storedAs: 'dependabot_alert',
+      idPrefix: 'dependabot:',
+      parent: inRepository,
+      key: 'dependabot:{owner}/{repo}#{alert_number}',
+      notState: ['dismissed_reason'],
+      state: {
+        state: {
+          initial: 'open',
+          transitions: [
+            { operation: 'dependabot/update-alert', from: '*', to: 'dismissed', source: 'https://docs.github.com/rest/dependabot/alerts#update-a-dependabot-alert' },
+            { operation: 'dependabot/update-alert', from: '*', to: 'open', source: 'https://docs.github.com/rest/dependabot/alerts#update-a-dependabot-alert' },
+            // a push whose manifest no longer asks for a vulnerable version fixes it (semantics/push-reactions.ts)
+            { actor: 'vendor', from: ['open'], to: 'fixed', source: 'https://docs.github.com/code-security/dependabot/dependabot-alerts/about-dependabot-alerts' },
+          ],
+        },
+      },
+    },
+    'secret-scanning-alert': {
+      storedAs: 'secret_scanning_alert',
+      idPrefix: 'secretscan:',
+      parent: inRepository,
+      key: 'secretscan:{owner}/{repo}#{alert_number}',
+      notState: ['resolution', 'validity'],
+      state: {
+        state: {
+          initial: 'open',
+          transitions: [
+            { operation: 'secret-scanning/update-alert', from: '*', to: 'resolved', source: 'https://docs.github.com/rest/secret-scanning/secret-scanning#update-a-secret-scanning-alert' },
+            { operation: 'secret-scanning/update-alert', from: '*', to: 'open', source: 'https://docs.github.com/rest/secret-scanning/secret-scanning#update-a-secret-scanning-alert' },
+          ],
+        },
+      },
+    },
+    // Pages builds (semantics/pages.ts): GitHub queues a requested build and builds it (queued → building →
+    // built or errored, docs.github.com/rest/pages/pages#request-a-github-pages-build); the twin records it built
+    // as it is requested (nothing builds offline), so it makes none of those moves
+    'page-build': {
+      storedAs: 'pages_build',
+      idPrefix: 'pagesbuild:',
+      parent: inRepository,
+      key: 'pagesbuild:{build_id}',
+      state: { status: { initial: 'built', vendorInitial: 'queued', transitions: [] } },
+    },
+    // packages (semantics/packages.ts)
+    package: { storedAs: 'package', idPrefix: 'package:', notState: ['package_type', 'visibility'] },
+    'package-version': { storedAs: 'package_version', idPrefix: 'packageversion:' },
+    // app installations (semantics/apps.ts)
+    installation: { storedAs: 'app_installation', idPrefix: 'installation:', notState: ['repository_selection'] },
+    // Actions (semantics/actions.ts): no runner executes anything; runs move only by rerun, cancel
+    // and the twin's runner door, from any state, as the twin always has
+    workflow: {
+      storedAs: 'workflow',
+      idPrefix: 'workflow:',
+      parent: inRepository,
+      state: {
+        state: {
+          initial: 'active',
+          transitions: [
+            { operation: 'actions/disable-workflow', from: ['active'], to: 'disabled_manually', source: 'https://docs.github.com/rest/actions/workflows#disable-a-workflow' },
+            { operation: 'actions/enable-workflow', from: ['disabled_manually', 'disabled_inactivity', 'disabled_fork'], to: 'active', source: 'https://docs.github.com/rest/actions/workflows#enable-a-workflow' },
+          ],
+        },
+      },
+    },
+    'workflow-run': {
+      storedAs: 'workflow_run',
+      idPrefix: 'run:',
+      parent: inRepository,
+      key: 'run:{run_id}',
+      // the result a completed run records, not a state of its own
+      notState: ['conclusion'],
+      state: {
+        // a runner finishing it is the vendor's move (the twin's runner door, /_twin/.../complete)
+        status: {
+          initial: 'queued',
+          transitions: [
+            { operation: 'actions/re-run-workflow', from: '*', to: 'queued', source: 'https://docs.github.com/rest/actions/workflow-runs#re-run-a-workflow' },
+            { operation: 'actions/cancel-workflow-run', from: '*', to: 'completed', source: 'https://docs.github.com/rest/actions/workflow-runs#cancel-a-workflow-run' },
+            // a first-time contributor's run from a fork waits, completed as action_required, until a maintainer approves it
+            { operation: 'actions/approve-workflow-run', from: ['completed'], to: 'queued', source: 'https://docs.github.com/rest/actions/workflow-runs#approve-a-workflow-run-for-a-fork-pull-request' },
+            // a runner picking it up (the twin's runner door, /_twin/.../start)
+            { actor: 'vendor', from: ['queued'], to: 'in_progress', refusal: { status: 409, message: 'The run has already started' }, source: 'https://docs.github.com/actions/about-github-actions/understanding-github-actions#runners' },
+            { actor: 'vendor', from: ['queued', 'in_progress'], to: 'completed', refusal: { status: 409, message: 'The run has already completed' }, source: 'https://docs.github.com/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs' },
+          ],
+        },
+      },
+    },
+    job: {
+      storedAs: 'workflow_job',
+      idPrefix: 'job:',
+      parent: inRepository,
+      key: 'job:{job_id}',
+      // the result a completed job records, not a state of its own
+      notState: ['conclusion'],
+      state: {
+        // a job moves with its run: by the run's rerun and cancel, and when the runner finishes the run
+        status: {
+          initial: 'queued',
+          transitions: [
+            { operation: 'actions/re-run-workflow', from: '*', to: 'queued', source: 'https://docs.github.com/rest/actions/workflow-runs#re-run-a-workflow' },
+            { operation: 'actions/cancel-workflow-run', from: '*', to: 'completed', source: 'https://docs.github.com/rest/actions/workflow-runs#cancel-a-workflow-run' },
+            { actor: 'vendor', from: ['queued'], to: 'in_progress', source: 'https://docs.github.com/rest/actions/workflow-jobs#get-a-job-for-a-workflow-run' },
+            { actor: 'vendor', from: ['queued', 'in_progress'], to: 'completed', source: 'https://docs.github.com/rest/actions/workflow-jobs#get-a-job-for-a-workflow-run' },
+          ],
+        },
+      },
+    },
+    artifact: { storedAs: 'actions_artifact', idPrefix: 'artifact:', parent: inRepository, key: 'artifact:{artifact_id}' },
+    // a secret or variable is stored under its `container` (a repository, `owner/repo:env` for an
+    // environment's): one resource spans both, so no parent field names the repository alone
+    'actions-secret': { storedAs: 'actions_secret', idPrefix: 'secret:repo:' },
+    'actions-variable': { storedAs: 'actions_variable', idPrefix: 'variable:repo:' },
+    'organization-actions-secret': { storedAs: 'actions_secret', idPrefix: 'secret:org:', notState: ['visibility'] },
+    'organization-actions-variable': { storedAs: 'actions_variable', idPrefix: 'variable:org:', notState: ['visibility'] },
+    // deploy keys and autolinks (semantics/keys.ts)
+    'deploy-key': { storedAs: 'deploy_key', idPrefix: 'deploykey:', parent: inRepository, key: 'deploykey:{key_id}' },
+    // is_alphanumeric: how the prefix matches, set at creation
+    autolink: { storedAs: 'autolink', idPrefix: 'autolink:', parent: inRepository, key: 'autolink:{autolink_id}', notState: ['is_alphanumeric'] },
+    // rulesets and rule suites (semantics/rulesets.ts): enforcement is a setting an update names, any
+    // value from any value; a suite's results are the outcome it recorded
+    'repository-ruleset': { storedAs: 'ruleset', idPrefix: 'ruleset:', parent: inRepository, key: 'ruleset:{ruleset_id}', notState: ['current_user_can_bypass', 'enforcement', 'source_type', 'target'] },
+    'rule-suite': { storedAs: 'rule_suite', idPrefix: 'rulesuite:', parent: inRepository, key: 'rulesuite:{rule_suite_id}', notState: ['evaluation_result', 'result'] },
+    // deployments and environments (semantics/deployments.ts): a status is created with its state and
+    // never moves (the deployment's state is its latest status)
+    deployment: { storedAs: 'deployment', idPrefix: 'deployment:', parent: inRepository, key: 'deployment:{deployment_id}' },
+    'deployment-status': { storedAs: 'deployment_status', idPrefix: 'depstatus:', parent: inRepository, key: 'depstatus:{status_id}', notState: ['state'] },
+    environment: { storedAs: 'environment', idPrefix: 'env:', parent: inRepository, key: 'env:{owner}/{repo}#{environment_name}' },
+    // releases (semantics/releases.ts); tags are derived from published releases, never stored
+    // a release is created a draft or published; an edit publishes a draft (`draft: false`) or unpublishes
+    // it (`draft: true`), from either value as the twin always took it
+    release: {
+      storedAs: 'release',
+      idPrefix: 'release:',
+      parent: inRepository,
+      key: 'release:{release_id}',
+      state: {
+        draft: {
+          initial: false,
+          transitions: [
+            { operation: 'repos/update-release', from: '*', to: 'false', source: 'https://docs.github.com/rest/releases/releases#update-a-release' },
+            { operation: 'repos/update-release', from: '*', to: 'true', source: 'https://docs.github.com/rest/releases/releases#update-a-release' },
+          ],
+        },
+      },
+    },
+    'release-asset': {
+      storedAs: 'release_asset',
+      idPrefix: 'asset:',
+      parent: inRepository,
+      key: 'asset:{asset_id}',
+      state: {
+        // the upload completing moves it open → uploaded on GitHub (docs.github.com/rest/releases/assets#upload-a-release-asset);
+        // the twin records an asset already uploaded, so it makes no move
+        state: { initial: 'uploaded', vendorInitial: 'open', transitions: [] },
+      },
+    },
+    // repository webhooks (semantics/webhooks.ts)
+    // active: a setting an edit names
+    hook: { storedAs: 'webhook', idPrefix: 'webhook:', parent: inRepository, key: 'webhook:{hook_id}', notState: ['active'] },
+    // labels and milestones (semantics/labels.ts): a milestone's state is set by an edit, any value
+    // from any value, as the twin always took it
+    label: { storedAs: 'label', idPrefix: 'label:', parent: inRepository },
+    milestone: {
+      storedAs: 'milestone',
+      idPrefix: 'milestone:',
+      parent: inRepository,
+      key: '{owner}/{repo}#milestone:{milestone_number}', number: { field: 'number' },
+      state: {
+        state: {
+          initial: 'open',
+          transitions: [
+            { operation: 'issues/update-milestone', from: '*', to: 'closed', source: 'https://docs.github.com/rest/issues/milestones#update-a-milestone' },
+            { operation: 'issues/update-milestone', from: '*', to: 'open', source: 'https://docs.github.com/rest/issues/milestones#update-a-milestone' },
+          ],
+        },
+      },
+    },
+    // commit comments (semantics/commits.ts); commits are the git plane's, never stored
+    'commit-comment': { storedAs: 'commit_comment', idPrefix: 'commitcomment:', parent: inRepository, key: 'commitcomment:{comment_id}', notState: ['author_association'] },
+    // statuses and check runs (semantics/checks.ts): a caller moves a run to whatever status it posts,
+    // and a conclusion completes it; suites are derived from runs, never stored
+    // a status is created with its state and never moves (a commit's state is its latest per context)
+    status: { storedAs: 'commit_status', idPrefix: 'status:', parent: inRepository, notState: ['state'] },
+    'check-run': {
+      storedAs: 'check_run',
+      idPrefix: 'check:',
+      parent: inRepository,
+      key: 'check:{check_run_id}',
+      notState: ['conclusion'],
+      state: {
+        status: {
+          initial: 'queued',
+          transitions: [
+            { operation: 'checks/update', from: '*', to: 'in_progress', source: 'https://docs.github.com/rest/checks/runs#update-a-check-run' },
+            { operation: 'checks/update', from: '*', to: 'completed', source: 'https://docs.github.com/rest/checks/runs#update-a-check-run' },
+          ],
+        },
+      },
+    },
+    // Git Data (semantics/git.ts): refs are rows; blobs, trees, commits and tags are objects in the git
+    // plane the surface names no resource for
+    'git-ref': { storedAs: 'git_ref', idPrefix: 'gitref:', parent: inRepository, key: 'gitref:{owner}/{repo}#refs/{ref}' },
+    // repositories, branches and collaborators (semantics/repos.ts, semantics/branches.ts): a
+    // repository's merge and squash settings are settings an edit names, not states. An edit archives
+    // a repository and unarchives it; GitHub disables one on its own (no API moves `disabled`, and the
+    // twin never does); is_template is a setting.
+    'full-repository': {
+      storedAs: 'repository',
+      idPrefix: 'repo:',
+      notState: ['disabled', 'is_template', 'merge_commit_message', 'merge_commit_title', 'pull_request_creation_policy', 'squash_merge_commit_message', 'squash_merge_commit_title'],
+      state: {
+        archived: {
+          initial: false,
+          transitions: [
+            { operation: 'repos/update', from: '*', to: 'true', source: 'https://docs.github.com/rest/repos/repos#update-a-repository' },
+            { operation: 'repos/update', from: '*', to: 'false', source: 'https://docs.github.com/rest/repos/repos#update-a-repository' },
+          ],
+        },
+      },
+    },
+    'short-branch': { storedAs: 'branch', idPrefix: 'branch:', parent: inRepository, key: 'branch:{owner}/{repo}#{branch}' },
+    collaborator: { storedAs: 'collaborator', idPrefix: 'collab:', parent: inRepository, key: 'collab:{owner}/{repo}#{username}' },
+    // issues, their comments and reactions (semantics/issues.ts). An issue is keyed by its repository
+    // and number; its number is counted with the repository's pull requests (one sequence for both), so
+    // `number` cannot declare it. Its state moves by an edit from any value (closing defaults
+    // state_reason to completed, reopening to reopened).
+    issue: {
+      storedAs: 'issue',
+      idPrefix: 'issue:',
+      parent: inRepository,
+      key: '{owner}/{repo}#issue:{issue_number}',
+      // draft: a pull request's, which an issue answer carries for a pull request's number
+      notState: ['author_association', 'draft', 'state_reason'],
+      state: {
+        state: {
+          initial: 'open',
+          transitions: [
+            { operation: 'issues/update', from: '*', to: 'closed', source: 'https://docs.github.com/rest/issues/issues#update-an-issue' },
+            { operation: 'issues/update', from: '*', to: 'open', source: 'https://docs.github.com/rest/issues/issues#update-an-issue' },
+            // a pull request merged into the default branch closes the issues it links with a closing keyword, and so
+            // does a commit pushed there that names them (semantics/pulls.ts, semantics/push-reactions.ts)
+            { operation: 'pulls/merge', from: ['open'], to: 'closed', source: 'https://docs.github.com/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue' },
+            { actor: 'external', from: ['open'], to: 'closed', source: 'https://docs.github.com/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue' },
+          ],
+        },
+        // locking a locked conversation (or unlocking an unlocked one) is answered 204 as any other
+        locked: {
+          initial: false,
+          transitions: [
+            { operation: 'issues/lock', from: '*', to: 'true', source: 'https://docs.github.com/rest/issues/issues#lock-an-issue' },
+            { operation: 'issues/unlock', from: '*', to: 'false', source: 'https://docs.github.com/rest/issues/issues#unlock-an-issue' },
+          ],
+        },
+      },
+    },
+    'issue-comment': { storedAs: 'issue_comment', idPrefix: 'comment:', parent: inRepository, key: 'comment:{comment_id}', notState: ['author_association'] },
+    reaction: { storedAs: 'reaction', idPrefix: 'reaction:', parent: inRepository, key: 'reaction:{reaction_id}', notState: ['content'] },
+    'pull-request-review-comment': { storedAs: 'pull_request_review_comment', idPrefix: 'comment:', parent: inRepository, key: 'comment:{comment_id}', notState: ['author_association', 'side', 'start_side', 'subject_type'] },
+    // pull requests and reviews (semantics/pulls.ts): one machine per state field. A merge needs an open,
+    // unmerged, non-draft pull request (the handler asks ctx.legal of all three); an edit moves state
+    // from any value. Deleting the head branch closes it (git/delete-ref, on the pull request's machine).
+    // GitHub's auto-merge (GraphQL's enablePullRequestAutoMerge) lands one when its checks pass; the twin does
+    // not have it, so makes no such move. Draft moves by GraphQL alone
+    // (markPullRequestReadyForReview, convertPullRequestToDraft: another wire, `external`), which also
+    // needs it open (a merged one is closed). The conversation locks by the issue operations on its number.
+    'pull-request': {
+      storedAs: 'pull_request',
+      idPrefix: 'pr:',
+      parent: inRepository,
+      key: '{owner}/{repo}#{pull_number}',
+      notState: ['author_association'],
+      state: {
+        state: {
+          initial: 'open',
+          transitions: [
+            { operation: 'pulls/update', from: '*', to: 'closed', source: 'https://docs.github.com/rest/pulls/pulls#update-a-pull-request' },
+            { operation: 'pulls/update', from: '*', to: 'open', source: 'https://docs.github.com/rest/pulls/pulls#update-a-pull-request' },
+            { operation: 'pulls/merge', from: ['open'], to: 'closed', refusal: { status: 405, message: 'Pull Request is not mergeable' }, source: 'https://docs.github.com/rest/pulls/pulls#merge-a-pull-request' },
+            { operation: 'git/delete-ref', from: ['open'], to: 'closed', source: 'https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch-used-for-a-pull-request' },
+            { actor: 'external', from: ['open'], refusal: { status: 422, message: 'Pull request must be open' }, source: 'https://docs.github.com/graphql/reference/mutations#markpullrequestreadyforreview' },
+            // deleting the head branch by a git push closes it too, the git wire's (github-git-http.ts); after the
+            // guard, so an ask that names no state finds the guard
+            { actor: 'external', from: ['open'], to: 'closed', source: 'https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch-used-for-a-pull-request' },
+          ],
+        },
+        merged: {
+          initial: false,
+          transitions: [
+            { operation: 'pulls/merge', from: ['false'], to: 'true', refusal: { status: 405, message: 'Pull Request is not mergeable' }, source: 'https://docs.github.com/rest/pulls/pulls#merge-a-pull-request' },
+          ],
+        },
+        // a guard: a draft is never merged
+        draft: {
+          initial: false,
+          transitions: [
+            { operation: 'pulls/merge', from: ['false'], refusal: { status: 405, message: 'Draft pull requests cannot be merged.' }, source: 'https://docs.github.com/rest/pulls/pulls#merge-a-pull-request' },
+            { actor: 'external', from: ['true'], to: 'false', refusal: { status: 422, message: 'Pull request is already ready for review' }, source: 'https://docs.github.com/graphql/reference/mutations#markpullrequestreadyforreview' },
+            { actor: 'external', from: ['false'], to: 'true', refusal: { status: 422, message: 'Pull request is already a draft' }, source: 'https://docs.github.com/graphql/reference/mutations#convertpullrequesttodraft' },
+          ],
+        },
+        locked: {
+          initial: false,
+          transitions: [
+            { operation: 'issues/lock', from: '*', to: 'true', source: 'https://docs.github.com/rest/issues/issues#lock-an-issue' },
+            { operation: 'issues/unlock', from: '*', to: 'false', source: 'https://docs.github.com/rest/issues/issues#unlock-an-issue' },
+          ],
+        },
+      },
+    },
+    'pull-request-review': {
+      storedAs: 'pull_request_review',
+      idPrefix: 'review:',
+      parent: inRepository,
+      key: 'review:{review_id}',
+      notState: ['author_association'],
+      state: {
+        // set by the submitting event (APPROVE → APPROVED …); a dismissal overlays DISMISSED
+        state: { initial: 'COMMENTED', transitions: [{ operation: 'pulls/dismiss-review', from: '*', to: 'DISMISSED', source: 'https://docs.github.com/rest/pulls/reviews#dismiss-a-review-for-a-pull-request' }] },
+      },
+    },
+    // codespaces (semantics/codespaces.ts): start and stop move from any state, as the twin always has
+    codespace: {
+      storedAs: 'codespace',
+      idPrefix: 'codespace:',
+      notState: ['location'],
+      state: {
+        state: {
+          initial: 'Available',
+          transitions: [
+            { operation: 'codespaces/start-for-authenticated-user', from: '*', to: 'Available', source: 'https://docs.github.com/rest/codespaces/codespaces#start-a-codespace-for-the-authenticated-user' },
+            { operation: 'codespaces/stop-for-authenticated-user', from: '*', to: 'Shutdown', source: 'https://docs.github.com/rest/codespaces/codespaces#stop-a-codespace-for-the-authenticated-user' },
+          ],
+        },
+      },
+    },
+  },
+};