@volter/twin-github 0.1.2 → 2.0.0

package/dist/test-fixtures/github-known-deviations.json

@@ -0,0 +1,94 @@
+{
+  "_doc": "Declared evidence-twin scope: GitHub fields the twin does NOT model, each with a reason. Applies to ALL GitHub objects the twin serves (pull_request, pull_request_review, review-comment, pull-file, pull-commit, label, assignee, issue, issue_comment, commit_status, check_run, milestone, requested_reviewer, issue cross-reference event) — PR node_id names the twin GraphQL node; other objects retain the declared node_id gaps. Object-specific gaps are namespaced (label.*, assignee.*, reviewComment.*, pullFile.*, pullCommit.*, status.*, checkRun.*, milestone.*, requestedReviewer.*, issueEvent.*). The spec-conformance gate (github-conformance.ts) treats a missing-required field as a BUG unless it is declared here, so 'what we don't serve' is explicit and reviewable, not silently absent. See github-twin.ts header: the `github` world is an EVIDENCE mirror (metadata), not a content mirror. A trailing `.*` covers a whole unmodeled sub-object. NOTE: issues, commit statuses, check runs, and milestones are LOCAL simulator/fork constructs (no observed evidence fold — observed PR evidence never carries CI/checks/milestones/review-requests) and have no vendored conformance schema yet, so those objects are not run through the spec gate; their simplifications below are recorded for honesty.",
+  "deviations": [
+    { "path": "issue.id", "kind": "missing-required", "reason": "issue object: no real GitHub integer id is observed on pull (the issue body carries number/title/body/state); a fabricated id would be invented" },
+    { "path": "issue.node_id", "kind": "missing-required", "reason": "no real GraphQL node id for a local issue" },
+    { "path": "issue.user", "kind": "missing-required", "reason": "issue author not modeled; a synthetic simple-user would fabricate a login/id" },
+    { "path": "issue.reactions", "kind": "missing-required", "reason": "reaction rollup not modeled by the local issue construct" },
+    { "path": "issue.timeline_url", "kind": "missing-required", "reason": "timeline hypermedia not modeled" },
+    { "path": "id", "kind": "missing-required", "reason": "PR object: evidence mirror has no real GitHub id (reviews/comments DO emit an integer id from the local sequence)" },
+    { "path": "node_id", "kind": "missing-required", "reason": "PRs emit the synthetic node ID accepted by the twin GraphQL API. Other objects do not yet model node IDs." },
+    { "path": "created_at", "kind": "missing-required", "reason": "observed PR-evidence events do not carry PR creation timestamps" },
+    { "path": "updated_at", "kind": "missing-required", "reason": "see created_at — no PR timestamps in evidence" },
+    { "path": "title", "kind": "missing-required", "reason": "title IS folded on pull (content mirror) and on local writes; declared only for the edge case of a PR that surfaced solely via a review/comment reference (no PR-list entry), which has no title to emit" },
+    { "path": "user.*", "kind": "missing-required", "reason": "PR author login/type are retained when known. Other simple-user subfields, including vendor numeric id and profile URLs, are not modeled." },
+    { "path": "user", "kind": "missing-required", "reason": "When PR author identity was never observed and no explicit local create proves the modeled caller, user is omitted rather than fabricated." },
+    { "path": "_links.*", "kind": "missing-required", "reason": "hypermedia _links block not modeled by the evidence twin" },
+    { "path": "_links", "kind": "missing-required", "reason": "see _links.*" },
+    { "path": "author_association", "kind": "missing-required", "reason": "author relationship to repo not observed" },
+    { "path": "mergeable_state", "kind": "missing-required", "reason": "mergeability is a live-computed GitHub field, not observable evidence" },
+    { "path": "merged", "kind": "missing-required", "reason": "observed evidence carries no merge outcome, so a not-yet-merged PR emits merged=null (present-and-nullable); a local merge write (PUT .../merge) sets it to a typed boolean" },
+    { "path": "maintainer_can_modify", "kind": "missing-required", "reason": "permission flag not observed" },
+    { "path": "additions", "kind": "missing-required", "reason": "line-addition count is NOT in observed PR evidence (only file/commit counts are), so an observed PR omits it; a LOCAL write that carries a `files` list rolls additions up from the diff and emits a typed integer. Declared for the observed scope only." },
+    { "path": "deletions", "kind": "missing-required", "reason": "line-deletion count is NOT in observed PR evidence; observed PRs omit it, while a LOCAL write with a `files` list rolls deletions up from the diff and emits a typed integer. Declared for the observed scope only." },
+    { "path": "comments", "kind": "missing-required", "reason": "the issue-comment count is not surfaced" },
+    { "path": "review_comments", "kind": "missing-required", "reason": "the review-comment count is not surfaced" },
+    { "path": "commits", "kind": "missing-required", "reason": "emitted as a typed integer when observed; declared only for PRs whose evidence lacked a commit count" },
+    { "path": "changed_files", "kind": "missing-required", "reason": "emitted as a typed integer when observed; declared only for PRs whose evidence lacked a changed-files count" },
+    { "path": "base.label", "kind": "missing-required", "reason": "evidence tracks base ref only, not the owner:ref label" },
+    { "path": "base.sha", "kind": "missing-required", "reason": "evidence tracks head sha only; base sha is not observed" },
+    { "path": "base.user.*", "kind": "missing-required", "reason": "base repo owner not modeled (evidence twin)" },
+    { "path": "base.user", "kind": "missing-required", "reason": "see base.user.*" },
+    { "path": "base.repo.*", "kind": "missing-required", "reason": "full_name is served from the stored PR repository. Other Repository fields, including URL templates and settings, are not modeled here." },
+    { "path": "head.label", "kind": "missing-required", "reason": "evidence tracks head sha only, not the owner:ref label" },
+    { "path": "head.ref", "kind": "missing-required", "reason": "evidence tracks head sha; head branch ref is not observed" },
+    { "path": "head.user.*", "kind": "missing-required", "reason": "head repo owner not modeled (evidence twin)" },
+    { "path": "head.user", "kind": "missing-required", "reason": "see head.user.*" },
+    { "path": "head.repo.*", "kind": "missing-required", "reason": "full head Repository object not modeled by the evidence twin" },
+    { "path": "head.repo", "kind": "missing-required", "reason": "see head.repo.*" },
+    { "path": "submitted_at", "kind": "missing-required", "reason": "review object: OBSERVED reviews carry no submission timestamp (only existence); a LOCAL review write sets submitted_at to the write time. Omitted, not faked, when unknown." },
+    { "path": "label.id", "kind": "missing-required", "reason": "labels are written/read by NAME; the twin stores only the name and emits {name}. id/node_id/url/color/default/description would be fabricated, so the label object carries the name alone." },
+    { "path": "label.node_id", "kind": "missing-required", "reason": "see label.id — no real GraphQL node id for a name-only label" },
+    { "path": "label.url", "kind": "missing-required", "reason": "label url template not modeled (name-only label)" },
+    { "path": "label.color", "kind": "missing-required", "reason": "label color not supplied on write; would be fabricated" },
+    { "path": "label.default", "kind": "missing-required", "reason": "is-default flag not modeled for a name-only label" },
+    { "path": "label.description", "kind": "missing-required", "reason": "label description not modeled for a name-only label" },
+    { "path": "assignee.*", "kind": "missing-required", "reason": "assignees are written/read by LOGIN; the twin stores only the login and emits {login}. The rest of the simple-user object (id, node_id, avatar_url, urls, type) would be fabricated." },
+    { "path": "reviewComment.node_id", "kind": "missing-required", "reason": "PR review-comment object: no real GraphQL node id for a local comment" },
+    { "path": "reviewComment.diff_hunk", "kind": "missing-required", "reason": "OBSERVED review comments carry no diff evidence, so they omit diff_hunk; a LOCAL diff-threaded write (POST /pulls/:n/comments with path) anchors the comment and emits diff_hunk (the supplied hunk or ''). Declared for the observed scope only." },
+    { "path": "reviewComment.path", "kind": "missing-required", "reason": "OBSERVED review comments carry no diff path; a LOCAL diff-threaded write supplies path + line + side (+ optional start_line) and surfaces them on the comment. Declared for the observed scope only." },
+    { "path": "reviewComment.commit_id", "kind": "missing-required", "reason": "commit a review comment pins to is not observed" },
+    { "path": "reviewComment.original_commit_id", "kind": "missing-required", "reason": "original commit not observed" },
+    { "path": "reviewComment.author_association", "kind": "missing-required", "reason": "author relationship to repo not observed" },
+    { "path": "reviewComment._links.*", "kind": "missing-required", "reason": "hypermedia _links block not modeled" },
+    { "path": "pullFile.*", "kind": "behavior", "reason": "GET /pulls/:n/files: OBSERVED PR evidence carries a changed-files COUNT but no per-file detail, so an observed PR returns an EMPTY file list (never fabricated). A LOCAL PR write (POST/PATCH with a `files` list of {filename,status,additions,deletions,changes,patch}) carries real per-file diffs, returned here paginated; the remaining file sub-fields the write didn't supply (blob sha when omitted, contents/raw url templates beyond what's derived) stay unmodeled. The carried files also roll up changed_files/additions/deletions on the PR object." },
+    { "path": "pullCommit.*", "kind": "behavior", "reason": "GET /pulls/:n/commits: OBSERVED PR evidence carries a commit COUNT but no per-commit detail, so an observed PR returns an EMPTY commit list (never fabricated). A LOCAL PR write (POST/PATCH with a `commits` list of {sha, commit.message, commit.author{name,email,date}}) carries real commits, returned here paginated; the author/committer simple-user objects, tree, parents and verification are not modeled (the twin emits the message + commit.author it was given, with author/committer simple-users null). A missing sha is derived deterministically (sha256 of repo+index+message), never random." },
+    { "path": "checksStatus", "kind": "behavior", "reason": "CI status checks (commit statuses + check runs) are NOT in observed PR evidence — observed mirrors carry no CI. They are modeled as LOCAL-write constructs: POST /statuses/:sha + POST /check-runs persist via the action log, and GET .../commits/:ref/status|statuses|check-runs read them back. An observed-only PR therefore reports a 'pending' combined status with total_count 0 (the faithful empty), never a fabricated check." },
+    { "path": "requestedReviewers", "kind": "behavior", "reason": "Review REQUESTS are distinct from submitted reviews and are NOT in observed evidence (the fold sees submitted reviews only). Modeled as a LOCAL write (POST/DELETE /pulls/:n/requested_reviewers, body {reviewers:[login]}) storing bare logins; surfaced on the PR object (requested_reviewers) and GET /pulls/:n/requested_reviewers as {users:[{login}], teams:[]}. Observed-only PRs have none." },
+    { "path": "requestedReviewer.*", "kind": "missing-required", "reason": "requested reviewers are stored by LOGIN; the twin emits {login} and declares the rest of the simple-user object (id, node_id, avatar_url, urls, type) — it would be fabricated. requested_teams is not modeled (always empty)." },
+    { "path": "status.node_id", "kind": "missing-required", "reason": "commit_status object: no real GraphQL node id for a local status" },
+    { "path": "status.creator.*", "kind": "missing-required", "reason": "the user that created a status is not modeled (local CI construct); a synthetic simple-user would fabricate a login/id, so creator is null" },
+    { "path": "status.avatar_url", "kind": "missing-required", "reason": "status avatar_url not modeled (no creator)" },
+    { "path": "checkRun.node_id", "kind": "missing-required", "reason": "check_run object: no real GraphQL node id for a local check run" },
+    { "path": "checkRun.external_id", "kind": "missing-required", "reason": "check run external id not supplied on write" },
+    { "path": "checkRun.output.*", "kind": "missing-required", "reason": "check run output (title/summary/annotations) not modeled — would be fabricated" },
+    { "path": "checkRun.check_suite.*", "kind": "missing-required", "reason": "check run is not grouped into a modeled check suite (no suite evidence)" },
+    { "path": "checkRun.app.*", "kind": "missing-required", "reason": "the GitHub App that produced a check run is not modeled (local construct)" },
+    { "path": "checkRun.pull_requests", "kind": "missing-required", "reason": "the back-link from a check run to its PRs is not modeled (keyed by head_sha only)" },
+    { "path": "milestone.id", "kind": "missing-required", "reason": "milestone object: local construct emits a deterministic sequence id, but the real GitHub integer id / GraphQL node_id are not observed and not fabricated as the canonical id" },
+    { "path": "milestone.node_id", "kind": "missing-required", "reason": "no real GraphQL node id for a local milestone" },
+    { "path": "milestone.creator.*", "kind": "missing-required", "reason": "milestone creator not modeled; a synthetic simple-user would fabricate a login/id, so creator is omitted" },
+    { "path": "milestone.open_issues", "kind": "behavior", "reason": "issue/PR-per-milestone rollup counts are emitted as 0 — the twin does not yet aggregate how many issues/PRs reference a milestone, so it reports 0 rather than fabricating a count" },
+    { "path": "milestone.closed_issues", "kind": "behavior", "reason": "see milestone.open_issues — closed-issue rollup emitted as 0" },
+    { "path": "issueEvent.*", "kind": "behavior", "reason": "GET /issues/:n/events|timeline: real GitHub returns the full timeline (labeled/assigned/referenced/cross-referenced/...). The twin models ONLY the cross-referenced linked-PR/issue relation (set via the twin-extension _twin_linked field — GitHub has no direct link-write endpoint, links are inferred from body text). actor/created_at and the rich source object are emitted null/minimal rather than fabricated; other event types are not modeled." },
+    { "path": "issue.linked", "kind": "behavior", "reason": "linked PRs/issues are a simple LOCAL relation ([{type,number}]) the twin surfaces via the events endpoint as cross-referenced events. Real GitHub infers links from body cross-references / the timeline; the twin lets a simulator declare them explicitly (PATCH issue with _twin_linked) rather than parsing prose." },
+    { "path": "issue.milestone", "kind": "behavior", "reason": "an issue/PR milestone is set by NUMBER via PATCH {milestone:n}; the twin looks up the local milestone object (created via POST /milestones) and surfaces it, or null when none/unknown — it never fabricates a milestone object for an unknown number" },
+    { "path": "release.node_id", "kind": "missing-required", "reason": "release object: local construct emits a deterministic sequence id, but no real GraphQL node id is observed or fabricated" },
+    { "path": "release.author.*", "kind": "missing-required", "reason": "release author not modeled (local construct); a synthetic simple-user would fabricate a login/id, so author is null" },
+    { "path": "release.reactions", "kind": "missing-required", "reason": "reaction rollup not modeled by the local release construct" },
+    { "path": "release.discussion_url", "kind": "missing-required", "reason": "release-discussion hypermedia not modeled (Discussions are a separate todo)" },
+    { "path": "release.published_at", "kind": "behavior", "reason": "a DRAFT release emits published_at=null (real GitHub behavior — a draft has no publish time); a published (draft:false) release stamps published_at to the write time. Omitted/null, never faked." },
+    { "path": "asset.*", "kind": "behavior", "reason": "release ASSETS are MODELED AS METADATA ONLY: the twin carries name/label/content_type/size/state/download_count + derivable url templates (POST /releases/:id/assets persists via the action log; GET .../assets reads them back). The actual asset binary BYTES are a declared Non-goal (large + redundant — the same boundary as repo blob bytes); browser_download_url points at the asset path but the twin serves NO real content. uploader simple-user + node_id are not modeled (would be fabricated)." },
+    { "path": "tag.*", "kind": "behavior", "reason": "GET /tags + GET /git/refs/tags: tags are DERIVED from the LOCAL published (non-draft) releases the twin created — there is no observed git-data evidence, and git commit/blob BYTES are the Non-goal. The commit sha is deterministic (sha256 of repo+tag), the ref is a lightweight 'commit' ref (no annotated-tag object), and the full commit object (author/message/tree) + node_id are not modeled." },
+    { "path": "discussion.*", "kind": "behavior", "reason": "DISCUSSIONS TRANSPORT DEVIATION: on real GitHub, Discussions (and their categories/comments/answers) are served by the GraphQL v4 API, NOT REST — there is no public REST Discussions endpoint. The twin models them over its OWN REST handler (POST/GET/PATCH/DELETE /repos/:o/:r/discussions[/:num][/comments][/categories]) for CONSISTENCY with the rest of the twin's REST surface; the OBJECT shapes mirror the GraphQL node fields projected into a REST-style body (number/title/body/state/category/answer). This is an honest, declared transport+shape deviation, not a fidelity claim about GitHub's REST API. Discussions are LOCAL constructs (no observed evidence fold)." },
+    { "path": "discussion.node_id", "kind": "missing-required", "reason": "discussion object: no real GraphQL node id is observed for a local discussion (Discussions are a GraphQL product; the twin emits node_id=null rather than fabricating one)" },
+    { "path": "discussion.user", "kind": "missing-required", "reason": "discussion author not modeled (local construct); a synthetic simple-user would fabricate a login/id, so user is null" },
+    { "path": "discussion.reactions", "kind": "missing-required", "reason": "reaction rollup not modeled by the local discussion construct" },
+    { "path": "discussion.answer", "kind": "behavior", "reason": "the accepted answer is surfaced as answer_comment_id (the chosen comment's local id, null when none) + answer_chosen_at; the full GraphQL answer node (the embedded comment object) is not duplicated — the comment is fetchable via the comments list. Marking is only valid for an ANSWERABLE (Q&A) category; a mark on a non-answerable discussion 422s." },
+    { "path": "discussionCategory.*", "kind": "behavior", "reason": "discussion CATEGORIES are SEEDED per-repo with GitHub's default set (Announcements/General/Ideas/Q&A/Show and tell), only Q&A answerable; a custom category is a LOCAL construct (POST /discussions/categories). Ids are deterministic (sha256 of repo+slug), repository_id is a deterministic short hash, and node_id is not modeled. The real GraphQL category node carries more (createdAt/updatedAt/repository) that the twin omits." },
+    { "path": "discussionComment.node_id", "kind": "missing-required", "reason": "discussion-comment object: no real GraphQL node id for a local comment" },
+    { "path": "discussionComment.user", "kind": "missing-required", "reason": "discussion-comment author not modeled (local construct); user is null rather than a fabricated simple-user" },
+    { "path": "discussionComment.reactions", "kind": "missing-required", "reason": "reaction rollup not modeled by the local discussion-comment construct" },
+    { "path": "discussionComment.parent_id", "kind": "behavior", "reason": "a threaded REPLY pins to its parent comment via parent_id (set on the create body); a top-level comment has parent_id=null. The twin models a single reply level (parent → reply), matching GitHub's two-level discussion threading; is_answer marks the accepted answer (Q&A only)." }
+  ]
+}

package/dist/test-fixtures/github-openapi-operations.SOURCE.md

@@ -0,0 +1,76 @@
+# github-openapi-operations.json — provenance
+
+The **operation-inventory denominator** for the TWIN-15 spec-census pilot (B5a —
+`docs/COMPLETENESS_PASS.md`): a curated, hand-vendored *subset* of GitHub's published REST
+OpenAPI, used ONLY to enumerate `{method, path}` operations via
+`deriveFromOpenAPI` (`packages/world-tooling/src/derive.ts`) for
+`../github-spec-census.json` to map against. It is deliberately NOT a full spec fetch.
+
+- **Upstream:** `github/rest-api-description` (MIT licensed) —
+  `https://github.com/github/rest-api-description`, specifically
+  `descriptions/api.github.com/api.github.com.json`.
+- **How it was built:** hand-authored path/method entries from the operator's knowledge of
+  GitHub's documented REST API — **not fetched over the network**. This repo's completeness
+  pass runs offline/deterministic (see `docs/COMPLETENESS_PASS.md` — no live-vendor calls in
+  any gated script or test), so this fixture is vendored the same way
+  `github-pull-schema.json` et al. are: a real vendor contract, captured by hand instead of by
+  a live HTTP fetch.
+- **Curated on:** 2026-07-04.
+- **Scope (38 operations):** the domain `@volter/twin-github` actually models — issues, pull
+  requests, repos, git-data refs, commit/review comments (listing them, writing one, and
+  replying in a thread) — **plus a deliberate handful of
+  adjacent real GitHub operations the pack does NOT model** (repo-wide issue/PR comment and
+  event listings, community-profile metrics, fork upstream-merge, vulnerability-alerts toggle,
+  matching-refs listing, async-computed repo statistics, repo transfer, and the automated
+  security-fixes toggle). Those are real, documented GitHub endpoints — they exist specifically
+  so the census's `unmapped` bucket is genuinely exercised instead of a hollow
+  1:1 map that proves nothing (see the census's own "why a census where everything maps 1:1
+  proves nothing" doctrine note).
+- **Bounded, not exhaustive:** GitHub's real OpenAPI doc is multi-megabyte and covers hundreds
+  of operations across many products (Actions, Packages, Codespaces, Projects, …) the pack
+  models too (see `github-capabilities.ts`) but that are OUT of this pilot fixture's ~30-40 op
+  budget — B5a is explicitly a ONE-VENDOR, ONE-SLICE pilot; B5b (TWIN-16, since built) generalized
+  the denominator via the per-vendor spec-source registry `spec-sources.json` (repo root), which
+  registers this fixture/census pair as github's entry and rolls the same census format out to the
+  other vendors on the manifest-census duty cadence.
+- **TWIN-82 (R-T4) — the curation boundary is now mechanical, not just disclosed here:**
+  `../github-spec-census.json` carries a committed `scopePaths: ["/repos/{owner}/{repo}"]` array
+  and a `fullSpecEstimateOps` (~850) honest estimate of GitHub's full REST surface.
+  `scripts/spec-census.ts --check` fails if any fixture operation falls outside `scopePaths`, and
+  prints "census covers N ops within committed scope X; full spec ~M ops" on every run so the
+  sampled fraction is visible in gate output — not only in this prose note. `scripts/spec-refresh.ts`
+  refuses any `--scope-paths` CLI value that isn't a member of the committed `scopePaths` array (see
+  "Refresh" below), so the boundary can't silently drift from what an operator hand-types.
+
+## Refresh
+
+The fixture also inventories the single `POST /graphql` transport already included in the
+census's committed scope. Its first-party source is
+[GitHub: Forming calls with GraphQL](https://docs.github.com/en/graphql/guides/forming-calls-with-graphql)
+(verified 2026-09-06), not the REST OpenAPI repository: ordinary queries and mutations use
+POST at `https://api.github.com/graphql`. This entry inventories that transport, not every
+GraphQL field or mutation, and does not claim full schema coverage. REST-only fixture refreshes
+must preserve this separately sourced entry and its census mapping.
+
+If GitHub's REST API changes a path/method in this subset (or the pack's modeled domain
+grows), update this fixture and `../github-spec-census.json` together — `bun
+scripts/spec-census.ts --check` fails loudly (the completeness/tamper tooth) if the two drift
+out of bijection.
+
+**B6 (TWIN-17), built:** the manifest-census duty's refresh tool is `scripts/spec-refresh.ts`.
+Download GitHub's current `descriptions/api.github.com/api.github.com.json` (network happens
+OUTSIDE the tool — this repo's gate runs offline) and run:
+
+```
+bun scripts/spec-refresh.ts --vendor github --from-file <path-to-the-downloaded-spec> \
+  --scope-paths /repos/{owner}/{repo}
+```
+
+`--scope-paths` restricts the diff to this fixture's curated domain — without it, every one of
+GitHub's hundreds of out-of-subset operations (Actions, Packages, Codespaces, Projects, …) would
+be reported as spuriously "removed". The report names every added/removed `{method, path}` and
+exits nonzero if the vendor changed. Add `--apply` to rewrite this fixture and
+`../github-spec-census.json` together (new operations appended as `unmapped` for triage, removed
+operations dropped from both, `unmappedBaseline` left untouched so growth still WARNs); the tool
+then re-runs the bijection check itself before exiting. Once satisfied, record the duty:
+`bun scripts/next-duties.ts --record --duty manifest-census --target github`.

package/dist/test-fixtures/github-openapi-operations.json

@@ -0,0 +1,362 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "GitHub REST API (spec-census pilot subset)",
+    "version": "2026-06-14",
+    "description": "A curated, hand-vendored SUBSET of GitHub's published REST OpenAPI (github/rest-api-description, https://github.com/github/rest-api-description), used ONLY as the operation-inventory denominator for the TWIN-15 spec census (see ../github-spec-census.json). Domain covered: issues, pull requests, repos, git refs, and commit/review comments -- the surface the @volter/twin-github pack models -- PLUS a deliberate handful of adjacent real GitHub operations the pack does NOT model, so the census genuinely exercises its `unmapped` and `$ruled` buckets instead of mapping 1:1. This is NOT a full GitHub OpenAPI document (GitHub's real spec is multi-megabyte); it is bounded to ~30-40 operations by design, offline and deterministic -- see github-openapi-operations.SOURCE.md for exactly how each path/method was curated. Method + path + operationId + summary ONLY: no schemas and NO STATUS CODES. It used to carry a response code or two per operation, which read as the operation's whole response set -- diff status codes against the freshly fetched spec, never against this file."
+  },
+  "x-source": {
+    "vendor": "github",
+    "upstream": "https://github.com/github/rest-api-description",
+    "upstreamFile": "descriptions/api.github.com/api.github.com.json",
+    "vendored": "hand-authored from the operator's knowledge of GitHub's published REST API paths/methods -- NOT fetched over the network (offline/deterministic build requirement)",
+    "curatedOn": "2026-07-04",
+    "scope": "issues, pulls, repos, git-data refs, commit/review comments -- the domain the github pack models -- plus adjacent real GitHub operations the pack intentionally leaves unmapped/unmapped"
+  },
+  "paths": {
+    "/graphql": {
+      "post": {
+        "operationId": "graphql/api",
+        "summary": "Execute a GraphQL query or mutation",
+        "tags": ["graphql"],
+        "responses": { "200": { "description": "GraphQL response with data and/or errors" } }
+      }
+    },
+    "/repos/{owner}/{repo}/issues": {
+      "get": {
+        "operationId": "issues/list-for-repo",
+        "summary": "List repository issues",
+        "tags": [
+          "issues"
+        ]
+      },
+      "post": {
+        "operationId": "issues/create",
+        "summary": "Create an issue",
+        "tags": [
+          "issues"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/issues/{issue_number}": {
+      "patch": {
+        "operationId": "issues/update",
+        "summary": "Update an issue (title/body/state/labels/assignees/milestone)",
+        "tags": [
+          "issues"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/issues/{issue_number}/comments": {
+      "get": {
+        "operationId": "issues/list-comments",
+        "summary": "List issue comments",
+        "tags": [
+          "issues"
+        ]
+      },
+      "post": {
+        "operationId": "issues/create-comment",
+        "summary": "Create an issue comment",
+        "tags": [
+          "issues"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/issues/{issue_number}/labels": {
+      "post": {
+        "operationId": "issues/add-labels",
+        "summary": "Add labels to an issue",
+        "tags": [
+          "issues"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/issues/{issue_number}/lock": {
+      "put": {
+        "operationId": "issues/lock",
+        "summary": "Lock an issue conversation",
+        "tags": [
+          "issues"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/issues/comments": {
+      "get": {
+        "operationId": "issues/list-comments-for-repo",
+        "summary": "List issue comments for a repository (repo-wide, across all issues)",
+        "tags": [
+          "issues"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/issues/events": {
+      "get": {
+        "operationId": "issues/list-events-for-repo",
+        "summary": "List issue events for a repository (repo-wide, across all issues)",
+        "tags": [
+          "issues"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/pulls": {
+      "get": {
+        "operationId": "pulls/list",
+        "summary": "List pull requests",
+        "tags": [
+          "pulls"
+        ]
+      },
+      "post": {
+        "operationId": "pulls/create",
+        "summary": "Create a pull request",
+        "tags": [
+          "pulls"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/pulls/{pull_number}": {
+      "get": {
+        "operationId": "pulls/get",
+        "summary": "Get a pull request",
+        "tags": [
+          "pulls"
+        ]
+      },
+      "patch": {
+        "operationId": "pulls/update",
+        "summary": "Update a pull request",
+        "tags": [
+          "pulls"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/pulls/{pull_number}/merge": {
+      "put": {
+        "operationId": "pulls/merge",
+        "summary": "Merge a pull request",
+        "tags": [
+          "pulls"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/pulls/{pull_number}/files": {
+      "get": {
+        "operationId": "pulls/list-files",
+        "summary": "List pull request files",
+        "tags": [
+          "pulls"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/pulls/{pull_number}/reviews": {
+      "get": {
+        "operationId": "pulls/list-reviews",
+        "summary": "List reviews for a pull request",
+        "tags": [
+          "pulls"
+        ]
+      },
+      "post": {
+        "operationId": "pulls/create-review",
+        "summary": "Create a review for a pull request",
+        "tags": [
+          "pulls"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/pulls/{pull_number}/comments": {
+      "get": {
+        "operationId": "pulls/list-review-comments",
+        "summary": "List review comments on a pull request",
+        "tags": [
+          "pulls"
+        ],
+        "responses": {
+          "200": {
+            "description": "list of review comments"
+          }
+        }
+      },
+      "post": {
+        "operationId": "pulls/create-review-comment",
+        "summary": "Create a diff-anchored review comment",
+        "tags": [
+          "pulls"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies": {
+      "post": {
+        "operationId": "pulls/create-reply-for-review-comment",
+        "summary": "Create a reply for a review comment",
+        "tags": [
+          "pulls"
+        ],
+        "responses": {
+          "201": {
+            "description": "reply created"
+          }
+        }
+      }
+    },
+    "/repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers": {
+      "post": {
+        "operationId": "pulls/request-reviewers",
+        "summary": "Request reviewers for a pull request",
+        "tags": [
+          "pulls"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/pulls/comments": {
+      "get": {
+        "operationId": "pulls/list-review-comments-for-repo",
+        "summary": "List review comments in a repository (repo-wide, across all pull requests)",
+        "tags": [
+          "pulls"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}": {
+      "get": {
+        "operationId": "repos/get",
+        "summary": "Get a repository",
+        "tags": [
+          "repos"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/branches": {
+      "get": {
+        "operationId": "repos/list-branches",
+        "summary": "List branches",
+        "tags": [
+          "repos"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/contents/{path}": {
+      "get": {
+        "operationId": "repos/get-content",
+        "summary": "Get repository content",
+        "tags": [
+          "repos"
+        ]
+      },
+      "put": {
+        "operationId": "repos/create-or-update-file-contents",
+        "summary": "Create or update file contents",
+        "tags": [
+          "repos"
+        ]
+      },
+      "delete": {
+        "operationId": "repos/delete-file",
+        "summary": "Delete a file",
+        "tags": [
+          "repos"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/community/profile": {
+      "get": {
+        "operationId": "repos/get-community-profile-metrics",
+        "summary": "Get community profile metrics",
+        "tags": [
+          "repos"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/merge-upstream": {
+      "post": {
+        "operationId": "repos/merge-upstream",
+        "summary": "Sync a fork branch with the upstream repository",
+        "tags": [
+          "repos"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/vulnerability-alerts": {
+      "get": {
+        "operationId": "repos/check-vulnerability-alerts",
+        "summary": "Check if Dependabot vulnerability alerts are enabled",
+        "tags": [
+          "repos"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/git/refs": {
+      "post": {
+        "operationId": "git/create-ref",
+        "summary": "Create a reference",
+        "tags": [
+          "git"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/git/ref/{ref}": {
+      "get": {
+        "operationId": "git/get-ref",
+        "summary": "Get a reference",
+        "tags": [
+          "git"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/git/matching-refs/{ref}": {
+      "get": {
+        "operationId": "git/list-matching-refs",
+        "summary": "List matching references",
+        "tags": [
+          "git"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/commits/{commit_sha}/comments": {
+      "get": {
+        "operationId": "repos/list-commit-comments",
+        "summary": "List commit comments",
+        "tags": [
+          "repos"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/stats/contributors": {
+      "get": {
+        "operationId": "repos/get-contributors-stats",
+        "summary": "Get all contributor commit activity (async-computed statistics)",
+        "tags": [
+          "repos"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/stats/commit_activity": {
+      "get": {
+        "operationId": "repos/get-commit-activity-stats",
+        "summary": "Get the last year of commit activity (async-computed statistics)",
+        "tags": [
+          "repos"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/transfer": {
+      "post": {
+        "operationId": "repos/transfer",
+        "summary": "Transfer a repository to another owner",
+        "tags": [
+          "repos"
+        ]
+      }
+    },
+    "/repos/{owner}/{repo}/automated-security-fixes": {
+      "delete": {
+        "operationId": "repos/disable-automated-security-fixes",
+        "summary": "Disable automated security fixes (Dependabot security updates toggle)",
+        "tags": [
+          "repos"
+        ]
+      }
+    }
+  }
+}

package/dist/test-fixtures/github-pull-schema.SOURCE.md

@@ -0,0 +1,37 @@
+# github-pull-schema.json — provenance
+
+The **full** GitHub pull-request response schema (types, required, enums, nested
+`base`/`head`/`repo`/`user`), used by the GitHub twin's spec-conformance gate
+(`src/github-conformance.ts`, `src/github-conformance.test.ts`).
+
+- **Source:** `https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/dereferenced/api.github.com.deref.json`
+- **Repo:** `github/rest-api-description` (GitHub's published OpenAPI) — MIT licensed
+- **Fetched:** 2026-06-14
+- **Extraction:** the dereferenced spec inlines all `$ref`s into paths, so the PR
+  object is self-contained at
+  `paths["/repos/{owner}/{repo}/pulls/{pull_number}"].get.responses["200"].content["application/json"].schema`.
+  Vendored verbatim (no projection):
+  `jq '.paths["/repos/{owner}/{repo}/pulls/{pull_number}"].get.responses["200"].content["application/json"].schema'`
+
+## Why the FULL schema, not a field-name list
+
+This **replaces** the old `github-pull-fields.json`, which kept only
+`Object.keys(properties)` — bare field NAMES. A name list can only catch
+*fabrication* (a field GitHub doesn't have). It is structurally blind to:
+- **types** — it could not see that `changed_files` is an `integer` (the twin once
+  emitted it as `null`/object and the gate stayed green);
+- **omission** — a subset check never visits required fields the twin *fails* to
+  emit (the twin covered 10/48 fields; the old gate reported clean);
+- **enums / required / nullability** — all discarded by the projection.
+
+The full schema carries all of it, so the gate validates real types + required
+fields + enums offline, with no token. Fields the **evidence** twin deliberately
+does not model are declared in `github-known-deviations.json` (with reasons), so
+"what we don't serve" is explicit rather than silently absent.
+
+## Refresh
+
+Re-fetch the dereferenced spec and re-extract the PR schema when GitHub ships
+schema changes; then re-run `bun test src/github-conformance.test.ts`. A new
+failure means either real GitHub drift (update this fixture) or twin drift (fix
+the twin), and the violation report says which fields.