@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/manifest.d.ts

@@ -0,0 +1,8 @@
+import type { DerivedManifest } from '@volter/world-core';
+/** 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 declare const spanning: string[];
+export declare const manifest: DerivedManifest;

package/dist/src/manifest.js

@@ -0,0 +1,597 @@
+import { callerLogin, GITHUB_WORLD_USER } from "./github-twin.js";
+/** 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 = {
+    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' },
+                    ],
+                },
+            },
+        },
+    },
+};

package/dist/src/npm-registry.d.ts

@@ -0,0 +1,7 @@
+type Flow = {
+    root?: string;
+    now: () => string;
+};
+/** npm.pkg.github.com's publish, or undefined for any other request. */
+export declare function githubNpmRegistry(flow: Flow): (request: Request) => Promise<Response | undefined>;
+export {};