@volter/twin-github 0.1.1 → 2.0.0

package/README.md

@@ -1,13 +1,14 @@
 # @volter/twin-github
 
-The **GitHub twin** — a local replica of the GitHub **REST** pull-request API on
-the shared [`@volter/twin`](../control-plane) kernel. The real `@octokit/rest` client
+The **GitHub twin** — a local replica of the GitHub **REST** API (repositories, git data, issues, pull
+requests, Actions, releases, organizations and teams, Apps, Pages, security alerts and more) on
+the shared [`@volter/world-core`](../../world-core) kernel. The real `@octokit/rest` client
 works against it unmodified.
 
 > **Note:** both planes carry content. Local simulator/fork **writes** carry full content
 > (a created PR has a title/body/diffs), and the connector's *pull* path folds the CONTENT
 > real GitHub returns — PR/issue title/body/state, review bodies, comment bodies, and the
-> inline diff findings. The only deliberate GitHub out-of-scope carve-out is bulk pull of
+> inline diff findings. The one GitHub surface still unbuilt by design is bulk pull of
 > actual repository **code/file contents** (see Coverage below).
 
 ## Surface
@@ -30,7 +31,7 @@ works against it unmodified.
   with a `comments` array) carries that review's id, and a comment posted on its own carries
   the PR's **implicit review** — one deterministic id per (repo, PR). It is synthesized on
   `GET .../pulls/:n/reviews` *from the comments that name it* and never stored as a review of
-  its own; `_twin.review_count` counts it under exactly that condition, so the count and the
+  its own; the pull request's review count counts it under exactly that condition, so the count and the
   list describe one population (real GitHub serves the wrapper on `/reviews` and counts it
   too). The point is that the join a consumer does (`pull_request_review_id` → the reviews
   page) is live against the twin's own data; it used to be dead, because the twin answered
@@ -41,10 +42,32 @@ works against it unmodified.
   id is never a twin id: every pulled review and comment is rehashed before it is served, and
   no review id is ever sent back out (a push addresses a vendor comment by the `external_id`
   the pull recorded).
-- **Webhooks** (`github-events.ts`): `pull_request` / `pull_request_review` /
-  `issue_comment` with the `X-GitHub-Event` header.
+- **Repository webhooks** (`github-events.ts`): register through native `/repos/{owner}/{repo}/hooks`
+  CRUD. The server resolves stored subscriptions on every write, sends HTTP callbacks and stores
+  their outcomes in the same World. Hook configuration and delivery history survive server restart;
+  there is no separate registration helper. JSON and form payloads carry `X-GitHub-Event`,
+  `X-GitHub-Delivery` and, when configured, HMAC-SHA256 over the transmitted bytes. PR, review and
+  comment events carry their source records, including deleted comment snapshots and inline
+  comment parents. Native writes name the modeled `twin` sender separately from the source author;
+  PR IDs are stable modeled numbers and local PR update times come from their write history.
+  Unknown imported authors and update times remain unknown. Review webhook states use lowercase,
+  while REST states retain uppercase. Imported comments retain their stored identity on edit/delete;
+  known vendor edit times survive the projection. Local inline comments and replies retain their
+  target commit. PR synchronization snapshots are captured with their state writes, before callback
+  delivery, so a later push cannot replace an earlier event's head. Other emitted event types retain
+  partial payload coverage.
+  Native ping, delivery list/detail and explicit redelivery routes are supported; redelivery keeps
+  the original GUID and payload with current hook settings. Failed callbacks are recorded without
+  undoing the vendor mutation. Callback attempts run before the mutation response, with a ten-second
+  timeout per hook; automatic retries and crash recovery of pending attempts are not modeled.
+  Signing secrets are masked on native reads and the mirror. Full hook PATCH removes an omitted
+  secret; config PATCH preserves it. TLS verification remains enabled (`insecure_ssl: 1` is explicitly
+  unsupported). Identical configurations with overlapping subscriptions are refused on create or
+  update. Delivery records are local execution history and cannot be deployed to GitHub.
+  See [GitHub's repository webhook API](https://docs.github.com/en/rest/repos/webhooks) and
+  [delivery guidance](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks).
 - **Conformance** (`github-conformance.ts`): field-name subset vs the vendored
-  GitHub REST PR schema (PR + nested base/head/repo; `_twin` extras excluded).
+  GitHub REST PR schema (PR + nested base/head/repo).
 - **UI mirror** (`github-mirror-ui.ts`): a GitHub-style PR browser (React) with a
   per-repo selector ("multiple githubs"), a pure frontend (R3) — the shell + assets with
   the twin's own fetch adapter mounted beside them. It reads the world through the twin's
@@ -56,7 +79,7 @@ works against it unmodified.
   share (the store path, the PR/issue route grammar) live in `github-shared.ts`.
 - **Connector** (`github-connector.ts`): the live-vendor lifecycle over an injected
   octokit-like executor. `syncGithubFromReal` pulls a repo's PRs + issues and folds their
-  content; `pushPendingGithubActions` enacts local writes. Pull is **per-row conflict
+  content; the kernel performs local writes through `performGithubAction`. Pull is **per-row conflict
   tolerant**: if one stored event has diverged from what a resource now folds to (a
   `Conflicting duplicate` — e.g. a post-append line mutation raced the live writer), that
   ONE row is skipped rather than aborting the whole repo's fold, so every other resource in
@@ -106,11 +129,11 @@ works against it unmodified.
   reply route (`POST .../pulls/{n}/comments/{comment_id}/replies`), addressing the root by
   the id the *vendor* gave it — resolved from what a pull observed, or from what an earlier
   push in the same sweep returned. The connector NEVER forwards a twin-minted id to a real
-  account: a reply whose root has no known GitHub id is **refused**, ledgered in the push
-  result's `skipped` (action id, operation, reason) and left pending for a later sweep. That
-  per-action tolerance is the push-side twin of the pull's per-row conflict skip — one
-  refusal or one vendor rejection never aborts the other writes in the sweep, and nothing is
-  confirmed on a failure.
+  account: a reply whose root has no known GitHub id is refused. The kernel stops the
+  deployment at the first failed action and leaves it unconfirmed; later actions wait until
+  the failure is resolved. A successful root comment adopts the vendor ID before a subsequent
+  reply resolves it.
+
 
 ## CLI
 
@@ -122,10 +145,19 @@ world-github conformance [--root DIR]
 
 Point the real `@octokit/rest` `Octokit` at it via `baseUrl`.
 
+Locally created PRs use the modeled authenticated self account, `octocat`, matching
+`GET /user`. Pulled PRs retain the observed author; an unknown author is omitted.
+Older local PRs recover that same modeled author only when their retained history
+contains an explicit agent `pull_request.create`, without changing stored records.
+This does not add credential-specific review identity: the separate review-writer
+limitation described above still applies. PR responses include `base.repo.full_name`
+and the synthetic node ID `PR_<owner/repo>#<number>`, shared with the twin's GraphQL
+API. These node IDs address twin state and are not real GitHub node IDs.
+
 ## Interaction surfaces
 
-1. **SDK/API** — *zero edits (preferred):* `GITHUB_TWIN_URL=http://127.0.0.1:PORT node --require @volter/twin/inject your-app` redirects the real `@octokit/rest` from `api.github.com` to the twin. *Or* override directly: `new Octokit({ baseUrl: 'http://127.0.0.1:PORT', auth: 'twin' })`.
-2. **API + CLI** — `world-github serve` (writable) + drive with `volter-twin status|plan|refs github`, then push.
+1. **SDK/API** — *zero edits (preferred):* `GITHUB_TWIN_URL=http://127.0.0.1:PORT node --require @volter/world-core/inject your-app` redirects the real `@octokit/rest` from `api.github.com` to the twin. *Or* override directly: `new Octokit({ baseUrl: 'http://127.0.0.1:PORT', auth: 'twin' })`.
+2. **API + CLI** — run the twin in a World and inspect it with `volter world log` and `diff`. Use the [deployment guide](../../../docs/guides/deploy-from-a-shared-world.md) for changeset review and deployment.
 3. **Read-only** — `world-github serve --read-only`: unlimited local reads, no rate limits; writes refuse like GitHub (4xx).
 4. **UI mirror** — `world-github mirror` renders a GitHub-style view of the twin's state.
 
@@ -134,7 +166,7 @@ Point the real `@octokit/rest` `Octokit` at it via `baseUrl`.
 ## Coverage
 
 Goal: **honest, explicitly tracked coverage of GitHub's core feature surface.** The only
-accepted carve-outs are explicit out-of-scope items. Tracked in three buckets — anything not
+there are no exclusions. Tracked in three buckets — anything not
 done or carved out is a gap to close.
 
 **Done** — PRs (create/edit/merge/list/get; **full PR/issue content on pull** — title/body/state
@@ -149,7 +181,7 @@ list/get workflows, workflow_dispatch → queued run, rerun/cancel transitions,
 status/branch/event, run jobs; **rendered in the UI mirror** Actions view), **Actions
 secrets/variables** (repo + org scope — secret values never returned, mirroring GitHub),
 **Actions caches** (list/delete by id or key), **Actions artifacts** (register/list/get/delete
-metadata), **Actions run logs** (302 redirect to a signed URL; bytes out of scope), **Git Data
+metadata), **Actions run logs** (302 redirect to a signed URL; serving the bytes is a todo), **Git Data
 API** (refs create/get/update/delete, commits, trees, blobs *with content*, annotated tags),
 **deployments + deployment statuses** (create/list/filter + status history), **environments**
 (create/update/delete + protection-rule summaries; **rendered in the UI mirror** Deployments
@@ -158,20 +190,31 @@ pagination, webhooks, UI mirror (rung-5 ✅), connector (pull content+issues + p
 merge/review/comment/status/check/milestone/reviewers), **Gists** (create/edit/list/get/delete +
 comments).
 
-**The REAL git plane (smart HTTP).** The twin is now *clonable and pushable by an unmodified
-`git` CLI*: per-repo **real bare repositories** live under the twin instance's state dir, and
-`GET /:owner/:repo/info/refs` + `POST .../git-upload-pack|git-receive-pack` bridge the wire to
-real `git upload-pack`/`receive-pack --stateless-rpc` subprocesses (git is its own reference
-implementation — see `src/github-git-plane.ts` / `src/github-git-http.ts`; supabase's
-real-engine doctrine applied to git). The Git Data REST endpoints are **re-backed by the same
-bare repos**: a REST blob/tree/commit/tag create writes a *real* git object (real sha, fetchable
-by ref), a `git push` folds its ref changes into the kernel log (visible to REST refs/branches,
-re-points open PR heads — GitHub's `synchronize` — and fires the `push` webhook through the
-existing pipeline). One object store, not two. Refs minted on shas no object backs (a legacy
-lenient surface some verifies pin) stay control-plane-only and are never advertised, so an
-advertised ref is always clonable. The fidelity oracle is the **real git CLI** —
-`src/github-git.integration.test.ts` clones, pushes, fetches REST-authored commits, and replays
-the OA loop's verified-api signing flow (`POST git/commits` + `PATCH git/refs/heads/:branch`).
+Draft PRs become ready through GitHub's GraphQL
+[`markPullRequestReadyForReview`](https://docs.github.com/en/graphql/reference/pulls#markpullrequestreadyforreview)
+mutation and return to draft through
+[`convertPullRequestToDraft`](https://docs.github.com/en/graphql/reference/pulls#convertpullrequesttodraft).
+Both preserve the PR number, head and reviews and emit `pull_request` with action
+`ready_for_review` or `converted_to_draft`. Invalid selections, unknown nodes, closed PRs
+and requests for the current draft state fail without changing stored state.
+The payload subset is `clientMutationId` and
+`pullRequest { id number isDraft url }`.
+REST PR updates ignore the unsupported `draft` field; creation still accepts it.
+Deploying a draft-state change resolves the destination PR's own node ID and uses
+the matching GraphQL mutation, confirming the returned state before acknowledging it.
+
+**Git smart HTTP.** Unmodified Git clients clone and push through the portable JavaScript
+Git implementation in `@volter/world-core/git`. Git Data REST and smart HTTP share the
+object store and refs. Real Git is the test oracle; serving does not spawn Git subprocesses.
+Pushes update REST refs and open PR heads and emit push webhooks. Only refs backed by stored
+objects are advertised.
+
+PR merges check required statuses and check runs before updating the base ref. Three-way
+merges preserve non-overlapping file and text changes, reject conflicting changes, and
+compare the base tip again while holding the ref lock. Armed auto-merge runs on a protected branch when its declared required
+checks turn green. A newer failure supersedes an old success, and drafts stay open. Merge commits preserve two parents; squash and the modeled rebase method
+fold the result into one commit. Rename detection, binary conflict resolution, and general
+Git rebase semantics are not modeled.
 
 **SDLC control plane for merge gates** — commit statuses at a sha, check runs, branch
 protection that **persists** `required_status_checks` (contexts/strict) + `enforce_admins` and
@@ -189,13 +232,13 @@ hermetically against this twin.
 **orgs/teams/members** (membership), the rest of the
 **GraphQL API** (the modeled subset now includes the gh pr view merge-gate fields), security
 (code-scanning/dependabot/secret-scanning), packages/pages/codespaces, git-plane follow-ons
-(protection ENFORCED on receive-pack + PR merge, shallow/partial clone asserts, LFS, SSH
+(full protection enforcement on receive-pack and the remaining PR policies, shallow/partial clone asserts, LFS, SSH
 transport). (Actions **log bytes** stay out — CI-compute output, see Out of scope.)
 
 **Out of scope** (deliberately not modeled, with reason) —
 - ~~Actual repository code / file contents~~ **narrowed 2026-08-20**: the git plane now stores
   REAL blob/tree/commit bytes for repos exercised through Git Data REST or `git push`. What
-  remains out of scope is bulk *pull* of a real remote repository's full object graph through
+  remains unbuilt is bulk *pull* of a real remote repository's full object graph through
   the connector (large + redundant for an evidence twin); the API objects AND locally-authored
   bytes are covered.
 - Running real **CI compute** (executing Actions workflows): infra, not the API — the run/job
@@ -214,9 +257,18 @@ validated by *method identity*, so a subclass or a `Proxy` that replaces `checkB
 
 The declared numbers: **600 points / hour**, using GitHub's *own* published point scheme: a `GET`/`HEAD`/`OPTIONS` is 1 point. Bounded on every published axis at once — ≤12% of the 5,000 requests/hour primary limit; under the 900-points-per-**minute** secondary limit even if the whole hour were spent instantly. Writes are charged **8** rather than GitHub's own 5, the single departure from its table and a *tightening*: at 5 the hour-long window would admit 120 writes inside one minute, 1.5× the documented 80 content-generating requests/minute.
 
-The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/twin` →
-`control-plane/src/rateBudget.ts`); what lives here in [`src/github-budget.ts`](src/github-budget.ts) is this vendor's
+The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/world-core` →
+`packages/world-core/src/rateBudget.ts`); what lives here in [`src/github-budget.ts`](src/github-budget.ts) is this vendor's
 **declaration** (window, ceiling, per-endpoint weights, and a `reason` citing the limits above) plus
 the vendor-bound `GithubBudget`. The rule is ratified as
-[ARCHITECTURE.md](../../../ARCHITECTURE.md) **D8**, and the kernel module's header documents what the
+[../../../docs/contributing/architecture.md](../../../docs/contributing/architecture.md) **D8**, and the kernel module's header documents what the
 guard does *not* guarantee — read that before trusting it.
+
+Contents API writes in Git-backed repositories create real blobs, trees and commits on the selected branch. Reads of contents and README files honor branch, tag and commit references; clone/fetch sees the same bytes. Updates and deletions require the current blob SHA, and a competing branch update refuses with 409. Repositories represented only by connector observations retain their observed-file behavior.
+
+Discussion seeding uses GitHub GraphQL `repository.discussionCategories` and `createDiscussion`;
+readback and `addDiscussionComment` share the same stored discussion. Category lookup supports
+forward `first`/`after` pagination. The remaining GraphQL surface is partial; unsupported fields fail loudly.
+See [GitHub’s schema](https://docs.github.com/en/graphql/reference/discussions).
+Category fields are limited to ID, name, slug, description and answerability; emoji is not modeled.
+Creation emits the existing discussion webhook through the normal server delivery path.