@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"email":{"list":"/user/emails","create":{"path":"/user/emails","encoding":"json","body":[]},"actions":[],"states":{},"embeds":{}},"key":{"list":"/user/keys","retrieve":"/user/keys/{key_id}","create":{"path":"/user/keys","encoding":"json","body":[{"name":"key","type":"string","required":true},{"name":"title","type":"string","required":false}]},"actions":[],"states":{},"embeds":{}},"gpg-key":{"list":"/user/gpg_keys","retrieve":"/user/gpg_keys/{gpg_key_id}","create":{"path":"/user/gpg_keys","encoding":"json","body":[{"name":"armored_public_key","type":"string","required":true},{"name":"name","type":"string","required":false}]},"actions":[],"states":{},"embeds":{}},"gist-simple":{"retrieve":"/gists/{gist_id}","create":{"path":"/gists","encoding":"json","body":[{"name":"description","type":"string","required":false},{"name":"files","type":"object","required":true},{"name":"public","type":"union","required":false}]},"actions":[],"states":{},"embeds":{}},"base-gist":{"list":"/gists","actions":[],"states":{},"embeds":{}},"thread":{"list":"/notifications","retrieve":"/notifications/threads/{thread_id}","actions":[],"states":{},"embeds":{}},"organization-full":{"retrieve":"/orgs/{org}","actions":[],"states":{},"embeds":{}},"org-membership":{"retrieve":"/orgs/{org}/memberships/{username}","actions":[],"states":{"state":["active","pending"]},"embeds":{}},"org-hook":{"list":"/orgs/{org}/hooks","retrieve":"/orgs/{org}/hooks/{hook_id}","create":{"path":"/orgs/{org}/hooks","encoding":"json","body":[{"name":"active","type":"boolean","required":false},{"name":"config","type":"object","required":true},{"name":"events","type":"array","required":false},{"name":"name","type":"string","required":true}]},"actions":[],"states":{},"embeds":{}},"issue-type":{"list":"/orgs/{org}/issue-types","create":{"path":"/orgs/{org}/issue-types","encoding":"json","body":[{"name":"color","type":"string","required":false},{"name":"description","type":"string","required":false},{"name":"is_enabled","type":"boolean","required":true},{"name":"name","type":"string","required":true}]},"actions":[],"states":{},"embeds":{}},"team-full":{"retrieve":"/orgs/{org}/teams/{team_slug}","create":{"path":"/orgs/{org}/teams","encoding":"json","body":[{"name":"description","type":"string","required":false},{"name":"maintainers","type":"array","required":false},{"name":"name","type":"string","required":true},{"name":"notification_setting","type":"string","required":false},{"name":"parent_team_id","type":"integer","required":false},{"name":"parent_team_slug","type":"string","required":false},{"name":"permission","type":"string","required":false},{"name":"privacy","type":"string","required":false},{"name":"repo_names","type":"array","required":false}]},"actions":[],"states":{},"embeds":{}},"team":{"list":"/orgs/{org}/teams","actions":[],"states":{},"embeds":{}},"team-repository":{"retrieve":"/orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}","actions":[],"states":{},"embeds":{}},"projects-v2":{"list":"/orgs/{org}/projectsV2","retrieve":"/orgs/{org}/projectsV2/{project_number}","actions":[],"states":{"state":["closed","open"]},"embeds":{}},"projects-v2-field":{"actions":[],"states":{},"embeds":{}},"projects-v2-item-with-content":{"actions":[],"states":{},"embeds":{}},"code-scanning-alert-items":{"list":"/repos/{owner}/{repo}/code-scanning/alerts","actions":[],"states":{"state":["dismissed","fixed","open"]},"embeds":{}},"code-scanning-analysis":{"list":"/repos/{owner}/{repo}/code-scanning/analyses","retrieve":"/repos/{owner}/{repo}/code-scanning/analyses/{analysis_id}","actions":[],"states":{},"embeds":{}},"dependabot-alert":{"list":"/repos/{owner}/{repo}/dependabot/alerts","retrieve":"/repos/{owner}/{repo}/dependabot/alerts/{alert_number}","actions":[{"operation":"dependabot/update-alert","method":"PATCH","path":"/repos/{owner}/{repo}/dependabot/alerts/{alert_number}","field":"state","from":"*","to":"dismissed"},{"operation":"dependabot/update-alert","method":"PATCH","path":"/repos/{owner}/{repo}/dependabot/alerts/{alert_number}","field":"state","from":"*","to":"open"}],"states":{"state":["dismissed","fixed","open"]},"embeds":{}},"secret-scanning-alert":{"list":"/repos/{owner}/{repo}/secret-scanning/alerts","actions":[],"states":{"state":["open","resolved"]},"embeds":{}},"page-build":{"list":"/repos/{owner}/{repo}/pages/builds","retrieve":"/repos/{owner}/{repo}/pages/builds/latest","actions":[],"states":{"status":["built"]},"embeds":{}},"package":{"list":"/user/packages","retrieve":"/user/packages/{package_type}/{package_name}","actions":[],"states":{},"embeds":{}},"package-version":{"list":"/user/packages/{package_type}/{package_name}/versions","retrieve":"/user/packages/{package_type}/{package_name}/versions/{package_version_id}","actions":[],"states":{},"embeds":{}},"installation":{"list":"/app/installations","retrieve":"/app/installations/{installation_id}","actions":[],"states":{},"embeds":{}},"workflow":{"list":"/repos/{owner}/{repo}/actions/workflows","retrieve":"/repos/{owner}/{repo}/actions/workflows/{workflow_id}","actions":[],"states":{"state":["active","disabled_fork","disabled_inactivity","disabled_manually"]},"embeds":{}},"workflow-run":{"list":"/repos/{owner}/{repo}/actions/runs","retrieve":"/repos/{owner}/{repo}/actions/runs/{run_id}","actions":[{"operation":"actions/re-run-workflow","method":"POST","path":"/repos/{owner}/{repo}/actions/runs/{run_id}/rerun","field":"status","from":"*","to":"queued"},{"operation":"actions/cancel-workflow-run","method":"POST","path":"/repos/{owner}/{repo}/actions/runs/{run_id}/cancel","field":"status","from":"*","to":"completed"}],"states":{"status":["completed","in_progress","queued"]},"embeds":{}},"job":{"list":"/repos/{owner}/{repo}/actions/runs/{run_id}/jobs","retrieve":"/repos/{owner}/{repo}/actions/jobs/{job_id}","actions":[],"states":{"status":["completed","in_progress","queued"]},"embeds":{}},"artifact":{"list":"/repos/{owner}/{repo}/actions/artifacts","retrieve":"/repos/{owner}/{repo}/actions/artifacts/{artifact_id}","actions":[],"states":{},"embeds":{}},"actions-secret":{"list":"/repos/{owner}/{repo}/actions/secrets","retrieve":"/repos/{owner}/{repo}/actions/secrets/{secret_name}","actions":[],"states":{},"embeds":{}},"actions-variable":{"list":"/repos/{owner}/{repo}/actions/variables","retrieve":"/repos/{owner}/{repo}/actions/variables/{name}","actions":[],"states":{},"embeds":{}},"organization-actions-secret":{"list":"/orgs/{org}/actions/secrets","retrieve":"/orgs/{org}/actions/secrets/{secret_name}","actions":[],"states":{},"embeds":{}},"organization-actions-variable":{"list":"/orgs/{org}/actions/variables","retrieve":"/orgs/{org}/actions/variables/{name}","actions":[],"states":{},"embeds":{}},"deploy-key":{"list":"/repos/{owner}/{repo}/keys","retrieve":"/repos/{owner}/{repo}/keys/{key_id}","create":{"path":"/repos/{owner}/{repo}/keys","encoding":"json","body":[{"name":"key","type":"string","required":true},{"name":"read_only","type":"boolean","required":false},{"name":"title","type":"string","required":false}]},"actions":[],"states":{},"embeds":{}},"autolink":{"list":"/repos/{owner}/{repo}/autolinks","retrieve":"/repos/{owner}/{repo}/autolinks/{autolink_id}","create":{"path":"/repos/{owner}/{repo}/autolinks","encoding":"json","body":[{"name":"is_alphanumeric","type":"boolean","required":false},{"name":"key_prefix","type":"string","required":true},{"name":"url_template","type":"string","required":true}]},"actions":[],"states":{},"embeds":{}},"repository-ruleset":{"list":"/repos/{owner}/{repo}/rulesets","retrieve":"/repos/{owner}/{repo}/rulesets/{ruleset_id}","create":{"path":"/repos/{owner}/{repo}/rulesets","encoding":"json","body":[{"name":"bypass_actors","type":"array","required":false},{"name":"conditions","type":"repository-ruleset-conditions","required":false},{"name":"enforcement","type":"repository-rule-enforcement","required":true},{"name":"name","type":"string","required":true},{"name":"rules","type":"array","required":false},{"name":"target","type":"string","required":false}]},"actions":[],"states":{},"embeds":{}},"rule-suite":{"retrieve":"/repos/{owner}/{repo}/rulesets/rule-suites/{rule_suite_id}","actions":[],"states":{},"embeds":{}},"deployment":{"list":"/repos/{owner}/{repo}/deployments","retrieve":"/repos/{owner}/{repo}/deployments/{deployment_id}","create":{"path":"/repos/{owner}/{repo}/deployments","encoding":"json","body":[{"name":"auto_merge","type":"boolean","required":false},{"name":"description","type":"string","required":false},{"name":"environment","type":"string","required":false},{"name":"payload","type":"union","required":false},{"name":"production_environment","type":"boolean","required":false},{"name":"ref","type":"string","required":true},{"name":"required_contexts","type":"array","required":false},{"name":"task","type":"string","required":false},{"name":"transient_environment","type":"boolean","required":false}]},"actions":[],"states":{},"embeds":{}},"deployment-status":{"list":"/repos/{owner}/{repo}/deployments/{deployment_id}/statuses","retrieve":"/repos/{owner}/{repo}/deployments/{deployment_id}/statuses/{status_id}","create":{"path":"/repos/{owner}/{repo}/deployments/{deployment_id}/statuses","encoding":"json","body":[{"name":"auto_inactive","type":"boolean","required":false},{"name":"description","type":"string","required":false},{"name":"environment","type":"string","required":false},{"name":"environment_url","type":"string","required":false},{"name":"log_url","type":"string","required":false},{"name":"state","type":"string","required":true},{"name":"target_url","type":"string","required":false}]},"actions":[],"states":{},"embeds":{}},"environment":{"list":"/repos/{owner}/{repo}/environments","retrieve":"/repos/{owner}/{repo}/environments/{environment_name}","actions":[],"states":{},"embeds":{}},"release":{"list":"/repos/{owner}/{repo}/releases","retrieve":"/repos/{owner}/{repo}/releases/latest","create":{"path":"/repos/{owner}/{repo}/releases","encoding":"json","body":[{"name":"body","type":"string","required":false},{"name":"discussion_category_name","type":"string","required":false},{"name":"draft","type":"boolean","required":false},{"name":"generate_release_notes","type":"boolean","required":false},{"name":"make_latest","type":"string","required":false},{"name":"name","type":"string","required":false},{"name":"prerelease","type":"boolean","required":false},{"name":"tag_name","type":"string","required":true},{"name":"target_commitish","type":"string","required":false}]},"actions":[{"operation":"repos/update-release","method":"PATCH","path":"/repos/{owner}/{repo}/releases/{release_id}","field":"draft","from":"*","to":"false"},{"operation":"repos/update-release","method":"PATCH","path":"/repos/{owner}/{repo}/releases/{release_id}","field":"draft","from":"*","to":"true"}],"states":{"draft":["false","true"]},"embeds":{}},"release-asset":{"list":"/repos/{owner}/{repo}/releases/{release_id}/assets","retrieve":"/repos/{owner}/{repo}/releases/assets/{asset_id}","create":{"path":"/repos/{owner}/{repo}/releases/{release_id}/assets","encoding":"none","body":[]},"actions":[],"states":{"state":["uploaded"]},"embeds":{}},"hook":{"list":"/repos/{owner}/{repo}/hooks","retrieve":"/repos/{owner}/{repo}/hooks/{hook_id}","create":{"path":"/repos/{owner}/{repo}/hooks","encoding":"json","body":[{"name":"active","type":"boolean","required":false},{"name":"config","type":"object","required":false},{"name":"events","type":"array","required":false},{"name":"name","type":"string","required":false}]},"actions":[],"states":{},"embeds":{}},"label":{"list":"/repos/{owner}/{repo}/labels","retrieve":"/repos/{owner}/{repo}/labels/{name}","create":{"path":"/repos/{owner}/{repo}/labels","encoding":"json","body":[{"name":"color","type":"string","required":false},{"name":"description","type":"string","required":false},{"name":"name","type":"string","required":true}]},"actions":[],"states":{},"embeds":{}},"milestone":{"list":"/repos/{owner}/{repo}/milestones","retrieve":"/repos/{owner}/{repo}/milestones/{milestone_number}","create":{"path":"/repos/{owner}/{repo}/milestones","encoding":"json","body":[{"name":"description","type":"string","required":false},{"name":"due_on","type":"string","required":false},{"name":"state","type":"string","required":false},{"name":"title","type":"string","required":true}]},"actions":[{"operation":"issues/update-milestone","method":"PATCH","path":"/repos/{owner}/{repo}/milestones/{milestone_number}","field":"state","from":"*","to":"closed"},{"operation":"issues/update-milestone","method":"PATCH","path":"/repos/{owner}/{repo}/milestones/{milestone_number}","field":"state","from":"*","to":"open"}],"states":{"state":["closed","open"]},"embeds":{}},"commit-comment":{"list":"/repos/{owner}/{repo}/comments","retrieve":"/repos/{owner}/{repo}/comments/{comment_id}","create":{"path":"/repos/{owner}/{repo}/commits/{commit_sha}/comments","encoding":"json","body":[{"name":"body","type":"string","required":true},{"name":"line","type":"integer","required":false},{"name":"path","type":"string","required":false},{"name":"position","type":"integer","required":false}]},"actions":[],"states":{},"embeds":{}},"status":{"list":"/repos/{owner}/{repo}/commits/{ref}/statuses","actions":[],"states":{},"embeds":{}},"check-run":{"list":"/repos/{owner}/{repo}/commits/{ref}/check-runs","retrieve":"/repos/{owner}/{repo}/check-runs/{check_run_id}","create":{"path":"/repos/{owner}/{repo}/check-runs","encoding":"json","body":[{"name":"actions","type":"array","required":false},{"name":"completed_at","type":"string","required":false},{"name":"conclusion","type":"string","required":false},{"name":"details_url","type":"string","required":false},{"name":"external_id","type":"string","required":false},{"name":"head_sha","type":"string","required":true},{"name":"name","type":"string","required":true},{"name":"output","type":"object","required":false},{"name":"started_at","type":"string","required":false},{"name":"status","type":"string","required":false}]},"actions":[{"operation":"checks/update","method":"PATCH","path":"/repos/{owner}/{repo}/check-runs/{check_run_id}","field":"status","from":"*","to":"in_progress"},{"operation":"checks/update","method":"PATCH","path":"/repos/{owner}/{repo}/check-runs/{check_run_id}","field":"status","from":"*","to":"completed"}],"states":{"status":["completed","in_progress","queued"]},"embeds":{}},"git-ref":{"retrieve":"/repos/{owner}/{repo}/git/ref/{ref}","actions":[],"states":{},"embeds":{}},"full-repository":{"retrieve":"/repos/{owner}/{repo}","actions":[{"operation":"repos/update","method":"PATCH","path":"/repos/{owner}/{repo}","field":"archived","from":"*","to":"true"},{"operation":"repos/update","method":"PATCH","path":"/repos/{owner}/{repo}","field":"archived","from":"*","to":"false"}],"states":{"archived":["false","true"]},"embeds":{}},"short-branch":{"list":"/repos/{owner}/{repo}/branches","actions":[],"states":{},"embeds":{}},"collaborator":{"list":"/repos/{owner}/{repo}/collaborators","actions":[],"states":{},"embeds":{}},"issue":{"list":"/repos/{owner}/{repo}/issues","retrieve":"/repos/{owner}/{repo}/issues/{issue_number}","create":{"path":"/repos/{owner}/{repo}/issues","encoding":"json","body":[{"name":"assignee","type":"string","required":false},{"name":"assignees","type":"array","required":false},{"name":"body","type":"string","required":false},{"name":"issue_field_values","type":"array","required":false},{"name":"labels","type":"array","required":false},{"name":"milestone","type":"union","required":false},{"name":"parent_issue_id","type":"integer","required":false},{"name":"title","type":"union","required":true},{"name":"type","type":"string","required":false}]},"actions":[{"operation":"issues/update","method":"PATCH","path":"/repos/{owner}/{repo}/issues/{issue_number}","field":"state","from":"*","to":"closed"},{"operation":"issues/update","method":"PATCH","path":"/repos/{owner}/{repo}/issues/{issue_number}","field":"state","from":"*","to":"open"},{"operation":"issues/lock","method":"PUT","path":"/repos/{owner}/{repo}/issues/{issue_number}/lock","field":"locked","from":"*","to":"true"},{"operation":"issues/unlock","method":"DELETE","path":"/repos/{owner}/{repo}/issues/{issue_number}/lock","field":"locked","from":"*","to":"false"}],"states":{"state":["closed","open"],"locked":["false","true"]},"embeds":{}},"issue-comment":{"list":"/repos/{owner}/{repo}/issues/{issue_number}/comments","retrieve":"/repos/{owner}/{repo}/issues/comments/{comment_id}","create":{"path":"/repos/{owner}/{repo}/issues/{issue_number}/comments","encoding":"json","body":[{"name":"body","type":"string","required":true}]},"actions":[],"states":{},"embeds":{}},"reaction":{"list":"/repos/{owner}/{repo}/issues/{issue_number}/reactions","create":{"path":"/repos/{owner}/{repo}/issues/{issue_number}/reactions","encoding":"json","body":[{"name":"content","type":"string","required":true}]},"actions":[],"states":{},"embeds":{}},"pull-request-review-comment":{"list":"/repos/{owner}/{repo}/pulls/{pull_number}/comments","retrieve":"/repos/{owner}/{repo}/pulls/comments/{comment_id}","create":{"path":"/repos/{owner}/{repo}/pulls/{pull_number}/comments","encoding":"json","body":[{"name":"body","type":"string","required":true},{"name":"commit_id","type":"string","required":true},{"name":"in_reply_to","type":"integer","required":false},{"name":"line","type":"integer","required":false},{"name":"path","type":"string","required":true},{"name":"position","type":"integer","required":false},{"name":"side","type":"string","required":false},{"name":"start_line","type":"integer","required":false},{"name":"start_side","type":"string","required":false},{"name":"subject_type","type":"string","required":false}]},"actions":[],"states":{},"embeds":{}},"pull-request":{"retrieve":"/repos/{owner}/{repo}/pulls/{pull_number}","create":{"path":"/repos/{owner}/{repo}/pulls","encoding":"json","body":[{"name":"base","type":"string","required":true},{"name":"body","type":"string","required":false},{"name":"draft","type":"boolean","required":false},{"name":"head","type":"string","required":true},{"name":"head_repo","type":"string","required":false},{"name":"issue","type":"integer","required":false},{"name":"maintainer_can_modify","type":"boolean","required":false},{"name":"title","type":"string","required":false}]},"actions":[{"operation":"pulls/update","method":"PATCH","path":"/repos/{owner}/{repo}/pulls/{pull_number}","field":"state","from":"*","to":"closed"},{"operation":"pulls/update","method":"PATCH","path":"/repos/{owner}/{repo}/pulls/{pull_number}","field":"state","from":"*","to":"open"},{"operation":"pulls/merge","method":"PUT","path":"/repos/{owner}/{repo}/pulls/{pull_number}/merge","field":"state","from":["open"],"to":"closed"},{"operation":"pulls/merge","method":"PUT","path":"/repos/{owner}/{repo}/pulls/{pull_number}/merge","field":"merged","from":["false"],"to":"true"},{"operation":"pulls/merge","method":"PUT","path":"/repos/{owner}/{repo}/pulls/{pull_number}/merge","field":"draft","from":["false"]}],"states":{"state":["closed","open"],"merged":["false","true"],"draft":["false","true"],"locked":["false","true"]},"embeds":{}},"pull-request-review":{"list":"/repos/{owner}/{repo}/pulls/{pull_number}/reviews","retrieve":"/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}","create":{"path":"/repos/{owner}/{repo}/pulls/{pull_number}/reviews","encoding":"json","body":[{"name":"body","type":"string","required":false},{"name":"comments","type":"array","required":false},{"name":"commit_id","type":"string","required":false},{"name":"event","type":"string","required":false}]},"actions":[{"operation":"pulls/dismiss-review","method":"PUT","path":"/repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/dismissals","field":"state","from":"*","to":"DISMISSED"}],"states":{"state":["COMMENTED","DISMISSED"]},"embeds":{}},"codespace":{"list":"/user/codespaces","retrieve":"/user/codespaces/{codespace_name}","create":{"path":"/user/codespaces","encoding":"json","body":[]},"actions":[{"operation":"codespaces/start-for-authenticated-user","method":"POST","path":"/user/codespaces/{codespace_name}/start","field":"state","from":"*","to":"Available"},{"operation":"codespaces/stop-for-authenticated-user","method":"POST","path":"/user/codespaces/{codespace_name}/stop","field":"state","from":"*","to":"Shutdown"}],"states":{"state":["Available","Shutdown"]},"embeds":{}}}}

package/dist/src/github-budget.d.ts

@@ -0,0 +1,69 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. One HOUR — the horizon of GitHub's primary 5,000-requests limit. */
+export declare const GITHUB_BUDGET_WINDOW_MS: number;
+/**
+ * Weighted POINTS allowed inside one window. 600 points/hour is ≤ 12% of the primary 5,000
+ * requests/hour AND stays under the secondary 900 points/minute even if spent all at once.
+ */
+export declare const GITHUB_BUDGET_CEILING = 600;
+/**
+ * Weighted points allowed in any 60-SECOND sub-window, enforced by the kernel independently of the
+ * hourly ceiling. Without it, an hour-long window admits its entire 600 points in one millisecond —
+ * twenty times what the austere fallback allows in a minute — and nothing in the kernel reached that
+ * (§9 round 2, 2026-07-26). 300 is deliberately HALF the hourly ceiling: a full PR pull of a busy
+ * repo is ~80 points and the largest realistic burst is well under it, while both of GitHub's
+ * per-minute legs are honoured with room to spare — 300 < the 900-points/minute secondary limit, and
+ * 300/8 = 37 writes < the 80 content-generating requests/minute.
+ */
+export declare const GITHUB_BUDGET_BURST_CEILING = 300;
+/** Seconds. A `Retry-After` above this means the token is throttled hard — fail loudly, don't sleep. */
+export declare const GITHUB_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** GitHub's OWN published point costs. Not a proxy for them — the numbers themselves. */
+export declare const GITHUB_CALL_WEIGHTS: {
+    /**
+     * GitHub's own table prices a `POST`/`PATCH`/`PUT`/`DELETE` at **5 points**. This charges **8**,
+     * and the extra 3 are not a re-transcription of the vendor — they are what makes the OTHER
+     * documented write limit hold. GitHub caps content creation at **80 per minute** as well as 500
+     * per hour, and with an hour-long window a 5-point price lets 600/5 = 120 writes land inside a
+     * single minute: 1.5x that 80. At 8 points only 75 fit, which is under it. (§9 finding,
+     * 2026-07-26: the declaration cited the 80/min limit in its own header and then checked only the
+     * hourly leg.) Reads are unaffected, and the ratio is still write-dearer-than-read as published.
+     */
+    readonly write: 8;
+    /** "Most REST API GET, HEAD, and OPTIONS requests" — 1 point, per GitHub's own table. */
+    readonly other: 1;
+};
+/** THE PACK'S DECLARATION — pure data, the only GitHub-specific thing in the whole budget. */
+export declare const GITHUB_RATE_BUDGET: RateBudgetDeclaration;
+/**
+ * Price one call by its octokit-style ROUTE (`"GET /repos/{owner}/{repo}/pulls"`). The route, not
+ * the substituted path, is the key: it is what GitHub's docs name endpoints by, and it keeps the
+ * ledger's classification stable across owners and repos. A route nobody classified still costs
+ * `defaultWeight` — an unknown endpoint must never be free.
+ */
+export declare function githubCallWeight(route: string): number;
+/** Where GitHub's ledger lives. Token-keyed and cwd-independent by default (the primary limit is
+ *  per token, so a cwd-scoped ledger would hand the same PAT a fresh allowance in every checkout,
+ *  worktree and CI matrix leg — precisely the shape a matrix build has); pass `root` to opt into
+ *  world-scoped accounting instead. */
+export declare function githubBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options for GitHub's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type GithubBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * GitHub's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof GithubBudget` in `liveGithubExecute` means "a budget that
+ * accounts against GITHUB's ledger under GITHUB's ceiling": another vendor's `RateBudget` (with its
+ * own, possibly larger, ceiling) is NOT assignable there.
+ */
+export declare class GithubBudget extends RateBudget {
+    constructor(opts?: GithubBudgetOptions);
+}
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as GithubBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as GithubBudgetErrorKind } from '@volter/world-core';
+export type GithubBudgetReservation = RateBudgetReservation;
+export type GithubBudgetSnapshot = RateBudgetSnapshot;

package/dist/src/github-budget.js

@@ -0,0 +1,172 @@
+// GitHub's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveGithubExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's
+// header for the full rationale AND for the honest list of what the guard does not guarantee (an
+// injected clock or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not.
+//
+// ── HOW THE CEILING WAS CHOSEN: GITHUB'S OWN POINT SYSTEM ───────────────────────────────────
+// GitHub is the one vendor in this repo whose published scheme is ALREADY a weighted point budget,
+// so this declaration reproduces it rather than inventing a proxy for it. From
+// https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api (read 2026-07-26):
+//   • PRIMARY, per authenticated personal access token:  5,000 requests per HOUR
+//   • SECONDARY, points per minute:                        900 points per minute for REST endpoints
+//     — "most REST API GET, HEAD and OPTIONS requests"        = 1 point
+//     — "most REST API POST, PATCH, PUT or DELETE requests"   = 5 points
+//   • SECONDARY, concurrency:                              no more than 100 concurrent requests
+//   • SECONDARY, content creation:                          80 per minute and 500 per hour
+// The read weight IS GitHub's own number — 1 point. The write weight is deliberately DEARER than
+// GitHub's 5 (it is 8); see `GITHUB_CALL_WEIGHTS.write` for why that is what makes the
+// 80-content-creations-per-minute leg hold under an hour-long window. Nothing here is invented: the
+// only departure from the published table is in the tightening direction, and it is labelled.
+//
+// The window is an HOUR (the kernel's maximum, and the horizon of GitHub's primary limit) and the
+// ceiling is 600 points. That is bounded on BOTH published axes at once:
+//   • against the primary 5,000/hour: at most 600 requests can fit in 600 points, so ≤ 12% of it;
+//   • against the secondary 900 points/MINUTE: even spending the entire hour's allowance in a
+//     single instant is 600 points, still under 900 — the burst cannot breach it either;
+//   • against content creation (80/MINUTE and 500/hour): writes cost 8 rather than GitHub's own 5,
+//     because at 5 the hour-long window would admit 120 writes inside a single minute — 1.5x the
+//     80/minute leg. At 8, only 75 fit, so BOTH legs hold. See `GITHUB_CALL_WEIGHTS.write`.
+// A full PR pull of a busy repo is roughly 1 + 4 per PR ≈ 80 points for 20 PRs, so this admits
+// about seven complete pulls an hour — far more than an on-demand connector needs, and far below
+// the runaway shape.
+//
+// ⚠️ HONESTLY, ON THE COMPARISON WITH THE KERNEL FALLBACK. `DEFAULT_RATE_BUDGET` is 30 calls a
+// minute, i.e. 1,800 an hour sustained. This declaration is TIGHTER sustained (600/hour) but LOOSER
+// in a single minute — and that looseness is now BOUNDED AND ENFORCED rather than merely argued:
+// `burstCeiling` caps any 60-second sub-window at 300 points, which the kernel refuses against
+// independently of the hourly ceiling. 300 sits under both of GitHub's per-minute legs (the 900-
+// points/minute secondary limit, and 300/8 = 37 writes against the 80 content-generating requests
+// per minute), so the burst is inside the vendor's published contract by arithmetic, not by prose.
+// An hour-long window is the only way to bound GitHub's hourly PRIMARY limit at all; the burst bound
+// is what stops that from silently buying an instantaneous allowance nobody asked for.
+//
+// The window bounds spend, not PACE (the kernel refuses, it never sleeps — see its header). GitHub
+// also caps concurrency at 100, which a weighted ledger does not model at all; that is the caller's
+// job. The backstop for both is the cooldown, armed from `Retry-After` / a 403-or-429 /
+// `x-ratelimit-remaining: 0`.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'github';
+/** Rolling window, in ms. One HOUR — the horizon of GitHub's primary 5,000-requests limit. */
+export const GITHUB_BUDGET_WINDOW_MS = 60 * 60 * 1_000;
+/**
+ * Weighted POINTS allowed inside one window. 600 points/hour is ≤ 12% of the primary 5,000
+ * requests/hour AND stays under the secondary 900 points/minute even if spent all at once.
+ */
+export const GITHUB_BUDGET_CEILING = 600;
+/**
+ * Weighted points allowed in any 60-SECOND sub-window, enforced by the kernel independently of the
+ * hourly ceiling. Without it, an hour-long window admits its entire 600 points in one millisecond —
+ * twenty times what the austere fallback allows in a minute — and nothing in the kernel reached that
+ * (§9 round 2, 2026-07-26). 300 is deliberately HALF the hourly ceiling: a full PR pull of a busy
+ * repo is ~80 points and the largest realistic burst is well under it, while both of GitHub's
+ * per-minute legs are honoured with room to spare — 300 < the 900-points/minute secondary limit, and
+ * 300/8 = 37 writes < the 80 content-generating requests/minute.
+ */
+export const GITHUB_BUDGET_BURST_CEILING = 300;
+/** Seconds. A `Retry-After` above this means the token is throttled hard — fail loudly, don't sleep. */
+export const GITHUB_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** GitHub's OWN published point costs. Not a proxy for them — the numbers themselves. */
+export const GITHUB_CALL_WEIGHTS = {
+    /**
+     * GitHub's own table prices a `POST`/`PATCH`/`PUT`/`DELETE` at **5 points**. This charges **8**,
+     * and the extra 3 are not a re-transcription of the vendor — they are what makes the OTHER
+     * documented write limit hold. GitHub caps content creation at **80 per minute** as well as 500
+     * per hour, and with an hour-long window a 5-point price lets 600/5 = 120 writes land inside a
+     * single minute: 1.5x that 80. At 8 points only 75 fit, which is under it. (§9 finding,
+     * 2026-07-26: the declaration cited the 80/min limit in its own header and then checked only the
+     * hourly leg.) Reads are unaffected, and the ratio is still write-dearer-than-read as published.
+     */
+    write: 8,
+    /** "Most REST API GET, HEAD, and OPTIONS requests" — 1 point, per GitHub's own table. */
+    other: 1,
+};
+/** THE PACK'S DECLARATION — pure data, the only GitHub-specific thing in the whole budget. */
+export const GITHUB_RATE_BUDGET = {
+    windowMs: GITHUB_BUDGET_WINDOW_MS,
+    ceiling: GITHUB_BUDGET_CEILING,
+    burstCeiling: GITHUB_BUDGET_BURST_CEILING,
+    defaultWeight: GITHUB_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: GITHUB_BUDGET_MAX_RETRY_AFTER_S,
+    // Keyed by the octokit-style ROUTE (`"POST /repos/{owner}/{repo}/pulls"`), so the method is the
+    // first token and GitHub's own read/write split is expressible as one anchored rule.
+    rules: [
+        { match: '^(POST|PATCH|PUT|DELETE) ', weight: GITHUB_CALL_WEIGHTS.write },
+    ],
+    reason: "GitHub's published scheme IS a weighted point budget, so these weights are its own numbers, not " +
+        'a proxy (docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api, read ' +
+        '2026-07-26): 5,000 requests/hour primary per PAT; secondary limits of 900 POINTS per minute ' +
+        'with GET/HEAD/OPTIONS = 1 point and POST/PATCH/PUT/DELETE = 5 points, 100 concurrent requests, ' +
+        'and 80 content-generating requests/minute / 500 per hour. 600 points per HOUR is bounded on ' +
+        'every axis at once: at most 600 requests fit in 600 points (≤12% of the 5,000/hour primary), and ' +
+        'spending the entire hour instantly is still 600 < the 900/minute secondary. Writes are charged 8 ' +
+        "rather than GitHub's own 5 — the only departure from its table, and a TIGHTENING: at 5 points the " +
+        'hour-long window would admit 120 writes inside one minute, 1.5x the documented 80/minute content-' +
+        'creation leg, while at 8 only 75 fit, so both the 80/minute and 500/hour legs hold. Versus the kernel fallback (30 ' +
+        'calls/min = 1,800/hour) this is TIGHTER sustained but LOOSER in one minute — and that looseness is ' +
+        'BOUNDED: burstCeiling caps any 60s sub-window at 300 points, which the kernel enforces separately, ' +
+        'and 300 sits under both per-minute legs (900 points/min, and 300/8 = 37 writes vs 80 content-' +
+        'generating requests/min). An hour-long window is the only way to bound ' +
+        "GitHub's hourly primary limit at all. It bounds spend, not pace, and does not model the " +
+        'concurrency cap; the Retry-After / 403-or-429 cooldown is the backstop for both.',
+};
+// Declared at module load, so merely importing this module (which `github-connector.ts` does) is
+// enough to arm the real ceiling. `RateBudget` reads its policy live precisely so this declaration
+// takes effect the moment it lands, and constructing through the subclass below (which imports this
+// module) is what makes the ordering a non-issue in practice.
+declareRateBudget(VENDOR, GITHUB_RATE_BUDGET);
+/**
+ * Price one call by its octokit-style ROUTE (`"GET /repos/{owner}/{repo}/pulls"`). The route, not
+ * the substituted path, is the key: it is what GitHub's docs name endpoints by, and it keeps the
+ * ledger's classification stable across owners and repos. A route nobody classified still costs
+ * `defaultWeight` — an unknown endpoint must never be free.
+ */
+export function githubCallWeight(route) {
+    const at = route.indexOf('?');
+    const query = {};
+    if (at !== -1)
+        for (const [k, v] of new URLSearchParams(route.slice(at + 1)))
+            query[k] = v;
+    const raw = (at === -1 ? route : route.slice(0, at)).trim();
+    // NORMALIZED, because the method rule is otherwise trivially evaded (§9 finding, 2026-07-26):
+    // `fetch` upper-cases a known lowercase method before sending, so `'post /repos/…'` issues a real
+    // WRITE that a `^(POST|…) ` rule would price as a 1-point read; and a trailing slash makes a `$`
+    // anchor miss a route most routers treat as identical. Both are input variations, not attacks, and
+    // either one voids the read/write split that IS GitHub's own published point scheme.
+    const sp = raw.indexOf(' ');
+    const method = (sp === -1 ? raw : raw.slice(0, sp)).toUpperCase();
+    const path = sp === -1 ? '' : raw.slice(sp + 1);
+    const bare = path.length > 1 && path.endsWith('/') ? path.replace(/\/+$/, '') : path;
+    return rateBudgetWeight(VENDOR, bare === '' ? method : `${method} ${bare}`, query);
+}
+/** Where GitHub's ledger lives. Token-keyed and cwd-independent by default (the primary limit is
+ *  per token, so a cwd-scoped ledger would hand the same PAT a fresh allowance in every checkout,
+ *  worktree and CI matrix leg — precisely the shape a matrix build has); pass `root` to opt into
+ *  world-scoped accounting instead. */
+export function githubBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+    // excess-property check only catches object literals) must not redirect this pack's ledger to
+    // another vendor's file.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * GitHub's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof GithubBudget` in `liveGithubExecute` means "a budget that
+ * accounts against GITHUB's ledger under GITHUB's ceiling": another vendor's `RateBudget` (with its
+ * own, possibly larger, ceiling) is NOT assignable there.
+ */
+export class GithubBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as GithubBudgetError } from '@volter/world-core';

package/dist/src/github-capabilities.d.ts

@@ -0,0 +1,5 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare function withRoot(fn: (root: string) => Promise<boolean>): Promise<boolean>;
+export declare const GITHUB_CAPABILITIES: CapabilitySpec[];
+export declare const GITHUB_AREAS: readonly ["actions", "activity", "api", "auth", "billing", "checks", "codespaces", "connector", "copilot", "deployments", "discussions", "fields", "gists", "git", "interactions", "issues", "marketplace", "meta", "migrations", "notifications", "orgs", "packages", "pages", "projects", "pulls", "releases", "repos", "scim", "search", "security", "ui", "users", "webhooks"];
+export declare function githubCapabilities(): Promise<CapabilityReport>;